@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/tools/index.mjs

@@ -0,0 +1,84 @@
+/**
+ * lib/engine/tools/index.mjs — the built-in tool registry.
+ *
+ * Every built-in tool is one module exporting a tool object:
+ *
+ *   { name, description, input_schema, readOnly, run(input, ctx) }
+ *
+ * `run` resolves `{ ok:true, content }` or `{ ok:false, error }`; it never
+ * rejects for an expected failure. `readOnly` is what lets the loop run a
+ * batch of calls in parallel. Names and input schemas are compatible with the
+ * tool surface maestro's prompts and skills already use; descriptions are the
+ * engine's own.
+ *
+ * Adding a tool is adding a file and one line to BUILTIN_TOOLS. Registry ORDER
+ * is part of the prompt-cache prefix — append, do not reorder.
+ *
+ * @module lib/engine/tools/index
+ */
+
+import { readTool } from "./read.mjs";
+import { writeTool } from "./write.mjs";
+import { editTool } from "./edit.mjs";
+import { bashTool } from "./bash.mjs";
+import { globTool } from "./glob.mjs";
+import { grepTool } from "./grep.mjs";
+import { webFetchTool } from "./webfetch.mjs";
+import { webSearchTool } from "./websearch.mjs";
+import { lsTool } from "./ls.mjs";
+
+/**
+ * @typedef {Object} ToolContext
+ * @property {string} cwd
+ * @property {AbortSignal} [signal]
+ * @property {NodeJS.ProcessEnv} env
+ * @property {Map<string, {mtimeMs:number}>} fileState  files Read this run
+ * @property {boolean} [useRipgrep]  force (true) or forbid (false); default probes PATH
+ * @property {string[]} [envPassthrough]  extended-shape secrets the Bash tool keeps (CF-22)
+ */
+
+/**
+ * @typedef {Object} Tool
+ * @property {string} name
+ * @property {string} description
+ * @property {object} input_schema
+ * @property {boolean} readOnly
+ * @property {(input:any, ctx:ToolContext) => Promise<{ok:true, content:string}|{ok:false, error:string}>} run
+ */
+
+/** @type {ReadonlyArray<Tool>} */
+export const BUILTIN_TOOLS = Object.freeze([
+  readTool, writeTool, editTool, bashTool, globTool, grepTool,
+  // W3-G2: web tools (need ctx.gateway / ctx.models from the CLI).
+  webFetchTool, webSearchTool,
+  // W4-E2: LS (conformance row 10), appended so the cached prefix of the earlier tools holds.
+  lsTool,
+]);
+
+/**
+ * Select tools by name. `null`/`undefined` → all built-ins; `[]` → none.
+ * Unknown names are returned so the CLI can refuse them.
+ * @param {string[]|null|undefined} names
+ * @returns {{ tools: Tool[], unknown: string[] }}
+ */
+export function selectTools(names) {
+  if (names == null) return { tools: [...BUILTIN_TOOLS], unknown: [] };
+  const byName = new Map(BUILTIN_TOOLS.map((t) => [t.name, t]));
+  const unknown = names.filter((n) => !byName.has(n));
+  // Keep registry order regardless of the order names were given in.
+  const wanted = new Set(names);
+  return { tools: BUILTIN_TOOLS.filter((t) => wanted.has(t.name)), unknown };
+}
+
+/**
+ * The wire-facing definitions, in registry order.
+ * @param {Tool[]} tools
+ */
+export function toolDefinitions(tools) {
+  return tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }));
+}
+
+/** @param {Map<string, {mtimeMs:number}>} [fileState] */
+export function createToolContext({ cwd, env, signal, fileState, useRipgrep, envPassthrough = [] }) {
+  return { cwd, env, signal, fileState: fileState || new Map(), useRipgrep, envPassthrough };
+}

package/lib/engine/tools/list-agents.mjs

@@ -0,0 +1,32 @@
+/**
+ * lib/engine/tools/list-agents.mjs — ListAgents {}.
+ *
+ * The agent sessions running on this machine, from the local session registry
+ * (session-runtime/registry.mjs; stale entries are pruned as they are read):
+ * name, working directory, age, and whether each is idle or busy. Read-only.
+ * Exists only in a `cohort session` (`sessionOnly`).
+ *
+ * @module lib/engine/tools/list-agents
+ */
+
+import { describeSession } from "../session-runtime/registry.mjs";
+
+/**
+ * @param {{selfName:string, registry:{list:()=>any[]}, now?:()=>number}} o
+ */
+export function createListAgentsTool({ selfName, registry, now = Date.now }) {
+  return {
+    name: "ListAgents",
+    readOnly: true,
+    sessionOnly: true,
+    description:
+      "List the agent sessions running on this machine: each one's session name (the address SendMessage uses), working directory, how long it has run, and whether it is idle or busy. " +
+      "This session is marked self.",
+    input_schema: { type: "object", properties: {} },
+    async run() {
+      const t = now();
+      const sessions = registry.list().map((e) => describeSession(e, { now: t, self: selfName }));
+      return { ok: true, content: JSON.stringify({ sessions }, null, 2) };
+    },
+  };
+}

package/lib/engine/tools/ls.mjs

@@ -0,0 +1,127 @@
+/**
+ * lib/engine/tools/ls.mjs — the LS tool (conformance row 10).
+ *
+ * Input contract (compatible name and schema): `{ path, ignore? }`. Lists ONE
+ * directory, not recursively: each entry's name, type (dir, file, link, other)
+ * and size in bytes for files. Directories come first, then everything else,
+ * each group by name. At most `MAX_LS_ENTRIES` entries are shown; the count of
+ * the rest is reported.
+ *
+ * `ignore` is a list of glob patterns (walk.mjs `matchGlob`, the matcher Glob
+ * and Grep use) tested against each entry's name. Dot-entries are listed: this
+ * is a directory listing, not a search.
+ *
+ * Permissions: `LS` is one of the Read tools (permissions.mjs READ_TOOLS), so a
+ * `Read(<path glob>)` or `LS(<path glob>)` rule is matched against the listed
+ * directory (`targetPath` reads `input.path`). It is read-only: it runs in plan
+ * mode and needs no allow rule in default and dontAsk (docs/engine/posture.md).
+ * A symlink is reported as a link and not followed.
+ *
+ * Authorship: written for Cohort Engine by the Cohort team, 2026-09-14
+ * (original description text).
+ *
+ * @module lib/engine/tools/ls
+ */
+
+import { lstatSync, readdirSync, readlinkSync, statSync } from "node:fs";
+import path from "node:path";
+import { matchGlob } from "./walk.mjs";
+
+export const MAX_LS_ENTRIES = 1000;
+export const MAX_IGNORE_PATTERNS = 100;
+
+/**
+ * @typedef {{name:string, type:'dir'|'file'|'link'|'other', size:number|null, target:string|null}} LsEntry
+ */
+
+/**
+ * Order and render a listing (pure).
+ * @param {string} dir absolute
+ * @param {LsEntry[]} entries
+ * @param {{ignored:number, max?:number}} o
+ */
+export function formatListing(dir, entries, { ignored, max = MAX_LS_ENTRIES }) {
+  const rank = (/** @type LsEntry */ e) => (e.type === "dir" ? 0 : 1);
+  const sorted = [...entries].sort((a, b) => rank(a) - rank(b) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const shown = sorted.slice(0, max);
+  const lines = shown.map((e) => {
+    if (e.type === "dir") return `dir   ${" ".repeat(12)}${e.name}/`;
+    if (e.type === "link") return `link  ${" ".repeat(12)}${e.name} -> ${e.target ?? "?"}`;
+    const size = e.size === null ? "" : String(e.size);
+    return `${e.type === "file" ? "file" : "other"}${e.type === "file" ? "  " : " "}${size.padStart(10)}  ${e.name}`;
+  });
+  const notes = [];
+  if (sorted.length > shown.length) notes.push(`${sorted.length - shown.length} more entries not shown; narrow the listing with ignore, or use Glob`);
+  if (ignored > 0) notes.push(`${ignored} entr${ignored === 1 ? "y" : "ies"} matched ignore`);
+  const head = `${dir} (${sorted.length} entr${sorted.length === 1 ? "y" : "ies"})`;
+  if (shown.length === 0) return `${head}: empty${notes.length ? ` (${notes.join("; ")})` : ""}`;
+  return `${head}\n${lines.join("\n")}${notes.length ? `\n(${notes.join("; ")})` : ""}`;
+}
+
+export const lsTool = {
+  name: "LS",
+  readOnly: true,
+  description:
+    "List the entries of one directory: each name with its type (dir, file, link) and a file's size in bytes. Not recursive. " +
+    "`path` is the directory (absolute, or relative to the working directory). `ignore` takes glob patterns matched against entry names, such as `*.log` or `node_modules`. " +
+    "Use Glob to find files by pattern across a tree.",
+  input_schema: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "The directory to list." },
+      ignore: { type: "array", items: { type: "string" }, description: "Glob patterns; entries whose name matches one are left out." },
+    },
+    required: ["path"],
+  },
+
+  /**
+   * @param {{path:string, ignore?:string[]}} input
+   * @param {import('./index.mjs').ToolContext} ctx
+   */
+  async run(input, ctx) {
+    const raw = typeof input.path === "string" ? input.path.trim() : "";
+    if (raw === "") return { ok: false, error: "path must name a directory" };
+    const dir = path.resolve(ctx.cwd, raw);
+    const ignore = Array.isArray(input.ignore) ? input.ignore.filter((g) => typeof g === "string" && g.trim() !== "").map((g) => g.trim()) : [];
+    if (ignore.length > MAX_IGNORE_PATTERNS) return { ok: false, error: `at most ${MAX_IGNORE_PATTERNS} ignore patterns` };
+    try {
+      if (!statSync(dir).isDirectory()) return { ok: false, error: `${dir} is not a directory. Use Read for a file.` };
+    } catch {
+      return { ok: false, error: `Directory does not exist: ${dir}` };
+    }
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch (e) {
+      return { ok: false, error: `Could not list ${dir}: ${e instanceof Error ? e.message : e}` };
+    }
+    /** @type {LsEntry[]} */
+    const entries = [];
+    let ignored = 0;
+    for (const name of names) {
+      if (ctx.signal?.aborted) return { ok: false, error: "LS was interrupted" };
+      if (ignore.some((g) => matchGlob(name, g.replace(/\/+$/, "")))) {
+        ignored++;
+        continue;
+      }
+      const full = path.join(dir, name);
+      try {
+        const st = lstatSync(full);
+        if (st.isSymbolicLink()) {
+          let target = null;
+          try {
+            target = readlinkSync(full);
+          } catch {
+            /* unreadable link: shown without a target */
+          }
+          entries.push({ name, type: "link", size: null, target });
+        } else if (st.isDirectory()) entries.push({ name, type: "dir", size: null, target: null });
+        else if (st.isFile()) entries.push({ name, type: "file", size: st.size, target: null });
+        else entries.push({ name, type: "other", size: null, target: null });
+      } catch {
+        entries.push({ name, type: "other", size: null, target: null }); // vanished between readdir and lstat
+      }
+    }
+    return { ok: true, content: formatListing(dir, entries, { ignored }) };
+  },
+};

package/lib/engine/tools/monitor.mjs

@@ -0,0 +1,82 @@
+/**
+ * lib/engine/tools/monitor.mjs — Monitor {command, description, persistent?, timeout_ms?}.
+ *
+ * Starts a background command (a background shell of kind "monitor", so
+ * BashOutput reads it and KillShell stops it) whose stdout lines become events
+ * for this session (session-runtime/notifications.mjs): they reach a running
+ * turn at its next model request, and an idle session starts a turn for them.
+ *
+ *   · persistent: runs until KillShell, its own exit, or the end of the session.
+ *   · otherwise: stopped after `timeout_ms` (default 5 minutes, at most 1 hour);
+ *     the stop is reported as an event.
+ *   · when it exits by itself, that is reported as an event (CF-50).
+ *
+ * Permissions: a mutating tool (needs an allow rule, bypass or an approval), and
+ * its command is also held to the Bash deny and ask rules — `Bash(rm:*)` in
+ * `permissions.deny` refuses a Monitor running `rm` just as it refuses Bash.
+ * Exists only in a `cohort session` (`sessionOnly`).
+ *
+ * @module lib/engine/tools/monitor
+ */
+
+import { monitorLineNotice } from "../session-runtime/notifications.mjs";
+
+export const MONITOR_DEFAULT_TIMEOUT_MS = 5 * 60_000;
+export const MONITOR_MAX_TIMEOUT_MS = 60 * 60_000;
+
+/**
+ * @param {{shells:ReturnType<typeof import('./bash-background.mjs').createShellManager>,
+ *          notices:ReturnType<typeof import('../session-runtime/notifications.mjs').createNotificationQueue>,
+ *          cwd:()=>string,
+ *          checkCommand?:((command:string)=>{behavior:'allow'|'deny'|'ask', reason:string})|null,
+ *          setTimer?:(fn:()=>void, ms:number)=>any}} o
+ */
+export function createMonitorTool({ shells, notices, cwd, checkCommand = null, setTimer = setTimeout }) {
+  return {
+    name: "Monitor",
+    readOnly: false,
+    sessionOnly: true,
+    description:
+      "Start a command in the background and receive each line it prints to stdout as an event message, while you keep working or wait. " +
+      "Use it to watch a log, a feed or a long build. Lines are delivered in batches between turns; when you are idle, new lines start a turn. " +
+      "Set `persistent` to keep it running until you stop it with KillShell (or the session ends); otherwise it is stopped after `timeout_ms` " +
+      `(default ${MONITOR_DEFAULT_TIMEOUT_MS / 60_000} minutes, at most ${MONITOR_MAX_TIMEOUT_MS / 60_000}). Its full output can be read with BashOutput. ` +
+      "Print only lines worth reacting to: every line becomes part of the conversation.",
+    input_schema: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "The shell command to run." },
+        description: { type: "string", description: "What it watches, in a few words (labels its events)." },
+        persistent: { type: "boolean", description: "Keep running until stopped with KillShell or the session ends." },
+        timeout_ms: { type: "number", description: `Stop after this many milliseconds (not persistent only; at most ${MONITOR_MAX_TIMEOUT_MS}).` },
+      },
+      required: ["command", "description"],
+    },
+    /** @param {{command:string, description:string, persistent?:boolean, timeout_ms?:number}} input */
+    async run(input) {
+      if (input.command.trim() === "") return { ok: false, error: "The command is empty." };
+      const verdict = checkCommand ? checkCommand(input.command) : null;
+      if (verdict && verdict.behavior !== "allow") {
+        return { ok: false, error: `Not started: the Bash permission rules do not let this command run (${verdict.reason}).` };
+      }
+      const description = input.description.trim() || "monitor";
+      /** @type {{id:string, description:string}} */
+      const m = { id: "", description };
+      const started = shells.start({ command: input.command, cwd: cwd(), description, kind: "monitor", onLine: (line) => notices.push(monitorLineNotice(m, line)) });
+      if (!started.ok) return started;
+      m.id = started.id;
+      let note = "It runs until you stop it with KillShell or the session ends.";
+      if (!input.persistent) {
+        const ms = Math.min(MONITOR_MAX_TIMEOUT_MS, Math.max(1, Math.round(input.timeout_ms ?? MONITOR_DEFAULT_TIMEOUT_MS)));
+        const t = setTimer(async () => {
+          if (shells.list().find((s) => s.id === m.id)?.status !== "running") return;
+          await shells.kill(m.id);
+          notices.push(`Monitor ${m.id} (${description}) was stopped after its ${ms} ms timeout.`);
+        }, ms);
+        t?.unref?.();
+        note = `It is stopped after ${ms} ms.`;
+      }
+      return { ok: true, content: `Monitor ${m.id} started: ${description}. Each stdout line arrives as an event. ${note} Stop it early with KillShell {"shell_id":"${m.id}"}.` };
+    },
+  };
+}

package/lib/engine/tools/notebook-edit.mjs

@@ -0,0 +1,218 @@
+/**
+ * lib/engine/tools/notebook-edit.mjs — Jupyter notebooks: the NotebookEdit tool
+ * and the rendering the Read tool uses for `.ipynb` files.
+ *
+ * Input contract: `{ notebook_path, cell_id?, new_source, cell_type?: code|markdown, edit_mode?: replace|insert|delete }`.
+ *   replace  (default) the source of `cell_id`; a `cell_type` changes the cell's type
+ *   insert   a new cell after `cell_id`, or first when no `cell_id`; needs `cell_type`
+ *   delete   the cell `cell_id` (`new_source` is ignored)
+ * A cell is named by its nbformat `id`, or by position as `cell-<n>` / `<n>` (0-based).
+ *
+ * The notebook must have been Read in this run and unchanged since (the Write
+ * and Edit rule). A code cell whose source changes loses its outputs and
+ * execution count, since they no longer describe it. New cells get an id when
+ * the notebook's format (4.5 and later) has cell ids. The file is written
+ * atomically as nbformat JSON (one-space indent, trailing newline).
+ *
+ * `parseNotebook`, `findCellIndex`, `applyNotebookEdit` and `renderNotebook` are pure.
+ *
+ * @module lib/engine/tools/notebook-edit
+ */
+
+import { randomBytes } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "../../fs-atomic.mjs";
+import { checkFresh } from "./write.mjs";
+
+export const MAX_RENDERED_OUTPUT_CHARS = 2_000;
+
+/**
+ * @param {string} text
+ * @returns {{ok:true, nb:any}|{ok:false, error:string}}
+ */
+export function parseNotebook(text) {
+  let nb;
+  try {
+    nb = JSON.parse(text);
+  } catch (e) {
+    return { ok: false, error: `not valid JSON (${e instanceof Error ? e.message : e})` };
+  }
+  if (!nb || typeof nb !== "object" || !Array.isArray(nb.cells)) return { ok: false, error: "not a Jupyter notebook (no cells array)" };
+  return { ok: true, nb };
+}
+
+/** @param {unknown} source */
+export function sourceText(source) {
+  return Array.isArray(source) ? source.join("") : typeof source === "string" ? source : "";
+}
+
+/** nbformat stores source as lines that keep their newlines. @param {string} text */
+export function toSourceLines(text) {
+  return text === "" ? [] : text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+
+/** @param {any} nb @param {string} cellId */
+export function findCellIndex(nb, cellId) {
+  const id = String(cellId).trim();
+  const byId = nb.cells.findIndex((/** @type any */ c) => c && c.id === id);
+  if (byId !== -1) return byId;
+  const m = /^(?:cell-)?(\d+)$/.exec(id);
+  if (m) {
+    const n = Number(m[1]);
+    return n < nb.cells.length ? n : -1;
+  }
+  return -1;
+}
+
+/** @param {any} nb */
+function hasCellIds(nb) {
+  return Number(nb.nbformat) > 4 || (Number(nb.nbformat) === 4 && Number(nb.nbformat_minor) >= 5);
+}
+
+/**
+ * @param {any} nb
+ * @param {{cell_id?:string, new_source?:string, cell_type?:string, edit_mode?:string}} input
+ * @param {{newCellId:()=>string}} o
+ * @returns {{ok:true, nb:any, summary:string}|{ok:false, error:string}}
+ */
+export function applyNotebookEdit(nb, input, { newCellId }) {
+  const mode = input.edit_mode ?? "replace";
+  const cells = [...nb.cells];
+  const type = input.cell_type;
+  if (type !== undefined && type !== "code" && type !== "markdown") return { ok: false, error: `cell_type must be code or markdown, got "${type}"` };
+  const source = typeof input.new_source === "string" ? input.new_source : "";
+  const locate = () => {
+    if (input.cell_id === undefined || input.cell_id === "") return { ok: false, error: `edit_mode ${mode} needs a cell_id` };
+    const i = findCellIndex(nb, input.cell_id);
+    if (i === -1) return { ok: false, error: `no cell "${input.cell_id}" (the notebook has ${cells.length} cells; use a cell id or cell-<n>)` };
+    return { ok: true, i };
+  };
+
+  if (mode === "delete") {
+    const at = locate();
+    if (!at.ok) return at;
+    cells.splice(at.i, 1);
+    return { ok: true, nb: { ...nb, cells }, summary: `Deleted cell ${input.cell_id}.` };
+  }
+  if (mode === "insert") {
+    if (!type) return { ok: false, error: "edit_mode insert needs a cell_type (code or markdown)" };
+    let index = 0;
+    if (input.cell_id !== undefined && input.cell_id !== "") {
+      const at = locate();
+      if (!at.ok) return at;
+      index = at.i + 1;
+    }
+    /** @type any */
+    const cell = { cell_type: type, metadata: {}, source: toSourceLines(source) };
+    if (hasCellIds(nb)) cell.id = newCellId();
+    if (type === "code") Object.assign(cell, { execution_count: null, outputs: [] });
+    cells.splice(index, 0, cell);
+    return { ok: true, nb: { ...nb, cells }, summary: `Inserted a ${type} cell at position ${index}${cell.id ? ` (id ${cell.id})` : ""}.` };
+  }
+  if (mode !== "replace") return { ok: false, error: `edit_mode must be replace, insert or delete, got "${mode}"` };
+  const at = locate();
+  if (!at.ok) return at;
+  const old = cells[at.i];
+  const nextType = type ?? old.cell_type;
+  /** @type any */
+  const cell = { ...old, cell_type: nextType, source: toSourceLines(source) };
+  if (nextType === "code") {
+    cell.outputs = [];
+    cell.execution_count = null;
+  } else {
+    delete cell.outputs;
+    delete cell.execution_count;
+  }
+  cells[at.i] = cell;
+  return { ok: true, nb: { ...nb, cells }, summary: `Replaced the source of cell ${input.cell_id}${type && type !== old.cell_type ? ` and changed it to ${type}` : ""}.` };
+}
+
+/** @param {any} nb */
+export function serializeNotebook(nb) {
+  return `${JSON.stringify(nb, null, 1)}\n`;
+}
+
+/** @param {string} s */
+function clipOutput(s) {
+  const t = s.replace(/\x1b\[[0-9;]*m/g, "");
+  return t.length <= MAX_RENDERED_OUTPUT_CHARS ? t : `${t.slice(0, MAX_RENDERED_OUTPUT_CHARS)}… [output truncated]`;
+}
+
+/** @param {any} o */
+function renderOutput(o) {
+  if (!o || typeof o !== "object") return "";
+  if (o.output_type === "stream") return clipOutput(sourceText(o.text));
+  if (o.output_type === "error") return clipOutput(`${o.ename}: ${o.evalue}${Array.isArray(o.traceback) ? `\n${o.traceback.join("\n")}` : ""}`);
+  const data = o.data && typeof o.data === "object" ? o.data : {};
+  if (data["text/plain"] !== undefined) return clipOutput(sourceText(data["text/plain"]));
+  const kinds = Object.keys(data);
+  return kinds.length ? `[${kinds.join(", ")} output not shown]` : "";
+}
+
+/**
+ * The notebook as text for the model: each cell with its position, id and
+ * type, its source, and its text outputs.
+ * @param {any} nb @param {string} file
+ */
+export function renderNotebook(nb, file) {
+  const lang = nb.metadata?.language_info?.name ?? nb.metadata?.kernelspec?.language ?? null;
+  const parts = [`Notebook ${file}: ${nb.cells.length} cell${nb.cells.length === 1 ? "" : "s"}${lang ? `, ${lang}` : ""}. Name cells for NotebookEdit by id or as cell-<n>.`];
+  nb.cells.forEach((/** @type any */ c, /** @type number */ i) => {
+    const head = [`cell-${i}`, c.id ? `id ${c.id}` : null, c.cell_type, c.execution_count != null ? `execution_count ${c.execution_count}` : null].filter(Boolean).join(" · ");
+    const body = [`[${head}]`, sourceText(c.source)];
+    const outputs = Array.isArray(c.outputs) ? c.outputs.map(renderOutput).filter(Boolean) : [];
+    if (outputs.length) body.push(`[outputs of cell-${i}]`, ...outputs);
+    parts.push(body.join("\n"));
+  });
+  return parts.join("\n\n");
+}
+
+export const notebookEditTool = {
+  name: "NotebookEdit",
+  readOnly: false,
+  description:
+    "Change one cell of a Jupyter notebook (.ipynb): replace a cell's source, insert a new cell, or delete a cell. `notebook_path` must be absolute, " +
+    "and the notebook must be Read first. Name the cell by the id or cell-<n> label that Read shows. insert places the new cell after `cell_id` " +
+    "(or first, without one) and needs `cell_type`.",
+  input_schema: {
+    type: "object",
+    properties: {
+      notebook_path: { type: "string", description: "Absolute path of the .ipynb file." },
+      cell_id: { type: "string", description: "The cell to change, or the cell to insert after." },
+      new_source: { type: "string", description: "The new source of the cell." },
+      cell_type: { type: "string", enum: ["code", "markdown"], description: "The cell type; required for insert." },
+      edit_mode: { type: "string", enum: ["replace", "insert", "delete"], description: "Defaults to replace." },
+    },
+    required: ["notebook_path", "new_source"],
+  },
+
+  /**
+   * @param {{notebook_path:string, cell_id?:string, new_source:string, cell_type?:string, edit_mode?:string}} input
+   * @param {import('./index.mjs').ToolContext} ctx
+   */
+  async run(input, ctx) {
+    const file = input.notebook_path;
+    if (!path.isAbsolute(file)) return { ok: false, error: `notebook_path must be absolute, got "${file}"` };
+    if (path.extname(file) !== ".ipynb") return { ok: false, error: `${file} is not a .ipynb notebook; use Edit for other files.` };
+    let st;
+    try {
+      st = statSync(file);
+    } catch {
+      return { ok: false, error: `Notebook does not exist: ${file}` };
+    }
+    const fresh = checkFresh(file, st, ctx.fileState);
+    if (!fresh.ok) return fresh;
+    const parsed = parseNotebook(readFileSync(file, "utf8"));
+    if (!parsed.ok) return { ok: false, error: `${file}: ${parsed.error}` };
+    const edited = applyNotebookEdit(parsed.nb, input, { newCellId: () => randomBytes(4).toString("hex") });
+    if (!edited.ok) return { ok: false, error: edited.error };
+    try {
+      writeFileAtomic(file, serializeNotebook(edited.nb), { mode: st.mode & 0o7777 });
+    } catch (e) {
+      return { ok: false, error: `Could not write ${file}: ${e instanceof Error ? e.message : e}` };
+    }
+    ctx.fileState.set(file, { mtimeMs: statSync(file).mtimeMs });
+    return { ok: true, content: `${edited.summary} ${file} now has ${edited.nb.cells.length} cells.` };
+  },
+};

package/lib/engine/tools/read.mjs

@@ -0,0 +1,103 @@
+/**
+ * lib/engine/tools/read.mjs — the Read tool.
+ *
+ * Input contract (compatible name and schema): `{ file_path, offset?, limit? }`.
+ * Output: the selected lines, each prefixed with its 1-based line number and a
+ * tab, so the model can cite and edit by line. Records the file's mtime in the
+ * run's file state, which is what lets Edit and Write refuse to change a file
+ * the model has not looked at (or that changed underneath it).
+ *
+ * @module lib/engine/tools/read
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { parseNotebook, renderNotebook } from "./notebook-edit.mjs";
+
+export const DEFAULT_LINE_LIMIT = 2000;
+export const MAX_LINE_CHARS = 2000;
+export const MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Render a slice of text as numbered lines (pure).
+ * @param {string} text
+ * @param {number} offset 1-based first line
+ * @param {number} limit
+ * @returns {{ body: string, totalLines: number, shown: number }}
+ */
+export function renderNumbered(text, offset, limit) {
+  const lines = text.split(/\r?\n/);
+  if (lines.length > 0 && lines[lines.length - 1] === "" && text.endsWith("\n")) lines.pop();
+  const start = Math.max(1, offset);
+  const slice = lines.slice(start - 1, start - 1 + limit);
+  const width = String(start + slice.length - 1).length;
+  const body = slice
+    .map((l, i) => {
+      const n = String(start + i).padStart(Math.max(6, width), " ");
+      const content = l.length > MAX_LINE_CHARS ? `${l.slice(0, MAX_LINE_CHARS)}… [line truncated]` : l;
+      return `${n}\t${content}`;
+    })
+    .join("\n");
+  return { body, totalLines: lines.length, shown: slice.length };
+}
+
+export const readTool = {
+  name: "Read",
+  readOnly: true,
+  description:
+    "Read a text file from the local filesystem. `file_path` must be absolute. Output lists each line with its line number. " +
+    `Reads up to ${DEFAULT_LINE_LIMIT} lines from the start by default; pass \`offset\` (1-based line) and \`limit\` to page through longer files. ` +
+    "Read a file before changing it with Edit or overwriting it with Write. Use Glob to find a file and Bash `ls` to list a directory.",
+  input_schema: {
+    type: "object",
+    properties: {
+      file_path: { type: "string", description: "Absolute path of the file to read." },
+      offset: { type: "integer", minimum: 1, description: "1-based line number to start from." },
+      limit: { type: "integer", minimum: 1, description: "Maximum number of lines to return." },
+    },
+    required: ["file_path"],
+  },
+
+  /**
+   * @param {{file_path:string, offset?:number, limit?:number}} input
+   * @param {import('./index.mjs').ToolContext} ctx
+   */
+  async run(input, ctx) {
+    const file = input.file_path;
+    if (!path.isAbsolute(file)) return { ok: false, error: `file_path must be absolute, got "${file}"` };
+    let st;
+    try {
+      st = statSync(file);
+    } catch {
+      return { ok: false, error: `File does not exist: ${file}` };
+    }
+    if (st.isDirectory()) return { ok: false, error: `${file} is a directory. Use Glob or Bash ls to list it.` };
+    if (st.size > MAX_FILE_BYTES && input.offset === undefined && input.limit === undefined) {
+      return { ok: false, error: `${file} is ${st.size} bytes; pass offset and limit to read part of it.` };
+    }
+    let buf;
+    try {
+      buf = readFileSync(file);
+    } catch (e) {
+      return { ok: false, error: `Could not read ${file}: ${e instanceof Error ? e.message : e}` };
+    }
+    if (buf.subarray(0, 8192).includes(0)) {
+      return { ok: false, error: `${file} appears to be a binary file and cannot be shown as text.` };
+    }
+    ctx.fileState.set(file, { mtimeMs: st.mtimeMs });
+    if (buf.length === 0) return { ok: true, content: `(${file} exists but is empty)` };
+    if (file.endsWith(".ipynb")) {
+      const nb = parseNotebook(buf.toString("utf8"));
+      if (nb.ok) return { ok: true, content: renderNotebook(nb.nb, file) }; // otherwise shown as text below
+    }
+    const offset = input.offset ?? 1;
+    const limit = input.limit ?? DEFAULT_LINE_LIMIT;
+    const { body, totalLines, shown } = renderNumbered(buf.toString("utf8"), offset, limit);
+    if (shown === 0) {
+      return { ok: true, content: `(offset ${offset} is past the end of ${file}, which has ${totalLines} lines)` };
+    }
+    const last = offset + shown - 1;
+    const tail = last < totalLines ? `\n\n(showing lines ${offset}-${last} of ${totalLines}; use offset to read more)` : "";
+    return { ok: true, content: body + tail };
+  },
+};