@voctiv/agent-sdk 0.2.10 → 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,128 @@ 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 only supported by the main SIP channel. Worker-isolated, WS, and headless channels do not create nested 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
+
+Use `channel.sip.makeCall()` when a live SIP script needs to create an outbound B-leg immediately and connect it to the current call. This is different from `platform.call()`, which schedules a separate platform-managed call.
+
+For a normal SIP URI, pass `sipUri` explicitly:
+
+```ts
+const bLeg = await channel.sip.makeCall({
+  sipUri: 'sip:+12025551234@trunk.example.com',
+});
+
+await bLeg.sip.waitForAnswer();
+
+const teardown = channel.sip.bridge(bLeg);
+```
+
+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({
+  msisdn: '+12025551234',
+});
+
+await bLeg.sip.waitForAnswer();
+const teardown = channel.sip.bridge(bLeg);
+```
+
+Pass `channel` as a trunk-name override when selecting which outbound trunk to use:
+
+```ts
+const bLeg = await channel.sip.makeCall({
+  msisdn: '+12025551234',
+  channel: 'carrier-main',
+});
+
+await bLeg.sip.waitForAnswer();
+const teardown = channel.sip.bridge(bLeg);
+```
+
+The returned B-leg is a full `MediaChannel`. You can interact with it before or after bridging:
+
+```ts
+const bLeg = await channel.sip.makeCall({
+  msisdn: '+12025551234',
+});
+
+await channel.audio.say('I am calling the second participant now.');
+
+await bLeg.sip.waitForAnswer();
+await bLeg.audio.say('You are about to be connected.');
+
+const teardown = channel.sip.bridge(bLeg);
+
+channel.events.terminated$.subscribe(() => {
+  teardown();
+  bLeg.sip.hangup();
+});
+```
+
+```ts
+const bLeg = await channel.sip.makeCall({
+  msisdn: '+12025551234',
+  channel: 'carrier-main',
+});
+
+await bLeg.sip.waitForEarly();
+
+await bLeg.audio.say('Please wait while I connect the call.');
+
+const asr = await bLeg.createAsr({ language: 'en-US' });
+asr.result$.subscribe((text) => {
+  if (/operator/i.test(text)) {
+    bLeg.sip.sendDtmf('0');
+  }
+});
+
+await bLeg.sip.waitForAnswer();
+
+const teardown = channel.sip.bridge(bLeg);
+
+channel.events.terminated$.subscribe(() => {
+  teardown();
+  bLeg.sip.hangup();
+  asr.destroy();
+});
+```
+
+`bridge()` returns a teardown function. Call it when you want to disconnect the audio bridge without necessarily hanging up either leg. Use `bLeg.sip.hangup()` or `channel.sip.hangup()` when you want to terminate a call leg.
+
+While a bridge is active, `channel.audio.say()` still sends audio only to the A-leg and `bLeg.audio.say()` sends audio only to the B-leg. These syntheses are mixed into the selected leg while the participants can also hear each other, so pause or tear down the bridge first if you need a private prompt.
 
 ## ASR, VAD, And Smart Turn
 
@@ -213,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.
@@ -258,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({
@@ -269,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
@@ -293,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', {
@@ -306,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.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' },
+});
 
-`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()`.
+// 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
 
@@ -322,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
+
+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. |
 
-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.
+`play()` ignores `tts*` and `cache` for raw audio. `preload()` only accepts `cache` overrides.
 
 ## TTS Credentials And Vendor Parameters
 
@@ -369,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('Здравствуйте!', {
@@ -382,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):
@@ -415,12 +634,14 @@ 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
 
 ASR and TTS errors are propagated to the script. Unhandled errors are always logged server-side, but scripts can catch them to react: fall back to a different vendor, notify the caller, or abort the dialog.
 
+`channel.events.error$` is the canonical stream for media/runtime errors. TTS methods still reject their own promise when the awaited operation fails, and `AsrHandle.error$` still exposes errors scoped to one recognizer, but the same ASR/TTS failures are also emitted on `channel.events.error$`.
+
 ### TTS Errors — Promise Rejection
 
 `say()` and `play()` reject their promises when TTS/playback fails:
@@ -460,13 +681,16 @@ A degraded handle (returned when connector creation itself failed) has an inert
 
 ### Channel Error Stream
 
-`channel.events.error$` is a unified stream of all media errors — both ASR and TTS:
+`channel.events.error$` is a unified stream of all media errors — ASR creation/runtime failures, TTS synthesis/playback failures, SIP/channel failures, and other host media errors:
 
 ```ts
 channel.events.error$.subscribe((err) => {
-  logger.warn(`[${err.source}] ${err.message}`, {
+  logger.warn(`[${err.source}:${err.operation ?? 'unknown'}] ${err.message}`, {
+    phase: err.phase,
     code: err.code,
     vendor: err.vendor,
+    queue: err.queue,
+    alias: err.alias,
   });
 });
 ```
@@ -475,18 +699,67 @@ channel.events.error$.subscribe((err) => {
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `source` | `'asr' \| 'tts' \| 'sip' \| 'channel'` | Which subsystem produced the error. |
+| `source` | `'asr' \| 'tts' \| 'sip' \| 'channel' \| 'llm'` | Which subsystem produced the error. |
+| `phase` | `'create' \| 'start' \| 'stream' \| 'playback' \| 'finalize' \| 'destroy'?` | Lifecycle phase where the error happened. |
+| `operation` | `string?` | Public SDK operation, e.g. `createAsr`, `audio.say`, or `audio.play`. |
+| `recoverable` | `boolean?` | Whether the runtime can keep the session alive after this error. |
+| `handleId` | `string?` | ASR handle id when the error belongs to a recognizer instance. |
+| `queue` | `number?` | Mixer queue index when the error belongs to an audio operation. |
+| `alias` | `string?` | Queue item alias when the error belongs to playback. |
 | `message` | `string` | Human-readable description. |
-| `code` | `number?` | HTTP status, gRPC status, or WebSocket close code. |
+| `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 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',
@@ -500,6 +773,8 @@ await channel.audio.say(answer);
 For streaming:
 
 ```ts
+import { map } from 'rxjs';
+
 const stream$ = channel.llm.stream('Answer briefly', {
   role: 'assistant',
 });
@@ -510,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?)` 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(utterance, options?)` runs intent/entity extraction. 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', {
@@ -526,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
 
@@ -535,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
 
@@ -547,6 +879,8 @@ 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 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:
 
 ```ts
@@ -610,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
 
@@ -635,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
 
@@ -647,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.
@@ -726,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
 
@@ -755,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.
@@ -790,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
 
@@ -825,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,29 +1,29 @@
 /**
  * @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';
-export type { ScriptDialogContext, ScriptRunTime, ScriptResult, PersistedScriptResult, ScriptError, } from './types/script-context';
+export type { ScriptDialogContext, ScriptPhase, ScriptRunTime, ScriptResult, PersistedScriptResult, ScriptError, AgentContext, AgentEnvSetOptions, StorageContextApi, } from './types/script-context';
+export { getScriptPhase } from './types/script-context';
 export type { NluScriptApi, PlatformApi, DialogApi, ScheduleCallOptions, SendMessageOptions, InboundMessage, MessagingApi, } from './types/platform';
 export type { ScriptLogger } from './types/logger';
 export type { MediaChannel, ChannelAudio, ChannelEvents, } from './types/media-channel';

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,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAEhC,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,31 +1,32 @@
 "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.defineScript = void 0;
+exports.isLegacyPhraseRecord = exports.LEGACY_PHRASE_RECORD_BRAND = exports.getScriptPhase = 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 script_context_1 = require("./types/script-context");
+Object.defineProperty(exports, "getScriptPhase", { enumerable: true, get: function () { return script_context_1.getScriptPhase; } });
 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; } });

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;AAmDrB,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/errors.d.ts

@@ -6,14 +6,28 @@
  */
 export interface MediaError {
     /** Which subsystem produced the error. */
-    source: 'asr' | 'tts' | 'sip' | 'channel';
+    source: 'asr' | 'tts' | 'sip' | 'channel' | 'llm';
+    /** Lifecycle phase where the error happened. */
+    phase?: 'create' | 'start' | 'stream' | 'playback' | 'finalize' | 'destroy';
+    /** Public SDK operation that produced the error, e.g. `createAsr`, `audio.say`, or `audio.play`. */
+    operation?: string;
+    /** Whether the runtime can keep the session alive after this error. */
+    recoverable?: boolean;
+    /** ASR handle id when the error belongs to a specific recognizer instance. */
+    handleId?: string;
+    /** Mixer queue index when the error belongs to an audio operation. */
+    queue?: number;
+    /** Queue item alias when the error belongs to a specific playback item. */
+    alias?: string;
     /** Human-readable description (same string that appears in server logs). */
     message: string;
     /** HTTP status code, gRPC status, or WebSocket close code when available. */
-    code?: number;
+    code?: number | string;
     /** Vendor/engine identifier, e.g. `"yandex"`, `"elevenlabs"`, `"azure"`. */
     vendor?: string;
     /** Arbitrary provider-specific payload for advanced diagnostics. */
     details?: unknown;
+    /** Original provider/runtime error when available in-process. */
+    cause?: unknown;
 }
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IAC1C,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,CAAC;IAClD,gDAAgD;IAChD,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5E,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}

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;
     /**
@@ -118,12 +118,13 @@ export interface ChannelEvents {
     /** Structured messages from the WS client or bridge (event + payload). */
     readonly message$: Observable<DataMessage>;
     /**
-     * Unified stream of runtime media errors (ASR connector failures, TTS HTTP errors,
-     * missing API keys, etc.).
+     * Canonical stream of runtime media errors (ASR connector creation/runtime failures,
+     * TTS synthesis/playback failures, missing API keys, etc.).
      *
-     * Subscribing is optional — unhandled errors are always logged server-side. Use this
-     * when the script needs to react (e.g. fall back to a different vendor, notify the
-     * caller, or abort the dialog).
+     * TTS methods still reject their own promises when the awaited operation fails, and
+     * `AsrHandle.error$` still exposes recognizer-scoped errors, but the same failures
+     * are also emitted here for one-place monitoring. Subscribing is optional —
+     * unhandled errors are always logged server-side.
      *
      * ```ts
      * channel.events.error$.subscribe(err => {

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

@@ -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/platform.d.ts

@@ -46,17 +46,18 @@ export interface ScheduleCallOptions {
      */
     entryPoint?: string;
     /**
-     * Legacy compatibility field for callers that schedule without a current `scriptId`.
+     * Legacy compatibility field for old callers.
      *
-     * ScriptEngine uses this to allow scheduling when the current script id is not
-     * available. It does not resolve script names or paths from this field.
+     * Outbound calls can be scheduled without a legacy `script_id`; the dialer can
+     * resolve the runtime script from the agent UUID. This field is not used to
+     * resolve script names or paths.
      */
     script?: string;
     /**
      * Legacy trunk id as string or number (same as LE `call.trunk_id`) when `trunkId` is not set.
      * Forwarded to the dialer for `X-Via-Trunk` / gateway routing.
      */
-    channel?: string;
+    channel?: string | number;
     /** How many times to retry on failure. Stored as `recall_count` in call params. */
     recallCount?: number;
     /** Delay in seconds between retries. Stored as `recall_delay` in call params. */
@@ -73,8 +74,8 @@ export interface ScheduleCallOptions {
     protoAdditional?: Record<string, string>;
     /**
      * LE `call.trunk_id` — required for the legacy mass outbound dialer to originate SIP.
-     * If omitted, the scheduler tries `channel` (numeric), `dialog.params.trunk_id`, then
-     * env `LEGACY_V3_SCHEDULED_CALL_DEFAULT_TRUNK_ID`.
+     * If omitted, the scheduler tries `channel` (numeric), `dialog.params.trunk_id`,
+     * `agent.trunk_id`, then env `LEGACY_V3_SCHEDULED_CALL_DEFAULT_TRUNK_ID`.
      */
     trunkId?: number;
     /** LE `call.pool_id` when absent from dialog params. */
@@ -151,6 +152,10 @@ export interface MessagingApi {
  * Provides access to NLU, dialog state management, outbound call scheduling,
  * phrase records, and messaging. These operations are legacy-platform backed and
  * require `context.legacyV3Compat === true`.
+ *
+ * `platform.call(msisdn)` may be called without options. The host fills omitted
+ * scheduling/routing fields from agent/dialog settings when available; explicit
+ * `options` always win over those defaults.
  */
 export interface PlatformApi {
     /** NLU intent/entity extraction API; throws outside legacy V3 compatibility mode. */

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

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

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

@@ -1,5 +1,26 @@
 import type { BehaviorSubject } from 'rxjs';
 import type { InboundMessage } from './platform';
+/** Options for writing legacy LE-style agent environment values. */
+export interface AgentEnvSetOptions {
+    /** TTL in days, matching legacy `nn.agent.env(..., expire=days)`. */
+    expire?: number;
+}
+/** Legacy LE-style global environment shared by all dialogs of the agent. */
+export interface AgentContext {
+    /** Numeric NLU / LE agent id, when resolved by the host. */
+    id?: number;
+    /** Omni / LE agent UUID, when resolved by the host. */
+    uuid?: string;
+    /** Read/write agent-level env stored in Redis under `agent:{uuid}`. */
+    env?: {
+        (): Promise<Record<string, unknown>>;
+        <T = unknown>(key: string): Promise<T | undefined>;
+        (key: string, value: unknown, options?: AgentEnvSetOptions): Promise<void>;
+        (values: Record<string, unknown>, options?: AgentEnvSetOptions): Promise<void>;
+    };
+}
+/** Read LE/CMS global variables from `storage` with agent → company fallback. */
+export type StorageContextApi = (...keys: string[]) => Promise<Record<string, string | null>>;
 /**
  * First-level **`context`** passed to every **`defineScript`** handler.
  *
@@ -37,6 +58,13 @@ export interface ScriptDialogContext {
      * May be `0` when no agent id is configured; NLU and `platform.call()` will then fail.
      */
     agentId: number;
+    /** Agent identity and legacy global agent env (`context.agent.env`). */
+    agent?: AgentContext;
+    /**
+     * Read global variables configured in agent settings, then company-level globals.
+     * Always returns an object containing every requested key.
+     */
+    storage?: StorageContextApi;
     /**
      * **Snapshot** of dialog/session payload when the script run started.
      *
@@ -79,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. */
@@ -139,6 +168,23 @@ export interface ScriptRunTime {
      */
     extend(requestedMs: number): number;
 }
+/**
+ * High-level phase of a script execution lifecycle. Useful for branching logic
+ * between pre-call preparation, the live call, and post-call processing.
+ */
+export type ScriptPhase = 'before_call' | 'online' | 'after_call_success' | 'after_call_failed' | 'messaging' | 'recall' | 'headless_other';
+/**
+ * Determines which phase of the dialog lifecycle the script is currently executing in.
+ *
+ * - `before_call` — headless run that typically schedules an outbound call.
+ * - `online` — live SIP/media session (voice call active).
+ * - `after_call_success` — headless run after a successful call completion.
+ * - `after_call_failed` — headless run after call failure (no answer, reject, etc.).
+ * - `messaging` — headless run triggered by an inbound message.
+ * - `recall` — headless recall attempt.
+ * - `headless_other` — any other headless invocation not matching the above.
+ */
+export declare function getScriptPhase(context: ScriptDialogContext): ScriptPhase;
 /** Error info attached to {@link ScriptResult} when a script fails. */
 export interface ScriptError {
     /**

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":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;;;;;;OASG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,4DAA4D;IAC5D,cAAc,EAAE,OAAO,CAAC;IAExB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IAE5D,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAErC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB,yDAAyD;IACzD,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,WAAW,IAAI,MAAM,CAAC;IACtB,4CAA4C;IAC5C,iBAAiB,IAAI,MAAM,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;CACrC;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAsB,SAAQ,YAAY;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B"}
+{"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

@@ -1,3 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getScriptPhase = getScriptPhase;
+const AFTER_CALL_SUCCESS_ENTRY_POINTS = new Set([
+    'on_success_call',
+    'after_call_success',
+    'on_done_call',
+]);
+const AFTER_CALL_FAILED_ENTRY_POINTS = new Set([
+    'on_failed_call',
+    'after_call_failed',
+]);
+const RECALL_ENTRY_POINTS = new Set(['on_recall', 'recall']);
+/**
+ * Determines which phase of the dialog lifecycle the script is currently executing in.
+ *
+ * - `before_call` — headless run that typically schedules an outbound call.
+ * - `online` — live SIP/media session (voice call active).
+ * - `after_call_success` — headless run after a successful call completion.
+ * - `after_call_failed` — headless run after call failure (no answer, reject, etc.).
+ * - `messaging` — headless run triggered by an inbound message.
+ * - `recall` — headless recall attempt.
+ * - `headless_other` — any other headless invocation not matching the above.
+ */
+function getScriptPhase(context) {
+    if (!context.headless)
+        return 'online';
+    const ep = context.entryPoint?.trim().toLowerCase() ?? '';
+    if (AFTER_CALL_SUCCESS_ENTRY_POINTS.has(ep))
+        return 'after_call_success';
+    if (AFTER_CALL_FAILED_ENTRY_POINTS.has(ep))
+        return 'after_call_failed';
+    if (RECALL_ENTRY_POINTS.has(ep))
+        return 'recall';
+    if (ep === 'on_message_api_received' || context.inboundMessage)
+        return 'messaging';
+    if (!ep || ep === 'main' || ep === 'default')
+        return 'before_call';
+    return 'headless_other';
+}
 //# sourceMappingURL=script-context.js.map

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

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

@@ -437,22 +437,27 @@ export interface ChannelSip {
      */
     sendProgress(): void;
     /**
-     * Initiate an **outbound** SIP call to the given SIP URI.
+     * Initiate an **outbound** SIP call and return the new B-leg.
      *
      * Returns a new {@link MediaChannel} representing the B-leg. The returned channel
      * has its own `sip`, `audio`, `events`, etc. — use `waitForAnswer()` or
      * `waitForEarly()` on the B-leg before sending audio.
      *
-     * Supported only by the main-thread SIP channel. Worker-isolated, WS, and headless
-     * channels throw because the current worker bridge does not proxy nested call legs.
+     * 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 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.
+     * @param opts.channel - Legacy-mode trunk name override, matching `nv.bridge(..., channel=...)`.
+     * @param opts.protoAdditional - Legacy-mode extra outbound INVITE headers.
      * @param opts.fromUri - Optional caller-ID override SIP URI.
      * @returns A new `MediaChannel` for the outbound leg.
      *
      * ```ts
      * const bLeg = await channel.sip.makeCall({
-     *   sipUri: 'sip:+12025551234@trunk.carrier.com',
+     *   msisdn: '+12025551234',
+     *   channel: 'carrier-main',
      * });
      * await bLeg.sip.waitForAnswer();
      * // Bridge both legs so callers hear each other
@@ -460,8 +465,11 @@ export interface ChannelSip {
      * ```
      */
     makeCall(opts: {
-        sipUri: string;
+        sipUri?: string;
+        msisdn?: string;
+        channel?: string;
         fromUri?: string;
+        protoAdditional?: Record<string, string>;
         legacyInviteHeaders?: {
             xViaTrunk: string;
             protoAdditional?: Record<string, string>;

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voctiv/agent-sdk",
-  "version": "0.2.10",
+  "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",