@voctiv/agent-sdk 0.2.0 → 0.2.1

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

@@ -10,34 +10,64 @@ import { TextInput } from './text-input';
  * 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 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, volume, {@link PlayOptions.ttsVendor}, {@link PlayOptions.name}
-     *   (LE `key_storage` row), {@link PlayOptions.ttsConfig}, {@link PlayOptions.ttsStrategy}, etc.
+     * @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 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`** and cache PCM so a later **`say`/`play`** with the same source
-     * starts faster.
+     * 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.
      */
     preload(source: string): Promise<void>;
     /**
-     * Run TTS ahead of time and store audio in the host cache (exact semantics depend on connector).
+     * 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`**).
      */
@@ -48,26 +78,33 @@ export interface ChannelAudio {
      */
     queue(index: number): MixerQueueControl;
     /**
-     * Remove one item by **`alias`** from a queue (default queue **0** if omitted).
+     * 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 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 (nuclear option for teardown). */
+    /** Stop and clear **all** queues; WS clients also receive an audio interrupt signal. */
     stopAll(): void;
 }
 /** Channel-level observables: VAD-related speech, barge-in, session end, and arbitrary data messages. */
 export interface ChannelEvents {
-    /** User started speaking (VAD speech start). */
+    /** User started speaking (VAD speech start, socket speech event, or synthetic text input). */
     readonly speechStart$: Observable<void>;
-    /** User stopped speaking (VAD speech end). */
+    /** User stopped speaking (VAD speech end, socket speech event, ASR final, or synthetic text input). */
     readonly speechEnd$: Observable<void>;
-    /** User speech caused an interrupt of bot audio (barge-in path). */
+    /** User speech caused an interrupt of bot audio (barge-in path; may be inert without VAD). */
     readonly interrupt$: Observable<void>;
     /** Session is ending: hangup, client disconnect, or explicit **`channel.destroy()`**. */
     readonly terminated$: Observable<void>;
@@ -78,7 +115,7 @@ export interface ChannelEvents {
 export interface LlmOptions {
     /** Override dialog UUID for Omni/LLM tracing (defaults to script dialog). */
     dialogUuid?: string;
-    /** Chat role hint, e.g. **`"assistant"`**, **`"user"`**. */
+    /** 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;
@@ -91,20 +128,26 @@ export interface LlmOptions {
     agentUuid?: string;
     /** Multi-agent: current alias for routing. */
     currentAgentAlias?: string;
-    /** Opaque payload forwarded to the LLM backend. */
+    /** 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`**. */
+/** 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;
 }
@@ -123,17 +166,20 @@ export interface LlmStreamChunk {
  */
 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`**. */
+    /** 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`**. */
+    /** 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. */
+    /** Structured extraction / JSON-style fill from conversation context via Omni extract. */
     extract(options?: ExtractOptions): Promise<Record<string, any>>;
     /**
      * Open a persistent Omni chat stream (see host docs for URL and auth).
@@ -141,31 +187,495 @@ export interface ChannelLlm {
      */
     makePersistentStream(options?: LlmOptions): PersistentLlmStreamHandle;
 }
-/** SIP: DTMF, INFO, hold/mute/hangup, outbound **`makeCall`**, **`bridge`**. */
+/**
+ * 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 {
+    /**
+     * 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
+     * - 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 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
+     * 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;
+    /**
+     * 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>;
+    /**
+     * 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;
 }
 /**
  * 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.
- * In **headless** mode (see {@link import('./define-script').ScriptDialogContext.headless}),
- * audio/SIP may be no-ops while **`llm`** / **`platform`** still work.
+ * 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 {
     readonly type: 'sip' | 'ws';
@@ -187,20 +697,25 @@ export interface MediaChannel {
     /**
      * 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 must {@link AsrHandle.destroy} when the session ends.
+     * @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>;
-    /** Push synthetic ASR results (testing / WS debug). */
+    /** Push synthetic ASR results (testing / WS debug). No-op on headless channels. */
     readonly textInput: TextInput;
     readonly audio: ChannelAudio;
     readonly events: ChannelEvents;
     readonly llm: ChannelLlm;
     readonly sip: ChannelSip;
-    /** Emit a structured message to the remote peer (WS). */
+    /** Emit a structured message to the remote peer. Implemented for WS; SIP ignores it and headless logs it. */
     sendMessage(data: DataMessage): void;
-    /** Release connectors, mixer, and subscriptions. */
+    /** Release connectors, mixer, recordings, persistent LLM streams, and subscriptions. */
     destroy(): void;
 }
 //# sourceMappingURL=media-channel.d.ts.map