getpatter 0.4.1 → 0.4.3

package/dist/index.d.ts

@@ -124,6 +124,48 @@ interface Guardrail {
     /** Replacement text spoken when guardrail triggers */
     replacement?: string;
 }
+interface HookContext {
+    readonly callId: string;
+    readonly caller: string;
+    readonly callee: string;
+    readonly history: ReadonlyArray<{
+        role: string;
+        text: string;
+    }>;
+}
+interface PipelineHooks {
+    /** Called with the raw PCM audio chunk before it is forwarded to the STT provider.
+     *  Return null to drop the chunk (e.g., for custom VAD gating). */
+    beforeSendToStt?: (audio: Buffer, ctx: HookContext) => Buffer | null | Promise<Buffer | null>;
+    /** Called after STT produces a transcript, before LLM. Return null to skip this turn. */
+    afterTranscribe?: (transcript: string, ctx: HookContext) => string | null | Promise<string | null>;
+    /** Called before TTS, per-sentence in streaming mode. Return null to skip TTS for this sentence. */
+    beforeSynthesize?: (text: string, ctx: HookContext) => string | null | Promise<string | null>;
+    /** Called after TTS produces an audio chunk. Return null to discard this chunk. */
+    afterSynthesize?: (audio: Buffer, text: string, ctx: HookContext) => Buffer | null | Promise<Buffer | null>;
+}
+/** Voice activity event emitted by a VADProvider. */
+interface VADEvent {
+    readonly type: 'speech_start' | 'speech_end' | 'silence';
+    readonly confidence?: number;
+    readonly durationMs?: number;
+}
+/** Server-side voice activity detector. Integrated before STT in pipeline mode. */
+interface VADProvider {
+    processFrame(pcmChunk: Buffer, sampleRate: number): Promise<VADEvent | null>;
+    close(): Promise<void>;
+}
+/** Pre-STT audio filter — noise cancellation, gain, EQ. */
+interface AudioFilter {
+    process(pcmChunk: Buffer, sampleRate: number): Promise<Buffer>;
+    close(): Promise<void>;
+}
+/** Mixes background audio (hold music, thinking cues) with TTS output. */
+interface BackgroundAudioPlayer$1 {
+    start(): Promise<void>;
+    mix(agentPcm: Buffer, sampleRate: number): Promise<Buffer>;
+    stop(): Promise<void>;
+}
 interface AgentOptions {
     systemPrompt: string;
     voice?: string;
@@ -143,6 +185,18 @@ interface AgentOptions {
     variables?: Record<string, string>;
     /** Output guardrails — filter AI responses before TTS */
     guardrails?: Guardrail[];
+    /** Pipeline hooks — intercept and transform data at each pipeline stage (pipeline mode only). */
+    hooks?: PipelineHooks;
+    /** Text transforms applied to LLM output before TTS (pipeline mode only).
+     *  Each function receives a string and returns the transformed string.
+     *  Applied in order before the ``beforeSynthesize`` hook. */
+    textTransforms?: Array<(text: string) => string>;
+    /** Optional server-side VAD (e.g., Silero). Pipeline mode only. */
+    vad?: VADProvider;
+    /** Optional pre-STT audio filter (noise cancellation). Pipeline mode only. */
+    audioFilter?: AudioFilter;
+    /** Optional background audio mixer (hold music, thinking cues). Pipeline mode only. */
+    backgroundAudio?: BackgroundAudioPlayer$1;
 }
 type PipelineMessageHandler = (data: Record<string, unknown>) => Promise<string>;
 interface ServeOptions {
@@ -269,6 +323,50 @@ declare class Patter {
     private registerNumber;
 }
 
+/**
+ * Factory function that builds a {@link ToolDefinition} from a concise
+ * parameter spec, auto-generating the full JSON Schema `parameters` object.
+ *
+ * @example
+ * ```ts
+ * import { defineTool } from 'getpatter';
+ *
+ * const getWeather = defineTool({
+ *   name: 'get_weather',
+ *   description: 'Get the current weather for a location.',
+ *   parameters: {
+ *     location: { type: 'string', description: 'City name or zip code' },
+ *     unit: { type: 'string', description: 'Temperature unit', default: 'celsius' },
+ *   },
+ *   handler: async (args) => {
+ *     return `Sunny, 22°${(args.unit as string)[0].toUpperCase()}`;
+ *   },
+ * });
+ * ```
+ */
+
+/** Shorthand property spec accepted by {@link defineTool}. */
+interface ParamSpec {
+    readonly type: string;
+    readonly description?: string;
+    /** When present the parameter is *not* required. */
+    readonly default?: unknown;
+}
+/** Input accepted by {@link defineTool}. */
+interface DefineToolInput {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: Readonly<Record<string, ParamSpec>>;
+    readonly handler: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<string>;
+}
+/**
+ * Build a full {@link ToolDefinition} from a concise parameter spec.
+ *
+ * Parameters that include a `default` value are treated as optional; all
+ * others are added to the JSON Schema `required` array.
+ */
+declare function defineTool(input: DefineToolInput): ToolDefinition;
+
 interface Logger {
     info(message: string, ...args: unknown[]): void;
     warn(message: string, ...args: unknown[]): void;
@@ -278,6 +376,109 @@ interface Logger {
 declare function getLogger(): Logger;
 declare function setLogger(logger: Logger): void;
 
+/**
+ * Sentence chunker for streaming TTS in pipeline mode.
+ *
+ * Accumulates streaming LLM tokens and yields complete sentences.
+ * Uses regex-based marker replacement for robust sentence boundary
+ * detection, handling abbreviations, acronyms, decimals, websites,
+ * ellipsis, and CJK punctuation.
+ *
+ * Algorithm adapted from LiveKit Agents (Apache 2.0):
+ * https://github.com/livekit/agents
+ */
+/** Default minimum sentence length before emitting. */
+declare const DEFAULT_MIN_SENTENCE_LEN = 20;
+/**
+ * Accumulates streaming tokens and yields complete sentences.
+ *
+ * @example
+ * ```typescript
+ * const chunker = new SentenceChunker();
+ * for await (const token of llmStream) {
+ *   for (const sentence of chunker.push(token)) {
+ *     await tts.synthesizeStream(sentence);
+ *   }
+ * }
+ * for (const sentence of chunker.flush()) {
+ *   await tts.synthesizeStream(sentence);
+ * }
+ * ```
+ */
+declare class SentenceChunker {
+    private buffer;
+    private readonly minSentenceLen;
+    constructor(options?: {
+        minSentenceLen?: number;
+    });
+    /** Feed a token. Returns zero or more complete sentences. */
+    push(token: string): string[];
+    /** Flush remaining buffer as final sentence(s). Call at end of stream. */
+    flush(): string[];
+    /** Discard buffered text. Call on interrupt. */
+    reset(): void;
+}
+
+/**
+ * Pipeline hook executor for pipeline mode.
+ *
+ * Runs user-defined hooks at each stage of the STT → LLM → TTS pipeline.
+ * Fail-open: if a hook throws, the error is logged and the original value
+ * passes through unchanged.
+ */
+
+declare class PipelineHookExecutor {
+    private readonly hooks;
+    constructor(hooks: PipelineHooks | undefined);
+    /**
+     * Run beforeSendToStt hook. Returns null to drop the audio chunk.
+     * If no hook is defined, returns the audio unchanged.
+     * Fail-open: on exception, the original audio passes through.
+     */
+    runBeforeSendToStt(audio: Buffer, ctx: HookContext): Promise<Buffer | null>;
+    /**
+     * Run afterTranscribe hook. Returns null if hook vetoes the turn.
+     * If no hook is defined, returns the transcript unchanged.
+     */
+    runAfterTranscribe(transcript: string, ctx: HookContext): Promise<string | null>;
+    /**
+     * Run beforeSynthesize hook. Returns null if hook vetoes TTS for this sentence.
+     * If no hook is defined, returns the text unchanged.
+     */
+    runBeforeSynthesize(text: string, ctx: HookContext): Promise<string | null>;
+    /**
+     * Run afterSynthesize hook. Returns null if hook vetoes this audio chunk.
+     * If no hook is defined, returns the audio unchanged.
+     */
+    runAfterSynthesize(audio: Buffer, text: string, ctx: HookContext): Promise<Buffer | null>;
+}
+
+/**
+ * Built-in text transforms for cleaning LLM output before TTS synthesis.
+ *
+ * These functions strip markdown formatting and emoji characters so that TTS
+ * engines produce natural-sounding speech rather than reading aloud syntax
+ * like "asterisk asterisk bold asterisk asterisk" or Unicode pictographs.
+ */
+/**
+ * Remove markdown formatting from text, preserving the readable content.
+ *
+ * Handles: headers, bold, italic, code blocks/inline, links, images,
+ * strikethrough, list markers, block quotes, horizontal rules, HTML tags.
+ */
+declare function filterMarkdown(text: string): string;
+/**
+ * Remove emoji characters from text, preserving normal text, punctuation,
+ * and non-emoji Unicode (CJK, accented characters, etc.).
+ */
+declare function filterEmoji(text: string): string;
+/**
+ * Combined filter: strip markdown formatting and emoji from text.
+ *
+ * Intended as a convenience for the most common TTS pre-processing use case.
+ */
+declare function filterForTTS(text: string): string;
+
 declare class PatterError extends Error {
     constructor(message: string);
 }
@@ -371,10 +572,19 @@ interface CallMetrics {
     telephony_provider: string;
 }
 interface CallControl {
-    /** Transfer the call to a different number. */
+    /** Transfer the call to a different number or SIP URI. */
     transfer(number: string): Promise<void>;
     /** Hang up the call. */
     hangup(): Promise<void>;
+    /**
+     * Send DTMF digits (for IVR navigation, e.g. "1234#").
+     *
+     * @param digits  String of DTMF digits (0-9, *, #, A-D).
+     * @param options Per-call tuning. `delayMs` defaults to `300`.
+     */
+    sendDtmf?(digits: string, options?: {
+        delayMs?: number;
+    }): Promise<void>;
     /** Current call ID. */
     readonly callId: string;
     /** Caller number. */
@@ -417,6 +627,8 @@ declare class CallMetricsAccumulator {
     });
     /** Configure audio format for STT byte-to-seconds conversion. */
     configureSttFormat(sampleRate?: number, bytesPerSample?: number): void;
+    /** Whether a turn is currently being measured (startTurn called, not yet completed). */
+    get turnActive(): boolean;
     startTurn(): void;
     recordSttComplete(text: string, audioSeconds?: number): void;
     recordLlmComplete(): void;
@@ -460,7 +672,7 @@ declare class OpenAIRealtimeAdapter {
     }> | undefined);
     connect(): Promise<void>;
     sendAudio(mulawAudio: Buffer): void;
-    onEvent(callback: (type: string, data: unknown) => void): void;
+    onEvent(callback: (type: string, data: unknown) => void | Promise<void>): void;
     cancelResponse(): void;
     sendText(text: string): Promise<void>;
     sendFunctionResult(callId: string, result: string): Promise<void>;
@@ -477,27 +689,116 @@ declare class ElevenLabsConvAIAdapter {
     constructor(apiKey: string, agentId?: string, voiceId?: string, _modelId?: string, _language?: string, firstMessage?: string);
     connect(): Promise<void>;
     sendAudio(audioBytes: Buffer): void;
-    onEvent(callback: (type: string, data: unknown) => void): void;
+    onEvent(callback: (type: string, data: unknown) => void | Promise<void>): void;
     close(): void;
 }
 
-interface LocalConfig {
-    twilioSid?: string;
-    twilioToken?: string;
-    openaiKey?: string;
-    phoneNumber: string;
-    webhookUrl: string;
-    telephonyProvider?: 'twilio' | 'telnyx';
-    telnyxKey?: string;
-    telnyxConnectionId?: string;
+interface Transcript$4 {
+    readonly text: string;
+    readonly isFinal: boolean;
+    readonly confidence: number;
+}
+type TranscriptCallback$4 = (transcript: Transcript$4) => void;
+declare class DeepgramSTT {
+    private readonly apiKey;
+    private readonly language;
+    private readonly model;
+    private readonly encoding;
+    private readonly sampleRate;
+    private ws;
+    private callbacks;
+    /** Request ID from Deepgram — used to query actual cost post-call. */
+    requestId: string;
+    constructor(apiKey: string, language?: string, model?: string, encoding?: string, sampleRate?: number);
+    /** Factory for Twilio calls — mulaw 8 kHz. */
+    static forTwilio(apiKey: string, language?: string, model?: string): DeepgramSTT;
+    connect(): Promise<void>;
+    sendAudio(audio: Buffer): void;
+    onTranscript(callback: TranscriptCallback$4): void;
+    close(): void;
+}
+
+/**
+ * OpenAI Whisper STT adapter for the Patter SDK pipeline mode.
+ *
+ * Buffers incoming PCM16 audio and periodically sends it to the
+ * OpenAI Whisper transcription API as a WAV file.
+ */
+interface Transcript$3 {
+    readonly text: string;
+    readonly isFinal: boolean;
+    readonly confidence: number;
+}
+type TranscriptCallback$3 = (transcript: Transcript$3) => void;
+declare class WhisperSTT {
+    private readonly apiKey;
+    private readonly model;
+    private readonly language;
+    private readonly bufferSize;
+    private buffer;
+    private callbacks;
+    private running;
+    private pendingTranscriptions;
+    constructor(apiKey: string, model?: string, language?: string, bufferSize?: number);
+    /** 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;
+    connect(): Promise<void>;
+    sendAudio(audio: Buffer): void;
+    private trackTranscription;
+    onTranscript(callback: TranscriptCallback$3): void;
+    close(): Promise<void>;
+    private transcribeBuffer;
+}
+
+/**
+ * Remote message handler for B2B webhook and WebSocket integration.
+ *
+ * Allows onMessage to be a URL string instead of a callable:
+ * - HTTP webhook: onMessage="https://api.customer.com/patter/message"
+ * - WebSocket: onMessage="ws://localhost:9000/stream"
+ */
+declare class RemoteMessageHandler {
+    private readonly webhookSecret;
     /**
-     * Telnyx Ed25519 public key (base64-encoded, DER/SPKI format) used to verify
-     * incoming webhook signatures. Obtain from the Telnyx portal under
-     * API Keys → Webhook Keys. When provided, unauthenticated webhook requests
-     * are rejected with HTTP 403.
+     * @param webhookSecret Optional HMAC secret. When provided, outgoing webhook
+     *   requests include an `X-Patter-Signature` header so the receiver can
+     *   verify the payload originated from Patter.
      */
-    telnyxPublicKey?: string;
+    constructor(webhookSecret?: string);
+    /**
+     * Compute HMAC-SHA256 hex digest for the given body.
+     */
+    private signPayload;
+    /**
+     * Release resources held by this handler.
+     */
+    close(): void;
+    /**
+     * POST transcript to HTTP webhook, return response text.
+     *
+     * The webhook receives a JSON payload:
+     *   { text, call_id, caller, callee, history }
+     *
+     * The response can be plain text or JSON { text: "..." }.
+     *
+     * When `webhookSecret` was provided at construction time, the request
+     * includes an `X-Patter-Signature` header with the HMAC-SHA256 hex
+     * digest of the JSON body.
+     */
+    callWebhook(url: string, data: Record<string, unknown>): Promise<string>;
+    /**
+     * Send transcript via WebSocket, yield response chunks.
+     *
+     * Sends the message data as JSON. Receives one or more JSON frames
+     * with { text: "..." } - multiple frames enable streaming.
+     * A frame with { done: true } signals end of response.
+     */
+    callWebSocket(url: string, data: Record<string, unknown>): AsyncGenerator<string, void, unknown>;
 }
+/** Check if onMessage is a remote URL string. */
+declare function isRemoteUrl(onMessage: unknown): onMessage is string;
+/** Check if a URL is a WebSocket URL. */
+declare function isWebSocketUrl(url: string): boolean;
 
 /**
  * In-memory metrics store for the local dashboard.
@@ -543,6 +844,24 @@ declare class MetricsStore extends EventEmitter {
     get callCount(): number;
 }
 
+interface LocalConfig {
+    twilioSid?: string;
+    twilioToken?: string;
+    openaiKey?: string;
+    phoneNumber: string;
+    webhookUrl: string;
+    telephonyProvider?: 'twilio' | 'telnyx';
+    telnyxKey?: string;
+    telnyxConnectionId?: string;
+    /**
+     * Telnyx Ed25519 public key (base64-encoded, DER/SPKI format) used to verify
+     * incoming webhook signatures. Obtain from the Telnyx portal under
+     * API Keys → Webhook Keys. When provided, unauthenticated webhook requests
+     * are rejected with HTTP 403.
+     */
+    telnyxPublicKey?: string;
+}
+
 /**
  * Dashboard authentication middleware for Express.
  *
@@ -592,6 +911,15 @@ declare function callsToJson(calls: CallRecord[]): string;
 declare function mountDashboard(app: Express, store: MetricsStore, token?: string): void;
 declare function mountApi(app: Express, store: MetricsStore, token?: string): void;
 
+/**
+ * Dashboard notification for live call updates.
+ *
+ * When the SDK completes a call, it fires a POST to the standalone dashboard
+ * (if running) so calls appear in real time.  Data lives only in memory —
+ * nothing is written to disk.
+ */
+declare function notifyDashboard(callData: Record<string, unknown>, port?: number): void;
+
 /**
  * Built-in LLM loop for pipeline mode when no onMessage handler is provided.
  *
@@ -648,54 +976,45 @@ declare class LLMLoop {
 }
 
 /**
- * Remote message handler for B2B webhook and WebSocket integration.
+ * Fallback LLM provider that tries multiple providers in sequence.
  *
- * Allows onMessage to be a URL string instead of a callable:
- * - HTTP webhook: onMessage="https://api.customer.com/patter/message"
- * - WebSocket: onMessage="ws://localhost:9000/stream"
+ * If the primary provider fails, the next provider is tried, and so on.
+ * Each provider gets a configurable number of retries before being skipped.
+ * Failed providers are marked unavailable and periodically re-checked in the
+ * background.
  */
-declare class RemoteMessageHandler {
-    private readonly webhookSecret;
-    /**
-     * @param webhookSecret Optional HMAC secret. When provided, outgoing webhook
-     *   requests include an `X-Patter-Signature` header so the receiver can
-     *   verify the payload originated from Patter.
-     */
-    constructor(webhookSecret?: string);
-    /**
-     * Compute HMAC-SHA256 hex digest for the given body.
-     */
-    private signPayload;
-    /**
-     * Release resources held by this handler.
-     */
-    close(): void;
-    /**
-     * POST transcript to HTTP webhook, return response text.
-     *
-     * The webhook receives a JSON payload:
-     *   { text, call_id, caller, callee, history }
-     *
-     * The response can be plain text or JSON { text: "..." }.
-     *
-     * When `webhookSecret` was provided at construction time, the request
-     * includes an `X-Patter-Signature` header with the HMAC-SHA256 hex
-     * digest of the JSON body.
-     */
-    callWebhook(url: string, data: Record<string, unknown>): Promise<string>;
-    /**
-     * Send transcript via WebSocket, yield response chunks.
-     *
-     * Sends the message data as JSON. Receives one or more JSON frames
-     * with { text: "..." } - multiple frames enable streaming.
-     * A frame with { done: true } signals end of response.
-     */
-    callWebSocket(url: string, data: Record<string, unknown>): AsyncGenerator<string, void, unknown>;
+
+interface FallbackLLMProviderOptions {
+    /** Number of retry attempts per provider before moving to the next (default 1). */
+    readonly maxRetryPerProvider?: number;
+    /** Interval in ms between background recovery probes (default 30_000). */
+    readonly recoveryIntervalMs?: number;
+}
+/** Thrown when all providers have been exhausted. */
+declare class AllProvidersFailedError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a provider fails after already yielding partial output. */
+declare class PartialStreamError extends Error {
+    constructor(message: string);
+}
+declare class FallbackLLMProvider implements LLMProvider {
+    private readonly providers;
+    private readonly availability;
+    private readonly maxRetryPerProvider;
+    private readonly recoveryIntervalMs;
+    private readonly recoveryTimers;
+    constructor(providers: ReadonlyArray<LLMProvider>, options?: FallbackLLMProviderOptions);
+    /** Returns a snapshot of per-provider availability. */
+    getAvailability(): ReadonlyArray<boolean>;
+    /** Clears all background recovery timers. Call this when shutting down. */
+    destroy(): void;
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+    private tryProviders;
+    private markUnavailable;
+    private startRecovery;
+    private stopRecovery;
 }
-/** Check if onMessage is a remote URL string. */
-declare function isRemoteUrl(onMessage: unknown): onMessage is string;
-/** Check if a URL is a WebSocket URL. */
-declare function isWebSocketUrl(url: string): boolean;
 
 /**
  * Interactive terminal test mode for voice agents.
@@ -714,36 +1033,286 @@ declare class TestSession {
     }): Promise<void>;
 }
 
-interface Transcript$1 {
+/**
+ * Gemini Live realtime adapter.
+ *
+ * Partially adapted (~65% port) from LiveKit Agents
+ * (livekit-plugins-google, Apache 2.0). Reframed to Patter's realtime adapter
+ * surface — connect / sendAudio / onEvent / close — matching OpenAIRealtimeAdapter.
+ *
+ * Uses the @google/genai SDK lazily imported at connect() so consumers that do
+ * not use Gemini Live do not pay the load cost. Install with:
+ *
+ *    npm install @google/genai
+ */
+declare const GEMINI_DEFAULT_INPUT_SR = 16000;
+declare const GEMINI_DEFAULT_OUTPUT_SR = 24000;
+type GeminiLiveEventHandler = (type: 'audio' | 'transcript_output' | 'function_call' | 'speech_started' | 'response_done' | 'error', data: unknown) => void | Promise<void>;
+interface GeminiLiveOptions {
+    model?: string;
+    voice?: string;
+    instructions?: string;
+    language?: string;
+    tools?: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
+    inputSampleRate?: number;
+    outputSampleRate?: number;
+    temperature?: number;
+}
+declare class GeminiLiveAdapter {
+    private readonly apiKey;
+    private readonly model;
+    private readonly voice;
+    private readonly instructions;
+    private readonly language;
+    private readonly tools?;
+    private readonly inputSampleRate;
+    /** Output sample rate — exposed so callers can configure downstream transcoding. */
+    readonly outputSampleRate: number;
+    private readonly temperature;
+    private client;
+    private session;
+    private receiveLoop;
+    private handlers;
+    private running;
+    constructor(apiKey: string, options?: GeminiLiveOptions);
+    connect(): Promise<void>;
+    sendAudio(pcm: Buffer): void;
+    sendText(text: string): Promise<void>;
+    sendFunctionResult(callId: string, result: string): Promise<void>;
+    cancelResponse(): void;
+    onEvent(handler: GeminiLiveEventHandler): void;
+    private emit;
+    private pumpReceive;
+    close(): Promise<void>;
+}
+
+/**
+ * Ultravox realtime adapter.
+ *
+ * Partially adapted (~70% port) from LiveKit Agents
+ * (livekit-plugins-ultravox, Apache 2.0). Pure WebSocket protocol — no vendor SDK.
+ *
+ * Reframed to Patter's connect / sendAudio / onEvent / close surface,
+ * matching OpenAIRealtimeAdapter.
+ */
+declare const ULTRAVOX_DEFAULT_API_BASE = "https://api.ultravox.ai/api";
+declare const ULTRAVOX_DEFAULT_SR = 16000;
+type UltravoxEventHandler = (type: 'audio' | 'transcript_input' | 'transcript_output' | 'function_call' | 'speech_started' | 'response_done' | 'error', data: unknown) => void | Promise<void>;
+interface UltravoxOptions {
+    model?: string;
+    voice?: string;
+    instructions?: string;
+    language?: string;
+    tools?: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
+    apiBase?: string;
+    sampleRate?: number;
+    firstMessage?: string;
+}
+declare class UltravoxRealtimeAdapter {
+    private readonly apiKey;
+    private readonly model;
+    private readonly voice;
+    private readonly instructions;
+    private readonly language;
+    private readonly tools?;
+    private readonly apiBase;
+    private readonly sampleRate;
+    private readonly firstMessage;
+    private ws;
+    private handlers;
+    /** Exposed for diagnostics — true while the underlying socket is open. */
+    running: boolean;
+    constructor(apiKey: string, options?: UltravoxOptions);
+    connect(): Promise<void>;
+    sendAudio(pcm: Buffer): void;
+    sendText(text: string): Promise<void>;
+    sendFunctionResult(callId: string, result: string): Promise<void>;
+    cancelResponse(): void;
+    onEvent(handler: UltravoxEventHandler): void;
+    private emit;
+    private handleMessage;
+    close(): Promise<void>;
+}
+
+/**
+ * Thin scheduling wrapper around node-cron (MIT).
+ *
+ *    import { scheduleCron, scheduleOnce } from 'getpatter';
+ *
+ *    const handle = scheduleCron('* /5 * * * *', async () => doWork());
+ *    handle.cancel();
+ *
+ * node-cron is an optional dependency. This module imports it lazily so that
+ * consumers who never schedule anything do not need it installed.
+ */
+type JobCallback = () => void | Promise<void>;
+interface ScheduleHandle {
+    readonly jobId: string;
+    cancel(): void;
+    readonly pending: boolean;
+}
+/** Schedule ``callback`` on a cron expression (node-cron dialect). */
+declare function scheduleCron(cron: string, callback: JobCallback): Promise<ScheduleHandle>;
+/** Schedule ``callback`` once at the given date. */
+declare function scheduleOnce(at: Date, callback: JobCallback): ScheduleHandle;
+/** Schedule ``callback`` every ``intervalMs`` milliseconds. */
+declare function scheduleInterval(intervalMs: number, callback: JobCallback): ScheduleHandle;
+
+/**
+ * Soniox Speech-to-Text adapter for Patter (TypeScript).
+ *
+ * Pure WebSocket client for the Soniox real-time STT API. Accumulates
+ * `is_final` tokens and flushes them on `<end>`/`<fin>` endpoint tokens,
+ * mirroring the Python `SonioxSTT` adapter.
+ *
+ * Adapted from LiveKit Agents (Apache 2.0):
+ * https://github.com/livekit/agents
+ * (source: livekit-plugins/livekit-plugins-soniox/livekit/plugins/soniox/stt.py
+ *  at commit 78a66bcf79c5cea82989401c408f1dff4b961a5b)
+ *
+ * Speechmatics TypeScript adapter is **intentionally not ported**: the
+ * official Speechmatics Voice SDK (`speechmatics.voice`) is Python-only at
+ * the time of writing. Python users should install the optional
+ * `speechmatics` extra; TypeScript users need to wait for an official
+ * upstream SDK before this adapter can land without a WS-handshake reimpl.
+ */
+interface Transcript$2 {
     readonly text: string;
     readonly isFinal: boolean;
     readonly confidence: number;
 }
-type TranscriptCallback$1 = (transcript: Transcript$1) => void;
-declare class DeepgramSTT {
+type TranscriptCallback$2 = (transcript: Transcript$2) => void;
+interface SonioxSTTOptions {
+    model?: string;
+    languageHints?: string[];
+    languageHintsStrict?: boolean;
+    sampleRate?: number;
+    numChannels?: number;
+    enableSpeakerDiarization?: boolean;
+    enableLanguageIdentification?: boolean;
+    maxEndpointDelayMs?: number;
+    clientReferenceId?: string;
+    baseUrl?: string;
+}
+declare class SonioxSTT {
+    private ws;
+    private callbacks;
+    private final;
+    private keepaliveTimer;
     private readonly apiKey;
-    private readonly language;
     private readonly model;
-    private readonly encoding;
+    private readonly languageHints?;
+    private readonly languageHintsStrict;
     private readonly sampleRate;
+    private readonly numChannels;
+    private readonly enableSpeakerDiarization;
+    private readonly enableLanguageIdentification;
+    private readonly maxEndpointDelayMs;
+    private readonly clientReferenceId?;
+    private readonly baseUrl;
+    constructor(apiKey: string, options?: SonioxSTTOptions);
+    /** Factory for Twilio-style 8 kHz linear PCM. */
+    static forTwilio(apiKey: string, languageHints?: string[]): SonioxSTT;
+    private buildConfig;
+    connect(): Promise<void>;
+    private clearKeepalive;
+    private handleMessage;
+    private emit;
+    sendAudio(audio: Buffer): void;
+    onTranscript(callback: TranscriptCallback$2): void;
+    close(): void;
+}
+
+/**
+ * AssemblyAI Universal Streaming STT adapter for the Patter SDK pipeline mode.
+ *
+ * Implements a `DeepgramSTT`-shaped provider using AssemblyAI's v3 streaming
+ * WebSocket API. Pure `ws` transport — does NOT depend on the vendor SDK.
+ *
+ * Algorithm adapted from LiveKit Agents (Apache 2.0):
+ * https://github.com/livekit/agents
+ * Source: livekit-plugins/livekit-plugins-assemblyai/livekit/plugins/assemblyai/stt.py
+ * Upstream ref SHA: 78a66bcf79c5cea82989401c408f1dff4b961a5b
+ */
+interface Transcript$1 {
+    readonly text: string;
+    readonly isFinal: boolean;
+    readonly confidence: number;
+}
+type TranscriptCallback$1 = (transcript: Transcript$1) => void;
+type AssemblyAIEncoding = 'pcm_s16le' | 'pcm_mulaw';
+type AssemblyAIModel = 'universal-streaming-english' | 'universal-streaming-multilingual' | 'u3-rt-pro';
+interface AssemblyAISTTOptions {
+    /** One of the AssemblyAI speech models. */
+    readonly model?: AssemblyAIModel;
+    /** PCM encoding: 16-bit little-endian (default) or G.711 mu-law for telephony. */
+    readonly encoding?: AssemblyAIEncoding;
+    /** Sample rate in Hz — 16000 for wideband audio, 8000 for telephony. */
+    readonly sampleRate?: number;
+    /** Override the streaming base URL (e.g. EU: `wss://streaming.eu.assemblyai.com`). */
+    readonly baseUrl?: string;
+    /** Enable automatic language detection (defaults: true for multilingual/u3-rt-pro). */
+    readonly languageDetection?: boolean;
+    /** 0..1 confidence required before end-of-turn is finalized. */
+    readonly endOfTurnConfidenceThreshold?: number;
+    /** Minimum ms of silence required before end-of-turn finalizes. */
+    readonly minTurnSilence?: number;
+    /** Maximum ms of silence before the turn is force-finalized. */
+    readonly maxTurnSilence?: number;
+    /** When true, wait for the formatted transcript before emitting final. */
+    readonly formatTurns?: boolean;
+    /** Bias keywords/phrases. */
+    readonly keytermsPrompt?: readonly string[];
+    /** Text prompt (u3-rt-pro only). */
+    readonly prompt?: string;
+    /** VAD threshold (0..1). */
+    readonly vadThreshold?: number;
+    /** Enable diarization / speaker labels. */
+    readonly speakerLabels?: boolean;
+    /** Max speakers for diarization. */
+    readonly maxSpeakers?: number;
+    /** Domain hint (e.g. "medical"). */
+    readonly domain?: string;
+}
+declare class AssemblyAISTT {
+    private readonly apiKey;
+    private readonly options;
     private ws;
     private callbacks;
-    /** Request ID from Deepgram — used to query actual cost post-call. */
-    requestId: string;
-    constructor(apiKey: string, language?: string, model?: string, encoding?: string, sampleRate?: number);
+    /** AssemblyAI session id — set when the `Begin` message arrives. */
+    sessionId: string;
+    /** Unix timestamp when the AssemblyAI session expires. */
+    expiresAt: number;
+    constructor(apiKey: string, options?: AssemblyAISTTOptions);
     /** Factory for Twilio calls — mulaw 8 kHz. */
-    static forTwilio(apiKey: string, language?: string, model?: string): DeepgramSTT;
+    static forTwilio(apiKey: string, model?: AssemblyAIModel): AssemblyAISTT;
+    private buildUrl;
     connect(): Promise<void>;
+    private handleEvent;
+    private emit;
     sendAudio(audio: Buffer): void;
     onTranscript(callback: TranscriptCallback$1): void;
     close(): void;
 }
 
 /**
- * OpenAI Whisper STT adapter for the Patter SDK pipeline mode.
+ * Cartesia STT (ink-whisper) adapter for the Patter SDK pipeline mode.
  *
- * Buffers incoming PCM16 audio and periodically sends it to the
- * OpenAI Whisper transcription API as a WAV file.
+ * Implements a `DeepgramSTT`-shaped provider using Cartesia's streaming
+ * WebSocket API. Pure `ws` transport — does NOT depend on the vendor SDK.
+ *
+ * Algorithm adapted from LiveKit Agents (Apache 2.0):
+ * https://github.com/livekit/agents
+ * Source: livekit-plugins/livekit-plugins-cartesia/livekit/plugins/cartesia/stt.py
+ * Upstream ref SHA: 78a66bcf79c5cea82989401c408f1dff4b961a5b
  */
 interface Transcript {
     readonly text: string;
@@ -751,22 +1320,36 @@ interface Transcript {
     readonly confidence: number;
 }
 type TranscriptCallback = (transcript: Transcript) => void;
-declare class WhisperSTT {
+/** Cartesia STT currently only accepts 16-bit PCM little-endian. */
+type CartesiaEncoding = 'pcm_s16le';
+interface CartesiaSTTOptions {
+    /** Cartesia STT model. Currently only `"ink-whisper"`. */
+    readonly model?: string;
+    /** BCP-47 language code. */
+    readonly language?: string;
+    /** PCM encoding; Cartesia only supports `pcm_s16le`. */
+    readonly encoding?: CartesiaEncoding;
+    /** Sample rate in Hz. Cartesia accepts 8000, 16000, 24000, 44100, 48000. */
+    readonly sampleRate?: number;
+    /** Override base URL (HTTP or WS). Defaults to Cartesia prod. */
+    readonly baseUrl?: string;
+}
+declare class CartesiaSTT {
     private readonly apiKey;
-    private readonly model;
-    private readonly language;
-    private readonly bufferSize;
-    private buffer;
+    private readonly options;
+    private ws;
     private callbacks;
-    private running;
-    constructor(apiKey: string, model?: string, language?: string, bufferSize?: number);
-    /** 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;
+    private keepaliveTimer;
+    /** Cartesia request id — set from the server transcript events. */
+    requestId: string;
+    constructor(apiKey: string, options?: CartesiaSTTOptions);
+    private buildWsUrl;
     connect(): Promise<void>;
+    private handleEvent;
+    private emit;
     sendAudio(audio: Buffer): void;
     onTranscript(callback: TranscriptCallback): void;
     close(): void;
-    private transcribeBuffer;
 }
 
 declare class ElevenLabsTTS {
@@ -818,6 +1401,111 @@ declare class OpenAITTS {
     static resample24kTo16k(audio: Buffer): Buffer;
 }
 
+interface CartesiaTTSOptions {
+    model?: string;
+    voice?: string;
+    language?: string;
+    sampleRate?: number;
+    speed?: string | number;
+    emotion?: string | string[];
+    volume?: number;
+    baseUrl?: string;
+    apiVersion?: string;
+}
+declare class CartesiaTTS {
+    private readonly apiKey;
+    private readonly model;
+    private readonly voice;
+    private readonly language;
+    private readonly sampleRate;
+    private readonly speed?;
+    private readonly emotion?;
+    private readonly volume?;
+    private readonly baseUrl;
+    private readonly apiVersion;
+    constructor(apiKey: string, opts?: CartesiaTTSOptions);
+    /** Build the JSON payload for the Cartesia bytes endpoint. */
+    private buildPayload;
+    /** Synthesize text and return the concatenated audio buffer. */
+    synthesize(text: string): Promise<Buffer>;
+    /**
+     * Synthesize text and yield raw PCM_S16LE chunks at the configured
+     * `sampleRate` as they arrive from Cartesia.
+     */
+    synthesizeStream(text: string): AsyncGenerator<Buffer>;
+}
+
+interface RimeTTSOptions {
+    model?: string;
+    speaker?: string;
+    lang?: string;
+    sampleRate?: number;
+    repetitionPenalty?: number;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    speedAlpha?: number;
+    reduceLatency?: boolean;
+    pauseBetweenBrackets?: boolean;
+    phonemizeBetweenBrackets?: boolean;
+    baseUrl?: string;
+}
+declare class RimeTTS {
+    private readonly apiKey;
+    private readonly model;
+    private readonly speaker;
+    private readonly lang;
+    private readonly sampleRate;
+    private readonly repetitionPenalty?;
+    private readonly temperature?;
+    private readonly topP?;
+    private readonly maxTokens?;
+    private readonly speedAlpha?;
+    private readonly reduceLatency?;
+    private readonly pauseBetweenBrackets?;
+    private readonly phonemizeBetweenBrackets?;
+    private readonly baseUrl;
+    private readonly totalTimeoutMs;
+    constructor(apiKey: string, opts?: RimeTTSOptions);
+    private buildPayload;
+    synthesize(text: string): Promise<Buffer>;
+    /**
+     * Synthesize text and yield raw PCM_S16LE chunks at the configured
+     * `sampleRate` as they stream in.
+     */
+    synthesizeStream(text: string): AsyncGenerator<Buffer>;
+}
+
+type LMNTAudioFormat = 'aac' | 'mp3' | 'mulaw' | 'raw' | 'wav';
+type LMNTModel = 'blizzard' | 'aurora';
+type LMNTSampleRate = 8000 | 16000 | 24000;
+interface LMNTTTSOptions {
+    model?: LMNTModel;
+    voice?: string;
+    language?: string;
+    format?: LMNTAudioFormat;
+    sampleRate?: LMNTSampleRate;
+    temperature?: number;
+    topP?: number;
+    baseUrl?: string;
+}
+declare class LMNTTTS {
+    private readonly apiKey;
+    private readonly model;
+    private readonly voice;
+    private readonly language;
+    private readonly format;
+    private readonly sampleRate;
+    private readonly temperature;
+    private readonly topP;
+    private readonly baseUrl;
+    constructor(apiKey: string, opts?: LMNTTTSOptions);
+    private buildPayload;
+    synthesize(text: string): Promise<Buffer>;
+    /** Yield audio chunks as they arrive — raw PCM_S16LE by default. */
+    synthesizeStream(text: string): AsyncGenerator<Buffer>;
+}
+
 /**
  * Audio transcoding utilities for Patter TypeScript SDK.
  *
@@ -889,4 +1577,294 @@ interface TunnelHandle {
  */
 declare function startTunnel(port: number, timeoutMs?: number): Promise<TunnelHandle>;
 
-export { type Agent, type AgentOptions, AuthenticationError, type Call, type CallControl, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOptions, type CallRecord, type ConnectOptions, type CostBreakdown, type CreateAgentOptions, DEFAULT_PRICING, DeepgramSTT, ElevenLabsConvAIAdapter, ElevenLabsTTS, type Guardrail, type IncomingMessage, type LLMChunk, LLMLoop, type LLMProvider, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type MessageHandler, MetricsStore, OpenAILLMProvider, OpenAIRealtimeAdapter, OpenAITTS, Patter, PatterConnectionError, PatterError, type PatterOptions, type PhoneNumber, type PipelineMessageHandler, type ProviderPricing, ProvisionError, RemoteMessageHandler, type SSEEvent, type STTConfig, type ServeOptions, type TTSConfig, TestSession, type ToolDefinition, type TunnelHandle, type TurnMetrics, WhisperSTT, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, deepgram, elevenlabs, getLogger, isRemoteUrl, isWebSocketUrl, makeAuthMiddleware, mergePricing, mountApi, mountDashboard, mulawToPcm16, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, setLogger, startTunnel, whisper };
+/**
+ * Typed conversation history management with truncation support.
+ *
+ * Replaces raw `list[dict]` history with a structured ChatContext class
+ * that provides immutable messages, automatic ID generation, truncation
+ * preserving system prompts, and format conversion for OpenAI / Anthropic.
+ */
+type ChatRole = "system" | "user" | "assistant" | "tool";
+interface ChatMessage {
+    readonly id: string;
+    readonly role: ChatRole;
+    readonly content: string;
+    readonly timestamp: number;
+    readonly name?: string;
+    readonly toolCallId?: string;
+}
+interface OpenAIMessage {
+    role: string;
+    content: string;
+    name?: string;
+    tool_call_id?: string;
+}
+interface AnthropicMessage {
+    role: string;
+    content: string;
+}
+interface AnthropicConversion {
+    system: string | undefined;
+    messages: ReadonlyArray<AnthropicMessage>;
+}
+interface ChatContextJSON {
+    messages: ReadonlyArray<ChatMessage>;
+}
+declare class ChatContext {
+    private items;
+    constructor(systemPrompt?: string);
+    addUser(content: string): ChatMessage;
+    addAssistant(content: string): ChatMessage;
+    addSystem(content: string): ChatMessage;
+    addToolResult(content: string, toolCallId: string): ChatMessage;
+    getMessages(): ReadonlyArray<ChatMessage>;
+    getLastN(n: number): ReadonlyArray<ChatMessage>;
+    get length(): number;
+    /**
+     * Keep the first system message (if any) plus the last `maxMessages`
+     * non-system-first messages. When no system message exists at index 0,
+     * simply keeps the last `maxMessages` messages.
+     */
+    truncate(maxMessages: number): void;
+    toOpenAI(): OpenAIMessage[];
+    /**
+     * Convert to Anthropic format. The first system message (if present)
+     * is extracted into a separate `system` field, and only user/assistant
+     * messages are included in the messages array.
+     */
+    toAnthropic(): AnthropicConversion;
+    copy(): ChatContext;
+    toJSON(): ChatContextJSON;
+    static fromJSON(data: ChatContextJSON): ChatContext;
+}
+
+/**
+ * IVR auto-navigation activity for telephony calls (TypeScript port).
+ *
+ * Detects IVR prompts via transcribed speech, forwards DTMF responses
+ * through `CallControl.sendDtmf`, and recovers from two common failure
+ * modes:
+ *
+ * 1. The agent hears the same IVR prompt repeated several times
+ *    (loop detection). `TfidfLoopDetector` flags this by comparing the
+ *    cosine similarity of recent transcript chunks.
+ * 2. The IVR falls silent while both parties are passive (silence
+ *    detection). A debounced timer triggers a follow-up after
+ *    `maxSilenceDuration` seconds of combined silence.
+ *
+ * The Python port uses scikit-learn for TF-IDF; TypeScript has no
+ * equivalent battle-tested package in the std library, so we ship a
+ * minimal in-house bag-of-words + cosine-similarity implementation.
+ * It is intentionally simple — enough to match repeated IVR prompts.
+ *
+ * Algorithm adapted from LiveKit Agents (Apache 2.0):
+ * https://github.com/livekit/agents
+ *
+ * Source:
+ *  - livekit-agents/livekit/agents/voice/ivr/ivr_activity.py
+ *  - livekit-agents/livekit/agents/beta/tools/send_dtmf.py
+ * LiveKit SHA at port time: 78a66bcf79c5cea82989401c408f1dff4b961a5b
+ */
+
+/** Valid DTMF tone values (keypad characters). */
+declare const DTMF_EVENTS: readonly ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#", "A", "B", "C", "D"];
+type DtmfEvent = (typeof DTMF_EVENTS)[number];
+/** Join DTMF events into a space-separated debug string. */
+declare function formatDtmf(events: DtmfEvent[]): string;
+interface TfidfLoopDetectorOptions {
+    /** Number of recent chunks to keep in the comparison window. */
+    windowSize?: number;
+    /** Cosine similarity above which two chunks are "the same prompt". */
+    similarityThreshold?: number;
+    /** Consecutive near-duplicates required before firing. */
+    consecutiveThreshold?: number;
+}
+/**
+ * Detects repeated IVR prompts via cosine similarity on bag-of-words
+ * vectors. Not a full TF-IDF implementation — good enough for catching
+ * IVRs that re-read the same menu.
+ */
+declare class TfidfLoopDetector {
+    private readonly windowSize;
+    private readonly similarityThreshold;
+    private readonly consecutiveThreshold;
+    private chunks;
+    private consecutiveSimilar;
+    constructor(opts?: TfidfLoopDetectorOptions);
+    reset(): void;
+    addChunk(text: string): void;
+    checkLoopDetection(): boolean;
+}
+/** Async callback fired when the TF-IDF detector trips. */
+type LoopCallback = () => Promise<void> | void;
+/** Async callback fired after sustained silence. */
+type SilenceCallback = () => Promise<void> | void;
+interface IVRActivityOptions {
+    /** Seconds of combined silence before firing `onSilence`. Default `5.0`. */
+    maxSilenceDuration?: number;
+    /** Enable the TF-IDF loop detector. Default `true`. */
+    loopDetector?: boolean;
+    /** Fired when the loop detector trips. */
+    onLoopDetected?: LoopCallback;
+    /** Fired after `maxSilenceDuration` seconds of combined silence. */
+    onSilence?: SilenceCallback;
+}
+/** OpenAI-style function tool spec with attached handler. */
+interface IVRToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (args: {
+        events: string[];
+    }) => Promise<string>;
+}
+/**
+ * Coordinate IVR navigation heuristics for a single call.
+ *
+ * Usage::
+ *
+ *     const ivr = new IVRActivity(callControl);
+ *     await ivr.start();
+ *
+ *     // In the STT loop, on each final transcript:
+ *     await ivr.onUserTranscribed(text);
+ *
+ *     // When done:
+ *     await ivr.stop();
+ */
+declare class IVRActivity {
+    private readonly callControl;
+    private readonly maxSilenceDurationMs;
+    private readonly loopDetector;
+    private readonly onLoopDetected?;
+    private readonly onSilence?;
+    private currentUserState;
+    private currentAgentState;
+    private readonly debouncedSilence;
+    private lastShouldSchedule;
+    private started;
+    constructor(callControl: CallControl, opts?: IVRActivityOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onUserTranscribed(text: string): Promise<void>;
+    noteUserState(state: string): void;
+    noteAgentState(state: string): void;
+    get tools(): IVRToolDefinition[];
+    private scheduleSilenceCheck;
+    private shouldScheduleCheck;
+    private onSilenceDetected;
+    private buildSendDtmfTool;
+}
+
+declare const BuiltinAudioClip: {
+    readonly CITY_AMBIENCE: "city-ambience.ogg";
+    readonly FOREST_AMBIENCE: "forest-ambience.ogg";
+    readonly OFFICE_AMBIENCE: "office-ambience.ogg";
+    readonly CROWDED_ROOM: "crowded-room.ogg";
+    readonly KEYBOARD_TYPING: "keyboard-typing.ogg";
+    readonly KEYBOARD_TYPING2: "keyboard-typing2.ogg";
+    readonly HOLD_MUSIC: "hold_music.ogg";
+};
+type BuiltinAudioClipName = (typeof BuiltinAudioClip)[keyof typeof BuiltinAudioClip];
+/** Resolve a bundled clip name to its absolute path on disk. */
+declare function builtinClipPath(clip: BuiltinAudioClipName): string;
+/** Raw int16 mono LE PCM already decoded into memory. */
+interface RawPcmSource {
+    readonly kind: 'pcm';
+    readonly pcm: Buffer;
+    readonly sampleRate: number;
+    readonly volume?: number;
+    readonly probability?: number;
+}
+/** File on disk that a user-supplied decoder will turn into raw PCM. */
+interface FilePcmSource {
+    readonly kind: 'file';
+    readonly path: string;
+    readonly decode: (p: string) => Promise<{
+        pcm: Buffer;
+        sampleRate: number;
+    }>;
+    readonly volume?: number;
+    readonly probability?: number;
+}
+/** One of the bundled clips — requires a ``decode`` function at start() time. */
+interface BuiltinPcmSource {
+    readonly kind: 'builtin';
+    readonly clip: BuiltinAudioClipName;
+    readonly decode: (p: string) => Promise<{
+        pcm: Buffer;
+        sampleRate: number;
+    }>;
+    readonly volume?: number;
+    readonly probability?: number;
+}
+type AudioSource = RawPcmSource | FilePcmSource | BuiltinPcmSource;
+interface AudioConfig {
+    readonly source: AudioSource;
+    /** Probability weight used when ``BackgroundAudioPlayer`` receives a list. */
+    readonly probability?: number;
+    /** Master volume [0, 1] applied on top of the per-source ``volume``. */
+    readonly volume?: number;
+}
+interface BackgroundAudioOptions {
+    /** Overall mix ratio [0, 1].  Defaults to 0.1 (LiveKit's hold-music ratio). */
+    readonly volume?: number;
+    /** When true the source restarts on exhaustion. */
+    readonly loop?: boolean;
+}
+/**
+ * Return ``agent + bg * ratio`` as a new Buffer of the same length as
+ * ``agent``.  Background is zero-padded or truncated to match.
+ */
+declare function mixPcm(agent: Buffer, bg: Buffer, ratio: number): Buffer;
+/**
+ * Linear-interpolation resample from ``srcSr`` to ``dstSr``.  Input and
+ * output are mono int16 LE PCM buffers.  Used for low-fidelity background
+ * audio (hold music at attenuated volume); not suitable for wideband
+ * program audio.
+ */
+declare function resamplePcm(src: Buffer, srcSr: number, dstSr: number): Buffer;
+declare function selectSoundFromList(sounds: readonly AudioConfig[]): AudioConfig | null;
+/**
+ * Mix a background audio clip into an outbound PCM stream.
+ *
+ * Accepts a single :class:`AudioSource`, a single :class:`AudioConfig`, or a
+ * list of :class:`AudioConfig` (in which case one is picked via
+ * probability-weighted random selection).  Call ``start()`` before any
+ * ``mix()`` and ``stop()`` to release decoded PCM.
+ */
+declare class BackgroundAudioPlayer implements BackgroundAudioPlayer$1 {
+    private readonly source;
+    private readonly volume;
+    private readonly loop;
+    private started;
+    private pcm;
+    private sourceSr;
+    private position;
+    private readonly resampleCache;
+    constructor(source: AudioSource | AudioConfig | readonly AudioConfig[], opts?: BackgroundAudioOptions);
+    /**
+     * Decode the configured source and arm the mixer.  Subsequent calls are
+     * no-ops while the player is active.
+     */
+    start(): Promise<void>;
+    /**
+     * Return a mix of ``agentPcm`` with the next background chunk.  The result
+     * is always exactly ``agentPcm.length`` bytes long.  Returns a copy of
+     * ``agentPcm`` when the player is not started, when ``volume == 0``, or
+     * when the source has been exhausted and ``loop`` is false.
+     */
+    mix(agentPcm: Buffer, sampleRate: number): Promise<Buffer>;
+    /** Release all cached PCM and reset the player. */
+    stop(): Promise<void>;
+    private resolveSource;
+    private decodeSource;
+    private applyGain;
+    private resampleTo;
+}
+
+export { type Agent, type AgentOptions, AllProvidersFailedError, type AnthropicConversion, type AnthropicMessage, type AssemblyAIEncoding, type AssemblyAIModel, AssemblyAISTT, type AssemblyAISTTOptions, type AudioConfig, type AudioSource, AuthenticationError, type BackgroundAudioOptions, BackgroundAudioPlayer, BuiltinAudioClip, type BuiltinAudioClipName, type BuiltinPcmSource, type Call, type CallControl, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOptions, type CallRecord, type CartesiaEncoding, CartesiaSTT, type CartesiaSTTOptions, CartesiaTTS, type CartesiaTTSOptions, ChatContext, type ChatMessage, type ChatRole, type ConnectOptions, type CostBreakdown, type CreateAgentOptions, DEFAULT_MIN_SENTENCE_LEN, DEFAULT_PRICING, DTMF_EVENTS, DeepgramSTT, type DefineToolInput, type DtmfEvent, ElevenLabsConvAIAdapter, ElevenLabsTTS, FallbackLLMProvider, type FallbackLLMProviderOptions, type FilePcmSource, GEMINI_DEFAULT_INPUT_SR, GEMINI_DEFAULT_OUTPUT_SR, GeminiLiveAdapter, type GeminiLiveEventHandler, type Guardrail, type HookContext, IVRActivity, type IVRActivityOptions, type IVRToolDefinition, type IncomingMessage, type JobCallback, type LLMChunk, LLMLoop, type LLMProvider, type LMNTAudioFormat, type LMNTModel, type LMNTSampleRate, LMNTTTS, type LMNTTTSOptions, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type LoopCallback, type MessageHandler, MetricsStore, OpenAILLMProvider, type OpenAIMessage, OpenAIRealtimeAdapter, OpenAITTS, type ParamSpec, PartialStreamError, Patter, PatterConnectionError, PatterError, type PatterOptions, type PhoneNumber, PipelineHookExecutor, type PipelineHooks, type PipelineMessageHandler, type ProviderPricing, ProvisionError, type RawPcmSource, RemoteMessageHandler, RimeTTS, type RimeTTSOptions, type SSEEvent, type STTConfig, type ScheduleHandle, SentenceChunker, type ServeOptions, type SilenceCallback, SonioxSTT, type SonioxSTTOptions, type TTSConfig, TestSession, TfidfLoopDetector, type TfidfLoopDetectorOptions, type ToolDefinition, type TunnelHandle, type TurnMetrics, ULTRAVOX_DEFAULT_API_BASE, ULTRAVOX_DEFAULT_SR, type UltravoxEventHandler, UltravoxRealtimeAdapter, WhisperSTT, builtinClipPath, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, deepgram, defineTool, elevenlabs, filterEmoji, filterForTTS, filterMarkdown, formatDtmf, getLogger, isRemoteUrl, isWebSocketUrl, makeAuthMiddleware, mergePricing, mixPcm, mountApi, mountDashboard, mulawToPcm16, notifyDashboard, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, resamplePcm, scheduleCron, scheduleInterval, scheduleOnce, selectSoundFromList, setLogger, startTunnel, whisper };