@noobdemon/noob-cli 1.0.1

package/src/models.js

@@ -0,0 +1,58 @@
+// Model catalog supported by the Noob Demon gateway.
+export const MODELS = [
+  { id: "gateway-gpt-5", name: "GPT-5", provider: "openai", tier: "flagship" },
+  { id: "gateway-gpt-5-1", name: "GPT-5.1", provider: "openai", tier: "flagship" },
+  { id: "gateway-gpt-5-3", name: "GPT-5.3", provider: "openai", tier: "flagship" },
+  { id: "gateway-gpt-5-4", name: "GPT-5.4", provider: "openai", tier: "flagship" },
+  { id: "gateway-gpt-5-5", name: "GPT-5.5", provider: "openai", tier: "flagship" },
+  { id: "gateway-gpt-o3", name: "o3", provider: "openai", tier: "reasoning" },
+  { id: "gateway-gpt-o3-mini", name: "o3 Mini", provider: "openai", tier: "reasoning" },
+  { id: "gateway-gpt-o4-mini", name: "o4-mini", provider: "openai", tier: "reasoning" },
+  { id: "gateway-gpt-4o", name: "GPT-4o", provider: "openai", tier: "standard" },
+  { id: "gateway-gpt-4-1-mini", name: "GPT-4.1 Mini", provider: "openai", tier: "fast" },
+  { id: "gateway-gpt-4-1-nano", name: "GPT-4.1 Nano", provider: "openai", tier: "fast" },
+  { id: "gateway-gpt-5-mini", name: "GPT-5 Mini", provider: "openai", tier: "fast" },
+  { id: "gateway-gpt-5-nano", name: "GPT-5 Nano", provider: "openai", tier: "fast" },
+  { id: "gateway-gpt-5-online", name: "GPT-5 Online", provider: "openai", tier: "standard" },
+  { id: "gateway-claude-opus-4-7", name: "Claude Opus 4.7", provider: "anthropic", tier: "flagship" },
+  { id: "gateway-claude-opus-4-6", name: "Claude Opus 4.6", provider: "anthropic", tier: "flagship" },
+  { id: "gateway-claude-opus-4-5", name: "Claude Opus 4.5", provider: "anthropic", tier: "flagship" },
+  { id: "gateway-claude-opus-4-1", name: "Claude Opus 4.1", provider: "anthropic", tier: "standard" },
+  { id: "gateway-claude-sonnet-4", name: "Claude Sonnet 4", provider: "anthropic", tier: "standard" },
+  { id: "gateway-claude-sonnet-4-6", name: "Claude Sonnet 4.6", provider: "anthropic", tier: "standard" },
+  { id: "gateway-google-2.5-pro", name: "Gemini 2.5 Pro", provider: "google", tier: "flagship" },
+  { id: "gateway-gemini-3-pro", name: "Gemini 3 Pro", provider: "google", tier: "flagship" },
+  { id: "gateway-gemini-3-1-pro", name: "Gemini 3.1 Pro", provider: "google", tier: "flagship" },
+  { id: "gateway-gemini-2.5-flash", name: "Gemini 2.5 Flash", provider: "google", tier: "fast" },
+  { id: "gateway-deepseek-v4-pro", name: "DeepSeek V4 Pro", provider: "deepseek", tier: "flagship" },
+  { id: "gateway-deepseek-v4-flash", name: "DeepSeek V4 Flash", provider: "deepseek", tier: "fast" },
+  { id: "gateway-deepseek-r1", name: "DeepSeek R1", provider: "deepseek", tier: "reasoning" },
+  { id: "gateway-deepseek-v3", name: "DeepSeek V3", provider: "deepseek", tier: "standard" },
+  { id: "gateway-grok-4", name: "Grok 4", provider: "xai", tier: "flagship" },
+  { id: "gateway-grok-3", name: "Grok 3", provider: "xai", tier: "standard" },
+  { id: "gateway-qwen-3-max", name: "Qwen 3 Max", provider: "alibaba", tier: "standard" },
+  { id: "gateway-qwen-qwq-32b", name: "Qwen QwQ 32B", provider: "alibaba", tier: "reasoning" },
+  { id: "gateway-deepinfra-kimi-k2", name: "Kimi K2", provider: "moonshot", tier: "standard" },
+  { id: "gateway-llama-3-3-70b-versatile", name: "Llama 3.3 70B", provider: "meta", tier: "standard" },
+];
+
+export const PROVIDERS = {
+  openai: { name: "OpenAI", color: "#10a37f" },
+  anthropic: { name: "Anthropic", color: "#d97706" },
+  google: { name: "Google", color: "#3b82f6" },
+  deepseek: { name: "DeepSeek", color: "#06b6d4" },
+  xai: { name: "xAI", color: "#ef4444" },
+  alibaba: { name: "Alibaba", color: "#8b5cf6" },
+  moonshot: { name: "Moonshot", color: "#ec4899" },
+  meta: { name: "Meta", color: "#6366f1" },
+};
+
+export const DEFAULT_MODEL = "gateway-claude-opus-4-7";
+
+export function findModel(id) {
+  return MODELS.find((m) => m.id === id);
+}
+
+export function providerColor(providerKey) {
+  return PROVIDERS[providerKey]?.color || "#a78bfa";
+}

package/src/repl.js

@@ -0,0 +1,420 @@
+import readline from "node:readline";
+import process from "node:process";
+import ora from "ora";
+import chalk from "chalk";
+import { runAgent } from "./agent.js";
+import { stream, usage, ApiError } from "./api.js";
+import { runTool, describe, DESTRUCTIVE } from "./tools.js";
+import { MODELS, PROVIDERS, findModel, providerColor, DEFAULT_MODEL } from "./models.js";
+import { c, banner, modelBadge, renderMarkdown, box } from "./ui.js";
+import { config } from "./config.js";
+import { t } from "./i18n.js";
+
+export async function startRepl(opts = {}) {
+  const state = {
+    model: findModel(opts.model) || findModel(config.model) || findModel(DEFAULT_MODEL),
+    mode: "chat", // chat | merge | search
+    history: [],
+    autoApprove: new Set(),
+    yolo: !!opts.yolo,
+  };
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let closed = false;
+  let pending = null;
+  let lastPrompt = "";
+  let awaitingInput = false;
+  rl.on("close", () => {
+    closed = true;
+    if (pending) {
+      const res = pending;
+      pending = null;
+      res(null);
+    }
+  });
+  const ask = (q) =>
+    new Promise((res) => {
+      if (closed) return res(null);
+      lastPrompt = q;
+      awaitingInput = true;
+      pending = res;
+      rl.question(q, (a) => {
+        pending = null;
+        awaitingInput = false;
+        res(a);
+      });
+    });
+
+  // Shift+Tab — quick yolo toggle.
+  if (process.stdin.isTTY) {
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.on("keypress", (_str, key) => {
+      if (!key || key.name !== "tab" || !key.shift) return;
+      state.yolo = !state.yolo;
+      const msg = state.yolo ? c.err("  " + t.yoloOn) : c.ok("  " + t.yoloOff);
+      if (awaitingInput) {
+        const buf = rl.line;
+        readline.cursorTo(process.stdout, 0);
+        readline.clearLine(process.stdout, 0);
+        console.log(msg);
+        process.stdout.write(lastPrompt + buf);
+      } else {
+        console.log("\n" + msg);
+      }
+    });
+  }
+
+  let abort = null; // active turn controller
+  let sigintArmed = false;
+  process.on("SIGINT", () => {
+    if (abort) {
+      abort.abort();
+      abort = null;
+      console.log(c.err("\n  ✗ " + t.interrupted));
+      return;
+    }
+    if (sigintArmed) {
+      console.log(c.dim("\n  " + t.bye));
+      process.exit(0);
+    }
+    sigintArmed = true;
+    console.log(c.dim("\n  " + t.pressAgainToExit));
+    setTimeout(() => (sigintArmed = false), 2000);
+    if (awaitingInput) process.stdout.write(lastPrompt + (rl.line || ""));
+  });
+
+  banner();
+  printStatus(state);
+  if (!config.apiKey) console.log("\n" + c.tool("  " + t.notLoggedIn) + "\n");
+  else console.log(c.dim("  " + t.ready + "\n"));
+
+  if (opts.prompt) {
+    console.log(c.user(t.promptYou) + c.dim("› ") + opts.prompt);
+    await handle(opts.prompt);
+  }
+
+  // Main loop — runs until /exit, double Ctrl+C, or EOF. Never exits after a task.
+  while (!closed) {
+    const raw = await ask(c.user("\n" + t.promptYou) + c.dim("› "));
+    if (raw == null) break;
+    const input = raw.trim();
+    if (!input) continue;
+    if (input.startsWith("/")) {
+      const done = await command(input);
+      if (done) break;
+      continue;
+    }
+    await handle(input);
+  }
+  rl.close();
+
+  // ── turn handler ─────────────────────────────────────────────────────────
+  async function handle(text) {
+    if (!config.apiKey) {
+      console.log(c.tool("  " + t.notLoggedIn));
+      return;
+    }
+    abort = new AbortController();
+    const spinner = ora({ color: "magenta", spinner: "dots" });
+    const t0 = Date.now();
+    let timer = null;
+    const tick = (label) => {
+      const elapsed = ((Date.now() - t0) / 1000).toFixed(0);
+      spinner.text = c.dim(`${label}… ${elapsed}s`);
+    };
+
+    try {
+      if (state.mode !== "chat") {
+        spinner.start();
+        timer = setInterval(() => tick(state.mode === "search" ? t.searching : t.merging), 200);
+        const { text: answer } = await stream({
+          mode: state.mode,
+          message: text,
+          signal: abort.signal,
+          onStatus: (s) => (spinner.text = c.dim("  " + s)),
+        });
+        clearInterval(timer);
+        spinner.stop();
+        printAnswer(answer, state.mode === "search" ? "Tìm web" : "Merge AI", "#f59e0b");
+        return;
+      }
+
+      state.history.push({ role: "user", content: text });
+      spinner.start();
+      timer = setInterval(() => tick(t.thinking), 200);
+
+      const answer = await runAgent({
+        history: state.history,
+        model: state.model.id,
+        signal: abort.signal,
+        onStatus: () => tick(t.thinking),
+        onTool: async (name, input) => {
+          clearInterval(timer);
+          spinner.stop();
+          const res = await execTool(name, input);
+          spinner.start();
+          timer = setInterval(() => tick(t.thinking), 200);
+          return res;
+        },
+      });
+
+      clearInterval(timer);
+      spinner.stop();
+      printAnswer(answer, state.model.name, providerColor(state.model.provider));
+    } catch (err) {
+      clearInterval(timer);
+      spinner.stop();
+      if (err.name === "AbortError") return;
+      printError(err);
+    } finally {
+      abort = null;
+    }
+  }
+
+  async function execTool(name, input) {
+    const desc = describe(name, input);
+    const color = name === "run_command" ? "#ef4444" : "#f59e0b";
+    console.log("\n" + chalk.hex(color)("  ⚙ " + name) + c.dim("  " + desc));
+
+    if (name === "write_file" && input.content) preview(input.content, input.path);
+    else if (name === "edit_file") preview(`- ${truncate(input.old_string)}\n+ ${truncate(input.new_string)}`, input.path);
+
+    if (DESTRUCTIVE.has(name) && !state.yolo && !state.autoApprove.has(name)) {
+      const a = ((await ask(c.tool("  cho phép? ") + c.dim("[y] có / [n] không / [a] luôn " + name + " › "))) ?? "n")
+        .trim()
+        .toLowerCase();
+      if (a === "a") state.autoApprove.add(name);
+      else if (a !== "y" && a !== "") {
+        console.log(c.err("  " + t.denied));
+        return { allow: false };
+      }
+    }
+
+    const sp = ora({ text: c.dim("  " + t.running), color: "yellow" }).start();
+    try {
+      const result = await runTool(name, input);
+      sp.stop();
+      console.log(c.ok("  ✓ ") + c.dim(firstLine(result)));
+      return { allow: true, result };
+    } catch (err) {
+      sp.stop();
+      console.log(c.err("  ✗ " + err.message));
+      return { allow: true, result: "ERROR: " + err.message };
+    }
+  }
+
+  // ── slash commands ─────────────────────────────────────────────────────
+  async function command(input) {
+    const [cmd, ...rest] = input.slice(1).split(/\s+/);
+    const arg = rest.join(" ").trim();
+    switch (cmd) {
+      case "help":
+        printHelp();
+        break;
+      case "model":
+        arg ? selectModel(arg) : listModels();
+        break;
+      case "models":
+        listModels();
+        break;
+      case "merge":
+        state.mode = state.mode === "merge" ? "chat" : "merge";
+        console.log(c.tool("  " + (state.mode === "merge" ? t.mergeOn : t.mergeOff)));
+        break;
+      case "search":
+        state.mode = state.mode === "search" ? "chat" : "search";
+        console.log(c.accent("  " + (state.mode === "search" ? t.searchOn : t.searchOff)));
+        break;
+      case "chat":
+        state.mode = "chat";
+        console.log(c.dim("  " + t.backToChat));
+        break;
+      case "yolo":
+        state.yolo = !state.yolo;
+        console.log((state.yolo ? c.err : c.ok)("  " + (state.yolo ? t.yoloOn : t.yoloOff)));
+        break;
+      case "login":
+        doLogin(arg);
+        break;
+      case "logout":
+        config.clearKey();
+        console.log(c.ok("  " + t.loggedOut));
+        break;
+      case "usage":
+        await showUsage();
+        break;
+      case "clear":
+      case "new":
+        state.history = [];
+        console.clear();
+        banner();
+        printStatus(state);
+        console.log(c.dim("  " + t.ctxCleared + "\n"));
+        break;
+      case "cwd":
+        console.log(c.dim("  " + process.cwd()));
+        break;
+      case "status":
+        printStatus(state);
+        break;
+      case "exit":
+      case "quit":
+      case "q":
+        console.log(c.dim("  " + t.bye));
+        return true;
+      default:
+        console.log(c.err("  " + t.unknownCmd(cmd)) + c.dim("  " + t.tryHelp));
+    }
+    return false;
+  }
+
+  function doLogin(key) {
+    if (!key) return console.log(c.err("  " + t.needKeyArg));
+    config.setKey(key);
+    console.log(c.ok("  ✓ ") + c.dim(t.loginSaved(config.path)));
+    showUsage().catch(() => {});
+  }
+
+  async function showUsage() {
+    if (!config.apiKey) return console.log(c.tool("  " + t.notLoggedIn));
+    const sp = ora({ text: c.dim("  ..."), color: "magenta" }).start();
+    try {
+      const u = await usage();
+      sp.stop();
+      if (!u.ok) return printError(new ApiError(t.errInvalidKey, { code: u.error }));
+      printUsage(u);
+    } catch (err) {
+      sp.stop();
+      printError(err);
+    }
+  }
+
+  function selectModel(q) {
+    const s = q.toLowerCase();
+    const m =
+      MODELS.find((x) => x.id === q) ||
+      MODELS.find((x) => x.name.toLowerCase() === s) ||
+      MODELS.find((x) => x.name.toLowerCase().includes(s) || x.id.includes(s));
+    if (!m) return console.log(c.err("  " + t.noModelMatch(q)) + c.dim("  /models"));
+    state.model = m;
+    state.mode = "chat";
+    config.setModel(m.id);
+    console.log(c.ok("  " + t.switchTo + " ") + modelBadge(m));
+    if (m.provider === "openai" || m.provider === "google")
+      console.log(c.dim("  ") + c.tool(t.providerRefuses(PROVIDERS[m.provider].name)));
+  }
+
+  function printStatus(s) {
+    const mode =
+      s.mode === "merge" ? c.tool("Merge AI") : s.mode === "search" ? c.accent("Tìm web") : modelBadge(s.model);
+    const key = config.apiKey ? c.ok(" 🔑") : c.err(" 🔒");
+    console.log("  " + mode + key + (s.yolo ? c.err("  ⚠ yolo") : "") + c.dim("  thư mục: " + shortCwd()));
+  }
+}
+
+// ── presentation helpers ───────────────────────────────────────────────────
+function printAnswer(text, name, color) {
+  if (!text?.trim()) return;
+  console.log("\n" + chalk.hex(color).bold("  ● " + name));
+  console.log(
+    renderMarkdown(text)
+      .split("\n")
+      .map((l) => "  " + l)
+      .join("\n") + "\n",
+  );
+}
+
+function printError(err) {
+  const map = {
+    missing_key: t.errMissingKey,
+    invalid_key: t.errInvalidKey,
+    key_dead: t.errKeyDead,
+    trial_exhausted: t.errTrialExhausted,
+    key_disabled: t.errDisabled,
+    rate_limited: t.errRateLimited(err.reset_at ? fmtTime(err.reset_at) : ""),
+  };
+  const msg = (err instanceof ApiError && map[err.code]) || err.message || t.errConn;
+  console.log(c.err("  ✗ " + msg));
+  if (err instanceof ApiError && (err.code === "missing_key" || err.code === "invalid_key" || err.status === 401))
+    console.log(c.dim("  → noob login <api-key>"));
+}
+
+function printUsage(u) {
+  const planName = { pro: "Pro", proplus: "Pro+", admin: "Admin", trial: "Trial" }[u.plan] || u.plan;
+  const lines = [
+    chalk.bold(t.usageTitle),
+    `  ${t.plan}: ${chalk.bold(planName)}    ${t.status}: ${u.status === "active" ? c.ok(u.status) : c.err(u.status)}`,
+  ];
+  if (u.plan === "admin") lines.push(`  ${t.remaining}: ${c.ok(t.unlimited)}`);
+  else if (u.plan === "trial") lines.push(`  ${t.remaining}: ${c.accent(t.trialLeft(u.remaining ?? 0))}`);
+  else lines.push(`  ${t.remaining}: ${c.accent(String(u.remaining))} / ${u.limit}  (${t.windowInfo(u.window_count ?? 0, u.limit)})`);
+  if (u.reset_at) lines.push(c.dim(`  ${t.resetAt}: ${fmtTime(u.reset_at)}`));
+  if (u.total_used != null) lines.push(c.dim(`  ${t.used} (tổng): ${u.total_used}`));
+  console.log(box(lines.join("\n"), t.usageTitle, "#a78bfa"));
+}
+
+function printHelp() {
+  console.log(
+    box(
+      [
+        chalk.bold(t.helpCommands),
+        "  " + t.cmdModel,
+        "  " + t.cmdModels,
+        "  " + t.cmdMerge,
+        "  " + t.cmdSearch,
+        "  " + t.cmdChat,
+        "  " + t.cmdYolo,
+        "  " + t.cmdLogin,
+        "  " + t.cmdLogout,
+        "  " + t.cmdUsage,
+        "  " + t.cmdClear,
+        "  " + t.cmdStatus,
+        "  " + t.cmdExit,
+        "",
+        chalk.bold(t.helpTips),
+        c.dim("  " + t.tip1),
+        c.dim("  " + t.tip2),
+        c.dim("  " + t.tip3),
+      ].join("\n"),
+      t.helpTitle,
+      "#a78bfa",
+    ),
+  );
+}
+
+function listModels() {
+  const byProv = {};
+  for (const m of MODELS) (byProv[m.provider] ||= []).push(m);
+  const lines = [];
+  for (const [pk, ms] of Object.entries(byProv)) {
+    lines.push(chalk.hex(providerColor(pk)).bold(PROVIDERS[pk]?.name || pk));
+    lines.push(ms.map((m) => "  " + chalk.hex(providerColor(pk))("●") + " " + m.name + c.dim(` (${m.tier})`)).join("\n"));
+  }
+  console.log("\n" + lines.join("\n") + c.dim("\n\n  " + t.modelListHint) + "\n");
+}
+
+const shortCwd = () => {
+  const p = process.cwd();
+  return p.length > 48 ? "…" + p.slice(-47) : p;
+};
+const firstLine = (s) => (s.split("\n")[0] || "").slice(0, 100);
+const truncate = (s = "", n = 120) => (s.length > n ? s.slice(0, n) + "…" : s).replace(/\n/g, "⏎");
+const fmtTime = (iso) => {
+  try {
+    return new Date(iso).toLocaleString("vi-VN");
+  } catch {
+    return iso;
+  }
+};
+
+function preview(content, label) {
+  const lines = content.split("\n").slice(0, 12);
+  const more = content.split("\n").length - lines.length;
+  console.log(
+    c.dim("  ┌─ " + (label || "")) +
+      "\n" +
+      lines.map((l) => c.dim("  │ ") + l.slice(0, 110)).join("\n") +
+      (more > 0 ? c.dim(`\n  │ … +${more} dòng nữa`) : "") +
+      c.dim("\n  └─"),
+  );
+}

package/src/tools.js

@@ -0,0 +1,183 @@
+import fs from "node:fs/promises";
+import fssync from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+const MAX_OUT = 30000; // hard cap on any tool result fed back to the model
+const cwd = () => process.cwd();
+const abs = (p) => path.resolve(cwd(), p);
+const rel = (p) => path.relative(cwd(), p) || ".";
+
+function clip(s) {
+  if (s.length <= MAX_OUT) return s;
+  return s.slice(0, MAX_OUT) + `\n… [truncated, ${s.length - MAX_OUT} more chars]`;
+}
+
+// Tools that mutate the filesystem or run code require user approval.
+export const DESTRUCTIVE = new Set(["write_file", "edit_file", "run_command"]);
+
+export const TOOLS = {
+  async read_file({ path: p, offset, limit }) {
+    const data = await fs.readFile(abs(p), "utf8");
+    let lines = data.split("\n");
+    const start = offset ? Math.max(0, offset - 1) : 0;
+    if (offset || limit) lines = lines.slice(start, limit ? start + limit : undefined);
+    const width = String(start + lines.length).length;
+    return clip(
+      lines.map((l, idx) => String(start + idx + 1).padStart(width) + "  " + l).join("\n"),
+    );
+  },
+
+  async write_file({ path: p, content }) {
+    await fs.mkdir(path.dirname(abs(p)), { recursive: true });
+    await fs.writeFile(abs(p), content ?? "", "utf8");
+    const n = (content ?? "").split("\n").length;
+    return `Wrote ${n} line(s) to ${rel(abs(p))}`;
+  },
+
+  async edit_file({ path: p, old_string, new_string, replace_all }) {
+    const file = abs(p);
+    const data = await fs.readFile(file, "utf8");
+    if (old_string === new_string) throw new Error("old_string and new_string are identical");
+    const count = data.split(old_string).length - 1;
+    if (count === 0) throw new Error("old_string not found in file");
+    if (count > 1 && !replace_all)
+      throw new Error(`old_string is not unique (${count} matches); set replace_all or add context`);
+    const next = replace_all ? data.split(old_string).join(new_string) : data.replace(old_string, new_string);
+    await fs.writeFile(file, next, "utf8");
+    return `Edited ${rel(file)} (${replace_all ? count : 1} replacement(s))`;
+  },
+
+  async list_dir({ path: p = "." }) {
+    const dir = abs(p);
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const rows = entries
+      .filter((e) => !e.name.startsWith(".git") && e.name !== "node_modules")
+      .sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name))
+      .map((e) => (e.isDirectory() ? e.name + "/" : e.name));
+    return clip(`${rel(dir)}/  (${rows.length} entries)\n` + rows.map((r) => "  " + r).join("\n"));
+  },
+
+  async glob({ pattern }) {
+    const hits = [];
+    const rx = globToRegExp(pattern);
+    (function walk(dir) {
+      let ents;
+      try {
+        ents = fssync.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of ents) {
+        if (e.name === "node_modules" || e.name.startsWith(".git")) continue;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) walk(full);
+        else if (rx.test(rel(full).split(path.sep).join("/"))) hits.push(rel(full));
+        if (hits.length > 500) return;
+      }
+    })(cwd());
+    return hits.length ? clip(hits.join("\n")) : "No files matched.";
+  },
+
+  async grep({ pattern, path: p = ".", glob: g }) {
+    const rx = new RegExp(pattern, "i");
+    const gRx = g ? globToRegExp(g) : null;
+    const out = [];
+    (function walk(dir) {
+      let ents;
+      try {
+        ents = fssync.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of ents) {
+        if (e.name === "node_modules" || e.name.startsWith(".git")) continue;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        const relp = rel(full).split(path.sep).join("/");
+        if (gRx && !gRx.test(relp)) continue;
+        let txt;
+        try {
+          txt = fssync.readFileSync(full, "utf8");
+        } catch {
+          continue;
+        }
+        if (txt.includes("\u0000")) continue; // skip binary files
+        txt.split("\n").forEach((l, idx) => {
+          if (rx.test(l) && out.length < 200) out.push(`${relp}:${idx + 1}: ${l.trim().slice(0, 200)}`);
+        });
+      }
+    })(abs(p));
+    return out.length ? clip(out.join("\n")) : "No matches.";
+  },
+
+  run_command({ command, timeout = 60000 }) {
+    return new Promise((resolve) => {
+      const isWin = process.platform === "win32";
+      const shell = isWin ? "powershell.exe" : "/bin/bash";
+      const args = isWin ? ["-NoProfile", "-NonInteractive", "-Command", command] : ["-c", command];
+      const child = spawn(shell, args, { cwd: cwd() });
+      let out = "";
+      const killer = setTimeout(() => child.kill(), timeout);
+      child.stdout.on("data", (d) => (out += d));
+      child.stderr.on("data", (d) => (out += d));
+      child.on("error", (e) => {
+        clearTimeout(killer);
+        resolve(`Failed to start command: ${e.message}`);
+      });
+      child.on("close", (code) => {
+        clearTimeout(killer);
+        const tail = `\n[exit code ${code}]`;
+        resolve(clip((out.trim() || "(no output)") + tail));
+      });
+    });
+  },
+};
+
+function globToRegExp(glob) {
+  let rx = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        rx += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++;
+      } else rx += "[^/]*";
+    } else if (ch === "?") rx += "[^/]";
+    else if (".+^${}()|[]\\".includes(ch)) rx += "\\" + ch;
+    else rx += ch;
+  }
+  return new RegExp("^" + rx + "$");
+}
+
+// One-line human preview for the permission prompt / activity log.
+export function describe(name, input) {
+  switch (name) {
+    case "read_file":
+      return `read ${input.path}`;
+    case "write_file":
+      return `write ${input.path} (${(input.content ?? "").split("\n").length} lines)`;
+    case "edit_file":
+      return `edit ${input.path}`;
+    case "list_dir":
+      return `ls ${input.path || "."}`;
+    case "glob":
+      return `glob ${input.pattern}`;
+    case "grep":
+      return `grep "${input.pattern}"${input.path ? " in " + input.path : ""}`;
+    case "run_command":
+      return `$ ${input.command}`;
+    default:
+      return name;
+  }
+}
+
+export async function runTool(name, input) {
+  const fn = TOOLS[name];
+  if (!fn) throw new Error(`Unknown tool: ${name}`);
+  return await fn(input || {});
+}