TTS Voice Pack Model Option Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a local Voice Pack model option under the official TTS provider; when selected, the voice picker shows server-enabled Voice Packs instead of raw provider voices.

Architecture: Keep provider selection unchanged. Treat Voice Pack as a local UI-only model id in the Speech settings page, and resolve it to the selected pack snapshot only when binding and building speech requests. Existing real TTS model + raw voice behavior stays unchanged.

Tech Stack: Vue 3 Composition API, Pinia stores, Stage UI components, TypeScript, Vitest, UnoCSS.

Global Constraints

Do not create implementation commits.
Do not add aliases to raw TTS voices.
Do not filter raw provider catalogs through a new allowlist.
Do not make Voice Pack the only official TTS path.
Do not hardcode default male or female voices in the client.
Do not change Voice Pack billing semantics.
Do not change server-side LLM_ROUTER_CONFIG model aliases.
Keep Voice Pack provider/model/voice ids hidden from the user-facing UI.

File Structure

Modify packages/stage-pages/src/pages/settings/modules/speech.vue
- Owns the user-facing Speech settings flow.
- Adds a local synthetic Voice Pack model option.
- Projects enabled Voice Packs into voice-card options when the synthetic option is selected.
- Removes the old separate Voice Pack section from the left column.
Modify packages/stage-ui/src/stores/modules/speech.ts
- Exports the synthetic VOICE_PACK_MODEL_ID.
- Prevents the official raw-voice loader from requesting /audio/voices?model=voice-pack.
- Keeps the synthetic model selected when the official provider validates model state.
Modify packages/stage-ui/src/stores/modules/speech.test.ts
- Adds regression coverage for existing Voice Pack request resolution.
- Confirms pack metadata stays attached to speech requests.

Task 1: Integrate Voice Pack Into Model And Voice Selection

Files:

Modify: packages/stage-pages/src/pages/settings/modules/speech.vue
Modify: packages/stage-ui/src/stores/modules/speech.ts

Interfaces:

Consumes: useVoicePacksStore().packs, useAiriCardStore().bindVoicePackToActiveCard(pack), activeSpeechModel, activeSpeechVoiceId, availableVoices.
Produces: exported VOICE_PACK_MODEL_ID, local displayedProviderModels, isVoicePackModelSelected, and displayedVoiceOptions values used by the template.
Step 1: Add the synthetic model id and display helpers

Add to packages/stage-ui/src/stores/modules/speech.ts near the Voice Pack parameter constants:

export const VOICE_PACK_MODEL_ID = 'voice-pack'

Import it in packages/stage-pages/src/pages/settings/modules/speech.vue.

Add near the other page-level constants:

const VOICE_PACK_MODEL_OPTION = {
  id: VOICE_PACK_MODEL_ID,
  name: 'Voice Pack',
  description: 'Server-curated voices',
}

Add computed helpers:

const isOfficialSpeechProvider = computed(() => activeSpeechProvider.value === OFFICIAL_SPEECH_PROVIDER_ID)
const isVoicePackModelSelected = computed(() => isOfficialSpeechProvider.value && activeSpeechModel.value === VOICE_PACK_MODEL_ID)
const displayedProviderModels = computed(() => {
  if (!isOfficialSpeechProvider.value)
    return providerModels.value
  return [VOICE_PACK_MODEL_OPTION, ...providerModels.value]
})

Step 2: Replace the old separate Voice Pack section

Delete the <template v-if="shouldShowVoicePackSection">...</template> block. Keep voicePacksStore.load() on mount.

Step 3: Project Voice Packs into voice-card options

Add helpers:

function voicePackVoiceId(packId: string) {
  return `voice-pack:${packId}`
}

function packIdFromVoicePackVoiceId(voiceId: string) {
  return voiceId.startsWith('voice-pack:') ? voiceId.slice('voice-pack:'.length) : null
}

const selectedVoicePack = computed(() => {
  const packId = packIdFromVoicePackVoiceId(activeSpeechVoiceId.value)
  if (packId)
    return voicePacks.value.find(pack => pack.id === packId) ?? null
  const snapshot = activeCard.value?.extensions.airi.modules.speech.voicePack
  return snapshot ? voicePacks.value.find(pack => pack.id === snapshot.packId) ?? null : null
})

const displayedVoiceOptions = computed(() => {
  if (isVoicePackModelSelected.value) {
    return voicePacks.value.map(pack => ({
      id: voicePackVoiceId(pack.id),
      name: pack.name,
      description: pack.description ?? undefined,
      previewURL: '',
      customizable: false,
    }))
  }

  return (availableVoices.value[activeSpeechProvider.value] ?? [])
    .filter((voice) => {
      if (!activeSpeechModel.value)
        return true
      return !voice.compatibleModels || voice.compatibleModels.includes(activeSpeechModel.value)
    })
    .map(voice => ({
      id: voice.id,
      name: voice.name,
      description: voice.description,
      previewURL: voice.previewURL,
      customizable: false,
    }))
})

Step 4: Handle Voice Pack voice selection

Update selectSpeechVoice so selecting a projected Voice Pack binds the server pack and tracks the underlying pack:

async function selectSpeechVoice(voiceId: string | undefined) {
  if (!voiceId)
    return

  const packId = packIdFromVoicePackVoiceId(voiceId)
  if (isVoicePackModelSelected.value && packId) {
    const pack = voicePacks.value.find(item => item.id === packId)
    if (!pack)
      return
    await bindVoicePack(pack)
    activeSpeechVoiceId.value = voiceId
    activeSpeechVoice.value = {
      id: voiceId,
      name: pack.name,
      description: pack.description ?? pack.name,
      previewURL: '',
      languages: [{ code: 'en', title: 'English' }],
      provider: activeSpeechProvider.value,
      gender: 'neutral',
    }
    return
  }

  trackVoiceSelected({
    tts_provider_id: activeSpeechProvider.value || 'unknown',
    tts_model_id: currentTtsModelId(),
    ...voiceAnalyticsPayload(voiceId),
    source: 'settings',
  })
}

Step 5: Keep model switching from sending voice-pack to /audio/voices

Update the active model watcher:

watch(activeSpeechModel, async (model) => {
  if (!activeSpeechProvider.value)
    return

  activeSpeechVoiceId.value = ''
  activeSpeechVoice.value = undefined

  if (model === VOICE_PACK_MODEL_ID)
    return

  await speechStore.loadVoicesForProvider(activeSpeechProvider.value, model || undefined)
})

Step 6: Use displayed model and voice lists in the template

Change providerModels usages in the model picker to displayedProviderModels.

Change the voice picker condition to:

vue

v-else-if="activeSpeechProvider !== 'openai-compatible-audio-speech' && displayedVoiceOptions.length > 0"

Change the voice picker :voices binding to:

vue

:voices="displayedVoiceOptions"

Change the manual voice input condition so it does not show for the Voice Pack model:

vue

v-if="!isVoicePackModelSelected && (activeSpeechProvider === 'openai-compatible-audio-speech' || !availableVoices[activeSpeechProvider] || availableVoices[activeSpeechProvider].length === 0)"

Step 7: Verify the page compiles

Run:

bash

pnpm -F @proj-airi/stage-pages typecheck

Expected: PASS, or unrelated pre-existing package errors documented with exact output.

Task 2: Preserve Voice Pack Speech Request Semantics

Files:

Modify: packages/stage-pages/src/pages/settings/modules/speech.vue
Modify: packages/stage-ui/src/stores/modules/speech.test.ts

Interfaces:

Consumes: bindVoicePackToActiveCard, voicePackForSpeechProvider, resolveVoicePackSpeechInput.
Produces: regression proof that the UI display change does not break server validation metadata.
Step 1: Keep preview generation resolving snapshots

Ensure generateTestSpeech() keeps this behavior:

const voicePack = boundVoicePack.value
if (voicePack) {
  model = voicePack.ttsModelId
  if (!voice || voice.id !== voicePack.voiceId)
    voice = createVoicePackVoice(voicePack)
}

Step 2: Keep request metadata test coverage

Confirm or add a test in packages/stage-ui/src/stores/modules/speech.test.ts:

it('passes Voice Pack snapshot billing metadata through adapter options', () => {
  const speechStore = useSpeechStore()
  const result = speechStore.resolveVoicePackSpeechInput({
    text: 'hello',
    voice: {
      id: 'voice-a',
      name: 'Voice A',
      provider: OFFICIAL_SPEECH_PROVIDER_ID,
      languages: [{ code: 'en-US', title: 'English' }],
    },
    voicePack: {
      packId: 'vp-1',
      costMultiplier: 1.5,
    },
  })

  expect(result.providerConfig.extraBody).toEqual({
    voice_pack: {
      pack_id: 'vp-1',
      cost_multiplier: 1.5,
    },
  })
})

Step 3: Run targeted tests

Run:

bash

pnpm exec vitest run packages/stage-ui/src/stores/modules/speech.test.ts

Expected: PASS.

Task 3: Final Verification

Files:

Check: packages/stage-pages/src/pages/settings/modules/speech.vue
Check: packages/stage-ui/src/stores/modules/speech.test.ts

Interfaces:

Consumes: all previous tasks.
Produces: verified implementation ready for user review.
Step 1: Run lint

Run:

bash

pnpm lint

Expected: PASS, or unrelated pre-existing errors documented with exact output.

Step 2: Run typecheck

Run:

bash

pnpm type-check

Expected: PASS, or unrelated pre-existing errors documented with exact output.

Step 3: Inspect final diff

Run:

bash

git diff -- packages/stage-pages/src/pages/settings/modules/speech.vue packages/stage-ui/src/stores/modules/speech.test.ts

Expected: diff only contains the Voice Pack model-option integration and related tests.