agent.libx.js 0.89.9 → 0.92.2

package/dist/index.js

@@ -851,6 +851,17 @@ ${out}`.trim() : out || "(command succeeded, no output)";
   );
   return `Started background job ${id} \u2014 poll with JobOutput({id:"${id}"}) / JobStatus, stop with JobKill.`;
 }
+function exitSessionTool(onExit) {
+  return {
+    name: "ExitSession",
+    description: `End the current session and exit the CLI. Call this when the user says goodbye, asks to quit, or clearly indicates they want to stop the conversation (e.g. "ok bye", "that's all", "exit", "goodnight").`,
+    parameters: { type: "object", properties: {} },
+    async run() {
+      onExit();
+      return "Session ending. Goodbye!";
+    }
+  };
+}
 function defaultTools() {
   return [bashTool, readTool, editTool];
 }
@@ -2835,7 +2846,15 @@ var Agent = class _Agent {
       toolCallsTotal += toolCalls.length;
       if (o.maxToolCalls && toolCallsTotal > o.maxToolCalls) return kill("max_tool_calls");
       for (const tc of toolCalls) {
-        const content = await this.dispatch(tc);
+        const raw = await this.dispatch(tc);
+        let content;
+        if (typeof raw === "string") {
+          content = raw;
+        } else {
+          const parts = [{ type: "text", text: raw.text }];
+          for (const img of raw.images ?? []) parts.push(imagePart(`data:${img.mimeType};base64,${img.data}`));
+          content = parts;
+        }
         this.transcript.push({ role: "tool", tool_call_id: tc.id, name: tc.function.name, content });
       }
     }
@@ -2892,10 +2911,17 @@ var Agent = class _Agent {
       return earlyError;
     }
     let result;
+    let images;
     let threw = false;
     try {
       log3.debug(`${tc.function.name}(${tc.function.arguments})`);
-      result = await tool.run(args, this.ctx);
+      const raw = await tool.run(args, this.ctx);
+      if (typeof raw === "string") {
+        result = raw;
+      } else {
+        result = raw.text;
+        images = raw.images;
+      }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       log3.debug(`${tc.function.name} -> error: ${msg}`);
@@ -2905,7 +2931,12 @@ var Agent = class _Agent {
     if (!threw) result = await this.maybeAutoTest(tc.function.name, result);
     await hooks?.postToolUse?.(call, result, meta);
     this.options.host?.notify?.({ kind: "tool_result", id: tc.id ?? "", output: result, isError: threw });
-    return result;
+    if (images?.length) {
+      for (const img of images) {
+        this.options.host?.notify?.({ kind: "tool_result_image", id: tc.id ?? "", dataUrl: `data:${img.mimeType};base64,${img.data}` });
+      }
+    }
+    return images?.length ? { text: result, images } : result;
   }
   static WRITE_CLASS = ["Write", "Edit", "MultiEdit", "ApplyEdits"];
   /** Append an autoTest failure section to a write-class tool result, if configured. */
@@ -3452,6 +3483,11 @@ function digestRun(messages, maxChars) {
 import { MemFilesystem as MemFilesystem2 } from "@livx.cc/wcli/core";
 init_logging();
 var log7 = forComponent("DuplexAgent");
+function describeCall(call) {
+  const v = call.args && Object.values(call.args).find((x) => typeof x === "string" && x.trim());
+  const hint = v ? ` (${String(v).replace(/\s+/g, " ").trim().slice(0, 48)})` : "";
+  return `${call.name}${hint}`;
+}
 var DuplexAgentOptions = class {
   /** Any ai.libx.js AIClient — shared by the voice and worker agents (routed by model). */
   ai;
@@ -3472,8 +3508,16 @@ var DuplexAgentOptions = class {
   /** Awaited BEFORE a delegated worker spawns — open a per-task checkpoint frame, audit, etc.
    *  (post-spawn would race the worker's first edits). */
   onTaskStart;
+  /** Re-voice throttled worker progress asides ('[task t1 progress] …') so long tasks aren't dead
+   *  air. Off by default — each update costs a voice turn (LLM call + speech). */
+  progressUpdates = false;
+  /** Min ms between progress re-voices per task. */
+  progressIntervalMs = 25e3;
+  /** Host overrides for QuickLook lookups (keyed by `what`). The engine's defaults go through the
+   *  (possibly jailed) fs — e.g. `.git/**` is deny-listed, so the CLI supplies 'branch' itself. */
+  quickLook;
 };
-var VOICE_SYSTEM_PROMPT = 'You are a spoken voice assistant \u2014 the user HEARS everything you say. Use short sentences. One idea per sentence. No markdown, no bullet lists, no code blocks, no headings, no emoji.\nKeep turns SHORT \u2014 one to three sentences, then stop. Never lecture, enumerate cases, or add caveats unprompted. Conversation is a fast exchange: give the one thing asked, and let the user pull more if they want it.\nYou work in a pair: you talk, and a background worker with FULL access to the user\'s environment (files, shell, web) does the hands-on work. You can find out or do ANYTHING by calling `Delegate` with a clear, self-contained brief \u2014 so NEVER tell the user you can\'t see, access, or do something. Delegate and find out. When the user mentions their project, folder, files, or environment ("this project", "the current folder", "my code"), delegate IMMEDIATELY \u2014 do not ask for paths or details the worker can discover itself. Never pretend to have done the work or invent results \u2014 the worker\'s report is your only source.\nAfter calling Delegate, tell the user you are on it in one short sentence, then end your turn. Do not wait for the result.\nResults arrive later as events like "[task t1 completed] \u2026" or "[task t1 failed] \u2026". When one arrives, summarize it for the ear in one or two short sentences. Never read raw file paths, diffs, or code aloud verbatim.\nDo not fire a second Delegate for work already in flight \u2014 check `TaskStatus` first. Use `CancelTask` when the user asks to stop something.';
+var VOICE_SYSTEM_PROMPT = 'You are a spoken voice assistant \u2014 the user HEARS everything you say. Use short sentences. One idea per sentence. No markdown, no bullet lists, no code blocks, no headings, no emoji.\nKeep turns SHORT \u2014 one to three sentences, then stop. Never lecture, enumerate cases, or add caveats unprompted. Conversation is a fast exchange: give the one thing asked, and let the user pull more if they want it.\nYou work in a pair: you talk, and a background worker with FULL access to the user\'s environment (files, shell, web) does the hands-on work. You can find out or do ANYTHING by calling `Delegate` with a clear, self-contained brief \u2014 so NEVER tell the user you can\'t see, access, or do something. Delegate and find out. When the user mentions their project, folder, files, or environment ("this project", "the current folder", "my code"), delegate IMMEDIATELY \u2014 do not ask for paths or details the worker can discover itself. Never pretend to have done the work or invent results \u2014 the worker\'s report is your only source.\nAfter calling Delegate, tell the user you are on it in one short sentence, then end your turn. Do not wait for the result.\nResults arrive later as events like "[task t1 completed] \u2026" or "[task t1 failed] \u2026". When one arrives, summarize it for the ear in one or two short sentences. "[task t1 progress] \u2026" events are interim status, NOT results \u2014 give at most a half-sentence aside ("still on it \u2014 running tests now") and end your turn. Never present progress as a finished result.\nNever read raw file paths, diffs, or code aloud verbatim.\nDo not fire a second Delegate for work already in flight \u2014 check `TaskStatus` first. Use `CancelTask` when the user asks to stop something.\nPRIORITY: when the user says goodbye or wants to end/finish/wrap up the session ("ok bye", "that\'s all", "let\'s finish", "let\'s end", "goodnight", "exit", "wrap up"), call `ExitSession` IMMEDIATELY \u2014 do not delegate, do not check status, just exit.\nFor TRIVIAL instant lookups only \u2014 current time, git branch, listing a folder, peeking at a small file \u2014 use `QuickLook` (instant, no task). Anything requiring searching, reasoning, running commands, or editing still goes through `Delegate`.\nNEVER claim to have stored, saved, or remembered something durably \u2014 you cannot. Anything the user wants persisted (their name, preferences, notes) must be Delegated so a worker writes it to memory.\nUser messages may arrive via speech-to-text and can carry transcription artifacts \u2014 odd words, cut-offs, homophones ("for you" vs "folder"). Read for INTENT, not surface text. If a message seems garbled or surprising, briefly confirm what they meant ("did you mean\u2026?") instead of answering the literal words.';
 var VOICE_STYLE_CONVERSATIONAL = `Speak like a person in a live conversation, not an assistant reading a script. React first, then deliver: a quick impulsive beat ("oh nice", "hmm, hold on", "ah, got it") before the substance. Use contractions always. Vary sentence length \u2014 some very short. Light fillers and backchannels are fine ("mm-hm", "right", "let's see") but at most one per reply \u2014 never stack them. When you delegate, say it like a human would ("hang on, let me actually dig into that \u2014 gimme a minute") instead of announcing a task. When a result comes back, react to it like you just found out ("okay so \u2014 turns out\u2026"). Match the user's energy: a quick question gets a quick answer \u2014 a few words is a perfectly good turn. Prefer a short answer plus an offer ("want the details?") over covering everything. Never narrate your own mechanics (no "I will now delegate", no task ids out loud).`;
 var DuplexAgent = class {
   options;
@@ -3493,7 +3537,10 @@ var DuplexAgent = class {
       model: o.voiceModel,
       stream: true,
       host: o.host,
-      systemPrompt: VOICE_SYSTEM_PROMPT + (o.voiceStyle === "conversational" ? "\n" + VOICE_STYLE_CONVERSATIONAL : ""),
+      // Runtime context line: without it the voice confidently invents "facts" like today's date
+      // (its training cutoff) instead of delegating or admitting it doesn't know.
+      systemPrompt: VOICE_SYSTEM_PROMPT + (o.voiceStyle === "conversational" ? "\n" + VOICE_STYLE_CONVERSATIONAL : "") + `
+Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}.`,
       instructionFiles: false,
       maxSteps: 8,
       // a voice turn should never loop
@@ -3502,7 +3549,7 @@ var DuplexAgent = class {
       // no defaultTools() — the voice can only Delegate, never touch files itself. Set AFTER the
       // voiceOptions spread (addTools() would be clobbered by the first prepare()); extra voice
       // tools come in via voiceOptions.tools and are merged here.
-      tools: [...o.voiceOptions?.tools ?? [], this.delegateTool(), this.taskStatusTool(), this.cancelTaskTool()]
+      tools: [...o.voiceOptions?.tools ?? [], this.delegateTool(), this.taskStatusTool(), this.cancelTaskTool(), this.quickLookTool()]
     });
   }
   /** One user turn: the voice agent streams the reply (and may Delegate). Serialized with re-voice turns. */
@@ -3555,18 +3602,69 @@ ${recent}` : brief;
   spawnWorker(id, label, briefText) {
     const o = this.options;
     const controller = new AbortController();
+    const base = o.workerOptions?.hooks;
+    const report = o.progressUpdates ? this.progressReporter(id) : void 0;
+    const hooks = report ? {
+      ...base,
+      preToolUse: async (call, meta) => {
+        const d = await base?.preToolUse?.(call, meta);
+        report.pre(call);
+        return d;
+      },
+      postToolUse: async (call, result, meta) => {
+        await base?.postToolUse?.(call, result, meta);
+        report.post(call);
+      }
+    } : base;
     const worker = new Agent({
       ai: o.ai,
       fs: o.fs,
       model: o.workerModel,
       ...o.workerOptions,
       // may override ai/fs/model/tools/… —
+      ...hooks ? { hooks } : {},
       signal: controller.signal
       // …but never the per-task cancellation signal
     });
     const promise = worker.run(briefText).then((res) => this.onWorkerSettled(id, res)).catch((err) => this.onWorkerFailed(id, err));
     this.tasks.set(id, { id, label, status: "running", controller, promise });
   }
+  /** Throttled per-task progress: worker tool calls → at most one progress re-voice per interval.
+   *  Two sources, one throttle: completed steps (post) and a heartbeat for a SINGLE long tool call
+   *  (pre records the in-flight call; a self-cleaning timer narrates "still inside Bash — 70s").
+   *  Completion supersedes: nothing is emitted once the task has settled. */
+  progressReporter(id) {
+    let lastAt = Date.now();
+    let steps = 0;
+    let inflight = null;
+    const due = () => {
+      const rec = this.tasks.get(id);
+      return rec && rec.status === "running" && Date.now() - lastAt >= this.options.progressIntervalMs ? rec : void 0;
+    };
+    const emit = (rec, line, call) => {
+      lastAt = Date.now();
+      this.notify("task_progress", `task ${id} (${rec.label}): ${line}`, { id, steps, call: call.name });
+      this.queueRevoice(`[task ${id} progress] ${line}`);
+    };
+    const timer = setInterval(() => {
+      const rec = this.tasks.get(id);
+      if (!rec || rec.status !== "running") return clearInterval(timer);
+      if (!inflight || !due()) return;
+      emit(rec, `still inside ${describeCall(inflight.call)} \u2014 ${Math.round((Date.now() - inflight.at) / 1e3)}s on this step`, inflight.call);
+    }, Math.max(this.options.progressIntervalMs, 250));
+    timer.unref?.();
+    return {
+      pre: (call) => {
+        inflight = { call, at: Date.now() };
+      },
+      post: (call) => {
+        steps++;
+        inflight = null;
+        const rec = due();
+        if (rec) emit(rec, `still running \u2014 ${steps} steps so far, now: ${describeCall(call)}`, call);
+      }
+    };
+  }
   onWorkerSettled(id, res) {
     const rec = this.tasks.get(id);
     if (res.finishReason === "aborted" || rec.status === "cancelled") {
@@ -3627,6 +3725,58 @@ ${recent}` : brief;
       }
     };
   }
+  /** Sub-100ms read-only lookups the voice may do itself — everything else stays Delegate-only.
+   *  fs-only (no shell; the engine is VFS-abstracted): time, git branch (.git/HEAD read), ls, file
+   *  head. Output is hard-capped so a lookup can never bloat the skinny voice context. */
+  quickLookTool() {
+    const CAP = 2e3;
+    const kinds = [.../* @__PURE__ */ new Set(["time", "branch", "ls", "file", ...Object.keys(this.options.quickLook ?? {})])];
+    return {
+      name: "QuickLook",
+      description: `Instant read-only lookup \u2014 one of: ${kinds.join(", ")}. For trivial facts only; anything needing search, commands, or reasoning goes through Delegate.`,
+      parameters: {
+        type: "object",
+        required: ["what"],
+        properties: {
+          what: { type: "string", enum: kinds, description: "what to look up" },
+          path: { type: "string", description: "for ls/file: the path to look at" }
+        }
+      },
+      run: async ({ what, path }) => {
+        const fs = this.options.fs;
+        try {
+          const over = this.options.quickLook?.[String(what)];
+          if (over) return await over(path ? String(path) : void 0);
+          switch (String(what)) {
+            case "time":
+              return (/* @__PURE__ */ new Date()).toString();
+            case "branch": {
+              if (!fs) return "unavailable (no filesystem)";
+              const head = (await fs.readFile(".git/HEAD")).trim();
+              return head.startsWith("ref: refs/heads/") ? `branch: ${head.slice("ref: refs/heads/".length)}` : `detached HEAD at ${head.slice(0, 12)}`;
+            }
+            case "ls": {
+              if (!fs) return "unavailable (no filesystem)";
+              const names = await fs.readDir(String(path ?? "."));
+              return names.slice(0, 50).join("\n") + (names.length > 50 ? `
+\u2026 (+${names.length - 50} more)` : "");
+            }
+            case "file": {
+              if (!fs) return "unavailable (no filesystem)";
+              if (!path) return "file lookup needs a path";
+              const text = await fs.readFile(String(path));
+              return text.length > CAP ? text.slice(0, CAP) + `
+\u2026 (truncated \u2014 ${text.length} chars total; Delegate for the full file)` : text;
+            }
+            default:
+              return `unknown lookup '${what}'`;
+          }
+        } catch (e) {
+          return `lookup failed: ${e?.message ?? e}`;
+        }
+      }
+    };
+  }
   cancelTaskTool() {
     return {
       name: "CancelTask",
@@ -3645,15 +3795,26 @@ ${recent}` : brief;
 };
 
 // src/mcp.ts
-function toText(result) {
-  if (result == null) return "";
-  if (typeof result === "string") return result;
+function toResult(result) {
+  if (result == null) return { text: "" };
+  if (typeof result === "string") return { text: result };
   const content = result.content;
   if (Array.isArray(content)) {
-    const text = content.map((c) => typeof c?.text === "string" ? c.text : JSON.stringify(c)).join("\n");
-    if (text) return text;
+    const texts = [];
+    const images = [];
+    for (const c of content) {
+      if (c?.type === "image" && typeof c.data === "string" && c.mimeType) {
+        images.push({ mimeType: c.mimeType, data: c.data });
+      } else if (typeof c?.text === "string") {
+        texts.push(c.text);
+      } else {
+        texts.push(JSON.stringify(c));
+      }
+    }
+    const text = texts.join("\n");
+    if (text || images.length) return { text, ...images.length ? { images } : {} };
   }
-  return JSON.stringify(result);
+  return { text: JSON.stringify(result) };
 }
 function mcpToolToAgentTool(spec, callTool, prefix = "mcp__") {
   return {
@@ -3661,7 +3822,8 @@ function mcpToolToAgentTool(spec, callTool, prefix = "mcp__") {
     description: spec.description ?? `MCP tool ${spec.name}`,
     parameters: spec.inputSchema ?? { type: "object", properties: {} },
     async run(args, _ctx) {
-      return toText(await callTool(spec.name, args ?? {}));
+      const r = toResult(await callTool(spec.name, args ?? {}));
+      return r.images?.length ? r : r.text;
     }
   };
 }
@@ -3703,7 +3865,8 @@ function makeMcpToolSearch(specs, callTool, options = {}) {
     async run({ name, args }) {
       const n = String(name ?? "");
       if (!byName.has(n)) return `Error: unknown MCP tool '${n}'. Use ToolSearch to find valid names.`;
-      return toText(await callTool(n, args ?? {}));
+      const r = toResult(await callTool(n, args ?? {}));
+      return r.images?.length ? r : r.text;
     }
   };
   return [searchTool, callMcpTool];
@@ -3761,11 +3924,471 @@ var RecordingLifecycle = class {
 
 // src/index.ts
 init_logging();
+
+// src/voice/engine.ts
+init_logging();
+var log8 = forComponent("VoiceEngine");
+var now = () => performance.now();
+var VoiceEngineOptions = class {
+  stt;
+  tts;
+  player;
+  /** a final utterance arrived (endpoint) — host dispatches it as a turn */
+  onUtterance = () => {
+  };
+  /** live partial transcript while listening (host renders the 🎤 line) */
+  onPartial = () => {
+  };
+  onState = () => {
+  };
+  /** user spoke/acted over playback — host aborts the in-flight turn (called AFTER audio is killed).
+   *  phase: 'speaking' = cut mid-speech (real interruption); 'drain' = in the final audio tail
+   *  (normal turn-taking — hosts shouldn't alarm). */
+  onBargeIn = () => {
+  };
+  /** spoken micro-ack on utterance endpoint (masks LLM TTFT); '' disables */
+  ackPhrase = "";
+  /** Endpoint merge window (ms): hold an endpointed utterance briefly — if speech resumes (spelled
+   *  letters, mid-thought pauses), the next utterance MERGES instead of dispatching a truncated one
+   *  ("E-L-Y." / "A."). Costs this much latency per turn; 0 disables. */
+  utteranceMergeMs = 350;
+  /** heuristic (non-AEC) energy barge-in tuning */
+  bargeRmsMult = 2;
+  bargeRmsFloor = 500;
+};
+var VoiceEngine = class {
+  options;
+  state = "idle";
+  stt;
+  tts;
+  player;
+  speaking = false;
+  // audible (deltas flowing OR audio draining)
+  ctxOpen = false;
+  // the current TTS context still accepts deltas (false once end-frame sent)
+  interrupted = false;
+  // barge-in latch: drop in-flight deltas until the next legitimate turn
+  spokeDeltas = false;
+  // a TTS context is open for the current spoken turn
+  drainTimer = null;
+  // heuristic tier state (inert under AEC) — frozen as validated in the experiment
+  echoWords = /* @__PURE__ */ new Set();
+  prevReply = "";
+  reply = "";
+  echoUntil = 0;
+  baseline = 0;
+  hot = 0;
+  suspectUntil = 0;
+  ackAt = 0;
+  // when the micro-ack was spoken — its echo can leak before the AEC filter converges
+  pendingUtt = "";
+  // endpointed text held for the merge window
+  pendingTimer = null;
+  lastInterrupted = null;
+  constructor(options) {
+    this.options = { ...new VoiceEngineOptions(), ...options };
+    const o = this.options;
+    if (!o.stt || !o.tts || !o.player) throw new Error("VoiceEngine needs stt, tts and player (see cli/voice.ts VoiceIO for platform defaults)");
+    this.stt = o.stt;
+    this.tts = o.tts;
+    this.player = o.player;
+  }
+  async start() {
+    this.tts.onAudio = (c) => {
+      if (this.speaking) this.player.write(c);
+    };
+    this.stt.onPartial = (text) => this.handlePartial(text);
+    this.stt.onUtterance = (text) => this.handleUtterance(text);
+    this.stt.onLevel = (rms) => this.handleLevel(rms);
+    await Promise.all([this.tts.connect(), this.stt.start()]);
+    this.setState("listening");
+    log8.info(`voice I/O up (${this.stt.usingAec ? "AEC" : "heuristic echo"} capture)`);
+  }
+  get usingAec() {
+    return this.stt.usingAec;
+  }
+  idleWaiters = [];
+  setState(s) {
+    if (this.state === s) return;
+    this.state = s;
+    this.options.onState(s);
+    if (s !== "speaking" && s !== "thinking") {
+      for (const r of this.idleWaiters.splice(0)) r();
+    }
+  }
+  /** Resolve when the engine is no longer speaking (immediate if already idle). */
+  awaitIdle() {
+    if (this.state !== "speaking" && this.state !== "thinking") return Promise.resolve();
+    return new Promise((r) => this.idleWaiters.push(r));
+  }
+  // --- speaking side (host-driven) ---
+  /** open a spoken turn (idempotent — safe from both onUtterance and first-delta paths).
+   *  `ack` speaks the configured micro-ack as the context opener (utterance path only —
+   *  masks LLM TTFT; re-voice turns begun by their first delta skip it). */
+  beginSpeech(ack = false) {
+    if (this.speaking && this.ctxOpen) return;
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
+    this.interrupted = false;
+    if (!this.speaking) this.player.markTurn();
+    this.speaking = true;
+    this.ctxOpen = true;
+    this.spokeDeltas = false;
+    this.reply = "";
+    this.echoWords = new Set(this.words(this.prevReply));
+    this.tts.newContext();
+    if (ack && this.options.ackPhrase) {
+      this.tts.speak(this.options.ackPhrase + " ", true);
+      this.spokeDeltas = true;
+      this.ackAt = now();
+    }
+    this.setState("thinking");
+  }
+  speakDelta(text) {
+    if (this.interrupted) return;
+    if (!this.speaking || !this.ctxOpen) this.beginSpeech();
+    this.reply += text;
+    for (const w of this.words(this.reply)) this.echoWords.add(w);
+    this.tts.speak(text, true);
+    this.spokeDeltas = true;
+    this.setState("speaking");
+  }
+  /** close the spoken turn (idempotent); stays audible until ALL audio arrived AND playback drains */
+  endSpeech() {
+    this.interrupted = false;
+    if (!this.speaking) return;
+    this.ctxOpen = false;
+    if (this.reply) this.prevReply = this.reply;
+    const settle = () => {
+      if (this.ctxOpen) {
+        this.drainTimer = null;
+        return;
+      }
+      this.drainTimer = null;
+      this.speaking = false;
+      this.echoUntil = now() + 2500;
+      if (!this.usingAec) this.stt.reset();
+      this.setState("listening");
+    };
+    const drainThenSettle = () => {
+      if (this.drainTimer) clearTimeout(this.drainTimer);
+      this.drainTimer = setTimeout(settle, this.player.drainMs() + 300);
+    };
+    if (this.spokeDeltas) {
+      this.tts.onDone = drainThenSettle;
+      this.tts.end();
+      if (this.drainTimer) clearTimeout(this.drainTimer);
+      this.drainTimer = setTimeout(drainThenSettle, 15e3);
+    } else drainThenSettle();
+  }
+  /** text of the reply cut by the last barge-in — consumed by the host to tell the model what
+   *  the user did NOT hear. Cleared on read. */
+  takeInterruptedReply() {
+    const r = this.lastInterrupted;
+    this.lastInterrupted = null;
+    return r;
+  }
+  /** barge-in: stop audio NOW, cancel generation, reset for the user's utterance */
+  interrupt() {
+    if (!this.speaking && !this.drainTimer) return;
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
+    const heardChars = Math.round(Math.max(0, this.player.playedMs()) / 1e3 * 15);
+    if (this.reply) this.lastInterrupted = { full: this.reply, heard: this.reply.slice(0, heardChars) };
+    this.speaking = false;
+    this.ctxOpen = false;
+    this.interrupted = true;
+    this.suspectUntil = 0;
+    this.echoUntil = now() + 2500;
+    this.tts.cancel();
+    this.player.kill();
+    if (!this.usingAec) this.stt.reset();
+    if (this.reply) this.prevReply = this.reply;
+    this.setState("listening");
+  }
+  stop() {
+    if (this.pendingTimer) clearTimeout(this.pendingTimer);
+    if (this.drainTimer) clearTimeout(this.drainTimer);
+    this.stt.stop();
+    this.player.kill();
+    this.tts.close();
+    this.setState("idle");
+  }
+  // --- listening side (STT-driven) ---
+  words(s) {
+    return s.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((w) => w.length >= 2);
+  }
+  novelWords(text) {
+    return this.words(text).filter((w) => !this.echoWords.has(w));
+  }
+  echoActive() {
+    return this.speaking || now() < this.echoUntil;
+  }
+  handlePartial(text) {
+    if (this.speaking) {
+      const barge = this.novelWords(text).length >= (this.usingAec ? 1 : this.suspectUntil ? 1 : 2);
+      if (barge) {
+        const phase = this.ctxOpen ? "speaking" : "drain";
+        this.interrupt();
+        this.options.onBargeIn(phase);
+      }
+      return;
+    }
+    if (this.pendingUtt && text.trim()) {
+      if (this.pendingTimer) {
+        clearTimeout(this.pendingTimer);
+        this.pendingTimer = null;
+      }
+    }
+    if (!this.echoActive() || this.novelWords(text).length >= 1) this.options.onPartial(text);
+  }
+  handleUtterance(text) {
+    if (this.echoActive() && this.novelWords(text).length < (this.usingAec ? 1 : 2)) {
+      this.stt.reset();
+      return;
+    }
+    const squash = (t) => t.toLowerCase().replace(/[^a-z]/g, "").replace(/(.)\1+/g, "$1");
+    if (this.ackAt && now() - this.ackAt < 6e3 && squash(text) === squash(this.options.ackPhrase)) {
+      this.ackAt = 0;
+      return;
+    }
+    this.pendingUtt = this.pendingUtt ? `${this.pendingUtt} ${text}` : text;
+    if (this.pendingTimer) clearTimeout(this.pendingTimer);
+    if (!this.options.utteranceMergeMs) return this.flushUtterance();
+    this.pendingTimer = setTimeout(() => this.flushUtterance(), this.options.utteranceMergeMs);
+  }
+  flushUtterance() {
+    if (this.pendingTimer) {
+      clearTimeout(this.pendingTimer);
+      this.pendingTimer = null;
+    }
+    const text = this.pendingUtt;
+    this.pendingUtt = "";
+    if (text) this.options.onUtterance(text);
+  }
+  /** energy two-stage barge-in (heuristic tier only): spike over echo baseline → pause + confirm via STT */
+  handleLevel(rms) {
+    if (this.usingAec) return;
+    if (!this.speaking) {
+      this.baseline = 0;
+      this.hot = 0;
+      return;
+    }
+    if (!this.baseline) {
+      this.baseline = rms;
+      return;
+    }
+    this.baseline = this.baseline * 0.9 + rms * 0.1;
+    if (rms > Math.max(this.baseline * this.options.bargeRmsMult, this.options.bargeRmsFloor)) this.hot++;
+    else this.hot = 0;
+    if (this.hot >= 2 && !this.suspectUntil) {
+      this.suspectUntil = now() + 1300;
+      setTimeout(() => {
+        this.suspectUntil = 0;
+      }, 1350);
+    }
+  }
+};
+
+// src/voice/soniox.ts
+init_logging();
+
+// src/voice/types.ts
+var STT_SAMPLE_RATE = 16e3;
+var TTS_SAMPLE_RATE = 44100;
+async function resolveAuth(auth) {
+  return typeof auth === "function" ? await auth() : auth;
+}
+
+// src/voice/soniox.ts
+var log9 = forComponent("SonioxSTT");
+var now2 = () => performance.now();
+var SonioxSTTOptions = class {
+  auth = "";
+  source;
+  model = "stt-rt-preview";
+  languageHints = ["en"];
+};
+var SonioxSTT = class {
+  options;
+  ws;
+  stopped = false;
+  sourceStarted = false;
+  onPartial = () => {
+  };
+  onUtterance = () => {
+  };
+  /** mic energy (RMS) per chunk — drives the energy-based heuristic barge-in tier */
+  onLevel = () => {
+  };
+  finalText = "";
+  partialText = "";
+  constructor(options) {
+    this.options = { ...new SonioxSTTOptions(), ...options };
+  }
+  get usingAec() {
+    return this.options.source?.aec ?? false;
+  }
+  async connectWs() {
+    const apiKey = await resolveAuth(this.options.auth);
+    this.ws = new WebSocket("wss://stt-rt.soniox.com/transcribe-websocket");
+    await new Promise((res, rej) => {
+      this.ws.onopen = () => res();
+      this.ws.onerror = (e) => rej(new Error(`soniox ws: ${e.message || "connect failed"}`));
+    });
+    this.ws.send(
+      JSON.stringify({
+        api_key: apiKey,
+        model: this.options.model,
+        audio_format: "pcm_s16le",
+        sample_rate: STT_SAMPLE_RATE,
+        num_channels: 1,
+        language_hints: this.options.languageHints,
+        enable_endpoint_detection: true
+      })
+    );
+    this.ws.onmessage = (ev) => this.handle(JSON.parse(String(ev.data)));
+    this.ws.onclose = (ev) => {
+      if (this.stopped) return;
+      log9.warn(`soniox ws closed (${ev.code} ${ev.reason || ""}) \u2014 reconnecting`);
+      this.reset();
+      this.connectWs().catch((e) => log9.error(`soniox reconnect failed: ${e.message}`));
+    };
+  }
+  async start() {
+    await this.connectWs();
+    if (this.sourceStarted) return;
+    this.sourceStarted = true;
+    await this.options.source.start((chunk) => {
+      let sum = 0;
+      const view = new DataView(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+      for (let i = 0; i + 1 < chunk.byteLength; i += 2) {
+        const v = view.getInt16(i, true);
+        sum += v * v;
+      }
+      this.onLevel(Math.sqrt(sum / (chunk.byteLength / 2)));
+      if (this.ws.readyState === WebSocket.OPEN) this.ws.send(chunk);
+    });
+  }
+  handle(m) {
+    if (m.error_message) return log9.error(`soniox: ${m.error_message}`);
+    let endpoint = false;
+    for (const t of m.tokens ?? []) {
+      if (t.text === "<end>") endpoint = true;
+      else if (t.is_final) this.finalText += t.text;
+    }
+    this.partialText = (m.tokens ?? []).filter((t) => !t.is_final && t.text !== "<end>").map((t) => t.text).join("");
+    this.onPartial(this.finalText + this.partialText);
+    if (endpoint && this.finalText.trim()) {
+      const utterance = this.finalText.trim();
+      this.reset();
+      this.onUtterance(utterance, now2());
+    }
+  }
+  reset() {
+    this.finalText = "";
+    this.partialText = "";
+  }
+  stop() {
+    this.stopped = true;
+    this.options.source?.stop();
+    if (this.ws) this.ws.onclose = null;
+    this.ws?.close();
+  }
+};
+
+// src/voice/cartesia.ts
+init_logging();
+var log10 = forComponent("CartesiaTTS");
+var now3 = () => performance.now();
+var CartesiaTTSOptions = class {
+  auth = "";
+  voiceId = "";
+  model = "sonic-3.5";
+  /** 'apiKey' (server/CLI) → `api_key=` URL param; 'token' (browser, BE-minted) → `access_token=`. */
+  authMode = "apiKey";
+};
+var CartesiaTTS = class {
+  options;
+  ws;
+  ctxSeq = 0;
+  ctxId = "";
+  onAudio = () => {
+  };
+  onDone = () => {
+  };
+  firstAudioAt = 0;
+  constructor(options) {
+    this.options = { ...new CartesiaTTSOptions(), ...options };
+  }
+  async connect() {
+    const key = await resolveAuth(this.options.auth);
+    const param = this.options.authMode === "token" ? "access_token" : "api_key";
+    this.ws = new WebSocket(`wss://api.cartesia.ai/tts/websocket?cartesia_version=2026-03-01&${param}=${key}`);
+    await new Promise((res, rej) => {
+      this.ws.onopen = () => res();
+      this.ws.onerror = (e) => rej(new Error(`cartesia ws: ${e.message || "connect failed"}`));
+    });
+    this.ws.onclose = (ev) => log10.warn(`cartesia ws closed (${ev.code} ${ev.reason || ""})`);
+    this.ws.onmessage = (ev) => {
+      const m = JSON.parse(String(ev.data));
+      if (m.context_id && m.context_id !== this.ctxId) return;
+      if (m.type === "chunk" && m.data) {
+        if (!this.firstAudioAt) this.firstAudioAt = now3();
+        this.onAudio(base64ToBytes(m.data));
+      } else if (m.type === "done") this.onDone();
+      else if (m.type === "error" && !/already been cancelled|does not exist/.test(m.message || "")) log10.warn(`cartesia: ${JSON.stringify(m)}`);
+    };
+  }
+  newContext() {
+    this.ctxId = `ctx-${++this.ctxSeq}`;
+    this.firstAudioAt = 0;
+    return this.ctxId;
+  }
+  frame(transcript, cont) {
+    return JSON.stringify({
+      model_id: this.options.model,
+      transcript,
+      voice: { mode: "id", id: this.options.voiceId },
+      output_format: { container: "raw", encoding: "pcm_s16le", sample_rate: TTS_SAMPLE_RATE },
+      context_id: this.ctxId,
+      continue: cont
+    });
+  }
+  speak(text, cont) {
+    if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(this.frame(text, cont));
+  }
+  end() {
+    if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(this.frame("", false));
+  }
+  cancel() {
+    if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify({ context_id: this.ctxId, cancel: true }));
+  }
+  close() {
+    if (this.ws) this.ws.onclose = null;
+    this.ws?.close();
+  }
+};
+function base64ToBytes(b64) {
+  if (typeof Buffer !== "undefined") return Buffer.from(b64, "base64");
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+// src/index.ts
 import { MemFilesystem as MemFilesystem3, IndexedDbFilesystem, CommandExecutor as CommandExecutor2, registerHeadlessCommands as registerHeadlessCommands2 } from "@livx.cc/wcli/core";
 export {
   Agent,
   AgentOptions,
   BodDbFilesystem,
+  CartesiaTTS,
+  CartesiaTTSOptions,
   CommandExecutor2 as CommandExecutor,
   ConsoleHostBridge,
   DEFAULT_DENY,
@@ -3785,9 +4408,15 @@ export {
   PermissionPolicy,
   RecordingHooks,
   RecordingLifecycle,
+  STT_SAMPLE_RATE,
   SandboxJobRegistry,
   ScriptedHostBridge,
+  SonioxSTT,
+  SonioxSTTOptions,
+  TTS_SAMPLE_RATE,
   VOICE_SYSTEM_PROMPT,
+  VoiceEngine,
+  VoiceEngineOptions,
   applyEditsTool,
   askUserQuestionTool,
   bashTool,
@@ -3799,6 +4428,7 @@ export {
   defaultTools,
   diskAgentOptions,
   editTool,
+  exitSessionTool,
   expandCommand,
   expandTemplate,
   forComponent,
@@ -3835,6 +4465,7 @@ export {
   relevanceScore,
   repoIndex,
   repoMapTool,
+  resolveAuth,
   rollbackTool,
   sandboxAgentOptions,
   slugify,