@zenera/neo 1.1.0

package/dist/tools/sandbox.d.ts

@@ -0,0 +1,172 @@
+import { type AnyTool } from '../types.ts';
+/** Where the workspace appears inside the container. */
+export declare const SANDBOX_MOUNT = "/workspace";
+/** The image a project gets when it does not name one. */
+export declare const DEFAULT_SANDBOX_IMAGE = "docker.io/library/python:3.14-slim-bookworm";
+/** The family name config selects the whole set by: `tools: [sandbox:*]`. */
+export declare const SANDBOX_GROUP = "sandbox";
+/**
+ * Everything about a container that an author can state, and that two agents
+ * can therefore disagree about. Two specs that are equal share a container;
+ * two that differ get one each, because the identity of a container here *is*
+ * its configuration.
+ */
+export interface SandboxSpec {
+    /** the base image commands run in */
+    image?: string;
+    /** fractional cores, as podman's `--cpus` */
+    cpus?: number;
+    /** MiB, as podman's `--memory` */
+    memory?: number;
+    network?: SandboxNetwork;
+    /** where the workspace is mounted, and the default cwd */
+    workdir?: string;
+    /** default seconds a single command may take */
+    timeout?: number;
+    /** uid, name, or `uid:gid`; unset means the image's own user */
+    user?: string;
+    /** keep the container between sessions rather than removing it */
+    persist?: boolean;
+    /** environment inside the container — resolved values, never a passthrough */
+    env?: Record<string, string>;
+}
+export type SandboxNetwork = 'bridge' | 'none' | 'host';
+export interface SandboxMount {
+    /** absolute host path */
+    host: string;
+    /** absolute path inside the container */
+    at: string;
+    readOnly?: boolean;
+}
+export interface SandboxOptions extends SandboxSpec {
+    /** host directory mounted at `workdir` */
+    root: string;
+    /**
+     * Stable name for whatever owns this sandbox — a session id, typically.
+     * It prefixes the container name, so a crashed process leaves something a
+     * human can recognise rather than a hash.
+     */
+    key: string;
+    /** refuse to mount the workspace writable */
+    readOnly?: boolean;
+    /** extra bind mounts; the host side must already exist */
+    mounts?: readonly SandboxMount[];
+    /** the container engine binary */
+    engine?: string;
+    /** how processes are spawned — the seam tests replace */
+    exec?: Runner;
+}
+/**
+ * Per-agent overrides on top of one base spec. An agent that overrides nothing
+ * shares the base container; an agent that names a different image gets its
+ * own, and two agents that name the *same* different image share that.
+ */
+export interface SandboxPoolOptions extends SandboxOptions {
+    agents?: Record<string, SandboxSpec>;
+}
+/** A failure the caller can do something about — a missing engine, usually. */
+export declare class SandboxError extends Error {
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export interface ProcOptions {
+    /** written to stdin, which is then closed */
+    input?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** per stream */
+    maxBytes?: number;
+}
+export interface ProcResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+    timedOut: boolean;
+}
+export type Runner = (bin: string, args: readonly string[], opts?: ProcOptions) => Promise<ProcResult>;
+export declare const runProcess: Runner;
+interface Resolved extends Required<Omit<SandboxSpec, 'user'>> {
+    user?: string;
+    root: string;
+    key: string;
+    readOnly: boolean;
+    mounts: readonly SandboxMount[];
+    engine: string;
+}
+export interface ExecOptions {
+    cwd?: string;
+    /** seconds; the spec's default otherwise */
+    timeout?: number;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    exit_code: number;
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+    timed_out?: boolean;
+    duration_ms: number;
+}
+interface Job {
+    id: string;
+    command: string;
+    cwd: string;
+    startedAt: number;
+}
+/**
+ * The container, started when it is first needed and not before. A project
+ * whose agents never shell out never pays for an image pull, and a session
+ * that only ever asks a question never leaves anything behind.
+ */
+export declare class Sandbox {
+    #private;
+    readonly name: string;
+    readonly spec: Resolved;
+    constructor(opts: SandboxOptions);
+    /** Whether anything was actually started — `dispose` is free when not. */
+    get started(): boolean;
+    /**
+     * Idempotent, and single-flight: several tool calls in one batch all await
+     * the same start rather than racing to create the same container.
+     */
+    start(): Promise<void>;
+    /**
+     * Runs one command and waits for it. The script goes down stdin, so no part
+     * of it is ever parsed by a shell on this side of the container.
+     */
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Starts a command and returns. The wrapper writes the log and the exit
+     * code to files the container owns, which is what makes the job readable
+     * after the `exec` that started it has long returned.
+     */
+    startJob(command: string, opts?: ExecOptions): Promise<Job>;
+    /** A window of a job's log, plus whether it is still going. */
+    readJob(id: string, from?: number): Promise<unknown>;
+    /** Signals a job's whole process group, so its children go too. */
+    stopJob(id: string): Promise<unknown>;
+    /**
+     * Stops a persisted container and removes an ephemeral one. Stopping
+     * rather than removing is what makes `persist` mean anything: a stopped
+     * container costs disk, a running one costs the machine's whole budget.
+     */
+    dispose(): Promise<void>;
+    /**
+     * A path inside the container, contained to the working directory. Purely
+     * lexical, and correctly so: this is the container's path space, not this
+     * machine's, and there is nothing here to resolve a symlink against.
+     */
+    inside(path?: string): string;
+}
+export declare class SandboxPool {
+    #private;
+    constructor(opts: SandboxPoolOptions);
+    for(agent?: string): Sandbox;
+    /** The containers that were actually started, for a status line. */
+    get running(): readonly Sandbox[];
+    dispose(): Promise<void>;
+}
+export declare function sandboxTools<TCtx = unknown>(opts: SandboxPoolOptions | SandboxPool): AnyTool<TCtx>[];
+export {};
+//# sourceMappingURL=sandbox.d.ts.map