@ikarmic/forge-core 4.4.0 → 5.0.0

package/dist/tools/list-files.d.ts

@@ -6,6 +6,7 @@ declare const params: z.ZodObject<{
     max_entries: z.ZodOptional<z.ZodNumber>;
     /** Include dotfiles. Default false. */
     include_hidden: z.ZodOptional<z.ZodBoolean>;
+    include_ignored: z.ZodOptional<z.ZodBoolean>;
     /** Recurse into subdirectories. Default false. */
     recursive: z.ZodOptional<z.ZodBoolean>;
     /** Max recursion depth when recursive=true. Default 4. */
@@ -15,12 +16,14 @@ declare const params: z.ZodObject<{
     recursive?: boolean | undefined;
     max_entries?: number | undefined;
     include_hidden?: boolean | undefined;
+    include_ignored?: boolean | undefined;
     max_depth?: number | undefined;
 }, {
     path?: string | undefined;
     recursive?: boolean | undefined;
     max_entries?: number | undefined;
     include_hidden?: boolean | undefined;
+    include_ignored?: boolean | undefined;
     max_depth?: number | undefined;
 }>;
 export interface ListEntry {
@@ -35,4 +38,3 @@ export interface ListFilesResult {
 }
 export declare const listFilesTool: ToolDefinition<z.infer<typeof params>, ListFilesResult>;
 export {};
-//# sourceMappingURL=list-files.d.ts.map

package/dist/tools/list-files.js

@@ -1,6 +1,7 @@
 import { readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
+import { IgnoreRules } from './ignore-rules.js';
 import { resolveAndCheckPath, DEFAULT_IGNORED_DIRS } from './shared.js';
 const params = z.object({
     path: z
@@ -11,6 +12,10 @@ const params = z.object({
     max_entries: z.number().int().positive().max(5000).optional().describe('Maximum entries to return.'),
     /** Include dotfiles. Default false. */
     include_hidden: z.boolean().optional().describe('Include dotfiles (entries starting with ".").'),
+    include_ignored: z
+        .boolean()
+        .optional()
+        .describe('Also list paths matched by .gitignore / .forgeignore (skipped by default).'),
     /** Recurse into subdirectories. Default false. */
     recursive: z.boolean().optional().describe('Recurse into subdirectories.'),
     /** Max recursion depth when recursive=true. Default 4. */
@@ -24,6 +29,7 @@ export const listFilesTool = {
         const root = resolveAndCheckPath(args.path ?? '.', ctx);
         const maxEntries = args.max_entries ?? 500;
         const includeHidden = args.include_hidden ?? false;
+        const rules = args.include_ignored ? null : IgnoreRules.forRoot(ctx.cwd);
         const recursive = args.recursive ?? false;
         const maxDepth = args.max_depth ?? 4;
         const out = [];
@@ -53,6 +59,8 @@ export const listFilesTool = {
                 if (DEFAULT_IGNORED_DIRS.has(entry.name))
                     continue;
                 const abs = path.join(dir, entry.name);
+                if (rules?.isIgnored(abs, entry.isDirectory()))
+                    continue;
                 if (entry.isDirectory()) {
                     out.push({ path: abs, type: 'directory' });
                     if (recursive && depth < maxDepth) {
@@ -77,4 +85,3 @@ export const listFilesTool = {
         return { path: root, entries: out, truncated };
     },
 };
-//# sourceMappingURL=list-files.js.map

package/dist/tools/list-symbols.d.ts

@@ -19,4 +19,3 @@ export interface ListSymbolsResult {
 }
 export declare const listSymbolsTool: ToolDefinition<z.infer<typeof params>, ListSymbolsResult>;
 export {};
-//# sourceMappingURL=list-symbols.d.ts.map

package/dist/tools/list-symbols.js

@@ -23,4 +23,3 @@ export const listSymbolsTool = {
         return { path: rel, symbols: topLevel };
     },
 };
-//# sourceMappingURL=list-symbols.js.map

package/dist/tools/memory.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type MemoryType } from '../memory/memory-store.js';
 import type { ToolDefinition } from '../types.js';
 declare const readParams: z.ZodObject<{
     /**
@@ -27,21 +28,32 @@ export interface MemoryReadResult {
     empty: boolean;
 }
 export declare const memoryReadTool: ToolDefinition<z.infer<typeof readParams>, MemoryReadResult>;
+/** Longest body `memory_write` accepts. Memory holds short facts, not documents. */
+export declare const MAX_BODY_CHARS = 1200;
 declare const writeParams: z.ZodObject<{
     /** Where to write: 'project' (default) or 'global'. */
     scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
-    /** Section heading. If the heading already exists, replaces its body. */
+    /** Section heading. If the heading already exists (ignoring case and spacing), replaces its body. */
     heading: z.ZodString;
     /** Section body. Markdown allowed. */
     body: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<["convention", "decision", "correction", "reference"]>>;
+    refs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    pin: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     body: string;
     heading: string;
+    type?: "reference" | "convention" | "decision" | "correction" | undefined;
     scope?: "project" | "global" | undefined;
+    refs?: string[] | undefined;
+    pin?: boolean | undefined;
 }, {
     body: string;
     heading: string;
+    type?: "reference" | "convention" | "decision" | "correction" | undefined;
     scope?: "project" | "global" | undefined;
+    refs?: string[] | undefined;
+    pin?: boolean | undefined;
 }>;
 export interface MemoryWriteResult {
     scope: 'project' | 'global';
@@ -49,7 +61,27 @@ export interface MemoryWriteResult {
     heading: string;
     replaced: boolean;
     bytes: number;
+    type: MemoryType;
+    /** Headings removed to keep the file under the size cap. */
+    dropped: string[];
+    /** Unified diff of the file change. */
+    diff: string;
 }
 export declare const memoryWriteTool: ToolDefinition<z.infer<typeof writeParams>, MemoryWriteResult>;
+declare const forgetParams: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
+    heading: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    heading: string;
+    scope?: "project" | "global" | undefined;
+}, {
+    heading: string;
+    scope?: "project" | "global" | undefined;
+}>;
+export interface MemoryForgetResult {
+    scope: 'project' | 'global';
+    heading: string;
+    removed: boolean;
+}
+export declare const memoryForgetTool: ToolDefinition<z.infer<typeof forgetParams>, MemoryForgetResult>;
 export {};
-//# sourceMappingURL=memory.d.ts.map

package/dist/tools/memory.js

@@ -1,5 +1,8 @@
+import path from 'node:path';
 import { z } from 'zod';
-import { composeSectionUpdate, findProjectMemoryRoot, globalMemoryPath, loadMemory, projectMemoryPath, readMemoryFile, writeMemoryFile, } from '../memory/memory-store.js';
+import { computeUnifiedDiff } from '../diff/unified-diff.js';
+import { DEFAULT_MAX_BYTES, capMemory, composeSectionUpdate, findProjectMemoryRoot, globalMemoryPath, loadMemory, normalizeHeading, parseMemory, projectMemoryPath, readMemoryFile, removeSection, writeMemoryFile, } from '../memory/memory-store.js';
+import { redact } from './redact.js';
 /**
  * Resolve the project memory file path from the agent's cwd. Returns null
  * when no project memory root is found (the tool then falls back to the
@@ -81,42 +84,131 @@ export const memoryReadTool = {
         return { scope: 'both', content, empty: content.length === 0 };
     },
 };
+/** Longest body `memory_write` accepts. Memory holds short facts, not documents. */
+export const MAX_BODY_CHARS = 1200;
+const MEMORY_TYPES = ['convention', 'decision', 'correction', 'reference'];
 const writeParams = z.object({
     /** Where to write: 'project' (default) or 'global'. */
     scope: z.enum(['project', 'global']).optional().describe('Which memory file to write to. Default "project".'),
-    /** Section heading. If the heading already exists, replaces its body. */
-    heading: z.string().min(1).describe('Section heading (e.g. "Build commands"). Replaces an existing section with the same name.'),
+    /** Section heading. If the heading already exists (ignoring case and spacing), replaces its body. */
+    heading: z.string().min(1).describe('Specific one-line heading (e.g. "Package manager"). Replaces an existing section with the same name.'),
     /** Section body. Markdown allowed. */
-    body: z.string().describe('Section body in markdown.'),
+    body: z.string().describe(`One fact in markdown, under ${MAX_BODY_CHARS} characters. No "## " lines.`),
+    type: z
+        .enum(MEMORY_TYPES)
+        .optional()
+        .describe('convention (how the project is built/styled, default), decision (a choice and its reason), correction (something the user told you not to do), reference (where to find something outside the repo).'),
+    refs: z
+        .array(z.string())
+        .optional()
+        .describe('Relative paths (or path#symbol) this entry depends on, so Forge can flag it stale when they disappear.'),
+    pin: z.boolean().optional().describe('Always include this section in the prompt. Use sparingly: pins share a 2 KB budget.'),
 });
+function reject(reason) {
+    throw new Error(`memory_write rejected: ${reason}`);
+}
+/** Validate and compose a write without touching disk. Throws `memory_write rejected: ...`. */
+async function planWrite(args, ctx) {
+    const scope = args.scope ?? 'project';
+    // Trim once, up front, so the "was this a replace?" check and
+    // composeSectionUpdate's own heading-match agree: otherwise incidental
+    // whitespace in args.heading makes a heading never match its own
+    // previously-written section, and duplicates accumulate.
+    const heading = args.heading.trim();
+    if (/[\r\n]/.test(heading))
+        reject('heading must be a single line');
+    const maxBody = ctx.memoryMaxBodyChars ?? MAX_BODY_CHARS;
+    if (args.body.length > maxBody) {
+        reject(`body is ${args.body.length} characters; the limit is ${maxBody}. Summarize it or split it into separate sections.`);
+    }
+    const secrets = redact(`${heading}\n${args.body}`);
+    if (secrets.total > 0) {
+        reject(`content looks like a secret (${Object.keys(secrets.counts).join(', ')}); never store credentials in memory`);
+    }
+    if (/^##\s/m.test(args.body)) {
+        reject('a body line starts with "## ", which would create a separate section; write each section with its own memory_write call');
+    }
+    for (const ref of args.refs ?? []) {
+        if (path.isAbsolute(ref) || ref.split(/[\\/]/).includes('..')) {
+            reject(`refs must be relative paths inside the project (got "${ref}")`);
+        }
+        // These would split or end the one-line metadata comment the refs are stored in.
+        if (/[,;\r\n]|-->/.test(ref)) {
+            reject(`refs cannot contain ",", ";", "-->" or a line break (got "${ref}")`);
+        }
+    }
+    const targetPath = scope === 'global' ? globalMemoryPath() : (await resolveProjectMemoryPath(ctx.cwd)) ?? projectMemoryPath(ctx.cwd);
+    const current = await readMemoryFile(targetPath);
+    const wanted = normalizeHeading(heading);
+    const existing = parseMemory(current, targetPath, 0).find((s) => normalizeHeading(s.heading) === wanted);
+    const replaced = existing !== undefined;
+    // A rewrite that leaves type/refs/pin out keeps what the section already had.
+    const type = args.type ?? existing?.type ?? 'convention';
+    const refs = args.refs ?? existing?.refs ?? [];
+    const pinned = args.pin ?? existing?.pinned ?? false;
+    const composed = composeSectionUpdate(current, heading, args.body, {
+        type,
+        ...(refs.length > 0 ? { refs } : {}),
+        ...(pinned ? { pinned: true } : {}),
+    });
+    const { content: updated, dropped } = capMemory(composed, DEFAULT_MAX_BYTES, heading);
+    return { scope, targetPath, current, updated, heading, type, replaced, dropped };
+}
+function fileDiff(before, after) {
+    return computeUnifiedDiff(before, after, { filePath: 'MEMORY.md', contextLines: 1 }).text;
+}
 export const memoryWriteTool = {
     name: 'memory_write',
-    description: "Write or replace a section of the project's memory file (`.forge/MEMORY.md`). Use to record project conventions the agent should remember across sessions: build commands, code style, deployment steps, etc. If the heading already exists, its body is replaced; otherwise the section is appended.",
+    description: "Write or replace one section of the project's memory file (`.forge/MEMORY.md`), kept across sessions. SAVE: a correction or preference the user stated for the future, a non-obvious project convention, the reason behind a decision, a pointer to an external resource. DO NOT SAVE: anything derivable from the code or git history, one-off task details or run progress, secrets or credentials. One fact per section, a specific heading, short body; replace an existing section instead of adding a near-duplicate. Use `memory_forget` to remove an entry that is wrong.",
     parameters: writeParams,
+    previewApproval: async (args, ctx) => {
+        try {
+            const plan = await planWrite(args, ctx);
+            const note = plan.dropped.length > 0 ? `\n(size cap: would also remove ${plan.dropped.join(', ')})` : '';
+            return fileDiff(plan.current, plan.updated) + note;
+        }
+        catch (err) {
+            return err instanceof Error ? err.message : String(err);
+        }
+    },
     execute: async (args, ctx) => {
-        const scope = args.scope ?? 'project';
-        // Trim once, up front, so the "was this a replace?" check and
-        // composeSectionUpdate's own heading-match agree: otherwise incidental
-        // whitespace in args.heading makes a heading never match its own
-        // previously-written section, and duplicates accumulate.
-        const heading = args.heading.trim();
-        const targetPath = scope === 'global'
-            ? globalMemoryPath()
-            : (await resolveProjectMemoryPath(ctx.cwd)) ?? projectMemoryPath(ctx.cwd);
-        const current = await readMemoryFile(targetPath);
-        const replaced = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`, 'm').test(current);
-        const updated = composeSectionUpdate(current, heading, args.body);
-        await writeMemoryFile(targetPath, updated);
+        const plan = await planWrite(args, ctx);
+        await writeMemoryFile(plan.targetPath, plan.updated);
         return {
-            scope,
-            path: targetPath,
-            heading,
-            replaced,
-            bytes: Buffer.byteLength(updated, 'utf8'),
+            scope: plan.scope,
+            path: plan.targetPath,
+            heading: plan.heading,
+            replaced: plan.replaced,
+            bytes: Buffer.byteLength(plan.updated, 'utf8'),
+            type: plan.type,
+            dropped: plan.dropped,
+            diff: fileDiff(plan.current, plan.updated),
         };
     },
 };
-function escapeRegExp(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const forgetParams = z.object({
+    scope: z.enum(['project', 'global']).optional().describe('Which memory file to edit. Default "project".'),
+    heading: z.string().min(1).describe('Heading of the section to remove (case and spacing ignored).'),
+});
+async function planForget(args, ctx) {
+    const scope = args.scope ?? 'project';
+    const targetPath = scope === 'global' ? globalMemoryPath() : (await resolveProjectMemoryPath(ctx.cwd)) ?? projectMemoryPath(ctx.cwd);
+    const current = await readMemoryFile(targetPath);
+    return { scope, targetPath, current, ...removeSection(current, args.heading) };
 }
-//# sourceMappingURL=memory.js.map
+export const memoryForgetTool = {
+    name: 'memory_forget',
+    destructive: true,
+    description: "Remove one section from the project's memory file (`.forge/MEMORY.md`). Use it to retire an entry the user says is wrong or that no longer applies.",
+    parameters: forgetParams,
+    previewApproval: async (args, ctx) => {
+        const plan = await planForget(args, ctx);
+        return plan.removed ? fileDiff(plan.current, plan.content) : `No section named "${args.heading.trim()}".`;
+    },
+    execute: async (args, ctx) => {
+        const plan = await planForget(args, ctx);
+        if (plan.removed)
+            await writeMemoryFile(plan.targetPath, plan.content);
+        return { scope: plan.scope, heading: args.heading.trim(), removed: plan.removed };
+    },
+};

package/dist/tools/notebook.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+type CellType = 'code' | 'markdown' | 'raw';
+interface Cell {
+    cell_type: CellType;
+    id?: string;
+    metadata?: Record<string, unknown>;
+    source: string | string[];
+    outputs?: unknown[];
+    execution_count?: number | null;
+    [key: string]: unknown;
+}
+interface Notebook {
+    cells: Cell[];
+    nbformat?: number;
+    nbformat_minor?: number;
+    metadata?: {
+        language_info?: {
+            name?: string;
+        };
+        kernelspec?: {
+            language?: string;
+        };
+    };
+    [key: string]: unknown;
+}
+export declare function isNotebookPath(p: string): boolean;
+export declare function parseNotebook(text: string): {
+    nb: Notebook;
+    indent: number;
+    trailingNewline: boolean;
+};
+export declare function sourceText(source: string | string[] | undefined): string;
+/** Jupyter's on-disk form: one string per line, each but the last keeping its newline. */
+export declare function toSourceLines(text: string): string[];
+/** One output as text: streams and text/plain as is, errors as name and message, rich media named only. */
+export declare function outputText(output: unknown): string;
+/** The notebook as numbered cells for the model to read. */
+export declare function renderNotebook(nb: Notebook): string;
+declare const params: z.ZodObject<{
+    path: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<["replace", "insert", "delete"]>>;
+    cell_index: z.ZodOptional<z.ZodNumber>;
+    cell_id: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    cell_type: z.ZodOptional<z.ZodEnum<["code", "markdown", "raw"]>>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    source?: string | undefined;
+    cell_type?: "code" | "raw" | "markdown" | undefined;
+    mode?: "replace" | "insert" | "delete" | undefined;
+    cell_index?: number | undefined;
+    cell_id?: string | undefined;
+}, {
+    path: string;
+    source?: string | undefined;
+    cell_type?: "code" | "raw" | "markdown" | undefined;
+    mode?: "replace" | "insert" | "delete" | undefined;
+    cell_index?: number | undefined;
+    cell_id?: string | undefined;
+}>;
+export interface EditNotebookResult {
+    path: string;
+    mode: 'replace' | 'insert' | 'delete';
+    cellIndex: number;
+    cells: number;
+}
+export declare const editNotebookTool: ToolDefinition<z.infer<typeof params>, EditNotebookResult>;
+export {};

package/dist/tools/notebook.js

@@ -0,0 +1,163 @@
+/**
+ * Jupyter notebooks (`.ipynb`). `read_file` shows a notebook as numbered cells
+ * (source plus a short text form of each output, never base64 images), and the
+ * `edit_notebook` tool replaces, inserts or deletes one cell while keeping the rest
+ * of the JSON (metadata, other cells' outputs, the file's indentation) as it was.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import { resolveAndCheckPath } from './shared.js';
+const OUTPUT_MAX = 2_000;
+export function isNotebookPath(p) {
+    return p.toLowerCase().endsWith('.ipynb');
+}
+export function parseNotebook(text) {
+    let nb;
+    try {
+        nb = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`not a valid notebook (bad JSON: ${err.message})`);
+    }
+    if (!nb || typeof nb !== 'object' || !Array.isArray(nb.cells))
+        throw new Error('not a valid notebook (no cells array)');
+    // Jupyter writes one space per level; keep whatever the file uses.
+    const indent = /^\{\r?\n( +)"/.exec(text)?.[1]?.length ?? 1;
+    return { nb: nb, indent, trailingNewline: text.endsWith('\n') };
+}
+export function sourceText(source) {
+    return Array.isArray(source) ? source.join('') : (source ?? '');
+}
+/** Jupyter's on-disk form: one string per line, each but the last keeping its newline. */
+export function toSourceLines(text) {
+    if (text === '')
+        return [];
+    const lines = text.split('\n');
+    return lines.map((l, i) => (i < lines.length - 1 ? `${l}\n` : l)).filter((l) => l !== '');
+}
+function clip(text) {
+    return text.length > OUTPUT_MAX ? `${text.slice(0, OUTPUT_MAX)}\n… (${text.length - OUTPUT_MAX} more characters)` : text;
+}
+/** One output as text: streams and text/plain as is, errors as name and message, rich media named only. */
+export function outputText(output) {
+    if (!output || typeof output !== 'object')
+        return '';
+    const o = output;
+    if (o.output_type === 'stream')
+        return clip(sourceText(o.text));
+    if (o.output_type === 'error')
+        return `${o.ename ?? 'Error'}: ${o.evalue ?? ''}`;
+    const data = o.data ?? {};
+    const plain = data['text/plain'];
+    const media = Object.keys(data).filter((k) => k !== 'text/plain');
+    const parts = [];
+    if (plain !== undefined)
+        parts.push(clip(sourceText(plain)));
+    if (media.length > 0)
+        parts.push(`[${media.join(', ')} output]`);
+    return parts.join('\n');
+}
+/** The notebook as numbered cells for the model to read. */
+export function renderNotebook(nb) {
+    const lang = nb.metadata?.language_info?.name ?? nb.metadata?.kernelspec?.language ?? 'python';
+    const blocks = nb.cells.map((cell, i) => {
+        const head = `### cell ${i} (${cell.cell_type}${cell.id ? `, id ${cell.id}` : ''})`;
+        const fence = cell.cell_type === 'code' ? lang : cell.cell_type === 'markdown' ? 'markdown' : '';
+        const outputs = (cell.outputs ?? []).map(outputText).filter((t) => t.trim().length > 0);
+        const out = outputs.length > 0 ? `\nOutput:\n${outputs.join('\n')}` : '';
+        return `${head}\n\`\`\`${fence}\n${sourceText(cell.source)}\n\`\`\`${out}`;
+    });
+    return `Notebook with ${nb.cells.length} cell${nb.cells.length === 1 ? '' : 's'} (language: ${lang}). Edit cells with edit_notebook.\n\n${blocks.join('\n\n')}`;
+}
+function newCellId() {
+    return randomBytes(4).toString('hex');
+}
+function findCell(nb, index, id) {
+    if (id !== undefined) {
+        const at = nb.cells.findIndex((c) => c.id === id);
+        if (at === -1)
+            throw new Error(`no cell with id ${id}`);
+        return at;
+    }
+    if (index === undefined)
+        throw new Error('give cell_index or cell_id');
+    if (index < 0 || index >= nb.cells.length)
+        throw new Error(`cell_index ${index} is out of range (0-${nb.cells.length - 1})`);
+    return index;
+}
+const params = z.object({
+    path: z.string().describe('Path of the .ipynb file.'),
+    mode: z
+        .enum(['replace', 'insert', 'delete'])
+        .optional()
+        .describe('replace (default) a cell\'s source, insert a new cell, or delete a cell.'),
+    cell_index: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('0-based cell number, as read_file shows it. For insert: the new cell goes at this position (default: the end).'),
+    cell_id: z.string().optional().describe('The cell id instead of cell_index (for insert: the new cell goes after it).'),
+    source: z.string().optional().describe('The new cell source (replace and insert).'),
+    cell_type: z.enum(['code', 'markdown', 'raw']).optional().describe('Type for an inserted cell (default code), or to change a replaced cell\'s type.'),
+});
+export const editNotebookTool = {
+    name: 'edit_notebook',
+    description: 'Edit a Jupyter notebook (.ipynb) one cell at a time: replace a cell\'s source, insert a new cell, or delete one. Read the notebook with read_file first to see the cell numbers. Outputs of an edited code cell are cleared; everything else in the file is kept.',
+    parameters: params,
+    destructive: false,
+    execute: async (args, ctx) => {
+        if (!isNotebookPath(args.path))
+            throw new Error(`${args.path} is not a .ipynb file; use edit_file for other files`);
+        const resolved = resolveAndCheckPath(args.path, ctx);
+        const text = await readFile(resolved, 'utf8').catch((err) => {
+            if (err.code === 'ENOENT')
+                throw new Error(`File not found: ${args.path}`);
+            throw err;
+        });
+        const { nb, indent, trailingNewline } = parseNotebook(text);
+        const mode = args.mode ?? 'replace';
+        const withIds = (nb.nbformat ?? 4) > 4 || ((nb.nbformat ?? 4) === 4 && (nb.nbformat_minor ?? 0) >= 5);
+        let at;
+        if (mode === 'insert') {
+            if (args.source === undefined)
+                throw new Error('insert needs source');
+            at = args.cell_id !== undefined ? findCell(nb, undefined, args.cell_id) + 1 : Math.min(args.cell_index ?? nb.cells.length, nb.cells.length);
+            const type = args.cell_type ?? 'code';
+            const cell = {
+                cell_type: type,
+                ...(withIds ? { id: newCellId() } : {}),
+                metadata: {},
+                source: toSourceLines(args.source),
+                ...(type === 'code' ? { execution_count: null, outputs: [] } : {}),
+            };
+            nb.cells.splice(at, 0, cell);
+        }
+        else if (mode === 'delete') {
+            at = findCell(nb, args.cell_index, args.cell_id);
+            nb.cells.splice(at, 1);
+        }
+        else {
+            if (args.source === undefined)
+                throw new Error('replace needs source');
+            at = findCell(nb, args.cell_index, args.cell_id);
+            const cell = nb.cells[at];
+            cell.source = toSourceLines(args.source);
+            if (args.cell_type && args.cell_type !== cell.cell_type) {
+                cell.cell_type = args.cell_type;
+                if (args.cell_type !== 'code') {
+                    delete cell.outputs;
+                    delete cell.execution_count;
+                }
+            }
+            // The old outputs belong to the old code.
+            if (cell.cell_type === 'code') {
+                cell.outputs = [];
+                cell.execution_count = null;
+            }
+        }
+        await writeFile(resolved, JSON.stringify(nb, null, indent) + (trailingNewline ? '\n' : ''), 'utf8');
+        return { path: resolved, mode, cellIndex: at, cells: nb.cells.length };
+    },
+};

package/dist/tools/policy.d.ts

@@ -66,4 +66,3 @@ export declare function normalizePathPattern(pattern: string, _cwd: string): str
  * project settings files, which concatenate (see sandbox-loader.ts).
  */
 export declare function mergeToolSandbox(base: ToolSandbox, override: ToolSandbox): ToolSandbox;
-//# sourceMappingURL=policy.d.ts.map

package/dist/tools/policy.js

@@ -188,4 +188,3 @@ export function mergeToolSandbox(base, override) {
     }
     return merged;
 }
-//# sourceMappingURL=policy.js.map

package/dist/tools/read-file.d.ts

@@ -22,6 +22,12 @@ export interface ReadFileResult {
     content: string;
     truncated: boolean;
 }
-export declare const readFileTool: ToolDefinition<z.infer<typeof params>, ReadFileResult>;
+/** A PDF comes back whole; the agent attaches it so document-capable models read it natively. */
+export interface ReadPdfResult {
+    path: string;
+    mime: 'application/pdf';
+    bytes: number;
+    dataUrl: string;
+}
+export declare const readFileTool: ToolDefinition<z.infer<typeof params>, ReadFileResult | ReadPdfResult>;
 export {};
-//# sourceMappingURL=read-file.d.ts.map

package/dist/tools/read-file.js

@@ -1,5 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { z } from 'zod';
+import { isNotebookPath, parseNotebook, renderNotebook } from './notebook.js';
+import { isPdf, MAX_ATTACHMENT_BYTES } from '../attachments.js';
 import { resolveAndCheckPath, truncateByLines } from './shared.js';
 const params = z.object({
     path: z.string().describe('Path to the file to read, relative to the working directory or absolute.'),
@@ -10,7 +12,7 @@ const params = z.object({
 });
 export const readFileTool = {
     name: 'read_file',
-    description: 'Read the contents of a file. Returns text with line numbers; supports an optional offset and max_lines to page through large files. Binary files are rejected.',
+    description: 'Read the contents of a file. Returns text with line numbers; supports an optional offset and max_lines to page through large files. A Jupyter notebook (.ipynb) is shown as numbered cells with their outputs. A PDF is attached whole so you can read it (text, tables and figures). Other binary files are rejected.',
     parameters: params,
     execute: async (args, ctx) => {
         const resolved = resolveAndCheckPath(args.path, ctx);
@@ -28,6 +30,22 @@ export const readFileTool = {
             }
             throw err;
         }
+        if (isNotebookPath(resolved) && !args.offset) {
+            // Raw notebook JSON is mostly metadata and base64 output: show the cells instead.
+            try {
+                const rendered = renderNotebook(parseNotebook(raw.toString('utf8')).nb);
+                return { path: resolved, totalLines: rendered.split('\n').length, offset: 1, content: rendered, truncated: false };
+            }
+            catch {
+                // Not valid notebook JSON: fall through and show the text as it is.
+            }
+        }
+        if (isPdf(raw)) {
+            if (raw.length > MAX_ATTACHMENT_BYTES) {
+                throw new Error(`PDF too large: ${raw.length} bytes exceeds ${MAX_ATTACHMENT_BYTES} (${args.path})`);
+            }
+            return { path: resolved, mime: 'application/pdf', bytes: raw.length, dataUrl: `data:application/pdf;base64,${raw.toString('base64')}` };
+        }
         // Reject obvious binary content.
         if (looksBinary(raw)) {
             throw new Error(`Refusing to read binary file: ${args.path} (${raw.length} bytes)`);
@@ -57,4 +75,3 @@ function looksBinary(buf) {
     }
     return false;
 }
-//# sourceMappingURL=read-file.js.map

package/dist/tools/read-image.d.ts

@@ -59,4 +59,3 @@ export declare const readImageTool: ToolDefinition<z.infer<typeof params>, ReadI
  */
 export declare function sniffMime(buf: Buffer, filePath: string): string | undefined;
 export {};
-//# sourceMappingURL=read-image.d.ts.map

package/dist/tools/read-image.js

@@ -119,4 +119,3 @@ export function sniffMime(buf, filePath) {
         default: return undefined;
     }
 }
-//# sourceMappingURL=read-image.js.map

package/dist/tools/read-only.d.ts

@@ -6,4 +6,3 @@
 export declare const READ_ONLY_TOOLS: readonly ["read_file", "list_files", "search_files", "find_symbol", "list_symbols", "find_references", "codebase_search", "memory_read"];
 /** The tools that run without a prompt: the user's list, or the read-only tools when none is set. */
 export declare function resolveAutoApprove(configured?: readonly string[]): string[];
-//# sourceMappingURL=read-only.d.ts.map

package/dist/tools/read-only.js

@@ -17,4 +17,3 @@ export const READ_ONLY_TOOLS = [
 export function resolveAutoApprove(configured) {
     return configured ? [...configured] : [...READ_ONLY_TOOLS];
 }
-//# sourceMappingURL=read-only.js.map

package/dist/tools/redact.d.ts

@@ -59,4 +59,3 @@ export declare function redact(text: string, options?: RedactOptions): Redaction
  * the text and just wants the metric.
  */
 export declare function countRedactions(text: string, options?: RedactOptions): number;
-//# sourceMappingURL=redact.d.ts.map