@trenchwork/coder 1.3.0

package/dist/tools/hitlTools.js

@@ -0,0 +1,185 @@
+/**
+ * HITL Tools - The ONLY human-in-the-loop tools in the repository
+ * Provides decision points for critical operations
+ */
+import { getHITL, hitl } from '../core/hitl.js';
+export function createHITLTools() {
+    return [
+        {
+            name: 'HITL_Decision',
+            description: 'Pause execution and ask the human to choose between 4 distinct alternatives YOU generate. Always provide exactly 4 substantively different options that span the realistic decision space (e.g. conservative vs. aggressive, narrow vs. broad scope, fast vs. thorough). The UI also offers an "Enter your own" write-in, so the user can always reject all 4 and propose their own plan. Use HITL_YesNo for genuine binary decisions instead.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: 'Decision title/question' },
+                    description: { type: 'string', description: 'Detailed description of the decision' },
+                    context: { type: 'string', description: 'Additional context information' },
+                    options: {
+                        type: 'array',
+                        description: 'Exactly 4 distinct candidate options. The UI automatically appends an "Enter your own" write-in so the user can also propose an alternative.',
+                        minItems: 4,
+                        maxItems: 4,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                id: { type: 'string' },
+                                label: { type: 'string' },
+                                description: { type: 'string' },
+                                shortcut: { type: 'string' }
+                            },
+                            required: ['id', 'label', 'description']
+                        }
+                    },
+                    defaultOptionId: { type: 'string', description: 'Default option ID' },
+                    requiresExplicitChoice: { type: 'boolean', description: 'Require explicit user choice' },
+                    autoPause: { type: 'boolean', description: 'Auto-pause execution for decision' },
+                    timeoutMs: { type: 'number', description: 'Timeout in milliseconds (0 = no timeout)' }
+                },
+                required: ['title', 'description', 'options']
+            },
+            handler: async (args) => {
+                const typedArgs = args;
+                const hitlSystem = getHITL({
+                    autoPause: typedArgs.autoPause ?? true,
+                    timeoutMs: typedArgs.timeoutMs ?? 0,
+                    logLevel: 'detailed'
+                });
+                const options = (typedArgs.options || []).map(opt => ({
+                    id: opt.id,
+                    label: opt.label,
+                    description: opt.description,
+                    shortcut: opt.shortcut
+                }));
+                // Enforce the 4-option contract at runtime — schemas can be ignored
+                // by some LLM providers. The "Enter your own" write-in is added by
+                // the HITL UI, so the human always sees 5 menu items.
+                if (options.length !== 4) {
+                    throw new Error(`HITL_Decision requires exactly 4 options, got ${options.length}. ` +
+                        `Generate 4 substantively different alternatives spanning the realistic decision space ` +
+                        `(e.g. conservative vs. aggressive, narrow vs. broad scope, fast vs. thorough). ` +
+                        `Use HITL_YesNo for binary decisions instead.`);
+                }
+                const selectedOptionId = await hitlSystem.requestDecision({
+                    id: `hitl-tool-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`,
+                    title: typedArgs.title,
+                    description: typedArgs.description,
+                    context: typedArgs.context || '',
+                    options,
+                    defaultOptionId: typedArgs.defaultOptionId,
+                    requiresExplicitChoice: typedArgs.requiresExplicitChoice ?? true
+                });
+                const selectedOption = options.find(opt => opt.id === selectedOptionId);
+                return `HITL decision: ${selectedOption?.label || selectedOptionId}
+Selected option ID: ${selectedOptionId}
+Timestamp: ${new Date().toISOString()}
+Note: HITL decision recorded. This is the ONLY human-in-the-loop system in the repository.`;
+            }
+        },
+        {
+            name: 'HITL_YesNo',
+            description: 'Simple yes/no decision point',
+            parameters: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: 'Decision title/question' },
+                    description: { type: 'string', description: 'Detailed description' },
+                    context: { type: 'string', description: 'Additional context' },
+                    defaultYes: { type: 'boolean', description: 'Default to yes (true) or no (false)' }
+                },
+                required: ['title', 'description']
+            },
+            handler: async (args) => {
+                const typedArgs = args;
+                const result = await hitl.askYesNo(typedArgs.title, typedArgs.description, typedArgs.context || '', typedArgs.defaultYes ?? true);
+                return `HITL yes/no decision: ${result ? 'yes' : 'no'}
+Approved: ${result}
+Timestamp: ${new Date().toISOString()}
+Note: HITL yes/no decision recorded`;
+            }
+        },
+        {
+            name: 'HITL_Select',
+            description: 'Select from multiple options',
+            parameters: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: 'Selection title' },
+                    description: { type: 'string', description: 'Detailed description' },
+                    options: { type: 'string', description: 'JSON array of options: [{id, label, description}]' },
+                    context: { type: 'string', description: 'Additional context' },
+                    defaultOptionId: { type: 'string', description: 'Default option ID' }
+                },
+                required: ['title', 'description', 'options']
+            },
+            handler: async (args) => {
+                const typedArgs = args;
+                let options;
+                try {
+                    options = JSON.parse(typedArgs.options);
+                }
+                catch (error) {
+                    throw new Error(`Invalid options JSON: ${error}`);
+                }
+                const result = await hitl.selectOption(typedArgs.title, typedArgs.description, options, typedArgs.context || '', typedArgs.defaultOptionId);
+                const selectedOption = options.find(opt => opt.id === result);
+                return `HITL selection: ${selectedOption?.label || result}
+Selected option ID: ${result}
+Timestamp: ${new Date().toISOString()}
+Note: HITL selection recorded`;
+            }
+        },
+        {
+            name: 'HITL_Approval',
+            description: 'Request approval for risky operation',
+            parameters: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: 'Approval title' },
+                    riskDescription: { type: 'string', description: 'Description of risks' },
+                    operationDetails: { type: 'string', description: 'Detailed operation description' }
+                },
+                required: ['title', 'riskDescription']
+            },
+            handler: async (args) => {
+                const typedArgs = args;
+                const result = await hitl.requestApproval(typedArgs.title, typedArgs.riskDescription, typedArgs.operationDetails || '');
+                return `HITL approval: ${result ? 'approved' : 'rejected'}
+Approved: ${result}
+Timestamp: ${new Date().toISOString()}
+Note: ${result ? 'Operation approved via HITL' : 'Operation rejected via HITL'}`;
+            }
+        },
+        {
+            name: 'HITL_Status',
+            description: 'Get HITL system status and history',
+            parameters: {
+                type: 'object',
+                properties: {
+                    clearHistory: { type: 'boolean', description: 'Clear decision history' }
+                }
+            },
+            handler: async (args) => {
+                const hitlSystem = getHITL();
+                if (args.clearHistory) {
+                    hitlSystem.clearHistory();
+                    return `HITL history cleared
+Timestamp: ${new Date().toISOString()}`;
+                }
+                const history = hitlSystem.getHistory();
+                const recentDecisions = history.slice(-5).map(decision => ({
+                    requestId: decision.requestId,
+                    selectedOptionId: decision.selectedOptionId,
+                    timestamp: decision.timestamp.toISOString(),
+                    hasCustomInput: !!decision.userInput
+                }));
+                return `HITL System Status
+Status: active
+Total decisions: ${history.length}
+Recent decisions:
+${recentDecisions.map(d => `  • ${d.selectedOptionId} at ${d.timestamp}${d.hasCustomInput ? ' (custom input)' : ''}`).join('\n')}
+Note: This is the ONLY human-in-the-loop system in the repository`;
+            }
+        }
+    ];
+}
+//# sourceMappingURL=hitlTools.js.map

package/dist/tools/hitlTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitlTools.js","sourceRoot":"","sources":["../../src/tools/hitlTools.ts"],"names":[],"mappings":"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"}

package/dist/tools/memoryTools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Persistent memory tools — save/recall facts across CLI sessions.
+ * Mirrors the Claude Agent SDK memory pattern: a per-project
+ * directory of markdown files, each with a name + brief description,
+ * indexed so the agent can browse and selectively load.
+ *
+ * Storage layout (all paths relative to the working directory):
+ *   .trenchwork/memory/
+ *     MEMORY.md         — index file the agent maintains
+ *     <name>.md         — individual memory entries
+ *
+ * Tools provided:
+ *   memory_save(name, content, description?)
+ *   memory_list()
+ *   memory_load(name)
+ *   memory_delete(name)
+ */
+import type { ToolDefinition } from '../core/toolRuntime.js';
+/**
+ * Append a one-line note to the project's `notes` memory entry — the `#<note>`
+ * quick-capture shortcut (Claude Code parity). Lands in the same store the
+ * agent reads (.trenchwork/memory/), so captured notes survive across sessions
+ * and show up in the index. Returns false for a blank note.
+ */
+export declare function appendMemoryNote(workingDir: string, note: string): boolean;
+export declare function createMemoryTools(workingDir: string): ToolDefinition[];
+//# sourceMappingURL=memoryTools.d.ts.map

package/dist/tools/memoryTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryTools.d.ts","sourceRoot":"","sources":["../../src/tools/memoryTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA0B7D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS1E;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE,CAoGtE"}

package/dist/tools/memoryTools.js

@@ -0,0 +1,197 @@
+/**
+ * Persistent memory tools — save/recall facts across CLI sessions.
+ * Mirrors the Claude Agent SDK memory pattern: a per-project
+ * directory of markdown files, each with a name + brief description,
+ * indexed so the agent can browse and selectively load.
+ *
+ * Storage layout (all paths relative to the working directory):
+ *   .trenchwork/memory/
+ *     MEMORY.md         — index file the agent maintains
+ *     <name>.md         — individual memory entries
+ *
+ * Tools provided:
+ *   memory_save(name, content, description?)
+ *   memory_list()
+ *   memory_load(name)
+ *   memory_delete(name)
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+function memoryDir(workingDir) {
+    return join(workingDir, '.trenchwork', 'memory');
+}
+function ensureDir(workingDir) {
+    const dir = memoryDir(workingDir);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+/** Sanitize a memory name for use as a filename. Strict allow-list. */
+function safeName(name) {
+    if (typeof name !== 'string')
+        return null;
+    const trimmed = name.trim();
+    if (!trimmed)
+        return null;
+    // Allow letters, digits, underscore, hyphen. Reject path traversal,
+    // dots (so the name can't escape .md), spaces.
+    if (!/^[A-Za-z0-9_-]+$/.test(trimmed))
+        return null;
+    if (trimmed.length > 80)
+        return null;
+    return trimmed;
+}
+/**
+ * Append a one-line note to the project's `notes` memory entry — the `#<note>`
+ * quick-capture shortcut (Claude Code parity). Lands in the same store the
+ * agent reads (.trenchwork/memory/), so captured notes survive across sessions
+ * and show up in the index. Returns false for a blank note.
+ */
+export function appendMemoryNote(workingDir, note) {
+    const text = (note || '').trim();
+    if (!text)
+        return false;
+    const dir = ensureDir(workingDir);
+    const file = join(dir, 'notes.md');
+    const existing = existsSync(file) ? readFileSync(file, 'utf-8') : '> Quick notes captured with #';
+    writeFileSync(file, `${existing.replace(/\s+$/, '')}\n- ${text}\n`, 'utf-8');
+    rebuildIndex(dir);
+    return true;
+}
+export function createMemoryTools(workingDir) {
+    return [
+        {
+            name: 'memory_save',
+            description: 'Save a piece of context (project facts, user preferences, prior decisions) to persistent memory so it survives across CLI sessions. Use for non-obvious facts the user shares OR validated approaches you want to repeat. Overwrites any existing entry with the same name.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Unique short identifier ([A-Za-z0-9_-]+, max 80 chars). Becomes the filename.' },
+                    content: { type: 'string', description: 'The memory body. Markdown is fine.' },
+                    description: { type: 'string', description: 'One-line summary used for the index. Optional but recommended.' },
+                },
+                required: ['name', 'content'],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const name = safeName(args['name']);
+                if (!name)
+                    return 'Error: name must match [A-Za-z0-9_-]+ (letters, digits, _, -).';
+                const content = args['content'];
+                if (typeof content !== 'string')
+                    return 'Error: content must be a string.';
+                const description = args['description'];
+                const dir = ensureDir(workingDir);
+                const filePath = join(dir, `${name}.md`);
+                const body = description && typeof description === 'string'
+                    ? `> ${description.trim()}\n\n${content}`
+                    : content;
+                writeFileSync(filePath, body, 'utf-8');
+                // Update MEMORY.md index — append/replace this entry.
+                rebuildIndex(dir);
+                return `⏺ memory_save(${name}) — saved (${Buffer.byteLength(body, 'utf8')} bytes)`;
+            },
+        },
+        {
+            name: 'memory_list',
+            description: 'List all saved memories with their one-line descriptions. Use BEFORE memory_load to see what\'s available.',
+            parameters: { type: 'object', properties: {}, additionalProperties: false },
+            handler: async () => {
+                const dir = memoryDir(workingDir);
+                if (!existsSync(dir))
+                    return 'No memories saved yet.';
+                const entries = readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'MEMORY.md');
+                if (entries.length === 0)
+                    return 'No memories saved yet.';
+                const lines = [`Memories (${entries.length}):`];
+                for (const file of entries.sort()) {
+                    const name = file.slice(0, -3);
+                    let desc = '';
+                    try {
+                        const body = readFileSync(join(dir, file), 'utf-8');
+                        const firstLine = body.split('\n')[0]?.trim() ?? '';
+                        if (firstLine.startsWith('>')) {
+                            desc = firstLine.slice(1).trim();
+                        }
+                    }
+                    catch { /* skip */ }
+                    lines.push(`  - ${name}${desc ? ` — ${desc}` : ''}`);
+                }
+                return lines.join('\n');
+            },
+        },
+        {
+            name: 'memory_load',
+            description: 'Load the full content of a previously saved memory by name. Use after memory_list to pull in relevant context.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'The memory identifier passed to memory_save.' },
+                },
+                required: ['name'],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const name = safeName(args['name']);
+                if (!name)
+                    return 'Error: name must match [A-Za-z0-9_-]+.';
+                const filePath = join(memoryDir(workingDir), `${name}.md`);
+                if (!existsSync(filePath))
+                    return `Memory not found: ${name}. Use memory_list to see what's saved.`;
+                return readFileSync(filePath, 'utf-8');
+            },
+        },
+        {
+            name: 'memory_delete',
+            description: 'Delete a memory permanently. Use sparingly — prefer overwriting via memory_save with the same name.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'The memory identifier to remove.' },
+                },
+                required: ['name'],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const name = safeName(args['name']);
+                if (!name)
+                    return 'Error: name must match [A-Za-z0-9_-]+.';
+                const dir = memoryDir(workingDir);
+                const filePath = join(dir, `${name}.md`);
+                if (!existsSync(filePath))
+                    return `Memory not found: ${name}.`;
+                unlinkSync(filePath);
+                rebuildIndex(dir);
+                return `⏺ memory_delete(${name}) — removed.`;
+            },
+        },
+    ];
+}
+/**
+ * Rebuild MEMORY.md from the current set of entries. The index is a
+ * simple bulleted list — agents that load all of MEMORY.md at the
+ * start of a session see the catalogue without reading every entry.
+ */
+function rebuildIndex(dir) {
+    if (!existsSync(dir))
+        return;
+    const entries = readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'MEMORY.md').sort();
+    const lines = ['# Memory index', '', 'Saved entries:', ''];
+    for (const file of entries) {
+        const name = file.slice(0, -3);
+        let desc = '';
+        try {
+            const body = readFileSync(join(dir, file), 'utf-8');
+            const firstLine = body.split('\n')[0]?.trim() ?? '';
+            if (firstLine.startsWith('>'))
+                desc = firstLine.slice(1).trim();
+        }
+        catch { /* skip */ }
+        lines.push(`- [${name}](./${name}.md)${desc ? ` — ${desc}` : ''}`);
+    }
+    if (entries.length === 0)
+        lines.push('_(empty)_');
+    writeFileSync(join(dir, 'MEMORY.md'), lines.join('\n') + '\n', 'utf-8');
+}
+//# sourceMappingURL=memoryTools.js.map

package/dist/tools/memoryTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryTools.js","sourceRoot":"","sources":["../../src/tools/memoryTools.ts"],"names":[],"mappings":"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"}

package/dist/tools/notebookTools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Notebook tools — Claude-Code-parity for .ipynb editing.
+ *
+ * Jupyter notebooks are JSON files where the bulk of useful content
+ * lives in `cells: [{ cell_type, source: string|string[], … }]`. Doing
+ * source edits via the generic Edit tool is brittle because the
+ * `source` field is sometimes a string and sometimes a string[],
+ * and surrounding JSON whitespace varies. This module exposes a
+ * structured tool — `NotebookEdit` — that addresses cells by index
+ * and rewrites just that cell's source while preserving everything
+ * else.
+ *
+ * Capabilities:
+ *   NotebookEdit({ notebook_path, cell_index, new_source, mode? })
+ *     mode: "replace" (default), "insert", "delete"
+ *     Returns a short summary of the change.
+ */
+import type { ToolDefinition } from '../core/toolRuntime.js';
+export declare function createNotebookTools(workingDir: string): ToolDefinition[];
+//# sourceMappingURL=notebookTools.d.ts.map

package/dist/tools/notebookTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notebookTools.d.ts","sourceRoot":"","sources":["../../src/tools/notebookTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA4C7D,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE,CAmGxE"}

package/dist/tools/notebookTools.js

@@ -0,0 +1,140 @@
+/**
+ * Notebook tools — Claude-Code-parity for .ipynb editing.
+ *
+ * Jupyter notebooks are JSON files where the bulk of useful content
+ * lives in `cells: [{ cell_type, source: string|string[], … }]`. Doing
+ * source edits via the generic Edit tool is brittle because the
+ * `source` field is sometimes a string and sometimes a string[],
+ * and surrounding JSON whitespace varies. This module exposes a
+ * structured tool — `NotebookEdit` — that addresses cells by index
+ * and rewrites just that cell's source while preserving everything
+ * else.
+ *
+ * Capabilities:
+ *   NotebookEdit({ notebook_path, cell_index, new_source, mode? })
+ *     mode: "replace" (default), "insert", "delete"
+ *     Returns a short summary of the change.
+ */
+import { existsSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+function resolvePath(workingDir, p) {
+    return isAbsolute(p) ? p : join(workingDir, p);
+}
+function sourceToString(src) {
+    if (typeof src === 'string')
+        return src;
+    if (Array.isArray(src))
+        return src.join('');
+    return '';
+}
+function stringToSource(text) {
+    // Jupyter convention: source is an array of lines, each ending
+    // with \n EXCEPT the last (matching how nb-format JSON serializes).
+    if (!text)
+        return [];
+    const parts = text.split('\n');
+    const out = [];
+    for (let i = 0; i < parts.length; i++) {
+        const isLast = i === parts.length - 1;
+        out.push(isLast ? parts[i] : `${parts[i]}\n`);
+    }
+    // Trim trailing empty entry if text ended with \n.
+    if (out.length && out[out.length - 1] === '')
+        out.pop();
+    return out;
+}
+export function createNotebookTools(workingDir) {
+    return [
+        {
+            name: 'NotebookEdit',
+            description: 'Edit a Jupyter notebook (.ipynb) cell by index. Use mode "replace" (default) to rewrite a cell\'s source, "insert" to add a new cell at the index (existing cells shift down), or "delete" to remove the cell. The notebook\'s structure (metadata, nbformat, other cells) is preserved exactly. PREFER this over Edit for .ipynb files — generic string edits break on the string|string[] source format.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    notebook_path: { type: 'string', description: 'Path to the .ipynb file (relative to working dir or absolute).' },
+                    cell_index: { type: 'number', description: '0-based index of the cell to operate on.' },
+                    new_source: { type: 'string', description: 'New cell source (text). Required for replace/insert; ignored for delete.' },
+                    cell_type: {
+                        type: 'string',
+                        enum: ['code', 'markdown', 'raw'],
+                        description: 'Cell type for insert mode. Default: code.',
+                    },
+                    mode: {
+                        type: 'string',
+                        enum: ['replace', 'insert', 'delete'],
+                        description: 'Operation. Default: replace.',
+                    },
+                },
+                required: ['notebook_path', 'cell_index'],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const pathArg = args['notebook_path'];
+                if (typeof pathArg !== 'string' || !pathArg.trim()) {
+                    return 'Error: notebook_path must be a non-empty string.';
+                }
+                const absPath = resolvePath(workingDir, pathArg);
+                if (!existsSync(absPath))
+                    return `Error: notebook not found: ${absPath}`;
+                if (!absPath.toLowerCase().endsWith('.ipynb')) {
+                    return `Error: notebook_path must end in .ipynb (got ${absPath}).`;
+                }
+                const stats = statSync(absPath);
+                if (stats.size > 5 * 1024 * 1024) {
+                    return `Error: notebook too large for direct edit (${Math.round(stats.size / 1024)}KB > 5MB cap).`;
+                }
+                const mode = (typeof args['mode'] === 'string' ? args['mode'] : 'replace');
+                const cellIndex = typeof args['cell_index'] === 'number' ? args['cell_index'] : -1;
+                const newSource = typeof args['new_source'] === 'string' ? args['new_source'] : '';
+                const cellType = (typeof args['cell_type'] === 'string' ? args['cell_type'] : 'code');
+                let nb;
+                try {
+                    nb = JSON.parse(readFileSync(absPath, 'utf-8'));
+                }
+                catch (err) {
+                    return `Error: notebook JSON parse failed (${err.message}).`;
+                }
+                if (!Array.isArray(nb.cells)) {
+                    return 'Error: notebook has no cells[] array.';
+                }
+                if (cellIndex < 0 || cellIndex > nb.cells.length) {
+                    return `Error: cell_index ${cellIndex} out of range (0..${nb.cells.length}).`;
+                }
+                if (mode === 'replace') {
+                    if (cellIndex >= nb.cells.length) {
+                        return `Error: replace mode needs an existing cell. Use insert for cell_index ${cellIndex}.`;
+                    }
+                    const before = sourceToString(nb.cells[cellIndex].source);
+                    nb.cells[cellIndex].source = stringToSource(newSource);
+                    // Reset outputs + execution count for code cells when source changes.
+                    if (nb.cells[cellIndex].cell_type === 'code') {
+                        nb.cells[cellIndex].outputs = [];
+                        nb.cells[cellIndex].execution_count = null;
+                    }
+                    writeFileSync(absPath, JSON.stringify(nb, null, 1) + '\n', 'utf-8');
+                    const beforeLines = before.split('\n').length;
+                    const afterLines = newSource.split('\n').length;
+                    return `⏺ NotebookEdit(${pathArg}) — replaced cell ${cellIndex} (${beforeLines} → ${afterLines} lines, ${nb.cells[cellIndex].cell_type})`;
+                }
+                if (mode === 'insert') {
+                    const newCell = cellType === 'code'
+                        ? { cell_type: 'code', source: stringToSource(newSource), metadata: {}, execution_count: null, outputs: [] }
+                        : { cell_type: cellType, source: stringToSource(newSource), metadata: {} };
+                    nb.cells.splice(cellIndex, 0, newCell);
+                    writeFileSync(absPath, JSON.stringify(nb, null, 1) + '\n', 'utf-8');
+                    return `⏺ NotebookEdit(${pathArg}) — inserted ${cellType} cell at index ${cellIndex} (${newSource.split('\n').length} lines)`;
+                }
+                if (mode === 'delete') {
+                    if (cellIndex >= nb.cells.length) {
+                        return `Error: cell_index ${cellIndex} out of range for delete (have ${nb.cells.length} cells).`;
+                    }
+                    const removed = nb.cells.splice(cellIndex, 1)[0];
+                    writeFileSync(absPath, JSON.stringify(nb, null, 1) + '\n', 'utf-8');
+                    return `⏺ NotebookEdit(${pathArg}) — deleted cell ${cellIndex} (${removed.cell_type})`;
+                }
+                return `Error: unknown mode "${mode}".`;
+            },
+        },
+    ];
+}
+//# sourceMappingURL=notebookTools.js.map

package/dist/tools/notebookTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notebookTools.js","sourceRoot":"","sources":["../../src/tools/notebookTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAoB7C,SAAS,WAAW,CAAC,UAAkB,EAAE,CAAS;IAChD,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,cAAc,CAAC,GAAkC;IACxD,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5C,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,+DAA+D;IAC/D,oEAAoE;IACpE,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QACtC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,mDAAmD;IACnD,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE;QAAE,GAAG,CAAC,GAAG,EAAE,CAAC;IACxD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,OAAO;QACL;YACE,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,4YAA4Y;YAC9Y,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gEAAgE,EAAE;oBAChH,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0CAA0C,EAAE;oBACvF,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0EAA0E,EAAE;oBACvH,SAAS,EAAE;wBACT,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC;wBACjC,WAAW,EAAE,2CAA2C;qBACzD;oBACD,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC;wBACrC,WAAW,EAAE,8BAA8B;qBAC5C;iBACF;gBACD,QAAQ,EAAE,CAAC,eAAe,EAAE,YAAY,CAAC;gBACzC,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACtB,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC;gBACtC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;oBACnD,OAAO,kDAAkD,CAAC;gBAC5D,CAAC;gBACD,MAAM,OAAO,GAAG,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;gBACjD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;oBAAE,OAAO,8BAA8B,OAAO,EAAE,CAAC;gBACzE,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC9C,OAAO,gDAAgD,OAAO,IAAI,CAAC;gBACrE,CAAC;gBACD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;gBAChC,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;oBACjC,OAAO,8CAA8C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC;gBACrG,CAAC;gBAED,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAoC,CAAC;gBAC9G,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnF,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnF,MAAM,QAAQ,GAAG,CAAC,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAgC,CAAC;gBAErH,IAAI,EAAiB,CAAC;gBACtB,IAAI,CAAC;oBACH,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;gBAClD,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,sCAAuC,GAAa,CAAC,OAAO,IAAI,CAAC;gBAC1E,CAAC;gBACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC7B,OAAO,uCAAuC,CAAC;gBACjD,CAAC;gBACD,IAAI,SAAS,GAAG,CAAC,IAAI,SAAS,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;oBACjD,OAAO,qBAAqB,SAAS,qBAAqB,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC;gBAChF,CAAC;gBAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBACvB,IAAI,SAAS,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;wBACjC,OAAO,yEAAyE,SAAS,GAAG,CAAC;oBAC/F,CAAC;oBACD,MAAM,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,MAAM,CAAC,CAAC;oBAC3D,EAAE,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;oBACxD,sEAAsE;oBACtE,IAAI,EAAE,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;wBAC9C,EAAE,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,OAAO,GAAG,EAAE,CAAC;wBAClC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,eAAe,GAAG,IAAI,CAAC;oBAC9C,CAAC;oBACD,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;oBACpE,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;oBAC9C,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;oBAChD,OAAO,kBAAkB,OAAO,qBAAqB,SAAS,KAAK,WAAW,MAAM,UAAU,WAAW,EAAE,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,SAAS,GAAG,CAAC;gBAC7I,CAAC;gBAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACtB,MAAM,OAAO,GACX,QAAQ,KAAK,MAAM;wBACjB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;wBAC5G,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;oBAC/E,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;oBACvC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;oBACpE,OAAO,kBAAkB,OAAO,gBAAgB,QAAQ,kBAAkB,SAAS,KAAK,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC;gBAChI,CAAC;gBAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACtB,IAAI,SAAS,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;wBACjC,OAAO,qBAAqB,SAAS,kCAAkC,EAAE,CAAC,KAAK,CAAC,MAAM,UAAU,CAAC;oBACnG,CAAC;oBACD,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC;oBAClD,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;oBACpE,OAAO,kBAAkB,OAAO,oBAAoB,SAAS,KAAK,OAAO,CAAC,SAAS,GAAG,CAAC;gBACzF,CAAC;gBAED,OAAO,wBAAwB,IAAI,IAAI,CAAC;YAC1C,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/searchTools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unified Search Tools - Combines file pattern matching and content search
+ *
+ * Provides a single, powerful Search tool that handles:
+ * - File pattern matching (glob)
+ * - Content search (regex/grep)
+ * - Definition finding
+ */
+import type { ToolDefinition } from '../core/toolRuntime.js';
+export declare function createSearchTools(workingDir: string): ToolDefinition[];
+export { createSearchTools as createGrepTools };
+//# sourceMappingURL=searchTools.d.ts.map

package/dist/tools/searchTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchTools.d.ts","sourceRoot":"","sources":["../../src/tools/searchTools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAgF7D,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE,CAmGtE;AAiSD,OAAO,EAAE,iBAAiB,IAAI,eAAe,EAAE,CAAC"}