@voctiv/agent-sdk 0.3.0 → 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 |
@@ -554,6 +557,9 @@ All audio playback goes through **`channel.audio`** (`ChannelAudio`). There are
 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',
@@ -774,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

package/dist/index.d.ts

@@ -30,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';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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,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"}
+{"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

@@ -30,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAerB,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"}
+{"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/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/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.3.0",
+  "version": "0.3.1",
   "description": "Voctiv TypeScript agent SDK: defineScript and platform types for the voice/dialog scripting runtime.",
   "license": "UNLICENSED",
   "author": "",