@voctiv/agent-sdk 0.1.3 → 0.2.1

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

@@ -2,194 +2,720 @@ import { Observable } from 'rxjs';
 import { AsrConfig, AsrHandle } from './asr-handle';
 import { DtmfEvent, SipInfo, SipSignal, DataMessage } from './events';
 import { MixerQueueControl, PlayOptions } from './mixer';
+import type { LegacyPhraseRecord } from './legacy-phrase';
 import { TextInput } from './text-input';
 /**
- * Audio playback API — TTS synthesis, file playback, and queue management.
+ * Audio playback API — TTS synthesis, file/URL playback, caching, and multi-queue mixing.
  *
- * Audio is routed through a multi-queue mixer. Each queue can play items
- * independently with its own volume. Default queue index is 0.
+ * Audio is routed through a **multi-queue mixer** (indices **0–4**). Each queue has its own
+ * volume and lifecycle; use different **`queue`** values in {@link PlayOptions} so earcons,
+ * hold music, and agent TTS can be **`stop`**ped independently.
+ *
+ * ### Pre-answer behaviour (SIP)
+ *
+ * For SIP calls, `say()` and `play()` automatically wait for the RTP pipeline to be ready
+ * (early media or 200 OK) before starting playback. You do **not** need to call
+ * `sip.waitForEarly()` / `sip.waitForAnswer()` manually before speaking — the audio
+ * operation waits internally and starts as soon as the call enters `"early"` or `"active"` state.
+ *
+ * If the call terminates **before** any media is available, deferred `say`/`play` calls
+ * resolve as no-ops (they do not throw).
  */
 export interface ChannelAudio {
     /**
-     * Synthesize text via TTS and play it.
-     * Accepts a plain string or an RxJS Observable of string chunks (for streaming TTS).
-     * Resolves when playback finishes.
+     * Synthesize text with TTS and play the result on the selected mixer queue.
+     *
+     * On WS channels the runtime also emits text/audio progress events to the client
+     * (`TEXT_*`, `AUDIO_*`). On headless channels this is a no-op that only logs a warning.
+     *
+     * @param input - Plain string, or `Observable<string>` of chunks for streaming synthesis.
+     * @param options - Queue, alias, queue volume, {@link PlayOptions.ttsVendor},
+     *   {@link PlayOptions.name} (LE `key_storage` row), {@link PlayOptions.ttsConfig},
+     *   {@link PlayOptions.ttsStrategy}, etc.
+     * @returns Resolves when playback of this **`say`** invocation has finished (queue may still
+     *   contain other items).
+     *
+     * On SIP channels, if the call has not yet reached `"early"`/`"active"` state when
+     * `say()` is invoked, the call automatically waits for media availability. The Promise
+     * resolves as a no-op if the call terminates before media starts flowing.
      */
     say(input: string | Observable<string>, options?: PlayOptions): Promise<void>;
     /**
-     * Play a pre-recorded audio file from URL or local path.
-     * Resolves when playback finishes.
+     * 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.
+     *
+     * @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
+     *   ever wraps playback (normally ignored for raw audio).
+     *
+     * On SIP channels, automatically waits for early/active state before starting
+     * (same behaviour as `say()`).
+     */
+    play(source: string | LegacyPhraseRecord, options?: PlayOptions): Promise<void>;
+    /**
+     * Download/decode **`source`** through the audio player.
+     *
+     * In the current API runtime 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.
      */
-    play(source: string, options?: PlayOptions): Promise<void>;
-    /** Download, decode and cache audio (URL or file path) as PCM for instant playback. */
     preload(source: string): Promise<void>;
-    /** Pre-synthesize text via TTS and store in file cache for instant `say()` playback. */
+    /**
+     * 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, the current runtime logs a warning and
+     * resolves without throwing.
+     * @param text - Full text to synthesize.
+     * @param options - Same TTS-related options as **`say`** (vendor, **`name`**, **`ttsConfig`**).
+     */
     presay(text: string, options?: PlayOptions): Promise<void>;
-    /** Access a specific mixer queue by index (0–4). */
+    /**
+     * @param index - Mixer queue **0–4**.
+     * @returns Control handle for that queue’s volume and item lifecycle observables.
+     */
     queue(index: number): MixerQueueControl;
-    /** Remove a specific item by alias from a queue. */
+    /**
+     * Remove one item by **`alias`**.
+     *
+     * When **`queue`** is omitted, the SIP/WS runtime searches all five queues. When set,
+     * only that queue is inspected. For sentence-split TTS, internal queue item aliases are
+     * suffixed as `alias-0`, `alias-1`, etc.; remove the concrete suffix if you need to
+     * cancel one synthesized sentence.
+     * @param alias - **`PlayOptions.alias`** of the item to drop.
+     * @param queue - Queue index; defaults to **0**.
+     */
     remove(alias: string, queue?: number): void;
-    /** Stop and clear all items in a specific queue. */
+    /**
+     * Stop playback and clear all pending items on a single queue.
+     *
+     * Also aborts in-flight sentence TTS generation for that queue in the current runtime.
+     * @param queue - Queue index **0–4**.
+     */
     stop(queue: number): void;
-    /** Stop and clear all queues. */
+    /** Stop and clear **all** queues; WS clients also receive an audio interrupt signal. */
     stopAll(): void;
 }
-/** Observables for channel-level events (speech detection, termination, data messages). */
+/** Channel-level observables: VAD-related speech, barge-in, session end, and arbitrary data messages. */
 export interface ChannelEvents {
-    /** Fires when the caller starts speaking (VAD-based). */
+    /** User started speaking (VAD speech start, socket speech event, or synthetic text input). */
     readonly speechStart$: Observable<void>;
-    /** Fires when the caller stops speaking. */
+    /** User stopped speaking (VAD speech end, socket speech event, ASR final, or synthetic text input). */
     readonly speechEnd$: Observable<void>;
-    /** Fires when caller speech interrupts bot playback. */
+    /** User speech caused an interrupt of bot audio (barge-in path; may be inert without VAD). */
     readonly interrupt$: Observable<void>;
-    /** Fires when the session ends (hangup, timeout, or explicit destroy). */
+    /** Session is ending: hangup, client disconnect, or explicit **`channel.destroy()`**. */
     readonly terminated$: Observable<void>;
-    /** Fires on incoming data messages (e.g. from WS client). */
+    /** Structured messages from the WS client or bridge (event + payload). */
     readonly message$: Observable<DataMessage>;
 }
-/** Options for LLM `ask()` and `stream()` calls. */
+/** Options for **`channel.llm.ask`** / **`stream`** / **`makePersistentStream`**. */
 export interface LlmOptions {
-    /** Override dialog UUID for LLM context tracking. */
+    /** Override dialog UUID for Omni/LLM tracing (defaults to script dialog). */
     dialogUuid?: string;
-    /** System role hint (e.g. `"assistant"`, `"user"`). */
+    /** Chat role sent with the message, e.g. **`"assistant"`**, **`"user"`**. */
     role?: string;
-    /** If `true`, the message is added to history but not displayed. */
+    /** When `true`, message may be hidden from user-visible transcript (host-dependent). */
     hidden?: boolean;
-    /** Speaker name for multi-turn dialogs. */
+    /**
+     * **LLM-only**: speaker / persona label in multi-party chat. **Not** related to
+     * {@link PlayOptions.name} (TTS **`key_storage.name`**).
+     */
     name?: string;
-    /** Override agent UUID for routing to a specific LLM agent. */
+    /** Route the request to a specific Omni agent profile (UUID). */
     agentUuid?: string;
-    /** Current agent alias for multi-agent scenarios. */
+    /** Multi-agent: current alias for routing. */
     currentAgentAlias?: string;
-    /** Arbitrary payload forwarded to the LLM backend. */
+    /** Opaque payload forwarded to the Omni LLM backend. */
     payload?: Record<string, any>;
-    /** Enable debug logging for this request. */
+    /** Verbose logging on the LLM path. */
     debug?: boolean;
-    /** Restrict response to specific agent aliases. */
+    /** Restrict which agent aliases may handle the request. */
     agentAliasFilter?: string[];
 }
-/** Options for LLM structured extraction. */
+/** Options for **`channel.llm.extract`**. All fields except `dialogUuid` are forwarded to Omni extract. */
 export interface ExtractOptions {
-    /** Override dialog UUID. */
+    /** Override dialog UUID for extraction context; defaults to the current script dialog. */
     dialogUuid?: string;
-    /** Extraction prompt / instruction. */
+    /** Optional extraction prompt/instruction forwarded to Omni. */
     prompt?: string;
-    /** LLM model name. */
+    /** Model name or id understood by the Omni backend. */
     model?: string;
-    /** Top-p (nucleus) sampling parameter. */
+    /** Nucleus sampling value forwarded to Omni. */
     topP?: number;
-    /** Temperature sampling parameter. */
+    /** Temperature forwarded to Omni. */
     temperature?: number;
-    /** Custom model configuration. */
+    /** Custom model descriptor forwarded as-is. */
     customModel?: Record<string, any>;
     [key: string]: unknown;
 }
-/** A single chunk from an LLM streaming response. */
+/** One chunk from **`channel.llm.stream`**. */
 export interface LlmStreamChunk {
-    /** Request ID. */
     id: string;
-    /** Sequential chunk number. */
     chunkId: number;
-    /** Text content of this chunk. */
     content: string;
-    /** Non-null when the stream is done (e.g. `"stop"`, `"length"`). */
     finishReason: string | null;
-    /** Raw SSE event data. */
     event: any;
-    /** Tool call messages (function calling). */
     toolMessages?: any[];
-    /** Full raw response object. */
     raw: Record<string, any>;
 }
 /**
- * Long-lived Omni LLM session over Socket.IO — same dialog history without reloading from DB each turn.
+ * 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 (Large Language Model) API — text generation and structured extraction.
- */
+/** LLM facade on the media channel. */
 export interface ChannelLlm {
-    /** Send a message and get a complete response. */
+    /** Single-shot completion for **`message`**; consumes the Omni SSE stream and returns concatenated text. */
     ask(message: string, options?: LlmOptions): Promise<string>;
-    /** Send a message and get a streaming response (Observable of chunks). */
+    /** Token/chunk stream for **`message`** parsed from Omni SSE `data:` events. */
     stream(message: string, options?: LlmOptions): Observable<LlmStreamChunk>;
-    /** Structured data extraction using LLM (e.g. filling a form from conversation). */
+    /** Structured extraction / JSON-style fill from conversation context via Omni extract. */
     extract(options?: ExtractOptions): Promise<Record<string, any>>;
     /**
-     * Open a persistent Socket.IO stream to Omni (`/v1/chat-stream`).
-     * Default routing (e.g. agentUuid) can be set via `options`; per-send overrides are allowed on `send()`.
+     * Open a persistent Omni chat stream (see host docs for URL and auth).
+     * @param options - Default **`agentUuid`**, **`dialogUuid`**, etc.; per-**`send`** overrides allowed.
      */
     makePersistentStream(options?: LlmOptions): PersistentLlmStreamHandle;
 }
 /**
- * SIP telephony controls — DTMF, call control, bridging.
+ * 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. Billing typically has **not** started. | **Outbound:** remote sends 183 Session Progress with SDP. **Inbound:** your script calls `sip.sendProgress()`. |
+ * | **`active`** | 200 OK received/sent — the call is fully established. Billing starts. | **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"`, audio flows in both directions, and **billing has not started**
+ * (billing typically begins at 200 OK, depending on the carrier). 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 billing starts
+ *
+ * ```ts
+ * // Inbound call arrives — state is 'ringing'
+ * channel.sip.sendProgress();
+ * // State is now 'early' — full duplex audio, billing NOT started
+ *
+ * const asr = await channel.createAsr();
+ * await channel.audio.say('Please say your account number.');
+ * const account = await firstValueFrom(asr.result$);
+ *
+ * // Now answer — billing starts
+ * 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 {
-    /** Observable of DTMF digit events. */
+    /**
+     * 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>;
-    /** Observable of SIP INFO messages. */
+    /**
+     * 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>;
-    /** Observable of SIP call state changes (e.g. ringing, confirmed, terminated). */
+    /**
+     * 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>;
-    /** Send a DTMF digit to the remote party. */
+    /**
+     * 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
+     * - Billing has typically **not** started yet (depends on carrier)
+     *
+     * 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 message. */
+    /**
+     * 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 call on hold. */
+    /**
+     * 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 call. */
+    /**
+     * Resume a held SIP call (sends re-INVITE with `a=sendrecv`).
+     */
     unhold(): void;
-    /** Mute outgoing audio. */
+    /**
+     * 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;
-    /** Unmute outgoing audio. */
+    /** Resume sending audio after {@link mute}. No-op on WS/headless channels. */
     unmute(): void;
-    /** Hang up the call. */
+    /**
+     * 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 incoming call. */
+    /**
+     * 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
+     * billing starts.
+     *
+     * If the call is in `"early"` state (after `sendProgress()`), `answer()` promotes it
+     * to `"active"` — audio was already flowing, billing now begins.
+     *
+     * ```ts
+     * // Simple: answer immediately
+     * channel.sip.answer();
+     * await channel.audio.say('Hello, how can I help?');
+     * ```
+     *
+     * ```ts
+     * // Advanced: pre-answer → answer
+     * channel.sip.sendProgress();               // early media, no billing
+     * await channel.audio.say('One moment…');
+     * channel.sip.answer();                      // billing starts
+     * await channel.audio.say('How can I help?');
+     * ```
+     */
     answer(): void;
-    /** Originate a new outbound SIP call and return its media channel. */
+    /**
+     * 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 but the call is **not yet billed**
+     *   (billing typically starts at 200 OK, depending on the carrier).
+     *
+     * 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, billing has NOT started
+     *
+     * await channel.audio.say('Please hold while we connect you…');
+     *
+     * // Now answer (billing starts)
+     * 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 billing started
+     * 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',
+     * });
+     * 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>;
-    /** Bridge two channels together (conference). Returns a teardown function. */
+    /**
+     * 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. The current runtime 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;
 }
 /**
- * Media channel — the main interface for voice, audio, SIP, and LLM interaction.
+ * Primary script API for real-time voice: ASR, TTS/audio, SIP, LLM, and **`params`** from the host.
  *
- * Every script receives a `channel` object. In headless mode,
- * audio and SIP methods are no-ops or stubs.
+ * **`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.
+ * In headless mode audio/SIP/text input are mostly no-ops while **`llm`** / **`platform`**
+ * still work.
  */
 export interface MediaChannel {
-    /** Channel transport type: `"sip"` for phone calls, `"ws"` for WebSocket sessions. */
     readonly type: 'sip' | 'ws';
-    /** Inbound caller ID (phone number or WS client ID). */
     readonly callerId: string;
-    /** Called number / destination DID. */
     readonly calledNumber: string;
-    /** Channel-level params (merged from route, agent defaults, etc.). */
+    /**
+     * Merged session parameters from env, Omni, Voctiv platform defaults, and route.
+     *
+     * Relevant to ASR/TTS when **Voctiv platform** compatibility is on (host-dependent keys), for example:
+     * - **`asrVendor`**, **`ttsVendor`**, **`asrConfig`**, **`ttsConfig`**
+     * - **`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)
+     *
+     * Treat as read-only unless your integration explicitly documents mutable keys.
+     */
     readonly params: Record<string, unknown>;
-    /** Create a new ASR (speech recognition) handle with optional config. */
+    /**
+     * Create a speech recognizer for this session.
+     *
+     * SIP channels feed remote RTP audio. WS channels feed socket `audio` frames and can
+     * create a per-session VAD on first ASR creation. Headless channels return an inert
+     * handle with empty observables.
+     *
+     * @param config - Optional {@link AsrConfig}: **`vendor`**, **`name`** (storage row), **`language`**,
+     *   **`data`** overlays, VAD / smart-turn tuning.
+     * @returns A handle you should {@link AsrHandle.destroy} when you no longer need recognition.
+     *   If connector creation fails, SIP/WS return a degraded handle with VAD observables but no STT results.
+     */
     createAsr(config?: AsrConfig): Promise<AsrHandle>;
-    /** Virtual text input for testing — push text as if ASR recognized it. */
+    /** Push synthetic ASR results (testing / WS debug). No-op on headless channels. */
     readonly textInput: TextInput;
-    /** Audio playback and TTS. */
     readonly audio: ChannelAudio;
-    /** Channel events (speech, termination, data messages). */
     readonly events: ChannelEvents;
-    /** LLM text generation and extraction. */
     readonly llm: ChannelLlm;
-    /** SIP telephony controls. */
     readonly sip: ChannelSip;
-    /** Send a data message to the remote party (WS). */
+    /** Emit a structured message to the remote peer. Implemented for WS; SIP ignores it and headless logs it. */
     sendMessage(data: DataMessage): void;
-    /** Terminate the channel and release all resources. */
+    /** Release connectors, mixer, recordings, persistent LLM streams, and subscriptions. */
     destroy(): void;
 }
 //# sourceMappingURL=media-channel.d.ts.map