getpatter 0.6.3 → 0.6.5

package/dist/{chunk-Z6W5XFWS.mjs → chunk-CRPJLVHB.mjs}

@@ -5,7 +5,7 @@ import {
   createResampler8kTo16k,
   mulawToPcm16,
   pcm16ToMulaw
-} from "./chunk-CL2U3YET.mjs";
+} from "./chunk-BO227NTF.mjs";
 import {
   getLogger
 } from "./chunk-MVOQFAEO.mjs";
@@ -1039,11 +1039,25 @@ function calculateRealtimeCachedSavings(usage, pricing, model) {
   const rates = resolveProviderRates(pricing.openai_realtime, model);
   if (rates.unit !== "token") return 0;
   const input = usage.input_token_details ?? {};
-  const cached = input.cached_tokens_details ?? {};
   const cachedAudioRate = rates.cached_audio_input_per_token ?? rates.audio_input_per_token ?? 0;
   const cachedTextRate = rates.cached_text_input_per_token ?? rates.text_input_per_token ?? 0;
-  const cachedAudio = Math.min(cached.audio_tokens ?? 0, input.audio_tokens ?? 0);
-  const cachedText = Math.min(cached.text_tokens ?? 0, input.text_tokens ?? 0);
+  const totalAudio = input.audio_tokens ?? 0;
+  const totalText = input.text_tokens ?? 0;
+  let cachedAudio;
+  let cachedText;
+  const details = input.cached_tokens_details;
+  if (details && (details.audio_tokens !== void 0 || details.text_tokens !== void 0)) {
+    cachedAudio = Math.min(details.audio_tokens ?? 0, totalAudio);
+    cachedText = Math.min(details.text_tokens ?? 0, totalText);
+  } else if (input.cached_tokens && input.cached_tokens > 0) {
+    const totalIn = totalAudio + totalText;
+    const ratio = totalIn > 0 ? input.cached_tokens / totalIn : 0;
+    cachedAudio = Math.min(Math.round(totalAudio * ratio), totalAudio);
+    cachedText = Math.min(Math.round(totalText * ratio), totalText);
+  } else {
+    cachedAudio = 0;
+    cachedText = 0;
+  }
   const fullAudio = cachedAudio * (rates.audio_input_per_token ?? 0);
   const fullText = cachedText * (rates.text_input_per_token ?? 0);
   const discountedAudio = cachedAudio * cachedAudioRate;
@@ -1290,14 +1304,49 @@ var MetricsStore = class extends EventEmitter {
     } else {
       for (let i = this.calls.length - 1; i >= 0; i--) {
         if (this.calls[i].call_id === callId) {
-          this.calls[i].status = status;
-          Object.assign(this.calls[i], extra);
+          this.calls[i] = { ...this.calls[i], status, ...extra };
           break;
         }
       }
     }
     this.publish("call_status", { call_id: callId, status, ...extra });
   }
+  /**
+   * Record a single transcript line (user/assistant) as it becomes known.
+   *
+   * FIX-5 (issue #154): the live forward path for the dashboard transcript.
+   * The Realtime stream handler calls this the moment each line is known — the
+   * user line right after the hallucination filter accepts it, the assistant
+   * line when its turn flushes — keyed by the monotonic ``turnIndex`` reserved
+   * at turn-open (``reserveTurnIndex``). Each line is appended to the active
+   * call's ``transcript`` array and broadcast over SSE as a ``transcript_line``
+   * event so the dashboard can render lines as they arrive and re-sort by
+   * ``(turnIndex, user<assistant)`` — making a late-arriving user line land
+   * ABOVE its agent line. ``recordTurn`` de-dups against the lines pushed here
+   * by ``(turnIndex, role)`` so the metrics path never double-pushes the same
+   * text. Parity with Python ``record_transcript_line``.
+   */
+  recordTranscriptLine(data) {
+    const callId = data.call_id || "";
+    const { role, text, turnIndex } = data;
+    if (!callId || role !== "user" && role !== "assistant" || !text) return;
+    const active = this.activeCalls.get(callId);
+    if (active) {
+      if (!active.transcript) active.transcript = [];
+      active.transcript.push({
+        role,
+        text,
+        timestamp: Date.now() / 1e3,
+        turnIndex
+      });
+    }
+    this.publish("transcript_line", {
+      call_id: callId,
+      turnIndex,
+      role,
+      text
+    });
+  }
   /** Append a single conversation turn to an active call and broadcast it via SSE. */
   recordTurn(data) {
     const callId = data.call_id || "";
@@ -1312,14 +1361,19 @@ var MetricsStore = class extends EventEmitter {
       const userText = typeof turnRecord.user_text === "string" ? turnRecord.user_text : "";
       const agentText = typeof turnRecord.agent_text === "string" ? turnRecord.agent_text : "";
       const ts = typeof turnRecord.timestamp === "number" ? turnRecord.timestamp : Date.now() / 1e3;
-      if (userText.length > 0) {
-        active.transcript.push({ role: "user", text: userText, timestamp: ts });
+      const turnIndex = typeof turnRecord.turn_index === "number" ? turnRecord.turn_index : void 0;
+      const alreadyLive = (role) => turnIndex !== void 0 && (active.transcript ?? []).some(
+        (e) => e.turnIndex === turnIndex && e.role === role
+      );
+      if (userText.length > 0 && !alreadyLive("user")) {
+        active.transcript.push({ role: "user", text: userText, timestamp: ts, turnIndex });
       }
-      if (agentText.length > 0 && agentText !== "[interrupted]") {
+      if (agentText.length > 0 && agentText !== "[interrupted]" && !alreadyLive("assistant")) {
         active.transcript.push({
           role: "assistant",
           text: agentText,
-          timestamp: ts
+          timestamp: ts,
+          turnIndex
         });
       }
     }
@@ -1392,7 +1446,7 @@ var MetricsStore = class extends EventEmitter {
   getCall(callId) {
     if (this.deletedCallIds.has(callId)) return null;
     for (let i = this.calls.length - 1; i >= 0; i--) {
-      if (this.calls[i].call_id === callId) return this.calls[i];
+      if (this.calls[i].call_id === callId) return { ...this.calls[i] };
     }
     return null;
   }
@@ -1434,7 +1488,9 @@ var MetricsStore = class extends EventEmitter {
     }
     if (accepted.length === 0) return [];
     accepted.sort();
-    this.persistDeletedIds();
+    this.persistDeletedIds().catch(
+      (err) => getLogger().debug(`MetricsStore.deleteCalls: persistDeletedIds failed: ${String(err)}`)
+    );
     this.publish("calls_deleted", { call_ids: accepted });
     return accepted;
   }
@@ -1446,19 +1502,19 @@ var MetricsStore = class extends EventEmitter {
   getDeletedCallIds() {
     return Array.from(this.deletedCallIds).sort();
   }
-  /** Atomically persist the deleted-ids set to disk. Best-effort. */
-  persistDeletedIds() {
+  /** Atomically persist the deleted-ids set to disk. Best-effort async. */
+  async persistDeletedIds() {
     if (this.deletedIdsPath === null) return;
     try {
       const dir = path2.dirname(this.deletedIdsPath);
-      fs2.mkdirSync(dir, { recursive: true });
+      await fs2.promises.mkdir(dir, { recursive: true });
       const tmp = this.deletedIdsPath + ".tmp";
       const payload = {
         version: 1,
         deleted_call_ids: Array.from(this.deletedCallIds).sort()
       };
-      fs2.writeFileSync(tmp, JSON.stringify(payload, null, 2), "utf8");
-      fs2.renameSync(tmp, this.deletedIdsPath);
+      await fs2.promises.writeFile(tmp, JSON.stringify(payload, null, 2), "utf8");
+      await fs2.promises.rename(tmp, this.deletedIdsPath);
     } catch (err) {
       getLogger().debug(
         `MetricsStore.persistDeletedIds: ${String(err)}`
@@ -1467,7 +1523,8 @@ var MetricsStore = class extends EventEmitter {
   }
   /** Look up an active call by id (returns undefined if not active or unknown). */
   getActive(callId) {
-    return this.activeCalls.get(callId);
+    const rec = this.activeCalls.get(callId);
+    return rec !== void 0 ? { ...rec } : void 0;
   }
   /** Return all currently active (not yet ended) calls. */
   getActiveCalls() {
@@ -1712,8 +1769,8 @@ function loadTranscriptJsonl(filePath) {
       } catch {
         continue;
       }
-      const tsIso = typeof row.ts === "string" ? Date.parse(row.ts) : NaN;
-      const tsNumeric = typeof row.timestamp === "number" ? row.timestamp * 1e3 : NaN;
+      const tsIso = typeof row.ts === "string" ? Date.parse(row.ts) / 1e3 : NaN;
+      const tsNumeric = typeof row.timestamp === "number" ? row.timestamp : NaN;
       const timestamp = Number.isFinite(tsIso) ? tsIso : Number.isFinite(tsNumeric) ? tsNumeric : 0;
       const userText = typeof row.user_text === "string" ? row.user_text : "";
       const agentText = typeof row.agent_text === "string" ? row.agent_text : "";
@@ -1870,8 +1927,8 @@ function mountDashboard(app, store, token = "") {
     res.type("text/html").send(DASHBOARD_HTML);
   });
   app.get("/api/dashboard/calls", auth, (req, res) => {
-    const limit = Math.min(parseInt(req.query.limit || "50", 10) || 50, 1e3);
-    const offset = parseInt(req.query.offset || "0", 10) || 0;
+    const limit = Math.min(Math.max(0, parseInt(req.query.limit || "50", 10) || 50), 1e3);
+    const offset = Math.max(0, parseInt(req.query.offset || "0", 10) || 0);
     res.json(store.getCalls(limit, offset));
   });
   app.get("/api/dashboard/calls/:callId", auth, (req, res) => {
@@ -1961,8 +2018,8 @@ data: ${data}
 function mountApi(app, store, token = "") {
   const auth = makeAuthMiddleware(token);
   app.get("/api/v1/calls", auth, (req, res) => {
-    const limit = Math.min(parseInt(req.query.limit || "50", 10) || 50, 1e3);
-    const offset = parseInt(req.query.offset || "0", 10) || 0;
+    const limit = Math.min(Math.max(0, parseInt(req.query.limit || "50", 10) || 50), 1e3);
+    const offset = Math.max(0, parseInt(req.query.offset || "0", 10) || 0);
     const calls = store.getCalls(limit, offset);
     res.json({
       data: calls,
@@ -2219,14 +2276,31 @@ var RemoteMessageHandler = class {
       while (chunks.length > 0) {
         yield chunks.shift();
       }
+      const READ_TIMEOUT_MS = 3e4;
       while (!done && !error) {
-        const text = await new Promise((resolve2) => {
+        const messagePromise = new Promise((resolve2) => {
           if (chunks.length > 0) {
             resolve2(chunks.shift());
           } else {
             resolveNext = resolve2;
           }
         });
+        let timeoutHandle;
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutHandle = setTimeout(
+            () => reject(new Error("WebSocket read timeout: no frame received within 30 s")),
+            READ_TIMEOUT_MS
+          );
+        });
+        let text;
+        try {
+          text = await Promise.race([messagePromise, timeoutPromise]);
+        } catch (timeoutErr) {
+          resolveNext = null;
+          throw timeoutErr;
+        } finally {
+          clearTimeout(timeoutHandle);
+        }
         if (text === null) break;
         yield text;
       }
@@ -2286,6 +2360,12 @@ var PatterError = class extends Error {
     this.code = options?.code ?? ErrorCode.INTERNAL;
   }
 };
+var PatterConfigError = class extends PatterError {
+  constructor(message, options) {
+    super(message, { code: options?.code ?? ErrorCode.CONFIG });
+    this.name = "PatterConfigError";
+  }
+};
 var PatterConnectionError = class extends PatterError {
   constructor(message, options) {
     super(message, { code: options?.code ?? ErrorCode.CONNECTION });
@@ -2530,18 +2610,6 @@ var DeepgramSTT = class _DeepgramSTT {
     } catch {
       return;
     }
-    const dataType = String(data.type ?? "unknown");
-    if (dataType === "Results") {
-      const transcript2 = (data.channel?.alternatives?.[0]?.transcript ?? "").trim();
-      const isFinal = Boolean(data.is_final);
-      const speechFinal2 = Boolean(data.speech_final);
-      const fromFinalize = Boolean(data.from_finalize);
-      getLogger().info(
-        `[DIAG] DG Results text=${JSON.stringify(transcript2.slice(0, 60))} isFinal=${isFinal} speechFinal=${speechFinal2} fromFinalize=${fromFinalize}`
-      );
-    } else if (dataType !== "Metadata") {
-      getLogger().info(`[DIAG] DG event type=${dataType}`);
-    }
     if (data.type === "Metadata" && data.request_id) {
       this.requestId = data.request_id;
       return;
@@ -2631,7 +2699,7 @@ var DeepgramSTT = class _DeepgramSTT {
     if (!this.ws || this.ws.readyState !== WebSocket2.OPEN) {
       this.audioDroppedCount++;
       if (this.audioDroppedCount === 1 || this.audioDroppedCount % 50 === 0) {
-        getLogger().info(
+        getLogger().debug(
           `[DIAG] DeepgramSTT.sendAudio dropped (ws state=${this.ws?.readyState ?? "null"}) \u2014 total dropped=${this.audioDroppedCount}`
         );
       }
@@ -2640,7 +2708,7 @@ var DeepgramSTT = class _DeepgramSTT {
     if (audio.length === 0) return;
     this.audioSentCount++;
     if (this.audioSentCount === 1 || this.audioSentCount % 100 === 0) {
-      getLogger().info(
+      getLogger().debug(
         `[DIAG] DeepgramSTT.sendAudio: total chunks sent=${this.audioSentCount} (last=${audio.length} bytes)`
       );
     }
@@ -2678,16 +2746,16 @@ var DeepgramSTT = class _DeepgramSTT {
   finalize() {
     const ws = this.ws;
     if (!ws || ws.readyState !== WebSocket2.OPEN) {
-      getLogger().info(
+      getLogger().debug(
         `[DIAG] DeepgramSTT.finalize SKIPPED (ws state=${ws?.readyState ?? "null"})`
       );
       return;
     }
     try {
       ws.send(JSON.stringify({ type: "Finalize" }));
-      getLogger().info("[DIAG] DeepgramSTT.finalize sent {type:Finalize}");
+      getLogger().debug("[DIAG] DeepgramSTT.finalize sent {type:Finalize}");
     } catch (err) {
-      getLogger().info(`[DIAG] DeepgramSTT.finalize send failed: ${String(err)}`);
+      getLogger().debug(`[DIAG] DeepgramSTT.finalize send failed: ${String(err)}`);
     }
   }
   /** Send Finalize, briefly drain trailing transcripts, then close the socket. */
@@ -2760,6 +2828,7 @@ var CallMetricsAccumulator = class {
   _pricing;
   _callStart;
   _turns = [];
+  // mutable internal array; immutable when exposed via TurnMetrics[] → readonly TurnMetrics[]
   // Per-turn timing state
   _turnStart = null;
   _sttComplete = null;
@@ -2846,6 +2915,16 @@ var CallMetricsAccumulator = class {
    * (the common cause of missing endpoint signals).
    */
   _endpointSignalMissingCount = 0;
+  /**
+   * Monotonic per-call turn counter. Reserved at turn OPEN
+   * (``onAdapterSpeechStopped`` / ``speech_stopped``) via
+   * ``reserveTurnIndex()`` and threaded through the buffering pipeline into
+   * ``recordTurnComplete`` / ``recordTurnInterrupted`` as ``preReservedIndex``.
+   * This makes ``turn_index`` stable under drops / interrupts (previously it
+   * was assigned at completion as ``this._turns.length``, which shifted when a
+   * turn was dropped). Parity with Python ``_next_turn_index``.
+   */
+  _nextTurnIndex = 0;
   constructor(opts) {
     this.callId = opts.callId;
     this.providerMode = opts.providerMode;
@@ -2894,12 +2973,27 @@ var CallMetricsAccumulator = class {
     this._turnUserText = "";
     this._turnSttAudioSeconds = 0;
     this._turnAlreadyClosed = false;
+    this._initialTtfbEmitted = false;
     this._vadStoppedAt = null;
     this._sttFinalAt = null;
     this._turnCommittedAt = null;
     this._onUserTurnCompletedDelayMs = null;
     this._eventBus?.emit("turn_started", { callId: this.callId });
   }
+  /**
+   * Reserve and return the next monotonic turn index.
+   *
+   * Called once per turn at the moment the turn OPENS (Realtime:
+   * ``onAdapterSpeechStopped``). The returned index is threaded through the
+   * buffering pipeline and handed back to ``recordTurnComplete`` /
+   * ``recordTurnInterrupted`` as ``preReservedIndex`` so the emitted
+   * ``turn_index`` matches the live per-line transcript ordering even when a
+   * turn is dropped or interrupted between open and close. Parity with Python
+   * ``reserve_turn_index``.
+   */
+  reserveTurnIndex() {
+    return this._nextTurnIndex++;
+  }
   /**
    * Start a new turn only if no turn is currently open.
    * Use this at inbound-audio ingestion points so the turn timer begins
@@ -2937,6 +3031,7 @@ var CallMetricsAccumulator = class {
   anchorUserSpeechStart() {
     if (this._turnCommittedMono !== null) return;
     this._turnStart = hrTimeMs();
+    this._turnAlreadyClosed = false;
     this._endpointSignalAt = null;
     this._vadStoppedAt = null;
     this._sttFinalAt = null;
@@ -3060,11 +3155,14 @@ var CallMetricsAccumulator = class {
    * ``user_text=''``. The caller treats ``null`` as "nothing to emit";
    * ``emitTurnMetrics`` is already null-safe.
    */
-  recordTurnComplete(agentText) {
+  recordTurnComplete(agentText, preReservedIndex) {
     if (this._turnAlreadyClosed) return null;
     const latency = this._computeTurnLatency();
     const turn = {
-      turn_index: this._turns.length,
+      // Use the pre-reserved index (stable across drops/interrupts) when the
+      // caller threaded one through; otherwise fall back to the append
+      // position for back-compat with callers that never reserved.
+      turn_index: preReservedIndex ?? this._turns.length,
       user_text: this._turnUserText,
       agent_text: agentText,
       latency,
@@ -3073,10 +3171,10 @@ var CallMetricsAccumulator = class {
       timestamp: Date.now() / 1e3
     };
     this._turns.push(turn);
-    this._resetTurnState();
-    this._turnAlreadyClosed = true;
     this._eventBus?.emit("turn_ended", { callId: this.callId, turn });
     this._eventBus?.emit("metrics_collected", { callId: this.callId, turn });
+    this._resetTurnState();
+    this._turnAlreadyClosed = true;
     return turn;
   }
   /**
@@ -3088,12 +3186,12 @@ var CallMetricsAccumulator = class {
    * a future refactor that reorders the bargein + LLM-unwind paths)
    * from overwriting a turn that the complete path already emitted.
    */
-  recordTurnInterrupted() {
+  recordTurnInterrupted(preReservedIndex) {
     if (this._turnStart === null) return null;
     if (this._turnAlreadyClosed) return null;
     const latency = this._computeTurnLatency();
     const turn = {
-      turn_index: this._turns.length,
+      turn_index: preReservedIndex ?? this._turns.length,
       user_text: this._turnUserText,
       agent_text: "[interrupted]",
       latency,
@@ -3145,8 +3243,10 @@ var CallMetricsAccumulator = class {
   }
   /**
    * Record the delta (ms) between turn-committed and when on_user_turn_completed
-   * pipeline hook finished.  Stored for inclusion in the next ``emitEouMetrics``
-   * call (or an explicit re-emit if desired).
+   * pipeline hook finished. Does NOT re-emit: like Python's
+   * ``record_on_user_turn_completed_delay``, this only stores the value; the
+   * single EOU emission happens on ``recordTurnCommitted`` (3-timestamp guard,
+   * delay defaults to 0 if not yet recorded).
    */
   recordOnUserTurnCompletedDelay(delayMs) {
     this._onUserTurnCompletedDelayMs = delayMs;
@@ -3159,7 +3259,7 @@ var CallMetricsAccumulator = class {
    * ``transcriptionDelay``       = turnCommitted − vadStopped  (ms)
    * ``onUserTurnCompletedDelay`` = caller-supplied delta (ms) or 0
    */
-  /** Emit `EOUMetrics` once VAD-stop, STT-final, and turn-committed timestamps are all known. */
+  /** Emit `EOUMetrics` once VAD-stop, STT-final, turn-committed, and on_user_turn_completed delay are all known. */
   emitEouMetrics() {
     if (this._vadStoppedAt === null || this._sttFinalAt === null || this._turnCommittedAt === null) {
       return;
@@ -3575,10 +3675,16 @@ var MCPManager = class {
     }
     const aggregatedTools = [];
     for (const cfg of this.configs) {
+      try {
+        validateWebhookUrl(cfg.url);
+      } catch (e) {
+        getLogger().error(`MCP server '${cfg.name}' (${cfg.url}) rejected by SSRF guard: ${String(e)}`);
+        continue;
+      }
       const transport = new transportModule.StreamableHTTPClientTransport(new URL(cfg.url), {
         requestInit: { headers: cfg.headers }
       });
-      const client = new mcpModule.Client({ name: "patter", version: "0.6.0" });
+      const client = new mcpModule.Client({ name: "patter", version: VERSION });
       try {
         await client.connect(transport);
       } catch (e) {
@@ -3650,6 +3756,268 @@ var MCPManager = class {
   }
 };
 
+// src/consult.ts
+init_esm_shims();
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_TOOL_NAME = "consult_agent";
+var DEFAULT_DESCRIPTION = "Consult your back-office agent for deeper reasoning, fresh information, or actions beyond this call. Use when the caller asks something you cannot answer directly.";
+var MAX_RESPONSE_CHARS = 1e6;
+var REPLY_KEYS = ["reply", "response", "text", "result", "answer", "message"];
+var GRACEFUL_FALLBACK = "I wasn't able to reach the system to get that answer right now.";
+var OPENCLAW_DEFAULT_BASE_URL = "http://127.0.0.1:18789/v1";
+var OPENCLAW_API_KEY_ENV = "OPENCLAW_API_KEY";
+var OPENCLAW_SESSION_HEADER = "x-openclaw-session-key";
+var OPENCLAW_DESCRIPTION = "Consult your OpenClaw agent for anything account-specific \u2014 appointments, customer records, schedules, or actions in the back-office system. NEVER state an appointment time, customer detail, or schedule fact from your own memory; ALWAYS call this tool for those and read back what it returns.";
+var OPENCLAW_REASSURANCE = "Let me check on that for you, one moment.";
+var OPENCLAW_AGENT_RE = /^[A-Za-z0-9._:/-]+$/;
+var PARAMETERS = {
+  type: "object",
+  properties: {
+    request: {
+      type: "string",
+      description: "The question or task to send to your back-office agent for deeper reasoning, fresh information, or an action beyond this call. State it self-containedly \u2014 the dialog history is not forwarded with the consult."
+    }
+  },
+  required: ["request"]
+};
+function isLoopbackOrPrivateHost(baseUrl) {
+  let host;
+  try {
+    host = new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  if (host === "localhost" || host === "0.0.0.0" || host === "::1") return true;
+  if (host.endsWith(".local")) return true;
+  if (/^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host)) return true;
+  if (/^169\.254\./.test(host)) return true;
+  const m = host.match(/^172\.(\d+)\./);
+  if (m) {
+    const octet = Number(m[1]);
+    if (octet >= 16 && octet <= 31) return true;
+  }
+  if (host.includes(":") && (/^f[cd][0-9a-f]{2}:/.test(host) || /^fe[89ab][0-9a-f]:/.test(host))) {
+    return true;
+  }
+  return false;
+}
+function openclawConsult(agent, opts = {}) {
+  if (!agent || !OPENCLAW_AGENT_RE.test(agent)) {
+    throw new Error(
+      "OpenClaw agent must be a non-empty id of letters, digits, and ._:/- only"
+    );
+  }
+  const baseUrl = opts.baseUrl ?? OPENCLAW_DEFAULT_BASE_URL;
+  const model = agent.includes("/") || agent.includes(":") ? agent : `openclaw/${agent}`;
+  return {
+    openaiCompatible: {
+      baseUrl,
+      model,
+      apiKey: opts.apiKey,
+      apiKeyEnv: OPENCLAW_API_KEY_ENV,
+      sessionHeader: OPENCLAW_SESSION_HEADER
+    },
+    timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    toolName: opts.toolName ?? DEFAULT_TOOL_NAME,
+    description: opts.description ?? OPENCLAW_DESCRIPTION,
+    reassurance: opts.reassurance ?? OPENCLAW_REASSURANCE,
+    headers: opts.headers,
+    allowLoopback: opts.allowLoopback ?? isLoopbackOrPrivateHost(baseUrl)
+  };
+}
+function buildConsultTool(config) {
+  const hasUrl = config.url != null;
+  const hasOpenAI = config.openaiCompatible != null;
+  if (hasUrl === hasOpenAI) {
+    throw new Error("ConsultConfig requires exactly one of url or openaiCompatible");
+  }
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const baseHeaders = {
+    ...config.headers ?? {},
+    "Content-Type": "application/json"
+  };
+  const handler = hasOpenAI ? buildOpenAIHandler(config.openaiCompatible, baseHeaders, timeoutMs, config.allowLoopback ?? false) : buildWebhookHandler(config.url, baseHeaders, timeoutMs, config.allowLoopback ?? false);
+  const tool = {
+    name: config.toolName ?? DEFAULT_TOOL_NAME,
+    description: config.description ?? DEFAULT_DESCRIPTION,
+    parameters: PARAMETERS,
+    handler
+  };
+  return config.reassurance != null ? { ...tool, reassurance: config.reassurance } : tool;
+}
+function buildWebhookHandler(url, headers, timeoutMs, allowLoopback) {
+  validateWebhookUrl(url, allowLoopback);
+  return async (args, context) => {
+    const requestText = typeof args?.request === "string" ? args.request : "";
+    const payload = {
+      request: requestText,
+      call_id: context?.call_id ?? "",
+      caller: context?.caller ?? "",
+      callee: context?.callee ?? ""
+    };
+    let body;
+    try {
+      const resp = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (!resp.ok) {
+        getLogger().warn(`consult tool: orchestrator returned HTTP ${resp.status}`);
+        return GRACEFUL_FALLBACK;
+      }
+      body = (await resp.text()).slice(0, MAX_RESPONSE_CHARS);
+    } catch (e) {
+      getLogger().warn(
+        `consult tool: orchestrator call failed: ${e instanceof Error ? e.name : "error"}`
+      );
+      return GRACEFUL_FALLBACK;
+    }
+    try {
+      const data = JSON.parse(body);
+      if (data && typeof data === "object" && !Array.isArray(data)) {
+        const obj = data;
+        for (const key of REPLY_KEYS) {
+          if (typeof obj[key] === "string") return obj[key];
+        }
+      }
+      return JSON.stringify(data);
+    } catch {
+      return body;
+    }
+  };
+}
+function buildOpenAIHandler(oc, baseHeaders, timeoutMs, allowLoopback) {
+  const endpoint = oc.baseUrl.replace(/\/+$/, "") + "/chat/completions";
+  validateWebhookUrl(endpoint, allowLoopback);
+  const apiKey = oc.apiKey ?? (oc.apiKeyEnv ? process.env[oc.apiKeyEnv] : void 0);
+  const headers = { ...baseHeaders };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  const sessionHeader = oc.sessionHeader;
+  const model = oc.model;
+  return async (args, context) => {
+    const requestText = typeof args?.request === "string" ? args.request : "";
+    const callId = context?.call_id ?? "";
+    const caller = context?.caller ?? "";
+    const callee = context?.callee ?? "";
+    const contextLines = ["You are answering an inbound phone call relayed by a voice agent."];
+    if (caller) contextLines.push(`Caller: ${caller}`);
+    if (callee) contextLines.push(`Line dialed: ${callee}`);
+    contextLines.push(
+      "Reply concisely in a spoken, conversational style \u2014 it is read aloud to the caller."
+    );
+    const reqHeaders = { ...headers };
+    if (sessionHeader && callId) reqHeaders[sessionHeader] = callId;
+    const payload = {
+      model,
+      messages: [
+        { role: "system", content: contextLines.join("\n") },
+        { role: "user", content: requestText }
+      ],
+      stream: false
+    };
+    if (callId) payload.user = callId;
+    try {
+      const resp = await fetch(endpoint, {
+        method: "POST",
+        headers: reqHeaders,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (resp.status === 404) {
+        getLogger().warn(
+          "consult tool: OpenAI-compatible endpoint returned 404 \u2014 is it enabled? (OpenClaw: set gateway.http.endpoints.chatCompletions.enabled = true)"
+        );
+        return GRACEFUL_FALLBACK;
+      }
+      if (!resp.ok) {
+        getLogger().warn(`consult tool: openai-compatible returned HTTP ${resp.status}`);
+        return GRACEFUL_FALLBACK;
+      }
+      const data = await resp.json();
+      const content = data?.choices?.[0]?.message?.content;
+      if (typeof content === "string" && content.trim()) {
+        return content.trim().slice(0, MAX_RESPONSE_CHARS);
+      }
+      getLogger().warn("consult tool: response missing choices[0].message.content");
+      return GRACEFUL_FALLBACK;
+    } catch (e) {
+      getLogger().warn(
+        `consult tool: openai-compatible call failed: ${e instanceof Error ? e.name : "error"}`
+      );
+      return GRACEFUL_FALLBACK;
+    }
+  };
+}
+var POSTCALL_INSTRUCTION = "A phone call handled by the voice agent has just ended. Here is the record of the call. Log it and follow up if anything needs action.";
+var POSTCALL_MAX_TRANSCRIPT_CHARS = 12e3;
+function buildPostCallRecord(data, includeTranscript) {
+  const lines = [];
+  const caller = data.caller;
+  const callee = data.callee;
+  if (caller) lines.push(`Caller: ${caller}`);
+  if (callee) lines.push(`Line dialed: ${callee}`);
+  const metrics = data.metrics;
+  const duration = metrics?.durationSeconds ?? metrics?.duration_seconds;
+  if (typeof duration === "number") lines.push(`Duration: ${Math.round(duration)}s`);
+  if (includeTranscript) {
+    const entries = data.transcript ?? [];
+    const rendered = entries.filter((e) => e && typeof e === "object").map((e) => `${e.role ?? "?"}: ${e.text ?? ""}`).join("\n");
+    if (rendered) lines.push("Transcript:\n" + rendered.slice(0, POSTCALL_MAX_TRANSCRIPT_CHARS));
+  }
+  return lines.length ? lines.join("\n") : "(no call details available)";
+}
+function openclawPostCallNotifier(agent, opts = {}) {
+  const cfg = openclawConsult(agent, {
+    baseUrl: opts.baseUrl,
+    apiKey: opts.apiKey,
+    timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    allowLoopback: opts.allowLoopback
+  });
+  const oc = cfg.openaiCompatible;
+  const endpoint = oc.baseUrl.replace(/\/+$/, "") + "/chat/completions";
+  validateWebhookUrl(endpoint, cfg.allowLoopback ?? false);
+  const apiKey = oc.apiKey ?? (oc.apiKeyEnv ? process.env[oc.apiKeyEnv] : void 0);
+  const sessionHeader = oc.sessionHeader;
+  const model = oc.model;
+  const timeoutMs = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const includeTranscript = opts.includeTranscript ?? true;
+  const instruction = opts.instruction ?? POSTCALL_INSTRUCTION;
+  return async (data) => {
+    const callId = (data ?? {}).call_id ?? "";
+    const record = buildPostCallRecord(data ?? {}, includeTranscript);
+    const headers = { "Content-Type": "application/json" };
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+    if (sessionHeader && callId) headers[sessionHeader] = callId;
+    const payload = {
+      model,
+      messages: [
+        { role: "system", content: instruction },
+        { role: "user", content: record }
+      ],
+      stream: false
+    };
+    if (callId) payload.user = callId;
+    try {
+      const resp = await fetch(endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (!resp.ok) {
+        getLogger().warn(`openclaw post-call notify: HTTP ${resp.status}`);
+      }
+    } catch (e) {
+      getLogger().warn(
+        `openclaw post-call notify failed: ${e instanceof Error ? e.name : "error"}`
+      );
+    }
+  };
+}
+
 // src/sentence-chunker.ts
 init_esm_shims();
 var DEFAULT_MIN_SENTENCE_LEN = 20;
@@ -4351,6 +4719,52 @@ async function withSpan(name, attrs, fn) {
 }
 
 // src/stream-handler.ts
+var DEFAULT_TOOL_CALL_PREAMBLE_BLOCK = `# Preambles
+
+Use short preambles only when they help the user understand that work is happening. A preamble is one short spoken update describing the action you are about to take \u2014 not hidden reasoning, and never a claim about the result.
+
+## When to use a preamble
+Use a preamble when:
+- you are about to call a tool that may take noticeable time;
+- you need to reason through a multi-step request;
+- you are checking records, availability, account state, or policy details;
+- you are preparing an escalation or handoff;
+- silence would make the assistant feel unresponsive.
+
+When a preamble is needed, output it immediately before the reasoning or tool call.
+
+## When to NOT use a preamble
+Do not use a preamble when:
+- the answer is direct and can be given immediately;
+- the user is only confirming, correcting, or declining something;
+- the audio is unclear and you need clarification instead;
+- the tool call is lightweight and the user would not benefit from an update.
+
+## Style
+- Keep it to one short sentence (two only before a high-impact action).
+- Vary the wording across turns; do not reuse the same opener.
+- Describe the action, not the internal reasoning.
+- Never imply success or failure before the tool returns.
+
+Prefer:
+- "I'll check that order now."
+- "I'll look up your appointment details."
+- "I'll verify that before we make any changes."
+- "I'll check the policy and then give you the next step."
+- "I'll pull that up so we can make sure it's the right account."
+
+Avoid:
+- "Let me think about that for a second."
+- "Please wait while I process your request."
+- "I'm going to use my tools now."
+- "Hmm..." / "One moment while I process that..."`;
+function applyToolCallPreambles(prompt, knob) {
+  if (!knob) return prompt;
+  const block = typeof knob === "string" ? knob : DEFAULT_TOOL_CALL_PREAMBLE_BLOCK;
+  return prompt ? `${block}
+
+${prompt}` : block;
+}
 function checkGuardrails(text, guardrails) {
   if (!guardrails) return null;
   for (const guard of guardrails) {
@@ -4408,39 +4822,63 @@ function augmentWithBuiltinHandoffTools(userTools, callbacks) {
   return out;
 }
 var HALLUCINATIONS = /* @__PURE__ */ new Set([
-  "you",
-  "thank you",
-  "thanks",
-  "yeah",
-  "yes",
-  "no",
-  "okay",
-  "ok",
-  "uh",
-  "um",
-  "mmm",
-  "hmm",
-  ".",
-  "bye",
-  "right",
-  "cool",
-  // Whisper YouTube-caption hallucinations
+  // Issue #154: the hallucination filter is now DISPLAY-ONLY — it no longer
+  // gates response creation (the server drives the response on
+  // ``input_audio_buffer.committed`` by default). Dropping a phrase here
+  // therefore deletes the user's transcript line (recordSttComplete never
+  // fires → empty user_text → dashboard skips the user line). So this set is
+  // restricted to genuine NON-SPEECH artefacts that Whisper emits on
+  // silence / TTS echo, NOT real conversational words. Standalone words like
+  // 'yes', 'no', 'okay', 'right', 'you', 'thanks' were REMOVED — they are
+  // legitimate user replies and must reach the transcript. Parity with
+  // Python ``_STT_HALLUCINATIONS``.
+  //
+  // Whisper caption / training-set hallucinations. Whisper was trained heavily
+  // on captioned video, so on silence / PSTN echo it falls back to the most
+  // common caption credits + sign-offs. Curated from widely-reported
+  // Whisper-on-silence outputs across the open-source ASR community.
   "thank you for watching",
   "thanks for watching",
   "thank you for watching!",
   "thanks for watching!",
   "thank you so much for watching",
+  "thank you for watching please subscribe",
+  "thanks for watching please subscribe",
   "thanks for listening",
+  "we'll see you next time",
+  "see you next time",
+  "bye bye",
   "please subscribe",
+  "please subscribe to my channel",
+  "don't forget to subscribe",
+  "like and subscribe",
   "subscribe",
+  "subtitles by the amara.org community",
+  "subtitles by the amara org community",
+  "subtitles by",
+  "transcribed by",
+  "transcription by castingwords",
+  "the end",
+  // Music / sound markers.
   "music",
   "[music]",
+  "piano music",
+  "applause",
+  "[applause]",
   "\u266A",
+  // Silence markers.
   "[no audio]",
   "[silence]",
   "[blank_audio]",
   "(silence)"
 ]);
+function isSttHallucination(text) {
+  const stripped = text.trim().toLowerCase().replace(/[.,!?;:…。！？\s]+$/u, "").trim();
+  if (stripped === "") return true;
+  if (HALLUCINATIONS.has(stripped)) return true;
+  const pieces = stripped.split(/[.!?…。！？]+/u).map((p) => p.trim()).filter((p) => p.length > 0);
+  return pieces.length > 1 && pieces.every((p) => HALLUCINATIONS.has(p));
+}
 var StreamHandler = class _StreamHandler {
   deps;
   ws;
@@ -4739,7 +5177,14 @@ var StreamHandler = class _StreamHandler {
    * barge-in armed during the audible tail. Tunable via env.
    */
   endSpeakingWithGrace() {
-    const grace = Number(process.env.PATTER_TTS_TAIL_GRACE_MS ?? 1500);
+    const rawGrace = process.env.PATTER_TTS_TAIL_GRACE_MS;
+    const parsedGrace = rawGrace !== void 0 ? Number(rawGrace) : NaN;
+    const grace = rawGrace !== void 0 && Number.isFinite(parsedGrace) ? parsedGrace : 1500;
+    if (rawGrace !== void 0 && !Number.isFinite(parsedGrace)) {
+      getLogger().warn(
+        `PATTER_TTS_TAIL_GRACE_MS="${rawGrace}" is not a valid number \u2014 using default 1500ms`
+      );
+    }
     if (grace > 0) {
       const gen = this.speakingGeneration;
       this.clearGraceTimer();
@@ -4833,6 +5278,14 @@ var StreamHandler = class _StreamHandler {
       `[DIAG] Flushed ${replayed} pre-barge-in frame(s) (~${replayed * 20} ms) to STT`
     );
   }
+  /**
+   * Per-call resolved tool list. Starts as ``null`` (falls back to
+   * ``deps.agent.tools``). Populated by ``initMcpTools`` when MCP servers
+   * are configured so discovered tools are merged in without mutating the
+   * shared ``AgentOptions`` object. Code that needs the effective tool list
+   * should read ``this.resolvedTools ?? this.deps.agent.tools``.
+   */
+  resolvedTools = null;
   llmLoop = null;
   /**
    * Per-call tool executor — provides retry-with-exponential-backoff and a
@@ -4876,6 +5329,17 @@ var StreamHandler = class _StreamHandler {
   userTranscriptPending = false;
   pendingAssistantTurn = null;
   pendingAssistantTimer = null;
+  /**
+   * Reserved monotonic turn index for the in-flight Realtime turn (issue
+   * #154, fix 5/6). Reserved in ``onAdapterSpeechStopped`` via
+   * ``metricsAcc.reserveTurnIndex()`` the moment the turn OPENS, then threaded
+   * through to the live per-line transcript events (``recordTranscriptLine``)
+   * and into ``recordTurnComplete`` / ``recordTurnInterrupted`` so the
+   * dashboard can sort a late-arriving user line ABOVE its agent line by
+   * ``(turnIndex, role)``. ``null`` until the first turn opens. Parity with
+   * Python ``_current_turn_index``.
+   */
+  currentTurnIndex = null;
   /**
    * Hard cap on how long we wait for the user transcript before flushing
    * the buffered assistant turn alone. 3 s covers OpenAI Whisper's typical
@@ -4957,6 +5421,23 @@ var StreamHandler = class _StreamHandler {
    * streaming/regular LLM, WebSocket remote, Realtime response_done) so the
    * payload shape lives in one place.
    */
+  /**
+   * Emit a live per-line transcript event to the dashboard store (issue #154,
+   * fix 5). Routed through a single helper so the call shape lives in one
+   * place. ``recordTranscriptLine`` appends the line to the active call's
+   * transcript and publishes a ``transcript_line`` SSE event; the dashboard
+   * sorts by (turnIndex, user<assistant) so a late user line lands above its
+   * agent line. No-op when no turn index has been reserved yet.
+   */
+  emitTranscriptLine(role, text) {
+    if (this.currentTurnIndex === null) return;
+    this.deps.metricsStore.recordTranscriptLine({
+      call_id: this.callId,
+      turnIndex: this.currentTurnIndex,
+      role,
+      text
+    });
+  }
   async emitTurnMetrics(turn) {
     if (turn == null) return;
     this.deps.metricsStore.recordTurn({ call_id: this.callId, turn });
@@ -5063,7 +5544,7 @@ var StreamHandler = class _StreamHandler {
     if (customParams.callee && !this.callee) this.callee = customParams.callee;
     const mode = this.deps.agent.engine ? `engine=${this.deps.agent.engine.kind ?? "unknown"}` : "pipeline";
     getLogger().info(
-      `Call started: ${callId} (${this.deps.bridge.label}, ${mode}, ${sanitizeLogValue(this.caller || "?")} \u2192 ${sanitizeLogValue(this.callee || "?")})`
+      `Call started: ${callId} (${this.deps.bridge.label}, ${mode}, ${maskPhoneNumber(this.caller || "?")} \u2192 ${maskPhoneNumber(this.callee || "?")})`
     );
     if (Object.keys(customParams).length > 0) {
       getLogger().debug(`Custom params: ${sanitizeLogValue(JSON.stringify(customParams))}`);
@@ -5108,10 +5589,13 @@ var StreamHandler = class _StreamHandler {
     const resolvedPrompt = Object.keys(allVars).length > 0 ? this.deps.resolveVariables(this.deps.agent.systemPrompt, allVars) : this.deps.agent.systemPrompt;
     const provider2 = this.deps.agent.provider ?? "openai_realtime";
     await this.initMcpTools();
+    this.injectConsultTool();
     if (provider2 === "pipeline") {
       await this.initPipeline(resolvedPrompt);
     } else {
-      await this.initRealtimeAdapter(resolvedPrompt);
+      await this.initRealtimeAdapter(
+        applyToolCallPreambles(resolvedPrompt, this.deps.agent.toolCallPreambles)
+      );
     }
   }
   /**
@@ -5136,10 +5620,25 @@ var StreamHandler = class _StreamHandler {
     }
     if (discovered.length === 0) return;
     MCPManager.assertNoConflicts(this.deps.agent.tools, discovered);
-    const mutableAgent = this.deps.agent;
-    mutableAgent.tools = [...mutableAgent.tools ?? [], ...discovered];
+    this.resolvedTools = [...this.deps.agent.tools ?? [], ...discovered];
     getLogger().info(`MCP: merged ${discovered.length} tool(s) into agent`);
   }
+  /**
+   * Merge the built-in ``consult`` tool into the per-call tool list when
+   * ``agent.consult`` is set, mirroring {@link initMcpTools}: the shared
+   * ``deps.agent`` is NOT mutated; the merged list is stored on
+   * ``this.resolvedTools`` so ``buildAIAdapter`` (Realtime) and the pipeline
+   * ``LLMLoop`` both see it. Idempotent — a no-op if a tool with the same name
+   * is already present.
+   */
+  injectConsultTool() {
+    const consult = this.deps.agent.consult;
+    if (!consult) return;
+    const consultTool = buildConsultTool(consult);
+    const base = this.resolvedTools ?? (this.deps.agent.tools ?? []);
+    if (base.some((t) => t.name === consultTool.name)) return;
+    this.resolvedTools = [...base, consultTool];
+  }
   /** Set the stream SID (Twilio only, called after parsing 'start' event). */
   /** Set the carrier-side stream id (Twilio `streamSid` / Telnyx stream identifier). */
   setStreamSid(sid) {
@@ -5159,8 +5658,12 @@ var StreamHandler = class _StreamHandler {
       if (activeVad && !this.vadDisabled) {
         try {
           const vadPromise = activeVad.processFrame(pcm16k, 16e3);
-          const timeoutPromise = new Promise((resolve2) => setTimeout(() => resolve2(null), 25));
+          let vadTimeoutId;
+          const timeoutPromise = new Promise((resolve2) => {
+            vadTimeoutId = setTimeout(() => resolve2(null), 25);
+          });
           const evt = await Promise.race([vadPromise, timeoutPromise]);
+          clearTimeout(vadTimeoutId);
           if (evt) {
             getLogger().info(
               `[VAD] ${evt.type}  agentSpeaking=${this.isSpeaking}`
@@ -5233,7 +5736,7 @@ var StreamHandler = class _StreamHandler {
         if ((this.deps.agent.bargeInThresholdMs ?? 300) === 0) return;
       }
       const hooks = this.deps.agent.hooks;
-      if (hooks) {
+      if (hooks?.beforeSendToStt) {
         const hookExecutor = new PipelineHookExecutor(hooks);
         const hookCtx = this.buildHookContext();
         const processed = await hookExecutor.runBeforeSendToStt(pcm16k, hookCtx);
@@ -5504,7 +6007,7 @@ var StreamHandler = class _StreamHandler {
     }
     if (!this.deps.agent.vad) {
       try {
-        const { SileroVAD } = await import("./silero-vad-LNDFGIY7.mjs");
+        const { SileroVAD } = await import("./silero-vad-RGF5HCIR.mjs");
         this.autoVad = await SileroVAD.forPhoneCall();
         getLogger().info(
           `auto-VAD enabled (SileroVAD, phone preset). Pass agent.vad=\u2026 to override.`
@@ -5659,7 +6162,7 @@ var StreamHandler = class _StreamHandler {
       }
       const providerModel = this.deps.agent.llm?.model ?? "";
       const augmentedTools = augmentWithBuiltinHandoffTools(
-        this.deps.agent.tools,
+        this.resolvedTools ?? this.deps.agent.tools,
         {
           transferCall: (number) => this.deps.bridge.transferCall(this.callId, number),
           endCall: () => this.deps.bridge.endCall(this.callId, this.ws)
@@ -5683,7 +6186,7 @@ var StreamHandler = class _StreamHandler {
       let llmModel = this.deps.agent.model || "gpt-4o-mini";
       if (llmModel.includes("realtime")) llmModel = "gpt-4o-mini";
       const augmentedTools = augmentWithBuiltinHandoffTools(
-        this.deps.agent.tools,
+        this.resolvedTools ?? this.deps.agent.tools,
         {
           transferCall: (number) => this.deps.bridge.transferCall(this.callId, number),
           endCall: () => this.deps.bridge.endCall(this.callId, this.ws)
@@ -6107,6 +6610,14 @@ var StreamHandler = class _StreamHandler {
           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);
+            } catch (err) {
+              getLogger().error(`llmErrorMessage fallback synthesis failed (${label}):`, err);
+            }
+          }
         }
       }
       this.metricsAcc.recordLlmComplete();
@@ -6207,7 +6718,7 @@ var StreamHandler = class _StreamHandler {
   // ---------------------------------------------------------------------------
   async initRealtimeAdapter(resolvedPrompt) {
     const label = this.deps.bridge.label;
-    this.adapter = this.deps.buildAIAdapter(resolvedPrompt);
+    this.adapter = this.deps.buildAIAdapter(resolvedPrompt, this.resolvedTools ?? void 0);
     let parked;
     if (typeof this.deps.popPrewarmedConnections === "function") {
       try {
@@ -6280,6 +6791,7 @@ var StreamHandler = class _StreamHandler {
     response_done: async (eventData) => this.onAdapterResponseDone(eventData),
     speech_started: async () => this.onAdapterSpeechInterrupt(),
     interruption: async () => this.onAdapterSpeechInterrupt(),
+    error: async (eventData) => this.onAdapterError(eventData),
     function_call: async (eventData) => {
       if (this.adapter instanceof OpenAIRealtimeAdapter) {
         await this.handleFunctionCall(eventData);
@@ -6366,21 +6878,31 @@ var StreamHandler = class _StreamHandler {
     if (!this.metricsAcc.turnActive) this.metricsAcc.startTurn();
     this.currentAgentText = "";
     this.responseAudioStarted = false;
+    this.currentTurnIndex = this.metricsAcc.reserveTurnIndex();
     this.userTranscriptPending = true;
     await this.emitUserSpeechEnded();
   }
   async onAdapterTranscriptInput(inputText) {
-    const stripped = inputText.trim().toLowerCase();
-    if (HALLUCINATIONS.has(stripped) || stripped === "") {
+    if (isSttHallucination(inputText)) {
       getLogger().debug(
         `Realtime transcript_input dropped (likely Whisper hallucination on silence/echo): ${sanitizeLogValue(inputText.slice(0, 60))}`
       );
       this.userTranscriptPending = false;
+      if (this.pendingAssistantTurn !== null) {
+        const buffered = this.pendingAssistantTurn;
+        this.pendingAssistantTurn = null;
+        if (this.pendingAssistantTimer) {
+          clearTimeout(this.pendingAssistantTimer);
+          this.pendingAssistantTimer = null;
+        }
+        await this.flushAssistantTurn(buffered);
+      }
       return;
     }
     getLogger().debug(`User (${this.deps.bridge.label}): ${sanitizeLogValue(inputText)}`);
     this.history.push({ role: "user", text: inputText, timestamp: Date.now() });
-    if (this.adapter instanceof OpenAIRealtimeAdapter) {
+    this.emitTranscriptLine("user", inputText);
+    if (this.adapter instanceof OpenAIRealtimeAdapter && this.adapter.getGateResponseOnTranscript()) {
       void this.adapter.requestResponse().catch(
         (err) => getLogger().debug(`Realtime requestResponse failed: ${String(err)}`)
       );
@@ -6427,8 +6949,12 @@ var StreamHandler = class _StreamHandler {
         history: [...this.history.entries]
       });
     }
+    const reservedIndex = this.currentTurnIndex;
+    this.emitTranscriptLine("assistant", text);
     this.responseAudioStarted = false;
-    await this.emitTurnMetrics(this.metricsAcc.recordTurnComplete(text));
+    await this.emitTurnMetrics(
+      this.metricsAcc.recordTurnComplete(text, reservedIndex ?? void 0)
+    );
   }
   /**
    * Push an assistant turn into history and fire `onTranscript` so host
@@ -6527,7 +7053,9 @@ var StreamHandler = class _StreamHandler {
         this.pendingAssistantTimer = null;
         this.userTranscriptPending = false;
         if (buffered !== null) {
-          void this.flushAssistantTurn(buffered);
+          this.flushAssistantTurn(buffered).catch(
+            (err) => getLogger().error("flushAssistantTurn (fallback timer) failed:", err)
+          );
         }
       }, _StreamHandler.REALTIME_USER_TRANSCRIPT_WAIT_MS);
       this.responseAudioStarted = false;
@@ -6536,7 +7064,9 @@ var StreamHandler = class _StreamHandler {
     await this.flushAssistantTurn(text);
   }
   async onAdapterSpeechInterrupt() {
-    if (this.adapter instanceof OpenAIRealtimeAdapter) {
+    const isEngine = this.adapter instanceof OpenAIRealtimeAdapter;
+    const clientManaged = isEngine && this.adapter.getGateResponseOnTranscript();
+    if (clientManaged) {
       const startedAt = this.adapter.currentResponseFirstAudioAt;
       if (startedAt !== null) {
         const elapsedMs = Date.now() - startedAt;
@@ -6549,12 +7079,20 @@ var StreamHandler = class _StreamHandler {
       }
     }
     this.deps.bridge.sendClear(this.ws, this.streamSid);
-    if (this.adapter instanceof OpenAIRealtimeAdapter) this.adapter.cancelResponse();
+    if (clientManaged) {
+      this.metricsAcc.recordBargeinDetected();
+      this.adapter.cancelResponse();
+    } else if (isEngine) {
+      this.adapter.truncate();
+    }
     this.metricsAcc.recordTurnInterrupted();
     if (this.responseAudioStarted) {
       await this.emitAgentSpeechEnded(true);
     }
     await this.emitUserSpeechStarted();
+    if (clientManaged) {
+      this.metricsAcc.anchorUserSpeechStart();
+    }
     this.currentAgentText = "";
     this.responseAudioStarted = false;
     this.pendingAssistantTurn = null;
@@ -6564,6 +7102,28 @@ var StreamHandler = class _StreamHandler {
     }
     this.userTranscriptPending = false;
   }
+  /**
+   * Handle a Realtime ``error`` event (issue #154, fix 4).
+   *
+   * Both Realtime providers dispatch ``('error', …)`` for server-side errors,
+   * non-normal socket closes, and socket errors, but the stream handler
+   * previously had no entry for it in the dispatch table so these were
+   * silently swallowed. We surface them at WARN level with ONLY the error
+   * envelope fields (``type`` / ``code`` / ``message``) — never any audio or
+   * transcript body, to avoid logging PII. The call is NOT terminated: the
+   * provider decides whether to recover, and many of these (e.g. a transient
+   * ``input_audio_buffer_commit_empty``) are non-fatal. Parity with the
+   * Python ``elif ev_type == 'error'`` branches.
+   */
+  async onAdapterError(eventData) {
+    const err = eventData ?? {};
+    const type = typeof err.type === "string" ? err.type : "unknown";
+    const code = typeof err.code === "string" ? err.code : "";
+    const message = typeof err.message === "string" ? err.message : "";
+    getLogger().warn(
+      `Realtime error (${this.deps.bridge.label}) type=${type} code=${code} message=${sanitizeLogValue(message)}`
+    );
+  }
   /**
    * Emit a tool-invocation event into the transcript timeline. Pushes a
    * `role=tool` entry into `history` (so it appears in the dashboard
@@ -6631,7 +7191,8 @@ var StreamHandler = class _StreamHandler {
       }
       return;
     }
-    const toolDef = this.deps.agent.tools?.find((t) => t.name === fc.name);
+    const effectiveTools = this.resolvedTools ?? this.deps.agent.tools;
+    const toolDef = effectiveTools?.find((t) => t.name === fc.name);
     if (!toolDef) {
       getLogger().warn(`Realtime tool '${fc.name}' not found in agent.tools \u2014 skipping`);
       const result2 = JSON.stringify({ error: `Tool '${fc.name}' not registered`, fallback: true });
@@ -6654,7 +7215,8 @@ var StreamHandler = class _StreamHandler {
       if (msg && this.adapter instanceof OpenAIRealtimeAdapter) {
         const realtimeAdapter = this.adapter;
         reassuranceTimer = setTimeout(() => {
-          realtimeAdapter.sendText(msg).catch((e) => {
+          const fire = typeof realtimeAdapter.sendReassurance === "function" ? realtimeAdapter.sendReassurance(msg) : realtimeAdapter.sendText(msg);
+          fire.catch((e) => {
             getLogger().warn(`Reassurance message failed for tool '${fc.name}': ${String(e)}`);
           });
         }, afterMs);
@@ -6674,7 +7236,8 @@ var StreamHandler = class _StreamHandler {
         parsedArgs,
         {
           call_id: this.callId,
-          caller: this.caller
+          caller: this.caller,
+          callee: this.callee
         },
         onProgress
       );
@@ -6924,7 +7487,9 @@ var CallLogger = class {
       getLogger().warn(`call_log write failed (${sanitizeLogValue(callId)}): ${sanitizeLogValue(String(err))}`);
     }
     if (crypto4.randomBytes(1)[0] < 5) {
-      this.sweepOldDays();
+      void this.sweepOldDays().catch(
+        (e) => getLogger().debug(`call_log sweep failed: ${sanitizeLogValue(String(e))}`)
+      );
     }
   }
   /** Append a single turn record to the call's `transcript.jsonl`. */
@@ -6999,23 +7564,27 @@ var CallLogger = class {
     }
   }
   // --- Retention ---------------------------------------------------------
-  sweepOldDays() {
+  async sweepOldDays() {
     if (this.root === null) return;
     const days = retentionDays();
     if (days === 0) return;
     const cutoff = Date.now() / 1e3 - days * 86400;
     const callsRoot = path3.join(this.root, "calls");
-    if (!fs3.existsSync(callsRoot)) return;
     try {
-      for (const yearName of fs3.readdirSync(callsRoot)) {
+      await fsp.access(callsRoot);
+    } catch {
+      return;
+    }
+    try {
+      for (const yearName of await fsp.readdir(callsRoot)) {
         if (!/^\d+$/.test(yearName)) continue;
         const yearDir = path3.join(callsRoot, yearName);
-        if (!fs3.statSync(yearDir).isDirectory()) continue;
-        for (const monthName of fs3.readdirSync(yearDir)) {
+        if (!(await fsp.stat(yearDir)).isDirectory()) continue;
+        for (const monthName of await fsp.readdir(yearDir)) {
           if (!/^\d+$/.test(monthName)) continue;
           const monthDir = path3.join(yearDir, monthName);
-          if (!fs3.statSync(monthDir).isDirectory()) continue;
-          for (const dayName of fs3.readdirSync(monthDir)) {
+          if (!(await fsp.stat(monthDir)).isDirectory()) continue;
+          for (const dayName of await fsp.readdir(monthDir)) {
             if (!/^\d+$/.test(dayName)) continue;
             const dayDir = path3.join(monthDir, dayName);
             const y = Number.parseInt(yearName, 10);
@@ -7023,16 +7592,16 @@ var CallLogger = class {
             const d = Number.parseInt(dayName, 10);
             const ts = Date.UTC(y, m - 1, d) / 1e3;
             if (ts < cutoff) {
-              rmTree(dayDir);
+              await rmTreeAsync(dayDir);
             }
           }
           try {
-            if (fs3.readdirSync(monthDir).length === 0) fs3.rmdirSync(monthDir);
+            if ((await fsp.readdir(monthDir)).length === 0) await fsp.rmdir(monthDir);
           } catch {
           }
         }
         try {
-          if (fs3.readdirSync(yearDir).length === 0) fs3.rmdirSync(yearDir);
+          if ((await fsp.readdir(yearDir)).length === 0) await fsp.rmdir(yearDir);
         } catch {
         }
       }
@@ -7041,21 +7610,21 @@ var CallLogger = class {
     }
   }
 };
-function rmTree(target) {
+async function rmTreeAsync(target) {
   try {
-    for (const child of fs3.readdirSync(target)) {
+    for (const child of await fsp.readdir(target)) {
       const childPath = path3.join(target, child);
-      const stat = fs3.lstatSync(childPath);
+      const stat = await fsp.lstat(childPath);
       if (stat.isDirectory()) {
-        rmTree(childPath);
+        await rmTreeAsync(childPath);
       } else {
         try {
-          fs3.unlinkSync(childPath);
+          await fsp.unlink(childPath);
         } catch {
         }
       }
     }
-    fs3.rmdirSync(target);
+    await fsp.rmdir(target);
   } catch {
   }
 }
@@ -7116,13 +7685,16 @@ function telnyxHangupOutcome(cause) {
   if (c === "call_rejected" || c === "rejected" || c === "destination_out_of_order") return "failed";
   return null;
 }
-function validateWebhookUrl(url) {
+function validateWebhookUrl(url, allowLoopback = false) {
   const parsed = new URL(url);
   if (!["http:", "https:"].includes(parsed.protocol)) {
     throw new Error(`Invalid webhook URL scheme: ${parsed.protocol}`);
   }
   const rawHost = parsed.hostname;
   const host = rawHost.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+  if (allowLoopback) {
+    return;
+  }
   const BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
     "localhost",
     "ip6-localhost",
@@ -7164,6 +7736,34 @@ function validateWebhookUrl(url) {
     }
   }
 }
+function extractHost(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  let host = trimmed.replace(/^[a-z]+:\/\//i, "").replace(/\/.*$/, "");
+  if (host.startsWith("[")) {
+    return host.slice(1).split("]", 1)[0].toLowerCase();
+  }
+  if (!host.includes("::")) {
+    const lastColon = host.lastIndexOf(":");
+    if (lastColon !== -1 && /^\d+$/.test(host.slice(lastColon + 1))) {
+      host = host.slice(0, lastColon);
+    }
+  }
+  return host.toLowerCase();
+}
+function isLoopbackHost(value) {
+  const host = extractHost(value);
+  if (!host) return false;
+  if (host === "localhost" || host === "ip6-localhost" || host === "ip6-loopback") {
+    return true;
+  }
+  if (host === "::1" || host === "::ffff:127.0.0.1") return true;
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (v4) {
+    return parseInt(v4[1], 10) === 127;
+  }
+  return false;
+}
 function validateTelnyxSignature(rawBody, signature, timestamp, publicKey, toleranceSec = 300) {
   try {
     const ts = parseInt(timestamp, 10);
@@ -7227,7 +7827,7 @@ function resolveVariables(template, variables) {
   }
   return result;
 }
-function buildAIAdapter(config, agent, resolvedPrompt) {
+function buildAIAdapter(config, agent, resolvedPrompt, toolsOverride) {
   const engine = agent.engine;
   if (agent.provider === "elevenlabs_convai") {
     if (!engine || engine.kind !== "elevenlabs_convai") {
@@ -7242,12 +7842,24 @@ function buildAIAdapter(config, agent, resolvedPrompt) {
       agent.firstMessage ?? ""
     );
   }
-  const agentTools = agent.tools?.map((t) => ({
-    name: t.name,
-    description: t.description,
-    parameters: t.parameters,
-    strict: t.strict
-  })) ?? [];
+  const preamblesOn = Boolean(agent.toolCallPreambles);
+  const agentTools = (toolsOverride ?? agent.tools)?.map((t) => {
+    let description = t.description;
+    const reassurance = t.reassurance;
+    const sample = typeof reassurance === "string" ? reassurance : void 0;
+    if (preamblesOn && sample) {
+      description = `${description}
+
+Preamble sample phrases:
+- ${sample}`;
+    }
+    return {
+      name: t.name,
+      description,
+      parameters: t.parameters,
+      strict: t.strict
+    };
+  }) ?? [];
   const tools = [...agentTools, TRANSFER_CALL_TOOL, END_CALL_TOOL];
   const isOpenAIEngine = engine && (engine.kind === "openai_realtime" || engine.kind === "openai_realtime_2");
   const openaiKey = isOpenAIEngine ? engine.apiKey : config.openaiKey ?? "";
@@ -7259,8 +7871,27 @@ function buildAIAdapter(config, agent, resolvedPrompt) {
     if (engine.inputAudioTranscriptionModel !== void 0) {
       adapterOptions.inputAudioTranscriptionModel = engine.inputAudioTranscriptionModel;
     }
+    if (engine.noiseReduction !== void 0) {
+      adapterOptions.noiseReduction = engine.noiseReduction;
+    }
+    if (engine.turnDetection !== void 0) {
+      adapterOptions.turnDetection = engine.turnDetection;
+    }
+    if (engine.gateResponseOnTranscript !== void 0) {
+      adapterOptions.gateResponseOnTranscript = engine.gateResponseOnTranscript;
+    }
+  }
+  const agentOpts = agent;
+  if (agentOpts.openaiRealtimeNoiseReduction !== void 0) {
+    adapterOptions.noiseReduction = agentOpts.openaiRealtimeNoiseReduction;
+  }
+  if (agentOpts.realtimeTurnDetection !== void 0) {
+    adapterOptions.turnDetection = agentOpts.realtimeTurnDetection;
   }
-  const AdapterCtor = engine && engine.kind === "openai_realtime_2" ? OpenAIRealtime2Adapter : OpenAIRealtimeAdapter;
+  if (agentOpts.openaiRealtimeGateResponseOnTranscript !== void 0) {
+    adapterOptions.gateResponseOnTranscript = agentOpts.openaiRealtimeGateResponseOnTranscript;
+  }
+  const AdapterCtor = OpenAIRealtime2Adapter;
   return new AdapterCtor(
     openaiKey,
     agent.model,
@@ -7294,6 +7925,11 @@ var TwilioBridge = class {
         getLogger().warn(`TwilioBridge.transferCall rejected: invalid CallSid ${JSON.stringify(callId)}`);
         return;
       }
+      const E164_RE = /^\+[1-9]\d{6,14}$/;
+      if (!E164_RE.test(toNumber)) {
+        getLogger().warn(`TwilioBridge.transferCall rejected: invalid target ${JSON.stringify(toNumber)}`);
+        return;
+      }
       const transferUrl = `https://api.twilio.com/2010-04-01/Accounts/${this.config.twilioSid}/Calls/${callId}.json`;
       await fetch(transferUrl, {
         method: "POST",
@@ -7509,7 +8145,7 @@ var TelnyxBridge = class {
 };
 var GRACEFUL_SHUTDOWN_TIMEOUT_MS = 1e4;
 var EmbeddedServer = class {
-  constructor(config, agent, onCallStart, onCallEnd, onTranscript, onMessage, recording = false, voicemailMessage = "", onMetrics, pricingOverrides, dashboard = true, dashboardToken = "") {
+  constructor(config, agent, onCallStart, onCallEnd, onTranscript, onMessage, recording = false, voicemailMessage = "", onMetrics, pricingOverrides, dashboard = true, dashboardToken = "", allowInsecureDashboard = false) {
     this.config = config;
     this.agent = agent;
     this.onCallStart = onCallStart;
@@ -7521,6 +8157,7 @@ var EmbeddedServer = class {
     this.onMetrics = onMetrics;
     this.dashboard = dashboard;
     this.dashboardToken = dashboardToken;
+    this.allowInsecureDashboard = allowInsecureDashboard;
     this.metricsStore = new MetricsStore();
     this.pricing = mergePricing(pricingOverrides);
     const logRoot = config.persistRoot === void 0 ? resolveLogRoot() : config.persistRoot;
@@ -7547,8 +8184,31 @@ var EmbeddedServer = class {
   onMetrics;
   dashboard;
   dashboardToken;
+  allowInsecureDashboard;
   server = null;
   wss = null;
+  /**
+   * Whether the dashboard + ``/api/*`` routes were mounted in ``start()``.
+   * The dashboard is now ALWAYS mounted when enabled (it never 404s): an
+   * exposed, token-less bind is protected with an auto-generated token
+   * rather than refused. This flag is therefore ``true`` whenever the
+   * dashboard is enabled — kept so the startup banner can gate on it.
+   */
+  dashboardMounted = false;
+  /**
+   * The token actually in effect for the dashboard + ``/api/*`` routes,
+   * resolved in ``start()``. One of: the explicit ``dashboardToken`` if set;
+   * a freshly generated UUID when the bind is exposed and
+   * ``allowInsecureDashboard`` is ``false``; or ``''`` (OPEN) for loopback
+   * local dev and for an exposed bind with ``allowInsecureDashboard=true``.
+   * Read by the startup banner (to print the ready URL with ``?token=``) and
+   * by authentic tests (to authenticate).
+   */
+  effectiveDashboardToken = "";
+  /** The token in effect for the dashboard, resolved at ``start()``. Empty string = served OPEN. */
+  get resolvedDashboardToken() {
+    return this.effectiveDashboardToken;
+  }
   twilioTokenWarningLogged = false;
   telnyxSigWarningLogged = false;
   metricsStore;
@@ -7566,12 +8226,14 @@ var EmbeddedServer = class {
   activeConnections = /* @__PURE__ */ new Set();
   activeCallIds = /* @__PURE__ */ new Map();
   /**
-   * Per-call AMD result callback set by ``Patter.call()`` for the most
-   * recent outbound call. Public so ``client.ts`` can populate it after
-   * server start. Cleared after firing once per call to avoid leaking
-   * across calls.
+   * Per-call AMD result callbacks keyed by CallSid / call_control_id.
+   * Public so ``client.ts`` can register a callback per outbound call.
+   * The Map slot is deleted after the callback fires once — preventing
+   * cross-call misfires when multiple concurrent outbound calls are in
+   * flight (single-slot was a race condition: the last registered callback
+   * would win for every in-flight AMD result).
    */
-  onMachineDetection;
+  onMachineDetectionByCallSid = /* @__PURE__ */ new Map();
   /**
    * Pre-warm first-message audio accessor wired by ``Patter.serve()``.
    * The per-call StreamHandler invokes this with its ``callId`` at the
@@ -7692,6 +8354,42 @@ var EmbeddedServer = class {
     this.completions.clear();
     this.amdClass.clear();
   }
+  /**
+   * Decide whether this server is reachable beyond loopback (127.0.0.1).
+   *
+   * The dashboard serves call transcripts and metadata (PII), so before
+   * mounting it unauthenticated we must know whether anyone off-host can
+   * reach the port. Signals (in order):
+   *
+   *   (a)+(b) — a public webhook URL. ``client.ts`` resolves
+   *       ``config.webhookUrl`` to the live hostname for every serve path:
+   *       a cloudflared quick-tunnel host, a {@link StaticTunnel} hostname,
+   *       or an explicit ``webhookUrl``. A tunnel directive (signal a) and a
+   *       public webhook URL (signal b) therefore both surface here as a
+   *       non-loopback, non-private webhook host. This is the case that
+   *       matters for tunnels — the whole port (dashboard included) is
+   *       published on a public ``*.trycloudflare.com`` URL.
+   *
+   *   (c) — an EXPLICIT non-loopback bind override via ``PATTER_BIND_HOST``.
+   *       Node's ``http.Server.listen(port, host)`` defaults to 127.0.0.1
+   *       here (see ``start()``), so plain local dev is never flagged; only
+   *       an operator who set ``PATTER_BIND_HOST`` to e.g. ``0.0.0.0`` is.
+   *
+   * Only loopback webhook hosts (127.0.0.0/8, localhost, ::1) are treated as
+   * not-exposed. RFC1918 / LAN hosts ARE exposure — they are reachable by
+   * other machines on the network — matching the Python SDK's gate.
+   */
+  isExposed() {
+    const bindOverride = process.env.PATTER_BIND_HOST;
+    if (bindOverride && !isLoopbackHost(bindOverride)) {
+      return true;
+    }
+    const host = extractHost(this.config.webhookUrl ?? "");
+    if (host && !isLoopbackHost(host)) {
+      return true;
+    }
+    return false;
+  }
   /** Bind HTTP + WebSocket listeners on `port`, mount carrier webhooks and dashboard routes. */
   async start(port = 8e3) {
     const webhookUrlPattern = /^[a-zA-Z0-9][a-zA-Z0-9.\-]+[a-zA-Z0-9]$/;
@@ -7727,6 +8425,9 @@ var EmbeddedServer = class {
           }
           next();
         });
+        req.on("error", (err) => {
+          next(err);
+        });
       } else {
         next();
       }
@@ -7737,8 +8438,25 @@ var EmbeddedServer = class {
       res.json({ status: "ok", mode: "local" });
     });
     if (this.dashboard) {
-      mountDashboard(app, this.metricsStore, this.dashboardToken);
-      mountApi(app, this.metricsStore, this.dashboardToken);
+      const exposed = this.isExposed();
+      if (this.dashboardToken) {
+        this.effectiveDashboardToken = this.dashboardToken;
+      } else if (exposed && !this.allowInsecureDashboard) {
+        this.effectiveDashboardToken = crypto5.randomUUID();
+        getLogger().warn(
+          `Dashboard is reachable beyond 127.0.0.1 without a configured token; protecting it with an auto-generated token. Open: http://127.0.0.1:${port}/?token=${this.effectiveDashboardToken}  Set dashboardToken for a stable token, or allowInsecureDashboard=true to serve it open.`
+        );
+      } else if (exposed && this.allowInsecureDashboard) {
+        this.effectiveDashboardToken = "";
+        getLogger().warn(
+          "Dashboard served WITHOUT authentication on a publicly-reachable bind (allowInsecureDashboard=true). Call transcripts and metadata are exposed to anyone who can reach this URL."
+        );
+      } else {
+        this.effectiveDashboardToken = "";
+      }
+      mountDashboard(app, this.metricsStore, this.effectiveDashboardToken);
+      mountApi(app, this.metricsStore, this.effectiveDashboardToken);
+      this.dashboardMounted = true;
     }
     app.post("/webhooks/twilio/status", (req, res) => {
       if (this.config.twilioToken) {
@@ -7824,8 +8542,9 @@ var EmbeddedServer = class {
       if (callSid) {
         this.amdClass.set(callSid, classifyTwilioAmd(answeredBy));
       }
-      const cb = this.onMachineDetection;
+      const cb = callSid ? this.onMachineDetectionByCallSid.get(callSid) : void 0;
       if (cb && callSid) {
+        this.onMachineDetectionByCallSid.delete(callSid);
         try {
           await cb({
             call_id: callSid,
@@ -7952,8 +8671,9 @@ var EmbeddedServer = class {
         if (amdCallId) {
           this.amdClass.set(amdCallId, classifyTelnyxAmd(amdResult));
         }
-        const cbTx = this.onMachineDetection;
+        const cbTx = amdCallId ? this.onMachineDetectionByCallSid.get(amdCallId) : void 0;
         if (cbTx && amdCallId) {
+          this.onMachineDetectionByCallSid.delete(amdCallId);
           try {
             await cbTx({
               call_id: amdCallId,
@@ -8121,8 +8841,13 @@ var EmbeddedServer = class {
       getLogger().info(`AMD result for ${sanitizeLogValue(callUuid)}: ${sanitizeLogValue(amdRaw)}`);
       const classification = classifyPlivoAmd(amdRaw);
       if (callUuid) this.amdClass.set(callUuid, classification);
-      const cb = this.onMachineDetection;
+      let cbKey = callUuid && this.onMachineDetectionByCallSid.has(callUuid) ? callUuid : void 0;
+      if (cbKey === void 0 && this.onMachineDetectionByCallSid.size === 1) {
+        cbKey = this.onMachineDetectionByCallSid.keys().next().value;
+      }
+      const cb = cbKey !== void 0 ? this.onMachineDetectionByCallSid.get(cbKey) : void 0;
       if (cb && callUuid) {
+        if (cbKey !== void 0) this.onMachineDetectionByCallSid.delete(cbKey);
         try {
           await cb({
             call_id: callUuid,
@@ -8203,27 +8928,34 @@ var EmbeddedServer = class {
         this.handleTwilioStream(ws, url);
       }
     });
-    await new Promise((resolve2) => {
+    await new Promise((resolve2, reject) => {
       const bindHost = process.env.PATTER_BIND_HOST ?? "127.0.0.1";
+      this.server.once("error", reject);
       this.server.listen(port, bindHost, () => {
+        this.server.off("error", reject);
         getLogger().info(`Server on port ${port}`);
         getLogger().info(`Webhook: https://${this.config.webhookUrl}`);
         getLogger().info(`Phone:   ${this.config.phoneNumber}`);
         const model = this.agent.model ?? "";
-        if (model && model !== "gpt-4o-mini-realtime-preview" && model.includes("realtime")) {
+        const calibrated = ["gpt-realtime-mini", "gpt-4o-mini-realtime-preview"];
+        if (model && !calibrated.includes(model) && model.includes("realtime")) {
           getLogger().warn(
-            `Agent uses "${sanitizeLogValue(model)}" but DEFAULT_PRICING.openai_realtime is calibrated for "gpt-4o-mini-realtime-preview". Pass Patter({ pricing: { openai_realtime: {...} } }) to set rates for this model, otherwise the dashboard cost display will under-report.`
+            `Agent uses "${sanitizeLogValue(model)}" but DEFAULT_PRICING.openai_realtime is calibrated for the default Realtime models (gpt-realtime-mini / gpt-4o-mini-realtime-preview). Pass Patter({ pricing: { openai_realtime: {...} } }) to set rates for this model, otherwise the dashboard cost display will under-report.`
           );
         }
-        if (this.dashboard) {
-          console.log("\n\u2500\u2500\u2500\u2500 Dashboard \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-          getLogger().info(`URL: http://127.0.0.1:${port}/`);
-          if (!this.dashboardToken) {
+        if (this.dashboard && this.dashboardMounted) {
+          getLogger().info("\u2500\u2500\u2500\u2500 Dashboard \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+          if (this.effectiveDashboardToken) {
+            getLogger().info(
+              `URL: http://127.0.0.1:${port}/?token=${this.effectiveDashboardToken}`
+            );
+          } else {
+            getLogger().info(`URL: http://127.0.0.1:${port}/`);
             getLogger().warn(
               "Dashboard is enabled without authentication. Set dashboardToken to protect call data. This is safe for local development but should not be exposed on a public network."
             );
           }
-          console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+          getLogger().info("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
         }
         resolve2();
       });
@@ -8299,7 +9031,7 @@ var EmbeddedServer = class {
       onMessage: this.onMessage,
       onMetrics: wrappedMetrics,
       recording: this.recording,
-      buildAIAdapter: (resolvedPrompt) => buildAIAdapter(this.config, this.agent, resolvedPrompt),
+      buildAIAdapter: (resolvedPrompt, toolsOverride) => buildAIAdapter(this.config, this.agent, resolvedPrompt, toolsOverride),
       sanitizeVariables,
       resolveVariables,
       popPrewarmAudio: this.popPrewarmAudio,
@@ -8573,17 +9305,18 @@ var EmbeddedServer = class {
     }
     if (this.activeConnections.size > 0) {
       getLogger().info(`Waiting for ${this.activeConnections.size} active connection(s) to close...`);
-      await Promise.race([
-        new Promise((resolve2) => {
-          const checkInterval = setInterval(() => {
-            if (this.activeConnections.size === 0) {
-              clearInterval(checkInterval);
-              resolve2();
-            }
-          }, 100);
-        }),
-        new Promise((resolve2) => setTimeout(resolve2, GRACEFUL_SHUTDOWN_TIMEOUT_MS))
-      ]);
+      let checkInterval;
+      const drainPromise = new Promise((resolve2) => {
+        checkInterval = setInterval(() => {
+          if (this.activeConnections.size === 0) {
+            clearInterval(checkInterval);
+            resolve2();
+          }
+        }, 100);
+      });
+      const timeoutPromise = new Promise((resolve2) => setTimeout(resolve2, GRACEFUL_SHUTDOWN_TIMEOUT_MS));
+      await Promise.race([drainPromise, timeoutPromise]);
+      clearInterval(checkInterval);
     }
     if (this.activeConnections.size > 0) {
       getLogger().info(`Force-closing ${this.activeConnections.size} remaining connection(s)`);
@@ -8630,10 +9363,13 @@ var CircuitBreakerRegistry = class {
     if (s.state === CircuitBreakerState.OPEN) {
       if (this.clock() - s.openedAt >= this.cooldownMs) {
         s.state = CircuitBreakerState.HALF_OPEN;
+        s.probeInFlight = true;
         return true;
       }
       return false;
     }
+    if (s.probeInFlight) return false;
+    s.probeInFlight = true;
     return true;
   }
   /** Mark a successful execution. Resets the breaker to CLOSED. */
@@ -8643,19 +9379,21 @@ var CircuitBreakerRegistry = class {
     s.state = CircuitBreakerState.CLOSED;
     s.consecutiveFailures = 0;
     s.openedAt = 0;
+    s.probeInFlight = false;
   }
   /** Mark a failed execution; trips OPEN once threshold is reached. */
   recordFailure(toolName) {
     if (this.threshold <= 0) return;
     let s = this.state.get(toolName);
     if (!s) {
-      s = { state: CircuitBreakerState.CLOSED, consecutiveFailures: 0, openedAt: 0 };
+      s = { state: CircuitBreakerState.CLOSED, consecutiveFailures: 0, openedAt: 0, probeInFlight: false };
       this.state.set(toolName, s);
     }
     s.consecutiveFailures += 1;
     if (s.consecutiveFailures >= this.threshold) {
       s.state = CircuitBreakerState.OPEN;
       s.openedAt = this.clock();
+      s.probeInFlight = false;
     }
   }
   /**
@@ -8680,7 +9418,18 @@ var CircuitBreakerRegistry = class {
 var DEFAULT_TOOL_MAX_RETRIES = 2;
 var DEFAULT_TOOL_RETRY_DELAY_MS = 500;
 var DEFAULT_TOOL_TIMEOUT_MS = 1e4;
+var MAX_TOOL_TIMEOUT_MS = 3e5;
 var TOOL_MAX_RESPONSE_BYTES = 1 * 1024 * 1024;
+var ToolTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ToolTimeoutError";
+  }
+};
+function resolveToolTimeoutMs(toolTimeoutMs, defaultMs) {
+  if (toolTimeoutMs === void 0) return defaultMs;
+  return Math.max(100, Math.min(toolTimeoutMs, MAX_TOOL_TIMEOUT_MS));
+}
 async function invokeHandler(handler, args, callContext, onProgress) {
   const invoked = handler(args, callContext);
   if (invoked && typeof invoked === "object" && typeof invoked[Symbol.asyncIterator] === "function" && typeof invoked.next === "function") {
@@ -8740,15 +9489,41 @@ var DefaultToolExecutor = class {
         retry_after_ms: cooldown
       });
     }
+    const effectiveTimeoutMs = resolveToolTimeoutMs(
+      toolDef.timeoutMs,
+      this.requestTimeoutMs
+    );
     if (toolDef.handler) {
       const totalAttempts = this.maxRetries + 1;
       let lastErr = null;
       for (let attempt = 0; attempt < totalAttempts; attempt++) {
+        let timeoutTimer;
         try {
-          const result = await invokeHandler(toolDef.handler, args, callContext, onProgress);
+          const handlerPromise = invokeHandler(toolDef.handler, args, callContext, onProgress);
+          const result = await Promise.race([
+            handlerPromise,
+            new Promise((_, reject) => {
+              timeoutTimer = setTimeout(
+                () => reject(
+                  new ToolTimeoutError(
+                    `Tool handler '${toolDef.name}' timed out after ${effectiveTimeoutMs}ms`
+                  )
+                ),
+                effectiveTimeoutMs
+              );
+            })
+          ]);
           this.breaker.recordSuccess(toolDef.name);
           return result;
         } catch (e) {
+          if (e instanceof ToolTimeoutError) {
+            getLogger().error(String(e));
+            this.breaker.recordFailure(toolDef.name);
+            return JSON.stringify({
+              error: String(e),
+              fallback: true
+            });
+          }
           lastErr = e;
           if (attempt < totalAttempts - 1) {
             getLogger().warn(
@@ -8756,6 +9531,8 @@ var DefaultToolExecutor = class {
             );
             await new Promise((r) => setTimeout(r, backoffDelayMs(this.retryDelayMs, attempt)));
           }
+        } finally {
+          if (timeoutTimer !== void 0) clearTimeout(timeoutTimer);
         }
       }
       this.breaker.recordFailure(toolDef.name);
@@ -8792,7 +9569,10 @@ var DefaultToolExecutor = class {
                   ...callContext,
                   attempt: attempt + 1
                 }),
-                signal: AbortSignal.timeout(this.requestTimeoutMs)
+                // Use per-tool timeout when set, otherwise fall back to
+                // the executor-level default. Mirrors Python's per-request
+                // ``timeout=`` override on httpx.AsyncClient.post().
+                signal: AbortSignal.timeout(effectiveTimeoutMs)
               });
               if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
               const result = JSON.stringify(await resp.json());
@@ -8942,7 +9722,7 @@ var OpenAILLMProvider = class {
       body.tools = tools;
     }
     const signal = mergeAbortSignals(opts?.signal, AbortSignal.timeout(3e4));
-    const response = await fetch("https://api.openai.com/v1/chat/completions", {
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -8962,50 +9742,55 @@ var OpenAILLMProvider = class {
     if (!reader) return;
     const decoder = new TextDecoder();
     let buffer = "";
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() || "";
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed || !trimmed.startsWith("data: ")) continue;
-        const data = trimmed.slice(6);
-        if (data === "[DONE]") continue;
-        let chunk;
-        try {
-          chunk = JSON.parse(data);
-        } catch {
-          continue;
-        }
-        if (chunk.usage) {
-          const cached = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
-          const uncachedInput = Math.max(0, (chunk.usage.prompt_tokens ?? 0) - cached);
-          yield {
-            type: "usage",
-            inputTokens: uncachedInput,
-            outputTokens: chunk.usage.completion_tokens,
-            cacheReadInputTokens: cached
-          };
-        }
-        const delta = chunk.choices?.[0]?.delta;
-        if (!delta) continue;
-        if (delta.content) {
-          yield { type: "text", content: delta.content };
-        }
-        if (delta.tool_calls) {
-          for (const tc of delta.tool_calls) {
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || !trimmed.startsWith("data: ")) continue;
+          const data = trimmed.slice(6);
+          if (data === "[DONE]") continue;
+          let chunk;
+          try {
+            chunk = JSON.parse(data);
+          } catch {
+            continue;
+          }
+          if (chunk.usage) {
+            const cached = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+            const uncachedInput = Math.max(0, (chunk.usage.prompt_tokens ?? 0) - cached);
             yield {
-              type: "tool_call",
-              index: tc.index,
-              id: tc.id,
-              name: tc.function?.name,
-              arguments: tc.function?.arguments
+              type: "usage",
+              inputTokens: uncachedInput,
+              outputTokens: chunk.usage.completion_tokens,
+              cacheReadInputTokens: cached
             };
           }
+          const delta = chunk.choices?.[0]?.delta;
+          if (!delta) continue;
+          if (delta.content) {
+            yield { type: "text", content: delta.content };
+          }
+          if (delta.tool_calls) {
+            for (const tc of delta.tool_calls) {
+              yield {
+                type: "tool_call",
+                index: tc.index,
+                id: tc.id,
+                name: tc.function?.name,
+                arguments: tc.function?.arguments
+              };
+            }
+          }
         }
       }
+    } finally {
+      reader.cancel().catch(() => {
+      });
     }
   }
 };
@@ -9116,12 +9901,14 @@ ${systemPrompt}` : DEFAULT_PHONE_PREAMBLE;
     const hasAfterLlmResponse = Boolean(hookExecutor?.hasAfterLlmResponse() && hookCtx);
     const hasAfterLlmChunk = Boolean(hookExecutor?.hasAfterLlmChunk());
     const allEmittedText = [];
+    const callId = callContext.call_id;
+    const streamOpts = typeof callId === "string" && callId.length > 0 ? { ...opts, callId } : 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);
@@ -9139,7 +9926,7 @@ ${systemPrompt}` : DEFAULT_PHONE_PREAMBLE;
             chunk.inputTokens ?? 0,
             chunk.outputTokens ?? 0,
             chunk.cacheReadInputTokens ?? 0,
-            chunk.cacheCreationInputTokens ?? 0
+            chunk.cacheWriteInputTokens ?? 0
           );
         } else if (chunk.type === "tool_call") {
           hasToolCalls = true;
@@ -9368,12 +10155,12 @@ var TestSession = class {
           }
           continue;
         }
-        conversationHistory.push({
-          role: "user",
-          text: userInput,
-          timestamp: Date.now()
-        });
         if (onMessage) {
+          conversationHistory.push({
+            role: "user",
+            text: userInput,
+            timestamp: Date.now()
+          });
           try {
             const responseText = await onMessage({
               text: userInput,
@@ -9403,6 +10190,11 @@ var TestSession = class {
           }
           log.info("");
           const responseText = parts.join("");
+          conversationHistory.push({
+            role: "user",
+            text: userInput,
+            timestamp: Date.now()
+          });
           if (responseText) {
             conversationHistory.push({
               role: "assistant",
@@ -9434,6 +10226,7 @@ var TestSession = class {
 export {
   ErrorCode,
   PatterError,
+  PatterConfigError,
   PatterConnectionError,
   AuthenticationError,
   ProvisionError,
@@ -9477,6 +10270,8 @@ export {
   mergeAbortSignals,
   OpenAILLMProvider,
   LLMLoop,
+  openclawConsult,
+  openclawPostCallNotifier,
   DEFAULT_MIN_SENTENCE_LEN,
   SentenceChunker,
   PipelineHookExecutor,