@voctiv/agent-sdk 0.1.2 → 0.2.0

package/dist/define-script.d.ts

@@ -1,7 +1,8 @@
 import type { BehaviorSubject, Observable } from 'rxjs';
-import { MediaChannel } from './types/media-channel';
+import type { MediaChannel } from './types/media-channel';
 import { ScriptLogger } from './types/logger';
 import type { NluExtractOptions, NluInferResult } from './types/nlu';
+import type { LegacyGetRecordsParams, LegacyPhraseRecord } from './types/legacy-phrase';
 /**
  * NLU (Natural Language Understanding) API.
  *
@@ -23,11 +24,11 @@ export interface NluScriptApi {
     extract$(utterance: string, options?: NluExtractOptions): Observable<NluInferResult>;
 }
 /**
- * Typed first-level dialog context passed to every script.
- * Contains all metadata about the current session: caller info,
- * script identity, routing params, and legacy compat fields.
+ * First-level **`context`** passed to every **`defineScript`** handler.
  *
- * Index signature allows arbitrary extra fields for forward compat.
+ * Combines **identity** (dialog, script, agent), **telephony** (caller/destination),
+ * **payload** (**`initialData`** vs **`dialogParams`**), **Voctiv platform** rows (**`dialogEntity`**),
+ * and **runtime** (**`env$`**, **`runTime`**). The index signature allows extra host-specific keys.
  */
 export interface ScriptDialogContext {
     /** Short language code, e.g. `"ru"`, `"en"`. */
@@ -52,11 +53,27 @@ export interface ScriptDialogContext {
     agentUuid?: string;
     /** Numeric NLU agent ID used for extract() calls. */
     agentId: number;
-    /** Original params snapshot at session start (immutable). */
-    initialParams: Record<string, unknown>;
-    /** Mutable merged params (channel + session + route). */
-    params: Record<string, unknown>;
-    /** Whether legacy V3 compatibility mode is active. */
+    /**
+     * **Snapshot** of dialog/session payload when the script run started.
+     *
+     * Shallow copy of the merge **`channelParams` + `sessionParams`** after the server removes
+     * untrusted keys (e.g. client cannot spoof **`agentUuid`** here). **Do not mutate** — use
+     * **`dialogParams`** for the live map. Compare with **`dialogParams`** to see what changed
+     * during the call (if the host updates the live object).
+     */
+    initialData: Record<string, unknown>;
+    /**
+     * **Live** dialog/session parameter map for this run (same merge as **`initialData`** at start).
+     *
+     * The host may add or overwrite keys while the session progresses. For media scripts this
+     * aligns with {@link import('./types/media-channel').MediaChannel.params} (Omni defaults, route,
+     * Voctiv platform ASR/TTS: **`defaultAsrName`**, **`defaultTtsName`**, **`asrVendor`**, **`ttsVendor`**,
+     * **`asrConfig`**, **`ttsConfig`**, **`authentication_data`**, **`legacyAsrKeysByName`** /
+     * **`legacyTtsKeysByName`**, etc.). **Read/write** according to your integration; scripts should
+     * treat unknown keys as opaque.
+     */
+    dialogParams: Record<string, unknown>;
+    /** Whether Voctiv platform compatibility mode is active. */
     legacyV3Compat: boolean;
     /** `true` when the script runs without a real media channel (offline / queue / messaging). */
     headless: boolean;
@@ -70,14 +87,19 @@ export interface ScriptDialogContext {
      * **Persistence:** On script completion (success or error), the runtime snapshots `env$` and
      * persists it; the script return value must not carry env (see {@link ScriptResult}).
      *
-     * Only active in legacy V3 compatibility mode.
+     * Only active in Voctiv platform compatibility mode.
      */
     env$?: BehaviorSubject<Record<string, unknown> | undefined>;
-    /** Raw `dialog` table row from legacy DB. */
+    /** Raw `dialog` table row from the Voctiv platform database. */
     dialogEntity?: Record<string, unknown>;
-    /** Raw `call` table row from legacy DB. */
+    /** Raw `call` table row from the Voctiv platform database. */
     callEntity?: Record<string, unknown>;
-    /** Available TTS/ASR media key identifiers (legacy compat). */
+    /**
+     * Optional catalog of media keys exposed to the script (Voctiv platform / Omni), e.g. UUIDs or labels
+     * for UI or logging. **Credentials** still come from **`dialogParams.authentication_data`**
+     * (and the channel mirror); use **`name`** on {@link import('./types/asr-handle').AsrConfig} /
+     * {@link import('./types/mixer').PlayOptions} to select **`key_storage.name`** when LE credential maps exist.
+     */
     availableMediaKeys?: string[];
     /** Script entry point for routing (e.g. `"on_recall"`, `"on_message_api_received"`). */
     entryPoint?: string;
@@ -89,13 +111,39 @@ export interface ScriptDialogContext {
     recallDelay?: number;
     /** Inbound message that triggered this headless session (messaging). */
     inboundMessage?: InboundMessage;
+    /**
+     * Async-phase execution budget: remaining time, extension pool, {@link ScriptRunTime.extend}.
+     * Injected by the runtime; absent only in tests or non-standard hosts.
+     */
+    runTime?: ScriptRunTime;
     /** @internal NLU runtime config — opaque to scripts. */
     _nlu?: unknown;
     [key: string]: unknown;
 }
+/**
+ * Time budget for the script async phase (after VM load). Lets scripts check remaining time
+ * and request limited extensions (capped by the runtime).
+ */
+export interface ScriptRunTime {
+    /** Initial budget in ms before any {@link extend}. */
+    readonly budgetMs: number;
+    /** Maximum total extra ms grantable across all {@link extend} calls for this session. */
+    readonly maxExtendMs: number;
+    /** Milliseconds left until the runtime stops the async script phase. */
+    remainingMs(): number;
+    /** Extension quota not yet granted (ms). */
+    remainingExtendMs(): number;
+    /**
+     * Grants up to `requestedMs` additional runtime, limited by remaining extension quota.
+     * @returns Granted milliseconds (0 if nothing could be granted).
+     */
+    extend(requestedMs: number): number;
+}
 /** Error info attached to {@link ScriptResult} when a script fails. */
 export interface ScriptError {
-    /** Error category: `"script_error"` | `"server_error"` (mirrors old LE stat names). */
+    /**
+     * Machine-readable category, e.g. `script_error`, `script_load_failed`, `time_limit_exceeded`.
+     */
     code: string;
     /** Human-readable error description. */
     message: string;
@@ -113,7 +161,7 @@ export interface ScriptResult {
     error?: ScriptError;
 }
 /**
- * Result after the runtime attaches the final `env$` snapshot (legacy persistence).
+ * Result after the runtime attaches the final `env$` snapshot (Voctiv platform persistence).
  * Scripts never construct this type — use {@link ScriptResult} from `defineScript` handlers.
  */
 export interface PersistedScriptResult extends ScriptResult {
@@ -150,7 +198,7 @@ export interface ScheduleCallOptions {
  * Dialog state API — read and update dialog routing metadata.
  *
  * Setting `entryPoint` or `result` immediately persists the change
- * to the legacy DB (non-blocking, fire-and-forget).
+ * to the Voctiv platform database (non-blocking, fire-and-forget).
  */
 export interface DialogApi {
     /** Current script entry point (e.g. `"on_recall"`). Set to change routing for next call. */
@@ -206,10 +254,10 @@ export interface MessagingApi {
     readonly message$: Observable<InboundMessage>;
 }
 /**
- * Platform API — legacy-compatible operations available to scripts.
+ * Platform API — Voctiv platform–compatible operations available to scripts.
  *
  * Provides access to NLU, dialog state management, outbound call scheduling,
- * and messaging. Only functional in legacy V3 compatibility mode
+ * and messaging. Only functional in Voctiv platform compatibility mode
  * (except `nlu` which is always available).
  */
 export interface PlatformApi {
@@ -226,6 +274,13 @@ export interface PlatformApi {
      * @param options - Scheduling, routing, and retry options.
      */
     call(msisdn: string, options?: ScheduleCallOptions): Promise<void>;
+    /**
+     * Voctiv platform only: load `record_phrase` / `record_phrase_file` rows from the LE PostgreSQL database
+     * (same filters as old `RecordPhrase.get_records`). Returns playable phrase record objects.
+     * Requires numeric `agent_id` on the dialog (params or `NLU_DEFAULT_AGENT_ID`) and
+     * `LEGACY_V3_RECORD_PHRASE_ROOT` pointing at the phrase file storage root.
+     */
+    getRecords?(params: LegacyGetRecordsParams): Promise<LegacyPhraseRecord[]>;
 }
 /**
  * Top-level context passed to every script function.
@@ -257,7 +312,7 @@ export interface ScriptContext {
     channel: MediaChannel;
     /** Structured logger — writes to system log and optionally to `dialog_stats` DB table. */
     logger: ScriptLogger;
-    /** Dialog context with session metadata, routing params, and legacy fields. */
+    /** Dialog context with session metadata, routing params, and Voctiv platform fields. */
     context: ScriptDialogContext;
     /** Platform API — NLU, dialog state, messaging, outbound calls. */
     platform: PlatformApi;
@@ -268,15 +323,27 @@ export interface ScriptContext {
  */
 export type ScriptFn = (ctx: ScriptContext) => void | ScriptResult | Promise<void | ScriptResult>;
 /**
- * Define a script entry point.
- * Wrap your script function with this to enable type checking and runtime registration.
+ * Mark the default export as a typed script entry point (identity wrapper; no runtime transform).
+ *
+ * The host loads this module, invokes the function with {@link ScriptContext}, and persists
+ * {@link ScriptResult} / {@link ScriptDialogContext.env$} according to Voctiv platform rules.
+ *
+ * @param fn - Handler receiving **`{ channel, logger, context, platform }`**.
+ *   - Use **`channel`** for ASR/TTS (see {@link import('./types/asr-handle').AsrConfig.name},
+ *     {@link import('./types/mixer').PlayOptions.name} for LE **`key_storage.name`** selection).
+ *   - Use **`context.dialogParams`** / **`context.dialogUuid`** for routing; **`platform`** for NLU, calls, messaging.
+ * @returns The same **`fn`** reference.
  *
  * @example
  * ```ts
  * import { defineScript } from '@lib/scripting-sdk';
  *
  * export default defineScript(async ({ channel, logger, context, platform }) => {
- *   // your script logic here
+ *   const asr = await channel.createAsr({
+ *     name: 'my-yandex-key',
+ *     vendor: 'Y',
+ *     language: 'ru-RU',
+ *   });
  * });
  * ```
  */

package/dist/define-script.d.ts.map

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

package/dist/define-script.js

@@ -2,15 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineScript = defineScript;
 /**
- * Define a script entry point.
- * Wrap your script function with this to enable type checking and runtime registration.
+ * Mark the default export as a typed script entry point (identity wrapper; no runtime transform).
+ *
+ * The host loads this module, invokes the function with {@link ScriptContext}, and persists
+ * {@link ScriptResult} / {@link ScriptDialogContext.env$} according to Voctiv platform rules.
+ *
+ * @param fn - Handler receiving **`{ channel, logger, context, platform }`**.
+ *   - Use **`channel`** for ASR/TTS (see {@link import('./types/asr-handle').AsrConfig.name},
+ *     {@link import('./types/mixer').PlayOptions.name} for LE **`key_storage.name`** selection).
+ *   - Use **`context.dialogParams`** / **`context.dialogUuid`** for routing; **`platform`** for NLU, calls, messaging.
+ * @returns The same **`fn`** reference.
  *
  * @example
  * ```ts
  * import { defineScript } from '@lib/scripting-sdk';
  *
  * export default defineScript(async ({ channel, logger, context, platform }) => {
- *   // your script logic here
+ *   const asr = await channel.createAsr({
+ *     name: 'my-yandex-key',
+ *     vendor: 'Y',
+ *     language: 'ru-RU',
+ *   });
  * });
  * ```
  */

package/dist/define-script.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-script.js","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":";;AA4TA,oCAEC;AAfD;;;;;;;;;;;;GAYG;AACH,SAAgB,YAAY,CAAC,EAAY;IACvC,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"define-script.js","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":";;AAoYA,oCAEC;AA3BD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,YAAY,CAAC,EAAY;IACvC,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/index.d.ts

@@ -1,9 +1,29 @@
+/**
+ * @packageDocumentation
+ * **Agent scripting SDK** for `node-asr-tts-connector`: typed **`defineScript`** context,
+ * {@link import('./types/media-channel').MediaChannel}, ASR/TTS, LLM, SIP, and Voctiv platform (LE-compat) helpers.
+ *
+ * ### Selecting ASR/TTS credentials by `key_storage.name` (Voctiv platform)
+ *
+ * When the host enables Voctiv platform PostgreSQL key auth, **`channel.params.authentication_data`**
+ * may contain:
+ * - **`legacyAsrKeysByName`**: map **`name`** → `{ platform, flat }` for ASR
+ * - **`legacyTtsKeysByName`**: same for TTS
+ *
+ * Rows are scoped to **this dialog’s agent and company** (no agent UUID in the script). Use:
+ * - {@link import('./types/asr-handle').AsrConfig.name} or **`data.name`** on **`createAsr`**
+ * - {@link import('./types/mixer').PlayOptions.name} or **`ttsConfig.name`** on **`say`/`play`/`presay`**
+ *
+ * Channel defaults **`defaultAsrName`** / **`defaultTtsName`** apply when **`name`** is omitted.
+ */
 export { defineScript } from './define-script';
-export type { ScriptContext, ScriptDialogContext, ScriptResult, PersistedScriptResult, ScriptError, ScriptFn, NluScriptApi, PlatformApi, DialogApi, ScheduleCallOptions, SendMessageOptions, InboundMessage, MessagingApi, } from './define-script';
+export type { ScriptContext, ScriptDialogContext, ScriptRunTime, ScriptResult, PersistedScriptResult, ScriptError, ScriptFn, NluScriptApi, PlatformApi, DialogApi, ScheduleCallOptions, SendMessageOptions, InboundMessage, MessagingApi, } from './define-script';
 export type { ScriptLogger } from './types/logger';
-export type { MediaChannel, ChannelAudio, ChannelEvents, ChannelLlm, ChannelSip, LlmOptions, LlmStreamChunk, ExtractOptions, } from './types/media-channel';
+export type { MediaChannel, ChannelAudio, ChannelEvents, ChannelLlm, ChannelSip, LlmOptions, LlmStreamChunk, ExtractOptions, PersistentLlmStreamHandle, } from './types/media-channel';
 export type { AsrHandle, AsrConfig, AsrVadConfig, AsrSmartTurnConfig } from './types/asr-handle';
 export type { MixerQueueControl, PlayOptions, TtsStrategy, TtsVendor } from './types/mixer';
+export type { LegacyPhraseRecord, LegacyGetRecordsParams, LegacySavePhraseOptions, } from './types/legacy-phrase';
+export { LEGACY_PHRASE_RECORD_BRAND, isLegacyPhraseRecord, } from './types/legacy-phrase';
 export type { TextInput } from './types/text-input';
 export type { DtmfEvent, SipInfo, SipSignal, DataMessage, } from './types/events';
 export type { NluExtractOptions, NluInferResult } from './types/nlu';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACjG,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC5F,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACjG,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GACxB,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"}

package/dist/index.js

@@ -1,6 +1,27 @@
 "use strict";
+/**
+ * @packageDocumentation
+ * **Agent scripting SDK** for `node-asr-tts-connector`: typed **`defineScript`** context,
+ * {@link import('./types/media-channel').MediaChannel}, ASR/TTS, LLM, SIP, and Voctiv platform (LE-compat) helpers.
+ *
+ * ### Selecting ASR/TTS credentials by `key_storage.name` (Voctiv platform)
+ *
+ * When the host enables Voctiv platform PostgreSQL key auth, **`channel.params.authentication_data`**
+ * may contain:
+ * - **`legacyAsrKeysByName`**: map **`name`** → `{ platform, flat }` for ASR
+ * - **`legacyTtsKeysByName`**: same for TTS
+ *
+ * Rows are scoped to **this dialog’s agent and company** (no agent UUID in the script). Use:
+ * - {@link import('./types/asr-handle').AsrConfig.name} or **`data.name`** on **`createAsr`**
+ * - {@link import('./types/mixer').PlayOptions.name} or **`ttsConfig.name`** on **`say`/`play`/`presay`**
+ *
+ * Channel defaults **`defaultAsrName`** / **`defaultTtsName`** apply when **`name`** is omitted.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineScript = void 0;
+exports.isLegacyPhraseRecord = exports.LEGACY_PHRASE_RECORD_BRAND = 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 legacy_phrase_1 = require("./types/legacy-phrase");
+Object.defineProperty(exports, "LEGACY_PHRASE_RECORD_BRAND", { enumerable: true, get: function () { return legacy_phrase_1.LEGACY_PHRASE_RECORD_BRAND; } });
+Object.defineProperty(exports, "isLegacyPhraseRecord", { enumerable: true, get: function () { return legacy_phrase_1.isLegacyPhraseRecord; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAA+C;AAAtC,6GAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAqCrB,uDAG+B;AAF7B,2HAAA,0BAA0B,OAAA;AAC1B,qHAAA,oBAAoB,OAAA"}

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

@@ -1,5 +1,8 @@
 import { Observable } from 'rxjs';
-/** Voice Activity Detection (VAD) tuning parameters. */
+/**
+ * Voice Activity Detection (VAD) tuning — used when the runtime attaches an energy/Silero-based
+ * VAD in front of the ASR connector. Exact semantics depend on the telephony VAD implementation.
+ */
 export interface AsrVadConfig {
     /** Energy threshold to start speech detection (0.0–1.0). */
     positiveThreshold?: number;
@@ -11,70 +14,117 @@ export interface AsrVadConfig {
     energyFloor?: number;
     /** Smoothing factor for noise floor estimation (0.0–1.0). */
     noiseFloorAlpha?: number;
-    /** Frames of audio to include before detected speech start. */
+    /** Frames of PCM (typically 20 ms @ 8 kHz) to prepend before detected speech start. */
     preSpeechFrames?: number;
     /** Silence frames after speech before confirming end-of-speech. */
     postSpeechFrames?: number;
 }
-/** Smart turn-taking configuration — controls when to finalize ASR during conversation. */
+/**
+ * Smart turn-taking — controls when the runtime finalizes an utterance (end-of-turn) while
+ * streaming audio to ASR. Reduces cutting off the user mid-sentence when enabled.
+ */
 export interface AsrSmartTurnConfig {
-    /** Enable smart turn-taking (default: false). */
+    /** When `true`, turn-taking heuristics are applied (defaults vary by host). */
     enabled?: boolean;
-    /** Frames of speech before starting a turn. */
+    /** Frames of speech that must be seen before a “turn” can start. */
     triggerFrames?: number;
-    /** Frames to wait before retrying after a short pause. */
+    /** Frames to wait before retrying after a short pause inside an utterance. */
     retryFrames?: number;
-    /** Max silence frames before force-finalizing the turn. */
+    /** Max silence frames before force-finalizing the current turn. */
     maxSilenceFrames?: number;
-    /** Milliseconds to wait for confirmation after potential end-of-turn. */
+    /** Milliseconds to wait for confirmation after a candidate end-of-turn. */
     confirmMs?: number;
-    /** Hard timeout: finalize after this many ms of silence regardless. */
+    /** Hard cap: finalize after this many milliseconds of silence regardless of other rules. */
     silenceTimeoutMs?: number;
 }
-/** Configuration for creating an ASR (speech recognition) handle. */
+/**
+ * Arguments for {@link import('./media-channel').MediaChannel.createAsr}.
+ *
+ * ### Voctiv platform + logic-executor `key_storage`
+ *
+ * When Voctiv platform compatibility is on and the connector loaded credentials from PostgreSQL, the session’s
+ * `authentication_data` includes **`legacyAsrKeysByName`**: a map from **`key_storage.name`**
+ * (string) to flat connector parameters (`api_key`, `base_url`, …) for **this dialog’s agent
+ * and company**. You do **not** pass agent UUID in the script — the dialog already belongs to an agent.
+ *
+ * - **`name`**: pick which row from that map to use (same value as in LE admin for the key).
+ * - If omitted, the channel default **`defaultAsrName`** (from Omni / route) is used.
+ * - If neither is set, credentials fall back to the usual **`authentication_data.asr.<engine>`**
+ *   blob for the resolved vendor (main/reserved keys on the agent).
+ *
+ * You may also set the same selector as **`data.name`**; it must not be sent to the ASR vendor
+ * as a connector field — the runtime strips it when merging config.
+ *
+ * ### Vendor
+ *
+ * **`vendor`** is resolved via internal aliases (`"yandex"`, `"Y"`, `"neuro_v3"`, …). If you set
+ * **`name`** but omit **`vendor`**, the runtime may infer vendor from the key row’s **`platform`**
+ * in the catalog.
+ */
 export interface AsrConfig {
-    /** ASR vendor / engine identifier. */
+    /**
+     * ASR vendor / engine hint: single-letter code (`"Y"`, `"D"`, …) or legacy name
+     * (`"yandex"`, `"neuro_v3"`, …). See host `media-vendor-aliases` mapping.
+     */
     vendor?: string;
-    /** Recognition language (BCP-47, e.g. `"ru-RU"`). */
+    /**
+     * logic-executor **`key_storage.name`** for this dialog’s agent + company. Selects credentials
+     * from **`authentication_data.legacyAsrKeysByName[name]`** when Voctiv platform PostgreSQL key auth is enabled.
+     * Overrides channel **`defaultAsrName`**.
+     */
+    name?: string;
+    /** Recognition language (BCP-47), e.g. `"ru-RU"`. Passed through to the connector as `language`. */
     language?: string;
-    /** Vendor-specific configuration parameters. */
+    /**
+     * Vendor-specific connection parameters (URLs, timeouts, model ids, …). Merged last over
+     * catalog credentials so the script can override per call. Primitive values are stringified.
+     * Do not rely on **`name`** here for third-party “model name” fields — use a key not consumed
+     * as the storage row selector, or set **`name`** only at the top level.
+     */
     data?: Record<string, unknown>;
-    /** VAD tuning. */
+    /** Optional VAD tuning for this session (see host implementation). */
     vad?: AsrVadConfig;
-    /** Smart turn-taking tuning. */
+    /** Optional smart-turn tuning for this session. */
     smartTurn?: AsrSmartTurnConfig;
 }
 /**
- * ASR handle — a live speech recognition session.
+ * Live speech recognition session returned by {@link import('./media-channel').MediaChannel.createAsr}.
  *
- * Created via `channel.createAsr(config)`. Emits partial and final
- * recognition results as Observables. Must be destroyed when no longer needed.
+ * Subscribe to **`partial$`** / **`result$`** for transcripts; wire **`speechStart$`** /
+ * **`speechEnd$`** / **`interrupt$`** for barge-in and UI. Always call **`destroy()`** when done
+ * (e.g. on `channel.events.terminated$`) to release connector and subscriptions.
  */
 export interface AsrHandle {
-    /** Unique handle identifier. */
+    /** Opaque id (passed to `channel.textInput` helpers in automated tests). */
     readonly id: string;
-    /** Emits final recognition results (complete utterances). */
+    /**
+     * Emits one string per finalized utterance (end-of-turn). Empty strings may occur;
+     * filter in application code if needed.
+     */
     readonly result$: Observable<string>;
-    /** Emits partial (intermediate) recognition results. `isFinal` = true on last partial. */
+    /**
+     * Streaming partial hypotheses. **`isFinal: true`** marks the last partial before a finalize
+     * or end-of-turn aligned with **`result$`**.
+     */
     readonly partial$: Observable<{
         text: string;
         isFinal: boolean;
     }>;
-    /** Fires when speech is detected in the audio stream. */
+    /** Fires when VAD detects speech start (user started talking). */
     readonly speechStart$: Observable<void>;
-    /** Fires when speech ends. */
+    /** Fires when VAD detects speech end (user stopped). */
     readonly speechEnd$: Observable<void>;
-    /** Fires when ASR determines the user is interrupting (barge-in). */
+    /** Fires on barge-in / interrupt signals from the ASR stack (host-specific). */
     readonly interrupt$: Observable<void>;
-    /** VAD probability stream (0.0–1.0) — useful for visualization. */
+    /** Normalized voice-activity probability 0–1 when the host exposes it; else may be inert. */
     readonly vadProbability$: Observable<number>;
-    /** Temporarily pause recognition (audio is still buffered). */
+    /** Pause audio consumption by the recognizer (implementation may buffer). */
     pause(): void;
-    /** Resume recognition after pause. */
+    /** Resume after {@link pause}. */
     resume(): void;
-    /** Force-finalize the current utterance (trigger result$ immediately). */
+    /** Force end of current utterance and flush **`result$`** as soon as possible. */
     finalize(): void;
-    /** Destroy this ASR handle and release all resources. */
+    /** Tear down streams, connector, and subscriptions. Idempotent-safe on well-behaved hosts. */
     destroy(): void;
 }
 //# sourceMappingURL=asr-handle.d.ts.map

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,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC,wDAAwD;AACxD,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,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,kBAAkB;IAClB,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,gCAAgC;IAChC,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAClE,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,mEAAmE;IACnE,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC7C,+DAA+D;IAC/D,KAAK,IAAI,IAAI,CAAC;IACd,sCAAsC;IACtC,MAAM,IAAI,IAAI,CAAC;IACf,0EAA0E;IAC1E,QAAQ,IAAI,IAAI,CAAC;IACjB,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB"}
+{"version":3,"file":"asr-handle.d.ts","sourceRoot":"","sources":["../../src/types/asr-handle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC;;;GAGG;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,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;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;;;;;OAKG;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;;;;;;GAMG;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,6EAA6E;IAC7E,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/legacy-phrase.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Marker for pre-recorded phrase rows loaded from the Voctiv platform LE PostgreSQL DB
+ * ({@link PlatformApi.getRecords}). Pass to {@link ChannelAudio.play} instead of a URL/path string.
+ *
+ * Only used when Voctiv platform compatibility mode is enabled.
+ */
+export declare const LEGACY_PHRASE_RECORD_BRAND: "__legacyPhraseRecord";
+export interface LegacyPhraseRecord {
+    readonly [LEGACY_PHRASE_RECORD_BRAND]: true;
+    /** Absolute filesystem path passed to the audio decoder (same layout as old logic-executor `nv.say`). */
+    readonly path: string;
+    /** Phrase transcript / label from DB. */
+    readonly text: string;
+    /** Phrase name (`record_phrase.name`). */
+    readonly phraseName: string;
+}
+export declare function isLegacyPhraseRecord(source: unknown): source is LegacyPhraseRecord;
+/** Parameters for {@link PlatformApi.getRecords} (Voctiv platform LE `RecordPhrase` / `record_phrase_file`). */
+export interface LegacyGetRecordsParams {
+    phraseName: string;
+    flag: string;
+    language: string;
+}
+/**
+ * When set on {@link PlayOptions}, after TTS the audio is copied under the Voctiv platform record-phrase root
+ * and a `record_phrase` / `record_phrase_file` row is inserted so {@link PlatformApi.getRecords}
+ * can retrieve it. Also registers the PCM in the TTS file cache for subsequent `say`/`presay`.
+ *
+ * Only honored when Voctiv platform compatibility mode is active and `LEGACY_V3_RECORD_PHRASE_ROOT` is set.
+ */
+export interface LegacySavePhraseOptions {
+    phraseName: string;
+    /** Defaults to dialog `flag` from channel params when omitted. */
+    flag?: string;
+    /** Defaults to dialog language from channel params when omitted. */
+    language?: string;
+}
+//# sourceMappingURL=legacy-phrase.d.ts.map

package/dist/types/legacy-phrase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-phrase.d.ts","sourceRoot":"","sources":["../../src/types/legacy-phrase.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,wBAAkC,CAAC;AAE1E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,0BAA0B,CAAC,EAAE,IAAI,CAAC;IAC5C,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,kBAAkB,CAOlF;AAED,gHAAgH;AAChH,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/types/legacy-phrase.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_PHRASE_RECORD_BRAND = void 0;
+exports.isLegacyPhraseRecord = isLegacyPhraseRecord;
+/**
+ * Marker for pre-recorded phrase rows loaded from the Voctiv platform LE PostgreSQL DB
+ * ({@link PlatformApi.getRecords}). Pass to {@link ChannelAudio.play} instead of a URL/path string.
+ *
+ * Only used when Voctiv platform compatibility mode is enabled.
+ */
+exports.LEGACY_PHRASE_RECORD_BRAND = '__legacyPhraseRecord';
+function isLegacyPhraseRecord(source) {
+    return (typeof source === 'object' &&
+        source !== null &&
+        source[exports.LEGACY_PHRASE_RECORD_BRAND] === true &&
+        typeof source.path === 'string');
+}
+//# sourceMappingURL=legacy-phrase.js.map

package/dist/types/legacy-phrase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-phrase.js","sourceRoot":"","sources":["../../src/types/legacy-phrase.ts"],"names":[],"mappings":";;;AAkBA,oDAOC;AAzBD;;;;;GAKG;AACU,QAAA,0BAA0B,GAAG,sBAA+B,CAAC;AAY1E,SAAgB,oBAAoB,CAAC,MAAe;IAClD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACd,MAA6B,CAAC,kCAA0B,CAAC,KAAK,IAAI;QACnE,OAAQ,MAA6B,CAAC,IAAI,KAAK,QAAQ,CACxD,CAAC;AACJ,CAAC"}

package/dist/types/logger.d.ts

@@ -1,7 +1,7 @@
 /**
  * Structured logger available to scripts.
  *
- * In legacy compat mode, log entries are also batch-written
+ * In Voctiv platform compatibility mode, log entries are also batch-written
  * to the `dialog_stats` DB table (equivalent of old LE `nn.log`).
  */
 export interface ScriptLogger {

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

@@ -2,180 +2,205 @@ import { Observable } from 'rxjs';
 import { AsrConfig, AsrHandle } from './asr-handle';
 import { DtmfEvent, SipInfo, SipSignal, DataMessage } from './events';
 import { MixerQueueControl, PlayOptions } from './mixer';
+import type { LegacyPhraseRecord } from './legacy-phrase';
 import { TextInput } from './text-input';
 /**
- * Audio playback API — TTS synthesis, file playback, and queue management.
+ * Audio playback API — TTS synthesis, file/URL playback, caching, and multi-queue mixing.
  *
- * Audio is routed through a multi-queue mixer. Each queue can play items
- * independently with its own volume. Default queue index is 0.
+ * Audio is routed through a **multi-queue mixer** (indices **0–4**). Each queue has its own
+ * volume and lifecycle; use different **`queue`** values in {@link PlayOptions} so earcons,
+ * hold music, and agent TTS can be **`stop`**ped independently.
  */
 export interface ChannelAudio {
     /**
-     * Synthesize text via TTS and play it.
-     * Accepts a plain string or an RxJS Observable of string chunks (for streaming TTS).
-     * Resolves when playback finishes.
+     * Synthesize text with TTS and play the result on the selected mixer queue.
+     *
+     * @param input - Plain string, or `Observable<string>` of chunks for streaming synthesis.
+     * @param options - Queue, alias, volume, {@link PlayOptions.ttsVendor}, {@link PlayOptions.name}
+     *   (LE `key_storage` row), {@link PlayOptions.ttsConfig}, {@link PlayOptions.ttsStrategy}, etc.
+     * @returns Resolves when playback of this **`say`** invocation has finished (queue may still
+     *   contain other items).
      */
     say(input: string | Observable<string>, options?: PlayOptions): Promise<void>;
     /**
-     * Play a pre-recorded audio file from URL or local path.
-     * Resolves when playback finishes.
+     * Play audio from a URL/path string, or a {@link LegacyPhraseRecord} from the Voctiv platform phrase DB.
+     *
+     * @param source - HTTP(S) URL, local path, or structured {@link LegacyPhraseRecord} (no TTS).
+     * @param options - Queue, alias, volume, loop; **`tts*`** fields apply only if the host
+     *   ever wraps playback (normally ignored for raw audio).
+     */
+    play(source: string | LegacyPhraseRecord, options?: PlayOptions): Promise<void>;
+    /**
+     * Download/decode **`source`** and cache PCM so a later **`say`/`play`** with the same source
+     * starts faster.
+     * @param source - URL or file path accepted by the host’s fetch layer.
      */
-    play(source: string, options?: PlayOptions): Promise<void>;
-    /** Download, decode and cache audio (URL or file path) as PCM for instant playback. */
     preload(source: string): Promise<void>;
-    /** Pre-synthesize text via TTS and store in file cache for instant `say()` playback. */
+    /**
+     * Run TTS ahead of time and store audio in the host cache (exact semantics depend on connector).
+     * @param text - Full text to synthesize.
+     * @param options - Same TTS-related options as **`say`** (vendor, **`name`**, **`ttsConfig`**).
+     */
     presay(text: string, options?: PlayOptions): Promise<void>;
-    /** Access a specific mixer queue by index (0–4). */
+    /**
+     * @param index - Mixer queue **0–4**.
+     * @returns Control handle for that queue’s volume and item lifecycle observables.
+     */
     queue(index: number): MixerQueueControl;
-    /** Remove a specific item by alias from a queue. */
+    /**
+     * Remove one item by **`alias`** from a queue (default queue **0** if omitted).
+     * @param alias - **`PlayOptions.alias`** of the item to drop.
+     * @param queue - Queue index; defaults to **0**.
+     */
     remove(alias: string, queue?: number): void;
-    /** Stop and clear all items in a specific queue. */
+    /**
+     * Stop playback and clear all pending items on a single queue.
+     * @param queue - Queue index **0–4**.
+     */
     stop(queue: number): void;
-    /** Stop and clear all queues. */
+    /** Stop and clear **all** queues (nuclear option for teardown). */
     stopAll(): void;
 }
-/** Observables for channel-level events (speech detection, termination, data messages). */
+/** Channel-level observables: VAD-related speech, barge-in, session end, and arbitrary data messages. */
 export interface ChannelEvents {
-    /** Fires when the caller starts speaking (VAD-based). */
+    /** User started speaking (VAD speech start). */
     readonly speechStart$: Observable<void>;
-    /** Fires when the caller stops speaking. */
+    /** User stopped speaking (VAD speech end). */
     readonly speechEnd$: Observable<void>;
-    /** Fires when caller speech interrupts bot playback. */
+    /** User speech caused an interrupt of bot audio (barge-in path). */
     readonly interrupt$: Observable<void>;
-    /** Fires when the session ends (hangup, timeout, or explicit destroy). */
+    /** Session is ending: hangup, client disconnect, or explicit **`channel.destroy()`**. */
     readonly terminated$: Observable<void>;
-    /** Fires on incoming data messages (e.g. from WS client). */
+    /** Structured messages from the WS client or bridge (event + payload). */
     readonly message$: Observable<DataMessage>;
 }
-/** Options for LLM `ask()` and `stream()` calls. */
+/** Options for **`channel.llm.ask`** / **`stream`** / **`makePersistentStream`**. */
 export interface LlmOptions {
-    /** Override dialog UUID for LLM context tracking. */
+    /** Override dialog UUID for Omni/LLM tracing (defaults to script dialog). */
     dialogUuid?: string;
-    /** System role hint (e.g. `"assistant"`, `"user"`). */
+    /** Chat role hint, e.g. **`"assistant"`**, **`"user"`**. */
     role?: string;
-    /** If `true`, the message is added to history but not displayed. */
+    /** When `true`, message may be hidden from user-visible transcript (host-dependent). */
     hidden?: boolean;
-    /** Speaker name for multi-turn dialogs. */
+    /**
+     * **LLM-only**: speaker / persona label in multi-party chat. **Not** related to
+     * {@link PlayOptions.name} (TTS **`key_storage.name`**).
+     */
     name?: string;
-    /** Override agent UUID for routing to a specific LLM agent. */
+    /** Route the request to a specific Omni agent profile (UUID). */
     agentUuid?: string;
-    /** Current agent alias for multi-agent scenarios. */
+    /** Multi-agent: current alias for routing. */
     currentAgentAlias?: string;
-    /** Arbitrary payload forwarded to the LLM backend. */
+    /** Opaque payload forwarded to the LLM backend. */
     payload?: Record<string, any>;
-    /** Enable debug logging for this request. */
+    /** Verbose logging on the LLM path. */
     debug?: boolean;
-    /** Restrict response to specific agent aliases. */
+    /** Restrict which agent aliases may handle the request. */
     agentAliasFilter?: string[];
 }
-/** Options for LLM structured extraction. */
+/** Options for **`channel.llm.extract`**. */
 export interface ExtractOptions {
-    /** Override dialog UUID. */
     dialogUuid?: string;
-    /** Extraction prompt / instruction. */
     prompt?: string;
-    /** LLM model name. */
     model?: string;
-    /** Top-p (nucleus) sampling parameter. */
     topP?: number;
-    /** Temperature sampling parameter. */
     temperature?: number;
-    /** Custom model configuration. */
     customModel?: Record<string, any>;
     [key: string]: unknown;
 }
-/** A single chunk from an LLM streaming response. */
+/** One chunk from **`channel.llm.stream`**. */
 export interface LlmStreamChunk {
-    /** Request ID. */
     id: string;
-    /** Sequential chunk number. */
     chunkId: number;
-    /** Text content of this chunk. */
     content: string;
-    /** Non-null when the stream is done (e.g. `"stop"`, `"length"`). */
     finishReason: string | null;
-    /** Raw SSE event data. */
     event: any;
-    /** Tool call messages (function calling). */
     toolMessages?: any[];
-    /** Full raw response object. */
     raw: Record<string, any>;
 }
 /**
- * LLM (Large Language Model) API — text generation and structured extraction.
+ * Long-lived LLM Socket.IO stream — amortizes connection setup across many user turns.
  */
+export interface PersistentLlmStreamHandle {
+    readonly stream$: Observable<LlmStreamChunk>;
+    send(message: string, options?: LlmOptions): void;
+    disconnect(): void;
+    reconnect(): void;
+}
+/** LLM facade on the media channel. */
 export interface ChannelLlm {
-    /** Send a message and get a complete response. */
+    /** Single-shot completion for **`message`**. */
     ask(message: string, options?: LlmOptions): Promise<string>;
-    /** Send a message and get a streaming response (Observable of chunks). */
+    /** Token/chunk stream for **`message`**. */
     stream(message: string, options?: LlmOptions): Observable<LlmStreamChunk>;
-    /** Structured data extraction using LLM (e.g. filling a form from conversation). */
+    /** Structured extraction / JSON-style fill from conversation context. */
     extract(options?: ExtractOptions): Promise<Record<string, any>>;
+    /**
+     * Open a persistent Omni chat stream (see host docs for URL and auth).
+     * @param options - Default **`agentUuid`**, **`dialogUuid`**, etc.; per-**`send`** overrides allowed.
+     */
+    makePersistentStream(options?: LlmOptions): PersistentLlmStreamHandle;
 }
-/**
- * SIP telephony controls — DTMF, call control, bridging.
- */
+/** SIP: DTMF, INFO, hold/mute/hangup, outbound **`makeCall`**, **`bridge`**. */
 export interface ChannelSip {
-    /** Observable of DTMF digit events. */
     readonly dtmf$: Observable<DtmfEvent>;
-    /** Observable of SIP INFO messages. */
     readonly sipInfo$: Observable<SipInfo>;
-    /** Observable of SIP call state changes (e.g. ringing, confirmed, terminated). */
     readonly sipSignal$: Observable<SipSignal>;
-    /** Send a DTMF digit to the remote party. */
     sendDtmf(digit: string, duration?: number): void;
-    /** Send a SIP INFO message. */
     sendInfo(contentType: string, body: string): void;
-    /** Put the call on hold. */
     hold(): void;
-    /** Resume a held call. */
     unhold(): void;
-    /** Mute outgoing audio. */
     mute(): void;
-    /** Unmute outgoing audio. */
     unmute(): void;
-    /** Hang up the call. */
     hangup(): void;
-    /** Answer an incoming call. */
     answer(): void;
-    /** Originate a new outbound SIP call and return its media channel. */
     makeCall(opts: {
         sipUri: string;
         fromUri?: string;
     }): Promise<MediaChannel>;
-    /** Bridge two channels together (conference). Returns a teardown function. */
     bridge(other: MediaChannel): () => void;
 }
 /**
- * Media channel — the main interface for voice, audio, SIP, and LLM interaction.
+ * Primary script API for real-time voice: ASR, TTS/audio, SIP, LLM, and **`params`** from the host.
  *
- * Every script receives a `channel` object. In headless mode,
- * audio and SIP methods are no-ops or stubs.
+ * **`type`** is **`"sip"`** for telephony or **`"ws"`** for WebSocket/script-manager sessions.
+ * In **headless** mode (see {@link import('./define-script').ScriptDialogContext.headless}),
+ * audio/SIP may be no-ops while **`llm`** / **`platform`** still work.
  */
 export interface MediaChannel {
-    /** Channel transport type: `"sip"` for phone calls, `"ws"` for WebSocket sessions. */
     readonly type: 'sip' | 'ws';
-    /** Inbound caller ID (phone number or WS client ID). */
     readonly callerId: string;
-    /** Called number / destination DID. */
     readonly calledNumber: string;
-    /** Channel-level params (merged from route, agent defaults, etc.). */
+    /**
+     * Merged session parameters from env, Omni, Voctiv platform defaults, and route.
+     *
+     * 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}
+     * - **`authentication_data`**: may include **`legacyAsrKeysByName`**, **`legacyTtsKeysByName`**
+     *   (built from LE DB for this dialog’s agent + company)
+     *
+     * Treat as read-only unless your integration explicitly documents mutable keys.
+     */
     readonly params: Record<string, unknown>;
-    /** Create a new ASR (speech recognition) handle with optional config. */
+    /**
+     * Create a speech recognizer for this session.
+     *
+     * @param config - Optional {@link AsrConfig}: **`vendor`**, **`name`** (storage row), **`language`**,
+     *   **`data`** overlays, VAD / smart-turn tuning.
+     * @returns A handle you must {@link AsrHandle.destroy} when the session ends.
+     */
     createAsr(config?: AsrConfig): Promise<AsrHandle>;
-    /** Virtual text input for testing — push text as if ASR recognized it. */
+    /** Push synthetic ASR results (testing / WS debug). */
     readonly textInput: TextInput;
-    /** Audio playback and TTS. */
     readonly audio: ChannelAudio;
-    /** Channel events (speech, termination, data messages). */
     readonly events: ChannelEvents;
-    /** LLM text generation and extraction. */
     readonly llm: ChannelLlm;
-    /** SIP telephony controls. */
     readonly sip: ChannelSip;
-    /** Send a data message to the remote party (WS). */
+    /** Emit a structured message to the remote peer (WS). */
     sendMessage(data: DataMessage): void;
-    /** Terminate the channel and release all resources. */
+    /** Release connectors, mixer, and subscriptions. */
     destroy(): void;
 }
 //# sourceMappingURL=media-channel.d.ts.map

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":"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"}

package/dist/types/mixer.d.ts

@@ -1,42 +1,106 @@
 import { Observable } from 'rxjs';
-/** TTS synthesis strategy. Default: `sentence`. */
+import type { LegacySavePhraseOptions } from './legacy-phrase';
+/**
+ * How TTS audio is chunked and fed to the mixer.
+ *
+ * - **`sentence`**: split on sentence boundaries (default).
+ * - **`streaming`**: incremental chunks as they arrive (mainly for streaming-capable vendors, e.g. ElevenLabs).
+ * - **`full`**: synthesize the entire utterance as one segment before playback.
+ */
 export type TtsStrategy = 'sentence' | 'streaming' | 'full';
-/** TTS vendor identifier. */
+/**
+ * Internal TTS vendor code used by the connector factory.
+ *
+ * - **`A`**: default / Neuro-style path.
+ * - **`E`** / **`ES`**: ElevenLabs (`ES` = persistent streaming session where supported).
+ * - **`V`**, **`G`**: host-specific vendors (e.g. Voctiv, Google).
+ */
 export type TtsVendor = 'A' | 'E' | 'ES' | 'V' | 'G';
-/** Options for `say()` and `play()` calls. */
+/**
+ * Options for {@link import('./media-channel').ChannelAudio.say},
+ * {@link import('./media-channel').ChannelAudio.play}, and
+ * {@link import('./media-channel').ChannelAudio.presay}.
+ *
+ * ### Voctiv platform + `key_storage` (TTS credentials)
+ *
+ * Same idea as ASR: when Voctiv platform compatibility is on and keys are loaded from PostgreSQL, **`authentication_data`**
+ * contains **`legacyTtsKeysByName`**, keyed by **`key_storage.name`** for **this dialog’s agent
+ * and company** (agent is implied by the dialog — no UUID in the script).
+ *
+ * - **`name`** on **`PlayOptions`**: select that row’s flat credentials for this synthesis.
+ * - Alternative: **`ttsConfig.name`** (the **`name`** entry is stripped before vendor params).
+ * - If omitted, **`defaultTtsName`** on the channel (Omni / route) applies.
+ * - Otherwise credentials come from **`authentication_data.tts.<engine>`** for the resolved vendor.
+ *
+ * ### Note on the field **`name`**
+ *
+ * This **`name`** is **not** the same as {@link import('./media-channel').LlmOptions.name}
+ * (speaker label for LLM). It only selects the TTS key row when LE key catalogs (`legacyTtsKeysByName`, etc.) are present.
+ */
 export interface PlayOptions {
-    /** Target mixer queue index (0–4). Default: 0. */
+    /**
+     * Mixer queue index **0–4**. Use separate queues to layer music, earcons, and agent TTS
+     * so **`stop(queue)`** does not cut unrelated audio.
+     * @defaultValue 0
+     */
     queue?: number;
-    /** Unique alias for this item — used to remove or track it. */
+    /**
+     * Stable id for this queue item — used with **`remove`**, debug UIs, and completion tracking.
+     * Should be unique per logical utterance if you need to cancel a specific playback.
+     */
     alias?: string;
-    /** Loop playback until explicitly stopped. */
+    /** When `true`, the item restarts after it finishes until **`stop`** / **`remove`**. */
     loop?: boolean;
-    /** Delay in milliseconds between loop iterations. */
+    /** Milliseconds of silence between loop iterations (if **`loop`**). */
     loopDelayMs?: number;
-    /** Queue volume 0.0 (silent) – 1.0 (full). Applied to the target queue for this call. */
+    /** Linear gain for this queue **0.0** (mute) – **1.0** (unity). */
     volume?: number;
-    /** TTS synthesis strategy: `sentence` | `streaming` | `full` (entire utterance). Default: `sentence`. */
+    /** Chunking strategy for TTS; see {@link TtsStrategy}. */
     ttsStrategy?: TtsStrategy;
-    /** TTS vendor override. */
+    /**
+     * Force a specific TTS vendor for this call, overriding **`channel.params.ttsVendor`**.
+     * Ignored for **`play()`** when the source is raw audio (no synthesis).
+     */
     ttsVendor?: TtsVendor;
-    /** Vendor-specific TTS config (voice name, speed, pitch, etc.). */
+    /**
+     * logic-executor **`key_storage.name`**: use **`authentication_data.legacyTtsKeysByName[name]`**
+     * for credentials. Overrides **`defaultTtsName`** on the channel.
+     */
+    name?: string;
+    /**
+     * Flat string map passed to the TTS connector (voice id, model, `output_format`, …).
+     * Merged after catalog credentials; later wins. The key **`name`** is reserved for the
+     * storage-row selector and is removed before sending to the vendor.
+     */
     ttsConfig?: Record<string, string>;
+    /**
+     * Voctiv platform only: after synthesis, persist audio under **`record_phrase`** + filesystem root so
+     * {@link import('./define-script').PlatformApi.getRecords} can return a {@link import('./legacy-phrase').LegacyPhraseRecord}.
+     */
+    legacySavePhrase?: LegacySavePhraseOptions;
 }
-/** Control interface for a single mixer queue. */
+/**
+ * Per-queue mixer control: volume, observability, and manual removal.
+ *
+ * Obtain via **`channel.audio.queue(index)`**.
+ */
 export interface MixerQueueControl {
-    /** Queue index (0–4). */
+    /** Queue index **0–4** (matches **`PlayOptions.queue`**). */
     readonly index: number;
-    /** Current volume (0.0–1.0). Set to change. */
+    /** Current linear volume **0.0–1.0**; assign to change gain for this queue. */
     volume: number;
-    /** Fires when an item starts playing (emits alias). */
+    /** Emits **`alias`** when an item in this queue starts playing. */
     readonly itemStarted$: Observable<string>;
-    /** Fires when an item finishes playing (emits alias). */
+    /** Emits **`alias`** when an item finishes (natural end or skip). */
     readonly itemFinished$: Observable<string>;
-    /** Fires when the queue becomes empty. */
+    /** Emits once when the queue has no pending items. */
     readonly queueEmpty$: Observable<void>;
-    /** Remove a specific item from this queue by alias. */
+    /**
+     * Remove a single item by **`alias`**.
+     * @param alias - Same string passed in **`PlayOptions.alias`** for that item.
+     */
     remove(alias: string): void;
-    /** Clear all items from this queue. */
+    /** Drop all queued and current items on this queue. */
     clear(): void;
 }
 //# sourceMappingURL=mixer.d.ts.map

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;AAElC,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D,6BAA6B;AAC7B,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,CAAC;AAErD,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yGAAyG;IACzG,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,2BAA2B;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IAEf,uDAAuD;IACvD,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IAEvC,uDAAuD;IACvD,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uCAAuC;IACvC,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,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,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;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IAEf,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3C,sDAAsD;IACtD,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/text-input.d.ts

@@ -1,9 +1,23 @@
 /**
- * Virtual text input — pushes text directly into an AsrHandle's streams
- * as if ASR recognized it. For automated testing via WS API without real audio.
+ * Virtual ASR injection — pushes transcript text into a live {@link import('./asr-handle').AsrHandle}
+ * as if the speech recognizer had produced it. Used by WebSocket test clients and automation
+ * **without** sending real microphone audio.
+ *
+ * Methods require the **`asrId`** returned by **`AsrHandle.id`** from **`channel.createAsr()`**.
  */
 export interface TextInput {
+    /**
+     * Inject a **final** transcript for the given ASR instance.
+     * @param asrId - Value of **`(await channel.createAsr()).id`**.
+     * @param text - Full utterance text (final result).
+     */
     pushResult(asrId: string, text: string): void;
+    /**
+     * Inject a partial or final hypothesis.
+     * @param asrId - Target ASR **`id`**.
+     * @param text - Partial or final text.
+     * @param isFinal - When `true`, marks this partial as the last before a final (host may align with **`result$`**).
+     */
     pushPartial(asrId: string, text: string, isFinal?: boolean): void;
 }
 //# sourceMappingURL=text-input.d.ts.map

package/dist/types/text-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-input.d.ts","sourceRoot":"","sources":["../../src/types/text-input.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACnE"}
+{"version":3,"file":"text-input.d.ts","sourceRoot":"","sources":["../../src/types/text-input.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACnE"}

package/package.json

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