getpatter 0.5.3 → 0.6.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { EventEmitter } from 'events';
 import { Request, Response, NextFunction, Express } from 'express';
 
 /** Twilio carrier credentials holder for Patter. */
+/** Constructor options for the Twilio {@link Carrier}. */
 interface TwilioCarrierOptions {
     /** Twilio Account SID. Falls back to TWILIO_ACCOUNT_SID env var. */
     accountSid?: string;
@@ -13,7 +14,7 @@ interface TwilioCarrierOptions {
  *
  * @example
  * ```ts
- * import * as twilio from "getpatter/carriers/twilio";
+ * import * as twilio from "getpatter/telephony/twilio";
  * const carrier = new twilio.Carrier();                     // reads env
  * const carrier = new twilio.Carrier({ accountSid: "AC...", authToken: "..." });
  * ```
@@ -26,6 +27,7 @@ declare class Carrier$1 {
 }
 
 /** Telnyx carrier credentials holder for Patter. */
+/** Constructor options for the Telnyx {@link Carrier}. */
 interface TelnyxCarrierOptions {
     /** Telnyx API key. Falls back to TELNYX_API_KEY env var. */
     apiKey?: string;
@@ -39,7 +41,7 @@ interface TelnyxCarrierOptions {
  *
  * @example
  * ```ts
- * import * as telnyx from "getpatter/carriers/telnyx";
+ * import * as telnyx from "getpatter/telephony/telnyx";
  * const carrier = new telnyx.Carrier();                     // reads env
  * const carrier = new telnyx.Carrier({ apiKey: "KEY...", connectionId: "123" });
  * ```
@@ -53,6 +55,7 @@ declare class Carrier {
 }
 
 /** OpenAI Realtime engine — marker class for Patter client dispatch. */
+/** Constructor options for the OpenAI `Realtime` engine marker. */
 interface RealtimeOptions {
     /** API key. Falls back to OPENAI_API_KEY env var when omitted. */
     apiKey?: string;
@@ -60,6 +63,21 @@ interface RealtimeOptions {
     model?: string;
     /** Voice preset. Defaults to alloy. */
     voice?: string;
+    /**
+     * Reasoning-effort tier for `gpt-realtime-2`. When omitted the
+     * `session.reasoning` field is not sent and the server default applies.
+     * OpenAI recommends `"low"` for production voice flows — higher tiers add
+     * measurable per-turn latency. Has no effect on models that ignore the
+     * field.
+     */
+    reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
+    /**
+     * Override for the Realtime session's `input_audio_transcription.model`.
+     * Omit to keep the adapter default (`whisper-1`). Use
+     * `"gpt-realtime-whisper"` for low-latency transcript partials,
+     * `"gpt-4o-transcribe"` for higher accuracy.
+     */
+    inputAudioTranscriptionModel?: string;
 }
 /**
  * OpenAI Realtime engine marker.
@@ -69,6 +87,11 @@ interface RealtimeOptions {
  * import * as openai from "getpatter/engines/openai";
  * const engine = new openai.Realtime();                     // reads OPENAI_API_KEY
  * const engine = new openai.Realtime({ voice: "alloy" });
+ * const engine = new openai.Realtime({
+ *   model: "gpt-realtime-2",
+ *   reasoningEffort: "low",                                  // gpt-realtime-2 only
+ *   inputAudioTranscriptionModel: "gpt-realtime-whisper",
+ * });
  * ```
  */
 declare class Realtime {
@@ -76,10 +99,13 @@ declare class Realtime {
     readonly apiKey: string;
     readonly model: string;
     readonly voice: string;
+    readonly reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
+    readonly inputAudioTranscriptionModel?: string;
     constructor(opts?: RealtimeOptions);
 }
 
 /** ElevenLabs ConvAI engine — marker class for Patter client dispatch. */
+/** Constructor options for the ElevenLabs `ConvAI` engine marker. */
 interface ConvAIOptions {
     /** API key. Falls back to ELEVENLABS_API_KEY env var when omitted. */
     apiKey?: string;
@@ -175,6 +201,7 @@ declare class Ngrok {
  * consumed either form keeps working.
  */
 
+/** Options accepted by `new Guardrail(...)` / `guardrail(...)`. */
 interface GuardrailOptions {
     /** Name for logging when triggered. */
     name: string;
@@ -204,7 +231,9 @@ declare class Guardrail$1 {
 }
 /** Factory helper mirroring Python's `guardrail(...)` function. */
 declare function guardrail(opts: GuardrailOptions): Guardrail$1;
+/** Async handler invoked in-process when the LLM calls a `Tool`. */
 type ToolHandler = (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<string>;
+/** Options accepted by `new Tool(...)` / `tool(...)`. */
 interface ToolOptions {
     /** Tool name (visible to the LLM). */
     name: string;
@@ -283,6 +312,7 @@ interface STTTranscript {
     /** Which provider event this transcript represents (e.g. ``Results``). */
     eventType?: string;
 }
+/** Callback invoked by an `STTAdapter` for each (partial or final) transcript event. */
 type STTTranscriptCallback = (t: STTTranscript) => Promise<void> | void;
 /** Shape shared by every STT adapter in the SDK. */
 interface STTAdapter {
@@ -290,7 +320,20 @@ interface STTAdapter {
     sendAudio(pcm: Buffer): void | Promise<void>;
     onTranscript(cb: STTTranscriptCallback): void;
     close(): void | Promise<void>;
+    /**
+     * Optional: ask the provider to immediately finalise the in-flight
+     * utterance (rather than waiting for its own endpoint timer). Called by
+     * ``StreamHandler`` whenever the SDK's VAD signals ``speech_end``, and
+     * after a barge-in cancel — both moments where waiting for the
+     * provider's endpoint heuristic stalls the next turn.
+     *
+     * Implementations that do not support utterance-level finalisation
+     * (e.g. one-shot transcribers like Whisper) should omit this method
+     * entirely; the stream handler does an optional-chained call.
+     */
+    finalize?(): void | Promise<void>;
 }
+/** Shape shared by every TTS adapter in the SDK. */
 interface TTSAdapter {
     synthesizeStream(text: string): AsyncIterable<Buffer>;
 }
@@ -303,8 +346,10 @@ interface TTSAdapter {
  * passes through unchanged.
  */
 
+/** Runs user-defined pipeline hooks (`beforeSendToStt`, `afterTranscribe`, …) with fail-open semantics. */
 declare class PipelineHookExecutor {
     private readonly hooks;
+    private readonly afterLlm;
     constructor(hooks: PipelineHooks | undefined);
     /**
      * Run beforeSendToStt hook. Returns null to drop the audio chunk.
@@ -325,14 +370,47 @@ declare class PipelineHookExecutor {
      */
     runBeforeLlm(messages: Array<Record<string, unknown>>, ctx: HookContext): Promise<Array<Record<string, unknown>>>;
     /**
-     * Run afterLlm hook. Returns a possibly-modified assistant text.
-     * Returning ``null`` from the hook means "keep the original".
-     * Fail-open: on exception, the original text passes through.
+     * Tier 1 — per-token sync transform. Returns the (possibly transformed)
+     * chunk. Fail-open: on exception or non-string return, the original chunk
+     * passes through unchanged. Must be cheap (~0 ms budget).
+     */
+    runAfterLlmChunk(chunk: string): string;
+    /**
+     * Tier 2 — per-sentence rewrite. Returns rewritten sentence text, the
+     * original sentence (if hook returned `null`), or `null` to drop the
+     * sentence entirely (empty string is treated as drop). Fail-open.
+     */
+    runAfterLlmSentence(sentence: string, ctx: HookContext): Promise<string | null>;
+    /**
+     * Tier 3 — per-response rewrite. Returns the (possibly rewritten) full
+     * response text. Triggered after the LLM stream completes. Caller is
+     * responsible for buffering tokens before invocation. Fail-open.
+     */
+    runAfterLlmResponse(text: string, ctx: HookContext): Promise<string>;
+    /**
+     * Backward-compatible alias for `runAfterLlmResponse`. Existing call sites
+     * in the LLM loop continue to work unchanged.
+     *
+     * @deprecated Use `runAfterLlmResponse` directly.
      */
     runAfterLlm(text: string, ctx: HookContext): Promise<string>;
     /**
-     * Whether ``afterLlm`` is configured. Used by the LLM loop to decide
-     * whether to buffer streaming tokens before yielding them.
+     * Whether a per-response (tier 3) `onResponse` transform is configured.
+     * The LLM loop uses this to decide whether to buffer streaming tokens
+     * before yielding them. Per-token (tier 1) and per-sentence (tier 2)
+     * transforms do NOT require buffering.
+     */
+    hasAfterLlmResponse(): boolean;
+    /** Whether a per-sentence (tier 2) transform is configured. */
+    hasAfterLlmSentence(): boolean;
+    /** Whether a per-token (tier 1) transform is configured. */
+    hasAfterLlmChunk(): boolean;
+    /**
+     * Backward-compatible alias for `hasAfterLlmResponse`. The legacy callable
+     * form maps to `onResponse`, so this preserves the original semantic for
+     * existing call sites.
+     *
+     * @deprecated Use `hasAfterLlmResponse` directly.
      */
     hasAfterLlm(): boolean;
     /**
@@ -350,13 +428,15 @@ declare class PipelineHookExecutor {
 /**
  * Lightweight in-process event bus for Patter call lifecycle events.
  *
- * Mirrors the Python ``PatterEventBus`` (sdk-py/getpatter/observability/event_bus.py).
+ * Mirrors the Python ``PatterEventBus`` (libraries/python/getpatter/observability/event_bus.py).
  * Consumers subscribe with ``on()`` and receive typed payloads.  ``emit()`` is
  * synchronous but handles async listeners: rejections are surfaced via the
  * Patter logger rather than being swallowed or crashing the call.
  */
+/** String tag identifying every event type the `EventBus` knows how to dispatch. */
 type PatterEventType = 'turn_started' | 'turn_ended' | 'eou_metrics' | 'interruption' | 'llm_metrics' | 'tts_metrics' | 'stt_metrics' | 'metrics_collected' | 'call_ended' | 'transcript_partial' | 'transcript_final' | 'llm_chunk' | 'tts_chunk' | 'tool_call_started';
 type Listener<T = unknown> = (payload: T) => void | Promise<void>;
+/** In-process pub/sub for Patter call-lifecycle events. */
 declare class EventBus {
     private readonly listeners;
     /**
@@ -370,6 +450,65 @@ declare class EventBus {
     emit<T = unknown>(event: PatterEventType, payload: T): void;
 }
 
+/**
+ * Per-tool circuit breaker for the Patter SDK.
+ *
+ * Trips OPEN after N consecutive failures, rejects calls for a cooldown
+ * window so a flaky downstream (DB outage, vendor API rate-limit, dead
+ * webhook) doesn't burn LLM tokens on retries that will keep failing.
+ * After the cooldown elapses the next call probes (HALF_OPEN); a success
+ * resets to CLOSED, a failure reopens. The model receives a structured
+ * ``{ error, fallback: true }`` JSON in all rejection paths so it can
+ * recover gracefully instead of waiting forever.
+ *
+ * Lightweight in-memory implementation — one ``CircuitBreakerRegistry``
+ * per ``DefaultToolExecutor``, state is per tool name. Not persisted
+ * across process restarts (intentional — voice calls are too short for
+ * persistence to matter).
+ */
+/** Lifecycle states for the breaker. */
+declare const CircuitBreakerState: {
+    readonly CLOSED: "closed";
+    readonly OPEN: "open";
+    readonly HALF_OPEN: "half_open";
+};
+type CircuitBreakerState = (typeof CircuitBreakerState)[keyof typeof CircuitBreakerState];
+/** Tunables for a single per-tool breaker. */
+interface CircuitBreakerOptions {
+    /** Consecutive failures that flip CLOSED → OPEN. ``0`` disables. */
+    failureThreshold?: number;
+    /** Time (ms) the breaker stays OPEN before allowing a probe. */
+    cooldownMs?: number;
+}
+interface PerToolState {
+    state: CircuitBreakerState;
+    consecutiveFailures: number;
+    openedAt: number;
+}
+/** Per-name registry tracking circuit state for a fleet of tools. */
+declare class CircuitBreakerRegistry {
+    private readonly threshold;
+    private readonly cooldownMs;
+    private readonly state;
+    /** Inject for deterministic tests; defaults to ``Date.now()``. */
+    private readonly clock;
+    constructor(opts?: CircuitBreakerOptions, clock?: () => number);
+    /** Returns ``true`` when this tool is currently allowed to run. */
+    allow(toolName: string): boolean;
+    /** Mark a successful execution. Resets the breaker to CLOSED. */
+    recordSuccess(toolName: string): void;
+    /** Mark a failed execution; trips OPEN once threshold is reached. */
+    recordFailure(toolName: string): void;
+    /**
+     * Time until the breaker transitions OPEN → HALF_OPEN, in ms. Returns
+     * ``0`` when the breaker is currently allowing calls. Useful for
+     * tests and the structured rejection JSON.
+     */
+    timeUntilHalfOpen(toolName: string): number;
+    /** Snapshot for debugging / metrics. */
+    snapshot(toolName: string): PerToolState | null;
+}
+
 /**
  * Built-in LLM loop for pipeline mode when no onMessage handler is provided.
  *
@@ -387,7 +526,7 @@ interface LlmUsageRecorder {
 }
 /**
  * Pluggable tool executor — mirrors the Python ``ToolExecutor`` in
- * ``sdk-py/getpatter/services/tool_executor.py``.
+ * ``libraries/python/getpatter/services/tool_executor.py``.
  *
  * Implementors receive a fully-resolved ``ToolDefinition`` (handler +/ webhook
  * URL already validated by the SDK) and MUST return a JSON-stringifiable
@@ -395,28 +534,50 @@ interface LlmUsageRecorder {
  * ``{ error: "...", fallback: true }`` rather than thrown.
  */
 interface ToolExecutor {
-    execute(toolDef: ToolDefinition, args: Record<string, unknown>, callContext: Record<string, unknown>): Promise<string>;
+    execute(toolDef: ToolDefinition, args: Record<string, unknown>, callContext: Record<string, unknown>, onProgress?: (text: string) => void | Promise<void>): Promise<string>;
 }
+/** Constructor options for `DefaultToolExecutor`. */
 interface DefaultToolExecutorOptions {
     /** Total attempts = maxRetries + 1. Default: 2 (i.e. 3 attempts). */
     maxRetries?: number;
-    /** Delay between attempts, in ms. */
+    /** Delay between attempts, in ms. Each retry waits this × ``2^attempt``. */
     retryDelayMs?: number;
     /** Per-request timeout for webhook calls, in ms. */
     requestTimeoutMs?: number;
+    /**
+     * Circuit-breaker tunables. Default trips OPEN after 5 consecutive
+     * failures and stays OPEN for 30 s. Pass ``{ failureThreshold: 0 }`` to
+     * disable entirely (legacy behaviour).
+     */
+    circuitBreaker?: CircuitBreakerOptions;
 }
 /**
- * Default executor — webhook with retry/fallback and local handler preference.
+ * Default executor — webhook + handler with retry/exponential-backoff
+ * and a per-tool circuit breaker.
  *
- * This is the out-of-the-box behavior and is 1:1 equivalent to the previous
- * inline logic in ``LLMLoop.executeTool``.
+ * Failure modes return a structured ``{ error, fallback: true }`` JSON
+ * so the model can recover gracefully (e.g. respond "I couldn't reach
+ * the booking system, can I take your number to call you back?")
+ * instead of hanging on an exception that never surfaces.
  */
 declare class DefaultToolExecutor implements ToolExecutor {
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly requestTimeoutMs;
+    private readonly breaker;
     constructor(opts?: DefaultToolExecutorOptions);
-    execute(toolDef: ToolDefinition, args: Record<string, unknown>, callContext: Record<string, unknown>): Promise<string>;
+    /** Expose the breaker for tests + dashboard observability. */
+    get circuitBreaker(): CircuitBreakerRegistry;
+    execute(toolDef: ToolDefinition, args: Record<string, unknown>, callContext: Record<string, unknown>, 
+    /**
+     * Optional progress sink — invoked with each ``{ progress: string }``
+     * value yielded by an async-generator handler. Wired by the stream
+     * handler to ``OpenAIRealtimeAdapter.sendText`` so the agent speaks
+     * the progress message inline. ``null``/``undefined`` discards
+     * progress (function handlers always discard since they have no
+     * progress channel).
+     */
+    onProgress?: (text: string) => void | Promise<void>): Promise<string>;
 }
 /** A single streaming chunk yielded by an LLM provider. */
 interface LLMChunk {
@@ -440,8 +601,21 @@ interface LLMChunk {
  *   invocation.  Chunks with the same ``index`` are concatenated.
  * - ``{ type: "done" }`` — signals the end of the stream (optional).
  */
+/**
+ * Optional knobs passed by the LLM loop into ``provider.stream``. Today the
+ * only field is ``signal``: a per-turn AbortSignal that the stream handler
+ * trips on barge-in so the underlying ``fetch`` / SDK call is cancelled
+ * IMMEDIATELY instead of waiting for the next token. Without this, a
+ * barge-in fired while the upstream LLM is still composing its first
+ * sentence leaves the fetch open until the provider's own timeout (often
+ * 30 s) elapses, blocking the next user transcript and producing the
+ * "agent stays silent after interruption" symptom.
+ */
+interface LLMStreamOptions {
+    signal?: AbortSignal;
+}
 interface LLMProvider {
-    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
 }
 /** Optional sampling kwargs forwarded into the OpenAI Chat Completions body. */
 interface OpenAILLMSamplingOptions {
@@ -481,8 +655,10 @@ declare class OpenAILLMProvider implements LLMProvider {
     private readonly presencePenalty?;
     private readonly stop?;
     constructor(apiKey: string, model: string, sampling?: OpenAILLMSamplingOptions);
-    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+    /** Stream OpenAI Chat Completions chunks for the given messages/tools. */
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
 }
+/** Pipeline-mode LLM driver: runs the chat loop, dispatches tool calls, and emits text deltas. */
 declare class LLMLoop {
     private readonly provider;
     private readonly systemPrompt;
@@ -493,7 +669,8 @@ declare class LLMLoop {
     private eventBus?;
     private readonly _providerName;
     private readonly _modelName;
-    constructor(apiKey: string, model: string, systemPrompt: string, tools?: ToolDefinition[] | null, llmProvider?: LLMProvider);
+    private onToolCall?;
+    constructor(apiKey: string, model: string, systemPrompt: string, tools?: ToolDefinition[] | null, llmProvider?: LLMProvider, disablePhonePreamble?: boolean);
     /**
      * Swap in a custom tool executor (e.g. different retry policy, metrics
      * wrapping, tenant-aware fan-out). The default is ``DefaultToolExecutor``.
@@ -505,6 +682,14 @@ declare class LLMLoop {
      * appears. Set to ``undefined`` to disable.
      */
     setEventBus(bus: EventBus | undefined): void;
+    /**
+     * Set or replace the post-tool-execution observer. The callback is
+     * awaited after every successful tool execution with
+     * `(name, args, result)`. Pass `undefined` to disable. Mirrors the
+     * Python `LLMLoop.set_on_tool_call` setter so callers (e.g. the
+     * pipeline `StreamHandler`) can wire the loop after construction.
+     */
+    setOnToolCall(callback: ((name: string, args: Record<string, unknown>, result: string) => Promise<void>) | undefined): void;
     /**
      * Stream LLM response tokens, handling tool calls automatically.
      * Yields text tokens as they arrive from the LLM.
@@ -516,16 +701,23 @@ declare class LLMLoop {
     run(userText: string, history: Array<{
         role: string;
         text: string;
-    }>, callContext: Record<string, unknown>, metrics?: LlmUsageRecorder, hookExecutor?: PipelineHookExecutor, hookCtx?: HookContext): AsyncGenerator<string, void, unknown>;
+    }>, callContext: Record<string, unknown>, metrics?: LlmUsageRecorder, hookExecutor?: PipelineHookExecutor, hookCtx?: HookContext, opts?: LLMStreamOptions): AsyncGenerator<string, void, unknown>;
     private executeTool;
     private buildMessages;
 }
 
+/**
+ * Public type definitions for the Patter SDK — agent options, pipeline hooks,
+ * provider config envelopes, and serve/call request/response shapes.
+ */
+
+/** Inbound message handed to a `MessageHandler` per turn (legacy single-turn API). */
 interface IncomingMessage {
     readonly text: string;
     readonly callId: string;
     readonly caller: string;
 }
+/** STT provider configuration envelope (provider name + key + language + provider-specific options). */
 interface STTConfig {
     readonly provider: string;
     readonly apiKey: string;
@@ -539,6 +731,7 @@ interface STTConfig {
     /** Provider-specific knobs (e.g. Deepgram endpointing). */
     options?: Record<string, unknown>;
 }
+/** TTS provider configuration envelope (provider name + key + voice + provider-specific options). */
 interface TTSConfig {
     readonly provider: string;
     readonly apiKey: string;
@@ -550,17 +743,94 @@ interface TTSConfig {
     toDict(): Record<string, string | Record<string, unknown>>;
     options?: Record<string, unknown>;
 }
+/** Single-turn message handler — receives the user's transcript, returns the agent's reply. */
 type MessageHandler = (msg: IncomingMessage) => Promise<string>;
+/** Generic call-lifecycle callback (start/end/transcript/metrics). */
 type CallEventHandler = (data: Record<string, unknown>) => Promise<void>;
+/**
+ * Public MCP server configuration. ``string`` is shorthand for
+ * ``{ url: <string>, transport: 'streamable-http' }``. Re-exported from
+ * ``tools/mcp-client`` to keep a single source of truth.
+ */
+type MCPServerConfig = string | {
+    readonly url: string;
+    readonly transport?: 'streamable-http';
+    /** Headers attached to every transport request — typically auth. */
+    readonly headers?: Record<string, string>;
+    /** Optional logical name for telemetry / log lines. */
+    readonly name?: string;
+};
+/** Internal shape of a tool definition (matches `Tool` from `public-api.ts`). */
 interface ToolDefinition {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
     /** Webhook URL — called when the LLM invokes this tool. Mutually exclusive with handler. */
     webhookUrl?: string;
-    /** Local handler function — when provided, called instead of webhookUrl. */
-    handler?: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<string>;
+    /**
+     * Local handler — called instead of ``webhookUrl`` when present.
+     *
+     * Two forms:
+     *
+     *  - **Async function**: returns the final result as a JSON string.
+     *    The model receives only the final return value.
+     *
+     *  - **Async generator**: yields zero or more progress updates before
+     *    returning. Each ``yield`` of ``{ progress: string }`` is spoken
+     *    inline by the agent (Realtime: via ``adapter.sendText``) so the
+     *    caller hears live status during long-running tools. The final
+     *    ``return`` value (or last ``yield`` if no return) is the
+     *    function-call result sent to the model. Pipeline mode currently
+     *    ignores the progress yields — the final value is still used as
+     *    the tool result.
+     */
+    handler?: ((args: Record<string, unknown>, context: Record<string, unknown>) => Promise<string>) | ((args: Record<string, unknown>, context: Record<string, unknown>) => AsyncGenerator<{
+        progress?: string;
+        result?: string;
+    }, string | void, unknown>);
+    /**
+     * "Reassurance" filler the agent speaks while a slow tool call runs.
+     * Bridges the silence when a handler or webhook takes longer than
+     * humans naturally tolerate (~1.5 s) without sounding dead.
+     *
+     * Two forms:
+     *  - string: shorthand for ``{ message: <string>, afterMs: 1500 }``.
+     *  - object: explicit ``{ message, afterMs? }``. ``afterMs`` is the
+     *    grace window before the reassurance fires; if the tool returns
+     *    earlier, no message is spoken.
+     *
+     * Currently honoured only in **Realtime mode** — the SDK enqueues the
+     * message via ``OpenAIRealtimeAdapter.sendText`` so the model
+     * synthesises it inline. Pipeline mode has no clean injection point
+     * mid-turn yet; the option is silently ignored there. Off by default.
+     */
+    reassurance?: string | {
+        message: string;
+        afterMs?: number;
+    };
+    /**
+     * Enable OpenAI strict mode for this tool's function schema. When ``true``
+     * the model is constrained to emit arguments that exactly match the
+     * declared schema — no missing required fields, no extra properties, no
+     * type coercion. Defaults to ``false`` for backward compatibility.
+     *
+     * Strict mode requires the schema to satisfy OpenAI's structural rules:
+     * - root must be ``type: "object"``
+     * - every nested object must have ``additionalProperties: false``
+     * - every property listed in ``properties`` must also be in ``required``
+     *
+     * Patter validates these requirements at ``agent()`` build time when
+     * ``strict: true`` is set; an invalid schema raises immediately rather
+     * than failing silently mid-call. Use ``null`` in a union (``["string",
+     * "null"]``) to express "optional" — strict mode does not allow truly
+     * optional fields.
+     *
+     * Recommended for any tool whose handler/webhook can't safely tolerate
+     * malformed arguments (DB writes, payment, transfers).
+     */
+    strict?: boolean;
 }
+/** Constructor options for `new Patter({...})` in local-server mode. */
 interface LocalOptions {
     /**
      * Telephony carrier instance. Required.
@@ -579,6 +849,34 @@ interface LocalOptions {
     tunnel?: CloudflareTunnel | Static | boolean;
     phoneNumber: string;
     webhookUrl?: string;
+    /**
+     * On-disk persistence for the dashboard's call history. The dashboard
+     * itself is in-memory, but enabling ``persist`` writes per-call records
+     * (metadata.json, transcript.jsonl, events.jsonl) to disk and rebuilds
+     * the in-memory cache on startup so the dashboard survives process
+     * restarts without an external database.
+     *
+     * Accepted values:
+     * - omitted / ``false`` (default): no disk writes; the dashboard resets
+     *   on every restart. Backward-compatible with prior behaviour.
+     * - ``true``: write under the platform default location
+     *   (``~/Library/Application Support/patter`` on macOS,
+     *   ``%LOCALAPPDATA%\\patter`` on Windows,
+     *   ``$XDG_DATA_HOME/patter`` on Linux). Equivalent to setting
+     *   ``PATTER_LOG_DIR=auto``.
+     * - string: write under the supplied absolute path. Equivalent to
+     *   setting ``PATTER_LOG_DIR=<path>``.
+     *
+     * The ``PATTER_LOG_DIR`` env var still works as a deployment-time
+     * override and takes precedence over an unset ``persist``. When
+     * ``persist`` is set explicitly the env var is ignored.
+     *
+     * Retention: defaults to 30 days, controlled by
+     * ``PATTER_LOG_RETENTION_DAYS`` (set to ``0`` to keep forever).
+     * Phone numbers are masked by default; control via
+     * ``PATTER_LOG_REDACT_PHONE``.
+     */
+    persist?: boolean | string;
     /**
      * @internal — allows ``StreamHandler`` to build the default OpenAI
      * ``LLMLoop`` when no ``onMessage`` handler is supplied. The
@@ -587,6 +885,7 @@ interface LocalOptions {
      */
     openaiKey?: string;
 }
+/** Internal shape of a guardrail (matches `Guardrail` class from `public-api.ts`). */
 interface Guardrail {
     /** Name for logging when triggered */
     name: string;
@@ -597,6 +896,7 @@ interface Guardrail {
     /** Replacement text spoken when guardrail triggers */
     replacement?: string;
 }
+/** Per-call context passed to every pipeline hook. */
 interface HookContext {
     readonly callId: string;
     readonly caller: string;
@@ -606,6 +906,32 @@ interface HookContext {
         text: string;
     }>;
 }
+/**
+ * Streaming-friendly post-LLM transform hook. Three tiers, all optional:
+ *
+ * - **`onChunk`** — per-token pure transform. Sync, must be fast (~0 ms
+ *   budget). Use for: regex replace, markdown strip, profanity char-swap.
+ * - **`onSentence`** — per-sentence rewrite. Runs between the sentence
+ *   chunker and TTS. Returns rewritten text or `null` to keep original;
+ *   ``""`` (empty string) drops the sentence silently. Latency budget
+ *   ~50–300 ms. Use for: PII redaction, persona overlay, refusal swap.
+ * - **`onResponse`** — per-full-response rewrite. **Blocks streaming TTS**
+ *   until the LLM stream completes, then runs once on the full text.
+ *   Latency cost: 500 ms – 2 s. Use only when sentence-level rewrite is
+ *   insufficient (e.g. structured output validation). Avoid in latency-
+ *   sensitive paths.
+ *
+ * The legacy single-callable signature `(text, ctx) => string` is still
+ * accepted; it maps to `onResponse` and emits a deprecation warning.
+ */
+interface AfterLLMHook {
+    onChunk?: (chunk: string) => string;
+    onSentence?: (sentence: string, ctx: HookContext) => string | null | Promise<string | null>;
+    onResponse?: (text: string, ctx: HookContext) => string | null | Promise<string | null>;
+}
+/** Legacy single-callable form of after_llm. Maps to `onResponse`. @deprecated Pass `{ onResponse }` instead. */
+type AfterLLMLegacy = (text: string, ctx: HookContext) => string | null | Promise<string | null>;
+/** Optional callbacks fired at each stage of the STT→LLM→TTS pipeline. */
 interface PipelineHooks {
     /** Called with the raw PCM audio chunk before it is forwarded to the STT provider.
      *  Return null to drop the chunk (e.g., for custom VAD gating). */
@@ -616,10 +942,16 @@ interface PipelineHooks {
      *  Return null to keep them, or return a new list to replace
      *  (useful for prompt injection, message filtering, RAG augmentation). */
     beforeLlm?: (messages: Array<Record<string, unknown>>, ctx: HookContext) => Array<Record<string, unknown>> | null | Promise<Array<Record<string, unknown>> | null>;
-    /** Called with the final assistant text after the LLM stream completes.
-     *  Return null to keep, or return a new string to replace
-     *  (useful for output validation, redaction, post-processing). */
-    afterLlm?: (text: string, ctx: HookContext) => string | null | Promise<string | null>;
+    /**
+     * Post-LLM transform. Pass either:
+     * - the new **3-tier object** (`{ onChunk, onSentence, onResponse }`) for
+     *   streaming-friendly per-chunk / per-sentence / per-response transforms;
+     * - or the **legacy callable** `(text, ctx) => string` (deprecated) which
+     *   maps to `onResponse` semantics and blocks streaming TTS.
+     *
+     * See `AfterLLMHook` for the full tier contract.
+     */
+    afterLlm?: AfterLLMHook | AfterLLMLegacy;
     /** Called before TTS, per-sentence in streaming mode. Return null to skip TTS for this sentence. */
     beforeSynthesize?: (text: string, ctx: HookContext) => string | null | Promise<string | null>;
     /** Called after TTS produces an audio chunk. Return null to discard this chunk. */
@@ -647,11 +979,27 @@ interface BackgroundAudioPlayer$1 {
     mix(agentPcm: Buffer, sampleRate: number): Promise<Buffer>;
     stop(): Promise<void>;
 }
+/**
+ * Configuration for a local-mode voice AI agent.
+ *
+ * Several fields (``voice``, ``model``, ``language``) are also carried by
+ * engine markers (``OpenAIRealtime``, ``ElevenLabsConvAI``) and by the
+ * server-instantiated adapters. When the same setting is set in two places,
+ * precedence is:
+ *
+ * 1. **Explicit field on** ``phone.agent({ voice, model, language })`` always wins.
+ * 2. Otherwise, when an ``engine`` is passed, the engine's value is used
+ *    (see ``Patter.agent()`` for the resolution).
+ * 3. Otherwise, the AgentOptions default is used.
+ */
+/** Configuration for a local-mode voice AI agent (passed to `phone.agent({...})`). */
 interface AgentOptions {
     systemPrompt: string;
     /**
      * Voice preset. When ``engine`` is provided, its ``voice`` is used unless
-     * explicitly overridden here.
+     * explicitly overridden here. Format depends on the engine:
+     * OpenAI Realtime accepts a name (``'alloy'``, ``'echo'``, ...);
+     * ElevenLabs ConvAI accepts a voice ID.
      */
     voice?: string;
     /**
@@ -659,10 +1007,56 @@ interface AgentOptions {
      * unless explicitly overridden here.
      */
     model?: string;
+    /**
+     * BCP-47 language code (e.g. ``'en'``, ``'it'``). Forwarded to STT (in
+     * pipeline mode) and to the engine adapter at call time. STTConfig has its
+     * own ``language`` field for the rare case where STT must use a different
+     * language than the rest of the pipeline.
+     */
     language?: string;
     firstMessage?: string;
     /** Tool definitions — ``Tool`` class instances from ``getpatter``. */
     tools?: Array<Tool>;
+    /**
+     * Model Context Protocol (MCP) servers to plug into this agent. Each
+     * server is queried at call start via ``tools/list`` and its tools
+     * are merged into ``tools`` with synthetic handlers that dispatch
+     * back through the MCP client. Lets you connect to existing MCP
+     * servers (Google Workspace, PayPal, GitHub, Postgres, …) without
+     * writing a wrapper handler.
+     *
+     * Each entry is either a URL string (shorthand for
+     * ``{ url, transport: 'streamable-http' }``) or an explicit object
+     * with optional ``headers`` for auth and a ``name`` for telemetry.
+     *
+     * Requires the optional dependency ``@modelcontextprotocol/sdk``.
+     * When unset, MCP is fully disabled and the SDK ships without the
+     * dependency installed.
+     *
+     * Cost: one HTTP handshake + ``tools/list`` round-trip per server at
+     * call start (~50-200 ms × N servers). Future iterations may cache
+     * the discovered list process-wide.
+     */
+    mcpServers?: ReadonlyArray<MCPServerConfig>;
+    /**
+     * When ``true``, ship ``systemPrompt`` to the LLM verbatim. Default
+     * (``false``) prepends a phone-friendly preamble that instructs the
+     * model to avoid markdown, emojis, bullet lists, and verbose replies —
+     * the conventions live phone calls require.
+     */
+    disablePhonePreamble?: boolean;
+    /**
+     * Acoustic echo cancellation. When `true` (pipeline mode only) the SDK
+     * instantiates an `NlmsEchoCanceller` that subtracts the agent's own
+     * TTS bleed from the inbound mic stream before VAD/STT see it.
+     * Strongly recommended for speakerphone / tunnel deployments where the
+     * bleed otherwise keeps VAD permanently in "speaking" state and
+     * barge-in only fires during natural TTS pauses. Off by default —
+     * handset / headset deployments don't have the bleed, and the 0.5–2 s
+     * convergence period would briefly attenuate caller speech if they
+     * spoke before any TTS played.
+     */
+    echoCancellation?: boolean;
     /**
      * Realtime / ConvAI engine instance. When present, the agent runs in the
      * matching mode (``openai_realtime`` or ``elevenlabs_convai``). When absent,
@@ -709,8 +1103,22 @@ interface AgentOptions {
      * Default: 300.
      */
     bargeInThresholdMs?: number;
+    /**
+     * When true, the sentence chunker emits the first clause of each response
+     * on a soft punctuation boundary (",", em-dash, en-dash) once ~40 chars
+     * have accumulated. Saves 200–500 ms TTFA on the first sentence of each
+     * turn at the cost of slightly clipping prosody on the very first chunk.
+     * Hard-disabled when ``language`` starts with ``"it"`` (Italian decimal
+     * comma would split mid-number). Default: false.
+     *
+     * See SentenceChunker constructor for the full guard list (decimal,
+     * currency, balanced delimiter, ellipsis).
+     */
+    aggressiveFirstFlush?: boolean;
 }
+/** Pipeline-mode message handler — given full turn context, returns the agent's reply. */
 type PipelineMessageHandler = (data: Record<string, unknown>) => Promise<string>;
+/** Options for `Patter.serve({...})`. */
 interface ServeOptions {
     agent: AgentOptions;
     port?: number;
@@ -738,12 +1146,73 @@ interface ServeOptions {
     dashboardDb?: string;
     /** When true (default), persist dashboard data. */
     dashboardPersist?: boolean;
+    /**
+     * When true (default), `serve()` calls the carrier's API on startup to
+     * point the configured phone number's webhook URL at this server. Set
+     * to `false` when the webhook is managed externally (Terraform, an edge
+     * gateway / voice-router, or any infra-as-code system) — otherwise every
+     * boot will silently overwrite the externally-managed value.
+     *
+     * Required `false` when:
+     *   - Twilio's voice_url should point at a router/gateway in front of
+     *     this server rather than directly at it.
+     *   - Multiple replicas share the same Twilio number; only one should
+     *     write the webhook.
+     *   - Compliance forbids the runtime from holding write credentials
+     *     against the carrier console.
+     *
+     * Ignored (treated as true) when `tunnel: true`, because the tunnel
+     * hostname is dynamic and only known at runtime — the carrier MUST be
+     * reconfigured for inbound calls to land.
+     */
+    manageWebhook?: boolean;
+}
+/**
+ * Normalised AMD (answering-machine detection) result emitted to
+ * ``LocalCallOptions.onMachineDetection`` once the carrier reports back.
+ * The ``raw`` field preserves the provider value verbatim so callers can
+ * apply provider-specific logic; ``classification`` is the SDK's
+ * carrier-agnostic projection that test/acceptance code should check.
+ */
+interface MachineDetectionResult {
+    readonly call_id: string;
+    readonly carrier: 'twilio' | 'telnyx';
+    /** Carrier-agnostic projection. Use this in app code unless you really need the raw provider value. */
+    readonly classification: 'human' | 'machine' | 'fax' | 'unknown';
+    /**
+     * Raw provider value:
+     * - Twilio: ``human``, ``machine_start``, ``machine_end_beep``,
+     *   ``machine_end_silence``, ``machine_end_other``, ``fax``, ``unknown``.
+     * - Telnyx: ``human``, ``machine``, ``not_sure``.
+     */
+    readonly raw: string;
+    /** Unix epoch seconds at which the result was received from the carrier. */
+    readonly detected_at: number;
 }
+/** Options for `Patter.call({...})` to place an outbound call. */
 interface LocalCallOptions {
     to: string;
     agent: AgentOptions;
+    /**
+     * Enable answering-machine detection. **Defaults to ``true``** — the SDK
+     * asks Twilio (``MachineDetection=DetectMessageEnd`` + Async AMD) or
+     * Telnyx (``answering_machine_detection=greeting_end``) to classify
+     * whoever picks up. Async AMD on Twilio adds ~0 answer-latency on human
+     * pickups (the call connects immediately and the result arrives via
+     * webhook 2-5 s later), so ON-by-default is safe. Pass ``false`` to
+     * disable when you want to skip per-call AMD billing or you already
+     * know the destination is a human.
+     */
     machineDetection?: boolean;
-    /** If set, spoken as a voicemail message when AMD detects a machine. Requires machineDetection=true. */
+    /**
+     * Called once when the carrier finishes the AMD check. Fires for both
+     * ``human`` and ``machine`` outcomes. Combine with ``voicemailMessage``
+     * to get both the legacy voicemail-drop AND a result callback (the SDK
+     * fires the callback after the drop is queued). Acceptance tests use
+     * this to mark a run INVALID when ``classification !== 'human'``.
+     */
+    onMachineDetection?: (result: MachineDetectionResult) => void | Promise<void>;
+    /** If set, spoken as a voicemail message when AMD detects a machine. Implicitly enables ``machineDetection``. */
     voicemailMessage?: string;
     /** Dynamic variables merged into agent.variables before call. Override agent-level variables. */
     variables?: Record<string, string>;
@@ -770,6 +1239,7 @@ interface LocalCallOptions {
  * the JSONL/JSON files, the store is just a cache on top).
  */
 
+/** Snapshot of a call as held by the dashboard store. */
 interface CallRecord {
     call_id: string;
     caller: string;
@@ -792,10 +1262,12 @@ interface CallRecord {
     metrics?: Record<string, unknown> | null;
     [key: string]: unknown;
 }
+/** Server-Sent-Event payload broadcast by `MetricsStore` for live UI updates. */
 interface SSEEvent {
     type: string;
     data: Record<string, unknown>;
 }
+/** In-memory bounded ring buffer of recent calls plus active-call tracking. */
 declare class MetricsStore extends EventEmitter {
     private readonly maxCalls;
     private calls;
@@ -810,6 +1282,7 @@ declare class MetricsStore extends EventEmitter {
         maxCalls?: number;
     });
     private publish;
+    /** Mark a call as in-progress (creates the row if it does not yet exist). */
     recordCallStart(data: Record<string, unknown>): void;
     /**
      * Pre-register an outbound call before any webhook fires. Lets the
@@ -823,15 +1296,23 @@ declare class MetricsStore extends EventEmitter {
      * row from active to completed so the UI freezes the live duration timer.
      */
     updateCallStatus(callId: string, status: string, extra?: Record<string, unknown>): void;
+    /** Append a single conversation turn to an active call and broadcast it via SSE. */
     recordTurn(data: Record<string, unknown>): void;
+    /** Move a call from active to completed and persist its final metrics. */
     recordCallEnd(data: Record<string, unknown>, metrics?: Record<string, unknown> | null): void;
+    /** Return a window of completed calls in newest-first order. */
     getCalls(limit?: number, offset?: number): CallRecord[];
+    /** Look up a completed call by id (newest match wins). */
     getCall(callId: string): CallRecord | null;
     /** Look up an active call by id (returns undefined if not active or unknown). */
     getActive(callId: string): CallRecord | undefined;
+    /** Return all currently active (not yet ended) calls. */
     getActiveCalls(): CallRecord[];
+    /** Compute summary statistics across the buffered call history. */
     getAggregates(): Record<string, unknown>;
+    /** Return calls whose `started_at` falls within `[fromTs, toTs]` (Unix seconds). */
     getCallsInRange(fromTs?: number, toTs?: number): CallRecord[];
+    /** Number of completed calls currently in the ring buffer. */
     get callCount(): number;
     /**
      * Rebuild the in-memory call list from `metadata.json` files written by
@@ -846,10 +1327,185 @@ declare class MetricsStore extends EventEmitter {
     hydrate(logRoot: string | null | undefined): number;
 }
 
+/** Async-or-sync callback. Sync return values are silently ignored. */
+type SpeechEventCallback = (payload: Readonly<Record<string, unknown>>) => void | Promise<void>;
+type UserState = "listening" | "speaking" | "thinking" | "away";
+type AgentState = "initializing" | "idle" | "listening" | "thinking" | "speaking";
+interface ConversationStateSnapshot {
+    readonly user: UserState;
+    readonly agent: AgentState;
+}
+type EouTrigger = "vad_silence" | "semantic_turn_detector" | "manual_commit";
+interface UserSpeechStartedOptions {
+    readonly vadConfidence?: number;
+    readonly audioOffsetMs?: number;
+    readonly timestampMs?: number;
+}
+interface UserSpeechEndedOptions extends UserSpeechStartedOptions {
+    readonly speechDurationMs: number;
+}
+interface UserSpeechEosOptions {
+    readonly trigger: EouTrigger;
+    readonly trailingSilenceMs?: number;
+    readonly transcriptSoFar?: string;
+    readonly timestampMs?: number;
+}
+interface AgentSpeechStartedOptions {
+    readonly ttsProvider?: string;
+    readonly engine?: string;
+    readonly timestampMs?: number;
+}
+interface AgentSpeechEndedOptions {
+    readonly speechDurationMs: number;
+    readonly interrupted?: boolean;
+    readonly timestampMs?: number;
+}
+interface LlmFirstTokenOptions {
+    readonly llmProvider: string;
+    readonly model: string;
+    readonly timestampMs?: number;
+}
+interface AudioOutOptions {
+    readonly ttsProvider: string;
+    readonly timestampMs?: number;
+}
+/**
+ * Per-call dispatcher for the seven turn-taking events. A single instance is
+ * shared by every `Patter` instance and survives across calls — the per-turn
+ * state (`turnIdx`, `firstTokenForTurn`, `firstAudioForTurn`) lives here too
+ * so the runner sees a monotonically-increasing turn index across a session.
+ *
+ * Backwards compatibility: every callback defaults to `null`. Existing users
+ * who never set a callback see exactly the previous behaviour and zero
+ * overhead.
+ */
+declare class SpeechEvents {
+    onUserSpeechStarted: SpeechEventCallback | null;
+    onUserSpeechEnded: SpeechEventCallback | null;
+    onUserSpeechEos: SpeechEventCallback | null;
+    onAgentSpeechStarted: SpeechEventCallback | null;
+    onAgentSpeechEnded: SpeechEventCallback | null;
+    onLlmToken: SpeechEventCallback | null;
+    onAudioOut: SpeechEventCallback | null;
+    private userState;
+    private agentState;
+    private turnIdxValue;
+    private firstTokenForTurn;
+    private firstAudioForTurn;
+    private callStartMs;
+    /** Snapshot of the current per-side state of the call. */
+    get conversationState(): ConversationStateSnapshot;
+    /** Current 0-based turn index. Increments on every EOU commit. */
+    get turnIdx(): number;
+    /** Record the call-start wall-clock for ``audioOffsetMs`` math. */
+    markCallStarted(tsMs?: number): void;
+    /** Reset per-turn cursors. Called automatically on EOU commit. */
+    resetTurnState(): void;
+    /** Fire on the VAD positive edge of the inbound stream.
+     *
+     * Do not coalesce: the runner consumes positive→negative→positive
+     * transitions in order. For server-VAD engines (OpenAI Realtime, Telnyx
+     * Voice AI), forward the upstream signal directly — do not re-run a VAD
+     * layer on top.
+     */
+    fireUserSpeechStarted(opts?: UserSpeechStartedOptions): Promise<void>;
+    /** Fire on the VAD trailing edge (raw — *not* EOU).
+     *
+     * `speechDurationMs` is the length of the segment that just ended; the
+     * runner uses it to compute talk-ratio.
+     */
+    fireUserSpeechEnded(opts: UserSpeechEndedOptions): Promise<void>;
+    /** Fire on the committed end-of-utterance.
+     *
+     * This is the canonical "user finished" signal — VAD edge + trailing
+     * silence + (optionally) a semantic turn-detector model agreement. The
+     * runner uses the timestamp of this event to compute
+     * `eos_to_first_token_ms` (Hamming AI threshold: <800 ms good, >1500 ms
+     * critical).
+     */
+    fireUserSpeechEos(opts: UserSpeechEosOptions): Promise<void>;
+    /** Fire on the FIRST audio chunk of the current agent turn that crosses
+     * to the wire (not the first chunk produced by TTS).
+     *
+     * The user hears the wire chunk, so this is the timestamp the runner
+     * anchors barge-in latency on.
+     */
+    fireAgentSpeechStarted(opts?: AgentSpeechStartedOptions): Promise<void>;
+    /** Fire on the LAST audio chunk of the current agent turn.
+     *
+     * `interrupted=true` marks the turn as cancelled by barge-in; the runner
+     * treats it as the `agent_speech_stopped` half of a barge-in pair.
+     */
+    fireAgentSpeechEnded(opts: AgentSpeechEndedOptions): Promise<void>;
+    /** Fire on the FIRST LLM token of the current turn (TTFT marker).
+     *
+     * Idempotent within a turn — guarded by `firstTokenForTurn`. Combined
+     * with `on_user_speech_eos.timestamp_ms` the runner computes
+     * `eos_to_first_token_ms`.
+     */
+    fireLlmFirstToken(opts: LlmFirstTokenOptions): Promise<void>;
+    /** Fire on the FIRST TTS audio chunk for the current turn.
+     *
+     * Distinct from `fireAgentSpeechStarted`: this is the agent-side buffer
+     * arrival (TTS warmup), not the wire-time chunk. Idempotent within a
+     * turn — guarded by `firstAudioForTurn`.
+     */
+    fireAudioOut(opts: AudioOutOptions): Promise<void>;
+    private resolveOffset;
+    private dispatch;
+}
+
+/** Top-level SDK entry point — wraps a carrier + embedded server + agent loop. */
 declare class Patter {
     private localConfig;
     private embeddedServer;
     private tunnelHandle;
+    private _tunnelReadyResolve;
+    private _tunnelReadyReject;
+    private _tunnelReady;
+    private _readyResolve;
+    private _readyReject;
+    private _ready;
+    /**
+     * True iff ``localConfig.webhookUrl`` was populated by ``serve()`` from a
+     * freshly-started cloudflared tunnel (rather than by the constructor from
+     * an explicit ``webhookUrl`` / ``StaticTunnel`` config). ``disconnect()``
+     * uses this flag to clear ONLY the auto-assigned hostname so a subsequent
+     * ``serve()`` call (e.g. from a plugin's ``ensureServing`` cycle that
+     * disposes + restarts on agent-identity changes) does not throw
+     * ``Cannot use both tunnel: true and webhookUrl``.
+     */
+    private tunnelOwnsWebhookUrl;
+    /**
+     * Speech-edge events for turn-taking instrumentation. Public surface: the
+     * seven `on*` proxy accessors below plus the `conversationState` snapshot.
+     * Defaults are no-ops — existing users who never set a callback see exactly
+     * the previous behaviour.
+     *
+     * See `src/_speech-events.ts` for the full event taxonomy and the
+     * industry-alignment table (LiveKit / Pipecat / OpenAI Realtime).
+     */
+    readonly speechEvents: SpeechEvents;
+    get onUserSpeechStarted(): SpeechEventCallback | null;
+    set onUserSpeechStarted(cb: SpeechEventCallback | null);
+    get onUserSpeechEnded(): SpeechEventCallback | null;
+    set onUserSpeechEnded(cb: SpeechEventCallback | null);
+    get onUserSpeechEos(): SpeechEventCallback | null;
+    set onUserSpeechEos(cb: SpeechEventCallback | null);
+    get onAgentSpeechStarted(): SpeechEventCallback | null;
+    set onAgentSpeechStarted(cb: SpeechEventCallback | null);
+    get onAgentSpeechEnded(): SpeechEventCallback | null;
+    set onAgentSpeechEnded(cb: SpeechEventCallback | null);
+    get onLlmToken(): SpeechEventCallback | null;
+    set onLlmToken(cb: SpeechEventCallback | null);
+    get onAudioOut(): SpeechEventCallback | null;
+    set onAudioOut(cb: SpeechEventCallback | null);
+    /**
+     * Snapshot of the current per-side state of the call.
+     * Mirrors LiveKit's `user_state_changed` / `agent_state_changed`
+     * payloads. Read-only and safe to call at any time.
+     */
+    get conversationState(): ConversationStateSnapshot;
     /**
      * Live `MetricsStore` for the embedded server. Returns `null` before
      * `serve()` is called. Exposed so integrations like `PatterTool` can
@@ -857,12 +1513,73 @@ declare class Patter {
      * `call_start`, `call_end`).
      */
     get metricsStore(): MetricsStore | null;
+    /**
+     * Resolves to the public webhook hostname as soon as it is known —
+     * either statically configured or freshly minted by the tunnel.
+     *
+     * **Prefer `phone.ready` for outbound calls.** This promise resolves
+     * before the embedded HTTP / WebSocket server is in `listen` state, so
+     * a `phone.call` placed immediately afterwards can still race the
+     * Twilio Media Streams upgrade and produce a "11100 Invalid URL
+     * format" call drop on answer.
+     *
+     * Kept as a separate signal because some integrations (e.g. webhook
+     * registration) only need the hostname, not the WS server.
+     */
+    get tunnelReady(): Promise<string>;
+    /**
+     * Resolves to the public webhook hostname once the SDK is fully ready
+     * to handle carrier callbacks: tunnel resolved, carrier auto-config
+     * complete, and the embedded HTTP / WS server in `listen` state.
+     *
+     * Use this for outbound calls instead of guessing `setTimeout` after
+     * `void phone.serve(...)`:
+     *
+     * ```ts
+     * void phone.serve({ agent, tunnel: true });
+     * await phone.ready;
+     * await phone.call({ to: '+15550001234', agent });
+     * ```
+     *
+     * Rejects with the underlying exception if `serve()` fails before the
+     * server is listening.
+     */
+    get ready(): Promise<string>;
     constructor(options: LocalOptions);
+    /** Resolve user-supplied agent options against engine defaults and return the merged config. */
     agent(opts: AgentOptions): AgentOptions;
+    /** Boot the embedded HTTP/WebSocket server, configure the carrier webhook, and resolve `ready`. */
     serve(opts: ServeOptions): Promise<void>;
+    private _serveImpl;
+    /** Run the agent in interactive terminal-test mode (no real telephony). */
     test(opts: ServeOptions): Promise<void>;
+    /** Place an outbound call via the configured carrier. */
     call(options: LocalCallOptions): Promise<void>;
+    /**
+     * Stop the embedded server and any running tunnel. Safe to call multiple
+     * times. Leaves the instance reusable: a subsequent ``serve()`` works as
+     * if the previous lifecycle never happened.
+     */
     disconnect(): Promise<void>;
+    /**
+     * Terminate an active call on the configured carrier.
+     *
+     * Posts a hangup to the carrier (Twilio
+     * ``Calls(callSid).update({status:'completed'})`` or Telnyx
+     * ``/v2/calls/{callControlId}/actions/hangup``) so the bridge tears down
+     * gracefully — the SDK's WebSocket handler then fires ``onCallEnd`` with
+     * the final ``CallMetrics`` before the WS closes.
+     *
+     * Use this when the host application needs to end a call programmatically
+     * without going through the LLM tool-call path (e.g. an admin override,
+     * a watchdog, or an integration test runner).
+     *
+     * @param callSid - Carrier-issued call identifier (Twilio Call SID or
+     *   Telnyx call_control_id) returned from a previous ``call(...)`` or
+     *   captured in the ``onCallStart`` callback's payload.
+     * @throws Error when ``callSid`` is empty or no carrier is configured.
+     */
+    endCall(callSid: string): Promise<void>;
 }
 
 /**
@@ -909,13 +1626,23 @@ interface DefineToolInput {
  */
 declare function defineTool(input: DefineToolInput): ToolDefinition;
 
+/**
+ * Process-wide logger used by the SDK.
+ *
+ * Provides the in-library logger abstraction (`getLogger`/`setLogger`) and
+ * default console-based implementation. Library code MUST use these helpers
+ * rather than calling `console.*` directly so applications can route logs.
+ */
+/** Minimal logger interface implemented by the default console logger and any user-supplied replacement. */
 interface Logger {
     info(message: string, ...args: unknown[]): void;
     warn(message: string, ...args: unknown[]): void;
     error(message: string, ...args: unknown[]): void;
     debug(message: string, ...args: unknown[]): void;
 }
+/** Return the active logger (defaults to a console-backed implementation). */
 declare function getLogger(): Logger;
+/** Replace the process-wide logger; useful for routing SDK logs into a host app's logger. */
 declare function setLogger(logger: Logger): void;
 
 /**
@@ -925,9 +1652,6 @@ declare function setLogger(logger: Logger): void;
  * Uses regex-based marker replacement for robust sentence boundary
  * detection, handling abbreviations, acronyms, decimals, websites,
  * ellipsis, and CJK punctuation.
- *
- * Algorithm adapted from LiveKit Agents (Apache 2.0):
- * https://github.com/livekit/agents
  */
 /** Default minimum sentence length before emitting. */
 declare const DEFAULT_MIN_SENTENCE_LEN = 20;
@@ -951,9 +1675,29 @@ declare class SentenceChunker {
     private buffer;
     private readonly minSentenceLen;
     private readonly minWordsForShortFlush;
+    private readonly aggressiveFirstMinLen;
+    private readonly aggressiveFirstFlush;
+    private readonly language;
+    private isFirstFlush;
     constructor(options?: {
         minSentenceLen?: number;
         minWordsForShortFlush?: number;
+        /**
+         * When true, the chunker emits the first clause of each response on a
+         * soft punctuation boundary (",", em-dash, en-dash) once
+         * `aggressiveFirstMinLen` characters accumulate. Saves 200-500 ms TTFA
+         * on the first sentence of each turn. Subsequent sentences fall through
+         * to the standard sentence-boundary path. Default: false.
+         */
+        aggressiveFirstFlush?: boolean;
+        aggressiveFirstMinLen?: number;
+        /**
+         * BCP-47-ish language tag. Italian uses comma as decimal separator
+         * (3,14) and dot as thousands (1.000) — both invert the English
+         * convention — so aggressive comma flush is hard-disabled when language
+         * starts with "it" regardless of `aggressiveFirstFlush`. Default: "en".
+         */
+        language?: string;
     });
     /**
      * Feed a token. Returns zero or more complete sentences.
@@ -964,10 +1708,11 @@ declare class SentenceChunker {
      *   sentence, all but the last (potentially incomplete) are emitted.
      * - **Short-flush path** — when the buffer is shorter than `minSentenceLen`
      *   but ends with a sentence terminator AND has at least
-     *   `minWordsForShortFlush` whitespace-separated words, emit it
-     *   immediately. This drops TTS TTFB on short greetings like `"Hi there!"`
-     *   while keeping single-word utterances (`"Sì."`) buffered until
-     *   `flush()`.
+     *   `minWordsForShortFlush` whitespace-separated words (default 1 — a
+     *   single-word reply like `"Yes."` flushes immediately for low TTS
+     *   TTFB). Acronym ("U.S.") and decimal ("f(x) = 2.") guards still block
+     *   dangerous cases. Bump `minWordsForShortFlush` to 2+ to keep
+     *   single-word utterances buffered until `flush()`.
      */
     push(token: string): string[];
     /**
@@ -975,18 +1720,41 @@ declare class SentenceChunker {
      *
      * A buffer qualifies when **all** of these hold:
      * 1. Last non-whitespace char is a sentence terminator.
-     * 2. Word count is at least `minWordsForShortFlush` (default 2 — keeps
-     *    single-word "Sì." / "Yes." buffered until `flush()`).
+     * 2. Word count is at least `minWordsForShortFlush` (default 1 —
+     *    single-word replies like `"Yes."` flush immediately).
      * 3. The buffer contains exactly one terminator (the trailing one).
      *    Multiple terminators mean we may be mid-stream of a longer merged
      *    utterance like `"Hey! Hi! Hello! This is a sentence."` — let the
      *    standard path keep merging.
      * 4. The char immediately before the terminator is NOT a digit (avoids
      *    decimal mid-stream like `"f(x) = x * 2."` flushing before `54`).
-     * 5. The char immediately before the terminator is NOT an uppercase
-     *    ASCII letter (avoids acronym patterns like `"U.S."` / `"U."`).
+     * 5. The trailing word is NOT a short ASCII all-caps acronym of 1-3 chars
+     *    (`"U."` / `"U.S."` / `"USA."`).
+     * 6. The trailing word is NOT a known honorific from any of the
+     *    per-language `HONORIFICS_*` constants (`"Mr."`, `"Sr."`, `"Dr."`,
+     *    `"Hr."`, `"Mme."`, ...).
      */
     private maybeShortFlush;
+    /**
+     * Try to flush the first clause of the response on a soft punctuation
+     * boundary (comma / em-dash / en-dash) to minimise TTFA.
+     *
+     * Returns the flushed clause text (with terminator) or `null` if no safe
+     * boundary is found. All of these guards must pass:
+     *
+     * 1. **Min length** — buffer ≥ `aggressiveFirstMinLen` (default 40).
+     * 2. **Trailing terminator** — last non-whitespace char in `SOFT_TERMINATORS`.
+     * 3. **Decimal/thousands guard** — refuse if comma is between two digits
+     *    or surrounded by digit-thousands grouping.
+     * 4. **Currency guard** — refuse if a currency symbol appears in the
+     *    preceding 8 characters.
+     * 5. **Balanced delimiter** — refuse if open parens/brackets/braces or
+     *    unmatched double-quotes still pending.
+     * 6. **Ellipsis** — refuse if buffer ends with `...` or `…`.
+     * 7. **Sub-token ambiguity** — only fire when at least one trailing char
+     *    after the terminator has arrived.
+     */
+    private maybeAggressiveFirstFlush;
     /** Flush remaining buffer as final sentence(s). Call at end of stream. */
     flush(): string[];
     /** Discard buffered text. Call on interrupt. */
@@ -1019,21 +1787,83 @@ declare function filterEmoji(text: string): string;
  */
 declare function filterForTTS(text: string): string;
 
+/**
+ * Public error taxonomy for the Patter SDK.
+ *
+ * Every Patter exception carries a stable, machine-readable {@link ErrorCode}
+ * on its `code` property. Downstream code can branch on the code without
+ * relying on class name strings or message parsing.
+ *
+ * The class hierarchy is preserved for backward compatibility — existing
+ * `instanceof PatterConnectionError` checks keep working — and the enum is
+ * purely additive.
+ *
+ * Mirrored byte-for-byte by the Python `ErrorCode` StrEnum in
+ * `libraries/python/getpatter/exceptions.py`.
+ */
+/**
+ * Stable, machine-readable error codes attached to every Patter exception.
+ *
+ * Values are short, `UPPER_SNAKE_CASE` strings. Existing values must never
+ * change — downstream callers branch on them. New codes are additive.
+ *
+ * This is shipped as a `const` object plus value-union type rather than a
+ * TS `enum` so it's tree-shakeable and compatible with `verbatimModuleSyntax`.
+ */
+declare const ErrorCode: {
+    /** Invalid constructor args, missing required env var, frozen-config violation. */
+    readonly CONFIG: "CONFIG";
+    /** WebSocket connect failure, HTTP 5xx from provider, network error. */
+    readonly CONNECTION: "CONNECTION";
+    /** Provider rejected our credentials (HTTP 401/403, invalid signature). */
+    readonly AUTH: "AUTH";
+    /** Provider response, voicemail post, or other awaited operation timed out. */
+    readonly TIMEOUT: "TIMEOUT";
+    /** Provider returned HTTP 429. */
+    readonly RATE_LIMIT: "RATE_LIMIT";
+    /** Twilio / Telnyx webhook signature verification failed. */
+    readonly WEBHOOK_VERIFICATION: "WEBHOOK_VERIFICATION";
+    /** Caller passed a malformed phone number, tool arg, etc. */
+    readonly INPUT_VALIDATION: "INPUT_VALIDATION";
+    /** Generic catch-all for unexpected upstream provider failures. */
+    readonly PROVIDER_ERROR: "PROVIDER_ERROR";
+    /** Phone number provisioning, webhook configuration, or carrier setup failed. */
+    readonly PROVISION: "PROVISION";
+    /** Assertion failed / unexpected internal state. Likely a Patter bug. */
+    readonly INTERNAL: "INTERNAL";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Base class for every error thrown by the Patter SDK. */
 declare class PatterError extends Error {
-    constructor(message: string);
+    /** Stable, machine-readable error code. Subclasses set the default. */
+    readonly code: ErrorCode;
+    constructor(message: string, options?: {
+        code?: ErrorCode;
+    });
 }
+/** Network / WebSocket / HTTP-level connectivity failure when talking to a provider. */
 declare class PatterConnectionError extends PatterError {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        code?: ErrorCode;
+    });
 }
+/** Provider rejected our credentials (HTTP 401/403, invalid webhook signature, etc.). */
 declare class AuthenticationError extends PatterError {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        code?: ErrorCode;
+    });
 }
+/** Phone-number provisioning or carrier setup failed. */
 declare class ProvisionError extends PatterError {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        code?: ErrorCode;
+    });
 }
 /** Thrown when a provider returns HTTP 429 on connect/upgrade. */
 declare class RateLimitError extends PatterConnectionError {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        code?: ErrorCode;
+    });
 }
 
 /**
@@ -1080,14 +1910,8 @@ declare function soniox(opts: {
     apiKey: string;
     language?: string;
 }): STTConfig;
-/**
- * Speechmatics STT config helper.
- *
- * NOTE: the Speechmatics adapter is currently Python-only. Calling this helper
- * throws a clear error so callers can switch providers or use the Python SDK
- * until the TS adapter ships.
- */
-declare function speechmatics(_opts: {
+/** Speechmatics real-time STT config helper. */
+declare function speechmatics(opts: {
     apiKey: string;
     language?: string;
 }): STTConfig;
@@ -1133,8 +1957,31 @@ declare function geminiLive(opts: {
     voice?: string;
 }): RealtimeConfig;
 
+/**
+ * Billing units used by ``DEFAULT_PRICING`` entries. String values keep the
+ * pricing table JSON-serialisable and backwards-compatible with consumers
+ * that still compare against the raw strings.
+ */
+declare const PricingUnit: {
+    readonly MINUTE: "minute";
+    readonly THOUSAND_CHARS: "1k_chars";
+    readonly TOKEN: "token";
+};
+/** String value for one of the entries in `PricingUnit`. */
+type PricingUnitValue = (typeof PricingUnit)[keyof typeof PricingUnit];
+/** Per-model rate overrides — same shape as `ProviderPricing` minus the unit. */
+type ModelPricing = Omit<ProviderPricing, 'unit' | 'models'> & {
+    unit?: PricingUnitValue | string;
+};
+/** Single provider's pricing entry inside `DEFAULT_PRICING` or a user override map. */
 interface ProviderPricing {
-    unit: string;
+    /**
+     * Billing unit. The library ships with values from :data:`PricingUnit`,
+     * but the field stays ``string`` so user overrides loaded from JSON /
+     * env config (which are unconstrained at the type system) keep flowing
+     * through ``mergePricing`` without type assertions.
+     */
+    unit: PricingUnitValue | string;
     price?: number;
     audio_input_per_token?: number;
     audio_output_per_token?: number;
@@ -1142,17 +1989,51 @@ interface ProviderPricing {
     text_output_per_token?: number;
     cached_audio_input_per_token?: number;
     cached_text_input_per_token?: number;
+    /**
+     * Per-model rate overrides keyed by model identifier. When the cost-calc
+     * function receives a ``model`` arg, the matching entry overlays the
+     * provider defaults; missing models fall back to the surrounding rates
+     * (legacy behaviour). Longest-prefix match handles versioned IDs like
+     * ``gpt-realtime-2-2026-05`` against ``gpt-realtime-2``. See
+     * :func:`resolveProviderRates`.
+     */
+    models?: Record<string, ModelPricing>;
 }
+/**
+ * Built-in pricing table — overridable via `Patter({ pricing: {...} })`.
+ *
+ * Each provider entry carries provider-level defaults plus an optional
+ * `models` map for per-model overrides. When the cost-calc function gets a
+ * model arg it auto-resolves via {@link resolveProviderRates} (longest-prefix
+ * fallback for versioned model IDs). Empty/unknown model → provider defaults.
+ */
 declare const DEFAULT_PRICING: Record<string, ProviderPricing>;
 /**
  * Merge user overrides into a copy of DEFAULT_PRICING.
- * Performs a shallow per-provider merge.
+ *
+ * Performs a per-provider shallow merge with one exception: the nested
+ * ``models`` dict is itself merged shallowly (per-model entries replace
+ * the default entry but unmentioned models keep their built-in rates).
+ * A user override of ``{ deepgram: { models: { 'nova-2': { price: 0.01 } } } }``
+ * keeps every other Deepgram model rate intact.
  */
 declare function mergePricing(overrides?: Record<string, Partial<ProviderPricing>> | null): Record<string, ProviderPricing>;
-/** Calculate STT cost from audio duration. */
-declare function calculateSttCost(provider: string, audioSeconds: number, pricing: Record<string, ProviderPricing>): number;
-/** Calculate TTS cost from character count. */
-declare function calculateTtsCost(provider: string, characterCount: number, pricing: Record<string, ProviderPricing>): number;
+/**
+ * Calculate STT cost from audio duration.
+ *
+ * When ``model`` is supplied and the provider entry has a matching
+ * ``models`` override, the per-model rate is used; otherwise falls back
+ * to the provider-level rate (legacy behaviour, model omitted).
+ */
+declare function calculateSttCost(provider: string, audioSeconds: number, pricing: Record<string, ProviderPricing>, model?: string | null): number;
+/**
+ * Calculate TTS cost from character count.
+ *
+ * When ``model`` is supplied and the provider entry has a matching
+ * ``models`` override, the per-model rate is used; otherwise falls back
+ * to the provider-level rate (legacy behaviour, model omitted).
+ */
+declare function calculateTtsCost(provider: string, characterCount: number, pricing: Record<string, ProviderPricing>, model?: string | null): number;
 /**
  * Calculate OpenAI Realtime cost from token usage.
  *
@@ -1176,7 +2057,7 @@ declare function calculateRealtimeCost(usage: {
         audio_tokens?: number;
         text_tokens?: number;
     };
-}, pricing: Record<string, ProviderPricing>): number;
+}, pricing: Record<string, ProviderPricing>, model?: string | null): number;
 /**
  * Calculate telephony cost from call duration.
  *
@@ -1192,6 +2073,7 @@ declare function calculateTelephonyCost(provider: string, durationSeconds: numbe
  * Port of the Python `CallMetricsAccumulator` from `sdk/patter/services/metrics.py`.
  */
 
+/** Per-turn latency breakdown across the STT/LLM/TTS pipeline. */
 interface LatencyBreakdown {
     stt_ms: number;
     /**
@@ -1228,7 +2110,21 @@ interface LatencyBreakdown {
      * TTS audio byte sent. Optional — undefined when TTS never completed.
      */
     tts_total_ms?: number;
+    /**
+     * **User-perceived agent response latency**: time from end-of-user-speech
+     * (VAD stop or STT ``speech_final``) to the first audio byte the agent
+     * sent back. Computed as ``endpoint_ms + llm_ttft_ms + tts_ms`` when all
+     * three signals are available — falls back to undefined otherwise.
+     *
+     * This is the metric you should watch for SLO / p95 dashboards. Unlike
+     * ``total_ms`` (which spans the user's entire utterance and therefore
+     * grows with how long the user spoke), ``agent_response_ms`` isolates
+     * the system-controlled latency: silence detection + LLM TTFT + TTS
+     * first byte.
+     */
+    agent_response_ms?: number;
 }
+/** Per-call cost breakdown by component (STT/TTS/LLM/telephony) plus the total. */
 interface CostBreakdown {
     stt: number;
     tts: number;
@@ -1242,6 +2138,7 @@ interface CostBreakdown {
      */
     llm_cached_savings?: number;
 }
+/** Metrics captured for a single conversation turn. */
 interface TurnMetrics {
     turn_index: number;
     user_text: string;
@@ -1251,6 +2148,7 @@ interface TurnMetrics {
     tts_characters: number;
     timestamp: number;
 }
+/** Aggregated metrics for an entire call (turns, costs, latency percentiles). */
 interface CallMetrics {
     call_id: string;
     duration_seconds: number;
@@ -1267,6 +2165,7 @@ interface CallMetrics {
     llm_provider: string;
     telephony_provider: string;
 }
+/** Programmatic control surface for a live call (transfer, hangup, DTMF). */
 interface CallControl {
     /** Transfer the call to a different number or SIP URI. */
     transfer(number: string): Promise<void>;
@@ -1288,6 +2187,7 @@ interface CallControl {
     /** Callee number. */
     readonly callee: string;
 }
+/** Mutable per-call accumulator that stamps timestamps and emits final `CallMetrics`. */
 declare class CallMetricsAccumulator {
     callId: string;
     readonly providerMode: string;
@@ -1295,6 +2195,14 @@ declare class CallMetricsAccumulator {
     readonly sttProvider: string;
     readonly ttsProvider: string;
     readonly llmProvider: string;
+    /**
+     * Model identifiers for per-model rate resolution (see pricing.ts). Empty
+     * string means "not known" → cost calc falls back to provider defaults,
+     * matching pre-2026.3 behaviour.
+     */
+    readonly sttModel: string;
+    readonly ttsModel: string;
+    readonly realtimeModel: string;
     private readonly _pricing;
     private readonly _callStart;
     private readonly _turns;
@@ -1349,6 +2257,12 @@ declare class CallMetricsAccumulator {
         sttProvider?: string;
         ttsProvider?: string;
         llmProvider?: string;
+        /** Model identifier for the STT adapter (e.g. ``"nova-3-multilingual"``). */
+        sttModel?: string;
+        /** Model identifier for the TTS adapter (e.g. ``"eleven_multilingual_v2"``). */
+        ttsModel?: string;
+        /** Model identifier for the realtime adapter (e.g. ``"gpt-realtime-2"``). */
+        realtimeModel?: string;
         pricing?: Record<string, Partial<ProviderPricing>> | null;
         eventBus?: EventBus;
         /** When true, only the first TTFB emission per call is forwarded to the event bus. */
@@ -1363,6 +2277,7 @@ declare class CallMetricsAccumulator {
     configureSttFormat(sampleRate?: number, bytesPerSample?: number): void;
     /** Whether a turn is currently being measured (startTurn called, not yet completed). */
     get turnActive(): boolean;
+    /** Begin a new turn — stamps the turn start timestamp and resets per-turn state. */
     startTurn(): void;
     /**
      * Start a new turn only if no turn is currently open.
@@ -1370,6 +2285,7 @@ declare class CallMetricsAccumulator {
      * on the first audio byte rather than just before recordSttComplete().
      */
     startTurnIfIdle(): void;
+    /** Stamp end-of-STT, capture the user's transcript, and accrue billed STT seconds. */
     recordSttComplete(text: string, audioSeconds?: number): void;
     /** Record the timestamp of the first LLM token (TTFT). No-op after first call. */
     recordLlmFirstToken(): void;
@@ -1380,8 +2296,11 @@ declare class CallMetricsAccumulator {
      * No-op after first call.
      */
     recordLlmFirstSentenceComplete(): void;
+    /** Stamp end-of-LLM (last token received). */
     recordLlmComplete(): void;
+    /** Stamp first TTS audio byte sent on the wire (used to compute TTS TTFB). */
     recordTtsFirstByte(): void;
+    /** Record final TTS text length and stamp the last-byte timestamp. */
     recordTtsComplete(text: string): void;
     /**
      * Capture the timestamp when the last TTS audio byte was sent on the wire.
@@ -1401,7 +2320,9 @@ declare class CallMetricsAccumulator {
      * to compute ``bargein_ms``.
      */
     recordTtsStopped(ts?: number): void;
+    /** Close the current turn cleanly and append a `TurnMetrics` record. */
     recordTurnComplete(agentText: string): TurnMetrics;
+    /** Close the current turn as interrupted (barge-in) and return the recorded metrics. */
     recordTurnInterrupted(): TurnMetrics | null;
     /**
      * Record the moment VAD emitted speech_end for the current utterance.
@@ -1435,6 +2356,7 @@ declare class CallMetricsAccumulator {
      * ``transcriptionDelay``       = turnCommitted − vadStopped  (ms)
      * ``onUserTurnCompletedDelay`` = caller-supplied delta (ms) or 0
      */
+    /** Emit `EOUMetrics` once VAD-stop, STT-final, and turn-committed timestamps are all known. */
     emitEouMetrics(): void;
     /**
      * Record that a caller utterance started overlapping with agent speech.
@@ -1451,7 +2373,16 @@ declare class CallMetricsAccumulator {
      * @param ts Optional override timestamp in hrTimeMs units.
      */
     recordOverlapEnd(wasInterruption: boolean, ts?: number): void;
+    /** Accumulate inbound STT audio bytes for cost calculation when seconds are unknown. */
     addSttAudioBytes(byteCount: number): void;
+    /**
+     * Record an OpenAI Realtime usage payload and roll up its cost + cached-savings.
+     *
+     * `model` allows the cost calc to pick the per-model rate (e.g.
+     * `gpt-realtime-2`). Defaults to whatever was supplied at construction
+     * time (`this.realtimeModel`); pass an explicit value to override per-call
+     * (the `response.done` payload carries the model used).
+     */
     recordRealtimeUsage(usage: {
         input_token_details?: {
             audio_tokens?: number;
@@ -1465,8 +2396,10 @@ declare class CallMetricsAccumulator {
             audio_tokens?: number;
             text_tokens?: number;
         };
-    }): void;
+    }, model?: string | null): void;
+    /** Override the carrier-billed telephony cost (e.g. exact value reported via Twilio API). */
     setActualTelephonyCost(cost: number): void;
+    /** Override the provider-billed STT cost when an exact figure is available. */
     setActualSttCost(cost: number): void;
     /**
      * Accumulate LLM token cost for pipeline mode (non-Realtime).
@@ -1482,7 +2415,9 @@ declare class CallMetricsAccumulator {
      * @param cacheWriteTokens  Cache write tokens (billed at cache_write rate if present)
      */
     recordLlmUsage(provider: string, model: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number): void;
+    /** Finalize the call: flush any in-flight turn, compute aggregates, and return `CallMetrics`. */
     endCall(): CallMetrics;
+    /** Return the cost breakdown for the call so far without ending it. */
     getCostSoFar(): CostBreakdown;
     private _resetTurnState;
     private _computeTurnLatency;
@@ -1499,15 +2434,31 @@ declare class CallMetricsAccumulator {
     private _computePercentileLatency;
 }
 
+/**
+ * OpenAI Realtime WebSocket adapter for Patter's realtime mode.
+ *
+ * Wraps `wss://api.openai.com/v1/realtime` and exposes the unified
+ * Patter realtime contract (`connect / sendAudio / onEvent / close`) on
+ * {@link OpenAIRealtimeAdapter}. Audio negotiation defaults to
+ * `g711_ulaw` so traffic flows through Twilio/Telnyx without transcoding.
+ */
 /**
  * Supported OpenAI Realtime wire audio formats. See
  * https://platform.openai.com/docs/guides/realtime for the full list.
- * ``g711_ulaw`` matches what Twilio/Telnyx emit natively on the phone leg,
- * so no transcoding is needed. ``pcm16`` is used in the terminal test-mode
- * path and when the telephony provider negotiates L16/16000.
+ * `G711_ULAW` matches what Twilio/Telnyx emit natively on the phone leg, so
+ * no transcoding is needed. `PCM16` is used in the terminal test-mode path
+ * and when the telephony provider negotiates L16/16000.
  */
-type OpenAIRealtimeAudioFormat = 'g711_ulaw' | 'g711_alaw' | 'pcm16';
+declare const OpenAIRealtimeAudioFormat: {
+    readonly G711_ULAW: "g711_ulaw";
+    readonly G711_ALAW: "g711_alaw";
+    readonly PCM16: "pcm16";
+};
+/** Union of {@link OpenAIRealtimeAudioFormat} string values. */
+type OpenAIRealtimeAudioFormat = (typeof OpenAIRealtimeAudioFormat)[keyof typeof OpenAIRealtimeAudioFormat];
+/** Callback signature for events emitted by {@link OpenAIRealtimeAdapter}. */
 type RealtimeEventCallback = (type: string, data: unknown) => void | Promise<void>;
+/** Constructor options for {@link OpenAIRealtimeAdapter}. */
 interface OpenAIRealtimeOptions {
     temperature?: number;
     maxResponseOutputTokens?: number | 'inf';
@@ -1522,7 +2473,15 @@ interface OpenAIRealtimeOptions {
      * Increase for dictation-style flows where the user pauses mid-sentence.
      */
     silenceDurationMs?: number;
+    /**
+     * Reasoning-effort tier for `gpt-realtime-2`. When omitted the field is
+     * not sent and the server default applies. OpenAI recommends `"low"` for
+     * production voice flows — higher tiers add measurable per-turn latency.
+     * Has no effect on models that don't support the `reasoning` field.
+     */
+    reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
 }
+/** Realtime WebSocket adapter for OpenAI's `gpt-realtime` family. */
 declare class OpenAIRealtimeAdapter {
     private readonly apiKey;
     private readonly model;
@@ -1536,13 +2495,17 @@ declare class OpenAIRealtimeAdapter {
     private heartbeat;
     private currentResponseItemId;
     private currentResponseAudioMs;
+    private currentResponseFirstAudioAt;
     private readonly options;
     constructor(apiKey: string, model?: string, voice?: string, instructions?: string, tools?: Array<{
         name: string;
         description: string;
         parameters: Record<string, unknown>;
+        strict?: boolean;
     }> | undefined, audioFormat?: OpenAIRealtimeAudioFormat, options?: OpenAIRealtimeOptions);
+    /** Open the Realtime WebSocket and apply the session configuration. */
     connect(): Promise<void>;
+    /** Append a base64-encoded audio chunk to the realtime input buffer. */
     sendAudio(mulawAudio: Buffer): void;
     /**
      * Register a listener for parsed realtime events.
@@ -1553,14 +2516,54 @@ declare class OpenAIRealtimeAdapter {
      * a Set of callbacks. Use {@link offEvent} to remove one.
      */
     onEvent(callback: RealtimeEventCallback): void;
+    /** Remove a previously registered {@link onEvent} callback. */
     offEvent(callback: RealtimeEventCallback): void;
     private ensureMessageListener;
+    /** Truncate the in-flight assistant turn and cancel the active response.
+     *
+     * ``audio_end_ms`` MUST reflect what the caller actually heard, not what
+     * the server generated. OpenAI streams audio at 5-10x real-time, so the
+     * byte-derived counter overstates playback whenever the consumer cleared
+     * its playout buffer (e.g. ``send_clear``) before the audio reached the
+     * speaker. We bound the truncate point by wall-clock time since the first
+     * chunk of this response — that's the physical maximum a 1x real-time
+     * playback could have produced. Without this cap, OpenAI keeps the full
+     * generated assistant text on the transcript, and the model replays /
+     * resumes from it on the next turn — manifesting as re-greetings and
+     * mid-sentence fragments after a barge-in storm.
+     */
     cancelResponse(): void;
+    /** Inject a user text turn and request a new response. */
     sendText(text: string): Promise<void>;
+    /**
+     * Make the AI speak ``text`` as its opening line.
+     *
+     * Triggers ``response.create`` with explicit ``instructions`` that force
+     * the model to render ``text`` verbatim as its first audio utterance.
+     * This is the correct semantics for ``Agent.firstMessage`` per its
+     * docstring ("What the AI says when the callee answers").
+     *
+     * Without this, ``sendText(firstMessage)`` would inject ``text`` as
+     * ``role: user`` and the AI would *reply* to its own greeting, producing
+     * role-confused openings (e.g. a receptionist agent responding "I'd like
+     * to schedule a haircut" because it took its own first_message as a
+     * customer cue).
+     */
+    sendFirstMessage(text: string): Promise<void>;
+    /** Submit a tool/function-call result and request the next response. */
     sendFunctionResult(callId: string, result: string): Promise<void>;
+    /** Stop the heartbeat, drop listeners, and close the Realtime WebSocket. */
     close(): void;
 }
 
+/**
+ * ElevenLabs Conversational AI (ConvAI) WebSocket adapter for Patter.
+ *
+ * Wraps the `wss://api.elevenlabs.io/v1/convai/conversation` endpoint and
+ * normalises agent audio + transcript + control events into a single
+ * `onEvent(type, data)` callback. See {@link ElevenLabsConvAIAdapter}.
+ */
+/** Constructor options for {@link ElevenLabsConvAIAdapter}. */
 interface ElevenLabsConvAIOptions {
     apiKey: string;
     agentId?: string;
@@ -1573,6 +2576,7 @@ interface ElevenLabsConvAIOptions {
     useSignedUrl?: boolean;
 }
 type EventCallback = (type: string, data: unknown) => void | Promise<void>;
+/** WebSocket adapter for ElevenLabs ConvAI managed-agent conversations. */
 declare class ElevenLabsConvAIAdapter {
     private ws;
     private eventCallback;
@@ -1613,6 +2617,7 @@ declare class ElevenLabsConvAIAdapter {
      */
     static forTelnyx(apiKey: string, agentId: string, options?: Omit<ElevenLabsConvAIOptions, 'apiKey' | 'agentId' | 'outputAudioFormat' | 'inputAudioFormat'>): ElevenLabsConvAIAdapter;
     private fetchSignedUrl;
+    /** Open the ConvAI WebSocket and send the conversation init payload. */
     connect(): Promise<void>;
     private safeInvoke;
     private respondToPing;
@@ -1620,8 +2625,11 @@ declare class ElevenLabsConvAIAdapter {
     private finalizeAgentTurn;
     private scheduleSilenceDone;
     private handleMessage;
+    /** Send a caller-side audio chunk to ConvAI as a base64 `user_audio_chunk`. */
     sendAudio(audioBytes: Buffer): void;
+    /** Register the event callback that receives ConvAI server messages. */
     onEvent(callback: EventCallback): void;
+    /** Close the ConvAI WebSocket and release the event callback. */
     close(): Promise<void>;
 }
 
@@ -1632,6 +2640,7 @@ declare class ElevenLabsConvAIAdapter {
  * - HTTP webhook: onMessage="https://api.customer.com/patter/message"
  * - WebSocket: onMessage="ws://localhost:9000/stream"
  */
+/** Dispatches per-turn messages to a remote HTTP webhook or WebSocket endpoint. */
 declare class RemoteMessageHandler {
     private readonly webhookSecret;
     /**
@@ -1675,6 +2684,12 @@ declare function isRemoteUrl(onMessage: unknown): onMessage is string;
 /** Check if a URL is a WebSocket URL. */
 declare function isWebSocketUrl(url: string): boolean;
 
+/**
+ * Embedded HTTP/WebSocket server — wires Express webhooks for the configured
+ * carrier (Twilio or Telnyx) into the per-call `StreamHandler` and dashboard.
+ */
+
+/** Resolved configuration consumed by `EmbeddedServer` (carrier credentials, webhook URL, etc.). */
 interface LocalConfig {
     twilioSid?: string;
     twilioToken?: string;
@@ -1699,6 +2714,14 @@ interface LocalConfig {
      * Set to false only for local development against mock providers.
      */
     requireSignature?: boolean;
+    /**
+     * Resolved on-disk persistence root for the dashboard's call history,
+     * or ``null`` to disable. Computed by ``client.ts`` from the public
+     * ``LocalOptions.persist`` option (with ``PATTER_LOG_DIR`` env-var
+     * fallback). When ``null``, `CallLogger` is a no-op and the dashboard
+     * is in-memory-only — restarts wipe history.
+     */
+    persistRoot?: string | null;
 }
 
 /**
@@ -1709,6 +2732,7 @@ interface LocalConfig {
  * - ?token=<token> query parameter
  */
 
+/** Build an Express middleware that gates the dashboard behind a static bearer token. */
 declare function makeAuthMiddleware(token?: string): (req: Request, res: Response, next: NextFunction) => void;
 
 /**
@@ -1747,7 +2771,9 @@ declare function callsToJson(calls: CallRecord[]): string;
  *   GET /api/v1/analytics/costs         - B2B cost breakdown
  */
 
+/** Mount the dashboard UI + read-only `/api/dashboard/*` routes onto an Express app. */
 declare function mountDashboard(app: Express, store: MetricsStore, token?: string): void;
+/** Mount the B2B-style `/api/v1/*` JSON routes onto an Express app. */
 declare function mountApi(app: Express, store: MetricsStore, token?: string): void;
 
 /**
@@ -1758,11 +2784,19 @@ declare function mountApi(app: Express, store: MetricsStore, token?: string): vo
  * nothing is written to disk.
  *
  * TODO(parity): Python's `notify_dashboard` is now an async fire-and-forget
- * coroutine (see sdk-py/getpatter/dashboard/persistence.py). This TS version
+ * coroutine (see libraries/python/getpatter/dashboard/persistence.py). This TS version
  * uses `http.request` which is already non-blocking, but for parity consider
  * exposing this as `async function notifyDashboard(...): Promise<void>` so
  * call sites can `await` or `void` it explicitly, matching the Python API.
  */
+/**
+ * Fire-and-forget POST a completed call payload into a locally-running dashboard, if any.
+ *
+ * Skip entirely when ``PATTER_DASHBOARD_NOTIFY`` is set to ``0``/``false``
+ * (case-insensitive). This avoids 404 spam in the receiver's access log
+ * when callers embed Patter alongside their own HTTP server on port
+ * 8000 (e.g. agent-to-agent test runners).
+ */
 declare function notifyDashboard(callData: Record<string, unknown>, port?: number): void;
 
 /**
@@ -1774,6 +2808,7 @@ declare function notifyDashboard(callData: Record<string, unknown>, port?: numbe
  * background.
  */
 
+/** Constructor options for `FallbackLLMProvider`. */
 interface FallbackLLMProviderOptions {
     /** Number of retry attempts per provider before moving to the next (default 1). */
     readonly maxRetryPerProvider?: number;
@@ -1788,6 +2823,7 @@ declare class AllProvidersFailedError extends Error {
 declare class PartialStreamError extends Error {
     constructor(message: string);
 }
+/** LLM provider that delegates to a sequence of underlying providers, falling back on failure. */
 declare class FallbackLLMProvider implements LLMProvider {
     private readonly providers;
     private readonly availability;
@@ -1820,6 +2856,7 @@ declare class FallbackLLMProvider implements LLMProvider {
      * directly.
      */
     completeStream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<string, void, unknown>;
+    /** Streaming entry point — yields chunks from the first provider that succeeds. */
     stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
     private tryProviders;
     private markUnavailable;
@@ -1927,6 +2964,7 @@ declare const PARAMETERS_SCHEMA: {
     };
     readonly required: readonly ["to"];
 };
+/** Constructor options for `PatterTool`. */
 interface PatterToolOptions {
     /**
      * Patter instance to dial through. Must be in local mode (have a `carrier`).
@@ -1950,12 +2988,14 @@ interface PatterToolOptions {
      */
     recording?: boolean;
 }
+/** Args accepted by `PatterTool.execute()` (and the OpenAI/Anthropic/Hermes tool schemas). */
 interface PatterToolExecuteArgs {
     to: string;
     goal?: string;
     first_message?: string;
     max_duration_sec?: number;
 }
+/** Result envelope returned by `PatterTool.execute()` once the underlying call ends. */
 interface PatterToolResult {
     call_id: string;
     status: string;
@@ -1968,6 +3008,7 @@ interface PatterToolResult {
     }>;
     metrics?: Record<string, unknown> | null;
 }
+/** Wraps a live `Patter` instance as a tool callable from external agent frameworks. */
 declare class PatterTool {
     readonly name: string;
     readonly description: string;
@@ -2023,6 +3064,7 @@ declare class PatterTool {
     start(): Promise<void>;
     /** Stop the underlying Patter server (and reject any pending calls). */
     stop(): Promise<void>;
+    /** Place an outbound call and resolve once it ends with the transcript and metrics. */
     execute(args: PatterToolExecuteArgs): Promise<PatterToolResult>;
     /** Issue the outbound dial under the mutex and return its assigned call_id. */
     private acquireCallId;
@@ -2043,7 +3085,9 @@ declare class PatterTool {
  * input/output in the terminal. Useful for rapid agent development.
  */
 
+/** Drives an interactive terminal-based test "call" against an agent. */
 declare class TestSession {
+    /** Run a REPL-style session that loops user input through the agent's LLM/onMessage handler. */
     run(opts: {
         agent: AgentOptions;
         openaiKey?: string;
@@ -2056,9 +3100,8 @@ declare class TestSession {
 /**
  * Gemini Live realtime adapter.
  *
- * Partially adapted (~65% port) from LiveKit Agents
- * (livekit-plugins-google, Apache 2.0). Reframed to Patter's realtime adapter
- * surface — connect / sendAudio / onEvent / close — matching OpenAIRealtimeAdapter.
+ * Implements Patter's realtime adapter surface — connect / sendAudio /
+ * onEvent / close — matching OpenAIRealtimeAdapter.
  *
  * Uses the @google/genai SDK lazily imported at connect() so consumers that do
  * not use Gemini Live do not pay the load cost. Install with:
@@ -2073,6 +3116,7 @@ declare class TestSession {
  */
 declare const GEMINI_DEFAULT_INPUT_SR = 16000;
 declare const GEMINI_DEFAULT_OUTPUT_SR = 24000;
+/** Callback signature for events emitted by {@link GeminiLiveAdapter}. */
 type GeminiLiveEventHandler = (type: 'audio' | 'transcript_output' | 'function_call' | 'speech_started' | 'response_done' | 'error', data: unknown) => void | Promise<void>;
 interface GeminiLiveOptions {
     model?: string;
@@ -2088,6 +3132,7 @@ interface GeminiLiveOptions {
     outputSampleRate?: number;
     temperature?: number;
 }
+/** Realtime adapter for Google's Gemini Live native-audio API. */
 declare class GeminiLiveAdapter {
     private readonly apiKey;
     private readonly model;
@@ -2111,28 +3156,33 @@ declare class GeminiLiveAdapter {
      */
     private pendingToolCalls;
     constructor(apiKey: string, options?: GeminiLiveOptions);
+    /** Lazily import @google/genai, open a Live session, and start the receive loop. */
     connect(): Promise<void>;
+    /** Send a PCM audio chunk to Gemini as base64 inline data. */
     sendAudio(pcm: Buffer): void;
+    /** Send a text turn to Gemini and mark the turn complete. */
     sendText(text: string): Promise<void>;
+    /** Send a tool/function-call result back to Gemini. */
     sendFunctionResult(callId: string, result: string): Promise<void>;
+    /** No-op — Gemini Live barge-in is VAD-driven, not client-cancelled. */
     cancelResponse(): void;
+    /** Register an event handler that receives every Gemini Live event. */
     onEvent(handler: GeminiLiveEventHandler): void;
     private emit;
     private pumpReceive;
+    /** Close the Gemini Live session and stop the receive loop. */
     close(): Promise<void>;
 }
 
 /**
  * Ultravox realtime adapter.
  *
- * Partially adapted (~70% port) from LiveKit Agents
- * (livekit-plugins-ultravox, Apache 2.0). Pure WebSocket protocol — no vendor SDK.
- *
- * Reframed to Patter's connect / sendAudio / onEvent / close surface,
- * matching OpenAIRealtimeAdapter.
+ * Pure WebSocket protocol — no vendor SDK. Implements Patter's connect /
+ * sendAudio / onEvent / close surface, matching OpenAIRealtimeAdapter.
  */
 declare const ULTRAVOX_DEFAULT_API_BASE = "https://api.ultravox.ai/api";
 declare const ULTRAVOX_DEFAULT_SR = 16000;
+/** Callback signature for events emitted by {@link UltravoxRealtimeAdapter}. */
 type UltravoxEventHandler = (type: 'audio' | 'transcript_input' | 'transcript_output' | 'function_call' | 'speech_started' | 'response_done' | 'error', data: unknown) => void | Promise<void>;
 interface UltravoxOptions {
     model?: string;
@@ -2148,6 +3198,7 @@ interface UltravoxOptions {
     sampleRate?: number;
     firstMessage?: string;
 }
+/** Realtime WebSocket adapter for Ultravox managed-agent calls. */
 declare class UltravoxRealtimeAdapter {
     private readonly apiKey;
     private readonly model;
@@ -2163,14 +3214,21 @@ declare class UltravoxRealtimeAdapter {
     /** Exposed for diagnostics — true while the underlying socket is open. */
     running: boolean;
     constructor(apiKey: string, options?: UltravoxOptions);
+    /** Create the Ultravox call, fetch the joinUrl, and open the WebSocket. */
     connect(): Promise<void>;
+    /** Send a binary PCM audio chunk to the Ultravox call. */
     sendAudio(pcm: Buffer): void;
+    /** Inject a user text message into the Ultravox conversation. */
     sendText(text: string): Promise<void>;
+    /** Send a tool/function-call result back to Ultravox. */
     sendFunctionResult(callId: string, result: string): Promise<void>;
+    /** Clear the playback buffer to interrupt the agent's current response. */
     cancelResponse(): void;
+    /** Register an event handler that receives every Ultravox event. */
     onEvent(handler: UltravoxEventHandler): void;
     private emit;
     private handleMessage;
+    /** Close the Ultravox WebSocket and mark the adapter idle. */
     close(): Promise<void>;
 }
 
@@ -2185,7 +3243,9 @@ declare class UltravoxRealtimeAdapter {
  * node-cron is an optional dependency. This module imports it lazily so that
  * consumers who never schedule anything do not need it installed.
  */
+/** Callback fired by the scheduler — sync or async, return value ignored. */
 type JobCallback = () => void | Promise<void>;
+/** Handle returned by `scheduleCron`/`scheduleOnce`/`scheduleInterval` for cancellation. */
 interface ScheduleHandle {
     readonly jobId: string;
     cancel(): void;
@@ -2225,29 +3285,34 @@ declare function scheduleInterval(intervalOrOpts: number | {
  * Pure WebSocket client for the Soniox real-time STT API. Accumulates
  * `is_final` tokens and flushes them on `<end>`/`<fin>` endpoint tokens,
  * mirroring the Python `SonioxSTT` adapter.
- *
- * Adapted from LiveKit Agents (Apache 2.0):
- * https://github.com/livekit/agents
- * (source: livekit-plugins/livekit-plugins-soniox/livekit/plugins/soniox/stt.py
- *  at commit 78a66bcf79c5cea82989401c408f1dff4b961a5b)
- *
- * Speechmatics TypeScript adapter is **intentionally not ported**: the
- * official Speechmatics Voice SDK (`speechmatics.voice`) is Python-only at
- * the time of writing. Python users should install the optional
- * `speechmatics` extra; TypeScript users need to wait for an official
- * upstream SDK before this adapter can land without a WS-handshake reimpl.
  */
-interface Transcript$4 {
+/** Known Soniox real-time STT models. */
+declare const SonioxModel: {
+    readonly STT_RT_V4: "stt-rt-v4";
+    readonly STT_RT_V3: "stt-rt-v3";
+    readonly STT_RT_V2: "stt-rt-v2";
+};
+type SonioxModel = (typeof SonioxModel)[keyof typeof SonioxModel];
+/** Common PCM sample rates for Soniox streaming input. */
+declare const SonioxSampleRate: {
+    readonly HZ_8000: 8000;
+    readonly HZ_16000: 16000;
+    readonly HZ_24000: 24000;
+};
+type SonioxSampleRate = (typeof SonioxSampleRate)[keyof typeof SonioxSampleRate];
+/** Patter-normalised transcript event emitted by {@link SonioxSTT}. */
+interface Transcript$6 {
     readonly text: string;
     readonly isFinal: boolean;
     readonly confidence: number;
 }
-type TranscriptCallback$4 = (transcript: Transcript$4) => void;
+type TranscriptCallback$6 = (transcript: Transcript$6) => void;
+/** Constructor options for {@link SonioxSTT}. */
 interface SonioxSTTOptions$1 {
-    model?: string;
+    model?: SonioxModel | string;
     languageHints?: string[];
     languageHintsStrict?: boolean;
-    sampleRate?: number;
+    sampleRate?: SonioxSampleRate | number;
     numChannels?: number;
     enableSpeakerDiarization?: boolean;
     enableLanguageIdentification?: boolean;
@@ -2255,6 +3320,7 @@ interface SonioxSTTOptions$1 {
     clientReferenceId?: string;
     baseUrl?: string;
 }
+/** Streaming STT adapter for Soniox's real-time WebSocket API. */
 declare class SonioxSTT {
     private ws;
     private callbacks;
@@ -2275,12 +3341,16 @@ declare class SonioxSTT {
     /** Factory for Twilio-style 8 kHz linear PCM. */
     static forTwilio(apiKey: string, languageHints?: string[]): SonioxSTT;
     private buildConfig;
+    /** Open the streaming WebSocket and send the initial config payload. */
     connect(): Promise<void>;
     private clearKeepalive;
     private handleMessage;
     private emit;
+    /** Send a binary PCM16-LE audio chunk to Soniox for transcription. */
     sendAudio(audio: Buffer): void;
-    onTranscript(callback: TranscriptCallback$4): void;
+    /** Register a transcript listener (max 10 concurrent listeners). */
+    onTranscript(callback: TranscriptCallback$6): void;
+    /** Send the empty-frame stream terminator and close the WebSocket. */
     close(): void;
 }
 
@@ -2289,17 +3359,36 @@ declare class SonioxSTT {
  *
  * Pure `ws` transport — does NOT depend on the vendor SDK.
  */
-interface Transcript$3 {
+/** Patter-normalised transcript event emitted by {@link AssemblyAISTT}. */
+interface Transcript$5 {
     readonly text: string;
     readonly isFinal: boolean;
     readonly confidence: number;
     /** Optional event hint, e.g. `"SpeechStarted"` for barge-in signals. */
     readonly eventType?: string;
 }
-type TranscriptCallback$3 = (transcript: Transcript$3) => void;
-type AssemblyAIEncoding = 'pcm_s16le' | 'pcm_mulaw';
-type AssemblyAIModel = 'universal-streaming-english' | 'universal-streaming-multilingual' | 'u3-rt-pro' | 'whisper-rt';
-type AssemblyAIDomain = 'general' | 'medical-v1';
+type TranscriptCallback$5 = (transcript: Transcript$5) => void;
+/** Audio encodings accepted by AssemblyAI's v3 streaming endpoint. */
+declare const AssemblyAIEncoding: {
+    readonly PCM_S16LE: "pcm_s16le";
+    readonly PCM_MULAW: "pcm_mulaw";
+};
+type AssemblyAIEncoding = (typeof AssemblyAIEncoding)[keyof typeof AssemblyAIEncoding];
+/** Known AssemblyAI Universal Streaming speech models. */
+declare const AssemblyAIModel: {
+    readonly UNIVERSAL_STREAMING_ENGLISH: "universal-streaming-english";
+    readonly UNIVERSAL_STREAMING_MULTILINGUAL: "universal-streaming-multilingual";
+    readonly U3_RT_PRO: "u3-rt-pro";
+    readonly WHISPER_RT: "whisper-rt";
+};
+type AssemblyAIModel = (typeof AssemblyAIModel)[keyof typeof AssemblyAIModel];
+/** Valid `domain` values for AssemblyAI's v3 streaming endpoint. */
+declare const AssemblyAIDomain: {
+    readonly GENERAL: "general";
+    readonly MEDICAL_V1: "medical-v1";
+};
+type AssemblyAIDomain = (typeof AssemblyAIDomain)[keyof typeof AssemblyAIDomain];
+/** Constructor options for {@link AssemblyAISTT}. */
 interface AssemblyAISTTOptions$1 {
     /** One of the AssemblyAI speech models. */
     readonly model?: AssemblyAIModel;
@@ -2337,6 +3426,7 @@ interface AssemblyAISTTOptions$1 {
     /** Domain hint — must be `"general"` or `"medical-v1"`. */
     readonly domain?: AssemblyAIDomain;
 }
+/** Streaming STT adapter for AssemblyAI's v3 Universal Streaming API. */
 declare class AssemblyAISTT {
     private readonly apiKey;
     private readonly options;
@@ -2345,6 +3435,22 @@ declare class AssemblyAISTT {
     private closing;
     private reconnectAttempts;
     private terminationResolve;
+    /**
+     * Coalescing buffer for inbound audio frames. AssemblyAI's v3
+     * streaming endpoint requires each ws frame to carry 50–1000 ms of
+     * audio (server emits error 3007 below 50 ms — observed in the
+     * field as a fully-billed call with zero transcripts). Twilio sends
+     * 20 ms frames, so the SDK must batch ~3 frames before forwarding.
+     *
+     * We accumulate raw bytes here until the cumulative duration crosses
+     * the configured target (default 60 ms — comfortably above the 50 ms
+     * floor with one frame of headroom against jitter), then flush in a
+     * single `ws.send()`.
+     */
+    private chunkBuffer;
+    private chunkBufferBytes;
+    /** Target send size in bytes — recomputed lazily once encoding/sample-rate is known. */
+    private chunkBufferTargetBytes;
     /** AssemblyAI session id — set when the `Begin` message arrives. */
     sessionId: string | null;
     /** Unix timestamp when the AssemblyAI session expires. */
@@ -2354,13 +3460,21 @@ declare class AssemblyAISTT {
     static forTwilio(apiKey: string, model?: AssemblyAIModel): AssemblyAISTT;
     private buildUrl;
     private buildHeaders;
+    /** Open the streaming WebSocket and arm message handlers. */
     connect(): Promise<void>;
     private awaitOpen;
     private attachHandlers;
     private reconnect;
     private handleEvent;
     private emit;
+    /** Send a binary PCM/mu-law audio chunk to AssemblyAI for transcription. */
     sendAudio(audio: Buffer): void;
+    /**
+     * Compute the byte count corresponding to ~60 ms of audio for the
+     * configured encoding / sample rate. Sits one Twilio frame (20 ms)
+     * above AssemblyAI's 50 ms floor so jitter never dips below.
+     */
+    private computeTargetChunkBytes;
     private estimateChunkDurationMs;
     /**
      * Send an `UpdateConfiguration` frame to change settings mid-stream.
@@ -2374,7 +3488,9 @@ declare class AssemblyAISTT {
     }): void;
     /** Force the server to finalize the current turn (for barge-in). */
     forceEndpoint(): void;
-    onTranscript(callback: TranscriptCallback$3): () => void;
+    /** Register a transcript listener. Returns an unsubscribe function. */
+    onTranscript(callback: TranscriptCallback$5): () => void;
+    /** Send a Terminate frame, wait briefly for ack, and close the socket. */
     close(): Promise<void>;
 }
 
@@ -2383,32 +3499,50 @@ declare class AssemblyAISTT {
  *
  * Implements a `DeepgramSTT`-shaped provider using Cartesia's streaming
  * WebSocket API. Pure `ws` transport — does NOT depend on the vendor SDK.
- *
- * Algorithm adapted from LiveKit Agents (Apache 2.0):
- * https://github.com/livekit/agents
- * Source: livekit-plugins/livekit-plugins-cartesia/livekit/plugins/cartesia/stt.py
- * Upstream ref SHA: 78a66bcf79c5cea82989401c408f1dff4b961a5b
  */
-interface Transcript$2 {
+/** Patter-normalised transcript event emitted by {@link CartesiaSTT}. */
+interface Transcript$4 {
     readonly text: string;
     readonly isFinal: boolean;
     readonly confidence: number;
 }
-type TranscriptCallback$2 = (transcript: Transcript$2) => void;
+type TranscriptCallback$4 = (transcript: Transcript$4) => void;
+/** Known Cartesia STT models. */
+declare const CartesiaSTTModel: {
+    readonly INK_WHISPER: "ink-whisper";
+};
+type CartesiaSTTModel = (typeof CartesiaSTTModel)[keyof typeof CartesiaSTTModel];
+/** Audio encodings accepted by Cartesia's STT websocket endpoint. */
+declare const CartesiaSTTEncoding: {
+    readonly PCM_S16LE: "pcm_s16le";
+};
+type CartesiaSTTEncoding = (typeof CartesiaSTTEncoding)[keyof typeof CartesiaSTTEncoding];
+/** Common PCM sample rates accepted by Cartesia STT. */
+declare const CartesiaSTTSampleRate: {
+    readonly HZ_8000: 8000;
+    readonly HZ_16000: 16000;
+    readonly HZ_24000: 24000;
+    readonly HZ_44100: 44100;
+    readonly HZ_48000: 48000;
+};
+type CartesiaSTTSampleRate = (typeof CartesiaSTTSampleRate)[keyof typeof CartesiaSTTSampleRate];
 /** Cartesia STT currently only accepts 16-bit PCM little-endian. */
+/** Legacy encoding alias kept for callers using the bare string form. */
 type CartesiaEncoding = 'pcm_s16le';
+/** Constructor options for {@link CartesiaSTT}. */
 interface CartesiaSTTOptions$1 {
     /** Cartesia STT model. Currently only `"ink-whisper"`. */
-    readonly model?: string;
+    readonly model?: CartesiaSTTModel | string;
     /** BCP-47 language code. */
     readonly language?: string;
     /** PCM encoding; Cartesia only supports `pcm_s16le`. */
-    readonly encoding?: CartesiaEncoding;
+    readonly encoding?: CartesiaSTTEncoding | CartesiaEncoding;
     /** Sample rate in Hz. Cartesia accepts 8000, 16000, 24000, 44100, 48000. */
-    readonly sampleRate?: number;
+    readonly sampleRate?: CartesiaSTTSampleRate | number;
     /** Override base URL (HTTP or WS). Defaults to Cartesia prod. */
     readonly baseUrl?: string;
 }
+/** Streaming STT adapter for Cartesia's ink-whisper WebSocket API. */
 declare class CartesiaSTT {
     private readonly apiKey;
     private readonly options;
@@ -2422,13 +3556,16 @@ declare class CartesiaSTT {
     requestId: string | null;
     constructor(apiKey: string, options?: CartesiaSTTOptions$1);
     private buildWsUrl;
+    /** Open the streaming WebSocket and arm message + keepalive handlers. */
     connect(): Promise<void>;
     private handleEvent;
     private emit;
+    /** Send a binary PCM16-LE audio chunk to Cartesia for transcription. */
     sendAudio(audio: Buffer): void;
-    onTranscript(callback: TranscriptCallback$2): void;
+    /** Register a transcript listener. */
+    onTranscript(callback: TranscriptCallback$4): void;
     /** Remove a previously registered transcript callback. */
-    offTranscript(callback: TranscriptCallback$2): void;
+    offTranscript(callback: TranscriptCallback$4): void;
     /**
      * Synchronous best-effort close. Sends `finalize` and closes the socket
      * without waiting for the server to flush any remaining transcripts.
@@ -2446,9 +3583,35 @@ declare class CartesiaSTT {
     closeAsync(): Promise<void>;
 }
 
-type LMNTAudioFormat = 'aac' | 'mp3' | 'mulaw' | 'raw' | 'wav';
-type LMNTModel = 'blizzard' | 'aurora';
-type LMNTSampleRate = 8000 | 16000 | 24000;
+/**
+ * LMNT TTS provider — HTTP `/v1/ai/speech/bytes` endpoint.
+ *
+ * Defaults to `format='raw'` (PCM_S16LE) at 16 kHz so the output drops
+ * directly into Patter's telephony pipeline without transcoding.
+ */
+/** Supported LMNT audio output formats. `RAW` is PCM_S16LE. */
+declare const LMNTAudioFormat: {
+    readonly AAC: "aac";
+    readonly MP3: "mp3";
+    readonly MULAW: "mulaw";
+    readonly RAW: "raw";
+    readonly WAV: "wav";
+};
+type LMNTAudioFormat = (typeof LMNTAudioFormat)[keyof typeof LMNTAudioFormat];
+/** LMNT TTS model families. */
+declare const LMNTModel: {
+    readonly BLIZZARD: "blizzard";
+    readonly AURORA: "aurora";
+};
+type LMNTModel = (typeof LMNTModel)[keyof typeof LMNTModel];
+/** Supported PCM sample rates for LMNT raw output. */
+declare const LMNTSampleRate: {
+    readonly HZ_8000: 8000;
+    readonly HZ_16000: 16000;
+    readonly HZ_24000: 24000;
+};
+type LMNTSampleRate = (typeof LMNTSampleRate)[keyof typeof LMNTSampleRate];
+/** Constructor options for {@link LMNTTTS}. */
 interface LMNTTTSOptions$1 {
     model?: LMNTModel;
     voice?: string;
@@ -2459,6 +3622,7 @@ interface LMNTTTSOptions$1 {
     topP?: number;
     baseUrl?: string;
 }
+/** LMNT TTS adapter backed by the `/v1/ai/speech/bytes` HTTP streaming endpoint. */
 declare class LMNTTTS {
     private readonly apiKey;
     private readonly model;
@@ -2471,12 +3635,23 @@ declare class LMNTTTS {
     private readonly baseUrl;
     constructor(apiKey: string, opts?: LMNTTTSOptions$1);
     private buildPayload;
+    /** Synthesize text and return the concatenated audio buffer. */
     synthesize(text: string): Promise<Buffer>;
     /** Yield audio chunks as they arrive — raw PCM_S16LE by default. */
     synthesizeStream(text: string): AsyncGenerator<Buffer>;
 }
 
+/**
+ * Deepgram streaming STT adapter for the Patter SDK pipeline mode.
+ *
+ * Pure `ws` transport — connects to `wss://api.deepgram.com/v1/listen` with
+ * a long-lived KeepAlive pump and emits Patter-normalised {@link Transcript}
+ * events through {@link DeepgramSTT.onTranscript}. See {@link DeepgramSTT}
+ * for the public class.
+ */
+/** Which Deepgram server event a {@link Transcript} represents. */
 type TranscriptEventType = 'Results' | 'UtteranceEnd' | 'SpeechStarted';
+/** Per-word timing/confidence record returned by Deepgram in `words[]`. */
 interface DeepgramWord {
     readonly word?: string;
     readonly start?: number;
@@ -2485,7 +3660,8 @@ interface DeepgramWord {
     readonly punctuated_word?: string;
     readonly speaker?: number;
 }
-interface Transcript$1 {
+/** Patter-normalised transcript event emitted by {@link DeepgramSTT}. */
+interface Transcript$3 {
     readonly text: string;
     readonly isFinal: boolean;
     readonly confidence: number;
@@ -2500,8 +3676,8 @@ interface Transcript$1 {
     /** Which provider event this Transcript represents. Default ``Results``. */
     readonly eventType?: TranscriptEventType;
 }
-type TranscriptCallback$1 = (transcript: Transcript$1) => void;
-type ErrorCallback = (error: Error) => void;
+type TranscriptCallback$3 = (transcript: Transcript$3) => void;
+type ErrorCallback$1 = (error: Error) => void;
 /**
  * Optional tuning knobs for Deepgram live transcription.
  *
@@ -2539,6 +3715,7 @@ interface DeepgramSTTOptions$1 {
     /** Emit VAD events (``SpeechStarted`` / ``UtteranceEnd``). Default ``true``. */
     readonly vadEvents?: boolean;
 }
+/** Streaming STT adapter for Deepgram's `/v1/listen` WebSocket API. */
 declare class DeepgramSTT {
     private ws;
     private readonly transcriptCallbacks;
@@ -2572,6 +3749,7 @@ declare class DeepgramSTT {
     /** Factory for Twilio calls — mulaw 8 kHz. Forwards tuning options through. */
     static forTwilio(apiKey: string, language?: string, model?: string, options?: DeepgramSTTOptions$1): DeepgramSTT;
     private buildUrl;
+    /** Open the streaming WebSocket and arm message + keepalive handlers. */
     connect(): Promise<void>;
     private openSocket;
     private clearKeepalive;
@@ -2580,11 +3758,31 @@ declare class DeepgramSTT {
     private emitError;
     private handleError;
     private handleClose;
+    /** Send a binary audio chunk to Deepgram for transcription. */
     sendAudio(audio: Buffer): void;
-    onTranscript(callback: TranscriptCallback$1): void;
-    offTranscript(callback: TranscriptCallback$1): void;
-    onError(callback: ErrorCallback): void;
-    offError(callback: ErrorCallback): void;
+    private audioSentCount;
+    private audioDroppedCount;
+    /** Register a transcript listener. */
+    onTranscript(callback: TranscriptCallback$3): void;
+    /** Remove a previously registered transcript listener. */
+    offTranscript(callback: TranscriptCallback$3): void;
+    /** Register an error listener for socket / API failures. */
+    onError(callback: ErrorCallback$1): void;
+    /** Remove a previously registered error listener. */
+    offError(callback: ErrorCallback$1): void;
+    /**
+     * Force Deepgram to immediately emit a final ``Results`` frame for the
+     * in-flight utterance, rather than waiting for its own endpoint
+     * heuristic (utterance_end_ms ~1 s + natural-pause endpointing).
+     * Called by the SDK on VAD ``speech_end`` and after barge-in cancel —
+     * both moments where the SDK already knows the user has stopped
+     * speaking and waiting for Deepgram's own endpointing only adds
+     * dead air.
+     *
+     * Idempotent: safe to call when the socket is closed/closing.
+     */
+    finalize(): void;
+    /** Send Finalize, briefly drain trailing transcripts, then close the socket. */
     close(): void;
 }
 
@@ -2605,7 +3803,7 @@ type DeepgramSTTOptions = DeepgramSTTOptions$1 & {
  * const stt = new deepgram.STT({ apiKey: "dg_...", endpointingMs: 80 });
  * ```
  */
-declare class STT$5 extends DeepgramSTT {
+declare class STT$6 extends DeepgramSTT {
     static readonly providerKey = "deepgram";
     constructor(opts?: DeepgramSTTOptions);
 }
@@ -2616,13 +3814,16 @@ declare class STT$5 extends DeepgramSTT {
  * Buffers incoming PCM16 audio and periodically sends it to the
  * OpenAI Whisper transcription API as a WAV file.
  */
-interface Transcript {
+/** Patter-normalised transcript event emitted by {@link WhisperSTT}. */
+interface Transcript$2 {
     readonly text: string;
     readonly isFinal: boolean;
     readonly confidence: number;
 }
-type TranscriptCallback = (transcript: Transcript) => void;
+type TranscriptCallback$2 = (transcript: Transcript$2) => void;
+/** Response format requested from `POST /v1/audio/transcriptions`. */
 type WhisperResponseFormat = 'json' | 'verbose_json';
+/** Buffered STT adapter for OpenAI's Whisper transcription HTTP API. */
 declare class WhisperSTT {
     private readonly apiKey;
     private readonly model;
@@ -2649,7 +3850,9 @@ declare class WhisperSTT {
     constructor(apiKey: string, language?: string, model?: string, bufferSize?: number, responseFormat?: WhisperResponseFormat);
     /** Factory for Twilio calls — mulaw 8 kHz is transcoded upstream, so we still receive PCM 16-bit. */
     static forTwilio(apiKey: string, language?: string, model?: string): WhisperSTT;
+    /** Reset the audio buffer and arm the adapter for incoming chunks. */
     connect(): Promise<void>;
+    /** Buffer a PCM16 chunk; flushes to Whisper once `bufferSize` bytes are reached. */
     sendAudio(audio: Buffer): void;
     private flushChunks;
     private trackTranscription;
@@ -2658,14 +3861,17 @@ declare class WhisperSTT {
      * which capped at 10 and silently replaced the last one, we now keep all
      * registered callbacks in a Set; use {@link offTranscript} to remove one.
      */
-    onTranscript(callback: TranscriptCallback): void;
-    offTranscript(callback: TranscriptCallback): void;
+    onTranscript(callback: TranscriptCallback$2): void;
+    /** Remove a previously registered transcript listener. */
+    offTranscript(callback: TranscriptCallback$2): void;
+    /** Flush any buffered audio, await pending transcriptions, and clear listeners. */
     close(): Promise<void>;
     private transcribeBuffer;
 }
 
 /** OpenAI Whisper STT for Patter pipeline mode. */
 
+/** Constructor options for the Whisper `STT` adapter. */
 interface WhisperSTTOptions {
     /** API key. Falls back to OPENAI_API_KEY env var when omitted. */
     apiKey?: string;
@@ -2685,7 +3891,7 @@ interface WhisperSTTOptions {
  * const stt = new whisper.STT({ apiKey: "sk-...", language: "en" });
  * ```
  */
-declare class STT$4 extends WhisperSTT {
+declare class STT$5 extends WhisperSTT {
     static readonly providerKey = "whisper";
     constructor(opts?: WhisperSTTOptions);
 }
@@ -2705,6 +3911,7 @@ declare class STT$4 extends WhisperSTT {
  * ``whisper-1``.
  */
 
+/** STT adapter restricted to OpenAI's GPT-4o Transcribe model family. */
 declare class OpenAITranscribeSTT extends WhisperSTT {
     /**
      * @param apiKey OpenAI API key.
@@ -2719,6 +3926,7 @@ declare class OpenAITranscribeSTT extends WhisperSTT {
 
 /** OpenAI GPT-4o Transcribe STT for Patter pipeline mode. */
 
+/** Constructor options for the OpenAI Transcribe `STT` adapter. */
 interface OpenAITranscribeSTTOptions {
     /** API key. Falls back to OPENAI_API_KEY env var when omitted. */
     apiKey?: string;
@@ -2742,13 +3950,14 @@ interface OpenAITranscribeSTTOptions {
  * const stt = new openaiTranscribe.STT({ apiKey: "sk-...", language: "en" });
  * ```
  */
-declare class STT$3 extends OpenAITranscribeSTT {
+declare class STT$4 extends OpenAITranscribeSTT {
     static readonly providerKey = "openai_transcribe";
     constructor(opts?: OpenAITranscribeSTTOptions);
 }
 
 /** Cartesia streaming STT for Patter pipeline mode. */
 
+/** Constructor options for the Cartesia `STT` adapter. */
 interface CartesiaSTTOptions {
     /** API key. Falls back to CARTESIA_API_KEY env var when omitted. */
     apiKey?: string;
@@ -2768,13 +3977,14 @@ interface CartesiaSTTOptions {
  * const stt = new cartesia.STT({ apiKey: "..." });
  * ```
  */
-declare class STT$2 extends CartesiaSTT {
+declare class STT$3 extends CartesiaSTT {
     static readonly providerKey = "cartesia_stt";
     constructor(opts?: CartesiaSTTOptions);
 }
 
 /** Soniox streaming STT for Patter pipeline mode. */
 
+/** Constructor options for the Soniox `STT` adapter. */
 interface SonioxSTTOptions {
     /** API key. Falls back to SONIOX_API_KEY env var when omitted. */
     apiKey?: string;
@@ -2799,13 +4009,14 @@ interface SonioxSTTOptions {
  * const stt = new soniox.STT({ apiKey: "..." });
  * ```
  */
-declare class STT$1 extends SonioxSTT {
+declare class STT$2 extends SonioxSTT {
     static readonly providerKey = "soniox";
     constructor(opts?: SonioxSTTOptions);
 }
 
 /** AssemblyAI Universal Streaming STT for Patter pipeline mode. */
 
+/** Constructor options for the AssemblyAI `STT` adapter. */
 interface AssemblyAISTTOptions {
     /** API key. Falls back to ASSEMBLYAI_API_KEY env var when omitted. */
     apiKey?: string;
@@ -2814,6 +4025,17 @@ interface AssemblyAISTTOptions {
     sampleRate?: number;
     baseUrl?: string;
     languageDetection?: boolean;
+    /**
+     * BCP-47 language hint (e.g. ``"it"``, ``"en"``). AssemblyAI does NOT
+     * expose a per-call language override — the language is determined by
+     * the chosen ``model`` (English-only models reject non-English audio,
+     * multilingual models auto-detect). This field is accepted for
+     * cross-provider parity with ``DeepgramSTT``/``WhisperSTT``/
+     * ``OpenAITranscribeSTT``/``CartesiaSTT`` but is currently a no-op:
+     * pick a multilingual ``model`` (e.g. ``universal-streaming-pro``)
+     * and the provider will detect Italian automatically.
+     */
+    language?: string;
     endOfTurnConfidenceThreshold?: number;
     minTurnSilence?: number;
     maxTurnSilence?: number;
@@ -2835,31 +4057,234 @@ interface AssemblyAISTTOptions {
  * const stt = new assemblyai.STT({ apiKey: "..." });
  * ```
  */
-declare class STT extends AssemblyAISTT {
+declare class STT$1 extends AssemblyAISTT {
     static readonly providerKey = "assemblyai";
     constructor(opts?: AssemblyAISTTOptions);
 }
 
+/**
+ * Speechmatics Speech-to-Text adapter for the Patter SDK pipeline mode.
+ *
+ * Streams PCM audio to the Speechmatics real-time WebSocket API
+ * (`wss://eu.rt.speechmatics.com/v2`) and emits Patter-normalised
+ * {@link Transcript} events. Mirrors `SpeechmaticsSTT` in the Python SDK.
+ *
+ * Divergence from Python: the Python adapter wraps the official
+ * `speechmatics-voice` Python SDK (Voice Agent presets, smart turn
+ * detection, etc.). No equivalent Node SDK is published, so this TypeScript
+ * adapter speaks the underlying RT v2 wire protocol directly via `ws`.
+ * The user-facing options (`turnDetectionMode`, `endOfUtteranceSilenceTrigger`,
+ * `maxDelay`, `enablePartials`, `enableDiarization`, `additionalVocab`,
+ * `operatingPoint`, `domain`, `outputLocale`, `language`, `sampleRate`) all
+ * map 1:1 onto the Python adapter so callers can switch SDKs without
+ * changing their config.
+ */
+/** Patter-normalised transcript event emitted by {@link SpeechmaticsSTT}. */
+interface Transcript$1 {
+    readonly text: string;
+    readonly isFinal: boolean;
+    readonly confidence: number;
+}
+type TranscriptCallback$1 = (transcript: Transcript$1) => void;
+type ErrorCallback = (error: Error) => void;
+/**
+ * Endpoint / turn-detection handling mode. Mirrors the values accepted by
+ * Python's `TurnDetectionMode`. Maps onto Speechmatics's
+ * `conversation_config` knobs on the wire.
+ */
+declare const TurnDetectionMode: {
+    readonly EXTERNAL: "external";
+    readonly FIXED: "fixed";
+    readonly ADAPTIVE: "adaptive";
+    readonly SMART_TURN: "smart_turn";
+};
+type TurnDetectionMode = (typeof TurnDetectionMode)[keyof typeof TurnDetectionMode];
+/** Common PCM sample rates for Speechmatics streaming input. */
+declare const SpeechmaticsSampleRate: {
+    readonly HZ_8000: 8000;
+    readonly HZ_16000: 16000;
+    readonly HZ_44100: 44100;
+};
+type SpeechmaticsSampleRate = (typeof SpeechmaticsSampleRate)[keyof typeof SpeechmaticsSampleRate];
+/** Audio encodings accepted by Speechmatics's real-time API. */
+declare const SpeechmaticsAudioEncoding: {
+    readonly PCM_S16LE: "pcm_s16le";
+};
+type SpeechmaticsAudioEncoding = (typeof SpeechmaticsAudioEncoding)[keyof typeof SpeechmaticsAudioEncoding];
+/** Speechmatics operating points (accuracy vs latency trade-off). */
+declare const SpeechmaticsOperatingPoint: {
+    readonly ENHANCED: "enhanced";
+    readonly STANDARD: "standard";
+};
+type SpeechmaticsOperatingPoint = (typeof SpeechmaticsOperatingPoint)[keyof typeof SpeechmaticsOperatingPoint];
+/** Speechmatics RT server-message type names emitted to the client. */
+declare const SpeechmaticsServerMessage: {
+    readonly RECOGNITION_STARTED: "RecognitionStarted";
+    readonly ADD_PARTIAL_TRANSCRIPT: "AddPartialTranscript";
+    readonly ADD_TRANSCRIPT: "AddTranscript";
+    readonly END_OF_UTTERANCE: "EndOfUtterance";
+    readonly END_OF_TRANSCRIPT: "EndOfTranscript";
+    readonly AUDIO_ADDED: "AudioAdded";
+    readonly INFO: "Info";
+    readonly WARNING: "Warning";
+    readonly ERROR: "Error";
+};
+type SpeechmaticsServerMessage = (typeof SpeechmaticsServerMessage)[keyof typeof SpeechmaticsServerMessage];
+/** Constructor options for {@link SpeechmaticsSTT}. */
+interface SpeechmaticsSTTOptions$1 {
+    /** Override the realtime endpoint (default `wss://eu.rt.speechmatics.com/v2`). */
+    readonly baseUrl?: string;
+    /** BCP-47 language code. Default `"en"`. */
+    readonly language?: string;
+    /** Endpoint / turn-detection mode. Default `"adaptive"`. */
+    readonly turnDetectionMode?: TurnDetectionMode;
+    /** PCM sample rate (Hz). Default 16000. */
+    readonly sampleRate?: SpeechmaticsSampleRate | number;
+    /** Attach speaker IDs to transcripts. Default `false`. */
+    readonly enableDiarization?: boolean;
+    /** Max latency in seconds before the engine emits finals. Range 0.7..4.0. */
+    readonly maxDelay?: number;
+    /** Silence (s) that triggers EOU. Range (0, 2). */
+    readonly endOfUtteranceSilenceTrigger?: number;
+    /** Max EOU delay (s); must exceed `endOfUtteranceSilenceTrigger`. */
+    readonly endOfUtteranceMaxDelay?: number;
+    /** Include partial transcripts in interim output. Default `true`. */
+    readonly includePartials?: boolean;
+    /** Additional vocabulary entries (`{content, sounds_like?}`). */
+    readonly additionalVocab?: ReadonlyArray<Record<string, unknown>>;
+    /** Operating point (`enhanced` | `standard`). */
+    readonly operatingPoint?: SpeechmaticsOperatingPoint;
+    /** Optional Speechmatics domain (e.g. `"finance"`). */
+    readonly domain?: string;
+    /** Optional output locale (e.g. `"en-GB"`). */
+    readonly outputLocale?: string;
+}
+/**
+ * Streaming STT adapter for Speechmatics's RT v2 WebSocket API.
+ *
+ * @example
+ * ```ts
+ * const stt = new SpeechmaticsSTT('sm_api_key', { language: 'en' });
+ * stt.onTranscript((t) => console.log(t.text, t.isFinal));
+ * await stt.connect();
+ * stt.sendAudio(pcm16Chunk);
+ * stt.close();
+ * ```
+ */
+declare class SpeechmaticsSTT {
+    private ws;
+    private readonly transcriptCallbacks;
+    private readonly errorCallbacks;
+    private running;
+    /** Sequence number of the last audio chunk acknowledged via `AudioAdded`. */
+    private lastSeqNo;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly language;
+    private readonly turnDetectionMode;
+    private readonly sampleRate;
+    private readonly enableDiarization;
+    private readonly maxDelay;
+    private readonly endOfUtteranceSilenceTrigger;
+    private readonly endOfUtteranceMaxDelay;
+    private readonly includePartials;
+    private readonly additionalVocab;
+    private readonly operatingPoint;
+    private readonly domain;
+    private readonly outputLocale;
+    constructor(apiKey: string, options?: SpeechmaticsSTTOptions$1);
+    /** Build the JSON `StartRecognition` payload sent on connect. */
+    private buildStartRecognition;
+    /** Open the streaming WebSocket and send the `StartRecognition` frame. */
+    connect(): Promise<void>;
+    /** Send a binary PCM16-LE audio chunk to Speechmatics for transcription. */
+    sendAudio(audio: Buffer): void;
+    /** Register a transcript listener. */
+    onTranscript(callback: TranscriptCallback$1): void;
+    /** Remove a previously registered transcript listener. */
+    offTranscript(callback: TranscriptCallback$1): void;
+    /** Register an error listener for socket / API failures. */
+    onError(callback: ErrorCallback): void;
+    /** Remove a previously registered error listener. */
+    offError(callback: ErrorCallback): void;
+    private handleMessage;
+    /** Translate a Speechmatics transcript message into a Patter `Transcript`. */
+    private toTranscript;
+    private emitTranscript;
+    private emitError;
+    private handleError;
+    private handleClose;
+    /** Send `EndOfStream` and close the WebSocket. Idempotent. */
+    close(): void;
+}
+
+/** Speechmatics streaming STT for Patter pipeline mode. */
+
+type SpeechmaticsSTTOptions = SpeechmaticsSTTOptions$1 & {
+    /** API key. Falls back to SPEECHMATICS_API_KEY env var when omitted. */
+    apiKey?: string;
+};
+/**
+ * Speechmatics streaming STT.
+ *
+ * @example
+ * ```ts
+ * import * as speechmatics from "getpatter/stt/speechmatics";
+ * const stt = new speechmatics.STT();              // reads SPEECHMATICS_API_KEY
+ * const stt = new speechmatics.STT({ apiKey: "sm_...", language: "en" });
+ * ```
+ */
+declare class STT extends SpeechmaticsSTT {
+    static readonly providerKey = "speechmatics";
+    constructor(opts?: SpeechmaticsSTTOptions);
+}
+
 /**
  * Known stable ElevenLabs voice models (from the official ElevenLabs API
- * reference). Provided as a string-literal union for autocomplete + type
- * narrowing; the public ``modelId`` option also accepts ``string`` so
- * users can pass forward-compat IDs we haven't enumerated yet.
- *
- * - ``eleven_v3`` — newest, highest quality (slower TTFT than Flash).
- * - ``eleven_flash_v2_5`` — current default, fastest (~75 ms TTFT).
- * - ``eleven_turbo_v2_5`` — balanced quality/speed.
- * - ``eleven_multilingual_v2`` — best multilingual support.
- * - ``eleven_monolingual_v1`` — legacy English-only.
- */
-type ElevenLabsModel = 'eleven_v3' | 'eleven_flash_v2_5' | 'eleven_turbo_v2_5' | 'eleven_multilingual_v2' | 'eleven_monolingual_v1';
-type ElevenLabsOutputFormat = 'mp3_22050_32' | 'mp3_44100_32' | 'mp3_44100_64' | 'mp3_44100_96' | 'mp3_44100_128' | 'mp3_44100_192' | 'pcm_8000' | 'pcm_16000' | 'pcm_22050' | 'pcm_24000' | 'pcm_44100' | 'ulaw_8000';
+ * reference). Exposed as a typed `as const` object so callers can pass
+ * `ElevenLabsModel.FLASH_V2_5` and get autocomplete / static checking; the
+ * public `modelId` option also accepts an arbitrary `string` so users can
+ * pass forward-compat IDs we haven't enumerated yet.
+ *
+ * - `V3` — newest, highest quality (slower TTFT than Flash).
+ * - `FLASH_V2_5` — current default, fastest (~75 ms TTFT).
+ * - `TURBO_V2_5` — balanced quality/speed.
+ * - `MULTILINGUAL_V2` — best multilingual support.
+ * - `MONOLINGUAL_V1` — legacy English-only.
+ */
+declare const ElevenLabsModel: {
+    readonly V3: "eleven_v3";
+    readonly FLASH_V2_5: "eleven_flash_v2_5";
+    readonly TURBO_V2_5: "eleven_turbo_v2_5";
+    readonly MULTILINGUAL_V2: "eleven_multilingual_v2";
+    readonly MONOLINGUAL_V1: "eleven_monolingual_v1";
+};
+/** Union of {@link ElevenLabsModel} string values. */
+type ElevenLabsModel = (typeof ElevenLabsModel)[keyof typeof ElevenLabsModel];
+declare const ElevenLabsOutputFormat: {
+    readonly MP3_22050_32: "mp3_22050_32";
+    readonly MP3_44100_32: "mp3_44100_32";
+    readonly MP3_44100_64: "mp3_44100_64";
+    readonly MP3_44100_96: "mp3_44100_96";
+    readonly MP3_44100_128: "mp3_44100_128";
+    readonly MP3_44100_192: "mp3_44100_192";
+    readonly PCM_8000: "pcm_8000";
+    readonly PCM_16000: "pcm_16000";
+    readonly PCM_22050: "pcm_22050";
+    readonly PCM_24000: "pcm_24000";
+    readonly PCM_44100: "pcm_44100";
+    readonly ULAW_8000: "ulaw_8000";
+};
+/** Union of {@link ElevenLabsOutputFormat} string values. */
+type ElevenLabsOutputFormat = (typeof ElevenLabsOutputFormat)[keyof typeof ElevenLabsOutputFormat];
+/** ElevenLabs voice tuning knobs forwarded as `voice_settings` in the request. */
 interface ElevenLabsVoiceSettings {
     stability?: number;
     similarity_boost?: number;
     style?: number;
     use_speaker_boost?: boolean;
 }
+/** Constructor options for {@link ElevenLabsTTS}. */
 interface ElevenLabsTTSOptions$1 {
     voiceId?: string;
     /**
@@ -2951,16 +4376,25 @@ declare class ElevenLabsTTS {
 
 /** ElevenLabs TTS for Patter pipeline mode. */
 
+/** Constructor options for the ElevenLabs `TTS` adapter. */
 interface ElevenLabsTTSOptions {
     /** API key. Falls back to ELEVENLABS_API_KEY env var when omitted. */
-    apiKey?: string;
-    voiceId?: string;
+    readonly apiKey?: string;
+    readonly voiceId?: string;
     /**
      * ElevenLabs voice model ID. Default is ``eleven_flash_v2_5`` (lowest TTFT).
      * Pass ``eleven_v3`` for highest quality, or any string for forward-compat.
      */
-    modelId?: ElevenLabsModel | string;
-    outputFormat?: string;
+    readonly modelId?: ElevenLabsModel | string;
+    readonly outputFormat?: string;
+    /**
+     * BCP-47 language code (e.g. `"it"`, `"es"`). Forwarded to ElevenLabs as
+     * the `language_code` request body field — required for multilingual /
+     * Flash v2.5 voices to render the right accent.
+     */
+    readonly languageCode?: string;
+    /** ElevenLabs `voice_settings` object (stability, similarity_boost, …). */
+    readonly voiceSettings?: Record<string, unknown>;
 }
 /** Options for the carrier-specific factories — same as the constructor minus `outputFormat`. */
 type ElevenLabsCarrierOptions = Omit<ElevenLabsTTSOptions, "outputFormat">;
@@ -2979,17 +4413,180 @@ type ElevenLabsCarrierOptions = Omit<ElevenLabsTTSOptions, "outputFormat">;
  * 16 kHz, native Telnyx default) on phone calls to skip the SDK-side
  * resampling / transcoding step.
  */
-declare class TTS$4 extends ElevenLabsTTS {
+declare class TTS$6 extends ElevenLabsTTS {
     static readonly providerKey = "elevenlabs";
     constructor(opts?: ElevenLabsTTSOptions);
     /** Pipeline TTS pre-configured for Twilio Media Streams (`ulaw_8000`). */
-    static forTwilio(opts?: ElevenLabsCarrierOptions): TTS$4;
-    static forTwilio(apiKey: string, options?: Omit<ElevenLabsTTSOptions, "outputFormat">): TTS$4;
+    static forTwilio(opts?: ElevenLabsCarrierOptions): TTS$6;
+    static forTwilio(apiKey: string, options?: Omit<ElevenLabsTTSOptions, "outputFormat">): TTS$6;
     /** Pipeline TTS pre-configured for Telnyx (`pcm_16000`). */
-    static forTelnyx(opts?: ElevenLabsCarrierOptions): TTS$4;
-    static forTelnyx(apiKey: string, options?: Omit<ElevenLabsTTSOptions, "outputFormat">): TTS$4;
+    static forTelnyx(opts?: ElevenLabsCarrierOptions): TTS$6;
+    static forTelnyx(apiKey: string, options?: Omit<ElevenLabsTTSOptions, "outputFormat">): TTS$6;
+}
+
+/**
+ * WebSocket-based ElevenLabs TTS provider — opt-in low-latency variant.
+ *
+ * Targets the ElevenLabs streaming-input WebSocket endpoint
+ * (`/v1/text-to-speech/{voice_id}/stream-input`) instead of the HTTP
+ * `/stream` endpoint used by `ElevenLabsTTS`. Saves the HTTP request setup
+ * time per utterance (~50 ms) and avoids the HTTP cold-start TLS handshake
+ * when calls are bursty.
+ *
+ * API matches `ElevenLabsTTS` (`synthesizeStream(text)` returns an
+ * `AsyncGenerator<Buffer>`) so it can be passed anywhere a TTSAdapter is
+ * expected.
+ *
+ * Behaviour notes
+ * - WebSocket is opened **per-utterance** (matches HTTP semantics). A
+ *   future revision may pool a WS across utterances of the same call
+ *   session — see roadmap Phase 5b.
+ * - `auto_mode=true` is enabled by default. Pass `autoMode: false` to
+ *   send a custom `chunk_length_schedule`.
+ * - `outputFormat` is exposed as a query parameter so `ulaw_8000` (Twilio
+ *   native) and `pcm_16000` (Telnyx native) work without resampling.
+ * - `eleven_v3` is **not** supported — the WS endpoint rejects it.
+ * - `optimize_streaming_latency` is officially deprecated and is not
+ *   exposed.
+ */
+
+/** Constructor options for {@link ElevenLabsWebSocketTTS}. */
+interface ElevenLabsWebSocketTTSOptions {
+    apiKey: string;
+    voiceId?: string;
+    modelId?: ElevenLabsModel | string;
+    outputFormat?: string;
+    voiceSettings?: Record<string, unknown>;
+    languageCode?: string;
+    /** Let the server pick chunk timing. Default true. */
+    autoMode?: boolean;
+    /** WS keep-alive timeout in seconds (5–180). Default 60. */
+    inactivityTimeout?: number;
+    /**
+     * Manual chunk schedule, only used when ``autoMode: false``. Each value
+     * must be 5–500. ElevenLabs default is ``[120, 160, 250, 290]``.
+     */
+    chunkLengthSchedule?: number[];
+    /** Outgoing audio re-chunk size in bytes. Default 4096. */
+    chunkSize?: number;
+}
+/** WebSocket-based ElevenLabs TTS adapter — opt-in low-latency variant. */
+declare class ElevenLabsWebSocketTTS implements TTSAdapter {
+    static readonly providerKey = "elevenlabs_ws";
+    readonly apiKey: string;
+    readonly voiceId: string;
+    readonly modelId: string;
+    readonly voiceSettings?: Record<string, unknown>;
+    readonly languageCode?: string;
+    readonly autoMode: boolean;
+    readonly inactivityTimeout: number;
+    readonly chunkLengthSchedule?: number[];
+    readonly chunkSize: number;
+    /**
+     * The wire format requested over the ElevenLabs WS. Initially set from
+     * the constructor; ``setTelephonyCarrier`` may auto-flip it to the
+     * carrier's native codec when the caller did NOT pass ``outputFormat``
+     * explicitly.
+     */
+    private _outputFormat;
+    private readonly _outputFormatExplicit;
+    /** Public read-only view of the (possibly auto-flipped) wire format. */
+    get outputFormat(): string;
+    constructor(opts: ElevenLabsWebSocketTTSOptions);
+    /**
+     * Hook called by ``StreamHandler`` to advise the carrier wire format.
+     *
+     * When the user did NOT pass an explicit ``outputFormat`` in the
+     * constructor options, this flips the format to the carrier's native
+     * wire codec — saving a client-side transcode step. Calling with an
+     * unknown carrier (``""`` / ``"custom"``) is a no-op.
+     *
+     * When ``outputFormat`` was explicitly passed (incl. via the
+     * ``forTwilio`` / ``forTelnyx`` factories), this method is a no-op —
+     * the user's choice always wins.
+     */
+    setTelephonyCarrier(carrier: string): void;
+    /** Pre-configured for Twilio Media Streams (`ulaw_8000`). */
+    static forTwilio(opts: Omit<ElevenLabsWebSocketTTSOptions, 'outputFormat'>): ElevenLabsWebSocketTTS;
+    /** Pre-configured for Telnyx (`pcm_16000`). */
+    static forTelnyx(opts: Omit<ElevenLabsWebSocketTTSOptions, 'outputFormat'>): ElevenLabsWebSocketTTS;
+    private buildUrl;
+    /**
+     * Single-shot synthesis: open WS, send text, yield bytes, close.
+     *
+     * Resilience contract:
+     * - Connection bounded by ``CONNECT_TIMEOUT_MS`` (5s, was 15s).
+     * - Each idle wait bounded by ``FRAME_TIMEOUT_MS`` (30s) so a stalled
+     *   server cannot keep the generator alive indefinitely.
+     * - Permanent error handler attached BEFORE the open await — prevents
+     *   ``uncaughtException`` if an error fires after the once-listener
+     *   resolves.
+     * - All event listeners removed in ``finally`` (no closure leak past
+     *   socket close).
+     * - Server-reported ``error`` raises ``ElevenLabsTTSError``.
+     * - Per-frame audio payload capped at ``MAX_AUDIO_B64_BYTES``.
+     * - Best-effort EOS ``{"text":""}`` sent in finally (not immediately
+     *   after flush — auto_mode could otherwise truncate the tail audio).
+     */
+    synthesizeStream(text: string): AsyncGenerator<Buffer>;
+    /** No-op — connections are per-utterance and torn down inside synthesizeStream. */
+    close(): Promise<void>;
 }
 
+/** ElevenLabs WebSocket TTS for Patter pipeline mode (opt-in low-latency). */
+
+/** Constructor options for the ElevenLabs WebSocket `TTS` adapter. */
+interface ElevenLabsWebSocketOptions {
+    /** API key. Falls back to ELEVENLABS_API_KEY env var when omitted. */
+    apiKey?: string;
+    voiceId?: string;
+    modelId?: ElevenLabsModel | string;
+    outputFormat?: string;
+    /** Let the server pick chunk timing. Default true. */
+    autoMode?: boolean;
+    voiceSettings?: Record<string, unknown>;
+    languageCode?: string;
+    /** WS keep-alive timeout in seconds (5–180). Default 60. */
+    inactivityTimeout?: number;
+    /** Manual chunk schedule, only used when ``autoMode: false``. */
+    chunkLengthSchedule?: number[];
+}
+/** Options for the carrier-specific factories — same as the constructor minus `outputFormat`. */
+type ElevenLabsWebSocketCarrierOptions = Omit<ElevenLabsWebSocketOptions, 'outputFormat'>;
+/**
+ * ElevenLabs streaming TTS over WebSocket.
+ *
+ * Drop-in replacement for `getpatter/tts/elevenlabs.TTS` (HTTP) using the
+ * `stream-input` WebSocket endpoint. Saves the per-utterance HTTP request
+ * setup time; otherwise behaves identically.
+ *
+ * @example
+ * ```ts
+ * import * as elevenlabsWs from "getpatter/tts/elevenlabs-ws";
+ * const tts = new elevenlabsWs.TTS();              // reads ELEVENLABS_API_KEY
+ * const tts = elevenlabsWs.TTS.forTwilio({ apiKey: "..." });
+ * ```
+ *
+ * **Telephony optimisation** — use {@link TTS.forTwilio} (μ-law @ 8 kHz)
+ * or {@link TTS.forTelnyx} (PCM @ 16 kHz) on phone calls.
+ */
+declare class TTS$5 extends ElevenLabsWebSocketTTS {
+    static readonly providerKey = "elevenlabs_ws";
+    constructor(opts?: ElevenLabsWebSocketOptions);
+    /** WebSocket TTS pre-configured for Twilio Media Streams (`ulaw_8000`). */
+    static forTwilio(opts?: ElevenLabsWebSocketCarrierOptions): TTS$5;
+    /** WebSocket TTS pre-configured for Telnyx (`pcm_16000`). */
+    static forTelnyx(opts?: ElevenLabsWebSocketCarrierOptions): TTS$5;
+}
+
+/**
+ * OpenAI TTS adapter for Patter — HTTP `/v1/audio/speech` endpoint.
+ *
+ * Wraps `gpt-4o-mini-tts` (and legacy `tts-1*`) and ships a stateful
+ * 24 kHz → 16/8 kHz resampler with anti-alias LPF so the output drops
+ * directly into the telephony pipeline. See {@link OpenAITTS}.
+ */
+/** OpenAI TTS adapter with built-in streaming resample to 16/8 kHz. */
 declare class OpenAITTS {
     private readonly apiKey;
     private readonly voice;
@@ -2997,7 +4594,8 @@ declare class OpenAITTS {
     private readonly instructions;
     private readonly speed;
     private readonly antiAlias;
-    constructor(apiKey: string, voice?: string, model?: string, instructions?: string | null, speed?: number | null, antiAlias?: boolean);
+    private readonly targetSampleRate;
+    constructor(apiKey: string, voice?: string, model?: string, instructions?: string | null, speed?: number | null, antiAlias?: boolean, targetSampleRate?: number);
     /**
      * Synthesise text to speech and return the full audio as a single Buffer.
      *
@@ -3017,29 +4615,36 @@ declare class OpenAITTS {
      */
     synthesizeStream(text: string): AsyncGenerator<Buffer>;
     /**
-     * Streaming 24 kHz → 16 kHz resampler (PCM16-LE). Applies a single-pole
-     * lowpass ahead of the 3:2 decimation and carries filter + sample state
-     * across chunks so the cadence doesn't reset at every network read.
+     * Streaming 24 kHz → {16, 8} kHz resampler (PCM16-LE). Applies a single-pole
+     * lowpass ahead of the decimation and carries filter + sample state across
+     * chunks so the cadence doesn't reset at every network read.
+     *
+     * Output rate is selected by ``ctx.targetSampleRate``:
+     *   16000 → 3:2 decimation (sample 0 + mid(1,2))   [default]
+     *    8000 → 3:1 decimation (sample 0 only)         [fix #46]
      *
-     * ``ctx.lpfEnabled`` (default true on the streaming path, false for the
-     * legacy static helper) controls whether the LPF is engaged — we keep
-     * the helper bit-exact for the downsample-only tests while the real
-     * streaming path gets anti-alias filtering.
+     * ``ctx.lpfEnabled`` controls whether the LPF is engaged — kept disabled
+     * for the legacy static helper so the bit-exact downsample-only tests
+     * remain valid; the real streaming path always engages it.
      */
     static resampleStreaming(audio: Buffer, ctx: ResampleCtx): Buffer;
     /** @deprecated use {@link resampleStreaming} with persistent state. */
     static resample24kTo16k(audio: Buffer): Buffer;
 }
+/** Streaming-resample state passed across calls to {@link OpenAITTS.resampleStreaming}. */
 interface ResampleCtx {
     carryByte: number | null;
     leftover: number[];
     lpfPrev: number;
     /** Enable the single-pole lowpass ahead of decimation. Default true. */
     lpfEnabled?: boolean;
+    /** Final output sample rate. 16000 = 3:2 decimation, 8000 = 3:1. */
+    targetSampleRate?: number;
 }
 
 /** OpenAI TTS for Patter pipeline mode. */
 
+/** Constructor options for the OpenAI `TTS` adapter. */
 interface OpenAITTSOptions {
     /** API key. Falls back to OPENAI_API_KEY env var when omitted. */
     apiKey?: string;
@@ -3066,22 +4671,70 @@ interface OpenAITTSOptions {
  * const tts = new openai.TTS({ apiKey: "sk-...", voice: "alloy" });
  * ```
  */
-declare class TTS$3 extends OpenAITTS {
+declare class TTS$4 extends OpenAITTS {
     static readonly providerKey = "openai_tts";
     constructor(opts?: OpenAITTSOptions);
 }
 
+/**
+ * Cartesia TTS provider — HTTP `/tts/bytes` endpoint.
+ *
+ * Cartesia also offers a WebSocket streaming mode with word timestamps;
+ * this provider focuses on the chunked-bytes HTTP API which maps cleanly
+ * onto Patter's `synthesize(text)` contract and keeps the provider
+ * dependency-free (just `fetch`).
+ *
+ * Default model is `sonic-3` (GA snapshot `sonic-3-2026-01-12`) — Cartesia's
+ * current GA model with a documented ~90 ms TTFB target. Voice IDs from the
+ * sonic-2 generation (including the default Katie voice) remain compatible.
+ *
+ * **Telephony optimization** — the constructor default
+ * `sampleRate=16000` is correct for web playback, dashboard previews, and
+ * 16 kHz pipelines. For real phone calls, use the carrier-specific
+ * factories instead:
+ *
+ * - {@link CartesiaTTS.forTwilio} requests `sampleRate=8000` natively from
+ *   Cartesia. Twilio's media-stream WebSocket expects μ-law @ 8 kHz, so
+ *   the SDK normally resamples 16 kHz → 8 kHz before doing the PCM →
+ *   μ-law transcode in `TwilioAudioSender`. Asking Cartesia for 8 kHz
+ *   PCM at the source skips the resample step (saves ~10–30 ms first-
+ *   byte plus per-frame CPU and removes a potential aliasing source).
+ *   The PCM → μ-law transcode still happens client-side.
+ * - {@link CartesiaTTS.forTelnyx} requests `sampleRate=16000`. Telnyx
+ *   negotiates L16/16000 on its bidirectional media WebSocket, so
+ *   16 kHz PCM is already the format used end-to-end and no
+ *   transcoding happens. This is the same as the bare-constructor
+ *   default and exists for API symmetry with the Twilio factory.
+ */
+/** Known Cartesia TTS models. */
+declare const CartesiaTTSModel: {
+    readonly SONIC_3: "sonic-3";
+    readonly SONIC_2: "sonic-2";
+    readonly SONIC: "sonic";
+};
+type CartesiaTTSModel = (typeof CartesiaTTSModel)[keyof typeof CartesiaTTSModel];
+/** Common PCM sample rates accepted by the Cartesia bytes endpoint. */
+declare const CartesiaTTSSampleRate: {
+    readonly HZ_8000: 8000;
+    readonly HZ_16000: 16000;
+    readonly HZ_22050: 22050;
+    readonly HZ_24000: 24000;
+    readonly HZ_44100: 44100;
+};
+type CartesiaTTSSampleRate = (typeof CartesiaTTSSampleRate)[keyof typeof CartesiaTTSSampleRate];
+/** Constructor options for {@link CartesiaTTS}. */
 interface CartesiaTTSOptions$1 {
-    model?: string;
+    model?: CartesiaTTSModel | string;
     voice?: string;
     language?: string;
-    sampleRate?: number;
+    sampleRate?: CartesiaTTSSampleRate | number;
     speed?: string | number;
     emotion?: string | string[];
     volume?: number;
     baseUrl?: string;
     apiVersion?: string;
 }
+/** Cartesia TTS provider backed by the HTTP `/tts/bytes` streaming endpoint. */
 declare class CartesiaTTS {
     private readonly apiKey;
     private readonly model;
@@ -3126,6 +4779,7 @@ declare class CartesiaTTS {
 
 /** Cartesia TTS for Patter pipeline mode. */
 
+/** Constructor options for the Cartesia `TTS` adapter. */
 interface CartesiaTTSOptions {
     /** API key. Falls back to CARTESIA_API_KEY env var when omitted. */
     apiKey?: string;
@@ -3160,17 +4814,18 @@ type CartesiaCarrierOptions = Omit<CartesiaTTSOptions, "sampleRate">;
  * or {@link TTS.forTelnyx} (PCM @ 16 kHz, native Telnyx default) on
  * phone calls.
  */
-declare class TTS$2 extends CartesiaTTS {
+declare class TTS$3 extends CartesiaTTS {
     static readonly providerKey = "cartesia_tts";
     constructor(opts?: CartesiaTTSOptions);
     /** Pipeline TTS pre-configured for Twilio Media Streams (PCM @ 8 kHz). */
-    static forTwilio(opts?: CartesiaCarrierOptions): TTS$2;
-    static forTwilio(apiKey: string, options?: Omit<CartesiaTTSOptions, "sampleRate">): TTS$2;
+    static forTwilio(opts?: CartesiaCarrierOptions): TTS$3;
+    static forTwilio(apiKey: string, options?: Omit<CartesiaTTSOptions, "sampleRate">): TTS$3;
     /** Pipeline TTS pre-configured for Telnyx (PCM @ 16 kHz). */
-    static forTelnyx(opts?: CartesiaCarrierOptions): TTS$2;
-    static forTelnyx(apiKey: string, options?: Omit<CartesiaTTSOptions, "sampleRate">): TTS$2;
+    static forTelnyx(opts?: CartesiaCarrierOptions): TTS$3;
+    static forTelnyx(apiKey: string, options?: Omit<CartesiaTTSOptions, "sampleRate">): TTS$3;
 }
 
+/** Constructor options for {@link RimeTTS}. */
 interface RimeTTSOptions$1 {
     model?: string;
     speaker?: string;
@@ -3186,6 +4841,7 @@ interface RimeTTSOptions$1 {
     phonemizeBetweenBrackets?: boolean;
     baseUrl?: string;
 }
+/** Rime TTS adapter for the `users.rime.ai/v1/rime-tts` HTTP streaming endpoint. */
 declare class RimeTTS {
     private readonly apiKey;
     private readonly model;
@@ -3204,6 +4860,7 @@ declare class RimeTTS {
     private readonly totalTimeoutMs;
     constructor(apiKey: string, opts?: RimeTTSOptions$1);
     private buildPayload;
+    /** Synthesize text and return the concatenated audio buffer. */
     synthesize(text: string): Promise<Buffer>;
     /**
      * Synthesize text and yield raw PCM_S16LE chunks at the configured
@@ -3214,6 +4871,7 @@ declare class RimeTTS {
 
 /** Rime TTS for Patter pipeline mode. */
 
+/** Constructor options for the Rime `TTS` adapter. */
 interface RimeTTSOptions {
     /** API key. Falls back to RIME_API_KEY env var when omitted. */
     apiKey?: string;
@@ -3241,13 +4899,14 @@ interface RimeTTSOptions {
  * const tts = new rime.TTS({ apiKey: "...", speaker: "astra" });
  * ```
  */
-declare class TTS$1 extends RimeTTS {
+declare class TTS$2 extends RimeTTS {
     static readonly providerKey = "rime";
     constructor(opts?: RimeTTSOptions);
 }
 
 /** LMNT TTS for Patter pipeline mode. */
 
+/** Constructor options for the LMNT `TTS` adapter. */
 interface LMNTTTSOptions {
     /** API key. Falls back to LMNT_API_KEY env var when omitted. */
     apiKey?: string;
@@ -3270,13 +4929,135 @@ interface LMNTTTSOptions {
  * const tts = new lmnt.TTS({ apiKey: "...", voice: "leah" });
  * ```
  */
-declare class TTS extends LMNTTTS {
+declare class TTS$1 extends LMNTTTS {
     static readonly providerKey = "lmnt";
     constructor(opts?: LMNTTTSOptions);
 }
 
+/**
+ * Inworld TTS provider — HTTP NDJSON streaming endpoint.
+ *
+ * Calls `POST https://api.inworld.ai/tts/v1/voice:stream`. The response is
+ * NDJSON: one JSON object per line of the form
+ *   `{"result": {"audioContent": "<base64-PCM_S16LE>", "timestampInfo": ...}}`
+ *
+ * The default config requests `audioEncoding=PCM` at 16 kHz so the output drops
+ * straight into the Patter pipeline without transcoding. Inworld TTS-2 is the
+ * default model — pass `model: "inworld-tts-1.5-max"` for the prior generation.
+ */
+/** Inworld TTS model families. */
+declare const InworldModel: {
+    readonly TTS_2: "inworld-tts-2";
+    readonly TTS_1_5_MAX: "inworld-tts-1.5-max";
+    readonly TTS_1_5_MINI: "inworld-tts-1.5-mini";
+    readonly TTS_1_MAX: "inworld-tts-1-max";
+    readonly TTS_1: "inworld-tts-1";
+};
+type InworldModel = (typeof InworldModel)[keyof typeof InworldModel];
+/** Inworld audio encoding values accepted by the REST API. */
+declare const InworldAudioEncoding: {
+    readonly PCM: "PCM";
+    readonly LINEAR16: "LINEAR16";
+    readonly OGG_OPUS: "OGG_OPUS";
+    readonly MP3: "MP3";
+};
+type InworldAudioEncoding = (typeof InworldAudioEncoding)[keyof typeof InworldAudioEncoding];
+/** TTS-2 stability mode (ignored by older models). */
+declare const InworldDeliveryMode: {
+    readonly EXPRESSIVE: "EXPRESSIVE";
+    readonly BALANCED: "BALANCED";
+    readonly STABLE: "STABLE";
+};
+type InworldDeliveryMode = (typeof InworldDeliveryMode)[keyof typeof InworldDeliveryMode];
+/** Constructor options for {@link InworldTTS}. */
+interface InworldTTSOptions$1 {
+    /** Model id. Defaults to `"inworld-tts-2"`. */
+    model?: InworldModel | string;
+    /** Voice name (e.g. `"Ashley"`, `"Olivia"`, `"Craig"`, `"Remy"`). */
+    voice?: string;
+    /** BCP-47 language tag, e.g. `"en"`, `"it"`, `"es"`. */
+    language?: string;
+    /** Output audio encoding. Defaults to `"PCM"` (raw PCM_S16LE). */
+    audioEncoding?: InworldAudioEncoding | string;
+    /** Output sample rate in Hz. Defaults to 16000. */
+    sampleRate?: number;
+    /** Bitrate hint (bits/sec) — used for OGG_OPUS / MP3. Default 64000. */
+    bitrate?: number;
+    /** Sampling temperature 0.0–2.0 (TTS-1.5 only — ignored by TTS-2). */
+    temperature?: number;
+    /** Speaking rate multiplier 0.5–1.5. Default 1.0. */
+    speakingRate?: number;
+    /** Stability mode for TTS-2 (`EXPRESSIVE` / `BALANCED` / `STABLE`). */
+    deliveryMode?: InworldDeliveryMode | string;
+    /** Override the REST endpoint (e.g. for on-prem deployments). */
+    baseUrl?: string;
+}
+/**
+ * Inworld TTS over the `/tts/v1/voice:stream` HTTP NDJSON endpoint.
+ *
+ * The Inworld dashboard provides a Base64 token that is already in the form
+ * expected by the `Authorization: Basic <token>` header — pass it as-is. If
+ * you only have the raw API key string, base64-encode `${apiKey}:` yourself
+ * before calling the constructor.
+ */
+declare class InworldTTS {
+    private readonly authToken;
+    private readonly model;
+    private readonly voice;
+    private readonly language?;
+    private readonly audioEncoding;
+    private readonly sampleRate;
+    private readonly bitrate;
+    private readonly temperature?;
+    private readonly speakingRate;
+    private readonly deliveryMode?;
+    private readonly baseUrl;
+    constructor(authToken: string, opts?: InworldTTSOptions$1);
+    private buildPayload;
+    /** Synthesize text and return the concatenated audio buffer. */
+    synthesize(text: string): Promise<Buffer>;
+    /**
+     * Yield audio chunks as they arrive. With the default `audioEncoding=PCM`
+     * these are raw PCM_S16LE bytes at `sampleRate`.
+     */
+    synthesizeStream(text: string): AsyncGenerator<Buffer>;
+}
+
+/** Inworld TTS for Patter pipeline mode. */
+
+/** Constructor options for the Inworld `TTS` adapter. */
+interface InworldTTSOptions {
+    /** Inworld Base64 auth token. Falls back to INWORLD_API_KEY env var. */
+    apiKey?: string;
+    model?: InworldModel | string;
+    voice?: string;
+    language?: string;
+    audioEncoding?: InworldAudioEncoding | string;
+    sampleRate?: number;
+    bitrate?: number;
+    temperature?: number;
+    speakingRate?: number;
+    deliveryMode?: InworldDeliveryMode | string;
+    baseUrl?: string;
+}
+/**
+ * Inworld TTS — defaults to the TTS-2 model.
+ *
+ * @example
+ * ```ts
+ * import * as inworld from "getpatter/tts/inworld";
+ * const tts = new inworld.TTS();                        // reads INWORLD_API_KEY
+ * const tts = new inworld.TTS({ apiKey: "...", voice: "Olivia", language: "en" });
+ * ```
+ */
+declare class TTS extends InworldTTS {
+    static readonly providerKey = "inworld";
+    constructor(opts?: InworldTTSOptions);
+}
+
 /** OpenAI LLM for Patter pipeline mode. */
 
+/** Constructor options for the OpenAI Chat Completions `LLM` adapter. */
 interface OpenAILLMOptions {
     /** API key. Falls back to OPENAI_API_KEY env var when omitted. */
     apiKey?: string;
@@ -3327,16 +5108,8 @@ declare class LLM$4 extends OpenAILLMProvider {
  * Anthropic shape and the vendor event stream is normalised back into
  * Patter's ``{ type: 'text' | 'tool_call' | 'done' }`` chunk protocol.
  *
- * Portions adapted from LiveKit Agents
- * (https://github.com/livekit/agents, commit
- * 78a66bcf79c5cea82989401c408f1dff4b961a5b,
- * file livekit-plugins/livekit-plugins-anthropic/livekit/plugins/anthropic/llm.py),
- * licensed under Apache License 2.0. Copyright 2023 LiveKit, Inc.
- *
- * Adaptations from the LiveKit source:
- *   * Ported the Python async class pair (``llm.LLM`` /
- *     ``llm.LLMStream``) into a single TypeScript class that satisfies
- *     Patter's ``LLMProvider`` interface.
+ * Implementation notes:
+ *   * Single TypeScript class satisfying Patter's ``LLMProvider`` interface.
  *   * Uses native ``fetch`` + SSE parsing instead of the official
  *     ``@anthropic-ai/sdk`` to keep Patter's runtime dependencies lean
  *     (mirrors how ``OpenAILLMProvider`` is implemented in
@@ -3346,6 +5119,7 @@ declare class LLM$4 extends OpenAILLMProvider {
  *     chunk protocol.
  */
 
+/** Constructor options for {@link AnthropicLLMProvider}. */
 interface AnthropicLLMOptions$1 {
     apiKey: string;
     model?: string;
@@ -3377,11 +5151,13 @@ declare class AnthropicLLMProvider implements LLMProvider {
     private readonly anthropicVersion;
     private readonly promptCaching;
     constructor(options: AnthropicLLMOptions$1);
-    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+    /** Stream Patter-format LLM chunks for the given OpenAI-style chat history. */
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
 }
 
 /** Anthropic Claude LLM for Patter pipeline mode. */
 
+/** Constructor options for the Anthropic Claude `LLM` adapter. */
 interface AnthropicLLMOptions {
     /** API key. Falls back to ANTHROPIC_API_KEY env var when omitted. */
     apiKey?: string;
@@ -3430,20 +5206,11 @@ declare class LLM$3 extends AnthropicLLMProvider {
  *
  * Groq exposes an OpenAI-compatible Chat Completions API. We reuse the
  * streaming code path by implementing the same SSE parser as
- * ``OpenAILLMProvider`` but pointed at ``api.groq.com``.
- *
- * Portions adapted from LiveKit Agents
- * (https://github.com/livekit/agents, commit
- * 78a66bcf79c5cea82989401c408f1dff4b961a5b,
- * file livekit-plugins/livekit-plugins-groq/livekit/plugins/groq/services.py),
- * licensed under Apache License 2.0. Copyright LiveKit, Inc.
- *
- * Adaptations from the LiveKit source:
- *   * Ported the Python ``groq.LLM`` subclass (which subclasses the
- *     LiveKit OpenAI plugin) into a tiny TypeScript wrapper that swaps
- *     the base URL and defaults to ``llama-3.3-70b-versatile``.
+ * ``OpenAILLMProvider`` but pointed at ``api.groq.com``. Defaults to
+ * ``llama-3.3-70b-versatile``.
  */
 
+/** Constructor options for {@link GroqLLMProvider}. */
 interface GroqLLMOptions$1 {
     apiKey: string;
     model?: string;
@@ -3485,11 +5252,13 @@ declare class GroqLLMProvider implements LLMProvider {
     private readonly presencePenalty?;
     private readonly stop?;
     constructor(options: GroqLLMOptions$1);
-    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+    /** Stream Patter-format LLM chunks from the Groq chat completions API. */
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
 }
 
 /** Groq LLM for Patter pipeline mode. */
 
+/** Constructor options for the Groq `LLM` adapter. */
 interface GroqLLMOptions {
     /** API key. Falls back to GROQ_API_KEY env var when omitted. */
     apiKey?: string;
@@ -3542,21 +5311,14 @@ declare class LLM$2 extends GroqLLMProvider {
  * compression to reduce TTFT for requests with large prompts
  * (see https://inference-docs.cerebras.ai/payload-optimization).
  *
- * Portions adapted from LiveKit Agents
- * (https://github.com/livekit/agents, commit
- * 78a66bcf79c5cea82989401c408f1dff4b961a5b,
- * file livekit-plugins/livekit-plugins-cerebras/livekit/plugins/cerebras/llm.py),
- * licensed under Apache License 2.0. Copyright 2026 LiveKit, Inc.
- *
- * Adaptations from the LiveKit source:
- *   * LiveKit's ``cerebras.LLM`` subclasses the LiveKit OpenAI plugin.
- *     Patter's analogue is a tiny wrapper around ``fetch`` that swaps
- *     the base URL and default model.
- *   * The msgpack payload optimisation from LiveKit is Python-only
- *     (msgpack in Node land isn't as standard); only gzip compression
- *     is ported. Enable with ``gzipCompression: true``.
+ * Implementation notes:
+ *   * Tiny wrapper around ``fetch`` that swaps the base URL and default
+ *     model relative to the OpenAI-compatible API.
+ *   * Gzip compression of the request body is supported via
+ *     ``gzipCompression: true`` (default).
  */
 
+/** Constructor options for {@link CerebrasLLMProvider}. */
 interface CerebrasLLMOptions$1 {
     apiKey: string;
     model?: string;
@@ -3624,11 +5386,13 @@ declare class CerebrasLLMProvider implements LLMProvider {
     private readonly presencePenalty?;
     private readonly stop?;
     constructor(options: CerebrasLLMOptions$1);
-    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+    /** Stream Patter-format LLM chunks from the Cerebras chat completions API. */
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
 }
 
 /** Cerebras LLM for Patter pipeline mode. */
 
+/** Constructor options for the Cerebras `LLM` adapter. */
 interface CerebrasLLMOptions {
     /** API key. Falls back to CEREBRAS_API_KEY env var when omitted. */
     apiKey?: string;
@@ -3685,23 +5449,16 @@ declare class LLM$1 extends CerebrasLLMProvider {
  * and ``tools`` shapes, and streamed response parts are normalised to
  * Patter's ``{ type: 'text' | 'tool_call' | 'done' }`` chunks.
  *
- * Portions adapted from LiveKit Agents
- * (https://github.com/livekit/agents, commit
- * 78a66bcf79c5cea82989401c408f1dff4b961a5b,
- * file livekit-plugins/livekit-plugins-google/livekit/plugins/google/llm.py),
- * licensed under Apache License 2.0. Copyright 2023 LiveKit, Inc.
- *
- * Adaptations from the LiveKit source:
- *   * LiveKit uses the ``google-genai`` Python SDK. The TypeScript port
- *     uses native ``fetch`` against the REST SSE endpoint so we don't
+ * Implementation notes:
+ *   * Uses native ``fetch`` against the REST SSE endpoint so we don't
  *     pull in a large SDK dependency.
- *   * Collapsed the Python ``llm.LLM`` / ``llm.LLMStream`` pair into a
- *     single class that satisfies Patter's ``LLMProvider`` interface.
- *   * Dropped Vertex AI support (which requires GCP auth) — only the
- *     Developer API (API key) path is ported. Vertex can be added by a
- *     follow-up PR once credential plumbing is in place.
+ *   * Single class that satisfies Patter's ``LLMProvider`` interface.
+ *   * Vertex AI support (which requires GCP auth) is not included — only
+ *     the Developer API (API key) path is supported. Vertex can be added
+ *     by a follow-up PR once credential plumbing is in place.
  */
 
+/** Constructor options for {@link GoogleLLMProvider}. */
 interface GoogleLLMOptions$1 {
     apiKey: string;
     model?: string;
@@ -3717,11 +5474,13 @@ declare class GoogleLLMProvider implements LLMProvider {
     private readonly temperature?;
     private readonly maxOutputTokens?;
     constructor(options: GoogleLLMOptions$1);
-    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+    /** Stream Patter-format LLM chunks from the Gemini SSE endpoint. */
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
 }
 
 /** Google Gemini LLM for Patter pipeline mode. */
 
+/** Constructor options for the Google Gemini `LLM` adapter. */
 interface GoogleLLMOptions {
     /**
      * API key. Falls back to ``GEMINI_API_KEY`` first, then ``GOOGLE_API_KEY``.
@@ -3754,28 +5513,24 @@ declare class LLM extends GoogleLLMProvider {
 }
 
 /**
- * Silero VAD provider (TypeScript port).
+ * Silero VAD provider.
  *
  * Acoustic voice activity detection backed by the Silero ONNX model. Buffers
  * incoming int16 LE PCM frames, runs inference on fixed-size windows
  * (256 samples at 8 kHz, 512 at 16 kHz), applies an exponential probability
  * filter, and emits VADEvent transitions (speech_start / speech_end).
  *
- * Ported from LiveKit Agents (Apache 2.0):
- *   https://github.com/livekit/agents
- * Sources:
- *   - livekit-plugins/livekit-plugins-silero/livekit/plugins/silero/vad.py
- *   - livekit-plugins/livekit-plugins-silero/livekit/plugins/silero/onnx_model.py
- *
- * Adaptations for Patter:
+ * Notes:
  *   - Input is raw PCM `Buffer` (int16 LE, mono) via
- *     `processFrame(pcmChunk, sampleRate)`, not `livekit.rtc.AudioFrame`.
+ *     `processFrame(pcmChunk, sampleRate)`.
  *   - onnxruntime-node is loaded lazily as an optional dependency.
- *   - Emits `VADEvent` (Patter protocol) instead of LiveKit event types.
+ *   - Emits `VADEvent` (Patter protocol).
  */
 
 declare const SUPPORTED_SAMPLE_RATES: readonly [8000, 16000];
+/** Sample rates supported by the bundled Silero ONNX model (8 kHz or 16 kHz). */
 type SileroSampleRate = (typeof SUPPORTED_SAMPLE_RATES)[number];
+/** Options accepted by {@link SileroVAD.load}. */
 interface SileroVADOptions {
     minSpeechDuration?: number;
     minSilenceDuration?: number;
@@ -3790,13 +5545,16 @@ interface SileroVADOptions {
  * Minimal structural type for the subset of `onnxruntime-node` we depend on.
  * Declared locally so consumers don't need the package installed at build time.
  */
+/** Minimal subset of `onnxruntime-node`'s `InferenceSession` that Silero needs. */
 interface OnnxInferenceSession {
     run(feeds: Record<string, OnnxTensor>): Promise<Record<string, OnnxTensor>>;
 }
+/** Minimal subset of an `onnxruntime-node` tensor used by Silero inference. */
 interface OnnxTensor {
     readonly data: Float32Array | BigInt64Array;
     readonly dims: readonly number[];
 }
+/** Minimal `onnxruntime-node` module surface accepted by {@link SileroVAD}. */
 interface OnnxRuntime {
     InferenceSession: {
         create(pathOrBuffer: string | Uint8Array, options?: Record<string, unknown>): Promise<OnnxInferenceSession>;
@@ -3822,21 +5580,50 @@ declare class SileroVAD implements VADProvider {
     private closed;
     private constructor();
     /**
-     * Load the Silero VAD model. Defaults match the LiveKit Silero plugin.
+     * Load the Silero VAD model.
      * Throws if `onnxruntime-node` is not installed.
      */
     static load(options?: SileroVADOptions): Promise<SileroVAD>;
+    /**
+     * Convenience factory for telephony pipelines.
+     *
+     * Identical to {@link SileroVAD.load} but pins `sampleRate` to 16000 Hz
+     * — the only sample rate Patter's pipeline-mode audio bus uses (8 kHz
+     * mulaw from Twilio is upsampled to 16 kHz PCM before reaching the
+     * VAD). Every other parameter mirrors the upstream Silero VAD
+     * defaults from `snakers4/silero-vad` (`get_speech_timestamps` /
+     * `VADIterator`):
+     *
+     *   - `activationThreshold = 0.5` — upstream `threshold`
+     *   - `deactivationThreshold = 0.35` — upstream `neg_threshold = threshold - 0.15`
+     *   - `minSpeechDuration = 0.25` — upstream `min_speech_duration_ms = 250`
+     *   - `minSilenceDuration = 0.1` — upstream `min_silence_duration_ms = 100`
+     *   - `prefixPaddingDuration = 0.03` — upstream `speech_pad_ms = 30`
+     *
+     * Override any field by passing `options`. Deployments that experience
+     * truncation on natural pauses can raise `minSilenceDuration` (e.g.
+     * 0.5–1.0 s) per call site rather than as a global default.
+     *
+     * @example
+     * ```ts
+     * const vad = await SileroVAD.forPhoneCall();
+     * // or, if natural-pause truncation is observed:
+     * const vad = await SileroVAD.forPhoneCall({ minSilenceDuration: 0.5 });
+     * ```
+     */
+    static forPhoneCall(options?: SileroVADOptions): Promise<SileroVAD>;
     /**
      * Internal factory used by tests — bypasses onnxruntime-node loading.
      * @internal
      */
     static fromOnnxModel(runtime: OnnxRuntime, session: OnnxInferenceSession, options: Required<Omit<SileroVADOptions, 'onnxFilePath' | 'forceCpu'>>): SileroVAD;
+    /** Sample rate (Hz) the underlying ONNX model was loaded with. */
     get sampleRate(): SileroSampleRate;
     /**
      * Number of int16 PCM samples that must be provided per call to
      * processFrame for the model to run one inference window.
      *
-     * Constraint (ported from LiveKit Agents / Silero ONNX spec):
+     * Constraint (Silero ONNX spec):
      *   - 16 000 Hz → 512 samples (32 ms)
      *   -  8 000 Hz → 256 samples (32 ms)
      *
@@ -3847,8 +5634,10 @@ declare class SileroVAD implements VADProvider {
      * passing exactly one window per call minimises heap allocation.
      */
     numFramesRequired(): number;
+    /** Run VAD on a PCM16 chunk; returns a transition event or null if no change. */
     processFrame(pcmChunk: Buffer, sampleRate: number): Promise<VADEvent | null>;
     private advanceState;
+    /** Mark the VAD as closed; subsequent processFrame calls throw. */
     close(): Promise<void>;
 }
 
@@ -3924,6 +5713,8 @@ interface StatefulResamplerOptions {
  * - 16 000 → 8 000 Hz  (2:1 decimation with 5-tap FIR anti-alias)
  * - 8 000 → 16 000 Hz  (1:2 linear interpolation)
  * - 24 000 → 16 000 Hz (3:2 linear interpolation)
+ * - 24 000 → 8 000 Hz  (3:1 decimation with linear interpolation;
+ *   collapses 24k→16k→8k chain — fix #46)
  *
  * All methods accept and return Buffer (PCM16-LE, mono by default).
  */
@@ -3998,6 +5789,10 @@ declare class StatefulResampler {
      * handled using `resample24Last`.
      */
     private _resample24kTo16k;
+    /** 3:1 decimation — collapses the 24k→16k→8k chain into a single step. */
+    private _resample24kTo8k;
+    /** Shared phase-stepping resampler used by 24→16 (step 1.5) and 24→8 (step 3). */
+    private _resample24kStep;
 }
 /** Create a stateful 16 kHz → 8 kHz downsampling resampler. */
 declare function createResampler16kTo8k(): StatefulResampler;
@@ -4005,6 +5800,8 @@ declare function createResampler16kTo8k(): StatefulResampler;
 declare function createResampler8kTo16k(): StatefulResampler;
 /** Create a stateful 24 kHz → 16 kHz resampler (3:2 linear interpolation). */
 declare function createResampler24kTo16k(): StatefulResampler;
+/** Create a stateful 24 kHz → 8 kHz resampler (3:1 decimation, fix #46). */
+declare function createResampler24kTo8k(): StatefulResampler;
 /**
  * Upsample 8 kHz PCM16 to 16 kHz using linear interpolation.
  *
@@ -4051,6 +5848,7 @@ declare function resample24kTo16k(pcm24k: Buffer): Buffer;
  *
  * Install: npm install cloudflared
  */
+/** Handle returned by `startTunnel` exposing the public hostname and a stopper. */
 interface TunnelHandle {
     /** Public hostname (no protocol), e.g. "random-name.trycloudflare.com" */
     hostname: string;
@@ -4073,7 +5871,9 @@ declare function startTunnel(port: number, timeoutMs?: number): Promise<TunnelHa
  * that provides immutable messages, automatic ID generation, truncation
  * preserving system prompts, and format conversion for OpenAI / Anthropic.
  */
+/** Role tag attached to every `ChatMessage`. */
 type ChatRole = "system" | "user" | "assistant" | "tool";
+/** Single immutable entry in a `ChatContext` history. */
 interface ChatMessage {
     readonly id: string;
     readonly role: ChatRole;
@@ -4082,16 +5882,19 @@ interface ChatMessage {
     readonly name?: string;
     readonly toolCallId?: string;
 }
+/** Wire shape produced by `ChatContext.toOpenAI()` (matches OpenAI Chat Completions). */
 interface OpenAIMessage {
     role: string;
     content: string;
     name?: string;
     tool_call_id?: string;
 }
+/** Single message in `AnthropicConversion.messages`. */
 interface AnthropicMessage {
     role: string;
     content: string;
 }
+/** Result of `ChatContext.toAnthropic()` — system prompt extracted from the message list. */
 interface AnthropicConversion {
     system: string | undefined;
     messages: ReadonlyArray<AnthropicMessage>;
@@ -4099,15 +5902,23 @@ interface AnthropicConversion {
 interface ChatContextJSON {
     messages: ReadonlyArray<ChatMessage>;
 }
+/** Mutable conversation history with system-prompt-aware truncation and provider conversion helpers. */
 declare class ChatContext {
     private items;
     constructor(systemPrompt?: string);
+    /** Append a user message and return the created `ChatMessage`. */
     addUser(content: string): ChatMessage;
+    /** Append an assistant message and return the created `ChatMessage`. */
     addAssistant(content: string): ChatMessage;
+    /** Append a system message and return the created `ChatMessage`. */
     addSystem(content: string): ChatMessage;
+    /** Append a tool-result message tied to a tool-call id. */
     addToolResult(content: string, toolCallId: string): ChatMessage;
+    /** Return a snapshot of all messages currently in the context. */
     getMessages(): ReadonlyArray<ChatMessage>;
+    /** Return the last `n` messages (or `[]` when `n <= 0`). */
     getLastN(n: number): ReadonlyArray<ChatMessage>;
+    /** Number of messages currently in the context. */
     get length(): number;
     /**
      * Keep the first system message (if any) plus the last `maxMessages`
@@ -4115,6 +5926,7 @@ declare class ChatContext {
      * simply keeps the last `maxMessages` messages.
      */
     truncate(maxMessages: number): void;
+    /** Convert the conversation to the OpenAI Chat Completions message format. */
     toOpenAI(): OpenAIMessage[];
     /**
      * Convert to Anthropic format. The first system message (if present)
@@ -4122,8 +5934,11 @@ declare class ChatContext {
      * messages are included in the messages array.
      */
     toAnthropic(): AnthropicConversion;
+    /** Return a new `ChatContext` with the same messages (independent storage). */
     copy(): ChatContext;
+    /** Serialize the context to a JSON-safe object. */
     toJSON(): ChatContextJSON;
+    /** Reconstruct a `ChatContext` from the result of `toJSON()`. */
     static fromJSON(data: ChatContextJSON): ChatContext;
 }
 
@@ -4145,21 +5960,15 @@ declare class ChatContext {
  * equivalent battle-tested package in the std library, so we ship a
  * minimal in-house bag-of-words + cosine-similarity implementation.
  * It is intentionally simple — enough to match repeated IVR prompts.
- *
- * Algorithm adapted from LiveKit Agents (Apache 2.0):
- * https://github.com/livekit/agents
- *
- * Source:
- *  - livekit-agents/livekit/agents/voice/ivr/ivr_activity.py
- *  - livekit-agents/livekit/agents/beta/tools/send_dtmf.py
- * LiveKit SHA at port time: 78a66bcf79c5cea82989401c408f1dff4b961a5b
  */
 
 /** Valid DTMF tone values (keypad characters). */
 declare const DTMF_EVENTS: readonly ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#", "A", "B", "C", "D"];
+/** Single DTMF tone value (a member of `DTMF_EVENTS`). */
 type DtmfEvent = (typeof DTMF_EVENTS)[number];
 /** Join DTMF events into a space-separated debug string. */
 declare function formatDtmf(events: DtmfEvent[]): string;
+/** Constructor options for `TfidfLoopDetector`. */
 interface TfidfLoopDetectorOptions {
     /** Number of recent chunks to keep in the comparison window. */
     windowSize?: number;
@@ -4180,14 +5989,18 @@ declare class TfidfLoopDetector {
     private chunks;
     private consecutiveSimilar;
     constructor(opts?: TfidfLoopDetectorOptions);
+    /** Forget all previously observed chunks and reset the consecutive-hit counter. */
     reset(): void;
+    /** Record a new transcript chunk in the rolling window. */
     addChunk(text: string): void;
+    /** Returns true once the most recent chunks look like a repeated IVR prompt. */
     checkLoopDetection(): boolean;
 }
 /** Async callback fired when the TF-IDF detector trips. */
 type LoopCallback = () => Promise<void> | void;
 /** Async callback fired after sustained silence. */
 type SilenceCallback = () => Promise<void> | void;
+/** Constructor options for `IVRActivity`. */
 interface IVRActivityOptions {
     /** Seconds of combined silence before firing `onSilence`. Default `5.0`. */
     maxSilenceDuration?: number;
@@ -4237,11 +6050,17 @@ declare class IVRActivity {
     private lastShouldSchedule;
     private started;
     constructor(callControl: CallControl, opts?: IVRActivityOptions);
+    /** Begin tracking transcripts and silence; call once per call. */
     start(): Promise<void>;
+    /** Stop tracking and cancel any pending silence timer. */
     stop(): Promise<void>;
+    /** Feed a final user-side transcript chunk into the loop detector. */
     onUserTranscribed(text: string): Promise<void>;
+    /** Record the current user-turn state (e.g. `"listening"`, `"away"`). */
     noteUserState(state: string): void;
+    /** Record the current agent-turn state (e.g. `"idle"`, `"listening"`). */
     noteAgentState(state: string): void;
+    /** Tool definitions to expose to the LLM (currently only `send_dtmf_events`). */
     get tools(): IVRToolDefinition[];
     private scheduleSilenceCheck;
     private shouldScheduleCheck;
@@ -4249,6 +6068,30 @@ declare class IVRActivity {
     private buildSendDtmfTool;
 }
 
+/**
+ * Background-audio mixer for the Patter TypeScript SDK. Patter routes
+ * outbound PCM through the pipeline stream handler, so this module exposes
+ * a ``start / mix / stop`` API that does no I/O of its own. See
+ * {@link BackgroundAudioPlayer} for the public class.
+ *
+ * Notes:
+ *
+ *  - PCM mixing is a ~40-line pure-JavaScript routine operating on
+ *    ``Buffer`` (see :func:`mixPcm` below). Clipping is done against the
+ *    int16 range.
+ *  - ``.ogg`` decoding is not done in this module. Node does not bundle a
+ *    Vorbis decoder and shipping a native one would triple the SDK size.
+ *    Instead, callers supply a :class:`RawPcmSource` (pre-decoded int16
+ *    mono LE PCM at a known sample rate) OR a :class:`DecodedSource` via a
+ *    user-supplied decoder. The Python SDK ships the bundled ``.ogg``
+ *    clips and their decoder; the TS package exposes the raw files next to
+ *    this module for users who wire up their own decoder.
+ *
+ * Attribution for the bundled audio clips themselves is preserved in
+ * ``src/resources/audio/NOTICE``.
+ */
+
+/** Names of the .ogg clips bundled with the SDK under ``resources/audio/``. */
 declare const BuiltinAudioClip: {
     readonly CITY_AMBIENCE: "city-ambience.ogg";
     readonly FOREST_AMBIENCE: "forest-ambience.ogg";
@@ -4258,6 +6101,7 @@ declare const BuiltinAudioClip: {
     readonly KEYBOARD_TYPING2: "keyboard-typing2.ogg";
     readonly HOLD_MUSIC: "hold_music.ogg";
 };
+/** Filename of one of the bundled clips (e.g. ``"city-ambience.ogg"``). */
 type BuiltinAudioClipName = (typeof BuiltinAudioClip)[keyof typeof BuiltinAudioClip];
 /** Resolve a bundled clip name to its absolute path on disk. */
 declare function builtinClipPath(clip: BuiltinAudioClipName): string;
@@ -4291,7 +6135,9 @@ interface BuiltinPcmSource {
     readonly volume?: number;
     readonly probability?: number;
 }
+/** Tagged union of every input shape accepted by the player. */
 type AudioSource = RawPcmSource | FilePcmSource | BuiltinPcmSource;
+/** A source plus optional probability weight + volume for list-style players. */
 interface AudioConfig {
     readonly source: AudioSource;
     /** Probability weight used when ``BackgroundAudioPlayer`` receives a list. */
@@ -4299,8 +6145,9 @@ interface AudioConfig {
     /** Master volume [0, 1] applied on top of the per-source ``volume``. */
     readonly volume?: number;
 }
+/** Constructor options for {@link BackgroundAudioPlayer}. */
 interface BackgroundAudioOptions {
-    /** Overall mix ratio [0, 1].  Defaults to 0.1 (LiveKit's hold-music ratio). */
+    /** Overall mix ratio [0, 1].  Defaults to 0.1 (typical hold-music ratio). */
     readonly volume?: number;
     /** When true the source restarts on exhaustion. */
     readonly loop?: boolean;
@@ -4317,6 +6164,7 @@ declare function mixPcm(agent: Buffer, bg: Buffer, ratio: number): Buffer;
  * program audio.
  */
 declare function resamplePcm(src: Buffer, srcSr: number, dstSr: number): Buffer;
+/** Probability-weighted random pick from a list of {@link AudioConfig}. */
 declare function selectSoundFromList(sounds: readonly AudioConfig[]): AudioConfig | null;
 /**
  * Mix a background audio clip into an outbound PCM stream.
@@ -4356,26 +6204,31 @@ declare class BackgroundAudioPlayer implements BackgroundAudioPlayer$1 {
     private resampleTo;
 }
 
+/** Constructor options for {@link TwilioAdapter}. */
 interface TwilioAdapterOptions {
     /** Optional Twilio edge region (e.g. ``ie1`` for Ireland). */
     region?: string;
 }
+/** Options accepted by {@link TwilioAdapter.provisionNumber}. */
 interface ProvisionNumberOptions$1 {
     /** ISO-3166-1 alpha-2 country code, e.g. ``"US"``. */
     countryCode: string;
     /** Optional North-American area code (e.g. ``"415"``). */
     areaCode?: string;
 }
+/** Result returned by {@link TwilioAdapter.provisionNumber}. */
 interface ProvisionNumberResult$1 {
     readonly phoneNumber: string;
     readonly sid: string;
 }
+/** Options accepted by {@link TwilioAdapter.configureNumber}. */
 interface ConfigureNumberOptions$1 {
     /** URL Twilio should hit when the number receives a call. */
     voiceUrl: string;
     /** Optional status callback URL for call lifecycle events. */
     statusCallback?: string;
 }
+/** Options accepted by {@link TwilioAdapter.initiateCall}. */
 interface InitiateCallOptions$1 {
     from: string;
     to: string;
@@ -4397,9 +6250,11 @@ interface InitiateCallOptions$1 {
     /** Raw extra form parameters forwarded to the Calls endpoint. */
     extraParams?: Record<string, string>;
 }
+/** Result returned by {@link TwilioAdapter.initiateCall}. */
 interface InitiateCallResult$1 {
     readonly callSid: string;
 }
+/** Direct REST adapter for Twilio Programmable Voice & Numbers API. */
 declare class TwilioAdapter {
     readonly accountSid: string;
     readonly region: string | undefined;
@@ -4426,18 +6281,22 @@ declare class TwilioAdapter {
     endCall(callSid: string): Promise<void>;
 }
 
+/** Options accepted by {@link TelnyxAdapter.provisionNumber}. */
 interface ProvisionNumberOptions {
     /** ISO-3166-1 alpha-2 country code (e.g. ``"US"``). */
     countryCode: string;
 }
+/** Result returned by {@link TelnyxAdapter.provisionNumber}. */
 interface ProvisionNumberResult {
     readonly phoneNumber: string;
     readonly orderId: string;
 }
+/** Options accepted by {@link TelnyxAdapter.configureNumber}. */
 interface ConfigureNumberOptions {
     /** Telnyx Call Control Application / Connection ID. */
     connectionId: string;
 }
+/** Options accepted by {@link TelnyxAdapter.initiateCall}. */
 interface InitiateCallOptions {
     from: string;
     to: string;
@@ -4446,13 +6305,16 @@ interface InitiateCallOptions {
     /** Opaque state string that Telnyx echoes back on webhooks. Base64-encoded on wire. */
     clientState?: string;
 }
+/** Result returned by {@link TelnyxAdapter.initiateCall}. */
 interface InitiateCallResult {
     readonly callControlId: string;
 }
+/** Options accepted by {@link TelnyxAdapter.endCall}. */
 interface EndCallOptions {
     /** Idempotency key for the hangup command. */
     commandId?: string;
 }
+/** Direct REST adapter for Telnyx Call Control & Numbers API. */
 declare class TelnyxAdapter {
     private readonly apiKey;
     readonly connectionId: string | undefined;
@@ -4479,6 +6341,102 @@ declare class TelnyxAdapter {
     endCall(callControlId: string, opts?: EndCallOptions): Promise<void>;
 }
 
+/**
+ * Telnyx Speech-to-Text adapter (WebSocket streaming).
+ *
+ * Bridges the Telnyx `/v2/speech-to-text/transcription` WebSocket API to the
+ * Patter SDK pipeline-mode STT interface. Implemented in TypeScript
+ * (`ws` + `Buffer`) with a callback-based interface matching the other
+ * Patter STT providers (Deepgram, Whisper).
+ */
+/** Patter-normalised transcript event emitted by {@link TelnyxSTT}. */
+interface Transcript {
+    readonly text: string;
+    readonly isFinal: boolean;
+    readonly confidence: number;
+}
+type TranscriptCallback = (transcript: Transcript) => void;
+/** Backing transcription engine accepted by Telnyx STT. */
+type TelnyxTranscriptionEngine = 'telnyx' | 'google' | 'deepgram' | 'azure';
+/** Common PCM sample rates accepted by Telnyx STT. */
+declare const TelnyxSTTSampleRate: {
+    readonly HZ_8000: 8000;
+    readonly HZ_16000: 16000;
+    readonly HZ_24000: 24000;
+};
+/** Union of {@link TelnyxSTTSampleRate} integer values. */
+type TelnyxSTTSampleRate = (typeof TelnyxSTTSampleRate)[keyof typeof TelnyxSTTSampleRate];
+/** Input audio formats accepted by Telnyx STT. */
+declare const TelnyxSTTInputFormat: {
+    readonly WAV: "wav";
+};
+/** Union of {@link TelnyxSTTInputFormat} string values. */
+type TelnyxSTTInputFormat = (typeof TelnyxSTTInputFormat)[keyof typeof TelnyxSTTInputFormat];
+/** Streaming STT adapter for Telnyx's `/v2/speech-to-text` WebSocket. */
+declare class TelnyxSTT {
+    private readonly apiKey;
+    private readonly language;
+    private readonly transcriptionEngine;
+    private readonly sampleRate;
+    private readonly baseUrl;
+    private ws;
+    private callbacks;
+    private headerSent;
+    constructor(apiKey: string, language?: string, transcriptionEngine?: TelnyxTranscriptionEngine, sampleRate?: number, baseUrl?: string);
+    /** Open the streaming WebSocket and arm message handlers. */
+    connect(): Promise<void>;
+    /** Send a binary PCM16 audio chunk; emits the WAV header on the first call. */
+    sendAudio(audio: Buffer): void;
+    /** Register a transcript listener (max 10 concurrent listeners). */
+    onTranscript(callback: TranscriptCallback): void;
+    /** Close the streaming WebSocket. */
+    close(): void;
+}
+
+/**
+ * Telnyx Text-to-Speech adapter (WebSocket streaming).
+ *
+ * Bridges the Telnyx `/v2/text-to-speech/speech` WebSocket API to the
+ * Patter SDK pipeline-mode TTS interface. Implemented in TypeScript
+ * (`ws` + `Buffer`) with the same `synthesize` / `synthesizeStream`
+ * method shape used by the other Patter TTS providers (ElevenLabs,
+ * OpenAI). The stream yields raw MP3 bytes.
+ */
+/** Common Telnyx NaturalHD voices accepted by the TTS endpoint. */
+declare const TelnyxTTSVoice: {
+    readonly NATURAL_HD_ASTRA: "Telnyx.NaturalHD.astra";
+    readonly NATURAL_HD_LUNA: "Telnyx.NaturalHD.luna";
+    readonly NATURAL_HD_ATLAS: "Telnyx.NaturalHD.atlas";
+    readonly NATURAL_HD_HERA: "Telnyx.NaturalHD.hera";
+    readonly NATURAL_HD_ZEUS: "Telnyx.NaturalHD.zeus";
+};
+/** Union of {@link TelnyxTTSVoice} string values. */
+type TelnyxTTSVoice = (typeof TelnyxTTSVoice)[keyof typeof TelnyxTTSVoice];
+/** Sample rates supported by the Telnyx TTS WebSocket endpoint. */
+declare const TelnyxTTSSampleRate: {
+    readonly HZ_8000: 8000;
+    readonly HZ_16000: 16000;
+    readonly HZ_24000: 24000;
+};
+/** Union of {@link TelnyxTTSSampleRate} integer values. */
+type TelnyxTTSSampleRate = (typeof TelnyxTTSSampleRate)[keyof typeof TelnyxTTSSampleRate];
+/** Streaming TTS adapter for Telnyx's `/v2/text-to-speech/speech` WebSocket. */
+declare class TelnyxTTS {
+    private readonly apiKey;
+    private readonly voice;
+    private readonly baseUrl;
+    constructor(apiKey: string, voice?: string, baseUrl?: string);
+    /** Collect every audio chunk into a single Buffer. */
+    synthesize(text: string): Promise<Buffer>;
+    /**
+     * Stream MP3-encoded audio chunks as they arrive from Telnyx.
+     *
+     * The server sends JSON frames of the shape `{"audio": "<base64-mp3>"}`.
+     * Callers that need PCM must decode the MP3 bytes (e.g. via `ffmpeg`).
+     */
+    synthesizeStream(text: string): AsyncGenerator<Buffer>;
+}
+
 declare const SPAN_CALL = "getpatter.call";
 declare const SPAN_STT = "getpatter.stt";
 declare const SPAN_LLM = "getpatter.llm";
@@ -4495,6 +6453,7 @@ interface Span {
     recordException(exception: unknown): void;
     end(): void;
 }
+/** Options for `initTracing()`. */
 interface InitTracingOptions {
     serviceName?: string;
     otlpEndpoint?: string;
@@ -4545,4 +6504,4 @@ interface CallEvent {
     readonly direction?: string;
 }
 
-export { type AgentOptions, AllProvidersFailedError, type AnthropicConversion, LLM$3 as AnthropicLLM, type AnthropicLLMOptions, type AnthropicMessage, type AssemblyAIEncoding, type AssemblyAIModel, STT as AssemblyAISTT, type AssemblyAISTTOptions, type AudioConfig, type AudioSource, AuthenticationError, type BackgroundAudioOptions, BackgroundAudioPlayer, BuiltinAudioClip, type BuiltinAudioClipName, type BuiltinPcmSource, type CallControl, type CallEvent, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallRecord, type CartesiaEncoding, STT$2 as CartesiaSTT, type CartesiaSTTOptions, TTS$2 as CartesiaTTS, type CartesiaTTSOptions, LLM$1 as CerebrasLLM, type CerebrasLLMOptions, ChatContext, type ChatMessage, type ChatRole, CloudflareTunnel, type CostBreakdown, DEFAULT_MIN_SENTENCE_LEN, DEFAULT_PRICING, DTMF_EVENTS, STT$5 as DeepgramSTT, type DeepgramSTTOptions, DefaultToolExecutor, type DefaultToolExecutorOptions, type DefineToolInput, type DtmfEvent, ConvAI as ElevenLabsConvAI, ElevenLabsConvAIAdapter, type ConvAIOptions as ElevenLabsConvAIOptions, TTS$4 as ElevenLabsTTS, type ElevenLabsTTSOptions, EventBus, FallbackLLMProvider, type FallbackLLMProviderOptions, type FilePcmSource, GEMINI_DEFAULT_INPUT_SR, GEMINI_DEFAULT_OUTPUT_SR, GeminiLiveAdapter, type GeminiLiveEventHandler, LLM as GoogleLLM, type GoogleLLMOptions, LLM$2 as GroqLLM, type GroqLLMOptions, Guardrail$1 as Guardrail, type GuardrailOptions, type HookContext, IVRActivity, type IVRActivityOptions, type IVRToolDefinition, type IncomingMessage, type InitTracingOptions, type JobCallback, type LLMChunk, LLMLoop, type LLMProvider, type LMNTAudioFormat, type LMNTModel, type LMNTSampleRate, TTS as LMNTTTS, type LMNTTTSOptions, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type LoopCallback, type MessageHandler, MetricsStore, Ngrok, LLM$4 as OpenAILLM, type OpenAILLMOptions, OpenAILLMProvider, type OpenAIMessage, Realtime as OpenAIRealtime, OpenAIRealtimeAdapter, type RealtimeOptions as OpenAIRealtimeOptions, TTS$3 as OpenAITTS, type OpenAITTSOptions, STT$3 as OpenAITranscribeSTT, type OpenAITranscribeSTTOptions, type ParamSpec, PartialStreamError, Patter, PatterConnectionError, PatterError, type PatterEventType, PatterTool, type PatterToolExecuteArgs, type PatterToolOptions, type PatterToolResult, PcmCarry, PipelineHookExecutor, type PipelineHooks, type PipelineMessageHandler, type ProviderPricing, ProvisionError, RateLimitError, type RawPcmSource, type RealtimeConfig, RemoteMessageHandler, TTS$1 as RimeTTS, type RimeTTSOptions, SPAN_BARGEIN, SPAN_CALL, SPAN_ENDPOINT, SPAN_LLM, SPAN_STT, SPAN_TOOL, SPAN_TTS, type SSEEvent, type STTConfig, type ScheduleHandle, SentenceChunker, type ServeOptions, type SilenceCallback, type SileroSampleRate, SileroVAD, type SileroVADOptions, STT$1 as SonioxSTT, type SonioxSTTOptions$1 as SonioxSTTOptions, type Span, StatefulResampler, type StatefulResamplerOptions, Static as StaticTunnel, type TTSConfig, Carrier as Telnyx, TelnyxAdapter, type TelnyxCarrierOptions, type ConfigureNumberOptions as TelnyxConfigureNumberOptions, type EndCallOptions as TelnyxEndCallOptions, type InitiateCallOptions as TelnyxInitiateCallOptions, type InitiateCallResult as TelnyxInitiateCallResult, type ProvisionNumberOptions as TelnyxProvisionNumberOptions, type ProvisionNumberResult as TelnyxProvisionNumberResult, TestSession, TfidfLoopDetector, type TfidfLoopDetectorOptions, Tool, type ToolDefinition, type ToolExecutor, type ToolHandler, type ToolOptions, type TunnelHandle, type TurnMetrics, Carrier$1 as Twilio, TwilioAdapter, type TwilioAdapterOptions, type TwilioCarrierOptions, type ConfigureNumberOptions$1 as TwilioConfigureNumberOptions, type InitiateCallOptions$1 as TwilioInitiateCallOptions, type InitiateCallResult$1 as TwilioInitiateCallResult, type ProvisionNumberOptions$1 as TwilioProvisionNumberOptions, type ProvisionNumberResult$1 as TwilioProvisionNumberResult, ULTRAVOX_DEFAULT_API_BASE, ULTRAVOX_DEFAULT_SR, type UltravoxEventHandler, UltravoxRealtimeAdapter, STT$4 as WhisperSTT, type WhisperSTTOptions, assemblyai, builtinClipPath, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, cartesia, createResampler16kTo8k, createResampler24kTo16k, createResampler8kTo16k, deepgram, defineTool, elevenlabs, filterEmoji, filterForTTS, filterMarkdown, formatDtmf, geminiLive, getLogger, guardrail, initTracing, isRemoteUrl, isTracingEnabled, isWebSocketUrl, lmnt, makeAuthMiddleware, mergePricing, mixPcm, mountApi, mountDashboard, mulawToPcm16, notifyDashboard, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, resamplePcm, rime, scheduleCron, scheduleInterval, scheduleOnce, selectSoundFromList, setLogger, soniox, speechmatics, startSpan, startTunnel, tool, ultravox, whisper };
+export { type AgentOptions, type AgentState, AllProvidersFailedError, type AnthropicConversion, LLM$3 as AnthropicLLM, type AnthropicLLMOptions, type AnthropicMessage, AssemblyAIEncoding, AssemblyAIModel, STT$1 as AssemblyAISTT, type AssemblyAISTTOptions, type AudioConfig, type AudioSource, AuthenticationError, type BackgroundAudioOptions, BackgroundAudioPlayer, BuiltinAudioClip, type BuiltinAudioClipName, type BuiltinPcmSource, type CallControl, type CallEvent, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallRecord, type CartesiaEncoding, STT$3 as CartesiaSTT, type CartesiaSTTOptions, TTS$3 as CartesiaTTS, type CartesiaTTSOptions, LLM$1 as CerebrasLLM, type CerebrasLLMOptions, ChatContext, type ChatMessage, type ChatRole, CloudflareTunnel, type ConversationStateSnapshot, type CostBreakdown, DEFAULT_MIN_SENTENCE_LEN, DEFAULT_PRICING, DTMF_EVENTS, STT$6 as DeepgramSTT, type DeepgramSTTOptions, DefaultToolExecutor, type DefaultToolExecutorOptions, type DefineToolInput, type DtmfEvent, ConvAI as ElevenLabsConvAI, ElevenLabsConvAIAdapter, type ConvAIOptions as ElevenLabsConvAIOptions, TTS$6 as ElevenLabsTTS, type ElevenLabsTTSOptions, type ElevenLabsWebSocketOptions, TTS$5 as ElevenLabsWebSocketTTS, type EouTrigger, ErrorCode, EventBus, FallbackLLMProvider, type FallbackLLMProviderOptions, type FilePcmSource, GEMINI_DEFAULT_INPUT_SR, GEMINI_DEFAULT_OUTPUT_SR, GeminiLiveAdapter, type GeminiLiveEventHandler, LLM as GoogleLLM, type GoogleLLMOptions, LLM$2 as GroqLLM, type GroqLLMOptions, Guardrail$1 as Guardrail, type GuardrailOptions, type HookContext, IVRActivity, type IVRActivityOptions, type IVRToolDefinition, type IncomingMessage, type InitTracingOptions, TTS as InworldTTS, type InworldTTSOptions, type JobCallback, type LLMChunk, LLMLoop, type LLMProvider, LMNTAudioFormat, LMNTModel, LMNTSampleRate, TTS$1 as LMNTTTS, type LMNTTTSOptions, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type LoopCallback, type MessageHandler, MetricsStore, Ngrok, LLM$4 as OpenAILLM, type OpenAILLMOptions, OpenAILLMProvider, type OpenAIMessage, Realtime as OpenAIRealtime, OpenAIRealtimeAdapter, type RealtimeOptions as OpenAIRealtimeOptions, TTS$4 as OpenAITTS, type OpenAITTSOptions, STT$4 as OpenAITranscribeSTT, type OpenAITranscribeSTTOptions, type ParamSpec, PartialStreamError, Patter, PatterConnectionError, PatterError, type PatterEventType, PatterTool, type PatterToolExecuteArgs, type PatterToolOptions, type PatterToolResult, PcmCarry, PipelineHookExecutor, type PipelineHooks, type PipelineMessageHandler, type ProviderPricing, ProvisionError, RateLimitError, type RawPcmSource, type RealtimeConfig, RemoteMessageHandler, TTS$2 as RimeTTS, type RimeTTSOptions, SPAN_BARGEIN, SPAN_CALL, SPAN_ENDPOINT, SPAN_LLM, SPAN_STT, SPAN_TOOL, SPAN_TTS, type SSEEvent, type STTConfig, type ScheduleHandle, SentenceChunker, type ServeOptions, type SilenceCallback, type SileroSampleRate, SileroVAD, type SileroVADOptions, STT$2 as SonioxSTT, type SonioxSTTOptions$1 as SonioxSTTOptions, type Span, type SpeechEventCallback, SpeechEvents, SpeechmaticsAudioEncoding, SpeechmaticsOperatingPoint, STT as SpeechmaticsSTT, type SpeechmaticsSTTOptions, SpeechmaticsSampleRate, SpeechmaticsServerMessage, TurnDetectionMode as SpeechmaticsTurnDetectionMode, StatefulResampler, type StatefulResamplerOptions, Static as StaticTunnel, type TTSConfig, Carrier as Telnyx, TelnyxAdapter, type TelnyxCarrierOptions, type ConfigureNumberOptions as TelnyxConfigureNumberOptions, type EndCallOptions as TelnyxEndCallOptions, type InitiateCallOptions as TelnyxInitiateCallOptions, type InitiateCallResult as TelnyxInitiateCallResult, type ProvisionNumberOptions as TelnyxProvisionNumberOptions, type ProvisionNumberResult as TelnyxProvisionNumberResult, TelnyxSTT, TelnyxSTTInputFormat, TelnyxSTTSampleRate, type Transcript as TelnyxSTTTranscript, TelnyxTTS, TelnyxTTSSampleRate, TelnyxTTSVoice, type TelnyxTranscriptionEngine, TestSession, TfidfLoopDetector, type TfidfLoopDetectorOptions, Tool, type ToolDefinition, type ToolExecutor, type ToolHandler, type ToolOptions, type TunnelHandle, type TurnMetrics, Carrier$1 as Twilio, TwilioAdapter, type TwilioAdapterOptions, type TwilioCarrierOptions, type ConfigureNumberOptions$1 as TwilioConfigureNumberOptions, type InitiateCallOptions$1 as TwilioInitiateCallOptions, type InitiateCallResult$1 as TwilioInitiateCallResult, type ProvisionNumberOptions$1 as TwilioProvisionNumberOptions, type ProvisionNumberResult$1 as TwilioProvisionNumberResult, ULTRAVOX_DEFAULT_API_BASE, ULTRAVOX_DEFAULT_SR, type UltravoxEventHandler, UltravoxRealtimeAdapter, type UserState, STT$5 as WhisperSTT, type WhisperSTTOptions, assemblyai, builtinClipPath, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, cartesia, createResampler16kTo8k, createResampler24kTo16k, createResampler24kTo8k, createResampler8kTo16k, deepgram, defineTool, elevenlabs, filterEmoji, filterForTTS, filterMarkdown, formatDtmf, geminiLive, getLogger, guardrail, initTracing, isRemoteUrl, isTracingEnabled, isWebSocketUrl, lmnt, makeAuthMiddleware, mergePricing, mixPcm, mountApi, mountDashboard, mulawToPcm16, notifyDashboard, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, resamplePcm, rime, scheduleCron, scheduleInterval, scheduleOnce, selectSoundFromList, setLogger, soniox, speechmatics, startSpan, startTunnel, tool, ultravox, whisper };