agent.libx.js 0.93.8 → 0.93.10

package/dist/index.js

@@ -1978,7 +1978,7 @@ IMPLICIT CAPTURE: when the user shares their name, role, a preference, a correct
 For explicit "remember X" requests, also call Remember directly and confirm briefly ("got it").
 Do NOT remember: transient task details, conversation filler, things you'd forget in a real conversation.
 Keep it invisible: never announce "saving to memory" or list what you remembered unless asked.
-For anything requiring files, shell, or web \u2014 still Delegate.`;
+For anything requiring files, shell, or web \u2014 still Act.`;
 async function loadMemory(fs, dir, opts = {}) {
   const dirs = (Array.isArray(dir) ? dir : [dir]).filter(Boolean);
   const writeDir = dirs[0];
@@ -2687,6 +2687,10 @@ var AgentOptions = class {
   autoTest;
   /** Provider-specific options forwarded to ai.chat() (e.g. cursor mcpServers, cwd). */
   providerOptions;
+  /** Prompt caching (providers that support it, e.g. Anthropic): cache tools/system/conversation
+   *  prefix across the loop's steps — reads cost 0.1x, writes 1.25x. A multi-step agent loop
+   *  re-sends its whole prefix every step, so this is a large net cost cut. Default on. */
+  promptCache = true;
   /** Tool selection mode: 'auto' = model decides (needed for Groq); undefined = provider default. */
   toolChoice;
   /** Extended-thinking / reasoning effort, normalized across providers (anthropic, openai).
@@ -2876,7 +2880,7 @@ var Agent = class _Agent {
     const wireTools = toWireTools(this.activeTools);
     const useStream = o.stream === true && typeof o.host?.notify === "function";
     let steps = 0;
-    const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
     let usageEstimated = false;
     const start = Date.now();
     let toolCallsTotal = 0;
@@ -2907,6 +2911,7 @@ var Agent = class _Agent {
       } : void 0;
       const reasonOpts = {
         ...frag,
+        ...o.promptCache ? { promptCache: true } : {},
         ...o.providerOptions || cursorPo ? { providerOptions: { ...frag.providerOptions, ...o.providerOptions, ...cursorPo } } : {}
       };
       try {
@@ -2934,6 +2939,8 @@ var Agent = class _Agent {
         usage.promptTokens += res.usage.promptTokens ?? 0;
         usage.completionTokens += res.usage.completionTokens ?? 0;
         usage.totalTokens += res.usage.totalTokens ?? 0;
+        usage.cacheCreationTokens += res.usage.cacheCreationTokens ?? 0;
+        usage.cacheReadTokens += res.usage.cacheReadTokens ?? 0;
       }
       const toolCalls = res.toolCalls ?? [];
       this.transcript.push({
@@ -3606,15 +3613,18 @@ function describeCall(call) {
   return `${call.name}${hint}`;
 }
 var DuplexAgentOptions = class {
-  /** Any ai.libx.js AIClient — shared by the voice and worker agents (routed by model). */
+  /** Any ai.libx.js AIClient — shared by all tiers (routed by model). */
   ai;
-  /** The WORKER's filesystem. If omitted the worker keeps Agent's jailed-disk-at-cwd default. */
+  /** The WORKER's filesystem (act + think). If omitted the worker keeps Agent's jailed-disk-at-cwd default. */
   fs;
-  voiceModel = "groq/openai/gpt-oss-20b";
-  workerModel = "anthropic/claude-sonnet-4-6";
+  reflexModel = "groq/openai/gpt-oss-20b";
+  actModel = "anthropic/claude-sonnet-4-6";
+  /** Premium reasoning model. Set to `false` to disable the Think tier entirely. */
+  thinkModel = "anthropic/claude-opus-4-6";
   /** Escape hatches merged over the derived per-agent options. */
-  voiceOptions;
-  workerOptions;
+  reflexOptions;
+  actOptions;
+  thinkOptions;
   /** Receives the voice text_delta stream + task lifecycle events. */
   host;
   /** How many recent transcript messages are rendered into a worker's brief. */
@@ -3622,7 +3632,7 @@ var DuplexAgentOptions = class {
   /** Voice register: 'neutral' = clean spoken style; 'conversational' = human-like — fillers,
    *  backchannels, impulsive first reactions before content (mimics real duplex conversation). */
   voiceStyle = "neutral";
-  /** Awaited BEFORE a delegated worker spawns — open a per-task checkpoint frame, audit, etc.
+  /** Awaited BEFORE a 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
@@ -3645,8 +3655,10 @@ var DuplexAgentOptions = class {
   /** User-scope memory dir for global facts (type=user/feedback). Forwarded to Remember's routing. */
   memoryUserDir;
 };
-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.\n"[task t1 asks] \u2026" events are QUESTIONS from a background task \u2014 relay to the user in your own words, short, then end your turn. When the user answers, call `AnswerTask` with that id and their answer. NEVER answer on the user\'s behalf for permissions or risky operations; if their reply is ambiguous, confirm first.\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`.\n{{MEMORY_SLOT}}\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 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 have three cognitive tiers \u2014 like a human brain:\n\u2022 YOU (reflex) \u2014 instant, lightweight. Handle greetings, simple questions, status checks, QuickLook.\n\u2022 `Act` \u2014 your hands. A standard background worker with FULL access to the user\'s environment (files, shell, web). Use for reading, editing, searching, running tasks, building \u2014 any real work.\n{{THINK_SLOT}}\nYou can find out or do ANYTHING by calling `Act` with a clear, self-contained brief \u2014 so NEVER tell the user you can\'t see, access, or do something. Act and find out. When the user mentions their project, folder, files, or environment ("this project", "the current folder", "my code"), call `Act` 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 Act or Think, 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.\n"[task t1 asks] \u2026" events are QUESTIONS from a background task \u2014 relay to the user in your own words, short, then end your turn. When the user answers, call `AnswerTask` with that id and their answer. NEVER answer on the user\'s behalf for permissions or risky operations; if their reply is ambiguous, confirm first.\nIf the user\'s message sounds INCOMPLETE \u2014 trailing off mid-sentence, a fragment that needs more context ("and then we", "but the problem is"), hesitation fillers ("uh", "um") \u2014 call `Hold` instead of answering. This keeps listening for the rest of their thought. Only respond with substance when you have a complete question or request.\nDispatch discipline: send ONE self-contained task per request \u2014 a single worker with the full brief beats several workers with fragments (each worker starts fresh and re-discovers context). NEVER dispatch a worker just to read files or gather information \u2014 workers explore and discover context themselves; pass on what you already know and let one worker do the whole job. Split into parallel tasks only when the user asks for genuinely independent things. When a task completes, report its result and stop \u2014 do NOT dispatch follow-up work (verification, polish, extras) the user did not ask for, unless the report itself signals failure or doubt.\nDo not fire a second Act/Think 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 act, 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 goes through `Act`.\n{{MEMORY_SLOT}}\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 THINK_GUIDANCE = "\u2022 `Think` \u2014 your brain. A premium reasoning model, FAR more expensive than Act. Reserve it for open-ended architecture/design questions, or a problem Act already FAILED at. ALL implementation work \u2014 coding, refactoring, debugging, edge cases, tests \u2014 goes to Act; Act is highly capable. Never send the same work to both.";
+var THINK_DISABLED_GUIDANCE = "(Think tier is not available \u2014 use Act for all escalations.)";
+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 escalate to Act or Think, 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 act", no task ids out loud).`;
 var DuplexAgent = class {
   options;
   voice;
@@ -3665,21 +3677,32 @@ var DuplexAgent = class {
     if (o.memoryDir && o.fs) {
       this.memoryReady = loadMemory(o.fs, o.memoryDir, { maxWritesPerSession: 10, userDir: o.memoryUserDir });
     }
-    const memSlot = o.memoryDir && o.fs ? VOICE_MEMORY_PROMPT : "NEVER 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.";
-    const prompt = VOICE_SYSTEM_PROMPT.replace("{{MEMORY_SLOT}}", memSlot) + (o.voiceStyle === "conversational" ? "\n" + VOICE_STYLE_CONVERSATIONAL : "") + `
+    const memSlot = o.memoryDir && o.fs ? VOICE_MEMORY_PROMPT : "NEVER claim to have stored, saved, or remembered something durably \u2014 you cannot. Anything the user wants persisted (their name, preferences, notes) must go through Act so a worker writes it to memory.";
+    const thinkSlot = o.thinkModel !== false ? THINK_GUIDANCE : THINK_DISABLED_GUIDANCE;
+    const prompt = VOICE_SYSTEM_PROMPT.replace("{{MEMORY_SLOT}}", memSlot).replace("{{THINK_SLOT}}", thinkSlot) + (o.voiceStyle === "conversational" ? "\n" + VOICE_STYLE_CONVERSATIONAL : "") + `
 Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}.`;
+    const tools = [
+      ...o.reflexOptions?.tools ?? [],
+      this.actTool(),
+      ...o.thinkModel !== false ? [this.thinkTool()] : [],
+      this.taskStatusTool(),
+      this.cancelTaskTool(),
+      this.quickLookTool(),
+      this.answerTaskTool(),
+      this.holdTool()
+    ];
     this.voice = new Agent({
       ai: o.ai,
       fs: new MemFilesystem2(),
-      model: o.voiceModel,
+      model: o.reflexModel,
       stream: true,
       host: o.host,
       systemPrompt: prompt,
       instructionFiles: false,
       maxSteps: 8,
       timeoutMs: 3e4,
-      ...o.voiceOptions,
-      tools: [...o.voiceOptions?.tools ?? [], this.delegateTool(), this.taskStatusTool(), this.cancelTaskTool(), this.quickLookTool(), this.answerTaskTool()]
+      ...o.reflexOptions,
+      tools
     });
   }
   /** Resolve memory tools + inject index into voice system prompt (once). */
@@ -3690,7 +3713,7 @@ Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}.`;
     this.voice.options.tools.push(...mem.tools);
     if (mem.index) this.voice.options.systemPrompt += "\n\n" + mem.index;
   }
-  /** One user turn: the voice agent streams the reply (and may Delegate). Serialized with re-voice turns. */
+  /** One user turn: the voice agent streams the reply (and may Act/Think). Serialized with re-voice turns. */
   send(content) {
     return this.enqueue(async () => {
       await this.initMemory();
@@ -3731,19 +3754,25 @@ Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}.`;
       this.notify("revoice_done", "");
     });
   }
-  /** The worker's brief: the Delegate args + a STATIC text snapshot of the recent conversation. */
-  buildBrief(brief) {
+  /** The worker's brief: the Act/Think args + a STATIC text snapshot of the recent conversation.
+   *  Act briefs get a self-verify footer — the worker's report is trusted without review, so it
+   *  must check its own work before reporting (nearly free under prompt caching; measured honest:
+   *  it does NOT fix one-shot logic bugs — see mind/10). Think tasks are pure reasoning — no footer. */
+  buildBrief(brief, tier = "act") {
     const recent = this.voice.transcript.filter((m) => (m.role === "user" || m.role === "assistant") && contentText(m.content).trim()).slice(-this.options.excerptTurns).map((m) => `${m.role}: ${contentText(m.content)}`).join("\n");
-    return recent ? `${brief}
+    const verify = tier === "act" ? "\n\nBefore reporting done: re-read what you changed and check it against EVERY requirement above \u2014 fix any gap first. Your report is trusted without review." : "";
+    return (recent ? `${brief}
 
 ## Recent conversation (for context)
-${recent}` : brief;
+${recent}` : brief) + verify;
   }
   /** Spawn a detached worker for task `id`; its settlement notifies + enqueues the re-voice turn. */
-  spawnWorker(id, label, briefText) {
+  spawnWorker(id, label, briefText, tier = "act") {
     const o = this.options;
+    const tierOpts = tier === "think" ? o.thinkOptions : o.actOptions;
+    const tierModel = tier === "think" ? o.thinkModel : o.actModel;
     const controller = new AbortController();
-    const base = o.workerOptions?.hooks;
+    const base = tierOpts?.hooks ?? o.actOptions?.hooks;
     const report = o.progressUpdates ? this.progressReporter(id) : void 0;
     const hooks = report ? {
       ...base,
@@ -3770,13 +3799,12 @@ ${recent}` : brief;
     const worker = new Agent({
       ai: o.ai,
       fs: o.fs,
-      model: o.workerModel,
-      ...o.workerOptions,
-      // may override ai/fs/model/tools/… —
+      model: tierModel,
+      ...tier === "think" ? { reasoning: tierOpts?.reasoning ?? "high" } : {},
+      ...tierOpts,
       ...workerHost ? { host: workerHost } : {},
       ...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 });
@@ -3864,7 +3892,14 @@ ${recent}` : brief;
     }
     rec.status = "done";
     log7.verbose(`task ${id} done (${res.steps} steps)`);
-    this.notify("task_done", `task ${id} (${rec.label}) completed`, { id, text: res.text, usage: res.usage, usageEstimated: res.usageEstimated });
+    this.notify("task_done", `task ${id} (${rec.label}) completed`, {
+      id,
+      text: res.text,
+      usage: res.usage,
+      usageEstimated: res.usageEstimated,
+      steps: res.steps,
+      toolCalls: res.messages.filter((m) => m.role === "tool").length
+    });
     this.queueRevoice(`[task ${id} completed] ${res.text}`);
   }
   onWorkerFailed(id, err) {
@@ -3877,11 +3912,32 @@ ${recent}` : brief;
     this.notify("task_error", `task ${rec.id} (${rec.label}) failed: ${msg}`);
     this.queueRevoice(`[task ${rec.id} failed] ${msg}`);
   }
-  // --- the three voice tools (closures over this instance) ---
-  delegateTool() {
+  // --- voice tools (closures over this instance) ---
+  /** Live-switch the think tier: `false` disables (removes the Think tool from the voice agent),
+   *  a model id enables (adds the tool if missing). The system-prompt THINK_SLOT text is frozen at
+   *  construction — the tool's own description carries the routing guidance, so a live enable works;
+   *  dispatch()'s think→act fallback covers any straggler calls after a live disable. */
+  setThinkModel(model) {
+    this.options.thinkModel = model;
+    const tools = this.voice.options.tools;
+    const i = tools.findIndex((t) => t.name === "Think");
+    if (model === false && i >= 0) tools.splice(i, 1);
+    else if (model !== false && i < 0) tools.push(this.thinkTool());
+  }
+  /** User/programmatic spawn: the CLI's /act and /think commands. Returns the task id. */
+  async dispatch(brief, tier = "act", label) {
+    if (tier === "think" && this.options.thinkModel === false) tier = "act";
+    const id = `t${++this.seq}`;
+    const lbl = label ?? tier;
+    await this.options.onTaskStart?.(id, lbl);
+    this.spawnWorker(id, lbl, this.buildBrief(brief, tier), tier);
+    this.notify("task_started", `task ${id} (${lbl}) started`, { id, brief, tier });
+    return id;
+  }
+  actTool() {
     return {
-      name: "Delegate",
-      description: 'Escalate real work (reading/editing files, searching, running tasks, deep analysis) to a background worker agent. Returns immediately with a task id; the result arrives later as a "[task <id> completed]" event. Provide a clear, self-contained `brief` (the worker does not hear the live conversation).',
+      name: "Act",
+      description: 'Escalate real work (reading/editing files, searching, running tasks, building) to a standard background worker. Returns immediately with a task id; the result arrives later as a "[task <id> completed]" event. Provide a clear, self-contained `brief` (the worker does not hear the live conversation).',
       parameters: {
         type: "object",
         required: ["brief"],
@@ -3891,12 +3947,26 @@ ${recent}` : brief;
         }
       },
       run: async ({ brief, label }) => {
-        const id = `t${++this.seq}`;
-        const lbl = String(label ?? "task");
-        await this.options.onTaskStart?.(id, lbl);
-        this.spawnWorker(id, lbl, this.buildBrief(String(brief ?? "")));
-        this.notify("task_started", `task ${id} (${lbl}) started`, { id, brief });
-        return `Delegated as task ${id}. Acknowledge briefly; the result will arrive as a [task ${id} completed] event.`;
+        const id = await this.dispatch(String(brief ?? ""), "act", label ? String(label) : void 0);
+        return `Acting on task ${id}. Acknowledge briefly; the result will arrive as a [task ${id} completed] event.`;
+      }
+    };
+  }
+  thinkTool() {
+    return {
+      name: "Think",
+      description: "Escalate to a premium deep-reasoning agent for complex analysis, architecture decisions, hard debugging, or planning. Same async pattern as Act \u2014 returns a task id. Use when the problem needs careful thought before (or instead of) action. Do not use Think for simple tasks \u2014 Act is cheaper and faster.",
+      parameters: {
+        type: "object",
+        required: ["brief"],
+        properties: {
+          brief: { type: "string", description: "the question or problem to reason about deeply" },
+          label: { type: "string", description: "a short (2-4 word) label for the task" }
+        }
+      },
+      run: async ({ brief, label }) => {
+        const id = await this.dispatch(String(brief ?? ""), "think", label ? String(label) : void 0);
+        return `Thinking on task ${id}. Acknowledge briefly; the result will arrive as a [task ${id} completed] event.`;
       }
     };
   }
@@ -3912,7 +3982,7 @@ ${recent}` : brief;
       }
     };
   }
-  /** Sub-100ms read-only lookups the voice may do itself — everything else stays Delegate-only.
+  /** Sub-100ms read-only lookups the voice may do itself — everything else stays Act-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() {
@@ -3920,7 +3990,7 @@ ${recent}` : brief;
     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.`,
+      description: `Instant read-only lookup \u2014 one of: ${kinds.join(", ")}. For trivial facts only; anything needing search, commands, or reasoning goes through Act.`,
       parameters: {
         type: "object",
         required: ["what"],
@@ -3953,7 +4023,7 @@ ${recent}` : brief;
               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;
+\u2026 (truncated \u2014 ${text.length} chars total; Act for the full file)` : text;
             }
             default:
               return `unknown lookup '${what}'`;
@@ -3981,6 +4051,22 @@ ${recent}` : brief;
       }
     };
   }
+  holdTool() {
+    return {
+      name: "Hold",
+      description: 'The user seems mid-thought \u2014 hold the turn (stay listening) instead of answering. Optionally pass a short filler ("mhm", "go on") to speak while waiting. Use when the message sounds incomplete, trailing off, or like they paused to think.',
+      parameters: {
+        type: "object",
+        properties: {
+          filler: { type: "string", description: 'optional short filler to speak ("mhm", "go on", "mm-hm")' }
+        }
+      },
+      run: async ({ filler }) => {
+        if (filler) this.notify("hold_filler", String(filler));
+        return "Holding \u2014 listening for the rest of the user's thought. Do not respond further this turn.";
+      }
+    };
+  }
   cancelTaskTool() {
     return {
       name: "CancelTask",
@@ -4160,6 +4246,14 @@ var VoiceEngineOptions = class {
    *  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;
+  /** Extended merge window (ms) for utterances that look incomplete (trailing conjunction/filler).
+   *  Gives the user time to finish their thought without triggering a model call. */
+  incompleteMergeMs = 1500;
+  /** Filler phrase spoken when holding for an incomplete utterance ('' disables). */
+  holdFiller = "";
+  /** Called when the engine holds an incomplete utterance (host can render a visual cue). */
+  onHold = () => {
+  };
   /** heuristic (non-AEC) energy barge-in tuning */
   bargeRmsMult = 2;
   bargeRmsFloor = 500;
@@ -4173,7 +4267,7 @@ var VoiceEngineOptions = class {
   /** no new partial activity for this long while paused → resume, drop the interjection */
   overlapResumeMs = 700;
 };
-var VoiceEngine = class {
+var VoiceEngine = class _VoiceEngine {
   options;
   state = "idle";
   stt;
@@ -4322,6 +4416,13 @@ var VoiceEngine = class {
     this.lastInterrupted = null;
     return r;
   }
+  /** Speak a short filler phrase without starting a model turn (stays in listening mode after). */
+  speakFiller(text) {
+    if (!text || this.speaking) return;
+    this.beginSpeech();
+    this.speakDelta(text);
+    this.endSpeech();
+  }
   /** barge-in: stop audio NOW, cancel generation, reset for the user's utterance */
   interrupt() {
     if (!this.speaking && !this.drainTimer) return;
@@ -4405,6 +4506,11 @@ var VoiceEngine = class {
     }
     if (!this.echoActive() || (this.usingAec ? this.genuine(text) : this.novelWords(text).length >= 1)) this.options.onPartial(text);
   }
+  static TRAIL_RE = /(?:^|\s)(?:and|but|or|so|to|the|a|an|of|in|for|with|that|if|uh|um|like|about|from|into|on|is|are|was|were|,)$/i;
+  /** The utterance sounds like the user paused mid-thought (trailing conjunction/filler/comma). */
+  looksIncomplete(text) {
+    return _VoiceEngine.TRAIL_RE.test(text.trim());
+  }
   handleUtterance(text) {
     if (this.speaking && (this.ctxOpen || this.pausedAt) && this.overlapCapable) {
       this.stt.reset();
@@ -4421,6 +4527,17 @@ var VoiceEngine = class {
     }
     this.pendingUtt = this.pendingUtt ? `${this.pendingUtt} ${text}` : text;
     if (this.pendingTimer) clearTimeout(this.pendingTimer);
+    if (this.options.incompleteMergeMs && this.looksIncomplete(this.pendingUtt)) {
+      log8.verbose(`hold: incomplete utterance "${this.pendingUtt.slice(-40)}"`);
+      this.options.onHold();
+      if (this.options.holdFiller && !this.speaking) {
+        this.beginSpeech();
+        this.speakDelta(this.options.holdFiller);
+        this.endSpeech();
+      }
+      this.pendingTimer = setTimeout(() => this.flushUtterance(), this.options.incompleteMergeMs);
+      return;
+    }
     if (!this.options.utteranceMergeMs || this.words(this.pendingUtt).length >= 4) return this.flushUtterance();
     this.pendingTimer = setTimeout(() => this.flushUtterance(), this.options.utteranceMergeMs);
   }
@@ -4636,7 +4753,7 @@ var CartesiaTTSOptions = class {
   /** 'apiKey' (server/CLI) → `api_key=` URL param; 'token' (browser, BE-minted) → `access_token=`. */
   authMode = "apiKey";
 };
-var CartesiaTTS = class {
+var CartesiaTTS = class _CartesiaTTS {
   options;
   ws;
   ctxSeq = 0;
@@ -4646,6 +4763,12 @@ var CartesiaTTS = class {
   onDone = () => {
   };
   firstAudioAt = 0;
+  /** Circuit breaker: consecutive error count + down flag. */
+  consecutiveErrors = 0;
+  down = false;
+  probeTimer = null;
+  static CB_THRESHOLD = 3;
+  static CB_PROBE_MS = 3e4;
   constructor(options) {
     this.options = { ...new CartesiaTTSOptions(), ...options };
   }
@@ -4675,10 +4798,34 @@ var CartesiaTTS = class {
       const m = JSON.parse(String(ev.data));
       if (m.context_id && m.context_id !== this.ctxId) return;
       if (m.type === "chunk" && m.data) {
+        this.consecutiveErrors = 0;
+        if (this.down) {
+          this.down = false;
+          log10.info("TTS recovered");
+          this.stopProbe();
+        }
         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)}`);
+      } else if (m.type === "done") {
+        this.consecutiveErrors = 0;
+        if (this.down) {
+          this.down = false;
+          log10.info("TTS recovered");
+          this.stopProbe();
+        }
+        this.onDone();
+      } else if (m.type === "error") {
+        if (/already been cancelled|does not exist/.test(m.message || "")) return;
+        this.consecutiveErrors++;
+        if (!this.down && this.consecutiveErrors >= _CartesiaTTS.CB_THRESHOLD) {
+          this.down = true;
+          log10.warn(`TTS circuit breaker open \u2014 ${this.consecutiveErrors} consecutive errors, switching to text-only`);
+          this.onDone();
+          this.startProbe();
+        } else if (!this.down) {
+          log10.warn(`cartesia: ${JSON.stringify(m)}`);
+        }
+      }
     };
   }
   /** Ensure the WS is open before sending — reconnects if idle-closed. */
@@ -4702,17 +4849,42 @@ var CartesiaTTS = class {
     });
   }
   speak(text, cont) {
+    if (this.down) return;
     if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(this.frame(text, cont));
     else void this.ensureConnected().then(() => this.ws?.readyState === WebSocket.OPEN && this.ws.send(this.frame(text, cont)));
   }
   end() {
+    if (this.down) {
+      this.onDone();
+      return;
+    }
     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 }));
   }
+  startProbe() {
+    if (this.probeTimer) return;
+    this.probeTimer = setInterval(() => {
+      if (!this.down) {
+        this.stopProbe();
+        return;
+      }
+      this.consecutiveErrors = 0;
+      this.newContext();
+      if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(this.frame(".", false));
+    }, _CartesiaTTS.CB_PROBE_MS);
+    this.probeTimer.unref?.();
+  }
+  stopProbe() {
+    if (this.probeTimer) {
+      clearInterval(this.probeTimer);
+      this.probeTimer = null;
+    }
+  }
   close() {
     this.closed = true;
+    this.stopProbe();
     if (this.ws) this.ws.onclose = null;
     this.ws?.close();
   }