@theokit/sdk-tools 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,9 +1,13 @@
-import { readFile, copyFile, mkdir, writeFile, readdir, open } from 'fs/promises';
+import { readFile, copyFile, mkdir, writeFile, readdir, open, stat } from 'fs/promises';
 import { dirname, join, relative, resolve, sep } from 'path';
 import { defineTool, ConfigurationError } from '@theokit/sdk';
 import { z } from 'zod';
-import { existsSync, mkdirSync, writeFileSync, realpathSync, lstatSync, readlinkSync } from 'fs';
+import { existsSync, statSync, mkdirSync, writeFileSync, realpathSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'fs';
+import { replaceFileAtomic } from '@theokit/sdk/internal/persistence';
+import { safeFilenameForId, safePathJoin as safePathJoin$1 } from '@theokit/sdk/path-safety';
 import { spawn } from 'child_process';
+import { lookup } from 'dns/promises';
+import { isIP } from 'net';
 
 // src/apply-patch.ts
 var PathTraversalError = class extends ConfigurationError {
@@ -55,8 +59,8 @@ function realpathOfDeepestExisting(path) {
   } catch {
   }
   try {
-    const stat = lstatSync(path);
-    if (stat.isSymbolicLink()) {
+    const stat2 = lstatSync(path);
+    if (stat2.isSymbolicLink()) {
       const target = readlinkSync(path);
       const parentReal = realpathOfDeepestExisting(dirname(path));
       const parentBase = parentReal ?? dirname(path);
@@ -219,6 +223,45 @@ function applyHunks(content, changes) {
   }
   return result.join("\n");
 }
+function createSessionArtifactStore(options) {
+  const { dir } = options;
+  const idStrategy = options.idStrategy ?? ((id) => safeFilenameForId(id));
+  const extension = options.extension ?? ".md";
+  function path(id) {
+    return safePathJoin$1(dir, `${idStrategy(id)}${extension}`);
+  }
+  async function write(id, content) {
+    const target = path(id);
+    await mkdir(dir, { recursive: true });
+    await replaceFileAtomic(target, content);
+    return target;
+  }
+  async function read(id) {
+    try {
+      return await readFile(path(id), "utf8");
+    } catch {
+      return void 0;
+    }
+  }
+  async function has(id) {
+    try {
+      await stat(path(id));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async function list() {
+    let entries;
+    try {
+      entries = await readdir(dir);
+    } catch {
+      return [];
+    }
+    return entries.filter((name) => name.endsWith(extension)).map((name) => name.slice(0, name.length - extension.length));
+  }
+  return { write, read, has, list, path };
+}
 function createEditFileTool(opts) {
   const { projectRoot } = opts;
   return defineTool({
@@ -548,6 +591,439 @@ function globToRegex(pattern) {
   }
   return new RegExp(`^${regexStr}$`);
 }
+var CatastrophicCommandError = class extends ConfigurationError {
+  name = "CatastrophicCommandError";
+  constructor(reason) {
+    super(`Refused a catastrophic shell command: ${reason} (shell guardrail).`, {
+      code: "catastrophic_command"
+    });
+  }
+};
+function unquote(token) {
+  return token.replace(/^(['"])(.*)\1$/, "$2").replace(/^['"]|['"]$/g, "");
+}
+function commandSegments(command) {
+  return command.split(/&&|\|\||[;|&\n]/).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function commandArgs(segment, name) {
+  const tokens = segment.split(/\s+/);
+  let i = 0;
+  if (tokens[i] === "sudo") i += 1;
+  if (tokens[i] !== name) return null;
+  return tokens.slice(i + 1);
+}
+function commandSegmentsNamed(command, name) {
+  return commandSegments(command).map((s) => commandArgs(s, name)).filter((args) => args !== null);
+}
+function isRecursiveForce(args) {
+  const flags = args.filter((t) => t.startsWith("-")).join(" ");
+  if (flags.length === 0) return false;
+  const recursive = /-[a-z]*r/i.test(flags) || /--recursive/.test(flags);
+  const force = /-[a-z]*f/i.test(flags) || /--force/.test(flags);
+  return recursive && force;
+}
+function isRecursive(args) {
+  const flags = args.filter((t) => t.startsWith("-")).join(" ");
+  return /-[a-z]*r/i.test(flags) || /--recursive/.test(flags);
+}
+var SAFE_ABSOLUTE_TARGET = /^\/(tmp|var\/tmp)(\/|$)/;
+function targetsDangerousPath(args) {
+  const targets = args.filter((token) => token.length > 0 && !token.startsWith("-")).map(unquote);
+  return targets.some((raw) => {
+    const t = raw.replace(/\/+/g, "/");
+    if (t === "/dev/null" || SAFE_ABSOLUTE_TARGET.test(t)) return false;
+    return /^\/($|\*)/.test(t) || // "/" or "/*"
+    /^\/[^/]/.test(t) || // an absolute path like /etc, /usr/local, /home/user/x
+    t === "~" || t.startsWith("~/") || /\$\{?HOME\b\}?/.test(t) || // $HOME or ${HOME}
+    t === ".." || t.startsWith("../") || t.includes("/..") || t === "*";
+  });
+}
+var DEVICE_WIPE = [
+  /\bmkfs(\.\w+)?\b/,
+  /\bdd\b[^\n]*\bof=\/dev\//,
+  /\btruncate\b[^\n]*\s\/dev\//,
+  />\s*\/dev\/(sd|nvme|hd|vd|mmcblk|disk|loop|dm-)/
+];
+var checkRemoteExec = (cmd) => /\b(curl|wget|fetch)\b[^\n]*\|\s*(sudo\s+)?(sh|bash|zsh|dash|python[0-9.]*|node|ruby|perl)\b/i.test(
+  cmd
+) || /(\$\(|<\()\s*(sudo\s+)?(curl|wget|fetch)\b/i.test(cmd) || /\b(eval|source)\b[^\n]*\b(curl|wget|fetch)\b/i.test(cmd) ? "executes a remote download (pipe / command-substitution / eval) \u2014 remote code execution" : null;
+var checkDeviceWipe = (cmd) => DEVICE_WIPE.some((re) => re.test(cmd)) ? "writes to a raw block device / formats a disk" : null;
+var checkForkBomb = (cmd) => /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(cmd) ? "fork bomb" : null;
+var checkDestructiveGit = (cmd) => {
+  if (/\bgit\b[^\n]*\bpush\b[^\n]*(--force(?!-with-lease)\b|\s-f\b|\s\+\S)/.test(cmd)) {
+    return "git force-push (overwrites remote history)";
+  }
+  if (/\bgit\b[^\n]*\breset\b[^\n]*--hard\b/.test(cmd)) {
+    return "git reset --hard (discards committed and working changes)";
+  }
+  if (/\bgit\b[^\n]*\bclean\b[^\n]*(-[a-z]*f[a-z]*d|-[a-z]*d[a-z]*f)/.test(cmd)) {
+    return "git clean -fd (permanently deletes untracked files)";
+  }
+  return null;
+};
+var checkRm = (cmd) => commandSegmentsNamed(cmd, "rm").some((a) => isRecursiveForce(a) && targetsDangerousPath(a)) ? "recursive force-delete of an absolute, home, or parent path" : null;
+var checkPerm = (cmd) => ["chmod", "chown"].some(
+  (name) => commandSegmentsNamed(cmd, name).some((a) => isRecursive(a) && targetsDangerousPath(a))
+) ? "recursive permission change on an absolute, home, or parent path" : null;
+var checkFind = (cmd) => /\bfind\s+(\/\S*|~\S*|\$\{?HOME\}?\S*)\s[^\n]*(-delete\b|-exec\s+rm\b)/.test(cmd) ? "find -delete / -exec rm on an absolute or home path" : null;
+var checkExfiltration = (cmd) => {
+  const touchesSecret = /(^|[\s/'"])(\.env(\.\w+)?|id_rsa|id_ed25519|\.ssh(\/|\b)|credentials|\.aws(\/|\b)|\.npmrc)\b/.test(
+    cmd
+  );
+  const sendsNetwork = /\b(curl|wget|nc|netcat|scp|ftp|telnet)\b/.test(cmd) || /\bpython[0-9.]*\s+-m\s+http/.test(cmd);
+  return touchesSecret && sendsNetwork ? "sends a secret/credential file over the network (exfiltration)" : null;
+};
+var CATEGORY_CHECKS = [
+  checkRemoteExec,
+  checkDeviceWipe,
+  checkForkBomb,
+  checkDestructiveGit,
+  checkRm,
+  checkPerm,
+  checkFind,
+  checkExfiltration
+];
+function catastrophicShellReason(command) {
+  const cmd = command.trim();
+  if (cmd.length === 0) return null;
+  for (const check of CATEGORY_CHECKS) {
+    const reason = check(cmd);
+    if (reason) return reason;
+  }
+  return null;
+}
+
+// src/internal/command-policy.ts
+function denyCatastrophicCommands() {
+  return (command) => catastrophicShellReason(command);
+}
+function commandDenialReason(command, policies) {
+  for (const policy of policies) {
+    const reason = policy(command);
+    if (reason !== null) return reason;
+  }
+  return null;
+}
+function isCommandAllowed(command, policies) {
+  return commandDenialReason(command, policies) === null;
+}
+var SsrfBlockedError = class extends ConfigurationError {
+  name = "SsrfBlockedError";
+  constructor(host, detail) {
+    super(
+      `Blocked request to "${host}"${detail ? ` (${detail})` : ""}: address is private, loopback, link-local, or reserved (SSRF guard).`,
+      { code: "ssrf_blocked" }
+    );
+  }
+};
+function v4ToInt(ip) {
+  const parts = ip.split(".");
+  return (Number(parts[0]) << 24 | Number(parts[1]) << 16 | Number(parts[2]) << 8 | Number(parts[3])) >>> 0;
+}
+function inV4Cidr(ipInt, base, prefix) {
+  const mask = prefix === 0 ? 0 : 4294967295 << 32 - prefix >>> 0;
+  return (ipInt & mask) === (v4ToInt(base) & mask);
+}
+var V4_BLOCKED = [
+  ["0.0.0.0", 8],
+  // "this host"
+  ["10.0.0.0", 8],
+  // private
+  ["100.64.0.0", 10],
+  // CGNAT
+  ["127.0.0.0", 8],
+  // loopback
+  ["169.254.0.0", 16],
+  // link-local + cloud metadata
+  ["172.16.0.0", 12],
+  // private
+  ["192.168.0.0", 16],
+  // private
+  ["224.0.0.0", 4],
+  // multicast
+  ["240.0.0.0", 4]
+  // reserved
+];
+function isBlockedV4(ip) {
+  const n = v4ToInt(ip);
+  return V4_BLOCKED.some(([base, prefix]) => inV4Cidr(n, base, prefix));
+}
+function foldDottedTail(s) {
+  const lastColon = s.lastIndexOf(":");
+  const tail = s.slice(lastColon + 1);
+  if (!tail.includes(".")) return s;
+  if (isIP(tail) !== 4) return null;
+  const o = tail.split(".").map(Number);
+  const hi = (o[0] << 8 | o[1]).toString(16);
+  const lo = (o[2] << 8 | o[3]).toString(16);
+  return `${s.slice(0, lastColon + 1)}${hi}:${lo}`;
+}
+function expandHextets(s) {
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tailGroups = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  if (halves.length === 1) return head.length === 8 ? head : null;
+  const missing = 8 - head.length - tailGroups.length;
+  if (missing < 0) return null;
+  return [...head, ...Array(missing).fill("0"), ...tailGroups];
+}
+function ipv6ToBytes(ip) {
+  const folded = foldDottedTail(ip.toLowerCase().split("%")[0] ?? "");
+  if (folded === null) return null;
+  const groups = expandHextets(folded);
+  if (groups === null || groups.length !== 8) return null;
+  const bytes = [];
+  for (const g of groups) {
+    const n = Number.parseInt(g || "0", 16);
+    bytes.push(n >> 8, n & 255);
+  }
+  return bytes;
+}
+function allZero(bytes, from, to) {
+  for (let i = from; i < to; i += 1) if (bytes[i] !== 0) return false;
+  return true;
+}
+function isBlockedV6Bytes(b) {
+  if (allZero(b, 0, 10) && b[10] === 255 && b[11] === 255) {
+    return isBlockedV4(`${b[12]}.${b[13]}.${b[14]}.${b[15]}`);
+  }
+  if (allZero(b, 0, 15) && (b[15] === 1 || b[15] === 0)) return true;
+  if (allZero(b, 0, 12)) return isBlockedV4(`${b[12]}.${b[13]}.${b[14]}.${b[15]}`);
+  if (b[0] === 254 && (b[1] & 192) === 128) return true;
+  return (b[0] & 254) === 252;
+}
+function isBlockedIp(ip) {
+  const fam = isIP(ip);
+  if (fam === 4) return isBlockedV4(ip);
+  if (fam === 6) {
+    const bytes = ipv6ToBytes(ip);
+    return bytes === null ? true : isBlockedV6Bytes(bytes);
+  }
+  return true;
+}
+async function resolveAndScreen(rawHost, options = {}) {
+  const host = rawHost.replace(/^\[|\]$/g, "");
+  if (isIP(host) !== 0) {
+    if (isBlockedIp(host)) throw new SsrfBlockedError(host);
+    return [host];
+  }
+  const lookup$1 = options.lookup ?? lookup;
+  const addrs = await lookup$1(host, { all: true });
+  if (addrs.length === 0) throw new SsrfBlockedError(host, "no addresses");
+  for (const a of addrs) {
+    if (isBlockedIp(a.address)) throw new SsrfBlockedError(host, a.address);
+  }
+  return addrs.map((a) => a.address);
+}
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
+function redirectTarget(res, current, originalUrl) {
+  const location = res.headers.get("location");
+  if (!REDIRECT_STATUSES.has(res.status) || !location) return void 0;
+  const next = new URL(location, current);
+  if (next.protocol !== "http:" && next.protocol !== "https:") {
+    throw new SsrfBlockedError(originalUrl, `non-http redirect to ${next.protocol}`);
+  }
+  return next.href;
+}
+async function screenedFetch(url, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const maxRedirects = options.maxRedirects ?? 5;
+  let current = url;
+  for (let hop = 0; hop <= maxRedirects; hop += 1) {
+    if (!options.allowPrivateHosts) {
+      await resolveAndScreen(new URL(current).hostname, { lookup: options.lookup });
+    }
+    const res = await fetchImpl(current, { redirect: "manual", signal: options.signal });
+    const next = redirectTarget(res, current, url);
+    if (next === void 0) return res;
+    current = next;
+  }
+  throw new SsrfBlockedError(url, "too many redirects");
+}
+var DEFAULT_BUDGET = 8e3;
+var DEFAULT_MAX_DEPTH = 4;
+var PER_DIR_CAP = 200;
+var TRUNCATED_MARKER = "\u2026 (truncated)";
+var DOC_HEAD_CHARS = 200;
+var DEFAULT_REPO_MAP_IGNORE = [
+  "node_modules",
+  ".git",
+  "dist",
+  ".theo",
+  ".next",
+  "build",
+  "coverage",
+  "target",
+  "out"
+];
+var PROJECT_DOCS = ["AGENTS.md", "CLAUDE.md", "README.md"];
+var MANIFESTS = ["package.json", "pyproject.toml", "Cargo.toml", "go.mod"];
+function safeExists(p) {
+  try {
+    return existsSync(p);
+  } catch {
+    return false;
+  }
+}
+function safeReadHead(p, n) {
+  try {
+    return readFileSync(p, "utf-8").slice(0, n).replace(/\s+/g, " ").trim();
+  } catch {
+    return "";
+  }
+}
+function buildEnvContext(cwd) {
+  const lines = [
+    "<env>",
+    `  Working directory: ${cwd}`,
+    `  Platform: ${process.platform} (${process.arch})`,
+    `  Node: ${process.version}`,
+    `  Is git repo: ${safeExists(join(cwd, ".git")) ? "yes" : "no"}`,
+    `  Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}`
+  ];
+  const docs = PROJECT_DOCS.filter((d) => safeExists(join(cwd, d)));
+  if (docs.length > 0) {
+    lines.push(`  Project docs: ${docs.join(", ")}`);
+    const head = safeReadHead(join(cwd, docs[0]), DOC_HEAD_CHARS);
+    if (head) lines.push(`  ${docs[0]} (head): ${head}`);
+  }
+  const manifests = MANIFESTS.filter((m) => safeExists(join(cwd, m)));
+  if (manifests.length > 0) lines.push(`  Manifests: ${manifests.join(", ")}`);
+  lines.push("</env>");
+  return lines.join("\n");
+}
+function compareEntries(a, b) {
+  const ad = a.isDirectory() ? 0 : 1;
+  const bd = b.isDirectory() ? 0 : 1;
+  return ad !== bd ? ad - bd : a.name.localeCompare(b.name);
+}
+function visibleEntries(dir, ignore) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => !ignore.has(e.name) && !e.name.startsWith(".")).sort(compareEntries);
+}
+function pushLine(ctx, line) {
+  if (ctx.used + line.length + 1 > ctx.budget) {
+    ctx.truncated = true;
+    return false;
+  }
+  ctx.lines.push(line);
+  ctx.used += line.length + 1;
+  return true;
+}
+function emitEntry(ctx, dir, e, depth, indent) {
+  const isDir = e.isDirectory();
+  if (!pushLine(ctx, `${indent}${isDir ? `${e.name}/` : e.name}`)) return false;
+  if (isDir && depth + 1 < ctx.maxDepth) return walkDir2(ctx, join(dir, e.name), depth + 1);
+  return true;
+}
+function walkDir2(ctx, dir, depth) {
+  const entries = visibleEntries(dir, ctx.ignore);
+  const shown = entries.slice(0, PER_DIR_CAP);
+  const indent = "  ".repeat(depth);
+  for (const e of shown) {
+    if (!emitEntry(ctx, dir, e, depth, indent)) return false;
+  }
+  if (entries.length > shown.length) {
+    return pushLine(ctx, `${indent}\u2026 (${entries.length - shown.length} more)`);
+  }
+  return true;
+}
+function buildRepoMap(cwd, opts = {}) {
+  try {
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory()) {
+      return `(unavailable: ${cwd} is not a readable directory)`;
+    }
+  } catch {
+    return `(unavailable: ${cwd})`;
+  }
+  const ctx = {
+    ignore: /* @__PURE__ */ new Set([...DEFAULT_REPO_MAP_IGNORE, ...opts.ignore ?? []]),
+    maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH,
+    budget: opts.budget ?? DEFAULT_BUDGET,
+    lines: [],
+    used: 0,
+    truncated: false
+  };
+  walkDir2(ctx, cwd, 0);
+  return ctx.truncated ? `${ctx.lines.join("\n")}
+${TRUNCATED_MARKER}` : ctx.lines.join("\n");
+}
+
+// src/internal/tool-aci.ts
+function withDescription(tool, description) {
+  return {
+    name: tool.name,
+    description,
+    inputSchema: tool.inputSchema,
+    handler: tool.handler
+  };
+}
+function esc(s) {
+  return String(s).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function renderToolList(tools) {
+  if (tools.length === 0) return "<tools></tools>";
+  const lines = ["<tools>"];
+  for (const t of tools) {
+    lines.push(
+      "  <tool>",
+      `    <name>${esc(t.name)}</name>`,
+      `    <description>${esc(t.description)}</description>`,
+      "  </tool>"
+    );
+  }
+  lines.push("</tools>");
+  return lines.join("\n");
+}
+
+// src/internal/tool-guidance.ts
+var DEFAULT_TOOL_GUIDANCE = {
+  not_found: "The path does not exist. Use `list_dir` or `glob_files` to find the correct path, then retry.",
+  path_traversal: "That path escapes the project root. Use a path inside the project directory.",
+  forbidden_path: "That path is a protected file (.env, .git, lock files, etc.). Choose a different, non-sensitive path.",
+  no_match: "The search text was not found verbatim. Re-read the file with `read_file` and copy the exact text (including whitespace/indentation) before editing.",
+  timeout: "The operation timed out. Narrow the scope or pass a larger `timeout_ms`.",
+  invalid_url: "The URL is malformed. Provide a full absolute http(s):// URL.",
+  ssrf_blocked: "That host is private/loopback/reserved and is blocked. Use a public URL.",
+  catastrophic_command: "That command is blocked as catastrophic. Use a safer, scoped command (e.g. a relative path instead of `/`).",
+  binary_file: "The file is binary and cannot be read as text. Use a tool suited to binary data.",
+  too_large: "The target is too large to process directly. Use a bounded range or a narrower scope."
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function injectGuidance(handlerOutput, guidance) {
+  let parsed;
+  try {
+    parsed = JSON.parse(handlerOutput);
+  } catch {
+    return handlerOutput;
+  }
+  if (!isRecord(parsed) || parsed.ok !== false) return handlerOutput;
+  if ("guidance" in parsed) return handlerOutput;
+  const code = parsed.error;
+  if (typeof code !== "string") return handlerOutput;
+  const hint = guidance[code];
+  if (!hint) return handlerOutput;
+  return JSON.stringify({ ...parsed, guidance: hint });
+}
+function withToolResultGuidance(tool, guidance) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: async (input) => injectGuidance(await tool.handler(input), guidance)
+  };
+}
+function withDefaultGuidance(tool) {
+  return withToolResultGuidance(tool, DEFAULT_TOOL_GUIDANCE);
+}
 var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
   const { projectRoot, max = DEFAULT_MAX_ENTRIES } = opts;
@@ -613,39 +1089,82 @@ var PLAN_INSTRUCTIONS = [
   "When ready, use plan_mode with action 'exit' to return to normal mode."
 ].join("\n");
 var NORMAL_INSTRUCTIONS = "Returned to NORMAL MODE. You may now execute changes.";
-function createPlanModeTool() {
+var DESCRIPTION = "Toggle between normal and plan mode. Actions: 'enter' (switch to plan mode), 'exit' (return to normal), 'status' (check current mode). Returns { ok, mode, message }.";
+function planModeSchema(withPlan) {
+  const properties = {
+    action: {
+      type: "string",
+      enum: ["enter", "exit", "status"],
+      description: "The action to perform."
+    }
+  };
+  if (withPlan) {
+    properties.plan = {
+      type: "string",
+      description: "On 'exit', the plan text to persist to the artifact store."
+    };
+  }
+  return { type: "object", properties, required: ["action"] };
+}
+function renderMode(action, mode) {
+  switch (action) {
+    case "enter":
+      return JSON.stringify({ ok: true, mode, message: PLAN_INSTRUCTIONS });
+    case "exit":
+      return JSON.stringify({ ok: true, mode, message: NORMAL_INSTRUCTIONS });
+    case "status":
+      return JSON.stringify({ ok: true, mode, message: `Current mode: ${mode}` });
+    default:
+      return void 0;
+  }
+}
+function invalidAction(action) {
+  return JSON.stringify({
+    ok: false,
+    error: "invalid_action",
+    message: `Unknown action '${action}'. Valid: enter, exit, status.`
+  });
+}
+function createPlanModeTool(options) {
   let mode = "normal";
+  if (options === void 0) {
+    return {
+      name: "plan_mode",
+      description: DESCRIPTION,
+      inputSchema: planModeSchema(false),
+      handler: (input) => {
+        if (input.action === "enter") mode = "plan";
+        else if (input.action === "exit") mode = "normal";
+        return renderMode(input.action, mode) ?? invalidAction(input.action);
+      },
+      currentMode: () => mode
+    };
+  }
+  const { artifactStore, artifactId = "plan" } = options;
   return {
     name: "plan_mode",
-    description: "Toggle between normal and plan mode. Actions: 'enter' (switch to plan mode), 'exit' (return to normal), 'status' (check current mode). Returns { ok, mode, message }.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        action: {
-          type: "string",
-          enum: ["enter", "exit", "status"],
-          description: "The action to perform."
-        }
-      },
-      required: ["action"]
-    },
-    handler: (input) => {
-      switch (input.action) {
-        case "enter":
-          mode = "plan";
-          return JSON.stringify({ ok: true, mode, message: PLAN_INSTRUCTIONS });
-        case "exit":
-          mode = "normal";
-          return JSON.stringify({ ok: true, mode, message: NORMAL_INSTRUCTIONS });
-        case "status":
-          return JSON.stringify({ ok: true, mode, message: `Current mode: ${mode}` });
-        default:
+    description: DESCRIPTION,
+    inputSchema: planModeSchema(true),
+    handler: async (input) => {
+      if (input.action === "enter") {
+        mode = "plan";
+        return JSON.stringify({ ok: true, mode, message: PLAN_INSTRUCTIONS });
+      }
+      if (input.action === "exit") {
+        mode = "normal";
+        if (typeof input.plan === "string" && input.plan.length > 0) {
+          const path = await artifactStore.write(artifactId, input.plan);
           return JSON.stringify({
-            ok: false,
-            error: "invalid_action",
-            message: `Unknown action '${input.action}'. Valid: enter, exit, status.`
+            ok: true,
+            mode,
+            message: NORMAL_INSTRUCTIONS,
+            persisted: true,
+            path
           });
+        }
+        return JSON.stringify({ ok: true, mode, message: NORMAL_INSTRUCTIONS, persisted: false });
       }
+      return renderMode(input.action, mode) ?? invalidAction(input.action);
     },
     currentMode: () => mode
   };
@@ -735,21 +1254,21 @@ async function openHandleSafe(absolutePath, path) {
   }
 }
 async function readContent(handle, path) {
-  const stat = await handle.stat();
-  if (stat.size > MAX_FILE_SIZE) {
+  const stat2 = await handle.stat();
+  if (stat2.size > MAX_FILE_SIZE) {
     return JSON.stringify({
       ok: false,
       error: "too_large",
       path,
-      size: stat.size,
+      size: stat2.size,
       limit: MAX_FILE_SIZE
     });
   }
-  if (await isBinaryProbe(handle, Number(stat.size))) {
-    return JSON.stringify({ ok: false, error: "binary_file", path, size: stat.size });
+  if (await isBinaryProbe(handle, Number(stat2.size))) {
+    return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
   }
   const content = await handle.readFile({ encoding: "utf-8" });
-  return JSON.stringify({ ok: true, content, size: stat.size });
+  return JSON.stringify({ ok: true, content, size: stat2.size });
 }
 async function isBinaryProbe(handle, size) {
   const probeLen = Math.min(BINARY_PROBE_BYTES, size);
@@ -988,7 +1507,7 @@ var DEFAULT_TIMEOUT_MS3 = 3e4;
 var MAX_TIMEOUT_MS = 3e5;
 var MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
 function createShellTool(opts) {
-  const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3 } = opts;
+  const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3, allowCatastrophic = false } = opts;
   return defineTool({
     name: "shell_exec",
     description: "Execute a shell command in the project directory. Returns stdout, stderr, and exit code. Default timeout 30s, max 5 minutes. Output capped at 5 MB. Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
@@ -997,6 +1516,13 @@ function createShellTool(opts) {
       timeout_ms: z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
     }),
     handler: async ({ command, timeout_ms }) => {
+      if (!allowCatastrophic) {
+        const reason = catastrophicShellReason(command);
+        if (reason) {
+          const err = new CatastrophicCommandError(reason);
+          return JSON.stringify({ ok: false, error: err.code, reason });
+        }
+      }
       const timeoutMs = Math.min(timeout_ms ?? defaultTimeoutMs, MAX_TIMEOUT_MS);
       const result = await runShell(projectRoot, command, timeoutMs);
       return result;
@@ -1075,6 +1601,11 @@ function formatResult(result, timeoutMs) {
   });
 }
 
+// src/todo-plan-nodes.ts
+function todoItemsToPlanNodes(items) {
+  return items.map((item) => ({ id: item.id, label: item.title, status: item.status }));
+}
+
 // src/todolist.ts
 function ok(data) {
   return JSON.stringify({ ok: true, ...data });
@@ -1095,6 +1626,9 @@ function createTodolistTool() {
   function findById(id) {
     return items.find((i) => i.id === id);
   }
+  function listResult(extra) {
+    return ok({ ...extra, items: [...items], items_summary: formatList() });
+  }
   function formatList() {
     if (items.length === 0) return "No tasks. Use action 'add' to create one.";
     const lines = items.map((item) => {
@@ -1117,7 +1651,7 @@ ${done}/${items.length} done | ${inProg} in progress | ${pending} pending`);
       createdAt: Date.now()
     };
     items.push(item);
-    return ok({ id: item.id, message: `Added: ${item.title}`, items_summary: formatList() });
+    return listResult({ id: item.id, message: `Added: ${item.title}` });
   }
   function handleSetStatus(input, status) {
     const id = requireId(input);
@@ -1127,7 +1661,7 @@ ${done}/${items.length} done | ${inProg} in progress | ${pending} pending`);
     item.status = status;
     if (status === "done") item.completedAt = Date.now();
     const verb = status === "done" ? "Completed" : "Started";
-    return ok({ message: `${verb}: ${item.title}`, items_summary: formatList() });
+    return listResult({ message: `${verb}: ${item.title}` });
   }
   function handleRemove(input) {
     const id = requireId(input);
@@ -1135,29 +1669,26 @@ ${done}/${items.length} done | ${inProg} in progress | ${pending} pending`);
     const idx = items.findIndex((i) => i.id === id);
     if (idx === -1) return fail({ error: "not_found", id });
     const removed = items.splice(idx, 1)[0];
-    return ok({ message: `Removed: ${removed.title}`, items_summary: formatList() });
+    return listResult({ message: `Removed: ${removed.title}` });
   }
   function handleClearCompleted() {
     const before = items.length;
     const kept = items.filter((i) => i.status !== "done");
     items.length = 0;
     items.push(...kept);
-    return ok({
-      message: `Cleared ${before - items.length} completed items`,
-      items_summary: formatList()
-    });
+    return listResult({ message: `Cleared ${before - items.length} completed items` });
   }
   const actions = {
     add: handleAdd,
     in_progress: (input) => handleSetStatus(input, "in_progress"),
     complete: (input) => handleSetStatus(input, "done"),
     remove: handleRemove,
-    list: () => ok({ items_summary: formatList() }),
+    list: () => listResult({}),
     clear_completed: handleClearCompleted
   };
   return {
     name: "todolist",
-    description: "Track multi-step task progress. Actions: 'add' (create task with title), 'complete' (mark done by id), 'in_progress' (mark started by id), 'remove' (delete by id), 'list' (show all), 'clear_completed' (remove done items). Returns { ok, items_summary }.",
+    description: "Track multi-step task progress. Actions: 'add' (create task with title), 'complete' (mark done by id), 'in_progress' (mark started by id), 'remove' (delete by id), 'list' (show all), 'clear_completed' (remove done items). Returns { ok, items, items_summary } (items = structured array; items_summary = formatted text).",
     inputSchema: {
       type: "object",
       properties: {
@@ -1210,6 +1741,7 @@ var DEFAULT_TIMEOUT_MS4 = 3e4;
 var MAX_BODY_BYTES = 1 * 1024 * 1024;
 function createWebFetchTool(opts) {
   const defaultTimeoutMs = opts?.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS4;
+  const allowPrivateHosts = opts?.allowPrivateHosts ?? false;
   return defineTool({
     name: "web_fetch",
     description: "Fetch content from a URL via HTTP/HTTPS. Rejects non-http(s) URLs. Response body capped at 1 MB. Returns { ok, content, status_code } or { ok: false, error }.",
@@ -1237,7 +1769,10 @@ function createWebFetchTool(opts) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeoutMs);
       try {
-        const response = await fetch(url, { signal: controller.signal });
+        const response = await screenedFetch(url, {
+          signal: controller.signal,
+          allowPrivateHosts
+        });
         clearTimeout(timer);
         const contentLength = response.headers.get("content-length");
         if (contentLength && Number(contentLength) > MAX_BODY_BYTES) {
@@ -1269,6 +1804,9 @@ function createWebFetchTool(opts) {
         });
       } catch (err) {
         clearTimeout(timer);
+        if (err instanceof SsrfBlockedError) {
+          return JSON.stringify({ ok: false, error: "ssrf_blocked", url, reason: err.message });
+        }
         const e = err;
         if (e.name === "AbortError") {
           return JSON.stringify({ ok: false, error: "timeout", url, timeout_ms: timeoutMs });
@@ -1312,6 +1850,34 @@ function createWebSearchTool(opts) {
     }
   });
 }
+var BRAVE_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+function createBraveWebSearchAdapter(opts = {}) {
+  const apiKey = opts.apiKey ?? process.env.BRAVE_API_KEY;
+  if (!apiKey) {
+    throw new ConfigurationError("BRAVE_API_KEY is not set (pass { apiKey } or set the env var).", {
+      code: "no_api_key"
+    });
+  }
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const endpoint = opts.endpoint ?? BRAVE_ENDPOINT;
+  const base = new URL(endpoint);
+  return async (query, maxResults) => {
+    const url = new URL(base);
+    url.searchParams.set("q", query);
+    url.searchParams.set("count", String(maxResults));
+    const res = await fetchImpl(url.toString(), {
+      headers: { "X-Subscription-Token": apiKey, Accept: "application/json" }
+    });
+    if (!res.ok) throw new Error(`brave_search_failed: HTTP ${res.status}`);
+    const json = await res.json();
+    const results = json?.web?.results ?? [];
+    return results.map((r) => ({
+      title: String(r?.title ?? ""),
+      url: String(r?.url ?? ""),
+      snippet: String(r?.description ?? "")
+    }));
+  };
+}
 var BINARY_PROBE_BYTES3 = 8 * 1024;
 function createWriteFileTool(opts) {
   const { projectRoot } = opts;
@@ -1354,8 +1920,8 @@ async function isBinaryFile(absolutePath) {
     return false;
   }
   try {
-    const stat = await handle.stat();
-    const probeLen = Math.min(BINARY_PROBE_BYTES3, Number(stat.size));
+    const stat2 = await handle.stat();
+    const probeLen = Math.min(BINARY_PROBE_BYTES3, Number(stat2.size));
     if (probeLen <= 0) return false;
     const probe = Buffer.alloc(probeLen);
     const { bytesRead } = await handle.read(probe, 0, probeLen, 0);
@@ -1368,6 +1934,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { createApplyPatchTool, createEditFileTool, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, formatCode, formatDiff, formatError, formatFileList, truncateOutput };
+export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withToolResultGuidance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map