@voctiv/agent-sdk 0.3.0 → 0.3.2

package/README.md

@@ -70,17 +70,25 @@ export default defineScript(async ({ channel, logger, context }) => {
 });
 ```
 
+
+
 ## Examples
 
-The [`examples/`](./examples/) folder contains copy-paste-ready scripts:
+The `[examples/](./examples/)` folder contains copy-paste-ready scripts:
+
+
+| Example                                                                     | Description                                                                |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [outbound-with-recall.ts](./examples/outbound-with-recall.ts)               | Outbound with `recallCount` / `recallDelay` (automatic redial on failure)  |
+| [recall-routing-by-attempt.ts](./examples/recall-routing-by-attempt.ts)     | Online recall: branch on `context.attempt` (`getScriptPhase` → `'online'`) |
+| [schedule-call-with-defaults.ts](./examples/schedule-call-with-defaults.ts) | `platform.call()` without explicit recall — CMS defaults from `context`    |
+| [after-call-continuation.ts](./examples/after-call-continuation.ts)         | `onSuccessCall` / `onFailedCall` vs recall (mutually exclusive)            |
+| [read-recall-from-params.ts](./examples/read-recall-from-params.ts)         | `parseRecallDelaySeconds()` / `parseRecallCount()` on legacy params        |
+| [custom-media-providers.ts](./examples/custom-media-providers.ts)           | Host-only `mediaProviders` module (`ScriptAsrConnector` / `ScriptTtsConnector`) |
+| [custom-media-providers-script.ts](./examples/custom-media-providers-script.ts) | Sandboxed `defineScript` entry that uses custom vendors (no `ws` import) |
+
+
 
-| Example | Description |
-|---------|-------------|
-| [outbound-with-recall.ts](./examples/outbound-with-recall.ts) | Outbound with `recallCount` / `recallDelay` (automatic redial on failure) |
-| [recall-routing-by-attempt.ts](./examples/recall-routing-by-attempt.ts) | Online recall: branch on `context.attempt` (`getScriptPhase` → `'online'`) |
-| [schedule-call-with-defaults.ts](./examples/schedule-call-with-defaults.ts) | `platform.call()` without explicit recall — CMS defaults from `context` |
-| [after-call-continuation.ts](./examples/after-call-continuation.ts) | `onSuccessCall` / `onFailedCall` vs recall (mutually exclusive) |
-| [read-recall-from-params.ts](./examples/read-recall-from-params.ts) | `parseRecallDelaySeconds()` / `parseRecallCount()` on legacy params |
 
 ### Quick recall example
 
@@ -112,17 +120,25 @@ const delaySec = parseRecallDelaySeconds(context.dialogParams?.recall_delay); //
 const maxAttempts = parseRecallCount(context.dialogParams?.recall_count);
 ```
 
+
+
 ## What The SDK Contains
 
 `defineScript(fn)` marks the default export as the script entry point. It returns the same function and exists to give TypeScript the correct `ScriptContext` shape.
 
+`defineMediaProviders(def)` marks a named `mediaProviders` export for custom ASR/TTS factories.
+Ship it in a **sibling** module (`media-providers/`), not in the sandboxed script entry — see
+[Custom ASR / TTS Providers](#custom-asr--tts-providers).
+
 **Three different “context” names:**
 
-| Name | Meaning |
-| --- | --- |
-| `ScriptContext` | Top-level injection: `{ channel, logger, context, platform }` |
-| `context` (`ScriptDialogContext`) | Dialog identity, params, routing snapshot, `env$`, headless — see [Dialog Context](#dialog-context-and-persisted-env) |
-| `options.context` on `platform.nlu.extract` | Opaque NLU disambiguation string/JSON — **not** dialog context |
+
+| Name                                        | Meaning                                                                                                               |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `ScriptContext`                             | Top-level injection: `{ channel, logger, context, platform }`                                                         |
+| `context` (`ScriptDialogContext`)           | Dialog identity, params, routing snapshot, `env$`, headless — see [Dialog Context](#dialog-context-and-persisted-env) |
+| `options.context` on `platform.nlu.extract` | Opaque NLU disambiguation string/JSON — **not** dialog context                                                        |
+
 
 `ScriptContext` is the top-level object passed to a script:
 
@@ -143,6 +159,8 @@ const maxAttempts = parseRecallCount(context.dialogParams?.recall_count);
 - `channel.events` exposes speech, interrupt, termination, WS data message, and media error observables.
 - `channel.textInput` injects synthetic ASR results for tests and debug clients.
 
+
+
 ## SIP And Pre-Answer Media
 
 SIP sessions expose call state through `channel.sip.state`, `state$`, `progress$`, `early$`, and `answered$`.
@@ -154,6 +172,8 @@ The important states are:
 - `active`: final 200 OK has been received or sent.
 - `terminated`: the call ended and no more audio is possible.
 
+
+
 ### How Pre-Answer Works
 
 Pre-answer means the SIP media path is open before the call is finally answered with `200 OK`. In this state the caller can already hear TTS, the script can already receive audio for ASR, and DTMF can be exchanged.
@@ -231,14 +251,16 @@ carrier routing, diversion chains, and vendor SDP attributes.
 
 #### When to use what
 
-| Need | API | When |
-| --- | --- | --- |
-| Routing / identity / locale from the **inbound INVITE** (`Diversion`, `X-Trunk-Id`, `X-Neuro-UUID`, `X-language`, …) | `channel.sip.inviteSipHeaders` | Call **start** only (snapshot) |
-| Peer signal **during** the call (e.g. mid-call language in INFO body) | `channel.sip.sipInfo$` | After subscribe; each INFO |
-| DTMF digits | `channel.sip.dtmf$` | Prefer over parsing INFO |
-| SDP / codec / connection | `remoteSdp` / `getRemoteSdpDetails()` | May change (183 / 200 / re-INVITE) |
-| SIP response code / phrase (180, 486, …) | `sipSignal$` | Low-level; **no** response headers |
-| Live SIP headers on 200 / re-INVITE / BYE | — | **Not exposed** |
+
+| Need                                                                                                                 | API                                   | When                               |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------- |
+| Routing / identity / locale from the **inbound INVITE** (`Diversion`, `X-Trunk-Id`, `X-Neuro-UUID`, `X-language`, …) | `channel.sip.inviteSipHeaders`        | Call **start** only (snapshot)     |
+| Peer signal **during** the call (e.g. mid-call language in INFO body)                                                | `channel.sip.sipInfo$`                | After subscribe; each INFO         |
+| DTMF digits                                                                                                          | `channel.sip.dtmf$`                   | Prefer over parsing INFO           |
+| SDP / codec / connection                                                                                             | `remoteSdp` / `getRemoteSdpDetails()` | May change (183 / 200 / re-INVITE) |
+| SIP response code / phrase (180, 486, …)                                                                             | `sipSignal$`                          | Low-level; **no** response headers |
+| Live SIP headers on 200 / re-INVITE / BYE                                                                            | —                                     | **Not exposed**                    |
+
 
 Decision guide:
 
@@ -257,10 +279,12 @@ Outbound INVITE headers you **send** go through `platform.call({ protoAdditional
 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`, `X-language`, …).
 
-| Property | Updates during call? |
-| --- | --- |
+
+| Property           | Updates during call?                                                               |
+| ------------------ | ---------------------------------------------------------------------------------- |
 | `inviteSipHeaders` | **No** — INVITE snapshot only; outbound B-legs / WS / headless usually `undefined` |
 
+
 ```ts
 const h = channel.sip.inviteSipHeaders;
 const diversion = h?.Diversion; // string | string[] when multiple hops
@@ -273,10 +297,12 @@ Header names match what the host stack exposes (case-sensitive). Duplicate heade
 
 #### 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 |
+
+| 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;
@@ -306,11 +332,13 @@ 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) |
+
+| 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$`.
 
@@ -337,31 +365,33 @@ unnoticed. Guard them with `context.headless` or `channel.type` when a script ru
 SIP-only unless noted. WS/headless: most methods are no-ops and `state` behaves as synthetic
 `active`, except `makeCall()` and `bridge()`, which throw.
 
-| 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$` | Mid-call SIP INFO (`contentType` + `body` only; INFO headers not exposed) |
-| `sipSignal$` | Low-level stack events (`statusCode` / `statusPhrase` / optional `sdp`; no headers) |
-| `remoteSdp` | Latest negotiated remote SDP body; updates when new SDP arrives |
-| `inviteSipHeaders` | Start-of-call inbound INVITE header snapshot; 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` |
+
+| 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$`                    | Mid-call SIP INFO (`contentType` + `body` only; INFO headers not exposed)           |
+| `sipSignal$`                  | Low-level stack events (`statusCode` / `statusPhrase` / optional `sdp`; no headers) |
+| `remoteSdp`                   | Latest negotiated remote SDP body; updates when new SDP arrives                     |
+| `inviteSipHeaders`            | Start-of-call inbound INVITE header snapshot; 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
@@ -520,20 +550,22 @@ const asr = await channel.createAsr({
 
 Each vendor connector accepts its native parameter names:
 
-| Vendor | Accepted `data` keys |
-| --- | --- |
-| **Azure** | `subscription_key` or `api_key`, `region` |
-| **Yandex** | `api_key` or `token`, `folder_id` |
-| **ElevenLabs** | `api_key` (or `xi_api_key`), `model` |
-| **Deepgram** | `api_key` |
-| **Google** | `email`, `private_key`, `project_id` |
-| **Whisper** | `url`, `rate`, `toFloat` |
+
+| Vendor         | Accepted `data` keys                      |
+| -------------- | ----------------------------------------- |
+| **Azure**      | `subscription_key` or `api_key`, `region` |
+| **Yandex**     | `api_key` or `token`, `folder_id`         |
+| **ElevenLabs** | `api_key` (or `xi_api_key`), `model`      |
+| **Deepgram**   | `api_key`                                 |
+| **Google**     | `email`, `private_key`, `project_id`      |
+| **Whisper**    | `url`, `rate`, `toFloat`                  |
+
 
 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.
 
 ### Platform ASR Key Selection
 
-When platform credential catalogs are enabled, select ASR keys by **`name`**:
+When platform credential catalogs are enabled, select ASR keys by `name`:
 
 ```ts
 const asr = await channel.createAsr({
@@ -548,12 +580,15 @@ When both `name` (platform key) and explicit `data` are provided, `data` values
 
 ## TTS, Playback, And Mixer Queues
 
-All audio playback goes through **`channel.audio`** (`ChannelAudio`). There are no top-level
+All audio playback goes through `channel.audio` (`ChannelAudio`). There are no top-level
 `channel.say()` / `channel.play()` shortcuts on `MediaChannel`.
 
 Create a reusable TTS session with `channel.createTts(config?)` — same pattern as `createAsr`.
 Call `tts.say` / `tts.say$` / `tts.presay` on the handle so synthesis reuses the warmed SSL / streaming WebSocket.
 
+Custom engines from a logic package are documented in
+[Custom ASR / TTS Providers](#custom-asr--tts-providers).
+
 ```ts
 const tts = await channel.createTts({
   vendor: 'elevenlabs',
@@ -609,20 +644,22 @@ terminate the Observable via **error** (`MediaError`), and are also mirrored on
 You can still use `channel.audio.say(..., { tts })` if you prefer the channel API; a matching
 pre-warmed session is also reused when vendor+config align.
 
-| Method | Purpose |
-| --- | --- |
-| `channel.createTts(config?)` | Pre-warm a TTS connector / streaming socket; returns `TtsHandle` |
-| `tts.say(textOrObservable, options?)` | Synthesize via the handle's cached connection (`Promise`) |
-| `tts.say$(textOrObservable, options?)` | Same path with per-utterance status events (`Observable`) |
-| `tts.presay(text, options?)` | Pre-synthesize into the host TTS cache via the handle |
-| `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) |
+
+| Method                                          | Purpose                                                          |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| `channel.createTts(config?)`                    | Pre-warm a TTS connector / streaming socket; returns `TtsHandle` |
+| `tts.say(textOrObservable, options?)`           | Synthesize via the handle's cached connection (`Promise`)        |
+| `tts.say$(textOrObservable, options?)`          | Same path with per-utterance status events (`Observable`)        |
+| `tts.presay(text, options?)`                    | Pre-synthesize into the host TTS cache via the handle            |
+| `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.
 
@@ -655,6 +692,8 @@ await channel.audio.play('/opt/prompts/welcome.wav', {
 });
 ```
 
+
+
 ### Pre-synthesis And Preload
 
 `channel.audio.presay(text, options?)` runs TTS ahead of time and stores PCM in the host TTS
@@ -702,26 +741,28 @@ 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
+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`):
+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) |
 
-| 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`**:
+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.
+- `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);
@@ -759,23 +800,290 @@ For sentence-split TTS, queue item aliases are suffixed as `alias-0`, `alias-1`,
 
 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. |
+
+| Field         | Type                       | Applies to      | Description                                            |
+| ------------- | -------------------------- | --------------- | ------------------------------------------------------ |
+| `queue`       | `number?`                  | `say`, `play`   | Mixer queue **0–4** (default **0**).                   |
+| `alias`       | `string?`                  | `say`, `play`   | Stable item id for `remove()` and queue events.        |
+| `loop`        | `boolean?`                 | `say`, `play`   | Restart after finish until stopped/removed.            |
+| `loopDelayMs` | `number?`                  | `say`, `play`   | Silence between loop iterations.                       |
+| `volume`      | `number?`                  | `say`, `play`   | Sets **whole queue** gain **0.0–1.0** (not per-item).  |
+| `ttsStrategy` | `TtsStrategy?`             | `say`, `presay` | `sentence` | `streaming` | `full`.                     |
+| `ttsVendor`   | `TtsVendor?`               | `say`, `presay` | Override `channel.params.ttsVendor`.                   |
+| `name`        | `string?`                  | `say`, `presay` | Platform TTS credential `name` (key catalog selector). |
+| `ttsConfig`   | `Record<string, unknown>?` | `say`, `presay` | Vendor params; `name` key is stripped before send.     |
+| `cache`       | `true | CacheOptions?`     | `say`, `presay` | TTS file cache; optional platform phrase persist.      |
+
 
 `play()` ignores `tts*` and `cache` for raw audio. `preload()` only accepts `cache` overrides.
 
+## Custom ASR / TTS Providers
+
+Trusted logic packages can ship their own ASR/TTS engines. The host loads
+`export const mediaProviders` with a normal Node `require` **outside** the script VM
+(same privileges as the API). Use this only for packages you trust.
+
+Mid-script `registerAsr` / `registerTts` is **not** supported — declare vendors at module load.
+
+### Package layout (required for connectors that use `ws` / Node APIs)
+
+Put providers in a **sibling module**. Do **not** re-export them from the sandboxed entry
+(`dist/index.js`). The script worker evaluates the entry under a restricted VM: there is
+**no** global `process`, and loading `ws` (or similar) inside that graph fails even when
+`net` / `tls` are allowlisted.
+
+Recommended layout after `tsc`:
+
+```text
+dist/
+  index.js                 ← defineScript only (sandboxed)
+  media-providers/
+    index.js               ← export const mediaProviders (host-only)
+    my-asr.js
+    my-tts.js
+```
+
+Host resolution order for `mediaProviders`:
+
+1. `<entryDir>/media-providers/index.js`
+2. `<entryDir>/media-providers.js`
+3. `<scriptRoot>/media-providers/…` and `dist/media-providers/…` fallbacks
+4. the script entry itself (backward compatible — avoid for `ws`-based connectors)
+
+Sandboxed script code may import **lightweight** helpers from the providers package
+(e.g. vendor id constants) if those files do **not** `require('ws')` / touch `process`.
+Never import the connector classes or `mediaProviders` index from the entry.
+
+Examples:
+
+- Host module: [`examples/custom-media-providers.ts`](./examples/custom-media-providers.ts)
+- Script entry: [`examples/custom-media-providers-script.ts`](./examples/custom-media-providers-script.ts)
+
+### Contracts (implement the interfaces)
+
+There are no abstract base classes — implement the SDK interfaces so TypeScript checks
+the full surface and IDEs autocomplete correctly:
+
+| Interface | Role |
+| --- | --- |
+| `ScriptAsrConnector` | Custom STT connector returned by an `asr` factory |
+| `ScriptTtsConnector` | Unified batch + optional streaming TTS connector |
+| `MediaConnectorContext` | `id`, flattened `config`, `dialogUuid`, `debug$` passed into factories |
+| `MediaProviderShared` | Optional per-dialog object from `createShared` |
+
+`defineMediaProviders` is an identity helper for typing. Factories must return objects that
+satisfy those interfaces (classes with `implements` recommended).
+
+### Export shape (host module)
+
+```ts
+// media-providers/index.ts  — host-only (may use ws, https, process.env, …)
+import {
+  defineMediaProviders,
+  type MediaConnectorContext,
+  type MediaProviderShared,
+  type ScriptAsrConnector,
+  type ScriptTtsConnector,
+} from '@voctiv/agent-sdk';
+import { Subject } from 'rxjs';
+import { Readable } from 'stream';
+
+class MyAsr implements ScriptAsrConnector { /* … */ }
+class MyTts implements ScriptTtsConnector { /* … */ }
+
+export const mediaProviders = defineMediaProviders({
+  // Optional: one object per dialog, shared by ASR + TTS factories
+  createShared: (ctx) => ({
+    dialogUuid: ctx.dialogUuid,
+    dispose() { /* release app state */ },
+  }),
+  asr: {
+    'my-asr': (ctx, shared) => new MyAsr(ctx, shared),
+  },
+  tts: {
+    'my-tts': (ctx, shared) => new MyTts(ctx, shared),
+  },
+});
+```
+
+```ts
+// index.ts  — sandboxed entry (do NOT import ./media-providers or ws)
+import { defineScript } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel }) => {
+  // Credentials: pass via createAsr/createTts `data` (or platform/channel params).
+  // Do not rely on process.env here — `process` is not defined in the script VM.
+  const asr = await channel.createAsr({
+    vendor: 'my-asr',
+    language: 'ru-RU',
+    data: { api_key: String(channel.params.api_key ?? '') },
+  });
+  const tts = await channel.createTts({
+    vendor: 'my-tts',
+    data: {
+      api_key: String(channel.params.api_key ?? ''),
+      voice_id: '…',
+      output_format: 'pcm_16000', // preferred for telephony
+    },
+  });
+
+  await tts.say('Hello from a custom connector.', {
+    alias: 'greet',
+    ttsStrategy: 'streaming', // used when supportsStreaming() === true
+  });
+
+  tts.say$('One. Two.', { alias: 'reply' }).subscribe((_ev) => {
+    // queued | speaking | done | cancelled — same events as builtin TTS
+  });
+
+  await channel.audio.say('Again', { tts }); // warm handle reuse
+
+  asr.destroy();
+  tts.destroy();
+});
+```
+
+Host-side factories **may** read `process.env` (e.g. `ELEVENLABS_API_KEY`) because they run
+outside the VM. Prefer also accepting the same keys via `ctx.config` from `data`.
+
+### Implement ASR (`ScriptAsrConnector`)
+
+The host pushes **PCM S16LE mono 16 kHz** frames into `send()`. Emit partials on
+`transcription$` and finals on both `transcription$` (`isFinal: true`) and `result$`.
+
+| Member | Role |
+| --- | --- |
+| `transcription$` | `{ text, isFinal }` partials and finals |
+| `result$` | Final utterance strings (drives `AsrHandle.result$`) |
+| `error$` | Vendor / transport failures |
+| `send(audio)` | Accept inbound PCM (`ArrayBuffer` / `Buffer`) |
+| `speech(active)` | Optional VAD gate from the host (`true` = utterance open) |
+| `finalize()` | End-of-utterance nudge (flush / commit) |
+| `isOpen()` | Whether the vendor socket is ready |
+| `close()` | Tear down; complete Subjects |
+
+```ts
+class MyAsr implements ScriptAsrConnector {
+  readonly transcription$ = new Subject<{ text: string; isFinal: boolean }>();
+  readonly result$ = new Subject<string>();
+  readonly error$ = new Subject<{ message: string; code?: number }>();
+
+  constructor(
+    private readonly ctx: MediaConnectorContext,
+    private readonly shared: MediaProviderShared | undefined,
+  ) {
+    // ctx.config — flattened createAsr data + channel asrConfig
+    // ctx.dialogUuid, ctx.role, ctx.debug$
+  }
+
+  isOpen() { return true; }
+  send(audio: ArrayBufferLike) { /* forward PCM to vendor */ }
+  speech(_active: boolean) {}
+  finalize() {
+    const text = '…';
+    this.transcription$.next({ text, isFinal: true });
+    this.result$.next(text);
+  }
+  close() {
+    this.transcription$.complete();
+    this.result$.complete();
+    this.error$.complete();
+  }
+}
+```
+
+Factory `throw` during create → host degraded ASR handle (same as builtin). Prefer connecting
+lazily in `send()`; the host does not call a separate `connect()` on custom connectors.
+
+### Implement TTS (`ScriptTtsConnector`)
+
+**One class per vendor** covers batch HTTP and optional streaming WebSocket. Do **not**
+register a separate streaming map.
+
+| Member | Role |
+| --- | --- |
+| `supportsStreaming()` | `true` → host may use WS path for `ttsStrategy: 'streaming'` |
+| `textToSpeechStream(text, ctx?)` | Batch/HTTP synthesis → `Readable` of audio bytes |
+| `audio$` / `done$` | Streaming audio chunks and end-of-generation |
+| `open` / `startGeneration` / `sendText` / `flush` | Streaming lifecycle |
+| `sendSeparatorFlush?()` | Optional sentence separator flush |
+| `close()` | Soft-close sockets for **reuse** (do not complete Subjects if `open()` may run again) |
+
+```ts
+class MyTts implements ScriptTtsConnector {
+  readonly audio$ = new Subject<Buffer>();
+  readonly done$ = new Subject<void>();
+
+  supportsStreaming() {
+    return true; // or false for HTTP-only
+  }
+
+  async textToSpeechStream(
+    rawtext: string,
+    _ctx?: { previousText?: string; nextText?: string },
+  ) {
+    // Return PCM (preferred) or MP3/OGG. Hint format via createTts data:
+    // output_format: 'pcm_16000' | 'mp3_…'  or  audioFormat: 'pcm' | 'mp3'
+    return Readable.from([/* bytes */]);
+  }
+
+  async open() { /* open long-lived WS */ }
+  async startGeneration() { /* BOS / new utterance */ }
+  sendText(chunk: string) { /* stream tokens */ }
+  flush() { /* EOS; later emit done$ */ }
+  close() { /* close WS; keep Subjects alive for fingerprint reuse */ }
+}
+```
+
+- `supportsStreaming() === false` → streaming strategy falls back to sentence/full HTTP path.
+- Default audio assumption for custom vendors is **PCM** unless `output_format` / `audioFormat`
+  indicates a compressed format (`mp3`, `ogg`, …).
+
+### Using custom vendors in the script
+
+```ts
+const asr = await channel.createAsr({ vendor: 'my-asr', data: { /* … */ } });
+const tts = await channel.createTts({ vendor: 'my-tts', data: { /* … */ } });
+
+await tts.say('Hi', { alias: 'greet' });
+await tts.presay('Warm cache');
+tts.say$('Next', { alias: 'reply', ttsStrategy: 'streaming' }).subscribe(/* … */);
+
+await channel.audio.say('Reuse', { tts }); // same warm session
+```
+
+Vendor keys must be **multi-character** names. Builtin single-letter codes
+(`A`, `D`, `E`, `ES`, `G`, `V`, `W`, `W2`, …) **cannot** be overridden.
+
+### Warm reuse vs `createShared` vs PCM cache
+
+| Layer | What it caches | Scope |
+| --- | --- | --- |
+| Factory + session registries | One connector instance per `dialog + vendor + config fingerprint` (TCP/WS) | Host automatic |
+| `createShared` | Your app/vendor state shared by ASR↔TTS factories | One object per dialog |
+| `PlayOptions.cache` / `presay` | Synthesized PCM files | Host TTS file cache |
+
+Call `createAsr` / `createTts` early to warm sockets. Repeated `say` with the same handle (or
+matching fingerprint) must **not** open a new TCP/WS per utterance.
+
+The host also loads the same `mediaProviders` module into the **pipeline worker** process
+(separate `require`) when `PIPELINE_WORKERS` is enabled — keep the module side-effect free
+aside from exporting factories.
+
+### Security
+
+- Host `require` of `mediaProviders` runs with API privileges — **trusted packages only**.
+- Keep connector/`ws` code out of the sandboxed entry so the VM never evaluates it.
+- The script VM does **not** expose `process` (no `process.env` in `defineScript`).
+- Entry / provider paths are restricted to the script root (path traversal denied).
+- Optional host allowlists may further restrict which packages may export providers.
+
+
+
 ## TTS Credentials And Vendor Parameters
 
+
+
 ### Direct TTS Vendor Parameters
 
 Pass vendor-native credentials and settings directly through `PlayOptions.ttsConfig`. These values are forwarded to the TTS connector as-is and override any defaults or platform-resolved credentials.
@@ -795,10 +1103,12 @@ await channel.audio.say('Hello!', {
 
 Each TTS vendor connector accepts its native parameter names:
 
-| Vendor | Accepted `ttsConfig` keys |
-| --- | --- |
+
+| Vendor         | Accepted `ttsConfig` keys                                                                                                                                                                                                     |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **ElevenLabs** | `api_key` (or `xi_api_key`), `voice_id`, `model_id` (or `model`), `base_url`, `output_format`, `language_code`, `voice_settings_stability`, `voice_settings_similarity_boost`, `voice_settings_style`, `voice_settings_speed` |
-| **Voctiv** | `url`, `voice_id`, `language`, `emotion`, `speaking_rate`, `chunk_schedule` |
+| **Voctiv**     | `url`, `voice_id`, `language`, `emotion`, `speaking_rate`, `chunk_schedule`                                                                                                                                                   |
+
 
 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.
 
@@ -821,8 +1131,8 @@ When both `name` (platform key) and explicit `ttsConfig` values are provided, `t
 
 `cache` enables TTS result caching for `say()` and `presay()`:
 
-- **`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.
+- `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):
@@ -872,6 +1182,8 @@ try {
 }
 ```
 
+
+
 ### ASR Errors — `error$` Observable
 
 Runtime ASR errors (gRPC disconnect, auth failure, quota exceeded) are emitted on `AsrHandle.error$`:
@@ -911,20 +1223,22 @@ channel.events.error$.subscribe((err) => {
 
 `MediaError` fields:
 
-| Field | Type | Description |
-| --- | --- | --- |
-| `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`, `createTts`, `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 \| 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. |
+
+| Field         | Type                                                                   | Description                                                                        |
+| ------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `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`, `createTts`, `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 | 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.
 
@@ -932,14 +1246,16 @@ Subscribing to `error$` is optional. Old scripts that do not subscribe are not a
 
 `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)). |
+
+| 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(() => {
@@ -964,12 +1280,14 @@ create ASR or want one subscription for the whole channel).
 
 `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. |
+
+| 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`.
@@ -1023,9 +1341,11 @@ chat.send('And my last payment date?');
 chat.disconnect();
 ```
 
+
+
 ## Script Return Value
 
-Scripts may return `void` or a **`ScriptResult`**:
+Scripts may return `void` or a `ScriptResult`:
 
 ```ts
 return {
@@ -1033,33 +1353,35 @@ return {
 };
 ```
 
-- **`output`** — stored in dialog stats / host persistence. This is **not** the LE `dialog.result` lifecycle column — that is `platform.dialog.result` (see [Dialog State](#dialog-state)).
-- **`error`** — optional; usually auto-populated on crash, but scripts may set it explicitly.
+- `output` — stored in dialog stats / host persistence. This is **not** the LE `dialog.result` lifecycle column — that is `platform.dialog.result` (see [Dialog State](#dialog-state)).
+- `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`**.
+after completion into `PersistedScriptResult.env`.
 
 ## Script Lifecycle (`getScriptPhase`)
 
-The host always runs your single **`defineScript` export** — there is no separate runtime entry per
-name (unlike logic-executor Python `run_unit(entry_point=...)`). Use **`getScriptPhase(context)`**
+The host always runs your single `defineScript` **export** — there is no separate runtime entry per
+name (unlike logic-executor Python `run_unit(entry_point=...)`). Use `getScriptPhase(context)`
 to tell *why* the script is running now: live call, pre-call queue, post-call continuation,
 messaging, etc.
 
-**`context.headless === true` only means “no live SIP/media”.** It does **not** tell you whether
+`context.headless === true` **only means “no live SIP/media”.** It does **not** tell you whether
 the run is before or after a call. For that, use `getScriptPhase`.
 
 The return value is the `ScriptPhase` union — one of the phases in the table below.
 
-| Phase | `context.headless` | When | Typical `context.entryPoint` |
-|-------|-------------------|------|--------------------------------|
-| `before_call` | `true` | Dialog queue / bulk outbound **before** the first platform call (often schedules `platform.call`) | empty, `main`, `default` |
-| `online` | `false` | Live SIP session (inbound, outbound, **and automatic recall redials**) | any (ignored for phase) |
-| `after_call_success` | `true` | Headless run **after** a successful call | `on_success_call`, `after_call_success`, `on_done_call` |
-| `after_call_failed` | `true` | Headless run **after** failed attempts (when `onFailedCall` was configured) | `on_failed_call`, `after_call_failed` |
-| `messaging` | `true` | Inbound message triggered the run | `on_message_api_received`, or `context.inboundMessage` set |
-| `recall` | `true` | Headless recall leg (legacy `entry_point`) | `on_recall`, `recall` |
-| `headless_other` | `true` | Any other headless run with a custom `entry_point` | your custom name |
+
+| Phase                | `context.headless` | When                                                                                              | Typical `context.entryPoint`                               |
+| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `before_call`        | `true`             | Dialog queue / bulk outbound **before** the first platform call (often schedules `platform.call`) | empty, `main`, `default`                                   |
+| `online`             | `false`            | Live SIP session (inbound, outbound, **and automatic recall redials**)                            | any (ignored for phase)                                    |
+| `after_call_success` | `true`             | Headless run **after** a successful call                                                          | `on_success_call`, `after_call_success`, `on_done_call`    |
+| `after_call_failed`  | `true`             | Headless run **after** failed attempts (when `onFailedCall` was configured)                       | `on_failed_call`, `after_call_failed`                      |
+| `messaging`          | `true`             | Inbound message triggered the run                                                                 | `on_message_api_received`, or `context.inboundMessage` set |
+| `recall`             | `true`             | Headless recall leg (legacy `entry_point`)                                                        | `on_recall`, `recall`                                      |
+| `headless_other`     | `true`             | Any other headless run with a custom `entry_point`                                                | your custom name                                           |
+
 
 **Automatic recall** (`recallCount` + `recallDelay`) creates new **online** SIP legs with an
 incremented `context.attempt`. Branch with `(context.attempt ?? 0) > 0`, **not** `phase === 'recall'`.
@@ -1113,6 +1435,8 @@ export default defineScript(async ({ channel, context, logger, platform }) => {
 });
 ```
 
+
+
 ## Platform API
 
 `platform` exposes platform operations.
@@ -1138,28 +1462,32 @@ Platform APIs (`platform.nlu`, `platform.call`, dialog writes, messaging, phrase
 
 #### What `platform.dialog.result` is
 
-`platform.dialog.result` maps to the PostgreSQL column **`dialog.result`**: the **lifecycle status** of the dialog entity in the CMS / offline queue (in queue, in progress, closed). It is **not** the outcome of a SIP leg.
+`platform.dialog.result` maps to the PostgreSQL column `dialog.result`: the **lifecycle status** of the dialog entity in the CMS / offline queue (in queue, in progress, closed). It is **not** the outcome of a SIP leg.
+
+
+| Value     | Meaning                                                                          |
+| --------- | -------------------------------------------------------------------------------- |
+| `null`    | Often after-call continuation: dialog re-enters queue-api, then becomes `queued` |
+| `queued`  | In the offline queue, not yet claimed                                            |
+| `pending` | In progress (live SIP/WS or claimed queue row)                                   |
+| `done`    | Dialog closed successfully (terminal for the pipeline)                           |
+| `error`   | Dialog closed with a logic/runtime error                                         |
 
-| Value | Meaning |
-| --- | --- |
-| `null` | Often after-call continuation: dialog re-enters queue-api, then becomes `queued` |
-| `queued` | In the offline queue, not yet claimed |
-| `pending` | In progress (live SIP/WS or claimed queue row) |
-| `done` | Dialog closed successfully (terminal for the pipeline) |
-| `error` | Dialog closed with a logic/runtime error |
 
 The **host** also moves these statuses (live session → `pending`; shutdown without continuation → often `done` / `error`; automatic recall → `pending`; after-call chain → `null` + `entry_point` in params). Scripts set `platform.dialog.result` when they want to **explicitly** fix the LE dialog status (commonly `'done'` in a headless after-call handler). That does **not** replace `channel.sip.hangup()`.
 
 #### Do not confuse
 
-| API | Layer | Does | Does not |
-| --- | --- | --- | --- |
-| `platform.dialog.result` | LE `dialog` row | Lifecycle status (`done`, `pending`, …) | Hang up SIP; equal `call.result`; equal `ScriptResult.output` |
-| `platform.dialog.entryPoint` | LE `dialog.params` | Persist routing hint for later headless/queue runs | Change SIP state; select another script export |
-| `context.entryPoint` | `ScriptDialogContext` | **Snapshot** of `entry_point` at script start (`getScriptPhase`) | Persist if you assign it — write via `platform.dialog.entryPoint` |
-| `return { output }` / `ScriptResult` | Script return | dialog_stats / host dump | LE `dialog.result` column |
-| `channel.sip.hangup()` / `terminated$` | Media leg | End or observe SIP/WS media | Set `platform.dialog.result` by itself |
-| `call.result` (LE call row) | Per-call | SIP terminal code/phrase for CMS logs | Same as `dialog.result` |
+
+| API                                    | Layer                 | Does                                                             | Does not                                                          |
+| -------------------------------------- | --------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `platform.dialog.result`               | LE `dialog` row       | Lifecycle status (`done`, `pending`, …)                          | Hang up SIP; equal `call.result`; equal `ScriptResult.output`     |
+| `platform.dialog.entryPoint`           | LE `dialog.params`    | Persist routing hint for later headless/queue runs               | Change SIP state; select another script export                    |
+| `context.entryPoint`                   | `ScriptDialogContext` | **Snapshot** of `entry_point` at script start (`getScriptPhase`) | Persist if you assign it — write via `platform.dialog.entryPoint` |
+| `return { output }` / `ScriptResult`   | Script return         | dialog_stats / host dump                                         | LE `dialog.result` column                                         |
+| `channel.sip.hangup()` / `terminated$` | Media leg             | End or observe SIP/WS media                                      | Set `platform.dialog.result` by itself                            |
+| `call.result` (LE call row)            | Per-call              | SIP terminal code/phrase for CMS logs                            | Same as `dialog.result`                                           |
+
 
 There is no `context.result` field — read/write dialog lifecycle only through `platform.dialog.result`.
 
@@ -1204,7 +1532,7 @@ await platform.call('+12025551234', {
 });
 ```
 
-When the scheduled call connects, the host runs your **`defineScript` export** again. Branch inside that handler if needed (there is no separate runtime entry per name, unlike logic-executor Python `run_unit(entry_point=...)`).
+When the scheduled call connects, the host runs your `defineScript` **export** again. Branch inside that handler if needed (there is no separate runtime entry per name, unlike logic-executor Python `run_unit(entry_point=...)`).
 
 Use `dateEnd` to define the latest time when the call is still useful. If the platform cannot place the call before that deadline, it can skip the attempt.
 
@@ -1234,21 +1562,23 @@ After a failed **outbound** call the platform must choose **one** failure-handli
 `recallCount` + `recallDelay` and `onFailedCall` answer the same question in different ways, so
 they are **mutually exclusive** on `platform.call()` (logic-executor `nn.call` parity).
 
-| Strategy | `platform.call()` options | What happens on failure | Next script run |
-|----------|---------------------------|-------------------------|-----------------|
-| **Automatic recall** | `recallCount` + `recallDelay` (both required on the `call` row) | Host schedules another outbound `call` after `recallDelay`; bumps `dialog.params.attempt` | **Online** SIP leg — same `defineScript`, branch on `context.attempt` |
-| **After-call continuation** | `onFailedCall` (and optionally `onSuccessCall`) | Host sets `dialog.params.entry_point` to the handler name and re-queues the dialog | **Headless** run — `getScriptPhase(context)` → `after_call_failed` |
+
+| Strategy                    | `platform.call()` options                                       | What happens on failure                                                                   | Next script run                                                       |
+| --------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| **Automatic recall**        | `recallCount` + `recallDelay` (both required on the `call` row) | Host schedules another outbound `call` after `recallDelay`; bumps `dialog.params.attempt` | **Online** SIP leg — same `defineScript`, branch on `context.attempt` |
+| **After-call continuation** | `onFailedCall` (and optionally `onSuccessCall`)                 | Host sets `dialog.params.entry_point` to the handler name and re-queues the dialog        | **Headless** run — `getScriptPhase(context)` → `after_call_failed`    |
+
 
 **Why not both?** Recall is fully platform-driven (dialer redials without running your script between
 attempts). `onFailedCall` is script-driven (your handler decides logging, CRM, manual retry, etc.).
-If both were written to `call.params`, shutdown would be ambiguous. This host therefore **keeps
-`onFailedCall` and drops recall** at schedule time so the outbound still starts and the after-call
+If both were written to `call.params`, shutdown would be ambiguous. This host therefore **keeps**
+`onFailedCall` **and drops recall** at schedule time so the outbound still starts and the after-call
 branch runs on failure. (If both somehow land on an existing `call.params` row, recall still wins
 at shutdown — avoid writing both.)
 
 **Do not** pass `onFailedCall` together with `recallCount` and `recallDelay` in the same
 `platform.call()` invocation. If both are present (script options, dialog params, or CMS
-defaults), the host **keeps `onFailedCall` and drops recall** so the call still schedules —
+defaults), the host **keeps** `onFailedCall` **and drops recall** so the call still schedules —
 after-call continuation wins over automatic redial. Prefer configuring only one strategy
 explicitly.
 
@@ -1284,7 +1614,7 @@ export default defineScript(async ({ channel, context, logger }) => {
 See [examples/recall-routing-by-attempt.ts](./examples/recall-routing-by-attempt.ts).
 
 When you omit recall options, the host fills them from `context.recallCount` / `context.recallDelay`
-(effective values for the current dialog) **only when `onFailedCall` is not configured** for that
+(effective values for the current dialog) **only when** `onFailedCall` **is not configured** for that
 scheduled call. Those values fall back to CMS agent contact-rules
 (`context.agent?.recallCount` / `context.agent?.recallDelay`, legacy `nn.get_recall_count()` /
 `nn.get_recall_delay()`). See [Failed outbound: automatic recall vs after-call continuation](#failed-outbound-automatic-recall-vs-after-call-continuation).
@@ -1298,6 +1628,8 @@ Other scheduling options:
 - `entryPoint` (optional): stored as `entry_point` in call params for LE DB compatibility. The host still runs the same `defineScript` export; use `context.entryPoint` only if **you** branch on it inside the handler.
 - `protoAdditional`: extra protocol-level parameters, such as SIP headers expected by your telephony setup.
 
+
+
 ### Messaging
 
 ```ts
@@ -1315,9 +1647,9 @@ await platform.messaging.send({
 Offline, or headless, sessions run a script without a live SIP call, WebSocket audio stream, RTP pipeline, ASR, or TTS playback. They are used for platform-driven background logic, queued dialog processing, and messaging events.
 
 The script entry point is still the same `defineScript()` handler. Detect offline mode with
-`context.headless`, then use **`getScriptPhase(context)`** to distinguish pre-call queue runs
+`context.headless`, then use `getScriptPhase(context)` to distinguish pre-call queue runs
 (`before_call`) from post-call continuations (`after_call_success` / `after_call_failed`). See
-[Script Lifecycle (`getScriptPhase`)](#script-lifecycle-getscriptphase).
+[Script Lifecycle (](#script-lifecycle-getscriptphase)`getScriptPhase`[)](#script-lifecycle-getscriptphase).
 
 ```ts
 import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
@@ -1460,6 +1792,8 @@ export default defineScript(async ({ channel, context, platform }) => {
 });
 ```
 
+
+
 ## Dialog Context And Persisted Env
 
 `context` includes identity, telephony fields, params, routing metadata, and runtime helpers.
@@ -1479,14 +1813,18 @@ const counter = await context.agent?.env?.<number>('visitCount');
 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 | Read in script; pass explicitly to `platform.call()` when using **automatic recall** |
+
+| 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              | Read in script; pass explicitly to `platform.call()` when using **automatic recall**    |
+
 
 Precedence for effective values: **dialog/call params** (`recall_count`, `recall_delay`) **>** agent CMS defaults.
 
@@ -1592,7 +1930,7 @@ Headless channels are for offline, queue, or messaging sessions:
 
 - Audio methods are no-ops that log warnings.
 - SIP methods are no-ops, except `makeCall()` and `bridge()`, which throw: there is no real leg to
-  create, and a silent no-op would hide the mistake.
+create, and a silent no-op would hide the mistake.
 - `createAsr()` returns an inert handle whose observables complete immediately.
 - `createTts()` returns an inert handle (no vendor connection is opened).
 - LLM, NLU, messaging, platform calls, dialog state, and `env$` still work.
@@ -1600,7 +1938,7 @@ Headless channels are for offline, queue, or messaging sessions:
 Use `context.headless` plus `getScriptPhase(context)` when a script must behave differently without a
 real media channel or across pre-call / post-call headless runs. See
 [Offline / Headless Logic](#offline--headless-logic) and
-[Script Lifecycle (`getScriptPhase`)](#script-lifecycle-getscriptphase).
+[Script Lifecycle (](#script-lifecycle-getscriptphase)`getScriptPhase`[)](#script-lifecycle-getscriptphase).
 
 ## Text Input For Tests
 
@@ -1622,3 +1960,4 @@ The package ships as CommonJS with TypeScript declarations. Import from `@voctiv
 ```ts
 import { defineScript, type MediaChannel, type AsrHandle, type MediaError } from '@voctiv/agent-sdk';
 ```
+