@librechat/agents 3.1.77 → 3.1.78-dev.0

package/dist/esm/tools/local/LocalCodingTools.mjs

@@ -0,0 +1,1075 @@
+import { dirname, basename } from 'path';
+import { tool } from '@langchain/core/tools';
+import { createTwoFilesPatch } from 'diff';
+import { createLocalBashExecutionTool, createLocalCodeExecutionTool } from './LocalExecutionTools.mjs';
+import { createLocalProgrammaticToolCallingTool, createLocalBashProgrammaticToolCallingTool } from './LocalProgrammaticToolCalling.mjs';
+import { getWorkspaceFS, resolveWorkspacePathSafe, spawnLocalProcess, getSpawn, truncateLocalOutput } from './LocalExecutionEngine.mjs';
+import { createLocalFileCheckpointer } from './FileCheckpointer.mjs';
+import { locateEdit, applyEdit } from './editStrategies.mjs';
+import { decodeFile, encodeFile } from './textEncoding.mjs';
+import { classifyAttachment, imageAttachmentContent } from './attachments.mjs';
+import { runPostEditSyntaxCheck } from './syntaxCheck.mjs';
+import { createCompileCheckToolDefinition, createCompileCheckTool } from './CompileCheckTool.mjs';
+import { Constants } from '../../common/enum.mjs';
+
+const MAX_READ_CHARS = 256000;
+const DEFAULT_MAX_RESULTS = 200;
+const DEFAULT_MAX_READ_BYTES = 10 * 1024 * 1024;
+const BINARY_DETECTION_BYTES = 8000;
+/**
+ * Tool name aliases retained for back-compat with consumers that imported
+ * the per-file `Local*ToolName` constants. The canonical names live on
+ * `Constants.*` (see `src/common/enum.ts`); these aliases just point at
+ * them so a typo upstream gets caught at the type level.
+ */
+const LocalWriteFileToolName = Constants.WRITE_FILE;
+const LocalEditFileToolName = Constants.EDIT_FILE;
+const LocalGrepSearchToolName = Constants.GREP_SEARCH;
+const LocalGlobSearchToolName = Constants.GLOB_SEARCH;
+const LocalListDirectoryToolName = Constants.LIST_DIRECTORY;
+const LocalReadFileToolSchema = {
+    type: 'object',
+    properties: {
+        file_path: {
+            type: 'string',
+            description: 'Path to a local file, relative to the configured cwd unless absolute paths are allowed.',
+        },
+        offset: {
+            type: 'integer',
+            description: 'Optional 1-indexed line offset for large files.',
+        },
+        limit: {
+            type: 'integer',
+            description: 'Optional maximum number of lines to return.',
+        },
+    },
+    required: ['file_path'],
+};
+const LocalWriteFileToolSchema = {
+    type: 'object',
+    properties: {
+        file_path: {
+            type: 'string',
+            description: 'Path to write, relative to the configured cwd unless absolute paths are allowed.',
+        },
+        content: {
+            type: 'string',
+            description: 'Complete file contents to write.',
+        },
+    },
+    required: ['file_path', 'content'],
+};
+const LocalEditFileToolSchema = {
+    type: 'object',
+    properties: {
+        file_path: {
+            type: 'string',
+            description: 'Path to edit, relative to the configured cwd unless absolute paths are allowed.',
+        },
+        old_text: {
+            type: 'string',
+            description: 'Exact text to replace. Must appear exactly once.',
+        },
+        new_text: {
+            type: 'string',
+            description: 'Replacement text.',
+        },
+        edits: {
+            type: 'array',
+            description: 'Optional batch of exact replacements. Each old_text must appear exactly once in the original file.',
+            items: {
+                type: 'object',
+                properties: {
+                    old_text: { type: 'string' },
+                    new_text: { type: 'string' },
+                },
+                required: ['old_text', 'new_text'],
+            },
+        },
+    },
+    required: ['file_path'],
+};
+const LocalGrepSearchToolSchema = {
+    type: 'object',
+    properties: {
+        pattern: {
+            type: 'string',
+            description: 'Regex pattern to search for.',
+        },
+        path: {
+            type: 'string',
+            description: 'Directory or file to search. Defaults to cwd.',
+        },
+        glob: {
+            type: 'string',
+            description: 'Optional file glob passed to rg -g.',
+        },
+        max_results: {
+            type: 'integer',
+            description: 'Maximum matching lines to return.',
+        },
+    },
+    required: ['pattern'],
+};
+const LocalGlobSearchToolSchema = {
+    type: 'object',
+    properties: {
+        pattern: {
+            type: 'string',
+            description: 'File glob pattern, for example "src/**/*.ts".',
+        },
+        path: {
+            type: 'string',
+            description: 'Directory to search. Defaults to cwd.',
+        },
+        max_results: {
+            type: 'integer',
+            description: 'Maximum file paths to return.',
+        },
+    },
+    required: ['pattern'],
+};
+const LocalListDirectoryToolSchema = {
+    type: 'object',
+    properties: {
+        path: {
+            type: 'string',
+            description: 'Directory to list. Defaults to cwd.',
+        },
+    },
+};
+function lineWindow(content, offset, limit) {
+    const start = Math.max((offset ?? 1) - 1, 0);
+    // Avoid splitting the whole file when the caller asked for a small
+    // window. For a 10 MB file with `offset: 1, limit: 10`, the prior
+    // `content.split('\n')` allocated millions of strings to throw all
+    // but 10 away. We walk newline indices directly: O(start + limit)
+    // instead of O(file). When `limit` is omitted, fall back to the
+    // simple split — it's the same amount of work either way.
+    if (limit == null || limit <= 0) {
+        const lines = content.split('\n');
+        const selected = lines.slice(start);
+        const numbered = selected
+            .map((line, index) => `${String(start + index + 1).padStart(6, ' ')}\t${line}`)
+            .join('\n');
+        return {
+            text: truncateLocalOutput(numbered, MAX_READ_CHARS),
+            truncated: numbered.length > MAX_READ_CHARS,
+        };
+    }
+    // Walk to the start line by counting newlines.
+    let cursor = 0;
+    for (let i = 0; i < start; i++) {
+        const next = content.indexOf('\n', cursor);
+        if (next === -1) {
+            // File has fewer lines than `offset` — return empty window.
+            return { text: '', truncated: false };
+        }
+        cursor = next + 1;
+    }
+    // Collect up to `limit` lines from `cursor`.
+    const out = [];
+    let pos = cursor;
+    let exhausted = true;
+    for (let k = 0; k < limit; k++) {
+        const next = content.indexOf('\n', pos);
+        if (next === -1) {
+            out.push(content.slice(pos));
+            break;
+        }
+        out.push(content.slice(pos, next));
+        pos = next + 1;
+        if (k === limit - 1 && pos < content.length) {
+            exhausted = false;
+        }
+    }
+    const numbered = out
+        .map((text, index) => `${String(start + index + 1).padStart(6, ' ')}\t${text}`)
+        .join('\n');
+    return {
+        text: truncateLocalOutput(numbered, MAX_READ_CHARS),
+        truncated: !exhausted || numbered.length > MAX_READ_CHARS,
+    };
+}
+const MAX_DIFF_CHARS = 4000;
+async function maybeRunSyntaxCheck(path, config) {
+    const mode = config.postEditSyntaxCheck ?? 'off';
+    if (mode === 'off')
+        return undefined;
+    const outcome = await runPostEditSyntaxCheck(path, config);
+    if (outcome == null)
+        return undefined;
+    return { mode, outcome };
+}
+function appendSyntaxCheckSummary(base, run) {
+    if (run == null)
+        return base;
+    if (run.outcome.ok)
+        return base;
+    const banner = run.mode === 'strict'
+        ? `\n\n[syntax-check FAILED via ${run.outcome.checker}]\n`
+        : `\n\n[syntax-check warning via ${run.outcome.checker}]\n`;
+    return `${base}${banner}${run.outcome.output}`;
+}
+/**
+ * Revert a write_file/edit_file mutation in `postEditSyntaxCheck:
+ * 'strict'` mode after the post-write syntax check failed. Strict
+ * mode advertises a safety gate, so leaving the corrupted file on
+ * disk + throwing is a half-broken contract — the model "reacts" to
+ * the error but the next call sees broken on-disk state. Codex P2
+ * [49]. Best-effort: a swallowed error here means the workspace is
+ * still in the bad post-write state, but we still throw the
+ * original syntax-check error so the caller knows.
+ *
+ * - If the file existed pre-write: restore the previous bytes with
+ *   the original encoding.
+ * - If the file is brand-new: unlink it.
+ */
+async function revertStrictWrite(fs, path, existed, before, encoding) {
+    try {
+        if (existed) {
+            // encodeFile uses encoding.{hasBom,newline} to restore the
+            // on-disk shape; the `text` field is overridden by the
+            // explicit `before` arg we pass in.
+            await fs.writeFile(path, encodeFile(before, { ...encoding, text: before }), 'utf8');
+        }
+        else {
+            await fs.unlink(path);
+        }
+    }
+    catch {
+        /* best-effort: caller still sees the original syntax error */
+    }
+}
+function summariseDiff(filePath, before, after) {
+    if (before === after) {
+        return '(no textual changes)';
+    }
+    const name = basename(filePath);
+    const patch = createTwoFilesPatch(name, name, before, after, '', '', {
+        context: 3,
+    });
+    if (patch.length <= MAX_DIFF_CHARS) {
+        return patch;
+    }
+    return (patch.slice(0, MAX_DIFF_CHARS) +
+        `\n[... diff truncated, ${patch.length - MAX_DIFF_CHARS} more chars ...]`);
+}
+function normalizeEdits(input) {
+    const edits = Array.isArray(input.edits)
+        ? input.edits.map((edit) => ({
+            oldText: edit.old_text ?? '',
+            newText: edit.new_text ?? '',
+        }))
+        : [];
+    if (input.old_text != null || input.new_text != null) {
+        edits.push({
+            oldText: input.old_text ?? '',
+            newText: input.new_text ?? '',
+        });
+    }
+    return edits;
+}
+function toolDefinition(name, description, parameters) {
+    return {
+        name,
+        description,
+        parameters,
+        allowed_callers: ['direct', 'code_execution'],
+        responseFormat: Constants.CONTENT_AND_ARTIFACT,
+        toolType: 'builtin',
+    };
+}
+async function looksBinary(path, fs) {
+    let handle;
+    try {
+        handle = await fs.open(path, 'r');
+        const sample = Buffer.alloc(BINARY_DETECTION_BYTES);
+        const { bytesRead } = await handle.read(sample, 0, BINARY_DETECTION_BYTES, 0);
+        for (let i = 0; i < bytesRead; i++) {
+            if (sample[i] === 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+const DEFAULT_MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024;
+function createLocalReadFileTool(config = {}) {
+    const fs = getWorkspaceFS(config);
+    return tool(async (rawInput) => {
+        const input = rawInput;
+        const path = await resolveWorkspacePathSafe(input.file_path, config, 'read');
+        const fileStat = await fs.stat(path);
+        if (!fileStat.isFile()) {
+            throw new Error(`Path is not a file: ${input.file_path}`);
+        }
+        const maxBytes = Math.max(config.maxReadBytes ?? DEFAULT_MAX_READ_BYTES, 1);
+        if (fileStat.size > maxBytes) {
+            const stub = `File is ${fileStat.size} bytes, exceeds the ${maxBytes}-byte read cap. Read a slice via bash (e.g. head/sed) or raise local.maxReadBytes.`;
+            return [stub, { path, bytes: fileStat.size, truncated: true }];
+        }
+        if (await looksBinary(path, fs)) {
+            const attachmentMode = config.attachReadAttachments ?? 'off';
+            if (attachmentMode !== 'off') {
+                const attachment = await classifyAttachment({
+                    path,
+                    bytes: fileStat.size,
+                    mode: attachmentMode,
+                    maxBytes: config.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES,
+                    // Route through the configured WorkspaceFS so a custom
+                    // engine sees the same path semantics as `read_file`
+                    // itself (manual review finding F).
+                    fs,
+                });
+                if (attachment.kind === 'image') {
+                    return [
+                        imageAttachmentContent(path, attachment),
+                        {
+                            path,
+                            bytes: fileStat.size,
+                            mime: attachment.mime,
+                            attachment: 'image',
+                        },
+                    ];
+                }
+                if (attachment.kind === 'pdf') {
+                    return [
+                        [
+                            {
+                                type: 'text',
+                                text: `Read ${path} (application/pdf, ${fileStat.size} bytes). PDF attached as base64 data URL; vision-capable models that accept PDF will render it.`,
+                            },
+                            {
+                                type: 'image_url',
+                                image_url: { url: attachment.dataUrl },
+                            },
+                        ],
+                        {
+                            path,
+                            bytes: fileStat.size,
+                            mime: attachment.mime,
+                            attachment: 'pdf',
+                        },
+                    ];
+                }
+                if (attachment.kind === 'oversize') {
+                    return [
+                        `Refusing to embed ${attachment.mime} attachment (${attachment.bytes} bytes exceeds ${attachment.maxBytes}-byte cap).`,
+                        {
+                            path,
+                            bytes: fileStat.size,
+                            mime: attachment.mime,
+                            attachment: 'oversize',
+                        },
+                    ];
+                }
+                if (attachment.kind === 'binary') {
+                    return [
+                        `Refusing to read binary file (${fileStat.size} bytes, ${attachment.mime}): ${path}`,
+                        {
+                            path,
+                            bytes: fileStat.size,
+                            mime: attachment.mime,
+                            binary: true,
+                        },
+                    ];
+                }
+                // text-or-unknown falls through to the text-read path below.
+            }
+            else {
+                return [
+                    `Refusing to read binary file (${fileStat.size} bytes): ${path}`,
+                    { path, bytes: fileStat.size, binary: true },
+                ];
+            }
+        }
+        const content = await fs.readFile(path, 'utf8');
+        const result = lineWindow(content, input.offset, input.limit);
+        return [
+            result.truncated ? `${result.text}\n[truncated]` : result.text,
+            { path, bytes: fileStat.size },
+        ];
+    }, {
+        name: Constants.READ_FILE,
+        description: 'Read a local text file from the configured working directory with line numbers. ' +
+            'When `attachReadAttachments` is enabled (e.g. images-only), reading an image returns an ' +
+            '`image_url` content block so vision-capable models can see the file directly.',
+        schema: LocalReadFileToolSchema,
+        responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    });
+}
+function createLocalWriteFileTool(config = {}, checkpointer) {
+    const fs = getWorkspaceFS(config);
+    return tool(async (rawInput) => {
+        const input = rawInput;
+        if (config.readOnly === true) {
+            throw new Error('write_file is blocked in read-only local mode.');
+        }
+        const path = await resolveWorkspacePathSafe(input.file_path, config, 'write');
+        if (checkpointer != null) {
+            await checkpointer.captureBeforeWrite(path);
+        }
+        let before = '';
+        let encoding = { text: '', hasBom: false, newline: '\n' };
+        let existed = false;
+        try {
+            const raw = await fs.readFile(path, 'utf8');
+            const decoded = decodeFile(raw);
+            before = decoded.text;
+            encoding = decoded;
+            existed = true;
+        }
+        catch {
+            existed = false;
+        }
+        await fs.mkdir(dirname(path), { recursive: true });
+        const finalText = encodeFile(input.content, encoding);
+        await fs.writeFile(path, finalText, 'utf8');
+        const syntax = await maybeRunSyntaxCheck(path, config);
+        const diff = existed
+            ? summariseDiff(path, before, input.content)
+            : `(new file, ${input.content.length} chars)`;
+        const baseSummary = existed
+            ? `Overwrote ${path} (${input.content.length} chars). Diff:\n${diff}`
+            : `Created ${path} (${input.content.length} chars).`;
+        const summary = appendSyntaxCheckSummary(baseSummary, syntax);
+        if (syntax?.outcome.ok === false && syntax.mode === 'strict') {
+            // Roll back the write so strict mode is an actual gate, not
+            // "fail the call AND leave the corrupted file on disk".
+            // Codex P2 [49].
+            await revertStrictWrite(fs, path, existed, before, encoding);
+            throw new Error(`write_file syntax check failed (${syntax.outcome.checker}); reverted to pre-write state.\n${syntax.outcome.output}`);
+        }
+        return [
+            summary,
+            {
+                path,
+                bytes: finalText.length,
+                new_file: !existed,
+                newline: encoding.newline === '\r\n' ? 'CRLF' : 'LF',
+                had_bom: encoding.hasBom,
+                ...(syntax != null && syntax.outcome.ok === false
+                    ? { syntax_error: syntax.outcome.checker }
+                    : {}),
+            },
+        ];
+    }, {
+        name: LocalWriteFileToolName,
+        description: 'Create or overwrite a local text file in the configured working directory. ' +
+            'Preserves the existing BOM and line endings when overwriting; defaults to LF without BOM for new files. ' +
+            'Returns a unified diff of the changes when overwriting.',
+        schema: LocalWriteFileToolSchema,
+        responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    });
+}
+function createLocalEditFileTool(config = {}, checkpointer) {
+    const fs = getWorkspaceFS(config);
+    return tool(async (rawInput) => {
+        const input = rawInput;
+        if (config.readOnly === true) {
+            throw new Error('edit_file is blocked in read-only local mode.');
+        }
+        const edits = normalizeEdits(input);
+        if (edits.length === 0) {
+            throw new Error('edit_file requires old_text/new_text or edits[].');
+        }
+        const path = await resolveWorkspacePathSafe(input.file_path, config, 'write');
+        const raw = await fs.readFile(path, 'utf8');
+        const encoding = decodeFile(raw);
+        const original = encoding.text;
+        let next = original;
+        const strategiesUsed = [];
+        for (let i = 0; i < edits.length; i++) {
+            const edit = edits[i];
+            const match = locateEdit(next, edit.oldText);
+            if (match == null) {
+                throw new Error(`Edit ${i + 1}/${edits.length}: could not locate old_text in ${input.file_path}. ` +
+                    'Tried exact, line-trimmed, whitespace-normalized, and indentation-flexible matching. ' +
+                    'Re-read the file and copy the literal lines.');
+            }
+            strategiesUsed.push(match.strategy);
+            next = applyEdit(next, match, edit.newText);
+        }
+        if (checkpointer != null) {
+            await checkpointer.captureBeforeWrite(path);
+        }
+        const finalText = encodeFile(next, encoding);
+        await fs.writeFile(path, finalText, 'utf8');
+        const syntax = await maybeRunSyntaxCheck(path, config);
+        const diff = summariseDiff(path, original, next);
+        const fuzzy = strategiesUsed.some((s) => s !== 'exact');
+        const baseSummary = `Applied ${edits.length} edit(s) to ${path}` +
+            (fuzzy ? ` (strategies: ${strategiesUsed.join(', ')})` : '') +
+            `. Diff:\n${diff}`;
+        const summary = appendSyntaxCheckSummary(baseSummary, syntax);
+        if (syntax?.outcome.ok === false && syntax.mode === 'strict') {
+            // Restore the pre-edit bytes so strict mode is an actual
+            // gate (Codex P2 [49]). edit_file always operates on an
+            // existing file, so `existed = true` here.
+            await revertStrictWrite(fs, path, true, original, encoding);
+            throw new Error(`edit_file syntax check failed (${syntax.outcome.checker}); reverted to pre-edit state.\n${syntax.outcome.output}`);
+        }
+        return [
+            summary,
+            {
+                path,
+                edits: edits.length,
+                strategies: strategiesUsed,
+                newline: encoding.newline === '\r\n' ? 'CRLF' : 'LF',
+                had_bom: encoding.hasBom,
+                ...(syntax != null && syntax.outcome.ok === false
+                    ? { syntax_error: syntax.outcome.checker }
+                    : {}),
+            },
+        ];
+    }, {
+        name: LocalEditFileToolName,
+        description: 'Apply exact text replacements to a local file. The matcher tries exact, line-trimmed, whitespace-normalized, and indentation-flexible strategies in order so common LLM whitespace mistakes are recoverable. Each old_text must still match exactly one location. Returns a unified diff of the changes.',
+        schema: LocalEditFileToolSchema,
+        responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    });
+}
+/**
+ * Ripgrep availability cache, keyed on the *effective execution
+ * backend* — whatever function `getSpawn(config)` returns. Without
+ * the backend key, a Run that probes `rg` over Node's
+ * `child_process.spawn` would poison subsequent Runs whose
+ * `local.exec.spawn` routes to a remote sandbox or container that
+ * doesn't have rg installed: the cached `true` would skip the probe,
+ * the rg invocation would throw, and the Node fallback wouldn't be
+ * reached. Per-backend caching avoids that without paying for a
+ * spawn-per-search.
+ */
+// Per-backend × per-env cache. Codex P1 #34 — keying by spawn
+// backend alone misses the case where two Runs share a backend but
+// vary `local.env` (especially PATH). Stale cache then claims `rg`
+// is available, the rg path runs, and the spawn fails with ENOENT
+// instead of falling back to the Node walker. The inner Map is
+// keyed by a stable JSON hash of the effective env so each unique
+// env gets its own probe.
+let ripgrepAvailabilityByBackend = new WeakMap();
+function envCacheKey(env) {
+    // PATH is the only env entry that affects command lookup, but
+    // hashing the whole env keeps the key correct for hosts that
+    // vary anything else relevant. Stable JSON via sorted keys so
+    // {A:1,B:2} and {B:2,A:1} produce the same hash.
+    if (env == null)
+        return '';
+    const sorted = {};
+    for (const k of Object.keys(env).sort()) {
+        sorted[k] = env[k];
+    }
+    return JSON.stringify(sorted);
+}
+async function isRipgrepAvailable(config) {
+    const backend = getSpawn(config);
+    let envMap = ripgrepAvailabilityByBackend.get(backend);
+    if (envMap == null) {
+        envMap = new Map();
+        ripgrepAvailabilityByBackend.set(backend, envMap);
+    }
+    const envKey = envCacheKey(config.env);
+    let probePromise = envMap.get(envKey);
+    if (probePromise == null) {
+        probePromise = spawnLocalProcess('rg', ['--version'], { ...config, timeoutMs: 5000, sandbox: { enabled: false } }, { internal: true })
+            .then((probe) => probe != null && probe.exitCode === 0)
+            .catch(() => false);
+        envMap.set(envKey, probePromise);
+    }
+    return probePromise;
+}
+/**
+ * Test-only reset hook. Clears the ripgrep-availability cache so
+ * tests can swap in mocked spawn backends and reprobe deterministically.
+ *
+ * @internal Not part of the public SDK surface; the leading underscore
+ *   and `@internal` tag together signal that consumers should not call
+ *   this. Tests import it via the module path directly.
+ */
+function _resetRipgrepCacheForTests() {
+    ripgrepAvailabilityByBackend = new WeakMap();
+}
+// Skipped by the Node-fallback walker (used when ripgrep is
+// unavailable). Covers common build outputs, virtualenvs, and
+// caches so a `grep_search`/`glob_search` on a large monorepo or a
+// Python project with `.venv/` doesn't read every file under those
+// trees. ripgrep itself respects .gitignore so it doesn't need this
+// list. Audit follow-up from the comprehensive review (finding #3).
+const SKIP_DIRS = new Set([
+    '.git',
+    '.svn',
+    '.hg',
+    'node_modules',
+    '.next',
+    '.nuxt',
+    '.cache',
+    '.parcel-cache',
+    '.turbo',
+    'dist',
+    'build',
+    'out',
+    'target',
+    'vendor',
+    'coverage',
+    '.nyc_output',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'env',
+    '.tox',
+    '.mypy_cache',
+    '.pytest_cache',
+    '.ruff_cache',
+]);
+function globToRegExp(pattern) {
+    let result = '^';
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                result += '.*';
+                i += 1;
+                if (pattern[i + 1] === '/') {
+                    i += 1;
+                }
+            }
+            else {
+                result += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            result += '[^/]';
+        }
+        else if ('.+^$|(){}[]\\'.includes(c)) {
+            result += '\\' + c;
+        }
+        else {
+            result += c;
+        }
+    }
+    result += '$';
+    return new RegExp(result);
+}
+async function* walkFiles(root, fs) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.git') || SKIP_DIRS.has(entry.name)) {
+                continue;
+            }
+            const full = `${dir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                yield full;
+            }
+        }
+    }
+}
+/**
+ * Catastrophic-backtracking guardrails for the fallback grep path.
+ *
+ * Without ripgrep we run the model-supplied pattern through Node's
+ * `RegExp` engine, which uses a backtracking implementation. Patterns
+ * with nested unbounded quantifiers (`(a+)+`, `(.*)*`, etc.) can
+ * monopolise the event loop for arbitrary wall-clock time on
+ * pathological input, and `setTimeout` cannot interrupt a synchronous
+ * `RegExp.exec`. Manual review (finding D) flagged this as a real DoS.
+ *
+ * Mitigations applied here, in order of severity:
+ *   1. Cap pattern length so an obviously oversize regex is rejected
+ *      before compile.
+ *   2. Reject patterns that contain a nested unbounded quantifier of
+ *      the form `(...+|*)([+*]|{n,})` — the standard pathological
+ *      shape. Still a heuristic (not a full safety proof), but blocks
+ *      every common DoS construction we've seen in coding-agent logs.
+ *   3. Wall-clock budget for the overall search: each file's regex
+ *      pass is checked against a deadline; once exceeded the search
+ *      bails with a partial result. Doesn't interrupt a stuck
+ *      `exec()` call, but stops a slow pattern from making the whole
+ *      Run hang once the first hung file finishes.
+ *
+ * Hosts that need bulletproof regex safety should install `rg` —
+ * ripgrep uses RE2 internally and has no backtracking.
+ */
+const MAX_FALLBACK_PATTERN_LENGTH = 1024;
+const FALLBACK_GREP_BUDGET_MS = 5000;
+// Per-file byte cap. Codex P2 #41 — without it, the whole-file
+// `readFile` + `split('\n')` for a multi-GB log is an unbounded
+// allocation that the wall-clock budget (checked between files)
+// can't interrupt. Hosts that need to grep large files should
+// install ripgrep.
+const FALLBACK_GREP_MAX_FILE_BYTES = 5 * 1024 * 1024;
+/**
+ * Heuristic: walks `pattern` to find any `(<contents>)<quant>` where
+ * `<contents>` itself has an unbounded quantifier. Catches the
+ * classic `(a+)+` form AND the double-nested `((a+)+)` form (which a
+ * single-pass regex misses because `[^)]*` stops at the first inner
+ * close-paren). Misses sufficiently obfuscated cases — bulletproof
+ * ReDoS detection requires a real parser. The 5 s wall-clock budget
+ * is the hard backstop for anything this slip past.
+ */
+function hasNestedUnboundedQuantifier(pattern) {
+    for (let i = 1; i < pattern.length - 1; i++) {
+        if (pattern[i] !== ')')
+            continue;
+        if (pattern[i - 1] === '\\')
+            continue;
+        const next = pattern[i + 1];
+        if (next !== '+' && next !== '*' && next !== '{')
+            continue;
+        // Walk back to find the matching opening paren (respecting depth
+        // and `\(` escapes).
+        let depth = 1;
+        let j = i - 1;
+        while (j >= 0) {
+            const c = pattern[j];
+            const escaped = j > 0 && pattern[j - 1] === '\\';
+            if (!escaped) {
+                if (c === ')')
+                    depth++;
+                else if (c === '(') {
+                    depth--;
+                    if (depth === 0)
+                        break;
+                }
+            }
+            j--;
+        }
+        if (j < 0)
+            continue;
+        const inner = pattern.slice(j + 1, i);
+        if (/(?<!\\)[+*]/.test(inner))
+            return true;
+    }
+    return false;
+}
+class FallbackGrepError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+    }
+}
+function compileFallbackRegex(pattern) {
+    if (pattern.length > MAX_FALLBACK_PATTERN_LENGTH) {
+        throw new FallbackGrepError('pattern-too-long', `Pattern exceeds ${MAX_FALLBACK_PATTERN_LENGTH}-char fallback cap (install ripgrep for unbounded patterns).`);
+    }
+    if (hasNestedUnboundedQuantifier(pattern)) {
+        throw new FallbackGrepError('unsafe-pattern', 'Pattern contains a nested unbounded quantifier (e.g. `(a+)+` or `((a+)+)`) which can cause catastrophic backtracking in the Node fallback. Install ripgrep for RE2-safe matching.');
+    }
+    try {
+        return new RegExp(pattern);
+    }
+    catch (e) {
+        throw new FallbackGrepError('invalid-pattern', `Invalid regex: ${e.message}`);
+    }
+}
+async function fallbackGrep(root, pattern, globFilter, maxResults, fs) {
+    const rx = compileFallbackRegex(pattern);
+    const deadline = Date.now() + FALLBACK_GREP_BUDGET_MS;
+    const globRx = globFilter != null && globFilter !== '' ? globToRegExp(globFilter) : undefined;
+    const matches = [];
+    // Track skipped (oversize) files separately so they don't consume
+    // the maxResults budget. Codex P2 [43]: round 14's fix pushed skip
+    // sentinels into `matches`, so a directory of one oversize non-
+    // matching file falsely reported `matches: 1`, and enough
+    // oversize files could fill the budget before any real match was
+    // scanned. Now diagnostics are appended after real matches and
+    // independent of the budget.
+    const skippedDiagnostics = [];
+    for await (const file of walkFiles(root, fs)) {
+        if (Date.now() > deadline) {
+            // Wall-clock budget exceeded — return partial results rather
+            // than letting a slow pattern hang the Run.
+            return { matches, skipped: skippedDiagnostics };
+        }
+        if (globRx != null) {
+            const rel = file.startsWith(root + '/') ? file.slice(root.length + 1) : file;
+            if (!globRx.test(rel)) {
+                continue;
+            }
+        }
+        // Skip files larger than the per-file cap and remember them as
+        // diagnostics (NOT as matches). Codex P2 [41]: pre-fix
+        // `fs.readFile` then `.split('\n')` allocated the whole file +
+        // an array of every line, which a single multi-GB log could
+        // turn into an OOM even after the regex DoS guards.
+        let stat;
+        try {
+            stat = await fs.stat(file);
+        }
+        catch {
+            continue;
+        }
+        if (stat.size > FALLBACK_GREP_MAX_FILE_BYTES) {
+            skippedDiagnostics.push(`${file}:0:[skipped: file > ${FALLBACK_GREP_MAX_FILE_BYTES} bytes; install ripgrep for unbounded grep]`);
+            continue;
+        }
+        let content;
+        try {
+            content = await fs.readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (content.includes('\0')) {
+            continue;
+        }
+        // Re-check the deadline AFTER the read — a slow disk on one
+        // file can blow the budget without us noticing.
+        if (Date.now() > deadline) {
+            return { matches, skipped: skippedDiagnostics };
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (rx.test(lines[i])) {
+                matches.push(`${file}:${i + 1}:${lines[i]}`);
+                if (matches.length >= maxResults) {
+                    return { matches, skipped: skippedDiagnostics };
+                }
+            }
+        }
+    }
+    return { matches, skipped: skippedDiagnostics };
+}
+async function fallbackGlob(root, pattern, maxResults, fs) {
+    const rx = globToRegExp(pattern);
+    const out = [];
+    for await (const file of walkFiles(root, fs)) {
+        const rel = file.startsWith(root + '/') ? file.slice(root.length + 1) : file;
+        if (rx.test(rel)) {
+            out.push(file);
+            if (out.length >= maxResults) {
+                break;
+            }
+        }
+    }
+    return out;
+}
+function createLocalGrepSearchTool(config = {}) {
+    const fs = getWorkspaceFS(config);
+    return tool(async (rawInput) => {
+        const input = rawInput;
+        const target = await resolveWorkspacePathSafe(input.path ?? '.', config, 'read');
+        const maxResults = Math.max(input.max_results ?? DEFAULT_MAX_RESULTS, 1);
+        if (await isRipgrepAvailable(config)) {
+            // Pass the pattern through `-e` so dash-prefixed patterns
+            // like `-foo` are treated as the search regex, not as a
+            // (probably-unknown) flag. `rg --help` explicitly requires
+            // `-e/--regexp` (or `--`) for that case. Same trick avoids
+            // any future flag-conflict if a user query happens to look
+            // like an rg long option.
+            const args = [
+                '--line-number',
+                '--column',
+                '--hidden',
+                '--glob',
+                '!.git/**',
+                ...(input.glob != null && input.glob !== '' ? ['--glob', input.glob] : []),
+                '-e',
+                input.pattern,
+                target,
+            ];
+            const result = await spawnLocalProcess('rg', args, {
+                ...config,
+                timeoutMs: config.timeoutMs ?? 30000,
+            });
+            // ripgrep exit codes:
+            //   0  → at least one match
+            //   1  → no matches (clean — "No matches found.")
+            //   2  → real error (bad regex, unreadable target, etc.)
+            // Without this branch (Codex P2 #23 — same fix shape glob_search
+            // got from P2 #13), exit-2 errors silently mapped to
+            // `matches: 0`, so the agent treated tooling failures as a
+            // genuine absence of matches.
+            if (result.timedOut || (result.exitCode != null && result.exitCode > 1)) {
+                const detail = result.stderr.trim() || `rg exited ${result.exitCode}`;
+                return [
+                    `grep_search failed: ${detail}`,
+                    {
+                        matches: 0,
+                        engine: 'ripgrep',
+                        error: detail,
+                        exitCode: result.exitCode,
+                    },
+                ];
+            }
+            const lines = result.stdout.split('\n').filter(Boolean).slice(0, maxResults);
+            const output = lines.length > 0
+                ? lines.join('\n')
+                : result.stderr.trim() || 'No matches found.';
+            return [output, { matches: lines.length, engine: 'ripgrep' }];
+        }
+        try {
+            const { matches, skipped } = await fallbackGrep(target, input.pattern, input.glob, maxResults, fs);
+            // Display: real matches first, skip diagnostics appended.
+            // Artifact count: ONLY real matches (Codex P2 [43] —
+            // skip sentinels used to inflate the count and the budget).
+            const display = matches.length > 0
+                ? [...matches, ...skipped].join('\n')
+                : skipped.length > 0
+                    ? skipped.join('\n')
+                    : 'No matches found.';
+            return [
+                display,
+                {
+                    matches: matches.length,
+                    skipped: skipped.length,
+                    engine: 'node-fallback',
+                },
+            ];
+        }
+        catch (e) {
+            if (e instanceof FallbackGrepError) {
+                return [
+                    `grep_search refused the pattern: ${e.message}`,
+                    {
+                        matches: 0,
+                        engine: 'node-fallback',
+                        error: e.message,
+                        kind: e.kind,
+                    },
+                ];
+            }
+            throw e;
+        }
+    }, {
+        name: LocalGrepSearchToolName,
+        description: 'Search local files for a regex pattern (ripgrep when available, Node fallback otherwise).',
+        schema: LocalGrepSearchToolSchema,
+        responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    });
+}
+function createLocalGlobSearchTool(config = {}) {
+    const fs = getWorkspaceFS(config);
+    return tool(async (rawInput) => {
+        const input = rawInput;
+        const target = await resolveWorkspacePathSafe(input.path ?? '.', config, 'read');
+        const maxResults = Math.max(input.max_results ?? DEFAULT_MAX_RESULTS, 1);
+        if (await isRipgrepAvailable(config)) {
+            const result = await spawnLocalProcess('rg', ['--files', '--hidden', '--glob', '!.git/**', '--glob', input.pattern, target], { ...config, timeoutMs: config.timeoutMs ?? 30000 });
+            // rg --files exit codes:
+            //   0  → at least one file matched
+            //   1  → no files matched (clean — "No files found.")
+            //   2  → real error (bad glob, unreadable target, etc.)
+            // Without this branch, exit-2 errors used to silently map to
+            // "No files found." — the agent then treats a tooling failure
+            // as a real absence of matches.
+            if (result.timedOut || (result.exitCode != null && result.exitCode > 1)) {
+                const detail = result.stderr.trim() || `rg exited ${result.exitCode}`;
+                return [
+                    `glob_search failed: ${detail}`,
+                    {
+                        files: [],
+                        engine: 'ripgrep',
+                        error: detail,
+                        exitCode: result.exitCode,
+                    },
+                ];
+            }
+            const lines = result.stdout
+                .split('\n')
+                .filter(Boolean)
+                .slice(0, maxResults);
+            return [
+                lines.length > 0 ? lines.join('\n') : 'No files found.',
+                { files: lines, engine: 'ripgrep' },
+            ];
+        }
+        const files = await fallbackGlob(target, input.pattern, maxResults, fs);
+        return [
+            files.length > 0 ? files.join('\n') : 'No files found.',
+            { files, engine: 'node-fallback' },
+        ];
+    }, {
+        name: LocalGlobSearchToolName,
+        description: 'Find local files matching a glob pattern (ripgrep when available, Node fallback otherwise).',
+        schema: LocalGlobSearchToolSchema,
+        responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    });
+}
+function createLocalListDirectoryTool(config = {}) {
+    const fs = getWorkspaceFS(config);
+    return tool(async (rawInput) => {
+        const input = rawInput;
+        const path = await resolveWorkspacePathSafe(input.path ?? '.', config, 'read');
+        const entries = await fs.readdir(path, { withFileTypes: true });
+        const output = entries
+            .map((entry) => `${entry.isDirectory() ? 'dir ' : 'file'}\t${entry.name}`)
+            .join('\n');
+        return [output || 'Directory is empty.', { path, count: entries.length }];
+    }, {
+        name: LocalListDirectoryToolName,
+        description: 'List files and directories in a local directory.',
+        schema: LocalListDirectoryToolSchema,
+        responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    });
+}
+function createLocalCodingTools(config = {}, options = {}) {
+    const checkpointer = options.checkpointer ??
+        (config.fileCheckpointing === true
+            ? createLocalFileCheckpointer({ fs: config.exec?.fs })
+            : undefined);
+    return [
+        createLocalReadFileTool(config),
+        createLocalWriteFileTool(config, checkpointer),
+        createLocalEditFileTool(config, checkpointer),
+        createLocalGrepSearchTool(config),
+        createLocalGlobSearchTool(config),
+        createLocalListDirectoryTool(config),
+        createCompileCheckTool(config),
+        createLocalBashExecutionTool({ config }),
+        createLocalCodeExecutionTool(config),
+        createLocalProgrammaticToolCallingTool(config),
+        createLocalBashProgrammaticToolCallingTool(config),
+    ];
+}
+/**
+ * Variant of `createLocalCodingTools` that returns the bundle alongside
+ * the file checkpointer so callers can later call
+ * `bundle.checkpointer?.rewind()`.
+ */
+function createLocalCodingToolBundle(config = {}, options = {}) {
+    const checkpointer = options.checkpointer ??
+        (config.fileCheckpointing === true
+            ? createLocalFileCheckpointer({ fs: config.exec?.fs })
+            : undefined);
+    return {
+        tools: createLocalCodingTools(config, { checkpointer }),
+        checkpointer,
+    };
+}
+function createLocalCodingToolDefinitions() {
+    return [
+        toolDefinition(Constants.READ_FILE, 'Read a local text file from the configured working directory with line numbers.', LocalReadFileToolSchema),
+        toolDefinition(LocalWriteFileToolName, 'Create or overwrite a local text file in the configured working directory.', LocalWriteFileToolSchema),
+        toolDefinition(LocalEditFileToolName, 'Apply exact text replacements to a local file.', LocalEditFileToolSchema),
+        toolDefinition(LocalGrepSearchToolName, 'Search local files with ripgrep and return matching lines.', LocalGrepSearchToolSchema),
+        toolDefinition(LocalGlobSearchToolName, 'Find local files matching a glob pattern.', LocalGlobSearchToolSchema),
+        toolDefinition(LocalListDirectoryToolName, 'List files and directories in a local directory.', LocalListDirectoryToolSchema),
+        createCompileCheckToolDefinition(),
+    ];
+}
+function createLocalCodingToolRegistry() {
+    return new Map(createLocalCodingToolDefinitions().map((definition) => [
+        definition.name,
+        definition,
+    ]));
+}
+
+export { LocalEditFileToolName, LocalEditFileToolSchema, LocalGlobSearchToolName, LocalGlobSearchToolSchema, LocalGrepSearchToolName, LocalGrepSearchToolSchema, LocalListDirectoryToolName, LocalListDirectoryToolSchema, LocalReadFileToolSchema, LocalWriteFileToolName, LocalWriteFileToolSchema, _resetRipgrepCacheForTests, createLocalCodingToolBundle, createLocalCodingToolDefinitions, createLocalCodingToolRegistry, createLocalCodingTools, createLocalEditFileTool, createLocalGlobSearchTool, createLocalGrepSearchTool, createLocalListDirectoryTool, createLocalReadFileTool, createLocalWriteFileTool };
+//# sourceMappingURL=LocalCodingTools.mjs.map