eve/dist/src/execution/sandbox/bindings/docker-cli.d.ts

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

/**
 * Buffered result of one `docker …` invocation.
 *
 * `stdout` decodes the raw bytes as UTF-8 for the common text case;
 * `stdoutBytes` preserves the exact bytes for binary payloads (for
 * example reading a file out of a container via `cat`).
 */
export interface DockerCommandResult {
    readonly exitCode: number;
    readonly stderr: string;
    readonly stdout: string;
    readonly stdoutBytes: Buffer;
}
/**
 * Options for one buffered {@link DockerCli.run} invocation.
 */
export interface DockerRunOptions {
    readonly signal?: AbortSignal;
    readonly stdin?: Uint8Array;
}
/**
 * Handle to one streaming `docker …` invocation (e.g. `docker exec`).
 * Mirrors the AI SDK `Experimental_SandboxProcess` stream/wait/kill
 * shape so the sandbox engine can adapt it directly.
 */
export interface DockerProcess {
    readonly stdout: ReadableStream<Uint8Array>;
    readonly stderr: ReadableStream<Uint8Array>;
    wait(): Promise<{
        exitCode: number;
    }>;
    kill(): Promise<void>;
}
/**
 * Minimal Docker CLI driver the local sandbox engine runs on. A thin
 * subprocess wrapper in production; injectable so engine logic is unit
 * testable without a Docker daemon.
 */
export interface DockerCli {
    /** Runs `docker <args>` to completion, buffering stdout/stderr. */
    run(args: readonly string[], options?: DockerRunOptions): Promise<DockerCommandResult>;
    /** Spawns `docker <args>` with streaming stdout/stderr. */
    stream(args: readonly string[], options?: {
        readonly signal?: AbortSignal;
    }): DockerProcess;
}
/**
 * Raised when the `docker` executable cannot be spawned at all (not
 * installed or not on `PATH`).
 */
export declare class DockerUnavailableError extends Error {
    /** Structured remediation, surfaced by the semantic-error catalog. */
    readonly hint: string;
    constructor(cause?: unknown);
}
/**
 * Raised when the `docker` CLI exists but the daemon is not reachable.
 */
export declare class DockerDaemonUnavailableError extends Error {
    /** Structured remediation, surfaced by the semantic-error catalog. */
    readonly hint: string;
    constructor(detail: string);
}
/**
 * Verifies the Docker daemon answers before the engine performs its
 * first real operation, converting CLI/daemon failures into actionable
 * errors instead of letting individual commands fail obscurely.
 */
export declare function assertDockerDaemonAvailable(cli: DockerCli): Promise<void>;
/**
 * Synchronously probes whether a Docker daemon is reachable, for
 * `defaultSandbox()`'s availability chain. The result is cached for the
 * process lifetime: backend selection must be stable, and the probe
 * costs a subprocess round-trip.
 */
export declare function isDockerDaemonAvailableSync(): boolean;
/**
 * Creates the production {@link DockerCli} that shells out to the
 * `docker` executable (override the binary with `EVE_DOCKER_PATH`).
 */
export declare function createDockerCli(): DockerCli;