eve
Version:
Filesystem-first framework for durable backend AI agents that run anywhere.
84 lines (83 loc) • 3.14 kB
TypeScript
/**
* 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 reachable Docker daemon runs Linux
* containers, for `defaultSandbox()`'s availability chain. eve's Docker
* sandbox image is Linux-only, so a Windows-container daemon is not a
* compatible default even though it answers the Docker CLI. The result is
* cached for the process lifetime: backend selection must be stable, and
* the probe costs a subprocess round-trip.
*/
export declare function isLinuxDockerDaemonAvailableSync(): 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;