npm - @voctiv/agent-sdk - Versions diffs - 0.3.1 → 0.3.2 - Mend

@voctiv/agent-sdk 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +346 -209
package/dist/types/media-providers.d.ts +4 -0
package/dist/types/media-providers.d.ts.map +1 -1
package/dist/types/media-providers.js +4 -0
package/dist/types/media-providers.js.map +1 -1
package/examples/README.md +2 -1
package/examples/custom-media-providers-script.ts +47 -0
package/examples/custom-media-providers.ts +15 -31
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -70,18 +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 |
-| [custom-media-providers.ts](./examples/custom-media-providers.ts) | `defineMediaProviders` + custom ASR/TTS via `createAsr` / `createTts` |
 ### Quick recall example
@@ -113,19 +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 (trusted packages only). See [Custom ASR / TTS Providers](#custom-asr--tts-providers).
+`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:
@@ -146,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$`.
@@ -157,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.
@@ -234,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:
@@ -260,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
@@ -276,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;
@@ -309,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$`.
@@ -340,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
@@ -523,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({
@@ -551,7 +580,7 @@ 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`.
@@ -615,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.
@@ -661,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
@@ -708,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) |
-Top-level helpers on **`channel.audio`**:
+| 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) |
-- **`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.
+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);
@@ -765,34 +800,85 @@ 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 next to `defineScript`. The host
-`require`s a static **`export const mediaProviders`** **outside** the script sandbox (same
-process privileges as the API). Use this only for packages you trust.
+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.
-### Export shape
+### 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 {
-  defineScript,
   defineMediaProviders,
   type MediaConnectorContext,
   type MediaProviderShared,
@@ -802,6 +888,9 @@ import {
 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) => ({
@@ -815,17 +904,24 @@ export const mediaProviders = defineMediaProviders({
     '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: process.env.MY_ASR_KEY! },
+    data: { api_key: String(channel.params.api_key ?? '') },
   });
   const tts = await channel.createTts({
     vendor: 'my-tts',
     data: {
-      api_key: process.env.MY_TTS_KEY!,
+      api_key: String(channel.params.api_key ?? ''),
       voice_id: '…',
       output_format: 'pcm_16000', // preferred for telephony
     },
@@ -836,22 +932,19 @@ export default defineScript(async ({ channel }) => {
     ttsStrategy: 'streaming', // used when supportsStreaming() === true
   });
-  tts.say$('One. Two.', { alias: 'reply' }).subscribe((ev) => {
+  tts.say$('One. Two.', { alias: 'reply' }).subscribe((_ev) => {
     // queued | speaking | done | cancelled — same events as builtin TTS
   });
-  // Reuse the warm handle:
-  await channel.audio.say('Again', { tts });
+  await channel.audio.say('Again', { tts }); // warm handle reuse
   asr.destroy();
   tts.destroy();
 });
 ```
-`defineMediaProviders` is an identity helper for typing. The host looks up
-`module.exports.mediaProviders` (or `default.mediaProviders`) on the script entry file.
-Full stub: [`examples/custom-media-providers.ts`](./examples/custom-media-providers.ts).
+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`)
@@ -925,7 +1018,10 @@ class MyTts implements ScriptTtsConnector {
     return true; // or false for HTTP-only
   }
-  async textToSpeechStream(rawtext: string, _ctx?: { previousText?: string; nextText?: string }) {
+  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 */]);
@@ -946,12 +1042,12 @@ class MyTts implements ScriptTtsConnector {
 ### 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: { … } });
+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(…);
+tts.say$('Next', { alias: 'reply', ttsStrategy: 'streaming' }).subscribe(/* … */);
 await channel.audio.say('Reuse', { tts }); // same warm session
 ```
@@ -970,14 +1066,24 @@ Vendor keys must be **multi-character** names. Builtin single-letter codes
 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**.
-- Entry path is restricted to the script root (path traversal denied).
+- 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.
@@ -997,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.
@@ -1023,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):
@@ -1074,6 +1182,8 @@ try {
 }
 ```
 ### ASR Errors — `error$` Observable
 Runtime ASR errors (gRPC disconnect, auth failure, quota exceeded) are emitted on `AsrHandle.error$`:
@@ -1113,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.
@@ -1134,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(() => {
@@ -1166,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`.
@@ -1225,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 {
@@ -1235,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'`.
@@ -1315,6 +1435,8 @@ export default defineScript(async ({ channel, context, logger, platform }) => {
 });
 ```
 ## Platform API
 `platform` exposes platform operations.
@@ -1340,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`.
@@ -1406,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.
@@ -1436,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.
@@ -1486,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).
@@ -1500,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
@@ -1517,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';
@@ -1662,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.
@@ -1681,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.
@@ -1794,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.
@@ -1802,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
@@ -1824,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';
 ```

package/dist/types/media-providers.d.ts CHANGED Viewed

@@ -68,8 +68,12 @@ export interface MediaProvidersDefinition {
 /**
  * Mark a named export as custom media providers (identity helper).
  *
+ * Export from a sibling module (`media-providers/index.ts`), not from the
+ * sandboxed script entry. The host loads this outside the VM.
+ *
  * @example
  * ```ts
+ * // media-providers/index.ts (host-only)
  * export const mediaProviders = defineMediaProviders({
  *   createShared: (ctx) => new MySession(ctx),
  *   asr: { 'my-asr': (ctx, shared) => new MyAsr(ctx, shared) },

package/dist/types/media-providers.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"media-providers.d.ts","sourceRoot":"","sources":["../../src/types/media-providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5D,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEzC,MAAM,IAAI,OAAO,CAAC;IAClB,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,QAAQ,IAAI,IAAI,CAAC;IACjB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,IAAI,OAAO,CAAC;IAE7B,kBAAkB,CAChB,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,mBAAmB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,IAAI,IAAI,CAAC;IACd,kBAAkB,CAAC,IAAI,IAAI,CAAC;IAC5B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,qBAAqB,EAC1B,MAAM,EAAE,mBAAmB,GAAG,SAAS,KACpC,kBAAkB,CAAC;AAExB,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,qBAAqB,EAC1B,MAAM,EAAE,mBAAmB,GAAG,SAAS,KACpC,kBAAkB,CAAC;AAExB,MAAM,WAAW,wBAAwB;IACvC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;KACzB,KAAK,mBAAmB,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC1C;AAED~~;;;;;;;;;;;GAWG~~;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,wBAAwB,GAC5B,wBAAwB,CAE1B;AAED,qEAAqE;AACrE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC"}
1	+ {"version":3,"file":"media-providers.d.ts","sourceRoot":"","sources":["../../src/types/media-providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5D,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEzC,MAAM,IAAI,OAAO,CAAC;IAClB,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,QAAQ,IAAI,IAAI,CAAC;IACjB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,IAAI,OAAO,CAAC;IAE7B,kBAAkB,CAChB,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,mBAAmB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,IAAI,IAAI,CAAC;IACd,kBAAkB,CAAC,IAAI,IAAI,CAAC;IAC5B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,qBAAqB,EAC1B,MAAM,EAAE,mBAAmB,GAAG,SAAS,KACpC,kBAAkB,CAAC;AAExB,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,qBAAqB,EAC1B,MAAM,EAAE,mBAAmB,GAAG,SAAS,KACpC,kBAAkB,CAAC;AAExB,MAAM,WAAW,wBAAwB;IACvC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;KACzB,KAAK,mBAAmB,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,wBAAwB,GAC5B,wBAAwB,CAE1B;AAED,qEAAqE;AACrE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC"}

package/dist/types/media-providers.js CHANGED Viewed

@@ -4,8 +4,12 @@ exports.defineMediaProviders = defineMediaProviders;
 /**
  * Mark a named export as custom media providers (identity helper).
  *
+ * Export from a sibling module (`media-providers/index.ts`), not from the
+ * sandboxed script entry. The host loads this outside the VM.
+ *
  * @example
  * ```ts
+ * // media-providers/index.ts (host-only)
  * export const mediaProviders = defineMediaProviders({
  *   createShared: (ctx) => new MySession(ctx),
  *   asr: { 'my-asr': (ctx, shared) => new MyAsr(ctx, shared) },

package/dist/types/media-providers.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"media-providers.js","sourceRoot":"","sources":["../../src/types/media-providers.ts"],"names":[],"mappings":";;~~AAmGA~~,oDAIC;~~AAhBD;;;;;;;;;;;GAWG~~;AACH,SAAgB,oBAAoB,CAClC,GAA6B;IAE7B,OAAO,GAAG,CAAC;AACb,CAAC"}
1	+ {"version":3,"file":"media-providers.js","sourceRoot":"","sources":["../../src/types/media-providers.ts"],"names":[],"mappings":";;AAuGA,oDAIC;AApBD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,oBAAoB,CAClC,GAA6B;IAE7B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/examples/README.md CHANGED Viewed

@@ -11,7 +11,8 @@ Each file exports one `defineScript` handler. The host **always** invokes that s
 | [schedule-call-with-defaults.ts](./schedule-call-with-defaults.ts) | `platform.call()` using CMS defaults from `context` |
 | [after-call-continuation.ts](./after-call-continuation.ts) | `onSuccessCall` / `onFailedCall` + `getScriptPhase()` |
 | [read-recall-from-params.ts](./read-recall-from-params.ts) | `parseRecallDelaySeconds()` / `parseRecallCount()` |
-| [custom-media-providers.ts](./custom-media-providers.ts) | `defineMediaProviders` + `createAsr` / `createTts` / `say$` |
+| [custom-media-providers.ts](./custom-media-providers.ts) | Host-only `mediaProviders` (`implements ScriptAsrConnector` / `ScriptTtsConnector`) |
+| [custom-media-providers-script.ts](./custom-media-providers-script.ts) | Sandboxed `defineScript` using custom vendors (no `ws` / no `process.env`) |
 ## Recall flow

package/examples/custom-media-providers-script.ts ADDED Viewed

@@ -0,0 +1,47 @@
+/**
+ * Sandboxed script entry that uses custom mediaProviders vendors.
+ *
+ * Pair with `custom-media-providers.ts` deployed as `dist/media-providers/index.js`.
+ * This file must stay free of `ws` / connector imports — the script VM has no `process`.
+ */
+import { defineScript } from '@voctiv/agent-sdk';
+export default defineScript(async ({ channel, logger }) => {
+  channel.sip.answer();
+  // Pass credentials via `data` (or channel/platform params). Do not use process.env
+  // in the sandboxed entry — `process` is not defined in the script VM.
+  // Host-side factories in media-providers/ may still read process.env.
+  const apiKey = String(
+    (channel.params as Record<string, unknown>).api_key ?? '',
+  );
+  const asr = await channel.createAsr({
+    vendor: 'my-asr',
+    language: 'ru-RU',
+    data: { api_key: apiKey },
+  });
+  const tts = await channel.createTts({
+    vendor: 'my-tts',
+    data: {
+      api_key: apiKey,
+      voice_id: '…',
+      output_format: 'pcm_16000',
+    },
+  });
+  await tts.say('Hello from a custom TTS connector.', { alias: 'greet' });
+  tts.say$('One. Two.', { alias: 'reply', ttsStrategy: 'streaming' }).subscribe({
+    next: (ev) => {
+      logger.log('tts utterance', { state: ev.state, alias: ev.itemAlias });
+    },
+    error: (err) => logger.error('tts failed', err),
+  });
+  await channel.audio.say('Reuse handle', { tts });
+  asr.destroy();
+  tts.destroy();
+  channel.sip.hangup();
+});

package/examples/custom-media-providers.ts CHANGED Viewed

@@ -1,22 +1,25 @@
 /**
- * Custom ASR / TTS from a trusted logic package.
+ * Host-only custom ASR / TTS module.
  *
- * Export `mediaProviders` next to `defineScript`. The host loads that export
- * outside the sandbox and wires vendors into `createAsr` / `createTts` with the
- * same warm TCP/WS reuse as built-in engines.
+ * Ship as `dist/media-providers/index.js` next to the sandboxed script entry.
+ * The host `require`s this file outside the script VM (full Node: `ws`, `process`, …).
+ *
+ * Do **not** re-export `mediaProviders` from `dist/index.js` — the sandbox has no
+ * `process`, so loading `ws` there fails. Keep `defineScript` in a separate file
+ * (see `custom-media-providers-script.ts`).
  *
  * Batch and streaming TTS share one class (`supportsStreaming()` + streaming
- * lifecycle methods). Do not register a separate streaming map.
+ * lifecycle). Do not register a separate streaming map.
  */
 import { Readable } from 'stream';
 import { Subject } from 'rxjs';
 import {
-  defineScript,
   defineMediaProviders,
   type MediaConnectorContext,
   type MediaProviderShared,
   type ScriptAsrConnector,
   type ScriptTtsConnector,
+  type ScriptTtsSynthesisContext,
 } from '@voctiv/agent-sdk';
 type SharedSession = MediaProviderShared & {
@@ -38,7 +41,8 @@ class EchoAsr implements ScriptAsrConnector {
   }
   send(_audio: ArrayBufferLike): void {
-    // Forward PCM to your vendor here.
+    // Forward PCM (S16LE mono 16 kHz) to your vendor here.
+    void this.ctx;
   }
   speech(_active: boolean): void {}
@@ -71,7 +75,10 @@ class BatchOrStreamTts implements ScriptTtsConnector {
     return false;
   }
-  async textToSpeechStream(rawtext: string): Promise<Readable> {
+  async textToSpeechStream(
+    rawtext: string,
+    _ctx?: ScriptTtsSynthesisContext,
+  ): Promise<Readable> {
     void this.ctx;
     void this.shared;
     // Replace with HTTP keep-alive synthesis that returns a PCM stream.
@@ -103,26 +110,3 @@ export const mediaProviders = defineMediaProviders({
       new BatchOrStreamTts(ctx, shared as SharedSession),
   },
 });
-export default defineScript(async ({ channel, logger }) => {
-  channel.sip.answer();
-  const asr = await channel.createAsr({ vendor: 'my-asr' });
-  const tts = await channel.createTts({ vendor: 'my-tts' });
-  await tts.say('Hello from a custom TTS connector.');
-  tts.say$('One. Two.', { alias: 'reply' }).subscribe({
-    next: (ev) => {
-      logger.log('tts utterance', { state: ev.state, alias: ev.itemAlias });
-    },
-    error: (err) => logger.error('tts failed', err),
-  });
-  // Same warm handle via audio.say:
-  await channel.audio.say('Reuse handle', { tts });
-  asr.destroy();
-  tts.destroy();
-  channel.sip.hangup();
-});

package/package.json CHANGED Viewed

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