getpatter 0.4.3 → 0.4.4

package/dist/index.js

@@ -314,20 +314,36 @@ var init_deepgram_stt = __esm({
     init_logger();
     DEEPGRAM_WS_URL = "wss://api.deepgram.com/v1/listen";
     DeepgramSTT = class _DeepgramSTT {
-      constructor(apiKey, language = "en", model = "nova-3", encoding = "linear16", sampleRate = 16e3) {
-        this.apiKey = apiKey;
-        this.language = language;
-        this.model = model;
-        this.encoding = encoding;
-        this.sampleRate = sampleRate;
-      }
       ws = null;
       callbacks = [];
       /** Request ID from Deepgram — used to query actual cost post-call. */
       requestId = "";
-      /** Factory for Twilio calls — mulaw 8 kHz. */
-      static forTwilio(apiKey, language = "en", model = "nova-3") {
-        return new _DeepgramSTT(apiKey, language, model, "mulaw", 8e3);
+      apiKey;
+      language;
+      model;
+      encoding;
+      sampleRate;
+      endpointingMs;
+      utteranceEndMs;
+      smartFormat;
+      interimResults;
+      vadEvents;
+      constructor(apiKey, languageOrOptions, model, encoding, sampleRate, options) {
+        this.apiKey = apiKey;
+        const opts = typeof languageOrOptions === "object" && languageOrOptions !== null ? languageOrOptions : options ?? {};
+        this.language = (typeof languageOrOptions === "string" ? languageOrOptions : opts.language) ?? "en";
+        this.model = model ?? opts.model ?? "nova-3";
+        this.encoding = encoding ?? opts.encoding ?? "linear16";
+        this.sampleRate = sampleRate ?? opts.sampleRate ?? 16e3;
+        this.endpointingMs = opts.endpointingMs ?? 150;
+        this.utteranceEndMs = opts.utteranceEndMs === null ? null : opts.utteranceEndMs ?? 1e3;
+        this.smartFormat = opts.smartFormat ?? true;
+        this.interimResults = opts.interimResults ?? true;
+        this.vadEvents = opts.vadEvents ?? true;
+      }
+      /** Factory for Twilio calls — mulaw 8 kHz. Forwards tuning options through. */
+      static forTwilio(apiKey, language = "en", model = "nova-3", options = {}) {
+        return new _DeepgramSTT(apiKey, language, model, "mulaw", 8e3, options);
       }
       async connect() {
         const params = new URLSearchParams({
@@ -336,12 +352,15 @@ var init_deepgram_stt = __esm({
           encoding: this.encoding,
           sample_rate: String(this.sampleRate),
           channels: "1",
-          interim_results: "true",
-          endpointing: "300",
-          smart_format: "true",
-          vad_events: "true",
+          interim_results: this.interimResults ? "true" : "false",
+          endpointing: String(this.endpointingMs),
+          smart_format: this.smartFormat ? "true" : "false",
+          vad_events: this.vadEvents ? "true" : "false",
           no_delay: "true"
         });
+        if (this.utteranceEndMs !== null) {
+          params.set("utterance_end_ms", String(Math.max(this.utteranceEndMs, 1e3)));
+        }
         const url = `${DEEPGRAM_WS_URL}?${params.toString()}`;
         this.ws = new import_ws4.default(url, {
           headers: { Authorization: `Token ${this.apiKey}` }
@@ -376,7 +395,7 @@ var init_deepgram_stt = __esm({
           if (!text) return;
           const transcript = {
             text,
-            isFinal: Boolean(data.is_final) && Boolean(data.speech_final),
+            isFinal: Boolean(data.is_final) || Boolean(data.speech_final),
             confidence: best.confidence ?? 0
           };
           for (const cb of this.callbacks) {
@@ -616,9 +635,15 @@ var init_store = __esm({
       maxCalls;
       calls = [];
       activeCalls = /* @__PURE__ */ new Map();
-      constructor(maxCalls = 500) {
+      /**
+       * Accepts either a numeric ``maxCalls`` (legacy positional — matches the
+       * original TS API) or an options object ``{ maxCalls }`` to align with the
+       * Python SDK's keyword-argument style. Plain literals also work:
+       * ``new MetricsStore()`` / ``new MetricsStore(100)`` / ``new MetricsStore({ maxCalls: 100 })``.
+       */
+      constructor(maxCallsOrOpts = 500) {
         super();
-        this.maxCalls = maxCalls;
+        this.maxCalls = typeof maxCallsOrOpts === "number" ? maxCallsOrOpts : maxCallsOrOpts.maxCalls ?? 500;
       }
       publish(eventType, data) {
         this.emit("sse", { type: eventType, data });
@@ -626,22 +651,100 @@ var init_store = __esm({
       recordCallStart(data) {
         const callId = data.call_id || "";
         if (!callId) return;
+        const existing = this.activeCalls.get(callId);
+        if (existing) {
+          existing.caller = data.caller || existing.caller;
+          existing.callee = data.callee || existing.callee;
+          existing.direction = data.direction || existing.direction;
+          existing.status = "in-progress";
+          existing.turns = existing.turns || [];
+        } else {
+          const record = {
+            call_id: callId,
+            caller: data.caller || "",
+            callee: data.callee || "",
+            direction: data.direction || "inbound",
+            started_at: Date.now() / 1e3,
+            status: "in-progress",
+            turns: []
+          };
+          this.activeCalls.set(callId, record);
+        }
+        this.publish("call_start", {
+          call_id: callId,
+          caller: data.caller || "",
+          callee: data.callee || "",
+          direction: data.direction || "inbound"
+        });
+      }
+      /**
+       * Pre-register an outbound call before any webhook fires. Lets the
+       * dashboard surface attempts that never reach media (no-answer, busy,
+       * carrier-rejected). Mirrors the Python ``record_call_initiated``.
+       */
+      recordCallInitiated(data) {
+        const callId = data.call_id || "";
+        if (!callId) return;
+        if (this.activeCalls.has(callId)) return;
         const record = {
           call_id: callId,
           caller: data.caller || "",
           callee: data.callee || "",
-          direction: data.direction || "inbound",
+          direction: data.direction || "outbound",
           started_at: Date.now() / 1e3,
+          status: "initiated",
           turns: []
         };
         this.activeCalls.set(callId, record);
-        this.publish("call_start", {
+        this.publish("call_initiated", {
           call_id: callId,
           caller: record.caller,
           callee: record.callee,
-          direction: record.direction
+          direction: record.direction,
+          status: record.status
         });
       }
+      /**
+       * Update the status of an active or completed call. Terminal states
+       * (completed, no-answer, busy, failed, canceled, webhook_error) move the
+       * row from active to completed so the UI freezes the live duration timer.
+       */
+      updateCallStatus(callId, status, extra = {}) {
+        if (!callId || !status) return;
+        const TERMINAL = /* @__PURE__ */ new Set(["completed", "no-answer", "busy", "failed", "canceled", "webhook_error"]);
+        const active = this.activeCalls.get(callId);
+        if (active) {
+          active.status = status;
+          Object.assign(active, extra);
+          if (TERMINAL.has(status)) {
+            const entry = {
+              call_id: callId,
+              caller: active.caller || "",
+              callee: active.callee || "",
+              direction: active.direction || "outbound",
+              started_at: active.started_at || 0,
+              ended_at: Date.now() / 1e3,
+              status,
+              metrics: null,
+              ...extra
+            };
+            this.activeCalls.delete(callId);
+            this.calls.push(entry);
+            if (this.calls.length > this.maxCalls) {
+              this.calls = this.calls.slice(-this.maxCalls);
+            }
+          }
+        } else {
+          for (let i = this.calls.length - 1; i >= 0; i--) {
+            if (this.calls[i].call_id === callId) {
+              this.calls[i].status = status;
+              Object.assign(this.calls[i], extra);
+              break;
+            }
+          }
+        }
+        this.publish("call_status", { call_id: callId, status, ...extra });
+      }
       recordTurn(data) {
         const callId = data.call_id || "";
         const turn = data.turn;
@@ -658,6 +761,8 @@ var init_store = __esm({
         if (!callId) return;
         const active = this.activeCalls.get(callId);
         this.activeCalls.delete(callId);
+        const activeStatus = active?.status;
+        const resolvedStatus = activeStatus && activeStatus !== "in-progress" ? activeStatus : "completed";
         const entry = {
           call_id: callId,
           caller: data.caller || active?.caller || "",
@@ -666,6 +771,7 @@ var init_store = __esm({
           started_at: active?.started_at || 0,
           ended_at: Date.now() / 1e3,
           transcript: data.transcript || [],
+          status: resolvedStatus,
           metrics: metrics ?? null
         };
         this.calls.push(entry);
@@ -1867,18 +1973,73 @@ var init_remote_message = __esm({
 });
 
 // src/providers/elevenlabs-tts.ts
-var ELEVENLABS_BASE_URL, ElevenLabsTTS;
+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 ELEVENLABS_BASE_URL, ELEVENLABS_VOICE_ID_BY_NAME, VOICE_ID_PATTERN, ElevenLabsTTS;
 var init_elevenlabs_tts = __esm({
   "src/providers/elevenlabs-tts.ts"() {
     "use strict";
     ELEVENLABS_BASE_URL = "https://api.elevenlabs.io/v1";
+    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"
+    };
+    VOICE_ID_PATTERN = /^[A-Za-z0-9]{20}$/;
     ElevenLabsTTS = class {
       constructor(apiKey, voiceId = "21m00Tcm4TlvDq8ikWAM", modelId = "eleven_turbo_v2_5", outputFormat = "pcm_16000") {
         this.apiKey = apiKey;
-        this.voiceId = voiceId;
         this.modelId = modelId;
         this.outputFormat = outputFormat;
+        this.voiceId = resolveVoiceId(voiceId);
       }
+      voiceId;
       /**
        * Synthesise text to speech and return the full audio as a single Buffer.
        *
@@ -1963,6 +2124,11 @@ var init_openai_tts = __esm({
        *
        * 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, {
@@ -1986,14 +2152,23 @@ var init_openai_tts = __esm({
         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) {
-              yield _OpenAITTS.resample24kTo16k(Buffer.from(value));
+              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(() => {
@@ -2002,35 +2177,53 @@ var init_openai_tts = __esm({
         }
       }
       /**
-       * Resample 24 kHz PCM16-LE to 16 kHz by taking 2 out of every 3 samples.
-       *
-       * For each group of 3 input samples the first is kept as-is and the second
-       * output sample is the average of input samples 2 and 3.  This matches the
-       * Python SDK implementation.
+       * 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 resample24kTo16k(audio) {
-        if (audio.length < 2) return audio;
-        const sampleCount = Math.floor(audio.length / 2);
-        const samples = new Int16Array(sampleCount);
-        for (let i = 0; i < sampleCount; i++) {
-          samples[i] = audio.readInt16LE(i * 2);
-        }
-        const resampled = [];
-        for (let i = 0; i < samples.length; i += 3) {
-          resampled.push(samples[i]);
-          if (i + 1 < samples.length) {
-            if (i + 2 < samples.length) {
-              resampled.push(Math.trunc((samples[i + 1] + samples[i + 2]) / 2));
-            } else {
-              resampled.push(samples[i + 1]);
-            }
-          }
+      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 = Buffer.alloc(resampled.length * 2);
-        for (let i = 0; i < resampled.length; i++) {
-          out.writeInt16LE(resampled[i], i * 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;
         }
-        return out;
+        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]);
       }
     };
   }
@@ -2972,6 +3165,9 @@ var init_stream_handler = __esm({
       maxDurationTimer = null;
       transcriptProcessing = false;
       transcriptQueue = [];
+      // BUG #22 throttle state — mirror Python impl.
+      lastCommitText = "";
+      lastCommitAt = 0;
       history;
       metricsAcc;
       constructor(deps, ws, caller, callee) {
@@ -3082,15 +3278,23 @@ var init_stream_handler = __esm({
         this.streamSid = sid;
       }
       /** Handle an incoming audio chunk (already decoded from base64). */
-      handleAudio(audioBuffer) {
+      async handleAudio(audioBuffer) {
         const provider = this.deps.agent.provider ?? "openai_realtime";
-        if (provider === "pipeline" && this.stt && !this.isSpeaking) {
-          if (this.deps.bridge.telephonyProvider === "twilio") {
-            const pcm8k = mulawToPcm16(audioBuffer);
-            const pcm16k = resample8kTo16k(pcm8k);
-            this.stt.sendAudio(pcm16k);
+        if (provider === "pipeline" && this.stt) {
+          if (this.isSpeaking && (this.deps.agent.bargeInThresholdMs ?? 300) === 0) {
+            return;
+          }
+          const pcm8k = mulawToPcm16(audioBuffer);
+          const pcm16k = resample8kTo16k(pcm8k);
+          const hooks = this.deps.agent.hooks;
+          if (hooks) {
+            const hookExecutor = new PipelineHookExecutor(hooks);
+            const hookCtx = this.buildHookContext();
+            const processed = await hookExecutor.runBeforeSendToStt(pcm16k, hookCtx);
+            if (processed === null) return;
+            this.stt.sendAudio(processed);
           } else {
-            this.stt.sendAudio(audioBuffer);
+            this.stt.sendAudio(pcm16k);
           }
         } else if (this.adapter) {
           if (this.adapter instanceof ElevenLabsConvAIAdapter && this.deps.bridge.telephonyProvider === "twilio") {
@@ -3172,8 +3376,7 @@ var init_stream_handler = __esm({
             this.tts = new OpenAITTS(this.deps.agent.tts.apiKey, this.deps.agent.tts.voice ?? "alloy");
           }
         } else if (this.deps.agent.elevenlabsKey) {
-          const voiceId = this.deps.agent.voice && this.deps.agent.voice !== "alloy" ? this.deps.agent.voice : "21m00Tcm4TlvDq8ikWAM";
-          this.tts = new ElevenLabsTTS(this.deps.agent.elevenlabsKey, voiceId);
+          this.tts = new ElevenLabsTTS(this.deps.agent.elevenlabsKey, this.deps.agent.voice || "rachel");
         }
         if (!this.stt) {
           getLogger().info(`Pipeline mode (${label}): no STT configured`);
@@ -3285,7 +3488,59 @@ var init_stream_handler = __esm({
         }
       }
       async processTranscript(transcript) {
+        if (transcript.text && this.isSpeaking) {
+          getLogger().info(
+            `Barge-in: caller spoke over agent (${sanitizeLogValue(transcript.text.slice(0, 40))})`
+          );
+          this.isSpeaking = false;
+          try {
+            this.deps.bridge.sendClear(this.ws, this.streamSid);
+          } catch (err) {
+            getLogger().debug(`sendClear during barge-in failed: ${String(err)}`);
+          }
+          this.metricsAcc.recordTurnInterrupted();
+        }
         if (!transcript.isFinal || !transcript.text) return;
+        const now = Date.now();
+        const normalised = transcript.text.trim().toLowerCase();
+        const stripped = normalised.replace(/[.,!?;: ]+$/, "").trim();
+        const sinceLastMs = now - this.lastCommitAt;
+        const HALLUCINATIONS = /* @__PURE__ */ new Set([
+          "you",
+          "thank you",
+          "thanks",
+          "yeah",
+          "yes",
+          "no",
+          "okay",
+          "ok",
+          "uh",
+          "um",
+          "mmm",
+          "hmm",
+          ".",
+          "bye",
+          "right",
+          "cool"
+        ]);
+        if (HALLUCINATIONS.has(stripped) || stripped === "") {
+          getLogger().info(`Dropped likely STT hallucination: ${sanitizeLogValue(normalised.slice(0, 40))}`);
+          return;
+        }
+        if (sinceLastMs < 2e3 && normalised === this.lastCommitText) {
+          getLogger().info(
+            `Dropped duplicate final transcript (${(sinceLastMs / 1e3).toFixed(1)}s since last): ${sanitizeLogValue(normalised.slice(0, 40))}`
+          );
+          return;
+        }
+        if (sinceLastMs < 500) {
+          getLogger().info(
+            `Dropped back-to-back final transcript (${(sinceLastMs / 1e3).toFixed(2)}s since last): ${sanitizeLogValue(normalised.slice(0, 40))}`
+          );
+          return;
+        }
+        this.lastCommitText = normalised;
+        this.lastCommitAt = now;
         const label = this.deps.bridge.label;
         getLogger().info(`User (${label} pipeline): ${sanitizeLogValue(transcript.text)}`);
         this.metricsAcc.startTurn();
@@ -3770,6 +4025,25 @@ function buildAIAdapter(config, agent, resolvedPrompt) {
     tools
   );
 }
+function extractDeepgramOptions(options) {
+  if (!options) return {};
+  const get = (snake, camel) => options[snake] ?? options[camel];
+  const out = {};
+  const model = get("model", "model");
+  if (typeof model === "string") out.model = model;
+  const endpointing = get("endpointing_ms", "endpointingMs");
+  if (typeof endpointing === "number") out.endpointingMs = endpointing;
+  const utteranceEnd = get("utterance_end_ms", "utteranceEndMs");
+  if (utteranceEnd === null) out.utteranceEndMs = null;
+  else if (typeof utteranceEnd === "number") out.utteranceEndMs = utteranceEnd;
+  const smart = get("smart_format", "smartFormat");
+  if (typeof smart === "boolean") out.smartFormat = smart;
+  const interim = get("interim_results", "interimResults");
+  if (typeof interim === "boolean") out.interimResults = interim;
+  const vad = get("vad_events", "vadEvents");
+  if (typeof vad === "boolean") out.vadEvents = vad;
+  return out;
+}
 function isValidTelnyxTransferTarget(target) {
   if (typeof target !== "string" || !target) return false;
   if (/^\+[1-9]\d{6,14}$/.test(target)) return true;
@@ -3875,13 +4149,21 @@ var init_server = __esm({
         }
       }
       createStt(agent) {
+        const isPipeline = agent.provider === "pipeline";
         if (agent.stt) {
           if (agent.stt.provider === "deepgram") {
-            return DeepgramSTT.forTwilio(agent.stt.apiKey, agent.stt.language ?? "en");
+            const dgOptions = extractDeepgramOptions(agent.stt.options);
+            if (isPipeline) {
+              return new DeepgramSTT(agent.stt.apiKey, agent.stt.language ?? "en", dgOptions.model, "linear16", 16e3, dgOptions);
+            }
+            return DeepgramSTT.forTwilio(agent.stt.apiKey, agent.stt.language ?? "en", dgOptions.model, dgOptions);
           } else if (agent.stt.provider === "whisper") {
-            return WhisperSTT.forTwilio(agent.stt.apiKey, agent.stt.language ?? "en");
+            return isPipeline ? new WhisperSTT(agent.stt.apiKey, "whisper-1", agent.stt.language ?? "en") : WhisperSTT.forTwilio(agent.stt.apiKey, agent.stt.language ?? "en");
           }
         } else if (agent.deepgramKey) {
+          if (isPipeline) {
+            return new DeepgramSTT(agent.deepgramKey, agent.language ?? "en", "nova-3", "linear16", 16e3);
+          }
           return DeepgramSTT.forTwilio(agent.deepgramKey, agent.language ?? "en");
         }
         return null;
@@ -3923,12 +4205,12 @@ var init_server = __esm({
       label = "Telnyx";
       telephonyProvider = "telnyx";
       sendAudio(ws, audioBase64, _streamSid) {
-        ws.send(JSON.stringify({ event_type: "media", payload: { audio: { chunk: audioBase64 } } }));
+        ws.send(JSON.stringify({ event: "media", media: { payload: audioBase64 } }));
       }
       sendMark(_ws, _markName, _streamSid) {
       }
       sendClear(ws, _streamSid) {
-        ws.send(JSON.stringify({ event_type: "media_stop" }));
+        ws.send(JSON.stringify({ event: "clear" }));
       }
       async transferCall(callId, toNumber) {
         if (!isValidTelnyxTransferTarget(toNumber)) {
@@ -4024,7 +4306,15 @@ var init_server = __esm({
       createStt(agent) {
         if (agent.stt) {
           if (agent.stt.provider === "deepgram") {
-            return new DeepgramSTT(agent.stt.apiKey, agent.stt.language ?? "en", "nova-3", "linear16", 16e3);
+            const dgOptions = extractDeepgramOptions(agent.stt.options);
+            return new DeepgramSTT(
+              agent.stt.apiKey,
+              agent.stt.language ?? "en",
+              dgOptions.model ?? "nova-3",
+              "linear16",
+              16e3,
+              dgOptions
+            );
           } else if (agent.stt.provider === "whisper") {
             return new WhisperSTT(agent.stt.apiKey, "whisper-1", agent.stt.language ?? "en");
           }
@@ -4076,6 +4366,7 @@ var init_server = __esm({
       server = null;
       wss = null;
       twilioTokenWarningLogged = false;
+      telnyxSigWarningLogged = false;
       metricsStore;
       pricing;
       remoteHandler = new RemoteMessageHandler();
@@ -4123,6 +4414,31 @@ var init_server = __esm({
           mountApi(app, this.metricsStore, this.dashboardToken);
           getLogger().info("Dashboard: http://127.0.0.1:" + port + "/");
         }
+        app.post("/webhooks/twilio/status", (req, res) => {
+          if (this.config.twilioToken) {
+            const signature = req.headers["x-twilio-signature"] || "";
+            const url = `https://${this.config.webhookUrl}${req.originalUrl}`;
+            const params = req.body ?? {};
+            if (!validateTwilioSignature(url, params, signature, this.config.twilioToken)) {
+              res.status(403).send("Invalid signature");
+              return;
+            }
+          }
+          const body = req.body;
+          const callSid = sanitizeLogValue(body["CallSid"] ?? "");
+          const callStatus = sanitizeLogValue(body["CallStatus"] ?? "");
+          const duration = body["CallDuration"] ?? body["Duration"] ?? "";
+          getLogger().info(
+            `Twilio status ${callStatus} for call ${callSid} (duration=${duration})`
+          );
+          if (callSid && callStatus) {
+            const extra = {};
+            const parsed = parseFloat(duration);
+            if (!Number.isNaN(parsed)) extra.duration_seconds = parsed;
+            this.metricsStore.updateCallStatus(callSid, callStatus, extra);
+          }
+          res.status(204).send();
+        });
         app.post("/webhooks/twilio/recording", (req, res) => {
           if (this.config.twilioToken) {
             const signature = req.headers["x-twilio-signature"] || "";
@@ -4208,7 +4524,7 @@ var init_server = __esm({
           const twiml = `<?xml version="1.0" encoding="UTF-8"?><Response><Connect><Stream url="${xmlStreamUrl}"><Parameter name="caller" value="${xmlEscape(caller)}"/><Parameter name="callee" value="${xmlEscape(callee)}"/></Stream></Connect></Response>`;
           res.type("text/xml").send(twiml);
         });
-        app.post("/webhooks/telnyx/voice", (req, res) => {
+        app.post("/webhooks/telnyx/voice", async (req, res) => {
           if (this.config.telnyxPublicKey) {
             const rawBody = req.rawBody ?? "";
             const signature = req.headers["telnyx-signature-ed25519"] ?? "";
@@ -4217,7 +4533,8 @@ var init_server = __esm({
               getLogger().warn("Telnyx webhook rejected: invalid or missing Ed25519 signature");
               return res.status(403).send("Invalid signature");
             }
-          } else {
+          } else if (!this.telnyxSigWarningLogged) {
+            this.telnyxSigWarningLogged = true;
             getLogger().warn("Telnyx webhook signature verification is disabled. Set telnyxPublicKey in LocalOptions for production use.");
           }
           const body = req.body;
@@ -4227,41 +4544,77 @@ var init_server = __esm({
           if (typeof body.data.event_type !== "string" || typeof body.data.payload !== "object" || body.data.payload === null) {
             return res.status(400).send("Invalid body");
           }
-          const eventType = body?.data?.event_type ?? "";
+          const eventType = body.data.event_type ?? "";
+          const payload = body.data.payload ?? {};
           if (eventType === "call.dtmf.received") {
-            const digit = String(body.data?.payload?.digit ?? "").trim();
+            const digit = String(payload.digit ?? "").trim();
             if (digit) {
               getLogger().info(`Telnyx DTMF received (webhook): ${sanitizeLogValue(digit)}`);
             }
-            return res.json({ received: true });
+            return res.status(200).send();
           }
           if (eventType === "call.recording.saved") {
-            const recordingUrl = body.data?.payload?.recording_urls?.mp3 ?? body.data?.payload?.recording_urls?.wav ?? body.data?.payload?.public_recording_urls?.mp3 ?? "";
+            const recordingUrl = payload.recording_urls?.mp3 ?? payload.recording_urls?.wav ?? payload.public_recording_urls?.mp3 ?? "";
             if (recordingUrl) {
               getLogger().info(`Telnyx recording saved (webhook): ${sanitizeLogValue(recordingUrl)}`);
             }
-            return res.json({ received: true });
-          }
-          if (eventType === "call.initiated") {
-            const payload = body?.data?.payload ?? {};
-            const callControlId = payload.call_control_id ?? "";
-            const caller = payload.from ?? "";
-            const callee = payload.to ?? "";
-            const streamUrl = `wss://${this.config.webhookUrl}/ws/stream/${encodeURIComponent(callControlId)}?caller=${encodeURIComponent(caller)}&callee=${encodeURIComponent(callee)}`;
-            const commands = [
-              { command: "answer" },
-              {
-                command: "stream_start",
-                params: {
+            return res.status(200).send();
+          }
+          const callControlId = payload.call_control_id ?? "";
+          if (!callControlId) {
+            getLogger().warn("Telnyx webhook rejected: missing call_control_id");
+            return res.status(400).send("Invalid webhook payload");
+          }
+          const apiKey = this.config.telnyxKey;
+          if (!apiKey) {
+            getLogger().warn("Telnyx webhook: missing telnyxKey in LocalOptions");
+            return res.status(500).send("Missing Telnyx API key");
+          }
+          const apiBase = "https://api.telnyx.com/v2";
+          const authHeaders = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`
+          };
+          try {
+            if (eventType === "call.initiated") {
+              getLogger().info(`Telnyx call.initiated ${callControlId} \u2014 answering`);
+              const resp = await fetch(`${apiBase}/calls/${encodeURIComponent(callControlId)}/actions/answer`, {
+                method: "POST",
+                headers: authHeaders,
+                body: JSON.stringify({}),
+                signal: AbortSignal.timeout(1e4)
+              });
+              if (!resp.ok) {
+                getLogger().warn(`Telnyx answer failed: ${resp.status} ${(await resp.text()).slice(0, 200)}`);
+              }
+            } else if (eventType === "call.answered") {
+              const caller = payload.from ?? "";
+              const callee = payload.to ?? "";
+              const streamUrl = `wss://${this.config.webhookUrl}/ws/stream/${encodeURIComponent(callControlId)}?caller=${encodeURIComponent(caller)}&callee=${encodeURIComponent(callee)}`;
+              getLogger().info(`Telnyx call.answered ${callControlId} \u2014 starting stream`);
+              const resp = await fetch(`${apiBase}/calls/${encodeURIComponent(callControlId)}/actions/streaming_start`, {
+                method: "POST",
+                headers: authHeaders,
+                body: JSON.stringify({
                   stream_url: streamUrl,
-                  stream_track: "both_tracks"
-                }
+                  stream_track: "both_tracks",
+                  stream_bidirectional_mode: "rtp",
+                  stream_bidirectional_codec: "PCMU",
+                  stream_bidirectional_sampling_rate: 8e3,
+                  stream_bidirectional_target_legs: "self"
+                }),
+                signal: AbortSignal.timeout(1e4)
+              });
+              if (!resp.ok) {
+                getLogger().warn(`Telnyx streaming_start failed: ${resp.status} ${(await resp.text()).slice(0, 200)}`);
               }
-            ];
-            res.json({ commands });
-          } else {
-            res.json({ received: true });
+            } else {
+              getLogger().debug(`Telnyx event ignored: ${eventType}`);
+            }
+          } catch (e) {
+            getLogger().error(`Telnyx webhook handler error: ${String(e)}`);
           }
+          return res.status(200).send();
         });
         this.server = (0, import_http.createServer)(app);
         this.wss = new import_ws5.WebSocketServer({ noServer: true });
@@ -4408,11 +4761,12 @@ Connect AI agents to phone numbers in 4 lines of code
               getLogger().error("Failed to parse Telnyx WS message:", e);
               return;
             }
-            const eventType = data.event_type ?? "";
-            getLogger().info(`Telnyx event: ${eventType}`);
-            if (eventType === "stream_started" && !streamStarted) {
+            const event = data.event ?? "";
+            if (event === "connected") return;
+            getLogger().info(`Telnyx event: ${event}`);
+            if (event === "start" && !streamStarted) {
               streamStarted = true;
-              const callControlId = data.payload?.call_control_id ?? "";
+              const callControlId = data.start?.call_control_id ?? "";
               if (callControlId) this.activeCallIds.set(ws, callControlId);
               await handler.handleCallStart(callControlId);
               if (this.recording) {
@@ -4422,22 +4776,21 @@ Connect AI agents to phone numbers in 4 lines of code
                   getLogger().warn(`Could not start recording: ${String(e)}`);
                 }
               }
-            } else if (eventType === "media") {
-              const audioChunk = data.payload?.audio?.chunk ?? "";
+            } else if (event === "media") {
+              const track = data.media?.track ?? "inbound";
+              if (track !== "inbound") return;
+              const audioChunk = data.media?.payload ?? "";
               if (!audioChunk) return;
               handler.handleAudio(Buffer.from(audioChunk, "base64"));
-            } else if (eventType === "call.dtmf.received") {
-              const digit = String(data.payload?.digit ?? "").trim();
+            } else if (event === "dtmf") {
+              const digit = String(data.dtmf?.digit ?? "").trim();
               if (digit) {
                 getLogger().info(`Telnyx DTMF received: ${digit}`);
                 await handler.handleDtmf(digit);
               }
-            } else if (eventType === "call.recording.saved") {
-              const recordingUrl = data.payload?.recording_urls?.mp3 ?? data.payload?.recording_urls?.wav ?? data.payload?.public_recording_urls?.mp3 ?? "";
-              if (recordingUrl) {
-                getLogger().info(`Telnyx recording saved: ${recordingUrl}`);
-              }
-            } else if (eventType === "stream_stopped") {
+            } else if (event === "error") {
+              getLogger().warn(`Telnyx stream error: ${JSON.stringify(data)}`);
+            } else if (event === "stop") {
               await handler.handleStop();
             }
           } catch (err) {
@@ -6748,13 +7101,21 @@ var STTConfigImpl = class {
   provider;
   apiKey;
   language;
-  constructor(provider, apiKey, language = "en") {
+  options;
+  constructor(provider, apiKey, language = "en", options) {
     this.provider = provider;
     this.apiKey = apiKey;
     this.language = language;
+    if (options) this.options = options;
   }
   toDict() {
-    return { provider: this.provider, api_key: this.apiKey, language: this.language };
+    const out = {
+      provider: this.provider,
+      api_key: this.apiKey,
+      language: this.language
+    };
+    if (this.options) out.options = { ...this.options };
+    return out;
   }
 };
 var TTSConfigImpl = class {
@@ -6771,7 +7132,15 @@ var TTSConfigImpl = class {
   }
 };
 function deepgram(opts) {
-  return new STTConfigImpl("deepgram", opts.apiKey, opts.language ?? "en");
+  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");
@@ -6782,11 +7151,42 @@ function elevenlabs(opts) {
 function openaiTts(opts) {
   return new TTSConfigImpl("openai", opts.apiKey, opts.voice ?? "alloy");
 }
+function cartesia(opts) {
+  return new TTSConfigImpl(
+    "cartesia",
+    opts.apiKey,
+    opts.voice ?? "f786b574-daa5-4673-aa0c-cbe3e8534c02"
+  );
+}
+function rime(opts) {
+  return new TTSConfigImpl("rime", opts.apiKey, opts.voice ?? "astra");
+}
+function lmnt(opts) {
+  return new TTSConfigImpl("lmnt", opts.apiKey, opts.voice ?? "leah");
+}
 
 // src/client.ts
 init_server();
 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;
@@ -6797,7 +7197,8 @@ var Patter = class {
   embeddedServer = null;
   tunnelHandle = null;
   constructor(options) {
-    if ("mode" in options && options.mode === "local") {
+    const isLocal = "mode" in options && options.mode === "local" || !("apiKey" in options) && ("twilioSid" in options && options.twilioSid || "telnyxKey" in options && options.telnyxKey);
+    if (isLocal) {
       const local = options;
       if (!local.phoneNumber) {
         throw new Error("Local mode requires phoneNumber");
@@ -6957,23 +7358,42 @@ var Patter = class {
         const telnyxKey = this.localConfig.telnyxKey ?? "";
         const connectionId = this.localConfig.telnyxConnectionId ?? "";
         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 ?? "";
@@ -6985,13 +7405,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;
       }
@@ -7006,6 +7432,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;
@@ -7088,11 +7529,15 @@ 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
+  // Provider helpers — mirror the Python classmethod factories so callers can
+  // write ``Patter.deepgram({ apiKey })`` without importing the top-level.
   static deepgram = deepgram;
   static whisper = whisper;
   static elevenlabs = elevenlabs;
   static openaiTts = openaiTts;
+  static cartesia = cartesia;
+  static rime = rime;
+  static lmnt = lmnt;
   static guardrail(opts) {
     return {
       name: opts.name,
@@ -7158,8 +7603,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;
@@ -7293,6 +7738,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
   // -----------------------------------------------------------------------
@@ -7815,13 +8291,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();
@@ -7843,8 +8343,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(() => {
@@ -7861,27 +8371,6 @@ 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/index.ts
 init_deepgram_stt();