@openai/agents-core 0.8.4 → 0.9.0

package/dist/sandbox/sandboxes/unixLocal.mjs

@@ -0,0 +1,858 @@
+import { UserError } from "../../errors.mjs";
+import { applyDiff } from "../../utils/applyDiff.mjs";
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, unlink, writeFile, } from 'node:fs/promises';
+import { lstatSync, realpathSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { tmpdir, userInfo } from 'node:os';
+import { normalizeSandboxClientCreateArgs } from "../client.mjs";
+import { normalizeExposedPort, recordExposedPortEndpoint, } from "../session.mjs";
+import { normalizeRelativePath } from "../manifest.mjs";
+import { SandboxConfigurationError } from "../errors.mjs";
+import { WorkspacePathPolicy, } from "../workspacePaths.mjs";
+import { applyOwnershipRecursive, assertLocalWorkspaceManifestMetadataSupported, materializeLocalWorkspaceManifest, materializeLocalWorkspaceManifestEntry, materializeLocalWorkspaceManifestMounts, pathExists, } from "./shared/localWorkspace.mjs";
+import { mergeManifestEntryDelta, mergeManifestDelta, sanitizeEnvironmentForPersistence, serializeManifest, } from "./shared/manifestPersistence.mjs";
+import { isHostPathWithinRoot, relativeHostPathEscapesRoot, } from "../shared/hostPath.mjs";
+import { assertViewImageByteLength, imageOutputFromBytes, } from "../shared/media.mjs";
+import { elapsedSeconds, formatExecResponse, truncateOutput, } from "../shared/output.mjs";
+import { canReuseLocalSnapshotWorkspace, createWorkspaceArchive, localSnapshotIsRestorable, persistLocalSnapshot, restoreLocalSnapshotToWorkspace, restoreWorkspaceArchive, serializeLocalSnapshotSpec, } from "./shared/localSnapshots.mjs";
+import { spawnInPseudoTerminal } from "./shared/pty.mjs";
+import { runSandboxProcess } from "./shared/runProcess.mjs";
+import { resolveLocalShellCommand } from "./shared/shellCommand.mjs";
+import { deserializeLocalSandboxSessionStateValues, normalizeExposedPorts, } from "./shared/sessionStateValues.mjs";
+const DEFAULT_EXEC_YIELD_TIME_MS = 10_000;
+const DEFAULT_WRITE_STDIN_YIELD_TIME_MS = 250;
+const MAX_ACTIVE_PROCESS_OUTPUT_CHARS = 1024 * 1024;
+const RUN_AS_LOOKUP_TIMEOUT_MS = 10_000;
+const DEFAULT_SANDBOX_COMMAND_PATH = '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin';
+export class UnixLocalSandboxSession {
+    state;
+    defaultShell;
+    activeProcesses = new Map();
+    nextSessionId = 1;
+    closed = false;
+    constructor(args) {
+        this.state = args.state;
+        this.defaultShell = args.defaultShell;
+    }
+    createEditor(runAs) {
+        return new UnixLocalSandboxEditor(this, runAs);
+    }
+    supportsPty() {
+        return true;
+    }
+    async resolveExposedPort(port) {
+        const exposedPort = normalizeExposedPort(port);
+        const configuredPorts = this.state.configuredExposedPorts ?? [];
+        if (configuredPorts.length > 0 && !configuredPorts.includes(exposedPort)) {
+            throw new SandboxConfigurationError(`UnixLocalSandboxClient was not configured to expose port ${exposedPort}.`, {
+                provider: 'UnixLocalSandboxClient',
+                port: exposedPort,
+                configuredPorts,
+            });
+        }
+        return recordExposedPortEndpoint(this.state, {
+            host: '127.0.0.1',
+            port: exposedPort,
+            tls: false,
+        });
+    }
+    async execCommand(args) {
+        return formatExecResponse(await this.exec(args));
+    }
+    async exec(args) {
+        const start = Date.now();
+        const cwd = this.resolveCommandWorkdir(args.workdir);
+        const logicalCwd = this.logicalWorkdirForPath(args.workdir);
+        const child = await this.spawnShellCommand(this.translateCommandInput(args.cmd), {
+            cwd,
+            logicalCwd,
+            shell: args.shell,
+            login: args.login ?? true,
+            runAs: args.runAs,
+            tty: args.tty ?? false,
+        });
+        const activeProcess = this.trackChildProcess(child, {
+            tty: args.tty ?? false,
+        });
+        if (!args.tty) {
+            await waitForProcessOrTimeout(activeProcess, args.yieldTimeMs ?? DEFAULT_EXEC_YIELD_TIME_MS);
+            const processOutput = consumeActiveProcessOutput(activeProcess);
+            if (activeProcess.done) {
+                const output = truncateOutput(this.translateCommandOutput(processOutput.output), args.maxOutputTokens);
+                return {
+                    output: output.text,
+                    stdout: this.translateCommandOutput(processOutput.stdout),
+                    stderr: this.translateCommandOutput(processOutput.stderr),
+                    wallTimeSeconds: elapsedSeconds(start),
+                    exitCode: activeProcess.exitCode ?? 1,
+                    originalTokenCount: output.originalTokenCount,
+                };
+            }
+            const output = truncateOutput(this.translateCommandOutput(processOutput.output), args.maxOutputTokens);
+            const sessionId = this.allocateProcessId(activeProcess);
+            return {
+                output: output.text,
+                stdout: this.translateCommandOutput(processOutput.stdout),
+                stderr: this.translateCommandOutput(processOutput.stderr),
+                wallTimeSeconds: elapsedSeconds(start),
+                sessionId,
+                originalTokenCount: output.originalTokenCount,
+            };
+        }
+        const yieldTimeMs = args.yieldTimeMs ?? DEFAULT_EXEC_YIELD_TIME_MS;
+        await waitForProcessOrTimeout(activeProcess, yieldTimeMs);
+        if (activeProcess.done) {
+            const processOutput = consumeActiveProcessOutput(activeProcess);
+            const output = truncateOutput(this.translateCommandOutput(processOutput.output), args.maxOutputTokens);
+            return {
+                output: output.text,
+                stdout: this.translateCommandOutput(processOutput.stdout),
+                stderr: this.translateCommandOutput(processOutput.stderr),
+                wallTimeSeconds: elapsedSeconds(start),
+                exitCode: activeProcess.exitCode ?? 1,
+                originalTokenCount: output.originalTokenCount,
+            };
+        }
+        const sessionId = this.allocateProcessId(activeProcess);
+        const processOutput = consumeActiveProcessOutput(activeProcess);
+        const output = truncateOutput(this.translateCommandOutput(processOutput.output), args.maxOutputTokens);
+        return {
+            output: output.text,
+            stdout: this.translateCommandOutput(processOutput.stdout),
+            stderr: this.translateCommandOutput(processOutput.stderr),
+            wallTimeSeconds: elapsedSeconds(start),
+            sessionId,
+            originalTokenCount: output.originalTokenCount,
+        };
+    }
+    async writeStdin(args) {
+        const activeProcess = this.activeProcesses.get(args.sessionId);
+        if (!activeProcess) {
+            return formatExecResponse({
+                output: `write_stdin failed: session not found: ${args.sessionId}`,
+                wallTimeSeconds: 0,
+                exitCode: 1,
+            });
+        }
+        const start = Date.now();
+        const chars = args.chars ?? '';
+        if (!activeProcess.tty && chars.includes('\u0003')) {
+            activeProcess.child.kill('SIGINT');
+        }
+        const remainingChars = activeProcess.tty
+            ? chars
+            : chars.split('\u0003').join('');
+        if (remainingChars.length > 0) {
+            activeProcess.child.stdin.write(remainingChars);
+        }
+        await waitForProcessOrTimeout(activeProcess, args.yieldTimeMs ?? DEFAULT_WRITE_STDIN_YIELD_TIME_MS);
+        const processOutput = consumeActiveProcessOutput(activeProcess);
+        const output = truncateOutput(this.translateCommandOutput(processOutput.output), args.maxOutputTokens);
+        if (activeProcess.done) {
+            this.activeProcesses.delete(args.sessionId);
+            return formatExecResponse({
+                output: output.text,
+                wallTimeSeconds: elapsedSeconds(start),
+                exitCode: activeProcess.exitCode ?? 1,
+                originalTokenCount: output.originalTokenCount,
+            });
+        }
+        return formatExecResponse({
+            output: output.text,
+            wallTimeSeconds: elapsedSeconds(start),
+            sessionId: args.sessionId,
+            originalTokenCount: output.originalTokenCount,
+        });
+    }
+    async viewImage(args) {
+        await this.resolveFilesystemRunAs(args.runAs);
+        const filePath = this.resolveSandboxPath(args.path);
+        const info = await stat(filePath).catch(() => {
+            throw new UserError(`Image file not found: ${args.path}`);
+        });
+        if (!info.isFile()) {
+            throw new UserError(`Image path is not a file: ${args.path}`);
+        }
+        assertViewImageByteLength(args.path, info.size);
+        const bytes = await readFile(filePath);
+        return imageOutputFromBytes(args.path, bytes);
+    }
+    async pathExists(path, runAs) {
+        await this.resolveFilesystemRunAs(runAs);
+        return await pathExists(this.resolveSandboxPath(path));
+    }
+    async readFile(args) {
+        await this.resolveFilesystemRunAs(args.runAs);
+        const bytes = await readFile(this.resolveSandboxPath(args.path));
+        if (typeof args.maxBytes === 'number' && bytes.byteLength > args.maxBytes) {
+            return bytes.subarray(0, args.maxBytes);
+        }
+        return bytes;
+    }
+    async listDir(args) {
+        await this.resolveFilesystemRunAs(args.runAs);
+        const logicalPath = this.resolveLogicalPath(args.path);
+        const entries = await readdir(this.resolveSandboxPath(args.path), {
+            withFileTypes: true,
+        });
+        return entries.map((entry) => ({
+            name: entry.name,
+            path: logicalPath ? `${logicalPath}/${entry.name}` : entry.name,
+            type: entry.isDirectory() ? 'dir' : entry.isFile() ? 'file' : 'other',
+        }));
+    }
+    async materializeEntry(args) {
+        const runAs = await this.resolveFilesystemRunAs(args.runAs);
+        const logicalPath = this.resolveLogicalPath(args.path);
+        await materializeLocalWorkspaceManifestEntry(this.state.workspaceRootPath, logicalPath, args.entry);
+        if (runAs) {
+            await applyOwnershipRecursive(this.resolveSandboxPath(args.path), runAs.uid, runAs.gid);
+        }
+        this.state.manifest = mergeManifestEntryDelta(this.state.manifest, logicalPath, args.entry);
+    }
+    async applyManifest(manifest, runAs) {
+        assertLocalWorkspaceManifestMetadataSupported('UnixLocalSandboxClient', manifest);
+        const identity = await this.resolveFilesystemRunAs(runAs);
+        await materializeLocalWorkspaceManifest(manifest, this.state.workspaceRootPath);
+        const environment = await manifest.resolveEnvironment();
+        if (identity) {
+            for (const path of Object.keys(manifest.entries)) {
+                await applyOwnershipRecursive(this.resolveSandboxPath(path), identity.uid, identity.gid);
+            }
+        }
+        this.state.environment = {
+            ...this.state.environment,
+            ...environment,
+        };
+        this.state.manifest = mergeManifestDelta(this.state.manifest, manifest);
+    }
+    async persistWorkspace() {
+        return await createWorkspaceArchive(this.state.workspaceRootPath, this.state.manifest.ephemeralPersistencePaths());
+    }
+    async hydrateWorkspace(data) {
+        await restoreWorkspaceArchive(data, this.state.workspaceRootPath);
+        await this.materializeRestoredWorkspaceMounts();
+    }
+    async stop() {
+        await this.stopActiveProcesses();
+    }
+    async shutdown() {
+        await this.close();
+    }
+    async delete() {
+        await this.close();
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        await this.stopActiveProcesses();
+        if (this.state.workspaceRootOwned) {
+            await rm(this.state.workspaceRootPath, { recursive: true, force: true });
+        }
+    }
+    async stopActiveProcesses() {
+        await Promise.all([...this.activeProcesses.values()].map(async (activeProcess) => {
+            if (!activeProcess.done) {
+                activeProcess.child.kill('SIGTERM');
+                await waitForProcessOrTimeout(activeProcess, 250);
+            }
+            if (!activeProcess.done) {
+                activeProcess.child.kill('SIGKILL');
+                await activeProcess.donePromise.catch(() => { });
+            }
+        }));
+        this.activeProcesses.clear();
+    }
+    resolveSandboxPath(path, options = {}) {
+        const resolved = this.resolveSandboxPathTarget(path, options);
+        const workspaceRelativePath = resolved.workspaceRelativePath ?? '';
+        if (!workspaceRelativePath && !resolved.grant) {
+            return this.state.workspaceRootPath;
+        }
+        if (resolved.grant) {
+            return validateResolvedHostPath({
+                path,
+                resolvedPath: resolved.path,
+                allowedRoot: resolved.grant.path,
+            });
+        }
+        const mountPath = this.resolveLocalBindMountPath(workspaceRelativePath, path, options);
+        if (mountPath) {
+            return mountPath;
+        }
+        const resolvedPath = resolve(this.state.workspaceRootPath, workspaceRelativePath);
+        const relativeToRoot = relative(this.state.workspaceRootPath, resolvedPath);
+        if (relativeHostPathEscapesRoot(relativeToRoot)) {
+            throw new UserError(`Sandbox path "${path}" escapes the workspace root.`);
+        }
+        return validateResolvedHostPath({
+            path,
+            resolvedPath,
+            allowedRoot: this.state.workspaceRootPath,
+        });
+    }
+    resolveCommandWorkdir(path) {
+        return this.resolveSandboxPath(path);
+    }
+    resolveSandboxPathTarget(path, options = {}) {
+        return new WorkspacePathPolicy({
+            root: this.state.manifest.root,
+            extraPathGrants: this.state.manifest.extraPathGrants,
+        }).resolve(path, options);
+    }
+    resolveLocalBindMountPath(workspaceRelativePath, path, options) {
+        for (const { entry, mountPath } of this.state.manifest.mountTargets()) {
+            const source = localBindMountSource(entry);
+            if (!source) {
+                continue;
+            }
+            const mountRelativePath = new WorkspacePathPolicy({
+                root: this.state.manifest.root,
+            }).resolve(mountPath).workspaceRelativePath;
+            if (typeof mountRelativePath !== 'string') {
+                continue;
+            }
+            if (!pathWithinLogicalRoot(workspaceRelativePath, mountRelativePath)) {
+                continue;
+            }
+            if (options.forWrite && entry.readOnly !== false) {
+                throw new UserError(`Sandbox path "${path}" is inside a read-only local bind mount.`);
+            }
+            const childPath = workspaceRelativePath === mountRelativePath
+                ? ''
+                : workspaceRelativePath.slice(mountRelativePath.length + 1);
+            const resolvedPath = childPath ? resolve(source, childPath) : source;
+            return validateResolvedHostPath({
+                path,
+                resolvedPath,
+                allowedRoot: source,
+            });
+        }
+        return undefined;
+    }
+    resolveLogicalPath(path) {
+        if (!path || path.trim().length === 0) {
+            return '';
+        }
+        const logicalRoot = this.state.manifest.root;
+        const trimmed = path.trim();
+        if (trimmed === logicalRoot) {
+            return '';
+        }
+        if (logicalRoot === '/') {
+            return normalizeRelativePath(trimmed.startsWith('/') ? trimmed.slice(1) : trimmed);
+        }
+        if (trimmed.startsWith(`${logicalRoot}/`)) {
+            return normalizeRelativePath(trimmed.slice(logicalRoot.length + 1));
+        }
+        if (trimmed.startsWith('/')) {
+            throw new UserError(`Sandbox path "${path}" must stay within ${logicalRoot}.`);
+        }
+        return normalizeRelativePath(trimmed);
+    }
+    async spawnShellCommand(command, args) {
+        const { shellPath, flag } = resolveLocalShellCommand({
+            shell: args.shell,
+            defaultShell: this.defaultShell,
+            envShell: process.env.SHELL,
+            login: args.login,
+        });
+        const runAs = await this.resolveCommandRunAs(args.runAs);
+        const env = buildCommandEnvironment({
+            environment: this.state.environment,
+            shellPath,
+            home: this.state.workspaceRootPath,
+            pwd: args.logicalCwd,
+        });
+        if (args.tty) {
+            return spawnInPseudoTerminal(shellPath, [flag, command], {
+                cwd: args.cwd,
+                env,
+                ...(runAs
+                    ? {
+                        uid: runAs.uid,
+                        gid: runAs.gid,
+                    }
+                    : {}),
+            });
+        }
+        return spawn(shellPath, [flag, command], {
+            cwd: args.cwd,
+            env,
+            ...(runAs
+                ? {
+                    uid: runAs.uid,
+                    gid: runAs.gid,
+                }
+                : {}),
+            stdio: 'pipe',
+        });
+    }
+    translateCommandInput(command) {
+        // Unix-local is not a chroot; command rewriting preserves manifest-root UX while
+        // filesystem APIs continue to enforce host-path containment separately.
+        if (this.state.manifest.root === '/') {
+            return translateRootManifestCommandInput(command, this.state.workspaceRootPath);
+        }
+        return translateManifestRootCommandInput(command, this.state.manifest.root, this.state.workspaceRootPath);
+    }
+    translateCommandOutput(output) {
+        if (this.state.manifest.root === '/') {
+            return translateRootManifestCommandOutput(output, this.state.workspaceRootPath);
+        }
+        return translateManifestRootCommandOutput(output, this.state.manifest.root, this.state.workspaceRootPath);
+    }
+    async materializeRestoredWorkspaceMounts() {
+        await materializeLocalWorkspaceManifestMounts(this.state.manifest, this.state.workspaceRootPath);
+    }
+    logicalWorkdirForPath(path) {
+        return this.resolveSandboxPathTarget(path).path;
+    }
+    async resolveCommandRunAs(runAs) {
+        const identity = await this.resolveRunAsIdentity(runAs);
+        if (!identity || identity.isCurrentUser) {
+            return identity;
+        }
+        if (typeof process.getuid !== 'function' || process.getuid() !== 0) {
+            throw new UserError(`Unix-local sandbox runAs="${runAs}" requires the host process to run as root or the requested user.`);
+        }
+        return identity;
+    }
+    async resolveFilesystemRunAs(runAs) {
+        const identity = await this.resolveRunAsIdentity(runAs);
+        if (!identity || identity.isCurrentUser) {
+            return identity;
+        }
+        if (typeof process.getuid !== 'function' || process.getuid() !== 0) {
+            throw new UserError(`Unix-local sandbox filesystem operations cannot honor runAs="${runAs}" without root privileges.`);
+        }
+        return identity;
+    }
+    async resolveRunAsIdentity(runAs) {
+        if (!runAs || runAs.trim().length === 0) {
+            return undefined;
+        }
+        const requestedUser = runAs.trim();
+        const currentUser = userInfo().username;
+        const currentUid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+        const currentGid = typeof process.getgid === 'function' ? process.getgid() : undefined;
+        if (requestedUser === currentUser &&
+            currentUid !== undefined &&
+            currentGid !== undefined) {
+            return {
+                username: currentUser,
+                uid: currentUid,
+                gid: currentGid,
+                isCurrentUser: true,
+            };
+        }
+        const [uidResult, gidResult] = await Promise.all([
+            runSandboxProcess('id', ['-u', requestedUser], {
+                timeoutMs: RUN_AS_LOOKUP_TIMEOUT_MS,
+            }),
+            runSandboxProcess('id', ['-g', requestedUser], {
+                timeoutMs: RUN_AS_LOOKUP_TIMEOUT_MS,
+            }),
+        ]);
+        if (uidResult.status !== 0 || gidResult.status !== 0) {
+            throw new UserError(`Sandbox runAs user "${requestedUser}" could not be resolved on this host.`);
+        }
+        const uid = Number(uidResult.stdout.trim());
+        const gid = Number(gidResult.stdout.trim());
+        return {
+            username: requestedUser,
+            uid,
+            gid,
+            isCurrentUser: currentUid !== undefined &&
+                currentGid !== undefined &&
+                uid === currentUid &&
+                gid === currentGid,
+        };
+    }
+    trackChildProcess(child, options = {}) {
+        let resolveDone = () => { };
+        const donePromise = new Promise((resolve) => {
+            resolveDone = resolve;
+        });
+        let resolveOutputClosed = () => { };
+        const outputClosedPromise = new Promise((resolve) => {
+            resolveOutputClosed = resolve;
+        });
+        const activeProcess = {
+            child,
+            tty: options.tty ?? false,
+            output: '',
+            stdout: '',
+            stderr: '',
+            droppedOutputChars: 0,
+            droppedStdoutChars: 0,
+            droppedStderrChars: 0,
+            exitCode: null,
+            done: false,
+            donePromise,
+            resolveDone,
+            outputClosedPromise,
+            resolveOutputClosed,
+        };
+        let openOutputStreams = 2;
+        const markOutputStreamClosed = () => {
+            openOutputStreams -= 1;
+            if (openOutputStreams === 0) {
+                activeProcess.resolveOutputClosed();
+            }
+        };
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            appendActiveProcessOutput(activeProcess, chunk, 'stdout');
+        });
+        child.stderr.on('data', (chunk) => {
+            appendActiveProcessOutput(activeProcess, chunk, 'stderr');
+        });
+        child.stdout.once('close', markOutputStreamClosed);
+        child.stderr.once('close', markOutputStreamClosed);
+        child.on('close', (code, signal) => {
+            activeProcess.exitCode = code ?? signalToExitCode(signal);
+            activeProcess.done = true;
+            activeProcess.resolveDone();
+        });
+        child.on('error', (error) => {
+            appendActiveProcessOutput(activeProcess, `${error.message}\n`, 'stderr');
+            activeProcess.exitCode = 1;
+            activeProcess.done = true;
+            activeProcess.resolveOutputClosed();
+            activeProcess.resolveDone();
+        });
+        return activeProcess;
+    }
+    allocateProcessId(activeProcess) {
+        const sessionId = this.nextSessionId++;
+        this.activeProcesses.set(sessionId, activeProcess);
+        return sessionId;
+    }
+}
+export class UnixLocalSandboxClient {
+    backendId = 'unix_local';
+    supportsDefaultOptions = true;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async create(args, manifestOptions) {
+        const createArgs = normalizeSandboxClientCreateArgs(args, manifestOptions);
+        const manifest = createArgs.manifest;
+        const resolvedOptions = {
+            ...this.options,
+            ...createArgs.options,
+            ...(createArgs.snapshot
+                ? { snapshot: createArgs.snapshot }
+                : {}),
+            ...(createArgs.concurrencyLimits
+                ? { concurrencyLimits: createArgs.concurrencyLimits }
+                : {}),
+        };
+        assertLocalWorkspaceManifestMetadataSupported('UnixLocalSandboxClient', manifest);
+        const workspaceRootPath = await mkdtemp(join(resolvedOptions.workspaceBaseDir ?? tmpdir(), 'openai-agents-sandbox-'));
+        await materializeLocalWorkspaceManifest(manifest, workspaceRootPath, {
+            concurrencyLimits: resolvedOptions.concurrencyLimits,
+        });
+        const environment = await manifest.resolveEnvironment();
+        const configuredExposedPorts = normalizeExposedPorts(resolvedOptions.exposedPorts);
+        return new UnixLocalSandboxSession({
+            state: {
+                manifest,
+                workspaceRootPath,
+                workspaceRootOwned: true,
+                environment,
+                snapshotSpec: resolvedOptions.snapshot ?? null,
+                snapshot: null,
+                configuredExposedPorts,
+            },
+            defaultShell: resolvedOptions.defaultShell,
+        });
+    }
+    async resume(state) {
+        const restoredState = await this.restoreIfNeeded(state);
+        return new UnixLocalSandboxSession({
+            state: restoredState,
+            defaultShell: this.options.defaultShell,
+        });
+    }
+    async serializeSessionState(state) {
+        const snapshotSpec = state.snapshotSpec ?? this.options.snapshot ?? null;
+        const snapshot = await persistLocalSnapshot('UnixLocalSandboxClient', state, snapshotSpec);
+        state.snapshotSpec = snapshotSpec;
+        return {
+            manifest: serializeManifest(state.manifest),
+            workspaceRootPath: state.workspaceRootPath,
+            workspaceRootOwned: state.workspaceRootOwned,
+            environment: sanitizeEnvironmentForPersistence(state),
+            snapshotSpec: serializeLocalSnapshotSpec(snapshotSpec),
+            snapshot,
+            snapshotFingerprint: state.snapshotFingerprint ?? null,
+            snapshotFingerprintVersion: state.snapshotFingerprintVersion ?? null,
+            configuredExposedPorts: state.configuredExposedPorts ?? [],
+            exposedPorts: state.exposedPorts ?? null,
+        };
+    }
+    async deserializeSessionState(state) {
+        return deserializeLocalSandboxSessionStateValues(state, this.options.snapshot);
+    }
+    async restoreIfNeeded(state) {
+        if (await pathExists(state.workspaceRootPath)) {
+            if (await canReuseLocalSnapshotWorkspace(state)) {
+                return state;
+            }
+            if (await localSnapshotIsRestorable(state)) {
+                return await restoreSnapshotAndMounts(state, state.workspaceRootPath);
+            }
+            return state;
+        }
+        if (!(await localSnapshotIsRestorable(state))) {
+            throw new UserError('UnixLocal sandbox workspace is unavailable and no local snapshot could be restored.');
+        }
+        const workspaceRootPath = await mkdtemp(join(this.options.workspaceBaseDir ?? tmpdir(), 'openai-agents-sandbox-'));
+        return await restoreSnapshotAndMounts({
+            ...state,
+            workspaceRootPath,
+            workspaceRootOwned: true,
+        }, workspaceRootPath);
+    }
+}
+async function restoreSnapshotAndMounts(state, workspaceRootPath) {
+    const restoredState = await restoreLocalSnapshotToWorkspace(state, workspaceRootPath);
+    await materializeLocalWorkspaceManifestMounts(restoredState.manifest, restoredState.workspaceRootPath);
+    return restoredState;
+}
+function localBindMountSource(entry) {
+    if (entry.type !== 'mount' || typeof entry.source !== 'string') {
+        return undefined;
+    }
+    if (entry.mountStrategy !== undefined &&
+        entry.mountStrategy.type !== 'local_bind') {
+        return undefined;
+    }
+    return isAbsolute(entry.source) ? entry.source : undefined;
+}
+function pathWithinLogicalRoot(path, root) {
+    return path === root || path.startsWith(`${root}/`);
+}
+function validateResolvedHostPath(args) {
+    const allowedRootRealPath = realpathForValidation(args.allowedRoot, args.path);
+    const existingPath = nearestExistingPath(args.resolvedPath);
+    if (!existingPath) {
+        throw new UserError(`Sandbox path "${args.path}" escapes the workspace root.`);
+    }
+    const realPath = realpathForValidation(existingPath, args.path);
+    if (!isHostPathWithinRoot(allowedRootRealPath, realPath)) {
+        throw new UserError(`Sandbox path "${args.path}" escapes the workspace root.`);
+    }
+    return args.resolvedPath;
+}
+function nearestExistingPath(path) {
+    let current = path;
+    while (true) {
+        try {
+            lstatSync(current);
+            return current;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+function realpathForValidation(path, originalPath) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        throw new UserError(`Sandbox path "${originalPath}" escapes the workspace root.`);
+    }
+}
+class UnixLocalSandboxEditor {
+    session;
+    runAs;
+    constructor(session, runAs) {
+        this.session = session;
+        this.runAs = runAs;
+    }
+    async createFile(operation) {
+        const identity = await this.session.resolveFilesystemRunAs(this.runAs);
+        const filePath = this.session.resolveSandboxPath(operation.path, {
+            forWrite: true,
+        });
+        await mkdir(dirname(filePath), { recursive: true });
+        const content = applyDiff('', operation.diff, 'create');
+        await writeFile(filePath, content, { encoding: 'utf8', flag: 'wx' });
+        if (identity) {
+            await applyOwnershipRecursive(filePath, identity.uid, identity.gid);
+        }
+        return {};
+    }
+    async updateFile(operation) {
+        const identity = await this.session.resolveFilesystemRunAs(this.runAs);
+        const moveTo = operation.moveTo;
+        const filePath = this.session.resolveSandboxPath(operation.path, {
+            forWrite: true,
+        });
+        const destinationPath = moveTo
+            ? this.session.resolveSandboxPath(moveTo, { forWrite: true })
+            : filePath;
+        const current = await readFile(filePath, 'utf8');
+        const next = applyDiff(current, operation.diff);
+        await mkdir(dirname(destinationPath), { recursive: true });
+        await writeFile(destinationPath, next, 'utf8');
+        if (moveTo && destinationPath !== filePath) {
+            await unlink(filePath);
+        }
+        if (identity) {
+            await applyOwnershipRecursive(destinationPath, identity.uid, identity.gid);
+        }
+        return {};
+    }
+    async deleteFile(operation) {
+        await this.session.resolveFilesystemRunAs(this.runAs);
+        const filePath = this.session.resolveSandboxPath(operation.path, {
+            forWrite: true,
+        });
+        await unlink(filePath);
+        return {};
+    }
+}
+function buildCommandEnvironment(args) {
+    return {
+        PATH: DEFAULT_SANDBOX_COMMAND_PATH,
+        HOME: args.home,
+        USER: 'sandbox',
+        LOGNAME: 'sandbox',
+        SHELL: args.shellPath,
+        TMPDIR: '/tmp',
+        ...args.environment,
+        PWD: args.pwd,
+    };
+}
+function translateRootManifestCommandInput(command, workspaceRootPath) {
+    return command.replace(/(^|[\s"'=<>])\/([^\s"'|&;<>(){}]*)/g, (_match, prefix, pathSuffix) => `${prefix}${workspaceRootPath}/${pathSuffix}`);
+}
+function translateManifestRootCommandInput(command, manifestRoot, workspaceRootPath) {
+    const escapedManifestRoot = escapeRegExp(manifestRoot);
+    const pathPrefix = String.raw `(^|[\s"'=<>])`;
+    const pathSuffix = String.raw `(?=$|[\/\s"'|&;<>(){}])`;
+    return command.replace(new RegExp(`${pathPrefix}${escapedManifestRoot}${pathSuffix}`, 'g'), (_match, prefix) => `${prefix}${workspaceRootPath}`);
+}
+function translateRootManifestCommandOutput(output, workspaceRootPath) {
+    return translateWorkspaceRootCommandOutput(output, '/', workspaceRootPath);
+}
+function translateManifestRootCommandOutput(output, manifestRoot, workspaceRootPath) {
+    return translateWorkspaceRootCommandOutput(output, manifestRoot, workspaceRootPath);
+}
+function translateWorkspaceRootCommandOutput(output, manifestRoot, workspaceRootPath) {
+    const nestedPathReplacement = manifestRoot === '/' ? '/' : `${manifestRoot}/`;
+    let translated = output;
+    for (const path of workspaceRootOutputPaths(workspaceRootPath)) {
+        translated = translated
+            .split(`${path}/`)
+            .join(nestedPathReplacement)
+            .split(path)
+            .join(manifestRoot);
+    }
+    return translated;
+}
+function workspaceRootOutputPaths(workspaceRootPath) {
+    const paths = [workspaceRootPath];
+    try {
+        paths.push(realpathSync(workspaceRootPath));
+    }
+    catch {
+        return paths;
+    }
+    return Array.from(new Set(paths)).sort((a, b) => b.length - a.length);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function appendActiveProcessOutput(activeProcess, chunk, stream) {
+    if (chunk.length === 0) {
+        return;
+    }
+    const combined = appendBoundedOutput(activeProcess.output, activeProcess.droppedOutputChars, chunk);
+    activeProcess.output = combined.output;
+    activeProcess.droppedOutputChars = combined.droppedChars;
+    if (stream === 'stdout') {
+        const stdout = appendBoundedOutput(activeProcess.stdout, activeProcess.droppedStdoutChars, chunk);
+        activeProcess.stdout = stdout.output;
+        activeProcess.droppedStdoutChars = stdout.droppedChars;
+        return;
+    }
+    const stderr = appendBoundedOutput(activeProcess.stderr, activeProcess.droppedStderrChars, chunk);
+    activeProcess.stderr = stderr.output;
+    activeProcess.droppedStderrChars = stderr.droppedChars;
+}
+function appendBoundedOutput(output, droppedChars, chunk) {
+    const nextLength = output.length + chunk.length;
+    if (nextLength <= MAX_ACTIVE_PROCESS_OUTPUT_CHARS) {
+        return {
+            output: output + chunk,
+            droppedChars,
+        };
+    }
+    const nextDroppedChars = droppedChars + nextLength - MAX_ACTIVE_PROCESS_OUTPUT_CHARS;
+    if (chunk.length >= MAX_ACTIVE_PROCESS_OUTPUT_CHARS) {
+        return {
+            output: chunk.slice(-MAX_ACTIVE_PROCESS_OUTPUT_CHARS),
+            droppedChars: nextDroppedChars,
+        };
+    }
+    const existingCharsToKeep = MAX_ACTIVE_PROCESS_OUTPUT_CHARS - chunk.length;
+    return {
+        output: output.slice(-existingCharsToKeep) + chunk,
+        droppedChars: nextDroppedChars,
+    };
+}
+function consumeActiveProcessOutput(activeProcess) {
+    const output = withDroppedOutputPrefix(activeProcess.output, activeProcess.droppedOutputChars);
+    const stdout = withDroppedOutputPrefix(activeProcess.stdout, activeProcess.droppedStdoutChars);
+    const stderr = withDroppedOutputPrefix(activeProcess.stderr, activeProcess.droppedStderrChars);
+    activeProcess.output = '';
+    activeProcess.stdout = '';
+    activeProcess.stderr = '';
+    activeProcess.droppedOutputChars = 0;
+    activeProcess.droppedStdoutChars = 0;
+    activeProcess.droppedStderrChars = 0;
+    return { output, stdout, stderr };
+}
+function withDroppedOutputPrefix(output, droppedChars) {
+    if (droppedChars === 0) {
+        return output;
+    }
+    return `[...${droppedChars} characters truncated from process output...]\n${output}`;
+}
+async function waitForProcessOrTimeout(activeProcess, timeoutMs) {
+    if (activeProcess.done) {
+        return;
+    }
+    await Promise.race([
+        activeProcess.donePromise,
+        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+    if (activeProcess.done) {
+        await activeProcess.outputClosedPromise;
+    }
+}
+function signalToExitCode(signal) {
+    if (signal === 'SIGINT') {
+        return 130;
+    }
+    return 1;
+}
+//# sourceMappingURL=unixLocal.mjs.map