@librechat/agents 3.1.77 → 3.1.78-dev.0

package/dist/cjs/tools/local/LocalExecutionEngine.cjs

@@ -0,0 +1,1042 @@
+'use strict';
+
+var os = require('os');
+var path = require('path');
+var crypto = require('crypto');
+var promises = require('fs/promises');
+var fs = require('fs');
+var child_process = require('child_process');
+var bashAst = require('./bashAst.cjs');
+var workspaceFS = require('./workspaceFS.cjs');
+
+const DEFAULT_TIMEOUT_MS = 60000;
+const DEFAULT_MAX_OUTPUT_CHARS = 200000;
+/**
+ * Hard cap on total stdout+stderr bytes a child process can stream
+ * before we kill its process tree. Independent from `maxOutputChars`
+ * (which only affects what the *model* sees) — this is the OOM
+ * backstop. Configurable via `local.maxSpawnedBytes`.
+ */
+const DEFAULT_MAX_SPAWNED_BYTES = 50 * 1024 * 1024;
+const DEFAULT_LOCAL_SESSION_ID = 'local';
+const DEFAULT_SHELL = process.platform === 'win32' ? 'bash.exe' : 'bash';
+// `(?:--\s+)?` before each destructive-target alternation: GNU/BSD
+// utilities accept `--` as an end-of-options marker, so `rm -rf -- /`
+// is identical in effect to `rm -rf /` but pre-fix it slipped past
+// the guard because the regex required the path to follow option
+// flags directly. Codex P1 #20.
+// `DESTRUCTIVE_TARGET` is the canonical "protected location" pattern:
+// matches `/`, `~`, `$HOME`, `${HOME}`, `.`, each optionally followed
+// by a trailing-slash and/or wildcard glob suffix. The suffix matrix:
+//   ''     — `$HOME`              (round 14)
+//   '/'    — `$HOME/`             (round 14, Codex P1 [37])
+//   '*'    — `$HOME*`             (round 15, Codex P1 [42])
+//   '/*'   — `$HOME/*`            (round 15, Codex P1 [42])
+//   '.*'   — `$HOME.*`            (round 17, Codex P1 [47])
+//   '/.*'  — `$HOME/.*`           (round 17, Codex P1 [47]) — the
+//            dot-glob form deletes all dotfiles under the protected
+//            root, just as destructive as `/*` but the prior matrix
+//            missed it.
+// Suffix expression: `(?:\/?\.?\*|\/)?` — one of:
+//   `\/?\.?\*` → `*`, `.*`, `/*`, `/.*`
+//   `\/`       → `/`
+//   (empty)    → bare base
+const DESTRUCTIVE_TARGET = '(?:\\/|~|\\$\\{?HOME\\}?|\\.)(?:\\/?\\.?\\*|\\/)?';
+const dangerousCommandPatterns = [
+    new RegExp(`\\brm\\s+(?:-[^\\s]*[rf][^\\s]*\\s+|-[^\\s]*[r][^\\s]*\\s+-[^\\s]*[f][^\\s]*\\s+)(?:--\\s+)?${DESTRUCTIVE_TARGET}\\s*(?:$|[;&|])`),
+    /\b(?:mkfs|mkswap|fdisk|parted|diskutil)\b/,
+    /\bdd\s+[^;&|]*\bof=\/dev\//,
+    new RegExp(`\\bchmod\\s+-R\\s+(?:777|a\\+w)\\s+(?:--\\s+)?${DESTRUCTIVE_TARGET}(?:$|\\s|[;&|])`),
+    new RegExp(`\\bchown\\s+-R\\s+[^;&|]+\\s+(?:--\\s+)?${DESTRUCTIVE_TARGET}(?:$|\\s|[;&|])`),
+    /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/,
+];
+/**
+ * Companion patterns that look for destructive targets *inside*
+ * matching quote pairs. These are checked against the ORIGINAL
+ * command (not the post-quote-strip `normalized` form), because
+ * `stripQuotedContent` blanks the contents of quoted spans —
+ * which would otherwise let `rm -rf "/"` and friends slip past
+ * `dangerousCommandPatterns`.
+ *
+ * Kept as a separate list so we don't pay false-positive cost on
+ * benign uses like `echo "rm -rf /"` (the print case): each pattern
+ * here REQUIRES a quote *around the destructive path argument*, not
+ * just a quote *somewhere* in the command. `echo "rm -rf /"` has
+ * `/` outside of any quote-pair-around-the-path (the quotes wrap
+ * the whole `rm -rf /` text), so it doesn't match here either.
+ */
+// Quoted variant uses the same DESTRUCTIVE_TARGET (which accepts an
+// optional trailing slash) so `rm -rf "$HOME/"` and `rm -rf "~/"`
+// don't slip past. Codex P1 #37.
+const quotedDestructivePatterns = [
+    new RegExp(`\\brm\\s+(?:-[^\\s]*[rf][^\\s]*\\s+){1,3}(?:--\\s+)?["']${DESTRUCTIVE_TARGET}["']`),
+    new RegExp(`\\bchmod\\s+-R\\s+(?:777|a\\+w)\\s+(?:--\\s+)?["']${DESTRUCTIVE_TARGET}["']`),
+    new RegExp(`\\bchown\\s+-R\\s+[^;&|]+\\s+(?:--\\s+)?["']${DESTRUCTIVE_TARGET}["']`),
+];
+/**
+ * Catches destructive operations smuggled inside a nested shell or
+ * `eval` call, e.g. `bash -lc "rm -rf $HOME"` — the outer command
+ * looks benign (`bash -lc "..."`) and the destructive `rm` lives
+ * inside the quoted payload that `stripQuotedContent` blanks out.
+ * Comprehensive review (manual finding C) flagged this as a real
+ * bypass of the otherwise-correct quote-strip-then-match approach.
+ *
+ * Run against the ORIGINAL command (quotes intact) so the inside of
+ * the nested-shell payload is visible. Conservative: matches only
+ * the same operation set as `dangerousCommandPatterns` (rm -rf,
+ * chmod -R 777, chown -R) when they appear inside a `<shell> -[l]?c
+ * "..."` or `eval "..."` payload.
+ */
+const NESTED_SHELL_PREFIX = '(?:(?:ba|z|da|k)?sh|eval)\\s+(?:-l?c\\s+)?';
+const nestedShellDestructivePatterns = [
+    new RegExp(NESTED_SHELL_PREFIX +
+        '["\'][^"\']*\\brm\\s+-[^\\s"\']*[rf][^\\s"\']*\\s+(?:--\\s+)?(?:\\/|~|\\$\\{?HOME\\}?|\\.)'),
+    new RegExp(NESTED_SHELL_PREFIX +
+        '["\'][^"\']*\\bchmod\\s+-R\\s+(?:777|a\\+w)\\s+(?:--\\s+)?(?:\\/|~|\\$\\{?HOME\\}?|\\.)'),
+    new RegExp(NESTED_SHELL_PREFIX +
+        '["\'][^"\']*\\bchown\\s+-R\\s+[^;&|]+\\s+(?:--\\s+)?(?:\\/|~|\\$\\{?HOME\\}?|\\.)'),
+];
+const mutatingCommandPattern = /\b(?:rm|mv|cp|touch|mkdir|rmdir|ln|truncate|tee|sed\s+-i|perl\s+-pi|python(?:3)?\s+-c|node\s+-e|npm\s+(?:install|ci|update|publish)|pnpm\s+(?:install|update|publish)|yarn\s+(?:install|add|publish)|git\s+(?:add|commit|checkout|switch|reset|clean|rebase|merge|push|pull|stash|tag|branch)|chmod|chown)\b|(?:^|[^<])>\s*[^&]|\bcat\s+[^|;&]*>\s*/;
+/**
+ * POSIX convention: `128 + signum` when a process is killed by a
+ * signal. Maps the common signals; unknown ones default to 1 so the
+ * caller still sees a non-zero (failed) exit. Only used when Node's
+ * `close` event reports `exitCode === null` (true signal kill).
+ */
+const SIGNAL_TO_EXIT_CODE = {
+    SIGHUP: 129,
+    SIGINT: 130,
+    SIGQUIT: 131,
+    SIGILL: 132,
+    SIGTRAP: 133,
+    SIGABRT: 134,
+    SIGBUS: 135,
+    SIGFPE: 136,
+    SIGKILL: 137,
+    SIGUSR1: 138,
+    SIGSEGV: 139,
+    SIGUSR2: 140,
+    SIGPIPE: 141,
+    SIGALRM: 142,
+    SIGTERM: 143,
+};
+function exitCodeForSignal(signal) {
+    if (signal == null)
+        return 1;
+    return SIGNAL_TO_EXIT_CODE[signal] ?? 1;
+}
+let sandboxConfigKey;
+let sandboxInitialized = false;
+let sandboxRuntimePromise;
+function isToolExecutionConfig(config) {
+    return 'engine' in config || 'local' in config;
+}
+function resolveLocalExecutionConfig(config) {
+    if (config != null && isToolExecutionConfig(config)) {
+        return config.local ?? {};
+    }
+    return config ?? {};
+}
+function getLocalCwd(config) {
+    return path.resolve(config?.workspace?.root ?? config?.cwd ?? process.cwd());
+}
+/**
+ * Resolves the effective workspace boundary: a list of absolute roots
+ * that file operations are allowed to touch. The first entry is always
+ * the canonical root (`getLocalCwd`); subsequent entries come from
+ * `workspace.additionalRoots` when provided.
+ *
+ * Returns plain absolute paths — callers symlink-resolve when they
+ * need realpath equality (see `resolveWorkspacePathSafe`).
+ */
+function getWorkspaceRoots(config) {
+    const root = getLocalCwd(config);
+    const extras = config?.workspace?.additionalRoots ?? [];
+    if (extras.length === 0)
+        return [root];
+    const seen = new Set([root]);
+    const out = [root];
+    for (const extra of extras) {
+        // Relative `additionalRoots` entries are anchored to the
+        // workspace root (so monorepo configs like
+        // `additionalRoots: ['../shared']` resolve to a sibling of
+        // `root` rather than to `process.cwd()/../shared`, which would
+        // mean something completely different on a server with a
+        // different cwd).
+        const abs = path.isAbsolute(extra) ? path.resolve(extra) : path.resolve(root, extra);
+        if (!seen.has(abs)) {
+            seen.add(abs);
+            out.push(abs);
+        }
+    }
+    return out;
+}
+/**
+ * Pluggable spawn resolver. Honours `local.exec.spawn` first, falls
+ * back to the legacy top-level `local.spawn`, then to Node's
+ * `child_process.spawn`. Centralised so engine swapping is one knob.
+ */
+function getSpawn(config) {
+    return (config?.exec?.spawn ?? config?.spawn ?? child_process.spawn);
+}
+/**
+ * Pluggable filesystem resolver. Honours `local.exec.fs`, falls back
+ * to the Node-host implementation. A future remote engine supplies
+ * its own implementation here and inherits every file-touching tool.
+ */
+function getWorkspaceFS(config) {
+    return config?.exec?.fs ?? workspaceFS.nodeWorkspaceFS;
+}
+/**
+ * Resolves the workspace boundary for *write* operations. Honours
+ * `workspace.allowWriteOutside` (and the deprecated
+ * `allowOutsideWorkspace`) by returning `null`, which the path-safety
+ * helpers interpret as "skip the write clamp".
+ */
+function getWriteRoots(config) {
+    // Granular flag wins over the legacy one when explicitly set
+    // (true OR false) — otherwise a host tightening access during
+    // migration (`allowOutsideWorkspace: true, workspace.
+    // allowWriteOutside: false`) would still get the loose behavior
+    // because the legacy flag short-circuited the OR. Codex P1 #36.
+    const granular = config?.workspace?.allowWriteOutside;
+    if (granular === true)
+        return null;
+    if (granular === false)
+        return getWorkspaceRoots(config);
+    if (config?.allowOutsideWorkspace === true)
+        return null;
+    return getWorkspaceRoots(config);
+}
+/**
+ * Resolves the workspace boundary for *read* operations. Honours
+ * `workspace.allowReadOutside` (and the deprecated
+ * `allowOutsideWorkspace`) by returning `null`.
+ */
+function getReadRoots(config) {
+    // Same precedence as getWriteRoots: granular flag is authoritative
+    // when set, legacy flag is the fallback. Codex P1 #36.
+    const granular = config?.workspace?.allowReadOutside;
+    if (granular === true)
+        return null;
+    if (granular === false)
+        return getWorkspaceRoots(config);
+    if (config?.allowOutsideWorkspace === true)
+        return null;
+    return getWorkspaceRoots(config);
+}
+function getLocalSessionId(config) {
+    const cwd = getLocalCwd(config);
+    const digest = crypto.createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+    return `${DEFAULT_LOCAL_SESSION_ID}:${digest}`;
+}
+const missingSandboxRuntimeMessage = [
+    'Local sandbox is enabled, but @anthropic-ai/sandbox-runtime is not installed.',
+    'Install it with `npm install @anthropic-ai/sandbox-runtime`, or disable local sandboxing with `local.sandbox.enabled: false`.',
+].join(' ');
+/** Lazy-loads the ESM-only sandbox runtime only when sandboxing is enabled. */
+function loadSandboxRuntime() {
+    sandboxRuntimePromise ??= import('@anthropic-ai/sandbox-runtime');
+    return sandboxRuntimePromise;
+}
+function shouldUseLocalSandbox(config) {
+    return config.sandbox?.enabled === true;
+}
+let sandboxOffWarned = false;
+function maybeWarnSandboxOff(config) {
+    if (sandboxOffWarned || shouldUseLocalSandbox(config)) {
+        return;
+    }
+    sandboxOffWarned = true;
+    // eslint-disable-next-line no-console
+    console.warn('[@librechat/agents] Local execution engine is running without ' +
+        '@anthropic-ai/sandbox-runtime wrapping. The agent has full access to ' +
+        'the host filesystem and network. Set toolExecution.local.sandbox.enabled ' +
+        '= true to opt into process sandboxing.');
+}
+/**
+ * Test-only reset hook for the sandbox-off warning latch.
+ *
+ * @internal Not part of the public SDK surface.
+ */
+function _resetLocalEngineWarningsForTests() {
+    sandboxOffWarned = false;
+}
+function truncateLocalOutput(value, maxChars = DEFAULT_MAX_OUTPUT_CHARS) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    const head = Math.floor(maxChars * 0.6);
+    const tail = maxChars - head;
+    const omitted = value.length - maxChars;
+    return `${value.slice(0, head)}\n\n[... ${omitted} characters truncated ...]\n\n${value.slice(value.length - tail)}`;
+}
+function stripQuotedContent(command) {
+    let output = '';
+    let quote;
+    let escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (escaped) {
+            escaped = false;
+            output += ' ';
+            continue;
+        }
+        if (char === '\\') {
+            escaped = true;
+            output += ' ';
+            continue;
+        }
+        if (quote != null) {
+            if (char === quote) {
+                quote = undefined;
+            }
+            output += ' ';
+            continue;
+        }
+        if (char === '"' || char === '\'' || char === '`') {
+            quote = char;
+            output += ' ';
+            continue;
+        }
+        if (char === '#') {
+            while (i < command.length && command[i] !== '\n') {
+                output += ' ';
+                i++;
+            }
+            output += '\n';
+            continue;
+        }
+        output += char;
+    }
+    return output;
+}
+async function validateBashCommand(command, config = {}) {
+    const errors = [];
+    const warnings = [];
+    const normalized = stripQuotedContent(command);
+    if (command.trim() === '') {
+        errors.push('Command is empty.');
+    }
+    if (command.includes('\0')) {
+        errors.push('Command contains a NUL byte.');
+    }
+    if (config.allowDangerousCommands !== true) {
+        let blocked = false;
+        // Strip-then-match for the bare-form patterns (avoids false
+        // positives where the destructive text is buried inside a
+        // string the user is just printing).
+        for (const pattern of dangerousCommandPatterns) {
+            if (pattern.test(normalized)) {
+                errors.push('Command matches a destructive command pattern.');
+                blocked = true;
+                break;
+            }
+        }
+        // Original-form pass for patterns that REQUIRE matching quote
+        // pairs around a destructive path. Without this, `rm -rf "/"`
+        // and `chmod -R 777 "/"` slip past the strip-then-match pass
+        // because their destructive target is inside quotes.
+        if (!blocked) {
+            for (const pattern of quotedDestructivePatterns) {
+                if (pattern.test(command)) {
+                    errors.push('Command matches a destructive command pattern (quoted target).');
+                    blocked = true;
+                    break;
+                }
+            }
+        }
+        if (!blocked) {
+            for (const pattern of nestedShellDestructivePatterns) {
+                if (pattern.test(command)) {
+                    errors.push('Command matches a destructive command pattern (nested shell payload).');
+                    break;
+                }
+            }
+        }
+    }
+    const bashAstMode = config.bashAst ?? 'off';
+    if (bashAstMode !== 'off' && config.allowDangerousCommands !== true) {
+        const findings = bashAst.runBashAstChecks(normalized, bashAstMode);
+        const split = bashAst.bashAstFindingsToErrors(findings);
+        errors.push(...split.errors);
+        warnings.push(...split.warnings);
+    }
+    if (config.readOnly === true && mutatingCommandPattern.test(normalized)) {
+        errors.push('Command appears to mutate files or repository state in read-only local mode.');
+    }
+    // Use the same shell the actual execution path will use. Hard-coding
+    // DEFAULT_SHELL here would reject perfectly valid commands when the
+    // host configures `local.shell` to a non-bash binary (or when the
+    // runtime doesn't have bash installed at all but does have e.g. zsh).
+    const syntaxShell = config.shell ?? DEFAULT_SHELL;
+    const syntax = await spawnLocalProcess(syntaxShell, ['-n', '-c', command], {
+        ...config,
+        timeoutMs: Math.min(config.timeoutMs ?? DEFAULT_TIMEOUT_MS, 5000),
+        sandbox: { enabled: false },
+    }, { internal: true }).catch((error) => ({
+        stdout: '',
+        stderr: error.message,
+        exitCode: 1,
+        timedOut: false,
+    }));
+    if (syntax.exitCode !== 0) {
+        errors.push(syntax.stderr.trim() === ''
+            ? 'Command failed shell syntax validation.'
+            : `Command failed shell syntax validation: ${syntax.stderr.trim()}`);
+    }
+    if (/\bsudo\b/.test(normalized)) {
+        warnings.push('Command requests elevated privileges with sudo.');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+async function ensureSandbox(config, cwd) {
+    if (!shouldUseLocalSandbox(config)) {
+        return undefined;
+    }
+    const runtime = await loadSandboxRuntime().catch((error) => {
+        throw new Error(`${missingSandboxRuntimeMessage} Cause: ${error.message}`);
+    });
+    const runtimeConfig = buildSandboxRuntimeConfig(config, cwd, runtime.getDefaultWritePaths);
+    const nextKey = JSON.stringify(runtimeConfig);
+    if (sandboxInitialized && sandboxConfigKey === nextKey) {
+        return runtime.SandboxManager;
+    }
+    const dependencyCheck = runtime.SandboxManager.checkDependencies();
+    if (dependencyCheck.errors.length > 0) {
+        if (config.sandbox?.failIfUnavailable === true) {
+            throw new Error(`Local sandbox requested but unavailable: ${dependencyCheck.errors.join('; ')}`);
+        }
+        return undefined;
+    }
+    if (sandboxInitialized) {
+        await runtime.SandboxManager.reset();
+    }
+    // Cast at the runtime boundary — our public `BuiltSandboxRuntimeConfig`
+    // is intentionally structural to keep the optional peer dep out of
+    // generated `.d.ts` (Codex P1 #22). It's a structural subset of the
+    // peer's `SandboxRuntimeConfig`, so the assignment is sound at the
+    // one site where the peer is actually loaded.
+    await runtime.SandboxManager.initialize(runtimeConfig);
+    sandboxInitialized = true;
+    sandboxConfigKey = nextKey;
+    return runtime.SandboxManager;
+}
+/**
+ * Loopback addresses the in-process programmatic-tool bridge listens
+ * on (`LocalProgrammaticToolCalling.ts` binds 127.0.0.1). Sandboxed
+ * code launched by `run_tools_with_code` / `run_tools_with_bash` HTTPs
+ * back to that address — without the entries below, the bridge is
+ * silently blocked under sandbox.
+ */
+const BRIDGE_LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1'];
+function buildSandboxRuntimeConfig(config, cwd, getDefaultWritePaths) {
+    const sandbox = config.sandbox;
+    // Seed allowedDomains with loopback so the programmatic-tool bridge
+    // works under sandbox. If the host explicitly denied a loopback
+    // entry via `deniedDomains`, respect that and skip seeding it.
+    const userAllowed = sandbox?.network?.allowedDomains ?? [];
+    const denied = new Set(sandbox?.network?.deniedDomains ?? []);
+    const seededLoopback = BRIDGE_LOOPBACK_HOSTS.filter((host) => !denied.has(host) && !userAllowed.includes(host));
+    const allowedDomains = [...seededLoopback, ...userAllowed];
+    // Mirror the file-tools workspace boundary: anything in
+    // `additionalRoots` counts as in-workspace, so sandboxed shell/code
+    // can write there too. Without this, file_tools can resolve a
+    // sibling-root path but `bash`/`execute_code` is denied write
+    // access — confusing divergence flagged in Codex P2 #15.
+    const workspaceWriteRoots = config.workspace?.additionalRoots != null
+        ? getWorkspaceRoots(config)
+        : [cwd];
+    return {
+        network: {
+            allowedDomains,
+            deniedDomains: sandbox?.network?.deniedDomains ?? [],
+            ...(sandbox?.network?.allowUnixSockets != null && {
+                allowUnixSockets: sandbox.network.allowUnixSockets,
+            }),
+            ...(sandbox?.network?.allowAllUnixSockets != null && {
+                allowAllUnixSockets: sandbox.network.allowAllUnixSockets,
+            }),
+            ...(sandbox?.network?.allowLocalBinding != null && {
+                allowLocalBinding: sandbox.network.allowLocalBinding,
+            }),
+            ...(sandbox?.network?.allowMachLookup != null && {
+                allowMachLookup: sandbox.network.allowMachLookup,
+            }),
+        },
+        filesystem: {
+            denyRead: sandbox?.filesystem?.denyRead ?? [],
+            allowRead: sandbox?.filesystem?.allowRead,
+            allowWrite: sandbox?.filesystem?.allowWrite ?? [
+                ...workspaceWriteRoots,
+                ...getDefaultWritePaths(),
+            ],
+            denyWrite: sandbox?.filesystem?.denyWrite ?? [
+                '.env',
+                '.env.*',
+                '.git/config',
+                '.git/hooks/**',
+            ],
+            allowGitConfig: sandbox?.filesystem?.allowGitConfig,
+        },
+    };
+}
+async function spawnLocalProcess(command, args, config = {}, options) {
+    const cwd = getLocalCwd(config);
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxOutputChars = config.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+    // Streaming caps. Local tools execute arbitrary shell/code, so a noisy
+    // command (`yes`, `cat /dev/urandom | base64`, a verbose build) could
+    // accumulate gigabytes in memory before hitting the post-close cap.
+    // We bound in-memory per-stream and spill the rest to disk; we also
+    // hard-kill the child once total streamed bytes pass `maxSpawnedBytes`
+    // so a process producing unbounded output gets stopped instead of
+    // letting the host OOM.
+    const inMemoryCapBytes = maxOutputChars * 2;
+    const hardKillBytes = config.maxSpawnedBytes ?? DEFAULT_MAX_SPAWNED_BYTES;
+    const sandboxManager = await ensureSandbox(config, cwd);
+    // Internal probes (validateBashCommand syntax preflight,
+    // isRipgrepAvailable, syntax-check probe cache priming) pass
+    // `internal: true` so they don't emit a misleading "sandbox is
+    // off" warning AND don't flip `sandboxOffWarned = true`. Without
+    // this Codex P2 path: a run with `sandbox.enabled: true` would
+    // see a false warning from the syntax preflight, and the latch
+    // flip would suppress the warning in a *later* truly-unsandboxed
+    // run — exactly the scenario operators need to see.
+    if (sandboxManager == null && options?.internal !== true) {
+        maybeWarnSandboxOff(config);
+    }
+    let spawnCommand = command;
+    let spawnArgs = args;
+    if (sandboxManager != null) {
+        const rendered = [command, ...args.map(shellQuote)].join(' ');
+        const sandboxed = await sandboxManager.wrapWithSandbox(rendered);
+        spawnCommand = config.shell ?? DEFAULT_SHELL;
+        spawnArgs = ['-lc', sandboxed];
+    }
+    const launcher = getSpawn(config);
+    return new Promise((resolveResult, reject) => {
+        const child = launcher(spawnCommand, spawnArgs, {
+            cwd,
+            detached: process.platform !== 'win32',
+            env: { ...process.env, ...(config.env ?? {}) },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let totalSpawnedBytes = 0;
+        let overflowKilled = false;
+        let spillStream;
+        let spillPath;
+        let settled = false;
+        let timedOut = false;
+        let timeout;
+        const ensureSpill = () => {
+            if (spillStream != null)
+                return;
+            // Lazy-open the temp file the first time a stream's in-memory
+            // buffer overflows. Seed it with everything we've buffered so
+            // the file holds the FULL output (not just the post-cap tail).
+            // Uses the static `createWriteStream` import — `require('fs')`
+            // would throw `ReferenceError: require is not defined` in ESM
+            // consumers (this package ships both `dist/cjs` and `dist/esm`).
+            spillPath = path.resolve(os.tmpdir(), `lc-local-output-${crypto.randomUUID()}.txt`);
+            spillStream = fs.createWriteStream(spillPath);
+            spillStream.write('===== stdout =====\n');
+            spillStream.write(stdout);
+            spillStream.write('\n===== stderr =====\n');
+            spillStream.write(stderr);
+            spillStream.write('\n===== overflow stream begins here =====\n');
+        };
+        const handleChunk = (buf, kind) => {
+            totalSpawnedBytes += buf.length;
+            // hardKillBytes <= 0 means "no cap" per the public config contract
+            // (see LocalExecutionConfig.maxSpawnedBytes). Skip the kill check
+            // entirely in that case so a single byte doesn't terminate the run.
+            if (hardKillBytes > 0 &&
+                totalSpawnedBytes > hardKillBytes &&
+                !overflowKilled) {
+                overflowKilled = true;
+                killProcessTree(child);
+                return;
+            }
+            const current = kind === 'stdout' ? stdout : stderr;
+            if (current.length < inMemoryCapBytes) {
+                const text = buf.toString('utf8');
+                if (kind === 'stdout')
+                    stdout += text;
+                else
+                    stderr += text;
+                if (current.length + text.length >= inMemoryCapBytes) {
+                    ensureSpill();
+                }
+            }
+            else {
+                ensureSpill();
+                spillStream.write(`[${kind}] `);
+                spillStream.write(buf);
+            }
+        };
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timeout != null) {
+                clearTimeout(timeout);
+            }
+            const finalize = () => {
+                const truncated = {
+                    stdout: truncateLocalOutput(result.stdout, maxOutputChars),
+                    stderr: truncateLocalOutput(result.stderr, maxOutputChars),
+                };
+                resolveResult({
+                    ...result,
+                    ...truncated,
+                    ...(spillPath != null ? { fullOutputPath: spillPath } : {}),
+                });
+            };
+            if (spillStream == null) {
+                finalize();
+                return;
+            }
+            // Wait for the temp file to flush before reporting the path.
+            // Otherwise the model sees `full_output_path: …` for a file
+            // that's still being written.
+            spillStream.end(() => finalize());
+        };
+        const fail = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timeout != null) {
+                clearTimeout(timeout);
+            }
+            if (spillStream != null) {
+                spillStream.end();
+            }
+            reject(error);
+        };
+        if (timeoutMs > 0) {
+            timeout = setTimeout(() => {
+                timedOut = true;
+                killProcessTree(child);
+            }, timeoutMs);
+        }
+        child.stdout?.on('data', (chunk) => {
+            handleChunk(chunk, 'stdout');
+        });
+        child.stderr?.on('data', (chunk) => {
+            handleChunk(chunk, 'stderr');
+        });
+        child.on('error', fail);
+        child.on('close', (exitCode, signal) => {
+            // Synthesize a non-zero exit code whenever the process exited
+            // by signal — Node reports `exitCode: null` in that case and
+            // the formatter only prints non-null exit codes, so signal
+            // kills (overflow guard, `kill -9 $$` from inside the script,
+            // native crashes, OS OOM killer, …) would otherwise look like
+            // successful runs (Codex P1 + Codex P2). Overflow path keeps
+            // its 137 (SIGKILL) for compatibility; other signals map per
+            // POSIX `128 + signum`.
+            let finalExit = exitCode;
+            if (finalExit == null) {
+                if (overflowKilled) {
+                    finalExit = 137;
+                }
+                else if (signal != null) {
+                    finalExit = exitCodeForSignal(signal);
+                }
+            }
+            finish({
+                stdout,
+                stderr,
+                exitCode: finalExit,
+                timedOut,
+                ...(overflowKilled ? { overflowKilled: true } : {}),
+                ...(signal != null ? { signal } : {}),
+            });
+        });
+    });
+}
+async function executeLocalBash(command, config = {}) {
+    const validation = await validateBashCommand(command, config);
+    if (!validation.valid) {
+        throw new Error(validation.errors.join('\n'));
+    }
+    const shell = config.shell ?? DEFAULT_SHELL;
+    return spawnLocalProcess(shell, ['-lc', command], config);
+}
+/**
+ * Variant of `executeLocalBash` that exposes `args` as positional
+ * shell parameters (`$1`, `$2`, …). Mirrors what the other runtimes
+ * do in `getRuntimeCommand`. Uses the standard `bash -c <code> --
+ * arg0 arg1 …` form: the `--` becomes `$0`, then `args[0]` is `$1`
+ * and so on. Same AST validation as the no-args path.
+ *
+ * Used by both the `execute_code`/`lang:'bash'` path AND the
+ * `bash_tool` factory so the schema's `args` contract works
+ * identically in both surfaces.
+ */
+/**
+ * Matches a single arg that, on its own, references a protected
+ * location (`/`, `~`, `$HOME`, `${HOME}`, `.`, with optional trailing
+ * slash, wildcard, or dot-glob suffix). Used to spot the
+ * `command: 'rm -rf "$1"', args: ['/']` shape where the destructive
+ * target is moved into a positional arg to evade the command regex.
+ * Codex P1 [45], extended for dot-glob in Codex P1 [47] (mirrors the
+ * `DESTRUCTIVE_TARGET` suffix matrix exactly).
+ */
+const PROTECTED_TARGET_ARG_RE = /^(?:\/|~|\$\{?HOME\}?|\.)(?:\/?\.?\*|\/)?$/;
+/**
+ * Mutating-op recognizer for the args check. Conservative: only the
+ * three operations the destructive-command guard already covers
+ * directly (`rm -rf …`, `chmod -R …`, `chown -R …`). Other shell
+ * builtins might mutate state (`mv`, `cp` over an existing file,
+ * etc.) but the destructive guard doesn't try to catch those today,
+ * so we don't widen here either.
+ */
+const DESTRUCTIVE_OP_IN_COMMAND_RE = /\b(?:rm\s+-[^\s]*[rf]|chmod\s+-R|chown\s+-R)\b/;
+async function executeLocalBashWithArgs(command, args, config = {}) {
+    const validation = await validateBashCommand(command, config);
+    if (!validation.valid) {
+        throw new Error(validation.errors.join('\n'));
+    }
+    // Per-arg protected-target check (Codex P1 [45]). The command
+    // regex can't see `$1`/`$@` substitutions at runtime — `command:
+    // 'rm -rf "$1"', args: ['/']` would expand to `rm -rf '/'` inside
+    // bash but the validator only saw `rm -rf "$1"` (no destructive
+    // target). Block when (a) the command contains a destructive op
+    // AND (b) at least one arg matches the protected-target shape.
+    // Skipped when allowDangerousCommands is true (host-opted-in).
+    if (args.length > 0 &&
+        config.allowDangerousCommands !== true &&
+        DESTRUCTIVE_OP_IN_COMMAND_RE.test(command)) {
+        const offending = args.find((a) => PROTECTED_TARGET_ARG_RE.test(a));
+        if (offending !== undefined) {
+            throw new Error(`Command matches a destructive command pattern (protected target "${offending}" passed via positional arg).`);
+        }
+    }
+    const shell = config.shell ?? DEFAULT_SHELL;
+    return spawnLocalProcess(shell, ['-lc', command, '--', ...args], config);
+}
+async function executeLocalCode(input, config = {}) {
+    if (input.lang === 'bash') {
+        // Append `args` as positional parameters via the standard
+        // `bash -c <code> -- <args...>` form so `$1`, `$2`, … inside
+        // `code` resolve correctly. Honours the same args contract the
+        // other runtimes (py, js, …) already support.
+        if (input.args != null && input.args.length > 0) {
+            return executeLocalBashWithArgs(input.code, input.args, config);
+        }
+        return executeLocalBash(input.code, config);
+    }
+    const tempDir = path.resolve(os.tmpdir(), `lc-local-${crypto.randomUUID()}`);
+    await promises.mkdir(tempDir, { recursive: true });
+    try {
+        const runtime = getRuntimeCommand(input.lang, tempDir, input.code, input.args, config.shell);
+        if (runtime.source != null) {
+            await promises.writeFile(path.resolve(tempDir, runtime.fileName), runtime.source, 'utf8');
+        }
+        return await spawnLocalProcess(runtime.command, runtime.args, config);
+    }
+    finally {
+        await promises.rm(tempDir, { recursive: true, force: true });
+    }
+}
+function getRuntimeCommand(lang, tempDir, code, args = [], 
+// Override for the shell used by compile-style runtimes (`rs`,
+// `c`, `cpp`, `java`, `d`, `f90`). Threads `local.shell` so a host
+// that doesn't have bash (or wants `/bin/sh` / zsh) can still
+// execute these languages — Codex P2 #29: the bare-bash hardcode
+// mirrored the same gap that Codex P1 #6 fixed for the syntax
+// preflight, but had been missed for these runtime invocations.
+shellOverride) {
+    const fileFor = (name) => path.resolve(tempDir, name);
+    const shell = shellOverride ?? configShell();
+    switch (lang) {
+        case 'py':
+            return {
+                command: 'python3',
+                args: [fileFor('main.py'), ...args],
+                fileName: 'main.py',
+                source: code,
+            };
+        case 'js':
+            return {
+                command: 'node',
+                args: [fileFor('main.js'), ...args],
+                fileName: 'main.js',
+                source: code,
+            };
+        case 'ts':
+            return {
+                command: 'npx',
+                args: ['--no-install', 'tsx', fileFor('main.ts'), ...args],
+                fileName: 'main.ts',
+                source: code,
+            };
+        case 'php':
+            return {
+                command: 'php',
+                args: [fileFor('main.php'), ...args],
+                fileName: 'main.php',
+                source: code,
+            };
+        case 'go':
+            return {
+                command: 'go',
+                args: ['run', fileFor('main.go'), ...args],
+                fileName: 'main.go',
+                source: code,
+            };
+        case 'rs':
+            return {
+                command: shell,
+                args: [
+                    '-lc',
+                    `rustc ${shellQuote(fileFor('main.rs'))} -o ${shellQuote(fileFor('main-rs'))} && ${shellQuote(fileFor('main-rs'))} ${args.map(shellQuote).join(' ')}`,
+                ],
+                fileName: 'main.rs',
+                source: code,
+            };
+        case 'c':
+            return {
+                command: shell,
+                args: [
+                    '-lc',
+                    `cc ${shellQuote(fileFor('main.c'))} -o ${shellQuote(fileFor('main-c'))} && ${shellQuote(fileFor('main-c'))} ${args.map(shellQuote).join(' ')}`,
+                ],
+                fileName: 'main.c',
+                source: code,
+            };
+        case 'cpp':
+            return {
+                command: shell,
+                args: [
+                    '-lc',
+                    `c++ ${shellQuote(fileFor('main.cpp'))} -o ${shellQuote(fileFor('main-cpp'))} && ${shellQuote(fileFor('main-cpp'))} ${args.map(shellQuote).join(' ')}`,
+                ],
+                fileName: 'main.cpp',
+                source: code,
+            };
+        case 'java':
+            return {
+                command: shell,
+                args: [
+                    '-lc',
+                    `javac ${shellQuote(fileFor('Main.java'))} && java -cp ${shellQuote(tempDir)} Main ${args.map(shellQuote).join(' ')}`,
+                ],
+                fileName: 'Main.java',
+                source: code,
+            };
+        case 'r':
+            return {
+                command: 'Rscript',
+                args: [fileFor('main.R'), ...args],
+                fileName: 'main.R',
+                source: code,
+            };
+        case 'd':
+            return {
+                command: shell,
+                args: [
+                    '-lc',
+                    `dmd ${shellQuote(fileFor('main.d'))} -of=${shellQuote(fileFor('main-d'))} && ${shellQuote(fileFor('main-d'))} ${args.map(shellQuote).join(' ')}`,
+                ],
+                fileName: 'main.d',
+                source: code,
+            };
+        case 'f90':
+            return {
+                command: shell,
+                args: [
+                    '-lc',
+                    `gfortran ${shellQuote(fileFor('main.f90'))} -o ${shellQuote(fileFor('main-f90'))} && ${shellQuote(fileFor('main-f90'))} ${args.map(shellQuote).join(' ')}`,
+                ],
+                fileName: 'main.f90',
+                source: code,
+            };
+        default:
+            throw new Error(`Unsupported local runtime: ${lang}`);
+    }
+}
+function configShell() {
+    return process.platform === 'win32' ? 'bash.exe' : 'bash';
+}
+/**
+ * How long after SIGTERM we wait before escalating to SIGKILL. A
+ * cooperative process gets a graceful chance to flush + clean up;
+ * a process that ignores or traps SIGTERM (`trap '' TERM`) gets
+ * killed unconditionally so timeoutMs / maxSpawnedBytes can't be
+ * defeated by a hostile script. Codex P1 #28 — pre-fix the spawn
+ * promise would never resolve in that case and the entire tool run
+ * would hang past the advertised timeout.
+ */
+const SIGKILL_ESCALATION_MS = 2000;
+function sigterm(child) {
+    if (child.pid == null)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            child.kill('SIGTERM');
+            return;
+        }
+        process.kill(-child.pid, 'SIGTERM');
+    }
+    catch {
+        child.kill('SIGTERM');
+    }
+}
+function sigkill(child) {
+    if (child.pid == null)
+        return;
+    if (child.exitCode != null || child.signalCode != null)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            child.kill('SIGKILL');
+            return;
+        }
+        process.kill(-child.pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* already dead */
+        }
+    }
+}
+function killProcessTree(child) {
+    sigterm(child);
+    // Escalate to SIGKILL if the child is still alive after the grace
+    // window. Use unref() so the timer doesn't keep the Node process
+    // alive past the parent's natural exit.
+    const escalation = setTimeout(() => sigkill(child), SIGKILL_ESCALATION_MS);
+    escalation.unref?.();
+    child.once('close', () => clearTimeout(escalation));
+}
+function shellQuote(value) {
+    if (value === '') {
+        return '\'\'';
+    }
+    if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, '\'\\\'\'')}'`;
+}
+function resolveWorkspacePath(filePath, config = {}, intent = 'write') {
+    const cwd = getLocalCwd(config);
+    const absolutePath = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(cwd, filePath);
+    const roots = intent === 'write' ? getWriteRoots(config) : getReadRoots(config);
+    if (roots == null)
+        return absolutePath; // explicit allow-outside
+    if (absolutePath === cwd || isInsideAnyRoot(absolutePath, roots)) {
+        return absolutePath;
+    }
+    throw new Error(`Path is outside the local workspace: ${filePath}`);
+}
+function isInsideAnyRoot(absolutePath, roots) {
+    for (const root of roots) {
+        if (absolutePath === root)
+            return true;
+        const rel = path.relative(root, absolutePath);
+        if (!rel.startsWith('..') && !path.isAbsolute(rel))
+            return true;
+    }
+    return false;
+}
+async function realpathOrSelf(absolutePath, realpathImpl = promises.realpath) {
+    try {
+        return await realpathImpl(absolutePath);
+    }
+    catch {
+        return absolutePath;
+    }
+}
+/**
+ * Resolves the realpath of `absolutePath`, falling back to the nearest
+ * existing ancestor when the target itself does not yet exist (so the
+ * containment check still works for `write_file` to a brand-new path).
+ *
+ * Codex P2 #38: takes the realpath impl as a parameter so callers
+ * can route through `WorkspaceFS.realpath` when a custom engine is
+ * configured. Pre-fix, host `fs/promises.realpath` would fail on a
+ * remote/in-memory FS path and silently fall back to lexical
+ * containment, leaving the symlink-escape clamp ineffective on
+ * non-default engines.
+ */
+async function realpathOfPathOrAncestor(absolutePath, realpathImpl = promises.realpath) {
+    let current = absolutePath;
+    let suffix = '';
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+        try {
+            const real = await realpathImpl(current);
+            return suffix === '' ? real : path.resolve(real, suffix);
+        }
+        catch {
+            const parent = path.resolve(current, '..');
+            if (parent === current) {
+                return absolutePath;
+            }
+            const base = current.slice(parent.length + 1);
+            suffix = suffix === '' ? base : `${base}/${suffix}`;
+            current = parent;
+        }
+    }
+}
+/**
+ * Resolves a workspace path AND follows any symlinks before checking
+ * containment, so a symlink inside the workspace pointing outside is
+ * rejected even though the lexical path looks safe. Handles paths that
+ * don't yet exist (e.g. write_file targets) by realpath-resolving the
+ * nearest existing ancestor and re-attaching the unresolved suffix.
+ */
+async function resolveWorkspacePathSafe(filePath, config = {}, intent = 'write') {
+    const lexical = resolveWorkspacePath(filePath, config, intent);
+    const roots = intent === 'write' ? getWriteRoots(config) : getReadRoots(config);
+    if (roots == null) {
+        return lexical;
+    }
+    // Route realpath through the configured WorkspaceFS so a custom
+    // engine (in-memory, remote) gets the same symlink-escape clamp
+    // the host-fs path gets. Codex P2 #38: pre-fix the host realpath
+    // would fail on a non-default FS path and silently fall back to
+    // lexical containment, leaving the clamp ineffective.
+    const fsRealpath = (p) => getWorkspaceFS(config).realpath(p);
+    const realRoots = await Promise.all(roots.map((r) => realpathOrSelf(r, fsRealpath)));
+    const realPath = await realpathOfPathOrAncestor(lexical, fsRealpath);
+    if (isInsideAnyRoot(realPath, realRoots)) {
+        return lexical;
+    }
+    throw new Error(`Path is outside the local workspace (symlink escape): ${filePath}`);
+}
+
+exports._resetLocalEngineWarningsForTests = _resetLocalEngineWarningsForTests;
+exports.buildSandboxRuntimeConfig = buildSandboxRuntimeConfig;
+exports.executeLocalBash = executeLocalBash;
+exports.executeLocalBashWithArgs = executeLocalBashWithArgs;
+exports.executeLocalCode = executeLocalCode;
+exports.getLocalCwd = getLocalCwd;
+exports.getLocalSessionId = getLocalSessionId;
+exports.getReadRoots = getReadRoots;
+exports.getSpawn = getSpawn;
+exports.getWorkspaceFS = getWorkspaceFS;
+exports.getWorkspaceRoots = getWorkspaceRoots;
+exports.getWriteRoots = getWriteRoots;
+exports.resolveLocalExecutionConfig = resolveLocalExecutionConfig;
+exports.resolveWorkspacePath = resolveWorkspacePath;
+exports.resolveWorkspacePathSafe = resolveWorkspacePathSafe;
+exports.shellQuote = shellQuote;
+exports.spawnLocalProcess = spawnLocalProcess;
+exports.truncateLocalOutput = truncateLocalOutput;
+exports.validateBashCommand = validateBashCommand;
+//# sourceMappingURL=LocalExecutionEngine.cjs.map