@voctiv/agent-sdk 0.2.7 → 0.2.9

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

@@ -1,9 +1,12 @@
-import { Observable } from 'rxjs';
-import { AsrConfig, AsrHandle } from './asr-handle';
-import { DtmfEvent, SipInfo, SipSignal, DataMessage } from './events';
-import { MixerQueueControl, PlayOptions } from './mixer';
+import type { Observable } from 'rxjs';
+import type { AsrConfig, AsrHandle } from './asr-handle';
+import type { DataMessage } from './events';
+import type { MixerQueueControl, PlayOptions, PresayOptions, PreloadOptions } from './mixer';
 import type { LegacyPhraseRecord } from './legacy-phrase';
-import { TextInput } from './text-input';
+import type { TextInput } from './text-input';
+import type { MediaError } from './errors';
+import type { ChannelLlm } from './llm';
+import type { ChannelSip } from './sip';
 /**
  * Audio playback API — TTS synthesis, file/URL playback, caching, and multi-queue mixing.
  *
@@ -44,7 +47,7 @@ export interface ChannelAudio {
      * Play audio from a URL/path string, or a {@link LegacyPhraseRecord} from the Voctiv platform phrase DB.
      *
      * The runtime decodes the full source to PCM and pushes it to the mixer. `ttsVendor`,
-     * `ttsConfig`, `ttsStrategy`, and `legacySavePhrase` do not affect raw playback.
+     * `ttsConfig`, `ttsStrategy`, and `cache` do not affect raw playback.
      *
      * @param source - HTTP(S) URL, local path, or structured {@link LegacyPhraseRecord} (no TTS).
      * @param options - Queue, alias, volume, loop; **`tts*`** fields apply only if the host
@@ -57,24 +60,28 @@ export interface ChannelAudio {
     /**
      * Download/decode **`source`** through the audio player.
      *
-     * In ScriptEngine this warms the decoder/audio-player path for `play()`;
-     * it does not synthesize TTS and does not populate the TTS cache used by `presay()`.
-     * @param source - URL or file path accepted by the host’s fetch layer.
+     * In ScriptEngine this warms the decoder/audio-player path for `play()`.
+     * In legacy mode the decoded PCM is always persisted into `record_phrase` /
+     * `record_phrase_file` (default phrase name `_cache`).
+     *
+     * @param source - URL or file path accepted by the host's fetch layer.
+     * @param options - Optional; only `cache` is used to override persist name/flag/language.
      */
-    preload(source: string): Promise<void>;
+    preload(source: string, options?: PreloadOptions): Promise<void>;
     /**
      * Run TTS ahead of time and store PCM in the host TTS cache.
      *
      * Later `say()` calls with the same resolved TTS config and text can reuse the cached
-     * file. If the cache service is unavailable, ScriptEngine logs a warning and
-     * resolves without throwing.
+     * file. In legacy mode the result is always persisted into `record_phrase`
+     * (default phrase name `_cache`).
+     *
      * @param text - Full text to synthesize.
-     * @param options - Same TTS-related options as **`say`** (vendor, **`name`**, **`ttsConfig`**).
+     * @param options - TTS vendor/name/config and optional cache name/flag override.
      */
-    presay(text: string, options?: PlayOptions): Promise<void>;
+    presay(text: string, options?: PresayOptions): Promise<void>;
     /**
      * @param index - Mixer queue **0–4**.
-     * @returns Control handle for that queue’s volume and item lifecycle observables.
+     * @returns Control handle for that queue's volume and item lifecycle observables.
      */
     queue(index: number): MixerQueueControl;
     /**
@@ -110,570 +117,28 @@ export interface ChannelEvents {
     readonly terminated$: Observable<void>;
     /** Structured messages from the WS client or bridge (event + payload). */
     readonly message$: Observable<DataMessage>;
-}
-/** Options for **`channel.llm.ask`** / **`stream`** / **`makePersistentStream`**. */
-export interface LlmOptions {
-    /** Override dialog UUID for Omni/LLM tracing (defaults to script dialog). */
-    dialogUuid?: string;
-    /** Chat role sent with the message, e.g. **`"assistant"`**, **`"user"`**. */
-    role?: string;
-    /** When `true`, message may be hidden from user-visible transcript (host-dependent). */
-    hidden?: boolean;
-    /**
-     * **LLM-only**: speaker / persona label in multi-party chat. **Not** related to
-     * {@link PlayOptions.name} (TTS **`key_storage.name`**).
-     */
-    name?: string;
-    /** Route the request to a specific Omni agent profile (UUID). */
-    agentUuid?: string;
-    /** Multi-agent: current alias for routing. */
-    currentAgentAlias?: string;
-    /** Opaque payload forwarded to the Omni LLM backend. */
-    payload?: Record<string, any>;
-    /** Verbose logging on the LLM path. */
-    debug?: boolean;
-    /** Restrict which agent aliases may handle the request. */
-    agentAliasFilter?: string[];
-}
-/** Options for **`channel.llm.extract`**. All fields except `dialogUuid` are forwarded to Omni extract. */
-export interface ExtractOptions {
-    /** Override dialog UUID for extraction context; defaults to the current script dialog. */
-    dialogUuid?: string;
-    /** Optional extraction prompt/instruction forwarded to Omni. */
-    prompt?: string;
-    /** Model name or id understood by the Omni backend. */
-    model?: string;
-    /** Nucleus sampling value forwarded to Omni. */
-    topP?: number;
-    /** Temperature forwarded to Omni. */
-    temperature?: number;
-    /** Custom model descriptor forwarded as-is. */
-    customModel?: Record<string, any>;
-    [key: string]: unknown;
-}
-/** One chunk from **`channel.llm.stream`**. */
-export interface LlmStreamChunk {
-    id: string;
-    chunkId: number;
-    content: string;
-    finishReason: string | null;
-    event: any;
-    toolMessages?: any[];
-    raw: Record<string, any>;
-}
-/**
- * Long-lived LLM Socket.IO stream — amortizes connection setup across many user turns.
- */
-export interface PersistentLlmStreamHandle {
-    readonly stream$: Observable<LlmStreamChunk>;
-    /** Send one user/assistant turn over the existing stream; options override defaults for this send only. */
-    send(message: string, options?: LlmOptions): void;
-    /** Close the underlying Socket.IO stream without destroying the handle object. */
-    disconnect(): void;
-    /** Re-open the underlying Socket.IO stream after {@link disconnect}. */
-    reconnect(): void;
-}
-/** LLM facade on the media channel. */
-export interface ChannelLlm {
-    /** Single-shot completion for **`message`**; consumes the Omni SSE stream and returns concatenated text. */
-    ask(message: string, options?: LlmOptions): Promise<string>;
-    /** Token/chunk stream for **`message`** parsed from Omni SSE `data:` events. */
-    stream(message: string, options?: LlmOptions): Observable<LlmStreamChunk>;
-    /** Structured extraction / JSON-style fill from conversation context via Omni extract. */
-    extract(options?: ExtractOptions): Promise<Record<string, any>>;
-    /**
-     * Open a persistent Omni chat stream.
-     * @param options - Default **`agentUuid`**, **`dialogUuid`**, etc.; per-**`send`** overrides allowed.
-     */
-    makePersistentStream(options?: LlmOptions): PersistentLlmStreamHandle;
-}
-/**
- * SIP call state visible to script developers.
- *
- * ### Lifecycle
- *
- * ```
- *               outbound 183 w/ SDP
- * idle ──► ringing ─────────────────► early ──► active ──► terminated
- *              │                        ▲          ▲
- *              │   inbound              │          │
- *              │   sendProgress()───────┘          │
- *              └───────────────────────────────────┘  (early may be skipped)
- * ```
- *
- * | State | Meaning | How you get here |
- * |---|---|---|
- * | **`idle`** | Call object exists but no SIP signalling has started yet. | Initial state. |
- * | **`ringing`** | INVITE sent (outbound) or received (inbound); remote party is ringing. No media yet. | Automatic after INVITE. |
- * | **`early`** | RTP pipeline is up — you can **send and receive audio**, run ASR, play TTS. This is the "pre-answer" phase before final 200 OK. | **Outbound:** remote sends 183 Session Progress with SDP. **Inbound:** your script calls `sip.sendProgress()`. |
- * | **`active`** | 200 OK received/sent — the call is fully established. | **Outbound:** remote answers. **Inbound:** your script calls `sip.answer()`. |
- * | **`holding`** | Local hold is active. | Your script calls `sip.hold()`. |
- * | **`terminated`** | Call ended (BYE, CANCEL, or error). No further audio is possible. | Either side hangs up, or network error. |
- *
- * > **Note:** not every call goes through every state. A fast answer may jump
- * > `ringing` → `active` without `early`. An unanswered outbound call may go
- * > `ringing` → `terminated`. Inbound calls stay in `ringing` until you call
- * > either `sendProgress()` (→ `early`) or `answer()` (→ `active`).
- */
-export type SipState = 'idle' | 'ringing' | 'early' | 'active' | 'holding' | 'terminated';
-/**
- * A SIP 1xx provisional response forwarded to the script.
- *
- * Provisional responses are sent by the remote party **before** the final answer (200 OK).
- * Common examples:
- *
- * | Code | Phrase | Typical meaning |
- * |------|--------|-----------------|
- * | 100 | Trying | Request received, processing |
- * | 180 | Ringing | Remote phone is ringing (may carry SDP → early media) |
- * | 183 | Session Progress | Early media available — SDP is present, RTP can flow |
- *
- * Subscribe to `sip.progress$` to track every provisional response. The `sdp` field
- * is present only when the response carries a Session Description (media offer/answer).
- */
-export interface SipProgressEvent {
-    /** SIP status code (100–199). */
-    statusCode: number;
-    /** Human-readable reason phrase, e.g. `"Ringing"`, `"Session Progress"`. */
-    statusPhrase: string;
-    /** Raw SDP body when the provisional response carries a media description. */
-    sdp?: string;
-}
-/**
- * SIP channel API — call-state observables, DTMF, INFO, hold/mute/hangup,
- * outbound **`makeCall`**, **`bridge`**, and **pre-answer media**.
- *
- * ---
- *
- * ### Pre-answer media (early media)
- *
- * Both **inbound** and **outbound** calls support full-duplex audio **before** the
- * 200 OK answer. In the `"early"` state the RTP pipeline is fully operational —
- * ASR, TTS, `audio.say()`, `audio.play()`, and DTMF all work **exactly the same**
- * as in the `"active"` state.
- *
- * #### Outbound calls
- *
- * The remote side may send **183 Session Progress** with SDP (e.g. an IVR greeting,
- * ringback tone, or DTMF challenge). The call enters `"early"` automatically.
- *
- * #### Inbound calls
- *
- * Call `sip.sendProgress()` to send **183 Session Progress** to the caller. The call
- * enters `"early"` and audio flows in both directions before final 200 OK. The API
- * does not mark the call answered until `sip.answer()`; external billing still depends
- * on carrier policy. Call `sip.answer()` later to complete the answer.
- *
- * ---
- *
- * ### Quick examples
- *
- * #### Outbound — interact with an IVR before answer
- *
- * ```ts
- * const call = await channel.sip.makeCall({ sipUri: 'sip:+1234@trunk.example.com' });
- *
- * // Wait until RTP is ready (early media or full answer)
- * await call.sip.waitForEarly();
- * // Audio flows — start ASR to listen to the remote IVR
- * const asr = await call.createAsr();
- * asr.result$.subscribe((text) => {
- *   if (/press 1/i.test(text)) call.sip.sendDtmf('1');
- * });
- *
- * // Optionally wait for the actual answer
- * await call.sip.waitForAnswer();
- * await call.audio.say('Hello! We are calling about your order.');
- * ```
- *
- * #### Inbound — collect data before the final answer
- *
- * ```ts
- * // Inbound call arrives — state is 'ringing'
- * channel.sip.sendProgress();
- * // State is now 'early' — full duplex audio before final 200 OK
- *
- * const asr = await channel.createAsr();
- * await channel.audio.say('Please say your account number.');
- * const account = await firstValueFrom(asr.result$);
- *
- * // Now send final answer
- * channel.sip.answer();
- * await channel.audio.say(`Thank you! Looking up account ${account}…`);
- * ```
- *
- * #### Inbound — simple answer (no pre-answer)
- *
- * ```ts
- * // Inbound call — answer immediately
- * channel.sip.answer();
- * await channel.audio.say('Welcome!');
- * ```
- *
- * #### Audio auto-buffering
- *
- * You do **not** need to manually wait for early/answer before calling `audio.say()`
- * or `audio.play()`. These methods automatically defer until the RTP pipeline is ready
- * and resolve as no-ops if the call terminates first. The explicit `waitForEarly()` /
- * `waitForAnswer()` await points are useful when you need to **sequence logic** around
- * call state (e.g. create ASR only after media is available).
- */
-export interface ChannelSip {
-    /**
-     * Emits every time the remote party sends a DTMF digit (RFC 2833 in-band or SIP INFO).
-     *
-     * ```ts
-     * sip.dtmf$.subscribe(({ digit, duration }) => {
-     *   console.log(`User pressed ${digit}`);
-     * });
-     * ```
-     */
-    readonly dtmf$: Observable<DtmfEvent>;
-    /**
-     * Raw SIP INFO messages received on this call leg.
-     *
-     * Useful for carrier-specific signalling (e.g. `application/dtmf-relay`). On the
-     * current SIP runtime this stream is low-level and may not include parsed body
-     * details for every Sofia event; prefer `dtmf$` for DTMF.
-     */
-    readonly sipInfo$: Observable<SipInfo>;
-    /**
-     * Low-level SIP state-change events from the underlying Sofia stack.
-     *
-     * Prefer the higher-level **`state$`**, **`progress$`**, **`early$`**, **`answered$`**
-     * observables unless you need raw Sofia event details.
-     */
-    readonly sipSignal$: Observable<SipSignal>;
-    /**
-     * Live observable of the current call state.
-     *
-     * Emits the new {@link SipState} every time the call transitions. Starts with the
-     * state the call was in when the script began (typically `"ringing"` for inbound,
-     * `"idle"` or `"ringing"` for outbound).
-     *
-     * ```ts
-     * sip.state$.subscribe((state) => {
-     *   console.log(`Call state → ${state}`);
-     * });
-     * ```
-     *
-     * > **Tip:** for one-shot checks use the synchronous `sip.state` getter instead.
-     */
-    readonly state$: Observable<SipState>;
-    /**
-     * Current call state at the moment of access (synchronous).
-     *
-     * Returns one of: `'idle'`, `'ringing'`, `'early'`, `'active'`, `'holding'`, `'terminated'`.
-     *
-     * ```ts
-     * if (sip.state === 'active') {
-     *   await audio.say('Call is live');
-     * }
-     * ```
-     */
-    readonly state: SipState;
-    /**
-     * Whether the call has been answered — `true` after 200 OK is received (outbound)
-     * or sent (inbound via `sip.answer()`).
-     *
-     * This is a synchronous getter. For an awaitable version use {@link waitForAnswer}.
-     *
-     * ```ts
-     * if (!sip.isAnswered) {
-     *   console.log('Still waiting for answer…');
-     * }
-     * ```
-     */
-    readonly isAnswered: boolean;
-    /**
-     * Emits every SIP 1xx provisional response (180 Ringing, 183 Session Progress, etc.).
-     *
-     * Useful for tracking ringing state, ringback-tone detection, or reading SDP from
-     * early 183 responses. Each event is a {@link SipProgressEvent} with `statusCode`,
-     * `statusPhrase`, and optionally `sdp`.
-     *
-     * ```ts
-     * sip.progress$.subscribe(({ statusCode, statusPhrase }) => {
-     *   console.log(`1xx: ${statusCode} ${statusPhrase}`);
-     * });
-     * ```
-     *
-     * > **Note:** `progress$` may emit **zero** events if the remote party answers
-     * > immediately (200 OK without any provisional).
-     */
-    readonly progress$: Observable<SipProgressEvent>;
-    /**
-     * Emits **once** when early media becomes available — the RTP pipeline is up and
-     * audio can be sent/received **before** the call is formally answered.
-     *
-     * **Outbound:** fires automatically when the remote side sends a 1xx with SDP
-     * (typically **183 Session Progress**).
-     *
-     * **Inbound:** fires after your script calls `sip.sendProgress()`.
-     *
-     * After this event fires:
-     * - `audio.say()` / `audio.play()` will be heard by the remote party
-     * - `createAsr()` will receive remote audio
-     * - `dtmf$` will deliver in-band DTMF
-     * - The API has not marked the call answered yet; carrier billing policy may vary
-     *
-     * If the call is answered without any early media (outbound: no 183 with SDP;
-     * inbound: `answer()` called directly), `early$` **may not emit at all** —
-     * use `answered$` or `waitForAnswer()` instead.
-     *
-     * ```ts
-     * sip.early$.subscribe(() => {
-     *   console.log('Early media — RTP is flowing before answer');
-     * });
-     * ```
-     */
-    readonly early$: Observable<void>;
-    /**
-     * Emits **once** when the call is answered (200 OK received for outbound,
-     * or sent for inbound after `sip.answer()`).
-     *
-     * After this event the call state is `"active"` and the call is fully established.
-     *
-     * ```ts
-     * sip.answered$.subscribe(() => {
-     *   console.log('Call answered — full duplex');
-     * });
-     * ```
-     *
-     * > For the awaitable version see {@link waitForAnswer}.
-     */
-    readonly answered$: Observable<void>;
-    /**
-     * Returns a `Promise` that resolves when the call is answered (200 OK).
-     *
-     * If the call is **already answered** at the time of calling, resolves immediately.
-     *
-     * Useful in outbound scenarios where you want to block until the remote party picks up:
-     *
-     * ```ts
-     * const call = await channel.sip.makeCall({ sipUri: destination });
-     * await call.sip.waitForAnswer();
-     * await call.audio.say('You have picked up!');
-     * ```
-     *
-     * > **Warning:** if the call is never answered (busy, timeout, rejection) and your
-     * > script does not handle `events.terminated$`, this Promise will remain pending
-     * > until the call terminates (at which point the script exits).
-     */
-    waitForAnswer(): Promise<void>;
-    /**
-     * Returns a `Promise` that resolves as soon as the RTP pipeline is ready —
-     * either on **early media** or on **answer**, whichever comes first.
-     *
-     * If the call is already in `"early"` or `"active"` state, resolves immediately.
-     *
-     * #### Outbound usage
-     *
-     * The recommended await point when you want to start ASR / play audio
-     * **as early as possible** (including pre-answer):
-     *
-     * ```ts
-     * const call = await channel.sip.makeCall({ sipUri: destination });
-     *
-     * // Don't wait for full answer — start as soon as any media path exists
-     * await call.sip.waitForEarly();
-     *
-     * // ASR is already receiving remote audio (IVR prompts, ringback, etc.)
-     * const asr = await call.createAsr();
-     * asr.result$.subscribe((text) => console.log('Heard:', text));
-     *
-     * // Play DTMF to navigate an IVR — works even before 200 OK
-     * call.sip.sendDtmf('1');
-     * ```
-     *
-     * #### Inbound usage
-     *
-     * For inbound calls you must call `sendProgress()` **first** to trigger early media,
-     * then `waitForEarly()` resolves:
-     *
-     * ```ts
-     * channel.sip.sendProgress();
-     * await channel.sip.waitForEarly(); // resolves immediately after sendProgress()
-     * const asr = await channel.createAsr();
-     * ```
-     *
-     * > **Tip:** some carriers answer outbound calls without early media (180 without SDP).
-     * > In that case `waitForEarly()` resolves only when the 200 OK arrives.
-     */
-    waitForEarly(): Promise<void>;
-    /**
-     * Send a DTMF digit to the remote party.
-     *
-     * SIP channels delegate to the telephony stack. WS channels validate one digit
-     * and emit `dtmf-send` to the connected client. Headless channels ignore it.
-     *
-     * @param digit - One of `0`–`9`, `*`, `#`.
-     * @param duration - Tone duration in milliseconds (default **250 ms**).
-     *
-     * ```ts
-     * // Navigate an IVR: press 1, wait, press 3
-     * sip.sendDtmf('1');
-     * await new Promise((r) => setTimeout(r, 2000));
-     * sip.sendDtmf('3');
-     * ```
-     */
-    sendDtmf(digit: string, duration?: number): void;
-    /**
-     * Send a SIP INFO request with an arbitrary content type and body on this call leg.
-     *
-     * No-op on WS and headless channels.
-     *
-     * @param contentType - MIME type, e.g. `"application/dtmf-relay"`.
-     * @param body - Raw text body of the INFO request.
-     */
-    sendInfo(contentType: string, body: string): void;
-    /**
-     * Put the SIP call on hold (sends re-INVITE with `a=sendonly`).
-     *
-     * The remote party hears silence (or hold music if your carrier supports it).
-     * Call {@link unhold} to resume.
-     */
-    hold(): void;
-    /**
-     * Resume a held SIP call (sends re-INVITE with `a=sendrecv`).
-     */
-    unhold(): void;
-    /**
-     * Suppress outgoing SIP audio locally — the remote party hears silence,
-     * but you still receive their audio.
-     *
-     * This does **not** send a re-INVITE; it simply stops feeding PCM
-     * to the RTP encoder. Call {@link unmute} to resume.
-     */
-    mute(): void;
-    /** Resume sending audio after {@link mute}. No-op on WS/headless channels. */
-    unmute(): void;
-    /**
-     * Hang up the call.
-     *
-     * SIP channels send BYE. WS channels disconnect the socket. Headless channels destroy
-     * the synthetic channel. After this call `events.terminated$` will emit and the session ends.
-     */
-    hangup(): void;
     /**
-     * Answer an **inbound** call (sends 200 OK with SDP).
-     *
-     * No-op if the call is already answered or if this is an outbound call. Also no-op
-     * on WS/headless channels. After answering, the state transitions to `"active"` and
-     * the API records the call answer time.
-     *
-     * If the call is in `"early"` state (after `sendProgress()`), `answer()` promotes it
-     * to `"active"` — audio was already flowing and the final answer is now sent.
+     * Unified stream of runtime media errors (ASR connector failures, TTS HTTP errors,
+     * missing API keys, etc.).
      *
-     * ```ts
-     * // Simple: answer immediately
-     * channel.sip.answer();
-     * await channel.audio.say('Hello, how can I help?');
-     * ```
+     * Subscribing is optional — unhandled errors are always logged server-side. Use this
+     * when the script needs to react (e.g. fall back to a different vendor, notify the
+     * caller, or abort the dialog).
      *
      * ```ts
-     * // Advanced: pre-answer → answer
-     * channel.sip.sendProgress();               // early media before final 200 OK
-     * await channel.audio.say('One moment…');
-     * channel.sip.answer();                      // final 200 OK
-     * await channel.audio.say('How can I help?');
-     * ```
-     */
-    answer(): void;
-    /**
-     * Send **183 Session Progress** with SDP on an **inbound** call, enabling
-     * early media (full-duplex audio) **before** the 200 OK answer.
-     *
-     * After calling `sendProgress()`:
-     * - The call state transitions to `"early"` and `early$` emits.
-     * - `audio.say()`, `audio.play()`, `createAsr()`, `dtmf$` all work —
-     *   exactly the same as in the `"active"` state.
-     * - The remote party hears your audio before the final 200 OK. The API still treats
-     *   the call as not answered; external billing depends on carrier policy.
-     *
-     * Call `sip.answer()` later to send the final 200 OK and transition to `"active"`.
-     *
-     * No-op if the call is already in `"early"` or `"active"` state, or if this is
-     * an outbound / WS / headless channel.
-     *
-     * ### Typical use case: play a greeting before answering
-     *
-     * ```ts
-     * // Inbound call arrives — state is 'ringing'
-     * channel.sip.sendProgress();
-     * // State is now 'early' — audio flows before final 200 OK
-     *
-     * await channel.audio.say('Please hold while we connect you…');
-     *
-     * // Now answer with final 200 OK
-     * channel.sip.answer();
-     * await channel.audio.say('Hello! How can I help?');
-     * ```
-     *
-     * ### Typical use case: start ASR before answering
-     *
-     * ```ts
-     * channel.sip.sendProgress();
-     * const asr = await channel.createAsr();
-     * await channel.audio.say('Hi! What is your account number?');
-     * const result = await firstValueFrom(asr.result$);
-     * // Collected account number before sending final 200 OK
-     * channel.sip.answer();
-     * ```
-     */
-    sendProgress(): void;
-    /**
-     * Initiate an **outbound** SIP call to the given SIP URI.
-     *
-     * Returns a new {@link MediaChannel} representing the B-leg. The returned channel
-     * has its own `sip`, `audio`, `events`, etc. — use `waitForAnswer()` or
-     * `waitForEarly()` on the B-leg before sending audio.
-     *
-     * Supported only by the main-thread SIP channel. Worker-isolated, WS, and headless
-     * channels throw because the current worker bridge does not proxy nested call legs.
-     *
-     * @param opts.sipUri - Full SIP URI, e.g. `"sip:+12025551234@trunk.carrier.com"`.
-     * @param opts.fromUri - Optional caller-ID override SIP URI.
-     * @returns A new `MediaChannel` for the outbound leg.
-     *
-     * ```ts
-     * const bLeg = await channel.sip.makeCall({
-     *   sipUri: 'sip:+12025551234@trunk.carrier.com',
+     * channel.events.error$.subscribe(err => {
+     *   console.log(`[${err.source}] ${err.message}`);
      * });
-     * await bLeg.sip.waitForAnswer();
-     * // Bridge both legs so callers hear each other
-     * const teardown = channel.sip.bridge(bLeg);
-     * ```
-     */
-    makeCall(opts: {
-        sipUri: string;
-        fromUri?: string;
-    }): Promise<MediaChannel>;
-    /**
-     * Cross-connect audio between this SIP call and another SIP call (conference bridge).
-     *
-     * Both parties hear each other in real time. Returns a teardown function
-     * that disconnects the bridge when called. ScriptEngine only bridges two
-     * `SipMediaChannel` instances directly; non-SIP channels return a no-op teardown
-     * or throw depending on the host.
-     *
-     * @param other - The other `MediaChannel` (e.g. an outbound B-leg).
-     * @returns A function to tear down the bridge.
-     *
-     * ```ts
-     * const teardown = channel.sip.bridge(bLeg);
-     * // ... later
-     * teardown(); // disconnect the bridge
      * ```
      */
-    bridge(other: MediaChannel): () => void;
+    readonly error$: Observable<MediaError>;
 }
 /**
  * Primary script API for real-time voice: ASR, TTS/audio, SIP, LLM, and **`params`** from the host.
  *
  * **`type`** is **`"sip"`** for telephony or **`"ws"`** for WebSocket/script-manager sessions.
  * Headless sessions currently also expose a `"ws"` typed synthetic channel; use
- * {@link import('./define-script').ScriptDialogContext.headless} to distinguish them.
+ * {@link import('./script-context').ScriptDialogContext.headless} to distinguish them.
  * In headless mode audio/SIP/text input are mostly no-ops while **`llm`** / **`platform`**
  * still work.
  */
@@ -689,7 +154,7 @@ export interface MediaChannel {
      * - **`defaultAsrName`**, **`defaultTtsName`**: default **`key_storage.name`** when the script
      *   omits **`name`** on {@link AsrConfig} / {@link PlayOptions}
      * - **`authentication_data`**: may include **`legacyAsrKeysByName`**, **`legacyTtsKeysByName`**
-     *   (built from LE DB for this dialog’s agent + company)
+     *   (built from LE DB for this dialog's agent + company)
      *
      * Treat as read-only unless your integration explicitly documents mutable keys.
      */

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

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