jaitus 0.3.0

package/src/agent/tools.js

@@ -0,0 +1,923 @@
+// ─── Tools the agent can use ────────────────────────────────────────────────────
+//
+// Each tool is a schema the model sees plus an executor that runs locally. Two rules
+// hold everywhere:
+//
+//   1. Every path is resolved and checked to be inside the working directory. The model
+//      is not an attacker, but it is a text generator that will happily emit
+//      "../../.ssh/id_rsa" if a file it read suggests it. Containment is the CLI's job,
+//      not the model's.
+//   2. `needsPermission` decides what gets asked about. Reading is free; changing the
+//      user's disk or running a command is not.
+//
+// Results are returned as strings because that is what a tool_result block carries, and
+// they are truncated — a 4MB file pasted into the transcript costs real money and pushes
+// the actual task out of context.
+
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { loadIgnore, IGNORE_FILE } from '../project.js';
+import { searchWeb, formatResults } from './websearch.js';
+
+const MAX_OUTPUT = 60_000;      // characters returned to the model per tool call
+const MAX_READ_LINES = 2_000;
+
+export class ToolError extends Error {}
+
+function truncate(text, limit = MAX_OUTPUT) {
+  const s = String(text ?? '');
+  if (s.length <= limit) return s;
+  return `${s.slice(0, limit)}\n\n[truncated — ${s.length - limit} more characters]`;
+}
+
+/**
+ * Resolve a user/model-supplied path inside the working directory.
+ * Rejects anything that escapes it, including via a symlink whose real path leads out.
+ */
+function safePath(cwd, p) {
+  if (typeof p !== 'string' || !p.trim()) throw new ToolError('A path is required.');
+  const resolved = path.resolve(cwd, p);
+  const rel = path.relative(cwd, resolved);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new ToolError(`Refused: ${p} is outside the working directory.`);
+  }
+  // A symlink can still point out of the tree; check where it really lands.
+  try {
+    const real = fsSync.realpathSync(resolved);
+    const realRel = path.relative(fsSync.realpathSync(cwd), real);
+    if (realRel.startsWith('..') || path.isAbsolute(realRel)) {
+      throw new ToolError(`Refused: ${p} resolves outside the working directory.`);
+    }
+  } catch (e) {
+    if (e instanceof ToolError) throw e;
+    // Does not exist yet — fine for a write, and the containment check above already
+    // passed on the literal path.
+  }
+  return resolved;
+}
+
+// Paths handed to the model are always forward-slashed. path.relative() returns
+// backslashes on Windows, and the model will echo those straight into source files,
+// shell commands and further tool calls, where they are either wrong or eaten as escapes.
+const posix = (p) => p.split(path.sep).join('/');
+
+const IGNORED_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', '.cache', 'coverage',
+  '__pycache__', '.venv', 'venv', '.idea', '.vscode', 'vendor', 'target',
+]);
+
+// .jaitusignore is read once per working directory rather than per tool call: a session
+// makes hundreds of these and re-reading the file each time would be pure syscall.
+const ignoreCache = new Map();
+function ignoreFor(cwd) {
+  if (!ignoreCache.has(cwd)) ignoreCache.set(cwd, loadIgnore(cwd));
+  return ignoreCache.get(cwd);
+}
+
+/** Exported so a long-running session picks up an edit to the file. */
+export function forgetIgnoreCache() {
+  ignoreCache.clear();
+}
+
+/**
+ * An ignored path is refused for reads and writes alike, not merely hidden from
+ * listings. Hiding it only would mean the agent cannot find `secrets/` by browsing but
+ * will happily open it the moment a filename appears in a stack trace — which is the
+ * case the file was written for.
+ */
+function refuseIfIgnored(cwd, p) {
+  const rel = posix(path.relative(cwd, path.resolve(cwd, p)));
+  if (ignoreFor(cwd).matches(rel)) {
+    throw new ToolError(`Refused: ${p} is listed in ${IGNORE_FILE}.`);
+  }
+}
+
+async function walk(dir, cwd, out, depth, maxEntries) {
+  if (out.length >= maxEntries || depth < 0) return;
+  const ignore = ignoreFor(cwd);
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch { return; }
+  for (const e of entries) {
+    if (out.length >= maxEntries) return;
+    if (e.name.startsWith('.') && e.name !== '.env.example') continue;
+    const rel = posix(path.relative(cwd, path.join(dir, e.name)));
+    if (ignore.matches(rel)) continue;
+    if (e.isDirectory()) {
+      if (IGNORED_DIRS.has(e.name)) continue;
+      out.push(`${rel}/`);
+      await walk(path.join(dir, e.name), cwd, out, depth - 1, maxEntries);
+    } else {
+      out.push(rel);
+    }
+  }
+}
+
+export const TOOLS = [
+  {
+    name: 'read_file',
+    description:
+      'Read a text file from the project. Returns the contents with line numbers so they can be referred to precisely. Prefer reading before editing.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path relative to the project root.' },
+        offset: { type: 'integer', description: 'First line to return (1-based).' },
+        limit: { type: 'integer', description: 'How many lines to return.' },
+      },
+      required: ['path'],
+    },
+    summarise: (i) => `read ${i.path}`,
+    async run(input, { cwd }) {
+      const file = safePath(cwd, input.path);
+      refuseIfIgnored(cwd, input.path);
+      const stat = await fs.stat(file).catch(() => null);
+      if (!stat) throw new ToolError(`No such file: ${input.path}`);
+      if (stat.isDirectory()) throw new ToolError(`${input.path} is a directory — use list_files.`);
+      const raw = await fs.readFile(file, 'utf8');
+      const lines = raw.split('\n');
+      const start = Math.max(0, (input.offset || 1) - 1);
+      const end = Math.min(lines.length, start + (input.limit || MAX_READ_LINES));
+      const body = lines.slice(start, end)
+        .map((l, idx) => `${String(start + idx + 1).padStart(5)}  ${l}`)
+        .join('\n');
+      const more = end < lines.length ? `\n\n[${lines.length - end} more lines]` : '';
+      return truncate(body + more);
+    },
+  },
+
+  {
+    name: 'write_file',
+    description:
+      'Create a file, or completely replace one. For a small change to an existing file prefer edit_file — it is safer and cheaper.',
+    needsPermission: true,
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        content: { type: 'string' },
+      },
+      required: ['path', 'content'],
+    },
+    summarise: (i) => `write ${i.path} (${String(i.content || '').split('\n').length} lines)`,
+    async run(input, { cwd }) {
+      const file = safePath(cwd, input.path);
+      refuseIfIgnored(cwd, input.path);
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      const existed = await fs.stat(file).then(() => true).catch(() => false);
+      await fs.writeFile(file, String(input.content ?? ''), 'utf8');
+      return `${existed ? 'Replaced' : 'Created'} ${input.path}`;
+    },
+  },
+
+  {
+    name: 'edit_file',
+    description:
+      'Replace an exact string in a file. `old` must appear EXACTLY once unless replace_all is set — include enough surrounding context to make it unique. '
+      + 'Pass `edits` instead of old/new to make several replacements in one file atomically: either all of them apply or none do. '
+      + 'This is the preferred way to change existing code.',
+    needsPermission: true,
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        old: { type: 'string', description: 'The exact text to replace.' },
+        new: { type: 'string', description: 'What to replace it with.' },
+        replace_all: { type: 'boolean', description: 'Replace every occurrence instead of requiring exactly one. Use for a rename.' },
+        edits: {
+          type: 'array',
+          description: 'Several replacements applied in order to the same file. Use this instead of old/new for a multi-part change.',
+          items: {
+            type: 'object',
+            properties: {
+              old: { type: 'string' },
+              new: { type: 'string' },
+              replace_all: { type: 'boolean' },
+            },
+            required: ['old', 'new'],
+          },
+        },
+      },
+      required: ['path'],
+    },
+    summarise: (i) => (Array.isArray(i.edits) && i.edits.length ? `edit ${i.path} (${i.edits.length} changes)` : `edit ${i.path}`),
+    async run(input, { cwd }) {
+      const file = safePath(cwd, input.path);
+      refuseIfIgnored(cwd, input.path);
+      const raw = await fs.readFile(file, 'utf8').catch(() => null);
+      if (raw === null) throw new ToolError(`No such file: ${input.path}`);
+
+      const edits = Array.isArray(input.edits) && input.edits.length
+        ? input.edits
+        : [{ old: input.old, new: input.new, replace_all: input.replace_all }];
+      if (!edits.length || edits.some((e) => typeof e?.old !== 'string' || typeof e?.new !== 'string')) {
+        throw new ToolError('Give old and new, or a list of edits each with old and new.');
+      }
+
+      // Applied to a working copy and written once. A partial multi-edit — three of five
+      // replacements landing before the fourth fails to match — leaves a file in a state
+      // neither the model nor the user asked for, and the model cannot tell from the
+      // error which ones took.
+      let next = raw;
+      let changed = 0;
+      for (const [index, edit] of edits.entries()) {
+        const where = edits.length > 1 ? ` (edit ${index + 1} of ${edits.length})` : '';
+        if (edit.old === edit.new) throw new ToolError(`old and new are identical${where} — nothing to do.`);
+        const occurrences = next.split(edit.old).length - 1;
+        if (occurrences === 0) {
+          throw new ToolError(
+            `That exact text is not in ${input.path}${where}. Read the file again — whitespace and indentation must match exactly. Nothing was changed.`,
+          );
+        }
+        if (occurrences > 1 && !edit.replace_all) {
+          throw new ToolError(
+            `That text appears ${occurrences} times in ${input.path}${where}. Include more surrounding context, or set replace_all. Nothing was changed.`,
+          );
+        }
+        next = edit.replace_all ? next.split(edit.old).join(edit.new) : next.replace(edit.old, edit.new);
+        changed += occurrences;
+      }
+
+      await fs.writeFile(file, next, 'utf8');
+      const before = raw.split('\n').length;
+      const after = next.split('\n').length;
+      const delta = after - before;
+      return `Edited ${input.path}: ${changed} replacement${changed === 1 ? '' : 's'}`
+        + (delta ? `, ${delta > 0 ? '+' : ''}${delta} line${Math.abs(delta) === 1 ? '' : 's'}` : '');
+    },
+  },
+
+  {
+    name: 'glob',
+    description:
+      'Find files by name pattern — `**/*.test.js`, `src/**/*.tsx`, `*.md`. Returns paths, newest first. '
+      + 'This is the fast way to answer "which files are there"; use search to look inside them and list_files to browse a directory.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Glob pattern. `*` stays within one path segment, `**` crosses them.' },
+        path: { type: 'string', description: 'Directory to search from. Defaults to the project root.' },
+        limit: { type: 'integer', description: 'Maximum paths to return. Default 200.' },
+      },
+      required: ['pattern'],
+    },
+    summarise: (i) => `glob ${i.pattern}`,
+    async run(input, { cwd }) {
+      const root = safePath(cwd, input.path || '.');
+      const re = globToRegExp(String(input.pattern || ''));
+      const limit = Math.min(Math.max(Number(input.limit) || 200, 1), 2000);
+      const found = [];
+      await walk(root, cwd, found, 12, 20_000);
+      const matched = found.filter((rel) => !rel.endsWith('/') && re.test(rel));
+      if (!matched.length) {
+        return `No file matches ${input.pattern}. Note that * does not cross a / — use ** for that, as in **/*.ts.`;
+      }
+      // Newest first: when a pattern matches many files, the ones touched most recently
+      // are almost always the ones the question is about.
+      const withTimes = await Promise.all(matched.map(async (rel) => {
+        const stat = await fs.stat(path.resolve(cwd, rel)).catch(() => null);
+        return { rel, mtime: stat ? stat.mtimeMs : 0 };
+      }));
+      withTimes.sort((a, b) => b.mtime - a.mtime);
+      const shown = withTimes.slice(0, limit).map((f) => f.rel);
+      const more = withTimes.length > shown.length ? `\n\n[${withTimes.length - shown.length} more]` : '';
+      return truncate(`${shown.join('\n')}${more}`);
+    },
+  },
+
+  {
+    name: 'list_files',
+    description: 'List files and directories in the project. Build output and dependency directories are skipped.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Directory to list. Defaults to the project root.' },
+        depth: { type: 'integer', description: 'How deep to recurse. Default 2.' },
+      },
+    },
+    summarise: (i) => `list ${i.path || '.'}`,
+    async run(input, { cwd }) {
+      const dir = safePath(cwd, input.path || '.');
+      const found = [];
+      await walk(dir, cwd, found, input.depth ?? 2, 600);
+      if (!found.length) return 'No files found.';
+      return truncate(found.sort().join('\n'));
+    },
+  },
+
+  {
+    name: 'search',
+    description:
+      'Search file contents with a regular expression. Returns matching lines with their file and line number. Use this to find where something is defined or used.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'JavaScript regular expression.' },
+        path: { type: 'string', description: 'Directory to search. Defaults to the project root.' },
+        glob: { type: 'string', description: 'Only search files whose name ends with this, e.g. ".ts".' },
+      },
+      required: ['pattern'],
+    },
+    summarise: (i) => `search /${i.pattern}/`,
+    async run(input, { cwd }) {
+      let re;
+      try {
+        re = new RegExp(input.pattern, 'i');
+      } catch (e) {
+        throw new ToolError(`Not a valid regular expression: ${e.message}`);
+      }
+      const dir = safePath(cwd, input.path || '.');
+      const files = [];
+      await walk(dir, cwd, files, 8, 4000);
+      const hits = [];
+      for (const rel of files) {
+        if (rel.endsWith('/')) continue;
+        if (input.glob && !rel.endsWith(input.glob)) continue;
+        if (hits.length >= 200) break;
+        let text;
+        try {
+          const stat = await fs.stat(path.join(cwd, rel));
+          if (stat.size > 2_000_000) continue; // not a source file
+          text = await fs.readFile(path.join(cwd, rel), 'utf8');
+        } catch { continue; }
+        text.split('\n').forEach((line, i) => {
+          if (hits.length >= 200) return;
+          if (re.test(line)) hits.push(`${rel}:${i + 1}: ${line.trim().slice(0, 240)}`);
+        });
+      }
+      return hits.length ? truncate(hits.join('\n')) : 'No matches.';
+    },
+  },
+
+  {
+    name: 'run_command',
+    description:
+      'Run a shell command in the project directory — tests, a build, git, a linter. Returns stdout, stderr and the exit code. Never run something interactive; it will hang.',
+    needsPermission: true,
+    input_schema: {
+      type: 'object',
+      properties: {
+        command: { type: 'string' },
+        timeout_ms: { type: 'integer', description: 'Give up after this long. Default 120000.' },
+      },
+      required: ['command'],
+    },
+    summarise: (i) => i.command,
+    run(input, { cwd }) {
+      const command = String(input.command || '').trim();
+      if (!command) throw new ToolError('No command given.');
+      const timeout = Math.min(Math.max(Number(input.timeout_ms) || 120_000, 1000), 600_000);
+
+      return new Promise((resolve) => {
+        // `shell: true` rather than spawning cmd.exe with an argument array.
+        //
+        // On Windows, spawn('cmd.exe', ['/c', 'node -e "console.log(1)"']) escapes the
+        // inner quotes in a way cmd does not understand. The command then runs as
+        // something else entirely and exits 0 with NO OUTPUT — which an agent reads as
+        // "the tests passed and printed nothing". A silently wrong success is far worse
+        // than an error, and this is exactly how a coding agent ends up reporting a
+        // green build that never ran.
+        const child = spawn(command, {
+          cwd,
+          shell: true,
+          // No TTY: anything that would prompt gets EOF and exits instead of hanging
+          // forever with nobody able to type into it.
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d; });
+        child.stderr.on('data', (d) => { stderr += d; });
+
+        const timer = setTimeout(() => {
+          child.kill('SIGKILL');
+          stderr += `\n[killed after ${timeout}ms]`;
+        }, timeout);
+
+        child.on('error', (e) => {
+          clearTimeout(timer);
+          resolve(`Could not run the command: ${e.message}`);
+        });
+        child.on('close', (code) => {
+          clearTimeout(timer);
+          const parts = [];
+          if (stdout.trim()) parts.push(stdout.trim());
+          if (stderr.trim()) parts.push(`stderr:\n${stderr.trim()}`);
+          parts.push(`exit code: ${code}`);
+          resolve(truncate(parts.join('\n\n')));
+        });
+      });
+    },
+  },
+
+  {
+    name: 'web_search',
+    description:
+      'Search the public web for current information: library versions, documentation, error messages, news, API changes. Returns organic results with title, URL and a snippet. Use web_fetch on a promising URL to read the full page.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'The search query.' },
+      },
+      required: ['query'],
+    },
+    summarise: (i) => `search: ${i.query}`,
+    async run(input) {
+      const query = String(input.query || '').trim();
+      if (!query) throw new ToolError('No query given.');
+      let settings = null;
+      try { settings = (await import('../config.js')).loadSettings(); } catch { /* defaults */ }
+      try {
+        const found = await searchWeb(query, { settings });
+        return formatResults(found);
+      } catch (error) {
+        throw new ToolError(
+          `${error.message} Try a different wording, or fetch a known URL directly with web_fetch.`,
+        );
+      }
+    },
+  },
+
+  {
+    name: 'web_fetch',
+    description:
+      'Fetch a web page and return its readable text with scripts, styles and navigation stripped. For documentation, GitHub files (use raw.githubusercontent.com), API references, and any URL that came from web_search. Prefer this over run_command + curl — it is faster and returns clean text.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The http(s) URL to fetch.' },
+        max_chars: { type: 'integer', description: 'Maximum characters of text to return. Default 20000.' },
+      },
+      required: ['url'],
+    },
+    summarise: (i) => `fetch ${String(i.url).slice(0, 80)}`,
+    async run(input) {
+      const raw = String(input.url || '').trim();
+      if (!/^https?:\/\//i.test(raw)) throw new ToolError('Give a full http(s) URL.');
+      const limit = Math.min(Math.max(Number(input.max_chars) || 20_000, 1000), 50_000);
+
+      const cached = fetchCache.get(raw);
+      if (cached && Date.now() - cached.at < FETCH_CACHE_MS) {
+        return truncate(cached.text.slice(0, limit));
+      }
+
+      let res;
+      try {
+        res = await fetch(raw, {
+          headers: {
+            'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 jaitus-cli',
+            'accept': 'text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8',
+            'accept-language': 'en-US,en;q=0.9',
+          },
+          redirect: 'follow',
+          signal: AbortSignal.timeout(20_000),
+        });
+      } catch (e) {
+        throw new ToolError(explainFetchFailure(e, raw));
+      }
+
+      if (!res.ok) {
+        const hint = res.status === 403 || res.status === 429
+          ? ' The site is refusing automated requests — try a documentation mirror, the raw file (raw.githubusercontent.com for GitHub), or an official API.'
+          : res.status === 404 ? ' Check the URL; search for the page rather than guessing its path.'
+            : '';
+        throw new ToolError(`HTTP ${res.status} ${res.statusText || ''} for ${raw}.${hint}`);
+      }
+
+      const ctype = res.headers.get('content-type') || '';
+      if (/^application\/pdf/i.test(ctype)) {
+        throw new ToolError('That URL is a PDF, which this tool cannot read. Look for an HTML version, or download it with run_command and use a local tool.');
+      }
+      if (/^(image|audio|video)\//i.test(ctype)) {
+        throw new ToolError(`That URL is ${ctype.split(';')[0]}, not a document. Use read_image for a local image file.`);
+      }
+
+      let text;
+      if (/json|xml|csv|javascript|text\/plain|markdown/i.test(ctype)) {
+        text = await res.text();
+      } else {
+        text = readableText(await res.text());
+        if (!text.trim()) {
+          throw new ToolError(
+            'The page returned no readable text — it is almost certainly rendered by JavaScript. '
+            + 'Try the site\'s API, its raw markdown (many docs sites serve /llms.txt or a .md path), or a different source.',
+          );
+        }
+      }
+
+      // A short-lived cache, because an agent re-reads the same documentation page
+      // several times inside one task and each read is a second of latency it did not
+      // need to spend.
+      fetchCache.set(raw, { at: Date.now(), text });
+      if (fetchCache.size > 40) fetchCache.delete(fetchCache.keys().next().value);
+      return truncate(text.slice(0, limit));
+    },
+  },
+
+  {
+    name: 'todo_write',
+    description:
+      'Maintain a visible task list for the current request. Call it whenever work has multiple steps: once to plan, and again after each step completes. Users see the list live in the interface, so keep statuses truthful — never mark a step done before its work is finished. Replace the whole list on every call; omit clear to keep it.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        todos: {
+          type: 'array',
+          description: 'The complete list, in order.',
+          items: {
+            type: 'object',
+            properties: {
+              task: { type: 'string', description: 'One step, phrased as an outcome.' },
+              status: { type: 'string', enum: ['pending', 'in_progress', 'completed'], description: 'Where this step stands.' },
+            },
+            required: ['task', 'status'],
+          },
+        },
+        clear: { type: 'boolean', description: 'true to empty the list (for example when everything is done and the request is complete).' },
+      },
+    },
+    summarise: (i) => `update task list (${Array.isArray(i.todos) ? i.todos.length : 0} items)`,
+    async run(input) {
+      if (input.clear) { todoState.splice(0, todoState.length); return 'Task list cleared.'; }
+      if (!Array.isArray(input.todos)) throw new ToolError('Give a todos array (or clear: true).');
+      const cleaned = input.todos.map((t) => ({
+        task: String(t?.task || '').trim(),
+        status: ['pending', 'in_progress', 'completed'].includes(t?.status) ? t.status : 'pending',
+      })).filter((t) => t.task);
+      if (!cleaned.length) throw new ToolError('The list has no usable items.');
+      todoState.splice(0, todoState.length, ...cleaned);
+      return `Task list updated (${cleaned.filter((t) => t.status === 'completed').length}/${cleaned.length} done).`;
+    },
+  },
+
+  {
+    name: 'read_image',
+    description:
+      'Read an image file (png, jpg, jpeg, gif, webp) so you can actually see it: screenshots, UI mockups, diagrams, photos. Returns the image itself to your vision, not a text description. Max ~3 MB after base64.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to the image, relative to the project root.' },
+      },
+      required: ['path'],
+    },
+    summarise: (i) => `view ${i.path}`,
+    async run() { return '(image attached to the conversation above)'; },
+  },
+
+  {
+    name: 'background_run',
+    description:
+      'Start a long-running shell command (dev server, build watcher, test suite) in the background. Output streams to a log file; poll it with background_read instead of blocking the session on one long command.',
+    needsPermission: true,
+    input_schema: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'The shell command to run detached.' },
+      },
+      required: ['command'],
+    },
+    summarise: (i) => `bg ${String(i.command || '').slice(0, 60)}`,
+    async run(input, { cwd }) {
+      if (!input.command?.trim()) throw new ToolError('Give a command to run.');
+      const { startBackground } = await import('../background.js');
+      const job = startBackground(input.command, cwd);
+      return `Background job ${job.id} started (pid ${job.pid ?? '?'}). Read its output with background_read, stop it with background_stop.`;
+    },
+  },
+
+  {
+    name: 'background_list',
+    description: 'List running and finished background shell jobs started this session.',
+    needsPermission: false,
+    input_schema: { type: 'object', properties: {} },
+    summarise: () => 'list background jobs',
+    async run() {
+      const { listBackground } = await import('../background.js');
+      const all = listBackground();
+      if (!all.length) return 'No background jobs this session.';
+      return all.map((j) => `${j.running ? '…' : j.exit === 0 ? '✓' : '✗'} ${j.id}  ${j.command}  (pid ${j.pid ?? '?'})`).join('\n');
+    },
+  },
+
+  {
+    name: 'background_read',
+    description: 'Read the tail of a background job log without blocking. Poll this to follow a dev server or build.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Job id (or its unique prefix) from background_run or background_list.' },
+        tail: { type: 'integer', description: 'How many trailing lines to return (default 40).' },
+      },
+      required: ['id'],
+    },
+    summarise: (i) => `read bg ${i.id}`,
+    async run(input) {
+      const { readBackground } = await import('../background.js');
+      const job = readBackground(input.id, input.tail || 40);
+      if (!job) throw new ToolError(`No background job ${input.id}. List them with background_list.`);
+      return `${job.running ? 'Running' : `Finished (exit ${job.exit})`} — ${job.command}\n\n${job.tail}`;
+    },
+  },
+
+  {
+    name: 'background_stop',
+    description: 'Stop a running background shell job.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Job id (or its unique prefix).' },
+      },
+      required: ['id'],
+    },
+    summarise: (i) => `stop bg ${i.id}`,
+    async run(input) {
+      const { stopBackground } = await import('../background.js');
+      if (!stopBackground(input.id)) throw new ToolError(`No background job ${input.id}.`);
+      return `Stopped ${input.id}.`;
+    },
+  },
+];
+
+/** The live task list todo_write maintains; the session renders it in the panel. */
+export const todoState = [];
+
+/** The three image sizes the API accepts, newest API first. */
+export const IMAGE_MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
+
+/**
+ * Turn an image file into an API content block, or null when it is not a usable
+ * image (wrong kind, too big, unreadable). The caller attaches the block to the
+ * next user message so the model actually receives the pixels.
+ */
+export async function imageBlock(p) {
+  const ext = path.extname(p).toLowerCase();
+  const mime = IMAGE_MIME[ext];
+  if (!mime) return null;
+  try {
+    const buf = await fs.readFile(p);
+    if (buf.length > 3_500_000) return null;
+    return { type: 'image', source: { type: 'base64', media_type: mime, data: buf.toString('base64') } };
+  } catch { return null; }
+}
+
+/**
+ * read_image's bridge to the loop: same containment rules as every other file tool,
+ * then the pixel payload. Null (with the reason) when the image cannot be seen.
+ */
+export async function readImageForModel(cwd, p) {
+  const file = safePath(cwd, p);
+  refuseIfIgnored(cwd, p);
+  const block = await imageBlock(file);
+  if (!block) {
+    const ext = path.extname(String(p)).toLowerCase();
+    if (!IMAGE_MIME[ext]) throw new ToolError(`Not an image format the model can see (${ext || 'no extension'}). Supported: png, jpg, jpeg, gif, webp.`);
+    throw new ToolError('Image too large or unreadable (max ~3 MB). Compress or screenshot it smaller.');
+  }
+  return block;
+}
+
+const BROWSER_HEADERS = {
+  'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36',
+  'accept': 'text/html',
+  'accept-language': 'en-US,en;q=0.9',
+};
+
+/**
+ * A glob pattern as a regular expression.
+ *
+ * `*` stops at a path separator and `**` crosses them, which is the convention every
+ * tool a developer already uses follows. Getting that distinction wrong in either
+ * direction is the difference between `src/*.ts` meaning "the TypeScript files in src"
+ * and "every TypeScript file in the project".
+ */
+function globToRegExp(pattern) {
+  let out = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        i += 1;
+        // `**/` may match nothing at all, so `**/*.ts` finds `index.ts` at the root.
+        if (pattern[i + 1] === '/') { i += 1; out += '(?:.*/)?'; } else out += '.*';
+      } else out += '[^/]*';
+    } else if (ch === '?') out += '[^/]';
+    else if (ch === '{') out += '(?:';
+    else if (ch === '}') out += ')';
+    else if (ch === ',') out += '|';
+    else out += ch.replace(/[.+^$()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${out}$`, process.platform === 'win32' ? 'i' : '');
+}
+
+const fetchCache = new Map();
+const FETCH_CACHE_MS = 15 * 60 * 1000;
+
+/**
+ * Say what actually went wrong.
+ *
+ * `fetch()` reports every network failure as the string "fetch failed" and hides the
+ * reason on `error.cause`. An agent told "Fetch failed: fetch failed" has no way to
+ * choose between retrying, trying a different host, or telling the user their DNS is
+ * broken — and neither does the person reading the transcript.
+ */
+function explainFetchFailure(error, url) {
+  const code = error?.cause?.code || error?.code || '';
+  const host = (() => { try { return new URL(url).host; } catch { return url; } })();
+  const reasons = {
+    ENOTFOUND: `${host} does not resolve on this network — check the spelling, or DNS is blocking it.`,
+    EAI_AGAIN: `DNS lookup for ${host} timed out — the network or resolver is unavailable.`,
+    ECONNREFUSED: `${host} refused the connection.`,
+    ECONNRESET: `${host} closed the connection mid-response; retrying once is reasonable.`,
+    UND_ERR_CONNECT_TIMEOUT: `Could not connect to ${host} before the timeout — it may be unreachable from this network.`,
+    UND_ERR_HEADERS_TIMEOUT: `${host} accepted the connection but never sent headers.`,
+    CERT_HAS_EXPIRED: `${host} has an expired TLS certificate.`,
+    UNABLE_TO_VERIFY_LEAF_SIGNATURE: `${host}'s TLS certificate could not be verified — a proxy may be intercepting it.`,
+    DEPTH_ZERO_SELF_SIGNED_CERT: `${host} presents a self-signed certificate.`,
+  };
+  if (error?.name === 'TimeoutError' || error?.name === 'AbortError') return `Fetching ${host} timed out after 20s.`;
+  return reasons[code] || `Could not fetch ${host}: ${error?.message || error}${code ? ` (${code})` : ''}.`;
+}
+
+function isNewsQuery(query) {
+  return /\b(news|headlines?|breaking|today|latest|current events?)\b/i.test(query);
+}
+
+/** Google News exposes a public RSS search feed with dated, news-only results. */
+async function searchGoogleNews(query) {
+  const endpoint = isHeadlineRequest(query)
+    ? 'https://news.google.com/rss?hl=en-IN&gl=IN&ceid=IN:en'
+    : `https://news.google.com/rss/search?q=${encodeURIComponent(query)}&hl=en-IN&gl=IN&ceid=IN:en`;
+  const res = await fetch(endpoint, {
+    headers: { ...BROWSER_HEADERS, accept: 'application/rss+xml, application/xml;q=0.9, text/xml;q=0.8' },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const xml = await res.text();
+  const results = [];
+  for (const item of xml.match(/<item>[\s\S]*?<\/item>/g) || []) {
+    if (results.length >= 8) break;
+    const title = xmlText(item, 'title');
+    const url = xmlText(item, 'link');
+    const snippet = xmlText(item, 'description').replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+    if (title && /^https?:\/\//.test(url)) results.push({ title, url, snippet });
+  }
+  return results;
+}
+
+function isHeadlineRequest(query) {
+  const remaining = query
+    .toLowerCase()
+    .replace(/\b(top|latest|today|breaking|news|headlines?|current|events?|world|global|updates?)\b/g, '')
+    .replace(/[^a-z0-9]+/g, ' ').trim();
+  return remaining.length === 0;
+}
+
+function xmlText(source, name) {
+  const match = new RegExp(`<${name}>([\\s\\S]*?)<\\/${name}>`, 'i').exec(source);
+  if (!match) return '';
+  return match[1]
+    .replace(/^<!\[CDATA\[([\s\S]*)\]\]>$/, '$1')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").trim();
+}
+
+/** Bing: results live in <li class="b_algo"> blocks; links are bing.com/ck redirects whose u=a1<base64url> parameter carries the real URL. */
+async function searchBing(query) {
+  const res = await fetch(`https://www.bing.com/search?q=${encodeURIComponent(query)}&count=10`, {
+    headers: BROWSER_HEADERS, signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const html = await res.text();
+  const results = [];
+  for (const block of html.split('<li class="b_algo').slice(1)) {
+    if (results.length >= 8) break;
+    const hrefMatch = /<h2[^>]*><a[^>]+href="([^"]+)"/.exec(block);
+    const h2 = /<h2[^>]*>([\s\S]*?)<\/h2>/.exec(block);
+    if (!hrefMatch || !h2) continue;
+    const url = unwrapBingHref(hrefMatch[1]);
+    const title = stripTags(h2[1]).trim();
+    const snippetMatch = /<p[^>]*>([\s\S]*?)<\/p>/.exec(block);
+    const snippet = snippetMatch ? stripTags(snippetMatch[1]).trim() : '';
+    if (url && title) results.push({ url, title, snippet });
+  }
+  return results;
+}
+
+/** Bing wraps outbound links in a click-tracker; the target is base64url after u=a1. */
+function unwrapBingHref(href) {
+  const clean = href.replace(/&amp;/g, '&');
+  if (!clean.includes('bing.com/ck/')) return clean;
+  const u = /[?&]u=a1([^&]+)/.exec(clean);
+  if (!u) return clean;
+  let b64 = u[1].replace(/-/g, '+').replace(/_/g, '/');
+  while (b64.length % 4) b64 += '=';
+  try {
+    const decoded = Buffer.from(b64, 'base64').toString('utf8');
+    return /^https?:\/\//.test(decoded) ? decoded : clean;
+  } catch { return clean; }
+}
+
+/** Mojeek: independent index, friendly to scrapers, plain hrefs in <a class="ob". */
+async function searchMojeek(query) {
+  const res = await fetch(`https://www.mojeek.com/search?q=${encodeURIComponent(query)}`, {
+    headers: BROWSER_HEADERS, signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const html = await res.text();
+  const results = [];
+  const re = /<a[^>]+class="ob"[^>]+href="(https?:[^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+  let m;
+  while ((m = re.exec(html)) && results.length < 8) {
+    const title = stripTags(m[2]).trim();
+    if (title) results.push({ url: m[1].replace(/&amp;/g, '&'), title, snippet: '' });
+  }
+  return results;
+}
+
+/** DuckDuckGo's HTML endpoint — unreachable on some networks, so it is the last resort. */
+async function searchDuckDuckGo(query) {
+  const res = await fetch(`https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`, {
+    headers: BROWSER_HEADERS, signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const html = await res.text();
+  const results = [];
+  const re = /<a[^>]+class="result__a"[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+  let m;
+  while ((m = re.exec(html)) && results.length < 8) {
+    let href = m[1].replace(/&amp;/g, '&');
+    const uddg = /[?&]uddg=([^&]+)/.exec(href);
+    if (uddg) href = decodeURIComponent(uddg[1]);
+    if (href.startsWith('//')) href = `https:${href}`;
+    const title = stripTags(m[2]).trim();
+    if (title && /^https?:\/\//.test(href)) results.push({ url: href, title, snippet: '' });
+  }
+  const snippets = [];
+  const sre = /<a[^>]+class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
+  while ((m = sre.exec(html)) && snippets.length < 8) snippets.push(stripTags(m[1]).trim());
+  results.forEach((r, i) => { r.snippet = snippets[i] || ''; });
+  return results;
+}
+
+/** Strip tags and entities, then collapse whitespace — the text-only view of HTML. */
+function stripTags(s) {
+  return String(s)
+    .replace(/<[^>]*>/g, '')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ')
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(/\s+/g, ' ');
+}
+
+/**
+ * Crude but effective reader mode: drop scripts/styles/nav/headers/footers and known
+ * boilerplate, keep headings and paragraphs with their text, in document order.
+ */
+function readableText(html) {
+  return String(html)
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, ' ')
+    .replace(/<template[\s\S]*?<\/template>/gi, ' ')
+    .replace(/<(nav|header|footer|aside|form|svg)[\s\S]*?<\/\1>/gi, ' ')
+    .replace(/<!--[^]*?-->/g, ' ')
+    .replace(/<h([1-6])[^>]*>/gi, '\n\n')
+    .replace(/<\/(h[1-6])>/gi, '\n')
+    .replace(/<(p|div|section|article|li|br|tr)[^>]*>/gi, '\n')
+    .replace(/<(td|th)[^>]*>/gi, ' | ')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ')
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .split('\n')
+    .map((l) => l.replace(/\s+/g, ' ').trim())
+    .filter((l) => l.length > 0)
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n');
+}
+
+/** The tool list in the shape the Messages API expects. */
+export const toolSchemas = () =>
+  TOOLS.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.input_schema,
+  }));
+
+/** Tools by name, for dispatch in the loop. */
+export const byName = Object.fromEntries(TOOLS.map((t) => [t.name, t]));