getpatter 0.6.7 → 0.6.8

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as WebSocket from 'ws';
-import WebSocket__default from 'ws';
+import WebSocket__default, { WebSocket as WebSocket$1 } from 'ws';
 import { EventEmitter } from 'events';
 import { Request, Response, NextFunction, Express } from 'express';
 
@@ -184,6 +184,149 @@ declare class SpeechEvents {
     private dispatch;
 }
 
+/**
+ * Carrier-neutral local call recording — interleaved stereo WAV on disk.
+ *
+ * `LocalCallRecorder` taps the audio that already flows through the SDK's
+ * per-call `StreamHandler` and writes a synchronized two-channel recording:
+ *
+ * - **left channel  = caller** (inbound, post mulaw→PCM16 decode)
+ * - **right channel = agent**  (outbound TTS / Realtime / ConvAI audio)
+ *
+ * Unlike the carrier-side `recording: true` option (Twilio Recordings API,
+ * Telnyx `record_start`, Plivo Record API) this works on ANY carrier because
+ * nothing leaves the process: the recorder is fed at the transport tap points
+ * and appends PCM to `recording.wav` incrementally. Enable via
+ * `Patter.serve({ localRecording: true })` (or a directory string). Parity
+ * with Python `getpatter/audio/call_recorder.py`.
+ *
+ * ## Format
+ *
+ * 16-bit little-endian PCM, 16 kHz, 2 channels. A placeholder RIFF header is
+ * written at open with zero sizes; {@link LocalCallRecorder.close} patches
+ * the `RIFF` and `data` chunk sizes so the file is parseable by any WAV
+ * reader. The handler teardown paths (`handleStop` / `handleWsClose` →
+ * `fireCallEnd`) call `close()`, so a truncated call still yields a valid
+ * file.
+ *
+ * ## Time alignment (documented approach)
+ *
+ * The recorder is **caller-clocked**. On PSTN the inbound media stream is a
+ * continuous realtime sequence of ~20 ms frames (silence included), so the
+ * caller channel is used as the wall clock:
+ *
+ * - Each caller chunk advances the file by exactly its own duration. The
+ *   right channel for that span is popped from a bounded agent FIFO and
+ *   zero-padded (silence) when the agent has nothing buffered — i.e. the
+ *   lagging channel is padded with silence whenever the other channel writes.
+ * - Agent audio is appended to the FIFO on arrival and drained at the caller
+ *   clock rate. TTS providers push audio faster than realtime (multi-second
+ *   bursts); draining at the caller rate mirrors the carrier's own playout
+ *   buffer, so agent audio lands on the timeline roughly where the caller
+ *   actually heard it (frame-granularity ≈ the inbound chunk size, ~20 ms).
+ *
+ * Alignment is therefore duration-based, not wall-clock-based: cross-channel
+ * skew is bounded by the carrier playout backlog.
+ *
+ * ## Memory profile (allocation-light, no per-frame disk I/O)
+ *
+ * Interleaved frames accumulate in a 64 KiB write buffer (~1 s of stereo
+ * audio) that is flushed with a single `writeSync` when full and on
+ * `close()` — the 20 ms hot path never issues per-frame disk writes.
+ * Nothing accumulates for the call duration. Internal state is bounded: at
+ * most one odd carry byte on each PCM path, a fixed-state resampler per
+ * channel, the bounded write buffer, and an agent FIFO capped at
+ * {@link AGENT_BACKLOG_CAP_S} seconds (~1.9 MB) whose overflow is
+ * force-flushed against left-channel silence.
+ *
+ * Any I/O error disables the recorder for the rest of the call (logged
+ * once) — recording must never take down a live phone call.
+ */
+/** Output sample rate (both channels) — the SDK's internal PCM16 rate. */
+declare const RECORDING_SAMPLE_RATE = 16000;
+/**
+ * Maximum buffered agent audio (seconds) awaiting caller-clock drain. The
+ * agent FIFO mirrors the carrier playout buffer; 60 s covers even very long
+ * single-turn monologues. Overflow is force-flushed (silence on the caller
+ * channel), bounding memory at ~1.9 MB per recorded call.
+ */
+declare const AGENT_BACKLOG_CAP_S = 60;
+/** Wire encodings the taps may feed; everything is decoded to PCM16 16 kHz. */
+type RecorderEncoding = 'pcm16_16k' | 'mulaw_8k' | 'pcm16_8k' | 'pcm16_24k';
+/**
+ * Incremental stereo WAV writer for one call (left=caller, right=agent).
+ *
+ * The file is opened (and the placeholder header written) eagerly so
+ * permission errors surface at call start, not mid-call. All `add*` methods
+ * are synchronous and cheap (one decode + one buffered append per ~20 ms
+ * frame; disk writes happen in 64 KiB batches); errors never propagate —
+ * the recorder disables itself and logs a single warning.
+ */
+declare class LocalCallRecorder {
+    private readonly filePath;
+    private fd;
+    private dataBytes;
+    private isClosed;
+    private broken;
+    private readonly callerDecoder;
+    private readonly agentDecoder;
+    /** Bounded FIFO of decoded agent PCM16@16k awaiting caller-clock drain. */
+    private agentBacklog;
+    private agentBacklogBytes;
+    /** Test hook: shrink to exercise the overflow path without 60 s of audio. */
+    maxBacklogBytes: number;
+    private callerSampleCount;
+    private agentSampleCount;
+    /** Interleaved stereo bytes awaiting the next batched disk write. */
+    private pendingChunks;
+    private pendingBytes;
+    /** Stereo data bytes already flushed to disk (file offset = 44 + this). */
+    private flushedBytes;
+    constructor(filePath: string);
+    /** Target WAV path. */
+    get path(): string;
+    /** True once `close()` has run (or the recorder broke). */
+    get closed(): boolean;
+    /**
+     * Stereo frames appended so far (the 64 KiB write buffer flushes roughly
+     * once per second of audio and always on `close()`).
+     */
+    get framesWritten(): number;
+    /** Real caller samples ingested (excludes padding). */
+    get callerSamples(): number;
+    /** Real agent samples ingested (excludes padding). */
+    get agentSamples(): number;
+    /** Recorded duration so far (committed stereo frames / 16 kHz). */
+    get durationSeconds(): number;
+    /**
+     * Record a caller-side chunk; advances the file by its duration. The
+     * right channel for the span is drained from the agent FIFO and
+     * zero-padded (silence) when the agent is not speaking.
+     */
+    addCallerAudio(data: Buffer, encoding?: RecorderEncoding): void;
+    /** Buffer an agent-side chunk; it drains at the caller clock rate. */
+    addAgentAudio(data: Buffer, encoding?: RecorderEncoding): void;
+    /**
+     * Drain the agent FIFO, patch the WAV header, and close the file.
+     *
+     * Idempotent and exception-safe — callable from every teardown path
+     * (carrier `stop`, abnormal WS close, `fireCallEnd`). Returns the
+     * recording path when a playable file exists, else `null`.
+     */
+    close(): string | null;
+    /** Pop up to `numBytes` from the agent FIFO, zero-padded to size. */
+    private popAgentBacklog;
+    /**
+     * Interleave equal-length mono buffers and append to the write buffer.
+     * The buffer is flushed to disk in 64 KiB batches (and on `close()`),
+     * so the per-frame cost is one `Buffer.alloc` + array push — no syscall.
+     */
+    private writeFrames;
+    /** Write all buffered stereo bytes in one `writeSync` call. */
+    private flushPending;
+    private markBroken;
+}
+
 /**
  * OpenAI Realtime WebSocket adapter for Patter's realtime mode.
  *
@@ -347,8 +490,8 @@ declare class OpenAIRealtimeAdapter {
     protected readonly apiKey: string;
     protected readonly model: string;
     protected readonly voice: string;
-    protected readonly instructions: string;
-    protected readonly tools?: Array<{
+    protected instructions: string;
+    protected tools?: Array<{
         name: string;
         description: string;
         parameters: Record<string, unknown>;
@@ -547,6 +690,41 @@ declare class OpenAIRealtimeAdapter {
     sendReassurance(text: string): Promise<void>;
     /** Submit a tool/function-call result and request the next response. */
     sendFunctionResult(callId: string, result: string): Promise<void>;
+    /**
+     * Build the partial `session` body for a mid-session swap.
+     *
+     * v1-beta wire shape: flat `{ instructions, tools }`. The GA adapter
+     * overrides this to add the mandatory `"type": "realtime"` envelope.
+     * OpenAI merges partial `session.update` payloads server-side, so only the
+     * swapped fields are sent — audio formats, VAD tuning, and voice are
+     * untouched. Mirrors Python `_build_session_update_patch`.
+     */
+    protected buildSessionUpdatePatch(instructions: string | undefined, tools: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        strict?: boolean;
+    }> | undefined): Record<string, unknown>;
+    /**
+     * Apply a mid-session `instructions` / `tools` swap (multi-agent handoff).
+     *
+     * Sends a partial `session.update` carrying only the supplied fields and
+     * records them on the adapter so reconnect/warmup paths rebuild the
+     * session with the post-handoff config. Voice is intentionally NOT
+     * updatable here — OpenAI Realtime rejects a voice change once the session
+     * has produced audio, so the session keeps the voice established at call
+     * start (documented limitation). Mirrors Python
+     * `OpenAIRealtimeAdapter.update_session`.
+     */
+    updateSession(update: {
+        instructions?: string;
+        tools?: Array<{
+            name: string;
+            description: string;
+            parameters: Record<string, unknown>;
+            strict?: boolean;
+        }>;
+    }): Promise<void>;
     /** Stop the heartbeat, drop listeners, and close the Realtime WebSocket. */
     close(): void;
 }
@@ -620,6 +798,8 @@ declare class ElevenLabsConvAIAdapter {
     private finalizeAgentTurn;
     private scheduleSilenceDone;
     private handleMessage;
+    /** Answer a ``client_tool_call`` from the ElevenLabs agent. */
+    sendClientToolResult(toolCallId: string, result: string, isError?: boolean): void;
     /** 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. */
@@ -775,7 +955,7 @@ declare function calculateTelephonyCost(provider: string, durationSeconds: numbe
  * 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 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' | 'false_interruption';
 type Listener<T = unknown> = (payload: T) => void | Promise<void>;
 /** In-process pub/sub for Patter call-lifecycle events. */
 declare class EventBus {
@@ -912,11 +1092,29 @@ interface CallMetrics {
     /** Terminal error code when the call ended abnormally (a lowercased ErrorCode
      * value or "other"); empty/absent for a clean call. Never the message. */
     readonly error_code?: string;
+    /** PREEMPTIVE GENERATION counters (pipeline mode, only non-zero when
+     * `agent.preemptiveGeneration` is true). `preemptive_hits` counts
+     * speculative turns released on a matching final transcript (latency win);
+     * `preemptive_misses` counts speculations started but discarded
+     * (mismatched final, barge-in, replaced by a newer interim, buffer
+     * overflow) — i.e. wasted LLM/TTS spend. Mirrors Python
+     * `CallMetrics.preemptive_hits` / `preemptive_misses`. */
+    readonly preemptive_hits?: number;
+    readonly preemptive_misses?: number;
 }
 /** 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>;
+    /**
+     * Transfer the call to a different number or SIP URI.
+     *
+     * `options.mode === 'warm'` requests a hold-announce-bridge warm transfer
+     * (Twilio only for now); omitted / `'cold'` runs the historical blind
+     * redirect byte-identically. Warm mode resolves a
+     * {@link TransferCallResult} envelope (`{ error }` when unsupported or
+     * failed — the call keeps running); cold mode may resolve `void` (legacy
+     * contract). Mirrors Python `CallControl.transfer(number, mode=, summary=)`.
+     */
+    transfer(number: string, options?: TransferCallOptions): Promise<TransferCallResult | void>;
     /** Hang up the call. */
     hangup(): Promise<void>;
     /**
@@ -1000,6 +1198,8 @@ declare class CallMetricsAccumulator {
     private _actualTelephonyCost;
     private _actualSttCost;
     private _totalLlmCost;
+    private _preemptiveHits;
+    private _preemptiveMisses;
     private _llmModel;
     private _eventBus;
     /** Timestamp (hrTimeMs) when VAD emitted speech_end. */
@@ -1243,6 +1443,13 @@ declare class CallMetricsAccumulator {
             text_tokens?: number;
         };
     }, model?: string | null): void;
+    /** Count a preemptive (speculative) turn RELEASED on a matching final
+     * transcript — the buffered LLM+TTS work became the real turn. */
+    recordPreemptiveHit(): void;
+    /** Count a preemptive (speculative) turn started but discarded without
+     * release (mismatched final, barge-in during speculation, replaced by a
+     * newer interim, or buffer overflow). */
+    recordPreemptiveMiss(): 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. */
@@ -1527,6 +1734,1403 @@ declare class MetricsStore extends EventEmitter {
     hydrate(logRoot: string | null | undefined): number;
 }
 
+type AIAdapter = OpenAIRealtimeAdapter | ElevenLabsConvAIAdapter;
+/** Provider-specific operations that differ between Twilio, Telnyx and Plivo. */
+interface TelephonyBridge {
+    /** Human-readable label for log messages. */
+    readonly label: string;
+    /** Telephony provider name for metrics. */
+    readonly telephonyProvider: CarrierKind;
+    /** Wire format of the inbound media stream after the carrier has accepted
+     *  the call. Lets the StreamHandler decide whether to decode + resample
+     *  inbound audio without needing carrier-name knowledge — mulaw 8 kHz
+     *  carriers (Twilio, Plivo) say ``ulaw_8000``, PCM 16 kHz carriers
+     *  (Telnyx with PCMU bidirectional negotiation off) say ``pcm_16000``. */
+    readonly inputWireFormat: 'ulaw_8000' | 'pcm_16000';
+    /** Send an audio chunk (base64-encoded) to the telephony WebSocket. */
+    sendAudio(ws: WebSocket$1, audioBase64: string, streamSid: string): void;
+    /** Send a mark event to track audio playback progress (no-op for Telnyx). */
+    sendMark(ws: WebSocket$1, markName: string, streamSid: string): void;
+    /** Send a clear/interrupt event to stop audio playback. */
+    sendClear(ws: WebSocket$1, streamSid: string): void;
+    /** Transfer the call to a different number or SIP URI via provider API.
+     *  ``options.mode === 'warm'`` requests a hold-announce-bridge warm
+     *  transfer (Twilio only for now); the default / omitted options run the
+     *  historical cold (blind) redirect byte-identically. Returns a
+     *  {@link TransferCallResult} envelope for warm mode (``{ error }`` when
+     *  unsupported / failed — the call keeps running); cold mode may resolve
+     *  ``void`` (legacy contract). */
+    transferCall(callId: string, toNumber: string, options?: TransferCallOptions): Promise<TransferCallResult | void>;
+    /** Hang up the call via provider API. */
+    endCall(callId: string, ws: WebSocket$1): Promise<void>;
+    /** Send DTMF digits to the caller. Carriers using REST (Telnyx) ignore
+     *  ``ws``; carriers that send DTMF as a media-stream message (Plivo) use it. */
+    sendDtmf?(ws: WebSocket$1, callId: string, digits: string, delayMs: number): Promise<void>;
+    /** Start call recording via provider API (optional). */
+    startRecording?(callId: string): Promise<void>;
+    /** Stop call recording via provider API (optional). */
+    stopRecording?(callId: string): Promise<void>;
+    /** Create an STT instance appropriate for this provider's audio format.
+     *  Returns any of the supported STT adapters (DeepgramSTT, WhisperSTT,
+     *  CartesiaSTT, SonioxSTT, AssemblyAISTT) or null when no STT is configured. */
+    createStt(agent: AgentOptions): Promise<STTAdapter | null>;
+    /** Query actual telephony costs after call ends. */
+    queryTelephonyCost(metricsAcc: CallMetricsAccumulator, callId: string): Promise<void>;
+}
+/** Per-call dependencies injected into `StreamHandler` (immutable for the call's lifetime). */
+interface StreamHandlerDeps {
+    readonly config: {
+        readonly openaiKey?: string;
+        readonly twilioSid?: string;
+        readonly twilioToken?: string;
+    };
+    readonly agent: AgentOptions;
+    readonly bridge: TelephonyBridge;
+    readonly metricsStore: MetricsStore;
+    readonly pricing: Record<string, Partial<ProviderPricing>> | null;
+    readonly remoteHandler: RemoteMessageHandler;
+    /**
+     * Per-call start callback. A returned object is treated as PER-CALL AGENT
+     * OVERRIDES (snake_case keys: system_prompt, voice, model, language,
+     * first_message, provider, tools, variables) — parity with Python's
+     * ``apply_call_overrides``. Return nothing for the legacy observe-only
+     * behaviour.
+     */
+    readonly onCallStart?: (data: Record<string, unknown>) => Promise<void | Record<string, unknown> | undefined> | void | Record<string, unknown>;
+    readonly onCallEnd?: (data: Record<string, unknown>) => Promise<void>;
+    readonly onTranscript?: (data: Record<string, unknown>) => Promise<void>;
+    readonly onMessage?: PipelineMessageHandler | string;
+    readonly onMetrics?: (data: Record<string, unknown>) => Promise<void>;
+    readonly recording: boolean;
+    /**
+     * Optional factory returning a carrier-neutral local call recorder for
+     * ``callId`` (wired by ``EmbeddedServer.makeLocalRecorder`` when
+     * ``serve({ localRecording })`` is on). Returning ``null`` / leaving the
+     * field unset keeps every recording tap a no-op. The handler owns the
+     * recorder lifetime: created in ``handleCallStart``, finalized in
+     * ``fireCallEnd`` (every teardown path funnels there).
+     */
+    readonly makeLocalRecorder?: (callId: string) => LocalCallRecorder | null;
+    /** When true, only the first TTFB per call is forwarded to the event bus. Default false. */
+    readonly reportOnlyInitialTtfb?: boolean;
+    /**
+     * Optional speech-edge events dispatcher. When provided, the handler emits
+     * turn-taking edges (VAD start/stop, EOU commit, agent first/last wire
+     * chunk) as the call progresses. ``undefined`` means no events are fired
+     * — exact prior behaviour. See ``src/_speech-events.ts``.
+     */
+    readonly speechEvents?: SpeechEvents;
+    /** Build an AI adapter (OpenAI Realtime or ElevenLabs ConvAI). Injected to avoid circular imports. */
+    readonly buildAIAdapter: (resolvedPrompt: string, tools?: readonly ToolDefinition[]) => AIAdapter;
+    /** Sanitize untrusted key-value variables map. */
+    readonly sanitizeVariables: (raw: Record<string, unknown>) => Record<string, string>;
+    /** Replace {key} placeholders in a template string. */
+    readonly resolveVariables: (template: string, variables: Record<string, string>) => string;
+    /**
+     * Optional accessor returning pre-rendered first-message audio for
+     * ``callId``. Wired by ``Patter.serve()`` when the parent client has
+     * ``agent.prewarmFirstMessage: true``. Returning ``undefined`` means
+     * "no prewarm — always run live TTS".
+     */
+    readonly popPrewarmAudio?: (callId: string) => Buffer | undefined;
+    /**
+     * Optional accessor returning pre-opened, fully-handshaked provider
+     * WebSockets for ``callId`` so the per-call StreamHandler can
+     * adopt them at ``start`` instead of paying the cold handshake on
+     * the first turn. Wired by ``Patter.serve()``. Returning
+     * ``undefined`` (or any sub-field unset) means "no parked socket
+     * for this provider — fall back to fresh ``connect()``".
+     */
+    readonly popPrewarmedConnections?: (callId: string) => ParkedProviderConnections | undefined;
+}
+/** Per-call session controller — owns the AI adapter, STT/TTS pipeline, and metrics. */
+declare class StreamHandler {
+    private readonly deps;
+    private readonly ws;
+    private caller;
+    private callee;
+    private streamSid;
+    private callId;
+    private adapter;
+    private stt;
+    private tts;
+    private isSpeaking;
+    /**
+     * True only while the post-TTS tail-grace window is pending: the agent has
+     * finished its turn but ``isSpeaking`` is still held for
+     * ``PATTER_TTS_TAIL_GRACE_MS`` to swallow the fading echo tail. A VAD
+     * ``speech_start`` (or a transcript) during this window is the user's NEXT
+     * turn, not a barge-in — there is nothing left to interrupt. Set by
+     * ``endSpeakingWithGrace``; cleared by ``beginSpeaking``, the grace flip,
+     * ``cancelSpeaking``, and ``endTailGraceForNewTurn``. Parity with Python
+     * ``_tail_grace_active``.
+     */
+    private tailGraceActive;
+    /**
+     * Ring buffer of inbound PCM16 16 kHz frames captured while the agent
+     * is speaking and the self-hearing guard is dropping audio. On
+     * barge-in we flush this buffer to STT so Deepgram (or any other
+     * streaming STT) receives the user's first ~500 ms of speech — which
+     * would otherwise be lost while the VAD's `minSpeechDuration` window
+     * accumulated and fired `speech_start`. Each frame is 20 ms × 32 bytes
+     * (16 kHz × 16-bit mono) ≈ 640 bytes.
+     *
+     * Capped to ``INBOUND_AUDIO_RING_FRAMES`` to recover only the
+     * VAD-missed leading edge of the user's speech (default 250 ms,
+     * matching SileroVAD ``minSpeechDuration``). Earlier values up to
+     * 600 ms were including ~350 ms of pre-speech silence/agent-bleed in
+     * the replay; on PSTN (where AEC is a no-op) Deepgram trained on
+     * English happily transcribes that bleed as English garbage
+     * (``"The same as Edgar,"``, ``"Permadees."``) and commits it to
+     * the LLM as a phantom user transcript. See BUGS.md 2026-05-05
+     * post-barge-in bleed-transcription entry.
+     */
+    private inboundAudioRing;
+    private static readonly INBOUND_AUDIO_RING_FRAMES;
+    /**
+     * Cached LLM provider tag used by speech-event payloads. Mirrors the
+     * value passed to the metrics accumulator at construction time so the
+     * speech-edge events report the same provider classification as
+     * dashboard / pricing rows.
+     */
+    private llmProviderTag;
+    /**
+     * Auto-loaded SileroVAD when ``agent.vad`` is undefined. Populated by
+     * ``initPipeline`` and queried alongside ``agent.vad`` on every audio frame.
+     * Stays null when ``onnxruntime-node`` is not installed — the pipeline
+     * then falls back to the STT-endpoint heuristic (legacy behaviour).
+     */
+    private autoVad;
+    /**
+     * Acoustic echo canceller (NLMS adaptive filter). Lazily instantiated in
+     * ``initPipeline`` when ``agent.echoCancellation`` is true. ``null``
+     * otherwise — the mic path stays a pure pass-through for handset /
+     * headset deployments that don't have TTS bleed.
+     */
+    private aec;
+    /**
+     * Carrier-neutral local call recorder (stereo WAV; left=caller,
+     * right=agent). Created in ``handleCallStart`` via
+     * ``deps.makeLocalRecorder`` when ``serve({ localRecording })`` is on;
+     * ``null`` keeps every tap a no-op. Finalized (header patched, file
+     * closed) in ``fireCallEnd`` — both ``handleStop`` and ``handleWsClose``
+     * funnel there, so abnormal teardown still yields a parseable file.
+     * Parity with Python ``StreamHandler.local_recorder``.
+     */
+    private localRecorder;
+    /**
+     * Monotonic counter incremented on every TTS-start. The grace timer
+     * scheduled by ``endSpeakingWithGrace`` only flips ``isSpeaking=false``
+     * if the counter still matches its capture — a new turn that started in
+     * the meantime invalidates the obsolete timer instead of clobbering its
+     * own ``isSpeaking=true``.
+     */
+    private speakingGeneration;
+    /**
+     * Wall-clock timestamp (ms since epoch) when the current TTS turn
+     * started — captured by ``beginSpeaking`` and cleared by
+     * ``cancelSpeaking`` / the grace flip. Used to gate barge-in: we
+     * suppress the cancel for the first
+     * ``MIN_AGENT_SPEAKING_MS_BEFORE_BARGE_IN_AEC`` of every turn (when AEC
+     * is on) so the AEC filter has time to converge — otherwise residual
+     * TTS bleed in the mic stream looks like user speech to VAD and
+     * triggers an immediate self-cancellation of the agent's first
+     * sentence.
+     */
+    private speakingStartedAt;
+    /**
+     * Wall-clock (ms) when the FIRST TTS audio chunk actually reached the
+     * carrier wire — set in ``markFirstAudioSent`` after ``bridge.sendAudio``
+     * succeeds, cleared by ``beginSpeaking`` / ``cancelSpeaking``. The barge-in
+     * gate measures elapsed from this instant, NOT from ``speakingStartedAt``,
+     * because ElevenLabs (and other cloud TTS) take 200-700 ms to emit the
+     * first byte. A gate anchored to ``beginSpeaking`` would expire on
+     * background noise before any audio went out, exit the TTS loop on
+     * ``isSpeaking=false``, and silently cut the agent's first turn.
+     */
+    private firstAudioSentAt;
+    /**
+     * Estimated wall-clock (ms) when the LAST audio byte pushed to the carrier
+     * finishes PLAYING on the phone. The pipeline pushes TTS audio as fast as
+     * the provider synthesizes it (no pacing) and the carrier buffers + plays
+     * at realtime, so "we finished pushing" and "the caller finished hearing"
+     * can diverge by tens of seconds — especially with agent-runtime LLMs
+     * (Hermes/OpenClaw) that deliver a long reply all at once after a thinking
+     * pause. ``endSpeakingWithGrace`` holds ``isSpeaking=true`` (with
+     * ``tailGraceActive=false``) until this cursor passes, so a barge-in during
+     * the audible backlog still takes the cancel path (``sendClear`` drops the
+     * carrier buffer) instead of being treated as a calm next turn. Advanced by
+     * ``trackOutboundPlayback``; reset by ``cancelSpeaking`` (the buffer is
+     * cleared) and ``endTailGraceForNewTurn``.
+     */
+    private playbackBufferedUntil;
+    /**
+     * Per-turn playback timeline used to estimate the response prefix the
+     * caller actually HEARD when a barge-in lands. ``turnPlaybackTotalMs``
+     * accumulates the playout duration of every chunk pushed this turn
+     * (including filler audio, which keeps the timeline aligned);
+     * ``turnSpokenSegments`` records ``{text, startMs}`` for each RESPONSE
+     * sentence at its first audible chunk (filler / error-fallback audio
+     * advances the clock but adds no segment). ``heard = total - backlog``
+     * then maps to a sentence-granular prefix — see ``heardResponsePrefix``.
+     * Both reset at ``beginSpeaking``. Mirrors Python
+     * ``_turn_playback_total_s`` / ``_turn_spoken_segments``.
+     */
+    private turnPlaybackTotalMs;
+    private turnSpokenSegments;
+    /**
+     * Optional barge-in confirmation strategies. With an empty array the
+     * SDK falls back to the legacy "cancel on first VAD speech_start"
+     * behaviour. With one or more strategies, a VAD speech_start during
+     * TTS marks the barge-in as *pending* — TTS keeps streaming naturally
+     * — and the strategies are consulted on every STT transcript via
+     * ``handleBargeIn``. The first strategy that returns ``true`` cancels
+     * the agent; if none confirm within ``bargeInConfirmMs`` the pending
+     * state is dropped and the agent finishes its sentence.
+     */
+    private readonly bargeInStrategies;
+    /** Pending-barge-in confirmation timeout in milliseconds. */
+    private readonly bargeInConfirmMs;
+    /** Wall-clock (ms) when the current pending barge-in started, or
+     * ``null`` if no barge-in is pending. */
+    private bargeInPendingSince;
+    /** Timer that fires the pending-barge-in timeout. In
+     * ``bargeInMode: 'pause_resume'`` this same handle holds the
+     * false-interruption resume timer. */
+    private bargeInPendingTimer;
+    /**
+     * Pause-and-resume false-interruption handling (opt-in
+     * ``agent.bargeInMode: 'pause_resume'``; default ``'cancel'`` keeps
+     * today's behaviour byte-identical): PAUSE output on
+     * VAD speech_start (carrier cleared, sends gated on ``outputPaused``),
+     * KILL on a committed final transcript within ``bargeInConfirmMs``,
+     * RESUME from the first not-fully-heard sentence otherwise. Mirrors
+     * Python ``_barge_in_mode`` / ``_output_paused``.
+     */
+    private readonly bargeInMode;
+    /** True while output is paused: ``synthesizeSentence`` queues chunks
+     * into per-sentence retention entries instead of sending, and the LLM
+     * loops buffer whole sentences as text. */
+    private outputPaused;
+    /** Per-pause decision latch — resolved when the pause resolves
+     * (resume, kill, or teardown) so loop-side waiters can proceed. */
+    private pauseDecision;
+    /** Sentences produced by the LLM while paused (text, pre-guardrail).
+     * Spoken in order on resume; discarded on kill. Bounded by
+     * ``PAUSE_MAX_BUFFERED_SENTENCES`` — overflow degrades to a full
+     * cancel so memory stays bounded against a runaway stream. */
+    private pausedSentences;
+    /**
+     * Per-turn retained sentence audio (pause_resume mode only): one entry
+     * per response sentence holding every TTS chunk produced for it.
+     * ``sent`` counts chunks actually delivered to the carrier — the
+     * resume path resets it to 0 for the unheard tail and re-sends from
+     * memory (no TTS re-billing). Index-aligned with
+     * ``turnSpokenSegments`` for the stamped prefix. Bounded by
+     * ``PAUSE_RESUME_MAX_RETAINED_S``.
+     */
+    private turnSentenceAudio;
+    private pauseRetainedBytes;
+    /** Set when the retained-audio cap was exceeded while NOT paused (very
+     * long carrier backlog): retention is released and pause_resume falls
+     * back to legacy cancel for the rest of the turn. Reset at
+     * ``beginSpeaking``. */
+    private pauseResumeOverflowed;
+    /** Sentence index (into ``turnSpokenSegments`` / ``turnSentenceAudio``)
+     * of the first sentence the caller had NOT fully heard at pause time —
+     * the resume offset. Sentence granularity: the partially-played
+     * sentence is replayed from its start (natural-sounding repair) rather
+     * than resumed mid-word. */
+    private pauseResumeIndex;
+    /** False until the turn body finishes pushing audio (the
+     * ``endSpeakingWithGrace`` call in its finally). The resume path uses
+     * it to decide whether the #164 grace machinery must be re-armed for
+     * the re-sent tail (post-complete pause) or whether the still-running
+     * turn body will arm it itself. */
+    private turnOutputDone;
+    /** Cap on sentences buffered as text while output is paused. A pause
+     * lasts at most ``bargeInConfirmMs`` (1.5 s default) so this is
+     * generous; overflow degrades to a full cancel. Mirrors Python
+     * ``_PAUSE_MAX_BUFFERED_SENTENCES``. */
+    private static readonly PAUSE_MAX_BUFFERED_SENTENCES;
+    /** Cap (seconds of playout) on retained per-sentence TTS audio — both
+     * the already-sent tail kept for re-send and chunks queued while
+     * paused. 15 s ≈ 480 KB of PCM16 @ 16 kHz per concurrent call.
+     * Overflow while paused → degrade to full cancel; overflow while
+     * speaking → release retention and fall back to legacy cancel for the
+     * rest of the turn. Mirrors Python ``_PAUSE_RESUME_MAX_RETAINED_S``. */
+    private static readonly PAUSE_RESUME_MAX_RETAINED_S;
+    /**
+     * Set to true when a VAD ``speech_start`` was suppressed by the
+     * anti-echo gate during the current agent turn.  Cleared on
+     * ``beginSpeaking`` and ``cancelSpeaking``.  When the turn ends
+     * naturally (grace timer), the inbound audio ring is flushed to STT
+     * so the user's speech is not silently discarded.
+     */
+    private suppressedSpeechPending;
+    /** Rolling window byte budget: the last 8 s of PCM16 @ 16 kHz. */
+    private static readonly SEMANTIC_WINDOW_MAX_BYTES;
+    /** Re-score cadence while holding: one prediction per this much silence. */
+    private static readonly SEMANTIC_POLL_MS;
+    /** Rolling buffer of post-decode PCM16-16k frames (bounded to 8 s). */
+    private semanticAudioRing;
+    private semanticAudioRingBytes;
+    /** True while a sub-threshold prediction is holding the finalize open. */
+    private semanticHoldActive;
+    /** Wall-clock (ms) deadline for the hard cap, null when idle. */
+    private semanticHoldDeadlineMs;
+    /** Invalidates the backstop timer once its hold has been resolved. */
+    private semanticHoldGeneration;
+    /** Wall-clock backstop — finalizes at the cap even if audio stalls. */
+    private semanticHoldTimer;
+    /** Bytes accumulated since the last prediction while holding. */
+    private semanticPollPendingBytes;
+    /**
+     * Set on the FIRST detector failure: semantic endpointing is then
+     * disabled for the remainder of the call (one clear warning, plain
+     * VAD-silence behavior) instead of warning per turn against a
+     * permanently broken model. Mirrors Python ``_semantic_detector_failed``
+     * and the existing ``vadDisabled`` fail-once pattern.
+     */
+    private turnDetectorFailed;
+    /**
+     * EOU trigger for the NEXT committed turn. Stamped by the semantic
+     * finalize paths, consumed (and reset) on transcript commit. Parity
+     * with Python ``_last_eou_trigger``.
+     */
+    private lastEouTrigger;
+    /** Hard cap (ms) a semantic hold may defer the finalize. */
+    private readonly maxSemanticHoldMs;
+    /**
+     * Minimum wall-clock duration (ms) the agent must have been speaking
+     * before barge-in is allowed to fire when AEC is active. Covers the
+     * AEC warmup window (~500 ms) plus a safety margin so residual bleed
+     * during the convergence period does not self-trigger barge-in.
+     */
+    private static readonly MIN_AGENT_SPEAKING_MS_BEFORE_BARGE_IN_AEC;
+    /**
+     * Same as the AEC variant but for deployments where AEC is OFF
+     * (default on PSTN — Twilio/Telnyx). Without an adaptive filter to
+     * converge, the only justification for a gate is anti-flicker on
+     * micro-events (cough, click). Raised 100 → 500 ms on 2026-05-19
+     * after the 0.6.2 acceptance run showed a phantom VAD speech_start
+     * firing on the very first inbound frame (~500 ms into the call,
+     * which is past a 100 ms gate). The phantom barge-in cancelled the
+     * prewarmed firstMessage, the user heard a clipped (graffiante)
+     * audio fragment, and the SDK left ``_turnAlreadyClosed=true`` so
+     * subsequent ``recordTurnComplete`` calls were no-ops. 500 ms
+     * filters those phantoms while still letting a real interruption
+     * land within half a second of agent onset.
+     */
+    private static readonly MIN_AGENT_SPEAKING_MS_BEFORE_BARGE_IN_NO_AEC;
+    /** Handle for the pending grace-period timer, so it can be cleared on cleanup. */
+    private graceTimer;
+    /**
+     * AbortController for the current LLM streaming consumption.  Aborted by
+     * ``cancelSpeaking`` so the in-flight LLM stream stops generating tokens
+     * we will never speak — saves provider cost and frees the connection
+     * earlier.  Mirrors Python ``_llm_cancel_event``.
+     */
+    private llmAbort;
+    /**
+     * Wall-clock timestamp of the most recent ``cancelSpeaking`` call, or
+     * ``null`` if no cancel has fired since the call started. Used by
+     * ``beginSpeaking`` to enforce a short post-cancel drain window so the
+     * remote PSTN player finishes flushing the previous turn's in-flight
+     * audio before the next TTS chunk lands on top of it. Without this,
+     * the first sentence of a post-barge-in turn audibly overlaps with
+     * the tail of the cancelled turn (~50-200 ms of doubled audio).
+     */
+    private lastCancelAt;
+    /**
+     * Promise queue tracking outstanding Twilio marks the SDK has sent but
+     * not yet seen echoed back. Used by the firstMessage send loop to bound
+     * the depth of audio queued at the carrier — without this the loop
+     * pushes the entire TTS stream into Twilio's WebSocket in one burst,
+     * and a sendClear issued mid-buffer races against several seconds of
+     * already-queued media frames (BUG #128). The window depth is
+     * ``FIRST_MESSAGE_MARK_WINDOW``; ``onMark`` drains entries as Twilio
+     * confirms playback, ``cancelSpeaking`` resolves every pending entry so
+     * any awaiter exits immediately. Telnyx never populates this queue
+     * (Telnyx's media-stream protocol has no mark concept — the loop
+     * falls back to time-based pacing on that carrier).
+     */
+    private pendingMarks;
+    /**
+     * Monotonic counter for first-message mark names. Distinct from
+     * ``chunkCount`` (which the Realtime path uses) so the two paths can
+     * coexist without name collisions even when firstMessage finishes while
+     * a Realtime turn is still streaming.
+     */
+    /**
+     * Minimum drain window (ms) between a ``cancelSpeaking`` and the next
+     * ``beginSpeaking``. 150 ms covers a typical PSTN jitter buffer drain
+     * + Twilio Media Stream clear propagation. Lower values risk audio
+     * overlap on the first chunk; higher values increase the perceived
+     * "agent ack" latency after a barge-in. 150 ms is the smallest value
+     * that consistently eliminated the overlap during 0.6.0 acceptance.
+     */
+    private static readonly POST_CANCEL_DRAIN_MS;
+    /**
+     * Mark the start of a TTS span. Use instead of setting isSpeaking
+     * directly. Awaits the post-cancel drain window before flipping state
+     * so the remote player has time to flush the cancelled turn's tail.
+     */
+    private beginSpeaking;
+    /**
+     * Record that the first TTS audio chunk of the current turn has hit the
+     * carrier wire. Idempotent within a turn — only the first call sets the
+     * timestamp; later chunks are no-ops. Must be invoked AFTER the underlying
+     * ``bridge.sendAudio`` resolves so the gate is anchored to "audio actually
+     * went out", not "we asked the carrier to send it".
+     */
+    private markFirstAudioSent;
+    /**
+     * Advance ``playbackBufferedUntil`` by the playout duration of an outbound
+     * TTS chunk. ``numBytes`` is the size of the chunk BEFORE carrier encoding
+     * (the same buffer handed to ``encodePipelineAudio``): PCM16 @ 16 kHz in
+     * the default path (32 bytes/ms), or the carrier's native μ-law @ 8 kHz
+     * (8 bytes/ms) when the TTS adapter emits wire format directly
+     * (``ttsOutputFormatNativeForCarrier`` — Twilio/Plivo ``ulaw_8000``;
+     * Telnyx native is ``pcm_16000`` so it stays at 32 bytes/ms).
+     */
+    private trackOutboundPlayback;
+    /**
+     * Estimate the response prefix the caller actually HEARD this turn.
+     *
+     * The pipeline pushes audio faster than realtime, so at barge-in time
+     * ``heard = totalPushed - carrierBacklog`` ms of audio have actually
+     * played. Mapped at sentence granularity against ``turnSpokenSegments``:
+     * a sentence counts as heard once its playback has STARTED
+     * (``startMs <= heardMs``), so the sentence playing at the moment of
+     * interruption is included.
+     *
+     * Returns ``null`` when no segments were tracked this turn (nothing
+     * synthesized through the tracked path — callers fall back to the legacy
+     * full-text behaviour). Mirrors Python ``_heard_response_prefix``.
+     */
+    private heardResponsePrefix;
+    /**
+     * Replace the text of the most recent assistant entry in the conversation
+     * history. No-op when the last entry is not an assistant turn (e.g. the
+     * caller's next turn was already committed).
+     */
+    private rewriteLastAssistantEntry;
+    /**
+     * Heard-prefix semantics for a barge-in that lands AFTER
+     * the turn completed, while the carrier is still playing the buffered
+     * tail.
+     *
+     * The completed turn already recorded its FULL reply in history, but the
+     * caller only heard part of it before interrupting — a stateful agent
+     * runtime (Hermes / OpenClaw) would otherwise "remember saying" things
+     * the caller never heard. Rewrites the last assistant entry to the heard
+     * prefix + ``[interrupted by caller]``.
+     *
+     * MUST run BEFORE ``cancelSpeaking`` resets ``playbackBufferedUntil``
+     * (the backlog is the heard-prefix input). No-op when a turn is still in
+     * flight (the streaming path applies its own marker), when there is no
+     * backlog, or when everything was already heard. Mirrors Python
+     * ``_maybe_truncate_completed_turn_history``.
+     */
+    private maybeTruncateCompletedTurnHistory;
+    /**
+     * Atomically end speaking AND invalidate any pending grace timer.
+     * Use instead of ``this.isSpeaking = false`` at barge-in sites.
+     *
+     * Also aborts the in-flight LLM stream (if any) so the provider stops
+     * billing tokens we will never speak.
+     */
+    private cancelSpeaking;
+    /**
+     * Resolve every entry in ``pendingMarks`` and empty the queue. Idempotent
+     * — safe to call from ``cancelSpeaking`` and again from the grace path
+     * without leaking pending promises.
+     */
+    private drainPendingMarks;
+    /**
+     * Bytes-per-millisecond for a 16 kHz PCM16 mono stream. Used by
+     * ``sendPacedFirstMessageBytes`` to translate chunk size into a
+     * playout-duration sleep so we never deliver faster than the carrier
+     * can decode + play out (which manifested as severe crackling on the
+     * HTTP-TTS path with client-side resampling). 16000 samples/sec × 2
+     * bytes/sample = 32 bytes/ms.
+     */
+    private static readonly PCM16_16K_BYTES_PER_MS;
+    /** Cancel and clear the pending grace timer, if any. */
+    private clearGraceTimer;
+    /**
+     * Mark the agent as no longer producing TTS, honoring a grace period that
+     * approximates the carrier's playback buffer. The user may still hear the
+     * agent for ~1 s after we finish pushing audio (Twilio buffers ~1500 ms);
+     * keeping isSpeaking=true through that window keeps the VAD-driven
+     * barge-in armed during the audible tail. Tunable via env.
+     */
+    private endSpeakingWithGrace;
+    /**
+     * End the post-TTS tail-grace window because the user has begun their next
+     * turn. Unlike a barge-in, the agent's response already played out in full
+     * — there is nothing to cancel and no turn was interrupted. We flip the
+     * speaking flag off (bumping ``speakingGeneration`` so the scheduled grace
+     * timer no-ops), recover any leading audio the self-hearing guard captured
+     * into the ring (the user's first ~250 ms, which VAD needed before it could
+     * emit ``speech_start``), and let the live STT stream take over. We do NOT
+     * call ``sendClear``, ``recordBargeinDetected`` or ``recordTurnInterrupted``
+     * — none apply to a turn that completed normally.
+     *
+     * Without this, fast next-turn speech (humans reply in 200-700 ms, well
+     * inside the 1500 ms default grace) is withheld from STT and recorded as an
+     * empty ``[interrupted]`` turn, after which the agent goes silent for the
+     * rest of the call. Parity with Python ``_end_tail_grace_for_new_turn``.
+     */
+    private endTailGraceForNewTurn;
+    private resetBargeInStrategies;
+    /**
+     * Reset the active VAD provider's per-utterance state. No-op when the
+     * provider does not implement the optional ``reset()`` hook. Safe to call
+     * from any context — failures are swallowed and the VAD is disabled for
+     * the rest of the call so a flaky reset can never silently kill barge-in
+     * for every subsequent turn.
+     */
+    private resetVad;
+    /**
+     * Whether barge-in is allowed to fire right now. Gate length depends
+     * on whether AEC is active: 1 s with AEC (covers filter warmup),
+     * 250 ms without (anti-flicker only — keeps PSTN barge-in responsive).
+     */
+    private canBargeIn;
+    /**
+     * Replay the audio captured by the self-hearing guard right before a
+     * confirmed barge-in. VAD's ``minSpeechDuration`` window (default
+     * 250 ms) means ``speech_start`` fires only AFTER the user has been
+     * talking for that long; without this replay STT sees only the tail
+     * of the user's interruption and produces "the line is breaking up"
+     * partial transcripts. We deliberately do NOT call this on natural
+     * turn end — see the comment in ``endSpeakingWithGrace`` for why.
+     */
+    private flushInboundAudioRing;
+    /**
+     * Per-call resolved tool list. Starts as ``null`` (falls back to
+     * ``deps.agent.tools``). Populated by ``initMcpTools`` when MCP servers
+     * are configured so discovered tools are merged in without mutating the
+     * shared ``AgentOptions`` object. Code that needs the effective tool list
+     * should read ``this.resolvedTools ?? this.deps.agent.tools``.
+     */
+    private resolvedTools;
+    /**
+     * Per-call effective agent configuration. Starts as ``deps.agent`` and is
+     * REPLACED (never mutated — ``AgentOptions`` is shared and readonly) by a
+     * multi-agent ``handoff_to`` so the rest of the call runs with the target
+     * agent's LLM-visible config (system prompt, tools, variables, guardrails,
+     * text transforms, onward handoffs). Parity with the Python handler's
+     * ``self.agent`` swap.
+     */
+    private currentAgent;
+    private llmLoop;
+    /**
+     * Per-call tool executor — provides retry-with-exponential-backoff and a
+     * per-tool circuit breaker for Realtime function calls. Pipeline mode
+     * uses its own executor inside ``LLMLoop``; this one is dedicated to
+     * the Realtime path so a flaky downstream (DB outage, vendor rate
+     * limit) returns a structured ``{ error, fallback: true }`` instead of
+     * hanging the model on retries that will keep failing.
+     */
+    private readonly toolExecutor;
+    /**
+     * MCP server connection manager — populated lazily in
+     * ``initMcpTools()`` when the agent declares ``mcpServers``. Holds
+     * the open MCP client connections for the lifetime of the call so
+     * we can dispatch ``tools/call`` without re-handshaking on every
+     * function invocation. Cleared in ``fireCallEnd``.
+     */
+    private mcpManager;
+    private chunkCount;
+    private callEndFired;
+    private sttClosed;
+    private currentAgentText;
+    private responseAudioStarted;
+    /**
+     * Realtime turn ordering buffer. OpenAI Realtime emits
+     * `input_audio_transcription.completed` (user transcript) AFTER
+     * `response.done` (assistant complete) because Whisper transcription
+     * runs in parallel with — and slower than — model response. Without
+     * this buffer the pushed `history` order is [assistant, user, ...]
+     * which renders out-of-order in the dashboard.
+     *
+     * Behaviour:
+     *  - `onAdapterSpeechStopped` flips `userTranscriptPending = true`
+     *  - `onAdapterResponseDone` checks the flag; if set, stashes the
+     *    assistant text + a fallback timer
+     *  - `onAdapterTranscriptInput` clears the flag, pushes user, then
+     *    flushes any pending assistant turn
+     *  - The fallback timer flushes the assistant alone if the user
+     *    transcript never arrives (silence misclassified as speech, etc.)
+     */
+    private userTranscriptPending;
+    private pendingAssistantTurn;
+    private pendingAssistantTimer;
+    /**
+     * Reserved monotonic turn index for the in-flight Realtime turn (issue
+     * #154, fix 5/6). Reserved in ``onAdapterSpeechStopped`` via
+     * ``metricsAcc.reserveTurnIndex()`` the moment the turn OPENS, then threaded
+     * through to the live per-line transcript events (``recordTranscriptLine``)
+     * and into ``recordTurnComplete`` / ``recordTurnInterrupted`` so the
+     * dashboard can sort a late-arriving user line ABOVE its agent line by
+     * ``(turnIndex, role)``. ``null`` until the first turn opens. Parity with
+     * Python ``_current_turn_index``.
+     */
+    private currentTurnIndex;
+    /**
+     * Hard cap on how long we wait for the user transcript before flushing
+     * the buffered assistant turn alone. 3 s covers OpenAI Whisper's typical
+     * 200-800 ms post-response delay with substantial headroom for slow
+     * cellular audio uploads. Beyond this we accept the order will look
+     * "assistant-only" rather than block the call's transcript display.
+     */
+    private static readonly REALTIME_USER_TRANSCRIPT_WAIT_MS;
+    private maxDurationTimer;
+    private transcriptProcessing;
+    private transcriptQueue;
+    /**
+     * The in-flight turn dispatch (LLM + TTS) runs as a SINGLE tracked promise
+     * so the transcript drain loop keeps running ``handleBargeIn`` against the
+     * LIVE turn during a long (30-90 s) agent-runtime response, instead of
+     * head-of-line-blocking on it. Exactly one is in flight: the launcher awaits
+     * the previous one to settle (fast — a barge-in already aborted it) before
+     * starting the next, preserving history/metrics ordering. Parity with
+     * Python ``_dispatch_task``.
+     */
+    private dispatchTask;
+    /** Background greeting playback (see playFirstMessage). */
+    private firstMessageTask;
+    /**
+     * Cap (ms) on how long teardown waits for the backgrounded dispatch to
+     * settle. JS promises are not cancellable, so a user-supplied ``onMessage``
+     * (which receives no AbortSignal) parked on a hung external call could block
+     * call cleanup indefinitely — `llmAbort.abort()` only unblocks the built-in
+     * LLM/TTS paths. We bound the WAIT (Python hard-cancels the task instead).
+     * 30 s matches the webhook ceiling.
+     */
+    private static readonly DISPATCH_SETTLE_TIMEOUT_MS;
+    /**
+     * Opt-in (default OFF): forward inbound audio to STT even while the agent is
+     * speaking, so the transcript barge-in path can receive a transcript on
+     * echo-masked PSTN links where the VAD never fires. ECHO RISK without AEC.
+     * Parity with Python ``_forward_stt_while_speaking``.
+     */
+    private readonly forwardSttWhileSpeaking;
+    private lastCommitText;
+    private lastCommitAt;
+    private readonly preemptiveEnabled;
+    private readonly preemptiveMinStableMs;
+    /** The single in-flight speculation (at most one). ``null`` when idle,
+     * when discarded, or once released (a released speculation becomes the
+     * live turn tracked by ``dispatchTask`` instead). */
+    private speculation;
+    private interimNorm;
+    private interimText;
+    private interimStableTimer;
+    /** Hard cap (ms of playout) on TTS audio buffered by a speculative turn.
+     * Overflow aborts the speculation. Parity with Python
+     * ``_PREEMPTIVE_MAX_BUFFER_S``. */
+    private static readonly PREEMPTIVE_MAX_BUFFER_MS;
+    /** The agent's spoken text for the CURRENT turn, accumulated as tokens stream.
+     * The echo guard rejects transcripts matching it (the agent's own TTS bleeding
+     * back into STT when audio is forwarded during TTS without effective AEC).
+     * Reset in ``beginSpeaking``; only consulted while ``forwardSttWhileSpeaking``.
+     * Parity with Python ``_current_agent_spoken_text``. */
+    private currentAgentSpokenText;
+    private ttsByteCarry;
+    private readonly inboundResampler;
+    private readonly outboundResampler;
+    /**
+     * Inbound audio processing chain: decode (mulaw→PCM16) → stateful 8k→16k
+     * resample → AEC near-end → ``agent.audioFilter`` → VAD (slice 1 of the
+     * pipeline-stages decomposition — docs/architecture/pipeline-stages.md).
+     * Shares ``inboundResampler`` so ``flushResamplers`` keeps draining the
+     * tail on call close; AEC / filter / VAD are late-bound getters because
+     * ``initPipeline`` (and the unit suites) install ``aec`` / ``autoVad``
+     * after construction. Owns the per-call VAD error kill switch that
+     * previously lived here as ``vadDisabled``.
+     */
+    private readonly inputChain;
+    private readonly history;
+    private readonly metricsAcc;
+    private readonly _eventBus;
+    constructor(deps: StreamHandlerDeps, ws: WebSocket$1, caller: string, callee: string);
+    /**
+     * Record a completed turn in the dashboard store and fire the user-supplied
+     * ``onMetrics`` callback. Centralises the 4 emit sites (firstMessage, pipeline
+     * streaming/regular LLM, WebSocket remote, Realtime response_done) so the
+     * payload shape lives in one place.
+     */
+    /**
+     * Emit a live per-line transcript event to the dashboard store (issue #154,
+     * fix 5). Routed through a single helper so the call shape lives in one
+     * place. ``recordTranscriptLine`` appends the line to the active call's
+     * transcript and publishes a ``transcript_line`` SSE event; the dashboard
+     * sorts by (turnIndex, user<assistant) so a late user line lands above its
+     * agent line. No-op when no turn index has been reserved yet.
+     */
+    private emitTranscriptLine;
+    private emitTurnMetrics;
+    /** Reset the TTS odd-byte carry — call at every TTS stream entry/exit. */
+    private resetTtsCarry;
+    /**
+     * Flush both stateful resamplers and any TTS byte carry on call close.
+     * Emits tail bytes through the telephony bridge so the last ~20 ms of audio
+     * is not silently clipped on hangup. No-op if the WebSocket is already gone.
+     */
+    private flushResamplers;
+    /**
+     * Start call recording when configured. Bridges expose
+     * ``startRecording`` for carrier parity (Twilio and Telnyx supported).
+     */
+    private startRecordingIfRequested;
+    /**
+     * Subscribe to a Patter event on the per-call EventBus.
+     *
+     * The most common use-case is 'metrics_collected' — fired after every
+     * completed turn with the TurnMetrics payload.
+     *
+     * Returns an unsubscribe function; call it to stop receiving events.
+     *
+     * @example
+     * const off = handler.addObserver((payload) => {
+     *   console.log('turn metrics:', payload);
+     * });
+     * // later:
+     * off();
+     */
+    addObserver<T = unknown>(cb: (payload: T) => void | Promise<void>, event?: PatterEventType): () => void;
+    /**
+     * Handle the call-start event.
+     *
+     * @param callId       Call SID (Twilio) or call_control_id (Telnyx)
+     * @param customParams TwiML custom parameters (Twilio only, empty for Telnyx)
+     */
+    /** Initialize per-call state, build the AI adapter, and dispatch the `onCallStart` callback. */
+    handleCallStart(callId: string, customParams?: Record<string, string>): Promise<void>;
+    /**
+     * Connect to every configured MCP server, discover their tools via
+     * ``tools/list``, and merge them into ``agent.tools`` before the
+     * adapter is built. The synthetic handlers dispatch back through the
+     * MCP client so ``DefaultToolExecutor`` can invoke them like any
+     * other handler-tool. No-op when ``agent.mcpServers`` is empty or the
+     * optional ``@modelcontextprotocol/sdk`` is not installed.
+     */
+    private initMcpTools;
+    /**
+     * Merge the built-in ``consult`` tool into the per-call tool list when
+     * ``agent.consult`` is set, mirroring {@link initMcpTools}: the shared
+     * ``deps.agent`` is NOT mutated; the merged list is stored on
+     * ``this.resolvedTools`` so ``buildAIAdapter`` (Realtime) and the pipeline
+     * ``LLMLoop`` both see it. Idempotent — a no-op if a tool with the same name
+     * is already present.
+     */
+    private injectConsultTool;
+    /** Set the stream SID (Twilio only, called after parsing 'start' event). */
+    /** Set the carrier-side stream id (Twilio `streamSid` / Telnyx stream identifier). */
+    setStreamSid(sid: string): void;
+    /**
+     * Record a terminal/processing error as a coarse, anonymous code on the call
+     * metrics (code only, never the message). Surfaced via `call_completed`
+     * telemetry. Safe to call with any value; last write wins.
+     */
+    recordError(err: unknown): void;
+    /** Handle an incoming audio chunk (already decoded from base64). */
+    /** Forward inbound audio bytes to the AI adapter and (in pipeline mode) the STT provider. */
+    handleAudio(audioBuffer: Buffer): Promise<void>;
+    /** Handle a DTMF keypress event (Twilio only). */
+    /** Handle an inbound DTMF tone from the caller. */
+    handleDtmf(digit: string): Promise<void>;
+    /**
+     * Last mark name Twilio has confirmed playback of. Mirrors the Python
+     * ``TwilioAudioSender.last_confirmed_mark`` field — barge-in heuristics
+     * compare this against the latest sent mark to decide whether the agent's
+     * audio has actually reached the caller yet.
+     */
+    lastConfirmedMark: string;
+    /**
+     * Handle a Twilio ``mark`` event acknowledging that a previously sent
+     * audio chunk has been played out. Mirrors Python's
+     * ``twilio_handler.py``: ``audio_sender.on_mark_confirmed(mark_name)`` +
+     * ``handler.on_mark(mark_name)``.
+     */
+    /** Handle a Twilio Media Streams `mark` event acknowledging audio playback boundaries. */
+    onMark(markName: string): Promise<void>;
+    /**
+     * Await the backgrounded turn dispatch during teardown, but never block
+     * longer than ``DISPATCH_SETTLE_TIMEOUT_MS``. The earlier ``llmAbort.abort()``
+     * settles the built-in LLM/TTS paths immediately; the cap only bites a
+     * misbehaving user ``onMessage`` parked on a hung external call (JS promises
+     * can't be cancelled). No-op when nothing is in flight.
+     */
+    private settleDispatchForTeardown;
+    /**
+     * Apply per-call agent overrides returned by ``onCallStart``. snake_case
+     * keys mirror the Python payload contract (``apply_call_overrides``);
+     * ``stt_config``/``tts_config`` dicts are Python-only (TS agents carry
+     * adapter instances, not configs) and are ignored here with a warning.
+     * The deps object is per-handler, so swapping its ``agent`` is call-local.
+     */
+    private applyCallOverrides;
+    /** Handle call stop / stream end. */
+    /** Handle a carrier-emitted `stop` event signalling the call has ended. */
+    /** Append a post-decode PCM16-16k frame to the rolling 8 s window. */
+    private semanticBufferAppend;
+    /** Concatenate the rolling window for one detector prediction. */
+    private semanticWindowBytes;
+    /**
+     * Drop the rolling window — called when a turn commits so the next
+     * turn's window contains only its own audio (mirrors the reference
+     * smart-turn integrations, which score per-turn audio).
+     */
+    private resetSemanticWindow;
+    /**
+     * Score the rolling window; finalize, or hold for more silence.
+     *
+     * Fail-open AND fail-once: the first detector error falls back to the
+     * legacy immediate finalize (``vad_silence`` trigger) and disables
+     * semantic endpointing for the remainder of the call — a broken model
+     * must never stall a live phone call, and a permanently broken one
+     * (onnxruntime-node missing/incompatible, model file gone) must produce
+     * a single clear warning, not one per turn.
+     */
+    private semanticEouCheck;
+    /** Arm the hold state + the wall-clock backstop for the hard cap. */
+    private beginSemanticHold;
+    /** Drop the hold (and its backstop timer) without finalizing. Idempotent. */
+    private cancelSemanticHold;
+    /**
+     * Advance the audio clock of an active hold by one inbound frame.
+     *
+     * Finalizes (``vad_silence``) once the hard cap is reached; otherwise
+     * re-runs the detector after each additional ``SEMANTIC_POLL_MS`` of
+     * silence so a model that flips to "complete" with more trailing
+     * silence commits the turn as ``semantic_turn_detector``.
+     */
+    private pollSemanticHold;
+    /**
+     * Hard cap reached: finalize anyway so the turn can never hang. The
+     * semantic model never agreed, so the commit reason is the accumulated
+     * silence — the EOU trigger stays ``vad_silence``.
+     */
+    private resolveSemanticHoldCap;
+    /**
+     * Ask the STT provider to finalize the in-flight utterance NOW.
+     * Optional chained — Whisper-class adapters that don't support
+     * per-utterance finalisation simply skip. Extracted verbatim from the
+     * VAD ``speech_end`` branch so the default path stays byte-identical
+     * and the semantic turn-detector paths reuse it.
+     */
+    private finalizeSttForEou;
+    handleStop(): Promise<void>;
+    /** Handle WebSocket close event. */
+    /** Tear down adapter, STT/TTS, and per-call state when the carrier WebSocket closes. */
+    handleWsClose(): Promise<void>;
+    /** Close STT at most once; swallow errors. */
+    private closeSttOnce;
+    /**
+     * Encode a PCM 16kHz audio chunk for the telephony provider.
+     *
+     * Both Twilio and Telnyx negotiate PCMU (mulaw) 8 kHz on the bidirectional
+     * media stream — Twilio always, and Telnyx because ``streaming_start``
+     * (server.ts) requests ``stream_bidirectional_codec=PCMU`` at 8 kHz. So
+     * the wire format for both providers is mulaw 8 kHz; we resample 16 kHz
+     * PCM16 → 8 kHz then encode to mulaw. Mirrors the Python pipeline path
+     * (libraries/python/getpatter/handlers/telnyx_handler.py::TelnyxAudioSender).
+     *
+     * Maintains a 1-byte carry across calls so unaligned HTTP chunks from
+     * streaming TTS providers never byte-swap the PCM16 samples downstream.
+     */
+    private encodePipelineAudio;
+    /**
+     * Cached result of ``isTtsOutputFormatNativeForCarrier()`` — settled
+     * once at ``initPipeline`` time after ``setTelephonyCarrier`` has run
+     * on the TTS adapter. Stable for the call lifetime: changes to the
+     * adapter's output format mid-call would NOT flip this. ``true`` means
+     * ``encodePipelineAudio`` can take the bypass path.
+     */
+    private ttsOutputFormatNativeForCarrier;
+    /**
+     * Probe whether the TTS adapter is configured to emit bytes already in
+     * the carrier's wire codec. Currently: Twilio expects ``ulaw_8000``,
+     * Telnyx expects ``pcm_16000`` (no client transcode in either case if
+     * matched). Anything else takes the resample-and-encode path.
+     */
+    private isTtsOutputFormatNativeForCarrier;
+    /**
+     * Prepend any carry byte from the previous chunk, return the even-length
+     * portion, and stash the final odd byte (if any) for the next call.
+     */
+    private alignPcm16;
+    /**
+     * Stream a cached firstMessage buffer in pacing-friendly chunks.
+     *
+     * Splits ``prewarmBytes`` into 20 ms slices (matching Twilio's PSTN
+     * frame quantum) and
+     * forwards each through ``deps.bridge.sendAudio`` exactly like the
+     * live TTS path does — preserving Twilio mark/clear granularity. A
+     * single multi-second sendAudio call would push the whole intro into
+     * the carrier in one go and a ``sendClear`` issued mid-buffer would
+     * have nothing to clear ("agent keeps talking after barge-in" UX bug
+     * on the very first turn).
+     *
+     * Returns ``true`` when at least one chunk hit the wire — the caller
+     * uses that to decide whether to record TTS-first-byte / turn-complete
+     * metrics.
+     */
+    private streamPrewarmBytes;
+    /**
+     * Iterate ``bytes`` in 20 ms slices (Twilio PSTN frame quantum) and
+     * forward each via ``deps.bridge.sendAudio`` with mark-gated pacing
+     * (Twilio) or playout-time-based pacing (Telnyx). Caps the carrier-
+     * side buffer at ``FIRST_MESSAGE_MARK_WINDOW`` chunks so a barge-in's
+     * ``sendClear`` has ~120 ms (Twilio) or zero (Telnyx, immediately
+     * after the latest sleep) of audio to flush.
+     *
+     * Bails immediately when ``isSpeaking`` flips to false — both via the
+     * loop's pre-iter check and via ``drainPendingMarks`` (called from
+     * ``cancelSpeaking``) which unblocks any in-flight ``waitForMarkWindow``.
+     *
+     * Returns ``true`` when at least one chunk hit the wire — the caller
+     * uses that to decide whether to record TTS-first-byte / turn-complete
+     * metrics. See BUG #128 for the regression this fix targets.
+     */
+    /**
+     * Stream the configured greeting — runs as a BACKGROUND task.
+     *
+     * ``handleCallStart`` used to execute this inline; with the carrier WS
+     * events now serialized onto a per-connection FIFO, that blocked EVERY
+     * media frame for the whole greeting (VAD/barge-in structurally
+     * impossible on the first message, mark acks unread). ``handleCallStart``
+     * awaits ``beginSpeaking(true)`` BEFORE spawning this task so the
+     * self-hearing guard engages from the very first inbound frame.
+     * Mirrors the Python ``_play_first_message`` task.
+     */
+    private playFirstMessage;
+    private sendPacedFirstMessageBytes;
+    private initPipeline;
+    /** Build a HookContext for the current call state. */
+    private buildHookContext;
+    /** Synthesize a single sentence through TTS with hooks, sending audio to telephony. */
+    private synthesizeSentence;
+    /** Handle a final transcript from STT in pipeline mode. */
+    private handleTranscript;
+    private processTranscript;
+    /**
+     * Post-commit turn body (LLM dispatch → TTS → turn-complete) run as a
+     * tracked background task so the transcript drain loop is not blocked for
+     * the whole (possibly 30-90 s) agent-runtime turn. A barge-in — transcript
+     * (now reachable mid-turn) or VAD — aborts the in-flight ``llmAbort`` and
+     * flips ``isSpeaking``, which the LLM/TTS loops here observe and break on.
+     * Parity with Python ``_dispatch_turn``.
+     */
+    private dispatchTurn;
+    /**
+     * Barge-in: caller spoke over in-flight TTS. Flip ``isSpeaking`` so the
+     * sentence loop exits on its next check, clear downstream audio buffers,
+     * record the interruption, and return ``true`` so the caller skips the
+     * turn-complete record.
+     */
+    private handleBargeInAsync;
+    /**
+     * Synchronous wrapper that callers in legacy code paths can keep using.
+     * When ``bargeInStrategies`` is empty the work is fully synchronous and
+     * the result is correct. With strategies the call is dispatched as a
+     * floating promise — non-confirmed transcripts simply skip the cancel
+     * and the legacy boolean return is meaningless under that opt-in path.
+     */
+    private handleBargeIn;
+    /**
+     * Run the cancel/flush sequence for a confirmed barge-in. Shared by
+     * the legacy synchronous path and the strategy-confirmed async path.
+     */
+    private runBargeInCancel;
+    /** Mark a VAD-detected barge-in as pending (no cancel yet). */
+    private startPendingBargeIn;
+    /** Drop pending state without cancelling — used on confirm and on
+     * agent stop. Idempotent. */
+    private clearPendingBargeIn;
+    /** Retained-audio cap in bytes for the active TTS chunk format (mirrors
+     * the bytes-per-ms logic of ``trackOutboundPlayback``). */
+    private pauseRetainedCapBytes;
+    /**
+     * Whether a VAD ``speech_start`` during the agent's turn should take the
+     * pause-and-resume path instead of cancel/pending. Requires
+     * ``bargeInMode: 'pause_resume'`` AND resumable state: a dispatch in
+     * flight (the sentence/TTS loops honour the pause gate) or retained
+     * sentence audio from a just-completed turn still playing out of the
+     * carrier buffer. The firstMessage paced sender keeps today's
+     * immediate-cancel behaviour (its prewarm-bytes path has no retained
+     * sentences to resume from — known limitation).
+     */
+    private shouldPauseForBargeIn;
+    /**
+     * Resume offset at SENTENCE granularity: the first sentence (into
+     * ``turnSpokenSegments`` / ``turnSentenceAudio``) whose playback had NOT
+     * completed when the pause landed — computed from the #164
+     * playback-cursor bookkeeping (``heard = totalPushed - carrierBacklog``).
+     * Granularity choice: the partially-played sentence is replayed from its
+     * start (mark/clear bookkeeping is per-sentence and a clipped sentence
+     * restarted at its boundary sounds like a natural repair), rather than
+     * resumed mid-word at a byte offset.
+     */
+    private computePauseResumePoint;
+    /**
+     * PAUSE the agent's output on a VAD ``speech_start`` (pause_resume
+     * mode): gate further sends on ``outputPaused``, ``sendClear`` the
+     * carrier so queued audio stops quickly, and schedule the
+     * false-interruption resume timer. The LLM stream and the TTS provider
+     * stream are deliberately NOT cancelled — tokens keep buffering as
+     * sentences and synthesized audio queues in memory (both bounded) so a
+     * resume can pick up seamlessly.
+     */
+    private startPauseResume;
+    /**
+     * RESUME output after a pause that no transcript confirmed. Re-sends the
+     * cleared-but-unheard tail from the retained sentence audio (sentence
+     * granularity, no TTS re-billing), unpauses the live send path, and
+     * records the event as a FALSE interruption: the overlap closes via
+     * ``recordOverlapEnd(false)`` (the backchannel counter — the
+     * interruption count is NOT incremented) and the turn is never marked
+     * interrupted.
+     */
+    private resumeAfterFalseInterruption;
+    /** Drop all pause-and-resume state (flags + buffers) and wake any
+     * pause-decision waiter. Used by the kill path, fresh turns, and
+     * teardown. Idempotent. */
+    private discardPauseState;
+    /** Block until the in-flight pause resolves. ``true`` → resumed (keep
+     * speaking); ``false`` → killed (turn interrupted). Bounded: fails open
+     * past the confirm window plus margin (the resume timer guarantees a
+     * decision; the margin covers teardown races). Mirrors Python
+     * ``_await_pause_decision``. */
+    private awaitPauseDecision;
+    /** While paused, buffer ``sentence`` (pre-guardrail text) for the resume
+     * drain and return ``true``; return ``false`` when not paused (caller
+     * synthesizes normally). Overflow degrades to a full cancel — the
+     * bounded buffer is a memory-safety valve, not a speech queue. */
+    private bufferSentenceIfPaused;
+    /** Pop-and-return every sentence buffered during the pause. */
+    private releasePausedSentences;
+    /** Open a retention entry for a response sentence (pause_resume mode
+     * only — returns ``null`` otherwise, keeping the legacy send path
+     * byte-identical). Filler / error-fallback audio is never retained
+     * (``recordSegment=false`` callers skip this). */
+    private beginRetainedSentence;
+    /** Append ``chunk`` to the sentence's retention entry, enforcing the
+     * retained-audio cap. Returns ``true`` when retained; ``false`` on
+     * overflow (paused → the turn was just killed; speaking → retention was
+     * released and the caller falls back to direct sends). */
+    private retainPauseChunk;
+    /**
+     * Send every not-yet-sent chunk of a retention entry to the carrier
+     * (claim-then-send so concurrent drains can never double-send). Stamps
+     * the sentence's heard-prefix segment at its first sent chunk — a replay
+     * (``sent`` reset to 0) re-stamps at the new timeline position.
+     * ``force=true`` bypasses the pause gate (resume path only).
+     */
+    private drainSentenceEntry;
+    /** Whether a transcript may KILL a paused turn: it must be a committed
+     * FINAL (interims cannot confirm), not a known STT hallucination, and
+     * not a duplicate of the last committed utterance — the same filter
+     * family ``commitTranscript`` applies, evaluated without consuming its
+     * dedup state (the transcript still flows on to ``commitTranscript`` to
+     * become the user's next turn). */
+    private passesPausedKillFilters;
+    /**
+     * Dedup + throttle + hallucination filter for final STT transcripts.
+     * Mirrors ``PipelineStreamHandler._stt_loop`` on the Python side.
+     * Returns ``true`` when the transcript should be committed to a turn,
+     * ``false`` when it must be dropped. Drop reasons:
+     *   - text matches common short hallucinations ("you", "thanks", ...)
+     *   - duplicate final within 2 s of previous commit
+     *   - back-to-back finals under 500 ms (too tight to be real utterances)
+     */
+    private commitTranscript;
+    /**
+     * Whether a speculative dispatch may start right now. Built-in LLM loop
+     * only (an ``onMessage`` handler may have external side effects per
+     * invocation, so it is never run speculatively), and only while the agent
+     * is idle: not speaking (an interim during agent speech is barge-in
+     * material, not a next turn) and no turn dispatch in flight
+     * (single-in-flight contract). Parity with Python ``_can_speculate``.
+     */
+    private canSpeculate;
+    /**
+     * Read-only mirror of the ``commitTranscript`` filters: a candidate
+     * interim must pass the same hallucination / echo / duplicate checks a
+     * final would face at commit time — otherwise we would speculate on text
+     * whose final is guaranteed to be dropped. Never mutates the dedup state.
+     * Parity with Python ``_speculation_input_ok``.
+     */
+    private speculationInputOk;
+    /**
+     * Track an interim transcript and start a speculation when it qualifies:
+     * (a) it ends with sentence-final punctuation (immediate), or (b) it has
+     * been unchanged for ``preemptiveMinStableMs`` (one-shot stability timer).
+     * No-op when preemptive generation is disabled or the handler cannot
+     * speculate right now. Parity with Python ``_note_interim_transcript``.
+     */
+    private noteInterimTranscript;
+    /** Cancel the pending interim-stability timer, if any. Idempotent. */
+    private clearInterimStabilityTimer;
+    /** Drop interim-stability state — called once a final commits (the
+     * utterance is decided) and on teardown. */
+    private resetInterimTracking;
+    /**
+     * Launch a speculative dispatch for ``interimText``, replacing (and
+     * counting as a miss) any previous speculation on different text. The
+     * task's rejection handler is attached at creation (same contract as
+     * ``dispatchTask``). Parity with Python ``_start_speculation``.
+     */
+    private startSpeculation;
+    /**
+     * Discard the current speculation (if any): signal abort, await the task's
+     * unwind (bounded — JS promises are not cancellable, so a provider that
+     * ignores the signal must not block the caller), and count a miss unless
+     * this is teardown. The speculative task never touched history / carrier /
+     * per-turn metrics, so there is nothing to roll back. Idempotent. Parity
+     * with Python ``_abort_speculation``.
+     */
+    private abortSpeculation;
+    /**
+     * Self-abort from WITHIN the speculative task (LLM error, buffer overflow,
+     * afterTranscribe veto). Marks the speculation unreleasable and
+     * deregisters it so the commit path dispatches normally. Never awaits (the
+     * caller IS the task). Parity with Python ``_fail_speculation_inline``.
+     */
+    private failSpeculationInline;
+    /**
+     * Commit-time decision for the in-flight speculation. Returns ``true``
+     * when the speculation was RELEASED — the caller must NOT dispatch a
+     * normal turn (the speculative task is now the live turn, tracked via
+     * ``dispatchTask``). Returns ``false`` when there was no usable
+     * speculation (none in flight, failed, or mismatched — the mismatch is
+     * discarded here) and the normal dispatch must run.
+     *
+     * On release, the commit-point bookkeeping the normal path performs in
+     * ``processTranscript`` happens HERE — the ``onTranscript`` callback, the
+     * conversation-history user push (final transcript text), and the
+     * turn-committed metric anchors (so TTFT/latency reflect user-perceived
+     * timing from the REAL final-transcript commit) — exactly once per turn.
+     * Parity with Python ``_try_release_speculation``.
+     */
+    private tryReleaseSpeculation;
+    /** Playout duration (ms) of the audio a speculation has buffered so far.
+     * Same bytes-per-ms model as ``trackOutboundPlayback``. */
+    private specBufferMs;
+    /** Push one (already hook-processed) audio chunk of a RELEASED speculation
+     * to the carrier — the same per-chunk bookkeeping ``synthesizeSentence``
+     * performs on the live path. */
+    private specSendChunk;
+    /**
+     * Idempotent release flush: take the floor (``beginSpeaking``), stamp the
+     * post-commit LLM markers, and stream every buffered sentence to the
+     * carrier in order. After this the speculative task continues as a plain
+     * live turn. No-op until the speculation is released. Parity with Python
+     * ``_spec_ensure_flushed``.
+     */
+    private specEnsureFlushed;
+    /**
+     * Synthesize one sentence of an UNRELEASED speculation, holding the audio
+     * in ``spec.buffered``. Transitions to live sending mid-sentence the
+     * moment the release lands. Returns ``false`` when the speculation must
+     * stop (aborted, overflow, or barge-in after a mid-sentence release).
+     * Parity with Python ``_spec_synthesize_buffered``.
+     */
+    private specSynthesizeBuffered;
+    /**
+     * Guardrails + tier-2 hook + synthesis for one speculative sentence —
+     * buffered pre-release, live post-release (same transforms either way).
+     * Returns ``false`` when the turn must stop. Parity with Python
+     * ``_spec_speak_sentence``.
+     */
+    private specSpeakSentence;
+    /**
+     * Turn-complete bookkeeping for a RELEASED speculation — mirrors the tail
+     * of ``runPipelineLlm`` + ``dispatchTurn`` (metrics turn record,
+     * interrupted heard-prefix marker, assistant history entry). Runs exactly
+     * once, after all audio was sent/cancelled. Parity with Python
+     * ``_finish_released_speculation``.
+     */
+    private finishReleasedSpeculation;
+    /**
+     * Body of one speculative turn: LLM stream → sentence chunking → buffered
+     * TTS, then commit-or-discard.
+     *
+     * Until release this task is side-effect free outside ``spec`` itself —
+     * no conversation-history writes, no carrier audio, no per-turn metrics
+     * (LLM token usage/cost IS recorded by ``LLMLoop``: the tokens were
+     * genuinely consumed either way). After release it behaves exactly like a
+     * live ``dispatchTurn`` body. Parity with Python
+     * ``_run_speculative_dispatch``.
+     */
+    private runSpeculativeDispatch;
+    /**
+     * Schedule the opt-in long-turn filler and return its async ``clear()``.
+     *
+     * When ``agent.longTurnMessage`` is unset / empty the returned clear is a
+     * no-op (byte-identical to today's behaviour). Otherwise a one-shot timer
+     * fires after ``agent.longTurnMessageAfterS`` seconds and, IFF no audio has
+     * reached the carrier this turn (``!ttsFirstByteSent.value``) AND we still own
+     * the floor (``this.isSpeaking``), synthesizes the filler ONCE via the same
+     * per-sentence TTS primitive every sentence uses.
+     *
+     * The returned ``clear()`` is **async**: it stops the timer AND, if the filler
+     * already started synthesizing (its ``setTimeout`` callback runs in a separate
+     * macro-task, so it can fire just before the first real sentence), AWAITS the
+     * in-flight synthesis so the filler audio can never interleave with the real
+     * sentence that follows. Idempotent; self-synthesis failure degrades to
+     * silence (never crashes the turn). The caller must clear on first real audio,
+     * on the error branch, and in the finally.
+     */
+    private scheduleLongTurnFiller;
+    /**
+     * Streaming built-in LLM path with sentence chunking and per-sentence
+     * guardrails/TTS. Returns the concatenated (plain) response text plus whether
+     * the turn was cut short by a barge-in — the caller applies the interrupted
+     * marker to history only, keeping metrics on the plain text.
+     */
+    private runPipelineLlm;
+    /**
+     * Non-streaming path (onMessage function / webhook): apply output guardrails,
+     * push to history, sentence-chunk the text, synthesize. Returns ``true`` if
+     * TTS was interrupted mid-flight so the caller can skip turn-complete.
+     */
+    private runRegularLlm;
+    /** Handle streaming WebSocket remote response with TTS. */
+    private handleWebSocketResponse;
+    private initRealtimeAdapter;
+    private handleAdapterEvent;
+    /** Event-type → handler dispatch table for the Realtime adapter. */
+    private readonly adapterEventHandlers;
+    private userSpeechStartMs;
+    private agentTurnStartMs;
+    private emitUserSpeechStarted;
+    private emitUserSpeechEnded;
+    private emitUserSpeechEos;
+    private emitAgentSpeechStarted;
+    private emitAgentSpeechEnded;
+    /** Fire the per-turn LLM TTFT marker. Idempotent in the dispatcher
+     * — guarded by `firstTokenForTurn` on the SpeechEvents instance. */
+    private emitLlmFirstToken;
+    /** Fire the per-turn first-TTS-audio marker. Idempotent in the
+     * dispatcher — guarded by `firstAudioForTurn`. The provider tag falls
+     * back to the engine name for Realtime / ConvAI (no separate TTS). */
+    private emitAudioOut;
+    private onAdapterAudio;
+    private onAdapterSpeechStopped;
+    private onAdapterTranscriptInput;
+    /**
+     * Push an assistant turn into history, fire `onTranscript`, and emit
+     * turn-complete metrics. Shared between the immediate path (no user
+     * transcript pending) and the buffered path (flushed after user
+     * transcript arrives or fallback timer fires).
+     */
+    private flushAssistantTurn;
+    /**
+     * Push an assistant turn into history and fire `onTranscript` so host
+     * applications observe pipeline-mode replies the same way they observe
+     * realtime-mode replies. Mirrors `_emit_assistant_transcript` in the
+     * Python SDK and parallels `flushAssistantTurn` (realtime path).
+     * Caller is responsible for filtering empty strings.
+     */
+    private emitAssistantTranscript;
+    /**
+     * Surface a tool invocation from pipeline mode into the transcript
+     * timeline. Emits TWO events: one for the call (`name(argsJson)`) and
+     * one for the result (`name(...) → result`, truncated to 200 chars).
+     * Mirrors realtime mode's two `emitToolEvent` calls in
+     * `handleFunctionCall`. Wired as the `LLMLoop` `onToolCall` observer.
+     */
+    private recordToolCall;
+    private onAdapterTranscriptOutput;
+    private onAdapterResponseDone;
+    private onAdapterSpeechInterrupt;
+    /**
+     * Handle a Realtime ``error`` event (issue #154, fix 4).
+     *
+     * Both Realtime providers dispatch ``('error', …)`` for server-side errors,
+     * non-normal socket closes, and socket errors, but the stream handler
+     * previously had no entry for it in the dispatch table so these were
+     * silently swallowed. We surface them at WARN level with ONLY the error
+     * envelope fields (``type`` / ``code`` / ``message``) — never any audio or
+     * transcript body, to avoid logging PII. The call is NOT terminated: the
+     * provider decides whether to recover, and many of these (e.g. a transient
+     * ``input_audio_buffer_commit_empty``) are non-fatal. Parity with the
+     * Python ``elif ev_type == 'error'`` branches.
+     */
+    private onAdapterError;
+    /**
+     * Emit a tool-invocation event into the transcript timeline. Pushes a
+     * `role=tool` entry into `history` (so it appears in the dashboard
+     * transcript next to user/assistant turns) AND fires `onTranscript` so
+     * the host application can log / persist / render it. `result` is
+     * truncated for log readability — the full payload is in history.
+     */
+    private emitToolEvent;
+    /**
+     * Execute an ElevenLabs ``client_tool_call`` and ALWAYS answer it — a
+     * missing client_tool_result stalls the ElevenLabs agent until its own
+     * tool timeout. transfer_call/end_call declared as ElevenLabs client
+     * tools route to the carrier helpers. Mirrors Python
+     * ``_handle_convai_client_tool``.
+     */
+    private handleConvAIClientTool;
+    private handleFunctionCall;
+    /**
+     * The effective per-call tool list for the CURRENT agent: target tools plus
+     * the built-in consult tool when configured (deduped by name). Used after a
+     * handoff to rebuild `resolvedTools`.
+     */
+    private effectiveToolsForCurrentAgent;
+    /**
+     * Dispatch the built-in `handoff_to` tool on the Realtime path.
+     *
+     * Swaps the live session to the target agent's configuration via a
+     * mid-session `session.update` (new `instructions` + `tools`), updates
+     * `currentAgent` / `resolvedTools` so subsequent tool dispatch resolves
+     * against the target's tool list, and records a system-style history entry
+     * so transcripts show the handoff. ALWAYS sends a function result — an
+     * unknown name / malformed args produce an error envelope, never silence
+     * (a missing function result would wedge the model).
+     *
+     * Voice is intentionally NOT swapped: OpenAI Realtime rejects a voice
+     * change once the session has produced audio, so the session keeps the
+     * voice established at call start (documented limitation; an info log is
+     * emitted when the target requested a different voice). Parity with the
+     * Python `_handle_handoff_function_call`.
+     */
+    private handleHandoffFunctionCall;
+    /**
+     * Swap the live pipeline call to the named handoff target agent.
+     *
+     * Updates `currentAgent` (the shared `AgentOptions` is never mutated),
+     * swaps the LLM loop's system prompt + tool list so the NEXT turn runs as
+     * the target agent, and appends a system-style history entry recording the
+     * handoff. ALWAYS returns a tool-result string — an unknown name produces
+     * an error envelope, never silence.
+     *
+     * Live audio infrastructure (STT/TTS/VAD instances — and therefore the
+     * speaking voice) established at call start is intentionally retained:
+     * swapping a connected TTS provider mid-call is not supported in v1.
+     * Parity with the Python `_perform_handoff`.
+     */
+    private performHandoff;
+    /**
+     * Build the full pipeline tool list for the CURRENT agent: user tools +
+     * built-in `transfer_call` / `end_call` + the `handoff_to` tool when
+     * handoff targets are configured. Re-invoked after a handoff so the LLM
+     * loop advertises the target agent's tools (including its onward handoff
+     * map). Parity with the Python `_build_combined_pipeline_tools`.
+     */
+    private buildPipelineLlmTools;
+    private fireCallEnd;
+}
+
 /** Resolved configuration consumed by `EmbeddedServer` (carrier credentials, webhook URL, etc.). */
 interface LocalConfig {
     twilioSid?: string;
@@ -2370,10 +3974,11 @@ declare class OpenAILLMProvider implements LLMProvider {
 /** Pipeline-mode LLM driver: runs the chat loop, dispatches tool calls, and emits text deltas. */
 declare class LLMLoop {
     private readonly provider;
-    private readonly systemPrompt;
-    private readonly tools;
-    private readonly openaiTools;
-    private readonly toolMap;
+    private systemPrompt;
+    private disablePhonePreamble;
+    private tools;
+    private openaiTools;
+    private toolMap;
     private toolExecutor;
     private eventBus?;
     private readonly _providerName;
@@ -2382,6 +3987,28 @@ declare class LLMLoop {
     private _loggedUsageFallback;
     private onToolCall?;
     constructor(apiKey: string, model: string, systemPrompt: string, tools?: ToolDefinition[] | null, llmProvider?: LLMProvider, disablePhonePreamble?: boolean);
+    /**
+     * Prepend {@link DEFAULT_PHONE_PREAMBLE} unless disabled — byte-identical
+     * to the historical inline constructor logic.
+     */
+    private static applyPhonePreamble;
+    /** (Re)build `openaiTools` and `toolMap` from a tool list. */
+    private rebuildToolState;
+    /**
+     * Swap the system prompt and/or tool list mid-call (multi-agent handoff).
+     *
+     * Takes effect on the NEXT turn — `run` builds its messages array (with
+     * the system prompt at index 0) per turn, and reads `openaiTools` per
+     * provider iteration, so a swap that lands while a turn is in flight
+     * finishes the current turn under the old prompt and runs every subsequent
+     * turn as the new agent. Omitted fields keep the corresponding current
+     * value. Mirrors Python `LLMLoop.update_agent`.
+     */
+    updateAgent(update: {
+        systemPrompt?: string;
+        tools?: ToolDefinition[];
+        disablePhonePreamble?: boolean;
+    }): void;
     /**
      * Swap in a custom tool executor (e.g. different retry policy, metrics
      * wrapping, tenant-aware fan-out). The default is ``DefaultToolExecutor``.
@@ -2786,6 +4413,42 @@ interface OpenAICompatibleConsult {
      */
     readonly sessionHeader?: string;
 }
+/**
+ * Options for a call transfer initiated via the built-in `transfer_call`
+ * tool or `TelephonyBridge.transferCall`.
+ *
+ * Mirrors Python's `mode` / `summary` keywords on the per-carrier transfer
+ * functions.
+ */
+interface TransferCallOptions {
+    /**
+     * `'cold'` (default) redirects the caller immediately — byte-identical to
+     * the historical blind transfer. `'warm'` puts the caller on hold music,
+     * dials the target with an announced {@link summary}, then bridges the two
+     * together (Twilio only for now; other carriers return an error envelope).
+     */
+    readonly mode?: 'cold' | 'warm';
+    /**
+     * Warm mode only — one or two sentences announced to the human agent
+     * before the caller is bridged (who is calling and what they need).
+     */
+    readonly summary?: string;
+}
+/**
+ * Result of a transfer attempt. Cold transfers may resolve `void` (legacy
+ * contract); warm transfers resolve a result envelope —
+ * `{ status: 'transferring', mode: 'warm', ... }` on success or
+ * `{ error: ... }` when warm transfer is unsupported on the carrier or the
+ * carrier REST sequence failed (the call keeps running in that case).
+ */
+interface TransferCallResult {
+    readonly status?: string;
+    readonly mode?: 'cold' | 'warm';
+    readonly to?: string;
+    /** Per-call conference name (Twilio warm transfers). */
+    readonly conference?: string;
+    readonly error?: string;
+}
 /** Constructor options for `new Patter({...})` in local-server mode. */
 interface LocalOptions {
     /**
@@ -2945,6 +4608,29 @@ interface VADProvider {
      */
     reset?(): Promise<void> | void;
 }
+/**
+ * Semantic end-of-utterance (turn) detector.
+ *
+ * Predicts whether the caller has FINISHED their turn — as opposed to a
+ * VAD, which only reports whether they are currently producing sound.
+ * Implementations include `SmartTurnDetector` (pipecat-ai smart-turn v3,
+ * ONNX). Used via `Agent.turnDetector`; integrated in the pipeline stream
+ * handler on the VAD `speech_end` edge to defer the STT finalize until the
+ * model agrees the turn is complete (bounded by `Agent.maxSemanticHoldMs`).
+ * Mirror of the Python `TurnDetectorProvider` ABC.
+ */
+interface TurnDetectorProvider {
+    /** End-of-turn probability at/above which the turn is complete. */
+    readonly threshold: number;
+    /**
+     * Return the end-of-turn probability in `[0, 1]` for the window.
+     * `pcm16Window` is mono int16 little-endian PCM at 16 kHz covering the
+     * most recent seconds of caller audio (the handler keeps a rolling
+     * ~8 s buffer).
+     */
+    predict(pcm16Window: Buffer): Promise<number>;
+    close(): Promise<void>;
+}
 /** Pre-STT audio filter — noise cancellation, gain, EQ. */
 interface AudioFilter {
     process(pcmChunk: Buffer, sampleRate: number): Promise<Buffer>;
@@ -3078,6 +4764,18 @@ interface AgentOptions {
      * disables it. See {@link ConsultConfig}.
      */
     readonly consult?: ConsultConfig;
+    /**
+     * Multi-agent handoff targets: ``{ name: agentOptions }``. When set, Patter
+     * auto-injects a built-in ``handoff_to(name, reason?)`` tool (Realtime +
+     * Pipeline modes); calling it swaps the CURRENT call to the target agent's
+     * configuration mid-call — system prompt, tools, variables, guardrails,
+     * and onward ``handoffs`` are taken from the target. Audio infrastructure
+     * established at call start (STT/TTS/engine connection — and therefore
+     * voice on engines that cannot switch voice mid-session) is retained.
+     * Chained handoffs follow the TARGET's own ``handoffs`` map. ``undefined``
+     * (default) disables the tool. Mirrors Python ``Agent.handoffs``.
+     */
+    readonly handoffs?: Readonly<Record<string, AgentOptions>>;
     /**
      * When ``true``, ship ``systemPrompt`` to the LLM verbatim. Default
      * (``false``) prepends a phone-friendly preamble that instructs the
@@ -3132,6 +4830,26 @@ interface AgentOptions {
     readonly textTransforms?: ReadonlyArray<(text: string) => string>;
     /** Optional server-side VAD (e.g., Silero). Pipeline mode only. */
     readonly vad?: VADProvider;
+    /**
+     * Opt-in semantic end-of-utterance model (e.g. `SmartTurnDetector.load()`
+     * — pipecat-ai smart-turn v3, ONNX). Pipeline mode only. When set, a VAD
+     * `speech_end` no longer finalizes the STT utterance immediately: the
+     * detector scores the last ~8 s of caller audio and the turn is committed
+     * only once the end-of-turn probability reaches `turnDetector.threshold`
+     * (the EOU trigger is then stamped `semantic_turn_detector`). While the
+     * model says "incomplete" the handler re-polls on subsequent silence,
+     * bounded by `maxSemanticHoldMs`. Undefined (default) keeps today's pure
+     * VAD-silence endpointing byte-identical.
+     */
+    readonly turnDetector?: TurnDetectorProvider;
+    /**
+     * Hard cap (ms) on how long the semantic turn detector may hold a turn
+     * open past the VAD `speech_end` before the SDK finalizes anyway (with
+     * the `vad_silence` trigger), so a turn can never hang on a model that
+     * keeps predicting "incomplete". Only consulted when `turnDetector` is
+     * set. Default 1200 ms.
+     */
+    readonly maxSemanticHoldMs?: number;
     /** Optional pre-STT audio filter (noise cancellation). Pipeline mode only. */
     readonly audioFilter?: AudioFilter;
     /** Optional background audio mixer (hold music, thinking cues). Pipeline mode only. */
@@ -3163,10 +4881,32 @@ interface AgentOptions {
     /**
      * Maximum time (ms) to wait for at least one strategy to confirm a
      * pending barge-in before discarding the pending state and resuming
-     * TTS. Only consulted when ``bargeInStrategies`` is non-empty.
+     * TTS. Consulted when ``bargeInStrategies`` is non-empty AND as the
+     * false-interruption window for ``bargeInMode: 'pause_resume'``.
      * Default: 1500.
      */
     readonly bargeInConfirmMs?: number;
+    /**
+     * How a VAD ``speech_start`` during the agent's turn is handled
+     * (pipeline mode):
+     *
+     * - ``'cancel'`` (default): today's behaviour — the in-flight turn is
+     *   cancelled immediately (or marked pending when
+     *   ``bargeInStrategies`` are configured).
+     * - ``'pause_resume'`` (false-interruption handling):
+     *   output is PAUSED immediately — the carrier buffer is cleared and
+     *   no further TTS audio is sent — while the LLM stream and the TTS
+     *   provider stream stay alive (tokens buffer as sentences,
+     *   synthesized audio queues in memory, both bounded). If a committed
+     *   final transcript confirms the interruption within
+     *   ``bargeInConfirmMs`` the turn is cancelled exactly as in
+     *   ``'cancel'`` mode; if the window expires with no transcript (a
+     *   cough, line noise) the agent RESUMES from the first sentence the
+     *   caller had not fully heard, re-sending retained audio without
+     *   re-billing TTS, and the event is recorded as a false interruption
+     *   (a backchannel — not an interruption — in metrics).
+     */
+    readonly bargeInMode?: 'cancel' | 'pause_resume';
     /**
      * When ``true`` (default), ``Patter.call`` warms up the STT, TTS, and
      * LLM provider connections in parallel with the carrier-side
@@ -3209,6 +4949,31 @@ interface AgentOptions {
      * currency, balanced delimiter, ellipsis).
      */
     readonly aggressiveFirstFlush?: boolean;
+    /**
+     * PREEMPTIVE GENERATION (pipeline mode, built-in LLM loop only; opt-in).
+     * When ``true`` the SDK starts the LLM — and sentence-chunked TTS
+     * synthesis — EARLY on a confident INTERIM transcript (one that ends with
+     * sentence-final punctuation, or that has been unchanged for
+     * ``preemptiveMinStableMs``), holding all synthesized audio in memory.
+     * When the FINAL transcript commits: if it matches the speculated interim
+     * (normalized — case/punctuation/whitespace-insensitive) the buffered
+     * audio is RELEASED to the carrier immediately (the LLM+TTS latency was
+     * paid during the user's own end-of-utterance silence); if it differs,
+     * the speculation is discarded silently and the turn dispatches normally
+     * on the final. History and metrics record exactly one turn either way.
+     * The standard voice-AI "preemptive generation" pattern. Default:
+     * ``false`` — every turn waits for the final transcript, as today.
+     * Mirrors Python ``preemptive_generation``.
+     */
+    readonly preemptiveGeneration?: boolean;
+    /**
+     * Interim-stability window (ms) for preemptive generation: an interim
+     * transcript that does NOT end with sentence-final punctuation qualifies
+     * for speculation only once it has remained unchanged for this long.
+     * Only consulted when ``preemptiveGeneration`` is true. Default: 300.
+     * Mirrors Python ``preemptive_min_stable_ms``.
+     */
+    readonly preemptiveMinStableMs?: number;
     /**
      * Input noise reduction for speakerphone / conference audio (OpenAI
      * Realtime mode only). `undefined` (default) omits the field entirely
@@ -3284,7 +5049,13 @@ interface ServeOptions {
     readonly port?: number;
     /** When true, start a cloudflared tunnel automatically (requires `cloudflared` npm package). */
     readonly tunnel?: boolean;
-    readonly onCallStart?: (data: Record<string, unknown>) => Promise<void>;
+    /**
+     * Called when a call's media stream starts. Returning an object applies
+     * PER-CALL AGENT OVERRIDES (snake_case keys: system_prompt, voice, model,
+     * language, first_message, provider, tools, variables) — parity with the
+     * Python SDK. Return nothing to just observe.
+     */
+    readonly onCallStart?: (data: Record<string, unknown>) => Promise<void | Record<string, unknown> | undefined> | void | Record<string, unknown>;
     readonly onCallEnd?: (data: Record<string, unknown>) => Promise<void>;
     readonly onTranscript?: (data: Record<string, unknown>) => Promise<void>;
     /** Pipeline mode only — called with the user's transcript; return value is spoken.
@@ -3294,6 +5065,19 @@ interface ServeOptions {
     readonly onMetrics?: (data: Record<string, unknown>) => Promise<void>;
     /** When true, record calls via the Twilio Recordings API. */
     readonly recording?: boolean;
+    /**
+     * Carrier-neutral local call recording. When `true`, the SDK records each
+     * call at the transport as an interleaved stereo WAV — left channel =
+     * caller, right channel = agent — at 16 kHz PCM16, written incrementally
+     * to `<call_log_dir>/recording.wav` when call logging (`persist` /
+     * `PATTER_LOG_DIR`) is enabled, else to `./recordings/<call_id>.wav`.
+     * Pass a directory string to choose where the WAVs go. Works on every
+     * carrier (Twilio, Telnyx, Plivo) and every engine mode; independent of
+     * the carrier-side `recording` flag (both can be on). The final path is
+     * surfaced as `recording_path` in the `onCallEnd` payload and in the
+     * call-log metadata. Default `false`.
+     */
+    readonly localRecording?: boolean | string;
     /** If set, spoken as a voicemail message when AMD detects a machine. */
     readonly voicemailMessage?: string;
     /** Custom pricing overrides for cost calculation. */
@@ -3373,6 +5157,13 @@ interface MachineDetectionResult {
 interface LocalCallOptions {
     readonly to: string;
     readonly agent: AgentOptions;
+    /**
+     * Per-call greeting override — what the AI says when the callee answers.
+     * Overrides ``agent.firstMessage`` for this call only (prewarm synthesis
+     * and the stream handler both read the overridden value). Parity with
+     * Python ``call(first_message=...)``.
+     */
+    readonly firstMessage?: string;
     /**
      * Enable answering-machine detection. **Defaults to ``true``** — the SDK
      * asks Twilio (``MachineDetection=DetectMessageEnd`` + Async AMD) or
@@ -3465,15 +5256,6 @@ interface CallResult {
     readonly metrics: CallMetrics | null;
 }
 
-/**
- * Shared STT / TTS adapter dispatch.
- *
- * In v0.5.0+ callers always pass pre-instantiated adapters (``agent.stt`` /
- * ``agent.tts`` are ``STTAdapter`` / ``TTSAdapter`` instances), so these
- * helpers are thin pass-throughs that return the instance or null. Kept as
- * functions so the Twilio/Telnyx bridges have a single dispatch point.
- */
-
 /** Per-word timings / metadata (Deepgram-shaped). Optional on every adapter. */
 interface STTWord {
     readonly word?: string;
@@ -3618,7 +5400,7 @@ interface ElevenLabsTTSOptions$1 {
  *   ElevenLabs to produce μ-law directly skips that step (saves
  *   ~30–80 ms first-byte plus per-frame CPU and avoids any resampling
  *   aliasing).
- * - {@link ElevenLabsTTS.forTelnyx} emits `pcm_16000`. Telnyx negotiates
+ * - {@link ElevenLabsTTS.forTelnyx} emits `ulaw_8000`. The SDK pins Telnyx to PCMU;
  *   L16/16000 on its bidirectional media WebSocket, so 16 kHz PCM is
  *   already the format used end-to-end and no transcoding happens.
  *   ElevenLabs *also* supports `ulaw_8000` if your Telnyx profile is
@@ -3676,13 +5458,9 @@ declare class ElevenLabsTTS {
     /**
      * Construct an instance pre-configured for Telnyx bidirectional media.
      *
-     * Telnyx's default media-streaming codec is L16 PCM @ 16 kHz, which
-     * matches our default Telnyx handler. We pick `pcm_16000` so the audio
-     * flows end-to-end with zero resampling or transcoding.
-     *
-     * Trade-off: if your Telnyx profile is pinned to PCMU/8000 (μ-law),
-     * construct `ElevenLabsTTS` directly with `outputFormat: 'ulaw_8000'`
-     * — Telnyx supports that natively too.
+     * The SDK's ``streaming_start`` pins the Telnyx wire to PCMU/μ-law @
+     * 8 kHz (stream_bidirectional_codec=PCMU), so μ-law output flows
+     * end-to-end with zero resampling or transcoding.
      */
     static forTelnyx(apiKey: string, options?: Omit<ElevenLabsTTSOptions$1, 'outputFormat'>): ElevenLabsTTS;
     /**
@@ -3841,7 +5619,7 @@ declare class ElevenLabsWebSocketTTS implements TTSAdapter {
     cancelActiveStream(): void;
     /** Pre-configured for Twilio Media Streams (`ulaw_8000`). */
     static forTwilio(opts: Omit<ElevenLabsWebSocketTTSOptions, 'outputFormat'>): ElevenLabsWebSocketTTS;
-    /** Pre-configured for Telnyx (`pcm_16000`). */
+    /** Pre-configured for Telnyx (μ-law 8 kHz wire). */
     static forTelnyx(opts: Omit<ElevenLabsWebSocketTTSOptions, 'outputFormat'>): ElevenLabsWebSocketTTS;
     private buildUrl;
     /**
@@ -4148,6 +5926,14 @@ declare class Patter {
      * carrier ``start`` event instead of opening fresh ones — saving
      * ~150-900 ms of cold-start handshake on the first turn.
      */
+    /**
+     * Re-key prewarm caches from a dial-time id to the live carrier id.
+     * Plivo issues ``request_uuid`` at dial time but the media stream and
+     * webhooks carry ``CallUUID`` — without re-keying, prewarmed first-message
+     * audio and parked provider sockets never matched and always TTL-evicted
+     * as "wasted". Mirrors Python ``_alias_prewarm``.
+     */
+    aliasPrewarm: (oldId: string, newId: string) => void;
     popPrewarmedConnections: (callId: string) => ParkedProviderConnections | undefined;
     /**
      * Close any parked provider WebSockets for ``callId``. Wired into
@@ -5126,7 +6912,7 @@ declare class TestSession {
         agent: AgentOptions;
         openaiKey?: string;
         onMessage?: PipelineMessageHandler;
-        onCallStart?: (data: Record<string, unknown>) => Promise<void>;
+        onCallStart?: (data: Record<string, unknown>) => Promise<void | Record<string, unknown> | undefined> | void | Record<string, unknown>;
         onCallEnd?: (data: Record<string, unknown>) => Promise<void>;
     }): Promise<void>;
 }
@@ -5151,7 +6937,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>;
+type GeminiLiveEventHandler = (type: 'audio' | 'transcript_input' | 'transcript_output' | 'function_call' | 'speech_started' | 'response_done' | 'error', data: unknown) => void | Promise<void>;
 interface GeminiLiveOptions {
     model?: string;
     voice?: string;
@@ -5244,6 +7030,10 @@ declare class UltravoxRealtimeAdapter {
     private readonly sampleRate;
     private readonly firstMessage;
     private ws;
+    /** Last Ultravox state string (turn-end transition detection). */
+    private lastUltravoxState;
+    /** Whether the current agent turn streamed delta frames (dedupe finals). */
+    private agentStreamedDeltas;
     private handlers;
     /** Exposed for diagnostics — true while the underlying socket is open. */
     running: boolean;
@@ -5361,6 +7151,7 @@ declare class SonioxSTT {
     private ws;
     private readonly callbacks;
     private final;
+    private lastInterimText;
     private keepaliveTimer;
     private readonly apiKey;
     private readonly model;
@@ -5373,17 +7164,31 @@ declare class SonioxSTT {
     private readonly maxEndpointDelayMs;
     private readonly clientReferenceId?;
     private readonly baseUrl;
+    /** Construction args replayed by clone(). */
+    private readonly patterCtorArgs;
     constructor(apiKey: string, options?: SonioxSTTOptions$1);
     /** 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. */
+    /**
+     * Fresh adapter built with this instance's construction arguments —
+     * called per call by the stream handler so concurrent calls never share
+     * connection state (sockets/queues; cross-call transcript bleed).
+     */
+    clone(): this;
     connect(): Promise<void>;
     private clearKeepalive;
     private handleMessage;
     private emit;
     /** Send a binary PCM16-LE audio chunk to Soniox for transcription. */
     sendAudio(audio: Buffer): void;
+    /**
+     * Ask Soniox to finalize buffered audio immediately. The pipeline's VAD
+     * ``speech_end`` fast-path duck-types ``stt.finalize`` — without this
+     * every Soniox turn waited out the full endpointing delay. Mirrors Python.
+     */
+    finalize(): void;
     /** Register a transcript listener. */
     onTranscript(callback: TranscriptCallback$6): void;
     /** Unregister a previously registered transcript listener. */
@@ -5495,6 +7300,8 @@ declare class AssemblyAISTT {
     sessionId: string | null;
     /** Unix timestamp when the AssemblyAI session expires. */
     expiresAt: number | null;
+    /** Construction args replayed by clone(). */
+    private readonly patterCtorArgs;
     constructor(apiKey: string, options?: AssemblyAISTTOptions$1);
     /** Factory for Twilio calls — mulaw 8 kHz. */
     static forTwilio(apiKey: string, model?: AssemblyAIModel): AssemblyAISTT;
@@ -5517,6 +7324,12 @@ declare class AssemblyAISTT {
      */
     warmup(): Promise<void>;
     /** Open the streaming WebSocket and arm message handlers. */
+    /**
+     * Fresh adapter built with this instance's construction arguments —
+     * called per call by the stream handler so concurrent calls never share
+     * connection state (sockets/queues; cross-call transcript bleed).
+     */
+    clone(): this;
     connect(): Promise<void>;
     private awaitOpen;
     private attachHandlers;
@@ -5613,6 +7426,8 @@ declare class CartesiaSTT {
      * `null` until the first transcript event arrives (matches Python's `None`).
      */
     requestId: string | null;
+    /** Construction args replayed by clone(). */
+    private readonly patterCtorArgs;
     constructor(apiKey: string, options?: CartesiaSTTOptions$1);
     /**
      * Open a fresh WebSocket without arming any message / keepalive handlers
@@ -5641,6 +7456,12 @@ declare class CartesiaSTT {
      */
     warmup(): Promise<void>;
     /** Open the streaming WebSocket and arm message + keepalive handlers. */
+    /**
+     * Fresh adapter built with this instance's construction arguments —
+     * called per call by the stream handler so concurrent calls never share
+     * connection state (sockets/queues; cross-call transcript bleed).
+     */
+    clone(): this;
     connect(): Promise<void>;
     /**
      * Adopt a pre-opened, already-OPEN WebSocket produced by the prewarm
@@ -5869,6 +7690,8 @@ declare class DeepgramSTT {
      * ``(apiKey, language?, model?, encoding?, sampleRate?)`` for backward
      * compatibility with code that predated BUG #13.
      */
+    /** Construction args replayed by clone(). */
+    private readonly patterCtorArgs;
     constructor(apiKey: string, language?: string, model?: string, encoding?: string, sampleRate?: number, options?: DeepgramSTTOptions$1);
     constructor(apiKey: string, options: DeepgramSTTOptions$1 & {
         language?: string;
@@ -5893,6 +7716,12 @@ declare class DeepgramSTT {
      */
     warmup(): Promise<void>;
     /** Open the streaming WebSocket and arm message + keepalive handlers. */
+    /**
+     * Fresh adapter built with this instance's construction arguments —
+     * called per call by the stream handler so concurrent calls never share
+     * connection state (sockets/queues; cross-call transcript bleed).
+     */
+    clone(): this;
     connect(): Promise<void>;
     private openSocket;
     private clearKeepalive;
@@ -5946,13 +7775,11 @@ declare class DeepgramSTT {
  * 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.forTwilio} requests `sampleRate=16000` — the rate
+ *   the pipeline's carrier-side encoder expects. The previous 8 kHz
+ *   shortcut had no consuming hook: the audio sender unconditionally runs
+ *   its fixed 16 kHz → 8 kHz decimator, so 8 kHz input was decimated
+ *   AGAIN and played back at ~2x speed (chipmunk audio).
  * - {@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
@@ -6188,10 +8015,18 @@ declare class WhisperSTT {
      * ``(apiKey, model, language, bufferSize, responseFormat)`` — callers using
      * the old order will need to swap ``language`` and ``model``.
      */
+    /** Construction args replayed by clone(). */
+    private readonly patterCtorArgs;
     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. */
+    /**
+     * Fresh adapter built with this instance's construction arguments —
+     * called per call by the stream handler so concurrent calls never share
+     * connection state (sockets/queues; cross-call transcript bleed).
+     */
+    clone(): this;
     connect(): Promise<void>;
     /** Buffer a PCM16 chunk; flushes to Whisper once `bufferSize` bytes are reached. */
     sendAudio(audio: Buffer): void;
@@ -6277,7 +8112,7 @@ interface OpenAITranscribeSTTOptions {
     model?: string;
     language?: string;
     bufferSize?: number;
-    /** ``"verbose_json"`` exposes segment-level confidence / timestamps. */
+    /** ``"json"`` only — the gpt-4o transcribe models reject ``"verbose_json"`` (whisper-1/WhisperSTT supports it). */
     responseFormat?: WhisperResponseFormat;
 }
 /**
@@ -6537,10 +8372,18 @@ declare class SpeechmaticsSTT {
     private readonly operatingPoint;
     private readonly domain;
     private readonly outputLocale;
+    /** Construction args replayed by clone(). */
+    private readonly patterCtorArgs;
     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. */
+    /**
+     * Fresh adapter built with this instance's construction arguments —
+     * called per call by the stream handler so concurrent calls never share
+     * connection state (sockets/queues; cross-call transcript bleed).
+     */
+    clone(): this;
     connect(): Promise<void>;
     /** Send a binary PCM16-LE audio chunk to Speechmatics for transcription. */
     sendAudio(audio: Buffer): void;
@@ -6811,15 +8654,15 @@ type CartesiaCarrierOptions = Omit<CartesiaTTSOptions, "sampleRate">;
  * const tts = new cartesia.TTS({ apiKey: "..." });
  * ```
  *
- * **Telephony optimization** — use {@link TTS.forTwilio} (PCM @ 8 kHz,
- * skipping the SDK-side 16 kHz → 8 kHz resample before μ-law transcoding)
+ * **Telephony** — use {@link TTS.forTwilio} (PCM @ 16 kHz; the pipeline's
+ * carrier-side encoder performs the 16 kHz → 8 kHz + μ-law step itself)
  * or {@link TTS.forTelnyx} (PCM @ 16 kHz, native Telnyx default) on
  * phone calls.
  */
 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). */
+    /** Pipeline TTS pre-configured for Twilio Media Streams (PCM @ 16 kHz — the pipeline decimates to the 8 kHz wire itself; 8 kHz here was decimated AGAIN → chipmunk audio). */
     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). */
@@ -7794,8 +9637,8 @@ declare class LLM$3 extends OpenAICompatibleLLMProvider {
 /**
  * Custom LLM — point Patter's pipeline at ANY OpenAI-compatible endpoint.
  *
- * The industry-standard "Custom LLM" pattern (the same concept ElevenLabs
- * Agents, Retell, and Vapi expose under that name): Patter owns the phone leg
+ * The industry-standard "Custom LLM" pattern (the name the voice-AI
+ * ecosystem uses for this concept): Patter owns the phone leg
  * — carrier, STT, turn-taking, barge-in, TTS — and POSTs each conversation
  * turn to YOUR ``/chat/completions`` endpoint. That endpoint can be:
  *
@@ -8160,6 +10003,166 @@ declare class SileroVAD implements VADProvider {
     reset(): void;
 }
 
+/**
+ * Smart-turn v3 semantic turn detector (ONNX).
+ *
+ * Audio-native end-of-utterance model from the pipecat-ai project
+ * (https://github.com/pipecat-ai/smart-turn, Apache-2.0 — ~8 M params,
+ * <100 ms CPU inference). Unlike a VAD — which only knows *whether* the
+ * caller is producing sound — smart-turn looks at the prosody of the last
+ * few seconds of speech and predicts whether the caller has *finished
+ * their turn* or is merely pausing mid-sentence ("My phone number is…").
+ *
+ * Wiring: pass an instance as `agent.turnDetector`. The pipeline stream
+ * handler then defers the STT finalize that normally fires on a VAD
+ * `speech_end` until the model agrees the turn is complete (probability
+ * ≥ {@link SmartTurnDetector.threshold}), holding for at most
+ * `agent.maxSemanticHoldMs` (default 1200 ms) so a turn can never hang.
+ *
+ * Model file: the ONNX weights are NOT bundled with the SDK (~30 MB).
+ * Download a `smart-turn-v3*.onnx` file from
+ * https://huggingface.co/pipecat-ai/smart-turn-v3 and point the SDK at it
+ * via the `PATTER_SMART_TURN_MODEL` environment variable or the
+ * `modelPath` option of {@link SmartTurnDetector.load}.
+ *
+ * Preprocessing (matches `pipecat-ai/smart-turn` `inference.py` exactly —
+ * the v3 ONNX graph takes Whisper log-mel features, not a raw waveform):
+ *
+ *  1. int16 LE PCM → float in [-1, 1] (÷ 32768).
+ *  2. Keep the LAST 8 s of 16 kHz audio; left-pad with zeros to exactly
+ *     128 000 samples so the speech sits at the END of the window
+ *     (`truncate_audio_to_last_n_seconds`).
+ *  3. Zero-mean / unit-variance normalize the full padded window
+ *     (`WhisperFeatureExtractor(..., do_normalize=True)`).
+ *  4. Whisper log-mel: 400-point Hann STFT (hop 160, reflect-padded,
+ *     centered), 80 Slaney-scale mel filters, `log10` with 1e-10 floor,
+ *     clamp to `max - 8`, scale `(x + 4) / 4`, drop the trailing frame
+ *     → `(80, 800)` float32.
+ *  5. `session.run({ input_features })` — the graph applies the sigmoid
+ *     internally and returns the end-of-turn probability directly.
+ *     `probability > 0.5` ⇒ turn complete.
+ *
+ * `onnxruntime-node` is loaded lazily as an optional dependency (same
+ * pattern as `providers/silero-vad.ts`). The feature extraction is pure
+ * TypeScript (mixed-radix FFT) and yields to the event loop periodically
+ * so a per-turn prediction never blocks inbound audio handling.
+ */
+
+/** Env var consulted by {@link SmartTurnDetector.load} when no `modelPath` is given. */
+declare const SMART_TURN_MODEL_ENV_VAR = "PATTER_SMART_TURN_MODEL";
+/** Options accepted by {@link SmartTurnDetector.load}. */
+interface SmartTurnDetectorOptions {
+    /**
+     * End-of-turn probability at/above which the turn is considered
+     * complete. Default 0.5 per the smart-turn v3 reference.
+     */
+    readonly threshold?: number;
+    /**
+     * Path to the `smart-turn-v3*.onnx` file. Falls back to the
+     * `PATTER_SMART_TURN_MODEL` environment variable when omitted.
+     */
+    readonly modelPath?: string;
+    /** Restrict ONNX Runtime to the CPU execution provider (default true). */
+    readonly forceCpu?: boolean;
+}
+/**
+ * Semantic end-of-utterance detector backed by smart-turn v3 (ONNX).
+ *
+ * Load via {@link SmartTurnDetector.load} (throws with actionable
+ * instructions when the optional deps or the model file are missing) or
+ * {@link SmartTurnDetector.maybeLoad} (warns once and resolves `undefined`
+ * instead, so the agent degrades to plain VAD-silence endpointing rather
+ * than crashing):
+ *
+ * ```ts
+ * const detector = await SmartTurnDetector.load();   // PATTER_SMART_TURN_MODEL
+ * // or: await SmartTurnDetector.load({ modelPath: '…/smart-turn-v3.0.onnx' });
+ * // or: await SmartTurnDetector.maybeLoad();        // undefined when unprovisioned
+ *
+ * const agent = phone.agent({ ..., turnDetector: detector });
+ * ```
+ *
+ * {@link predict} takes the most recent window of mono int16 LE PCM at
+ * 16 kHz (up to 8 s — longer windows are truncated to the last 8 s,
+ * shorter ones are left-padded) and returns the probability in `[0, 1]`
+ * that the caller has finished their turn. The pipeline handler compares
+ * it against {@link threshold} (default 0.5).
+ *
+ * The model is stateless (no streaming RNN state), so a single instance
+ * may be shared across concurrent calls.
+ */
+declare class SmartTurnDetector implements TurnDetectorProvider {
+    private readonly runtime;
+    private session;
+    private readonly thresholdValue;
+    private closed;
+    private constructor();
+    /**
+     * Load the smart-turn v3 ONNX model and return a ready detector.
+     * Throws with download instructions when no model file is configured
+     * (see {@link SMART_TURN_MODEL_ENV_VAR}), and with install instructions
+     * when `onnxruntime-node` is missing.
+     */
+    static load(options?: SmartTurnDetectorOptions): Promise<SmartTurnDetector>;
+    /**
+     * Like {@link load}, but degrade instead of throw.
+     *
+     * Resolves to `undefined` — after a single clear warning — when semantic
+     * turn detection is not provisioned: the optional `onnxruntime-node`
+     * dependency is missing, no model file is configured, or the configured
+     * file cannot be loaded. Intended for deployments where the detector is
+     * a soft upgrade:
+     *
+     * ```ts
+     * const agent = phone.agent({
+     *   ...,
+     *   turnDetector: await SmartTurnDetector.maybeLoad(),
+     * });
+     * ```
+     *
+     * `turnDetector: undefined` keeps the plain VAD-silence endpointing, so
+     * the agent starts (and the call behaves) exactly as if the feature were
+     * never enabled — it never crashes the app.
+     *
+     * An out-of-range `threshold` still throws: that is a configuration bug,
+     * not a provisioning gap. Mirror of the Python
+     * `SmartTurnDetector.maybe_load`.
+     */
+    static maybeLoad(options?: SmartTurnDetectorOptions): Promise<SmartTurnDetector | undefined>;
+    /**
+     * Internal factory used by tests — bypasses onnxruntime-node loading.
+     * @internal
+     */
+    static fromOnnxSession(runtime: OnnxRuntime, session: OnnxInferenceSession, options?: {
+        threshold?: number;
+    }): SmartTurnDetector;
+    /** Identifier of the underlying model (`smart-turn-v3`). */
+    get model(): string;
+    /** Identifier of the runtime backend (`ONNX`). */
+    get provider(): string;
+    /** Input sample rate the model expects (16 000 Hz). */
+    get sampleRate(): number;
+    /** Maximum audio context the model consumes per prediction (8 s). */
+    get maxWindowSeconds(): number;
+    /** End-of-turn probability at/above which the turn is complete. */
+    get threshold(): number;
+    /**
+     * End-of-turn probability for the given recent-audio window.
+     *
+     * @param pcm16Window Mono int16 little-endian PCM at 16 kHz — ideally
+     *   the full audio of the caller's current turn, up to 8 s (the
+     *   handler keeps a rolling 8 s buffer). Longer input is truncated to
+     *   the most recent 8 s; shorter input is left-padded with silence,
+     *   matching the reference preprocessing exactly.
+     * @returns Probability in `[0, 1]` that the turn is COMPLETE (the
+     *   graph applies the sigmoid internally). Returns 0 for an empty
+     *   window.
+     */
+    predict(pcm16Window: Buffer): Promise<number>;
+    /** Release the ONNX session. Idempotent. */
+    close(): Promise<void>;
+}
+
 /** Options accepted by {@link DeepFilterNetFilter}. */
 interface DeepFilterNetOptions {
     /** Absolute path to a DeepFilterNet ONNX model.  If omitted, the filter
@@ -8341,6 +10344,21 @@ declare class OpenAIRealtime2Adapter extends OpenAIRealtimeAdapter {
     private inbound8kCarry;
     /** GA-shape `session.update` payload. See module-level docstring. */
     private buildGASessionConfig;
+    /**
+     * GA-shape partial `session.update` body for a mid-session swap.
+     *
+     * Identical to the base v1 patch plus the mandatory `"type": "realtime"`
+     * discriminator — the GA endpoint rejects a `session.update` without it.
+     * Used by {@link OpenAIRealtimeAdapter.updateSession} (inherited unchanged)
+     * for the multi-agent `handoff_to` flow. Mirrors the Python
+     * `OpenAIRealtime2Adapter._build_session_update_patch`.
+     */
+    protected buildSessionUpdatePatch(instructions: string | undefined, tools: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        strict?: boolean;
+    }> | undefined): Record<string, unknown>;
     /**
      * Open the Realtime WebSocket against the GA endpoint and apply the GA
      * session configuration. Header `OpenAI-Beta: realtime=v1` is OMITTED
@@ -8567,7 +10585,15 @@ declare class StatefulResampler {
     private readonly dstRate;
     private firHistory;
     private firHistoryValid;
-    private firPendingSample;
+    /**
+     * Samples after the last emitted FIR center, carried to the next chunk
+     * (1–2 samples: the next center and/or its missing lookahead). Replaces
+     * the old single ``firPendingSample`` — that design wrote the pending
+     * sample into history too (processed twice, true s-2 lost) and edge-
+     * replicated the +2 tap at every chunk end, producing audible crackle at
+     * chunk boundaries.
+     */
+    private firCarry;
     private upsampleLast;
     private upsampleHasHistory;
     private resample24Last;
@@ -9129,6 +11155,31 @@ declare class TwilioAdapter {
      * Mirrors the Python adapter's ``generate_stream_twiml``.
      */
     static generateStreamTwiml(streamUrl: string, parameters?: Record<string, string>): string;
+    /**
+     * TwiML that parks the CALLER leg in the warm-transfer conference.
+     *
+     * `startConferenceOnEnter="false"` keeps the caller on Twilio's default
+     * hold music until a participant with `startConferenceOnEnter="true"` (the
+     * human agent) joins; `endConferenceOnExit="true"` tears the conference
+     * down if the caller hangs up while waiting. When `statusCallbackUrl` is
+     * provided, conference lifecycle events (start / end / join / leave) are
+     * posted there for observability.
+     *
+     * Mirrors the Python adapter's `generate_warm_transfer_caller_twiml`.
+     */
+    static generateWarmTransferCallerTwiml(conferenceName: string, statusCallbackUrl?: string): string;
+    /**
+     * TwiML executed on the TARGET (human agent) leg of a warm transfer.
+     *
+     * Speaks the agent-provided handoff `summary` first (skipped when empty),
+     * then joins the conference with `startConferenceOnEnter="true"` — which
+     * starts the conference, stops the caller's hold music, and bridges the
+     * two. `endConferenceOnExit="true"` ends the conference (and therefore the
+     * caller leg) when the human agent hangs up.
+     *
+     * Mirrors the Python adapter's `generate_warm_transfer_target_twiml`.
+     */
+    static generateWarmTransferTargetTwiml(conferenceName: string, summary?: string): string;
     /** Force-complete an in-progress call. */
     endCall(callSid: string): Promise<void>;
 }
@@ -9291,7 +11342,15 @@ declare class TelnyxSTT {
     private ws;
     private callbacks;
     private headerSent;
+    /** Construction args replayed by clone(). */
+    private readonly patterCtorArgs;
     constructor(apiKey: string, language?: string, transcriptionEngine?: TelnyxTranscriptionEngine, sampleRate?: number, baseUrl?: string);
+    /**
+     * Fresh adapter built with this instance's construction arguments —
+     * called per call by the stream handler so concurrent calls never share
+     * connection state (sockets/queues; cross-call transcript bleed).
+     */
+    clone(): this;
     /** 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. */
@@ -9350,6 +11409,655 @@ declare class TelnyxTTS {
     synthesizeStream(text: string): AsyncGenerator<Buffer>;
 }
 
+/**
+ * Eval case data model.
+ *
+ * An {@link EvalCase} is a scripted scenario: a sequence of user turns, an
+ * expected-behavior description, and a rubric used by the judge LLM.
+ *
+ * Designed to be loaded from a YAML/JSON suite file — see
+ * {@link loadSuite} in `runner.ts`. Mirrors the Python
+ * `getpatter.evals.case` module (frozen dataclasses → readonly interfaces).
+ */
+
+/** A single user utterance in a scripted conversation. */
+interface EvalTurn {
+    readonly user: string;
+    /**
+     * Optional substrings the agent's reply should contain — used as a cheap
+     * pre-filter (logged, never fatal) before invoking the LLM judge.
+     */
+    readonly expectedContains?: ReadonlyArray<string>;
+}
+/** A complete evaluation scenario. */
+interface EvalCase {
+    readonly name: string;
+    readonly turns: ReadonlyArray<EvalTurn>;
+    readonly expectedBehavior: string;
+    readonly rubric: string;
+    /** Optional metadata for reporting/filtering. */
+    readonly tags?: ReadonlyArray<string>;
+    /**
+     * Optional first-message the agent should emit before any user turn.
+     * On the real-pipeline path (``agent`` set) it overrides the agent's own
+     * ``firstMessage`` so the REAL handler speaks it; on the legacy
+     * ``reply()`` path it is prepended to the transcript display-only.
+     */
+    readonly firstMessage?: string;
+    /**
+     * Optional REAL-pipeline target. When ``agent`` is set, the runner drives
+     * the case through {@link EvalSession} — the real `StreamHandler`
+     * pipeline call loop (tools, hooks, guardrails, history) — instead of the
+     * legacy ``reply()``-callable factory. ``llmProvider`` optionally
+     * overrides ``agent.llm`` (e.g. a {@link ScriptedLLMProvider} for CI).
+     * Both default to ``undefined`` so existing suites are unaffected.
+     */
+    readonly agent?: AgentOptions;
+    readonly llmProvider?: LLMProvider;
+}
+/** The judge's verdict on one case. */
+interface JudgeResult {
+    /** Score in [0.0, 1.0]. */
+    readonly score: number;
+    readonly passed: boolean;
+    readonly reasoning: string;
+}
+/** One line of a judge-facing transcript. */
+interface TranscriptEntry {
+    readonly role: string;
+    readonly text: string;
+}
+/** The result of running a single {@link EvalCase}. */
+interface EvalResult {
+    readonly caseName: string;
+    readonly transcript: ReadonlyArray<TranscriptEntry>;
+    readonly judge: JudgeResult;
+    readonly durationS: number;
+    readonly error: string | null;
+}
+/**
+ * Render an {@link EvalResult} as the JSON-report row shape — mirrors the
+ * Python `EvalResult.to_dict()` (snake_case keys, stable across SDKs so CI
+ * artefacts are interchangeable).
+ */
+declare function evalResultToDict(result: EvalResult): Record<string, unknown>;
+
+/**
+ * LLM-as-judge scoring for eval cases.
+ *
+ * Mirrors the Python `getpatter.evals.llm_judge` module. The judge is
+ * intentionally provider-specific (OpenAI chat completions) because
+ * reliability of structured JSON output matters more than provider
+ * flexibility for evals. Callers who need a different backend can implement
+ * a {@link JudgeBackend} and inject it via the ``backend`` option.
+ */
+
+/** Pluggable judge backend — anything exposing ``judge(prompt)``. */
+interface JudgeBackend {
+    judge(prompt: string): Promise<string>;
+}
+/** Options for {@link LLMJudge}. Defaults match the Python SDK byte-for-byte. */
+interface LLMJudgeOptions {
+    /** Model the judge should use. Default: ``gpt-4o-mini``. */
+    readonly model?: string;
+    /** OpenAI API key. Falls back to ``OPENAI_API_KEY`` when unset. */
+    readonly apiKey?: string;
+    /** Score threshold for a pass. Default: ``0.7``. */
+    readonly passThreshold?: number;
+    /** Test/alternative backend — any object exposing ``judge(prompt)``. */
+    readonly backend?: JudgeBackend;
+}
+/** Scores conversation transcripts against a rubric via an OpenAI model. */
+declare class LLMJudge {
+    readonly model: string;
+    readonly passThreshold: number;
+    private readonly apiKey?;
+    private readonly backend?;
+    constructor(options?: LLMJudgeOptions);
+    /** Return a {@link JudgeResult} for the given transcript. */
+    judgeCase(evalCase: EvalCase, transcript: ReadonlyArray<TranscriptEntry>): Promise<JudgeResult>;
+    private buildPrompt;
+    /** Call OpenAI chat completions directly over fetch (no SDK dependency). */
+    private callOpenAI;
+    /** Parse the judge's JSON — tolerant of extra whitespace / code fences. */
+    private parse;
+}
+
+/**
+ * Eval runner — executes an {@link EvalSuite} against a scripted agent.
+ *
+ * Two execution paths per case (mirrors the Python `getpatter.evals.runner`):
+ *
+ * - **Legacy** (default): the caller supplies an ``agentFactory`` returning
+ *   an async ``reply(text) => string`` callable — no SDK machinery involved.
+ * - **Real pipeline**: when an {@link EvalCase} carries ``agent`` (an
+ *   {@link AgentOptions}, optionally with ``llmProvider``), the runner
+ *   drives the case through {@link EvalSession} — the real `StreamHandler`
+ *   pipeline call loop with tools, hooks, guardrails, and history handling.
+ *
+ * ```ts
+ * const evalCase: EvalCase = {
+ *   name: 'books a table',
+ *   turns: [{ user: 'table for two at eight' }],
+ *   expectedBehavior: 'Agent books and confirms the table.',
+ *   rubric: 'Pass if a booking is confirmed.',
+ *   agent: myAgent,                              // real agent under test
+ *   llmProvider: new ScriptedLLMProvider([...]), // or a real provider
+ * };
+ * const results = await new EvalRunner({ judge }).run({ name: 's', cases: [evalCase] });
+ * ```
+ */
+
+/**
+ * An agent callable receives one user turn and returns the agent's final
+ * text response. This decouples the runner from the real Patter Agent
+ * wiring and lets callers plug in any chat-completions client or mock.
+ */
+type AgentCallable = (text: string) => Promise<string>;
+/** A factory takes no arguments and returns an {@link AgentCallable}. */
+type AgentFactory = () => AgentCallable | Promise<AgentCallable>;
+/** A named collection of {@link EvalCase} to run together. */
+interface EvalSuite {
+    readonly name: string;
+    readonly cases: ReadonlyArray<EvalCase>;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Options for {@link EvalRunner}. */
+interface EvalRunnerOptions {
+    /** Judge used to score each case. Default: ``new LLMJudge()``. */
+    readonly judge?: LLMJudge;
+}
+/** Drives one or more cases against an agent and produces a JSON report. */
+declare class EvalRunner {
+    readonly judge: LLMJudge;
+    constructor(options?: EvalRunnerOptions);
+    /**
+     * Run every case in ``suite`` sequentially.
+     *
+     * ``agentFactory`` is required only for cases that do NOT carry their own
+     * ``agent`` (the legacy ``reply()`` path).
+     */
+    run(suite: EvalSuite, agentFactory?: AgentFactory): Promise<EvalResult[]>;
+    /**
+     * Run a single case and return its {@link EvalResult}.
+     *
+     * Routes through the real-pipeline {@link EvalSession} when
+     * ``evalCase.agent`` is set; otherwise uses the legacy ``reply()``-callable
+     * ``agentFactory`` (unchanged behaviour).
+     */
+    runCase(evalCase: EvalCase, agentFactory?: AgentFactory): Promise<EvalResult>;
+    /**
+     * Legacy path — drives the case against a ``reply()`` callable.
+     *
+     * Appends into ``transcript`` in place so a mid-case exception still
+     * leaves the partial transcript for the judge (existing semantics).
+     */
+    private runTurnsWithReply;
+    /**
+     * Real-pipeline path — drives the case through {@link EvalSession}.
+     *
+     * The agent's REAL handler emits its own ``firstMessage`` (a
+     * ``evalCase.firstMessage`` overrides the agent's), tools/hooks/guardrails
+     * run for real, and the transcript mirrors what the pipeline actually
+     * said. Appends into ``transcript`` in place (partial-on-error, same as
+     * the legacy path).
+     */
+    private runTurnsWithSession;
+    /** Render a JSON report suitable for CI artefacts. */
+    report(suite: EvalSuite, results: ReadonlyArray<EvalResult>): string;
+}
+/**
+ * Load a suite from YAML or JSON.
+ *
+ * Schema (YAML):
+ *
+ * ```yaml
+ * name: "customer support v1"
+ * cases:
+ *   - name: "greeting is warm"
+ *     expected_behavior: "Agent greets the caller warmly and asks how it can help."
+ *     rubric: "Pass if reply contains a greeting and an open-ended question."
+ *     turns:
+ *       - user: "hi"
+ * ```
+ *
+ * Suite files use snake_case keys (shared byte-for-byte with the Python
+ * SDK so one suite file drives both); camelCase aliases are also accepted.
+ */
+declare function loadSuite(path: string): Promise<EvalSuite>;
+
+/**
+ * Eval-harness fakes — the ONLY mocked boundary of {@link EvalSession}.
+ *
+ * Everything inward of these (transcript commit filters, barge-in state
+ * machine, LLM loop, tool executor, hooks, guardrails, sentence chunking,
+ * metrics) is the REAL pipeline code. The fakes stand in for the
+ * paid/external surfaces a live call touches: the telephony carrier
+ * (audio sender), the STT socket, and the TTS socket.
+ */
+
+/**
+ * Records every carrier-bound audio operation; auto-acks marks.
+ *
+ * The TS analogue of the carrier boundary is the {@link TelephonyBridge}, so
+ * this fake implements it directly. ``sentAudio`` collects the decoded wire
+ * chunks handed to the carrier, ``clears`` counts ``sendClear`` calls
+ * (barge-in flushes), ``marks`` records mark names, ``endedCalls`` /
+ * ``transfers`` record call-control invocations. When attached to a handler,
+ * each ``sendMark`` is echoed back through ``handler.onMark`` so mark-gated
+ * pacing never deadlocks.
+ */
+declare class FakeAudioSender implements TelephonyBridge {
+    readonly label = "Eval";
+    readonly telephonyProvider: CarrierKind;
+    readonly inputWireFormat: "pcm_16000";
+    readonly sentAudio: Buffer[];
+    readonly marks: string[];
+    readonly endedCalls: string[];
+    readonly transfers: Array<{
+        readonly callId: string;
+        readonly toNumber: string;
+    }>;
+    clears: number;
+    private handler;
+    private sttFactory;
+    /** Wire the auto-ack loopback for ``sendMark`` → ``onMark``. */
+    attachHandler(handler: {
+        onMark(markName: string): Promise<void>;
+    }): void;
+    /** Wire the STT instance ``createStt`` should hand to the handler. */
+    attachSttFactory(factory: () => STTAdapter | null): void;
+    sendAudio(_ws: WebSocket$1, audioBase64: string, _streamSid: string): void;
+    sendMark(_ws: WebSocket$1, markName: string, _streamSid: string): void;
+    sendClear(_ws: WebSocket$1, _streamSid: string): void;
+    transferCall(callId: string, toNumber: string, _options?: TransferCallOptions): Promise<TransferCallResult | void>;
+    endCall(callId: string, _ws: WebSocket$1): Promise<void>;
+    createStt(_agent: AgentOptions): Promise<STTAdapter | null>;
+    queryTelephonyCost(): Promise<void>;
+}
+/**
+ * Callback-backed STT double feeding the handler's REAL transcript path.
+ *
+ * The harness pushes finalised transcripts via {@link FakeSTT.pushFinal};
+ * the handler consumes them through the same ``onTranscript`` callback a
+ * live Deepgram adapter drives, so ``handleBargeIn`` → ``commitTranscript``
+ * → ``dispatchTurn`` run exactly as on a real call. ``pushFinal`` resolves
+ * once the handler's transcript drain loop has fully processed the
+ * transcript (i.e. the dispatch task for it — if any — has been created),
+ * which is what {@link EvalSession.userSays} awaits before grabbing the
+ * dispatch task.
+ */
+declare class FakeSTT implements STTAdapter {
+    readonly sentAudio: Buffer[];
+    connected: boolean;
+    closed: boolean;
+    private callback;
+    connect(): Promise<void>;
+    sendAudio(pcm: Buffer): void;
+    onTranscript(cb: STTTranscriptCallback): void;
+    /** Inject one final transcript through the handler's real receive path. */
+    pushFinal(text: string): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * TTS double: records the text it is asked to speak, yields silence.
+ *
+ * The default chunk is 320 bytes of PCM16 @ 16 kHz (10 ms of silence) so the
+ * handler's playback-backlog accounting stays in the sub-frame range and a
+ * following turn is never misclassified as a barge-in against a phantom
+ * carrier backlog. ``closed`` flips when the handler's teardown invokes
+ * ``cancelActiveStream`` (the TS TTS adapters are per-request — teardown
+ * cancels the active stream rather than closing a connection).
+ */
+declare class FakeTTS implements TTSAdapter {
+    readonly spoken: string[];
+    closed: boolean;
+    private readonly chunk;
+    constructor(chunk?: Buffer);
+    synthesizeStream(text: string): AsyncIterable<Buffer>;
+    /** Invoked by the handler's real teardown (``handleStop``). */
+    cancelActiveStream(): void;
+}
+
+/**
+ * Deterministic scripted LLM provider for CI evals.
+ *
+ * The fourth fake-able boundary of {@link EvalSession}: instead of a paid
+ * model API, a {@link ScriptedLLMProvider} replays pre-scripted streaming
+ * chunks through the REAL {@link LLMLoop} — tool dispatch, history
+ * threading, usage accounting, and abort handling all run for real.
+ */
+
+/** Build one scripted assistant turn that streams ``text`` then usage. */
+declare function textTurn(text: string, options?: {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+}): LLMChunk[];
+/**
+ * Build one scripted turn that emits a single complete tool call.
+ *
+ * The {@link LLMLoop} executes the tool via the real ``DefaultToolExecutor``
+ * and re-submits — so a tool scenario needs a follow-up scripted turn
+ * (usually {@link textTurn}) for the post-tool-result response.
+ */
+declare function toolCallTurn(name: string, args?: Record<string, unknown>, options?: {
+    readonly callId?: string;
+}): LLMChunk[];
+/** One recorded {@link ScriptedLLMProvider.stream} request. */
+interface ScriptedLLMCall {
+    readonly messages: Array<Record<string, unknown>>;
+    readonly tools: Array<Record<string, unknown>> | null;
+    readonly callId: string | null;
+}
+/**
+ * Deterministic {@link LLMProvider}.
+ *
+ * Pops one scripted chunk-list per ``stream()`` call (i.e. per LLM-loop
+ * iteration — a tool-call turn consumes one script for the call and one for
+ * the post-result response). Records every request's ``messages`` and
+ * ``tools`` in {@link ScriptedLLMProvider.calls} so tests can assert exactly
+ * what the real pipeline sent to the model. Honours the per-turn abort
+ * signal between chunks like a well-behaved provider.
+ */
+declare class ScriptedLLMProvider implements LLMProvider {
+    /** Stable pricing/dashboard key (no real pricing entry — cost is 0). */
+    static readonly providerKey = "scripted";
+    readonly calls: ScriptedLLMCall[];
+    private readonly scripts;
+    constructor(turns?: ReadonlyArray<ReadonlyArray<LLMChunk>>);
+    /** Append another scripted turn (chunk list) to the script queue. */
+    addTurn(chunks: ReadonlyArray<LLMChunk>): void;
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
+}
+
+/**
+ * Stream-handler utilities — capped conversation history and SSRF-validated
+ * tool-webhook execution shared across the various per-call handlers.
+ */
+/** A single entry in the per-call conversation history. */
+interface HistoryEntry {
+    readonly role: string;
+    readonly text: string;
+    readonly timestamp: number;
+}
+
+/**
+ * Eval session — drives the REAL pipeline call loop, no telephony required.
+ *
+ * Unlike the legacy ``reply()``-callable path in `runner.ts` (which never
+ * touches the SDK), {@link EvalSession} constructs a real
+ * {@link StreamHandler} in pipeline mode and injects user turns through the
+ * exact same path a live phone call uses:
+ *
+ * ``FakeSTT → onTranscript → handleBargeIn → commitTranscript →
+ * dispatchTurn → LLMLoop (real DefaultToolExecutor, hooks, guardrails) →
+ * SentenceChunker → FakeTTS → FakeAudioSender``
+ *
+ * so tool calling, pipeline hooks, guardrail replacement,
+ * dedup/hallucination filtering, history handling, metrics, and the
+ * turn-taking state machine are all exercised for real. Only the
+ * paid/external boundary is faked: the telephony bridge (audio sender), the
+ * STT socket, the TTS socket, and — optionally — the LLM (a deterministic
+ * {@link ScriptedLLMProvider} for CI, or any real {@link LLMProvider} for
+ * live evals). See `fakes.ts` / `scripted-llm.ts`.
+ *
+ * Lifecycle (TS idiom — no async context managers in JS):
+ *
+ * ```ts
+ * const session = await EvalSession.create({ agent, llmProvider });
+ * try {
+ *   const result = await session.userSays('where is my order?');
+ *   expect(result)
+ *     .toolCalled('lookup_order', { orderId: 'A1' })
+ *     .agentTextContains('tomorrow');
+ * } finally {
+ *   await session.close();
+ * }
+ * ```
+ *
+ * ``EvalSession.create()`` = ``new EvalSession(options)`` + ``await
+ * session.start()``; ``close()`` runs the handler's real teardown
+ * (``handleStop``) and is idempotent. Always pair ``create`` with a
+ * ``finally { await session.close() }`` so fakes and timers are released
+ * even when an assertion throws.
+ *
+ * Notes
+ * -----
+ * - ``agent.stt`` / ``agent.tts`` configs are ignored (replaced by the
+ *   fakes); ``agent.provider`` is forced to ``'pipeline'``.
+ * - ``onMessage``-style agents are not supported — the session targets the
+ *   built-in {@link LLMLoop} path.
+ * - ``TurnResult.agentText`` is what the caller HEARD (post-guardrail,
+ *   post-hook, post-text-transform sentences handed to TTS).
+ *   ``historySnapshot`` mirrors the dashboard conversation history, where
+ *   the streaming path records the raw LLM text.
+ */
+
+/**
+ * One tool invocation observed through the handler's tool-event path.
+ *
+ * ``args`` is the parsed-JSON object the {@link LLMLoop} handed to the real
+ * ``DefaultToolExecutor``; ``result`` is the executor's string return value
+ * (``null`` only for hand-built records). Caller-immutable by convention.
+ */
+interface ToolCallRecord {
+    readonly name: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+    readonly result: string | null;
+}
+/**
+ * The observable outcome of one {@link EvalSession.userSays} turn.
+ *
+ * - ``userText`` — the injected user utterance.
+ * - ``agentText`` — what the caller heard this turn: the sentences handed to
+ *   TTS after guardrails / hooks / text transforms, joined by a single
+ *   space. Falls back to the assistant history entry when no TTS sentence
+ *   was produced (e.g. the turn was cut short before synthesis).
+ * - ``toolCalls`` — tool invocations recorded via the handler's tool-event
+ *   path (``LLMLoop`` ``onToolCall`` → ``recordToolCall``), in execution
+ *   order.
+ * - ``historySnapshot`` — the handler's full conversation history right
+ *   after the turn settled (``role`` / ``text`` / ``timestamp`` entries,
+ *   including ``role: 'tool'`` timeline entries).
+ * - ``interrupted`` — true when the turn was cut short (barge-in cancel,
+ *   hook veto, or an LLM error that interrupted the turn) — derived from
+ *   the handler's ``turn_ended`` events carrying ``[interrupted]``.
+ * - ``metricsTurn`` — the {@link TurnMetrics} emitted for this turn via the
+ *   handler's ``onMetrics`` callback, or ``null`` when the turn did not
+ *   complete normally (vetoed / interrupted).
+ */
+interface TurnResult {
+    readonly userText: string;
+    readonly agentText: string;
+    readonly toolCalls: ReadonlyArray<ToolCallRecord>;
+    readonly historySnapshot: ReadonlyArray<HistoryEntry>;
+    readonly interrupted: boolean;
+    readonly metricsTurn: TurnMetrics | null;
+}
+/**
+ * Render a conversation history in the judge transcript shape
+ * (``[{ role: 'user'|'agent'|'tool', text }]`` — assistant → agent).
+ * Shared by {@link EvalSession.transcript} and the assertion ``judge``.
+ */
+declare function historyTranscript(history: ReadonlyArray<{
+    readonly role: string;
+    readonly text: string;
+}>): TranscriptEntry[];
+/** Options for {@link EvalSession}. Defaults match the Python SDK. */
+interface EvalSessionOptions {
+    /**
+     * The agent under test. Its ``stt`` / ``tts`` configs are replaced by
+     * fakes and ``provider`` is forced to ``'pipeline'``; everything else
+     * (tools, guardrails, hooks, text transforms, firstMessage, variables,
+     * ...) is live.
+     */
+    readonly agent: AgentOptions;
+    /**
+     * Optional LLM provider override. Defaults to ``agent.llm``. Pass a
+     * {@link ScriptedLLMProvider} for deterministic CI evals or a real
+     * provider for live evals.
+     */
+    readonly llmProvider?: LLMProvider;
+    /**
+     * Legacy fallback — when neither ``llmProvider`` nor ``agent.llm`` is
+     * set, the built-in OpenAI provider is built from this key (live evals
+     * only; never use in CI).
+     */
+    readonly openaiKey?: string;
+    /** Call identity threaded through the handler, tools' call context, and metrics. */
+    readonly callId?: string;
+    readonly caller?: string;
+    readonly callee?: string;
+    /**
+     * Optional per-call variables resolved into the system prompt exactly
+     * like ``phone.call({ customParams })``.
+     */
+    readonly customParams?: Readonly<Record<string, string>>;
+    /**
+     * Per-turn ceiling in seconds for {@link EvalSession.userSays} (LLM +
+     * tools + TTS). Generous default (60) for live providers; scripted
+     * providers finish in milliseconds.
+     */
+    readonly turnTimeoutS?: number;
+}
+/**
+ * Harness around a real pipeline-mode {@link StreamHandler}.
+ *
+ * See the module docstring for usage. Construction is cheap; the handler is
+ * built and started in {@link EvalSession.start} (``EvalSession.create``
+ * calls it).
+ */
+declare class EvalSession {
+    readonly callId: string;
+    readonly caller: string;
+    readonly callee: string;
+    /** The faked carrier boundary — records audio / clears / marks. */
+    readonly audioSender: FakeAudioSender;
+    /** The faked STT boundary — inject transcripts via the session, not directly. */
+    readonly stt: FakeSTT;
+    /** The faked TTS boundary — ``spoken`` records every synthesised sentence. */
+    readonly tts: FakeTTS;
+    /**
+     * Every payload the handler fired through ``onTranscript`` — user /
+     * assistant / tool events, in emission order.
+     */
+    readonly transcriptEvents: Array<Record<string, unknown>>;
+    private readonly sourceAgent;
+    private readonly llmProvider?;
+    private readonly openaiKey;
+    private readonly customParams?;
+    private readonly turnTimeoutS;
+    private streamHandler;
+    private readonly toolCalls;
+    private readonly metricsTurns;
+    private interruptedTurns;
+    private offTurnEnded;
+    private started;
+    private closed;
+    constructor(options: EvalSessionOptions);
+    /** Build AND start a session — the canonical entry point. */
+    static create(options: EvalSessionOptions): Promise<EvalSession>;
+    /** Build and start the real handler (idempotent). */
+    start(): Promise<void>;
+    /** Run the handler's real teardown (``handleStop``). Idempotent. */
+    close(): Promise<void>;
+    /**
+     * Inject one final user transcript and await the full agent turn.
+     *
+     * The transcript flows through the handler's real receive path — barge-in
+     * handling, dedup/hallucination filtering, hooks, the LLM loop with real
+     * tool execution, guardrails, sentence chunking, and TTS — exactly as on
+     * a live call. Returns once the turn's dispatch task settles.
+     *
+     * Throws:
+     * - ``PatterError`` (``INPUT_VALIDATION``) — the REAL pipeline dropped
+     *   the transcript (duplicate within the 2 s throttle window, known STT
+     *   hallucination, or empty text) — same behaviour as a live call.
+     * - ``PatterError`` (``TIMEOUT``) — the turn did not settle within
+     *   ``timeoutS`` (default: the session's ``turnTimeoutS``).
+     */
+    userSays(text: string, options?: {
+        readonly timeoutS?: number;
+    }): Promise<TurnResult>;
+    /** The live {@link StreamHandler} (``null`` before ``start``). */
+    get handler(): StreamHandler | null;
+    /** Current conversation history (shallow copies of the entries). */
+    get history(): HistoryEntry[];
+    /** Full-session transcript in the judge shape (assistant → agent). */
+    transcript(): TranscriptEntry[];
+    /** Return the agent reshaped for harness execution. */
+    private buildEvalAgent;
+    private buildTurnResult;
+}
+
+/**
+ * Fluent assertions for {@link TurnResult}.
+ *
+ * Chainable expectations against the outcome of one real pipeline turn
+ * driven by {@link EvalSession}:
+ *
+ * ```ts
+ * const result = await session.userSays('book me a table for two');
+ * expect(result)
+ *   .toolCalled('book_table', { partySize: 2 })
+ *   .agentTextContains('booked');
+ *
+ * // Semantic check via the LLMJudge (async, ends the chain):
+ * await expect(result).judge(new LLMJudge(), {
+ *   intent: 'The agent confirms the booking and offers help.',
+ * });
+ * ```
+ *
+ * Every failed expectation throws Node's ``AssertionError`` with the
+ * observed values, so plain vitest reports are actionable without extra
+ * plumbing. Mirrors the Python `getpatter.evals.assertions` module.
+ */
+
+/** Wrap a {@link TurnResult} in a chainable expectation object. */
+declare function expect(result: TurnResult): TurnExpectation;
+/** Options for {@link TurnExpectation.agentTextContains}. */
+interface AgentTextContainsOptions {
+    /** Compare needles case-sensitively. Default: false (Python parity). */
+    readonly caseSensitive?: boolean;
+}
+/** Chainable assertions over one turn. See {@link expect}. */
+declare class TurnExpectation {
+    private readonly turnResult;
+    constructor(result: TurnResult);
+    /** The wrapped {@link TurnResult} (escape hatch for ad-hoc asserts). */
+    get result(): TurnResult;
+    /**
+     * Assert that tool ``name`` ran this turn.
+     *
+     * ``argsSubset`` (optional) must be recursively contained in the args of
+     * at least one matching invocation — extra argument keys are allowed,
+     * listed keys must match exactly.
+     */
+    toolCalled(name: string, argsSubset?: Record<string, unknown>): TurnExpectation;
+    /** Assert that no tool ran this turn (or that ``name`` did not). */
+    noToolCalled(name?: string): TurnExpectation;
+    /**
+     * Assert that every needle appears in the spoken agent text.
+     *
+     * Variadic form is case-insensitive (Python default); pass an array plus
+     * an options object for ``caseSensitive: true``.
+     */
+    agentTextContains(...needles: string[]): TurnExpectation;
+    agentTextContains(needles: string | ReadonlyArray<string>, options?: AgentTextContainsOptions): TurnExpectation;
+    /**
+     * Score this turn against ``intent`` with the LLM judge.
+     *
+     * Builds a synthetic {@link EvalCase} whose ``expectedBehavior`` is
+     * ``intent`` and judges the turn's full history snapshot. Throws
+     * ``AssertionError`` when the judge fails the turn; returns the
+     * {@link JudgeResult} otherwise (chain-ending, async).
+     */
+    judge(llmJudge: LLMJudge, options: {
+        readonly intent: string;
+        readonly rubric?: string;
+    }): Promise<JudgeResult>;
+}
+
 declare const SPAN_CALL = "getpatter.call";
 declare const SPAN_STT = "getpatter.stt";
 declare const SPAN_LLM = "getpatter.llm";
@@ -9384,6 +12092,11 @@ interface InitTracingOptions {
  * may be a no-op if the host hasn't registered one).
  */
 declare function initTracing(options?: InitTracingOptions): boolean;
+/**
+ * Flush any pending spans and tear down the tracer provider. Safe to call
+ * unconditionally — returns immediately when tracing was never wired up.
+ */
+declare function shutdownTracing(): Promise<void>;
 /** True only if the env flag is set AND the tracer initialized cleanly. */
 declare function isTracingEnabled(): boolean;
 /**
@@ -9397,6 +12110,75 @@ declare function isTracingEnabled(): boolean;
  * Returns a no-op span when tracing is disabled or unavailable.
  */
 declare function startSpan(name: string, attrs?: Record<string, unknown>): Span;
+/**
+ * Convenience wrapper — starts a span, runs ``fn``, records exceptions on
+ * throw, and always ends the span (try/finally). Mirrors Python's
+ * ``with start_span(...):`` context-manager ergonomics.
+ *
+ * ```ts
+ * await withSpan(SPAN_LLM, { 'llm.model': 'gpt-4o' }, async (span) => {
+ *   span.setAttribute('llm.tokens', 123);
+ *   return await callLLM();
+ * });
+ * ```
+ */
+declare function withSpan<T>(name: string, attrs: Record<string, unknown> | undefined, fn: (span: Span) => Promise<T>): Promise<T>;
+
+/**
+ * Stamp ``patter.*`` attributes on the current span, augmenting them with
+ * the ambient ``patter.call_id`` / ``patter.side`` from the active
+ * ``patterCallScope``. No-op when tracing is disabled or no scope is
+ * active.
+ *
+ * Behaviour mirrors the Python helper:
+ *   - If an active recording span exists, attributes are stamped on it.
+ *   - Otherwise a transient zero-duration ``patter.billable`` span is
+ *     opened to carry the attributes. Some collectors filter
+ *     zero-duration spans; callers that need guaranteed attribution
+ *     should wrap their billable work in their own span.
+ *
+ * Caller-provided ``patter.call_id`` / ``patter.side`` keys win over the
+ * scope's values.
+ */
+declare function recordPatterAttrs(attrs: Readonly<Record<string, unknown>>): void;
+/**
+ * Bind ``callId`` and ``side`` to the active span scope for the duration
+ * of ``fn``. Mirrors the Python ``patter_call_scope`` context manager:
+ * any ``recordPatterAttrs`` call made inside ``fn`` (or anything ``fn``
+ * awaits) sees the bound values.
+ *
+ * Note: JavaScript has no ContextVar equivalent, so this uses a
+ * module-level stack. Concurrent overlapping scopes on the same event
+ * loop will see the innermost scope's values — fine for the SDK's
+ * one-call-per-handler model. If callers need true async-context
+ * isolation, install ``AsyncLocalStorage``-backed propagation via the
+ * OTel SDK's context manager.
+ */
+declare function patterCallScope<T>(options: {
+    readonly callId: string;
+    readonly side?: string;
+}, fn: () => Promise<T>): Promise<T>;
+/**
+ * Wire an OTel ``SpanExporter`` into the SDK's tracer provider and
+ * remember the configured ``side`` on the Patter instance so the
+ * per-call handler reads it when entering ``patterCallScope``.
+ *
+ * Mirrors the Python ``attach_span_exporter`` contract:
+ *   - Stores ``side`` on ``patterInstance._patterSide`` unconditionally
+ *     (works even when ``@opentelemetry/*`` peer deps are missing).
+ *   - Idempotent on the *same exporter object reference*. Two distinct
+ *     exporter instances pointing at the same backend will both be
+ *     attached and spans will be exported twice — hold a single
+ *     exporter object across calls to avoid duplicates.
+ *
+ * When tracing isn't enabled (env flag off / SDK peer deps absent), the
+ * call is a no-op aside from storing ``_patterSide``.
+ */
+declare function attachSpanExporter(patterInstance: {
+    _patterSide?: string;
+} & Record<string, unknown>, exporter: unknown, options?: {
+    readonly side?: string;
+}): void;
 
 /**
  * Observability entrypoint — re-exports the tracing API.
@@ -9430,4 +12212,4 @@ declare const custom: Readonly<{
     LLM: typeof LLM$2;
 }>;
 
-export { type AgentOptions, type AgentState, AllProvidersFailedError, type AnthropicConversion, LLM$7 as AnthropicLLM, type AnthropicLLMOptions, type AnthropicMessage, AssemblyAIEncoding, AssemblyAIModel, STT$1 as AssemblyAISTT, type AssemblyAISTTOptions, type AudioConfig, type AudioSource, AuthenticationError, type BackgroundAudioOptions, BackgroundAudioPlayer, type EvaluateContext as BargeInEvaluateContext, type BargeInStrategy, BuiltinAudioClip, type BuiltinAudioClipName, type BuiltinPcmSource, type CallControl, type CallEvent, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOutcome, type CallRecord, type CallResult, type CarrierKind, type CartesiaEncoding, STT$3 as CartesiaSTT, type CartesiaSTTOptions, TTS$3 as CartesiaTTS, CartesiaTTSModel, type CartesiaTTSOptions, CartesiaTTSVoiceMode, LLM$5 as CerebrasLLM, type CerebrasLLMOptions, ChatContext, type ChatMessage, type ChatRole, CloudflareTunnel, type ConsultConfig, type ConversationStateSnapshot, type CostBreakdown, LLM$2 as CustomLLM, type CustomLLMOptions, DEFAULT_MIN_SENTENCE_LEN, DEFAULT_PRICING, DTMF_EVENTS, DeepFilterNetFilter, type DeepFilterNetOptions, DeepgramModel, STT$6 as DeepgramSTT, type DeepgramSTTOptions, DefaultToolExecutor, type DefaultToolExecutorOptions, type DefineToolInput, type DtmfEvent, ConvAI as ElevenLabsConvAI, ElevenLabsConvAIAdapter, type ConvAIOptions as ElevenLabsConvAIOptions, ElevenLabsModel, ElevenLabsOutputFormat, ElevenLabsTTS as ElevenLabsRestTTS, 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$4 as GoogleLLM, type GoogleLLMOptions, LLM$6 as GroqLLM, type GroqLLMOptions, Guardrail$1 as Guardrail, type GuardrailOptions, LLM$1 as HermesLLM, type HermesLLMOptions, type HookContext, IVRActivity, type IVRActivityOptions, type IVRToolDefinition, type IncomingMessage, type InitTracingOptions, TTS as InworldTTS, type InworldTTSOptions, type JobCallback, KrispFrameDuration, KrispSampleRate, KrispVivaFilter, type KrispVivaFilterOptions, 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, MinWordsStrategy, type MinWordsStrategyOptions, type ModelPricing, Ngrok, type OpenAICompatibleConsult, LLM$3 as OpenAICompatibleLLM, type OpenAICompatibleLLMOptions, OpenAICompatibleLLMProvider, LLM$8 as OpenAILLM, type OpenAILLMOptions, OpenAILLMProvider, type OpenAIMessage, Realtime as OpenAIRealtime, Realtime2 as OpenAIRealtime2, OpenAIRealtime2Adapter, type Realtime2Options as OpenAIRealtime2Options, OpenAIRealtimeAdapter, OpenAIRealtimeAudioFormat, OpenAIRealtimeModel, type RealtimeOptions as OpenAIRealtimeOptions, OpenAIRealtimeVADType, TTS$4 as OpenAITTS, type OpenAITTSOptions, STT$4 as OpenAITranscribeSTT, type OpenAITranscribeSTTOptions, OpenAITranscriptionModel, OpenAIVoice, LLM as OpenClawLLM, type OpenClawLLMOptions, PRICING_LAST_UPDATED, PRICING_VERSION, type ParamSpec, PartialStreamError, Patter, PatterConfigError, PatterConnectionError, PatterError, type PatterEventType, PatterTool, type PatterToolExecuteArgs, type PatterToolOptions, type PatterToolResult, PcmCarry, PipelineHookExecutor, type PipelineHooks, type PipelineMessageHandler, Carrier as Plivo, PlivoAdapter, type PlivoCarrierOptions, type InitiateCallOptions as PlivoInitiateCallOptions, type InitiateCallResult as PlivoInitiateCallResult, PricingUnit, type PricingUnitValue, type ProviderPricing, ProvisionError, RateLimitError, type RawPcmSource, type RealtimeConfig, type RealtimeTurnDetection, RemoteMessageHandler, RimeAudioFormat, RimeModel, 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 SessionContext, 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$1 as Telnyx, TelnyxAdapter, type TelnyxCarrierOptions, type ConfigureNumberOptions as TelnyxConfigureNumberOptions, type EndCallOptions as TelnyxEndCallOptions, type InitiateCallOptions$1 as TelnyxInitiateCallOptions, type InitiateCallResult$1 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$2 as Twilio, TwilioAdapter, type TwilioAdapterOptions, type TwilioCarrierOptions, type ConfigureNumberOptions$1 as TwilioConfigureNumberOptions, type InitiateCallOptions$2 as TwilioInitiateCallOptions, type InitiateCallResult$2 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, custom, deepgram, defineTool, elevenlabs, evaluateStrategies as evaluateBargeInStrategies, filterEmoji, filterForTTS, filterMarkdown, formatDtmf, geminiLive, getLogger, guardrail, hashCaller, hermes, initTracing, isRemoteUrl, isTracingEnabled, isWebSocketUrl, lmnt, makeAuthMiddleware, mergePricing, mixPcm, mountApi, mountDashboard, mulawToPcm16, notifyDashboard, openaiCompatible, openaiTts, openclaw, openclawConsult, openclawPostCallNotifier, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, resamplePcm, resetStrategies as resetBargeInStrategies, rime, scheduleCron, scheduleInterval, scheduleOnce, selectSoundFromList, setLogger, soniox, speechmatics, startSpan, startTunnel, tool, ultravox, whisper };
+export { AGENT_BACKLOG_CAP_S, type AgentCallable, type AgentFactory, type AgentOptions, type AgentState, type AgentTextContainsOptions, AllProvidersFailedError, type AnthropicConversion, LLM$7 as AnthropicLLM, type AnthropicLLMOptions, type AnthropicMessage, AssemblyAIEncoding, AssemblyAIModel, STT$1 as AssemblyAISTT, type AssemblyAISTTOptions, type AudioConfig, type AudioSource, AuthenticationError, type BackgroundAudioOptions, BackgroundAudioPlayer, type EvaluateContext as BargeInEvaluateContext, type BargeInStrategy, BuiltinAudioClip, type BuiltinAudioClipName, type BuiltinPcmSource, type CallControl, type CallEvent, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOutcome, type CallRecord, type CallResult, type CarrierKind, type CartesiaEncoding, STT$3 as CartesiaSTT, type CartesiaSTTOptions, TTS$3 as CartesiaTTS, CartesiaTTSModel, type CartesiaTTSOptions, CartesiaTTSVoiceMode, LLM$5 as CerebrasLLM, type CerebrasLLMOptions, ChatContext, type ChatMessage, type ChatRole, CloudflareTunnel, type ConsultConfig, type ConversationStateSnapshot, type CostBreakdown, LLM$2 as CustomLLM, type CustomLLMOptions, DEFAULT_MIN_SENTENCE_LEN, DEFAULT_PRICING, DTMF_EVENTS, DeepFilterNetFilter, type DeepFilterNetOptions, DeepgramModel, STT$6 as DeepgramSTT, type DeepgramSTTOptions, DefaultToolExecutor, type DefaultToolExecutorOptions, type DefineToolInput, type DtmfEvent, ConvAI as ElevenLabsConvAI, ElevenLabsConvAIAdapter, type ConvAIOptions as ElevenLabsConvAIOptions, ElevenLabsModel, ElevenLabsOutputFormat, ElevenLabsTTS as ElevenLabsRestTTS, TTS$6 as ElevenLabsTTS, type ElevenLabsTTSOptions, type ElevenLabsWebSocketOptions, TTS$5 as ElevenLabsWebSocketTTS, type EouTrigger, ErrorCode, type EvalCase, type EvalResult, EvalRunner, type EvalRunnerOptions, EvalSession, type EvalSessionOptions, type EvalSuite, type EvalTurn, EventBus, FakeAudioSender, FakeSTT, FakeTTS, FallbackLLMProvider, type FallbackLLMProviderOptions, type FilePcmSource, GEMINI_DEFAULT_INPUT_SR, GEMINI_DEFAULT_OUTPUT_SR, GeminiLiveAdapter, type GeminiLiveEventHandler, LLM$4 as GoogleLLM, type GoogleLLMOptions, LLM$6 as GroqLLM, type GroqLLMOptions, Guardrail$1 as Guardrail, type GuardrailOptions, LLM$1 as HermesLLM, type HermesLLMOptions, type HookContext, IVRActivity, type IVRActivityOptions, type IVRToolDefinition, type IncomingMessage, type InitTracingOptions, TTS as InworldTTS, type InworldTTSOptions, type JobCallback, type JudgeBackend, type JudgeResult, KrispFrameDuration, KrispSampleRate, KrispVivaFilter, type KrispVivaFilterOptions, type LLMChunk, LLMJudge, type LLMJudgeOptions, LLMLoop, type LLMProvider, LMNTAudioFormat, LMNTModel, LMNTSampleRate, TTS$1 as LMNTTTS, type LMNTTTSOptions, type LatencyBreakdown, type LocalCallOptions, LocalCallRecorder, type LocalConfig, type LocalOptions, type Logger, type LoopCallback, type MessageHandler, MetricsStore, MinWordsStrategy, type MinWordsStrategyOptions, type ModelPricing, Ngrok, type OpenAICompatibleConsult, LLM$3 as OpenAICompatibleLLM, type OpenAICompatibleLLMOptions, OpenAICompatibleLLMProvider, LLM$8 as OpenAILLM, type OpenAILLMOptions, OpenAILLMProvider, type OpenAIMessage, Realtime as OpenAIRealtime, Realtime2 as OpenAIRealtime2, OpenAIRealtime2Adapter, type Realtime2Options as OpenAIRealtime2Options, OpenAIRealtimeAdapter, OpenAIRealtimeAudioFormat, OpenAIRealtimeModel, type RealtimeOptions as OpenAIRealtimeOptions, OpenAIRealtimeVADType, TTS$4 as OpenAITTS, type OpenAITTSOptions, STT$4 as OpenAITranscribeSTT, type OpenAITranscribeSTTOptions, OpenAITranscriptionModel, OpenAIVoice, LLM as OpenClawLLM, type OpenClawLLMOptions, PRICING_LAST_UPDATED, PRICING_VERSION, type ParamSpec, PartialStreamError, Patter, PatterConfigError, PatterConnectionError, PatterError, type PatterEventType, PatterTool, type PatterToolExecuteArgs, type PatterToolOptions, type PatterToolResult, PcmCarry, PipelineHookExecutor, type PipelineHooks, type PipelineMessageHandler, Carrier as Plivo, PlivoAdapter, type PlivoCarrierOptions, type InitiateCallOptions as PlivoInitiateCallOptions, type InitiateCallResult as PlivoInitiateCallResult, PricingUnit, type PricingUnitValue, type ProviderPricing, ProvisionError, RECORDING_SAMPLE_RATE, RateLimitError, type RawPcmSource, type RealtimeConfig, type RealtimeTurnDetection, type RecorderEncoding, RemoteMessageHandler, RimeAudioFormat, RimeModel, TTS$2 as RimeTTS, type RimeTTSOptions, SMART_TURN_MODEL_ENV_VAR, SPAN_BARGEIN, SPAN_CALL, SPAN_ENDPOINT, SPAN_LLM, SPAN_STT, SPAN_TOOL, SPAN_TTS, type SSEEvent, type STTConfig, type ScheduleHandle, type ScriptedLLMCall, ScriptedLLMProvider, SentenceChunker, type ServeOptions, type SessionContext, type SilenceCallback, type SileroSampleRate, SileroVAD, type SileroVADOptions, SmartTurnDetector, type SmartTurnDetectorOptions, 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$1 as Telnyx, TelnyxAdapter, type TelnyxCarrierOptions, type ConfigureNumberOptions as TelnyxConfigureNumberOptions, type EndCallOptions as TelnyxEndCallOptions, type InitiateCallOptions$1 as TelnyxInitiateCallOptions, type InitiateCallResult$1 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 ToolCallRecord, type ToolDefinition, type ToolExecutor, type ToolHandler, type ToolOptions, type TranscriptEntry, type TransferCallOptions, type TransferCallResult, type TunnelHandle, TurnExpectation, type TurnMetrics, type TurnResult, Carrier$2 as Twilio, TwilioAdapter, type TwilioAdapterOptions, type TwilioCarrierOptions, type ConfigureNumberOptions$1 as TwilioConfigureNumberOptions, type InitiateCallOptions$2 as TwilioInitiateCallOptions, type InitiateCallResult$2 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, attachSpanExporter, builtinClipPath, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, cartesia, createResampler16kTo8k, createResampler24kTo16k, createResampler24kTo8k, createResampler8kTo16k, custom, deepgram, defineTool, elevenlabs, evalResultToDict, evaluateStrategies as evaluateBargeInStrategies, expect, filterEmoji, filterForTTS, filterMarkdown, formatDtmf, geminiLive, getLogger, guardrail, hashCaller, hermes, historyTranscript, initTracing, isRemoteUrl, isTracingEnabled, isWebSocketUrl, lmnt, loadSuite, makeAuthMiddleware, mergePricing, mixPcm, mountApi, mountDashboard, mulawToPcm16, notifyDashboard, openaiCompatible, openaiTts, openclaw, openclawConsult, openclawPostCallNotifier, patterCallScope, pcm16ToMulaw, recordPatterAttrs, resample16kTo8k, resample24kTo16k, resample8kTo16k, resamplePcm, resetStrategies as resetBargeInStrategies, rime, scheduleCron, scheduleInterval, scheduleOnce, selectSoundFromList, setLogger, shutdownTracing, soniox, speechmatics, startSpan, startTunnel, textTurn, tool, toolCallTurn, ultravox, whisper, withSpan };