@openai/agents-core/dist/sandbox/sandboxes/unixLocal.d.ts

The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.

import type { Editor } from '../../editor';
import type { ToolOutputImage } from '../../tool';
import { type ChildProcessWithoutNullStreams } from 'node:child_process';
import type { SandboxClient, SandboxClientOptions, SandboxClientCreateArgs, SandboxArchiveLimits, SandboxClientResumeOptions, SandboxConcurrencyLimits } from '../client';
import { type ExposedPortEndpoint, type ExecCommandArgs, type ListDirectoryArgs, type MaterializeEntryArgs, type ReadFileArgs, type SandboxDirectoryEntry, type SandboxExecResult, type SandboxSession, type SandboxSessionState, type ViewImageArgs, type WriteStdinArgs, type WorkspaceArchiveOptions } from '../session';
import { Manifest } from '../manifest';
import { type ResolveSandboxPathOptions } from '../workspacePaths';
import type { LocalSandboxSnapshot, LocalSandboxSnapshotSpec } from './types';
import { UnixLocalFiles, preparedFileIO, type LocalFileIOProtection } from './shared/unixLocalFiles';
export type { LocalFileIOProtection } from './shared/unixLocalFiles';
export interface UnixLocalSandboxClientOptions extends SandboxClientOptions {
    /**
     * Host file protection. Requires trusted Python 3 with descriptor-relative
     * filesystem support. auto is an alias for required; off is rejected.
     * Unavailable protection fails during preparation, before workspace setup.
     * This does not confine shell commands.
     */
    fileIOProtection?: LocalFileIOProtection;
    workspaceBaseDir?: string;
    snapshot?: LocalSandboxSnapshotSpec;
    defaultShell?: string;
    exposedPorts?: number[];
    concurrencyLimits?: SandboxConcurrencyLimits;
    archiveLimits?: SandboxArchiveLimits | null;
}
export interface UnixLocalSandboxSessionState extends SandboxSessionState {
    workspaceRootPath: string;
    workspaceRootOwned: boolean;
    environment: Record<string, string>;
    snapshotSpec?: LocalSandboxSnapshotSpec | null;
    snapshot?: LocalSandboxSnapshot | null;
    snapshotFingerprint?: string | null;
    snapshotFingerprintVersion?: string | null;
    configuredExposedPorts?: number[];
}
type UnixRunAsIdentity = {
    username: string;
    uid: number;
    gid: number;
    isCurrentUser: boolean;
};
export declare class UnixLocalSandboxSession<TState extends UnixLocalSandboxSessionState = UnixLocalSandboxSessionState> implements SandboxSession<TState> {
    readonly state: TState;
    protected readonly defaultShell?: string;
    protected archiveLimits?: SandboxArchiveLimits | null;
    private readonly activeProcesses;
    private nextSessionId;
    private closePromise?;
    private stopPromise?;
    private fileOperationGeneration;
    private readonly hostFiles;
    private get files();
    private readonly filesystemRoots;
    constructor(args: {
        state: TState;
        defaultShell?: string;
        archiveLimits?: SandboxArchiveLimits | null;
        fileIOProtection?: LocalFileIOProtection;
        [preparedFileIO]?: UnixLocalFiles | null;
    });
    /** Selected once at creation or resume; Docker subclasses use the container backend. */
    get fileIOBackend(): 'python' | 'docker';
    setArchiveLimits(limits?: SandboxArchiveLimits | null): void;
    createEditor(runAs?: string): Editor;
    supportsPty(): boolean;
    resolveExposedPort(port: number): Promise<ExposedPortEndpoint>;
    execCommand(args: ExecCommandArgs): Promise<string>;
    exec(args: ExecCommandArgs): Promise<SandboxExecResult>;
    writeStdin(args: WriteStdinArgs): Promise<string>;
    viewImage(args: ViewImageArgs): Promise<ToolOutputImage>;
    pathExists(path: string, runAs?: string): Promise<boolean>;
    directoryExists(path: string, runAs?: string): Promise<boolean>;
    readFile(args: ReadFileArgs): Promise<Uint8Array>;
    listDir(args: ListDirectoryArgs): Promise<SandboxDirectoryEntry[]>;
    materializeEntry(args: MaterializeEntryArgs): Promise<void>;
    private materializeEntryExclusive;
    applyManifest(manifest: Manifest, runAs?: string): Promise<void>;
    private applyManifestExclusive;
    persistWorkspace(): Promise<Uint8Array>;
    hydrateWorkspace(data: string | ArrayBuffer | Uint8Array, options?: WorkspaceArchiveOptions): Promise<void>;
    stop(): Promise<void>;
    private stopResources;
    shutdown(): Promise<void>;
    delete(): Promise<void>;
    close(): Promise<void>;
    private closeResources;
    private stopActiveProcesses;
    resolveSandboxPath(path?: string, options?: ResolveSandboxPathOptions): string;
    private resolveFilesystemPath;
    private resolveHostPath;
    protected resolveCommandWorkdir(path?: string): string;
    protected assertSessionUsable(): void;
    private captureFilesystemRoots;
    private filesystemRoot;
    private applyFileOperation;
    private resolveSandboxPathTarget;
    private resolveLocalBindMountPath;
    protected resolveLogicalPath(path?: string): string;
    protected spawnShellCommand(command: string, args: {
        cwd: string;
        logicalCwd: string;
        shell?: string;
        login: boolean;
        runAs?: string;
        tty?: boolean;
    }): Promise<ChildProcessWithoutNullStreams>;
    protected translateCommandInput(command: string): string;
    protected translateCommandOutput(output: string): string;
    protected materializeRestoredWorkspaceMounts(): Promise<void>;
    protected logicalWorkdirForPath(path?: string): string;
    protected resolveCommandRunAs(runAs?: string): Promise<UnixRunAsIdentity | undefined>;
    resolveFilesystemRunAs(runAs?: string): Promise<UnixRunAsIdentity | undefined>;
    protected resolveRunAsIdentity(runAs?: string): Promise<UnixRunAsIdentity | undefined>;
    private trackChildProcess;
    private allocateProcessId;
}
/**
 * Local sandbox client for Unix hosts.
 * Host file operations require trusted Python 3 with descriptor-relative
 * filesystem support. Set the host OPENAI_AGENTS_PYTHON to an absolute trusted
 * executable to override discovery. Unavailable protection and fileIOProtection:
 * 'off' fail during preparation. Resumed sessions use current client configuration.
 * File tools honor runAs using host permissions. Editor updates replace files,
 * require writable parent directories, and leave other hardlinks unchanged.
 */
export declare class UnixLocalSandboxClient implements SandboxClient<UnixLocalSandboxClientOptions, UnixLocalSandboxSessionState> {
    readonly backendId = "unix_local";
    readonly supportsDefaultOptions = true;
    private readonly options;
    constructor(options?: UnixLocalSandboxClientOptions);
    create(args?: SandboxClientCreateArgs<UnixLocalSandboxClientOptions> | Manifest, manifestOptions?: UnixLocalSandboxClientOptions): Promise<UnixLocalSandboxSession>;
    resume(state: UnixLocalSandboxSessionState, options?: SandboxClientResumeOptions<UnixLocalSandboxClientOptions>): Promise<UnixLocalSandboxSession>;
    serializeSessionState(state: UnixLocalSandboxSessionState): Promise<Record<string, unknown>>;
    deserializeSessionState(state: Record<string, unknown>): Promise<UnixLocalSandboxSessionState>;
    private restoreIfNeeded;
}