@qxbyte/muse 0.1.1 → 0.1.3

package/dist/index.js

@@ -109,17 +109,45 @@ var OpenAICompatibleClient = class {
     const { messages, tools, systemPrompt, temperature, maxTokens, abortSignal } = opts;
     const aiMessages = convertMessages(messages, systemPrompt);
     const aiTools = tools ? convertTools(tools) : void 0;
+    let attempt = 0;
+    const maxAttempts = 3;
+    let result;
+    while (true) {
+      try {
+        result = streamText({
+          model: this.modelProvider,
+          messages: aiMessages,
+          tools: aiTools,
+          temperature,
+          maxTokens,
+          abortSignal
+        });
+        break;
+      } catch (err) {
+        if (abortSignal?.aborted) {
+          yield { type: "error", error: err instanceof Error ? err : new Error(String(err)) };
+          return;
+        }
+        if (!isRetryable(err) || attempt >= maxAttempts - 1) {
+          yield { type: "error", error: err instanceof Error ? err : new Error(String(err)) };
+          return;
+        }
+        const delay = 1e3 * Math.pow(2, attempt);
+        log.warn(`LLM connect failed (attempt ${attempt + 1}/${maxAttempts}); retrying in ${delay}ms`, {
+          msg: err instanceof Error ? err.message : String(err)
+        });
+        await sleep(delay, abortSignal);
+        attempt += 1;
+      }
+    }
+    if (!result) {
+      yield { type: "error", error: new Error("Internal: stream result is undefined after retry loop.") };
+      return;
+    }
+    const stream = result.fullStream;
     try {
-      const result = streamText({
-        model: this.modelProvider,
-        messages: aiMessages,
-        tools: aiTools,
-        temperature,
-        maxTokens,
-        abortSignal
-      });
       const seenToolCalls = /* @__PURE__ */ new Set();
-      for await (const part of result.fullStream) {
+      for await (const part of stream) {
         switch (part.type) {
           case "text-delta":
             yield { type: "text", delta: part.textDelta };
@@ -225,6 +253,33 @@ function convertTools(tools) {
   }
   return result;
 }
+function isRetryable(err) {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message.toLowerCase();
+  const code = err.code ?? "";
+  if (code === "ECONNRESET" || code === "ETIMEDOUT" || code === "ENOTFOUND" || code === "ECONNREFUSED" || code === "EAI_AGAIN") {
+    return true;
+  }
+  if (msg.includes("fetch failed") || msg.includes("network") || msg.includes("socket hang up") || msg.includes("under maintenance") || msg.includes("rate limit") || msg.includes("429") || msg.includes("502") || msg.includes("503") || msg.includes("504")) {
+    return true;
+  }
+  return false;
+}
+async function sleep(ms, abortSignal) {
+  await new Promise((resolve6, reject) => {
+    if (abortSignal?.aborted) return reject(new Error("aborted"));
+    const t = setTimeout(() => {
+      abortSignal?.removeEventListener("abort", onAbort);
+      resolve6();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      abortSignal?.removeEventListener("abort", onAbort);
+      reject(new Error("aborted"));
+    };
+    abortSignal?.addEventListener("abort", onAbort);
+  });
+}
 function mapFinishReason(reason) {
   switch (reason) {
     case "stop":
@@ -480,8 +535,52 @@ function defineTool(def) {
 
 // src/tools/builtin/read.ts
 import { readFile, stat } from "fs/promises";
-import { resolve, isAbsolute } from "path";
+import { resolve as resolve2, isAbsolute } from "path";
 import { z } from "zod";
+
+// src/tools/_sensitive.ts
+import { homedir as homedir2 } from "os";
+import { basename, resolve } from "path";
+var HOME = homedir2();
+var SENSITIVE_DIRS = [
+  resolve(HOME, ".ssh"),
+  resolve(HOME, ".aws"),
+  resolve(HOME, ".gnupg"),
+  resolve(HOME, ".config", "gh")
+];
+var SENSITIVE_FILES = [
+  resolve(HOME, ".kube", "config"),
+  resolve(HOME, ".netrc"),
+  resolve(HOME, ".pypirc")
+];
+var SENSITIVE_BASENAMES = /* @__PURE__ */ new Set([
+  "id_rsa",
+  "id_ed25519",
+  "id_ecdsa",
+  "id_dsa"
+]);
+var ENV_PATTERN = /(?:^|\/)\.env(\..+)?$/;
+function checkSensitivePath(path) {
+  const abs = resolve(path);
+  for (const dir of SENSITIVE_DIRS) {
+    if (abs === dir || abs.startsWith(dir + "/")) {
+      return { blocked: true, reason: `sensitive directory ${dir.replace(HOME, "~")}` };
+    }
+  }
+  for (const f of SENSITIVE_FILES) {
+    if (abs === f) return { blocked: true, reason: `sensitive file ${f.replace(HOME, "~")}` };
+  }
+  const base = basename(abs);
+  if (SENSITIVE_BASENAMES.has(base)) {
+    return { blocked: true, reason: `private key filename ${base}` };
+  }
+  if (ENV_PATTERN.test(abs)) {
+    return { blocked: true, reason: `.env file (may contain secrets)` };
+  }
+  return { blocked: false };
+}
+
+// src/tools/builtin/read.ts
 var ReadArgs = z.object({
   file_path: z.string().describe("Absolute or cwd-relative path to the file."),
   offset: z.number().int().min(0).optional().describe("Line offset (0-based)."),
@@ -496,7 +595,11 @@ var ReadTool = defineTool({
   permission: "read",
   summarize: (args) => `Read(${args.file_path}${args.offset != null ? `, offset=${args.offset}` : ""}${args.limit != null ? `, limit=${args.limit}` : ""})`,
   async execute(args, ctx) {
-    const path = isAbsolute(args.file_path) ? args.file_path : resolve(ctx.cwd, args.file_path);
+    const path = isAbsolute(args.file_path) ? args.file_path : resolve2(ctx.cwd, args.file_path);
+    const sensitive = checkSensitivePath(path);
+    if (sensitive.blocked) {
+      return { content: `Refused: ${path} matches sensitive path policy (${sensitive.reason}).`, isError: true };
+    }
     let info;
     try {
       info = await stat(path);
@@ -529,9 +632,26 @@ var ReadTool = defineTool({
 });
 
 // src/tools/builtin/write.ts
-import { writeFile, mkdir, stat as stat2 } from "fs/promises";
-import { resolve as resolve2, isAbsolute as isAbsolute2, dirname as dirname2 } from "path";
+import { readFile as readFile2, writeFile, mkdir, stat as stat2 } from "fs/promises";
+import { resolve as resolve3, isAbsolute as isAbsolute2, dirname as dirname2 } from "path";
 import { z as z2 } from "zod";
+
+// src/tools/_diff.ts
+import { createPatch } from "diff";
+var MAX_DIFF_LINES = 200;
+function makeUnifiedDiff(filePath, oldContent, newContent) {
+  if (oldContent === newContent) return "";
+  const patch = createPatch(filePath, oldContent, newContent, "before", "after", { context: 3 });
+  return truncate(patch);
+}
+function truncate(diff) {
+  const lines = diff.split("\n");
+  if (lines.length <= MAX_DIFF_LINES) return diff;
+  return lines.slice(0, MAX_DIFF_LINES).join("\n") + `
+... [${lines.length - MAX_DIFF_LINES} more diff lines truncated]`;
+}
+
+// src/tools/builtin/write.ts
 var WriteArgs = z2.object({
   file_path: z2.string().describe("Absolute or cwd-relative path to the file."),
   content: z2.string().describe("Full content of the file.")
@@ -543,25 +663,33 @@ var WriteTool = defineTool({
   permission: "write",
   summarize: (args) => `Write(${args.file_path}, ${args.content.length} chars)`,
   async execute(args, ctx) {
-    const path = isAbsolute2(args.file_path) ? args.file_path : resolve2(ctx.cwd, args.file_path);
+    const path = isAbsolute2(args.file_path) ? args.file_path : resolve3(ctx.cwd, args.file_path);
+    const sensitive = checkSensitivePath(path);
+    if (sensitive.blocked) {
+      return { content: `Refused: ${path} matches sensitive path policy (${sensitive.reason}).`, isError: true };
+    }
     let existed = false;
+    let oldContent = "";
     try {
       const info = await stat2(path);
       existed = info.isFile();
+      if (existed) oldContent = await readFile2(path, "utf-8");
     } catch {
     }
     await mkdir(dirname2(path), { recursive: true });
     await writeFile(path, args.content, "utf-8");
+    const diff = makeUnifiedDiff(args.file_path, oldContent, args.content);
     return {
       content: existed ? `Overwrote ${path} (${args.content.length} bytes).` : `Created ${path} (${args.content.length} bytes).`,
-      summary: `${existed ? "Overwrote" : "Created"} ${args.file_path}`
+      summary: `${existed ? "Overwrote" : "Created"} ${args.file_path}`,
+      diff: diff || void 0
     };
   }
 });
 
 // src/tools/builtin/edit.ts
-import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
-import { resolve as resolve3, isAbsolute as isAbsolute3 } from "path";
+import { readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { resolve as resolve4, isAbsolute as isAbsolute3 } from "path";
 import { z as z3 } from "zod";
 var EditArgs = z3.object({
   file_path: z3.string().describe("Absolute or cwd-relative path to the file."),
@@ -576,10 +704,14 @@ var EditTool = defineTool({
   permission: "write",
   summarize: (args) => `Edit(${args.file_path})`,
   async execute(args, ctx) {
-    const path = isAbsolute3(args.file_path) ? args.file_path : resolve3(ctx.cwd, args.file_path);
+    const path = isAbsolute3(args.file_path) ? args.file_path : resolve4(ctx.cwd, args.file_path);
+    const sensitive = checkSensitivePath(path);
+    if (sensitive.blocked) {
+      return { content: `Refused: ${path} matches sensitive path policy (${sensitive.reason}).`, isError: true };
+    }
     let content;
     try {
-      content = await readFile2(path, "utf-8");
+      content = await readFile3(path, "utf-8");
     } catch (err) {
       throw new ToolError(`Cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`, "Edit", err);
     }
@@ -601,9 +733,11 @@ var EditTool = defineTool({
     }
     const newContent = args.replace_all ? content.split(args.old_string).join(args.new_string) : content.replace(args.old_string, args.new_string);
     await writeFile2(path, newContent, "utf-8");
+    const diff = makeUnifiedDiff(args.file_path, content, newContent);
     return {
       content: `Edited ${path}: replaced ${args.replace_all ? occurrences : 1} occurrence(s).`,
-      summary: `Edited ${args.file_path}`
+      summary: `Edited ${args.file_path}`,
+      diff: diff || void 0
     };
   }
 });
@@ -682,8 +816,8 @@ var BashTool = defineTool({
         maxBuffer: MAX_OUTPUT_BYTES * 2,
         cancelSignal: ctx.abortSignal
       });
-      const stdout = truncate(result.stdout ?? "", MAX_OUTPUT_BYTES, "stdout");
-      const stderr = truncate(result.stderr ?? "", MAX_OUTPUT_BYTES, "stderr");
+      const stdout = truncate2(result.stdout ?? "", MAX_OUTPUT_BYTES, "stdout");
+      const stderr = truncate2(result.stderr ?? "", MAX_OUTPUT_BYTES, "stderr");
       const parts = [];
       if (stdout) parts.push(`<stdout>
 ${stdout}
@@ -707,7 +841,7 @@ ${stderr}
     }
   }
 });
-function truncate(text, max, label) {
+function truncate2(text, max, label) {
   if (text.length <= max) return text;
   return text.slice(0, max) + `
 ... [${label} truncated, original ${text.length} bytes]`;
@@ -816,6 +950,366 @@ var GlobTool = defineTool({
   }
 });
 
+// src/tools/builtin/todo.ts
+import { z as z7 } from "zod";
+var TodoSchema = z7.object({
+  content: z7.string().describe("Imperative one-line task description (e.g. 'Run the test suite')."),
+  status: z7.enum(["pending", "in_progress", "completed"]).describe("Current status."),
+  activeForm: z7.string().optional().describe("Present-continuous form for the spinner (e.g. 'Running the test suite').")
+});
+var TodoWriteArgs = z7.object({
+  todos: z7.array(TodoSchema).describe("Full list. Replaces the current store.")
+});
+var TodoWriteTool = defineTool({
+  name: "TodoWrite",
+  description: "Maintain a structured task list for the current session. Pass the FULL list every call (it replaces the store). Mark exactly one task in_progress at a time; mark completed immediately when done; do not batch completions. Use when the task has 3+ distinct steps or is non-trivial. Skip for single trivial actions.",
+  parameters: TodoWriteArgs,
+  permission: "read",
+  summarize: (args) => `TodoWrite(${args.todos.length} items)`,
+  async execute(args, ctx) {
+    if (!ctx.todos) {
+      return {
+        content: "TodoWrite is unavailable: this agent run has no todo store. (Internal bug; tell the user.)",
+        isError: true
+      };
+    }
+    ctx.todos.set(args.todos);
+    const summary = args.todos.map((t, i) => `${i + 1}. ${t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[~]" : "[ ]"} ${t.content}`).join("\n");
+    return {
+      content: `Updated todos (${args.todos.length} items):
+${summary}`,
+      summary: `Todos: ${args.todos.filter((t) => t.status === "completed").length}/${args.todos.length} done`
+    };
+  }
+});
+
+// src/tools/builtin/webfetch.ts
+import { z as z8 } from "zod";
+var WebFetchArgs = z8.object({
+  url: z8.string().describe("Fully-qualified URL. http will be upgraded to https."),
+  prompt: z8.string().optional().describe(
+    "What information to look for. The host returns the page content; the LLM should then read it to answer the prompt."
+  )
+});
+var MAX_RESPONSE_BYTES = 1e6;
+var FETCH_TIMEOUT_MS = 3e4;
+var PRIVATE_HOST_PATTERNS = [
+  /^localhost$/i,
+  /^127\./,
+  /^0\.0\.0\.0$/,
+  /^169\.254\./,
+  /^10\./,
+  /^192\.168\./,
+  /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+  /^::1$/,
+  /^fc[0-9a-f]{2}:/i,
+  /^fe80:/i
+];
+function isPrivateHost(hostname) {
+  return PRIVATE_HOST_PATTERNS.some((p) => p.test(hostname));
+}
+var WebFetchTool = defineTool({
+  name: "WebFetch",
+  description: "Fetch a URL and return its textual content (HTML stripped to a markdown-ish form). Use for reading documentation, blog posts, or API specs. Private/loopback hosts are blocked. If the URL redirects to a different host, the redirect target is returned for you to re-fetch.",
+  parameters: WebFetchArgs,
+  permission: "network",
+  summarize: (args) => `WebFetch(${args.url})`,
+  async execute(args, ctx) {
+    let target;
+    try {
+      target = new URL(args.url);
+    } catch {
+      return { content: `Invalid URL: ${args.url}`, isError: true };
+    }
+    if (target.protocol === "http:") {
+      target.protocol = "https:";
+    }
+    if (target.protocol !== "https:") {
+      return { content: `Refused: only http(s) URLs are allowed.`, isError: true };
+    }
+    if (isPrivateHost(target.hostname)) {
+      return { content: `Refused: ${target.hostname} is a private/loopback host (SSRF guard).`, isError: true };
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    ctx.abortSignal?.addEventListener("abort", onAbort);
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const resp = await fetch(target.toString(), {
+        redirect: "manual",
+        signal: controller.signal,
+        headers: { "user-agent": "muse-cli/0.1" }
+      });
+      if (resp.status >= 300 && resp.status < 400) {
+        const loc = resp.headers.get("location");
+        if (loc) {
+          try {
+            const redirectURL = new URL(loc, target);
+            if (redirectURL.hostname !== target.hostname) {
+              return {
+                content: `Redirect to a different host: ${redirectURL.toString()}
+Re-fetch the new URL explicitly if you trust it.`,
+                summary: `Redirect to a different host: ${redirectURL.toString()}`,
+                kind: "warn"
+              };
+            }
+            return {
+              content: `Redirect (same host): ${redirectURL.toString()}
+Re-fetch the new URL to continue.`,
+              summary: `Redirect \u2192 ${redirectURL.pathname}`,
+              kind: "warn"
+            };
+          } catch {
+            return { content: `Redirect with unparseable location: ${loc}`, isError: true };
+          }
+        }
+      }
+      if (!resp.ok) {
+        return { content: `HTTP ${resp.status} ${resp.statusText} for ${target.toString()}`, isError: true };
+      }
+      const contentType = resp.headers.get("content-type") ?? "";
+      const reader = resp.body?.getReader();
+      if (!reader) return { content: `Empty response body.`, isError: true };
+      const chunks = [];
+      let total = 0;
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) {
+          total += value.byteLength;
+          if (total > MAX_RESPONSE_BYTES) {
+            await reader.cancel();
+            chunks.push(value.slice(0, value.byteLength - (total - MAX_RESPONSE_BYTES)));
+            break;
+          }
+          chunks.push(value);
+        }
+      }
+      const body = new TextDecoder("utf-8", { fatal: false }).decode(Buffer.concat(chunks.map((c) => Buffer.from(c))));
+      let processed = body;
+      if (/^text\/html|application\/xhtml/i.test(contentType)) {
+        processed = htmlToText(body);
+      }
+      const summary = args.prompt ? `# WebFetch result for: ${args.prompt}` : `Fetched ${target.hostname} (${total} bytes${total >= MAX_RESPONSE_BYTES ? ", truncated" : ""})`;
+      const truncated = processed.length > 2e5 ? processed.slice(0, 2e5) + "\n\n... [truncated]" : processed;
+      const preface = args.prompt ? `# WebFetch result for: ${args.prompt}
+
+Source: ${target.toString()}
+
+` : `Source: ${target.toString()}
+
+`;
+      return { content: preface + truncated, summary };
+    } catch (err) {
+      if (err.name === "AbortError") {
+        return { content: `WebFetch aborted (timeout or user cancel).`, isError: true };
+      }
+      return { content: `WebFetch failed: ${err instanceof Error ? err.message : String(err)}`, isError: true };
+    } finally {
+      clearTimeout(timer);
+      ctx.abortSignal?.removeEventListener("abort", onAbort);
+    }
+  }
+});
+function htmlToText(html) {
+  let s = html;
+  s = s.replace(/<(script|style|svg|noscript)\b[^>]*>[\s\S]*?<\/\1>/gi, "");
+  s = s.replace(/<!--[\s\S]*?-->/g, "");
+  s = s.replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi, (_m, lvl, txt) => {
+    return `
+
+${"#".repeat(parseInt(lvl, 10))} ${stripTags(txt).trim()}
+
+`;
+  });
+  s = s.replace(/<a\b[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, (_m, href, txt) => {
+    const label = stripTags(txt).trim();
+    return label ? `[${label}](${href})` : href;
+  });
+  s = s.replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, (_m, txt) => `
+- ${stripTags(txt).trim()}`);
+  s = s.replace(/<(p|div|section|article|header|footer|main|aside|nav|pre|blockquote|br|hr)\b[^>]*>/gi, "\n");
+  s = s.replace(/<\/(p|div|section|article|header|footer|main|aside|nav|pre|blockquote)>/gi, "\n");
+  s = s.replace(/<code\b[^>]*>([\s\S]*?)<\/code>/gi, (_m, txt) => `\`${stripTags(txt)}\``);
+  s = stripTags(s);
+  s = s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  s = s.replace(/\n{3,}/g, "\n\n").trim();
+  return s;
+}
+function stripTags(s) {
+  return s.replace(/<[^>]+>/g, "");
+}
+
+// src/tools/builtin/memory.ts
+import { z as z9 } from "zod";
+
+// src/loop/memory.ts
+import { mkdir as mkdir2, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join2 } from "path";
+import { createHash } from "crypto";
+function projectHash(cwd) {
+  return createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+}
+function memoryDir(cwd) {
+  return join2(homedir3(), ".muse", "projects", projectHash(cwd), "memory");
+}
+function memoryIndexPath(cwd) {
+  return join2(memoryDir(cwd), "MEMORY.md");
+}
+function memoryFilePath(cwd, name) {
+  return join2(memoryDir(cwd), `${name}.md`);
+}
+async function readMemoryFile(cwd, name) {
+  const path = memoryFilePath(cwd, name);
+  if (!existsSync(path)) {
+    throw new Error(`Memory "${name}" does not exist at ${path}.`);
+  }
+  return readFile4(path, "utf-8");
+}
+async function writeMemory(cwd, opts) {
+  const dir = memoryDir(cwd);
+  await mkdir2(dir, { recursive: true });
+  const filePath = memoryFilePath(cwd, opts.name);
+  const frontmatter = [
+    "---",
+    `name: ${opts.name}`,
+    `description: ${opts.description.replace(/\n/g, " ").trim()}`,
+    `metadata:`,
+    `  type: ${opts.type}`,
+    "---"
+  ].join("\n");
+  const content = `${frontmatter}
+
+${opts.body.trim()}
+`;
+  await writeFile3(filePath, content, "utf-8");
+  const indexPath = memoryIndexPath(cwd);
+  let index = "";
+  if (existsSync(indexPath)) index = await readFile4(indexPath, "utf-8");
+  const lines = index ? index.split("\n") : [];
+  const linePrefix = `- [${opts.name}](${opts.name}.md)`;
+  const newLine = `${linePrefix} \u2014 ${opts.description.replace(/\n/g, " ").trim()}`;
+  const existing = lines.findIndex((l) => l.startsWith(linePrefix));
+  let indexUpdated = false;
+  if (existing >= 0) {
+    if (lines[existing] !== newLine) {
+      lines[existing] = newLine;
+      indexUpdated = true;
+    }
+  } else {
+    lines.push(newLine);
+    indexUpdated = true;
+  }
+  if (indexUpdated) {
+    const out = lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+    await writeFile3(indexPath, out, "utf-8");
+  }
+  return { filePath, indexUpdated };
+}
+
+// src/tools/builtin/memory.ts
+var TYPES = ["user", "feedback", "project", "reference"];
+var MemoryWriteArgs = z9.object({
+  name: z9.string().regex(/^[a-z0-9][a-z0-9-_]*$/i, "must be a kebab- or snake-style slug").describe("Short kebab/snake slug; used as filename (<name>.md) and index key."),
+  description: z9.string().describe("One-line summary used in MEMORY.md index (decides future relevance)."),
+  type: z9.enum(TYPES).describe("user | feedback | project | reference"),
+  body: z9.string().describe("Memory content (markdown). For feedback/project, lead with the rule/fact then **Why:** and **How to apply:** lines.")
+});
+var MemoryWriteTool = defineTool({
+  name: "MemoryWrite",
+  description: "Save a long-term memory file under ~/.muse/projects/<hash>/memory/<name>.md and update MEMORY.md index. Use for: user role/preferences, validated approach decisions (feedback), project facts (auto-convert relative dates), external system references. Do NOT save: code patterns derivable from the repo, git history, fix recipes, ephemeral task state.",
+  parameters: MemoryWriteArgs,
+  permission: "write",
+  summarize: (args) => `MemoryWrite(${args.name}, type=${args.type})`,
+  async execute(args, ctx) {
+    const { filePath, indexUpdated } = await writeMemory(ctx.cwd, {
+      name: args.name,
+      description: args.description,
+      type: args.type,
+      body: args.body
+    });
+    return {
+      content: `Saved memory "${args.name}" (${args.type}) \u2192 ${filePath}${indexUpdated ? "\nMEMORY.md updated." : ""}`,
+      summary: `MemoryWrite ${args.name}`
+    };
+  }
+});
+var MemoryReadArgs = z9.object({
+  name: z9.string().describe("Memory slug to read (no .md extension).")
+});
+var MemoryReadTool = defineTool({
+  name: "MemoryRead",
+  description: "Read a specific long-term memory file by name. Use after seeing it referenced in MEMORY.md (which is auto-injected into the system prompt).",
+  parameters: MemoryReadArgs,
+  permission: "read",
+  summarize: (args) => `MemoryRead(${args.name})`,
+  async execute(args, ctx) {
+    try {
+      const content = await readMemoryFile(ctx.cwd, args.name);
+      return { content, summary: `MemoryRead ${args.name}` };
+    } catch (err) {
+      return { content: err instanceof Error ? err.message : String(err), isError: true };
+    }
+  }
+});
+
+// src/tools/builtin/ask-user-question.ts
+import { z as z10 } from "zod";
+var AskQuestionOptionSchema = z10.object({
+  label: z10.string().min(1).describe("Option text shown to the user. Concise (1-5 words)."),
+  description: z10.string().optional().describe("Optional one-line explanation of what this option means."),
+  preview: z10.string().optional().describe(
+    "Optional rich preview rendered in a right-side panel when this option is focused. Use for code/diagram/config snippets that help compare options visually. Multi-line text supported."
+  )
+});
+var AskQuestionSchema = z10.object({
+  question: z10.string().min(1).describe("Full question text (end with ?)."),
+  header: z10.string().min(1).max(16).describe("Very short label (chip), max 12 chars. E.g. 'Auth method'."),
+  options: z10.array(AskQuestionOptionSchema).min(2).max(4).describe("2-4 options. Mutually exclusive unless multiSelect=true."),
+  multiSelect: z10.boolean().optional().describe("Allow multiple selections. Default false.")
+});
+var AskUserQuestionArgs = z10.object({
+  questions: z10.array(AskQuestionSchema).min(1).max(4).describe("1-4 questions to ask the user sequentially.")
+});
+var AskUserQuestionTool = defineTool({
+  name: "AskUserQuestion",
+  description: "Ask the user one or more multiple-choice questions when their input is needed to proceed. Each question has 2-4 options. Use multiSelect=true for non-mutually-exclusive choices. Prefer this over plain-text questions when the answer space is bounded. If the user presses Esc, the entire batch is treated as cancelled.",
+  parameters: AskUserQuestionArgs,
+  permission: "read",
+  summarize: (args) => `AskUserQuestion(${args.questions.length} question${args.questions.length === 1 ? "" : "s"})`,
+  async execute(args, ctx) {
+    if (!ctx.askQuestions) {
+      return {
+        content: "AskUserQuestion is unavailable: this agent run has no question handler. (Internal bug; tell the user.)",
+        isError: true
+      };
+    }
+    const responses = await ctx.askQuestions(args.questions);
+    if (responses.length > 0 && responses[0].cancelled) {
+      return {
+        content: "User cancelled (Esc). No answers were collected.",
+        isError: false
+      };
+    }
+    const blocks = args.questions.map((q, qi) => {
+      const r = responses[qi];
+      const sel = r?.selections ?? [];
+      const ans = sel.length === 0 ? "(no answer)" : sel.join(", ");
+      const notes = r?.notes?.trim();
+      return notes ? `Q: ${q.question}
+A: ${ans}
+Notes: ${notes}` : `Q: ${q.question}
+A: ${ans}`;
+    });
+    return {
+      content: blocks.join("\n\n"),
+      summary: `Asked ${args.questions.length} question${args.questions.length === 1 ? "" : "s"}`
+    };
+  }
+});
+
 // src/tools/builtin/index.ts
 var BUILTIN_TOOLS = [
   ReadTool,
@@ -823,7 +1317,12 @@ var BUILTIN_TOOLS = [
   EditTool,
   BashTool,
   GrepTool,
-  GlobTool
+  GlobTool,
+  TodoWriteTool,
+  WebFetchTool,
+  MemoryReadTool,
+  MemoryWriteTool,
+  AskUserQuestionTool
 ];
 
 // src/permission/index.ts
@@ -836,6 +1335,8 @@ var MODE_CYCLE = [
 var PermissionGate = class {
   rules;
   mode = "default";
+  /** Session 级 allow：用户在 PermissionPrompt 选 "yes, for session" 后填充。 */
+  sessionAllow = /* @__PURE__ */ new Set();
   constructor(rules = {}) {
     this.rules = {
       allow: rules.allow ?? [],
@@ -855,8 +1356,16 @@ var PermissionGate = class {
     this.mode = MODE_CYCLE[(i + 1) % MODE_CYCLE.length];
     return this.mode;
   }
+  /** 用户在 PermissionPrompt 选 "yes, allow for session" 时记下。 */
+  allowForSession(toolName) {
+    this.sessionAllow.add(toolName);
+  }
+  isSessionAllowed(toolName) {
+    return this.sessionAllow.has(toolName);
+  }
   decide(input) {
     if (this.matches(this.rules.deny, input)) return "deny";
+    if (this.sessionAllow.has(input.toolName)) return "allow";
     switch (this.mode) {
       case "bypassPermissions":
         return "allow";
@@ -910,16 +1419,16 @@ var PermissionGate = class {
 };
 
 // src/session/jsonl.ts
-import { appendFile, mkdir as mkdir2, readdir, readFile as readFile3, stat as stat3 } from "fs/promises";
-import { existsSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname as dirname3, join as join2 } from "path";
-import { createHash, randomUUID } from "crypto";
-function projectHash(cwd) {
-  return createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+import { appendFile, mkdir as mkdir3, readdir, readFile as readFile5, stat as stat3 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { homedir as homedir4 } from "os";
+import { dirname as dirname3, join as join3 } from "path";
+import { createHash as createHash2, randomUUID } from "crypto";
+function projectHash2(cwd) {
+  return createHash2("sha256").update(cwd).digest("hex").slice(0, 16);
 }
 function sessionsDir(cwd) {
-  return join2(homedir2(), ".muse", "projects", projectHash(cwd), "sessions");
+  return join3(homedir4(), ".muse", "projects", projectHash2(cwd), "sessions");
 }
 var Session = class _Session {
   meta;
@@ -930,8 +1439,8 @@ var Session = class _Session {
   static async create(cwd) {
     const id = randomUUID();
     const dir = sessionsDir(cwd);
-    await mkdir2(dir, { recursive: true });
-    const path = join2(dir, `${id}.jsonl`);
+    await mkdir3(dir, { recursive: true });
+    const path = join3(dir, `${id}.jsonl`);
     const meta = {
       id,
       cwd,
@@ -947,7 +1456,7 @@ var Session = class _Session {
   }
   static async resolve(cwd, idOrPrefix) {
     const dir = sessionsDir(cwd);
-    if (!existsSync(dir)) return void 0;
+    if (!existsSync2(dir)) return void 0;
     const entries = await readdir(dir);
     const matches = entries.filter((e) => e.endsWith(".jsonl") && e.startsWith(idOrPrefix));
     if (matches.length === 0) return void 0;
@@ -955,12 +1464,12 @@ var Session = class _Session {
       throw new Error(`Ambiguous session id "${idOrPrefix}" matches ${matches.length} sessions; use more characters.`);
     }
     const top = matches[0];
-    const st = await stat3(join2(dir, top));
+    const st = await stat3(join3(dir, top));
     return {
       id: top.replace(/\.jsonl$/, ""),
       cwd,
       createdAt: st.mtime.toISOString(),
-      path: join2(dir, top)
+      path: join3(dir, top)
     };
   }
   /**
@@ -969,13 +1478,13 @@ var Session = class _Session {
    */
   static async listAll(cwd, limit) {
     const dir = sessionsDir(cwd);
-    if (!existsSync(dir)) return [];
+    if (!existsSync2(dir)) return [];
     const entries = await readdir(dir);
     const files = entries.filter((e) => e.endsWith(".jsonl"));
     if (files.length === 0) return [];
     const stats = await Promise.all(
       files.map(async (f) => {
-        const path = join2(dir, f);
+        const path = join3(dir, f);
         const st = await stat3(path);
         return { file: f, path, mtime: st.mtime };
       })
@@ -1012,7 +1521,7 @@ var Session = class _Session {
     const line = JSON.stringify(event) + "\n";
     this.writeQueue = this.writeQueue.then(async () => {
       try {
-        await mkdir2(dirname3(this.meta.path), { recursive: true });
+        await mkdir3(dirname3(this.meta.path), { recursive: true });
         await appendFile(this.meta.path, line, "utf-8");
       } catch (err) {
         log.warn(`session append failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1021,8 +1530,8 @@ var Session = class _Session {
     return this.writeQueue;
   }
   async readAll() {
-    if (!existsSync(this.meta.path)) return [];
-    const raw = await readFile3(this.meta.path, "utf-8");
+    if (!existsSync2(this.meta.path)) return [];
+    const raw = await readFile5(this.meta.path, "utf-8");
     const events = [];
     for (const line of raw.split("\n")) {
       if (!line.trim()) continue;
@@ -1037,7 +1546,7 @@ var Session = class _Session {
 async function readSummary(meta) {
   let events = [];
   try {
-    const raw = await readFile3(meta.path, "utf-8");
+    const raw = await readFile5(meta.path, "utf-8");
     for (const line of raw.split("\n")) {
       if (!line.trim()) continue;
       try {
@@ -1058,6 +1567,32 @@ async function readSummary(meta) {
   return { ...meta, preview, messageCount: messages.length };
 }
 
+// src/loop/todos.ts
+var TodoStore = class {
+  items = [];
+  list() {
+    return this.items.slice();
+  }
+  set(items) {
+    this.items = items.slice();
+  }
+  clear() {
+    this.items = [];
+  }
+  /** 把当前清单格式化为 system prompt 段落；无任务时返回空串。 */
+  toPromptSection() {
+    if (this.items.length === 0) return "";
+    const lines = this.items.map((t, i) => {
+      const marker = t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[~]" : "[ ]";
+      return `  ${i + 1}. ${marker} ${t.content}`;
+    });
+    return `# Current todos
+${lines.join("\n")}
+
+Update via TodoWrite as you make progress. Keep exactly one item in_progress at a time.`;
+  }
+};
+
 // src/loop/agent.ts
 var Agent = class {
   constructor(ctx) {
@@ -1065,6 +1600,7 @@ var Agent = class {
   }
   ctx;
   messages = [];
+  todos = new TodoStore();
   getMessages() {
     return this.messages;
   }
@@ -1081,10 +1617,14 @@ var Agent = class {
       const tools = this.ctx.tools.toLLMDefinitions(
         mode === "plan" ? (t) => t.permission === "read" : void 0
       );
+      const todoSection = this.todos.toPromptSection();
+      const systemPrompt = todoSection ? `${this.ctx.systemPrompt}
+
+${todoSection}` : this.ctx.systemPrompt;
       const stream = this.ctx.llm.stream({
         messages: this.messages,
         tools,
-        systemPrompt: this.ctx.systemPrompt,
+        systemPrompt,
         abortSignal: this.ctx.abortSignal
       });
       const assistantParts = [];
@@ -1108,6 +1648,7 @@ var Agent = class {
         this.ctx.events?.onTurnEnd?.();
         return;
       }
+      this.ctx.events?.onAssistantTurn?.();
       for (const call of toolCallsToRun) {
         await this.runToolCall(call);
       }
@@ -1173,27 +1714,37 @@ var Agent = class {
       return;
     }
     if (decision === "ask") {
-      approved = await this.ctx.events?.onPermissionRequest?.(call.name, call.args, summary) ?? false;
-      if (!approved) {
+      const userDecision = await this.ctx.events?.onPermissionRequest?.(call.name, call.args, summary) ?? "no";
+      if (userDecision === "no") {
         this.recordToolResult(call.id, call.name, `User rejected ${call.name}.`, true);
         return;
       }
+      if (userDecision === "session_allow") {
+        this.ctx.permissions.allowForSession(call.name);
+      }
+      approved = true;
     }
     const toolCtx = {
       cwd: this.ctx.cwd,
       abortSignal: this.ctx.abortSignal,
-      askPermission: async () => true
+      askPermission: async () => true,
       // 已在外层处理
+      todos: this.todos,
+      askQuestions: this.ctx.events?.onAskQuestions ? (qs) => this.ctx.events.onAskQuestions(qs) : void 0
     };
     const result = await this.ctx.tools.execute(call.name, call.args, toolCtx);
-    this.recordToolResult(call.id, call.name, result.content, result.isError ?? false, result.summary);
+    this.recordToolResult(call.id, call.name, result.content, result.isError ?? false, result.summary, result.diff, result.kind);
   }
-  recordToolResult(id, name, content, isError, summary) {
+  recordToolResult(id, name, content, isError, summary, diff, kind) {
     const toolMsg = {
       role: "tool",
       toolUseId: id,
       content,
-      isError
+      isError,
+      toolName: name,
+      ...diff ? { diff } : {},
+      ...summary ? { summary } : {},
+      ...kind ? { kind } : {}
     };
     this.messages.push(toolMsg);
     this.ctx.session.append({ type: "message", time: (/* @__PURE__ */ new Date()).toISOString(), message: toolMsg });
@@ -1202,10 +1753,10 @@ var Agent = class {
 };
 
 // src/loop/system-prompt.ts
-import { homedir as homedir3 } from "os";
+import { homedir as homedir5 } from "os";
 function buildSystemPrompt(opts) {
-  const { cwd, model, provider, lang, toolNames } = opts;
-  const home = homedir3();
+  const { cwd, model, provider, lang, toolNames, memoryIndex } = opts;
+  const home = homedir5();
   const displayCwd = cwd.startsWith(home) ? cwd.replace(home, "~") : cwd;
   const sections = [];
   sections.push(`You are Muse, a CLI coding assistant. You are running on the user's local machine via a terminal interface.`);
@@ -1229,60 +1780,76 @@ Prefer the dedicated tool over Bash when one fits (Read for file reading, Edit f
 - If a command may be destructive (rm -rf, force push, drop table, etc.), warn first and let the user run it manually.
 - When the user asks a question that does not need tools, just answer.`
   );
+  if (toolNames.includes("TodoWrite")) {
+    sections.push(
+      `# Task management
+- For non-trivial, multi-step work, use TodoWrite to plan and track progress.
+- Keep exactly one task in_progress; mark a task completed immediately when done.
+- Skip it for trivial single-step requests.`
+    );
+  }
   if (lang === "zh-CN") {
     sections.push(`# Output language
 Reply in Chinese (\u7B80\u4F53\u4E2D\u6587) unless the user writes in English.`);
   }
+  if (memoryIndex && memoryIndex.trim()) {
+    sections.push(
+      `# Memory (long-term)
+Below is MEMORY.md \u2014 your index of persistent facts about the user, project, and prior feedback. Each line points at a file you can MemoryRead. Use MemoryWrite to record new durable knowledge (user role/preferences, validated decisions, project facts, external references). Do NOT save things derivable from the repo or git history.
+
+` + memoryIndex
+    );
+  }
   return sections.join("\n\n");
 }
 
 // src/config/loader.ts
-import { readFile as readFile4 } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
-import { homedir as homedir4 } from "os";
-import { join as join3, resolve as resolve4 } from "path";
+import { readFile as readFile6 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import { homedir as homedir6 } from "os";
+import { join as join4, resolve as resolve5 } from "path";
 
 // src/config/types.ts
-import { z as z7 } from "zod";
-var ProviderConfigSchema = z7.object({
-  apiKey: z7.string().optional(),
-  baseUrl: z7.string().optional(),
-  extraHeaders: z7.record(z7.string()).optional()
+import { z as z11 } from "zod";
+var ProviderConfigSchema = z11.object({
+  apiKey: z11.string().optional(),
+  baseUrl: z11.string().optional(),
+  extraHeaders: z11.record(z11.string()).optional()
 }).passthrough();
-var LLMConfigSchema = z7.object({
-  provider: z7.string().optional().describe("Fallback provider preset (only used when no models.json entry matches)."),
-  model: z7.string().optional().describe("Active model id; should match an id in models.json."),
-  temperature: z7.number().min(0).max(2).optional(),
-  maxTokens: z7.number().int().positive().optional()
+var LLMConfigSchema = z11.object({
+  provider: z11.string().optional().describe("Fallback provider preset (only used when no models.local.json entry matches)."),
+  model: z11.string().optional().describe("Active model id; should match an id in models.local.json."),
+  temperature: z11.number().min(0).max(2).optional(),
+  maxTokens: z11.number().int().positive().optional()
 });
-var PermissionsSchema = z7.object({
-  allow: z7.array(z7.string()).optional(),
-  ask: z7.array(z7.string()).optional(),
-  deny: z7.array(z7.string()).optional(),
-  defaultMode: z7.enum(["strict", "relaxed", "ask"]).optional()
+var PermissionsSchema = z11.object({
+  allow: z11.array(z11.string()).optional(),
+  ask: z11.array(z11.string()).optional(),
+  deny: z11.array(z11.string()).optional(),
+  defaultMode: z11.enum(["strict", "relaxed", "ask"]).optional()
 });
-var UISchema = z7.object({
-  theme: z7.enum(["dark", "light"]).optional(),
-  lang: z7.enum(["en", "zh-CN"]).optional(),
-  showBanner: z7.boolean().optional()
+var UISchema = z11.object({
+  theme: z11.enum(["dark", "light"]).optional(),
+  lang: z11.enum(["en", "zh-CN"]).optional(),
+  showBanner: z11.boolean().optional()
 });
-var SettingsSchema = z7.object({
+var SettingsSchema = z11.object({
   llm: LLMConfigSchema.optional(),
-  providers: z7.record(ProviderConfigSchema).optional(),
+  providers: z11.record(ProviderConfigSchema).optional(),
   permissions: PermissionsSchema.optional(),
   ui: UISchema.optional(),
-  mcpServers: z7.record(z7.unknown()).optional(),
-  skills: z7.object({
-    enabled: z7.boolean().optional(),
-    disabled: z7.array(z7.string()).optional()
+  mcpServers: z11.record(z11.unknown()).optional(),
+  skills: z11.object({
+    enabled: z11.boolean().optional(),
+    disabled: z11.array(z11.string()).optional()
   }).optional()
 }).passthrough();
 
 // src/config/_env.ts
-var ENV_PATTERN = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+var ENV_PATTERN2 = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
 function expandEnvVars(value) {
   if (typeof value === "string") {
-    return value.replace(ENV_PATTERN, (_match, name) => process.env[name] ?? "");
+    return value.replace(ENV_PATTERN2, (_match, name) => process.env[name] ?? "");
   }
   if (Array.isArray(value)) {
     return value.map(expandEnvVars);
@@ -1316,7 +1883,7 @@ var DEFAULTS = {
     ollama: { baseUrl: "http://localhost:11434/v1" }
   },
   permissions: {
-    allow: ["Read", "Grep", "Glob"],
+    allow: ["Read", "Grep", "Glob", "TodoWrite"],
     ask: ["Write", "Edit", "Bash"],
     deny: [],
     defaultMode: "ask"
@@ -1327,9 +1894,9 @@ var DEFAULTS = {
   }
 };
 async function readJsonIfExists(path) {
-  if (!existsSync2(path)) return void 0;
+  if (!existsSync3(path)) return void 0;
   try {
-    const raw = await readFile4(path, "utf-8");
+    const raw = await readFile6(path, "utf-8");
     return JSON.parse(raw);
   } catch (err) {
     log.warn(`Failed to parse settings at ${path}: ${err instanceof Error ? err.message : String(err)}`);
@@ -1357,9 +1924,9 @@ async function loadSettings(cwd = process.cwd()) {
   const sources = ["<defaults>"];
   let merged = DEFAULTS;
   const candidates = [
-    join3(homedir4(), ".muse", "settings.json"),
-    join3(cwd, ".muse", "settings.json"),
-    join3(cwd, ".muse", "settings.local.json")
+    join4(homedir6(), ".muse", "settings.json"),
+    join4(cwd, ".muse", "settings.json"),
+    join4(cwd, ".muse", "settings.local.json")
   ];
   for (const path of candidates) {
     const raw = await readJsonIfExists(path);