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