@kosa8/sdk 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,798 @@
+import * as http from 'node:http';
+
+/**
+ * Shapes of the kosa8 native API (/kosa8/v1), taken from the daemon's Go
+ * source (pkg/apid/native, pkg/sandbox, pkg/engine, pkg/vnet). Field names
+ * are the daemon's JSON names, unchanged.
+ */
+/** GET /kosa8/v1/health */
+interface Health {
+    status: string;
+    version: string;
+    commit: string;
+    go: string;
+    uptime_seconds: number;
+    phase: string;
+}
+/** A host directory exposed inside a sandbox (pkg/sandbox Mount). */
+interface Mount {
+    host_path: string;
+    guest_path: string;
+    read_only: boolean;
+}
+/**
+ * Egress policy string the daemon accepts (pkg/vnet ParsePolicy):
+ * `any`, `deny`, `fakenet`, or `allow:HOST[,HOST...]` where each entry is a
+ * hostname, a `*.domain` wildcard, an IPv4 address or an IPv4 CIDR.
+ */
+type EgressPolicyString = 'any' | 'deny' | 'fakenet' | `allow:${string}`;
+/**
+ * Egress policy as this SDK takes it: one of the daemon's strings, or
+ * `{ allow: [...] }` for an allow-list (everything else is refused on the host).
+ */
+type EgressPolicy = EgressPolicyString | {
+    allow: readonly string[];
+};
+/** A host the sandbox may reach through an egress broker (pkg/broker HostRule). */
+interface BrokerHostRule {
+    /** Exact DNS name, a `*.domain` wildcard, or a literal IPv4 address. */
+    host: string;
+    /** Ports the host may be reached on. Empty means 443 and 80. */
+    ports?: number[];
+    /** Methods allowed for plain-HTTP requests. Empty means any. */
+    methods?: string[];
+}
+/** A credentialed upstream behind the broker (pkg/sandbox BrokerRoute). */
+interface BrokerRoute {
+    name: string;
+    upstream: string;
+    methods?: string[];
+    paths?: string[];
+    /** Header the broker sets on the way out, e.g. `Authorization` or `x-api-key`. */
+    header: string;
+    scheme?: string;
+    /** The real credential. Held by the broker on the host, never by the sandbox. */
+    secret: string;
+}
+/** Puts a sandbox behind an egress broker (pkg/sandbox BrokerSpec). */
+interface BrokerSpec {
+    allow?: BrokerHostRule[];
+    routes?: BrokerRoute[];
+}
+/** The broker as a running sandbox reports it (pkg/sandbox BrokerInfo). */
+interface BrokerInfo {
+    url: string;
+    hosts?: string[];
+    routes?: string[];
+}
+/** Packet capture to a pcapng file on the host (pkg/sandbox CaptureSpec). */
+interface CaptureSpec {
+    /** Absolute path on the host. */
+    path: string;
+    max_bytes?: number;
+    max_files?: number;
+}
+/** A sandbox (pkg/sandbox Sandbox). */
+interface Sandbox {
+    id: string;
+    name: string;
+    created: string;
+    /** running | paused | stopped */
+    state: string;
+    parent?: string;
+    cpus: number;
+    mem_mb: number;
+    disk_gb?: number;
+    mounts?: Mount[];
+    egress?: string;
+    capture?: string;
+    ip?: string;
+    labels?: Record<string, string>;
+    broker?: BrokerInfo;
+}
+/** A saved sandbox state (pkg/sandbox Snapshot). */
+interface Snapshot {
+    id: string;
+    sandbox: string;
+    created: string;
+    machine_id?: string;
+    mac?: string;
+    cpus: number;
+    mem_mb: number;
+    cmdline: string;
+    size_bytes: number;
+    state_path: string;
+    disk_path?: string;
+    data_path?: string;
+    disk_gb?: number;
+    ephemeral?: boolean;
+    mounts?: Mount[];
+    egress?: string;
+    received?: boolean;
+    received_mounts?: string[];
+    sealed?: boolean;
+    labels?: Record<string, string>;
+    encryption?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** A container inside an engine (pkg/engine Container). */
+interface Container {
+    id: string;
+    image: string;
+    status: string;
+    exit?: number;
+    ip?: string;
+}
+/** POST /kosa8/v1/sandboxes answer. */
+interface CreateSandboxResult {
+    sandbox: Sandbox;
+    boot_ms: number;
+    /** Present when the sandbox was created behind a broker: the stand-ins the sandbox holds. */
+    broker?: {
+        url: string;
+        placeholders: Record<string, string>;
+    };
+}
+/** POST /kosa8/v1/sandboxes/{id}/up answer. */
+interface StartSandboxResult {
+    sandbox: Sandbox;
+    boot_ms: number;
+    warning?: string;
+}
+/** POST /kosa8/v1/sandboxes/{id}/down answer. */
+interface StopSandboxResult {
+    ok: boolean;
+    sandbox?: Sandbox;
+    warning?: string;
+    already_stopped?: boolean;
+}
+/** DELETE /kosa8/v1/sandboxes/{id} answer. */
+interface DeleteSandboxResult {
+    ok: boolean;
+    wipe?: unknown;
+    files?: unknown;
+}
+/** POST /kosa8/v1/sandboxes/{id}/snapshot answer. */
+interface SnapshotSandboxResult {
+    snapshot: Snapshot;
+    snapshot_ms: number;
+    encrypted_by_policy?: string;
+    encrypt_ms?: number;
+    encryption?: unknown;
+}
+/** POST /kosa8/v1/sandboxes/{id}/fork answer. */
+interface ForkResult {
+    forks: Sandbox[];
+    /** The (ephemeral) snapshot the forks were restored from. */
+    snapshot: string;
+    fork_ms: number;
+    count: number;
+    encrypted_by_policy?: string;
+    encrypt_ms?: number;
+}
+/** POST /kosa8/v1/snapshots/{id}/restore answer. */
+interface RestoreResult {
+    sandbox: Sandbox;
+    restore_ms: number;
+    seal?: unknown;
+}
+/** DELETE /kosa8/v1/snapshots/{id} answer. */
+interface DeleteSnapshotResult {
+    ok: boolean;
+    removed: string;
+    encrypted: boolean;
+    shred?: unknown;
+    wipe?: unknown;
+    files?: unknown;
+}
+/** GET /kosa8/v1/sandboxes/{id}/egress answer (pkg/sandbox EgressStatus). */
+interface EgressStatus {
+    policy: string;
+    stats: {
+        passed: number;
+        denied: number;
+        dropped: number;
+        dns_answered: number;
+        dns_refused: number;
+        fakenet?: number;
+    };
+    capture?: string;
+    wildcards?: {
+        wildcard: string;
+        names?: string[];
+        more?: number;
+    }[];
+    fakenet?: {
+        interactions: number;
+        dropped?: number;
+        ca?: string;
+        log?: string;
+    };
+}
+/** One frame of a streamed answer (pkg/engine Frame), with `data` decoded. */
+interface Frame {
+    /** stdout | stderr | status */
+    stream?: string;
+    data?: Buffer;
+    done?: boolean;
+    ok?: boolean;
+    error?: string;
+    exit?: number;
+    id?: string;
+    image?: string;
+    [key: string]: unknown;
+}
+/** The collected result of a streamed run or exec. */
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    stdoutBytes: Buffer;
+    stderrBytes: Buffer;
+}
+/** A client-side restore point (same record as `kosa8 checkpoint`, pkg/checkpoint). */
+interface Checkpoint {
+    /** The underlying snapshot id, e.g. `web-ckpt-3`. */
+    id: string;
+    sandbox: string;
+    label: string;
+    auto?: boolean;
+    /** RFC 3339 time it was taken. */
+    created: string;
+}
+/** One branch of an explore. */
+interface ExploreBranch {
+    /** The forked sandbox's id. */
+    name: string;
+    variant: string;
+    exit: number;
+    output: string;
+    duration_ms: number;
+    error?: string;
+}
+interface ExploreResult {
+    parent: string;
+    branches: ExploreBranch[];
+    /** The fastest successful branch, or "" when every branch failed. */
+    winner: string;
+    removed: number;
+}
+
+/**
+ * Checkpoints are client-side bookkeeping over daemon snapshots, exactly as
+ * in the kosa8 CLI and MCP server (pkg/checkpoint): a checkpoint is a
+ * snapshot with the id `<sandbox>-ckpt-<n>`, and an ordered stack of them per
+ * sandbox records labels and order. The daemon itself has no checkpoint
+ * endpoint.
+ */
+/** How many checkpoints are kept per sandbox; the oldest is evicted (pkg/checkpoint MaxPerSandbox). */
+declare const MAX_CHECKPOINTS_PER_SANDBOX = 10;
+type StoreData = Record<string, Checkpoint[]>;
+/** Where checkpoint stacks are kept. */
+interface CheckpointStore {
+    /** Read every stack. */
+    load(): Promise<StoreData>;
+    /** Run `fn` on the stacks and save what it leaves, serialised against other updates. */
+    update<T>(fn: (data: StoreData) => T | Promise<T>): Promise<T>;
+}
+/** Reject a name that could escape the store (pkg/checkpoint validSandbox). */
+declare function validateSandboxName(name: string): void;
+/** Keeps stacks in memory only; nothing is shared with the kosa8 CLI. */
+declare class MemoryCheckpointStore implements CheckpointStore {
+    private data;
+    private queue;
+    load(): Promise<StoreData>;
+    update<T>(fn: (data: StoreData) => T | Promise<T>): Promise<T>;
+}
+/**
+ * The store the kosa8 CLI, MCP server and desk use: `~/.kosa8/checkpoints.json`
+ * (mode 0600, rewritten atomically). Checkpoints taken through the SDK are
+ * therefore visible to `kosa8 rewind` and the other way round.
+ *
+ * Updates are serialised within this process and between Node processes
+ * using this store (an exclusive lock file beside it). The Go tools lock the
+ * same file with flock(2), which Node cannot take, so an SDK update that
+ * lands in the same instant as a CLI update could lose one record; the
+ * snapshots themselves are unaffected.
+ */
+declare class FileCheckpointStore implements CheckpointStore {
+    readonly path: string;
+    private queue;
+    constructor(filePath?: string);
+    load(): Promise<StoreData>;
+    update<T>(fn: (data: StoreData) => T | Promise<T>): Promise<T>;
+    private locked;
+}
+/** The stack logic of pkg/checkpoint, over any store. */
+declare class CheckpointBook {
+    readonly store: CheckpointStore;
+    constructor(store: CheckpointStore);
+    /** The snapshot id the next checkpoint should use, and ids to evict to stay under the cap. */
+    nextId(sandbox: string): Promise<{
+        id: string;
+        evict: string[];
+    }>;
+    record(c: Omit<Checkpoint, 'created'> & {
+        created?: string;
+    }, evicted?: string[]): Promise<Checkpoint>;
+    list(sandbox: string): Promise<Checkpoint[]>;
+    latest(sandbox: string): Promise<Checkpoint>;
+    /** Find by id or (case-insensitive) label, newest match first. */
+    resolve(sandbox: string, ref: string): Promise<Checkpoint>;
+    /** Keep `id` as the top of the stack; return the ids taken after it (now meaningless). */
+    pop(sandbox: string, id: string): Promise<string[]>;
+    /** Drop every checkpoint of a sandbox; return the snapshot ids to delete. */
+    forget(sandbox: string): Promise<string[]>;
+}
+
+/** Who the audit log should file a request under (pkg/policyd Actor). */
+type Actor = 'human' | 'agent' | 'tool';
+interface TransportOptions {
+    /**
+     * Unix socket of the daemon. Default: `$HOME/.kosa8/run/kosa8.sock`.
+     * Ignored when `host` (or KOSA8_HOST) is set.
+     */
+    socketPath?: string;
+    /**
+     * A remote kosa8 worker: `https://host`, `http://host:port`, `tcp://host:port`
+     * or a bare `host:port`, the same spellings the kosa8 CLI accepts in
+     * KOSA8_HOST. `unix:///path/to.sock` selects a socket. Defaults to the
+     * KOSA8_HOST environment variable.
+     */
+    host?: string;
+    /** Bearer token for a remote worker. Defaults to KOSA8_TOKEN when KOSA8_HOST is in use. */
+    token?: string;
+    /**
+     * Allow plain http to a non-loopback host. Off by default, as in the CLI,
+     * because the token and every request would cross the network unencrypted.
+     * KOSA8_INSECURE=1 also allows it.
+     */
+    insecure?: boolean;
+    /** Sent as X-Kosa8-Actor so the audit log files requests correctly. Default `tool`. */
+    actor?: Actor;
+    /** Agent identity token (X-Kosa8-Agent-Token). Defaults to KOSA8_AGENT_TOKEN. */
+    agentToken?: string;
+    /** Extra headers on every request. */
+    headers?: Record<string, string>;
+    /** Environment to read KOSA8_* variables from. Default `process.env`. */
+    env?: Record<string, string | undefined>;
+}
+interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** A raw (non-JSON) request body, sent as-is; an async iterable is streamed chunked. */
+    rawBody?: Uint8Array | string | AsyncIterable<Uint8Array | string>;
+    /** Signed-approval id, sent as X-Kosa8-Approval. */
+    approval?: string;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+type Endpoint = {
+    kind: 'unix';
+    socketPath: string;
+} | {
+    kind: 'tcp';
+    url: URL;
+    token?: string;
+};
+declare const APPROVAL_HEADER = "X-Kosa8-Approval";
+declare const ACTOR_HEADER = "X-Kosa8-Actor";
+declare const AGENT_TOKEN_HEADER = "X-Kosa8-Agent-Token";
+/** The daemon's default socket: $HOME/.kosa8/run/kosa8.sock (pkg/paths). */
+declare function defaultSocketPath(): string;
+/** Resolve where to connect, following the CLI's KOSA8_HOST rules. */
+declare function resolveEndpoint(opts: TransportOptions): Endpoint;
+interface RawResponse {
+    status: number;
+    headers: http.IncomingHttpHeaders;
+    stream: http.IncomingMessage;
+}
+/** HTTP over the daemon's unix socket (or a remote worker). No dependencies. */
+declare class Transport {
+    private readonly endpoint;
+    private readonly actor;
+    private readonly agentToken?;
+    private readonly extraHeaders;
+    constructor(opts?: TransportOptions);
+    /** Human-readable description of where requests go. */
+    get target(): string;
+    private buildPath;
+    /** Send a request and return the raw response once headers arrive. */
+    raw(method: string, p: string, opts?: RequestOptions): Promise<RawResponse>;
+    /** Send a request and decode a JSON answer; HTTP errors become typed errors. */
+    json<T>(method: string, p: string, opts?: RequestOptions): Promise<T>;
+    /**
+     * Send a request whose answer is a stream of NDJSON frames (run, exec,
+     * attach). HTTP errors (a refusal before streaming began) become typed
+     * errors; each frame's base64 `data` is decoded to a Buffer.
+     */
+    frames(method: string, p: string, opts?: RequestOptions): AsyncGenerator<Frame>;
+}
+
+/** Options every call accepts. */
+interface CallOptions {
+    /**
+     * Id of a recorded signed approval for this exact action, sent as
+     * X-Kosa8-Approval. Needed only when the org policy requires one; a
+     * refusal (Kosa8ApprovalRequiredError) says how a human gets it.
+     */
+    approval?: string;
+    signal?: AbortSignal;
+}
+interface Kosa8ClientOptions extends TransportOptions {
+    /**
+     * Where checkpoint stacks are kept. Default: the kosa8 CLI's own store,
+     * `~/.kosa8/checkpoints.json`, so `kosa8 rewind` sees SDK checkpoints.
+     */
+    checkpointStore?: CheckpointStore;
+}
+interface CreateSandboxOptions extends CallOptions {
+    /** Sandbox name; the daemon generates one when omitted. */
+    name?: string;
+    cpus?: number;
+    memMb?: number;
+    /** Data disk in GB (holds images and everything written inside). 0 = daemon default. */
+    diskGb?: number;
+    mounts?: Mount[];
+    /**
+     * Network policy: `'deny'`, `'any'`, `'fakenet'`, `'allow:a.com,b.com'` or
+     * `{ allow: ['a.com', '*.b.com', '10.0.0.0/8'] }`. When omitted the daemon
+     * applies the org policy's default egress, else `any`.
+     */
+    egress?: EgressPolicy;
+    /** Shorthand for `egress: { allow: [...] }`. */
+    egressAllow?: readonly string[];
+    /** Start a packet capture from the first frame. */
+    capture?: CaptureSpec;
+    labels?: Record<string, string>;
+    /** Put the sandbox behind an egress broker that adds credentials it never holds. */
+    broker?: BrokerSpec;
+}
+interface RunOptions extends CallOptions {
+    env?: Record<string, string> | string[];
+    onStdout?: (chunk: Buffer) => void;
+    onStderr?: (chunk: Buffer) => void;
+    /** Progress lines the daemon emits (e.g. "pulling alpine"). */
+    onStatus?: (chunk: Buffer) => void;
+}
+interface ExecOptions extends CallOptions {
+    onStdout?: (chunk: Buffer) => void;
+    onStderr?: (chunk: Buffer) => void;
+}
+interface ForkOptions extends CallOptions {
+    /** Number of copies (default 1). */
+    n?: number;
+    /** Name prefix; copies are named `<prefix>1`, `<prefix>2`, ... (default `<sandbox>-fork`). */
+    prefix?: string;
+    /** Raise the copies' classification label above the parent's. */
+    label?: string;
+}
+interface ExploreOptions extends CallOptions {
+    /** Shell commands, one per branch (at least two). */
+    variants: string[];
+    /** Image the variants run in (default `alpine:latest`). */
+    image?: string;
+    /** Keep every branch instead of only the winner. */
+    keepAll?: boolean;
+    /** Keep this branch (by id) instead of the winner. */
+    keep?: string;
+    /** Per-branch time limit in ms (default 120000). */
+    timeoutMs?: number;
+    /** Branch name prefix (default `<sandbox>-explore-<n>`). */
+    prefix?: string;
+    /**
+     * Pull `image` into the parent sandbox before forking so every branch has
+     * it (a sandbox's engine does not pull on run). Default true.
+     */
+    pull?: boolean;
+}
+interface CheckpointOptions extends CallOptions {
+    /** Why it is being taken, e.g. "before the migration". */
+    label?: string;
+}
+interface CheckpointResult {
+    checkpoint: Checkpoint;
+    /** Older checkpoints dropped to stay under the cap of 10. */
+    evicted: string[];
+    snapshot: SnapshotSandboxResult;
+}
+interface RewindOptions extends CallOptions {
+    /** Checkpoint id or label (default: the most recent). */
+    to?: string;
+}
+interface RewindResult {
+    sandbox: Sandbox;
+    checkpoint: Checkpoint;
+    /** Checkpoints taken after the one returned to, now deleted. */
+    dropped: string[];
+    restore_ms: number;
+}
+interface RestoreOptions extends CallOptions {
+    /** Name for the restored sandbox. */
+    name?: string;
+    /** Raise the restored sandbox's classification label. */
+    label?: string;
+    /** Restore a sealed snapshot whose seal does not verify (recorded in the audit log). */
+    allowTampered?: boolean;
+}
+/**
+ * Typed client for the kosa8 native API over the daemon's unix socket.
+ *
+ * ```ts
+ * const kosa8 = new Kosa8Client();
+ * const { sandbox } = await kosa8.createSandbox({ name: 'demo', egress: 'deny' });
+ * ```
+ */
+declare class Kosa8Client {
+    readonly transport: Transport;
+    readonly checkpoints: CheckpointBook;
+    constructor(options?: Kosa8ClientOptions);
+    /** GET /kosa8/v1/health: daemon status and version. */
+    health(opts?: CallOptions): Promise<Health>;
+    /** The daemon's version string. */
+    version(opts?: CallOptions): Promise<string>;
+    /** POST /kosa8/v1/pull: pull an image into the host engine (checked against the registry allow-list). */
+    pull(ref: string, opts?: CallOptions): Promise<{
+        ok: boolean;
+        image: string;
+    }>;
+    /** GET /kosa8/v1/sandboxes */
+    listSandboxes(opts?: CallOptions): Promise<Sandbox[]>;
+    /** Find one sandbox by id or name (from the list; there is no single-sandbox GET). */
+    getSandbox(idOrName: string, opts?: CallOptions): Promise<Sandbox | undefined>;
+    /** POST /kosa8/v1/sandboxes: boot a microVM sandbox. */
+    createSandbox(options?: CreateSandboxOptions): Promise<CreateSandboxResult>;
+    /** POST /kosa8/v1/sandboxes/{id}/up: boot a stopped sandbox from its own disk. */
+    startSandbox(id: string, opts?: CallOptions): Promise<StartSandboxResult>;
+    /** POST /kosa8/v1/sandboxes/{id}/down: stop without deleting (disk kept). */
+    stopSandbox(id: string, opts?: CallOptions): Promise<StopSandboxResult>;
+    /**
+     * DELETE /kosa8/v1/sandboxes/{id}. Like `kosa8 sandbox rm`, the sandbox's
+     * checkpoints and their snapshots are dropped too unless
+     * `keepCheckpoints` is set.
+     */
+    deleteSandbox(id: string, opts?: CallOptions & {
+        wipe?: boolean;
+        keepCheckpoints?: boolean;
+    }): Promise<DeleteSandboxResult & {
+        checkpoints_dropped: number;
+    }>;
+    /** POST /kosa8/v1/sandboxes/{id}/pull: pull an image into the sandbox's private engine (fetched on the host). */
+    pullIntoSandbox(id: string, ref: string, opts?: CallOptions): Promise<{
+        ok: boolean;
+        image: string;
+    }>;
+    /** GET /kosa8/v1/sandboxes/{id}/images */
+    sandboxImages(id: string, opts?: CallOptions): Promise<string[]>;
+    /** GET /kosa8/v1/sandboxes/{id}/containers */
+    sandboxContainers(id: string, opts?: CallOptions): Promise<Container[]>;
+    /** GET /kosa8/v1/sandboxes/{id}/egress: the policy the host enforces and what it decided. */
+    sandboxEgress(id: string, opts?: CallOptions): Promise<EgressStatus>;
+    /**
+     * POST /kosa8/v1/sandboxes/{id}/run: run a container to completion inside
+     * the sandbox's engine. The image must already be in the sandbox
+     * (`pullIntoSandbox`). Resolves with the exit code; a non-zero exit is not
+     * an error.
+     */
+    run(id: string, image: string, args?: string[], opts?: RunOptions): Promise<ExecResult>;
+    /** POST /kosa8/v1/sandboxes/{id}/start: start a detached container; resolves with its id. */
+    startContainer(id: string, image: string, args?: string[], opts?: CallOptions): Promise<string>;
+    /** POST /kosa8/v1/sandboxes/{id}/exec: run a command in a running container of the sandbox. */
+    exec(id: string, container: string, args: string[], opts?: ExecOptions): Promise<ExecResult>;
+    /** The raw frame stream of an exec, for callers that want to process output as it arrives. */
+    execFrames(id: string, container: string, args: string[], opts?: CallOptions): AsyncGenerator<Frame>;
+    /** POST /kosa8/v1/sandboxes/{id}/start-interactive: start a container with stdin held open. */
+    startInteractive(id: string, image: string, args?: string[], opts?: CallOptions & {
+        env?: Record<string, string> | string[];
+        tty?: boolean;
+    }): Promise<string>;
+    /** POST /kosa8/v1/sandboxes/{id}/containers/{cid}/stdin: stream bytes into an interactive container's stdin. */
+    writeStdin(id: string, container: string, data: Uint8Array | string | AsyncIterable<Uint8Array | string>, opts?: CallOptions): Promise<{
+        ok: boolean;
+    }>;
+    /** POST /kosa8/v1/sandboxes/{id}/containers/{cid}/attach: follow a container's output until it exits. */
+    attach(id: string, container: string, opts?: ExecOptions): Promise<ExecResult>;
+    /** POST /kosa8/v1/sandboxes/{id}/snapshot: capture memory, processes and disks. */
+    snapshot(id: string, opts?: CallOptions & {
+        id?: string;
+        encrypt?: boolean;
+    }): Promise<SnapshotSandboxResult>;
+    /** GET /kosa8/v1/snapshots */
+    listSnapshots(opts?: CallOptions): Promise<Snapshot[]>;
+    /** POST /kosa8/v1/snapshots/{id}/restore: boot a sandbox from a snapshot, processes resumed. */
+    restoreSnapshot(snapshotId: string, opts?: RestoreOptions): Promise<RestoreResult>;
+    /** DELETE /kosa8/v1/snapshots/{id} */
+    deleteSnapshot(snapshotId: string, opts?: CallOptions & {
+        wipe?: boolean;
+        force?: boolean;
+    }): Promise<DeleteSnapshotResult>;
+    /** POST /kosa8/v1/sandboxes/{id}/fork: N live copies of a running sandbox. */
+    fork(id: string, opts?: ForkOptions): Promise<ForkResult>;
+    /**
+     * Best-of-N, as `kosa8 explore`: fork the sandbox once per variant, run
+     * each variant (`sh -c VARIANT` in `image`) in its own branch
+     * concurrently, keep the fastest successful branch and delete the rest.
+     */
+    explore(id: string, opts: ExploreOptions): Promise<ExploreResult>;
+    private runBranch;
+    /**
+     * Save a restore point: a snapshot with id `<sandbox>-ckpt-<n>`, recorded on
+     * the sandbox's checkpoint stack (the same store `kosa8 checkpoint` uses).
+     * The oldest is evicted past 10.
+     */
+    checkpoint(sandbox: string, opts?: CheckpointOptions): Promise<CheckpointResult>;
+    /** A sandbox's restore points, oldest first. */
+    listCheckpoints(sandbox: string): Promise<Checkpoint[]>;
+    /**
+     * Undo: put the sandbox back to a checkpoint under the same name, processes
+     * resumed. Deletes the sandbox, then restores the snapshot with its name;
+     * checkpoints taken after the target are discarded. Current state is lost.
+     */
+    rewind(sandbox: string, opts?: RewindOptions): Promise<RewindResult>;
+    /** A handle bound to one sandbox. */
+    sandbox(id: string): SandboxHandle;
+    private collect;
+}
+/** Convenience wrapper: the client's sandbox methods bound to one sandbox id. */
+declare class SandboxHandle {
+    readonly client: Kosa8Client;
+    readonly id: string;
+    constructor(client: Kosa8Client, id: string);
+    info(opts?: CallOptions): Promise<Sandbox | undefined>;
+    start(opts?: CallOptions): Promise<StartSandboxResult>;
+    stop(opts?: CallOptions): Promise<StopSandboxResult>;
+    delete(opts?: CallOptions & {
+        wipe?: boolean;
+        keepCheckpoints?: boolean;
+    }): Promise<DeleteSandboxResult & {
+        checkpoints_dropped: number;
+    }>;
+    pull(ref: string, opts?: CallOptions): Promise<{
+        ok: boolean;
+        image: string;
+    }>;
+    run(image: string, args?: string[], opts?: RunOptions): Promise<ExecResult>;
+    startContainer(image: string, args?: string[], opts?: CallOptions): Promise<string>;
+    exec(container: string, args: string[], opts?: ExecOptions): Promise<ExecResult>;
+    containers(opts?: CallOptions): Promise<Container[]>;
+    images(opts?: CallOptions): Promise<string[]>;
+    egress(opts?: CallOptions): Promise<EgressStatus>;
+    snapshot(opts?: CallOptions & {
+        id?: string;
+        encrypt?: boolean;
+    }): Promise<SnapshotSandboxResult>;
+    fork(opts?: ForkOptions): Promise<ForkResult>;
+    explore(opts: ExploreOptions): Promise<ExploreResult>;
+    checkpoint(opts?: CheckpointOptions): Promise<CheckpointResult>;
+    checkpoints(): Promise<Checkpoint[]>;
+    rewind(opts?: RewindOptions): Promise<RewindResult>;
+}
+
+/**
+ * Typed errors. Every error the daemon answers with carries its own words:
+ * `daemonMessage` is the daemon's `error` field verbatim, and `remediation`
+ * is its `remediation` field (what to do about it). A refusal because the
+ * org policy wants signed approvals also carries the refusal itself, under
+ * `approval`, exactly as the daemon sent it.
+ */
+/** An approval rule from the org policy, as the daemon reports it. */
+interface ApprovalRule {
+    [key: string]: unknown;
+}
+/** What the policy requires before an action may run. */
+interface ApprovalRequirement {
+    policy: string;
+    rules: ApprovalRule[];
+}
+/** The action a refusal is about. */
+interface ApprovalAction {
+    kind: string;
+    target?: string;
+    command?: string[];
+    sandbox?: string;
+    [key: string]: unknown;
+}
+/**
+ * The daemon's answer to a call the org policy wants signed approvals for
+ * and that did not bring a usable one (pkg/approve Refusal).
+ */
+interface ApprovalRefusal {
+    route: string;
+    action: ApprovalAction;
+    description: string;
+    /** read-only | contained | destructive | escalating */
+    class: string;
+    policy: string;
+    policy_digest: string;
+    requirement: ApprovalRequirement;
+    /** The approval id the call presented, if any. */
+    request_id?: string;
+    /** What was wrong: nothing presented, not recorded, used, expired, ... */
+    why: string;
+    /** People the policy lets approve this action. */
+    signers?: string[];
+    /** The CLI command that opens a request for exactly this action. */
+    request_command: string;
+}
+interface Kosa8ErrorOptions {
+    status?: number;
+    daemonMessage?: string;
+    remediation?: string;
+    method?: string;
+    path?: string;
+    body?: unknown;
+    cause?: unknown;
+}
+/** Base class of every error this SDK throws. */
+declare class Kosa8Error extends Error {
+    /** HTTP status the daemon answered with, when there was an answer. */
+    readonly status?: number;
+    /** The daemon's `error` text, verbatim. */
+    readonly daemonMessage?: string;
+    /** The daemon's `remediation` text: what to do about it. */
+    readonly remediation?: string;
+    readonly method?: string;
+    readonly path?: string;
+    /** The decoded response body, when there was one. */
+    readonly body?: unknown;
+    constructor(message: string, options?: Kosa8ErrorOptions);
+}
+/** The daemon could not be reached (no socket, connection refused, ...). */
+declare class Kosa8ConnectionError extends Kosa8Error {
+}
+/** The daemon answered with an HTTP error. */
+declare class Kosa8ApiError extends Kosa8Error {
+}
+/** 400: the request was malformed or a value was refused (an egress policy, say). */
+declare class Kosa8BadRequestError extends Kosa8ApiError {
+}
+/** 401: a bearer token (remote worker) or agent token was missing or refused. */
+declare class Kosa8AuthError extends Kosa8ApiError {
+}
+/** 403: refused by policy (org policy, registry allow-list, labels, ...). */
+declare class Kosa8PolicyError extends Kosa8ApiError {
+}
+/**
+ * 403 with a signed-approval refusal: the org policy wants people other than
+ * the caller to approve this exact action. Get the approval id from a human
+ * and repeat the call with `{ approval: id }`.
+ */
+declare class Kosa8ApprovalRequiredError extends Kosa8PolicyError {
+    readonly approval: ApprovalRefusal;
+    constructor(message: string, approval: ApprovalRefusal, options?: Kosa8ErrorOptions);
+}
+/** 404: no such sandbox, snapshot, container, ... */
+declare class Kosa8NotFoundError extends Kosa8ApiError {
+}
+/** 409: a conflict, e.g. the sandbox exists but is not running, or a snapshot id is taken. */
+declare class Kosa8ConflictError extends Kosa8ApiError {
+}
+/** 501: the platform cannot do this (sandboxes need macOS on Apple silicon or Linux with KVM). */
+declare class Kosa8UnsupportedError extends Kosa8ApiError {
+}
+/**
+ * A streamed operation (run, exec, attach) ended with an error frame rather
+ * than an exit code. Output produced before the error is kept.
+ */
+declare class Kosa8StreamError extends Kosa8Error {
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(message: string, out: {
+        stdout: string;
+        stderr: string;
+    }, options?: Kosa8ErrorOptions);
+}
+/** A client-side checkpoint operation failed (no checkpoint, bad name, ...). */
+declare class Kosa8CheckpointError extends Kosa8Error {
+}
+/**
+ * Build the typed error for an HTTP error answer. The message is the daemon's
+ * own, with its remediation in parentheses, the way the kosa8 CLI and MCP
+ * server print it.
+ */
+declare function errorFromResponse(status: number, body: unknown, ctx?: {
+    method?: string;
+    path?: string;
+}): Kosa8ApiError;
+
+export { ACTOR_HEADER, AGENT_TOKEN_HEADER, APPROVAL_HEADER, type Actor, type ApprovalAction, type ApprovalRefusal, type ApprovalRequirement, type ApprovalRule, type BrokerHostRule, type BrokerInfo, type BrokerRoute, type BrokerSpec, type CallOptions, type CaptureSpec, type Checkpoint, CheckpointBook, type CheckpointOptions, type CheckpointResult, type CheckpointStore, type Container, type CreateSandboxOptions, type CreateSandboxResult, type DeleteSandboxResult, type DeleteSnapshotResult, type EgressPolicy, type EgressPolicyString, type EgressStatus, type ExecOptions, type ExecResult, type ExploreBranch, type ExploreOptions, type ExploreResult, FileCheckpointStore, type ForkOptions, type ForkResult, type Frame, type Health, Kosa8ApiError, Kosa8ApprovalRequiredError, Kosa8AuthError, Kosa8BadRequestError, Kosa8CheckpointError, Kosa8Client, type Kosa8ClientOptions, Kosa8ConflictError, Kosa8ConnectionError, Kosa8Error, Kosa8NotFoundError, Kosa8PolicyError, Kosa8StreamError, Kosa8UnsupportedError, MAX_CHECKPOINTS_PER_SANDBOX, MemoryCheckpointStore, type Mount, type RequestOptions, type RestoreOptions, type RestoreResult, type RewindOptions, type RewindResult, type RunOptions, type Sandbox, SandboxHandle, type Snapshot, type SnapshotSandboxResult, type StartSandboxResult, type StopSandboxResult, Transport, type TransportOptions, defaultSocketPath, errorFromResponse, resolveEndpoint, validateSandboxName };