@voctiv/agent-sdk 0.2.11 → 0.2.13

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.
 
@@ -173,6 +173,70 @@ On SIP channels, `channel.audio.say()` and `channel.audio.play()` automatically
 
 If the call terminates before media becomes available, deferred audio resolves as a no-op.
 
+### SIP Signalling Metadata
+
+On **SIP channels**, `channel.sip` exposes raw signalling beyond call state — useful for
+carrier routing, diversion chains, and vendor SDP attributes.
+
+#### INVITE headers (`inviteSipHeaders`)
+
+Snapshot of SIP headers from an **inbound INVITE** at call setup. Includes standard and
+extension headers (`Diversion`, `P-Asserted-Identity`, `X-Trunk-Id`, `X-Neuro-UUID`, …).
+
+| Property | Updates during call? |
+| --- | --- |
+| `inviteSipHeaders` | **No** — INVITE snapshot only; outbound B-legs usually `undefined` |
+
+```ts
+const h = channel.sip.inviteSipHeaders;
+const diversion = h?.Diversion; // string | string[] when multiple hops
+const trunkId = h?.['X-Trunk-Id'];
+```
+
+Header names match what the host stack exposes (case-sensitive). Duplicate headers become
+`string[]`.
+
+#### Remote SDP (`remoteSdp`, `getRemoteSdpDetails()`)
+
+| Property / method | Updates during call? |
+| --- | --- |
+| `remoteSdp` | **Yes** — latest negotiated remote SDP (INVITE, 183, 200, re-INVITE) |
+| `getRemoteSdpDetails()` | **Yes** — re-parses current `remoteSdp` on each call |
+
+```ts
+const raw = channel.sip.remoteSdp;
+const details = channel.sip.getRemoteSdpDetails();
+
+details?.session.connection; // e.g. "IN IP4 203.0.113.5"
+details?.attributes.rtpmap; // e.g. "0 PCMU/8000"
+details?.attributes['x-vendor-tag']; // custom a=x-vendor-tag:...
+```
+
+`getRemoteSdpDetails()` parses session lines (`o=`, `s=`, `c=`, `m=audio`) and all `a=`
+attributes. It is not a full SDP validator — use `remoteSdp` when you need the raw body.
+
+#### SIP INFO (`sipInfo$`)
+
+Live stream of incoming SIP INFO messages (`contentType` + `body`). Prefer `dtmf$` for DTMF.
+
+```ts
+channel.sip.sipInfo$.subscribe(({ contentType, body }) => {
+  logger.log('SIP INFO', { contentType, body });
+});
+```
+
+Events before subscribe are not replayed.
+
+#### Relating streams to SDP
+
+| Stream | `sdp` field |
+| --- | --- |
+| `progress$` | Present when a 1xx response carries SDP (e.g. 183 early media) |
+| `sipSignal$` | Present only on callbacks that include SDP; often empty on final `active` |
+
+For the **persisted** negotiated SDP, use `remoteSdp` / `getRemoteSdpDetails()`, not only
+the per-event `sdp` on `sipSignal$`.
+
 ### SIP Controls
 
 `channel.sip` also supports:
@@ -186,7 +250,43 @@ 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$` | Live incoming SIP INFO (`SipInfo`: `contentType`, `body`) |
+| `sipSignal$` | Low-level SIP stack events (`SipSignal`; `sdp` only on that callback) |
+| `remoteSdp` | Latest negotiated remote SDP body; updates when new SDP arrives |
+| `inviteSipHeaders` | Inbound INVITE header snapshot (`SipInviteHeaders`); does not update |
+| `getRemoteSdpDetails()` | Parse `remoteSdp` → `ParsedSdpDetails` (session + `a=` attributes) |
+| `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$` for call lifecycle. Use `remoteSdp` / `getRemoteSdpDetails()` for negotiated
+media description; use `inviteSipHeaders` for routing headers from the inbound INVITE.
+See **SIP Signalling Metadata** above.
 
 ### SIP Bridge
 
@@ -204,7 +304,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 +315,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 +404,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 +449,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 +460,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 +498,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 +511,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 +558,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
 
@@ -460,9 +658,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 +671,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 +704,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 +780,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 +843,8 @@ await channel.audio.say(answer);
 For streaming:
 
 ```ts
+import { map } from 'rxjs';
+
 const stream$ = channel.llm.stream('Answer briefly', {
   role: 'assistant',
 });
@@ -613,13 +855,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 +928,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 +937,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 +949,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:
 
@@ -697,6 +996,11 @@ await platform.call('+12025551234', {
 
 This means the platform may retry up to three times, waiting about five minutes between attempts.
 
+When you omit these options, the host fills defaults from `context.recallCount` / `context.recallDelay`
+(effective values for the current dialog). Those in turn fall back to CMS agent contact-rules
+(`context.agent?.recallCount` / `context.agent?.recallDelay`, legacy `nn.get_recall_count()` /
+`nn.get_recall_delay()`).
+
 Other scheduling options:
 
 - `priority`: higher-priority calls can be processed earlier by the dialer.
@@ -715,7 +1019,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 +1044,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 +1052,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 +1131,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 +1160,72 @@ export default defineScript(async ({ channel, context, platform }) => {
 
 `context` includes identity, telephony fields, params, routing metadata, and runtime helpers.
 
+### Agent env, recall defaults, and storage
+
+When the host exposes agent identity, `context.agent` provides agent-scoped helpers:
+
+```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 });
+```
+
+#### Recall settings (agent defaults vs effective)
+
+Recall behavior uses **two layers** on `context`:
+
+| Layer | Fields | Source | Use when |
+|-------|--------|--------|----------|
+| Agent defaults | `context.agent?.recallCount`, `context.agent?.recallDelay` | CMS contact-rules (`agent.recall_count`, `agent.delay` → seconds) | Compare with CMS settings; legacy `nn.get_recall_count()` / `get_recall_delay()` parity |
+| Effective for this run | `context.recallCount`, `context.recallDelay` | `dialog.params` / `call.params`, then agent defaults | Schedule outbound calls, recall routing logic |
+
+Precedence for effective values: **dialog/call params** (`recall_count`, `recall_delay`) **>** agent CMS defaults.
+
+`context.attempt` is the current recall attempt counter from `dialog.params.attempt` (starts at 0).
+`context.entryPoint` is the routing branch for this run (e.g. after a failed call).
+
+```ts
+// Use effective values when scheduling the next outbound leg
+await context.platform?.call?.(msisdn, {
+  recallCount: context.recallCount,
+  recallDelay: context.recallDelay,
+  entryPoint: 'on_follow_up',
+});
+
+// Log CMS defaults vs per-dialog override
+logger.log('recall config', {
+  effective: { count: context.recallCount, delay: context.recallDelay },
+  agentDefault: {
+    count: context.agent?.recallCount,
+    delay: context.agent?.recallDelay,
+  },
+  attempt: context.attempt,
+});
+```
+
+Values are loaded once at script start from the legacy agent row (cached with other LE agent
+resolution). They are plain snapshots — not `BehaviorSubject`s and not re-fetched during the run.
+
+`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.
@@ -870,6 +1236,9 @@ Important fields:
 - `context.initialData`: shallow snapshot of params at script start.
 - `context.dialogParams`: live param map for the run.
 - `context.entryPoint`: current routing entry point.
+- `context.attempt`: current recall attempt number (`dialog.params.attempt`).
+- `context.recallCount` / `context.recallDelay`: effective recall settings for this dialog/call.
+- `context.agent?.recallCount` / `context.agent?.recallDelay`: CMS agent defaults (immutable snapshot).
 - `context.headless`: true for offline/queue/messaging sessions without a real media channel.
 - `context.runTime`: async execution budget helper.
 - `context.env$`: persisted dialog environment as an RxJS `BehaviorSubject`.
@@ -895,7 +1264,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 +1299,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';