@voctiv/agent-sdk 0.2.16 → 0.3.1

package/README.md

@@ -81,6 +81,7 @@ The [`examples/`](./examples/) folder contains copy-paste-ready scripts:
 | [schedule-call-with-defaults.ts](./examples/schedule-call-with-defaults.ts) | `platform.call()` without explicit recall — CMS defaults from `context` |
 | [after-call-continuation.ts](./examples/after-call-continuation.ts) | `onSuccessCall` / `onFailedCall` vs recall (mutually exclusive) |
 | [read-recall-from-params.ts](./examples/read-recall-from-params.ts) | `parseRecallDelaySeconds()` / `parseRecallCount()` on legacy params |
+| [custom-media-providers.ts](./examples/custom-media-providers.ts) | `defineMediaProviders` + custom ASR/TTS via `createAsr` / `createTts` |
 
 ### Quick recall example
 
@@ -116,6 +117,8 @@ const maxAttempts = parseRecallCount(context.dialogParams?.recall_count);
 
 `defineScript(fn)` marks the default export as the script entry point. It returns the same function and exists to give TypeScript the correct `ScriptContext` shape.
 
+`defineMediaProviders(def)` marks a named `mediaProviders` export for custom ASR/TTS factories (trusted packages only). See [Custom ASR / TTS Providers](#custom-asr--tts-providers).
+
 **Three different “context” names:**
 
 | Name | Meaning |
@@ -136,7 +139,8 @@ const maxAttempts = parseRecallCount(context.dialogParams?.recall_count);
 - `channel.type` is `"sip"` for telephony and `"ws"` for WebSocket/script-manager sessions. Headless sessions currently expose a synthetic `"ws"` channel; check `context.headless` to detect them.
 - `channel.params` is the merged runtime parameter map. Treat unknown keys as host-specific.
 - `channel.createAsr()` creates an ASR handle.
-- `channel.audio` controls TTS, raw playback, pre-synthesis, and mixer queues.
+- `channel.createTts()` returns a TTS handle (`tts.say` / `tts.say$` / `tts.presay`) with a reused SSL / WebSocket connection.
+- `channel.audio` controls channel-level TTS, raw playback, pre-synthesis, and mixer queues.
 - `channel.sip` controls SIP state, pre-answer media, DTMF, hold/mute/hangup, outbound calls, and bridging.
 - `channel.llm` talks to the Omni LLM backend.
 - `channel.events` exposes speech, interrupt, termination, WS data message, and media error observables.
@@ -460,7 +464,9 @@ While a bridge is active, `channel.audio.say()` still sends audio only to the A-
 
 ## ASR, VAD, And Smart Turn
 
-Create ASR with `channel.createAsr(config?)`.
+Create ASR with `channel.createAsr(config?)`. Prefer creating it once at dialog start so the
+host can warm the ASR TCP/WebSocket (one SSL handshake). A later `createAsr` with the same
+resolved vendor/credentials reuses that channel; `destroy()` closes it.
 
 ```ts
 const asr = await channel.createAsr({
@@ -490,7 +496,7 @@ const asr = await channel.createAsr({
 - `error$`: runtime errors from the ASR provider (see [Error Handling](#error-handling)).
 - `pause()` / `resume()` to stop or resume forwarding new audio frames.
 - `finalize()` to force the current utterance to flush.
-- `destroy()` to close connector streams and subscriptions.
+- `destroy()` to close the warm TCP/WS connector and subscriptions.
 
 SIP sessions use the call-level telephony VAD when it is available. WS sessions create one VAD/SmartTurn instance for the socket session on the first `createAsr()` call. Headless sessions return an inert ASR handle with empty observables.
 
@@ -548,8 +554,73 @@ When both `name` (platform key) and explicit `data` are provided, `data` values
 All audio playback goes through **`channel.audio`** (`ChannelAudio`). There are no top-level
 `channel.say()` / `channel.play()` shortcuts on `MediaChannel`.
 
+Create a reusable TTS session with `channel.createTts(config?)` — same pattern as `createAsr`.
+Call `tts.say` / `tts.say$` / `tts.presay` on the handle so synthesis reuses the warmed SSL / streaming WebSocket.
+
+Custom engines from a logic package are documented in
+[Custom ASR / TTS Providers](#custom-asr--tts-providers).
+
+```ts
+const tts = await channel.createTts({
+  vendor: 'elevenlabs',
+  name: 'elevenlabs-main',
+});
+
+await tts.say('Hello', {
+  ttsStrategy: 'streaming',
+  alias: 'greeting',
+});
+
+// Track queue / speaking / done per sentence for one say$ call:
+tts.say$('One. Two.', { alias: 'reply', queue: 0 }).subscribe({
+  next: (e) => {
+    if (e.state === 'queued') {
+      // e.text — full utterance (string) or '' until stream tokens arrive
+    }
+    if (e.state === 'speaking') {
+      // e.sentenceText / e.sentenceIndex — sentence starting playback
+      // e.itemAlias — e.g. reply-0
+    }
+    if (e.state === 'done') {
+      // that sentence finished; e.sentenceText / e.sentenceIndex / e.itemAlias
+    }
+    if (e.state === 'cancelled') {
+      // audio.stop / destroy; e.text so far
+    }
+  },
+  complete: () => {
+    // whole say$ finished (all sentences)
+  },
+  error: (err) => {
+    // MediaError — synthesis/playback failed
+  },
+});
+
+// Later turns reuse the same WebSocket:
+await tts.say(tokenStream, {
+  ttsStrategy: 'streaming',
+  alias: 'reply-2',
+});
+
+tts.destroy();
+```
+
+`tts.say()` stays a `Promise` (await until finished). `tts.say$()` returns an `Observable`
+of utterance lifecycle events for that call only (`queued` → (`speaking` → `done`)×N /
+`cancelled`, then complete). `done` is per sentence/phrase finishing playback; use the
+Observable `complete` callback for the end of the whole `say$` call. Synthesis failures
+terminate the Observable via **error** (`MediaError`), and are also mirrored on
+`tts.error$` / `channel.events.error$`. `channel.audio.say` remains Promise-only.
+
+You can still use `channel.audio.say(..., { tts })` if you prefer the channel API; a matching
+pre-warmed session is also reused when vendor+config align.
+
 | Method | Purpose |
 | --- | --- |
+| `channel.createTts(config?)` | Pre-warm a TTS connector / streaming socket; returns `TtsHandle` |
+| `tts.say(textOrObservable, options?)` | Synthesize via the handle's cached connection (`Promise`) |
+| `tts.say$(textOrObservable, options?)` | Same path with per-utterance status events (`Observable`) |
+| `tts.presay(text, options?)` | Pre-synthesize into the host TTS cache via the handle |
 | `channel.audio.say(textOrObservable, options?)` | Synthesize text with TTS and play on a mixer queue |
 | `channel.audio.play(source, options?)` | Play raw audio (URL, path, or platform phrase record) |
 | `channel.audio.presay(text, options?)` | Pre-synthesize TTS into the host cache (no playback) |
@@ -709,6 +780,202 @@ Shared by `say()`, `play()`, and (where noted) `presay()`:
 
 `play()` ignores `tts*` and `cache` for raw audio. `preload()` only accepts `cache` overrides.
 
+## Custom ASR / TTS Providers
+
+Trusted logic packages can ship their own ASR/TTS engines next to `defineScript`. The host
+`require`s a static **`export const mediaProviders`** **outside** the script sandbox (same
+process privileges as the API). Use this only for packages you trust.
+
+Mid-script `registerAsr` / `registerTts` is **not** supported — declare vendors at module load.
+
+### Export shape
+
+```ts
+import {
+  defineScript,
+  defineMediaProviders,
+  type MediaConnectorContext,
+  type MediaProviderShared,
+  type ScriptAsrConnector,
+  type ScriptTtsConnector,
+} from '@voctiv/agent-sdk';
+import { Subject } from 'rxjs';
+import { Readable } from 'stream';
+
+export const mediaProviders = defineMediaProviders({
+  // Optional: one object per dialog, shared by ASR + TTS factories
+  createShared: (ctx) => ({
+    dialogUuid: ctx.dialogUuid,
+    dispose() { /* release app state */ },
+  }),
+  asr: {
+    'my-asr': (ctx, shared) => new MyAsr(ctx, shared),
+  },
+  tts: {
+    'my-tts': (ctx, shared) => new MyTts(ctx, shared),
+  },
+});
+
+export default defineScript(async ({ channel }) => {
+  const asr = await channel.createAsr({
+    vendor: 'my-asr',
+    language: 'ru-RU',
+    data: { api_key: process.env.MY_ASR_KEY! },
+  });
+  const tts = await channel.createTts({
+    vendor: 'my-tts',
+    data: {
+      api_key: process.env.MY_TTS_KEY!,
+      voice_id: '…',
+      output_format: 'pcm_16000', // preferred for telephony
+    },
+  });
+
+  await tts.say('Hello from a custom connector.', {
+    alias: 'greet',
+    ttsStrategy: 'streaming', // used when supportsStreaming() === true
+  });
+
+  tts.say$('One. Two.', { alias: 'reply' }).subscribe((ev) => {
+    // queued | speaking | done | cancelled — same events as builtin TTS
+  });
+
+  // Reuse the warm handle:
+  await channel.audio.say('Again', { tts });
+
+  asr.destroy();
+  tts.destroy();
+});
+```
+
+`defineMediaProviders` is an identity helper for typing. The host looks up
+`module.exports.mediaProviders` (or `default.mediaProviders`) on the script entry file.
+
+Full stub: [`examples/custom-media-providers.ts`](./examples/custom-media-providers.ts).
+
+### Implement ASR (`ScriptAsrConnector`)
+
+The host pushes **PCM S16LE mono 16 kHz** frames into `send()`. Emit partials on
+`transcription$` and finals on both `transcription$` (`isFinal: true`) and `result$`.
+
+| Member | Role |
+| --- | --- |
+| `transcription$` | `{ text, isFinal }` partials and finals |
+| `result$` | Final utterance strings (drives `AsrHandle.result$`) |
+| `error$` | Vendor / transport failures |
+| `send(audio)` | Accept inbound PCM (`ArrayBuffer` / `Buffer`) |
+| `speech(active)` | Optional VAD gate from the host (`true` = utterance open) |
+| `finalize()` | End-of-utterance nudge (flush / commit) |
+| `isOpen()` | Whether the vendor socket is ready |
+| `close()` | Tear down; complete Subjects |
+
+```ts
+class MyAsr implements ScriptAsrConnector {
+  readonly transcription$ = new Subject<{ text: string; isFinal: boolean }>();
+  readonly result$ = new Subject<string>();
+  readonly error$ = new Subject<{ message: string; code?: number }>();
+
+  constructor(
+    private readonly ctx: MediaConnectorContext,
+    private readonly shared: MediaProviderShared | undefined,
+  ) {
+    // ctx.config — flattened createAsr data + channel asrConfig
+    // ctx.dialogUuid, ctx.role, ctx.debug$
+  }
+
+  isOpen() { return true; }
+  send(audio: ArrayBufferLike) { /* forward PCM to vendor */ }
+  speech(_active: boolean) {}
+  finalize() {
+    const text = '…';
+    this.transcription$.next({ text, isFinal: true });
+    this.result$.next(text);
+  }
+  close() {
+    this.transcription$.complete();
+    this.result$.complete();
+    this.error$.complete();
+  }
+}
+```
+
+Factory `throw` during create → host degraded ASR handle (same as builtin). Prefer connecting
+lazily in `send()`; the host does not call a separate `connect()` on custom connectors.
+
+### Implement TTS (`ScriptTtsConnector`)
+
+**One class per vendor** covers batch HTTP and optional streaming WebSocket. Do **not**
+register a separate streaming map.
+
+| Member | Role |
+| --- | --- |
+| `supportsStreaming()` | `true` → host may use WS path for `ttsStrategy: 'streaming'` |
+| `textToSpeechStream(text, ctx?)` | Batch/HTTP synthesis → `Readable` of audio bytes |
+| `audio$` / `done$` | Streaming audio chunks and end-of-generation |
+| `open` / `startGeneration` / `sendText` / `flush` | Streaming lifecycle |
+| `sendSeparatorFlush?()` | Optional sentence separator flush |
+| `close()` | Soft-close sockets for **reuse** (do not complete Subjects if `open()` may run again) |
+
+```ts
+class MyTts implements ScriptTtsConnector {
+  readonly audio$ = new Subject<Buffer>();
+  readonly done$ = new Subject<void>();
+
+  supportsStreaming() {
+    return true; // or false for HTTP-only
+  }
+
+  async textToSpeechStream(rawtext: string, _ctx?: { previousText?: string; nextText?: string }) {
+    // Return PCM (preferred) or MP3/OGG. Hint format via createTts data:
+    // output_format: 'pcm_16000' | 'mp3_…'  or  audioFormat: 'pcm' | 'mp3'
+    return Readable.from([/* bytes */]);
+  }
+
+  async open() { /* open long-lived WS */ }
+  async startGeneration() { /* BOS / new utterance */ }
+  sendText(chunk: string) { /* stream tokens */ }
+  flush() { /* EOS; later emit done$ */ }
+  close() { /* close WS; keep Subjects alive for fingerprint reuse */ }
+}
+```
+
+- `supportsStreaming() === false` → streaming strategy falls back to sentence/full HTTP path.
+- Default audio assumption for custom vendors is **PCM** unless `output_format` / `audioFormat`
+  indicates a compressed format (`mp3`, `ogg`, …).
+
+### Using custom vendors in the script
+
+```ts
+const asr = await channel.createAsr({ vendor: 'my-asr', data: { … } });
+const tts = await channel.createTts({ vendor: 'my-tts', data: { … } });
+
+await tts.say('Hi', { alias: 'greet' });
+await tts.presay('Warm cache');
+tts.say$('Next', { alias: 'reply', ttsStrategy: 'streaming' }).subscribe(…);
+
+await channel.audio.say('Reuse', { tts }); // same warm session
+```
+
+Vendor keys must be **multi-character** names. Builtin single-letter codes
+(`A`, `D`, `E`, `ES`, `G`, `V`, `W`, `W2`, …) **cannot** be overridden.
+
+### Warm reuse vs `createShared` vs PCM cache
+
+| Layer | What it caches | Scope |
+| --- | --- | --- |
+| Factory + session registries | One connector instance per `dialog + vendor + config fingerprint` (TCP/WS) | Host automatic |
+| `createShared` | Your app/vendor state shared by ASR↔TTS factories | One object per dialog |
+| `PlayOptions.cache` / `presay` | Synthesized PCM files | Host TTS file cache |
+
+Call `createAsr` / `createTts` early to warm sockets. Repeated `say` with the same handle (or
+matching fingerprint) must **not** open a new TCP/WS per utterance.
+
+### Security
+
+- Host `require` of `mediaProviders` runs with API privileges — **trusted packages only**.
+- Entry path is restricted to the script root (path traversal denied).
+- Optional host allowlists may further restrict which packages may export providers.
+
 ## TTS Credentials And Vendor Parameters
 
 ### Direct TTS Vendor Parameters
@@ -850,7 +1117,7 @@ channel.events.error$.subscribe((err) => {
 | --- | --- | --- |
 | `source` | `'asr' \| 'tts' \| 'sip' \| 'channel' \| 'llm'` | Which subsystem produced the error. |
 | `phase` | `'create' \| 'start' \| 'stream' \| 'playback' \| 'finalize' \| 'destroy'?` | Lifecycle phase where the error happened. |
-| `operation` | `string?` | Public SDK operation, e.g. `createAsr`, `audio.say`, or `audio.play`. |
+| `operation` | `string?` | Public SDK operation, e.g. `createAsr`, `createTts`, `audio.say`, or `audio.play`. |
 | `recoverable` | `boolean?` | Whether the runtime can keep the session alive after this error. |
 | `handleId` | `string?` | ASR handle id when the error belongs to a recognizer instance. |
 | `queue` | `number?` | Mixer queue index when the error belongs to an audio operation. |
@@ -1476,6 +1743,7 @@ Important fields:
 - `context.dialogUuid`: current dialog UUID.
 - `context.callerId` / `context.msisdn`: caller identity.
 - `context.destinationNumber`: called number.
+- `context.trunkId` / `context.trunkName`: LE trunk for this dialog/call (snapshot; name from `trunk` table).
 - `context.language` / `context.lang`: language selected for the run.
 - `context.flag`: business flag.
 - `context.initialData`: shallow snapshot of params at script start.
@@ -1528,6 +1796,7 @@ Headless channels are for offline, queue, or messaging sessions:
 - SIP methods are no-ops, except `makeCall()` and `bridge()`, which throw: there is no real leg to
   create, and a silent no-op would hide the mistake.
 - `createAsr()` returns an inert handle whose observables complete immediately.
+- `createTts()` returns an inert handle (no vendor connection is opened).
 - LLM, NLU, messaging, platform calls, dialog state, and `env$` still work.
 
 Use `context.headless` plus `getScriptPhase(context)` when a script must behave differently without a

package/dist/index.d.ts

@@ -13,6 +13,7 @@
  * When the host loads platform credential catalogs, **`channel.params.authentication_data`**
  * may contain named ASR/TTS key rows for the current dialog agent and company. Use:
  * - {@link import('./types/asr-handle').AsrConfig.name} or **`data.name`** on **`createAsr`**
+ * - {@link import('./types/tts-handle').TtsConfig.name} or **`data.name`** on **`createTts`**
  * - {@link import('./types/mixer').PlayOptions.name} or **`ttsConfig.name`** on **`say`/`play`/`presay`**
  *
  * Channel defaults **`defaultAsrName`** / **`defaultTtsName`** apply when **`name`** is omitted.
@@ -29,6 +30,8 @@
  */
 export { defineScript } from './define-script';
 export type { ScriptContext, ScriptFn } from './define-script';
+export { defineMediaProviders } from './types/media-providers';
+export type { MediaProvidersDefinition, MediaConnectorContext, MediaProviderShared, AsrProviderFactory, TtsProviderFactory, ScriptAsrConnector, ScriptAsrConnectorError, ScriptTtsConnector, TtsSynthesisContext as ScriptTtsSynthesisContext, } from './types/media-providers';
 export type { ScriptDialogContext, ScriptPhase, ScriptRunTime, ScriptResult, PersistedScriptResult, ScriptError, AgentContext, AgentEnvSetOptions, StorageContextApi, } from './types/script-context';
 export { getScriptPhase } from './types/script-context';
 export type { NluScriptApi, PlatformApi, DialogApi, ScheduleCallOptions, SendMessageOptions, InboundMessage, MessagingApi, } from './types/platform';
@@ -39,6 +42,7 @@ export type { ChannelLlm, LlmOptions, LlmStreamChunk, ExtractOptions, Persistent
 export type { ChannelSip, SipState, SipProgressEvent, SipInviteHeaders, ParsedSdpDetails, } from './types/sip';
 export type { MediaError } from './types/errors';
 export type { AsrHandle, AsrConfig, AsrVadConfig, AsrSmartTurnConfig } from './types/asr-handle';
+export type { TtsHandle, TtsConfig, TtsSayOptions, TtsPresayOptions, TtsUtteranceEvent, TtsUtteranceCancelReason, } from './types/tts-handle';
 export type { MixerQueueControl, PlayOptions, PresayOptions, PreloadOptions, TtsStrategy, TtsVendor } from './types/mixer';
 export type { LegacyPhraseRecord, LegacyGetRecordsParams, CacheOptions, } from './types/legacy-phrase';
 export { LEGACY_PHRASE_RECORD_BRAND, isLegacyPhraseRecord, } from './types/legacy-phrase';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE/D,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACjG,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3H,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,SAAS,EACT,OAAO,EACP,SAAS,EACT,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,IAAI,yBAAyB,GACjD,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACjG,YAAY,EACV,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3H,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,SAAS,EACT,OAAO,EACP,SAAS,EACT,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -14,6 +14,7 @@
  * When the host loads platform credential catalogs, **`channel.params.authentication_data`**
  * may contain named ASR/TTS key rows for the current dialog agent and company. Use:
  * - {@link import('./types/asr-handle').AsrConfig.name} or **`data.name`** on **`createAsr`**
+ * - {@link import('./types/tts-handle').TtsConfig.name} or **`data.name`** on **`createTts`**
  * - {@link import('./types/mixer').PlayOptions.name} or **`ttsConfig.name`** on **`say`/`play`/`presay`**
  *
  * Channel defaults **`defaultAsrName`** / **`defaultTtsName`** apply when **`name`** is omitted.
@@ -29,9 +30,11 @@
  * and live SIP INFO ({@link import('./types/events').SipInfo} on `sipInfo$`). See **`README.md`** → SIP Signalling Metadata.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseRecallDelaySeconds = exports.parseRecallCount = exports.isLegacyPhraseRecord = exports.LEGACY_PHRASE_RECORD_BRAND = exports.TranscriptionRole = exports.getScriptPhase = exports.defineScript = void 0;
+exports.parseRecallDelaySeconds = exports.parseRecallCount = exports.isLegacyPhraseRecord = exports.LEGACY_PHRASE_RECORD_BRAND = exports.TranscriptionRole = exports.getScriptPhase = exports.defineMediaProviders = exports.defineScript = void 0;
 var define_script_1 = require("./define-script");
 Object.defineProperty(exports, "defineScript", { enumerable: true, get: function () { return define_script_1.defineScript; } });
+var media_providers_1 = require("./types/media-providers");
+Object.defineProperty(exports, "defineMediaProviders", { enumerable: true, get: function () { return media_providers_1.defineMediaProviders; } });
 var script_context_1 = require("./types/script-context");
 Object.defineProperty(exports, "getScriptPhase", { enumerable: true, get: function () { return script_context_1.getScriptPhase; } });
 var logger_1 = require("./types/logger");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAerB,yDAAwD;AAA/C,gHAAA,cAAc,OAAA;AAavB,yCAAmD;AAA1C,2GAAA,iBAAiB,OAAA;AAgC1B,uDAG+B;AAF7B,2HAAA,0BAA0B,OAAA;AAC1B,qHAAA,oBAAoB,OAAA;AAUtB,+CAA2E;AAAlE,gHAAA,gBAAgB,OAAA;AAAE,uHAAA,uBAAuB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAGrB,2DAA+D;AAAtD,uHAAA,oBAAoB,OAAA;AAyB7B,yDAAwD;AAA/C,gHAAA,cAAc,OAAA;AAavB,yCAAmD;AAA1C,2GAAA,iBAAiB,OAAA;AAwC1B,uDAG+B;AAF7B,2HAAA,0BAA0B,OAAA;AAC1B,qHAAA,oBAAoB,OAAA;AAUtB,+CAA2E;AAAlE,gHAAA,gBAAgB,OAAA;AAAE,uHAAA,uBAAuB,OAAA"}

package/dist/types/asr-handle.d.ts

@@ -102,9 +102,13 @@ export interface AsrConfig {
 /**
  * Live speech recognition session returned by {@link import('./media-channel').MediaChannel.createAsr}.
  *
+ * Call **`createAsr` early** to warm the ASR TCP/WebSocket (SSL handshake once per
+ * dialog + vendor + credentials). A second `createAsr` with the same resolved config
+ * reuses that channel instead of opening another socket. Call **`destroy()`** when done
+ * (e.g. on `channel.events.terminated$`) to release the connector.
+ *
  * Subscribe to **`partial$`** / **`result$`** for transcripts; wire **`speechStart$`** /
- * **`speechEnd$`** / **`interrupt$`** for barge-in and UI. Call **`destroy()`** when done
- * (e.g. on `channel.events.terminated$`) to release connector and subscriptions.
+ * **`speechEnd$`** / **`interrupt$`** for barge-in and UI.
  *
  * If connector creation fails, SIP/WS return a degraded handle: VAD observables still
  * mirror the channel where possible, but `partial$` and `result$` do not emit real STT.

package/dist/types/asr-handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asr-handle.d.ts","sourceRoot":"","sources":["../../src/types/asr-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oGAAoG;IACpG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,sEAAsE;IACtE,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAClE,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,6FAA6F;IAC7F,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IAExC,0FAA0F;IAC1F,KAAK,IAAI,IAAI,CAAC;IACd,kCAAkC;IAClC,MAAM,IAAI,IAAI,CAAC;IACf,kFAAkF;IAClF,QAAQ,IAAI,IAAI,CAAC;IACjB,8FAA8F;IAC9F,OAAO,IAAI,IAAI,CAAC;CACjB"}
+{"version":3,"file":"asr-handle.d.ts","sourceRoot":"","sources":["../../src/types/asr-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oGAAoG;IACpG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,sEAAsE;IACtE,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAClE,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,6FAA6F;IAC7F,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IAExC,0FAA0F;IAC1F,KAAK,IAAI,IAAI,CAAC;IACd,kCAAkC;IAClC,MAAM,IAAI,IAAI,CAAC;IACf,kFAAkF;IAClF,QAAQ,IAAI,IAAI,CAAC;IACjB,8FAA8F;IAC9F,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/types/media-channel.d.ts

@@ -1,5 +1,6 @@
 import type { Observable } from 'rxjs';
 import type { AsrConfig, AsrHandle } from './asr-handle';
+import type { TtsConfig, TtsHandle } from './tts-handle';
 import type { DataMessage } from './events';
 import type { MixerQueueControl, PlayOptions, PresayOptions, PreloadOptions } from './mixer';
 import type { LegacyPhraseRecord } from './legacy-phrase';
@@ -153,7 +154,7 @@ export interface MediaChannel {
      * Relevant to ASR/TTS when **Voctiv platform** compatibility is on (host-dependent keys), for example:
      * - **`asrVendor`**, **`ttsVendor`**, **`asrConfig`**, **`ttsConfig`**
      * - **`defaultAsrName`**, **`defaultTtsName`**: default **`key_storage.name`** when the script
-     *   omits **`name`** on {@link AsrConfig} / {@link PlayOptions}
+     *   omits **`name`** on {@link AsrConfig} / {@link TtsConfig} / {@link PlayOptions}
      * - **`authentication_data`**: may include **`legacyAsrKeysByName`**, **`legacyTtsKeysByName`**
      *   (built from LE DB for this dialog's agent + company)
      *
@@ -161,11 +162,13 @@ export interface MediaChannel {
      */
     readonly params: Record<string, unknown>;
     /**
-     * Create a speech recognizer for this session.
+     * Create (or warm) a speech recognizer for this session so recognition can reuse one
+     * TCP/WebSocket (one SSL handshake) for the dialog + vendor + credentials.
      *
      * SIP channels feed remote RTP audio. WS channels feed socket `audio` frames and can
      * create a per-session VAD on first ASR creation. Headless channels return an inert
-     * handle with empty observables.
+     * handle with empty observables. A second call with the same resolved config returns
+     * the existing warm handle.
      *
      * @param config - Optional {@link AsrConfig}: **`vendor`**, **`name`** (storage row), **`language`**,
      *   **`data`** overlays, VAD / smart-turn tuning.
@@ -173,6 +176,24 @@ export interface MediaChannel {
      *   If connector creation fails, SIP/WS return a degraded handle with VAD observables but no STT results.
      */
     createAsr(config?: AsrConfig): Promise<AsrHandle>;
+    /**
+     * Create (or warm) a TTS connector for this session so later `audio.say` / `audio.presay`
+     * can reuse the SSL / WebSocket connection.
+     *
+     * For streaming-capable vendors (e.g. ElevenLabs with `ttsStrategy: 'streaming'`), the host
+     * opens the streaming socket during this call. For batch HTTP vendors, the connector instance
+     * is registered in the dialog-scoped factory (keep-alive pool).
+     *
+     * Prefer calling {@link TtsHandle.say} / {@link TtsHandle.presay} on the returned handle
+     * (same pattern as {@link AsrHandle}). You may also pass the handle as {@link PlayOptions.tts}
+     * to `channel.audio.say` / `presay`, or omit it when a later `say` resolves to the same
+     * vendor+config — the host will reuse a matching session.
+     *
+     * @param config - Optional {@link TtsConfig}: **`vendor`**, **`name`** (storage row), **`data`** overlays.
+     * @returns A handle you should {@link TtsHandle.destroy} when you no longer need the connection.
+     *   If connector creation fails, SIP/WS return a degraded handle (synthesis falls back to ephemeral).
+     */
+    createTts(config?: TtsConfig): Promise<TtsHandle>;
     /** Push synthetic ASR results (testing / WS debug). No-op on headless channels. */
     readonly textInput: TextInput;
     readonly audio: ChannelAudio;

package/dist/types/media-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-channel.d.ts","sourceRoot":"","sources":["../../src/types/media-channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"media-channel.d.ts","sourceRoot":"","sources":["../../src/types/media-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAExC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACxC;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wFAAwF;IACxF,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,yGAAyG;AACzG,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,uGAAuG;IACvG,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,8FAA8F;IAC9F,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAC3C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEzC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAElD;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAElD,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB,6GAA6G;IAC7G,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACrC,wFAAwF;IACxF,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/types/media-providers.d.ts

@@ -0,0 +1,83 @@
+import type { Observable, Subject } from 'rxjs';
+import type { Readable } from 'stream';
+/**
+ * Context passed to custom ASR/TTS factories from {@link defineMediaProviders}.
+ * Populated by the host outside the script sandbox.
+ */
+export interface MediaConnectorContext {
+    id: string;
+    config: Record<string, string>;
+    dialogUuid: string;
+    role?: string;
+    debug$: Subject<string>;
+}
+export interface ScriptAsrConnectorError {
+    message: string;
+    code?: number;
+}
+/**
+ * Host ASR connector contract for custom providers (same surface as runtime AsrConnector).
+ */
+export interface ScriptAsrConnector {
+    transcription$: Subject<{
+        text: string;
+        isFinal: boolean;
+    }>;
+    result$: Subject<string>;
+    error$: Subject<ScriptAsrConnectorError>;
+    isOpen(): boolean;
+    send(audio: ArrayBufferLike): void;
+    speech(active: boolean): void;
+    finalize(): void;
+    close(): void;
+}
+export type TtsSynthesisContext = {
+    previousText?: string;
+    nextText?: string;
+};
+/**
+ * Unified TTS connector: batch HTTP + optional streaming WebSocket methods.
+ */
+export interface ScriptTtsConnector {
+    supportsStreaming(): boolean;
+    textToSpeechStream(rawtext: string, ctx?: TtsSynthesisContext): Promise<Readable>;
+    readonly audio$: Subject<Buffer>;
+    readonly done$: Subject<void>;
+    open(): Promise<void>;
+    startGeneration(): Promise<void>;
+    sendText(chunk: string): void;
+    flush(): void;
+    sendSeparatorFlush?(): void;
+    close(): void;
+}
+/** Optional session object shared by ASR and TTS factories for one dialog. */
+export type MediaProviderShared = {
+    dispose?: () => void;
+    close?: () => void;
+} & Record<string, unknown>;
+export type AsrProviderFactory = (ctx: MediaConnectorContext, shared: MediaProviderShared | undefined) => ScriptAsrConnector;
+export type TtsProviderFactory = (ctx: MediaConnectorContext, shared: MediaProviderShared | undefined) => ScriptTtsConnector;
+export interface MediaProvidersDefinition {
+    createShared?: (ctx: {
+        dialogUuid: string;
+        debug$: Subject<string>;
+    }) => MediaProviderShared;
+    asr?: Record<string, AsrProviderFactory>;
+    tts?: Record<string, TtsProviderFactory>;
+}
+/**
+ * Mark a named export as custom media providers (identity helper).
+ *
+ * @example
+ * ```ts
+ * export const mediaProviders = defineMediaProviders({
+ *   createShared: (ctx) => new MySession(ctx),
+ *   asr: { 'my-asr': (ctx, shared) => new MyAsr(ctx, shared) },
+ *   tts: { 'my-tts': (ctx, shared) => new MyTts(ctx, shared) },
+ * });
+ * ```
+ */
+export declare function defineMediaProviders(def: MediaProvidersDefinition): MediaProvidersDefinition;
+/** @internal helper type for hosts that mirror connector subjects */
+export type SubjectLike<T> = Subject<T> | Observable<T>;
+//# sourceMappingURL=media-providers.d.ts.map

package/dist/types/media-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-providers.d.ts","sourceRoot":"","sources":["../../src/types/media-providers.ts"],"names":[],"mappings":"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"}

package/dist/types/media-providers.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineMediaProviders = defineMediaProviders;
+/**
+ * Mark a named export as custom media providers (identity helper).
+ *
+ * @example
+ * ```ts
+ * export const mediaProviders = defineMediaProviders({
+ *   createShared: (ctx) => new MySession(ctx),
+ *   asr: { 'my-asr': (ctx, shared) => new MyAsr(ctx, shared) },
+ *   tts: { 'my-tts': (ctx, shared) => new MyTts(ctx, shared) },
+ * });
+ * ```
+ */
+function defineMediaProviders(def) {
+    return def;
+}
+//# sourceMappingURL=media-providers.js.map

package/dist/types/media-providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-providers.js","sourceRoot":"","sources":["../../src/types/media-providers.ts"],"names":[],"mappings":";;AAmGA,oDAIC;AAhBD;;;;;;;;;;;GAWG;AACH,SAAgB,oBAAoB,CAClC,GAA6B;IAE7B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/types/mixer.d.ts

@@ -1,5 +1,6 @@
 import { Observable } from 'rxjs';
 import type { CacheOptions } from './legacy-phrase';
+import type { TtsHandle } from './tts-handle';
 /**
  * How TTS audio is chunked and fed to the mixer.
  *
@@ -74,8 +75,16 @@ export interface PlayOptions {
     /**
      * Force a specific TTS vendor for this call, overriding **`channel.params.ttsVendor`**.
      * Ignored for **`play()`** when the source is raw audio (no synthesis).
+     * When {@link tts} is set, the handle's resolved vendor/config take precedence.
      */
     ttsVendor?: TtsVendor;
+    /**
+     * Pre-warmed TTS session from {@link import('./media-channel').MediaChannel.createTts}.
+     * Reuses the cached connector / streaming WebSocket so synthesis skips a fresh SSL handshake.
+     * When set, the handle's resolved vendor and connector config are used (overrides
+     * {@link ttsVendor} / {@link name} / {@link ttsConfig} for credential resolution).
+     */
+    tts?: TtsHandle;
     /**
      * logic-executor **`key_storage.name`**: use **`authentication_data.legacyTtsKeysByName[name]`**
      * for credentials. Overrides **`defaultTtsName`** on the channel.
@@ -107,6 +116,11 @@ export interface PlayOptions {
  */
 export interface PresayOptions {
     ttsVendor?: TtsVendor;
+    /**
+     * Pre-warmed TTS session from {@link import('./media-channel').MediaChannel.createTts}.
+     * Same reuse semantics as {@link PlayOptions.tts}.
+     */
+    tts?: TtsHandle;
     name?: string;
     ttsConfig?: Record<string, unknown>;
     ttsStrategy?: TtsStrategy;

package/dist/types/mixer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mixer.d.ts","sourceRoot":"","sources":["../../src/types/mixer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,MAAM,GACN,SAAS,GACT,QAAQ,GACR,OAAO,GACP,UAAU,GACV,UAAU,GACV,eAAe,GACf,aAAa,GACb,KAAK,GACL,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,mFAAmF;IACnF,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IAEf,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1C,yFAAyF;IACzF,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3C;oFACgF;IAChF,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uDAAuD;IACvD,KAAK,IAAI,IAAI,CAAC;CACf"}
+{"version":3,"file":"mixer.d.ts","sourceRoot":"","sources":["../../src/types/mixer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,MAAM,GACN,SAAS,GACT,QAAQ,GACR,OAAO,GACP,UAAU,GACV,UAAU,GACV,eAAe,GACf,aAAa,GACb,KAAK,GACL,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,mFAAmF;IACnF,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IAEf,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1C,yFAAyF;IACzF,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3C;oFACgF;IAChF,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uDAAuD;IACvD,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/types/script-context.d.ts

@@ -59,6 +59,21 @@ export interface ScriptDialogContext {
     callerId: string;
     /** Called number (DID / destination for inbound calls). */
     destinationNumber: string;
+    /**
+     * LE trunk id for this dialog/call — snapshot at script start.
+     *
+     * Resolved from `call.trunk_id`, inbound `X-Trunk-Id`, `dialog.params.trunk_id`,
+     * then `agent.trunk_id`. Omitted when no trunk is configured.
+     */
+    trunkId?: number;
+    /**
+     * LE `trunk.name` for {@link trunkId}, resolved by the host at script start.
+     *
+     * Available in online and headless runs when the platform trunk table is reachable.
+     * Not a SIP wire header — for inbound id-only signalling use
+     * `channel.sip.inviteSipHeaders['X-Trunk-Id']`.
+     */
+    trunkName?: string;
     /** Script record ID in the system. */
     scriptId: string;
     /** Human-readable script name. */

package/dist/types/script-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script-context.d.ts","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"script-context.d.ts","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":"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"}

package/dist/types/script-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"script-context.js","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":";;AA6QA,wCAcC;AApCD,MAAM,+BAA+B,GAAG,IAAI,GAAG,CAAC;IAC9C,iBAAiB;IACjB,oBAAoB;IACpB,cAAc;CACf,CAAC,CAAC;AACH,MAAM,8BAA8B,GAAG,IAAI,GAAG,CAAC;IAC7C,gBAAgB;IAChB,mBAAmB;CACpB,CAAC,CAAC;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAAC,OAA4B;IACzD,IAAI,CAAC,OAAO,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAEvC,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAE1D,IAAI,+BAA+B,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,oBAAoB,CAAC;IACzE,IAAI,8BAA8B,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACvE,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjD,IAAI,EAAE,KAAK,yBAAyB,IAAI,OAAO,CAAC,cAAc;QAC5D,OAAO,WAAW,CAAC;IAErB,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAEnE,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"script-context.js","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":";;AA4RA,wCAcC;AApCD,MAAM,+BAA+B,GAAG,IAAI,GAAG,CAAC;IAC9C,iBAAiB;IACjB,oBAAoB;IACpB,cAAc;CACf,CAAC,CAAC;AACH,MAAM,8BAA8B,GAAG,IAAI,GAAG,CAAC;IAC7C,gBAAgB;IAChB,mBAAmB;CACpB,CAAC,CAAC;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAAC,OAA4B;IACzD,IAAI,CAAC,OAAO,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAEvC,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAE1D,IAAI,+BAA+B,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,oBAAoB,CAAC;IACzE,IAAI,8BAA8B,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACvE,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjD,IAAI,EAAE,KAAK,yBAAyB,IAAI,OAAO,CAAC,cAAc;QAC5D,OAAO,WAAW,CAAC;IAErB,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAEnE,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}

package/dist/types/tts-handle.d.ts

@@ -0,0 +1,194 @@
+import type { Observable } from 'rxjs';
+import type { MediaError } from './errors';
+import type { PlayOptions, PresayOptions } from './mixer';
+/**
+ * Arguments for {@link import('./media-channel').MediaChannel.createTts}.
+ *
+ * Mirrors {@link import('./asr-handle').AsrConfig} credential selection for TTS:
+ * when Voctiv platform compatibility is on, **`name`** selects a row from
+ * **`authentication_data.legacyTtsKeysByName`**. You may also set the same selector
+ * as **`data.name`** (stripped before vendor params are built).
+ *
+ * Call **`createTts`** early in the dialog to open / warm the vendor connection
+ * (HTTP keep-alive pool or streaming WebSocket) so later {@link TtsHandle.say}
+ * / {@link TtsHandle.say$} / {@link TtsHandle.presay} calls reuse it instead of
+ * paying SSL handshake latency on every utterance.
+ */
+export interface TtsConfig {
+    /**
+     * TTS vendor / engine hint, e.g. `"elevenlabs"`, `"google"`, `"azure"`, `"voctiv"`.
+     * Resolved via ScriptEngine vendor aliases. If you set **`name`** but omit **`vendor`**,
+     * the runtime may infer vendor from the key row's **`platform`** in the catalog.
+     */
+    vendor?: string;
+    /**
+     * logic-executor **`key_storage.name`** for this dialog's agent + company. Selects credentials
+     * from **`authentication_data.legacyTtsKeysByName[name]`** when Voctiv platform PostgreSQL key auth is enabled.
+     * Overrides channel **`defaultTtsName`**.
+     */
+    name?: string;
+    /**
+     * Vendor-specific connection parameters (voice id, model, `output_format`, nested JSON, …).
+     * Merged last over channel defaults and catalog credentials so the script can override
+     * per session. Primitives are stringified; objects and arrays are JSON-serialized.
+     *
+     * Do not rely on **`name`** here for third-party "model name" fields — the runtime consumes
+     * it as the storage row selector and removes it before vendor config is built.
+     */
+    data?: Record<string, unknown>;
+}
+/**
+ * Playback options for {@link TtsHandle.say} / {@link TtsHandle.say$}.
+ *
+ * Vendor / credentials come from {@link import('./media-channel').MediaChannel.createTts};
+ * only mixer and strategy fields apply here.
+ */
+export type TtsSayOptions = Omit<PlayOptions, 'tts' | 'ttsVendor' | 'name' | 'ttsConfig'>;
+/**
+ * Options for {@link TtsHandle.presay}.
+ *
+ * Vendor / credentials come from {@link import('./media-channel').MediaChannel.createTts}.
+ */
+export type TtsPresayOptions = Omit<PresayOptions, 'tts' | 'ttsVendor' | 'name' | 'ttsConfig'>;
+/** Why a tracked utterance was cancelled before natural completion. */
+export type TtsUtteranceCancelReason = 'stop' | 'destroy';
+/**
+ * Lifecycle events for one {@link TtsHandle.say$} invocation.
+ *
+ * Typical sequence (sentence strategy):
+ * `queued` → (`speaking` → `done`)×N then Observable **complete**.
+ * `done` means one sentence/phrase finished playback (not the whole `say$` call).
+ * Single-item / streaming strategy: one `speaking` → one `done` then **complete**.
+ * On barge-in / `audio.stop`: `queued` → (`speaking`?) → `cancelled` then **complete**.
+ * On synthesis failure: `queued` → (`speaking`?) then the Observable **errors** with
+ * {@link MediaError} (also mirrored on {@link TtsHandle.error$} / `channel.events.error$`).
+ */
+export type TtsUtteranceEvent = {
+    state: 'queued';
+    alias: string;
+    queue: number;
+    /**
+     * Full utterance text known so far.
+     * Plain string input: complete text. Token stream: grows as chunks arrive
+     * (initial `queued` may have `text: ''`).
+     */
+    text: string;
+} | {
+    state: 'speaking';
+    alias: string;
+    queue: number;
+    /** Full utterance text accumulated so far (stream) or the whole input (string). */
+    text: string;
+    /**
+     * Text of the sentence/segment currently starting playback when the host
+     * uses sentence-split aliases (`alias-0`, `alias-1`, …).
+     * For a single-item utterance (streaming strategy / exact alias) this equals {@link text}.
+     */
+    sentenceText: string;
+    /** Index of the sentence segment (`0` for `alias-0`), when applicable. */
+    sentenceIndex?: number;
+    /** Concrete mixer item alias (may be `alias-0` for sentence-split TTS). */
+    itemAlias?: string;
+} | {
+    state: 'done';
+    alias: string;
+    queue: number;
+    /** Full utterance text accumulated so far (stream) or the whole input (string). */
+    text: string;
+    /**
+     * Text of the sentence/segment that just finished playback.
+     * Same rules as {@link TtsUtteranceEvent} `speaking.sentenceText`.
+     */
+    sentenceText: string;
+    /** Index of the sentence segment (`0` for `alias-0`), when applicable. */
+    sentenceIndex?: number;
+    /** Concrete mixer item alias that finished. */
+    itemAlias?: string;
+} | {
+    state: 'cancelled';
+    alias: string;
+    queue: number;
+    reason: TtsUtteranceCancelReason;
+    /** Accumulated text at cancel time. */
+    text: string;
+};
+/**
+ * Pre-warmed TTS session returned by {@link import('./media-channel').MediaChannel.createTts}.
+ *
+ * Use **`say`** / **`say$`** / **`presay`** on this handle (same idea as
+ * {@link import('./asr-handle').AsrHandle} methods) so synthesis reuses the cached
+ * connector / streaming WebSocket. Call **`destroy()`** when done
+ * (e.g. on `channel.events.terminated$`) to release the session.
+ *
+ * You may still pass the handle as {@link import('./mixer').PlayOptions.tts} to
+ * `channel.audio.say` / `presay` if needed.
+ *
+ * If connector creation fails, SIP/WS return a degraded handle: `say`/`say$`/`presay` fall back
+ * to an ephemeral connection, and the creation failure is reported on
+ * {@link import('./media-channel').ChannelEvents.error$}.
+ *
+ * ```ts
+ * const tts = await channel.createTts({ name: 'elevenlabs-main' });
+ * tts.error$.subscribe(err => console.log('TTS error:', err.message));
+ *
+ * await tts.say('Hello', { alias: 'greeting' });
+ *
+ * tts.say$('Next', { alias: 'reply' }).subscribe({
+ *   next: (e) => { if (e.state === 'speaking') console.log('now playing', e.alias); },
+ *   error: (err) => console.log('TTS failed', err.message),
+ * });
+ *
+ * tts.destroy();
+ * ```
+ */
+export interface TtsHandle {
+    /** Opaque id for this pre-warmed TTS session. */
+    readonly id: string;
+    /**
+     * Runtime errors from the TTS provider for this session (auth failures, disconnects, etc.).
+     *
+     * A degraded handle (returned when connector creation itself failed) has an inert `error$`
+     * that never emits — the creation failure is reported on {@link import('./media-channel').ChannelEvents.error$} instead.
+     */
+    readonly error$: Observable<MediaError>;
+    /**
+     * Synthesize and play text on a mixer queue, reusing this session's connector.
+     *
+     * Resolves when playback of this invocation has finished (or was aborted).
+     * For per-utterance lifecycle (`queued` / `speaking` / `done` / …) use {@link say$}.
+     */
+    say(input: string | Observable<string>, options?: TtsSayOptions): Promise<void>;
+    /**
+     * Same synthesis path as {@link say}, but emits {@link TtsUtteranceEvent} for this utterance.
+     *
+     * Only available on handles from {@link import('./media-channel').MediaChannel.createTts}
+     * (not on `channel.audio.say`). Emits `done` per finished sentence; Observable **completes**
+     * when the whole call ends (or after `cancelled`). Synthesis failures go to the Observable
+     * **error** channel as {@link MediaError}.
+     *
+     * ```ts
+     * tts.say$('One. Two.', { alias: 'greet', queue: 0 }).subscribe({
+     *   next: (e) => {
+     *     switch (e.state) {
+     *       case 'queued': break;      // e.text — full string (or '' for live stream)
+     *       case 'speaking': break;    // e.sentenceText — sentence starting playback
+     *       case 'done': break;        // e.sentenceText — that sentence finished
+     *       case 'cancelled': break;   // stop / destroy
+     *     }
+     *   },
+     *   complete: () => {},              // whole say$ finished
+     *   error: (err: MediaError) => console.log('TTS failed', err.message),
+     * });
+     * ```
+     */
+    say$(input: string | Observable<string>, options?: TtsSayOptions): Observable<TtsUtteranceEvent>;
+    /**
+     * Pre-synthesize text into the host TTS cache using this session's connector.
+     *
+     * Same behaviour as {@link import('./media-channel').ChannelAudio.presay}.
+     */
+    presay(text: string, options?: TtsPresayOptions): Promise<void>;
+    /** Tear down the cached connector / streaming socket. Idempotent-safe on well-behaved hosts. */
+    destroy(): void;
+}
+//# sourceMappingURL=tts-handle.d.ts.map

package/dist/types/tts-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-handle.d.ts","sourceRoot":"","sources":["../../src/types/tts-handle.ts"],"names":[],"mappings":"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"}

package/dist/types/tts-handle.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=tts-handle.js.map

package/dist/types/tts-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-handle.js","sourceRoot":"","sources":["../../src/types/tts-handle.ts"],"names":[],"mappings":""}

package/examples/README.md

@@ -11,6 +11,7 @@ Each file exports one `defineScript` handler. The host **always** invokes that s
 | [schedule-call-with-defaults.ts](./schedule-call-with-defaults.ts) | `platform.call()` using CMS defaults from `context` |
 | [after-call-continuation.ts](./after-call-continuation.ts) | `onSuccessCall` / `onFailedCall` + `getScriptPhase()` |
 | [read-recall-from-params.ts](./read-recall-from-params.ts) | `parseRecallDelaySeconds()` / `parseRecallCount()` |
+| [custom-media-providers.ts](./custom-media-providers.ts) | `defineMediaProviders` + `createAsr` / `createTts` / `say$` |
 
 ## Recall flow
 

package/examples/custom-media-providers.ts

@@ -0,0 +1,128 @@
+/**
+ * Custom ASR / TTS from a trusted logic package.
+ *
+ * Export `mediaProviders` next to `defineScript`. The host loads that export
+ * outside the sandbox and wires vendors into `createAsr` / `createTts` with the
+ * same warm TCP/WS reuse as built-in engines.
+ *
+ * Batch and streaming TTS share one class (`supportsStreaming()` + streaming
+ * lifecycle methods). Do not register a separate streaming map.
+ */
+import { Readable } from 'stream';
+import { Subject } from 'rxjs';
+import {
+  defineScript,
+  defineMediaProviders,
+  type MediaConnectorContext,
+  type MediaProviderShared,
+  type ScriptAsrConnector,
+  type ScriptTtsConnector,
+} from '@voctiv/agent-sdk';
+
+type SharedSession = MediaProviderShared & {
+  turns: number;
+};
+
+class EchoAsr implements ScriptAsrConnector {
+  readonly transcription$ = new Subject<{ text: string; isFinal: boolean }>();
+  readonly result$ = new Subject<string>();
+  readonly error$ = new Subject<{ message: string; code?: number }>();
+
+  constructor(
+    private readonly ctx: MediaConnectorContext,
+    private readonly shared: SharedSession | undefined,
+  ) {}
+
+  isOpen(): boolean {
+    return true;
+  }
+
+  send(_audio: ArrayBufferLike): void {
+    // Forward PCM to your vendor here.
+  }
+
+  speech(_active: boolean): void {}
+
+  finalize(): void {
+    const text = 'heard';
+    this.transcription$.next({ text, isFinal: true });
+    this.result$.next(text);
+    if (this.shared) this.shared.turns += 1;
+  }
+
+  close(): void {
+    this.transcription$.complete();
+    this.result$.complete();
+    this.error$.complete();
+  }
+}
+
+class BatchOrStreamTts implements ScriptTtsConnector {
+  readonly audio$ = new Subject<Buffer>();
+  readonly done$ = new Subject<void>();
+
+  constructor(
+    private readonly ctx: MediaConnectorContext,
+    private readonly shared: SharedSession | undefined,
+  ) {}
+
+  /** Return true when this connector also owns a long-lived streaming socket. */
+  supportsStreaming(): boolean {
+    return false;
+  }
+
+  async textToSpeechStream(rawtext: string): Promise<Readable> {
+    void this.ctx;
+    void this.shared;
+    // Replace with HTTP keep-alive synthesis that returns a PCM stream.
+    return Readable.from([Buffer.from(rawtext, 'utf8')]);
+  }
+
+  async open(): Promise<void> {}
+  async startGeneration(): Promise<void> {}
+  sendText(_chunk: string): void {}
+  flush(): void {}
+  close(): void {
+    // Soft-close streaming sockets for reuse; do not complete Subjects if the
+    // host may call open() again on the same fingerprint.
+  }
+}
+
+export const mediaProviders = defineMediaProviders({
+  createShared: (): SharedSession => ({
+    turns: 0,
+    dispose() {
+      /* release vendor app state for this dialog */
+    },
+  }),
+  asr: {
+    'my-asr': (ctx, shared) => new EchoAsr(ctx, shared as SharedSession),
+  },
+  tts: {
+    'my-tts': (ctx, shared) =>
+      new BatchOrStreamTts(ctx, shared as SharedSession),
+  },
+});
+
+export default defineScript(async ({ channel, logger }) => {
+  channel.sip.answer();
+
+  const asr = await channel.createAsr({ vendor: 'my-asr' });
+  const tts = await channel.createTts({ vendor: 'my-tts' });
+
+  await tts.say('Hello from a custom TTS connector.');
+
+  tts.say$('One. Two.', { alias: 'reply' }).subscribe({
+    next: (ev) => {
+      logger.log('tts utterance', { state: ev.state, alias: ev.itemAlias });
+    },
+    error: (err) => logger.error('tts failed', err),
+  });
+
+  // Same warm handle via audio.say:
+  await channel.audio.say('Reuse handle', { tts });
+
+  asr.destroy();
+  tts.destroy();
+  channel.sip.hangup();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voctiv/agent-sdk",
-  "version": "0.2.16",
+  "version": "0.3.1",
   "description": "Voctiv TypeScript agent SDK: defineScript and platform types for the voice/dialog scripting runtime.",
   "license": "UNLICENSED",
   "author": "",