import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type * as Sandbox from "./Sandbox.ts";
/**
* The client half of the sandbox agent: the wire protocol a runtime speaks to
* a program that serves `alchemy/SandboxAgent`, and the `alchemy/Sandbox`
* handle built on it.
*
* A host bundle imports only this module. The server half
* (`alchemy/SandboxAgent`) spawns processes and reads files, so it stays in
* the sandbox's own bundle.
*/
/** Environment variable that carries a sandbox's bearer token and turns its agent on. */
export declare const SANDBOX_TOKEN_ENV = "ALCHEMY_SANDBOX_TOKEN";
/** Environment variable that carries a sandbox's idle timeout, in milliseconds. */
export declare const SANDBOX_IDLE_TIMEOUT_ENV = "ALCHEMY_SANDBOX_IDLE_TIMEOUT";
/**
* The port the agent listens on when it is added to an image that has no
* program of its own. A program that serves the agent itself answers on the
* program's port instead.
*/
export declare const SANDBOX_AGENT_PORT = 2468;
/** Environment variable that carries the port of an agent added to an image. */
export declare const SANDBOX_PORT_ENV = "ALCHEMY_SANDBOX_PORT";
declare const SandboxProcessNotFound_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
readonly _tag: "SandboxProcessNotFound";
} & Readonly;
/** No process or terminal has this id. It may have exited long ago. */
export declare class SandboxProcessNotFound extends SandboxProcessNotFound_base<{
readonly id: string;
readonly message: string;
}> {
}
declare const SandboxExecTimedOut_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
readonly _tag: "SandboxExecTimedOut";
} & Readonly;
/** `exec` ran longer than its `timeout` and was killed. */
export declare class SandboxExecTimedOut extends SandboxExecTimedOut_base<{
readonly timeoutMs: number;
readonly message: string;
}> {
}
declare const SandboxFileError_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
readonly _tag: "SandboxFileError";
} & Readonly;
/** A file operation failed. `reason` is the system error (`NotFound`, `PermissionDenied`, …). */
export declare class SandboxFileError extends SandboxFileError_base<{
readonly path: string;
readonly reason: string;
readonly message: string;
}> {
}
declare const SandboxPtyUnavailable_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
readonly _tag: "SandboxPtyUnavailable";
} & Readonly;
/** The sandbox can't open a terminal. */
export declare class SandboxPtyUnavailable extends SandboxPtyUnavailable_base<{
readonly message: string;
}> {
}
declare const SandboxSpawnError_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
readonly _tag: "SandboxSpawnError";
} & Readonly;
/** The command could not be started, or its output could not be read. */
export declare class SandboxSpawnError extends SandboxSpawnError_base<{
readonly message: string;
}> {
}
declare const SandboxAgentError_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
readonly _tag: "SandboxAgentError";
} & Readonly;
/** The agent could not be reached, or answered with something that is not its protocol. */
export declare class SandboxAgentError extends SandboxAgentError_base<{
readonly method?: string;
readonly status?: number;
readonly message: string;
}> {
}
/** Every error a sandbox agent call can fail with. */
export type SandboxError = SandboxProcessNotFound | SandboxExecTimedOut | SandboxFileError | SandboxPtyUnavailable | SandboxSpawnError | SandboxAgentError;
/**
* Turns whatever a sandbox agent call failed with into a {@link SandboxError}:
* an error the agent sent, a failed HTTP call, or an undecodable response.
*/
export declare const reviveSandboxError: (error: unknown) => SandboxError;
/** Encodes bytes for a JSON argument or result. */
export declare const toBase64: (bytes: Uint8Array) => string;
/** Decodes bytes from a JSON argument or result. */
export declare const fromBase64: (b64: string) => Uint8Array;
/** `ExecOptions` as JSON: the timeout in milliseconds and stdin as base64. */
export interface WireExecOptions {
readonly cwd?: string;
readonly env?: Readonly>;
readonly timeoutMs?: number;
readonly stdin?: string;
}
/** A piece of process output as JSON. */
export interface WireProcessOutput {
readonly fd: "stdout" | "stderr";
readonly b64: string;
}
/** The signals `kill` sends. */
export type WireSignal = "SIGTERM" | "SIGKILL";
/**
* The methods a sandbox agent serves over alchemy's RPC, next to the
* program's own. Their names start with `sandbox.` so they never collide with
* a program's methods. Bytes travel as base64 strings.
*/
export interface SandboxAgentRpc {
"sandbox.ping": () => Effect.Effect<{
readonly ok: true;
}, unknown>;
"sandbox.exec": (command: Sandbox.Command, options?: WireExecOptions) => Effect.Effect;
"sandbox.start": (command: Sandbox.Command, options?: WireExecOptions) => Effect.Effect<{
readonly id: string;
}, unknown>;
"sandbox.output": (id: string) => Effect.Effect, unknown>;
"sandbox.write": (id: string, b64: string) => Effect.Effect;
"sandbox.kill": (id: string, signal: WireSignal) => Effect.Effect;
"sandbox.wait": (id: string) => Effect.Effect<{
readonly exitCode: number;
}, unknown>;
"sandbox.files.read": (path: string) => Effect.Effect;
"sandbox.files.readText": (path: string) => Effect.Effect;
"sandbox.files.write": (path: string, b64: string) => Effect.Effect;
"sandbox.files.list": (path: string) => Effect.Effect, unknown>;
"sandbox.files.stat": (path: string) => Effect.Effect;
"sandbox.files.remove": (path: string) => Effect.Effect;
"sandbox.files.makeDir": (path: string) => Effect.Effect;
"sandbox.pty.open": (options: Sandbox.PtyOptions) => Effect.Effect<{
readonly id: string;
}, unknown>;
"sandbox.pty.output": (id: string) => Effect.Effect, unknown>;
"sandbox.pty.write": (id: string, b64: string) => Effect.Effect;
"sandbox.pty.resize": (id: string, cols: number, rows: number) => Effect.Effect;
}
/**
* What every sandbox that runs the agent can do: run a command, stream a
* process, use files, open a terminal. A provider adds what its platform has
* for a sandbox (ports, lifecycle).
*/
export interface SandboxAgentClient extends Sandbox.SandboxExec, Sandbox.SandboxProcesses, Sandbox.SandboxFiles, Sandbox.SandboxPty {
/** Re-attaches to a process started earlier, by its id. */
attach(id: string): Sandbox.Process;
/** Succeeds once the agent answers. */
readonly ping: Effect.Effect;
}
/**
* Builds the sandbox handle from an RPC stub that reaches the agent (see
* `makeFetchRpcStub` in `alchemy/Rpc`).
*/
export declare const makeSandboxAgentClient: (stub: SandboxAgentRpc) => SandboxAgentClient;
export {};
//# sourceMappingURL=SandboxAgentClient.d.ts.map