@voctiv/agent-sdk 0.2.11 → 0.2.12

package/README.md

@@ -1,10 +1,10 @@
 # @voctiv/agent-sdk
 
-TypeScript SDK for scripts executed by the `ScriptEngine` scripting runtime.
+TypeScript SDK for voice and dialog scripts.
 
-The package exports the `defineScript()` identity helper and the public ScriptEngine runtime types for voice channels, SIP calls, ASR, TTS, VAD, Smart Turn, LLM, dialog context, logging, and Voctiv legacy platform compatibility APIs.
+The package exports `defineScript()` and types for media channels, SIP, ASR, TTS, LLM, dialog context, logging, and platform APIs.
 
-The SDK itself does not open SIP calls, run ASR/TTS, or talk to platform services; it describes the objects injected into your script by ScriptEngine.
+The SDK describes the objects injected into your script by the host runtime; it does not open calls or run services itself.
 
 ## Installation
 
@@ -121,7 +121,7 @@ For inbound calls, the script controls this explicitly:
 3. Use `channel.audio.say()`, `channel.audio.play()`, `channel.createAsr()`, or `channel.sip.sendDtmf()` normally.
 4. Call `channel.sip.answer()` when you want to send the final `200 OK`.
 
-For outbound calls, pre-answer is controlled by the remote side. If the remote endpoint sends `183 Session Progress` with SDP, ScriptEngine moves the call to `early`. If it answers directly, `waitForEarly()` resolves when the call becomes `active`.
+For outbound calls, pre-answer is controlled by the remote side. If the remote endpoint sends `183 Session Progress` with SDP, the host runtime moves the call to `early`. If it answers directly, `waitForEarly()` resolves when the call becomes `active`.
 
 `early` is a media-ready state, not a final answer state. `answer()` is still the explicit transition that sends final `200 OK` for inbound calls. External billing behavior depends on the carrier.
 
@@ -186,7 +186,37 @@ If the call terminates before media becomes available, deferred audio resolves a
 - `makeCall()` to create an outbound SIP B-leg from the main SIP channel.
 - `bridge(other)` to cross-connect two SIP channels.
 
-`makeCall()` and `bridge()` are supported by SIP channels. In worker isolation mode the host proxies the returned B-leg, so direct media operations on it (`bLeg.audio.say()`, `bLeg.createAsr()`, `bLeg.sip.sendDtmf()`, LLM calls, and events) work the same way as on the main channel. WS and headless channels do not create real SIP legs.
+`makeCall()` and `bridge()` are supported on SIP channels. The returned B-leg is a full
+`MediaChannel` with the same API as the main channel. WS and headless channels do not create real SIP legs.
+
+### `channel.sip` Reference
+
+SIP-only unless noted. WS/headless: most methods are no-ops; `state` behaves as synthetic `active`.
+
+| Member | Description |
+| --- | --- |
+| `state` | Sync getter: `idle` \| `ringing` \| `early` \| `active` \| `holding` \| `terminated` |
+| `isAnswered` | `true` after 200 OK (outbound received / inbound sent via `answer()`) |
+| `state$` | Emits on every state transition |
+| `progress$` | SIP 1xx provisional responses (`SipProgressEvent`) |
+| `early$` | Emits once when RTP is up before final answer |
+| `answered$` | Emits once on 200 OK |
+| `dtmf$` | Remote DTMF digits (`DtmfEvent`: `digit`, `duration`) |
+| `sipInfo$` | Raw SIP INFO messages (`SipInfo`) |
+| `sipSignal$` | Low-level SIP stack events (`SipSignal`) |
+| `sendProgress()` | Inbound: send 183 Session Progress → `early` |
+| `waitForEarly()` | Await `early` or `active` (Promise) |
+| `waitForAnswer()` | Await final 200 OK (Promise) |
+| `answer()` | Inbound: send final 200 OK → `active` |
+| `sendDtmf(digit, duration?)` | Send DTMF tone |
+| `sendInfo(contentType, body)` | Send SIP INFO |
+| `hold()` / `unhold()` | SIP hold |
+| `mute()` / `unmute()` | Suppress local outgoing audio |
+| `hangup()` | Terminate call |
+| `makeCall(opts)` | Outbound B-leg (`MediaChannel`); `sipUri` or `msisdn` |
+| `bridge(other)` | Cross-connect two SIP calls; returns teardown `() => void` |
+
+Prefer `dtmf$` over `sipInfo$` for DTMF. Prefer `state$` / `early$` / `answered$` over raw `sipSignal$` unless you need low-level SIP details.
 
 ### SIP Bridge
 
@@ -204,7 +234,7 @@ await bLeg.sip.waitForAnswer();
 const teardown = channel.sip.bridge(bLeg);
 ```
 
-In legacy mode you can pass only `msisdn`. The host resolves the SIP URI from the current call/agent trunk settings, adds legacy outbound headers, and applies caller-id `proto_additional` from the selected trunk when configured.
+You can pass only `msisdn` instead of `sipUri`. The host resolves the SIP URI from agent and trunk settings and applies trunk caller-id options when configured.
 
 ```ts
 const bLeg = await channel.sip.makeCall({
@@ -215,7 +245,7 @@ await bLeg.sip.waitForAnswer();
 const teardown = channel.sip.bridge(bLeg);
 ```
 
-To match legacy `nv.bridge(..., channel=...)`, pass `channel` as a trunk-name override:
+Pass `channel` as a trunk-name override when selecting which outbound trunk to use:
 
 ```ts
 const bLeg = await channel.sip.makeCall({
@@ -304,7 +334,7 @@ const asr = await channel.createAsr({
 `AsrHandle` exposes:
 
 - `result$`: finalized utterances.
-- `partial$`: streaming partial hypotheses.
+- `partial$`: streaming partial hypotheses as `{ text, isFinal }`.
 - `speechStart$` / `speechEnd$`: VAD speech boundaries.
 - `interrupt$`: barge-in / interrupt events where the host supports them.
 - `vadProbability$`: normalized VAD probability when available.
@@ -349,9 +379,9 @@ Each vendor connector accepts its native parameter names:
 
 All vendors also accept the env-style names (`AZURE_SPEECH_KEY`, `ELEVENLABS_API_KEY`, etc.) for backwards compatibility, but vendor-native names are checked first and are preferred.
 
-### Voctiv Platform ASR Key Selection
+### Platform ASR Key Selection
 
-In Voctiv legacy compatibility mode, ASR credentials can also be selected by logic-executor `key_storage.name`:
+When platform credential catalogs are enabled, select ASR keys by **`name`**:
 
 ```ts
 const asr = await channel.createAsr({
@@ -360,12 +390,26 @@ const asr = await channel.createAsr({
 });
 ```
 
-The runtime looks in `channel.params.authentication_data.legacyAsrKeysByName[name]` for the current dialog agent and company. If `name` is omitted, `channel.params.defaultAsrName` may be used.
+The host resolves credentials from `channel.params.authentication_data` for the current dialog agent and company. If `name` is omitted, `channel.params.defaultAsrName` may be used.
 
 When both `name` (platform key) and explicit `data` are provided, `data` values win — they are applied last and override anything resolved from the platform.
 
 ## TTS, Playback, And Mixer Queues
 
+All audio playback goes through **`channel.audio`** (`ChannelAudio`). There are no top-level
+`channel.say()` / `channel.play()` shortcuts on `MediaChannel`.
+
+| Method | Purpose |
+| --- | --- |
+| `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) |
+| `channel.audio.preload(source, options?)` | Decode/warm a raw audio source (no playback) |
+| `channel.audio.queue(index)` | Per-queue control handle (`MixerQueueControl`) |
+| `channel.audio.remove(alias, queue?)` | Remove one queued item by alias |
+| `channel.audio.stop(queue)` | Clear a queue **and** abort in-flight sentence TTS for it |
+| `channel.audio.stopAll()` | Clear every queue (WS clients also get an audio interrupt) |
+
 `channel.audio.say(textOrObservable, options?)` synthesizes text and plays it through the mixer.
 
 ```ts
@@ -384,11 +428,11 @@ await channel.audio.say('Please wait while I check that.', {
 });
 ```
 
-Use full vendor names for `ttsVendor`. Dedicated TTS vendors include `"elevenlabs"`, `"google"`, and `"voctiv"`. The default TTS path can also accept compatible aliases such as `"azure"` or `"neuro_v3"`, depending on how ScriptEngine is configured.
+Use full vendor names for `ttsVendor`. Dedicated TTS vendors include `"elevenlabs"`, `"google"`, and `"voctiv"`. The default TTS path can also accept compatible aliases such as `"azure"` or `"neuro_v3"`, depending on how the host runtime is configured.
 
 Vendor-native parameter names (`api_key`, `voice_id`, `model_id`, `base_url`) are passed directly to the connector and override any platform defaults. See [TTS Credentials And Vendor Parameters](#tts-credentials-and-vendor-parameters) for the full list of accepted keys per vendor.
 
-`channel.audio.play(source, options?)` plays raw audio from a URL/path or a `LegacyPhraseRecord`.
+`channel.audio.play(source, options?)` plays raw audio from a URL/path or a phrase record from `platform.getRecords()`.
 
 ```ts
 await channel.audio.play('/opt/prompts/welcome.wav', {
@@ -397,9 +441,40 @@ await channel.audio.play('/opt/prompts/welcome.wav', {
 });
 ```
 
-`channel.audio.presay(text, options?)` pre-synthesizes TTS into the host TTS cache. If the cache is not available, the runtime logs a warning and resolves without throwing.
+### Pre-synthesis And Preload
 
-`channel.audio.preload(source)` decodes a raw audio source through the audio player. It does not synthesize TTS and does not populate the TTS cache used by `presay()`.
+`channel.audio.presay(text, options?)` runs TTS ahead of time and stores PCM in the host TTS
+cache. Later `say()` calls with the same resolved TTS config and text can reuse the cached file.
+Playback does **not** start. If the cache is unavailable, the runtime logs a warning and resolves
+without throwing.
+
+```ts
+await channel.audio.presay('Your balance is one hundred dollars.', {
+  ttsVendor: 'elevenlabs',
+  ttsConfig: { voice_id: 'bBLRWT6MSWBFAm76ZWXY' },
+});
+
+// Later — cache hit, faster playback:
+await channel.audio.say('Your balance is one hundred dollars.', {
+  alias: 'balance',
+  ttsVendor: 'elevenlabs',
+  ttsConfig: { voice_id: 'bBLRWT6MSWBFAm76ZWXY' },
+});
+```
+
+`PresayOptions` accepts `ttsVendor`, `name`, `ttsConfig`, `ttsStrategy`, and optional `cache`
+overrides (same shape as `PlayOptions.cache`).
+
+`channel.audio.preload(source, options?)` downloads/decodes a **raw audio** source through the
+audio player path. It does **not** synthesize TTS and does **not** populate the TTS cache used
+by `presay()`. Use it to warm the decoder before `play()`.
+
+```ts
+await channel.audio.preload('/opt/prompts/welcome.wav');
+await channel.audio.play('/opt/prompts/welcome.wav', { alias: 'welcome' });
+```
+
+When phrase persistence is enabled, `preload()` can store decoded audio for later playback via `platform.getRecords()`. Pass `options.cache` to override phrase name, flag, or language.
 
 ### TTS Strategies
 
@@ -413,24 +488,77 @@ When using an `Observable<string>` input, WS clients also receive text progress
 
 ### Mixer Queues
 
-The mixer has queues `0` through `4`. Use separate queues for main speech, earcons, hold music, or background audio.
+The mixer has queues **`0` through `4`**. Use separate queues for main speech, earcons, hold
+music, or background audio so barge-in on one queue does not cut unrelated audio.
+
+Obtain a per-queue handle with **`channel.audio.queue(index)`** (`MixerQueueControl`):
+
+| Member | Description |
+| --- | --- |
+| `index` | Queue index **0–4** |
+| `volume` | Linear gain **0.0–1.0** for the entire queue (get/set) |
+| `itemStarted$` | Emits item **`alias`** when playback starts |
+| `itemFinished$` | Emits **`alias`** when an item finishes, is removed, or is skipped by clear |
+| `queueEmpty$` | Emits when the queue is empty after all PCM has been mixed out |
+| `remove(alias)` | Drop one item on this queue |
+| `clear()` | Drop all items on this queue (does **not** abort in-flight TTS generation) |
+
+Top-level helpers on **`channel.audio`**:
+
+- **`remove(alias, queue?)`** — when `queue` is omitted, searches all five queues; when set, only that queue is checked.
+- **`stop(queue)`** — same as `clear()` **plus** aborts in-flight sentence TTS for that queue.
+- **`stopAll()`** — `stop()` on every queue; WS clients also receive an audio interrupt signal.
 
 ```ts
+const tts = channel.audio.queue(0);
 const music = channel.audio.queue(2);
+
+tts.itemStarted$.subscribe((alias) => logger.log('TTS started', { alias }));
+tts.queueEmpty$.subscribe(() => logger.log('Agent queue idle'));
+
 music.volume = 0.25;
 
 await channel.audio.play('/opt/audio/hold.wav', {
   queue: 2,
   alias: 'hold-music',
   loop: true,
+  loopDelayMs: 500,
 });
 
-channel.audio.stop(2);
+// Remove one earcon without touching TTS:
+channel.audio.remove('hold-music', 2);
+
+// Barge-in: stop agent speech and abort pending sentence synthesis:
+channel.audio.stop(0);
+
+// Or clear music only (no TTS abort on queue 0):
+music.clear();
 ```
 
-`PlayOptions.volume` changes the whole queue volume, not just one item. `stop(queue)` clears a queue and aborts in-flight sentence TTS for that queue. `stopAll()` clears every queue.
+`PlayOptions.volume` changes the whole queue volume, not just one item.
+
+For sentence-split TTS, queue item aliases are suffixed as `alias-0`, `alias-1`, and so on. Raw
+`play()` and direct streaming TTS use the alias exactly. Pass the suffixed alias to
+`remove()` when cancelling a single synthesized sentence.
+
+### PlayOptions Reference
 
-For sentence-split TTS, queue item aliases are suffixed as `alias-0`, `alias-1`, and so on. Raw `play()` and direct streaming TTS use the alias exactly.
+Shared by `say()`, `play()`, and (where noted) `presay()`:
+
+| Field | Type | Applies to | Description |
+| --- | --- | --- | --- |
+| `queue` | `number?` | `say`, `play` | Mixer queue **0–4** (default **0**). |
+| `alias` | `string?` | `say`, `play` | Stable item id for `remove()` and queue events. |
+| `loop` | `boolean?` | `say`, `play` | Restart after finish until stopped/removed. |
+| `loopDelayMs` | `number?` | `say`, `play` | Silence between loop iterations. |
+| `volume` | `number?` | `say`, `play` | Sets **whole queue** gain **0.0–1.0** (not per-item). |
+| `ttsStrategy` | `TtsStrategy?` | `say`, `presay` | `sentence` \| `streaming` \| `full`. |
+| `ttsVendor` | `TtsVendor?` | `say`, `presay` | Override `channel.params.ttsVendor`. |
+| `name` | `string?` | `say`, `presay` | Platform TTS credential **`name`** (key catalog selector). |
+| `ttsConfig` | `Record<string, unknown>?` | `say`, `presay` | Vendor params; `name` key is stripped before send. |
+| `cache` | `true \| CacheOptions?` | `say`, `presay` | TTS file cache; optional platform phrase persist. |
+
+`play()` ignores `tts*` and `cache` for raw audio. `preload()` only accepts `cache` overrides.
 
 ## TTS Credentials And Vendor Parameters
 
@@ -460,9 +588,9 @@ Each TTS vendor connector accepts its native parameter names:
 
 All vendors also accept the env-style names (`ELEVENLABS_API_KEY`, `ELEVENLABS_VOICE_ID`, etc.) for backwards compatibility, but vendor-native names are checked first and are preferred.
 
-### Voctiv Platform TTS Key Selection
+### Platform TTS Key Selection
 
-In Voctiv legacy compatibility mode, TTS credentials can also be selected by `PlayOptions.name` or `ttsConfig.name`.
+TTS credentials can also be selected by `PlayOptions.name` or `ttsConfig.name`:
 
 ```ts
 await channel.audio.say('Здравствуйте!', {
@@ -473,14 +601,14 @@ await channel.audio.say('Здравствуйте!', {
 });
 ```
 
-The runtime looks in `channel.params.authentication_data.legacyTtsKeysByName[name]`. If `name` is omitted, `channel.params.defaultTtsName` may be used.
+The host resolves credentials from `channel.params.authentication_data` for the current agent and company. If `name` is omitted, `channel.params.defaultTtsName` may be used.
 
 When both `name` (platform key) and explicit `ttsConfig` values are provided, `ttsConfig` values win — they are applied last and override anything resolved from the platform.
 
 `cache` enables TTS result caching for `say()` and `presay()`:
 
-- **`cache: true`** — read/write TTS file cache only (Redis + filesystem + DB).
-- **`cache: { phraseName, flag?, language? }`** — TTS cache **plus** persist into Voctiv platform `record_phrase` / `record_phrase_file` so `platform.getRecords()` can retrieve the audio later.
+- **`cache: true`** — read/write host TTS file cache.
+- **`cache: { phraseName, flag?, language? }`** — TTS cache **plus** persist as a platform phrase so `platform.getRecords()` can retrieve the audio later.
 
 ```ts
 // Cache only (no platform persist):
@@ -506,7 +634,7 @@ if (records?.[0]) {
 }
 ```
 
-This requires legacy compatibility mode, a trusted LE agent id/UUID, TTS cache, and `LEGACY_V3_RECORD_PHRASE_ROOT`.
+Phrase persistence requires platform phrase storage and TTS cache to be enabled on the host.
 
 ## Error Handling
 
@@ -582,14 +710,56 @@ channel.events.error$.subscribe((err) => {
 | `code` | `number \| string?` | HTTP status, gRPC status, provider code, or WebSocket close code. |
 | `vendor` | `string?` | Vendor identifier, e.g. `"yandex"`, `"elevenlabs"`, `"azure"`. |
 | `details` | `unknown?` | Arbitrary provider-specific payload. |
-| `cause` | `unknown?` | Original provider/runtime error when available in-process. |
+| `cause` | `unknown?` | Original underlying error when available. |
 
 Subscribing to `error$` is optional. Old scripts that do not subscribe are not affected — the observables simply go unobserved.
 
+## Channel Events
+
+`channel.events` exposes session-level observables that are **not** tied to a single ASR handle:
+
+| Observable | Emits when |
+| --- | --- |
+| `speechStart$` | User started speaking (VAD, socket event, or synthetic text input). |
+| `speechEnd$` | User stopped speaking (VAD end, ASR final, or synthetic text input). |
+| `interrupt$` | Barge-in: user speech interrupted bot audio (may be inert without VAD). |
+| `terminated$` | Session ending — hangup, WS disconnect, or `channel.destroy()`. |
+| `message$` | Structured WS data messages (`DataMessage`: `{ event, payload }`). |
+| `error$` | Unified media/runtime errors (see [Error Handling](#error-handling)). |
+
+```ts
+channel.events.speechStart$.subscribe(() => {
+  channel.audio.stop(0); // barge-in on agent TTS queue
+});
+
+channel.events.message$.subscribe(({ event, payload }) => {
+  logger.log('WS client event', { event, payload });
+});
+
+channel.events.terminated$.subscribe(() => {
+  asr.destroy();
+  channel.destroy();
+});
+```
+
+**ASR vs channel events:** `AsrHandle.speechStart$` / `speechEnd$` / `interrupt$` are scoped to one
+recognizer instance. `channel.events.*` aggregates session-level signals (useful when you do not
+create ASR or want one subscription for the whole channel).
+
 ## LLM API
 
 `channel.llm` talks to the Omni LLM backend.
 
+| Method | Returns | Description |
+| --- | --- | --- |
+| `ask(message, options?)` | `Promise<string>` | Single-shot completion (consumes SSE stream). |
+| `stream(message, options?)` | `Observable<LlmStreamChunk>` | Token/chunk stream; use `chunk.content` for TTS. |
+| `extract(options?)` | `Promise<Record<string, any>>` | Structured extraction via Omni extract API. |
+| `makePersistentStream(options?)` | `PersistentLlmStreamHandle` | Long-lived stream for multi-turn chat. |
+
+Common `LlmOptions`: `dialogUuid`, `agentUuid`, `role`, `hidden`, `name` (LLM speaker label — **not**
+the TTS credential `name`), `payload`, `debug`, `agentAliasFilter`, `currentAgentAlias`.
+
 ```ts
 const answer = await channel.llm.ask('Summarize the user request', {
   role: 'assistant',
@@ -603,6 +773,8 @@ await channel.audio.say(answer);
 For streaming:
 
 ```ts
+import { map } from 'rxjs';
+
 const stream$ = channel.llm.stream('Answer briefly', {
   role: 'assistant',
 });
@@ -613,13 +785,70 @@ await channel.audio.say(
 );
 ```
 
-`channel.llm.extract(options?)` runs structured extraction via Omni. `makePersistentStream(options?)` opens a long-lived Socket.IO stream and lets you send multiple turns without reconnecting.
+Structured extraction:
+
+```ts
+const fields = await channel.llm.extract({
+  prompt: 'Extract appointment date and time from the dialog.',
+  temperature: 0.2,
+});
+```
+
+Persistent multi-turn stream:
+
+```ts
+const chat = channel.llm.makePersistentStream({
+  agentUuid: context.agentUuid,
+  dialogUuid: context.dialogUuid,
+});
+
+chat.stream$.pipe(map((c) => c.content)).subscribe((text) => logger.debug('LLM chunk', { text }));
+
+chat.send('What is my balance?');
+chat.send('And my last payment date?');
+chat.disconnect();
+```
+
+## Script Return Value
+
+Scripts may return `void` or a **`ScriptResult`**:
+
+```ts
+return {
+  output: { intent: 'reschedule', score: 0.92 },
+};
+```
+
+- **`output`** — stored in dialog stats / host persistence.
+- **`error`** — optional; usually auto-populated on crash, but scripts may set it explicitly.
+
+**Do not** return `env` from the script. Persist state via `context.env$`; the runtime snapshots it
+after completion into **`PersistedScriptResult.env`**.
+
+Use **`getScriptPhase(context)`** to branch on lifecycle (`online`, `messaging`, `recall`, etc.):
+
+```ts
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ context }) => {
+  switch (getScriptPhase(context)) {
+    case 'online':
+      // live call
+      break;
+    case 'messaging':
+      // inbound message handling
+      break;
+  }
+});
+```
 
 ## Platform API
 
-`platform` exposes Voctiv platform operations.
+`platform` exposes platform operations.
+
+`platform.nlu.extract(utterance, options?)` runs intent/entity extraction. If `options.context` is omitted, current dialog params are serialized and used as NLU context.
 
-`platform.nlu.extract(utterance, options?)` calls NLU v3 `/infer`. The runtime sends `phrase`, `context`, and `agent_id`. If `options.context` is omitted, current dialog params are serialized and used as NLU context.
+`platform.nlu.extract$()` is an Observable wrapper — one `extract()` call per subscription, not a streaming NLU session.
 
 ```ts
 const result = await platform.nlu.extract('I want to reschedule', {
@@ -629,7 +858,7 @@ const result = await platform.nlu.extract('I want to reschedule', {
 });
 ```
 
-Platform APIs require `context.legacyV3Compat === true`. This includes NLU, outbound calls, dialog writes, messaging sends, and phrase records.
+Platform APIs (`platform.nlu`, `platform.call`, dialog writes, messaging, phrase records) are available when the host enables platform integration.
 
 ### Dialog State
 
@@ -638,7 +867,7 @@ platform.dialog.entryPoint = 'on_recall';
 platform.dialog.result = 'done';
 ```
 
-Setters update the local value immediately and ask the platform DB to persist asynchronously. They are not awaitable and should not be used as transactional writes.
+Setters update the local value immediately and persist to the platform asynchronously. They are not awaitable and should not be used as transactional writes.
 
 ### Platform-Scheduled Calls
 
@@ -650,7 +879,7 @@ The destination number should be E.164 formatted.
 await platform.call('+12025551234');
 ```
 
-When options are omitted, the host fills scheduling and routing defaults from agent/dialog settings when available. Supported default containers are `platformCall`, `outboundCall`, and `scheduleOutbound`; flat legacy keys such as `scheduleOutboundTrunkId`, `trunk_id`, `pool_id`, `bulk_uuid`, and `proto_additional` are also honored. Explicit `options` always win.
+When options are omitted, the host fills scheduling and routing defaults from agent and dialog settings. Explicit `options` always win.
 
 By default, the platform schedules the call for immediate processing. Use `date` to schedule it for the future:
 
@@ -715,7 +944,7 @@ await platform.messaging.send({
 });
 ```
 
-Outbound messages are transported through legacy Redis streams. `platform.messaging.message$` currently replays the inbound message that started a headless messaging script; it is not a live subscription to all future Redis messages.
+`platform.messaging.message$` replays the inbound message that started a headless messaging script; it is not a live subscription to all future messages.
 
 ## Offline / Headless Logic
 
@@ -740,11 +969,7 @@ export default defineScript(async ({ channel, context, logger, platform }) => {
 });
 ```
 
-Headless sessions can be started by host integrations such as:
-
-- a platform dialog queue worker that loads pending dialogs;
-- an inbound messaging worker, usually with `context.entryPoint === 'on_message_api_received'`;
-- an HTTP/API request that asks ScriptEngine to run a script without media.
+Headless sessions can be started by the host for background processing, inbound messaging, or API-triggered runs without media.
 
 ### What Works In Headless
 
@@ -752,7 +977,7 @@ These APIs are available and are the intended tools for offline scripts:
 
 - `context.dialogParams`, `context.initialData`, `context.dialogEntity`, and `context.callEntity` for platform data.
 - `context.env$` for persisted per-dialog state.
-- `platform.nlu.extract()` for text NLU when legacy platform compatibility is enabled.
+- `platform.nlu.extract()` for text NLU when platform integration is enabled.
 - `platform.messaging.send()` for outbound messages through the configured platform messaging transport.
 - `platform.call()` for scheduling outbound platform-managed calls.
 - `platform.dialog.entryPoint` and `platform.dialog.result` for updating dialog routing and outcome.
@@ -831,7 +1056,7 @@ context.env$?.next({
 });
 ```
 
-Do not return `env` from the script. ScriptEngine snapshots `context.env$` after completion and persists it according to the host integration.
+Do not return `env` from the script. The runtime snapshots `context.env$` after completion and persists it for the dialog.
 
 ### Combining Voice And Offline In One Script
 
@@ -860,6 +1085,36 @@ export default defineScript(async ({ channel, context, platform }) => {
 
 `context` includes identity, telephony fields, params, routing metadata, and runtime helpers.
 
+### Agent env and storage
+
+When the host exposes agent identity, `context.agent` provides agent-scoped global variables:
+
+```ts
+// Read all agent env keys
+const all = await context.agent?.env?.();
+
+// Read one key
+const counter = await context.agent?.env?.<number>('visitCount');
+
+// Write with optional TTL (days)
+await context.agent?.env?.('visitCount', 42, { expire: 30 });
+```
+
+`context.storage('key1', 'key2')` reads CMS/global variables from agent settings, then company-level
+fallback. Always returns an object with every requested key (value or `null`).
+
+### Execution budget (`runTime`)
+
+Long-running async scripts can check and extend their time budget:
+
+```ts
+if ((context.runTime?.remainingMs() ?? Infinity) < 5000) {
+  context.runTime?.extend(30_000);
+}
+```
+
+`budgetMs` and `maxExtendMs` are fixed for the session; `extend()` grants up to the remaining quota.
+
 Important fields:
 
 - `context.dialogUuid`: current dialog UUID.
@@ -895,7 +1150,7 @@ logger.log('ASR result received', { text });
 logger.warn('Low confidence intent', { confidence });
 ```
 
-`logger.enableDebug(endpoint)` streams logs from the current script instance to a remote debug endpoint. `logger.breakpoint(label, snapshot?)` pauses only when an active debug session is connected; otherwise it resolves immediately.
+`logger.enableDebug(endpoint)` streams logs from the current script instance to a remote debug endpoint. `logger.disableDebug()` stops streaming. `logger.breakpoint(label, snapshot?)` pauses only when an active debug session is connected; otherwise it resolves immediately.
 
 ## WS And Headless Behavior
 
@@ -930,15 +1185,7 @@ This is mainly for WS debug clients and automated tests. Unknown ASR ids are ign
 
 ## Package Notes
 
-The package is published as CommonJS with TypeScript declarations in `dist`.
-
-Build locally with:
-
-```bash
-npm run build
-```
-
-The package exports only the public SDK entry point:
+The package ships as CommonJS with TypeScript declarations. Import from `@voctiv/agent-sdk`:
 
 ```ts
 import { defineScript, type MediaChannel, type AsrHandle, type MediaError } from '@voctiv/agent-sdk';

package/dist/index.d.ts

@@ -1,25 +1,24 @@
 /**
  * @packageDocumentation
- * **Agent scripting SDK** for `ScriptEngine`: typed **`defineScript`** context,
- * {@link import('./types/media-channel').MediaChannel}, ASR/TTS, LLM, SIP, and Voctiv platform (LE-compat) helpers.
- * These exports are types plus the `defineScript` identity helper; runtime behavior is
- * provided by ScriptEngine when it loads and executes your script.
+ * **Agent scripting SDK**: typed **`defineScript`** context,
+ * {@link import('./types/media-channel').MediaChannel}, ASR/TTS, LLM, SIP, and platform helpers.
+ *
+ * Full API reference: **`README.md`** in this package (`@voctiv/agent-sdk` on npm).
  *
- * ### Selecting ASR/TTS credentials by `key_storage.name` (Voctiv platform)
+ * These exports are types plus the `defineScript` identity helper; runtime behavior is
+ * provided by the host when it loads and executes your script.
  *
- * 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
+ * ### Selecting ASR/TTS credentials by name (platform key catalog)
  *
- * Rows are scoped to **this dialog's agent and company** (no agent UUID in the script). Use:
+ * 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/mixer').PlayOptions.name} or **`ttsConfig.name`** on **`say`/`play`/`presay`**
  *
  * Channel defaults **`defaultAsrName`** / **`defaultTtsName`** apply when **`name`** is omitted.
  *
- * Legacy platform APIs (`platform.nlu`, `platform.call`, messaging sends, dialog writes, and phrase
- * records) require `context.legacyV3Compat === true`.
+ * Platform APIs (`platform.nlu`, `platform.call`, messaging, dialog writes, phrase records)
+ * are available when the host enables platform integration.
  */
 export { defineScript } from './define-script';
 export type { ScriptContext, ScriptFn } from './define-script';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,26 +1,25 @@
 "use strict";
 /**
  * @packageDocumentation
- * **Agent scripting SDK** for `ScriptEngine`: typed **`defineScript`** context,
- * {@link import('./types/media-channel').MediaChannel}, ASR/TTS, LLM, SIP, and Voctiv platform (LE-compat) helpers.
- * These exports are types plus the `defineScript` identity helper; runtime behavior is
- * provided by ScriptEngine when it loads and executes your script.
+ * **Agent scripting SDK**: typed **`defineScript`** context,
+ * {@link import('./types/media-channel').MediaChannel}, ASR/TTS, LLM, SIP, and platform helpers.
+ *
+ * Full API reference: **`README.md`** in this package (`@voctiv/agent-sdk` on npm).
  *
- * ### Selecting ASR/TTS credentials by `key_storage.name` (Voctiv platform)
+ * These exports are types plus the `defineScript` identity helper; runtime behavior is
+ * provided by the host when it loads and executes your script.
  *
- * 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
+ * ### Selecting ASR/TTS credentials by name (platform key catalog)
  *
- * Rows are scoped to **this dialog's agent and company** (no agent UUID in the script). Use:
+ * 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/mixer').PlayOptions.name} or **`ttsConfig.name`** on **`say`/`play`/`presay`**
  *
  * Channel defaults **`defaultAsrName`** / **`defaultTtsName`** apply when **`name`** is omitted.
  *
- * Legacy platform APIs (`platform.nlu`, `platform.call`, messaging sends, dialog writes, and phrase
- * records) require `context.legacyV3Compat === true`.
+ * Platform APIs (`platform.nlu`, `platform.call`, messaging, dialog writes, phrase records)
+ * are available when the host enables platform integration.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isLegacyPhraseRecord = exports.LEGACY_PHRASE_RECORD_BRAND = exports.getScriptPhase = exports.defineScript = void 0;

package/dist/index.js.map

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

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

@@ -92,7 +92,7 @@ export interface ChannelAudio {
      * suffixed as `alias-0`, `alias-1`, etc.; remove the concrete suffix if you need to
      * cancel one synthesized sentence.
      * @param alias - **`PlayOptions.alias`** of the item to drop.
-     * @param queue - Queue index; defaults to **0**.
+     * @param queue - When set, only this queue index is searched; when omitted, all five queues are searched.
      */
     remove(alias: string, queue?: number): void;
     /**

package/dist/types/mixer.d.ts

@@ -137,7 +137,8 @@ export interface MixerQueueControl {
     readonly itemStarted$: Observable<string>;
     /** Emits **`alias`** when an item finishes, is removed, or is skipped by queue clear. */
     readonly itemFinished$: Observable<string>;
-    /** Emits whenever the queue becomes empty after all pending/current items are gone. */
+    /** Emits whenever the queue becomes empty after all pending/current items are gone
+     *  and their PCM has been emitted to the mixer output (not merely dequeued). */
     readonly queueEmpty$: Observable<void>;
     /**
      * Remove a single item by **`alias`**.

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,uFAAuF;IACvF,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;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"}

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

@@ -107,8 +107,9 @@ export interface ScriptDialogContext {
      * attaches it to the persisted result; the script return value must not carry env
      * (see {@link ScriptResult}).
      *
-     * Session runners decide where that snapshot is stored. In Voctiv platform compatibility
-     * mode it is used as the LE-style dialog environment.
+     * Session runners load the previous snapshot from Redis (`dialog:{uuid}`) at start and
+     * persist the final `env$` snapshot after every run (SIP, WebSocket, headless). Same key
+     * as legacy logic-executor `nn.env`.
      */
     env$?: BehaviorSubject<Record<string, unknown> | undefined>;
     /** Raw `dialog` table row from the Voctiv platform database. */

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":";;AA6NA,wCAaC;AAnCD,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;QAAE,OAAO,WAAW,CAAC;IAEnF,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":";;AA8NA,wCAaC;AAnCD,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;QAAE,OAAO,WAAW,CAAC;IAEnF,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAEnE,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}

package/dist/types/sip.d.ts

@@ -444,8 +444,8 @@ export interface ChannelSip {
      * `waitForEarly()` on the B-leg before sending audio.
      *
      * Supported by SIP channels. In worker isolation mode the host proxies the returned
-     * B-leg, including media operations, ASR, SIP control, LLM, and `bridge()`. WS and
-     * headless channels throw.
+     * B-leg, including media operations, ASR, SIP control, LLM, and `bridge()`. WS channels
+     * dial the B-leg via the host SIP stack and bridge client PCM to RTP. Headless channels throw.
      *
      * @param opts.sipUri - Full SIP URI, e.g. `"sip:+12025551234@trunk.carrier.com"`.
      * @param opts.msisdn - Legacy-mode phone number. The host resolves the SIP URI from the selected trunk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voctiv/agent-sdk",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Voctiv TypeScript agent SDK: defineScript and platform types for the voice/dialog scripting runtime.",
   "license": "UNLICENSED",
   "author": "",
@@ -22,7 +22,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",