@openai/agents-core/dist/sandbox/client.d.ts

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

import { Manifest, type ManifestInput } from './manifest';
import type { SandboxSessionLike, SandboxSessionState } from './session';
import type { SnapshotSpec } from './snapshot';
export type SandboxConcurrencyLimits = {
    manifestEntries?: number;
    localDirFiles?: number;
};
export type SandboxArchiveLimits = {
    maxInputBytes?: number | null;
    maxExtractedBytes?: number | null;
    maxMembers?: number | null;
};
export type ResolvedSandboxArchiveLimits = {
    maxInputBytes: number | null;
    maxExtractedBytes: number | null;
    maxMembers: number | null;
};
export declare const DEFAULT_SANDBOX_ARCHIVE_LIMITS: ResolvedSandboxArchiveLimits;
export type SandboxClientOptions = Record<string, unknown>;
export type SandboxClientCreateArgs<TOptions extends SandboxClientOptions = SandboxClientOptions> = {
    snapshot?: SnapshotSpec;
    manifest?: ManifestInput;
    options?: TOptions;
    concurrencyLimits?: SandboxConcurrencyLimits;
    archiveLimits?: SandboxArchiveLimits | null;
};
export type NormalizedSandboxClientCreateArgs<TOptions extends SandboxClientOptions = SandboxClientOptions> = {
    snapshot?: SnapshotSpec;
    manifest: Manifest;
    options?: TOptions;
    concurrencyLimits?: SandboxConcurrencyLimits;
    archiveLimits?: SandboxArchiveLimits | null;
};
export type SandboxClientResumeOptions<TOptions extends SandboxClientOptions = SandboxClientOptions> = {
    archiveLimits?: SandboxArchiveLimits | null;
    clientOptions?: TOptions;
    /**
     * Current trusted manifest for clients that prepare environment values in
     * their own execution context. Treat this manifest as authoritative for
     * environment preparation: persisted provider state is untrusted input and
     * must not override it. The client must not return resolved values through
     * runner-visible or serialized session state. After a successful resume,
     * the runtime binds its environment and SDK security policies to the
     * provider-returned manifest for SDK-side policy and tool preparation while
     * preserving provider-owned structural fields.
     */
    trustedManifest?: Manifest;
};
export type SandboxSessionResumeValidationInput<TSessionState extends SandboxSessionState = SandboxSessionState> = {
    source: 'explicit';
    state: TSessionState;
} | {
    source: 'runState';
    state: Record<string, unknown>;
};
export type SandboxClientCreate<TOptions extends SandboxClientOptions = SandboxClientOptions, TSessionState extends SandboxSessionState = SandboxSessionState> = {
    (args?: SandboxClientCreateArgs<TOptions>): Promise<SandboxSessionLike<TSessionState>>;
    (manifest: Manifest, options?: TOptions): Promise<SandboxSessionLike<TSessionState>>;
};
export type SandboxSessionSerializationOptions = {
    preserveOwnedSession?: boolean;
    reuseLiveSession?: boolean;
    /**
     * The runtime will close the owned session after serialization.
     */
    willCloseAfterSerialize?: boolean;
};
export type SandboxPreservedSessionReuseOptions<TOptions extends SandboxClientOptions = SandboxClientOptions> = {
    clientOptions?: TOptions;
    /**
     * Revalidate the entries materialized when the backend was created before
     * reusing a same-process preserved session.
     */
    revalidateManifestEntries?: boolean;
    /**
     * Current trusted manifest for environment preparation. Treat this manifest
     * as authoritative; the preserved provider state must not override it. Once
     * reuse is accepted, the runtime binds its environment and SDK security
     * policies to the provider-returned manifest while preserving provider-owned
     * structural fields.
     */
    trustedManifest?: Manifest;
};
export interface SandboxClient<TOptions extends SandboxClientOptions = SandboxClientOptions, TSessionState extends SandboxSessionState = SandboxSessionState> {
    backendId: string;
    supportsDefaultOptions?: boolean;
    /**
     * Delegates manifest environment preparation to the client execution
     * context. The runner preserves unresolved environment references; the
     * client must resolve them and validate environment-backed credentials
     * before provider side effects.
     *
     * Resolved values must never be returned through runner-visible session
     * state or serializeSessionState(). Same-process live reuse with unresolved
     * references requires canReusePreservedOwnedSession() so the client can
     * revalidate the session in its execution context.
     */
    environmentPreparation?: 'client';
    /**
     * Persisted provider state cannot authenticate enough backend authority to
     * reconnect safely, so only a same-process live session may be reused.
     */
    serializedSessionStateRequiresFreshCreation?: boolean;
    /**
     * Current trusted client options make serialized provider state unsafe to
     * resume. The runtime may replace a same-process live session when it can
     * authorize cleanup, but fails closed for untrusted cross-process state.
     */
    serializedSessionStateRequiresFreshCreationForOptions?(state: TSessionState, options?: SandboxClientResumeOptions<TOptions>): Promise<boolean> | boolean;
    /**
     * A rejected same-process live session cannot be resumed from its serialized
     * provider state and must be replaced through the normal create path.
     */
    preservedOwnedSessionReuseRejectionRequiresFreshCreation?: boolean;
    create?: SandboxClientCreate<TOptions, TSessionState>;
    delete?(state: TSessionState): Promise<void>;
    serializeSessionState?(state: TSessionState, options?: SandboxSessionSerializationOptions): Promise<Record<string, unknown>>;
    canPersistOwnedSessionState?(state: TSessionState): Promise<boolean> | boolean;
    canReusePreservedOwnedSession?(state: TSessionState, options?: SandboxPreservedSessionReuseOptions<TOptions>): Promise<boolean> | boolean;
    /**
     * Rebind trusted provider metadata after live reuse has been accepted and
     * the runtime has verified that the session state did not change.
     */
    rebindPreservedOwnedSessionState?(state: TSessionState, options?: SandboxPreservedSessionReuseOptions<TOptions>): void;
    deserializeSessionState?(state: Record<string, unknown>): Promise<TSessionState>;
    /**
     * Resolves the current trusted manifest to the provider-owned root used by
     * persisted session state before security-sensitive resume validation.
     */
    resolveTrustedManifestForResume?(manifest: Manifest, options?: TOptions): Manifest;
    /** Synchronously validates resume policy before environment materialization. */
    validateSessionStateForResume?(input: SandboxSessionResumeValidationInput<TSessionState>, options?: SandboxClientResumeOptions<TOptions>): void;
    resume?(state: TSessionState, options?: SandboxClientResumeOptions<TOptions>): Promise<SandboxSessionLike<TSessionState>>;
}
export type SandboxRunConfig<TOptions extends SandboxClientOptions = SandboxClientOptions, TSessionState extends SandboxSessionState = SandboxSessionState> = {
    client?: SandboxClient<TOptions, TSessionState>;
    options?: TOptions;
    session?: SandboxSessionLike<TSessionState>;
    sessionState?: TSessionState;
    manifest?: ManifestInput;
    snapshot?: SnapshotSpec;
    concurrencyLimits?: SandboxConcurrencyLimits;
    archiveLimits?: SandboxArchiveLimits | null;
    /**
     * Workspace-relative POSIX working directory for built-in sandbox tools in this run.
     */
    cwd?: string;
};
export declare function normalizeSandboxClientCreateArgs<TOptions extends SandboxClientOptions = SandboxClientOptions>(args?: SandboxClientCreateArgs<TOptions> | Manifest, manifestOptions?: TOptions, validationOptions?: {
    environmentPreparation?: 'client';
}): NormalizedSandboxClientCreateArgs<TOptions>;
export declare function resolveSandboxArchiveLimits(limits?: SandboxArchiveLimits | null): ResolvedSandboxArchiveLimits | null;
export declare function validateSandboxArchiveLimits(limits?: SandboxArchiveLimits | null): void;