eve/dist/src/shared/sandbox-provider.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import { type SandboxEnvironment, type SandboxSelectorContext } from "#shared/sandbox-environment.js";
import type { SandboxSession } from "#shared/sandbox-session.js";
export interface SandboxDeleteOptions {
    readonly abortSignal?: AbortSignal;
}
export interface SandboxProviderResourceFile {
    readonly content: string | Uint8Array;
    readonly relativePath: string;
}
export interface SandboxProviderResourceTree {
    readonly files: readonly SandboxProviderResourceFile[];
    readonly key: string;
    readonly mountPath: string;
    readonly targetPath: string;
}
export type SandboxProviderResourceSource = {
    readonly kind: "none";
} | {
    readonly key: string;
    readonly kind: "inline";
} | {
    readonly key: string;
    readonly kind: "materialized";
    readonly path: string;
};
export interface SandboxProviderResources {
    readonly skills?: SandboxProviderResourceTree;
    readonly source: SandboxProviderResourceSource;
    readonly workspace?: SandboxProviderResourceTree;
}
export declare function sandboxProviderResourceIdentity(resources: SandboxProviderResources): object;
export interface SandboxProviderTargetFile {
    readonly content: string | Uint8Array;
    readonly path: string;
}
export declare function providerResourceTargetFiles(resources: SandboxProviderResources): SandboxProviderTargetFile[];
export type SandboxPreparedArtifact = null | boolean | number | string | readonly SandboxPreparedArtifact[] | {
    readonly [key: string]: SandboxPreparedArtifact;
};
export declare function isSandboxPreparedArtifact(value: unknown): value is SandboxPreparedArtifact;
export declare function isSandboxPreparedArtifactRecord(artifact: unknown): artifact is {
    readonly [key: string]: SandboxPreparedArtifact;
};
export interface SandboxProviderFiles {
    list(): Promise<readonly string[]>;
    read(path: string): Promise<Uint8Array>;
    readText(path: string): Promise<string>;
}
export interface SandboxProviderHost {
    loadOptionalPackage<T>(input: {
        readonly autoInstall: boolean;
        readonly importModule: () => Promise<T>;
        readonly installPackageName?: string;
        readonly ignoredOptionalDependencies?: readonly string[];
        readonly missingMessage: string;
        readonly packageName: string;
    }): Promise<T>;
    resolveProjectPath(path: string): string;
}
export interface SandboxProviderPrepareContext {
    readonly files: SandboxProviderFiles;
    readonly host: SandboxProviderHost;
    readonly log?: (message: string) => void;
    readonly resources: SandboxProviderResources;
    readonly sourceRevision: string;
    readonly storagePath: string;
}
export interface SandboxProviderSessionContext {
    readonly host: SandboxProviderHost;
    readonly session: SandboxSelectorContext["session"];
    readonly storagePath: string;
}
export interface SandboxProviderHandle<Session extends SandboxSession = SandboxSession> {
    readonly sandbox: Session;
    onRuntimeShutdown(): Promise<void>;
    onSessionDelete(options?: SandboxDeleteOptions): Promise<void>;
    onSessionStop(): Promise<void>;
}
export interface SandboxProviderImplementation<OpenOptions extends object | undefined, PreparedArtifact extends SandboxPreparedArtifact, SessionState, Session extends SandboxSession = SandboxSession> {
    prepare(context: SandboxProviderPrepareContext): Promise<PreparedArtifact>;
    resume(context: SandboxProviderSessionContext, artifact: Readonly<PreparedArtifact>, state: Readonly<SessionState>): Promise<SandboxProviderHandle<Session>>;
    start(context: SandboxProviderSessionContext, options: Readonly<OpenOptions> | undefined, artifact: Readonly<PreparedArtifact>): Promise<{
        readonly handle: SandboxProviderHandle<Session>;
        readonly state: SessionState;
    }>;
}
type SandboxOptionArguments<Options extends object | undefined> = Options extends undefined ? [options?: undefined] : Record<never, never> extends Options ? [options?: Readonly<Options>] : [options: Readonly<Options>];
export type SandboxProviderDefinition<EnvironmentOptions extends object | undefined, OpenOptions extends object | undefined, PreparedArtifact extends SandboxPreparedArtifact, SessionState, Session extends SandboxSession> = {
    readonly name: string;
    readonly stateProtocolVersion?: number;
    environment(...args: SandboxOptionArguments<EnvironmentOptions>): SandboxProviderImplementation<OpenOptions, PreparedArtifact, SessionState, Session>;
};
export interface SandboxProvider<EnvironmentOptions extends object | undefined, OpenOptions extends object | undefined, Session extends SandboxSession> {
    readonly name: string;
    environment(...args: SandboxOptionArguments<EnvironmentOptions>): SandboxEnvironment<OpenOptions, Session>;
}
type ErasedSandboxProviderImplementation = SandboxProviderImplementation<object | undefined, SandboxPreparedArtifact, SandboxPreparedArtifact, SandboxSession>;
export interface SandboxProviderRuntime {
    readonly implementation: ErasedSandboxProviderImplementation;
    readonly providerName: string;
    readonly stateProtocolVersion: number;
}
export declare function defineSandboxProvider<EnvironmentOptions extends object | undefined = undefined, OpenOptions extends object | undefined = undefined, PreparedArtifact extends SandboxPreparedArtifact = SandboxPreparedArtifact, SessionState = SandboxPreparedArtifact, Session extends SandboxSession = SandboxSession>(definition: SandboxProviderDefinition<EnvironmentOptions, OpenOptions, PreparedArtifact, SessionState, Session>): SandboxProvider<EnvironmentOptions, OpenOptions, Session>;
export declare function createSandboxProviderResources(input: {
    readonly resourcesKey?: string;
    readonly resourcesPath?: string;
    readonly seedFiles?: readonly {
        readonly content: string | Uint8Array;
        readonly path: string;
    }[];
}): SandboxProviderResources;
export {};