indusagi-coding-agent 0.1.62 → 0.2.1

package/dist/guardrails.js

@@ -0,0 +1,2031 @@
+// src/conductor/bash-guard.ts
+var OPERATORS = ["&&", "||", ";", "|", "&", "\n"];
+function splitTopLevel(command) {
+  const slices = [];
+  let current = "";
+  let quote;
+  let i = 0;
+  const flush = () => {
+    const trimmed = current.trim();
+    if (trimmed.length > 0) slices.push(trimmed);
+    current = "";
+  };
+  while (i < command.length) {
+    const ch = command[i];
+    if (ch === "\\" && quote !== "'") {
+      current += ch;
+      if (i + 1 < command.length) {
+        current += command[i + 1];
+        i += 2;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+    if (quote !== void 0) {
+      current += ch;
+      if (ch === quote) quote = void 0;
+      i += 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      current += ch;
+      i += 1;
+      continue;
+    }
+    let matched;
+    for (const op of OPERATORS) {
+      if (command.startsWith(op, i)) {
+        matched = op;
+        break;
+      }
+    }
+    if (matched !== void 0) {
+      flush();
+      i += matched.length;
+      continue;
+    }
+    current += ch;
+    i += 1;
+  }
+  flush();
+  return slices;
+}
+function extractSubshells(slice) {
+  const inner = [];
+  let outer = "";
+  let quote;
+  let i = 0;
+  while (i < slice.length) {
+    const ch = slice[i];
+    if (ch === "\\" && quote !== "'") {
+      outer += ch;
+      if (i + 1 < slice.length) {
+        outer += slice[i + 1];
+        i += 2;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+    if (quote !== void 0) {
+      if (quote === '"' && ch === "`") {
+        const close = findBacktickClose(slice, i + 1);
+        inner.push(slice.slice(i + 1, close));
+        i = close + 1;
+        continue;
+      }
+      outer += ch;
+      if (ch === quote) quote = void 0;
+      i += 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      outer += ch;
+      i += 1;
+      continue;
+    }
+    if (ch === "(" || ch === "$" && slice[i + 1] === "(") {
+      const start = ch === "$" ? i + 2 : i + 1;
+      const close = findParenClose(slice, start);
+      inner.push(slice.slice(start, close));
+      i = close + 1;
+      continue;
+    }
+    if (ch === "`") {
+      const close = findBacktickClose(slice, i + 1);
+      inner.push(slice.slice(i + 1, close));
+      i = close + 1;
+      continue;
+    }
+    outer += ch;
+    i += 1;
+  }
+  return { outer: outer.trim(), inner };
+}
+function findParenClose(s, start) {
+  let depth = 1;
+  let quote;
+  let i = start;
+  while (i < s.length) {
+    const ch = s[i];
+    if (ch === "\\" && quote !== "'") {
+      i += 2;
+      continue;
+    }
+    if (quote !== void 0) {
+      if (ch === quote) quote = void 0;
+      i += 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      i += 1;
+      continue;
+    }
+    if (ch === "(" || ch === "$" && s[i + 1] === "(") depth += 1;
+    else if (ch === ")") {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+    i += 1;
+  }
+  return s.length;
+}
+function findBacktickClose(s, start) {
+  let i = start;
+  while (i < s.length) {
+    if (s[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (s[i] === "`") return i;
+    i += 1;
+  }
+  return s.length;
+}
+function tokenizeArgv(slice) {
+  const tokens = [];
+  let current = "";
+  let started = false;
+  let quote;
+  let i = 0;
+  const flush = () => {
+    if (started) tokens.push(current);
+    current = "";
+    started = false;
+  };
+  while (i < slice.length) {
+    const ch = slice[i];
+    if (ch === "\\" && quote !== "'") {
+      if (i + 1 < slice.length) {
+        current += slice[i + 1];
+        started = true;
+        i += 2;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+    if (quote !== void 0) {
+      if (ch === quote) {
+        quote = void 0;
+      } else {
+        current += ch;
+      }
+      started = true;
+      i += 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+      i += 1;
+      continue;
+    }
+    if (ch === " " || ch === "	") {
+      flush();
+      i += 1;
+      continue;
+    }
+    current += ch;
+    started = true;
+    i += 1;
+  }
+  flush();
+  return tokens;
+}
+var WRAPPERS = /* @__PURE__ */ new Set([
+  "env",
+  "nice",
+  "nohup",
+  "timeout",
+  "xargs",
+  "command",
+  "builtin",
+  "time",
+  "stdbuf",
+  "setsid",
+  "ionice"
+]);
+var ELEVATION = /* @__PURE__ */ new Set(["sudo", "doas"]);
+function stripWrappers(argv) {
+  const rest = [...argv];
+  let elevated = false;
+  for (; ; ) {
+    const head = rest[0];
+    if (head === void 0) break;
+    const token = head.toLowerCase();
+    if (ELEVATION.has(token)) {
+      rest.shift();
+      elevated = true;
+      consumeWrapperOptions(rest, token);
+      continue;
+    }
+    if (WRAPPERS.has(token)) {
+      rest.shift();
+      consumeWrapperOptions(rest, token);
+      continue;
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(head)) {
+      rest.shift();
+      continue;
+    }
+    break;
+  }
+  return { rest, elevated };
+}
+function consumeWrapperOptions(rest, wrapper) {
+  for (; ; ) {
+    const head = rest[0];
+    if (head === void 0) return;
+    if (head === "--") {
+      rest.shift();
+      return;
+    }
+    if (head.startsWith("-")) {
+      rest.shift();
+      if (!head.includes("=") && FLAG_TAKES_VALUE.has(head)) {
+        const value = rest[0];
+        if (value !== void 0 && !value.startsWith("-")) rest.shift();
+      }
+      continue;
+    }
+    if ((wrapper === "timeout" || wrapper === "nice") && /^\d+[a-z]?$/i.test(head)) {
+      rest.shift();
+      continue;
+    }
+    return;
+  }
+}
+var FLAG_TAKES_VALUE = /* @__PURE__ */ new Set(["-n", "-u", "-g", "-s", "--kill-after", "--signal", "--user"]);
+function parseBashCommand(command) {
+  if (typeof command !== "string" || command.trim().length === 0) return [];
+  const out = [];
+  parseInto(command, out);
+  return out;
+}
+function parseInto(command, out) {
+  for (const slice of splitTopLevel(command)) {
+    const { outer, inner } = extractSubshells(slice);
+    if (outer.length > 0) {
+      const argv = tokenizeArgv(outer);
+      if (argv.length > 0) {
+        const { rest, elevated } = stripWrappers(argv);
+        const name = rest[0];
+        if (name !== void 0 && name.length > 0) {
+          out.push({
+            name: name.toLowerCase(),
+            args: rest.slice(1),
+            elevated,
+            raw: slice.trim()
+          });
+        }
+      }
+    }
+    for (const body of inner) {
+      if (body.trim().length > 0) parseInto(body, out);
+    }
+  }
+}
+function catastrophicMessage(reason) {
+  return `This command is blocked: ${reason}. It is on the built-in catastrophic-command blocklist and cannot be run regardless of permission rules.`;
+}
+function normPath(token) {
+  const collapsed = token.replace(/\/+/g, "/");
+  if (collapsed.length > 1 && collapsed.endsWith("/")) return collapsed.slice(0, -1);
+  return collapsed;
+}
+var ROOT_TARGETS = /* @__PURE__ */ new Set([
+  "/",
+  "/*",
+  "~",
+  "~/",
+  "$home",
+  "$home/",
+  "/bin",
+  "/boot",
+  "/dev",
+  "/etc",
+  "/home",
+  "/lib",
+  "/opt",
+  "/proc",
+  "/root",
+  "/sbin",
+  "/srv",
+  "/sys",
+  "/usr",
+  "/var"
+]);
+function isRootRm(cmd) {
+  if (cmd.name !== "rm") return false;
+  let recursive = false;
+  const targets = [];
+  for (const arg of cmd.args) {
+    if (arg.startsWith("--")) {
+      if (arg === "--recursive") recursive = true;
+      continue;
+    }
+    if (arg.startsWith("-") && arg.length > 1) {
+      if (arg.includes("r") || arg.includes("R")) recursive = true;
+      continue;
+    }
+    targets.push(normPath(arg.toLowerCase()));
+  }
+  if (!recursive) return false;
+  return targets.some((t) => ROOT_TARGETS.has(t) || t === "/.." || /^\/[a-z]+\/\*$/.test(t));
+}
+var FORK_BOMB = /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/;
+var CATASTROPHIC_RULES = [
+  {
+    reason: "recursive force-delete of a root or system directory (rm -rf /)",
+    test: isRootRm
+  },
+  {
+    reason: "piping a downloaded remote script straight into a shell (curl | sh)",
+    test: isRemoteScriptPipedToShell
+  },
+  {
+    reason: "writing raw bytes to a block device (dd of=/dev/\u2026)",
+    test: (cmd) => cmd.name === "dd" && cmd.args.some((a) => /^of=\/dev\/(sd|nvme|disk|hd|mmcblk|vd)/i.test(a))
+  },
+  {
+    reason: "formatting a filesystem (mkfs)",
+    test: (cmd) => /^mkfs(\.|$)/.test(cmd.name)
+  },
+  {
+    reason: "redirecting output over a raw disk device (> /dev/sd\u2026)",
+    test: (cmd) => /[>]\s*\/dev\/(sd|nvme|disk|hd|mmcblk|vd)/i.test(cmd.raw)
+  },
+  {
+    reason: "world-writable recursive chmod of a root or system directory (chmod -R 777 /)",
+    test: isRootChmod
+  }
+];
+var SHELL_SINKS = /* @__PURE__ */ new Set(["sh", "bash", "zsh", "dash", "ksh", "fish", "csh", "tcsh"]);
+var FETCHERS = /* @__PURE__ */ new Set(["curl", "wget", "fetch"]);
+function isRemoteScriptPipedToShell(cmd) {
+  if (!SHELL_SINKS.has(cmd.name)) return false;
+  return /\b(curl|wget|fetch)\b/i.test(cmd.raw) && /https?:\/\//i.test(cmd.raw);
+}
+function isRootChmod(cmd) {
+  if (cmd.name !== "chmod") return false;
+  let recursive = false;
+  let world = false;
+  const targets = [];
+  for (const arg of cmd.args) {
+    if (arg === "-R" || arg === "--recursive" || /^-[a-z]*R/i.test(arg)) recursive = true;
+    else if (/^[0-7]?777$/.test(arg) || arg.includes("o+w") || arg.includes("a+w")) world = true;
+    else if (!arg.startsWith("-")) targets.push(normPath(arg.toLowerCase()));
+  }
+  return recursive && world && targets.some((t) => ROOT_TARGETS.has(t));
+}
+function scanForRemotePipeToShell(cmds) {
+  const hasRemoteFetch = cmds.some(
+    (c) => FETCHERS.has(c.name) && c.args.some((a) => /^https?:\/\//i.test(a))
+  );
+  if (!hasRemoteFetch) return void 0;
+  const hasShellSink = cmds.some(
+    (c) => SHELL_SINKS.has(c.name) && !c.args.some((a) => !a.startsWith("-") && /\.(sh|bash)$/i.test(a))
+  );
+  if (hasShellSink) {
+    return "piping a downloaded remote script straight into a shell (curl | sh)";
+  }
+  return void 0;
+}
+function catastrophicReason(cmd) {
+  for (const rule of CATASTROPHIC_RULES) {
+    if (rule.test(cmd)) return rule.reason;
+  }
+  return void 0;
+}
+function evaluateCatastrophic(command) {
+  if (FORK_BOMB.test(command)) {
+    return catastrophicMessage("fork bomb");
+  }
+  const cmds = parseBashCommand(command);
+  if (cmds.length === 0) return void 0;
+  for (const cmd of cmds) {
+    const reason = catastrophicReason(cmd);
+    if (reason !== void 0) return catastrophicMessage(reason);
+  }
+  const piped = scanForRemotePipeToShell(cmds);
+  if (piped !== void 0) return catastrophicMessage(piped);
+  return void 0;
+}
+function bashSubcommandSubjects(command) {
+  const cmds = parseBashCommand(command);
+  if (cmds.length === 0) return [command];
+  return cmds.map((c) => [c.name, ...c.args].join(" ").trim());
+}
+
+// src/conductor/permissions.ts
+var READ_ONLY_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "read",
+  "ls",
+  "grep",
+  "find",
+  "glob",
+  "websearch",
+  "webfetch",
+  "todoread"
+]);
+var EDIT_TOOL_NAMES = /* @__PURE__ */ new Set(["edit", "write", "multiedit"]);
+function canon(toolName) {
+  return toolName.toLowerCase();
+}
+function isReadOnlyToolName(toolName, extra) {
+  const name = canon(toolName);
+  if (READ_ONLY_TOOL_NAMES.has(name)) return true;
+  if (extra) {
+    for (const candidate of extra) {
+      if (canon(candidate) === name) return true;
+    }
+  }
+  return false;
+}
+function isEditToolName(toolName) {
+  return EDIT_TOOL_NAMES.has(canon(toolName));
+}
+function normalizeMode(mode) {
+  return mode === "bypassPermissions" ? "bypass" : mode;
+}
+function parseRule(raw) {
+  const trimmed = raw.trim();
+  const open = trimmed.indexOf("(");
+  if (open === -1 || !trimmed.endsWith(")")) {
+    return { toolName: trimmed };
+  }
+  const toolName = trimmed.slice(0, open).trim();
+  const ruleContent = trimmed.slice(open + 1, trimmed.length - 1).trim();
+  return ruleContent.length > 0 ? { toolName, ruleContent } : { toolName };
+}
+function makeRule(ruleBehavior, raw) {
+  return { ruleBehavior, ruleValue: parseRule(raw) };
+}
+function ruleSubject(toolName, input) {
+  if (input === null || typeof input !== "object") {
+    return typeof input === "string" ? input : "";
+  }
+  const bag = input;
+  const name = canon(toolName);
+  if ((name === "bash" || name === "shell") && typeof bag.command === "string") {
+    return bag.command;
+  }
+  if (typeof bag.command === "string") return bag.command;
+  try {
+    return JSON.stringify(bag);
+  } catch {
+    return "";
+  }
+}
+function specifierMatches(specifier, subject) {
+  if (specifier.endsWith(":*")) {
+    return subject.startsWith(specifier.slice(0, -2));
+  }
+  if (specifier.endsWith("*") && !specifier.slice(0, -1).includes("*")) {
+    return subject.startsWith(specifier.slice(0, -1));
+  }
+  if (specifier.includes("*")) {
+    const escaped = specifier.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`).test(subject);
+  }
+  return specifier === subject;
+}
+function isBashTool(toolName) {
+  const name = canon(toolName);
+  return name === "bash" || name === "shell";
+}
+function bashSubjects(toolName, input) {
+  const command = ruleSubject(toolName, input);
+  if (command.length === 0) return [];
+  return bashSubcommandSubjects(command);
+}
+function toolMatchesRule(toolName, input, rule) {
+  const ruleName = canon(rule.ruleValue.toolName);
+  const callName = canon(toolName);
+  const nameMatches = ruleName === callName || ruleName.startsWith("mcp__") && callName.startsWith(`${ruleName}__`);
+  if (!nameMatches) return false;
+  const specifier = rule.ruleValue.ruleContent;
+  if (specifier === void 0) return true;
+  if (isBashTool(toolName)) {
+    const subjects = bashSubjects(toolName, input);
+    if (subjects.length === 0) return specifierMatches(specifier, ruleSubject(toolName, input));
+    return subjects.some((subject) => specifierMatches(specifier, subject));
+  }
+  return specifierMatches(specifier, ruleSubject(toolName, input));
+}
+function bashAllowSetCoversAll(toolName, input, allowRules) {
+  const callName = canon(toolName);
+  const subjects = bashSubjects(toolName, input);
+  if (subjects.length === 0) return false;
+  return subjects.every(
+    (subject) => allowRules.some((rule) => {
+      if (canon(rule.ruleValue.toolName) !== callName) return false;
+      const specifier = rule.ruleValue.ruleContent;
+      if (specifier === void 0) return true;
+      return specifierMatches(specifier, subject);
+    })
+  );
+}
+function resolveRuleDecision(toolName, input, rules, mode, readOnlyExtra) {
+  const m = normalizeMode(mode);
+  if (isBashTool(toolName)) {
+    const command = ruleSubject(toolName, input);
+    if (command.length > 0 && evaluateCatastrophic(command) !== void 0) {
+      return "deny";
+    }
+  }
+  for (const rule of rules) {
+    if (rule.ruleBehavior === "deny" && toolMatchesRule(toolName, input, rule)) {
+      return "deny";
+    }
+  }
+  const readOnly = isReadOnlyToolName(toolName, readOnlyExtra);
+  if (m === "plan" && !readOnly) {
+    return "deny";
+  }
+  for (const rule of rules) {
+    if (rule.ruleBehavior === "ask" && toolMatchesRule(toolName, input, rule)) {
+      return "ask";
+    }
+  }
+  if (m === "bypass") {
+    return "allow";
+  }
+  if (readOnly) {
+    return "allow";
+  }
+  if (m === "acceptEdits" && isEditToolName(toolName)) {
+    return "allow";
+  }
+  if (isBashTool(toolName)) {
+    const allowRules = rules.filter((r) => r.ruleBehavior === "allow");
+    if (allowRules.length > 0 && bashAllowSetCoversAll(toolName, input, allowRules)) {
+      return "allow";
+    }
+  } else {
+    for (const rule of rules) {
+      if (rule.ruleBehavior === "allow" && toolMatchesRule(toolName, input, rule)) {
+        return "allow";
+      }
+    }
+  }
+  return "ask";
+}
+function noResolverMessage(toolName) {
+  return `Tool "${toolName}" requires approval, but this session is non-interactive (no approval prompt is available). Denying. Add an allow rule under permissions.allow in settings, or run with --permission-mode acceptEdits/bypass, to permit it.`;
+}
+function declinedMessage(toolName) {
+  return `Tool "${toolName}" was denied by the user.`;
+}
+function blockedMessage(toolName) {
+  return `Tool "${toolName}" is blocked by the active permission policy.`;
+}
+function createPermissionGate(config) {
+  return async (toolName, input, opts) => {
+    if (isBashTool(toolName)) {
+      const command = ruleSubject(toolName, input);
+      if (command.length > 0) {
+        const reason = evaluateCatastrophic(command);
+        if (reason !== void 0) {
+          return { behavior: "deny", message: reason };
+        }
+      }
+    }
+    const behavior = resolveRuleDecision(
+      toolName,
+      input,
+      config.rules,
+      config.mode(),
+      config.readOnlyToolNames
+    );
+    if (behavior === "allow") {
+      return { behavior: "allow" };
+    }
+    if (behavior === "deny") {
+      return { behavior: "deny", message: blockedMessage(toolName) };
+    }
+    const resolver = config.requestApproval;
+    if (resolver === void 0) {
+      return { behavior: "deny", message: noResolverMessage(toolName) };
+    }
+    let choice;
+    try {
+      choice = await resolver(toolName, input, opts);
+    } catch {
+      choice = "deny";
+    }
+    if (choice === "deny") {
+      return { behavior: "deny", message: declinedMessage(toolName) };
+    }
+    if (choice === "allow-always" && config.appendAllowRule) {
+      config.appendAllowRule(makeRule("allow", toolName));
+    }
+    return { behavior: "allow" };
+  };
+}
+
+// src/briefing/compose.ts
+function joinBlocks(parts) {
+  return parts.filter((p) => p.trim().length > 0).join("\n\n");
+}
+function bullets(lines) {
+  return lines.map((l) => `- ${l}`).join("\n");
+}
+function escapeXml(value) {
+  let out = "";
+  for (const ch of value) {
+    switch (ch) {
+      case "&":
+        out += "&amp;";
+        break;
+      case "<":
+        out += "&lt;";
+        break;
+      case ">":
+        out += "&gt;";
+        break;
+      case '"':
+        out += "&quot;";
+        break;
+      case "'":
+        out += "&#39;";
+        break;
+      default:
+        out += ch;
+    }
+  }
+  return out;
+}
+function hasTool(ctx, id) {
+  return (ctx.tools ?? []).some((t) => t.name === id);
+}
+function hasToolPrefix(ctx, prefix) {
+  return (ctx.tools ?? []).some((t) => t.name.startsWith(prefix));
+}
+var TOOL_SUMMARIES = {
+  read: "Open a file's contents for inspection.",
+  write: "Create a new file or overwrite an existing one wholesale.",
+  edit: "Apply a precise in-place change by matching exact existing text.",
+  bash: "Run a shell command in the workspace.",
+  grep: "Search file contents by pattern across the tree.",
+  find: "Locate files and directories by name or glob.",
+  ls: "List the entries of a directory.",
+  task: "Hand a self-contained sub-task to a delegate agent.",
+  todoread: "Read back the current task checklist.",
+  todowrite: "Record or revise the task checklist.",
+  webfetch: "Retrieve and read the contents of a URL.",
+  websearch: "Query the web for current information."
+};
+function describeTool(tool) {
+  const summary = TOOL_SUMMARIES[tool.name] ?? tool.description?.trim() ?? "";
+  return summary.length > 0 ? `\`${tool.name}\` \u2014 ${summary}` : `\`${tool.name}\``;
+}
+var ROLE_SECTION = {
+  id: "role",
+  render() {
+    return joinBlocks([
+      "You are a terminal-based software engineering assistant. You operate inside a real workspace and make progress by reading code, running commands, and editing files directly \u2014 not by describing what someone else should do.",
+      "Work toward the user's actual goal. Take the initiative to gather the context you need, but stay within the scope of what was asked: do not redesign, rename, or refactor beyond the request unless the user invites it."
+    ]);
+  }
+};
+var TOOLS_SECTION = {
+  id: "tools",
+  title: "Tools",
+  applies(ctx) {
+    return (ctx.tools ?? []).length > 0;
+  },
+  render(ctx) {
+    const lines = (ctx.tools ?? []).map(describeTool);
+    return joinBlocks([
+      "# Tools",
+      "These capabilities are available to you this turn. Reach for the most specific one for the job.",
+      bullets(lines)
+    ]);
+  }
+};
+var GUIDELINES_SECTION = {
+  id: "guidelines",
+  title: "Working guidance",
+  render(ctx) {
+    const items = [];
+    if (hasTool(ctx, "read")) {
+      items.push(
+        "Always inspect a file with the reader before you change it. Do not shell out to `cat`, `head`, or `sed` to view a file when the reader is available."
+      );
+    }
+    if (hasTool(ctx, "edit")) {
+      items.push(
+        "For a targeted change, prefer the editor: it replaces an exact span of existing text, so the old text you supply must match the file byte-for-byte."
+      );
+    }
+    if (hasTool(ctx, "write")) {
+      items.push(
+        "Reserve the writer for creating a new file or replacing one in full; for anything smaller, edit in place rather than rewriting the whole file."
+      );
+    }
+    if (hasTool(ctx, "grep") || hasTool(ctx, "find") || hasTool(ctx, "ls")) {
+      items.push(
+        "Explore the tree with the dedicated search and listing tools rather than shell equivalents \u2014 they are quicker and already skip ignored paths."
+      );
+    }
+    if (hasTool(ctx, "bash")) {
+      items.push(
+        "Use the shell for builds, tests, and other commands that no purpose-built tool covers. Keep commands scoped and avoid destructive operations unless the user asked for them."
+      );
+    }
+    items.push(
+      "Keep your replies short and to the point. Lead with the result; add only the explanation the user needs to act on it."
+    );
+    items.push(
+      "When a change is non-trivial, verify it \u2014 run the build or the relevant tests \u2014 before you report it as done."
+    );
+    return joinBlocks(["# Working guidance", bullets(items)]);
+  }
+};
+var TASK_SECTION = {
+  id: "tasks",
+  title: "Task tracking",
+  applies(ctx) {
+    return hasTool(ctx, "todowrite") || hasTool(ctx, "todoread");
+  },
+  render() {
+    return joinBlocks([
+      "# Task tracking",
+      "For work that spans several steps, maintain a checklist with the task tools. Break the job into concrete items, mark exactly one in progress at a time, and tick items off as you finish them so the user can follow along."
+    ]);
+  }
+};
+var SUBAGENTS_SECTION = {
+  id: "subagents",
+  title: "Delegates",
+  applies(ctx) {
+    return (ctx.subagents ?? []).length > 0;
+  },
+  render(ctx) {
+    const lines = (ctx.subagents ?? []).map((s) => {
+      const when = s.when ? ` Use it when ${s.when}` : "";
+      return `**${s.name}** \u2014 ${s.purpose}.${when}`;
+    });
+    return joinBlocks([
+      "# Delegates",
+      "You can offload a focused, self-contained piece of work to one of these delegates with the task tool. Hand off when a sub-problem is well-scoped enough to be solved without your full conversation context.",
+      bullets(lines)
+    ]);
+  }
+};
+var PLAN_SECTION = {
+  id: "plan-mode",
+  title: "Plan mode",
+  applies(ctx) {
+    return hasTool(ctx, "enter_plan_mode") || hasTool(ctx, "exit_plan_mode");
+  },
+  render() {
+    return joinBlocks([
+      "# Plan mode",
+      bullets([
+        "For a task that needs investigation before any change, call `enter_plan_mode` first. That switches you into a read-only research phase: you may read, search, and inspect, but every file-mutating and shell tool is blocked until you leave.",
+        "While in plan mode, gather all the context you need and draft a concrete plan. Do not try to edit files or run commands \u2014 those calls are rejected with a steering message.",
+        "When the plan is ready, call `exit_plan_mode` with the full plan text. The user reviews it and either approves (you leave plan mode and carry the plan out) or rejects (you stay in plan mode to revise and re-propose). Use it to ask permission to start, not to do the work."
+      ])
+    ]);
+  }
+};
+var CONNECTORS_SECTION = {
+  id: "connectors",
+  title: "Connectors",
+  applies(ctx) {
+    return hasToolPrefix(ctx, "connector_") || hasToolPrefix(ctx, "saas_");
+  },
+  render() {
+    return joinBlocks([
+      "# Connectors",
+      bullets([
+        "When a task needs an external service (issue trackers, calendars, docs, and the like), prefer the connector tools over scraping or guessing.",
+        "Confirm the connection is authorized before you rely on it, and surface a clear next step if it is not.",
+        "Page through large result sets deliberately rather than assuming the first response is complete."
+      ])
+    ]);
+  }
+};
+var PROJECT_CONTEXT_SECTION = {
+  id: "project-context",
+  title: "Project context",
+  applies(ctx) {
+    return (ctx.contextDocs ?? []).length > 0;
+  },
+  render(ctx) {
+    const docs = (ctx.contextDocs ?? []).map(
+      (d) => `## ${d.path}
+
+${d.body.trim()}`
+    );
+    return joinBlocks([
+      "# Project context",
+      "The following project documents describe conventions for this repository. Treat them as standing instructions.",
+      ...docs
+    ]);
+  }
+};
+var SKILLS_SECTION = {
+  id: "skills",
+  title: "Skills",
+  applies(ctx) {
+    return (ctx.skills ?? []).length > 0;
+  },
+  render(ctx) {
+    const skills = ctx.skills ?? [];
+    const entries = skills.map((card) => {
+      return [
+        "  <skill>",
+        `    <name>${escapeXml(card.name)}</name>`,
+        `    <description>${escapeXml(card.description)}</description>`,
+        `    <location>${escapeXml(card.location)}</location>`,
+        "  </skill>"
+      ].join("\n");
+    });
+    return joinBlocks([
+      "# Skills",
+      "Each skill below is a set of task-specific instructions stored on disk. When a task lines up with a skill's description, load its file with the reader and follow it. Paths a skill mentions are relative to that skill's own directory.",
+      `<available_skills>
+${entries.join("\n")}
+</available_skills>`
+    ]);
+  }
+};
+var FOOTER_SECTION = {
+  id: "footer",
+  render(ctx) {
+    const where = ctx.cwd ?? ctx.workspace;
+    const when = (ctx.now ?? /* @__PURE__ */ new Date()).toISOString();
+    const lines = [];
+    if (where) lines.push(`Working directory: ${where}`);
+    lines.push(`Current time: ${when}`);
+    return lines.join("\n");
+  }
+};
+var BRIEFING_SECTIONS = [
+  ROLE_SECTION,
+  TOOLS_SECTION,
+  GUIDELINES_SECTION,
+  TASK_SECTION,
+  SUBAGENTS_SECTION,
+  PLAN_SECTION,
+  CONNECTORS_SECTION,
+  PROJECT_CONTEXT_SECTION,
+  SKILLS_SECTION,
+  FOOTER_SECTION
+];
+function composeBriefing(input) {
+  const inputs = isInputs(input) ? input : { sections: BRIEFING_SECTIONS, context: input };
+  const { sections, context, prelude, append } = inputs;
+  const rendered = [];
+  if (prelude && prelude.trim().length > 0) rendered.push(prelude.trim());
+  for (const section of sections) {
+    if (section.applies && !section.applies(context)) continue;
+    const fragment = section.render(context);
+    if (fragment.trim().length > 0) rendered.push(fragment.trim());
+  }
+  if (append && append.trim().length > 0) rendered.push(append.trim());
+  return joinBlocks(rendered);
+}
+function isInputs(value) {
+  return "sections" in value && "context" in value;
+}
+
+// src/briefing/context-docs.ts
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, parse, resolve } from "node:path";
+var DEFAULT_MAX_IMPORT_DEPTH = 5;
+var DEFAULT_MAX_BYTES_PER_DOC = 4e4;
+var CANDIDATE_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  "INDUSAGI.md",
+  "CLAUDE.local.md",
+  "AGENTS.local.md",
+  join(".indusagi", "CLAUDE.md"),
+  join(".claude", "CLAUDE.md")
+];
+var TEXT_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".md",
+  ".markdown",
+  ".txt",
+  ".text",
+  ".json",
+  ".jsonc",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".xml",
+  ".csv",
+  ".html",
+  ".htm",
+  ".css",
+  ".js",
+  ".ts",
+  ".tsx",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".mts",
+  ".cts",
+  ".py",
+  ".rb",
+  ".go",
+  ".rs",
+  ".sh",
+  ".env"
+]);
+var IMPORT_REGEX = /(?:^|\s)@((?:[^\s\\]|\\ )+)/g;
+function shortenPath(path, cwd, home) {
+  if (cwd.length > 0 && path.startsWith(cwd)) {
+    const rest = path.slice(cwd.length).replace(/^[/\\]+/, "");
+    return rest.length > 0 ? `./${rest}` : ".";
+  }
+  if (home.length > 0 && path.startsWith(home)) {
+    return `~${path.slice(home.length)}`;
+  }
+  return path;
+}
+function dirChain(cwd) {
+  const chain = [];
+  let current = cwd;
+  for (let i = 0; i < 256; i += 1) {
+    chain.push(current);
+    const parent = dirname(current);
+    if (parent === current || current === parse(current).root) break;
+    current = parent;
+  }
+  return chain.reverse();
+}
+function safeRealpath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+function isTextFile(path) {
+  const ext = extname(path).toLowerCase();
+  return ext.length === 0 || TEXT_FILE_EXTENSIONS.has(ext);
+}
+function readFileBody(absPath) {
+  if (!existsSync(absPath)) return null;
+  let raw;
+  try {
+    raw = readFileSync(absPath, "utf8");
+  } catch {
+    return null;
+  }
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function extractImports(body, baseDir, home) {
+  const out = [];
+  IMPORT_REGEX.lastIndex = 0;
+  let match;
+  while ((match = IMPORT_REGEX.exec(body)) !== null) {
+    let spec = match[1];
+    if (spec === void 0 || spec.length === 0) continue;
+    const hash = spec.indexOf("#");
+    if (hash >= 0) spec = spec.slice(0, hash);
+    spec = spec.replace(/\\ /g, " ").trim();
+    if (spec.length === 0) continue;
+    let abs;
+    if (spec.startsWith("~/")) {
+      abs = join(home, spec.slice(2));
+    } else if (isAbsolute(spec)) {
+      abs = spec;
+    } else {
+      abs = resolve(baseDir, spec);
+    }
+    if (!isTextFile(abs)) continue;
+    out.push(abs);
+  }
+  return out;
+}
+function loadDocTree(absPath, cwd, home, seen, depth, maxDepth, maxBytes, out) {
+  const real = safeRealpath(absPath);
+  if (seen.has(real)) return;
+  seen.add(real);
+  const body = readFileBody(absPath);
+  if (body === null) return;
+  const clipped = body.length > maxBytes ? body.slice(0, maxBytes) : body;
+  out.push({ path: shortenPath(absPath, cwd, home), body: clipped });
+  if (depth >= maxDepth) return;
+  const baseDir = dirname(absPath);
+  for (const child of extractImports(body, baseDir, home)) {
+    loadDocTree(child, cwd, home, seen, depth + 1, maxDepth, maxBytes, out);
+  }
+}
+function gatherContextDocs(cwd, home, opts) {
+  const out = [];
+  try {
+    const maxDepth = opts?.maxImportDepth ?? DEFAULT_MAX_IMPORT_DEPTH;
+    const maxBytes = opts?.maxBytesPerDoc ?? DEFAULT_MAX_BYTES_PER_DOC;
+    const seen = /* @__PURE__ */ new Set();
+    const roots = [...dirChain(cwd)];
+    if (home.length > 0) roots.push(home);
+    for (const dir of roots) {
+      if (dir.length === 0) continue;
+      for (const name of CANDIDATE_FILES) {
+        const candidate = join(dir, name);
+        loadDocTree(candidate, cwd, home, seen, 0, maxDepth, maxBytes, out);
+      }
+    }
+  } catch {
+    return out;
+  }
+  return out;
+}
+
+// src/capability-deck/contract.ts
+function capabilityId(raw) {
+  return raw;
+}
+function deckFault(kind, message, cause) {
+  return cause === void 0 ? { kind, message } : { kind, message, cause };
+}
+
+// src/capability-deck/builtin-bridge.ts
+import {
+  createReadTool,
+  createWriteTool,
+  createEditTool,
+  createLsTool,
+  createGrepTool,
+  createFindTool,
+  createBashTool,
+  createProcessTool,
+  createWebSearchTool,
+  createWebFetchTool,
+  todoReadTool,
+  todoWriteTool
+} from "indusagi/agent";
+var READ_ONLY = ["authoring", "survey"];
+var MUTATING = ["authoring"];
+var BUILTIN_DESCRIPTORS = [
+  {
+    id: capabilityId("read"),
+    title: "Read file",
+    summary: "Return the contents of a file at a path, optionally from an offset and capped to a line limit; renders images inline where supported.",
+    profiles: READ_ONLY,
+    build: (ctx) => createReadTool(ctx.cwd, {
+      readState: ctx.framework?.["readState"]
+    })
+  },
+  {
+    id: capabilityId("ls"),
+    title: "List directory",
+    summary: "Enumerate the entries of a directory, with an optional cap on how many are returned.",
+    profiles: READ_ONLY,
+    build: (ctx) => createLsTool(ctx.cwd)
+  },
+  {
+    id: capabilityId("grep"),
+    title: "Search file contents",
+    summary: "Scan files for lines matching a pattern, with optional case-insensitivity, literal matching, surrounding context, and a result cap.",
+    profiles: READ_ONLY,
+    build: (ctx) => createGrepTool(ctx.cwd)
+  },
+  {
+    id: capabilityId("find"),
+    title: "Find files by name",
+    summary: "Locate files and directories whose names match a glob-style pattern beneath a root, capped to a result limit.",
+    profiles: READ_ONLY,
+    build: (ctx) => createFindTool(ctx.cwd)
+  },
+  {
+    id: capabilityId("websearch"),
+    title: "Web search",
+    summary: "Query the live web for a string and return a ranked set of result snippets, capped to a requested count.",
+    profiles: READ_ONLY,
+    build: () => createWebSearchTool()
+  },
+  {
+    id: capabilityId("webfetch"),
+    title: "Fetch URL",
+    summary: "Retrieve a single URL and return its body as text, Markdown, or HTML, with an optional request timeout.",
+    profiles: READ_ONLY,
+    build: () => createWebFetchTool()
+  },
+  {
+    id: capabilityId("todoread"),
+    title: "Read checklist",
+    summary: "Read back the session's running task checklist so the agent can review what is pending, active, or done.",
+    profiles: READ_ONLY,
+    // The framework's default in-memory checklist singleton; a session-aware
+    // persistent store is wired by the separate checklist provisioner, not here.
+    build: () => todoReadTool
+  },
+  {
+    id: capabilityId("write"),
+    title: "Write file",
+    summary: "Create or overwrite a file at a path with the given contents, making parent directories as needed.",
+    profiles: MUTATING,
+    build: (ctx) => createWriteTool(ctx.cwd, {
+      readState: ctx.framework?.["readState"],
+      checkpoint: ctx.framework?.["checkpoint"]
+    })
+  },
+  {
+    id: capabilityId("edit"),
+    title: "Edit file",
+    summary: "Apply a find-and-replace edit to a file, swapping an exact span of old text for new text and reporting the resulting diff.",
+    profiles: MUTATING,
+    build: (ctx) => createEditTool(ctx.cwd, {
+      readState: ctx.framework?.["readState"],
+      checkpoint: ctx.framework?.["checkpoint"]
+    })
+  },
+  {
+    id: capabilityId("bash"),
+    title: "Run shell command",
+    summary: "Execute a shell command in the working directory, streaming its output and honoring an optional timeout.",
+    profiles: MUTATING,
+    build: (ctx) => createBashTool(ctx.cwd)
+  },
+  {
+    id: capabilityId("process"),
+    title: "Manage background processes",
+    summary: "Start, list, inspect, feed input to, and stop long-running background commands without blocking the agent on them.",
+    profiles: MUTATING,
+    build: (ctx) => createProcessTool({ cwd: ctx.cwd })
+  },
+  {
+    id: capabilityId("todowrite"),
+    title: "Update checklist",
+    summary: "Replace or amend the session's task checklist, setting each item's text, status, and priority.",
+    profiles: MUTATING,
+    // Paired with the read singleton above; both share the framework default
+    // in-memory store. The checklist provisioner swaps in a persistent store.
+    build: () => todoWriteTool
+  }
+];
+var BUILTIN_BRIDGE = Object.freeze(
+  Object.fromEntries(BUILTIN_DESCRIPTORS.map((d) => [d.id, d]))
+);
+var BUILTIN_IDS = BUILTIN_DESCRIPTORS.map(
+  (d) => d.id
+);
+var BUILTIN_PROFILES = Object.freeze(
+  Object.fromEntries(BUILTIN_DESCRIPTORS.map((d) => [d.id, d.profiles]))
+);
+function builtinDescriptors() {
+  return BUILTIN_DESCRIPTORS;
+}
+
+// src/capability-deck/manifest.ts
+function cardOf(descriptor) {
+  return {
+    id: descriptor.id,
+    title: descriptor.title,
+    summary: descriptor.summary,
+    build: descriptor.build
+  };
+}
+var CAPABILITY_CARDS = builtinDescriptors().map(cardOf);
+var CAPABILITY_INDEX = new Map(CAPABILITY_CARDS.map((card) => [card.id, card]));
+var CARD_PROFILES = new Map(
+  builtinDescriptors().map((descriptor) => [descriptor.id, descriptor.profiles])
+);
+function cardsForProfile(profile) {
+  if (profile === "all") return [...CAPABILITY_CARDS];
+  return CAPABILITY_CARDS.filter((card) => {
+    const profiles = CARD_PROFILES.get(card.id);
+    return profiles !== void 0 && profiles.includes(profile);
+  });
+}
+
+// src/capability-deck/cards/todo-card.ts
+import { Type } from "@sinclair/typebox";
+var TodoLedger = class {
+  items = [];
+  /** Replace the entire checklist with `next`; returns the stored snapshot. */
+  set(next) {
+    this.items = Object.freeze([...next]);
+    return this.items;
+  }
+  /** Return the current checklist as a frozen, read-only snapshot. */
+  read() {
+    return this.items;
+  }
+};
+var TodoItemSchema = Type.Object(
+  {
+    task: Type.String({ description: "Short imperative description of the work item." }),
+    state: Type.Union(
+      [
+        Type.Literal("pending"),
+        Type.Literal("active"),
+        Type.Literal("done"),
+        Type.Literal("dropped")
+      ],
+      { description: "Lifecycle state of the item." }
+    ),
+    weight: Type.Union([Type.Literal("low"), Type.Literal("normal"), Type.Literal("high")], {
+      description: "Relative importance of the item."
+    })
+  },
+  { additionalProperties: false }
+);
+var TodoParams = Type.Object(
+  {
+    action: Type.Union([Type.Literal("read"), Type.Literal("set")], {
+      description: "`read` returns the current checklist; `set` replaces it with the items you provide."
+    }),
+    items: Type.Optional(
+      Type.Array(TodoItemSchema, {
+        description: "The complete desired checklist. Required for `set` (send the whole list, not a delta); ignored for `read`."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+var TODO_DESCRIPTION = 'Maintain a working checklist for the current task. Call with `action:"set"` and a complete `items` list to record or revise your plan \u2014 always send the full intended list, since the previous one is discarded. Call with `action:"read"` to recall the current plan. Mark items `active` while in progress and `done` when finished so the list reflects real status; use `dropped` for work you decided to skip.';
+var STATE_GLYPH = {
+  pending: "[ ]",
+  active: "[~]",
+  done: "[x]",
+  dropped: "[-]"
+};
+function renderChecklist(items) {
+  if (items.length === 0) return "The checklist is empty.";
+  const lines = items.map((it) => {
+    const weight = it.weight === "normal" ? "" : ` (${it.weight})`;
+    return `${STATE_GLYPH[it.state]} ${it.task}${weight}`;
+  });
+  return lines.join("\n");
+}
+function buildTodoCapability(_ctx) {
+  const ledger = new TodoLedger();
+  return {
+    name: "todo",
+    label: "Checklist",
+    description: TODO_DESCRIPTION,
+    parameters: TodoParams,
+    async execute(_toolCallId, params) {
+      const items = params.action === "set" ? ledger.set(params.items ?? []) : ledger.read();
+      const heading = params.action === "set" ? "Checklist updated:" : "Current checklist:";
+      const text = `${heading}
+${renderChecklist(items)}`;
+      return {
+        content: [{ type: "text", text }],
+        details: { action: params.action, items }
+      };
+    }
+  };
+}
+var todoCard = {
+  id: capabilityId("todo"),
+  title: "Checklist",
+  summary: "Keep an in-memory checklist of the current task's steps; set or read it.",
+  // The card surface is the erased `Capability`; the builder keeps its precise
+  // params/details type for direct callers and erases here. The erasure goes
+  // through `unknown` because TypeBox tools are invariant in their schema (the
+  // framework's own tool arrays are `AgentTool<any>[]` for the same reason).
+  build: (ctx) => buildTodoCapability(ctx)
+};
+
+// src/capability-deck/cards/bg-process-card.ts
+import { spawn } from "node:child_process";
+import { Type as Type2 } from "@sinclair/typebox";
+var MAX_BUFFERED_LINES = 2e3;
+function pushLines(buf, chunk) {
+  for (const line of chunk.split(/\r?\n/)) {
+    if (line.length === 0) continue;
+    buf.lines.push(line);
+  }
+  if (buf.lines.length > MAX_BUFFERED_LINES) {
+    const drop = buf.lines.length - MAX_BUFFERED_LINES;
+    buf.lines.splice(0, drop);
+    buf.cursor = Math.max(0, buf.cursor - drop);
+  }
+}
+var DaemonTable = class {
+  handles = /* @__PURE__ */ new Map();
+  nextSeq = 1;
+  cwd;
+  constructor(cwd) {
+    this.cwd = cwd;
+  }
+  start(command) {
+    const id = `bg-${this.nextSeq++}`;
+    const child = spawn(command, {
+      cwd: this.cwd,
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false
+    });
+    const handle = {
+      id,
+      command,
+      child,
+      state: "running",
+      exitCode: null,
+      signal: null,
+      startedAt: Date.now(),
+      stdout: { lines: [], cursor: 0 },
+      stderr: { lines: [], cursor: 0 }
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (d) => pushLines(handle.stdout, d));
+    child.stderr?.on("data", (d) => pushLines(handle.stderr, d));
+    child.on("exit", (code, sig) => {
+      handle.exitCode = code;
+      handle.signal = sig;
+      handle.state = sig ? "signalled" : "exited";
+    });
+    child.on("error", (err) => {
+      pushLines(handle.stderr, `spawn error: ${String(err)}`);
+      handle.state = "exited";
+    });
+    this.handles.set(id, handle);
+    return handle;
+  }
+  get(id) {
+    return this.handles.get(id);
+  }
+  list() {
+    return [...this.handles.values()];
+  }
+  /**
+   * Signal a handle's process to terminate. Sends SIGTERM immediately and a
+   * SIGKILL after `graceMs` if the child is still alive. Resolves once the
+   * child has exited or the kill has been sent.
+   */
+  async stop(handle, graceMs = 3e3) {
+    if (handle.state !== "running") return;
+    const child = handle.child;
+    child.kill("SIGTERM");
+    await new Promise((resolve2) => {
+      const timer = setTimeout(() => {
+        if (handle.state === "running") child.kill("SIGKILL");
+        resolve2();
+      }, graceMs);
+      child.once("exit", () => {
+        clearTimeout(timer);
+        resolve2();
+      });
+    });
+  }
+};
+var DaemonParams = Type2.Object(
+  {
+    action: Type2.Union(
+      [Type2.Literal("start"), Type2.Literal("poll"), Type2.Literal("stop"), Type2.Literal("list")],
+      {
+        description: "`start` launches a long-running command; `poll` reads its captured output; `stop` terminates it; `list` shows all tracked processes."
+      }
+    ),
+    command: Type2.Optional(
+      Type2.String({
+        description: "Shell command to launch. Required for `start`."
+      })
+    ),
+    id: Type2.Optional(
+      Type2.String({
+        description: "Handle returned by `start`. Required for `poll` and `stop`."
+      })
+    ),
+    sinceLast: Type2.Optional(
+      Type2.Boolean({
+        description: "On `poll`, return only output appended since the previous poll of this handle. Defaults to false (return the full retained buffer)."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+var DAEMON_DESCRIPTION = 'Run and manage long-lived background processes that persist across tool calls \u2014 dev servers, file watchers, anything you start once and observe over time. Use `action:"start"` with a `command` to launch one (you get back a handle `id`), `action:"poll"` with that `id` to read its accumulated output, `action:"stop"` to terminate it, and `action:"list"` to see what is running. Do NOT use this for ordinary one-shot commands that finish on their own \u2014 run those with the shell tool.';
+function drainBuffer(buf, sinceLast) {
+  if (sinceLast) {
+    const fresh = buf.lines.slice(buf.cursor);
+    buf.cursor = buf.lines.length;
+    return fresh;
+  }
+  return [...buf.lines];
+}
+function statusLine(h) {
+  if (h.state === "running") return "running";
+  if (h.state === "signalled") return `signalled (${h.signal ?? "?"})`;
+  return `exited (code ${h.exitCode ?? "?"})`;
+}
+function buildDaemonCapability(ctx) {
+  const table = new DaemonTable(ctx.cwd);
+  return {
+    name: "bg-process",
+    label: "Background process",
+    description: DAEMON_DESCRIPTION,
+    parameters: DaemonParams,
+    async execute(_toolCallId, params) {
+      switch (params.action) {
+        case "start": {
+          if (!params.command) {
+            return errResult("start", "`command` is required to start a background process.");
+          }
+          const h = table.start(params.command);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Started background process ${h.id}: ${h.command}
+Poll it with action:"poll", id:"${h.id}".`
+              }
+            ],
+            details: { action: "start", ok: true, id: h.id, state: h.state }
+          };
+        }
+        case "poll": {
+          const h = params.id ? table.get(params.id) : void 0;
+          if (!h) return errResult("poll", `No background process with id "${params.id ?? ""}".`);
+          const out = drainBuffer(h.stdout, params.sinceLast ?? false);
+          const err = drainBuffer(h.stderr, params.sinceLast ?? false);
+          const parts = [`Process ${h.id} \u2014 ${statusLine(h)}`];
+          if (out.length) parts.push(`--- stdout ---
+${out.join("\n")}`);
+          if (err.length) parts.push(`--- stderr ---
+${err.join("\n")}`);
+          if (out.length === 0 && err.length === 0) parts.push("(no new output)");
+          return {
+            content: [{ type: "text", text: parts.join("\n") }],
+            details: { action: "poll", ok: true, id: h.id, state: h.state, exitCode: h.exitCode }
+          };
+        }
+        case "stop": {
+          const h = params.id ? table.get(params.id) : void 0;
+          if (!h) return errResult("stop", `No background process with id "${params.id ?? ""}".`);
+          await table.stop(h);
+          return {
+            content: [{ type: "text", text: `Stopped background process ${h.id} (${statusLine(h)}).` }],
+            details: { action: "stop", ok: true, id: h.id, state: h.state, exitCode: h.exitCode }
+          };
+        }
+        case "list": {
+          const all = table.list();
+          const text = all.length === 0 ? "No background processes are being tracked." : all.map((h) => `${h.id} [${statusLine(h)}] ${h.command}`).join("\n");
+          return {
+            content: [{ type: "text", text }],
+            details: {
+              action: "list",
+              ok: true,
+              processes: all.map((h) => ({ id: h.id, command: h.command, state: h.state }))
+            }
+          };
+        }
+      }
+    }
+  };
+}
+function errResult(action, message) {
+  return {
+    content: [{ type: "text", text: message }],
+    details: { action, ok: false },
+    isError: true
+  };
+}
+var daemonCard = {
+  id: capabilityId("bg-process"),
+  title: "Background process",
+  summary: "Start, poll, and stop long-lived child processes that span multiple turns.",
+  // Erase the precisely-typed builder to the `Capability` card surface (through
+  // `unknown`, as TypeBox tools are invariant in their parameter schema).
+  build: (ctx) => buildDaemonCapability(ctx)
+};
+
+// src/capability-deck/cards/task-card.ts
+import { Type as Type3 } from "@sinclair/typebox";
+var DELEGATE_HANDLE_KEY = "delegate";
+function readDelegateRunner(ctx) {
+  const handle = ctx.framework?.[DELEGATE_HANDLE_KEY];
+  if (handle && typeof handle.run === "function") {
+    return handle;
+  }
+  return void 0;
+}
+var TaskParams = Type3.Object(
+  {
+    objective: Type3.String({
+      description: "A complete, self-contained statement of what the sub-agent should accomplish. Include everything it needs; it does not share your conversation history."
+    }),
+    agent: Type3.Optional(
+      Type3.String({
+        description: "Optional named sub-agent profile to run as. Omit to use the default profile."
+      })
+    ),
+    context: Type3.Optional(
+      Type3.String({
+        description: "Optional extra background the sub-agent should start with."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+function baseDescription(agents) {
+  const roster = agents.length > 0 ? ` Available sub-agent profiles: ${agents.join(", ")}.` : "";
+  return "Delegate a focused, self-contained piece of work to a sub-agent that runs its own tool loop and returns a single report. Use this to keep your own context clean when a task is well-scoped \u2014 searching a large codebase, drafting a file, or investigating a question end-to-end. Give a complete `objective`; the sub-agent does not see your conversation." + roster;
+}
+var STUB_NOTE = "Sub-agent delegation is not wired in this environment, so the objective was not run. Wire a DelegateRunner into the deck context to enable it, or perform the work inline with the other tools.";
+function buildTaskCapability(ctx) {
+  const runner = readDelegateRunner(ctx);
+  const agents = runner?.listAgents?.() ?? [];
+  return {
+    name: "task",
+    label: "Delegate task",
+    description: baseDescription(agents),
+    parameters: TaskParams,
+    async execute(_toolCallId, params, signal) {
+      if (!runner) {
+        return {
+          content: [{ type: "text", text: STUB_NOTE }],
+          details: { delegated: false, ok: false, agent: params.agent },
+          isError: true
+        };
+      }
+      const result = await runner.run(
+        { objective: params.objective, agent: params.agent, context: params.context },
+        signal
+      );
+      return {
+        content: [{ type: "text", text: result.report }],
+        details: { delegated: true, ok: result.ok, agent: params.agent },
+        isError: result.ok ? void 0 : true
+      };
+    }
+  };
+}
+var taskCard = {
+  id: capabilityId("task"),
+  title: "Delegate task",
+  summary: "Hand a self-contained objective to a sub-agent and receive one report back.",
+  // Erase the precisely-typed builder to the `Capability` card surface (through
+  // `unknown`, as TypeBox tools are invariant in their parameter schema).
+  build: (ctx) => buildTaskCapability(ctx)
+};
+
+// src/capability-deck/cards/saas-card.ts
+import { Type as Type4 } from "@sinclair/typebox";
+var SAAS_GATEWAY_KEY = "saasGateway";
+function readGateway(ctx) {
+  const handle = ctx.framework?.[SAAS_GATEWAY_KEY];
+  if (handle && typeof handle.discover === "function" && typeof handle.execute === "function") {
+    return handle;
+  }
+  return void 0;
+}
+var SaasParams = Type4.Object(
+  {
+    action: Type4.Union([Type4.Literal("discover"), Type4.Literal("execute")], {
+      description: "`discover` lists available remote tool slugs; `execute` runs one slug with arguments."
+    }),
+    slug: Type4.Optional(
+      Type4.String({
+        description: "Vendor tool slug to run (e.g. GITHUB_CREATE_ISSUE). Required for `execute`."
+      })
+    ),
+    arguments: Type4.Optional(
+      Type4.Record(Type4.String(), Type4.Unknown(), {
+        description: "Arguments object for the remote tool, as the connector expects."
+      })
+    ),
+    toolkits: Type4.Optional(
+      Type4.Array(Type4.String(), {
+        description: "On `discover`, restrict results to these toolkit names."
+      })
+    ),
+    query: Type4.Optional(
+      Type4.String({
+        description: "On `discover`, free-text filter over available tools."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+var SAAS_DESCRIPTION = 'Discover and run third-party SaaS actions (GitHub, Slack, Gmail, etc.) through the connector gateway. Use `action:"discover"` to find the right tool slug, then `action:"execute"` with that `slug` and an `arguments` object to perform the action. Tool slugs are vendor-defined and case-sensitive; pass them exactly as listed.';
+var STUB_NOTE2 = "The SaaS connector gateway is not configured in this environment, so no remote action was performed. Configure a connector (and authenticate the relevant toolkit) to enable these actions.";
+function buildSaasCapability(ctx) {
+  const gateway = readGateway(ctx);
+  return {
+    name: "saas-action",
+    label: "SaaS action",
+    description: SAAS_DESCRIPTION,
+    parameters: SaasParams,
+    async execute(_toolCallId, params) {
+      if (!gateway) {
+        return {
+          content: [{ type: "text", text: STUB_NOTE2 }],
+          details: { action: params.action, ok: false },
+          isError: true
+        };
+      }
+      if (params.action === "discover") {
+        const tools = await gateway.discover({ toolkits: params.toolkits, query: params.query });
+        const text = tools.length === 0 ? "No remote tools matched." : tools.map((t) => `- ${t.slug}${t.description ? ` \u2014 ${t.description}` : ""}`).join("\n");
+        return {
+          content: [{ type: "text", text }],
+          details: { action: "discover", ok: true, count: tools.length }
+        };
+      }
+      if (!params.slug) {
+        return {
+          content: [{ type: "text", text: "`slug` is required to execute a SaaS action." }],
+          details: { action: "execute", ok: false },
+          isError: true
+        };
+      }
+      const result = await gateway.execute(params.slug, params.arguments ?? {});
+      return {
+        content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        details: { action: "execute", ok: result.ok, slug: params.slug },
+        isError: result.ok ? void 0 : true
+      };
+    }
+  };
+}
+var saasCard = {
+  id: capabilityId("saas-action"),
+  title: "SaaS action",
+  summary: "Discover and run third-party SaaS actions through the connector gateway.",
+  // Erase the precisely-typed builder to the `Capability` card surface (through
+  // `unknown`, as TypeBox tools are invariant in their parameter schema).
+  build: (ctx) => buildSaasCapability(ctx)
+};
+
+// src/capability-deck/cards/memory-card.ts
+import { Type as Type5 } from "@sinclair/typebox";
+var MEMORY_HANDLE_KEY = "memoryStore";
+var InMemoryStore = class {
+  buffer = "";
+  read() {
+    return this.buffer;
+  }
+  replace(content) {
+    this.buffer = content;
+  }
+  append(line) {
+    this.buffer = this.buffer.length === 0 ? line : `${this.buffer}
+${line}`;
+  }
+};
+function readStore(ctx) {
+  const handle = ctx.framework?.[MEMORY_HANDLE_KEY];
+  if (handle && typeof handle.read === "function" && typeof handle.replace === "function" && typeof handle.append === "function") {
+    return handle;
+  }
+  return new InMemoryStore();
+}
+var MemoryParams = Type5.Object(
+  {
+    action: Type5.Union(
+      [Type5.Literal("read"), Type5.Literal("replace"), Type5.Literal("append")],
+      {
+        description: "`read` returns the note; `replace` overwrites it; `append` adds a line to the end."
+      }
+    ),
+    content: Type5.Optional(
+      Type5.String({
+        description: "New note body (for `replace`) or the line to add (for `append`). Ignored for `read`."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+var MEMORY_DESCRIPTION = 'Keep a small working-memory note that persists across turns \u2014 durable facts, decisions, or reminders you want to retain even after older messages scroll out of context. Use `action:"read"` to recall it, `action:"replace"` to rewrite it from scratch, and `action:"append"` to add a single line. Keep it concise; it is a scratchpad, not a log.';
+function buildMemoryCapability(ctx) {
+  const store = readStore(ctx);
+  return {
+    name: "memory",
+    label: "Working memory",
+    description: MEMORY_DESCRIPTION,
+    parameters: MemoryParams,
+    async execute(_toolCallId, params) {
+      if (params.action === "replace") store.replace(params.content ?? "");
+      else if (params.action === "append" && params.content) store.append(params.content);
+      const note = store.read();
+      const heading = params.action === "read" ? "Working memory:" : params.action === "replace" ? "Working memory replaced:" : "Working memory appended:";
+      const body = note.length === 0 ? "(empty)" : note;
+      return {
+        content: [{ type: "text", text: `${heading}
+${body}` }],
+        details: { action: params.action, ok: true, length: note.length }
+      };
+    }
+  };
+}
+var memoryCard = {
+  id: capabilityId("memory"),
+  title: "Working memory",
+  summary: "Read and update a persistent scratch note that survives across turns.",
+  // Erase the precisely-typed builder to the `Capability` card surface (through
+  // `unknown`, as TypeBox tools are invariant in their parameter schema).
+  build: (ctx) => buildMemoryCapability(ctx)
+};
+
+// src/capability-deck/cards/plan-tools.ts
+import { Type as Type6 } from "@sinclair/typebox";
+var PLAN_HANDLE_KEY = "planController";
+function readPlanController(ctx) {
+  const handle = ctx.framework?.[PLAN_HANDLE_KEY];
+  if (handle && typeof handle.enterPlanMode === "function") {
+    return handle;
+  }
+  return void 0;
+}
+var EnterPlanParams = Type6.Object({}, { additionalProperties: false });
+var ENTER_PLAN_DESCRIPTION = "Enter plan mode: a read-only research phase in which you may only read, search, and inspect \u2014 every file-mutating and shell tool is blocked until you leave. Use this when a task needs investigation and a plan before any change is made. While in plan mode, gather all the context you need, then call `exit_plan_mode` with the plan you intend to carry out; the user reviews and approves it before you act.";
+var ENTER_PLAN_PROSE = "You are now in plan mode (read-only). Investigate freely with the read, search, and listing tools, but do not attempt to edit files or run shell commands \u2014 they are blocked here. When you have a concrete plan, call `exit_plan_mode` with the full plan text so the user can approve it before you make any changes.";
+function buildEnterPlanModeCapability(ctx) {
+  const controller = readPlanController(ctx);
+  return {
+    name: "enter_plan_mode",
+    label: "Enter plan mode",
+    description: ENTER_PLAN_DESCRIPTION,
+    readOnly: true,
+    parameters: EnterPlanParams,
+    async execute() {
+      const applied = controller !== void 0;
+      if (controller) controller.enterPlanMode();
+      return {
+        content: [{ type: "text", text: ENTER_PLAN_PROSE }],
+        details: { enterPlanMode: true, applied }
+      };
+    }
+  };
+}
+var ExitPlanParams = Type6.Object(
+  {
+    plan: Type6.String({
+      description: "The plan you intend to carry out, in markdown. The user reviews this before approving the exit from plan mode; on approval you leave plan mode and begin."
+    })
+  },
+  { additionalProperties: false }
+);
+var EXIT_PLAN_DESCRIPTION = "Leave plan mode and propose the plan you intend to carry out. Provide the full plan as `plan`; the user reviews it and either approves (you exit plan mode and begin the work) or rejects (you stay in plan mode to revise). Only call this once you have a concrete, reviewed plan \u2014 not to do work, but to ask permission to start it.";
+function buildExitPlanModeCapability(_ctx) {
+  return {
+    name: "exit_plan_mode",
+    label: "Exit plan mode",
+    description: EXIT_PLAN_DESCRIPTION,
+    // Marked read-only so the plan-mode gate never blocks the very tool used to
+    // request leaving plan mode (it mutates nothing — the conductor owns the flip).
+    readOnly: true,
+    parameters: ExitPlanParams,
+    async execute(_toolCallId, params) {
+      const plan = params.plan;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Proposed plan (awaiting your approval to leave plan mode):
+
+${plan}`
+          }
+        ],
+        details: { exitPlan: true, plan }
+      };
+    }
+  };
+}
+var enterPlanModeCard = {
+  id: capabilityId("enter_plan_mode"),
+  title: "Enter plan mode",
+  summary: "Switch into a read-only research phase where mutating tools are blocked.",
+  build: (ctx) => buildEnterPlanModeCapability(ctx)
+};
+var exitPlanModeCard = {
+  id: capabilityId("exit_plan_mode"),
+  title: "Exit plan mode",
+  summary: "Propose a plan and request approval to leave plan mode and begin work.",
+  build: (ctx) => buildExitPlanModeCapability(ctx)
+};
+
+// src/capability-deck/cards/index.ts
+var APP_NOVEL_CARDS = [
+  todoCard,
+  daemonCard,
+  taskCard,
+  saasCard,
+  memoryCard,
+  enterPlanModeCard,
+  exitPlanModeCard
+];
+
+// src/capability-deck/provision.ts
+var PROFILE_TABLE = Object.freeze({
+  authoring: { builtins: "survey", appCards: false },
+  survey: { builtins: "all", appCards: false },
+  all: { builtins: "all", appCards: true }
+});
+function cardsForDeckProfile(profile) {
+  const policy = PROFILE_TABLE[profile];
+  if (policy === void 0) {
+    throw deckFault(
+      "unknown_capability",
+      `No deck profile is registered under "${String(profile)}".`
+    );
+  }
+  const builtins = cardsForProfile(policy.builtins);
+  return policy.appCards ? [...builtins, ...APP_NOVEL_CARDS] : builtins;
+}
+function buildSelected(cards, ctx) {
+  const built = [];
+  for (const card of cards) {
+    try {
+      built.push(card.build(ctx));
+    } catch (cause) {
+      throw deckFault(
+        "build_failed",
+        `Capability "${String(card.id)}" failed to build.`,
+        cause
+      );
+    }
+  }
+  return built;
+}
+function provisionDeck(profile, ctx) {
+  const selected = cardsForDeckProfile(profile);
+  const capabilities = buildSelected(selected, ctx);
+  return {
+    tools() {
+      return [...capabilities];
+    },
+    box() {
+      return [...capabilities];
+    }
+  };
+}
+
+// src/boot/runners/read-state.ts
+import { normalize } from "node:path";
+var READ_STATE_HANDLE_KEY = "readState";
+var ReadStateStore = class {
+  entries = /* @__PURE__ */ new Map();
+  /** Normalize an absolute path into the store's canonical key. */
+  key(absPath) {
+    return normalize(absPath);
+  }
+  /** The recorded read fingerprint for a path, or `undefined` if never read. */
+  get(absPath) {
+    return this.entries.get(this.key(absPath));
+  }
+  /** Record (or replace) the read fingerprint for a path; returns this store. */
+  set(absPath, value) {
+    this.entries.set(this.key(absPath), value);
+    return this;
+  }
+  /** Whether a path has a recorded read fingerprint this session. */
+  has(absPath) {
+    return this.entries.has(this.key(absPath));
+  }
+  /** Drop a path's recorded read fingerprint; returns whether one existed. */
+  delete(absPath) {
+    return this.entries.delete(this.key(absPath));
+  }
+  /** Forget every recorded read for this session. */
+  clear() {
+    this.entries.clear();
+  }
+};
+function createReadStateStore() {
+  return new ReadStateStore();
+}
+
+// src/boot/runners/checkpoint.ts
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname as dirname2, normalize as normalize2 } from "node:path";
+var CHECKPOINT_HANDLE_KEY = "checkpoint";
+var ROOT_NODE_ID = "__root__";
+var CheckpointStore = class {
+  /** node id → (normalized abs path → first-seen pre-mutation content). */
+  byNode = /* @__PURE__ */ new Map();
+  /** The transcript node the next {@link record} files its snapshot under. */
+  current = null;
+  /** Normalize an absolute path into the store's canonical per-node key. */
+  key(absPath) {
+    return normalize2(absPath);
+  }
+  /** The node id new snapshots are currently filed under (`null` until pinned). */
+  activeNodeId() {
+    return this.current;
+  }
+  /**
+   * Pin the transcript node subsequent {@link record} calls file snapshots under.
+   *
+   * The conductor calls this as its head advances (at turn start), so all of a
+   * turn's edits key to the node that was active before the turn ran. Passing the
+   * same id again is harmless.
+   *
+   * @param id the active transcript node id, or `null` to fall back to the root
+   */
+  setActiveNodeId(id) {
+    this.current = id;
+  }
+  /** The node id snapshots are filed under right now (active id or the root). */
+  resolveNodeId() {
+    return this.current ?? ROOT_NODE_ID;
+  }
+  /**
+   * Capture the pre-mutation content of `absPath` under the active node.
+   *
+   * The framework's duck-typed `CheckpointHandle` entry point. Called once per
+   * mutated path immediately before the write lands, with the file's OLD on-disk
+   * content (or `null` when the file did not exist). First-seen wins: a later
+   * `record` of the same path under the same node is ignored so the snapshot
+   * reflects the file's state when the node became active, not a mid-turn rewrite.
+   *
+   * @param absPath  absolute path of the file about to be written
+   * @param previous the file's content before this mutation, or `null` if absent
+   */
+  record(absPath, previous) {
+    const nodeId = this.resolveNodeId();
+    let paths = this.byNode.get(nodeId);
+    if (paths === void 0) {
+      paths = /* @__PURE__ */ new Map();
+      this.byNode.set(nodeId, paths);
+    }
+    const k = this.key(absPath);
+    if (paths.has(k)) return;
+    paths.set(k, previous);
+  }
+  /**
+   * The recorded snapshots for a node, or `[]` when nothing was tracked there.
+   *
+   * Each entry pairs the normalized absolute path with the content it held before
+   * the node's first mutation of it (`null` = the file was absent).
+   *
+   * @param nodeId the transcript node to read snapshots for
+   */
+  snapshotFor(nodeId) {
+    const paths = this.byNode.get(nodeId);
+    if (paths === void 0) return [];
+    return [...paths].map(([path, previous]) => ({ path, previous }));
+  }
+  /** Whether a node has ANY recorded file snapshot (the picker's restore gate). */
+  hasSnapshot(nodeId) {
+    const paths = this.byNode.get(nodeId);
+    return paths !== void 0 && paths.size > 0;
+  }
+  /**
+   * Roll the working tree back to a node's recorded state.
+   *
+   * For each path the node tracked: when its snapshot is a string, the file is
+   * rewritten with that pre-mutation content (creating parent directories as
+   * needed); when the snapshot is `null` the file is DELETED (it did not exist at
+   * that point). Returns the absolute paths that were restored, in record order.
+   *
+   * A safe no-op when the node has no snapshot — navigating to a node that never
+   * mutated files restores nothing. Per-path failures are swallowed so one
+   * unwritable path never aborts the rest of the restore.
+   *
+   * @param nodeId the transcript node whose file state to restore to
+   * @returns the absolute paths that were written or deleted
+   */
+  restore(nodeId) {
+    const snapshots = this.snapshotFor(nodeId);
+    const restored = [];
+    for (const { path, previous } of snapshots) {
+      try {
+        if (previous === null) {
+          rmSync(path, { force: true });
+        } else {
+          mkdirSync(dirname2(path), { recursive: true });
+          writeFileSync(path, previous, "utf8");
+        }
+        restored.push(path);
+      } catch {
+      }
+    }
+    return restored;
+  }
+};
+function createCheckpointStore() {
+  return new CheckpointStore();
+}
+
+// src/guardrails.ts
+var READ_BEFORE_EDIT_MESSAGE = "File has not been read yet. Read it first before writing to it.";
+export {
+  CHECKPOINT_HANDLE_KEY,
+  CheckpointStore,
+  EDIT_TOOL_NAMES,
+  READ_BEFORE_EDIT_MESSAGE,
+  READ_ONLY_TOOL_NAMES,
+  READ_STATE_HANDLE_KEY,
+  ReadStateStore,
+  bashSubcommandSubjects,
+  composeBriefing,
+  createCheckpointStore,
+  createPermissionGate,
+  createReadStateStore,
+  evaluateCatastrophic,
+  gatherContextDocs,
+  makeRule,
+  provisionDeck,
+  resolveRuleDecision
+};