@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/tools.js

@@ -0,0 +1,663 @@
+import { open, opendir, realpath, stat, lstat, mkdir, rename, unlink } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { permissionMode, protectedPermissionRoots, assertLocalFilePath, inspectLocalFileResolution as inspectFileResolution, canonicalProtectedRoots as fileProtectedRoots } from './permissions.js';
+import { createCodingTools } from './coding-tools.js';
+import { createQaTools } from './qa/index.js';
+import { createBrowserSessionTool } from './browser-session.js';
+import { createAutomationTool } from './automation-tool.js';
+import { andorraCreateWriteTool } from '../vendor/engine/runtime/coding-agent/core/tools/write.js';
+import { andorraWithFileMutationQueue } from '../vendor/engine/runtime/coding-agent/core/tools/file-mutation-queue.js';
+import { clipText } from './text.js';
+import { pullRequestSettings } from './pull-requests.js';
+import { approveOperation } from './capabilities.js';
+const OUTPUT_LIMIT = 32_768;
+// Repair capacity is independent of model observation and directory scan budgets.
+const FILE_LIMIT = 8 * 1024 * 1024;
+const SEARCH_FILE_LIMIT = 262_144;
+function bounded(text) { return text.length > OUTPUT_LIMIT ? clipText(text, OUTPUT_LIMIT) + '\n[output truncated]' : text; }
+function string(args, key, allowEmpty = false) {
+    const value = args[key];
+    if (typeof value !== 'string' || (!allowEmpty && !value.length) || value.includes('\0'))
+        throw new Error(`${key} must be ${allowEmpty ? 'a' : 'a nonempty'} string without NUL bytes`);
+    return value;
+}
+function validate(args, keys) {
+    if (!args || Array.isArray(args) || typeof args !== 'object')
+        throw new Error('Arguments must be an object');
+    for (const key of Object.keys(args))
+        if (!keys.includes(key))
+            throw new Error(`Unknown argument: ${key}`);
+}
+function samePath(left, right) {
+    return process.platform === 'win32' ? path.resolve(left).toLowerCase() === path.resolve(right).toLowerCase() : left === right;
+}
+function within(root, target) {
+    const relative = path.relative(root, target);
+    return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+}
+/** Engine-written attachment spools: the user attached this content, so reads are trusted. */
+function trustedAttachment(context, target) {
+    return (context.attachmentRoots ?? []).some(root => within(root, target));
+}
+async function safePath(context, name, missing = false, beforeProbe) {
+    context.signal.throwIfAborted();
+    if (permissionMode(context) !== 'full-access')
+        assertLocalFilePath(name);
+    const root = await realpath(context.workspace);
+    const target = path.resolve(root, name);
+    // An attachment spool is trusted under its canonical spelling too: realpath may re-spell a
+    // path that legitimately points into the spool (a symlinked home, a differently cased root).
+    const targetTrusted = trustedAttachment(context, target) || await realpath(target).then(resolved => trustedAttachment(context, resolved)).catch(() => false);
+    const assertProbeAllowed = () => {
+        if (permissionMode(context) === 'full-access')
+            return;
+        assertLocalFilePath(name);
+        if (!within(root, target) && !targetTrusted)
+            throw new Error('Path escapes workspace');
+        if (permissionMode(context) && !targetTrusted && protectedPermissionRoots(root).some(protectedRoot => within(path.resolve(protectedRoot), target))) {
+            throw new Error('Protected repository/runtime metadata requires approval');
+        }
+    };
+    let ancestor = target;
+    while (true) {
+        try {
+            // Workspace resolution and authorization can yield to live revocation.
+            // Only explicit scoped grants bypass the final synchronous lexical guard.
+            if (beforeProbe)
+                await beforeProbe();
+            assertProbeAllowed();
+            const resolved = await realpath(ancestor);
+            if (beforeProbe)
+                await beforeProbe();
+            const trusted = targetTrusted || trustedAttachment(context, resolved);
+            if (permissionMode(context) !== 'full-access' && !within(root, resolved) && !trusted)
+                throw new Error('Symlink escapes workspace');
+            const canonical = path.join(resolved, path.relative(ancestor, target));
+            if (context.pinFilePaths && !samePath(canonical, target))
+                throw new Error('Approved file path changed; retry');
+            if (permissionMode(context) && permissionMode(context) !== 'full-access' && !trusted
+                && (await fileProtectedRoots(root)).some(protectedRoot => within(protectedRoot, canonical))) {
+                throw new Error('Protected repository/runtime metadata requires approval');
+            }
+            return canonical;
+        }
+        catch (error) {
+            if (!missing || error.code !== 'ENOENT' || ancestor === root)
+                throw error;
+            if (beforeProbe)
+                await beforeProbe();
+            assertProbeAllowed();
+            const link = await lstat(ancestor).catch((failure) => { if (failure.code !== 'ENOENT')
+                throw failure; return undefined; });
+            if (link?.isSymbolicLink())
+                throw new Error('Dangling symlink is not allowed');
+            ancestor = path.dirname(ancestor);
+        }
+    }
+}
+class UnsupportedFileContentError extends Error {
+}
+async function read(context, name) {
+    const resolved = await safePath(context, name);
+    if (!(await stat(resolved)).isFile())
+        throw new Error('Path is not a regular file');
+    context.signal.throwIfAborted();
+    // O_NONBLOCK also prevents a regular-file -> FIFO swap between stat and open
+    // from occupying a libuv worker forever. Retain fstat to validate the opened file.
+    const handle = await open(resolved, constants.O_RDONLY | (process.platform === 'win32' ? 0 : constants.O_NONBLOCK));
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new Error('Path is not a regular file');
+        if (info.size > FILE_LIMIT)
+            throw new Error(`File exceeds ${FILE_LIMIT} byte limit`);
+        const chunks = [];
+        let size = 0;
+        while (size <= FILE_LIMIT) {
+            context.signal.throwIfAborted();
+            // Read one extra byte to reject growth after fstat. Small files do not
+            // reserve the whole repair budget; chunks also bound cancellation latency.
+            const chunk = Buffer.alloc(Math.min(64 * 1024, FILE_LIMIT + 1 - size));
+            const result = await handle.read(chunk, 0, chunk.length, size);
+            if (!result.bytesRead)
+                break;
+            size += result.bytesRead;
+            chunks.push(chunk.subarray(0, result.bytesRead));
+        }
+        if (size > FILE_LIMIT)
+            throw new Error('File grew beyond read limit');
+        const buffer = Buffer.concat(chunks, size);
+        if (buffer.includes(0))
+            throw new UnsupportedFileContentError('Binary files are not supported');
+        try {
+            // Reject lossy decoding before edit_file can rewrite unrelated bytes.
+            // Include an existing BOM in the string so UTF-8 re-encoding preserves it.
+            return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, size));
+        }
+        catch {
+            throw new UnsupportedFileContentError('File is not valid UTF-8; text file tools cannot safely read or edit it');
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+function assertMutationPermission(context) {
+    if (!context.pinFilePaths && !context.fileMutationApproval?.explicit && permissionMode(context) === 'read-only')
+        throw new Error('Permission denied: file mutation grant was revoked');
+}
+async function mutationPermission(context, name) {
+    if (context.pinFilePaths || context.fileMutationApproval?.explicit)
+        return;
+    if (permissionMode(context) === 'read-only')
+        await authorize('Write', { path: name, warning: 'Read Only requires approval for this file mutation.' }, context);
+}
+async function atomicWrite(context, name, content, expectedContent) {
+    // Also covers canonical replace_all before any filesystem mutation.
+    if (Buffer.byteLength(content) > FILE_LIMIT)
+        throw new Error(`Content exceeds ${FILE_LIMIT} byte write limit`);
+    const resolved = await safePath(context, name, true);
+    await mutationPermission(context, name);
+    assertMutationPermission(context);
+    await mkdir(path.dirname(resolved), { recursive: true });
+    if (!samePath(await safePath(context, name, true), resolved))
+        throw new Error('File path changed before write; retry');
+    const existing = await stat(resolved).catch((error) => {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return undefined;
+    });
+    if (existing && !existing.isFile())
+        throw new Error('Path is not a regular file');
+    const temporary = path.join(path.dirname(resolved), `.andorracode-${randomUUID()}.tmp`);
+    let created = false;
+    try {
+        context.signal.throwIfAborted();
+        await mutationPermission(context, name);
+        assertMutationPermission(context);
+        const handle = await open(temporary, 'wx', 0o600);
+        created = true;
+        try {
+            await mutationPermission(context, name);
+            assertMutationPermission(context);
+            await handle.writeFile(content, { signal: context.signal });
+            if (existing)
+                await handle.chmod(existing.mode & 0o777);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        context.signal.throwIfAborted();
+        if (expectedContent !== undefined && await read(context, name) !== expectedContent)
+            throw new Error('File changed while writing; retry');
+        if (!samePath(await safePath(context, name, true), resolved) || !samePath(await safePath(context, temporary), temporary)) {
+            throw new Error('File path changed while writing; retry');
+        }
+        context.signal.throwIfAborted();
+        await mutationPermission(context, name);
+        assertMutationPermission(context);
+        await rename(temporary, resolved);
+        created = false;
+    }
+    finally {
+        if (created) {
+            // Cleanup must still run after cancellation, but cannot follow a swapped
+            // parent symlink outside the workspace.
+            const cleanupContext = { ...context, signal: new AbortController().signal };
+            const checked = await safePath(cleanupContext, temporary).catch(() => undefined);
+            if (checked && samePath(checked, temporary))
+                await unlink(temporary).catch(() => { });
+        }
+    }
+}
+export async function authorize(name, args, context) {
+    context.signal.throwIfAborted();
+    if (context.pinFilePaths)
+        return;
+    const mutation = ['write_file', 'edit_file', 'Write', 'Edit', 'write', 'edit'].includes(name) && !args.resolvedPath;
+    const automatic = () => mutation && ['ask-for-approval', 'approve-for-me'].includes(permissionMode(context) ?? '');
+    const liveMode = () => automatic() ? 'workspace-policy' : permissionMode(context) === 'full-access' ? 'yolo' : context.approvalMode ?? 'interactive';
+    while (true) {
+        context.signal.throwIfAborted();
+        await context.onApprovalEvent?.('node.tool.approval.requested', { name, arguments: args, mode: liveMode() });
+        // Both audit hooks may yield while the user changes live permissions.
+        let mode = liveMode();
+        let answer = false;
+        while (mode === 'interactive') {
+            answer = await context.approve(name, args, context.userSignal ?? context.signal);
+            context.signal.throwIfAborted();
+            if (answer !== 'policy-changed')
+                break;
+            mode = liveMode();
+        }
+        const policyGrant = mode === 'yolo' || mode === 'workspace-policy';
+        const approved = policyGrant || answer === true;
+        const actor = mode === 'yolo' ? 'yolo-policy' : mode === 'workspace-policy' ? 'workspace-policy' : mode === 'headless' ? 'headless-policy' : 'local-user';
+        await context.onApprovalEvent?.('node.tool.approval.decided', { name, mode, approved, actor });
+        if (!approved)
+            throw new Error('Permission denied');
+        context.signal.throwIfAborted();
+        // Only explicit user approval survives a mode change. Reacquire automatic
+        // grants through the live policy before returning control to the operation.
+        if (!policyGrant || liveMode() === mode) {
+            if (mutation && context.fileMutationApproval)
+                context.fileMutationApproval.explicit = !policyGrant;
+            return;
+        }
+    }
+}
+async function* files(context, directory, depth = 0, budget = { entries: 0 }) {
+    if (depth > 20)
+        return;
+    context.signal.throwIfAborted();
+    const resolved = await safePath(context, directory);
+    const protectedRoots = permissionMode(context) && permissionMode(context) !== 'full-access'
+        ? await fileProtectedRoots(await realpath(context.workspace)) : [];
+    for await (const entry of await opendir(resolved)) {
+        context.signal.throwIfAborted();
+        if (++budget.entries > 10_000)
+            throw new Error('Directory scan limit reached (10,000 entries); use a narrower path');
+        if (entry.isSymbolicLink() || ['.git', 'node_modules', '.andorracode'].includes(entry.name))
+            continue;
+        const child = path.join(directory, entry.name);
+        if (protectedRoots.some(root => within(root, path.join(resolved, entry.name))))
+            continue;
+        if (entry.isDirectory())
+            yield* files(context, child, depth + 1, budget);
+        else if (entry.isFile())
+            yield child;
+    }
+}
+const property = (description) => ({ type: 'string', description });
+function replacement(content, oldText, newText) {
+    const exact = content.indexOf(oldText);
+    if (exact >= 0) {
+        if (content.indexOf(oldText, exact + 1) !== -1)
+            throw new Error('old_text must occur exactly once');
+        return content.slice(0, exact) + newText + content.slice(exact + oldText.length);
+    }
+    // Only CRLF/LF differences are tolerated. Map normalized UTF-16 offsets back
+    // to the original text so bytes outside the replacement are never rewritten.
+    const offsets = [];
+    let normalized = '';
+    for (let index = 0; index < content.length; index++) {
+        offsets.push(index);
+        if (content[index] === '\r' && content[index + 1] === '\n')
+            index++;
+        normalized += content[index];
+    }
+    offsets.push(content.length);
+    const needle = oldText.replace(/\r\n/g, '\n');
+    const index = normalized.indexOf(needle);
+    if (index < 0 || normalized.indexOf(needle, index + 1) !== -1)
+        throw new Error('old_text must occur exactly once (including CRLF/LF-normalized matching)');
+    const start = offsets[index], end = offsets[index + needle.length];
+    const matched = content.slice(start, end);
+    const endings = matched.match(/\r\n|\n/g) ?? [];
+    const crlfCount = endings.filter(ending => ending === '\r\n').length;
+    // Earlier exact edits may have introduced mixed endings. A unique normalized
+    // target is still unambiguous: use its predominant style, breaking ties by its
+    // first newline, and never normalize the surrounding file.
+    const crlf = crlfCount > endings.length - crlfCount
+        || (crlfCount === endings.length - crlfCount && endings[0] === '\r\n');
+    const updated = newText.replace(/\r\n/g, '\n').replace(/\n/g, crlf ? '\r\n' : '\n');
+    return content.slice(0, start) + updated + content.slice(end);
+}
+function lineBound(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
+        throw new Error(`${key} must be a positive safe integer`);
+    return value;
+}
+async function readFileTool(args, context) {
+    const startLine = lineBound(args, 'startLine'), endLine = lineBound(args, 'endLine');
+    if (endLine !== undefined && endLine < (startLine ?? 1))
+        throw new Error('endLine must be greater than or equal to startLine');
+    const content = await read(context, string(args, 'path'));
+    if (startLine === undefined && endLine === undefined)
+        return bounded(content);
+    // Reuse the bounded, strict UTF-8 reader so ranges cannot bypass file safety checks.
+    const lines = content.split('\n');
+    if (content.endsWith('\n') || content === '')
+        lines.pop();
+    const first = startLine ?? 1;
+    if (first > lines.length)
+        return `[No lines at or after ${first}; file has ${lines.length} lines]`;
+    const last = Math.min(endLine ?? lines.length, lines.length);
+    // Stay below the runtime's observation cap, and put continuation before the body.
+    const rangeLimit = 20_000;
+    let selected = '', emittedLast = first - 1;
+    for (let line = first; line <= last; line++) {
+        const next = (line === first ? '' : '\n') + lines[line - 1];
+        if (selected.length + next.length > rangeLimit) {
+            if (line === first)
+                return `[Line ${first} of ${lines.length} exceeds ${rangeLimit} characters; line content truncated]\n${clipText(next, rangeLimit)}`;
+            break;
+        }
+        selected += next;
+        emittedLast = line;
+    }
+    const continuation = emittedLast < last ? `; continue with startLine=${emittedLast + 1}, endLine=${last}` : '';
+    return `[Lines ${first}-${emittedLast} of ${lines.length}${continuation}]\n${selected}`;
+}
+function tool(name, description, properties, required, execute, providerVisible = true) {
+    return { name, description, parameters: { type: 'object', properties, required, additionalProperties: false }, ...(providerVisible ? {} : { providerVisible: false }), execute: async (args, context) => {
+            validate(args, Object.keys(properties));
+            context.signal.throwIfAborted();
+            return execute(args, context);
+        } };
+}
+function legacyTool(name, description, properties, required, execute) {
+    return { ...tool(name, description, properties, required, execute), providerVisible: false };
+}
+/** One operation can gain access to its approved canonical path, never an entire run. */
+function filePermissionTool(tool) {
+    const fileTools = ['read_file', 'list_files', 'search_files', 'write_file', 'edit_file', 'Read', 'Write', 'Edit', 'Glob', 'Grep', 'read', 'write', 'edit', 'find', 'ls', 'grep'];
+    if (!fileTools.includes(tool.name))
+        return tool;
+    return { ...tool, executionMode: 'sequential', execute: async (args, context) => {
+            // The canonical path this call is authorized to touch, once the block below settles. A runtime
+            // that must read the file around the call (the transcript's diff figures) waits on the callback
+            // at the end: reading any earlier would do so before the access itself was granted.
+            let authorized;
+            if (['write_file', 'edit_file', 'Write', 'Edit', 'write', 'edit'].includes(tool.name)) {
+                context.toolState ??= { fileReads: new Map() };
+                // The attachment spool carve-out is a READ trust: a mutation lands outside the workspace
+                // and keeps the scoped approval these modes require, so the roots leave this call alone.
+                context = { ...context, fileMutationApproval: { explicit: false }, attachmentRoots: undefined };
+            }
+            const selected = permissionMode(context);
+            if (selected && selected !== 'full-access') {
+                const key = typeof args.file_path === 'string' ? 'file_path' : 'path';
+                const name = typeof args[key] === 'string' ? args[key] : '.';
+                assertLocalFilePath(name);
+                const root = await realpath(context.workspace);
+                const target = path.resolve(root, name);
+                // An attachment spool holds content the user attached to this very turn, written by the
+                // engine: reading it is as trusted as the workspace, and the outside-workspace approval
+                // this classification would demand is one a headless run cannot grant.
+                const attachmentTrusted = trustedAttachment(context, target)
+                    || await realpath(target).then(resolved => trustedAttachment(context, resolved)).catch(() => false);
+                if (!attachmentTrusted) {
+                    const outside = !within(root, target);
+                    // Classify lexical metadata descendants before even lstat/readlink: their
+                    // existence and filesystem errors require the same grant as their content.
+                    let lexicalProtected = protectedPermissionRoots(root).some(protectedRoot => within(path.resolve(protectedRoot), target));
+                    if (!outside && !lexicalProtected) {
+                        lexicalProtected = (await fileProtectedRoots(root)).some(protectedRoot => within(protectedRoot, target));
+                    }
+                    const inspected = outside || lexicalProtected ? { approvalRequired: false, target } : await inspectFileResolution(root, target);
+                    const resolutionApproved = outside || lexicalProtected || inspected.approvalRequired;
+                    let explicitlyApproved = false;
+                    const authorizePath = async (approvalArgs) => {
+                        await authorize(tool.name, approvalArgs, { ...context, approve: async (...approval) => {
+                                const result = await context.approve(...approval);
+                                if (result === true)
+                                    explicitlyApproved = true;
+                                return result;
+                            } });
+                    };
+                    // Even realpath can access a mapped network drive or reveal host-file
+                    // existence. Obtain the scoped grant before following any selected link.
+                    if (resolutionApproved) {
+                        const reason = outside ? 'Outside the workspace.' : lexicalProtected ? 'Protected repository/runtime metadata.' : 'A symbolic link or junction requires approval.';
+                        await authorizePath({ ...args, warning: `${reason} Approval permits resolving this path and accessing its canonical target for this call only.`, resolvedPath: target });
+                    }
+                    const resolutionContext = {
+                        ...context, runControl: undefined,
+                        get permissions() { return explicitlyApproved ? 'full-access' : permissionMode(context); },
+                    };
+                    const beforeResolution = async () => {
+                        while (resolutionApproved && !explicitlyApproved && permissionMode(context) !== 'full-access') {
+                            await authorizePath({ ...args, warning: lexicalProtected ? 'Protected repository/runtime metadata.' : 'Outside the workspace or a selected symbolic link.', resolvedPath: target });
+                        }
+                    };
+                    const resolved = await safePath(resolutionContext, inspected.target, ['write_file', 'Write', 'write'].includes(tool.name), beforeResolution);
+                    const protectedPath = !resolutionApproved && (await fileProtectedRoots(root)).some(protectedRoot => within(protectedRoot, resolved));
+                    if (resolutionApproved || !within(root, resolved) || protectedPath) {
+                        const approvalArgs = { ...args, warning: protectedPath || lexicalProtected ? 'Protected repository/runtime metadata.' : 'Outside the workspace or a selected symbolic link.', resolvedPath: resolved };
+                        if (!resolutionApproved)
+                            await authorizePath(approvalArgs);
+                        // A Full Access policy change is automatic authorization, not an
+                        // explicit per-call grant. Resolution may yield to its revocation.
+                        while (!explicitlyApproved && permissionMode(context) !== 'full-access')
+                            await authorizePath(approvalArgs);
+                        context.toolState ??= { fileReads: new Map() };
+                        if (explicitlyApproved)
+                            context = { ...context, permissions: 'full-access', pinFilePaths: true };
+                        args = { ...args, [key]: resolved };
+                    }
+                    authorized = resolved;
+                }
+            }
+            if (['write_file', 'edit_file', 'Write', 'Edit', 'write', 'edit'].includes(tool.name)) {
+                if (authorized === undefined) {
+                    // Full Access and the engine's own attachment spools need no resolution grant: the path
+                    // the call names, resolved against the workspace, is the one the tool will touch.
+                    const key = typeof args.file_path === 'string' ? 'file_path' : 'path';
+                    const named = typeof args[key] === 'string' ? args[key] : undefined;
+                    if (named !== undefined)
+                        authorized = path.resolve(context.workspace, named);
+                }
+                if (authorized !== undefined)
+                    await context.onFilePathAuthorized?.(authorized);
+            }
+            return tool.execute(args, context);
+        } };
+}
+function qaPermissionTool(tool) {
+    if (tool.name === 'qa.detect')
+        return tool;
+    return { ...tool, execute: async (args, context) => {
+            const selected = permissionMode(context);
+            const readOnlyTerminal = tool.name === 'qa.terminal' && ['read', 'status', 'wait', 'resize'].includes(String(args.action));
+            if (selected && !readOnlyTerminal) {
+                let explicitlyApproved = false;
+                do {
+                    await authorize(tool.name, { ...args, warning: 'UNSANDBOXED QA: this tool call can access the entire host filesystem and network.' }, {
+                        ...context, approve: async (...approval) => {
+                            const allowed = await context.approve(...approval);
+                            if (allowed === true)
+                                explicitlyApproved = true;
+                            return allowed;
+                        },
+                    });
+                    // Decision-event delivery can also yield to a live-mode downgrade.
+                    // An automatic Full Access decision never becomes a scoped user grant.
+                } while (!explicitlyApproved && permissionMode(context) !== 'full-access');
+                if (explicitlyApproved)
+                    context = { ...context, qaHostApproved: true };
+            }
+            return tool.execute(args, context);
+        } };
+}
+export function createTools() {
+    return [
+        createAutomationTool(),
+        legacyTool('read_file', 'Read a UTF-8 workspace file (8 MiB maximum). Optional 1-based inclusive startLine/endLine select a range; omitted bounds mean first/last line. Range reads return line metadata, up to 20000 content characters and a continuation hint; individual longer lines truncate. Use ranges to inspect tails of truncated files. Path-only reads return original content capped at 32768 characters.', {
+            path: property('Workspace-relative file path'),
+            startLine: { type: 'integer', minimum: 1, description: 'First line, inclusive (default 1)' },
+            endLine: { type: 'integer', minimum: 1, description: 'Last line, inclusive (default end of file); must be at least startLine' },
+        }, ['path'], readFileTool),
+        legacyTool('list_files', 'Recursively list up to 1,000 files, depth 20; skip symlinks, .git, node_modules and .andorracode.', { path: property('Workspace-relative directory, default .') }, [], async (args, context) => {
+            const result = [];
+            for await (const name of files(context, args.path === undefined ? '.' : string(args, 'path'))) {
+                result.push(name);
+                if (result.length >= 1000) {
+                    result.push('[file limit reached]');
+                    break;
+                }
+            }
+            return bounded(result.join('\n'));
+        }),
+        legacyTool('search_files', 'Bounded source search. Default smart mode is case-insensitive and relaxes whitespace/extra words plus simple word suffixes (for example "Create new graph" matches "Create a new Graph" and "Edit graph" matches "Edit Graphs"). Use mode=regex for an explicit JavaScript regular expression or mode=literal for substring matching. Searches at most 1,000 files and 16 MiB; returns 50 matches by default (max 200), with long matching lines clipped. Prefer repo_explore/CodeGraph first when it is available; use this as textual fallback or exact confirmation.', {
+            query: property('Search text or regular expression'),
+            path: property('Workspace-relative directory, default .'),
+            mode: { type: 'string', enum: ['smart', 'regex', 'literal'], description: 'Search mode; default smart' },
+            caseSensitive: { type: 'boolean', description: 'Case-sensitive matching; default false' },
+            maxResults: { type: 'integer', minimum: 1, maximum: 200, description: 'Maximum matching lines; default 50' },
+        }, ['query'], async (args, context) => {
+            const query = string(args, 'query');
+            const mode = args.mode === undefined ? 'smart' : args.mode;
+            if (!['smart', 'regex', 'literal'].includes(String(mode)))
+                throw new Error('mode must be smart, regex or literal');
+            const caseSensitive = args.caseSensitive ?? false;
+            if (typeof caseSensitive !== 'boolean')
+                throw new Error('caseSensitive must be a boolean');
+            const maxResults = args.maxResults ?? 50;
+            if (typeof maxResults !== 'number' || !Number.isSafeInteger(maxResults) || maxResults < 1 || maxResults > 200)
+                throw new Error('maxResults must be an integer from 1 to 200');
+            const escapeRegex = (value) => value.replace(/[.*+?^$()|[\\]{}]/g, '\\$&');
+            let matcher;
+            if (mode === 'literal') {
+                const needle = caseSensitive ? query : query.toLowerCase();
+                matcher = line => (caseSensitive ? line : line.toLowerCase()).includes(needle);
+            }
+            else {
+                let source = query;
+                if (mode === 'smart') {
+                    const tokens = query.trim().split(/\s+/).filter(Boolean);
+                    source = tokens.map(token => {
+                        const escaped = escapeRegex(token);
+                        return /^[A-Za-z0-9_-]+$/.test(token) ? '\\b' + escaped + '[A-Za-z0-9_-]*\\b' : escaped;
+                    }).join('[^\\n]{0,80}?');
+                }
+                let regex;
+                try {
+                    regex = new RegExp(source, caseSensitive ? '' : 'i');
+                }
+                catch (error) {
+                    throw new Error('Invalid search regular expression: ' + (error instanceof Error ? error.message : 'invalid pattern'));
+                }
+                matcher = line => regex.test(line);
+            }
+            const result = [];
+            let count = 0, bytes = 0, outputChars = 0;
+            for await (const name of files(context, args.path === undefined ? '.' : string(args, 'path'))) {
+                if (++count > 1000) {
+                    result.push('[file limit reached; narrow path]');
+                    break;
+                }
+                const info = await stat(await safePath(context, name));
+                if (info.size > SEARCH_FILE_LIMIT)
+                    continue;
+                if ((bytes += info.size) > 16_777_216) {
+                    result.push('[search byte limit reached at 16 MiB; narrow path]');
+                    break;
+                }
+                let content;
+                try {
+                    content = await read(context, name);
+                }
+                catch (error) {
+                    context.signal.throwIfAborted();
+                    if (error instanceof UnsupportedFileContentError)
+                        continue;
+                    throw error;
+                }
+                for (const [index, line] of content.split('\n').entries()) {
+                    context.signal.throwIfAborted();
+                    if (!matcher(line))
+                        continue;
+                    const rendered = line.length > 600 ? clipText(line, 600) + ' [line clipped]' : line;
+                    const match = name + ':' + (index + 1) + ':' + rendered;
+                    result.push(match);
+                    outputChars += match.length + 1;
+                    if (result.length >= maxResults || outputChars > 12_000) {
+                        return bounded(result.join('\n') + '\n[match/output limit reached; narrow path/query or raise maxResults]');
+                    }
+                }
+            }
+            return bounded(result.join('\n')) || 'No matches';
+        }),
+        legacyTool('write_file', 'Create or overwrite a UTF-8 workspace file; obeys workspace permissions; protected or outside paths require approval.', { path: property('Workspace-relative file path'), content: property('Complete file content') }, ['path', 'content'], async (args, context) => {
+            const name = string(args, 'path'), content = string(args, 'content', true);
+            if (Buffer.byteLength(content) > FILE_LIMIT)
+                throw new Error('Content exceeds write limit');
+            await safePath(context, name, true);
+            await authorize('write_file', args, context);
+            const native = andorraCreateWriteTool(context.workspace, { operations: {
+                    mkdir: async (directory) => { await safePath(context, directory, true); },
+                    writeFile: (target, value) => atomicWrite(context, target, value),
+                } });
+            await native.execute(randomUUID(), { path: name, content }, context.signal);
+            return `Wrote ${Buffer.byteLength(content)} bytes to ${name}`;
+        }),
+        legacyTool('edit_file', 'Replace one unique text occurrence; if exact matching fails, tolerate CRLF/LF differences and use the matched span\'s predominant newline style (ties use its first newline). Ambiguous fallback matches fail; surrounding bytes remain unchanged. Requires approval unless yolo is enabled.', { path: property('Workspace-relative file path'), old_text: property('Text occurring once; only CRLF/LF differences may be normalized'), new_text: property('Replacement text') }, ['path', 'old_text', 'new_text'], async (args, context) => {
+            const name = string(args, 'path'), oldText = string(args, 'old_text'), newText = string(args, 'new_text', true);
+            return andorraWithFileMutationQueue(await safePath(context, name), async () => {
+                const content = await read(context, name);
+                const updated = replacement(content, oldText, newText);
+                if (Buffer.byteLength(updated) > FILE_LIMIT)
+                    throw new Error('Content exceeds write limit');
+                await authorize('edit_file', args, context);
+                if (await read(context, name) !== content)
+                    throw new Error('File changed while awaiting approval; retry');
+                await atomicWrite(context, name, updated, content);
+                return `Updated ${name}`;
+            });
+        }),
+        tool('set_timer', 'Arm a self-wake timer. After the delay your prompt is delivered back to you as a user message. A session that is idle, or a run this process drives between its turns, takes it at the next turn boundary; a run that is still working when the deadline passes takes it when that run ends, as a new task in this session under the same graph, model, and thinking effort it was armed under. Use it to check on slow background work instead of polling it. Timers are held in the running session only: they fire at most once, they are lost when the process exits, and they are unavailable where no session can deliver a follow-up prompt.', {
+            prompt: property('The message delivered to you when the timer fires'),
+            seconds: { type: 'integer', minimum: 1, maximum: 86_400, description: 'Delay before delivery, in seconds (1 to 86400)' },
+        }, ['prompt', 'seconds'], async (args, context) => {
+            if (!context.timers)
+                throw new Error('set_timer is unavailable in this session; no session surface can deliver a follow-up prompt here.');
+            if (typeof args.seconds !== 'number' || !Number.isSafeInteger(args.seconds))
+                throw new Error('seconds must be an integer');
+            const timer = context.timers.arm(args.seconds, string(args, 'prompt'), context.sessionScope, context.wakeCarry);
+            // Recorded for the run that made it: a wake is this turn's promise, and a turn that fails to be saved has
+            // only its own to lose.
+            context.wakesArmed?.push(timer.id);
+            return `Timer ${timer.id.slice(0, 8)} armed: your prompt will be delivered in ${args.seconds} second${args.seconds === 1 ? '' : 's'}, at ${new Date(timer.fireAt).toISOString()}. It fires once.`;
+        }),
+        { ...tool('pull_request', 'Show or change the pull request this session tracks in the desktop Plan card. A PR you open with `gh pr create` is attached automatically; use attach for one opened another way. update changes its settings when the user asks: mergeWhenReady enables GitHub auto-merge (gh pr merge --auto), draft converts to a draft or marks it ready, autoFix wakes you with a prompt when new review comments arrive, autoArchive archives this session once the PR is merged or closed. dismiss removes it from the card. Only change a setting the user asked you to change.', {
+                action: { type: 'string', enum: ['status', 'attach', 'update', 'dismiss'], description: 'status shows the tracked PR; attach starts tracking url; update changes settings; dismiss stops tracking' },
+                url: property('The GitHub pull request URL (attach only)'),
+                autoFix: { type: 'boolean', description: 'Wake this session when new review comments arrive' },
+                mergeWhenReady: { type: 'boolean', description: 'GitHub auto-merge once checks and reviews pass' },
+                autoArchive: { type: 'boolean', description: 'Archive this session when the PR is merged or closed' },
+                draft: { type: 'boolean', description: 'true converts to a draft, false marks it ready for review' },
+            }, ['action'], async (args, context) => {
+                const control = context.pullRequests;
+                if (!control)
+                    throw new Error('pull_request is unavailable here; no session tracks a pull request for this run.');
+                const settings = pullRequestSettings(args);
+                // A setting is a change on GitHub (auto-merge, draft) or to what the engine will do unattended (Auto-fix
+                // runs, archiving), so it goes through the run's approval like any other host operation; a full-access
+                // run approves it by policy. Reading the PR and dismissing it change neither.
+                const approve = () => approveOperation(context, 'pull_request', { ...args, warning: 'Changes the pull request on GitHub, or what Andorra does on its own when the PR changes.' });
+                const describe = (pr) => `${pr.url} (${pr.state})${pr.title ? ` "${pr.title}"` : ''}: autoFix ${pr.autoFix ? 'on' : 'off'}, mergeWhenReady ${pr.mergeWhenReady ? 'on' : 'off'}, autoArchive ${pr.autoArchive ? 'on' : 'off'}`;
+                switch (args.action) {
+                    case 'status': {
+                        const pr = await control.status();
+                        return pr ? describe(pr) : 'No pull request is tracked for this session.';
+                    }
+                    case 'attach': {
+                        const url = string(args, 'url');
+                        if (Object.keys(settings).length)
+                            await approve();
+                        return `Tracking ${describe(await control.attach(url, settings))}`;
+                    }
+                    case 'update': {
+                        if (!Object.keys(settings).length)
+                            throw new Error('update needs at least one of autoFix, mergeWhenReady, autoArchive, draft');
+                        await approve();
+                        return `Updated ${describe(await control.update(settings))}`;
+                    }
+                    case 'dismiss':
+                        await control.dismiss();
+                        return 'The pull request is no longer tracked for this session.';
+                    default: throw new Error('action must be status, attach, update, or dismiss');
+                }
+            }), family: 'git', executionMode: 'sequential' },
+        ...createCodingTools({ safePath, read, atomicWrite, authorize, files, fileLimit: FILE_LIMIT }),
+        ...createQaTools().map(qaPermissionTool),
+        createBrowserSessionTool(authorize),
+    ].map(filePermissionTool);
+}