@openai/agents-core/dist/sandbox/session.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 { SandboxArchiveLimits } from './client';
import type { Entry } from './entries';
import type { Manifest } from './manifest';
import type { Snapshot } from './snapshot';
export declare const SANDBOX_SESSION_STATE_VERSION: 6;
export declare const SUPPORTED_SANDBOX_SESSION_STATE_VERSIONS: readonly [1, 2, 3, 4, 5, 6];
export type SandboxSessionStateVersion = (typeof SUPPORTED_SANDBOX_SESSION_STATE_VERSIONS)[number];
export type ExposedPortScheme = 'http' | 'ws';
export type ExposedPortEndpoint = {
    host: string;
    port: number;
    tls?: boolean;
    query?: string;
    protocol?: string;
    url?: string;
    [key: string]: unknown;
};
export type SandboxSessionStateEnvelope = {
    version: SandboxSessionStateVersion;
    backendId: string;
    environmentPreparation?: 'client';
    manifest: Record<string, unknown>;
    snapshot?: Snapshot | null;
    snapshotFingerprint?: string | null;
    snapshotFingerprintVersion?: string | null;
    workspaceReady: boolean;
    exposedPorts?: Record<string, ExposedPortEndpoint>;
    providerState: Record<string, unknown>;
};
export interface SandboxSessionState {
    manifest: Manifest;
    snapshot?: Snapshot | null;
    snapshotFingerprint?: string | null;
    snapshotFingerprintVersion?: string | null;
    workspaceReady?: boolean;
    environment?: Record<string, string>;
    exposedPorts?: Record<string, ExposedPortEndpoint>;
    [key: string]: unknown;
}
export type ExecCommandArgs = {
    cmd: string;
    workdir?: string;
    shell?: string;
    login?: boolean;
    tty?: boolean;
    yieldTimeMs?: number;
    maxOutputTokens?: number;
    runAs?: string;
};
export type SandboxExecResult = {
    output: string;
    stdout: string;
    stderr: string;
    wallTimeSeconds: number;
    exitCode?: number | null;
    sessionId?: number;
    originalTokenCount?: number;
};
export type WriteStdinArgs = {
    sessionId: number;
    chars?: string;
    yieldTimeMs?: number;
    maxOutputTokens?: number;
};
export type ViewImageArgs = {
    path: string;
    runAs?: string;
};
export type ReadFileArgs = {
    path: string;
    runAs?: string;
    maxBytes?: number;
};
export type ListDirectoryArgs = {
    path: string;
    runAs?: string;
};
export type SandboxDirectoryEntry = {
    name: string;
    path: string;
    type: 'file' | 'dir' | 'other';
};
export type MaterializeEntryArgs = {
    path: string;
    entry: Entry;
    runAs?: string;
};
export type WorkspaceArchiveData = string | ArrayBuffer | Uint8Array;
export type WorkspaceArchiveOptions = {
    archiveLimits?: SandboxArchiveLimits | null;
};
export type SandboxSessionLifecycleOptions = {
    reason?: string;
    [key: string]: unknown;
};
export type SandboxPreStopHook = () => Promise<void> | void;
export declare function normalizeExposedPort(port: number): number;
export declare function exposedPortStateKey(port: number): string;
export declare function recordExposedPortEndpoint(state: SandboxSessionState, endpoint: ExposedPortEndpoint, keyPort?: number): ExposedPortEndpoint;
export declare function getRecordedExposedPortEndpoint(state: SandboxSessionState, port: number): ExposedPortEndpoint | undefined;
export declare function urlForExposedPort(endpoint: ExposedPortEndpoint, scheme: ExposedPortScheme): string;
export interface SandboxSession<TState extends SandboxSessionState = SandboxSessionState> {
    state: TState;
    start?(options?: SandboxSessionLifecycleOptions): Promise<void>;
    running?(): Promise<boolean>;
    registerPreStopHook?(hook: SandboxPreStopHook): (() => void) | void;
    runPreStopHooks?(): Promise<void>;
    preStop?(options?: SandboxSessionLifecycleOptions): Promise<void>;
    stop?(options?: SandboxSessionLifecycleOptions): Promise<void>;
    shutdown?(options?: SandboxSessionLifecycleOptions): Promise<void>;
    delete?(options?: SandboxSessionLifecycleOptions): Promise<void>;
    createEditor?(runAs?: string): Editor;
    exec?(args: ExecCommandArgs): Promise<SandboxExecResult>;
    execCommand?(args: ExecCommandArgs): Promise<string>;
    writeStdin?(args: WriteStdinArgs): Promise<string>;
    viewImage?(args: ViewImageArgs): Promise<ToolOutputImage>;
    readFile?(args: ReadFileArgs): Promise<string | Uint8Array>;
    listDir?(args: ListDirectoryArgs): Promise<SandboxDirectoryEntry[]>;
    pathExists?(path: string, runAs?: string): Promise<boolean>;
    directoryExists?(path: string, runAs?: string): Promise<boolean>;
    materializeEntry?(args: MaterializeEntryArgs): Promise<void>;
    applyManifest?(manifest: Manifest, runAs?: string): Promise<void>;
    persistWorkspace?(): Promise<Uint8Array>;
    hydrateWorkspace?(data: WorkspaceArchiveData, options?: WorkspaceArchiveOptions): Promise<void>;
    setArchiveLimits?(limits?: SandboxArchiveLimits | null): void;
    resolveExposedPort?(port: number): Promise<ExposedPortEndpoint>;
    supportsPty?(): boolean;
    close?(): Promise<void>;
}
export type SandboxSessionLike<TState extends SandboxSessionState = SandboxSessionState> = SandboxSession<TState>;