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

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

import { type Entry, type Mount, type TypedMount } from './entries';
import { type SandboxPathGrant, type SandboxPathGrantInit } from './pathGrants';
import { type SandboxGroup, type SandboxGroupInit, type SandboxUser, type SandboxUserInit } from './users';
export type EnvResolver = () => string | Promise<string>;
export type EnvValue = {
    value: string;
    resolve?: EnvResolver;
    ephemeral?: boolean;
    description?: string;
};
export type SerializedEnvValueReference = {
    type: string;
    [key: string]: unknown;
};
export type EnvEntry = string | EnvResolver | EnvValue | Environment | SerializedEnvValueReference;
export type RenderManifestDescriptionOptions = {
    depth?: number | null;
    maxLines?: number;
    maxChars?: number;
};
export type ManifestEntries = Record<string, Entry>;
export type ManifestEnvironment = Record<string, EnvEntry>;
type ManifestEnvironmentValues<TEnvironment extends ManifestEnvironment> = {
    [Key in keyof TEnvironment]: Environment;
};
export declare class Environment {
    readonly value: string;
    readonly resolver?: EnvResolver;
    readonly ephemeral: boolean;
    readonly description?: string;
    constructor(entry: EnvEntry);
    resolve(): Promise<string>;
    init(): EnvValue;
    normalized(): EnvValue;
}
export type ManifestInit<TEntries extends ManifestEntries = ManifestEntries, TEnvironment extends ManifestEnvironment = ManifestEnvironment> = {
    version?: number;
    root?: string;
    entries?: TEntries;
    environment?: TEnvironment;
    users?: SandboxUserInit[];
    groups?: SandboxGroupInit[];
    extraPathGrants?: SandboxPathGrantInit[];
    remoteMountCommandAllowlist?: string[];
};
type IterEntry = {
    logicalPath: string;
    absolutePath: string;
    entry: Entry;
    depth: number;
};
export type ManifestMountTarget = IterEntry & {
    entry: Mount | TypedMount;
    mountPath: string;
};
type RenderedManifestDescription = {
    text: string;
    renderedPaths: number;
    totalPaths: number;
};
export declare class Manifest<TEntries extends ManifestEntries = ManifestEntries, TEnvironment extends ManifestEnvironment = ManifestEnvironment> {
    readonly version: number;
    readonly root: string;
    readonly entries: TEntries;
    readonly environment: ManifestEnvironmentValues<TEnvironment>;
    readonly users: SandboxUser[];
    readonly groups: SandboxGroup[];
    readonly extraPathGrants: SandboxPathGrant[];
    readonly remoteMountCommandAllowlist: string[];
    constructor(init?: ManifestInit<TEntries, TEnvironment>);
    /**
     * Returns a trusted manifest that acknowledges exposure of mount-scoped
     * credentials for exact in-container mount paths.
     *
     * This application-side policy is runtime-only. It is not accepted from
     * manifest init objects and is never serialized into sandbox session state.
     */
    withInContainerMountCredentialExposureAcknowledged(...mountPaths: string[]): Manifest<TEntries, TEnvironment>;
    /**
     * Returns a trusted manifest that acknowledges exposure of broad credential
     * authority for exact in-container mount paths.
     *
     * Broad authority includes ambient credentials, workload or managed
     * identity, and external credential files. This application-side policy is
     * runtime-only. It is not accepted from manifest init objects and is never
     * serialized into sandbox session state.
     */
    withInContainerMountBroadCredentialExposureAcknowledged(...mountPaths: string[]): Manifest<TEntries, TEnvironment>;
    validatedEntries(): Record<string, Entry>;
    iterEntries(): Generator<IterEntry>;
    ephemeralEntryPaths(): Set<string>;
    /**
     * Returns mount targets in most-specific-first order for path resolution.
     */
    mountTargets(): ManifestMountTarget[];
    /**
     * Returns mount targets in parent-first order for filesystem materializers.
     */
    mountTargetsForMaterialization(): ManifestMountTarget[];
    ephemeralMountTargets(): ManifestMountTarget[];
    ephemeralPersistencePaths(): Set<string>;
    resolveEnvironment(overrides?: Record<string, string>): Promise<Record<string, string>>;
    describe(depth?: number): string;
}
export type EnvValueReferenceClass<TReference extends EnvValueReference = EnvValueReference> = {
    readonly type: string;
    readonly prototype: TReference;
};
export type EnvValueReferenceParser<TReference extends EnvValueReference = EnvValueReference> = (payload: Readonly<Record<string, unknown>>) => TReference;
/**
 * A JSON-serializable reference to a runtime sandbox environment value.
 *
 * Subclasses must serialize only non-secret lookup metadata. Register each
 * subclass in every process that reconstructs manifests before parsing JSON.
 */
export declare abstract class EnvValueReference extends Environment {
    static readonly type: string;
    protected constructor(options?: {
        ephemeral?: boolean;
        description?: string;
    });
    get type(): string;
    abstract serialize(): Record<string, unknown>;
    abstract resolve(): Promise<string>;
    init(): EnvValueReference;
    normalized(): never;
    toJSON(): SerializedEnvValueReference;
}
/**
 * Registers one environment reference subtype for JSON reconstruction.
 *
 * The parser receives persisted data and must validate it before constructing
 * a reference, including allowlisting any secret-store lookup keys.
 *
 * Returns an unregister callback for test isolation and controlled module
 * lifecycle cleanup. Conflicting registrations fail instead of replacing the
 * active parser.
 */
export declare function registerEnvValueReference<TReference extends EnvValueReference>(referenceClass: EnvValueReferenceClass<TReference>, parse: EnvValueReferenceParser<TReference>): () => void;
export declare function serializeEnvValueReference(reference: EnvValueReference): SerializedEnvValueReference;
export declare function isEnvValueReference(value: unknown): value is EnvValueReference;
export declare function isSerializedEnvValueReference(value: unknown): value is SerializedEnvValueReference;
export type ManifestInput<TEntries extends ManifestEntries = ManifestEntries, TEnvironment extends ManifestEnvironment = ManifestEnvironment> = Manifest<TEntries, TEnvironment> | ManifestInit<TEntries, TEnvironment>;
export declare const MOUNT_CREDENTIAL_EXPOSURE_POLICY_KEYS: readonly ["in_container_mount_credential_exposure_allowed_paths", "_in_container_mount_credential_exposure_allowed_paths", "inContainerMountCredentialExposureAllowedPaths", "_inContainerMountCredentialExposureAllowedPaths", "in_container_mount_credential_exposure_acknowledged_paths", "_in_container_mount_credential_exposure_acknowledged_paths", "inContainerMountCredentialExposureAcknowledgedPaths", "_inContainerMountCredentialExposureAcknowledgedPaths", "in_container_mount_broad_credential_exposure_acknowledged_paths", "_in_container_mount_broad_credential_exposure_acknowledged_paths", "inContainerMountBroadCredentialExposureAcknowledgedPaths", "_inContainerMountBroadCredentialExposureAcknowledgedPaths"];
export type InContainerMountCredentialExposureAuthority = 'mount_scoped' | 'broad';
export declare function manifestAcknowledgesInContainerMountCredentialExposure(manifest: Manifest, mountPath: string, authority: InContainerMountCredentialExposureAuthority): boolean;
export declare function copyManifestMountCredentialExposurePolicy(target: Manifest, ...sources: Manifest[]): void;
export declare function replaceManifestMountCredentialExposurePolicy(target: Manifest, source: Manifest): void;
export declare function cloneManifest(manifest: ManifestInput): Manifest;
export declare function normalizeRelativePath(path: string): string;
export declare function renderManifestDescription(manifest: Manifest, options?: RenderManifestDescriptionOptions): RenderedManifestDescription;
export {};