@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/tools/schemas/standard.js

@@ -0,0 +1,966 @@
+/**
+ * Standard Tool Definitions
+ *
+ * Defines the 11 standard coding tools available to the Nimbus agentic loop.
+ * Each tool wraps existing filesystem operations (src/tools/file-ops.ts) or
+ * uses child_process for shell commands.
+ *
+ * Tools:
+ *   read_file, edit_file, multi_edit, write_file, bash,
+ *   glob, grep, list_dir, webfetch, todo_read, todo_write
+ */
+import { z } from 'zod';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { spawn, exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { glob as fastGlob } from 'fast-glob';
+const execAsync = promisify(exec);
+/**
+ * Execute a shell command using spawn with process group management.
+ * On timeout, kills the entire process group to avoid orphaned children.
+ */
+function spawnAsync(command, options) {
+    return new Promise((resolve, reject) => {
+        const maxBuffer = options.maxBuffer ?? 10 * 1024 * 1024;
+        const child = spawn('sh', ['-c', command], {
+            cwd: options.cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Create a new process group so we can kill the whole tree
+            detached: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let killed = false;
+        let stdoutOverflow = false;
+        let stderrOverflow = false;
+        // Kill process group helper
+        const killProcessGroup = () => {
+            killed = true;
+            try {
+                if (child.pid) {
+                    process.kill(-child.pid, 'SIGTERM');
+                    setTimeout(() => {
+                        try {
+                            if (child.pid) {
+                                process.kill(-child.pid, 'SIGKILL');
+                            }
+                        }
+                        catch {
+                            /* already dead */
+                        }
+                    }, 2000);
+                }
+            }
+            catch {
+                /* Process already exited */
+            }
+        };
+        // Wire AbortSignal (Ctrl+C) to kill the child process group
+        if (options.signal) {
+            if (options.signal.aborted) {
+                killProcessGroup();
+            }
+            else {
+                options.signal.addEventListener('abort', killProcessGroup, { once: true });
+            }
+        }
+        child.stdout?.on('data', (data) => {
+            options.onChunk?.(data.toString());
+            if (stdout.length + data.length > maxBuffer) {
+                stdoutOverflow = true;
+                return;
+            }
+            stdout += data.toString();
+        });
+        child.stderr?.on('data', (data) => {
+            options.onChunk?.(data.toString());
+            if (stderr.length + data.length > maxBuffer) {
+                stderrOverflow = true;
+                return;
+            }
+            stderr += data.toString();
+        });
+        const timer = options.timeout
+            ? setTimeout(() => {
+                killProcessGroup();
+            }, options.timeout)
+            : null;
+        child.on('close', code => {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            // Clean up abort listener
+            if (options.signal) {
+                options.signal.removeEventListener('abort', killProcessGroup);
+            }
+            if (killed) {
+                const err = new Error(options.signal?.aborted
+                    ? 'Command aborted by user'
+                    : `Command timed out after ${options.timeout}ms`);
+                err.stdout = stdout;
+                err.stderr = stderr;
+                reject(err);
+                return;
+            }
+            if (stdoutOverflow || stderrOverflow) {
+                stdout += '\n[Output truncated: exceeded buffer limit]';
+            }
+            if (code !== 0) {
+                const err = new Error(`Command exited with code ${code}`);
+                err.stdout = stdout;
+                err.stderr = stderr;
+                err.code = code;
+                reject(err);
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+        child.on('error', error => {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            reject(error);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Build a successful ToolResult. */
+function ok(output) {
+    return { output, isError: false };
+}
+/** Build an error ToolResult. */
+function err(message) {
+    return { output: '', error: message, isError: true };
+}
+// ---------------------------------------------------------------------------
+// 1. read_file
+// ---------------------------------------------------------------------------
+const readFileSchema = z.object({
+    path: z.string().describe('Absolute or relative path to the file to read'),
+    offset: z.number().optional().describe('1-based line number to start reading from'),
+    limit: z.number().optional().describe('Maximum number of lines to return'),
+});
+/** Patterns for sensitive files that should be blocked from read_file. */
+const SENSITIVE_FILE_PATTERNS = [
+    /\.env($|\.)/i, // .env, .env.local, .env.production, etc.
+    /credentials\.json$/i, // GCP credentials
+    /\.aws\/credentials$/i, // AWS credentials
+    /\.ssh\/(id_|known_hosts|config)/i, // SSH keys and config
+    /\.gnupg\//i, // GPG keys
+    /\.netrc$/i, // Network credentials
+    /secret[s]?\.ya?ml$/i, // Kubernetes secrets
+    /\.pem$/i, // SSL certificates
+    /\.key$/i, // Private keys
+    /\.p12$/i, // PKCS#12 certificates
+    /\.keystore$/i, // Java keystores
+    /\/\.git\/config$/i, // Git config (may contain tokens)
+    /token[s]?\.json$/i, // OAuth tokens
+];
+function isSensitivePath(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    return SENSITIVE_FILE_PATTERNS.some(pattern => pattern.test(normalized));
+}
+export const readFileTool = {
+    name: 'read_file',
+    description: 'Read file contents. Returns the text content of a file at the given path.',
+    inputSchema: readFileSchema,
+    permissionTier: 'auto_allow',
+    category: 'standard',
+    async execute(raw) {
+        try {
+            const input = readFileSchema.parse(raw);
+            const resolved = path.resolve(input.path);
+            // Block reading of sensitive files (credentials, keys, secrets)
+            if (isSensitivePath(resolved)) {
+                return err(`Blocked: ${path.basename(resolved)} appears to be a sensitive file (credentials, secrets, or keys). ` +
+                    `Reading it could expose secrets in the conversation history.`);
+            }
+            // Detect image files — return base64-encoded data for multimodal LLM support
+            const ext = path.extname(resolved).toLowerCase();
+            const imageExts = new Set([
+                '.png',
+                '.jpg',
+                '.jpeg',
+                '.gif',
+                '.bmp',
+                '.webp',
+                '.svg',
+                '.ico',
+                '.tiff',
+                '.tif',
+            ]);
+            // Subset that LLMs can actually process as vision input
+            const MULTIMODAL_EXTS = {
+                '.png': 'image/png',
+                '.jpg': 'image/jpeg',
+                '.jpeg': 'image/jpeg',
+                '.gif': 'image/gif',
+                '.webp': 'image/webp',
+            };
+            if (imageExts.has(ext)) {
+                try {
+                    const stats = await fs.stat(resolved);
+                    const sizeStr = stats.size < 1024
+                        ? `${stats.size} B`
+                        : stats.size < 1024 * 1024
+                            ? `${(stats.size / 1024).toFixed(1)} KB`
+                            : `${(stats.size / (1024 * 1024)).toFixed(1)} MB`;
+                    const mediaType = MULTIMODAL_EXTS[ext];
+                    // If the image is a supported multimodal format and under 20MB, include base64
+                    if (mediaType && stats.size < 20 * 1024 * 1024) {
+                        const buffer = await fs.readFile(resolved);
+                        const base64 = buffer.toString('base64');
+                        return ok(`[Image file: ${path.basename(resolved)}]\nType: ${ext.slice(1).toUpperCase()}\nSize: ${sizeStr}\nPath: ${resolved}\n\n` +
+                            `<image_data media_type="${mediaType}" encoding="base64">${base64}</image_data>`);
+                    }
+                    return ok(`[Image file: ${path.basename(resolved)}]\nType: ${ext.slice(1).toUpperCase()}\nSize: ${sizeStr}\nPath: ${resolved}\n\nNote: Image content cannot be displayed in text mode. Use an image viewer or IDE to see the contents.`);
+                }
+                catch {
+                    return ok(`[Image file: ${path.basename(resolved)}]\nPath: ${resolved}\n\nNote: Image content cannot be displayed in text mode.`);
+                }
+            }
+            // Detect Jupyter notebooks
+            if (ext === '.ipynb') {
+                try {
+                    const nbRaw = await fs.readFile(resolved, 'utf-8');
+                    const notebook = JSON.parse(nbRaw);
+                    if (!notebook.cells || !Array.isArray(notebook.cells)) {
+                        return ok(nbRaw); // Malformed notebook, return raw JSON
+                    }
+                    const parts = [`# Jupyter Notebook: ${path.basename(resolved)}\n`];
+                    for (let i = 0; i < notebook.cells.length; i++) {
+                        const cell = notebook.cells[i];
+                        const source = Array.isArray(cell.source)
+                            ? cell.source.join('')
+                            : String(cell.source || '');
+                        if (cell.cell_type === 'markdown') {
+                            parts.push(`## Cell ${i + 1} [Markdown]\n${source}\n`);
+                        }
+                        else if (cell.cell_type === 'code') {
+                            parts.push(`## Cell ${i + 1} [Code]\n\`\`\`python\n${source}\n\`\`\`\n`);
+                            // Show outputs
+                            if (cell.outputs && Array.isArray(cell.outputs)) {
+                                for (const output of cell.outputs) {
+                                    if (output.text) {
+                                        const text = Array.isArray(output.text)
+                                            ? output.text.join('')
+                                            : String(output.text);
+                                        parts.push(`Output:\n\`\`\`\n${text}\n\`\`\`\n`);
+                                    }
+                                    else if (output.data?.['text/plain']) {
+                                        const text = Array.isArray(output.data['text/plain'])
+                                            ? output.data['text/plain'].join('')
+                                            : String(output.data['text/plain']);
+                                        parts.push(`Output:\n\`\`\`\n${text}\n\`\`\`\n`);
+                                    }
+                                    else if (output.data?.['image/png'] || output.data?.['image/jpeg']) {
+                                        parts.push(`Output: [Image output — cannot display in text mode]\n`);
+                                    }
+                                }
+                            }
+                        }
+                        else if (cell.cell_type === 'raw') {
+                            parts.push(`## Cell ${i + 1} [Raw]\n${source}\n`);
+                        }
+                    }
+                    return ok(parts.join('\n'));
+                }
+                catch {
+                    // If notebook parsing fails, fall through to normal file read
+                }
+            }
+            const content = await fs.readFile(resolved, 'utf-8');
+            if (input.offset !== undefined || input.limit !== undefined) {
+                const lines = content.split('\n');
+                const start = (input.offset ?? 1) - 1; // convert to 0-based
+                const end = input.limit !== undefined ? start + input.limit : lines.length;
+                return ok(lines.slice(start, end).join('\n'));
+            }
+            return ok(content);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Failed to read file: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 2. edit_file
+// ---------------------------------------------------------------------------
+const editFileSchema = z.object({
+    path: z.string().describe('Path to the file to edit'),
+    old_string: z.string().describe('Exact text to find'),
+    new_string: z.string().describe('Replacement text'),
+    replace_all: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Replace all occurrences instead of just the first'),
+});
+export const editFileTool = {
+    name: 'edit_file',
+    description: 'Make a precise text replacement in a file. By default replaces the first occurrence of old_string with new_string. Set replace_all to true to replace every occurrence.',
+    inputSchema: editFileSchema,
+    permissionTier: 'ask_once',
+    category: 'standard',
+    isDestructive: true,
+    async execute(raw) {
+        try {
+            const input = editFileSchema.parse(raw);
+            const content = await fs.readFile(input.path, 'utf-8');
+            if (!content.includes(input.old_string)) {
+                return err(`old_string not found in ${input.path}. Make sure the string matches exactly, including whitespace and indentation.`);
+            }
+            let updated;
+            if (input.replace_all) {
+                // Count occurrences for the success message
+                let count = 0;
+                let searchPos = 0;
+                for (;;) {
+                    const idx = content.indexOf(input.old_string, searchPos);
+                    if (idx === -1) {
+                        break;
+                    }
+                    count++;
+                    searchPos = idx + input.old_string.length;
+                }
+                updated = content.replaceAll(input.old_string, input.new_string);
+                await fs.writeFile(input.path, updated, 'utf-8');
+                return ok(`Successfully replaced ${count} occurrence${count !== 1 ? 's' : ''} in ${input.path}`);
+            }
+            // Replace only the first occurrence
+            const idx = content.indexOf(input.old_string);
+            updated =
+                content.slice(0, idx) + input.new_string + content.slice(idx + input.old_string.length);
+            await fs.writeFile(input.path, updated, 'utf-8');
+            return ok(`Successfully edited ${input.path}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Failed to edit file: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 3. multi_edit
+// ---------------------------------------------------------------------------
+const multiEditSchema = z.object({
+    path: z.string().describe('Path to the file to edit'),
+    edits: z
+        .array(z.object({
+        old_string: z.string().describe('Exact text to find'),
+        new_string: z.string().describe('Replacement text'),
+    }))
+        .describe('Array of edits to apply sequentially'),
+});
+export const multiEditTool = {
+    name: 'multi_edit',
+    description: 'Make multiple text replacements in a single file atomically.',
+    inputSchema: multiEditSchema,
+    permissionTier: 'ask_once',
+    category: 'standard',
+    isDestructive: true,
+    async execute(raw) {
+        try {
+            const input = multiEditSchema.parse(raw);
+            const content = await fs.readFile(input.path, 'utf-8');
+            // Pre-compute all edit positions on the original content to detect
+            // overlap issues and enable bottom-up application.
+            const positioned = [];
+            const usedPositions = new Set();
+            for (let i = 0; i < input.edits.length; i++) {
+                const edit = input.edits[i];
+                // Search for the next occurrence that hasn't already been claimed
+                let searchFrom = 0;
+                let idx = -1;
+                for (;;) {
+                    idx = content.indexOf(edit.old_string, searchFrom);
+                    if (idx === -1) {
+                        break;
+                    }
+                    if (!usedPositions.has(idx)) {
+                        break;
+                    }
+                    searchFrom = idx + 1;
+                }
+                if (idx === -1) {
+                    return err(`Edit ${i + 1}: old_string not found in ${input.path}. Aborting — no changes were written.`);
+                }
+                usedPositions.add(idx);
+                positioned.push({
+                    index: idx,
+                    editIndex: i,
+                    old_string: edit.old_string,
+                    new_string: edit.new_string,
+                });
+            }
+            // Sort by position descending (bottom-up) so earlier edits don't
+            // shift the positions of later ones.
+            positioned.sort((a, b) => b.index - a.index);
+            let result = content;
+            for (const edit of positioned) {
+                result =
+                    result.slice(0, edit.index) +
+                        edit.new_string +
+                        result.slice(edit.index + edit.old_string.length);
+            }
+            await fs.writeFile(input.path, result, 'utf-8');
+            return ok(`Successfully applied ${input.edits.length} edit(s) to ${input.path}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Failed to apply multi-edit: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 4. write_file
+// ---------------------------------------------------------------------------
+const writeFileSchema = z.object({
+    path: z.string().describe('Path to the file to create or overwrite'),
+    content: z.string().describe('Full file content to write'),
+});
+export const writeFileTool = {
+    name: 'write_file',
+    description: 'Create or overwrite a file with the given content.',
+    inputSchema: writeFileSchema,
+    permissionTier: 'ask_once',
+    category: 'standard',
+    isDestructive: true,
+    async execute(raw) {
+        try {
+            const input = writeFileSchema.parse(raw);
+            await fs.mkdir(path.dirname(input.path), { recursive: true });
+            await fs.writeFile(input.path, input.content, 'utf-8');
+            return ok(`Successfully wrote ${input.path}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Failed to write file: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 5. bash
+// ---------------------------------------------------------------------------
+const bashSchema = z.object({
+    command: z.string().describe('Shell command to execute'),
+    timeout: z
+        .number()
+        .optional()
+        .default(120_000)
+        .describe('Timeout in milliseconds (default: 120000)'),
+    workdir: z.string().optional().describe('Working directory for the command'),
+});
+export const bashTool = {
+    name: 'bash',
+    description: 'Execute a shell command and return its output. Use for running tests, installing packages, or other terminal operations.',
+    inputSchema: bashSchema,
+    permissionTier: 'ask_once',
+    category: 'standard',
+    isDestructive: true,
+    async execute(raw) {
+        try {
+            const input = bashSchema.parse(raw);
+            const signal = raw?._signal;
+            const onChunk = raw?._onChunk;
+            const { stdout, stderr } = await spawnAsync(input.command, {
+                timeout: input.timeout,
+                cwd: input.workdir,
+                maxBuffer: 10 * 1024 * 1024, // 10 MB
+                signal,
+                onChunk,
+            });
+            const combined = [stdout, stderr].filter(Boolean).join('\n');
+            return ok(combined || '(no output)');
+        }
+        catch (error) {
+            if (error !== null && typeof error === 'object' && 'stdout' in error) {
+                // Process errors still carry partial output
+                const execErr = error;
+                const combined = [execErr.stdout, execErr.stderr].filter(Boolean).join('\n');
+                return err(combined || execErr.message || 'Command failed');
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Command failed: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 6. glob
+// ---------------------------------------------------------------------------
+const globSchema = z.object({
+    pattern: z.string().describe('Glob pattern to match files (e.g., "**/*.ts")'),
+    path: z.string().optional().describe('Base directory to search in (defaults to cwd)'),
+});
+export const globTool = {
+    name: 'glob',
+    description: 'Find files matching a glob pattern. Returns matching file paths.',
+    inputSchema: globSchema,
+    permissionTier: 'auto_allow',
+    category: 'standard',
+    async execute(raw) {
+        try {
+            const input = globSchema.parse(raw);
+            const matches = await fastGlob(input.pattern, {
+                cwd: input.path ?? process.cwd(),
+                absolute: true,
+                dot: false,
+            });
+            if (matches.length === 0) {
+                return ok('No files matched the pattern.');
+            }
+            return ok(matches.join('\n'));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Glob search failed: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 7. grep
+// ---------------------------------------------------------------------------
+const grepSchema = z.object({
+    pattern: z.string().describe('Regex pattern to search for'),
+    path: z.string().optional().describe('Directory or file to search in (defaults to cwd)'),
+    include: z.string().optional().describe('Glob filter for file types (e.g., "*.ts")'),
+});
+export const grepTool = {
+    name: 'grep',
+    description: 'Search file contents using a regex pattern. Returns matching lines with file paths and line numbers.',
+    inputSchema: grepSchema,
+    permissionTier: 'auto_allow',
+    category: 'standard',
+    async execute(raw) {
+        try {
+            const input = grepSchema.parse(raw);
+            const searchPath = input.path ?? process.cwd();
+            // Try ripgrep first (faster, respects .gitignore), fall back to grep
+            let command;
+            try {
+                await execAsync('rg --version', { timeout: 2000 });
+                const globFlag = input.include ? ` --glob ${JSON.stringify(input.include)}` : '';
+                command = `rg -n${globFlag} ${JSON.stringify(input.pattern)} ${JSON.stringify(searchPath)}`;
+            }
+            catch {
+                const includeFlag = input.include ? ` --include=${JSON.stringify(input.include)}` : '';
+                command = `grep -rn${includeFlag} ${JSON.stringify(input.pattern)} ${JSON.stringify(searchPath)}`;
+            }
+            const { stdout } = await execAsync(command, {
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            return ok(stdout || 'No matches found.');
+        }
+        catch (error) {
+            if (error !== null &&
+                typeof error === 'object' &&
+                'code' in error &&
+                error.code === 1) {
+                // grep/rg exit code 1 = no matches (not a real error)
+                return ok('No matches found.');
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Grep failed: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 8. list_dir
+// ---------------------------------------------------------------------------
+const listDirSchema = z.object({
+    path: z.string().describe('Absolute or relative path to the directory'),
+});
+export const listDirTool = {
+    name: 'list_dir',
+    description: 'List the contents of a directory. Returns file and directory names with type indicators.',
+    inputSchema: listDirSchema,
+    permissionTier: 'auto_allow',
+    category: 'standard',
+    async execute(raw) {
+        try {
+            const input = listDirSchema.parse(raw);
+            const entries = await fs.readdir(input.path, {
+                withFileTypes: true,
+            });
+            if (entries.length === 0) {
+                return ok('(empty directory)');
+            }
+            const lines = entries.map(entry => {
+                if (entry.isDirectory()) {
+                    return `[DIR]  ${entry.name}/`;
+                }
+                return `[FILE] ${entry.name}`;
+            });
+            return ok(lines.join('\n'));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Failed to list directory: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 9. webfetch
+// ---------------------------------------------------------------------------
+const webfetchSchema = z.object({
+    url: z.string().url().describe('URL to fetch content from'),
+    prompt: z.string().optional().describe('Optional prompt describing what information to extract'),
+});
+/** Maximum characters returned from a fetched page. */
+const WEBFETCH_MAX_CHARS = 50_000;
+export const webfetchTool = {
+    name: 'webfetch',
+    description: 'Fetch content from a URL and optionally process it with a prompt.',
+    inputSchema: webfetchSchema,
+    permissionTier: 'ask_once',
+    category: 'standard',
+    async execute(raw) {
+        try {
+            const input = webfetchSchema.parse(raw);
+            const response = await fetch(input.url);
+            if (!response.ok) {
+                return err(`HTTP ${response.status} ${response.statusText} fetching ${input.url}`);
+            }
+            let text = await response.text();
+            if (text.length > WEBFETCH_MAX_CHARS) {
+                text = `${text.slice(0, WEBFETCH_MAX_CHARS)}\n\n... (truncated, ${text.length} total characters)`;
+            }
+            if (input.prompt) {
+                // Attempt to process the fetched content through a fast LLM model.
+                // Falls back to returning raw text if the router is unavailable or
+                // the LLM call fails for any reason.
+                try {
+                    const { getAppContext } = await import('../../app');
+                    const ctx = getAppContext();
+                    if (ctx?.router) {
+                        const stream = ctx.router.routeStream({
+                            messages: [
+                                {
+                                    role: 'system',
+                                    content: 'You are a content extraction assistant. The user will provide web page content and a question or instruction. Extract the requested information concisely from the content. Do not add information that is not present in the content.',
+                                },
+                                {
+                                    role: 'user',
+                                    content: `${input.prompt}\n\n---\n\nWeb page content from ${input.url}:\n\n${text}`,
+                                },
+                            ],
+                            model: 'haiku',
+                            maxTokens: 4096,
+                        }, 'summarization');
+                        let result = '';
+                        for await (const chunk of stream) {
+                            if (chunk.content) {
+                                result += chunk.content;
+                            }
+                        }
+                        if (result.length > 0) {
+                            return ok(result);
+                        }
+                    }
+                }
+                catch {
+                    // LLM processing failed — fall through to raw text response.
+                }
+                return ok(`[Prompt: ${input.prompt}]\n\n${text}`);
+            }
+            return ok(text);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Fetch failed: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 10. todo_read
+// ---------------------------------------------------------------------------
+const todoReadSchema = z.object({}).describe('No input required');
+export const todoReadTool = {
+    name: 'todo_read',
+    description: "Read the current session's task list.",
+    inputSchema: todoReadSchema,
+    permissionTier: 'auto_allow',
+    category: 'standard',
+    async execute(_raw) {
+        try {
+            const { getDb } = await import('../../state/db');
+            const db = getDb();
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS todos (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          subject TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'pending',
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        )
+      `);
+            const rows = db.query('SELECT id, subject, status FROM todos ORDER BY id').all();
+            if (rows.length === 0) {
+                return ok('No tasks yet.');
+            }
+            const lines = rows.map(r => {
+                const indicator = r.status === 'completed' ? '[x]' : r.status === 'in_progress' ? '[~]' : '[ ]';
+                return `${r.id}. ${indicator} ${r.subject}`;
+            });
+            return ok(lines.join('\n'));
+        }
+        catch (error) {
+            // Fallback to original placeholder behavior on DB failure.
+            return ok('No tasks yet.');
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 11. todo_write
+// ---------------------------------------------------------------------------
+const todoWriteSchema = z.object({
+    tasks: z
+        .array(z.object({
+        subject: z.string().describe('Brief task title'),
+        status: z
+            .enum(['pending', 'in_progress', 'completed'])
+            .describe('Current status of the task'),
+    }))
+        .describe('Array of tasks to write to the session'),
+});
+export const todoWriteTool = {
+    name: 'todo_write',
+    description: "Update the session's task list.",
+    inputSchema: todoWriteSchema,
+    permissionTier: 'auto_allow',
+    category: 'standard',
+    async execute(raw) {
+        try {
+            const input = todoWriteSchema.parse(raw);
+            const { getDb } = await import('../../state/db');
+            const db = getDb();
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS todos (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          subject TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'pending',
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        )
+      `);
+            // Replace strategy: clear existing rows and insert the new set.
+            db.exec('DELETE FROM todos');
+            const insert = db.prepare('INSERT INTO todos (subject, status) VALUES (?, ?)');
+            const insertAll = db.transaction((tasks) => {
+                for (const t of tasks) {
+                    insert.run(t.subject, t.status);
+                }
+            });
+            insertAll(input.tasks);
+            const summary = input.tasks.map(t => {
+                const indicator = t.status === 'completed' ? '[x]' : t.status === 'in_progress' ? '[~]' : '[ ]';
+                return `${indicator} ${t.subject}`;
+            });
+            return ok(`Task list updated (${input.tasks.length} task${input.tasks.length === 1 ? '' : 's'}):\n${summary.join('\n')}`);
+        }
+        catch (error) {
+            // Fallback to original placeholder behavior on DB failure.
+            const message = error instanceof Error ? error.message : String(error);
+            return err(`Failed to update tasks: ${message}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// 12. web_search — Multi-engine search helpers
+// ---------------------------------------------------------------------------
+/**
+ * Search using the Brave Search API. Returns formatted markdown results
+ * or null if the request fails (allowing fallback to DuckDuckGo).
+ */
+async function searchBrave(query, maxResults, apiKey) {
+    try {
+        const encodedQuery = encodeURIComponent(query);
+        const response = await fetch(`https://api.search.brave.com/res/v1/web/search?q=${encodedQuery}&count=${maxResults}`, {
+            headers: {
+                Accept: 'application/json',
+                'Accept-Encoding': 'gzip',
+                'X-Subscription-Token': apiKey,
+            },
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        const results = [];
+        // Featured snippet
+        if (data.mixed?.main?.[0]?.type === 'faq') {
+            const faq = data.mixed.main[0];
+            if (faq.results?.[0]?.answer) {
+                results.push(`## Featured Answer\n${faq.results[0].answer}\n`);
+            }
+        }
+        // Web results
+        if (data.web?.results) {
+            results.push('## Results');
+            for (const r of data.web.results.slice(0, maxResults)) {
+                results.push(`### ${r.title}\n${r.description || ''}\nURL: ${r.url}\n`);
+            }
+        }
+        // Knowledge graph
+        if (data.infobox?.results?.[0]) {
+            const info = data.infobox.results[0];
+            results.push(`## ${info.title || 'Info'}\n${info.description || ''}`);
+        }
+        return results.length > 0 ? results.join('\n') : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Search using DuckDuckGo Instant Answer API. Returns formatted markdown
+ * results. This is the fallback engine that requires no API key.
+ */
+async function searchDuckDuckGo(query, maxResults) {
+    const encodedQuery = encodeURIComponent(query);
+    // Try the Instant Answer API first for direct answers
+    const iaResponse = await fetch(`https://api.duckduckgo.com/?q=${encodedQuery}&format=json&no_html=1&skip_disambig=1`);
+    const results = [];
+    if (iaResponse.ok) {
+        const data = (await iaResponse.json());
+        // Abstract (direct answer)
+        if (data.Abstract) {
+            results.push(`## Direct Answer\n${data.Abstract}\nSource: ${data.AbstractURL}\n`);
+        }
+        // Definition
+        if (data.Definition) {
+            results.push(`## Definition\n${data.Definition}\nSource: ${data.DefinitionURL}\n`);
+        }
+        // Answer (calculations, conversions, etc.)
+        if (data.Answer) {
+            results.push(`## Answer\n${data.Answer}\n`);
+        }
+        // Related topics
+        if (data.RelatedTopics && Array.isArray(data.RelatedTopics)) {
+            const topics = data.RelatedTopics.filter((t) => t.Text && t.FirstURL).slice(0, maxResults);
+            if (topics.length > 0) {
+                results.push('## Results');
+                for (const topic of topics) {
+                    results.push(`- ${topic.Text}\n  URL: ${topic.FirstURL}`);
+                }
+            }
+        }
+        // Infobox
+        if (data.Infobox?.content?.length > 0) {
+            results.push('## Info');
+            for (const item of data.Infobox.content.slice(0, 5)) {
+                if (item.label && item.value) {
+                    results.push(`- ${item.label}: ${item.value}`);
+                }
+            }
+        }
+        // Redirect (if DDG suggests a better page)
+        if (data.Redirect) {
+            results.push(`\nSuggested page: ${data.Redirect}`);
+        }
+    }
+    // If Instant Answer API returned nothing, try the HTML lite endpoint
+    if (results.length === 0) {
+        try {
+            const htmlResponse = await fetch(`https://html.duckduckgo.com/html/?q=${encodedQuery}`, {
+                headers: { 'User-Agent': 'Mozilla/5.0 (compatible; Nimbus-CLI/1.0)' },
+            });
+            if (htmlResponse.ok) {
+                const html = await htmlResponse.text();
+                // Parse result snippets from the lite HTML page
+                const resultPattern = /<a rel="nofollow" class="result__a" href="([^"]+)"[^>]*>([^<]+)<\/a>[\s\S]*?<a class="result__snippet"[^>]*>([^<]*)<\/a>/g;
+                let match;
+                let count = 0;
+                results.push('## Results');
+                while ((match = resultPattern.exec(html)) !== null && count < maxResults) {
+                    const url = match[1].startsWith('//') ? `https:${match[1]}` : match[1];
+                    const title = match[2]
+                        .replace(/&#x27;/g, "'")
+                        .replace(/&amp;/g, '&')
+                        .replace(/&quot;/g, '"');
+                    const snippet = match[3]
+                        .replace(/<\/?b>/g, '**')
+                        .replace(/&#x27;/g, "'")
+                        .replace(/&amp;/g, '&');
+                    results.push(`### ${title}\n${snippet}\nURL: ${url}\n`);
+                    count++;
+                }
+            }
+        }
+        catch {
+            // HTML fallback failed — fall through to "no results" message
+        }
+    }
+    if (results.length === 0) {
+        return `No results found for: "${query}". Try rephrasing the query or using more specific terms.\n\nTip: Set BRAVE_SEARCH_API_KEY env var for significantly better web search results.`;
+    }
+    return results.join('\n');
+}
+// ---------------------------------------------------------------------------
+// 12. web_search
+// ---------------------------------------------------------------------------
+const webSearchSchema = z.object({
+    query: z.string().describe('The search query string'),
+    maxResults: z
+        .number()
+        .optional()
+        .default(5)
+        .describe('Maximum number of results to return (default: 5)'),
+    engine: z
+        .enum(['auto', 'duckduckgo', 'brave'])
+        .optional()
+        .default('auto')
+        .describe('Search engine to use (default: auto)'),
+});
+export const webSearchTool = {
+    name: 'web_search',
+    description: 'Search the web using a query string. Returns titles, URLs, and snippets. ' +
+        'Supports Brave Search (set BRAVE_SEARCH_API_KEY) and DuckDuckGo. ' +
+        'Useful for finding documentation, looking up error messages, or researching technologies.',
+    inputSchema: webSearchSchema,
+    permissionTier: 'ask_once',
+    category: 'standard',
+    async execute(raw) {
+        try {
+            const input = webSearchSchema.parse(raw);
+            // Try Brave Search API first if key is available, then DuckDuckGo as fallback
+            const braveKey = process.env.BRAVE_SEARCH_API_KEY;
+            if ((input.engine === 'brave' || input.engine === 'auto') && braveKey) {
+                const result = await searchBrave(input.query, input.maxResults, braveKey);
+                if (result) {
+                    return ok(result);
+                }
+                if (input.engine === 'brave') {
+                    return err('Brave Search failed and no fallback allowed');
+                }
+            }
+            // DuckDuckGo HTML search (better results than Instant Answer API)
+            const result = await searchDuckDuckGo(input.query, input.maxResults);
+            return ok(result);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return err(`Web search failed: ${msg}`);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Aggregate export
+// ---------------------------------------------------------------------------
+/** All 12 standard tools as an ordered array. */
+export const standardTools = [
+    readFileTool,
+    editFileTool,
+    multiEditTool,
+    writeFileTool,
+    bashTool,
+    globTool,
+    grepTool,
+    listDirTool,
+    webfetchTool,
+    todoReadTool,
+    todoWriteTool,
+    webSearchTool,
+];