getpatter 0.6.4 → 0.6.6

package/dist/index.js

@@ -5,10 +5,10 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __glob = (map) => (path6) => {
-  var fn = map[path6];
+var __glob = (map) => (path7) => {
+  var fn = map[path7];
   if (fn) return fn();
-  throw new Error("Module not found in bundle: " + path6);
+  throw new Error("Module not found in bundle: " + path7);
 };
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
@@ -118,6 +118,110 @@ var init_errors = __esm({
   }
 });
 
+// src/telemetry/call-metrics.ts
+function engineFromMode(mode) {
+  if (mode === "openai_realtime" || mode === "openai_realtime_2") return "realtime";
+  if (mode === "elevenlabs_convai") return "convai";
+  if (mode === "pipeline") return "pipeline";
+  return "other";
+}
+function providerFromMetrics(m) {
+  const mode = m.provider_mode;
+  if (mode === "openai_realtime" || mode === "openai_realtime_2") return "openai";
+  if (mode === "elevenlabs_convai") return "elevenlabs";
+  for (const key of ["llm_provider", "stt_provider", "tts_provider"]) {
+    const v = m[key];
+    if (typeof v === "string" && v) return v.toLowerCase();
+  }
+  return "other";
+}
+function providerFromMode(mode) {
+  if (mode === "openai_realtime" || mode === "openai_realtime_2") return "openai";
+  if (mode === "elevenlabs_convai") return "elevenlabs";
+  return "other";
+}
+function carrierFamily(tp) {
+  return typeof tp === "string" && tp ? tp.toLowerCase() : "none";
+}
+function direction(value) {
+  const v = typeof value === "string" ? value.toLowerCase() : "";
+  return v === "inbound" || v === "outbound" ? v : void 0;
+}
+function turnCountBucket(n) {
+  if (n <= 0) return "0";
+  if (n === 1) return "1";
+  if (n <= 3) return "2_3";
+  if (n <= 6) return "4_6";
+  if (n <= 12) return "7_12";
+  return "13_plus";
+}
+function latencyMs(m) {
+  const p95 = m.latency_p95;
+  if (p95 && typeof p95 === "object") {
+    return p95.agent_response_ms;
+  }
+  return void 0;
+}
+function recordCallStarted(telemetry, opts) {
+  if (!telemetry) return;
+  try {
+    const dims = {
+      engine: engineFromMode(opts.providerMode),
+      provider: providerFromMode(opts.providerMode),
+      carrier: carrierFamily(opts.telephonyProvider)
+    };
+    const d = direction(opts.direction);
+    if (d !== void 0) dims.direction = d;
+    telemetry.record("call_started", dims);
+  } catch {
+  }
+}
+function recordCallCompleted(telemetry, opts) {
+  if (!telemetry) return;
+  try {
+    const dims = { outcome: opts.outcome };
+    const d = direction(opts.direction);
+    if (d !== void 0) dims.direction = d;
+    const metrics = opts.metrics;
+    if (metrics && typeof metrics === "object") {
+      const m = metrics;
+      dims.engine = engineFromMode(m.provider_mode);
+      dims.provider = providerFromMetrics(m);
+      dims.carrier = carrierFamily(m.telephony_provider);
+      if (typeof m.duration_seconds === "number") {
+        dims.duration_seconds = Math.max(0, Math.round(m.duration_seconds));
+      }
+      const lat = latencyMs(m);
+      if (typeof lat === "number") dims.latency_ms = Math.max(0, Math.round(lat));
+      const cost = m.cost;
+      if (cost && typeof cost === "object") {
+        const total = cost.total;
+        if (typeof total === "number" && Number.isFinite(total)) {
+          dims.cost_usd = Math.max(0, Math.round(total * 1e4) / 1e4);
+        }
+      }
+      if (Array.isArray(m.turns)) {
+        dims.turn_count_bucket = turnCountBucket(m.turns.length);
+      }
+      const errorCode = m.error_code;
+      if (typeof errorCode === "string" && errorCode) {
+        dims.error_code = errorCode;
+        dims.outcome = "error";
+      }
+    } else if (opts.carrier !== void 0) {
+      dims.carrier = carrierFamily(opts.carrier);
+    }
+    telemetry.record("call_completed", dims);
+  } catch {
+  }
+}
+var init_call_metrics = __esm({
+  "src/telemetry/call-metrics.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
 // src/logger.ts
 function getLogger() {
   return currentLogger;
@@ -2171,10 +2275,10 @@ var init_plivo_adapter = __esm({
         this.baseUrl = `${PLIVO_API_BASE}/Account/${encodeURIComponent(authId)}`;
         this.authHeader = `Basic ${Buffer.from(`${authId}:${authToken}`).toString("base64")}`;
       }
-      async request(method, path6, jsonBody) {
+      async request(method, path7, jsonBody) {
         const headers = { Authorization: this.authHeader };
         if (jsonBody !== void 0) headers["Content-Type"] = "application/json";
-        const response = await fetch(`${this.baseUrl}${path6}`, {
+        const response = await fetch(`${this.baseUrl}${path7}`, {
           method,
           headers,
           body: jsonBody !== void 0 ? JSON.stringify(jsonBody) : void 0,
@@ -2182,7 +2286,7 @@ var init_plivo_adapter = __esm({
         });
         const text = await response.text();
         if (!response.ok && response.status !== 404) {
-          throw new Error(`Plivo ${method} ${path6} failed: ${response.status} ${text}`);
+          throw new Error(`Plivo ${method} ${path7} failed: ${response.status} ${text}`);
         }
         let data = {};
         if (text) {
@@ -3705,9 +3809,9 @@ function loadDashboardHtml() {
     (0, import_node_path.join)(here, "dashboard", "ui.html"),
     (0, import_node_path.join)(here, "..", "dashboard", "ui.html")
   ];
-  for (const path6 of candidates) {
+  for (const path7 of candidates) {
     try {
-      return (0, import_node_fs.readFileSync)(path6, "utf8");
+      return (0, import_node_fs.readFileSync)(path7, "utf8");
     } catch {
     }
   }
@@ -4599,6 +4703,9 @@ var init_metrics = __esm({
       ttsModel;
       realtimeModel;
       _pricing;
+      // Terminal error code (lowercased ErrorCode value or "other"); set by
+      // recordError when the call ends abnormally. Empty for a clean call.
+      _errorCode = "";
       _callStart;
       _turns = [];
       // mutable internal array; immutable when exposed via TurnMetrics[] → readonly TurnMetrics[]
@@ -5169,11 +5276,35 @@ var init_metrics = __esm({
           telephony_provider: this.telephonyProvider,
           stt_model: this.sttModel,
           tts_model: this.ttsModel,
-          llm_model: this._llmModel
+          llm_model: this._llmModel,
+          error_code: this._errorCode
         };
         this._eventBus?.emit("call_ended", { callId: this.callId, metrics });
         return metrics;
       }
+      /**
+       * Record the call's terminal error as a coarse, anonymous code. Stores the
+       * PatterError `.code` lowercased; maps common timeout/connection errors; falls
+       * back to "other". Never stores the message. Last write wins.
+       */
+      recordError(err) {
+        const code = err?.code;
+        const name = err?.name;
+        const sys = typeof code === "string" ? code : "";
+        if (sys.startsWith("ECONN") || sys === "EHOSTUNREACH" || sys === "ENETUNREACH" || sys === "EPIPE") {
+          this._errorCode = "connection";
+          return;
+        }
+        if (typeof code === "string" && code) {
+          this._errorCode = code.toLowerCase();
+          return;
+        }
+        if (name === "TimeoutError" || name === "AbortError") {
+          this._errorCode = "timeout";
+        } else {
+          this._errorCode = "other";
+        }
+      }
       /** Return the cost breakdown for the call so far without ending it. */
       getCostSoFar() {
         const duration3 = (hrTimeMs() - this._callStart) / 1e3;
@@ -5963,7 +6094,7 @@ var init_llm_loop = __esm({
         });
         if (!response.ok) {
           const errText = await response.text();
-          getLogger().error(`LLM API error: ${response.status} ${errText}`);
+          getLogger().error(`LLM API error: ${response.status} ${errText.slice(0, 200)}`);
           throw new PatterConnectionError(
             `LLM API returned ${response.status}: ${errText.slice(0, 200)}`
           );
@@ -6131,12 +6262,22 @@ ${systemPrompt}` : DEFAULT_PHONE_PREAMBLE;
         const hasAfterLlmResponse = Boolean(hookExecutor?.hasAfterLlmResponse() && hookCtx);
         const hasAfterLlmChunk = Boolean(hookExecutor?.hasAfterLlmChunk());
         const allEmittedText = [];
+        const callId = callContext.call_id;
+        const caller = callContext.caller;
+        const callee = callContext.callee;
+        const hasContext = typeof callId === "string" && callId.length > 0 || typeof caller === "string" && caller.length > 0 || typeof callee === "string" && callee.length > 0;
+        const streamOpts = hasContext ? {
+          ...opts,
+          ...typeof callId === "string" && callId.length > 0 ? { callId } : {},
+          ...typeof caller === "string" && caller.length > 0 ? { caller } : {},
+          ...typeof callee === "string" && callee.length > 0 ? { callee } : {}
+        } : opts;
         for (let iter = 0; iter < maxIterations; iter++) {
           const toolCallsAccumulated = /* @__PURE__ */ new Map();
           const textParts = [];
           let hasToolCalls = false;
           let usageChunkReceived = false;
-          for await (const chunk of this.provider.stream(messages, this.openaiTools, opts)) {
+          for await (const chunk of this.provider.stream(messages, this.openaiTools, streamOpts)) {
             if (chunk.type === "text" && chunk.content) {
               const content = hasAfterLlmChunk && hookExecutor ? hookExecutor.runAfterLlmChunk(chunk.content) : chunk.content;
               textParts.push(content);
@@ -6264,6 +6405,7 @@ ${systemPrompt}` : DEFAULT_PHONE_PREAMBLE;
           { role: "system", content: this.systemPrompt }
         ];
         for (const entry of history) {
+          if (entry.role === "tool") continue;
           messages.push({
             role: entry.role === "assistant" ? "assistant" : "user",
             content: entry.text
@@ -6541,10 +6683,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path6) {
-  if (!path6)
+function getElementAtPath(obj, path7) {
+  if (!path7)
     return obj;
-  return path6.reduce((acc, key) => acc?.[key], obj);
+  return path7.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -6872,11 +7014,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path6, issues) {
+function prefixIssues(path7, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path6);
+    iss.path.unshift(path7);
     return iss;
   });
 }
@@ -7095,16 +7237,16 @@ function flattenError(error2, mapper = (issue2) => issue2.message) {
 }
 function formatError(error2, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error3, path6 = []) => {
+  const processError = (error3, path7 = []) => {
     for (const issue2 of error3.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path6, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path7, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path6, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path7, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path6, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path7, ...issue2.path]);
       } else {
-        const fullpath = [...path6, ...issue2.path];
+        const fullpath = [...path7, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -17908,20 +18050,20 @@ var require_compile = __commonJS({
     var util_1 = require_util();
     var validate_1 = require_validate();
     var SchemaEnv = class {
-      constructor(env) {
+      constructor(env2) {
         var _a3;
         this.refs = {};
         this.dynamicAnchors = {};
         let schema;
-        if (typeof env.schema == "object")
-          schema = env.schema;
-        this.schema = env.schema;
-        this.schemaId = env.schemaId;
-        this.root = env.root || this;
-        this.baseId = (_a3 = env.baseId) !== null && _a3 !== void 0 ? _a3 : (0, resolve_1.normalizeId)(schema === null || schema === void 0 ? void 0 : schema[env.schemaId || "$id"]);
-        this.schemaPath = env.schemaPath;
-        this.localRefs = env.localRefs;
-        this.meta = env.meta;
+        if (typeof env2.schema == "object")
+          schema = env2.schema;
+        this.schema = env2.schema;
+        this.schemaId = env2.schemaId;
+        this.root = env2.root || this;
+        this.baseId = (_a3 = env2.baseId) !== null && _a3 !== void 0 ? _a3 : (0, resolve_1.normalizeId)(schema === null || schema === void 0 ? void 0 : schema[env2.schemaId || "$id"]);
+        this.schemaPath = env2.schemaPath;
+        this.localRefs = env2.localRefs;
+        this.meta = env2.meta;
         this.$async = schema === null || schema === void 0 ? void 0 : schema.$async;
         this.refs = {};
       }
@@ -18105,15 +18247,15 @@ var require_compile = __commonJS({
           baseId = (0, resolve_1.resolveUrl)(this.opts.uriResolver, baseId, schId);
         }
       }
-      let env;
+      let env2;
       if (typeof schema != "boolean" && schema.$ref && !(0, util_1.schemaHasRulesButRef)(schema, this.RULES)) {
         const $ref = (0, resolve_1.resolveUrl)(this.opts.uriResolver, baseId, schema.$ref);
-        env = resolveSchema.call(this, root, $ref);
+        env2 = resolveSchema.call(this, root, $ref);
       }
       const { schemaId } = this.opts;
-      env = env || new SchemaEnv({ schema, schemaId, root, baseId });
-      if (env.schema !== env.root.schema)
-        return env;
+      env2 = env2 || new SchemaEnv({ schema, schemaId, root, baseId });
+      if (env2.schema !== env2.root.schema)
+        return env2;
       return void 0;
     }
   }
@@ -18265,8 +18407,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path6) {
-      let input = path6;
+    function removeDotSegments(path7) {
+      let input = path7;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -18519,8 +18661,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path6, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path6 && path6 !== "/" ? path6 : void 0;
+        const [path7, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path7 && path7 !== "/" ? path7 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -19608,8 +19750,8 @@ var require_ref = __commonJS({
       schemaType: "string",
       code(cxt) {
         const { gen, schema: $ref, it } = cxt;
-        const { baseId, schemaEnv: env, validateName, opts, self } = it;
-        const { root } = env;
+        const { baseId, schemaEnv: env2, validateName, opts, self } = it;
+        const { root } = env2;
         if (($ref === "#" || $ref === "#/") && baseId === root.baseId)
           return callRootRef();
         const schOrEnv = compile_1.resolveRef.call(self, root, baseId, $ref);
@@ -19619,8 +19761,8 @@ var require_ref = __commonJS({
           return callValidate(schOrEnv);
         return inlineRefSchema(schOrEnv);
         function callRootRef() {
-          if (env === root)
-            return callRef(cxt, validateName, env, env.$async);
+          if (env2 === root)
+            return callRef(cxt, validateName, env2, env2.$async);
           const rootName = gen.scopeValue("root", { ref: root });
           return callRef(cxt, (0, codegen_1._)`${rootName}.validate`, root, root.$async);
         }
@@ -19650,14 +19792,14 @@ var require_ref = __commonJS({
     exports2.getValidate = getValidate;
     function callRef(cxt, v, sch, $async) {
       const { gen, it } = cxt;
-      const { allErrors, schemaEnv: env, opts } = it;
+      const { allErrors, schemaEnv: env2, opts } = it;
       const passCxt = opts.passContext ? names_1.default.this : codegen_1.nil;
       if ($async)
         callAsyncRef();
       else
         callSyncRef();
       function callAsyncRef() {
-        if (!env.$async)
+        if (!env2.$async)
           throw new Error("async schema referenced by sync schema");
         const valid = gen.let("valid");
         gen.try(() => {
@@ -21959,12 +22101,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs6, exportName) {
+    function addFormats(ajv, list, fs8, exportName) {
       var _a3;
       var _b;
       (_a3 = (_b = ajv.opts.code).formats) !== null && _a3 !== void 0 ? _a3 : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs6[f]);
+        ajv.addFormat(f, fs8[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -27781,6 +27923,26 @@ function isSttHallucination(text) {
   const pieces = stripped.split(/[.!?…。！？]+/u).map((p) => p.trim()).filter((p) => p.length > 0);
   return pieces.length > 1 && pieces.every((p) => HALLUCINATIONS.has(p));
 }
+function normalizeForEcho(text) {
+  return text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/u, " ").trim().replace(/\s+/gu, " ");
+}
+function looksLikeEcho(candidate, agentText) {
+  const a = normalizeForEcho(agentText);
+  const c = normalizeForEcho(candidate);
+  if (!a || !c) return false;
+  const words = c.split(" ").filter(Boolean);
+  if (words.length < ECHO_MIN_CANDIDATE_WORDS) return false;
+  if (a.includes(c)) return true;
+  const agentWords = new Set(a.split(" "));
+  const overlap = words.filter((w) => agentWords.has(w)).length / words.length;
+  return overlap >= ECHO_WORD_OVERLAP_THRESHOLD;
+}
+function isNearDuplicate(a, b) {
+  if (!a || !b) return false;
+  if (a === b) return true;
+  const [shorter, longer] = a.length <= b.length ? [a, b] : [b, a];
+  return longer.startsWith(shorter + " ");
+}
 async function queryDeepgramCost(metricsAcc, deepgramKey, deepgramRequestId) {
   try {
     const projResp = await fetch("https://api.deepgram.com/v1/projects", {
@@ -27811,7 +27973,7 @@ async function queryDeepgramCost(metricsAcc, deepgramKey, deepgramRequestId) {
   } catch {
   }
 }
-var DEFAULT_TOOL_CALL_PREAMBLE_BLOCK, HALLUCINATIONS, StreamHandler;
+var DEFAULT_TOOL_CALL_PREAMBLE_BLOCK, HALLUCINATIONS, ECHO_WORD_OVERLAP_THRESHOLD, ECHO_MIN_CANDIDATE_WORDS, StreamHandler;
 var init_stream_handler = __esm({
   "src/stream-handler.ts"() {
     "use strict";
@@ -27924,6 +28086,8 @@ Avoid:
       "[blank_audio]",
       "(silence)"
     ]);
+    ECHO_WORD_OVERLAP_THRESHOLD = 0.6;
+    ECHO_MIN_CANDIDATE_WORDS = 4;
     StreamHandler = class _StreamHandler {
       deps;
       ws;
@@ -27936,6 +28100,17 @@ Avoid:
       stt = null;
       tts = null;
       isSpeaking = false;
+      /**
+       * True only while the post-TTS tail-grace window is pending: the agent has
+       * finished its turn but ``isSpeaking`` is still held for
+       * ``PATTER_TTS_TAIL_GRACE_MS`` to swallow the fading echo tail. A VAD
+       * ``speech_start`` (or a transcript) during this window is the user's NEXT
+       * turn, not a barge-in — there is nothing left to interrupt. Set by
+       * ``endSpeakingWithGrace``; cleared by ``beginSpeaking``, the grace flip,
+       * ``cancelSpeaking``, and ``endTailGraceForNewTurn``. Parity with Python
+       * ``_tail_grace_active``.
+       */
+      tailGraceActive = false;
       /**
        * Ring buffer of inbound PCM16 16 kHz frames captured while the agent
        * is speaking and the self-hearing guard is dropping audio. On
@@ -28011,6 +28186,35 @@ Avoid:
        * ``isSpeaking=false``, and silently cut the agent's first turn.
        */
       firstAudioSentAt = null;
+      /**
+       * Estimated wall-clock (ms) when the LAST audio byte pushed to the carrier
+       * finishes PLAYING on the phone. The pipeline pushes TTS audio as fast as
+       * the provider synthesizes it (no pacing) and the carrier buffers + plays
+       * at realtime, so "we finished pushing" and "the caller finished hearing"
+       * can diverge by tens of seconds — especially with agent-runtime LLMs
+       * (Hermes/OpenClaw) that deliver a long reply all at once after a thinking
+       * pause. ``endSpeakingWithGrace`` holds ``isSpeaking=true`` (with
+       * ``tailGraceActive=false``) until this cursor passes, so a barge-in during
+       * the audible backlog still takes the cancel path (``sendClear`` drops the
+       * carrier buffer) instead of being treated as a calm next turn. Advanced by
+       * ``trackOutboundPlayback``; reset by ``cancelSpeaking`` (the buffer is
+       * cleared) and ``endTailGraceForNewTurn``.
+       */
+      playbackBufferedUntil = 0;
+      /**
+       * Per-turn playback timeline used to estimate the response prefix the
+       * caller actually HEARD when a barge-in lands. ``turnPlaybackTotalMs``
+       * accumulates the playout duration of every chunk pushed this turn
+       * (including filler audio, which keeps the timeline aligned);
+       * ``turnSpokenSegments`` records ``{text, startMs}`` for each RESPONSE
+       * sentence at its first audible chunk (filler / error-fallback audio
+       * advances the clock but adds no segment). ``heard = total - backlog``
+       * then maps to a sentence-granular prefix — see ``heardResponsePrefix``.
+       * Both reset at ``beginSpeaking``. Mirrors Python
+       * ``_turn_playback_total_s`` / ``_turn_spoken_segments``.
+       */
+      turnPlaybackTotalMs = 0;
+      turnSpokenSegments = [];
       /**
        * Optional barge-in confirmation strategies. With an empty array the
        * SDK falls back to the legacy "cancel on first VAD speech_start"
@@ -28128,11 +28332,15 @@ Avoid:
         }
         this.speakingGeneration++;
         this.isSpeaking = true;
+        this.tailGraceActive = false;
         this.speakingStartedAt = Date.now();
         this.suppressedSpeechPending = false;
         void isFirstMessage;
         this.firstAudioSentAt = Date.now();
         this.inboundAudioRing = [];
+        this.currentAgentSpokenText = "";
+        this.turnPlaybackTotalMs = 0;
+        this.turnSpokenSegments = [];
         this.resetVad();
       }
       /**
@@ -28147,6 +28355,87 @@ Avoid:
           this.firstAudioSentAt = Date.now();
         }
       }
+      /**
+       * Advance ``playbackBufferedUntil`` by the playout duration of an outbound
+       * TTS chunk. ``numBytes`` is the size of the chunk BEFORE carrier encoding
+       * (the same buffer handed to ``encodePipelineAudio``): PCM16 @ 16 kHz in
+       * the default path (32 bytes/ms), or the carrier's native μ-law @ 8 kHz
+       * (8 bytes/ms) when the TTS adapter emits wire format directly
+       * (``ttsOutputFormatNativeForCarrier`` — Twilio/Plivo ``ulaw_8000``;
+       * Telnyx native is ``pcm_16000`` so it stays at 32 bytes/ms).
+       */
+      trackOutboundPlayback(numBytes) {
+        if (numBytes <= 0) return;
+        const bytesPerMs = this.ttsOutputFormatNativeForCarrier && this.deps.bridge.telephonyProvider !== "telnyx" ? 8 : 32;
+        const now = Date.now();
+        const chunkMs = numBytes / bytesPerMs;
+        const base = this.playbackBufferedUntil > now ? this.playbackBufferedUntil : now;
+        this.playbackBufferedUntil = base + chunkMs;
+        this.turnPlaybackTotalMs += chunkMs;
+      }
+      /**
+       * Estimate the response prefix the caller actually HEARD this turn.
+       *
+       * The pipeline pushes audio faster than realtime, so at barge-in time
+       * ``heard = totalPushed - carrierBacklog`` ms of audio have actually
+       * played. Mapped at sentence granularity against ``turnSpokenSegments``:
+       * a sentence counts as heard once its playback has STARTED
+       * (``startMs <= heardMs``), so the sentence playing at the moment of
+       * interruption is included.
+       *
+       * Returns ``null`` when no segments were tracked this turn (nothing
+       * synthesized through the tracked path — callers fall back to the legacy
+       * full-text behaviour). Mirrors Python ``_heard_response_prefix``.
+       */
+      heardResponsePrefix() {
+        if (this.turnSpokenSegments.length === 0) return null;
+        const remainingMs = Math.max(0, this.playbackBufferedUntil - Date.now());
+        const heardMs = Math.max(0, this.turnPlaybackTotalMs - remainingMs);
+        const heard = this.turnSpokenSegments.filter((s) => s.startMs <= heardMs);
+        return {
+          text: heard.map((s) => s.text).join(" "),
+          heardEverything: heard.length === this.turnSpokenSegments.length
+        };
+      }
+      /**
+       * Replace the text of the most recent assistant entry in the conversation
+       * history. No-op when the last entry is not an assistant turn (e.g. the
+       * caller's next turn was already committed).
+       */
+      rewriteLastAssistantEntry(text) {
+        const entries = this.history.entries;
+        const last = entries[entries.length - 1];
+        if (last && last.role === "assistant") {
+          entries[entries.length - 1] = { ...last, text };
+        }
+      }
+      /**
+       * LiveKit-style "heard prefix" semantics for a barge-in that lands AFTER
+       * the turn completed, while the carrier is still playing the buffered
+       * tail.
+       *
+       * The completed turn already recorded its FULL reply in history, but the
+       * caller only heard part of it before interrupting — a stateful agent
+       * runtime (Hermes / OpenClaw) would otherwise "remember saying" things
+       * the caller never heard. Rewrites the last assistant entry to the heard
+       * prefix + ``[interrupted by caller]``.
+       *
+       * MUST run BEFORE ``cancelSpeaking`` resets ``playbackBufferedUntil``
+       * (the backlog is the heard-prefix input). No-op when a turn is still in
+       * flight (the streaming path applies its own marker), when there is no
+       * backlog, or when everything was already heard. Mirrors Python
+       * ``_maybe_truncate_completed_turn_history``.
+       */
+      maybeTruncateCompletedTurnHistory() {
+        if (this.dispatchTask !== null) return;
+        const remainingMs = this.playbackBufferedUntil - Date.now();
+        if (remainingMs <= 0) return;
+        const heard = this.heardResponsePrefix();
+        if (heard === null || heard.heardEverything) return;
+        this.rewriteLastAssistantEntry(
+          heard.text ? `${heard.text} [interrupted by caller]` : "[interrupted by caller]"
+        );
+      }
       /**
        * Atomically end speaking AND invalidate any pending grace timer.
        * Use instead of ``this.isSpeaking = false`` at barge-in sites.
@@ -28157,10 +28446,12 @@ Avoid:
       cancelSpeaking() {
         this.speakingGeneration++;
         this.isSpeaking = false;
+        this.tailGraceActive = false;
         this.speakingStartedAt = null;
         this.firstAudioSentAt = null;
         this.lastCancelAt = Date.now();
         this.suppressedSpeechPending = false;
+        this.playbackBufferedUntil = 0;
         this.drainPendingMarks();
         if (this.llmAbort !== null) {
           try {
@@ -28233,23 +28524,37 @@ Avoid:
         if (grace > 0) {
           const gen = this.speakingGeneration;
           this.clearGraceTimer();
-          this.graceTimer = setTimeout(() => {
-            this.graceTimer = null;
-            if (this.speakingGeneration === gen) {
-              this.isSpeaking = false;
-              this.speakingStartedAt = null;
-              this.firstAudioSentAt = null;
-              this.clearPendingBargeIn();
-              void this.resetBargeInStrategies();
-              if (this.suppressedSpeechPending) {
-                this.suppressedSpeechPending = false;
-                this.flushInboundAudioRing();
+          const startTailGrace = () => {
+            this.tailGraceActive = true;
+            this.graceTimer = setTimeout(() => {
+              this.graceTimer = null;
+              if (this.speakingGeneration === gen) {
+                this.isSpeaking = false;
+                this.tailGraceActive = false;
+                this.speakingStartedAt = null;
+                this.firstAudioSentAt = null;
+                this.clearPendingBargeIn();
+                void this.resetBargeInStrategies();
+                if (this.suppressedSpeechPending) {
+                  this.suppressedSpeechPending = false;
+                  this.flushInboundAudioRing();
+                }
+                this.resetVad();
               }
-              this.resetVad();
-            }
-          }, grace);
+            }, grace);
+          };
+          const bufferedMs = Math.max(0, this.playbackBufferedUntil - Date.now());
+          if (bufferedMs <= 0) {
+            startTailGrace();
+          } else {
+            this.graceTimer = setTimeout(() => {
+              this.graceTimer = null;
+              if (this.speakingGeneration === gen) startTailGrace();
+            }, bufferedMs);
+          }
         } else {
           this.isSpeaking = false;
+          this.tailGraceActive = false;
           this.speakingStartedAt = null;
           this.firstAudioSentAt = null;
           this.clearPendingBargeIn();
@@ -28261,6 +28566,35 @@ Avoid:
           this.resetVad();
         }
       }
+      /**
+       * End the post-TTS tail-grace window because the user has begun their next
+       * turn. Unlike a barge-in, the agent's response already played out in full
+       * — there is nothing to cancel and no turn was interrupted. We flip the
+       * speaking flag off (bumping ``speakingGeneration`` so the scheduled grace
+       * timer no-ops), recover any leading audio the self-hearing guard captured
+       * into the ring (the user's first ~250 ms, which VAD needed before it could
+       * emit ``speech_start``), and let the live STT stream take over. We do NOT
+       * call ``sendClear``, ``recordBargeinDetected`` or ``recordTurnInterrupted``
+       * — none apply to a turn that completed normally.
+       *
+       * Without this, fast next-turn speech (humans reply in 200-700 ms, well
+       * inside the 1500 ms default grace) is withheld from STT and recorded as an
+       * empty ``[interrupted]`` turn, after which the agent goes silent for the
+       * rest of the call. Parity with Python ``_end_tail_grace_for_new_turn``.
+       */
+      endTailGraceForNewTurn() {
+        this.isSpeaking = false;
+        this.tailGraceActive = false;
+        this.speakingStartedAt = null;
+        this.firstAudioSentAt = null;
+        this.playbackBufferedUntil = 0;
+        this.speakingGeneration++;
+        this.clearGraceTimer();
+        this.clearPendingBargeIn();
+        void this.resetBargeInStrategies();
+        this.suppressedSpeechPending = false;
+        this.flushInboundAudioRing();
+      }
       async resetBargeInStrategies() {
         if (this.bargeInStrategies.length === 0) return;
         const { resetStrategies: resetStrategies2 } = await Promise.resolve().then(() => (init_barge_in_strategies(), barge_in_strategies_exports));
@@ -28396,9 +28730,43 @@ Avoid:
       maxDurationTimer = null;
       transcriptProcessing = false;
       transcriptQueue = [];
+      /**
+       * The in-flight turn dispatch (LLM + TTS) runs as a SINGLE tracked promise
+       * so the transcript drain loop keeps running ``handleBargeIn`` against the
+       * LIVE turn during a long (30-90 s) agent-runtime response, instead of
+       * head-of-line-blocking on it. Exactly one is in flight: the launcher awaits
+       * the previous one to settle (fast — a barge-in already aborted it) before
+       * starting the next, preserving history/metrics ordering. Parity with
+       * Python ``_dispatch_task``.
+       */
+      dispatchTask = null;
+      /**
+       * Cap (ms) on how long teardown waits for the backgrounded dispatch to
+       * settle. JS promises are not cancellable, so a user-supplied ``onMessage``
+       * (which receives no AbortSignal) parked on a hung external call could block
+       * call cleanup indefinitely — `llmAbort.abort()` only unblocks the built-in
+       * LLM/TTS paths. We bound the WAIT (Python hard-cancels the task instead).
+       * 30 s matches the webhook ceiling.
+       */
+      static DISPATCH_SETTLE_TIMEOUT_MS = 3e4;
+      /**
+       * Opt-in (default OFF): forward inbound audio to STT even while the agent is
+       * speaking, so the transcript barge-in path can receive a transcript on
+       * echo-masked PSTN links where the VAD never fires. ECHO RISK without AEC.
+       * Parity with Python ``_forward_stt_while_speaking``.
+       */
+      forwardSttWhileSpeaking = ["1", "true", "yes"].includes(
+        (process.env.PATTER_FORWARD_STT_WHILE_SPEAKING ?? "").trim().toLowerCase()
+      );
       // Throttle state for back-to-back STT finals — see ``commitTranscript``.
       lastCommitText = "";
       lastCommitAt = 0;
+      /** The agent's spoken text for the CURRENT turn, accumulated as tokens stream.
+       * The echo guard rejects transcripts matching it (the agent's own TTS bleeding
+       * back into STT when audio is forwarded during TTS without effective AEC).
+       * Reset in ``beginSpeaking``; only consulted while ``forwardSttWhileSpeaking``.
+       * Parity with Python ``_current_agent_spoken_text``. */
+      currentAgentSpokenText = "";
       // PCM16 byte-alignment carry for TTS streaming (pipeline mode).
       // HTTP streams from ElevenLabs / OpenAI / Cartesia can yield chunks of any
       // size, including odd byte counts. Silently dropping the trailing odd byte
@@ -28418,6 +28786,11 @@ Avoid:
         this.ws = ws;
         this.caller = caller;
         this.callee = callee;
+        if (this.forwardSttWhileSpeaking) {
+          getLogger().warn(
+            "PATTER_FORWARD_STT_WHILE_SPEAKING=on: inbound audio is sent to STT during TTS so transcript barge-in works on echo-masked links. Without AEC the agent's own voice may be transcribed as a phantom interruption \u2014 pair with agent.bargeInStrategies."
+          );
+        }
         this.bargeInStrategies = (deps.agent.bargeInStrategies ?? []).slice();
         const confirmMs = deps.agent.bargeInConfirmMs;
         this.bargeInConfirmMs = typeof confirmMs === "number" && Number.isFinite(confirmMs) && confirmMs > 0 ? confirmMs : 1500;
@@ -28617,12 +28990,12 @@ Avoid:
         } catch {
         }
         if (this.deps.onCallStart) {
-          const direction = this.deps.metricsStore.getActive(callId)?.direction ?? "inbound";
+          const direction2 = this.deps.metricsStore.getActive(callId)?.direction ?? "inbound";
           await this.deps.onCallStart({
             call_id: callId,
             caller: this.caller,
             callee: this.callee,
-            direction,
+            direction: direction2,
             telephony_provider: this.deps.bridge.telephonyProvider,
             ...Object.keys(customParams).length > 0 ? { custom_params: customParams } : {}
           });
@@ -28689,6 +29062,17 @@ Avoid:
       setStreamSid(sid) {
         this.streamSid = sid;
       }
+      /**
+       * Record a terminal/processing error as a coarse, anonymous code on the call
+       * metrics (code only, never the message). Surfaced via `call_completed`
+       * telemetry. Safe to call with any value; last write wins.
+       */
+      recordError(err) {
+        try {
+          this.metricsAcc.recordError(err);
+        } catch {
+        }
+      }
       /** Handle an incoming audio chunk (already decoded from base64). */
       /** Forward inbound audio bytes to the AI adapter and (in pipeline mode) the STT provider. */
       async handleAudio(audioBuffer) {
@@ -28715,6 +29099,9 @@ Avoid:
                 );
               }
               if (evt?.type === "speech_start") {
+                if (this.isSpeaking && this.tailGraceActive) {
+                  this.endTailGraceForNewTurn();
+                }
                 const phantomSuppressed = this.isSpeaking && !this.canBargeIn();
                 if (phantomSuppressed) {
                   getLogger().info(
@@ -28722,7 +29109,8 @@ Avoid:
                   );
                   this.suppressedSpeechPending = true;
                 } else if (this.isSpeaking) {
-                  if (this.bargeInStrategies.length > 0) {
+                  const deferCancel = this.bargeInStrategies.length > 0 || this.forwardSttWhileSpeaking && !this.aec;
+                  if (deferCancel) {
                     this.startPendingBargeIn();
                     this.metricsAcc.anchorUserSpeechStart();
                     return;
@@ -28732,6 +29120,7 @@ Avoid:
                   this.metricsAcc.recordBargeinDetected();
                   const bargeinSpan = startSpan(SPAN_BARGEIN, { "patter.call.id": this.callId });
                   try {
+                    this.maybeTruncateCompletedTurnHistory();
                     this.cancelSpeaking();
                     try {
                       this.deps.bridge.sendClear(this.ws, this.streamSid);
@@ -28776,9 +29165,10 @@ Avoid:
               if (this.inboundAudioRing.length > _StreamHandler.INBOUND_AUDIO_RING_FRAMES) {
                 this.inboundAudioRing.shift();
               }
+              if (!this.forwardSttWhileSpeaking) return;
+            } else if ((this.deps.agent.bargeInThresholdMs ?? 300) === 0) {
               return;
             }
-            if ((this.deps.agent.bargeInThresholdMs ?? 300) === 0) return;
           }
           const hooks = this.deps.agent.hooks;
           if (hooks?.beforeSendToStt) {
@@ -28840,6 +29230,27 @@ Avoid:
           }
         }
       }
+      /**
+       * Await the backgrounded turn dispatch during teardown, but never block
+       * longer than ``DISPATCH_SETTLE_TIMEOUT_MS``. The earlier ``llmAbort.abort()``
+       * settles the built-in LLM/TTS paths immediately; the cap only bites a
+       * misbehaving user ``onMessage`` parked on a hung external call (JS promises
+       * can't be cancelled). No-op when nothing is in flight.
+       */
+      async settleDispatchForTeardown() {
+        if (!this.dispatchTask) return;
+        const settle = this.dispatchTask.catch(() => {
+        });
+        let timer;
+        const cap = new Promise((resolve2) => {
+          timer = setTimeout(resolve2, _StreamHandler.DISPATCH_SETTLE_TIMEOUT_MS);
+        });
+        try {
+          await Promise.race([settle, cap]);
+        } finally {
+          if (timer) clearTimeout(timer);
+        }
+      }
       /** Handle call stop / stream end. */
       /** Handle a carrier-emitted `stop` event signalling the call has ended. */
       async handleStop() {
@@ -28856,6 +29267,7 @@ Avoid:
           } catch {
           }
         }
+        await this.settleDispatchForTeardown();
         this.clearPendingBargeIn();
         this.drainPendingMarks();
         this.clearGraceTimer();
@@ -28883,6 +29295,7 @@ Avoid:
           } catch {
           }
         }
+        await this.settleDispatchForTeardown();
         this.clearPendingBargeIn();
         this.drainPendingMarks();
         this.clearGraceTimer();
@@ -29277,7 +29690,7 @@ Avoid:
         };
       }
       /** Synthesize a single sentence through TTS with hooks, sending audio to telephony. */
-      async synthesizeSentence(sentence, hookExecutor, hookCtx, ttsFirstByteSent) {
+      async synthesizeSentence(sentence, hookExecutor, hookCtx, ttsFirstByteSent, recordSegment = true) {
         if (!this.tts || !this.isSpeaking) return;
         let transformed = sentence;
         const transforms = this.deps.agent.textTransforms;
@@ -29303,8 +29716,16 @@ Avoid:
             if (this.aec) {
               this.aec.pushFarEnd(processedAudio);
             }
+            if (recordSegment) {
+              this.turnSpokenSegments.push({
+                text: processedText,
+                startMs: this.turnPlaybackTotalMs
+              });
+              recordSegment = false;
+            }
             const encoded = this.encodePipelineAudio(processedAudio);
             this.deps.bridge.sendAudio(this.ws, encoded, this.streamSid);
+            this.trackOutboundPlayback(processedAudio.length);
             this.markFirstAudioSent();
           }
         } catch (e) {
@@ -29379,64 +29800,101 @@ Avoid:
           return;
         }
         this.history.push({ role: "user", text: filteredTranscript, timestamp: Date.now() });
-        let responseText = "";
         this.metricsAcc.recordOnUserTurnCompletedDelay(0);
         this.metricsAcc.recordTurnCommitted();
         closeEndpointSpan();
-        if (this.deps.onMessage && typeof this.deps.onMessage === "function") {
-          try {
-            responseText = await this.deps.onMessage({
+        await this.dispatchTask?.catch(() => {
+        });
+        const historySnapshot = [...this.history.entries];
+        this.dispatchTask = this.dispatchTurn(
+          filteredTranscript,
+          hookExecutor,
+          hookCtx,
+          interrupted,
+          historySnapshot
+        );
+      }
+      /**
+       * Post-commit turn body (LLM dispatch → TTS → turn-complete) run as a
+       * tracked background task so the transcript drain loop is not blocked for
+       * the whole (possibly 30-90 s) agent-runtime turn. A barge-in — transcript
+       * (now reachable mid-turn) or VAD — aborts the in-flight ``llmAbort`` and
+       * flips ``isSpeaking``, which the LLM/TTS loops here observe and break on.
+       * Parity with Python ``_dispatch_turn``.
+       */
+      async dispatchTurn(filteredTranscript, hookExecutor, hookCtx, interrupted, historySnapshot) {
+        const label = this.deps.bridge.label;
+        let responseText = "";
+        try {
+          if (this.deps.onMessage && typeof this.deps.onMessage === "function") {
+            try {
+              responseText = await this.deps.onMessage({
+                text: filteredTranscript,
+                call_id: this.callId,
+                caller: this.caller,
+                callee: this.callee,
+                history: historySnapshot
+              });
+            } catch (e) {
+              getLogger().error(`onMessage error (${label}):`, e);
+              return;
+            }
+            if (!responseText) {
+              getLogger().warn(
+                `onMessage returned empty/void (${label}) \u2014 no TTS will play. If you intended to observe transcripts, use onTranscript instead; if you meant to answer via the built-in LLM, remove onMessage and pass openaiKey.`
+              );
+            }
+          } else if (this.deps.onMessage && isRemoteUrl(this.deps.onMessage)) {
+            const msgData = {
               text: filteredTranscript,
               call_id: this.callId,
               caller: this.caller,
               callee: this.callee,
-              history: [...this.history.entries]
-            });
-          } catch (e) {
-            getLogger().error(`onMessage error (${label}):`, e);
-            return;
-          }
-          if (!responseText) {
+              history: historySnapshot
+            };
+            if (isWebSocketUrl(this.deps.onMessage)) {
+              await this.handleWebSocketResponse(msgData);
+              return;
+            }
+            try {
+              responseText = await this.deps.remoteHandler.callWebhook(this.deps.onMessage, msgData);
+            } catch (e) {
+              getLogger().error(`Webhook remote error (${label}):`, e);
+              return;
+            }
+          } else if (this.llmLoop) {
+            const llmResult = await this.runPipelineLlm(
+              filteredTranscript,
+              hookExecutor,
+              hookCtx,
+              historySnapshot
+            );
+            responseText = llmResult.text;
+            interrupted = interrupted || llmResult.interrupted;
+          } else {
             getLogger().warn(
-              `onMessage returned empty/void (${label}) \u2014 no TTS will play. If you intended to observe transcripts, use onTranscript instead; if you meant to answer via the built-in LLM, remove onMessage and pass openaiKey.`
+              `Pipeline (${label}) has no llm/onMessage handler \u2014 transcript "${sanitizeLogValue(filteredTranscript.slice(0, 60))}" dropped. Check that agent.llm or onMessage is configured.`
             );
-          }
-        } else if (this.deps.onMessage && isRemoteUrl(this.deps.onMessage)) {
-          const msgData = {
-            text: filteredTranscript,
-            call_id: this.callId,
-            caller: this.caller,
-            callee: this.callee,
-            history: [...this.history.entries]
-          };
-          if (isWebSocketUrl(this.deps.onMessage)) {
-            await this.handleWebSocketResponse(msgData);
             return;
           }
-          try {
-            responseText = await this.deps.remoteHandler.callWebhook(this.deps.onMessage, msgData);
-          } catch (e) {
-            getLogger().error(`Webhook remote error (${label}):`, e);
-            return;
+          if (!responseText) return;
+          if (this.llmLoop) {
+            let spokenText = responseText;
+            if (interrupted) {
+              const heard = this.heardResponsePrefix();
+              spokenText = heard === null ? `${responseText} [interrupted by caller]` : heard.text ? `${heard.text} [interrupted by caller]` : "[interrupted by caller]";
+            }
+            await this.emitAssistantTranscript(spokenText);
+            if (!interrupted) this.metricsAcc.recordTtsComplete(responseText);
+          } else {
+            interrupted = await this.runRegularLlm(responseText, hookExecutor, hookCtx) || interrupted;
+            responseText = this.history.entries[this.history.entries.length - 1]?.text ?? responseText;
           }
-        } else if (this.llmLoop) {
-          responseText = await this.runPipelineLlm(filteredTranscript, hookExecutor, hookCtx);
-        } else {
-          getLogger().warn(
-            `Pipeline (${label}) has no llm/onMessage handler \u2014 transcript "${sanitizeLogValue(filteredTranscript.slice(0, 60))}" dropped. Check that agent.llm or onMessage is configured.`
-          );
-          return;
-        }
-        if (!responseText) return;
-        if (this.llmLoop) {
-          await this.emitAssistantTranscript(responseText);
-          this.metricsAcc.recordTtsComplete(responseText);
-        } else {
-          interrupted = await this.runRegularLlm(responseText, hookExecutor, hookCtx) || interrupted;
-          responseText = this.history.entries[this.history.entries.length - 1]?.text ?? responseText;
-        }
-        if (!interrupted) {
-          await this.emitTurnMetrics(this.metricsAcc.recordTurnComplete(responseText));
+          if (!interrupted) {
+            await this.emitTurnMetrics(this.metricsAcc.recordTurnComplete(responseText));
+          }
+        } finally {
+          this.dispatchTask = null;
         }
       }
       /**
@@ -29447,6 +29905,18 @@ Avoid:
        */
       async handleBargeInAsync(transcript) {
         if (!transcript.text || !this.isSpeaking) return false;
+        if (this.tailGraceActive) {
+          this.endTailGraceForNewTurn();
+          return false;
+        }
+        if (this.forwardSttWhileSpeaking && looksLikeEcho(transcript.text, this.currentAgentSpokenText)) {
+          getLogger().info(
+            `Barge-in suppressed: transcript matches agent's own speech (echo) \u2014 ${sanitizeLogValue(
+              transcript.text.slice(0, 40)
+            )}`
+          );
+          return false;
+        }
         if (!this.canBargeIn()) {
           getLogger().info(
             `Barge-in transcript suppressed (agent speaking < gate, aec=${this.aec ? "on" : "off"})`
@@ -29486,6 +29956,18 @@ Avoid:
        */
       handleBargeIn(transcript) {
         if (!transcript.text || !this.isSpeaking) return false;
+        if (this.tailGraceActive) {
+          this.endTailGraceForNewTurn();
+          return false;
+        }
+        if (this.forwardSttWhileSpeaking && looksLikeEcho(transcript.text, this.currentAgentSpokenText)) {
+          getLogger().info(
+            `Barge-in suppressed: transcript matches agent's own speech (echo) \u2014 ${sanitizeLogValue(
+              transcript.text.slice(0, 40)
+            )}`
+          );
+          return false;
+        }
         if (this.bargeInStrategies.length === 0) {
           if (!this.canBargeIn()) {
             getLogger().info(
@@ -29517,6 +29999,7 @@ Avoid:
         this.metricsAcc.recordBargeinDetected();
         const bargeinSpan = startSpan(SPAN_BARGEIN, { "patter.call.id": this.callId });
         try {
+          this.maybeTruncateCompletedTurnHistory();
           this.cancelSpeaking();
           try {
             this.deps.bridge.sendClear(this.ws, this.streamSid);
@@ -29580,15 +30063,21 @@ Avoid:
           getLogger().debug(`Dropped likely STT hallucination: ${sanitizeLogValue(normalised.slice(0, 40))}`);
           return false;
         }
+        if (this.forwardSttWhileSpeaking && this.isSpeaking && looksLikeEcho(text, this.currentAgentSpokenText)) {
+          getLogger().debug(
+            `Dropped agent-echo transcript (not a user turn): ${sanitizeLogValue(normalised.slice(0, 40))}`
+          );
+          return false;
+        }
         if (sinceLastMs < 2e3 && normalised === this.lastCommitText) {
           getLogger().debug(
             `Dropped duplicate final transcript (${(sinceLastMs / 1e3).toFixed(1)}s since last): ${sanitizeLogValue(normalised.slice(0, 40))}`
           );
           return false;
         }
-        if (sinceLastMs < 500) {
+        if (sinceLastMs < 500 && isNearDuplicate(normalised, this.lastCommitText)) {
           getLogger().debug(
-            `Dropped back-to-back final transcript (${(sinceLastMs / 1e3).toFixed(2)}s since last): ${sanitizeLogValue(normalised.slice(0, 40))}`
+            `Dropped back-to-back near-duplicate final (${(sinceLastMs / 1e3).toFixed(2)}s since last): ${sanitizeLogValue(normalised.slice(0, 40))}`
           );
           return false;
         }
@@ -29596,11 +30085,63 @@ Avoid:
         this.lastCommitAt = now;
         return true;
       }
+      /**
+       * Schedule the opt-in long-turn filler and return its async ``clear()``.
+       *
+       * When ``agent.longTurnMessage`` is unset / empty the returned clear is a
+       * no-op (byte-identical to today's behaviour). Otherwise a one-shot timer
+       * fires after ``agent.longTurnMessageAfterS`` seconds and, IFF no audio has
+       * reached the carrier this turn (``!ttsFirstByteSent.value``) AND we still own
+       * the floor (``this.isSpeaking``), synthesizes the filler ONCE via the same
+       * per-sentence TTS primitive every sentence uses.
+       *
+       * The returned ``clear()`` is **async**: it stops the timer AND, if the filler
+       * already started synthesizing (its ``setTimeout`` callback runs in a separate
+       * macro-task, so it can fire just before the first real sentence), AWAITS the
+       * in-flight synthesis so the filler audio can never interleave with the real
+       * sentence that follows. Idempotent; self-synthesis failure degrades to
+       * silence (never crashes the turn). The caller must clear on first real audio,
+       * on the error branch, and in the finally.
+       */
+      scheduleLongTurnFiller(ttsFirstByteSent, hookExecutor, hookCtx, label) {
+        const message = this.deps.agent.longTurnMessage;
+        if (!message) return async () => {
+        };
+        const afterS = this.deps.agent.longTurnMessageAfterS ?? 4;
+        let cancelled = false;
+        let inFlight = null;
+        const timer = setTimeout(() => {
+          if (cancelled || ttsFirstByteSent.value || !this.isSpeaking) return;
+          inFlight = this.synthesizeSentence(
+            message,
+            hookExecutor,
+            hookCtx,
+            ttsFirstByteSent,
+            false
+          ).catch((err) => {
+            getLogger().error(
+              `longTurnMessage filler synthesis failed (${label}):`,
+              err
+            );
+          });
+        }, Math.max(0, afterS * 1e3));
+        return async () => {
+          cancelled = true;
+          clearTimeout(timer);
+          if (inFlight !== null) {
+            const pending = inFlight;
+            inFlight = null;
+            await pending;
+          }
+        };
+      }
       /**
        * Streaming built-in LLM path with sentence chunking and per-sentence
-       * guardrails/TTS. Returns the concatenated response text.
+       * guardrails/TTS. Returns the concatenated (plain) response text plus whether
+       * the turn was cut short by a barge-in — the caller applies the interrupted
+       * marker to history only, keeping metrics on the plain text.
        */
-      async runPipelineLlm(filteredTranscript, hookExecutor, hookCtx) {
+      async runPipelineLlm(filteredTranscript, hookExecutor, hookCtx, historySnapshot) {
         const label = this.deps.bridge.label;
         const callCtx = { call_id: this.callId, caller: this.caller, callee: this.callee };
         const chunker = new SentenceChunker({
@@ -29613,6 +30154,12 @@ Avoid:
         this.llmAbort = new AbortController();
         const llmSignal = this.llmAbort.signal;
         let llmError = false;
+        const clearLongTurnFiller = this.scheduleLongTurnFiller(
+          ttsFirstByteSent,
+          hookExecutor,
+          hookCtx,
+          label
+        );
         const llmSpan = startSpan(SPAN_LLM, { "patter.call.id": this.callId });
         const guardAndSpeak = async (sentence, isFirst) => {
           if (isFirst) this.metricsAcc.recordLlmFirstSentenceComplete();
@@ -29623,6 +30170,7 @@ Avoid:
             if (transformed === null) return;
             sentenceText = transformed;
           }
+          await clearLongTurnFiller();
           await this.synthesizeSentence(sentenceText, hookExecutor, hookCtx, ttsFirstByteSent);
         };
         let firstSentenceEmitted = false;
@@ -29630,7 +30178,7 @@ Avoid:
           try {
             for await (const token of this.llmLoop.run(
               filteredTranscript,
-              this.history.entries,
+              historySnapshot,
               callCtx,
               this.metricsAcc,
               hookExecutor,
@@ -29641,6 +30189,7 @@ Avoid:
               this.metricsAcc.recordLlmFirstToken();
               await this.emitLlmFirstToken();
               allParts.push(token);
+              this.currentAgentSpokenText = allParts.join("");
               for (const sentence of chunker.push(token)) {
                 if (!this.isSpeaking) break;
                 await guardAndSpeak(sentence, !firstSentenceEmitted);
@@ -29650,11 +30199,20 @@ Avoid:
             }
           } catch (e) {
             const isAbort = e?.name === "AbortError" || llmSignal.aborted;
+            await clearLongTurnFiller();
             if (!isAbort) {
               llmError = true;
               chunker.reset();
               getLogger().error(`LLM loop error (${label}):`, e);
               this.metricsAcc.recordTurnInterrupted();
+              const fallback = this.deps.agent.llmErrorMessage;
+              if (fallback && !ttsFirstByteSent.value && this.isSpeaking) {
+                try {
+                  await this.synthesizeSentence(fallback, hookExecutor, hookCtx, ttsFirstByteSent, false);
+                } catch (err) {
+                  getLogger().error(`llmErrorMessage fallback synthesis failed (${label}):`, err);
+                }
+              }
             }
           }
           this.metricsAcc.recordLlmComplete();
@@ -29666,6 +30224,7 @@ Avoid:
             }
           }
         } finally {
+          await clearLongTurnFiller();
           this.endSpeakingWithGrace();
           this.llmAbort = null;
           try {
@@ -29673,7 +30232,7 @@ Avoid:
           } catch {
           }
         }
-        return allParts.join("");
+        return { text: allParts.join(""), interrupted: llmSignal.aborted };
       }
       /**
        * Non-streaming path (onMessage function / webhook): apply output guardrails,
@@ -30760,7 +31319,7 @@ function validateTelnyxSignature(rawBody, signature, timestamp, publicKey, toler
     if (!Number.isFinite(ts)) return false;
     const tsMs = ts < 1e12 ? ts * 1e3 : ts;
     const ageMs = Date.now() - tsMs;
-    if (ageMs < 0 || ageMs > toleranceSec * 1e3) return false;
+    if (ageMs > toleranceSec * 1e3 || ageMs < -TELNYX_FUTURE_SKEW_MS) return false;
     const payload = `${timestamp}|${rawBody}`;
     const keyBuffer = Buffer.from(publicKey, "base64");
     const keyObject = import_node_crypto4.default.createPublicKey({
@@ -30806,7 +31365,7 @@ function sanitizeVariables(raw) {
   for (const key of Object.keys(raw)) {
     if (BLOCKED_KEYS.has(key)) continue;
     const val = raw[key];
-    safe[key] = typeof val === "string" ? val : String(val ?? "");
+    safe[key] = (typeof val === "string" ? val : String(val ?? "")).replace(/[\x00-\x1f\x7f]/g, "").slice(0, 500);
   }
   return safe;
 }
@@ -30901,7 +31460,7 @@ async function sleep(ms) {
   if (ms <= 0) return;
   await new Promise((resolve2) => setTimeout(resolve2, ms));
 }
-var import_node_crypto4, import_express, import_http, import_ws5, TRANSFER_CALL_TOOL, END_CALL_TOOL, TwilioBridge, TELNYX_DTMF_ALLOWED, TELNYX_DTMF_DURATION_MS, TelnyxBridge, GRACEFUL_SHUTDOWN_TIMEOUT_MS, EmbeddedServer;
+var import_node_crypto4, import_express, import_http, import_ws5, TRANSFER_CALL_TOOL, END_CALL_TOOL, TELNYX_FUTURE_SKEW_MS, TwilioBridge, TELNYX_DTMF_ALLOWED, TELNYX_DTMF_DURATION_MS, TelnyxBridge, GRACEFUL_SHUTDOWN_TIMEOUT_MS, EmbeddedServer;
 var init_server = __esm({
   "src/server.ts"() {
     "use strict";
@@ -30910,6 +31469,7 @@ var init_server = __esm({
     import_express = __toESM(require("express"));
     import_http = require("http");
     import_ws5 = require("ws");
+    init_call_metrics();
     init_openai_realtime_2();
     init_elevenlabs_convai();
     init_plivo_adapter();
@@ -30949,6 +31509,7 @@ var init_server = __esm({
         }
       }
     };
+    TELNYX_FUTURE_SKEW_MS = 3e4;
     TwilioBridge = class {
       constructor(config2) {
         this.config = config2;
@@ -31250,6 +31811,9 @@ var init_server = __esm({
       twilioTokenWarningLogged = false;
       telnyxSigWarningLogged = false;
       metricsStore;
+      /** Anonymous telemetry client, set by ``client.ts`` ``serve()``; emits the
+       * per-call ``call_completed`` event from the call-end path. */
+      telemetry;
       pricing;
       remoteHandler = new RemoteMessageHandler();
       /**
@@ -31353,6 +31917,12 @@ var init_server = __esm({
        * Mirrors Python's ``_resolve_completion``.
        */
       resolveCompletion(callId, args) {
+        if (args.outcome === "no_answer" || args.outcome === "busy" || args.outcome === "failed") {
+          recordCallCompleted(this.telemetry, {
+            outcome: args.outcome,
+            carrier: this.config.telephonyProvider
+          });
+        }
         const entry = this.completions.get(callId);
         if (!entry || entry.done) return;
         const data = args.data;
@@ -32101,7 +32671,13 @@ var init_server = __esm({
           return Object.fromEntries(Object.entries(snap).filter(([, v]) => v !== void 0));
         };
         const store = this.metricsStore;
+        const telemetry = this.telemetry;
         const wrappedStart = async (data) => {
+          recordCallStarted(telemetry, {
+            providerMode: agent.provider ?? void 0,
+            telephonyProvider: bridge.telephonyProvider,
+            direction: data.direction
+          });
           if (logger2.enabled) {
             const callId = typeof data.call_id === "string" ? data.call_id : "";
             const dataCaller = typeof data.caller === "string" ? data.caller : "";
@@ -32132,6 +32708,11 @@ var init_server = __esm({
           if (userMetrics) await userMetrics(data);
         };
         const wrappedEnd = async (data) => {
+          recordCallCompleted(this.telemetry, {
+            outcome: "completed",
+            metrics: data.metrics,
+            direction: data.direction
+          });
           if (logger2.enabled) {
             const callId = typeof data.call_id === "string" ? data.call_id : "";
             const metricsObj = data.metrics ?? null;
@@ -32187,7 +32768,7 @@ var init_server = __esm({
               await handler.handleCallStart(callSid, customParameters);
             } else if (event === "media") {
               const payload = data.media?.payload ?? "";
-              handler.handleAudio(Buffer.from(payload, "base64"));
+              await handler.handleAudio(Buffer.from(payload, "base64"));
             } else if (event === "mark") {
               const markName = String(data.mark?.name ?? "");
               if (markName) await handler.onMark(markName);
@@ -32199,6 +32780,7 @@ var init_server = __esm({
             }
           } catch (err) {
             getLogger().error("Stream handler error:", err);
+            handler.recordError(err);
           }
         });
         ws.on("close", async () => {
@@ -32243,7 +32825,7 @@ var init_server = __esm({
               if (track !== "inbound") return;
               const audioChunk = data.media?.payload ?? "";
               if (!audioChunk) return;
-              handler.handleAudio(Buffer.from(audioChunk, "base64"));
+              await handler.handleAudio(Buffer.from(audioChunk, "base64"));
             } else if (event === "dtmf") {
               const digit = String(data.dtmf?.digit ?? "").trim();
               if (digit) {
@@ -32257,9 +32839,11 @@ var init_server = __esm({
             }
           } catch (err) {
             getLogger().error("Stream handler error (Telnyx):", err);
+            handler.recordError(err);
           }
         });
         ws.on("close", async () => {
+          this.activeCallIds.delete(ws);
           await handler.handleWsClose();
         });
       }
@@ -32288,7 +32872,7 @@ var init_server = __esm({
               await handler.handleCallStart(callId);
             } else if (event === "media") {
               const payload = data.media?.payload ?? "";
-              if (payload) handler.handleAudio(Buffer.from(payload, "base64"));
+              if (payload) await handler.handleAudio(Buffer.from(payload, "base64"));
             } else if (event === "playedStream") {
               const markName = String(data.name ?? "");
               if (markName) await handler.onMark(markName);
@@ -32302,6 +32886,7 @@ var init_server = __esm({
             }
           } catch (err) {
             getLogger().error("Stream handler error (Plivo):", err);
+            handler.recordError(err);
           }
         });
         ws.on("close", async () => {
@@ -34182,6 +34767,7 @@ __export(index_exports, {
   CerebrasLLM: () => LLM4,
   ChatContext: () => ChatContext,
   CloudflareTunnel: () => CloudflareTunnel,
+  CustomLLM: () => LLM7,
   DEFAULT_MIN_SENTENCE_LEN: () => DEFAULT_MIN_SENTENCE_LEN,
   DEFAULT_PRICING: () => DEFAULT_PRICING,
   DTMF_EVENTS: () => DTMF_EVENTS,
@@ -34205,6 +34791,7 @@ __export(index_exports, {
   GoogleLLM: () => LLM5,
   GroqLLM: () => LLM3,
   Guardrail: () => Guardrail,
+  HermesLLM: () => LLM8,
   IVRActivity: () => IVRActivity,
   InworldTTS: () => TTS7,
   KrispFrameDuration: () => KrispFrameDuration,
@@ -34215,6 +34802,8 @@ __export(index_exports, {
   MetricsStore: () => MetricsStore,
   MinWordsStrategy: () => MinWordsStrategy,
   Ngrok: () => Ngrok,
+  OpenAICompatibleLLM: () => LLM6,
+  OpenAICompatibleLLMProvider: () => OpenAICompatibleLLMProvider,
   OpenAILLM: () => LLM,
   OpenAILLMProvider: () => OpenAILLMProvider,
   OpenAIRealtime: () => Realtime,
@@ -34228,6 +34817,7 @@ __export(index_exports, {
   OpenAITranscribeSTT: () => STT3,
   OpenAITranscriptionModel: () => OpenAITranscriptionModel,
   OpenAIVoice: () => OpenAIVoice,
+  OpenClawLLM: () => LLM9,
   PRICING_LAST_UPDATED: () => PRICING_LAST_UPDATED,
   PRICING_VERSION: () => PRICING_VERSION,
   PartialStreamError: () => PartialStreamError,
@@ -34296,6 +34886,7 @@ __export(index_exports, {
   createResampler24kTo16k: () => createResampler24kTo16k,
   createResampler24kTo8k: () => createResampler24kTo8k,
   createResampler8kTo16k: () => createResampler8kTo16k,
+  custom: () => custom2,
   deepgram: () => deepgram,
   defineTool: () => defineTool,
   elevenlabs: () => elevenlabs,
@@ -34307,6 +34898,8 @@ __export(index_exports, {
   geminiLive: () => geminiLive,
   getLogger: () => getLogger,
   guardrail: () => guardrail,
+  hashCaller: () => hashCaller,
+  hermes: () => hermes,
   initTracing: () => initTracing,
   isRemoteUrl: () => isRemoteUrl,
   isTracingEnabled: () => isTracingEnabled,
@@ -34319,7 +34912,9 @@ __export(index_exports, {
   mountDashboard: () => mountDashboard,
   mulawToPcm16: () => mulawToPcm16,
   notifyDashboard: () => notifyDashboard,
+  openaiCompatible: () => openaiCompatible,
   openaiTts: () => openaiTts,
+  openclaw: () => openclaw,
   openclawConsult: () => openclawConsult,
   openclawPostCallNotifier: () => openclawPostCallNotifier,
   pcm16ToMulaw: () => pcm16ToMulaw,
@@ -34350,6 +34945,60 @@ init_cjs_shims();
 init_errors();
 init_server();
 
+// src/telephony/twilio.ts
+init_cjs_shims();
+var Carrier2 = 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/telephony/telnyx.ts
+init_cjs_shims();
+var Carrier3 = 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/client.ts
+init_plivo();
+
 // src/engines/openai.ts
 init_cjs_shims();
 init_openai_realtime();
@@ -34576,6 +35225,570 @@ function validateAllToolSchemas(tools) {
 // src/client.ts
 init_logger();
 
+// src/telemetry/index.ts
+init_cjs_shims();
+
+// src/telemetry/client.ts
+init_cjs_shims();
+init_logger();
+
+// src/telemetry/consent.ts
+init_cjs_shims();
+
+// src/telemetry/env.ts
+init_cjs_shims();
+var CI_ENV_VARS = [
+  "CI",
+  "CONTINUOUS_INTEGRATION",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "TRAVIS",
+  "CIRCLECI",
+  "APPVEYOR",
+  "TF_BUILD",
+  "TEAMCITY_VERSION",
+  "BUILDKITE",
+  "DRONE",
+  "JENKINS_URL",
+  "HUDSON_URL",
+  "BAMBOO_BUILDKEY",
+  "CODEBUILD_BUILD_ID"
+];
+var TEST_ENV_VARS = ["VITEST", "JEST_WORKER_ID"];
+function isTruthy(value) {
+  if (value === void 0) return false;
+  const v = value.trim().toLowerCase();
+  return v !== "" && v !== "0" && v !== "false" && v !== "no" && v !== "off";
+}
+function isCi() {
+  return CI_ENV_VARS.some((name) => isTruthy(process.env[name]));
+}
+function isTest() {
+  if (TEST_ENV_VARS.some((name) => process.env[name] !== void 0)) return true;
+  const node = (process.env.NODE_ENV ?? "").trim().toLowerCase();
+  const patter = (process.env.PATTER_ENV ?? "").trim().toLowerCase();
+  return node === "test" || patter === "test";
+}
+
+// src/telemetry/install-id.ts
+init_cjs_shims();
+var import_node_crypto5 = require("crypto");
+var fs5 = __toESM(require("fs"));
+var os2 = __toESM(require("os"));
+var path5 = __toESM(require("path"));
+var RUN_ID = (0, import_node_crypto5.randomUUID)().replace(/-/g, "");
+var HEX32 = /^[0-9a-f]{32}$/;
+var VERSION_RE = /^[0-9][0-9a-z.+-]{0,31}$/;
+var cachedInstallId = null;
+function runId() {
+  return RUN_ID;
+}
+function statePath() {
+  const base = process.env.PATTER_TELEMETRY_STATE_DIR || process.env.XDG_STATE_HOME;
+  const root = base && base.length > 0 ? base : path5.join(os2.homedir(), ".getpatter");
+  return path5.join(root, "install-id");
+}
+function installId() {
+  if (cachedInstallId !== null) return cachedInstallId;
+  const p = statePath();
+  try {
+    const existing = fs5.readFileSync(p, "utf8").trim();
+    if (HEX32.test(existing)) {
+      cachedInstallId = existing;
+      return cachedInstallId;
+    }
+  } catch {
+  }
+  const newId = (0, import_node_crypto5.randomUUID)().replace(/-/g, "");
+  try {
+    fs5.mkdirSync(path5.dirname(p), { recursive: true });
+    fs5.writeFileSync(p, newId, "utf8");
+    cachedInstallId = newId;
+  } catch {
+    cachedInstallId = RUN_ID;
+  }
+  return cachedInstallId;
+}
+function versionPath() {
+  return path5.join(path5.dirname(statePath()), "version");
+}
+function previousVersion(current) {
+  const p = versionPath();
+  let prev = "";
+  try {
+    prev = fs5.readFileSync(p, "utf8").trim();
+  } catch {
+    prev = "";
+  }
+  try {
+    fs5.mkdirSync(path5.dirname(p), { recursive: true });
+    fs5.writeFileSync(p, current, "utf8");
+  } catch {
+  }
+  return VERSION_RE.test(prev) ? prev : "";
+}
+function daysSinceInstallBucket() {
+  let mtimeMs;
+  try {
+    mtimeMs = fs5.statSync(statePath()).mtimeMs;
+  } catch {
+    return "0";
+  }
+  const days = Math.max(0, Math.floor((Date.now() - mtimeMs) / 864e5));
+  if (days === 0) return "0";
+  if (days <= 7) return "1_7";
+  if (days <= 30) return "8_30";
+  return "30_plus";
+}
+function firstRunPath() {
+  return path5.join(path5.dirname(statePath()), "first-run");
+}
+function isFirstRun() {
+  const p = firstRunPath();
+  try {
+    if (fs5.existsSync(p)) return false;
+  } catch {
+    return false;
+  }
+  try {
+    fs5.mkdirSync(path5.dirname(p), { recursive: true });
+    fs5.writeFileSync(p, "1", "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function optOutPath() {
+  return path5.join(path5.dirname(statePath()), "telemetry-disabled");
+}
+function isOptedOut() {
+  try {
+    return fs5.existsSync(optOutPath());
+  } catch {
+    return false;
+  }
+}
+
+// src/telemetry/consent.ts
+function isEnabled(flag) {
+  if (isTruthy(process.env.DO_NOT_TRACK)) return false;
+  if (isTruthy(process.env.PATTER_TELEMETRY_DISABLED)) return false;
+  if (isOptedOut()) return false;
+  if (flag === false) return false;
+  if (isCi() || isTest()) return false;
+  return true;
+}
+
+// src/telemetry/events.ts
+init_cjs_shims();
+var os3 = __toESM(require("os"));
+
+// src/telemetry/stack.ts
+init_cjs_shims();
+var STACK_VENDORS = /* @__PURE__ */ new Set([
+  "openai",
+  "anthropic",
+  "google",
+  "cerebras",
+  "groq",
+  "deepgram",
+  "elevenlabs",
+  "cartesia",
+  "whisper",
+  "soniox",
+  "assemblyai",
+  "speechmatics",
+  "lmnt",
+  "rime",
+  "inworld",
+  "telnyx",
+  "other"
+]);
+var VENDOR_ALIASES = {
+  cartesia_stt: "cartesia",
+  cartesia_tts: "cartesia",
+  openai_tts: "openai",
+  openai_transcribe: "openai",
+  elevenlabs_ws: "elevenlabs",
+  telnyx_stt: "telnyx",
+  telnyx_tts: "telnyx"
+};
+var RAW_UNSAFE_RE = /[^a-z0-9._-]/;
+var DATE_SUFFIX_RE = /-\d{8}$/;
+function vendorOf(providerKey) {
+  if (!providerKey) return "other";
+  const v = VENDOR_ALIASES[providerKey] ?? providerKey;
+  return STACK_VENDORS.has(v) ? v : "other";
+}
+function modelToken(vendor, rawModel) {
+  if (!rawModel) return `${vendor}-other`;
+  const m = rawModel.trim().toLowerCase();
+  if (m.length > 40 || RAW_UNSAFE_RE.test(m)) return `${vendor}-other`;
+  const token = m.replace(/_/g, "-").replace(DATE_SUFFIX_RE, "").replace(/^[-.]+|[-.]+$/g, "");
+  return token ? `${vendor}-${token}` : `${vendor}-other`;
+}
+function readProviderKey(obj) {
+  const ctor = obj?.constructor;
+  const key = ctor?.providerKey;
+  return typeof key === "string" && key ? key : null;
+}
+function readModel(obj) {
+  const rec = obj;
+  for (const attr of ["model", "modelId", "_model"]) {
+    const v = rec?.[attr];
+    if (typeof v === "string" && v) return v;
+  }
+  return "";
+}
+function layerDims(obj, providerField, modelField) {
+  if (obj === null || obj === void 0) return {};
+  const vendor = vendorOf(readProviderKey(obj));
+  return { [providerField]: vendor, [modelField]: modelToken(vendor, readModel(obj)) };
+}
+function stackDimensions(stt, tts, llm) {
+  return {
+    ...layerDims(stt, "stt_provider", "stt_model"),
+    ...layerDims(tts, "tts_provider", "tts_model"),
+    ...layerDims(llm, "llm_provider", "llm_model")
+  };
+}
+
+// src/telemetry/events.ts
+var SCHEMA_VERSION2 = 5;
+var EVENT_SDK_INITIALIZED = "sdk_initialized";
+var EVENT_FIRST_RUN = "first_run";
+var EVENT_CLI_COMMAND = "cli_command";
+var EVENT_FEATURE_USED = "feature_used";
+var EVENT_AGENT_CONFIGURED = "agent_configured";
+var EVENT_CALL_STARTED = "call_started";
+var EVENT_CALL_COMPLETED = "call_completed";
+var ALLOWED_EVENTS = /* @__PURE__ */ new Set([
+  EVENT_SDK_INITIALIZED,
+  EVENT_FIRST_RUN,
+  EVENT_CLI_COMMAND,
+  EVENT_FEATURE_USED,
+  EVENT_AGENT_CONFIGURED,
+  EVENT_CALL_STARTED,
+  EVENT_CALL_COMPLETED
+]);
+var DIMENSION_VALUES = {
+  carrier: /* @__PURE__ */ new Set(["twilio", "telnyx", "plivo", "none"]),
+  tunnel: /* @__PURE__ */ new Set(["static", "configured", "none"]),
+  engine: /* @__PURE__ */ new Set(["realtime", "convai", "pipeline"]),
+  provider: /* @__PURE__ */ new Set([
+    "openai",
+    "elevenlabs",
+    "deepgram",
+    "cartesia",
+    "cerebras",
+    "anthropic",
+    "google",
+    "whisper",
+    "other"
+  ]),
+  // agent_configured dimensions
+  custom_tool_count_bucket: /* @__PURE__ */ new Set(["0", "1", "2_3", "4_6", "7_12", "13_plus"]),
+  integration: /* @__PURE__ */ new Set(["openclaw", "mcp", "hermes", "other", "none"]),
+  integration_kind: /* @__PURE__ */ new Set(["consult", "mcp", "none"]),
+  mcp_server_count_bucket: /* @__PURE__ */ new Set(["0", "1", "2_3", "4_plus"]),
+  // call_started / call_completed: inbound vs outbound — a core usage split.
+  direction: /* @__PURE__ */ new Set(["inbound", "outbound", "none"]),
+  // cli_command: which CLI subcommand was invoked (never args/flags values).
+  cli_command: /* @__PURE__ */ new Set(["dashboard", "eval", "telemetry", "none", "other"]),
+  // call_completed: the call's terminal outcome
+  outcome: /* @__PURE__ */ new Set(["completed", "error", "no_answer", "busy", "failed"]),
+  // call_completed: terminal error code (mirrors ErrorCode, plus "other"). Never
+  // the error message.
+  error_code: /* @__PURE__ */ new Set([
+    "config",
+    "connection",
+    "auth",
+    "timeout",
+    "rate_limit",
+    "webhook_verification",
+    "input_validation",
+    "provider_error",
+    "provision",
+    "internal",
+    "other"
+  ]),
+  // feature_used (pipeline): per-layer vendor of the composed stack. A
+  // providerKey not on the closed allowlist collapses to "other"; an absent layer
+  // is omitted (the value set keeps "none" only as a safety token).
+  stt_provider: /* @__PURE__ */ new Set([...STACK_VENDORS, "none"]),
+  tts_provider: /* @__PURE__ */ new Set([...STACK_VENDORS, "none"]),
+  llm_provider: /* @__PURE__ */ new Set([...STACK_VENDORS, "none"]),
+  // sdk_initialized: anonymous deploy-shape (presence-only env/file probes).
+  invoked_by_agent: /* @__PURE__ */ new Set(["claude", "cursor", "copilot", "gemini", "windsurf", "other", "none"]),
+  serverless: /* @__PURE__ */ new Set(["lambda", "cloud_run", "vercel", "azure_functions", "none"]),
+  cloud: /* @__PURE__ */ new Set(["aws", "gcp", "azure", "fly", "none"]),
+  package_manager: /* @__PURE__ */ new Set(["npm", "pnpm", "yarn", "bun", "pip", "uv", "poetry", "pipenv", "conda", "none"]),
+  days_since_install_bucket: /* @__PURE__ */ new Set(["0", "1_7", "8_30", "30_plus"]),
+  // agent_configured: feature-adoption (Realtime tuning).
+  noise_reduction: /* @__PURE__ */ new Set(["near_field", "far_field", "none"]),
+  turn_detection: /* @__PURE__ */ new Set(["default", "custom", "none"]),
+  // call_completed: how many conversational turns the call had.
+  turn_count_bucket: /* @__PURE__ */ new Set(["0", "1", "2_3", "4_6", "7_12", "13_plus"])
+};
+var NUMERIC_DIMENSIONS = /* @__PURE__ */ new Set([
+  "builtin_tool_count",
+  "latency_ms",
+  "duration_seconds",
+  "cost_usd"
+]);
+var STRING_DIMENSIONS = /* @__PURE__ */ new Set([
+  "stt_model",
+  "tts_model",
+  "llm_model",
+  "previous_sdk_version"
+]);
+var MODEL_TOKEN_RE = /^[a-z0-9][a-z0-9.-]{0,40}$/;
+var BOOL_DIMENSIONS = /* @__PURE__ */ new Set([
+  "container",
+  "preambles_used",
+  "per_tool_timeouts_set",
+  "llm_fallback_configured"
+]);
+var ALLOWED_DIMENSIONS = /* @__PURE__ */ new Set([
+  ...Object.keys(DIMENSION_VALUES),
+  ...NUMERIC_DIMENSIONS,
+  ...STRING_DIMENSIONS,
+  ...BOOL_DIMENSIONS
+]);
+function osFamily() {
+  const p = os3.platform();
+  if (p === "win32") return "windows";
+  return p || "unknown";
+}
+function arch2() {
+  const a = os3.arch();
+  if (a === "x64") return "x86_64";
+  if (a === "arm64") return "arm64";
+  return "other";
+}
+function runtimeVersion() {
+  const parts = (process.versions.node ?? "0.0").split(".");
+  return `${parts[0] ?? "0"}.${parts[1] ?? "0"}`;
+}
+function buildEvent(name, opts) {
+  if (!ALLOWED_EVENTS.has(name)) {
+    throw new Error(`unknown telemetry event: ${name}`);
+  }
+  const event = {
+    event: name,
+    schema_version: SCHEMA_VERSION2,
+    run_id: runId(),
+    install_id: installId(),
+    sdk: "typescript",
+    sdk_version: opts.sdkVersion,
+    os: osFamily(),
+    arch: arch2(),
+    runtime: "node",
+    runtime_version: runtimeVersion(),
+    ci: isCi() || isTest()
+  };
+  for (const [key, raw] of Object.entries(opts.dimensions ?? {})) {
+    if (!ALLOWED_DIMENSIONS.has(key) || raw === null || raw === void 0) {
+      continue;
+    }
+    let value = raw;
+    const allowed = DIMENSION_VALUES[key];
+    if (allowed && !(typeof value === "string" && allowed.has(value))) {
+      value = "other";
+    } else if (STRING_DIMENSIONS.has(key)) {
+      if (!(typeof value === "string" && MODEL_TOKEN_RE.test(value))) {
+        continue;
+      }
+    } else if (BOOL_DIMENSIONS.has(key) && typeof value !== "boolean") {
+      continue;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      event[key] = value;
+    }
+  }
+  return event;
+}
+
+// src/telemetry/client.ts
+var DEFAULT_ENDPOINT = "https://telemetry.getpatter.com/v1/ingest";
+var TIMEOUT_MS = 3e3;
+var BUFFER_MAX = 256;
+var noticeShown = false;
+var liveClients = /* @__PURE__ */ new Set();
+var exitHookRegistered = false;
+function showNoticeOnce() {
+  if (noticeShown) return;
+  noticeShown = true;
+  getLogger().info(
+    "Anonymous usage telemetry is on (no PII, no call content). Collected: a random anonymous install id, SDK version, language, OS family, runtime version, coarse feature flags, the composed stack (provider + model per layer), tool counts, integration category, and per-call duration, latency, cost, and error codes (no call content, no message text). Disable with PATTER_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1, or telemetry: false. Details: https://docs.getpatter.com/telemetry"
+  );
+}
+function registerExitHook() {
+  if (exitHookRegistered) return;
+  exitHookRegistered = true;
+  process.once("beforeExit", () => {
+    for (const ref of [...liveClients]) {
+      const client = ref.deref();
+      if (client) void client.close();
+      else liveClients.delete(ref);
+    }
+  });
+}
+var TelemetryClient = class {
+  sdkVersion;
+  enabledFlag;
+  endpoint;
+  debug;
+  buffer = [];
+  flushing = false;
+  closed = false;
+  selfRef = new WeakRef(this);
+  constructor(options) {
+    this.sdkVersion = options.sdkVersion;
+    this.enabledFlag = isEnabled(options.flag);
+    this.endpoint = options.endpoint ?? process.env.PATTER_TELEMETRY_ENDPOINT ?? DEFAULT_ENDPOINT;
+    this.debug = isTruthy(process.env.PATTER_TELEMETRY_DEBUG);
+    if (this.enabledFlag && !this.debug) {
+      showNoticeOnce();
+      registerExitHook();
+      liveClients.add(this.selfRef);
+    }
+  }
+  get enabled() {
+    return this.enabledFlag;
+  }
+  /** Enqueue an event. Fire-and-forget; never throws, never blocks. */
+  record(name, dimensions) {
+    if (!this.enabledFlag || this.closed) return;
+    let event;
+    try {
+      event = buildEvent(name, { sdkVersion: this.sdkVersion, dimensions });
+    } catch (err) {
+      getLogger().debug("telemetry buildEvent failed", err);
+      return;
+    }
+    if (this.debug) {
+      try {
+        process.stderr.write(`[patter telemetry] ${JSON.stringify(event)}
+`);
+      } catch {
+      }
+      return;
+    }
+    try {
+      if (this.buffer.length >= BUFFER_MAX) this.buffer.shift();
+      this.buffer.push(event);
+      this.scheduleFlush();
+    } catch (err) {
+      getLogger().debug("telemetry enqueue failed", err);
+    }
+  }
+  /**
+   * Schedule a flush of any buffered events. Events recorded before the server
+   * is running (e.g. at `new Patter(...)`) sit in the buffer; call this once the
+   * server is up so they ship promptly. Cheap when disabled or buffer is empty.
+   */
+  flushPending() {
+    if (!this.enabledFlag || this.debug) return;
+    try {
+      this.scheduleFlush();
+    } catch (err) {
+      getLogger().debug("telemetry flushPending failed", err);
+    }
+  }
+  /** Flush remaining events (graceful shutdown). Never throws. */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    liveClients.delete(this.selfRef);
+    if (!this.enabledFlag || this.debug) return;
+    try {
+      await this.flush();
+    } catch (err) {
+      getLogger().debug("telemetry close flush failed", err);
+    }
+  }
+  scheduleFlush() {
+    if (this.flushing) return;
+    this.flushing = true;
+    void this.flush().finally(() => {
+      this.flushing = false;
+    });
+  }
+  async flush() {
+    if (this.buffer.length === 0) return;
+    const events = this.buffer.splice(0, this.buffer.length);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    timer.unref?.();
+    try {
+      await fetch(this.endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(events),
+        signal: controller.signal
+      });
+    } catch (err) {
+      getLogger().debug("telemetry flush failed", err);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
+// src/telemetry/environment.ts
+init_cjs_shims();
+var fs6 = __toESM(require("fs"));
+var env = process.env;
+function invokedByAgent() {
+  if ("CLAUDECODE" in env || "CLAUDE_CODE" in env || "CLAUDE_CODE_ENTRYPOINT" in env)
+    return "claude";
+  if ("CURSOR_TRACE_ID" in env || "CURSOR_AGENT" in env) return "cursor";
+  if ("GITHUB_COPILOT_AGENT" in env || "COPILOT_AGENT_ID" in env) return "copilot";
+  if ("GEMINI_CLI" in env || "GEMINI_AGENT" in env) return "gemini";
+  if ("WINDSURF" in env || "WINDSURF_AGENT" in env) return "windsurf";
+  if ("AIDER" in env || "OPENAI_AGENT" in env) return "other";
+  return "none";
+}
+function inContainer() {
+  try {
+    if (fs6.existsSync("/.dockerenv")) return true;
+  } catch {
+  }
+  if (env.KUBERNETES_SERVICE_HOST) return true;
+  try {
+    const blob = fs6.readFileSync("/proc/1/cgroup", "utf8");
+    return blob.includes("docker") || blob.includes("containerd") || blob.includes("kubepods");
+  } catch {
+    return false;
+  }
+}
+function serverless() {
+  if (env.AWS_LAMBDA_FUNCTION_NAME) return "lambda";
+  if (env.K_SERVICE) return "cloud_run";
+  if (env.VERCEL) return "vercel";
+  if (env.AZURE_FUNCTIONS_ENVIRONMENT || env.FUNCTIONS_WORKER_RUNTIME) return "azure_functions";
+  return "none";
+}
+function cloud() {
+  if (env.AWS_REGION || env.AWS_EXECUTION_ENV || env.AWS_LAMBDA_FUNCTION_NAME) return "aws";
+  if (env.K_SERVICE || env.GOOGLE_CLOUD_PROJECT || env.GCP_PROJECT) return "gcp";
+  if (env.WEBSITE_INSTANCE_ID || env.AZURE_FUNCTIONS_ENVIRONMENT) return "azure";
+  if (env.FLY_APP_NAME) return "fly";
+  return "none";
+}
+function packageManager() {
+  const ua = env.npm_config_user_agent ?? "";
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("yarn")) return "yarn";
+  if (ua.startsWith("bun")) return "bun";
+  if (ua.startsWith("npm")) return "npm";
+  return "none";
+}
+
+// src/client.ts
+init_version();
+
 // src/_speech-events.ts
 init_cjs_shims();
 init_logger();
@@ -34881,6 +36094,79 @@ function closeParkedConnections(slot) {
     }
   }
 }
+function carrierFamily2(carrier) {
+  if (carrier instanceof Carrier2) return "twilio";
+  if (carrier instanceof Carrier3) return "telnyx";
+  if (carrier instanceof Carrier) return "plivo";
+  return "none";
+}
+function telemetryEngineFamily(opts) {
+  if (opts.engine) {
+    return opts.engine.constructor.name.toLowerCase().includes("convai") ? "convai" : "realtime";
+  }
+  if (opts.provider === "elevenlabs_convai") return "convai";
+  if (opts.provider === "pipeline") return "pipeline";
+  if (opts.provider === "openai_realtime") return "realtime";
+  if (opts.stt || opts.tts) return "pipeline";
+  return "realtime";
+}
+function telemetryProviderFamily(family) {
+  if (family === "realtime") return "openai";
+  if (family === "convai") return "elevenlabs";
+  return "other";
+}
+function telemetryBucketCustomTools(n) {
+  if (n <= 0) return "0";
+  if (n === 1) return "1";
+  if (n <= 3) return "2_3";
+  if (n <= 6) return "4_6";
+  if (n <= 12) return "7_12";
+  return "13_plus";
+}
+function telemetryBucketMcp(n) {
+  if (n <= 0) return "0";
+  if (n === 1) return "1";
+  if (n <= 3) return "2_3";
+  return "4_plus";
+}
+function telemetryIntegration(opts) {
+  const nMcp = opts.mcpServers?.length ?? 0;
+  if (nMcp > 0) {
+    return { integration: "mcp", integrationKind: "mcp", mcpBucket: telemetryBucketMcp(nMcp) };
+  }
+  if (opts.consult) {
+    let isOpenclaw = false;
+    const oc = opts.consult.openaiCompatible;
+    if (oc) {
+      const model = oc.model ?? "";
+      const baseUrl = oc.baseUrl ?? "";
+      isOpenclaw = model.startsWith("openclaw/") || baseUrl.includes(":18789");
+    }
+    return {
+      integration: isOpenclaw ? "openclaw" : "other",
+      integrationKind: "consult",
+      mcpBucket: "0"
+    };
+  }
+  return { integration: "none", integrationKind: "none", mcpBucket: "0" };
+}
+function telemetryEnvironmentDims() {
+  try {
+    const dims = {
+      invoked_by_agent: invokedByAgent(),
+      container: inContainer(),
+      serverless: serverless(),
+      cloud: cloud(),
+      package_manager: packageManager(),
+      days_since_install_bucket: daysSinceInstallBucket()
+    };
+    const prev = previousVersion(VERSION);
+    if (prev) dims.previous_sdk_version = prev;
+    return dims;
+  } catch {
+    return {};
+  }
+}
 var Patter = class {
   localConfig;
   embeddedServer = null;
@@ -34901,6 +36187,14 @@ var Patter = class {
    * ``Cannot use both tunnel: true and webhookUrl``.
    */
   tunnelOwnsWebhookUrl = false;
+  /**
+   * Anonymous usage telemetry (opt-out, default ON). Separate from
+   * ``./observability`` (user-facing OTel). Fire-and-forget and fail-safe — it
+   * can never block or break a call. See ``./telemetry``.
+   */
+  telemetry;
+  telemetrySeenEngines = /* @__PURE__ */ new Set();
+  telemetrySeenAgentShapes = /* @__PURE__ */ new Set();
   /**
    * Pre-rendered first-message TTS audio per outbound call_id. Populated
    * by :meth:`call` when ``agent.prewarmFirstMessage`` is true; consumed
@@ -35106,6 +36400,22 @@ var Patter = class {
       openaiKey: options.openaiKey,
       persistRoot: resolvePersistRoot(options.persist)
     };
+    this.telemetry = new TelemetryClient({
+      sdkVersion: VERSION,
+      flag: options.telemetry
+    });
+    const initDims = {
+      carrier: carrierFamily2(carrier),
+      tunnel: tunnel instanceof Static ? "static" : options.tunnel ? "configured" : "none",
+      ...telemetryEnvironmentDims()
+    };
+    if (this.telemetry.enabled) {
+      try {
+        if (isFirstRun()) this.telemetry.record("first_run", initDims);
+      } catch {
+      }
+    }
+    this.telemetry.record("sdk_initialized", initDims);
     this._tunnelReady = new Promise((resolve2, reject) => {
       this._tunnelReadyResolve = resolve2;
       this._tunnelReadyReject = reject;
@@ -35125,6 +36435,55 @@ var Patter = class {
   // === Agent definition ===
   /** Resolve user-supplied agent options against engine defaults and return the merged config. */
   agent(opts) {
+    const family = telemetryEngineFamily(opts);
+    const stack = stackDimensions(opts.stt, opts.tts, opts.llm);
+    const featureKey = family + "|" + Object.entries(stack).sort().map(([k, v]) => `${k}=${v}`).join(",");
+    if (!this.telemetrySeenEngines.has(featureKey)) {
+      this.telemetrySeenEngines.add(featureKey);
+      this.telemetry.record("feature_used", {
+        engine: family,
+        provider: telemetryProviderFamily(family),
+        ...stack
+      });
+    }
+    const builtin = opts.consult ? 1 : 0;
+    const customBucket = telemetryBucketCustomTools(opts.tools?.length ?? 0);
+    const { integration, integrationKind, mcpBucket } = telemetryIntegration(opts);
+    const engineObj = opts.engine;
+    const nr = opts.openaiRealtimeNoiseReduction ?? engineObj?.noiseReduction;
+    const noiseReduction = nr === "near_field" || nr === "far_field" ? nr : "none";
+    const td = opts.realtimeTurnDetection ?? engineObj?.turnDetection;
+    const turnDetection = td != null ? "custom" : "none";
+    const preamblesUsed = Boolean(opts.toolCallPreambles);
+    const perToolTimeoutsSet = Array.isArray(opts.tools) && opts.tools.some((t) => t.timeoutMs !== void 0);
+    const llmFallbackConfigured = typeof opts.llm?.getAvailability === "function";
+    const shapeKey = [
+      builtin,
+      customBucket,
+      integration,
+      integrationKind,
+      mcpBucket,
+      noiseReduction,
+      turnDetection,
+      preamblesUsed,
+      perToolTimeoutsSet,
+      llmFallbackConfigured
+    ].join("|");
+    if (!this.telemetrySeenAgentShapes.has(shapeKey)) {
+      this.telemetrySeenAgentShapes.add(shapeKey);
+      this.telemetry.record("agent_configured", {
+        builtin_tool_count: builtin,
+        custom_tool_count_bucket: customBucket,
+        integration,
+        integration_kind: integrationKind,
+        mcp_server_count_bucket: mcpBucket,
+        noise_reduction: noiseReduction,
+        turn_detection: turnDetection,
+        preambles_used: preamblesUsed,
+        per_tool_timeouts_set: perToolTimeoutsSet,
+        llm_fallback_configured: llmFallbackConfigured
+      });
+    }
     let working = { ...opts };
     if (opts.engine) {
       if (opts.provider) {
@@ -35314,6 +36673,7 @@ var Patter = class {
       opts.dashboardToken ?? "",
       opts.allowInsecureDashboard ?? false
     );
+    this.embeddedServer.telemetry = this.telemetry;
     this.embeddedServer.popPrewarmAudio = this.popPrewarmAudio;
     this.embeddedServer.popPrewarmedConnections = this.popPrewarmedConnections;
     this.embeddedServer.recordPrewarmWaste = this.recordPrewarmWaste;
@@ -35323,6 +36683,7 @@ var Patter = class {
         await waitForTunnelPubliclyReachable(webhookUrl);
       }
       this._readyResolve(webhookUrl);
+      this.telemetry.flushPending();
     } catch (err) {
       const e = err instanceof Error ? err : new Error(String(err));
       this._readyReject(e);
@@ -36005,6 +37366,7 @@ var Patter = class {
    * entries leak across ``serve`` / ``disconnect`` cycles. See FIX #93.
    */
   async disconnect() {
+    this.telemetry.flushPending();
     for (const handle of this.prewarmTtlTimers.values()) {
       clearTimeout(handle);
     }
@@ -36606,6 +37968,7 @@ var PatterTool = class {
   maxDurationSec;
   recording;
   started = false;
+  hermesTelemetryEmitted = false;
   /** Cached in-progress (or completed) start promise so concurrent execute()
    *  callers all await the same boot sequence instead of each racing into
    *  phone.serve(). Reset to null on failure so callers can retry after a
@@ -36762,6 +38125,20 @@ var PatterTool = class {
    * the same wire contract.
    */
   hermesHandler() {
+    if (!this.hermesTelemetryEmitted) {
+      this.hermesTelemetryEmitted = true;
+      try {
+        const tel = this.phone.telemetry;
+        tel?.record("agent_configured", {
+          builtin_tool_count: 0,
+          custom_tool_count_bucket: "0",
+          integration: "hermes",
+          integration_kind: "none",
+          mcp_server_count_bucket: "0"
+        });
+      } catch {
+      }
+    }
     return async (args) => {
       try {
         const result = await this.execute(args);
@@ -41852,6 +43229,314 @@ var LLM5 = class extends GoogleLLMProvider {
   }
 };
 
+// src/llm/openai-compatible.ts
+init_cjs_shims();
+var import_node_crypto6 = require("crypto");
+init_llm_loop();
+init_errors();
+init_logger();
+init_version();
+var DEFAULT_TIMEOUT_S = 60;
+function hashCaller(caller) {
+  if (!caller) return void 0;
+  return (0, import_node_crypto6.createHash)("sha256").update(caller, "utf8").digest("hex").slice(0, 16);
+}
+var OpenAICompatibleLLMProvider = class {
+  /**
+   * Stable pricing/dashboard key — read by stream-handler/metrics. Typed as
+   * ``string`` (not the narrowed literal) so the Hermes / OpenClaw presets can
+   * override it with their own key while still extending this class.
+   */
+  static providerKey = "openai_compatible";
+  /** Resolved bearer; undefined for keyless gateways. */
+  apiKey;
+  model;
+  baseUrl;
+  timeoutMs;
+  extraHeaders;
+  sessionUserPrefix;
+  sessionIdHeader;
+  sessionIdPrefix;
+  sessionKeyHeader;
+  sessionKey;
+  sessionKeyFactory;
+  temperature;
+  maxTokens;
+  responseFormat;
+  parallelToolCalls;
+  toolChoice;
+  seed;
+  topP;
+  frequencyPenalty;
+  presencePenalty;
+  stop;
+  constructor(options) {
+    if (!options.baseUrl) {
+      throw new Error(
+        'OpenAICompatibleLLMProvider requires a baseUrl (e.g. "http://127.0.0.1:11434/v1").'
+      );
+    }
+    if (!options.model) {
+      throw new Error("OpenAICompatibleLLMProvider requires a model.");
+    }
+    this.apiKey = options.apiKey ?? (options.apiKeyEnv ? process.env[options.apiKeyEnv] : void 0);
+    this.model = options.model;
+    this.baseUrl = options.baseUrl;
+    this.timeoutMs = (options.timeout ?? DEFAULT_TIMEOUT_S) * 1e3;
+    this.extraHeaders = options.extraHeaders;
+    this.sessionUserPrefix = options.sessionUserPrefix;
+    this.sessionIdHeader = options.sessionIdHeader;
+    this.sessionIdPrefix = options.sessionIdPrefix;
+    this.sessionKeyHeader = options.sessionKeyHeader;
+    this.sessionKey = options.sessionKey;
+    let sessionKeyFactory = options.sessionKeyFactory;
+    if (!sessionKeyFactory && options.sessionKeyFrom === "caller_hash") {
+      sessionKeyFactory = (ctx) => ctx.callerHash ? `patter-caller-${ctx.callerHash}` : void 0;
+    } else if (options.sessionKeyFrom !== void 0 && options.sessionKeyFrom !== "caller_hash") {
+      throw new Error(
+        `sessionKeyFrom must be 'caller_hash' or undefined, got ${JSON.stringify(
+          options.sessionKeyFrom
+        )}`
+      );
+    }
+    this.sessionKeyFactory = sessionKeyFactory;
+    this.temperature = options.temperature;
+    this.maxTokens = options.maxTokens;
+    this.responseFormat = options.responseFormat;
+    this.parallelToolCalls = options.parallelToolCalls;
+    this.toolChoice = options.toolChoice;
+    this.seed = options.seed;
+    this.topP = options.topP;
+    this.frequencyPenalty = options.frequencyPenalty;
+    this.presencePenalty = options.presencePenalty;
+    this.stop = options.stop;
+  }
+  /**
+   * Assemble the request headers. ``User-Agent`` is set first so any
+   * ``extraHeaders`` (and the per-call session headers) layer on top without
+   * silently dropping the SDK attribution, and the ``Authorization`` header is
+   * only added when a key is present (keyless gateways omit it).
+   *
+   * The two session headers are emitted INDEPENDENTLY, each gated on its own
+   * config (decoupled from ``sessionUserPrefix`` and from each other):
+   *  - ``sessionIdHeader`` (+ ``callId``) → ``` `${sessionIdPrefix}${callId}` ```
+   *  - ``sessionKeyHeader`` (+ ``sessionKey``) → the static ``sessionKey`` value.
+   * ``sessionKey`` is a credential-grade memory scope and is never logged.
+   */
+  buildHeaders(callId, caller, callee) {
+    const headers = {
+      "Content-Type": "application/json",
+      "User-Agent": `getpatter/${VERSION}`,
+      ...this.extraHeaders ?? {}
+    };
+    if (this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    if (this.sessionIdHeader && callId) {
+      headers[this.sessionIdHeader] = `${this.sessionIdPrefix ?? ""}${callId}`;
+    }
+    if (this.sessionKeyHeader) {
+      const sessionKeyValue = this.resolveSessionKey(callId, caller, callee);
+      if (sessionKeyValue) {
+        headers[this.sessionKeyHeader] = sessionKeyValue;
+      }
+    }
+    return headers;
+  }
+  /**
+   * Resolve the ``sessionKeyHeader`` VALUE for this call. When a
+   * ``sessionKeyFactory`` is configured it is called with a
+   * {@link SessionContext} (the raw ``caller`` plus its non-reversible
+   * {@link hashCaller}) and its return value wins — a falsy return omits the
+   * header. Otherwise the static ``sessionKey`` is used. Never logged.
+   */
+  resolveSessionKey(callId, caller, callee) {
+    if (this.sessionKeyFactory) {
+      const ctx = {
+        callId,
+        caller,
+        callee,
+        callerHash: hashCaller(caller)
+      };
+      return this.sessionKeyFactory(ctx);
+    }
+    return this.sessionKey;
+  }
+  /**
+   * Pre-call DNS / TLS warmup for the configured endpoint. Best-effort:
+   * 5 s timeout, all exceptions swallowed at debug level. The ``Authorization``
+   * header is only sent when a key is present so the operator-grade bearer is
+   * never echoed for keyless gateways (and the key is never logged).
+   */
+  async warmup() {
+    try {
+      const headers = {};
+      if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+      await fetch(`${this.baseUrl}/models`, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(5e3)
+      });
+    } catch (err) {
+      getLogger().debug(
+        `OpenAI-compatible LLM warmup failed (best-effort): ${String(err)}`
+      );
+    }
+  }
+  /**
+   * Build the request body. Mirrors the base OpenAI provider's sampling-kwarg
+   * assembly and additionally sets ``user`` for session continuity when
+   * ``sessionUserPrefix`` is set AND a ``callId`` is available — so the default
+   * (prefix unset) behaviour is byte-identical to the base provider.
+   */
+  buildBody(messages, tools, callId) {
+    const body = {
+      model: this.model,
+      messages,
+      stream: true,
+      stream_options: { include_usage: true }
+    };
+    if (this.temperature !== void 0) body.temperature = this.temperature;
+    if (this.maxTokens !== void 0) body.max_completion_tokens = this.maxTokens;
+    if (this.responseFormat !== void 0) body.response_format = this.responseFormat;
+    if (this.parallelToolCalls !== void 0) body.parallel_tool_calls = this.parallelToolCalls;
+    if (this.toolChoice !== void 0) body.tool_choice = this.toolChoice;
+    if (this.seed !== void 0) body.seed = this.seed;
+    if (this.topP !== void 0) body.top_p = this.topP;
+    if (this.frequencyPenalty !== void 0) body.frequency_penalty = this.frequencyPenalty;
+    if (this.presencePenalty !== void 0) body.presence_penalty = this.presencePenalty;
+    if (this.stop !== void 0) body.stop = this.stop;
+    if (tools) body.tools = tools;
+    if (this.sessionUserPrefix !== void 0 && callId) {
+      body.user = `${this.sessionUserPrefix}${callId}`;
+    }
+    return body;
+  }
+  /** Stream Patter-format LLM chunks from the configured chat completions API. */
+  async *stream(messages, tools, opts) {
+    const callId = opts?.callId;
+    const caller = opts?.caller;
+    const callee = opts?.callee;
+    const body = this.buildBody(messages, tools, callId);
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: this.buildHeaders(callId, caller, callee),
+      body: JSON.stringify(body),
+      signal: mergeAbortSignals(opts?.signal, AbortSignal.timeout(this.timeoutMs))
+    });
+    if (!response.ok) {
+      const errText = await response.text();
+      getLogger().error(
+        `OpenAI-compatible API error: ${response.status} ${errText}`
+      );
+      throw new PatterConnectionError(
+        `LLM API returned ${response.status}: ${errText.slice(0, 200)}`
+      );
+    }
+    yield* parseOpenAISseStream(response);
+  }
+};
+var LLM6 = class extends OpenAICompatibleLLMProvider {
+  static providerKey = "openai_compatible";
+};
+
+// src/llm/custom.ts
+init_cjs_shims();
+var LLM7 = class extends OpenAICompatibleLLMProvider {
+  /** Stable pricing/dashboard key — read by stream-handler/metrics. */
+  static providerKey = "custom";
+};
+
+// src/llm/hermes.ts
+init_cjs_shims();
+var BASE_URL = "http://127.0.0.1:8642/v1";
+var DEFAULT_MODEL5 = "hermes-agent";
+var API_KEY_ENV = "API_SERVER_KEY";
+var MODEL_ENV = "API_SERVER_MODEL_NAME";
+var SESSION_USER_PREFIX = "patter-call-";
+var SESSION_ID_HEADER = "X-Hermes-Session-Id";
+var SESSION_ID_PREFIX = "patter-call-";
+var SESSION_KEY_HEADER = "X-Hermes-Session-Key";
+var DEFAULT_TIMEOUT_S2 = 120;
+var LLM8 = class extends OpenAICompatibleLLMProvider {
+  static providerKey = "hermes";
+  constructor(opts = {}) {
+    const model = opts.model ?? process.env[MODEL_ENV] ?? DEFAULT_MODEL5;
+    const options = {
+      apiKey: opts.apiKey,
+      apiKeyEnv: API_KEY_ENV,
+      baseUrl: opts.baseUrl ?? BASE_URL,
+      model,
+      timeout: opts.timeout ?? DEFAULT_TIMEOUT_S2,
+      sessionUserPrefix: SESSION_USER_PREFIX,
+      sessionIdHeader: SESSION_ID_HEADER,
+      sessionIdPrefix: SESSION_ID_PREFIX,
+      sessionKeyHeader: SESSION_KEY_HEADER,
+      sessionKey: opts.sessionKey,
+      sessionKeyFrom: opts.sessionKeyFrom,
+      sessionKeyFactory: opts.sessionKeyFactory,
+      extraHeaders: opts.extraHeaders,
+      temperature: opts.temperature,
+      maxTokens: opts.maxTokens,
+      responseFormat: opts.responseFormat,
+      parallelToolCalls: opts.parallelToolCalls,
+      toolChoice: opts.toolChoice,
+      seed: opts.seed,
+      topP: opts.topP,
+      frequencyPenalty: opts.frequencyPenalty,
+      presencePenalty: opts.presencePenalty,
+      stop: opts.stop
+    };
+    super(options);
+  }
+};
+
+// src/llm/openclaw.ts
+init_cjs_shims();
+var BASE_URL2 = "http://127.0.0.1:18789/v1";
+var API_KEY_ENV2 = "OPENCLAW_API_KEY";
+var SESSION_HEADER = "x-openclaw-session-key";
+var SESSION_USER_PREFIX2 = "patter-call-";
+var DEFAULT_TIMEOUT_S3 = 120;
+var OPENCLAW_AGENT_RE2 = /^[A-Za-z0-9._:/-]+$/;
+var LLM9 = class extends OpenAICompatibleLLMProvider {
+  static providerKey = "openclaw";
+  constructor(opts) {
+    const agent = opts?.agent;
+    if (!agent || !OPENCLAW_AGENT_RE2.test(agent)) {
+      throw new Error(
+        `Invalid OpenClaw agent id: ${JSON.stringify(agent)}. Allowed characters: letters, digits, dot, underscore, colon, slash, dash.`
+      );
+    }
+    const model = agent.includes("/") || agent.includes(":") ? agent : `openclaw/${agent}`;
+    const options = {
+      apiKey: opts.apiKey,
+      apiKeyEnv: API_KEY_ENV2,
+      baseUrl: opts.baseUrl ?? BASE_URL2,
+      model,
+      timeout: opts.timeout ?? DEFAULT_TIMEOUT_S3,
+      sessionUserPrefix: SESSION_USER_PREFIX2,
+      // Wire-identical to the prior behaviour: header value is the raw call id
+      // (empty prefix), and OpenClaw's gateway also derives the session from
+      // the ``user`` field above. No separate memory-scope header.
+      sessionIdHeader: SESSION_HEADER,
+      sessionIdPrefix: "",
+      extraHeaders: opts.extraHeaders,
+      temperature: opts.temperature,
+      maxTokens: opts.maxTokens,
+      responseFormat: opts.responseFormat,
+      parallelToolCalls: opts.parallelToolCalls,
+      toolChoice: opts.toolChoice,
+      seed: opts.seed,
+      topP: opts.topP,
+      frequencyPenalty: opts.frequencyPenalty,
+      presencePenalty: opts.presencePenalty,
+      stop: opts.stop
+    };
+    super(options);
+  }
+};
+
 // src/index.ts
 init_silero_vad();
 
@@ -42088,57 +43773,6 @@ var KrispVivaFilter = class {
   }
 };
 
-// src/telephony/twilio.ts
-init_cjs_shims();
-var Carrier2 = 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/telephony/telnyx.ts
-init_cjs_shims();
-var Carrier3 = 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/index.ts
 init_plivo();
 init_openai_realtime_2();
@@ -42213,9 +43847,9 @@ init_tunnel();
 
 // src/chat-context.ts
 init_cjs_shims();
-var import_node_crypto5 = require("crypto");
+var import_node_crypto7 = require("crypto");
 function generateId() {
-  return (0, import_node_crypto5.randomUUID)().replace(/-/g, "").slice(0, 12);
+  return (0, import_node_crypto7.randomUUID)().replace(/-/g, "").slice(0, 12);
 }
 function createMessage(role, content, options) {
   return Object.freeze({
@@ -42864,8 +44498,8 @@ var TwilioAdapter = class _TwilioAdapter {
     this.baseUrl = opts.region ? `https://api.${opts.region}.twilio.com/2010-04-01` : TWILIO_API_BASE2;
     this.authHeader = `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString("base64")}`;
   }
-  async request(method, path6, body) {
-    const url2 = `${this.baseUrl}/Accounts/${encodeURIComponent(this.accountSid)}${path6}`;
+  async request(method, path7, body) {
+    const url2 = `${this.baseUrl}/Accounts/${encodeURIComponent(this.accountSid)}${path7}`;
     const headers = { Authorization: this.authHeader };
     if (body) headers["Content-Type"] = "application/x-www-form-urlencoded";
     const response = await fetch(url2, {
@@ -42876,7 +44510,7 @@ var TwilioAdapter = class _TwilioAdapter {
     });
     const text = await response.text();
     if (!response.ok) {
-      throw new Error(`Twilio ${method} ${path6} failed: ${response.status} ${text}`);
+      throw new Error(`Twilio ${method} ${path7} failed: ${response.status} ${text}`);
     }
     if (!text) return {};
     try {
@@ -42894,8 +44528,8 @@ var TwilioAdapter = class _TwilioAdapter {
     const country = encodeURIComponent(opts.countryCode);
     const queryParts = ["PageSize=1"];
     if (opts.areaCode) queryParts.push(`AreaCode=${encodeURIComponent(opts.areaCode)}`);
-    const path6 = `/AvailablePhoneNumbers/${country}/Local.json?${queryParts.join("&")}`;
-    const available = await this.request("GET", path6);
+    const path7 = `/AvailablePhoneNumbers/${country}/Local.json?${queryParts.join("&")}`;
+    const available = await this.request("GET", path7);
     const first = available.available_phone_numbers?.[0]?.phone_number;
     if (!first) {
       throw new Error(`TwilioAdapter: no numbers available for country ${opts.countryCode}`);
@@ -42995,7 +44629,7 @@ var TwilioAdapter = class _TwilioAdapter {
 
 // src/providers/telnyx-adapter.ts
 init_cjs_shims();
-var import_node_crypto6 = require("crypto");
+var import_node_crypto8 = require("crypto");
 init_logger();
 var TELNYX_API_BASE2 = "https://api.telnyx.com/v2";
 var TelnyxAdapter = class {
@@ -43007,8 +44641,8 @@ var TelnyxAdapter = class {
     this.apiKey = apiKey;
     this.connectionId = connectionId;
   }
-  async request(method, path6, body) {
-    const url2 = `${this.baseUrl}${path6}`;
+  async request(method, path7, body) {
+    const url2 = `${this.baseUrl}${path7}`;
     const headers = {
       Authorization: `Bearer ${this.apiKey}`
     };
@@ -43021,7 +44655,7 @@ var TelnyxAdapter = class {
     });
     const text = await response.text();
     if (!response.ok) {
-      throw new Error(`Telnyx ${method} ${path6} failed: ${response.status} ${text}`);
+      throw new Error(`Telnyx ${method} ${path7} failed: ${response.status} ${text}`);
     }
     if (!text) return {};
     try {
@@ -43105,7 +44739,7 @@ var TelnyxAdapter = class {
     if (!callControlId) throw new Error("TelnyxAdapter: callControlId is required");
     const encoded = encodeURIComponent(callControlId);
     const body = {
-      command_id: opts.commandId ?? (0, import_node_crypto6.randomUUID)()
+      command_id: opts.commandId ?? (0, import_node_crypto8.randomUUID)()
     };
     try {
       await this.request(
@@ -43386,6 +45020,12 @@ var TelnyxTTS = class {
 init_cjs_shims();
 init_tracing();
 init_event_bus();
+
+// src/index.ts
+var hermes = Object.freeze({ LLM: LLM8 });
+var openclaw = Object.freeze({ LLM: LLM9 });
+var openaiCompatible = Object.freeze({ LLM: LLM6 });
+var custom2 = Object.freeze({ LLM: LLM7 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AllProvidersFailedError,
@@ -43402,6 +45042,7 @@ init_event_bus();
   CerebrasLLM,
   ChatContext,
   CloudflareTunnel,
+  CustomLLM,
   DEFAULT_MIN_SENTENCE_LEN,
   DEFAULT_PRICING,
   DTMF_EVENTS,
@@ -43425,6 +45066,7 @@ init_event_bus();
   GoogleLLM,
   GroqLLM,
   Guardrail,
+  HermesLLM,
   IVRActivity,
   InworldTTS,
   KrispFrameDuration,
@@ -43435,6 +45077,8 @@ init_event_bus();
   MetricsStore,
   MinWordsStrategy,
   Ngrok,
+  OpenAICompatibleLLM,
+  OpenAICompatibleLLMProvider,
   OpenAILLM,
   OpenAILLMProvider,
   OpenAIRealtime,
@@ -43448,6 +45092,7 @@ init_event_bus();
   OpenAITranscribeSTT,
   OpenAITranscriptionModel,
   OpenAIVoice,
+  OpenClawLLM,
   PRICING_LAST_UPDATED,
   PRICING_VERSION,
   PartialStreamError,
@@ -43516,6 +45161,7 @@ init_event_bus();
   createResampler24kTo16k,
   createResampler24kTo8k,
   createResampler8kTo16k,
+  custom,
   deepgram,
   defineTool,
   elevenlabs,
@@ -43527,6 +45173,8 @@ init_event_bus();
   geminiLive,
   getLogger,
   guardrail,
+  hashCaller,
+  hermes,
   initTracing,
   isRemoteUrl,
   isTracingEnabled,
@@ -43539,7 +45187,9 @@ init_event_bus();
   mountDashboard,
   mulawToPcm16,
   notifyDashboard,
+  openaiCompatible,
   openaiTts,
+  openclaw,
   openclawConsult,
   openclawPostCallNotifier,
   pcm16ToMulaw,