agent.libx.js 0.92.8 → 0.93.1

package/dist/index.js

@@ -1970,34 +1970,61 @@ async function loadCommands(fs, dir, opts = {}) {
 // src/memory.ts
 init_tools_structured();
 var MAX_INDEX = 25;
+var MAX_INDEX_LINES = 200;
+var MAX_INDEX_BYTES = 25e3;
+var MEMORY_PROMPT = '## Memory guidelines\n**When to Remember:** user corrections ("no, do X instead"), preferences ("I prefer Y"), project constraints, recurring gotchas, role/context ("I\'m a data scientist"), workflow patterns confirmed by the user. Capture the WHY, not just the what.\n**When NOT to Remember:** task-specific scratch, transient state, things derivable from code/git, conversation filler, anything already in instruction files. If removing the memory wouldn\'t change future behavior, don\'t save it.\n**Types** (pass to Remember \u2014 this determines where the memory is stored):\n- `user` \u2014 role, preferences, knowledge level, collaboration style (GLOBAL \u2014 follows you across projects)\n- `feedback` \u2014 corrections, what to avoid/repeat, with WHY (GLOBAL)\n- `project` \u2014 ongoing work, goals, constraints, deadlines (LOCAL to this project; convert relative dates to absolute)\n- `reference` \u2014 pointers to external resources, URLs, vendor docs (LOCAL to this project)\n**Before acting on a recalled memory:** verify it\'s still true \u2014 a memory naming a file/function/flag is a claim from when it was written. Grep/read to confirm before recommending. Stale memory \u2192 update via Remember (same slug overwrites).\n**Dedup:** before writing, check if a similar memory exists (Recall or MemorySearch). Update the existing one rather than creating duplicates.\nCall `Recall` with a slug (or multiple slugs/a pattern) to load full bodies when relevant.\nCall `MemorySearch` with a query to find memories by content when you don\'t know the slug.\nCall `Remember` to persist a durable fact for future sessions.';
+var VOICE_MEMORY_PROMPT = `You have Remember and Recall tools \u2014 use them directly, no delegation needed.
+IMPLICIT CAPTURE: when the user shares their name, role, a preference, a correction ("no, do X instead"), or a project constraint \u2014 call Remember immediately without announcing it. Natural memory, not a ceremony.
+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.`;
 async function loadMemory(fs, dir, opts = {}) {
-  const indexPath = `${dir}/MEMORY.md`;
-  const tools = [recallTool(fs, dir), rememberTool(fs, dir), memorySearchTool(fs, dir)];
-  const md = await fs.exists(indexPath) ? (await fs.readFile(indexPath)).trim() : "";
-  if (!md) return { index: "", tools };
-  const lines = md.split("\n");
-  const pointers = lines.filter((l) => /^\s*-\s*\[.+\]\(.+\.md\)/.test(l));
-  const header = lines.filter((l) => !/^\s*-\s*\[.+\]\(.+\.md\)/.test(l)).join("\n").trim();
-  const { kept, rest } = topByRelevance(pointers, opts.relevanceHint ?? "", (l) => l, opts.max ?? MAX_INDEX);
+  const dirs = (Array.isArray(dir) ? dir : [dir]).filter(Boolean);
+  const writeDir = dirs[0];
+  const tools = [recallTool(fs, dirs), rememberTool(fs, writeDir, opts), memorySearchTool(fs, dirs)];
+  const allPointers = [];
+  const seenSlugs = /* @__PURE__ */ new Set();
+  let header = "";
+  let hasContent = false;
+  for (const d of dirs) {
+    const indexPath = `${d}/MEMORY.md`;
+    const md = await fs.exists(indexPath) ? (await fs.readFile(indexPath)).trim() : "";
+    if (!md) continue;
+    hasContent = true;
+    const lines = md.split("\n");
+    if (!header) header = lines.filter((l) => !/^\s*-\s*\[.+\]\(.+\.md\)/.test(l)).join("\n").trim();
+    for (const l of lines.filter((l2) => /^\s*-\s*\[.+\]\(.+\.md\)/.test(l2))) {
+      const slug = l.match(/\]\(([^)]+)\.md\)/)?.[1];
+      if (slug && !seenSlugs.has(slug)) {
+        seenSlugs.add(slug);
+        allPointers.push(l);
+      }
+    }
+  }
+  if (!hasContent) return { index: MEMORY_PROMPT, tools };
+  const { kept, rest } = topByRelevance(allPointers, opts.relevanceHint ?? "", (l) => l, opts.max ?? MAX_INDEX);
   const restSlugs = rest.map((l) => l.match(/\]\(([^)]+)\.md\)/)?.[1] ?? l.match(/\[([^\]]+)\]/)?.[1] ?? "").filter(Boolean);
-  const index = "## Memory (persistent context \u2014 recalled across sessions)\n" + (header ? header + "\n" : "") + kept.join("\n") + (restSlugs.length ? `
-- (${restSlugs.length} more learnings, slugs only \u2014 call \`Recall\` if relevant): ${restSlugs.join(", ")}` : "") + `
-
-These are pointers only. Call \`Recall\` with a slug (or multiple slugs/a pattern) to load full bodies when relevant.
-Call \`MemorySearch\` with a query to find memories by content when you don't know the slug.
-Call \`Remember\` to persist a durable fact for future sessions.`;
+  const index = MEMORY_PROMPT + "\n\n## Memory index (persistent context \u2014 recalled across sessions)\n" + (header ? header + "\n" : "") + kept.join("\n") + (restSlugs.length ? `
+- (${restSlugs.length} more learnings, slugs only \u2014 call \`Recall\` if relevant): ${restSlugs.join(", ")}` : "");
   return { index, tools };
 }
 function slugify(s, fallback = "note") {
   const base = String(s ?? "").trim().toLowerCase().replace(/\.md$/i, "").replace(/[^\w\s-]/g, "").replace(/[\s_]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, 48);
   return base || fallback;
 }
-async function writeFact(fs, dir, slug, body) {
+async function writeFact(fs, dir, slug, body, opts) {
   await mkdirp(fs, dir);
-  await fs.writeFile(`${dir}/${slug}.md`, body.endsWith("\n") ? body : body + "\n");
+  const content = opts?.type ? `---
+type: ${opts.type}
+---
+
+${body}` : body;
+  await fs.writeFile(`${dir}/${slug}.md`, content.endsWith("\n") ? content : content + "\n");
   const indexPath = `${dir}/MEMORY.md`;
   const idx = await fs.exists(indexPath) ? await fs.readFile(indexPath) : "# Memory Index\n";
-  const line = `- [${slug}](${slug}.md) \u2014 ${body.split("\n")[0].slice(0, 80)}`;
+  const summary = opts?.description || body.split("\n")[0].slice(0, 80);
+  const line = `- [${slug}](${slug}.md) \u2014 ${summary}`;
   const lines = idx.split("\n");
   const at = lines.findIndex((l) => l.includes(`(${slug}.md)`));
   if (at >= 0) {
@@ -2010,6 +2037,24 @@ async function writeFact(fs, dir, slug, body) {
 ${line}
 `);
   }
+  await truncateIndex(fs, indexPath);
+}
+async function truncateIndex(fs, path) {
+  const raw = await fs.readFile(path);
+  if (raw.length <= MAX_INDEX_BYTES) {
+    const count = raw.split("\n").filter((l) => /^\s*-\s*\[.+\]\(.+\.md\)/.test(l)).length;
+    if (count <= MAX_INDEX_LINES) return;
+  }
+  const lines = raw.split("\n");
+  const pointerIdxs = [];
+  for (let i = 0; i < lines.length; i++) if (/^\s*-\s*\[.+\]\(.+\.md\)/.test(lines[i])) pointerIdxs.push(i);
+  const drop = /* @__PURE__ */ new Set();
+  for (const pi of pointerIdxs) {
+    const candidate = lines.filter((_, i) => !drop.has(i)).join("\n");
+    if (candidate.length <= MAX_INDEX_BYTES && pointerIdxs.length - drop.size <= MAX_INDEX_LINES) break;
+    drop.add(pi);
+  }
+  if (drop.size) await fs.writeFile(path, lines.filter((_, i) => !drop.has(i)).join("\n"));
 }
 function cleanSlug(raw) {
   let s = String(raw ?? "").trim().replace(/\.md$/i, "").replace(/\\/g, "/").replace(/\/+/g, "/").replace(/^\/|\/$/g, "");
@@ -2035,12 +2080,30 @@ async function listSlugs(fs, dir, prefix = "") {
 async function loadFact(fs, dir, slug) {
   const path = `${dir}/${slug}.md`;
   try {
-    return await fs.readFile(path);
+    const raw = await fs.readFile(path);
+    const { body } = splitFrontmatter(raw);
+    return body || raw;
   } catch {
     return null;
   }
 }
-function recallTool(fs, dir) {
+async function loadFactMulti(fs, dirs, slug) {
+  for (const d of dirs) {
+    const r = await loadFact(fs, d, slug);
+    if (r != null) return r;
+  }
+  return null;
+}
+async function listSlugsMulti(fs, dirs) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const d of dirs) for (const s of await listSlugs(fs, d)) if (!seen.has(s)) {
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+function recallTool(fs, dirs) {
   return {
     name: "Recall",
     description: 'Load memory facts by slug. Pass `slug` for one, `slugs` for several, or `pattern` (glob like "auth*") to match. Returns full bodies, separated by `--- slug ---` headers.',
@@ -2059,12 +2122,12 @@ function recallTool(fs, dir) {
       else if (pattern) {
         const escaped = String(pattern).replace(/[.+^${}()|[\]\\]/g, "\\$&");
         const re = new RegExp("^" + escaped.replace(/\*/g, ".*").replace(/\?/g, ".") + "$", "i");
-        targets = (await listSlugs(ctx.fs, dir)).filter((s) => re.test(s));
+        targets = (await listSlugsMulti(fs, dirs)).filter((s) => re.test(s));
       }
       if (!targets.length) return `Error: no slugs resolved. Pass slug, slugs, or pattern.`;
       const parts = [];
       for (const s of targets.slice(0, 20)) {
-        const body = await loadFact(ctx.fs, dir, s);
+        const body = await loadFactMulti(fs, dirs, s);
         if (body != null) parts.push(targets.length > 1 ? `--- ${s} ---
 ${body}` : body);
         else parts.push(targets.length > 1 ? `--- ${s} ---
@@ -2075,7 +2138,7 @@ ${body}` : body);
     }
   };
 }
-function memorySearchTool(fs, dir) {
+function memorySearchTool(fs, dirs) {
   return {
     name: "MemorySearch",
     description: "Search memory facts by content \u2014 find relevant memories when you don't know the exact slug. Returns up to 10 matching slug + snippet pairs, ranked by relevance. Use `regex: true` for regex patterns.",
@@ -2090,7 +2153,7 @@ function memorySearchTool(fs, dir) {
     async run({ query, regex }, ctx) {
       const q = String(query ?? "").trim();
       if (!q) return "Error: empty query.";
-      const slugs = await listSlugs(ctx.fs, dir);
+      const slugs = await listSlugsMulti(fs, dirs);
       if (!slugs.length) return "(no memory facts found)";
       let matcher;
       if (regex) {
@@ -2106,7 +2169,7 @@ function memorySearchTool(fs, dir) {
       }
       const loaded = [];
       for (const slug of slugs) {
-        const body = await loadFact(ctx.fs, dir, slug);
+        const body = await loadFactMulti(fs, dirs, slug);
         if (body) loaded.push({ slug, body });
       }
       const idf = idfWeights(loaded.map((l) => l.body));
@@ -2125,7 +2188,9 @@ function memorySearchTool(fs, dir) {
     }
   };
 }
-function rememberTool(fs, dir) {
+function rememberTool(fs, dir, memOpts = {}) {
+  const maxWrites = memOpts.maxWritesPerSession ?? 25;
+  let writes = 0;
   return {
     name: "Remember",
     description: "Persist a durable fact for future sessions (a fix you found, a gotcha, a project constraint). Adds a pointer to the Memory index and stores the body. Use sparingly \u2014 only genuinely reusable knowledge, not task-specific scratch.",
@@ -2134,14 +2199,20 @@ function rememberTool(fs, dir) {
       required: ["fact"],
       properties: {
         fact: { type: "string", description: "the durable fact to remember (one or more lines)" },
-        slug: { type: "string", description: "optional kebab-case id; derived from the fact if omitted" }
+        slug: { type: "string", description: "optional kebab-case id; derived from the fact if omitted" },
+        type: { type: "string", enum: ["user", "feedback", "project", "reference"], description: "memory category (user/feedback/project/reference)" },
+        description: { type: "string", description: "one-line summary for the memory index (\u226480 chars)" }
       }
     },
-    async run({ fact, slug }, ctx) {
+    async run({ fact, slug, type, description }, ctx) {
       const body = String(fact ?? "").trim();
       if (!body) return `Error: nothing to remember (empty fact).`;
+      if (++writes > maxWrites) return `Rate limit: too many memories this session (${maxWrites}). Only persist genuinely durable facts.`;
       const name = slugify(slug || body.split("\n")[0]);
-      await writeFact(ctx.fs, dir, name, body);
+      const isGlobal = (type === "user" || type === "feedback") && memOpts.userDir;
+      const targetDir = isGlobal ? memOpts.userDir : dir;
+      await writeFact(fs, targetDir, name, body, { type, description });
+      memOpts.onMemorySaved?.(name, type);
       return `Remembered '${name}' (recallable in future sessions).`;
     }
   };
@@ -2575,8 +2646,11 @@ var AgentOptions = class {
   skillsDir;
   /** VFS dir(s) of slash-command templates (`<dir>/<name>.md`). If set: inject a catalog + add the `SlashCommand` tool. Multiple dirs are merged (first wins). */
   commandsDir;
-  /** VFS dir of memory (`<dir>/MEMORY.md`). If set: inject the index at run start (persistence = backend). */
+  /** VFS dir(s) of memory (`<dir>/MEMORY.md`). If set: inject the index at run start (persistence = backend).
+   *  Multiple dirs are merged (reads search all; writes go to first). */
   memoryDir;
+  /** User-scope memory dir for global facts (type=user/feedback). Remember routes by type when set. */
+  memoryUserDir;
   /** Filenames to discover as project instructions (e.g. `AGENT.md`, `AGENTS.md`, `CLAUDE.md`).
    *  Walks the VFS tree and merges all found files (general → specific, like Claude Code).
    *  `true` (default) = auto-discover standard names. `string[]` = custom names. `false` = skip. */
@@ -2613,6 +2687,8 @@ var AgentOptions = class {
   autoTest;
   /** Provider-specific options forwarded to ai.chat() (e.g. cursor mcpServers, cwd). */
   providerOptions;
+  /** Tool selection mode: 'auto' = model decides (needed for Groq); undefined = provider default. */
+  toolChoice;
   /** Extended-thinking / reasoning effort, normalized across providers (anthropic, openai).
    *  `'off'`/undefined = none; `'low'|'medium'|'high'` or a raw token budget. Mapped to the
    *  provider-specific request shape via {@link reasoningToChatFragment}; explicit `providerOptions` wins. */
@@ -2699,7 +2775,7 @@ var Agent = class _Agent {
       if (ins) systemPrompt += "\n\n" + ins;
     }
     if (o.memoryDir) {
-      const { index, tools: memTools } = await loadMemory(fs, o.memoryDir, { relevanceHint: taskHint });
+      const { index, tools: memTools } = await loadMemory(fs, o.memoryDir, { relevanceHint: taskHint, userDir: o.memoryUserDir });
       if (index) systemPrompt += "\n\n" + index;
       tools = [...tools, ...memTools];
     }
@@ -2826,10 +2902,10 @@ var Agent = class _Agent {
       };
       try {
         if (useStream) {
-          const r = await o.ai.chat({ model: o.model, messages: sent, tools: wireTools, stream: true, signal: o.signal, ...reasonOpts });
+          const r = await o.ai.chat({ model: o.model, messages: sent, tools: wireTools, stream: true, signal: o.signal, ...o.toolChoice ? { toolChoice: o.toolChoice } : {}, ...reasonOpts });
           res = await this.consumeStream(r);
         } else {
-          const r = await o.ai.chat({ model: o.model, messages: sent, tools: wireTools, stream: false, signal: o.signal, ...reasonOpts });
+          const r = await o.ai.chat({ model: o.model, messages: sent, tools: wireTools, stream: false, signal: o.signal, ...o.toolChoice ? { toolChoice: o.toolChoice } : {}, ...reasonOpts });
           res = r;
         }
       } catch (err) {
@@ -3554,8 +3630,13 @@ var DuplexAgentOptions = class {
   /** 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;
+  /** Memory directory/directories on the WORKER fs. If set, the voice agent gets Remember + Recall
+   *  tools directly (no delegation needed) and implicit capture guidance. */
+  memoryDir;
+  /** 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`.\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_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 DuplexAgent = class {
   options;
@@ -3567,34 +3648,45 @@ var DuplexAgent = class {
   flushQueued = false;
   /** Parked worker questions awaiting a (voice-relayed) user answer, keyed by ask id. */
   pendingAsks = /* @__PURE__ */ new Map();
+  /** Lazily resolved memory tools (async loadMemory runs in initMemory). */
+  memoryReady;
   constructor(options) {
     this.options = { ...new DuplexAgentOptions(), ...options };
     const o = this.options;
+    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 : "") + `
+Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}.`;
     this.voice = new Agent({
       ai: o.ai,
       fs: new MemFilesystem2(),
-      // scratch — NOT Agent's jailed-disk default (voice has no fs tools; edge-safe)
       model: o.voiceModel,
       stream: true,
       host: o.host,
-      // 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()}.`,
+      systemPrompt: prompt,
       instructionFiles: false,
       maxSteps: 8,
-      // a voice turn should never loop
       timeoutMs: 3e4,
       ...o.voiceOptions,
-      // 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(), this.quickLookTool(), this.answerTaskTool()]
     });
   }
+  /** Resolve memory tools + inject index into voice system prompt (once). */
+  async initMemory() {
+    if (!this.memoryReady) return;
+    const mem = await this.memoryReady;
+    this.memoryReady = void 0;
+    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. */
   send(content) {
-    return this.enqueue(() => this.voice.send(content));
+    return this.enqueue(async () => {
+      await this.initMemory();
+      return this.voice.send(content);
+    });
   }
   /** Resolve when all queued voice turns AND all in-flight worker tasks have settled (tests, graceful shutdown). */
   async idle() {
@@ -3689,6 +3781,7 @@ ${recent}` : brief;
     let steps = 0;
     let inflight = null;
     const due = () => {
+      if (this.pendingAsks.size) return void 0;
       const rec = this.tasks.get(id);
       return rec && rec.status === "running" && Date.now() - lastAt >= this.options.progressIntervalMs ? rec : void 0;
     };
@@ -4061,18 +4154,15 @@ var VoiceEngineOptions = class {
   /** heuristic (non-AEC) energy barge-in tuning */
   bargeRmsMult = 2;
   bargeRmsFloor = 500;
-  /** Overlap turn-taking (AEC tier, needs player.pause/resume) — human phone-call model:
-   *  onset → PAUSE (exact-sample hold, nothing lost); sustained overlap → cede (interrupt; the LLM
-   *  re-enters). Brief overlaps that die out (backchannels — "mm-hm", decided by DURATION, not
-   *  vocabulary) resume from the precise sample and are dropped. false disables. */
+  /** Overlap turn-taking (AEC tier, needs player.pause/resume) — human phone-call model, driven by
+   *  the STT ITSELF (a trained speech classifier) instead of energy thresholds (energy could not
+   *  separate residue bursts from speech in every room — hiccup whack-a-mole): partial text while
+   *  speaking → PAUSE (exact-sample hold); partial grows into dominant-novel ≥2 words → cede
+   *  (interrupt; the LLM re-enters); partial stalls/endpoints without ceding (backchannel by
+   *  DURATION, not vocabulary) → resume + drop. false disables. */
   overlapPause = true;
-  /** sustained overlap ≥ this → cede the turn */
-  overlapSustainMs = 350;
-  /** quiet for this long while paused → resume, drop the interjection */
+  /** no new partial activity for this long while paused → resume, drop the interjection */
   overlapResumeMs = 700;
-  /** energy floor for "overlap candidate" — must sit ABOVE typical room ambient (~110 rms measured;
-   *  ungated ambient re-arming the resume timer forever was a live wedge). User speech ≫ 300. */
-  overlapRms = 300;
 };
 var VoiceEngine = class {
   options;
@@ -4105,10 +4195,8 @@ var VoiceEngine = class {
   lastInterrupted = null;
   // overlap (pause) tier state — AEC + pause-capable sinks only
   pausedAt = 0;
-  overlapLoud = 0;
-  // loud chunks since pause (sustain must be real sound, not two clicks)
-  overlapLastLoudAt = 0;
-  // continuity guard: a gap re-arms the onset (sparse noise ≠ sustained speech)
+  lastOverlapPartial = "";
+  // change-detection: only NEW partial text counts as activity
   resumeTimer = null;
   constructor(options) {
     this.options = { ...new VoiceEngineOptions(), ...options };
@@ -4272,7 +4360,24 @@ var VoiceEngine = class {
   }
   handlePartial(text) {
     if (this.speaking) {
-      const barge = this.overlapCapable ? false : this.usingAec ? this.genuine(text) : this.novelWords(text).length >= (this.suspectUntil ? 1 : 2);
+      if (this.overlapCapable) {
+        const txt = text.trim();
+        if (!txt || txt === this.lastOverlapPartial) return;
+        this.lastOverlapPartial = txt;
+        if (!this.pausedAt) {
+          this.pausedAt = now();
+          this.player.pause();
+        }
+        if (this.genuine(txt) && this.words(txt).length >= 2) {
+          const phase = this.ctxOpen ? "speaking" : "drain";
+          this.interrupt();
+          this.options.onBargeIn(phase);
+          return;
+        }
+        this.armResume();
+        return;
+      }
+      const barge = this.usingAec ? this.genuine(text) : this.novelWords(text).length >= (this.suspectUntil ? 1 : 2);
       if (barge) {
         const phase = this.ctxOpen ? "speaking" : "drain";
         this.interrupt();
@@ -4281,15 +4386,13 @@ var VoiceEngine = class {
       return;
     }
     if (this.pendingUtt && text.trim()) {
-      if (this.pendingTimer) {
-        clearTimeout(this.pendingTimer);
-        this.pendingTimer = null;
-      }
+      if (this.pendingTimer) clearTimeout(this.pendingTimer);
+      this.pendingTimer = setTimeout(() => this.flushUtterance(), Math.max(800, this.options.utteranceMergeMs));
     }
     if (!this.echoActive() || (this.usingAec ? this.genuine(text) : this.novelWords(text).length >= 1)) this.options.onPartial(text);
   }
   handleUtterance(text) {
-    if (this.speaking && this.ctxOpen && this.overlapCapable) {
+    if (this.speaking && (this.ctxOpen || this.pausedAt) && this.overlapCapable) {
       this.stt.reset();
       return;
     }
@@ -4304,7 +4407,7 @@ var VoiceEngine = class {
     }
     this.pendingUtt = this.pendingUtt ? `${this.pendingUtt} ${text}` : text;
     if (this.pendingTimer) clearTimeout(this.pendingTimer);
-    if (!this.options.utteranceMergeMs) return this.flushUtterance();
+    if (!this.options.utteranceMergeMs || this.words(this.pendingUtt).length >= 4) return this.flushUtterance();
     this.pendingTimer = setTimeout(() => this.flushUtterance(), this.options.utteranceMergeMs);
   }
   flushUtterance() {
@@ -4319,45 +4422,12 @@ var VoiceEngine = class {
   get overlapCapable() {
     return this.usingAec && this.options.overlapPause && !!this.player.pause && !!this.player.resume;
   }
-  /** Overlap turn-taking (AEC tier): onset → pause (exact-sample hold); sustained → cede; died out
-   *  → resume. No vocabulary anywhere — duration and persistence decide (backchannels are short
-   *  and stop). Nothing is lost across a pause, so a false positive costs only a brief hold. */
-  handleOverlap(rms) {
-    const o = this.options;
-    if (!this.speaking || !this.overlapCapable) return;
-    if (rms < o.overlapRms) return;
-    const t = now();
-    if (!this.pausedAt) {
-      this.overlapLoud = t - this.overlapLastLoudAt <= 60 ? this.overlapLoud + 1 : 1;
-      this.overlapLastLoudAt = t;
-      if (this.overlapLoud < 3) return;
-      this.pausedAt = t;
-      this.player.pause();
-      this.armResume();
-      return;
-    }
-    if (t - this.overlapLastLoudAt > 300) {
-      this.pausedAt = t;
-      this.overlapLoud = 1;
-      this.overlapLastLoudAt = t;
-      this.armResume();
-      return;
-    }
-    this.overlapLastLoudAt = t;
-    this.overlapLoud++;
-    if (t - this.pausedAt >= o.overlapSustainMs && this.overlapLoud >= 4) {
-      const phase = this.ctxOpen ? "speaking" : "drain";
-      this.interrupt();
-      this.options.onBargeIn(phase);
-      return;
-    }
-    this.armResume();
-  }
   armResume() {
     if (this.resumeTimer) clearTimeout(this.resumeTimer);
     this.resumeTimer = setTimeout(() => {
       this.resumeTimer = null;
       if (!this.pausedAt) return;
+      this.stt.reset();
       this.resetOverlap(true);
     }, this.options.overlapResumeMs);
   }
@@ -4368,11 +4438,25 @@ var VoiceEngine = class {
     }
     if (this.pausedAt && resume) this.player.resume?.();
     this.pausedAt = 0;
-    this.overlapLoud = 0;
+    this.lastOverlapPartial = "";
+    this.gatePassTimes = [];
   }
   /** energy two-stage barge-in (heuristic tier only): spike over echo baseline → pause + confirm via STT */
+  gatePassTimes = [];
+  // recent gate-PASSING chunks (helper zeroes residue — nonzero = vetted)
   handleLevel(rms) {
-    if (this.usingAec) return this.handleOverlap(rms);
+    if (this.usingAec) {
+      if (!this.speaking || !this.overlapCapable || this.pausedAt || rms < 50) return;
+      const t = now();
+      this.gatePassTimes = this.gatePassTimes.filter((x) => t - x < 350);
+      this.gatePassTimes.push(t);
+      if (this.gatePassTimes.length < 2) return;
+      this.gatePassTimes = [];
+      this.pausedAt = t;
+      this.player.pause();
+      this.armResume();
+      return;
+    }
     if (!this.speaking) {
       this.baseline = 0;
       this.hot = 0;
@@ -4412,6 +4496,9 @@ var SonioxSTTOptions = class {
   source;
   model = "stt-rt-preview";
   languageHints = ["en"];
+  /** Client-side endpoint: finalized text + no new tokens for this long = utterance (don't wait for
+   *  Soniox's semantic <end>, which adds 0.5-1.5s — the difference between ping-pong and lag). */
+  silenceEndpointMs = 500;
 };
 var SonioxSTT = class {
   options;
@@ -4427,6 +4514,9 @@ var SonioxSTT = class {
   };
   finalText = "";
   partialText = "";
+  lastChangeAt = 0;
+  lastCombined = "";
+  endpointTimer = null;
   constructor(options) {
     this.options = { ...new SonioxSTTOptions(), ...options };
   }
@@ -4463,6 +4553,13 @@ var SonioxSTT = class {
     await this.connectWs();
     if (this.sourceStarted) return;
     this.sourceStarted = true;
+    this.endpointTimer = setInterval(() => {
+      const combined = (this.finalText + this.partialText).trim();
+      if (!combined || now2() - this.lastChangeAt < this.options.silenceEndpointMs) return;
+      this.reset();
+      this.onUtterance(combined, now2());
+    }, 120);
+    this.endpointTimer.unref?.();
     await this.options.source.start((chunk) => {
       let sum = 0;
       const view = new DataView(chunk.buffer, chunk.byteOffset, chunk.byteLength);
@@ -4482,7 +4579,12 @@ var SonioxSTT = class {
       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);
+    const combined = this.finalText + this.partialText;
+    if (combined !== this.lastCombined) {
+      this.lastCombined = combined;
+      this.lastChangeAt = now2();
+    }
+    this.onPartial(combined);
     if (endpoint && this.finalText.trim()) {
       const utterance = this.finalText.trim();
       this.reset();
@@ -4492,9 +4594,11 @@ var SonioxSTT = class {
   reset() {
     this.finalText = "";
     this.partialText = "";
+    this.lastCombined = "";
   }
   stop() {
     this.stopped = true;
+    if (this.endpointTimer) clearInterval(this.endpointTimer);
     this.options.source?.stop();
     if (this.ws) this.ws.onclose = null;
     this.ws?.close();
@@ -4600,6 +4704,7 @@ export {
   JailOptions,
   JailedFilesystem,
   LessonOptionsDefaults,
+  MEMORY_PROMPT,
   MemFilesystem3 as MemFilesystem,
   MountFilesystem,
   NodeDiskFilesystem,
@@ -4614,6 +4719,7 @@ export {
   SonioxSTT,
   SonioxSTTOptions,
   TTS_SAMPLE_RATE,
+  VOICE_MEMORY_PROMPT,
   VOICE_SYSTEM_PROMPT,
   VoiceEngine,
   VoiceEngineOptions,