flashlite 0.0.0-stage → 0.1.0

package/dist/tools.js

@@ -0,0 +1,889 @@
+// tools.ts — filesystem tools, path confinement, and separately approved commands.
+// File operations stay inside cwd unless the host grants live absolute access.
+// Commands are NOT sandboxed and require a separate approval snapshot.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { constants } from 'node:fs';
+import { readPage, searchFile } from "./boundedfs.js";
+import { absoluteCommandRisk, commandPolicy } from "./commandpolicy.js";
+import { executeCommand, validateCommand, sanitizeCommandOutput, DEFAULT_COMMAND_TIMEOUT_MS, MAX_COMMAND_TIMEOUT_MS } from "./terminal.js";
+import { parseTodos } from "./todo.js";
+export const MAX_READ_BYTES = 256 * 1024;
+/** Default page for read_file: ~8K tokens. The model can still ask for up to MAX_READ_BYTES. */
+export const DEFAULT_READ_BYTES = 32 * 1024;
+export const MAX_WRITE_BYTES = 1024 * 1024;
+export const MAX_LIST_ENTRIES = 500;
+export const MAX_GREP_RESULTS = 200;
+export const MAX_GREP_FILES = 5000;
+export const MAX_GREP_OUTPUT_BYTES = 64 * 1024;
+export const DEFAULT_GREP_SCAN_BYTES = 16 * 1024 * 1024;
+export const MAX_GREP_SCAN_BYTES = 100 * 1024 * 1024;
+export const MAX_DIRECTORY_SCAN_ENTRIES = 100000;
+export const MAX_BATCH_FILES = 20;
+export const MAX_TREE_ENTRIES = 5000;
+export const MAX_TREE_BYTES = 100 * 1024 * 1024;
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.venv', 'venv', '__pycache__', '.next', 'dist', 'build']);
+const SKIP_FILES = new Set(['.DS_Store']);
+const FILE_PATH_DESCRIPTION = 'relative path; absolute/~/.. only in unguarded auto';
+export class ConfinementError extends Error {
+}
+/**
+ * Confine a tool-supplied path to the working directory. Two checks, like the Swift
+ * FileToolbox: (1) the raw path must be relative (no absolute, ~, or drive-letter
+ * forms); (2) after resolution, both the lexical path and the realpath of its deepest
+ * existing ancestor must live under realpath(cwd), so symlinks can't escape.
+ * Returns the resolved absolute path to operate on.
+ */
+export async function confined(cwd, raw) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new ConfinementError('path must be a non-empty string');
+    }
+    if (raw.startsWith('~') || raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw)) {
+        throw new ConfinementError(`path must be relative to the working directory, got: ${raw}`);
+    }
+    if (raw.includes('\0'))
+        throw new ConfinementError('path contains a null byte');
+    // Anchor everything at the real cwd — on macOS tmpdir/realpath differ (/var vs /private/var).
+    const realCwd = await fs.realpath(cwd);
+    const resolved = path.resolve(realCwd, raw);
+    if (resolved !== realCwd && !resolved.startsWith(realCwd + path.sep)) {
+        throw new ConfinementError(`path escapes the working directory: ${raw}`);
+    }
+    // Symlink escape guard: realpath the deepest existing ancestor and re-check.
+    let probe = resolved;
+    try {
+        probe = await fs.realpath(resolved);
+    }
+    catch {
+        let dir = path.dirname(resolved);
+        while (true) {
+            try {
+                const realDir = await fs.realpath(dir);
+                const rest = resolved.slice(dir.length).split(path.sep).filter(Boolean);
+                probe = path.join(realDir, ...rest);
+                break;
+            }
+            catch {
+                const parent = path.dirname(dir);
+                if (parent === dir) {
+                    probe = resolved;
+                    break;
+                }
+                dir = parent;
+            }
+        }
+    }
+    if (probe !== realCwd && !probe.startsWith(realCwd + path.sep)) {
+        throw new ConfinementError(`path resolves outside the working directory (symlink): ${raw}`);
+    }
+    // A dangling symlink has no realpath; never let creation follow it outside cwd.
+    let ancestor = resolved;
+    while (ancestor !== realCwd) {
+        const stat = await fs.lstat(ancestor).catch(() => null);
+        if (stat?.isSymbolicLink()) {
+            await fs.realpath(ancestor).catch(() => {
+                throw new ConfinementError('dangling symlinks are not supported');
+            });
+        }
+        ancestor = path.dirname(ancestor);
+    }
+    return resolved;
+}
+// A host-only capability scoped to one execution, never model-supplied arguments.
+const absoluteAccess = new AsyncLocalStorage();
+const execution = new AsyncLocalStorage();
+function checkExecution() {
+    const options = execution.getStore();
+    options?.signal?.throwIfAborted();
+    if (options?.fileAuthorizationEnabled && !options.fileAuthorizationEnabled()) {
+        throw new Error('file authorization revoked — request approval again');
+    }
+    if (options?.absoluteAccess === true && !options.absoluteEnabled?.()) {
+        throw new Error('unguarded authorization revoked — request approval again');
+    }
+}
+function readRedactions() {
+    return absoluteAccess.getStore() === true ? execution.getStore()?.redactValues ?? [] : [];
+}
+async function toolPath(cwd, raw, unrestricted = absoluteAccess.getStore() === true) {
+    if (!unrestricted)
+        return confined(cwd, raw);
+    if (typeof raw !== 'string' || raw.trim() === '')
+        throw new ConfinementError('path must be a non-empty string');
+    if (raw.includes('\0'))
+        throw new ConfinementError('path contains a null byte');
+    const expanded = raw === '~' ? os.homedir() : raw.startsWith('~/') ? path.join(os.homedir(), raw.slice(2)) : raw;
+    return path.resolve(await fs.realpath(cwd), expanded);
+}
+export const TOOL_DEFINITIONS = [
+    {
+        name: 'run_command',
+        description: 'Run a noninteractive shell command for tests/builds or work file tools cannot do. NOT sandboxed. Needs separate command authorization; guarded auto still asks for network, installs, sudo, external paths, destructive Git or opaque syntax. Prefer one focused command over multiple calls. No background jobs or interactive input. Output is capped; default timeout 60s.',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'shell command, up to 16 KiB' },
+                cwd: { type: 'string', description: 'existing directory (default .); external only in unguarded auto' },
+                timeout_ms: { type: 'integer', minimum: 1, maximum: MAX_COMMAND_TIMEOUT_MS, default: DEFAULT_COMMAND_TIMEOUT_MS },
+            },
+            required: ['command'],
+        },
+        requiresApproval: true,
+        approvalScope: 'always',
+    },
+    {
+        name: 'read_file',
+        description: 'Read UTF-8 text. Small files return plain text; paged reads return JSON {content, total_bytes, next_offset_bytes}; pass next_offset_bytes as offset_bytes to continue. Page default 32 KiB, max 256 KiB. Binary files are refused.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: FILE_PATH_DESCRIPTION },
+                offset_bytes: { type: 'integer', minimum: 0, description: 'byte offset (default 0); use returned next_offset_bytes' },
+                max_bytes: { type: 'integer', minimum: 1, maximum: MAX_READ_BYTES, default: DEFAULT_READ_BYTES, description: 'page size in bytes (at least 4)' },
+            },
+            required: ['path'],
+        },
+        requiresApproval: false,
+    },
+    {
+        name: 'write_file',
+        description: 'Write a text file, creating parent directories; overwrites if it exists. Max 1 MB.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: FILE_PATH_DESCRIPTION },
+                content: { type: 'string', description: 'full new file contents' },
+            },
+            required: ['path', 'content'],
+        },
+        requiresApproval: true,
+    },
+    {
+        name: 'edit_file',
+        description: 'Replace one exact, unique occurrence of old_string in a text file (1 MiB limit). Read the file first to copy the exact text.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: FILE_PATH_DESCRIPTION },
+                old_string: { type: 'string', description: 'exact text to replace, unique in the file' },
+                new_string: { type: 'string', description: 'replacement text' },
+            },
+            required: ['path', 'old_string', 'new_string'],
+        },
+        requiresApproval: true,
+    },
+    {
+        name: 'list_dir',
+        description: 'List directory entries in lexical order (directories end in /), paged via next_offset.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: FILE_PATH_DESCRIPTION },
+                offset: { type: 'integer', minimum: 0, maximum: MAX_DIRECTORY_SCAN_ENTRIES, default: 0, description: 'entries to skip; use returned next_offset' },
+                limit: { type: 'integer', minimum: 1, maximum: MAX_LIST_ENTRIES, default: MAX_LIST_ENTRIES },
+            },
+            required: ['path'],
+        },
+        requiresApproval: false,
+    },
+    {
+        name: 'grep',
+        description: 'Literal text search (not regex) over a file or directory. Returns file:line:text matches and byte offsets for cropped snippets. Skips symlinks and special files; normally skips dependency/build dirs. Partial results do not prove absence: continue a file via next_start_byte or narrow a directory search.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'literal text to search for' },
+                path: { type: 'string', description: `search file or directory (default .); ${FILE_PATH_DESCRIPTION}` },
+                include: { type: 'string', description: 'only files whose path contains this string' },
+                start_byte: { type: 'integer', minimum: 0, default: 0, description: 'file-only zero-based byte search offset; retry returned next_start_byte with same file path and pattern' },
+                max_results: { type: 'integer', minimum: 1, maximum: MAX_GREP_RESULTS, default: MAX_GREP_RESULTS },
+                max_output_bytes: { type: 'integer', minimum: 1024, maximum: MAX_GREP_OUTPUT_BYTES, default: MAX_GREP_OUTPUT_BYTES, description: 'aggregate response byte budget including status/continuation metadata' },
+                max_scan_bytes: { type: 'integer', minimum: 1, maximum: MAX_GREP_SCAN_BYTES, default: DEFAULT_GREP_SCAN_BYTES, description: 'aggregate search bytes; increase or continue an exact file when partial' },
+            },
+            required: ['pattern'],
+        },
+        requiresApproval: false,
+    },
+    {
+        name: 'read_files',
+        description: 'Read up to 20 text files together. Returns JSON with content or an error for each path; 256 KB total content budget.',
+        parameters: {
+            type: 'object',
+            properties: { paths: { type: 'array', items: { type: 'string', description: FILE_PATH_DESCRIPTION }, minItems: 1, maxItems: MAX_BATCH_FILES } },
+            required: ['paths'],
+        },
+        requiresApproval: false,
+    },
+    {
+        name: 'file_info',
+        description: 'Inspect a file or directory without reading its content: type, size, permissions and modification time. Does not follow a final symlink.',
+        parameters: {
+            type: 'object', properties: { path: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['path'],
+        },
+        requiresApproval: false,
+    },
+    {
+        name: 'find_files',
+        description: 'Find files/directories recursively by literal path substring (not glob/regex). Skips symlinks, and outside unguarded auto .git/dependency/build dirs. Up to 500 results.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: `search directory (default .); ${FILE_PATH_DESCRIPTION}` },
+                pattern: { type: 'string', description: 'literal path substring (default all)' },
+                type: { type: 'string', enum: ['file', 'directory', 'all'], description: 'default all' },
+            },
+        },
+        requiresApproval: false,
+    },
+    {
+        name: 'make_dir',
+        description: 'Create a directory and missing parent directories. Existing directories are unchanged.',
+        parameters: {
+            type: 'object', properties: { path: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['path'],
+        },
+        requiresApproval: true,
+    },
+    {
+        name: 'copy_path',
+        description: 'Copy a file (binary ok) or directory tree to a new path. Never overwrites; refuses symlinks, special files and trees over 5000 entries / 100 MiB, and outside unguarded auto .git data.',
+        parameters: {
+            type: 'object', properties: { source: { type: 'string', description: FILE_PATH_DESCRIPTION }, destination: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['source', 'destination'],
+        },
+        requiresApproval: true,
+    },
+    {
+        name: 'move_path',
+        description: 'Move or rename a file/directory; across the drive in unguarded auto. Never overwrites; same limits as copy_path.',
+        parameters: {
+            type: 'object', properties: { source: { type: 'string', description: FILE_PATH_DESCRIPTION }, destination: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['source', 'destination'],
+        },
+        requiresApproval: true,
+    },
+    {
+        name: 'remove_path',
+        description: 'Permanently remove a file/directory — this cannot be undone; use git (or read/copy first) to recover. Outside unguarded auto it cannot remove the working directory or its ancestors, .git internals, or symlink trees.',
+        parameters: {
+            type: 'object', properties: { path: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['path'],
+        },
+        requiresApproval: true,
+    },
+    {
+        name: 'todo_write',
+        description: 'Track the task as a todo list. Each item has a content string and a status of pending, in_progress, completed, or cancelled. Pass the full list each time; items are replaced, not merged.',
+        parameters: {
+            type: 'object',
+            properties: {
+                todos: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            content: { type: 'string', description: 'the task description' },
+                            status: { type: 'string', enum: ['pending', 'in_progress', 'completed', 'cancelled'] },
+                        },
+                        required: ['content'],
+                    },
+                },
+            },
+            required: ['todos'],
+        },
+        requiresApproval: false,
+    },
+];
+const toolByName = new Map(TOOL_DEFINITIONS.map((t) => [t.name, t]));
+function argString(args, key) {
+    const v = args[key];
+    return typeof v === 'string' ? v : '';
+}
+function requiredString(args, key, allowEmpty = false) {
+    const value = args[key];
+    if (typeof value !== 'string' || (!allowEmpty && !value))
+        throw new Error(`${key} must be a ${allowEmpty ? '' : 'non-empty '}string`);
+    return value;
+}
+function integerArg(args, key, fallback, min, max = Number.MAX_SAFE_INTEGER) {
+    const value = args[key] === undefined ? fallback : args[key];
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min || value > max) {
+        throw new Error(`${key} must be an integer between ${min} and ${max}`);
+    }
+    return value;
+}
+async function readText(abs, limit = MAX_READ_BYTES) {
+    checkExecution();
+    const stat = await fs.stat(abs);
+    if (!stat.isFile())
+        throw new Error('not a regular file — use list_dir for directories');
+    if (stat.size > limit)
+        throw new Error(`file is ${stat.size} bytes (limit ${limit}) — use read_file with offset_bytes/max_bytes, or grep with this file path`);
+    const file = await fs.open(await fs.realpath(abs), constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    try {
+        if (!(await file.stat()).isFile())
+            throw new Error('not a regular file');
+        const buffer = Buffer.alloc(limit + 1);
+        let used = 0;
+        while (used < buffer.length) {
+            checkExecution();
+            const { bytesRead } = await file.read(buffer, used, buffer.length - used, null);
+            checkExecution();
+            if (!bytesRead)
+                break;
+            used += bytesRead;
+        }
+        if (used > limit)
+            throw new Error(`file exceeds ${limit} bytes — use grep to search it`);
+        const bytes = buffer.subarray(0, used);
+        if (bytes.includes(0))
+            throw new Error('binary file — use file_info or copy_path');
+        return bytes;
+    }
+    finally {
+        await file.close();
+    }
+}
+async function execReadFile(cwd, args) {
+    const abs = await toolPath(cwd, args.path);
+    const offset = integerArg(args, 'offset_bytes', 0, 0);
+    const limit = integerArg(args, 'max_bytes', DEFAULT_READ_BYTES, 1, MAX_READ_BYTES);
+    const page = await readPage(abs, offset, limit, checkExecution, readRedactions());
+    const whole = args.offset_bytes === undefined && args.max_bytes === undefined && page.next_offset_bytes === null;
+    return { toolCallId: '', content: whole ? page.content : JSON.stringify({ path: args.path, ...page }) };
+}
+async function writeText(abs, content) {
+    const file = await fs.open(abs, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o666);
+    try {
+        if (!(await file.stat()).isFile())
+            throw new Error('writes require a regular file');
+        checkExecution(); // immediately before destructive commit
+        await file.truncate(0);
+        await file.writeFile(content, 'utf8');
+    }
+    finally {
+        await file.close();
+    }
+}
+async function execWriteFile(cwd, args) {
+    const abs = await mutablePath(cwd, args.path);
+    const content = requiredString(args, 'content', true);
+    if (Buffer.byteLength(content) > MAX_WRITE_BYTES) {
+        throw new Error(`content is ${Buffer.byteLength(content)} bytes (limit ${MAX_WRITE_BYTES})`);
+    }
+    checkExecution();
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await writeText(abs, content);
+    return { toolCallId: '', content: `wrote ${Buffer.byteLength(content)} bytes to ${argString(args, 'path')}` };
+}
+async function execEditFile(cwd, args) {
+    const abs = await mutablePath(cwd, args.path);
+    const oldString = requiredString(args, 'old_string');
+    const newString = requiredString(args, 'new_string', true);
+    const original = (await readText(abs, MAX_WRITE_BYTES)).toString('utf8');
+    const first = original.indexOf(oldString);
+    if (first === -1)
+        throw new Error('old_string not found in the file — read it first for the exact text');
+    if (original.indexOf(oldString, first + 1) !== -1) {
+        throw new Error('old_string matches more than once — make it unique');
+    }
+    const edited = original.slice(0, first) + newString + original.slice(first + oldString.length);
+    if (Buffer.byteLength(edited) > MAX_WRITE_BYTES)
+        throw new Error(`edited file exceeds ${MAX_WRITE_BYTES} bytes`);
+    await writeText(abs, edited);
+    return { toolCallId: '', content: `edited ${argString(args, 'path')} (${original.length} -> ${edited.length} bytes)` };
+}
+async function execListDir(cwd, args) {
+    const abs = await toolPath(cwd, args.path);
+    const offset = integerArg(args, 'offset', 0, 0, MAX_DIRECTORY_SCAN_ENTRIES);
+    const limit = integerArg(args, 'limit', MAX_LIST_ENTRIES, 1, MAX_LIST_ENTRIES);
+    const entries = [];
+    let partial = false;
+    checkExecution();
+    const dir = await fs.opendir(abs).catch(() => { throw new Error(`no such directory: ${argString(args, 'path')}`); });
+    for await (const entry of dir) {
+        checkExecution();
+        if (entries.length >= MAX_DIRECTORY_SCAN_ENTRIES) {
+            partial = true;
+            break;
+        }
+        entries.push({ name: entry.name, directory: entry.isDirectory() });
+    }
+    // Compare raw names (not locale-dependent, and directory suffixes don't affect order).
+    entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const page = entries.slice(offset, offset + limit);
+    let content = page.map((entry) => entry.name + (entry.directory ? '/' : '')).join('\n') || (offset ? '(end of directory)' : '(empty directory)');
+    const next = offset + page.length;
+    if (partial)
+        content += `\n… (partial listing: scan capped at ${MAX_DIRECTORY_SCAN_ENTRIES} entries; sorted scanned subset only, no exhaustive next_offset; inspect narrower subdirectories)`;
+    else if (next < entries.length)
+        content += `\n… (${entries.length - next} more entries; next_offset: ${next}; retry list_dir with same path and offset: ${next})`;
+    return { toolCallId: '', content };
+}
+function skipSearchEntry(name) {
+    return absoluteAccess.getStore() !== true && (SKIP_DIRS.has(name) || SKIP_FILES.has(name));
+}
+async function walk(base, include, onFile) {
+    const stack = [base];
+    let seen = 0, skipped = 0;
+    while (stack.length) {
+        checkExecution();
+        const current = stack.pop();
+        if (!(await fs.lstat(current)).isDirectory()) {
+            skipped++;
+            continue;
+        }
+        const dir = await fs.opendir(current).catch(() => null);
+        if (!dir) {
+            checkExecution();
+            skipped++;
+            continue;
+        }
+        for await (const e of dir) {
+            checkExecution();
+            if (++seen > MAX_GREP_FILES)
+                return { capped: true, skipped };
+            if (skipSearchEntry(e.name) || e.isSymbolicLink())
+                continue;
+            const abs = path.join(dir.path, e.name);
+            if (e.isDirectory())
+                stack.push(abs);
+            else if (e.isFile()) {
+                const rel = path.relative(base, abs);
+                if (include && !rel.includes(include))
+                    continue;
+                if (await onFile(abs, rel))
+                    return { capped: true, skipped };
+            }
+            else
+                skipped++;
+        }
+    }
+    return { capped: false, skipped };
+}
+async function execGrep(cwd, args) {
+    const pattern = requiredString(args, 'pattern');
+    if (Buffer.byteLength(pattern) > 4096 || /[\r\n]/.test(pattern))
+        throw new Error('pattern must be at most 4096 UTF-8 bytes with no newlines; narrow the literal pattern');
+    const include = argString(args, 'include');
+    const startAbs = await toolPath(cwd, args.path === undefined ? '.' : args.path);
+    const stat = await fs.lstat(startAbs);
+    if (!stat.isFile() && !stat.isDirectory())
+        throw new Error('grep needs a regular file or directory; symlinks/special files are not searched');
+    const startByte = integerArg(args, 'start_byte', 0, 0);
+    if (stat.isDirectory() && startByte !== 0)
+        throw new Error('start_byte only supports a regular file path; narrow path to a file first');
+    const resultLimit = integerArg(args, 'max_results', MAX_GREP_RESULTS, 1, MAX_GREP_RESULTS);
+    const outputLimit = integerArg(args, 'max_output_bytes', MAX_GREP_OUTPUT_BYTES, 1024, MAX_GREP_OUTPUT_BYTES);
+    const scanLimit = integerArg(args, 'max_scan_bytes', DEFAULT_GREP_SCAN_BYTES, 1, MAX_GREP_SCAN_BYTES);
+    const results = [];
+    let outputBytes = 0, scanned = 0, skipped = 0, partial = false, snippets = 0;
+    let nextByte = null, nextFile = '', reason = '';
+    // Reserve status space in the aggregate budget, never append unbounded metadata.
+    const statusReserve = 512;
+    const search = async (abs, rel) => {
+        checkExecution();
+        if (scanned >= scanLimit) {
+            partial = true;
+            reason = 'scan byte budget reached';
+            nextByte = 0;
+            nextFile = rel;
+            return true;
+        }
+        try {
+            const progress = await searchFile(abs, Buffer.from(pattern), stat.isFile() ? startByte : 0, scanLimit - scanned, checkExecution, readRedactions(), (match) => {
+                const position = match.snippet || match.line === null ? ` [byte_offset: ${match.byte}; snippet]` : '';
+                let row = `${rel}:${match.line ?? '?'}:${match.content}${position}`;
+                for (const value of readRedactions())
+                    if (value)
+                        row = row.replaceAll(value, '[REDACTED]');
+                const bytes = Buffer.byteLength(row) + (results.length ? 1 : 0);
+                if (results.length >= resultLimit || outputBytes + bytes > outputLimit - statusReserve)
+                    return true;
+                results.push(row);
+                outputBytes += bytes;
+                if (match.snippet)
+                    snippets++;
+                return false;
+            });
+            scanned += progress.bytesRead;
+            if (progress.reason) {
+                partial = true;
+                if (progress.nextByte !== null) {
+                    nextByte = progress.nextByte;
+                    nextFile = rel;
+                    reason = progress.reason;
+                    return true;
+                }
+                skipped++;
+            }
+        }
+        catch (err) {
+            checkExecution(); // never swallow abort or live authorization revocation as a skip
+            if (stat.isFile())
+                throw err;
+            skipped++;
+            partial = true;
+        }
+        return false;
+    };
+    let traversal = { capped: false, skipped: 0 };
+    if (stat.isFile()) {
+        if (!include || argString(args, 'path').includes(include))
+            await search(startAbs, path.basename(startAbs));
+    }
+    else
+        traversal = await walk(startAbs, include, search);
+    skipped += traversal.skipped;
+    partial ||= traversal.capped || skipped > 0;
+    let content = results.join('\n') || (partial ? '(no matches in searched portion)' : '(no matches)');
+    const notes = [];
+    if (partial) {
+        notes.push(`partial search: ${reason || (traversal.capped ? `entries at ${MAX_GREP_FILES} capped` : 'files/directories skipped')}; skipped: ${skipped}; scanned_bytes: ${scanned}`);
+        if (nextByte !== null) {
+            notes.push(`next_start_byte: ${nextByte}`);
+            if (stat.isFile())
+                notes.push('retry same file path/pattern with start_byte: next_start_byte');
+            else {
+                const retryPath = sanitizeCommandOutput(JSON.stringify(path.join(typeof args.path === 'string' ? args.path : '.', nextFile)), readRedactions());
+                notes.push(Buffer.byteLength(retryPath) <= 128 ?
+                    `continue file path ${retryPath} with start_byte: next_start_byte; directory traversal incomplete — no exhaustive cursor` :
+                    'file path too long for bounded status; narrow path to a file; directory traversal incomplete — no exhaustive cursor');
+            }
+        }
+        notes.push('narrow path/include or raise max_scan_bytes/max_results/max_output_bytes within limits');
+    }
+    if (snippets)
+        notes.push(`truncated match snippets: ${snippets}; use read_file offset_bytes near byte_offset for full text`);
+    if (notes.length) {
+        // Sanitize BEFORE clipping so clipping cannot expose a fragment of a known key.
+        const status = sanitizeCommandOutput(`… (${notes.join('; ')})`, readRedactions());
+        const bytes = Buffer.from(status);
+        content += '\n' + (bytes.length <= statusReserve - 1 ? status : bytes.subarray(0, statusReserve - 4).toString('utf8') + '…');
+    }
+    return { toolCallId: '', content };
+}
+async function execReadFiles(cwd, args) {
+    if (!Array.isArray(args.paths) || !args.paths.length || args.paths.length > MAX_BATCH_FILES || args.paths.some((p) => typeof p !== 'string')) {
+        throw new Error(`paths must contain 1–${MAX_BATCH_FILES} strings`);
+    }
+    let remaining = MAX_READ_BYTES;
+    const results = [];
+    for (const raw of args.paths) {
+        checkExecution();
+        try {
+            const bytes = await readText(await toolPath(cwd, raw), remaining);
+            remaining -= bytes.length;
+            results.push({ path: raw, content: bytes.toString('utf8') });
+        }
+        catch (err) {
+            checkExecution();
+            results.push({ path: raw, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return { toolCallId: '', content: JSON.stringify(results) };
+}
+async function execFileInfo(cwd, args) {
+    const abs = await toolPath(cwd, args.path);
+    const stat = await fs.lstat(abs);
+    return { toolCallId: '', content: JSON.stringify({
+            path: args.path,
+            type: stat.isSymbolicLink() ? 'symlink' : stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'special',
+            size_bytes: stat.size,
+            permissions: (stat.mode & 0o777).toString(8).padStart(3, '0'),
+            modified_at: stat.mtime.toISOString(),
+        }) };
+}
+async function execFindFiles(cwd, args) {
+    const start = await toolPath(cwd, args.path ?? '.');
+    if (!(await fs.stat(start)).isDirectory())
+        throw new Error('find_files needs a directory');
+    const pattern = args.pattern === undefined ? '' : requiredString(args, 'pattern', true);
+    const type = args.type ?? 'all';
+    if (!['file', 'directory', 'all'].includes(type))
+        throw new Error('type must be file, directory, or all');
+    const results = [];
+    const stack = [start];
+    let seen = 0, capped = false;
+    while (stack.length && !capped) {
+        checkExecution();
+        const current = stack.pop();
+        if (!(await fs.lstat(current)).isDirectory())
+            throw new Error('search directory changed; retry find_files with a narrower path');
+        const dir = await fs.opendir(current);
+        for await (const entry of dir) {
+            checkExecution();
+            if (++seen > MAX_TREE_ENTRIES) {
+                capped = true;
+                break;
+            }
+            if (skipSearchEntry(entry.name) || entry.isSymbolicLink())
+                continue;
+            const abs = path.join(dir.path, entry.name);
+            const rel = path.relative(start, abs);
+            if (entry.isDirectory())
+                stack.push(abs);
+            if ((entry.isFile() || entry.isDirectory()) && rel.includes(pattern) &&
+                (type === 'all' || (type === 'file' ? entry.isFile() : entry.isDirectory()))) {
+                results.push(rel + (entry.isDirectory() ? '/' : ''));
+                if (results.length >= MAX_LIST_ENTRIES) {
+                    capped = true;
+                    break;
+                }
+            }
+        }
+    }
+    let content = results.sort().join('\n') || (capped ? '(no matches in searched portion)' : '(no matches)');
+    if (capped)
+        content += `\n… (partial search: capped at ${MAX_LIST_ENTRIES} results / ${MAX_TREE_ENTRIES} entries; narrow path/pattern/type or use list_dir pagination; no exhaustive continuation cursor)`;
+    return { toolCallId: '', content };
+}
+async function mutablePath(cwd, raw) {
+    const abs = await toolPath(cwd, raw);
+    if (absoluteAccess.getStore() === true)
+        return abs;
+    const root = await fs.realpath(cwd);
+    if (abs === root)
+        throw new Error('cannot mutate the working directory itself');
+    let probe = abs;
+    while (probe !== root) {
+        if (path.basename(probe) === '.git')
+            throw new Error('cannot mutate .git internals');
+        const stat = await fs.lstat(probe).catch((err) => {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        });
+        if (stat?.isSymbolicLink())
+            throw new Error('filesystem mutations do not support symlink paths');
+        probe = path.dirname(probe);
+    }
+    return abs;
+}
+async function requireMissing(abs) {
+    const exists = await fs.lstat(abs).catch((err) => {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    });
+    if (exists)
+        throw new Error('destination already exists — choose a new path; overwriting is not supported');
+}
+async function inspectTree(abs) {
+    const entries = [];
+    let bytes = 0;
+    const stack = [{ abs, rel: '' }];
+    while (stack.length) {
+        checkExecution();
+        const item = stack.pop();
+        if (entries.length >= MAX_TREE_ENTRIES)
+            throw new Error(`tree exceeds ${MAX_TREE_ENTRIES} entries`);
+        if (absoluteAccess.getStore() !== true && item.rel.split(path.sep).some((name) => name === '.git')) {
+            throw new Error('tree contains protected .git internals');
+        }
+        const stat = await fs.lstat(item.abs);
+        if (!stat.isDirectory() && !stat.isFile())
+            throw new Error('tree contains a symlink or special file — operation refused');
+        bytes += stat.isFile() ? stat.size : 0;
+        if (bytes > MAX_TREE_BYTES)
+            throw new Error('tree exceeds the 100 MiB limit');
+        entries.push({ ...item, directory: stat.isDirectory(), mode: stat.mode & 0o777 });
+        if (stat.isDirectory()) {
+            const dir = await fs.opendir(item.abs);
+            for await (const entry of dir) {
+                checkExecution();
+                if (entries.length + stack.length >= MAX_TREE_ENTRIES)
+                    throw new Error(`tree exceeds ${MAX_TREE_ENTRIES} entries`);
+                stack.push({ abs: path.join(item.abs, entry.name), rel: path.join(item.rel, entry.name) });
+            }
+        }
+    }
+    return entries;
+}
+async function execMakeDir(cwd, args) {
+    const abs = await mutablePath(cwd, args.path);
+    checkExecution();
+    await fs.mkdir(abs, { recursive: true });
+    return { toolCallId: '', content: `directory ready: ${args.path}` };
+}
+async function execTransfer(cwd, args, move) {
+    const source = await mutablePath(cwd, args.source);
+    const destination = await mutablePath(cwd, args.destination);
+    if (destination === source || destination.startsWith(source + path.sep))
+        throw new Error('destination must be outside the source tree');
+    await requireMissing(destination);
+    const entries = await inspectTree(source);
+    checkExecution();
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    if (move) {
+        checkExecution(); // immediately before committing the move
+        await fs.rename(source, destination);
+    }
+    else {
+        let created = false;
+        try {
+            for (const entry of entries) {
+                checkExecution();
+                const dest = path.join(destination, entry.rel);
+                // Recheck before each copy; never deliberately follow links from the source tree.
+                await mutablePath(cwd, path.relative(await fs.realpath(cwd), entry.abs));
+                const stat = await fs.lstat(entry.abs);
+                if (entry.directory ? !stat.isDirectory() : !stat.isFile())
+                    throw new Error('tree contains a symlink or special file — operation refused');
+                checkExecution();
+                if (entry.directory)
+                    await fs.mkdir(dest);
+                else
+                    await fs.copyFile(entry.abs, dest, constants.COPYFILE_EXCL);
+                if (!entry.rel)
+                    created = true;
+                checkExecution();
+                if (!entry.directory)
+                    await fs.chmod(dest, entry.mode);
+            }
+            checkExecution(); // cancellation after the final copy still rolls back this destination
+        }
+        catch (err) {
+            if (created)
+                await fs.rm(destination, { recursive: true, force: true });
+            throw err;
+        }
+    }
+    return { toolCallId: '', content: `${move ? 'moved' : 'copied'} ${args.source} → ${args.destination} (${entries.length} entries)` };
+}
+async function execRemovePath(cwd, args) {
+    const abs = await mutablePath(cwd, args.path);
+    await inspectTree(abs);
+    const projectRoot = await fs.realpath(cwd);
+    const relative = path.relative(projectRoot, abs);
+    // Deletion is permanent and cannot be undone — always refuse the working directory
+    // and its ancestors, even in unguarded auto where mutablePath does not block them.
+    if (abs === projectRoot || projectRoot.startsWith(abs + path.sep)) {
+        throw new Error('cannot permanently delete the working directory or one of its ancestors');
+    }
+    checkExecution(); // immediately before an irreversible removal
+    await fs.rm(abs, { recursive: true, force: false });
+    return { toolCallId: '', content: JSON.stringify({ removed: relative, permanent: true, hint: 'permanently deleted — use git or a copy to recover; there is no recovery store' }) };
+}
+export async function prepareCommand(cwd, args, redactValues = [], unrestricted = false) {
+    const command = validateCommand(args.command, args.timeout_ms, redactValues);
+    const rawCwd = args.cwd;
+    if (typeof rawCwd === 'string' && redactValues.some((value) => value && rawCwd.includes(value))) {
+        throw new Error('command cwd contains a protected credential');
+    }
+    const abs = await toolPath(cwd, args.cwd === undefined ? '.' : args.cwd, unrestricted);
+    if (!(await fs.stat(abs)).isDirectory())
+        throw new Error('command cwd must be an existing directory');
+    return { ...command, cwd: await fs.realpath(abs) };
+}
+const mutationTails = new Map();
+/** Execute a tool. Commands require an approval snapshot; failures become error results. */
+export async function executeTool(call, cwd, options = {}) {
+    const def = toolByName.get(call.name);
+    const result = () => execution.run(options, () => absoluteAccess.run(options.absoluteAccess === true, async () => {
+        if (!def)
+            throw new Error(`unknown tool: ${call.name}`);
+        options.signal?.throwIfAborted(); // also checked when serialized execution actually starts
+        if ((options.absoluteAccess === true || options.commandApproval?.kind === 'absolute') && !options.absoluteEnabled?.()) {
+            throw new Error('unguarded authorization revoked — request approval again');
+        }
+        if (call.argumentsInvalid)
+            throw new Error('invalid tool arguments');
+        switch (call.name) {
+            case 'run_command': {
+                const approved = options.commandApproval;
+                if (!approved)
+                    throw new Error('terminal commands require separate explicit approval or guarded-auto authorization');
+                const current = await prepareCommand(cwd, call.arguments, options.redactValues, options.absoluteAccess === true);
+                if (current.command !== approved.command || current.cwd !== approved.cwd || current.timeoutMs !== approved.timeoutMs) {
+                    throw new Error('terminal command changed after approval — request approval again');
+                }
+                if (approved.kind === 'absolute' && absoluteCommandRisk(current.command, current.cwd) && !approved.hugeRiskConfirmed) {
+                    throw new Error('exceptional huge-risk command requires separate explicit confirmation');
+                }
+                if (approved.kind === 'auto') {
+                    if (!options.autoEnabled?.())
+                        throw new Error('auto authorization revoked — request approval again');
+                    const decision = await commandPolicy(current.command, current.cwd);
+                    if (!decision.auto || !options.autoEnabled?.())
+                        throw new Error('auto authorization no longer eligible — request approval again');
+                }
+                if ((approved.kind === 'absolute' || options.absoluteAccess === true) && !options.absoluteEnabled?.()) {
+                    throw new Error('unguarded authorization revoked — request approval again');
+                }
+                options.signal?.throwIfAborted();
+                options.onStart?.();
+                const command = await executeCommand({ ...current, signal: options.signal, redactValues: options.redactValues });
+                return { toolCallId: '', content: JSON.stringify(command), isError: command.status === 'completed' ? undefined : true };
+            }
+            case 'read_file':
+                return await execReadFile(cwd, call.arguments);
+            case 'write_file':
+                return await execWriteFile(cwd, call.arguments);
+            case 'edit_file':
+                return await execEditFile(cwd, call.arguments);
+            case 'list_dir':
+                return await execListDir(cwd, call.arguments);
+            case 'grep':
+                return await execGrep(cwd, call.arguments);
+            case 'read_files':
+                return await execReadFiles(cwd, call.arguments);
+            case 'file_info':
+                return await execFileInfo(cwd, call.arguments);
+            case 'find_files':
+                return await execFindFiles(cwd, call.arguments);
+            case 'make_dir':
+                return await execMakeDir(cwd, call.arguments);
+            case 'copy_path':
+                return await execTransfer(cwd, call.arguments, false);
+            case 'move_path':
+                return await execTransfer(cwd, call.arguments, true);
+            case 'remove_path':
+                return await execRemovePath(cwd, call.arguments);
+            case 'todo_write': {
+                const parsed = parseTodos(call.arguments);
+                if (parsed.error)
+                    return { toolCallId: '', content: JSON.stringify({ error: parsed.error }), isError: true };
+                return { toolCallId: '', content: JSON.stringify({ status: 'ok', todos: parsed.todos }) };
+            }
+            default:
+                throw new Error(`unknown tool: ${call.name}`);
+        }
+    }));
+    try {
+        let r;
+        if (def?.requiresApproval) {
+            // Keep parallel batches from racing one another's mutations in the same project.
+            const key = await fs.realpath(cwd);
+            const task = (mutationTails.get(key) ?? Promise.resolve()).then(result);
+            const tail = task.then(() => { }, () => { });
+            mutationTails.set(key, tail);
+            try {
+                r = await task;
+            }
+            finally {
+                if (mutationTails.get(key) === tail)
+                    mutationTails.delete(key);
+            }
+        }
+        else {
+            r = await result();
+        }
+        r.toolCallId = call.id;
+        if (options.absoluteAccess === true) {
+            // Drive-wide reads must not put the known router credential into history.
+            for (const value of options.redactValues ?? [])
+                if (value)
+                    r.content = r.content.replaceAll(value, '[REDACTED]');
+        }
+        if (call.name === 'grep' && Buffer.byteLength(r.content) > integerArg(call.arguments, 'max_output_bytes', MAX_GREP_OUTPUT_BYTES, 1024, MAX_GREP_OUTPUT_BYTES)) {
+            throw new Error('grep response exceeds max_output_bytes after redaction; narrow path/include or raise max_output_bytes within the 65536-byte limit');
+        }
+        return r;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { toolCallId: call.id, content: call.name === 'run_command' || options.absoluteAccess === true ? sanitizeCommandOutput(message, options.redactValues) : message, isError: true };
+    }
+}
+export function toolRequiresApproval(name) {
+    return toolByName.get(name)?.requiresApproval ?? false;
+}