@trenchwork/erosolar 1.1.30 → 1.1.32

package/dist/tools/memoryTools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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):
+ *   .erosolar/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';
+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,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE,CAoGtE"}

package/dist/tools/memoryTools.js

@@ -0,0 +1,180 @@
+/**
+ * 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):
+ *   .erosolar/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, '.erosolar', '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;
+}
+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/monitorTools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Monitor — Claude-Code-parity background process management.
+ *
+ * Spawns a long-running command and lets the agent inspect/stream/stop it
+ * without blocking the conversation. Used for: dev servers, watchers,
+ * fuzzers, builds-in-progress. The Bash tool stays best for short
+ * commands; Monitor takes over once `run_in_background: true` is desired.
+ */
+import type { ToolDefinition } from '../core/toolRuntime.js';
+export declare function getMonitorRegistry(): ReadonlyMap<string, {
+    command: string;
+    status: string;
+}>;
+export declare function shutdownAllMonitors(): Promise<void>;
+export declare function createMonitorTools(workingDir: string): ToolDefinition[];
+//# sourceMappingURL=monitorTools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"monitorTools.d.ts","sourceRoot":"","sources":["../../src/tools/monitorTools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAgC7D,wBAAgB,kBAAkB,IAAI,WAAW,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAI7F;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWzD;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE,CAgIvE"}

package/dist/tools/monitorTools.js

@@ -0,0 +1,178 @@
+/**
+ * Monitor — Claude-Code-parity background process management.
+ *
+ * Spawns a long-running command and lets the agent inspect/stream/stop it
+ * without blocking the conversation. Used for: dev servers, watchers,
+ * fuzzers, builds-in-progress. The Bash tool stays best for short
+ * commands; Monitor takes over once `run_in_background: true` is desired.
+ */
+import { spawn } from 'node:child_process';
+import { callLambda } from '../utils/lambdaClient.js';
+const REGISTRY = new Map();
+const MAX_BUFFER_LINES = 1000;
+function nextId() {
+    return `mon-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+function appendOutput(entry, chunk) {
+    const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+    for (const line of text.split(/\r?\n/)) {
+        if (line.length === 0)
+            continue;
+        entry.buffer.push(line);
+    }
+    if (entry.buffer.length > MAX_BUFFER_LINES) {
+        entry.buffer.splice(0, entry.buffer.length - MAX_BUFFER_LINES);
+    }
+}
+export function getMonitorRegistry() {
+    const out = new Map();
+    for (const [id, e] of REGISTRY)
+        out.set(id, { command: e.command, status: e.status });
+    return out;
+}
+export async function shutdownAllMonitors() {
+    for (const entry of REGISTRY.values()) {
+        if (entry.status === 'running') {
+            try {
+                entry.proc.kill('SIGTERM');
+            }
+            catch {
+                // Ignore: process may already have exited.
+            }
+        }
+    }
+    REGISTRY.clear();
+}
+export function createMonitorTools(workingDir) {
+    return [
+        {
+            name: 'MonitorStart',
+            description: 'Spawn a long-running shell command in the background and return ' +
+                'a monitor id. Use for dev servers, watchers, fuzzers, builds. ' +
+                'Subsequent MonitorRead calls stream stdout/stderr lines.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string', description: 'Shell command to run.' },
+                    cwd: { type: 'string', description: 'Working directory (defaults to session cwd).' },
+                },
+                required: ['command'],
+            },
+            handler: async (args) => {
+                const command = String(args['command'] ?? '').trim();
+                if (!command)
+                    return 'MonitorStart requires a command.';
+                const cwd = typeof args['cwd'] === 'string' && args['cwd'].trim() ? args['cwd'].trim() : workingDir;
+                const id = nextId();
+                const proc = spawn(command, {
+                    cwd,
+                    shell: true,
+                    detached: false,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                const entry = {
+                    id,
+                    command,
+                    startedAt: new Date().toISOString(),
+                    status: 'running',
+                    buffer: [],
+                    proc,
+                };
+                proc.stdout?.on('data', (chunk) => appendOutput(entry, chunk));
+                proc.stderr?.on('data', (chunk) => appendOutput(entry, chunk));
+                proc.on('exit', (code, signal) => {
+                    entry.status = 'exited';
+                    entry.exitCode = code;
+                    entry.signal = signal;
+                    // Best-effort: mirror completion to the portal jobs collection.
+                    void callLambda('cliJobComplete', {
+                        id, status: code === 0 ? 'done' : 'failed', exitCode: code,
+                    }).catch(() => { });
+                });
+                proc.on('error', (err) => {
+                    appendOutput(entry, `[monitor error] ${err.message}`);
+                    entry.status = 'exited';
+                    entry.exitCode = -1;
+                    void callLambda('cliJobComplete', { id, status: 'failed', exitCode: -1 }).catch(() => { });
+                });
+                REGISTRY.set(id, entry);
+                // Best-effort: mirror to portal jobs collection so the operator
+                // sees this monitor in the rail "Jobs running" section.
+                void callLambda('cliJobStart', {
+                    id,
+                    kind: 'monitor',
+                    tool: 'shell',
+                    name: command.split(/\s+/)[0] || 'monitor',
+                    command: command.slice(0, 500),
+                    status: 'running',
+                    startedAt: Date.now(),
+                }).catch(() => { });
+                return `Monitor "${id}" started: ${command}`;
+            },
+        },
+        {
+            name: 'MonitorRead',
+            description: 'Read buffered output from a monitor. Pass `since: <line-index>` ' +
+                'to only return lines added since that index (the response includes ' +
+                'a `nextCursor` to use for the next read).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'Monitor id from MonitorStart.' },
+                    since: { type: 'number', description: 'Cursor returned by previous read.' },
+                },
+                required: ['id'],
+            },
+            handler: async (args) => {
+                const id = String(args['id'] ?? '');
+                const entry = REGISTRY.get(id);
+                if (!entry)
+                    return `No monitor with id "${id}".`;
+                const since = Number.isFinite(Number(args['since'])) ? Math.max(0, Number(args['since'])) : 0;
+                const slice = entry.buffer.slice(since);
+                const cursor = entry.buffer.length;
+                const head = `[${entry.status}${entry.status === 'exited' ? ` exit=${entry.exitCode ?? 'null'}` : ''}] cursor=${cursor}`;
+                return [head, ...slice].join('\n');
+            },
+        },
+        {
+            name: 'MonitorStop',
+            description: 'Send SIGTERM to a running monitor. Idempotent.',
+            parameters: {
+                type: 'object',
+                properties: { id: { type: 'string' } },
+                required: ['id'],
+            },
+            handler: async (args) => {
+                const id = String(args['id'] ?? '');
+                const entry = REGISTRY.get(id);
+                if (!entry)
+                    return `No monitor with id "${id}".`;
+                if (entry.status === 'running') {
+                    try {
+                        entry.proc.kill('SIGTERM');
+                    }
+                    catch (err) {
+                        return `MonitorStop kill failed: ${err instanceof Error ? err.message : String(err)}`;
+                    }
+                }
+                // Best-effort mirror.
+                void callLambda('cliJobUpdate', { id, status: 'stopped' }).catch(() => { });
+                return `Monitor "${id}" stopped.`;
+            },
+        },
+        {
+            name: 'MonitorList',
+            description: 'List active and recently-exited monitors.',
+            parameters: { type: 'object', properties: {} },
+            handler: async () => {
+                if (REGISTRY.size === 0)
+                    return 'No monitors.';
+                return Array.from(REGISTRY.values())
+                    .map((e) => `${e.id} [${e.status}] ${e.command}`)
+                    .join('\n');
+            },
+        },
+    ];
+}
+//# sourceMappingURL=monitorTools.js.map

package/dist/tools/monitorTools.js.map

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

package/dist/tools/planModeTools.d.ts

@@ -0,0 +1,32 @@
+/**
+ * EnterPlanMode / ExitPlanMode — Claude-Code-parity planning workflow.
+ *
+ * The agent enters plan mode to write down a multi-step implementation
+ * plan that the user reviews and approves before any tool that mutates
+ * state runs. ExitPlanMode is called when the plan is approved.
+ *
+ * Plans are persisted to <workingDir>/.erosolar/plans/<id>.json so the
+ * portal can render them and the user can revisit them later.
+ */
+import type { ToolDefinition } from '../core/toolRuntime.js';
+export type PlanStepStatus = 'pending' | 'in_progress' | 'completed' | 'skipped';
+export interface PlanStep {
+    id: string;
+    title: string;
+    detail?: string;
+    status: PlanStepStatus;
+}
+export interface PlanRecord {
+    id: string;
+    title: string;
+    goal?: string;
+    steps: PlanStep[];
+    status: 'draft' | 'approved' | 'completed' | 'abandoned';
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function getActivePlan(): PlanRecord | null;
+export declare function clearActivePlan(): void;
+export declare function listStoredPlans(workingDir: string): PlanRecord[];
+export declare function createPlanModeTools(workingDir: string): ToolDefinition[];
+//# sourceMappingURL=planModeTools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planModeTools.d.ts","sourceRoot":"","sources":["../../src/tools/planModeTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjF,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AA8BD,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,EAAE,CAahE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE,CA6IxE"}