getpatter 0.4.3 → 0.5.0

package/dist/index.mjs

@@ -10,18 +10,15 @@ import {
   DEFAULT_PRICING,
   DeepgramSTT,
   ElevenLabsConvAIAdapter,
-  ElevenLabsTTS,
   EmbeddedServer,
   LLMLoop,
   MetricsStore,
   OpenAILLMProvider,
   OpenAIRealtimeAdapter,
-  OpenAITTS,
   PipelineHookExecutor,
   RemoteMessageHandler,
   SentenceChunker,
   TestSession,
-  WhisperSTT,
   calculateRealtimeCost,
   calculateSttCost,
   calculateTelephonyCost,
@@ -39,7 +36,7 @@ import {
   resample16kTo8k,
   resample24kTo16k,
   resample8kTo16k
-} from "./chunk-35EVXMGB.mjs";
+} from "./chunk-757NVN4L.mjs";
 import {
   getLogger,
   setLogger
@@ -186,49 +183,86 @@ var PatterConnection = class {
   }
 };
 
-// src/providers.ts
-var STTConfigImpl = class {
-  provider;
+// src/engines/openai.ts
+var Realtime = class {
+  kind = "openai_realtime";
   apiKey;
-  language;
-  constructor(provider, apiKey, language = "en") {
-    this.provider = provider;
-    this.apiKey = apiKey;
-    this.language = language;
-  }
-  toDict() {
-    return { provider: this.provider, api_key: this.apiKey, language: this.language };
+  model;
+  voice;
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.OPENAI_API_KEY;
+    if (!key) {
+      throw new Error(
+        "OpenAI Realtime requires an apiKey. Pass { apiKey: 'sk-...' } or set OPENAI_API_KEY in the environment."
+      );
+    }
+    this.apiKey = key;
+    this.model = opts.model ?? "gpt-4o-mini-realtime-preview";
+    this.voice = opts.voice ?? "alloy";
   }
 };
-var TTSConfigImpl = class {
-  provider;
+
+// src/engines/elevenlabs.ts
+var ConvAI = class {
+  kind = "elevenlabs_convai";
   apiKey;
+  agentId;
   voice;
-  constructor(provider, apiKey, voice = "alloy") {
-    this.provider = provider;
-    this.apiKey = apiKey;
-    this.voice = voice;
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.ELEVENLABS_API_KEY;
+    const agent = opts.agentId ?? process.env.ELEVENLABS_AGENT_ID;
+    if (!key) {
+      throw new Error(
+        "ElevenLabs ConvAI requires an apiKey. Pass { apiKey: '...' } or set ELEVENLABS_API_KEY in the environment."
+      );
+    }
+    if (!agent) {
+      throw new Error(
+        "ElevenLabs ConvAI requires an agentId. Pass { agentId: 'agent_...' } or set ELEVENLABS_AGENT_ID in the environment."
+      );
+    }
+    this.apiKey = key;
+    this.agentId = agent;
+    this.voice = opts.voice;
   }
-  toDict() {
-    return { provider: this.provider, api_key: this.apiKey, voice: this.voice };
+};
+
+// src/tunnels/index.ts
+var CloudflareTunnel = class {
+  kind = "cloudflare";
+};
+var Static = class {
+  kind = "static";
+  hostname;
+  constructor(opts) {
+    if (!opts.hostname) {
+      throw new Error("Static tunnel requires a non-empty hostname.");
+    }
+    this.hostname = opts.hostname;
   }
 };
-function deepgram(opts) {
-  return new STTConfigImpl("deepgram", opts.apiKey, opts.language ?? "en");
-}
-function whisper(opts) {
-  return new STTConfigImpl("whisper", opts.apiKey, opts.language ?? "en");
-}
-function elevenlabs(opts) {
-  return new TTSConfigImpl("elevenlabs", opts.apiKey, opts.voice ?? "rachel");
-}
-function openaiTts(opts) {
-  return new TTSConfigImpl("openai", opts.apiKey, opts.voice ?? "alloy");
-}
 
 // src/client.ts
 var DEFAULT_BACKEND_URL2 = "wss://api.getpatter.com";
 var DEFAULT_REST_URL = "https://api.getpatter.com";
+function sttConfigToDict(cfg) {
+  const out = {
+    provider: cfg.provider,
+    api_key: cfg.apiKey,
+    language: cfg.language
+  };
+  if (cfg.options) out.options = { ...cfg.options };
+  return out;
+}
+function ttsConfigToDict(cfg) {
+  const out = {
+    provider: cfg.provider,
+    api_key: cfg.apiKey,
+    voice: cfg.voice
+  };
+  if (cfg.options) out.options = { ...cfg.options };
+  return out;
+}
 var Patter = class {
   apiKey;
   backendUrl;
@@ -239,20 +273,39 @@ var Patter = class {
   embeddedServer = null;
   tunnelHandle = null;
   constructor(options) {
-    if ("mode" in options && options.mode === "local") {
+    const hasCarrier = "carrier" in options && options.carrier !== void 0;
+    const isLocal = "mode" in options && options.mode === "local" || hasCarrier;
+    if (isLocal) {
       const local = options;
       if (!local.phoneNumber) {
         throw new Error("Local mode requires phoneNumber");
       }
-      if (!local.twilioSid && !local.telnyxKey) {
-        throw new Error("Local mode requires twilioSid or telnyxKey");
+      if (!local.carrier) {
+        throw new Error(
+          "Local mode requires a `carrier` instance. Pass `carrier: new Twilio({...})` or `carrier: new Telnyx({...})`."
+        );
       }
-      if (local.twilioSid && !local.twilioToken) {
-        throw new Error("twilioToken is required when using twilioSid");
+      const carrier = local.carrier;
+      const tunnel = local.tunnel;
+      let tunnelWebhookUrl;
+      if (tunnel instanceof Static) {
+        if (local.webhookUrl) {
+          throw new Error(
+            "Cannot use both `tunnel: new StaticTunnel(...)` and `webhookUrl`. Pick one."
+          );
+        }
+        tunnelWebhookUrl = tunnel.hostname;
       }
       this.mode = "local";
-      const normalizedLocal = local.webhookUrl ? { ...local, webhookUrl: local.webhookUrl.replace(/^https?:\/\//, "").replace(/\/$/, "") } : local;
-      this.localConfig = normalizedLocal;
+      const rawWebhook = tunnelWebhookUrl ?? local.webhookUrl;
+      const normalizedWebhook = rawWebhook ? rawWebhook.replace(/^https?:\/\//, "").replace(/\/$/, "") : void 0;
+      this.localConfig = {
+        carrier,
+        phoneNumber: local.phoneNumber,
+        webhookUrl: normalizedWebhook,
+        tunnel: local.tunnel,
+        openaiKey: local.openaiKey
+      };
       this.apiKey = "";
       this.backendUrl = DEFAULT_BACKEND_URL2;
       this.restUrl = DEFAULT_REST_URL;
@@ -269,25 +322,55 @@ var Patter = class {
   }
   // === Local mode ===
   agent(opts) {
-    if (opts.provider) {
+    let working = { ...opts };
+    if (opts.engine) {
+      if (opts.provider) {
+        throw new Error(
+          "Cannot pass both `engine:` and `provider:`. Use one (engine is preferred)."
+        );
+      }
+      const engine = opts.engine;
+      if (engine instanceof Realtime) {
+        working = {
+          ...working,
+          provider: "openai_realtime",
+          model: working.model ?? engine.model,
+          voice: working.voice ?? engine.voice
+        };
+        if (this.localConfig && !this.localConfig.openaiKey) {
+          this.localConfig = { ...this.localConfig, openaiKey: engine.apiKey };
+        }
+      } else if (engine instanceof ConvAI) {
+        working = {
+          ...working,
+          provider: "elevenlabs_convai",
+          voice: working.voice ?? engine.voice
+        };
+      } else {
+        throw new Error(
+          "Unknown engine. Expected OpenAIRealtime or ElevenLabsConvAI instance."
+        );
+      }
+    }
+    if (working.provider) {
       const valid = ["openai_realtime", "elevenlabs_convai", "pipeline"];
-      if (!valid.includes(opts.provider)) {
-        throw new Error(`provider must be one of: ${valid.join(", ")}. Got: '${opts.provider}'`);
+      if (!valid.includes(working.provider)) {
+        throw new Error(`provider must be one of: ${valid.join(", ")}. Got: '${working.provider}'`);
       }
     }
-    if (opts.tools) {
-      if (!Array.isArray(opts.tools)) {
+    if (working.tools) {
+      if (!Array.isArray(working.tools)) {
         throw new TypeError("tools must be an array");
       }
-      opts.tools.forEach((tool, i) => {
-        if (!tool.name) throw new Error(`tools[${i}] missing required 'name' field`);
-        if (!tool.webhookUrl && !tool.handler) throw new Error(`tools[${i}] requires either 'webhookUrl' or 'handler'`);
+      working.tools.forEach((tool2, i) => {
+        if (!tool2.name) throw new Error(`tools[${i}] missing required 'name' field`);
+        if (!tool2.webhookUrl && !tool2.handler) throw new Error(`tools[${i}] requires either 'webhookUrl' or 'handler'`);
       });
     }
-    if (opts.variables !== void 0 && (typeof opts.variables !== "object" || Array.isArray(opts.variables))) {
+    if (working.variables !== void 0 && (typeof working.variables !== "object" || Array.isArray(working.variables))) {
       throw new TypeError("variables must be an object");
     }
-    return { ...opts };
+    return working;
   }
   async serve(opts) {
     if (this.mode !== "local" || !this.localConfig) {
@@ -310,10 +393,14 @@ var Patter = class {
     }
     let webhookUrl = this.localConfig.webhookUrl ?? "";
     const port = opts.port ?? 8e3;
-    if (opts.tunnel && webhookUrl) {
+    const ctorTunnel = this.localConfig.tunnel;
+    const wantsCloudflaredFromServe = opts.tunnel === true;
+    const wantsCloudflaredFromCtor = ctorTunnel === true || ctorTunnel instanceof CloudflareTunnel;
+    const wantsCloudflared = wantsCloudflaredFromServe || wantsCloudflaredFromCtor;
+    if (wantsCloudflared && webhookUrl) {
       throw new Error("Cannot use both tunnel: true and webhookUrl. Pick one.");
     }
-    if (opts.tunnel) {
+    if (wantsCloudflared) {
       const { startTunnel: startTunnel2 } = await import("./tunnel-BL7A7GXW.mjs");
       this.tunnelHandle = await startTunnel2(port);
       webhookUrl = this.tunnelHandle.hostname;
@@ -323,17 +410,29 @@ var Patter = class {
         "No webhookUrl configured. Either:\n  - Pass webhookUrl in the Patter constructor\n  - Use tunnel: true in serve() to auto-create a tunnel"
       );
     }
+    const carrier = this.localConfig.carrier;
+    const telephonyProvider = carrier.kind === "twilio" ? "twilio" : "telnyx";
+    const { autoConfigureCarrier } = await import("./carrier-config-CPG5CROM.mjs");
+    await autoConfigureCarrier({
+      telephonyProvider,
+      twilioSid: carrier.kind === "twilio" ? carrier.accountSid : void 0,
+      twilioToken: carrier.kind === "twilio" ? carrier.authToken : void 0,
+      telnyxKey: carrier.kind === "telnyx" ? carrier.apiKey : void 0,
+      telnyxConnectionId: carrier.kind === "telnyx" ? carrier.connectionId : void 0,
+      phoneNumber: this.localConfig.phoneNumber,
+      webhookHost: webhookUrl
+    });
     this.embeddedServer = new EmbeddedServer(
       {
-        twilioSid: this.localConfig.twilioSid,
-        twilioToken: this.localConfig.twilioToken,
+        twilioSid: carrier.kind === "twilio" ? carrier.accountSid : void 0,
+        twilioToken: carrier.kind === "twilio" ? carrier.authToken : void 0,
         openaiKey: this.localConfig.openaiKey,
         phoneNumber: this.localConfig.phoneNumber,
         webhookUrl,
-        telephonyProvider: this.localConfig.telephonyProvider,
-        telnyxKey: this.localConfig.telnyxKey,
-        telnyxConnectionId: this.localConfig.telnyxConnectionId,
-        telnyxPublicKey: this.localConfig.telnyxPublicKey
+        telephonyProvider,
+        telnyxKey: carrier.kind === "telnyx" ? carrier.apiKey : void 0,
+        telnyxConnectionId: carrier.kind === "telnyx" ? carrier.connectionId : void 0,
+        telnyxPublicKey: carrier.kind === "telnyx" ? carrier.publicKey : void 0
       },
       opts.agent,
       opts.onCallStart,
@@ -353,7 +452,7 @@ var Patter = class {
     if (this.mode !== "local") {
       throw new Error("test() is only available in local mode");
     }
-    const { TestSession: TestSession2 } = await import("./test-mode-RH65MMSP.mjs");
+    const { TestSession: TestSession2 } = await import("./test-mode-YFOL2HYH.mjs");
     const session = new TestSession2();
     await session.run({
       agent: opts.agent,
@@ -394,32 +493,51 @@ var Patter = class {
       if (!this.localConfig) {
         throw new Error("local config missing");
       }
-      const { phoneNumber, webhookUrl, telephonyProvider } = this.localConfig;
-      if (telephonyProvider === "telnyx") {
-        const telnyxKey = this.localConfig.telnyxKey ?? "";
-        const connectionId = this.localConfig.telnyxConnectionId ?? "";
+      const { phoneNumber, webhookUrl, carrier } = this.localConfig;
+      if (carrier.kind === "telnyx") {
+        const telnyxKey = carrier.apiKey;
+        const connectionId = carrier.connectionId;
         const streamUrl = `wss://${webhookUrl}/ws/stream/${encodeURIComponent(localOpts.to)}?caller=${encodeURIComponent(phoneNumber)}&callee=${encodeURIComponent(localOpts.to)}`;
+        const telnyxPayload = {
+          connection_id: connectionId,
+          from: phoneNumber,
+          to: localOpts.to,
+          stream_url: streamUrl,
+          stream_track: "both_tracks"
+        };
+        if (localOpts.ringTimeout !== void 0) {
+          telnyxPayload.timeout_secs = Math.max(1, Math.floor(localOpts.ringTimeout));
+        }
         const response2 = await fetch("https://api.telnyx.com/v2/calls", {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
             Authorization: `Bearer ${telnyxKey}`
           },
-          body: JSON.stringify({
-            connection_id: connectionId,
-            from: phoneNumber,
-            to: localOpts.to,
-            stream_url: streamUrl,
-            stream_track: "both_tracks"
-          })
+          body: JSON.stringify(telnyxPayload)
         });
         if (!response2.ok) {
           throw new ProvisionError(`Failed to initiate Telnyx call: ${await response2.text()}`);
         }
+        if (this.embeddedServer) {
+          try {
+            const body = await response2.clone().json();
+            const callId = body.data?.call_control_id;
+            if (callId) {
+              this.embeddedServer.metricsStore.recordCallInitiated({
+                call_id: callId,
+                caller: phoneNumber,
+                callee: localOpts.to,
+                direction: "outbound"
+              });
+            }
+          } catch {
+          }
+        }
         return;
       }
-      const twilioSid = this.localConfig.twilioSid ?? "";
-      const twilioToken = this.localConfig.twilioToken ?? "";
+      const twilioSid = carrier.accountSid;
+      const twilioToken = carrier.authToken;
       const statusCallbackUrl = `https://${webhookUrl}/webhooks/twilio/status`;
       const url = `https://api.twilio.com/2010-04-01/Accounts/${twilioSid}/Calls.json`;
       const params = new URLSearchParams({
@@ -427,13 +545,19 @@ var Patter = class {
         From: phoneNumber,
         Url: `https://${webhookUrl}/webhooks/twilio/voice`,
         StatusCallback: statusCallbackUrl,
-        StatusCallbackMethod: "POST"
+        StatusCallbackMethod: "POST",
+        // Full lifecycle so the dashboard sees ringing/no-answer/busy/failed
+        // transitions even when media never arrives.
+        StatusCallbackEvent: "initiated ringing answered completed"
       });
       if (localOpts.machineDetection) {
         params.append("MachineDetection", "DetectMessageEnd");
         params.append("AsyncAmd", "true");
         params.append("AsyncAmdStatusCallback", `https://${webhookUrl}/webhooks/twilio/amd`);
       }
+      if (localOpts.ringTimeout !== void 0) {
+        params.append("Timeout", String(Math.max(1, Math.floor(localOpts.ringTimeout))));
+      }
       if (localOpts.voicemailMessage && this.embeddedServer) {
         this.embeddedServer.voicemailMessage = localOpts.voicemailMessage;
       }
@@ -448,6 +572,21 @@ var Patter = class {
       if (!response.ok) {
         throw new ProvisionError(`Failed to initiate call: ${await response.text()}`);
       }
+      if (this.embeddedServer) {
+        try {
+          const body = await response.clone().json();
+          const callSid = body.sid;
+          if (callSid) {
+            this.embeddedServer.metricsStore.recordCallInitiated({
+              call_id: callSid,
+              caller: phoneNumber,
+              callee: localOpts.to,
+              direction: "outbound"
+            });
+          }
+        } catch {
+        }
+      }
       return;
     }
     const cloudOpts = options;
@@ -530,61 +669,6 @@ var Patter = class {
     const data = await response.json();
     return data.map((c) => ({ id: c.id, direction: c.direction, caller: c.caller, callee: c.callee, startedAt: c.started_at, endedAt: c.ended_at, durationSeconds: c.duration_seconds, status: c.status, transcript: c.transcript }));
   }
-  // Provider helpers
-  static deepgram = deepgram;
-  static whisper = whisper;
-  static elevenlabs = elevenlabs;
-  static openaiTts = openaiTts;
-  static guardrail(opts) {
-    return {
-      name: opts.name,
-      blockedTerms: opts.blockedTerms,
-      check: opts.check,
-      replacement: opts.replacement ?? "I'm sorry, I can't respond to that."
-    };
-  }
-  /**
-   * Create a tool definition for use with `agent({ tools: [...] })`.
-   *
-   * Either `handler` (a function) or `webhookUrl` must be provided.
-   *
-   * @param opts.name - Tool name (visible to the LLM).
-   * @param opts.description - What the tool does (visible to the LLM).
-   * @param opts.parameters - JSON Schema for tool arguments.
-   * @param opts.handler - Async function called in-process when the LLM invokes the tool.
-   * @param opts.webhookUrl - URL to POST to when the LLM invokes the tool.
-   *
-   * @example
-   * ```ts
-   * phone.agent({
-   *   systemPrompt: 'You are a pizza bot.',
-   *   tools: [
-   *     Patter.tool({
-   *       name: 'check_menu',
-   *       description: 'Check available menu items',
-   *       handler: async (args) => JSON.stringify({ items: ['margherita'] }),
-   *     }),
-   *   ],
-   * });
-   * ```
-   */
-  static tool(opts) {
-    if (!opts.handler && !opts.webhookUrl) {
-      throw new Error("tool() requires either handler or webhookUrl");
-    }
-    const t = {
-      name: opts.name,
-      description: opts.description ?? "",
-      parameters: opts.parameters ?? { type: "object", properties: {} }
-    };
-    if (opts.handler) {
-      t.handler = opts.handler;
-    }
-    if (opts.webhookUrl) {
-      t.webhookUrl = opts.webhookUrl;
-    }
-    return t;
-  }
   // Internal
   async registerNumber(provider, providerKey, number, providerSecret, country = "US", stt, tts) {
     const credentials = { api_key: providerKey };
@@ -600,8 +684,8 @@ var Patter = class {
         provider,
         provider_credentials: credentials,
         country,
-        stt_config: stt?.toDict() ?? null,
-        tts_config: tts?.toDict() ?? null
+        stt_config: stt ? stt.toDict?.() ?? sttConfigToDict(stt) : null,
+        tts_config: tts ? tts.toDict?.() ?? ttsConfigToDict(tts) : null
       })
     });
     if (response.status === 409) return;
@@ -674,6 +758,62 @@ function filterForTTS(text) {
   return filterEmoji(filterMarkdown(text));
 }
 
+// src/providers.ts
+var STTConfigImpl = class {
+  provider;
+  apiKey;
+  language;
+  options;
+  constructor(provider, apiKey, language = "en", options) {
+    this.provider = provider;
+    this.apiKey = apiKey;
+    this.language = language;
+    if (options) this.options = options;
+  }
+  toDict() {
+    const out = {
+      provider: this.provider,
+      api_key: this.apiKey,
+      language: this.language
+    };
+    if (this.options) out.options = { ...this.options };
+    return out;
+  }
+};
+var TTSConfigImpl = class {
+  provider;
+  apiKey;
+  voice;
+  constructor(provider, apiKey, voice = "alloy") {
+    this.provider = provider;
+    this.apiKey = apiKey;
+    this.voice = voice;
+  }
+  toDict() {
+    return { provider: this.provider, api_key: this.apiKey, voice: this.voice };
+  }
+};
+function deepgram(opts) {
+  const options = {
+    model: opts.model ?? "nova-3",
+    endpointing_ms: opts.endpointingMs ?? 150,
+    utterance_end_ms: opts.utteranceEndMs === null ? null : opts.utteranceEndMs ?? 1e3,
+    smart_format: opts.smartFormat ?? true,
+    interim_results: opts.interimResults ?? true
+  };
+  if (opts.vadEvents !== void 0) options.vad_events = opts.vadEvents;
+  return new STTConfigImpl("deepgram", opts.apiKey, opts.language ?? "en", options);
+}
+function whisper(opts) {
+  return new STTConfigImpl("whisper", opts.apiKey, opts.language ?? "en");
+}
+function elevenlabs(opts) {
+  return new TTSConfigImpl("elevenlabs", opts.apiKey, opts.voice ?? "rachel");
+}
+function openaiTts(opts) {
+  return new TTSConfigImpl("openai", opts.apiKey, opts.voice ?? "alloy");
+}
+
 // src/fallback-provider.ts
 var AllProvidersFailedError = class extends Error {
   constructor(message) {
@@ -719,6 +859,37 @@ var FallbackLLMProvider = class {
       }
     }
   }
+  /**
+   * Async-friendly disposer. Parity with Python's ``FallbackLLMProvider.aclose()``
+   * — safe to call multiple times, returns a resolved Promise once all probe
+   * timers are cleared. Prefer this in async contexts so awaiting the
+   * shutdown integrates naturally with the owning lifecycle.
+   */
+  async aclose() {
+    this.destroy();
+  }
+  /**
+   * Explicit-resource-management hook so callers can write
+   * ``await using fallback = new FallbackLLMProvider([...])`` and have
+   * background probe timers cleared automatically when the block exits.
+   * Mirrors Python's ``async with FallbackLLMProvider(...)``.
+   */
+  async [Symbol.asyncDispose]() {
+    await this.aclose();
+  }
+  /**
+   * Stream only the text deltas, flattening the chunk envelope. Parity with
+   * Python's ``FallbackLLMProvider.complete_stream``. Tool-call and done
+   * markers are filtered out so callers can concatenate the yielded strings
+   * directly.
+   */
+  async *completeStream(messages, tools) {
+    for await (const chunk of this.stream(messages, tools)) {
+      if (chunk.type === "text") {
+        yield chunk.content ?? "";
+      }
+    }
+  }
   // -----------------------------------------------------------------------
   // LLMProvider implementation
   // -----------------------------------------------------------------------
@@ -1235,13 +1406,37 @@ function wrapCallback(cb) {
     }
   };
 }
-async function scheduleCron(cron, callback) {
-  const cm = await loadCron();
-  if (!cm.validate(cron)) {
-    throw new Error(`Invalid cron expression: ${cron}`);
-  }
-  const task = cm.schedule(cron, wrapCallback(callback));
-  return makeHandle(`cron-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, task);
+function scheduleCron(cron, callback) {
+  let cancelled = false;
+  let task = null;
+  const jobId = `cron-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  loadCron().then((cm) => {
+    if (cancelled) return;
+    if (!cm.validate(cron)) {
+      throw new Error(`Invalid cron expression: ${cron}`);
+    }
+    task = cm.schedule(cron, wrapCallback(callback));
+  }).catch((err) => getLogger().error(`scheduleCron failed: ${String(err)}`));
+  return {
+    jobId,
+    cancel() {
+      if (cancelled) return;
+      cancelled = true;
+      if (task) {
+        try {
+          task.stop();
+        } catch {
+        }
+        try {
+          task.destroy?.();
+        } catch {
+        }
+      }
+    },
+    get pending() {
+      return !cancelled;
+    }
+  };
 }
 function scheduleOnce(at, callback) {
   const delayMs = at.getTime() - Date.now();
@@ -1263,8 +1458,18 @@ function scheduleOnce(at, callback) {
     }
   };
 }
-function scheduleInterval(intervalMs, callback) {
-  if (intervalMs <= 0) throw new Error("intervalMs must be positive");
+function scheduleInterval(intervalOrOpts, callback) {
+  let intervalMs;
+  if (typeof intervalOrOpts === "number") {
+    intervalMs = intervalOrOpts;
+  } else if (intervalOrOpts.intervalMs !== void 0) {
+    intervalMs = intervalOrOpts.intervalMs;
+  } else if (intervalOrOpts.seconds !== void 0) {
+    intervalMs = intervalOrOpts.seconds * 1e3;
+  } else {
+    throw new Error("scheduleInterval requires seconds or intervalMs");
+  }
+  if (intervalMs <= 0) throw new Error("interval must be positive");
   let cancelled = false;
   const wrapped = wrapCallback(callback);
   const timer = setInterval(() => {
@@ -1281,85 +1486,378 @@ function scheduleInterval(intervalMs, callback) {
     }
   };
 }
-function makeHandle(jobId, task) {
-  let cancelled = false;
-  return {
-    jobId,
-    cancel() {
-      if (cancelled) return;
-      cancelled = true;
-      try {
-        task.stop();
-      } catch {
-      }
-      try {
-        task.destroy?.();
-      } catch {
-      }
-    },
-    get pending() {
-      return !cancelled;
+
+// src/stt/deepgram.ts
+var STT = class extends DeepgramSTT {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.DEEPGRAM_API_KEY;
+    if (!key) {
+      throw new Error(
+        "Deepgram STT requires an apiKey. Pass { apiKey: 'dg_...' } or set DEEPGRAM_API_KEY in the environment."
+      );
     }
-  };
-}
+    super(
+      key,
+      opts.language ?? "en",
+      opts.model ?? "nova-3",
+      opts.encoding ?? "linear16",
+      opts.sampleRate ?? 16e3,
+      {
+        endpointingMs: opts.endpointingMs ?? 150,
+        utteranceEndMs: opts.utteranceEndMs === null ? null : opts.utteranceEndMs ?? 1e3,
+        smartFormat: opts.smartFormat ?? true,
+        interimResults: opts.interimResults ?? true,
+        ...opts.vadEvents !== void 0 ? { vadEvents: opts.vadEvents } : {}
+      }
+    );
+  }
+};
 
-// src/providers/soniox-stt.ts
-import WebSocket3 from "ws";
-var SONIOX_WS_URL = "wss://stt-rt.soniox.com/transcribe-websocket";
-var KEEPALIVE_MESSAGE = '{"type": "keepalive"}';
-var END_TOKEN = "<end>";
-var FINALIZED_TOKEN = "<fin>";
-var KEEPALIVE_INTERVAL_MS = 5e3;
-function isEndToken(token) {
-  return token.text === END_TOKEN || token.text === FINALIZED_TOKEN;
+// src/providers/whisper-stt.ts
+var OPENAI_TRANSCRIPTION_URL = "https://api.openai.com/v1/audio/transcriptions";
+var DEFAULT_BUFFER_SIZE = 16e3 * 2;
+function wrapPcmInWav(pcm, sampleRate = 16e3, channels = 1, bitsPerSample = 16) {
+  const dataSize = pcm.length;
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + dataSize, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(channels, 22);
+  header.writeUInt32LE(sampleRate, 24);
+  header.writeUInt32LE(sampleRate * channels * (bitsPerSample / 8), 28);
+  header.writeUInt16LE(channels * (bitsPerSample / 8), 32);
+  header.writeUInt16LE(bitsPerSample, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(dataSize, 40);
+  return Buffer.concat([header, pcm]);
 }
-var TokenAccumulator = class {
-  text = "";
-  confSum = 0;
-  confCount = 0;
-  update(token) {
-    if (token.text) {
-      this.text += token.text;
-    }
-    if (typeof token.confidence === "number") {
-      this.confSum += token.confidence;
-      this.confCount += 1;
-    }
+var WhisperSTT = class _WhisperSTT {
+  apiKey;
+  model;
+  language;
+  bufferSize;
+  buffer = Buffer.alloc(0);
+  callbacks = [];
+  running = false;
+  pendingTranscriptions = [];
+  constructor(apiKey, model = "whisper-1", language, bufferSize = DEFAULT_BUFFER_SIZE) {
+    this.apiKey = apiKey;
+    this.model = model;
+    this.language = language;
+    this.bufferSize = bufferSize;
   }
-  get confidence() {
-    return this.confCount === 0 ? 0 : this.confSum / this.confCount;
+  /** Factory for Twilio calls — mulaw 8 kHz is transcoded upstream, so we still receive PCM 16-bit. */
+  static forTwilio(apiKey, language = "en", model = "whisper-1") {
+    return new _WhisperSTT(apiKey, model, language);
   }
-  reset() {
-    this.text = "";
-    this.confSum = 0;
-    this.confCount = 0;
+  async connect() {
+    this.running = true;
+    this.buffer = Buffer.alloc(0);
   }
-  get raw() {
-    return { sum: this.confSum, count: this.confCount };
+  sendAudio(audio) {
+    if (!this.running) return;
+    this.buffer = Buffer.concat([this.buffer, audio]);
+    if (this.buffer.length >= this.bufferSize) {
+      const pcm = this.buffer;
+      this.buffer = Buffer.alloc(0);
+      this.trackTranscription(this.transcribeBuffer(pcm));
+    }
+  }
+  trackTranscription(promise) {
+    const wrapped = promise.finally(() => {
+      const idx = this.pendingTranscriptions.indexOf(wrapped);
+      if (idx !== -1) this.pendingTranscriptions.splice(idx, 1);
+    });
+    this.pendingTranscriptions.push(wrapped);
   }
-};
-var SonioxSTT = class _SonioxSTT {
-  ws = null;
-  callbacks = [];
-  final = new TokenAccumulator();
-  keepaliveTimer = null;
-  apiKey;
-  model;
-  languageHints;
-  languageHintsStrict;
-  sampleRate;
-  numChannels;
-  enableSpeakerDiarization;
-  enableLanguageIdentification;
-  maxEndpointDelayMs;
-  clientReferenceId;
-  baseUrl;
-  constructor(apiKey, options = {}) {
-    if (!apiKey) {
-      throw new Error("Soniox apiKey is required");
+  onTranscript(callback) {
+    if (this.callbacks.length >= 10) {
+      getLogger().warn("WhisperSTT: maximum of 10 onTranscript callbacks reached; replacing the last callback.");
+      this.callbacks[this.callbacks.length - 1] = callback;
+      return;
     }
-    const maxEndpointDelayMs = options.maxEndpointDelayMs ?? 500;
-    if (maxEndpointDelayMs < 500 || maxEndpointDelayMs > 3e3) {
+    this.callbacks.push(callback);
+  }
+  async close() {
+    this.running = false;
+    if (this.buffer.length >= this.bufferSize / 4) {
+      const pcm = this.buffer;
+      this.buffer = Buffer.alloc(0);
+      this.trackTranscription(this.transcribeBuffer(pcm));
+    } else {
+      this.buffer = Buffer.alloc(0);
+    }
+    await Promise.allSettled(this.pendingTranscriptions);
+    this.callbacks = [];
+  }
+  // ------------------------------------------------------------------
+  // Private
+  // ------------------------------------------------------------------
+  async transcribeBuffer(pcm) {
+    const wav = wrapPcmInWav(pcm);
+    const formData = new FormData();
+    formData.append("file", new Blob([wav.buffer.slice(wav.byteOffset, wav.byteOffset + wav.byteLength)], { type: "audio/wav" }), "audio.wav");
+    formData.append("model", this.model);
+    if (this.language) {
+      formData.append("language", this.language);
+    }
+    try {
+      const resp = await fetch(OPENAI_TRANSCRIPTION_URL, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        body: formData,
+        signal: AbortSignal.timeout(15e3)
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        getLogger().error(`WhisperSTT transcription error: ${resp.status} ${body}`);
+        return;
+      }
+      const json = await resp.json();
+      const text = (json.text ?? "").trim();
+      if (!text) return;
+      const transcript = {
+        text,
+        isFinal: true,
+        confidence: 1
+      };
+      for (const cb of this.callbacks) {
+        cb(transcript);
+      }
+    } catch (err) {
+      getLogger().error(`WhisperSTT transcription error: ${String(err)}`);
+    }
+  }
+};
+
+// src/stt/whisper.ts
+var STT2 = class extends WhisperSTT {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.OPENAI_API_KEY;
+    if (!key) {
+      throw new Error(
+        "Whisper STT requires an apiKey. Pass { apiKey: 'sk-...' } or set OPENAI_API_KEY in the environment."
+      );
+    }
+    super(key, opts.model ?? "whisper-1", opts.language, opts.bufferSize);
+  }
+};
+
+// src/providers/cartesia-stt.ts
+import WebSocket3 from "ws";
+var DEFAULT_BASE_URL = "https://api.cartesia.ai";
+var API_VERSION = "2025-04-16";
+var USER_AGENT = "Patter/1.0 (integration=LiveKit-port; provider=Cartesia)";
+var KEEPALIVE_INTERVAL_MS = 3e4;
+var CONNECT_TIMEOUT_MS = 1e4;
+var MAX_CALLBACKS = 10;
+var CartesiaSTT = class {
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.options = options;
+    if (!apiKey) {
+      throw new Error("CartesiaSTT requires a non-empty apiKey");
+    }
+  }
+  ws = null;
+  callbacks = [];
+  keepaliveTimer = null;
+  /** Cartesia request id — set from the server transcript events. */
+  requestId = "";
+  buildWsUrl() {
+    const opts = this.options;
+    const rawBase = opts.baseUrl ?? DEFAULT_BASE_URL;
+    let base;
+    if (rawBase.startsWith("http://")) {
+      base = `ws://${rawBase.slice("http://".length)}`;
+    } else if (rawBase.startsWith("https://")) {
+      base = `wss://${rawBase.slice("https://".length)}`;
+    } else if (rawBase.startsWith("ws://") || rawBase.startsWith("wss://")) {
+      base = rawBase;
+    } else {
+      base = `wss://${rawBase}`;
+    }
+    const language = opts.language ?? "en";
+    const params = new URLSearchParams({
+      model: opts.model ?? "ink-whisper",
+      sample_rate: String(opts.sampleRate ?? 16e3),
+      encoding: opts.encoding ?? "pcm_s16le",
+      cartesia_version: API_VERSION,
+      api_key: this.apiKey,
+      language
+    });
+    return `${base}/stt/websocket?${params.toString()}`;
+  }
+  async connect() {
+    const url = this.buildWsUrl();
+    this.ws = new WebSocket3(url, {
+      headers: { "User-Agent": USER_AGENT }
+    });
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error("Cartesia STT connect timeout")),
+        CONNECT_TIMEOUT_MS
+      );
+      this.ws.once("open", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      this.ws.once("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+    this.ws.on("message", (raw) => {
+      let event;
+      try {
+        event = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      this.handleEvent(event);
+    });
+    this.keepaliveTimer = setInterval(() => {
+      if (this.ws && this.ws.readyState === WebSocket3.OPEN) {
+        try {
+          this.ws.ping();
+        } catch {
+        }
+      }
+    }, KEEPALIVE_INTERVAL_MS);
+  }
+  handleEvent(event) {
+    const type = event.type;
+    if (type === "transcript") {
+      const text = (event.text ?? "").trim();
+      const isFinal = Boolean(event.is_final);
+      if (!text && !isFinal) return;
+      if (event.request_id) {
+        this.requestId = event.request_id;
+      }
+      if (!text) return;
+      const confidence = Number(event.probability ?? 1);
+      this.emit({ text, isFinal, confidence });
+      return;
+    }
+    if (type === "error") {
+      getLogger().error(`Cartesia STT error: ${event.message ?? "unknown"}`);
+      return;
+    }
+  }
+  emit(transcript) {
+    for (const cb of this.callbacks) {
+      cb(transcript);
+    }
+  }
+  sendAudio(audio) {
+    if (!this.ws || this.ws.readyState !== WebSocket3.OPEN) return;
+    this.ws.send(audio);
+  }
+  onTranscript(callback) {
+    if (this.callbacks.length >= MAX_CALLBACKS) {
+      getLogger().warn(
+        "CartesiaSTT: maximum of 10 onTranscript callbacks reached; replacing the last callback."
+      );
+      this.callbacks[this.callbacks.length - 1] = callback;
+      return;
+    }
+    this.callbacks.push(callback);
+  }
+  close() {
+    if (this.keepaliveTimer) {
+      clearInterval(this.keepaliveTimer);
+      this.keepaliveTimer = null;
+    }
+    if (this.ws) {
+      try {
+        this.ws.send("finalize");
+      } catch {
+      }
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+};
+
+// src/stt/cartesia.ts
+var STT3 = class extends CartesiaSTT {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.CARTESIA_API_KEY;
+    if (!key) {
+      throw new Error(
+        "Cartesia STT requires an apiKey. Pass { apiKey: '...' } or set CARTESIA_API_KEY in the environment."
+      );
+    }
+    super(key, {
+      model: opts.model,
+      language: opts.language,
+      encoding: opts.encoding,
+      sampleRate: opts.sampleRate,
+      baseUrl: opts.baseUrl
+    });
+  }
+};
+
+// src/providers/soniox-stt.ts
+import WebSocket4 from "ws";
+var SONIOX_WS_URL = "wss://stt-rt.soniox.com/transcribe-websocket";
+var KEEPALIVE_MESSAGE = '{"type": "keepalive"}';
+var END_TOKEN = "<end>";
+var FINALIZED_TOKEN = "<fin>";
+var KEEPALIVE_INTERVAL_MS2 = 5e3;
+function isEndToken(token) {
+  return token.text === END_TOKEN || token.text === FINALIZED_TOKEN;
+}
+var TokenAccumulator = class {
+  text = "";
+  confSum = 0;
+  confCount = 0;
+  update(token) {
+    if (token.text) {
+      this.text += token.text;
+    }
+    if (typeof token.confidence === "number") {
+      this.confSum += token.confidence;
+      this.confCount += 1;
+    }
+  }
+  get confidence() {
+    return this.confCount === 0 ? 0 : this.confSum / this.confCount;
+  }
+  reset() {
+    this.text = "";
+    this.confSum = 0;
+    this.confCount = 0;
+  }
+  get raw() {
+    return { sum: this.confSum, count: this.confCount };
+  }
+};
+var SonioxSTT = class _SonioxSTT {
+  ws = null;
+  callbacks = [];
+  final = new TokenAccumulator();
+  keepaliveTimer = null;
+  apiKey;
+  model;
+  languageHints;
+  languageHintsStrict;
+  sampleRate;
+  numChannels;
+  enableSpeakerDiarization;
+  enableLanguageIdentification;
+  maxEndpointDelayMs;
+  clientReferenceId;
+  baseUrl;
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error("Soniox apiKey is required");
+    }
+    const maxEndpointDelayMs = options.maxEndpointDelayMs ?? 500;
+    if (maxEndpointDelayMs < 500 || maxEndpointDelayMs > 3e3) {
       throw new Error("maxEndpointDelayMs must be between 500 and 3000");
     }
     this.apiKey = apiKey;
@@ -1400,7 +1898,7 @@ var SonioxSTT = class _SonioxSTT {
     return config;
   }
   async connect() {
-    this.ws = new WebSocket3(this.baseUrl);
+    this.ws = new WebSocket4(this.baseUrl);
     await new Promise((resolve, reject) => {
       const timer = setTimeout(() => reject(new Error("Soniox connect timeout")), 1e4);
       this.ws.once("open", () => {
@@ -1419,13 +1917,13 @@ var SonioxSTT = class _SonioxSTT {
       getLogger().error(`SonioxSTT WebSocket error: ${String(err)}`);
     });
     this.keepaliveTimer = setInterval(() => {
-      if (this.ws && this.ws.readyState === WebSocket3.OPEN) {
+      if (this.ws && this.ws.readyState === WebSocket4.OPEN) {
         try {
           this.ws.send(KEEPALIVE_MESSAGE);
         } catch {
         }
       }
-    }, KEEPALIVE_INTERVAL_MS);
+    }, KEEPALIVE_INTERVAL_MS2);
   }
   clearKeepalive() {
     if (this.keepaliveTimer) {
@@ -1492,7 +1990,7 @@ var SonioxSTT = class _SonioxSTT {
     }
   }
   sendAudio(audio) {
-    if (!this.ws || this.ws.readyState !== WebSocket3.OPEN) return;
+    if (!this.ws || this.ws.readyState !== WebSocket4.OPEN) return;
     if (audio.length === 0) return;
     this.ws.send(audio);
   }
@@ -1522,12 +2020,27 @@ var SonioxSTT = class _SonioxSTT {
   }
 };
 
+// src/stt/soniox.ts
+var STT4 = class extends SonioxSTT {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.SONIOX_API_KEY;
+    if (!key) {
+      throw new Error(
+        "Soniox STT requires an apiKey. Pass { apiKey: '...' } or set SONIOX_API_KEY in the environment."
+      );
+    }
+    const { apiKey: _ignored, ...rest } = opts;
+    void _ignored;
+    super(key, rest);
+  }
+};
+
 // src/providers/assemblyai-stt.ts
-import WebSocket4 from "ws";
-var DEFAULT_BASE_URL = "wss://streaming.assemblyai.com";
+import WebSocket5 from "ws";
+var DEFAULT_BASE_URL2 = "wss://streaming.assemblyai.com";
 var DEFAULT_MIN_TURN_SILENCE_MS = 100;
-var CONNECT_TIMEOUT_MS = 1e4;
-var MAX_CALLBACKS = 10;
+var CONNECT_TIMEOUT_MS2 = 1e4;
+var MAX_CALLBACKS2 = 10;
 var AssemblyAISTT = class _AssemblyAISTT {
   constructor(apiKey, options = {}) {
     this.apiKey = apiKey;
@@ -1582,175 +2095,29 @@ var AssemblyAISTT = class _AssemblyAISTT {
       domain: opts.domain
     };
     const params = new URLSearchParams();
-    for (const [key, value] of Object.entries(raw)) {
-      if (value === void 0 || value === null) continue;
-      if (typeof value === "boolean") {
-        params.set(key, value ? "true" : "false");
-      } else {
-        params.set(key, String(value));
-      }
-    }
-    const base = opts.baseUrl ?? DEFAULT_BASE_URL;
-    return `${base}/v3/ws?${params.toString()}`;
-  }
-  async connect() {
-    const url = this.buildUrl();
-    this.ws = new WebSocket4(url, {
-      headers: {
-        Authorization: this.apiKey,
-        "Content-Type": "application/json",
-        "User-Agent": "Patter/1.0 (integration=LiveKit-port)"
-      }
-    });
-    await new Promise((resolve, reject) => {
-      const timer = setTimeout(
-        () => reject(new Error("AssemblyAI connect timeout")),
-        CONNECT_TIMEOUT_MS
-      );
-      this.ws.once("open", () => {
-        clearTimeout(timer);
-        resolve();
-      });
-      this.ws.once("error", (err) => {
-        clearTimeout(timer);
-        reject(err);
-      });
-    });
-    this.ws.on("message", (raw) => {
-      let event;
-      try {
-        event = JSON.parse(raw.toString());
-      } catch {
-        return;
-      }
-      this.handleEvent(event);
-    });
-  }
-  handleEvent(event) {
-    const type = event.type;
-    if (type === "Begin") {
-      this.sessionId = event.id ?? "";
-      this.expiresAt = event.expires_at ?? 0;
-      return;
-    }
-    if (type !== "Turn") {
-      return;
-    }
-    const endOfTurn = Boolean(event.end_of_turn);
-    const turnIsFormatted = Boolean(event.turn_is_formatted);
-    const words = event.words ?? [];
-    const transcriptText = (event.transcript ?? "").trim();
-    if (endOfTurn) {
-      if (this.options.formatTurns && !turnIsFormatted) return;
-      if (!transcriptText) return;
-      this.emit({
-        text: transcriptText,
-        isFinal: true,
-        confidence: averageConfidence(words)
-      });
-      return;
-    }
-    if (!words.length) return;
-    const interim = words.map((w) => (w.text ?? "").trim()).filter(Boolean).join(" ");
-    if (!interim) return;
-    this.emit({
-      text: interim,
-      isFinal: false,
-      confidence: averageConfidence(words)
-    });
-  }
-  emit(transcript) {
-    for (const cb of this.callbacks) {
-      cb(transcript);
-    }
-  }
-  sendAudio(audio) {
-    if (!this.ws || this.ws.readyState !== WebSocket4.OPEN) return;
-    this.ws.send(audio);
-  }
-  onTranscript(callback) {
-    if (this.callbacks.length >= MAX_CALLBACKS) {
-      getLogger().warn(
-        "AssemblyAISTT: maximum of 10 onTranscript callbacks reached; replacing the last callback."
-      );
-      this.callbacks[this.callbacks.length - 1] = callback;
-      return;
-    }
-    this.callbacks.push(callback);
-  }
-  close() {
-    if (this.ws) {
-      try {
-        this.ws.send(JSON.stringify({ type: "Terminate" }));
-      } catch {
-      }
-      this.ws.close();
-      this.ws = null;
-    }
-  }
-};
-function averageConfidence(words) {
-  if (!words.length) return 0;
-  let total = 0;
-  for (const w of words) {
-    total += Number(w.confidence ?? 0);
-  }
-  return total / words.length;
-}
-
-// src/providers/cartesia-stt.ts
-import WebSocket5 from "ws";
-var DEFAULT_BASE_URL2 = "https://api.cartesia.ai";
-var API_VERSION = "2025-04-16";
-var USER_AGENT = "Patter/1.0 (integration=LiveKit-port; provider=Cartesia)";
-var KEEPALIVE_INTERVAL_MS2 = 3e4;
-var CONNECT_TIMEOUT_MS2 = 1e4;
-var MAX_CALLBACKS2 = 10;
-var CartesiaSTT = class {
-  constructor(apiKey, options = {}) {
-    this.apiKey = apiKey;
-    this.options = options;
-    if (!apiKey) {
-      throw new Error("CartesiaSTT requires a non-empty apiKey");
-    }
-  }
-  ws = null;
-  callbacks = [];
-  keepaliveTimer = null;
-  /** Cartesia request id — set from the server transcript events. */
-  requestId = "";
-  buildWsUrl() {
-    const opts = this.options;
-    const rawBase = opts.baseUrl ?? DEFAULT_BASE_URL2;
-    let base;
-    if (rawBase.startsWith("http://")) {
-      base = `ws://${rawBase.slice("http://".length)}`;
-    } else if (rawBase.startsWith("https://")) {
-      base = `wss://${rawBase.slice("https://".length)}`;
-    } else if (rawBase.startsWith("ws://") || rawBase.startsWith("wss://")) {
-      base = rawBase;
-    } else {
-      base = `wss://${rawBase}`;
-    }
-    const language = opts.language ?? "en";
-    const params = new URLSearchParams({
-      model: opts.model ?? "ink-whisper",
-      sample_rate: String(opts.sampleRate ?? 16e3),
-      encoding: opts.encoding ?? "pcm_s16le",
-      cartesia_version: API_VERSION,
-      api_key: this.apiKey,
-      language
-    });
-    return `${base}/stt/websocket?${params.toString()}`;
+    for (const [key, value] of Object.entries(raw)) {
+      if (value === void 0 || value === null) continue;
+      if (typeof value === "boolean") {
+        params.set(key, value ? "true" : "false");
+      } else {
+        params.set(key, String(value));
+      }
+    }
+    const base = opts.baseUrl ?? DEFAULT_BASE_URL2;
+    return `${base}/v3/ws?${params.toString()}`;
   }
   async connect() {
-    const url = this.buildWsUrl();
+    const url = this.buildUrl();
     this.ws = new WebSocket5(url, {
-      headers: { "User-Agent": USER_AGENT }
+      headers: {
+        Authorization: this.apiKey,
+        "Content-Type": "application/json",
+        "User-Agent": "Patter/1.0 (integration=LiveKit-port)"
+      }
     });
     await new Promise((resolve, reject) => {
       const timer = setTimeout(
-        () => reject(new Error("Cartesia STT connect timeout")),
+        () => reject(new Error("AssemblyAI connect timeout")),
         CONNECT_TIMEOUT_MS2
       );
       this.ws.once("open", () => {
@@ -1771,33 +2138,39 @@ var CartesiaSTT = class {
       }
       this.handleEvent(event);
     });
-    this.keepaliveTimer = setInterval(() => {
-      if (this.ws && this.ws.readyState === WebSocket5.OPEN) {
-        try {
-          this.ws.ping();
-        } catch {
-        }
-      }
-    }, KEEPALIVE_INTERVAL_MS2);
   }
   handleEvent(event) {
     const type = event.type;
-    if (type === "transcript") {
-      const text = (event.text ?? "").trim();
-      const isFinal = Boolean(event.is_final);
-      if (!text && !isFinal) return;
-      if (event.request_id) {
-        this.requestId = event.request_id;
-      }
-      if (!text) return;
-      const confidence = Number(event.probability ?? 1);
-      this.emit({ text, isFinal, confidence });
+    if (type === "Begin") {
+      this.sessionId = event.id ?? "";
+      this.expiresAt = event.expires_at ?? 0;
       return;
     }
-    if (type === "error") {
-      getLogger().error(`Cartesia STT error: ${event.message ?? "unknown"}`);
+    if (type !== "Turn") {
+      return;
+    }
+    const endOfTurn = Boolean(event.end_of_turn);
+    const turnIsFormatted = Boolean(event.turn_is_formatted);
+    const words = event.words ?? [];
+    const transcriptText = (event.transcript ?? "").trim();
+    if (endOfTurn) {
+      if (this.options.formatTurns && !turnIsFormatted) return;
+      if (!transcriptText) return;
+      this.emit({
+        text: transcriptText,
+        isFinal: true,
+        confidence: averageConfidence(words)
+      });
       return;
     }
+    if (!words.length) return;
+    const interim = words.map((w) => (w.text ?? "").trim()).filter(Boolean).join(" ");
+    if (!interim) return;
+    this.emit({
+      text: interim,
+      isFinal: false,
+      confidence: averageConfidence(words)
+    });
   }
   emit(transcript) {
     for (const cb of this.callbacks) {
@@ -1811,7 +2184,7 @@ var CartesiaSTT = class {
   onTranscript(callback) {
     if (this.callbacks.length >= MAX_CALLBACKS2) {
       getLogger().warn(
-        "CartesiaSTT: maximum of 10 onTranscript callbacks reached; replacing the last callback."
+        "AssemblyAISTT: maximum of 10 onTranscript callbacks reached; replacing the last callback."
       );
       this.callbacks[this.callbacks.length - 1] = callback;
       return;
@@ -1819,13 +2192,9 @@ var CartesiaSTT = class {
     this.callbacks.push(callback);
   }
   close() {
-    if (this.keepaliveTimer) {
-      clearInterval(this.keepaliveTimer);
-      this.keepaliveTimer = null;
-    }
     if (this.ws) {
       try {
-        this.ws.send("finalize");
+        this.ws.send(JSON.stringify({ type: "Terminate" }));
       } catch {
       }
       this.ws.close();
@@ -1833,6 +2202,305 @@ var CartesiaSTT = class {
     }
   }
 };
+function averageConfidence(words) {
+  if (!words.length) return 0;
+  let total = 0;
+  for (const w of words) {
+    total += Number(w.confidence ?? 0);
+  }
+  return total / words.length;
+}
+
+// src/stt/assemblyai.ts
+var STT5 = class extends AssemblyAISTT {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.ASSEMBLYAI_API_KEY;
+    if (!key) {
+      throw new Error(
+        "AssemblyAI STT requires an apiKey. Pass { apiKey: '...' } or set ASSEMBLYAI_API_KEY in the environment."
+      );
+    }
+    const { apiKey: _ignored, ...rest } = opts;
+    void _ignored;
+    super(key, rest);
+  }
+};
+
+// src/providers/elevenlabs-tts.ts
+var ELEVENLABS_BASE_URL = "https://api.elevenlabs.io/v1";
+var ELEVENLABS_VOICE_ID_BY_NAME = {
+  rachel: "21m00Tcm4TlvDq8ikWAM",
+  drew: "29vD33N1CtxCmqQRPOHJ",
+  clyde: "2EiwWnXFnvU5JabPnv8n",
+  paul: "5Q0t7uMcjvnagumLfvZi",
+  domi: "AZnzlk1XvdvUeBnXmlld",
+  dave: "CYw3kZ02Hs0563khs1Fj",
+  fin: "D38z5RcWu1voky8WS1ja",
+  bella: "EXAVITQu4vr4xnSDxMaL",
+  antoni: "ErXwobaYiN019PkySvjV",
+  thomas: "GBv7mTt0atIp3Br8iCZE",
+  charlie: "IKne3meq5aSn9XLyUdCD",
+  george: "JBFqnCBsd6RMkjVDRZzb",
+  emily: "LcfcDJNUP1GQjkzn1xUU",
+  elli: "MF3mGyEYCl7XYWbV9V6O",
+  callum: "N2lVS1w4EtoT3dr4eOWO",
+  patrick: "ODq5zmih8GrVes37Dizd",
+  harry: "SOYHLrjzK2X1ezoPC6cr",
+  liam: "TX3LPaxmHKxFdv7VOQHJ",
+  dorothy: "ThT5KcBeYPX3keUQqHPh",
+  josh: "TxGEqnHWrfWFTfGW9XjX",
+  arnold: "VR6AewLTigWG4xSOukaG",
+  charlotte: "XB0fDUnXU5powFXDhCwa",
+  matilda: "XrExE9yKIg1WjnnlVkGX",
+  matthew: "Yko7PKHZNXotIFUBG7I9",
+  james: "ZQe5CZNOzWyzPSCn5a3c",
+  joseph: "Zlb1dXrM653N07WRdFW3",
+  jeremy: "bVMeCyTHy58xNoL34h3p",
+  michael: "flq6f7yk4E4fJM5XTYuZ",
+  ethan: "g5CIjZEefAph4nQFvHAz",
+  gigi: "jBpfuIE2acCO8z3wKNLl",
+  freya: "jsCqWAovK2LkecY7zXl4",
+  brian: "nPczCjzI2devNBz1zQrb",
+  grace: "oWAxZDx7w5VEj9dCyTzz",
+  daniel: "onwK4e9ZLuTAKqWW03F9",
+  lily: "pFZP5JQG7iQjIQuC4Bku",
+  serena: "pMsXgVXv3BLzUgSXRplE",
+  adam: "pNInz6obpgDQGcFmaJgB",
+  nicole: "piTKgcLEGmPE4e6mEKli",
+  bill: "pqHfZKP75CvOlQylNhV4",
+  jessie: "t0jbNlBVZ17f02VDIeMI",
+  ryan: "wViXBPUzp2ZZixB1xQuM",
+  sam: "yoZ06aMxZJJ28mfd3POQ",
+  glinda: "z9fAnlkpzviPz146aGWa",
+  giovanni: "zcAOhNBS3c14rBihAFp1",
+  mimi: "zrHiDhphv9ZnVXBqCLjz",
+  alloy: "21m00Tcm4TlvDq8ikWAM"
+};
+var VOICE_ID_PATTERN = /^[A-Za-z0-9]{20}$/;
+function resolveVoiceId(voice) {
+  if (!voice) return voice;
+  if (VOICE_ID_PATTERN.test(voice)) return voice;
+  return ELEVENLABS_VOICE_ID_BY_NAME[voice.toLowerCase()] ?? voice;
+}
+var ElevenLabsTTS = class {
+  constructor(apiKey, voiceId = "21m00Tcm4TlvDq8ikWAM", modelId = "eleven_turbo_v2_5", outputFormat = "pcm_16000") {
+    this.apiKey = apiKey;
+    this.modelId = modelId;
+    this.outputFormat = outputFormat;
+    this.voiceId = resolveVoiceId(voiceId);
+  }
+  voiceId;
+  /**
+   * Synthesise text to speech and return the full audio as a single Buffer.
+   *
+   * For large chunks (or when latency matters) call `synthesizeStream` instead.
+   */
+  async synthesize(text) {
+    const chunks = [];
+    for await (const chunk of this.synthesizeStream(text)) {
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+  /**
+   * Synthesise text and yield audio chunks as they arrive (streaming).
+   *
+   * The yielded buffers are raw PCM at 16 kHz (or whatever `outputFormat` is
+   * configured to).
+   */
+  async *synthesizeStream(text) {
+    const url = `${ELEVENLABS_BASE_URL}/text-to-speech/${encodeURIComponent(this.voiceId)}/stream?output_format=${encodeURIComponent(this.outputFormat)}`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "xi-api-key": this.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ text, model_id: this.modelId }),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`ElevenLabs TTS error ${response.status}: ${body}`);
+    }
+    if (!response.body) {
+      throw new Error("ElevenLabs TTS: no response body");
+    }
+    const reader = response.body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value && value.length > 0) {
+          yield Buffer.from(value);
+        }
+      }
+    } finally {
+      if (typeof reader.cancel === "function") await reader.cancel().catch(() => {
+      });
+      reader.releaseLock();
+    }
+  }
+};
+
+// src/tts/elevenlabs.ts
+var TTS = class extends ElevenLabsTTS {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.ELEVENLABS_API_KEY;
+    if (!key) {
+      throw new Error(
+        "ElevenLabs TTS requires an apiKey. Pass { apiKey: '...' } or set ELEVENLABS_API_KEY in the environment."
+      );
+    }
+    super(
+      key,
+      opts.voiceId ?? "21m00Tcm4TlvDq8ikWAM",
+      opts.modelId ?? "eleven_turbo_v2_5",
+      opts.outputFormat ?? "pcm_16000"
+    );
+  }
+};
+
+// src/providers/openai-tts.ts
+var OPENAI_TTS_URL = "https://api.openai.com/v1/audio/speech";
+var OpenAITTS = class _OpenAITTS {
+  constructor(apiKey, voice = "alloy", model = "tts-1") {
+    this.apiKey = apiKey;
+    this.voice = voice;
+    this.model = model;
+  }
+  /**
+   * Synthesise text to speech and return the full audio as a single Buffer.
+   *
+   * For large chunks (or when latency matters) call `synthesizeStream` instead.
+   */
+  async synthesize(text) {
+    const chunks = [];
+    for await (const chunk of this.synthesizeStream(text)) {
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+  /**
+   * Synthesise text and yield audio chunks as they arrive (streaming).
+   *
+   * OpenAI returns 24 kHz PCM16; each chunk is resampled to 16 kHz before
+   * yielding so the output is ready for telephony pipelines.
+   *
+   * The resampler carries state (buffered samples + odd trailing byte)
+   * between chunks — without that state cross-chunk sample alignment drifts
+   * and the caller hears pops / dropped audio (BUG #23, mirror of the
+   * Python `audioop.ratecv` fix).
+   */
+  async *synthesizeStream(text) {
+    const response = await fetch(OPENAI_TTS_URL, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: text,
+        voice: this.voice,
+        response_format: "pcm"
+      }),
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`OpenAI TTS error ${response.status}: ${body}`);
+    }
+    if (!response.body) {
+      throw new Error("OpenAI TTS: no response body");
+    }
+    const ctx = { carryByte: null, leftover: [] };
+    const reader = response.body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value && value.length > 0) {
+          const out = _OpenAITTS.resampleStreaming(Buffer.from(value), ctx);
+          if (out.length > 0) yield out;
+        }
+      }
+      if (ctx.leftover.length > 0) {
+        const tail = Buffer.alloc(ctx.leftover.length * 2);
+        for (let i = 0; i < ctx.leftover.length; i++) {
+          tail.writeInt16LE(ctx.leftover[i], i * 2);
+        }
+        yield tail;
+      }
+    } finally {
+      if (typeof reader.cancel === "function") await reader.cancel().catch(() => {
+      });
+      reader.releaseLock();
+    }
+  }
+  /**
+   * Streaming 24 kHz → 16 kHz resampler (PCM16-LE). Maintains cross-chunk
+   * state so the 3:2 pattern doesn't reset at every network read.
+   */
+  static resampleStreaming(audio, ctx) {
+    let buf;
+    if (ctx.carryByte !== null) {
+      buf = Buffer.concat([Buffer.from([ctx.carryByte]), audio]);
+      ctx.carryByte = null;
+    } else {
+      buf = audio;
+    }
+    if (buf.length % 2 === 1) {
+      ctx.carryByte = buf[buf.length - 1];
+      buf = buf.subarray(0, buf.length - 1);
+    }
+    if (buf.length === 0 && ctx.leftover.length === 0) {
+      return Buffer.alloc(0);
+    }
+    const sampleCount = buf.length / 2;
+    const samples = ctx.leftover.slice();
+    for (let i2 = 0; i2 < sampleCount; i2++) {
+      samples.push(buf.readInt16LE(i2 * 2));
+    }
+    const out = [];
+    let i = 0;
+    while (i + 2 < samples.length) {
+      out.push(samples[i]);
+      out.push(Math.trunc((samples[i + 1] + samples[i + 2]) / 2));
+      i += 3;
+    }
+    ctx.leftover = samples.slice(i);
+    const buffer = Buffer.alloc(out.length * 2);
+    for (let j = 0; j < out.length; j++) {
+      buffer.writeInt16LE(out[j], j * 2);
+    }
+    return buffer;
+  }
+  /** @deprecated use {@link resampleStreaming} with persistent state. */
+  static resample24kTo16k(audio) {
+    const ctx = { carryByte: null, leftover: [] };
+    const out = _OpenAITTS.resampleStreaming(audio, ctx);
+    if (ctx.leftover.length === 0) return out;
+    const tail = Buffer.alloc(ctx.leftover.length * 2);
+    for (let i = 0; i < ctx.leftover.length; i++) {
+      tail.writeInt16LE(ctx.leftover[i], i * 2);
+    }
+    return Buffer.concat([out, tail]);
+  }
+};
+
+// src/tts/openai.ts
+var TTS2 = class extends OpenAITTS {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.OPENAI_API_KEY;
+    if (!key) {
+      throw new Error(
+        "OpenAI TTS requires an apiKey. Pass { apiKey: 'sk-...' } or set OPENAI_API_KEY in the environment."
+      );
+    }
+    super(key, opts.voice ?? "alloy", opts.model ?? "tts-1");
+  }
+};
 
 // src/providers/cartesia-tts.ts
 var CARTESIA_BASE_URL = "https://api.cartesia.ai";
@@ -1932,6 +2600,21 @@ var CartesiaTTS = class {
   }
 };
 
+// src/tts/cartesia.ts
+var TTS3 = class extends CartesiaTTS {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.CARTESIA_API_KEY;
+    if (!key) {
+      throw new Error(
+        "Cartesia TTS requires an apiKey. Pass { apiKey: '...' } or set CARTESIA_API_KEY in the environment."
+      );
+    }
+    const { apiKey: _ignored, ...rest } = opts;
+    void _ignored;
+    super(key, rest);
+  }
+};
+
 // src/providers/rime-tts.ts
 var RIME_BASE_URL = "https://users.rime.ai/v1/rime-tts";
 var ARCANA_MODEL_TIMEOUT_MS = 60 * 4 * 1e3;
@@ -2059,6 +2742,21 @@ var RimeTTS = class {
   }
 };
 
+// src/tts/rime.ts
+var TTS4 = class extends RimeTTS {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.RIME_API_KEY;
+    if (!key) {
+      throw new Error(
+        "Rime TTS requires an apiKey. Pass { apiKey: '...' } or set RIME_API_KEY in the environment."
+      );
+    }
+    const { apiKey: _ignored, ...rest } = opts;
+    void _ignored;
+    super(key, rest);
+  }
+};
+
 // src/providers/lmnt-tts.ts
 var LMNT_BASE_URL = "https://api.lmnt.com/v1/ai/speech/bytes";
 var LMNTTTS = class {
@@ -2137,6 +2835,119 @@ var LMNTTTS = class {
   }
 };
 
+// src/tts/lmnt.ts
+var TTS5 = class extends LMNTTTS {
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.LMNT_API_KEY;
+    if (!key) {
+      throw new Error(
+        "LMNT TTS requires an apiKey. Pass { apiKey: '...' } or set LMNT_API_KEY in the environment."
+      );
+    }
+    const { apiKey: _ignored, ...rest } = opts;
+    void _ignored;
+    super(key, rest);
+  }
+};
+
+// src/carriers/twilio.ts
+var Carrier = class {
+  kind = "twilio";
+  accountSid;
+  authToken;
+  constructor(opts = {}) {
+    const sid = opts.accountSid ?? process.env.TWILIO_ACCOUNT_SID;
+    const tok = opts.authToken ?? process.env.TWILIO_AUTH_TOKEN;
+    if (!sid) {
+      throw new Error(
+        "Twilio carrier requires accountSid. Pass { accountSid: 'AC...' } or set TWILIO_ACCOUNT_SID in the environment."
+      );
+    }
+    if (!tok) {
+      throw new Error(
+        "Twilio carrier requires authToken. Pass { authToken: '...' } or set TWILIO_AUTH_TOKEN in the environment."
+      );
+    }
+    this.accountSid = sid;
+    this.authToken = tok;
+  }
+};
+
+// src/carriers/telnyx.ts
+var Carrier2 = class {
+  kind = "telnyx";
+  apiKey;
+  connectionId;
+  publicKey;
+  constructor(opts = {}) {
+    const key = opts.apiKey ?? process.env.TELNYX_API_KEY;
+    const conn = opts.connectionId ?? process.env.TELNYX_CONNECTION_ID;
+    const pub = opts.publicKey ?? process.env.TELNYX_PUBLIC_KEY;
+    if (!key) {
+      throw new Error(
+        "Telnyx carrier requires apiKey. Pass { apiKey: '...' } or set TELNYX_API_KEY in the environment."
+      );
+    }
+    if (!conn) {
+      throw new Error(
+        "Telnyx carrier requires connectionId. Pass { connectionId: '...' } or set TELNYX_CONNECTION_ID in the environment."
+      );
+    }
+    this.apiKey = key;
+    this.connectionId = conn;
+    this.publicKey = pub;
+  }
+};
+
+// src/public-api.ts
+var DEFAULT_GUARDRAIL_REPLACEMENT = "I'm sorry, I can't respond to that.";
+var Guardrail = class {
+  name;
+  blockedTerms;
+  check;
+  replacement;
+  constructor(opts) {
+    if (!opts.name) {
+      throw new Error("Guardrail requires a non-empty name.");
+    }
+    this.name = opts.name;
+    if (opts.blockedTerms) this.blockedTerms = opts.blockedTerms;
+    if (opts.check) this.check = opts.check;
+    this.replacement = opts.replacement ?? DEFAULT_GUARDRAIL_REPLACEMENT;
+  }
+};
+function guardrail(opts) {
+  return new Guardrail(opts);
+}
+var Tool = class {
+  name;
+  description;
+  parameters;
+  handler;
+  webhookUrl;
+  constructor(opts) {
+    if (!opts.name) {
+      throw new Error("Tool requires a non-empty name.");
+    }
+    const hasHandler = typeof opts.handler === "function";
+    const hasWebhook = typeof opts.webhookUrl === "string" && opts.webhookUrl.length > 0;
+    if (!hasHandler && !hasWebhook) {
+      throw new Error("Tool requires either handler or webhookUrl.");
+    }
+    if (hasHandler && hasWebhook) {
+      throw new Error("Tool accepts handler OR webhookUrl, not both.");
+    }
+    this.name = opts.name;
+    this.description = opts.description ?? "";
+    this.parameters = opts.parameters ?? { type: "object", properties: {} };
+    if (hasHandler) this.handler = opts.handler;
+    if (hasWebhook) this.webhookUrl = opts.webhookUrl;
+  }
+};
+function tool(opts) {
+  return new Tool(opts);
+}
+
 // src/chat-context.ts
 import { randomUUID } from "crypto";
 function generateId() {
@@ -2747,31 +3558,35 @@ function isAudioConfig(value) {
 }
 export {
   AllProvidersFailedError,
-  AssemblyAISTT,
+  STT5 as AssemblyAISTT,
   AuthenticationError,
   BackgroundAudioPlayer,
   BuiltinAudioClip,
   CallMetricsAccumulator,
-  CartesiaSTT,
-  CartesiaTTS,
+  STT3 as CartesiaSTT,
+  TTS3 as CartesiaTTS,
   ChatContext,
+  CloudflareTunnel,
   DEFAULT_MIN_SENTENCE_LEN,
   DEFAULT_PRICING,
   DTMF_EVENTS,
-  DeepgramSTT,
+  STT as DeepgramSTT,
+  ConvAI as ElevenLabsConvAI,
   ElevenLabsConvAIAdapter,
-  ElevenLabsTTS,
+  TTS as ElevenLabsTTS,
   FallbackLLMProvider,
   GEMINI_DEFAULT_INPUT_SR,
   GEMINI_DEFAULT_OUTPUT_SR,
   GeminiLiveAdapter,
+  Guardrail,
   IVRActivity,
   LLMLoop,
-  LMNTTTS,
+  TTS5 as LMNTTTS,
   MetricsStore,
   OpenAILLMProvider,
+  Realtime as OpenAIRealtime,
   OpenAIRealtimeAdapter,
-  OpenAITTS,
+  TTS2 as OpenAITTS,
   PartialStreamError,
   Patter,
   PatterConnectionError,
@@ -2779,15 +3594,19 @@ export {
   PipelineHookExecutor,
   ProvisionError,
   RemoteMessageHandler,
-  RimeTTS,
+  TTS4 as RimeTTS,
   SentenceChunker,
-  SonioxSTT,
+  STT4 as SonioxSTT,
+  Static as StaticTunnel,
+  Carrier2 as Telnyx,
   TestSession,
   TfidfLoopDetector,
+  Tool,
+  Carrier as Twilio,
   ULTRAVOX_DEFAULT_API_BASE,
   ULTRAVOX_DEFAULT_SR,
   UltravoxRealtimeAdapter,
-  WhisperSTT,
+  STT2 as WhisperSTT,
   builtinClipPath,
   calculateRealtimeCost,
   calculateSttCost,
@@ -2803,6 +3622,7 @@ export {
   filterMarkdown,
   formatDtmf,
   getLogger,
+  guardrail,
   isRemoteUrl,
   isWebSocketUrl,
   makeAuthMiddleware,
@@ -2824,5 +3644,6 @@ export {
   selectSoundFromList,
   setLogger,
   startTunnel,
+  tool,
   whisper
 };