@kosa8/sdk 0.0.0-stage → 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,1343 @@
+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;
+    /** When it stops or is deleted by itself (pkg/sandbox Lifecycle). */
+    lifecycle?: Lifecycle;
+    /** When it last stopped (RFC 3339). */
+    stopped_at?: string;
+}
+/**
+ * When a sandbox stops or goes away by itself (pkg/sandbox Lifecycle).
+ * A field left out (or 0) is off.
+ */
+interface Lifecycle {
+    /** Stop after this many minutes without use. */
+    auto_stop_min?: number;
+    /** Delete once it has been stopped this many minutes. */
+    auto_delete_min?: number;
+    /** Stop this many minutes after it was created, in use or not. */
+    ttl_min?: number;
+    /** Delete instead of stopping, disk and all. */
+    ephemeral?: boolean;
+}
+/** 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;
+}
+/** A file a code run produced: today, a chart as a PNG. */
+interface CodeArtifact {
+    /** Media type, e.g. `image/png`. */
+    type: string;
+    name: string;
+    data: Buffer;
+}
+/** The outcome of `runCode`. A non-zero `exitCode` is a result, not an error. */
+interface CodeResult {
+    /** `exitCode === 0` and not timed out. */
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    language: string;
+    image: string;
+    artifacts: CodeArtifact[];
+    durationMs: number;
+    timedOut: boolean;
+    /** Output was cut at the daemon's limit. */
+    truncated: boolean;
+}
+/** The outcome of one command in a shell session. `cwd` is where the shell is now. */
+interface ShellResult {
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    cwd: string;
+    durationMs: number;
+    timedOut: boolean;
+    truncated: boolean;
+}
+/** A file or folder in the sandbox workspace (pkg/engine FileInfo). */
+interface FileInfo {
+    name: string;
+    path: string;
+    /** file | dir | symlink | other */
+    type: string;
+    size: number;
+    /** Permission bits. */
+    mode: number;
+    mod_time: string;
+    /** A symlink's target. */
+    link?: string;
+}
+/** One changed path in `git status`. */
+interface GitFileStatus {
+    path: string;
+    /** A rename's old path. */
+    from?: string;
+    index: string;
+    worktree: string;
+}
+interface GitStatus {
+    branch: string;
+    upstream?: string;
+    ahead: number;
+    behind: number;
+    clean: boolean;
+    files: GitFileStatus[];
+}
+interface GitCommit {
+    hash: string;
+    author_name: string;
+    author_email: string;
+    date: string;
+    subject: string;
+}
+interface GitBranch {
+    name: string;
+    current: boolean;
+}
+/** The git operations the daemon runs (POST …/git). */
+type GitOp = 'clone' | 'status' | 'add' | 'commit' | 'push' | 'pull' | 'checkout' | 'branches' | 'log' | 'diff';
+/**
+ * The outcome of a git operation. A git failure is `ok: false`, not an error;
+ * `status`, `log` or `branches` are filled for those ops.
+ */
+interface GitResult {
+    op: string;
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** The repository, in the workspace. */
+    path: string;
+    status?: GitStatus;
+    log?: GitCommit[];
+    branches?: GitBranch[];
+}
+/** A shell session (POST/GET …/sessions). */
+interface SessionInfo {
+    name: string;
+    /** The session's container id. */
+    id: string;
+    image: string;
+    status: string;
+}
+/** POST …/previews answer: a signed link to a port in the sandbox. */
+interface Preview {
+    url: string;
+    token: string;
+    /** RFC 3339. */
+    expires_at: string;
+    container: string;
+    port: number;
+    /** Where the daemon's preview listener is. */
+    listen: string;
+}
+/** A sandbox template (GET /kosa8/v1/templates). */
+interface Template {
+    name: string;
+    image: string;
+    size_bytes: number;
+    created: string;
+    dockerfile?: string;
+}
+
+/**
+ * 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>;
+    /**
+     * The CLI's saved worker connection, used when neither `host` nor KOSA8_HOST
+     * is set (and no `socketPath` is given): what `kosa8 wsl setup` writes on
+     * Windows, and `kosa8 worker join` anywhere. Default
+     * `$HOME/.kosa8/worker.json`; `null` reads none.
+     */
+    workerFile?: string | null;
+}
+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;
+/** The CLI's saved worker connection: $HOME/.kosa8/worker.json (internal/cli/worker.go). */
+declare function defaultWorkerFile(): 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;
+    /** Stop it after this many idle minutes. */
+    autoStopMin?: number;
+    /** Stop it this many minutes after creation, in use or not. */
+    ttlMin?: number;
+    /** Delete it once it has been stopped this many minutes. */
+    autoDeleteMin?: number;
+    /** Delete it (disk and all) whenever it stops. */
+    ephemeral?: boolean;
+    /** Start it with a template's image (see `buildTemplate`). */
+    template?: string;
+}
+interface RunCodeOptions extends CallOptions {
+    /** `python` (default), `javascript` or `typescript`. */
+    language?: string;
+    /** Image to run in; the daemon picks one per language (or the sandbox template's). */
+    image?: string;
+    env?: Record<string, string>;
+    /** Time limit in seconds; past it the run is killed and `timedOut` set. */
+    timeoutS?: number;
+}
+interface WriteFileOptions extends CallOptions {
+    /** Permission bits as octal text, e.g. `0755`. */
+    mode?: string;
+}
+/** The fields of a git op; which ones matter depends on the op. */
+interface GitOptions extends CallOptions {
+    /** The repository, in the workspace. */
+    path?: string;
+    /** clone */
+    url?: string;
+    branch?: string;
+    /** clone --depth */
+    depth?: number;
+    /** push | pull; default origin */
+    remote?: string;
+    /** checkout -b */
+    create?: boolean;
+    /** add: these paths (default everything) */
+    files?: string[];
+    /** commit */
+    message?: string;
+    authorName?: string;
+    authorEmail?: string;
+    /** log: how many (default 20) */
+    n?: number;
+    /** diff --cached */
+    staged?: boolean;
+    /** For an https remote that needs credentials. */
+    username?: string;
+    token?: string;
+    /** Image git runs in. */
+    image?: string;
+}
+interface GitCommitOptions extends Omit<GitOptions, 'path' | 'message'> {
+    /** Stage everything first (default true). */
+    addAll?: boolean;
+}
+interface CreateSessionOptions extends CallOptions {
+    image?: string;
+    env?: Record<string, string>;
+}
+interface SessionExecOptions extends CallOptions {
+    /** Time limit in seconds for this command. */
+    timeoutS?: number;
+}
+interface ShellOptions extends SessionExecOptions {
+    /** Session to run in; made on first use. Default `main`. */
+    session?: string;
+}
+interface StartPtyOptions extends CallOptions {
+    image?: string;
+    command?: string[];
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+}
+interface CreatePreviewOptions extends CallOptions {
+    /** Which session's container serves the port. */
+    session?: string;
+    /** Or which container. */
+    container?: string;
+    /** How long the link lives, in seconds. */
+    expiresInS?: number;
+}
+interface SetLifecycleOptions extends CallOptions {
+    autoStopMin?: number;
+    autoDeleteMin?: number;
+    ttlMin?: number;
+    ephemeral?: boolean;
+}
+interface BuildTemplateOptions extends CallOptions {
+    /** Dockerfile name inside the context (default `Dockerfile`). */
+    dockerfile?: string;
+    buildArgs?: Record<string, string>;
+    /** Network the build sandbox gets (daemon default `any`). */
+    egress?: EgressPolicy;
+    /** Build again over an existing template of the same name. */
+    replace?: boolean;
+    /** Build output as it arrives. */
+    onOutput?: (chunk: Buffer, stream: string) => void;
+}
+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>;
+    /**
+     * POST /kosa8/v1/sandboxes/{id}/code: run a Python, JavaScript or
+     * TypeScript snippet. It starts in `/workspace`. Charts a Python snippet
+     * draws with matplotlib come back in `artifacts` as PNG bytes.
+     */
+    runCode(id: string, code: string, opts?: RunCodeOptions): Promise<CodeResult>;
+    /** GET …/files: a folder in the workspace (default `/workspace`), or one entry. */
+    listFiles(id: string, path?: string, opts?: CallOptions): Promise<FileInfo[]>;
+    /** GET …/files/stat: one entry, not following a symlink. */
+    statFile(id: string, path: string, opts?: CallOptions): Promise<FileInfo>;
+    /** GET …/files/content: a file's bytes. A body cut short is a Kosa8StreamError. */
+    readFile(id: string, path: string, opts?: CallOptions): Promise<Buffer>;
+    /** A file's contents as text (UTF-8 by default). */
+    readText(id: string, path: string, opts?: CallOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<string>;
+    /** PUT …/files/content: replace a file, making its folders. Answers the new entry. */
+    writeFile(id: string, path: string, data: Uint8Array | string | AsyncIterable<Uint8Array | string>, opts?: WriteFileOptions): Promise<FileInfo>;
+    /** DELETE …/files: a file, or with `recursive` a folder and everything in it. */
+    deleteFile(id: string, path: string, opts?: CallOptions & {
+        recursive?: boolean;
+    }): Promise<{
+        removed: string;
+    }>;
+    /** POST …/files/mkdir: a folder, with its parents. */
+    makeDir(id: string, path: string, opts?: CallOptions): Promise<FileInfo>;
+    /** POST …/files/move: rename or move a file or folder. Answers the entry at `to`. */
+    moveFile(id: string, from: string, to: string, opts?: CallOptions): Promise<FileInfo>;
+    /**
+     * POST …/git: one git operation in the workspace. A git failure resolves
+     * with `ok: false`; only a refusal (bad op, no sandbox, policy) throws.
+     */
+    git(id: string, op: GitOp | (string & {}), opts?: GitOptions): Promise<GitResult>;
+    /** Clone `url` into the workspace (into `path`, else a folder named after the repo). */
+    gitClone(id: string, url: string, opts?: GitOptions): Promise<GitResult>;
+    /** `git status` of the repository at `path`, parsed into `status`. */
+    gitStatus(id: string, path: string, opts?: GitOptions): Promise<GitResult>;
+    /** Stage everything (unless `addAll: false`) and commit. A failed add is returned as is. */
+    gitCommit(id: string, path: string, message: string, opts?: GitCommitOptions): Promise<GitResult>;
+    /** POST …/sessions: a shell that keeps `cd` and `export` between commands. */
+    createSession(id: string, name?: string, opts?: CreateSessionOptions): Promise<SessionInfo>;
+    /** GET …/sessions */
+    listSessions(id: string, opts?: CallOptions): Promise<SessionInfo[]>;
+    /** POST …/sessions/{name}/exec: run one command line in the session. */
+    sessionExec(id: string, session: string, command: string, opts?: SessionExecOptions): Promise<ShellResult>;
+    /** Run a command in a session (default `main`), making the session on first use. */
+    shell(id: string, command: string, opts?: ShellOptions): Promise<ShellResult>;
+    /** DELETE …/sessions/{name} */
+    deleteSession(id: string, session: string, opts?: CallOptions): Promise<{
+        deleted: string;
+    }>;
+    /**
+     * POST …/pty: a container with a terminal; resolves with its id. Connect
+     * to `/kosa8/v1/sandboxes/{id}/containers/{cid}/tty` with any WebSocket
+     * client: binary messages are the terminal, text messages JSON control.
+     */
+    startPty(id: string, opts?: StartPtyOptions): Promise<string>;
+    /** POST …/containers/{cid}/resize: set a terminal's size. */
+    resizePty(id: string, container: string, cols: number, rows: number, opts?: CallOptions): Promise<{
+        ok: boolean;
+    }>;
+    /** POST …/previews: a signed link, which expires, to a web server in the sandbox. */
+    createPreview(id: string, port: number, opts?: CreatePreviewOptions): Promise<Preview>;
+    /** POST /kosa8/v1/previews/rotate: end every preview link at once. */
+    revokePreviews(opts?: CallOptions): Promise<{
+        ok: boolean;
+        revoked: string;
+    }>;
+    /**
+     * POST …/lifecycle: change auto-stop, auto-delete, TTL or ephemeral.
+     * Options left out keep their value; 0 (or `false`) turns one off.
+     */
+    setLifecycle(id: string, opts?: SetLifecycleOptions): Promise<Sandbox>;
+    /** GET /kosa8/v1/templates */
+    listTemplates(opts?: CallOptions): Promise<Template[]>;
+    /** DELETE /kosa8/v1/templates/{name}. Sandboxes made from it keep their copy. */
+    deleteTemplate(name: string, opts?: CallOptions): Promise<{
+        deleted: string;
+    }>;
+    /**
+     * POST /kosa8/v1/templates: build `contextDir`'s Dockerfile in a throwaway
+     * sandbox and keep the image as a template, for `createSandbox({ template })`.
+     * The context is packed honouring `.dockerignore`. Resolves with the final
+     * frame (`{ done, ok, image }`); a failed build throws Kosa8StreamError.
+     */
+    buildTemplate(name: string, contextDir?: string, opts?: BuildTemplateOptions): Promise<Frame>;
+    /** 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>;
+    runCode(code: string, opts?: RunCodeOptions): Promise<CodeResult>;
+    listFiles(path?: string, opts?: CallOptions): Promise<FileInfo[]>;
+    statFile(path: string, opts?: CallOptions): Promise<FileInfo>;
+    readFile(path: string, opts?: CallOptions): Promise<Buffer<ArrayBufferLike>>;
+    readText(path: string, opts?: CallOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<string>;
+    writeFile(path: string, data: Uint8Array | string | AsyncIterable<Uint8Array | string>, opts?: WriteFileOptions): Promise<FileInfo>;
+    deleteFile(path: string, opts?: CallOptions & {
+        recursive?: boolean;
+    }): Promise<{
+        removed: string;
+    }>;
+    makeDir(path: string, opts?: CallOptions): Promise<FileInfo>;
+    moveFile(from: string, to: string, opts?: CallOptions): Promise<FileInfo>;
+    git(op: GitOp | (string & {}), opts?: GitOptions): Promise<GitResult>;
+    gitClone(url: string, opts?: GitOptions): Promise<GitResult>;
+    gitStatus(path: string, opts?: GitOptions): Promise<GitResult>;
+    gitCommit(path: string, message: string, opts?: GitCommitOptions): Promise<GitResult>;
+    createSession(name?: string, opts?: CreateSessionOptions): Promise<SessionInfo>;
+    sessions(opts?: CallOptions): Promise<SessionInfo[]>;
+    sessionExec(session: string, command: string, opts?: SessionExecOptions): Promise<ShellResult>;
+    shell(command: string, opts?: ShellOptions): Promise<ShellResult>;
+    deleteSession(session: string, opts?: CallOptions): Promise<{
+        deleted: string;
+    }>;
+    startPty(opts?: StartPtyOptions): Promise<string>;
+    resizePty(container: string, cols: number, rows: number, opts?: CallOptions): Promise<{
+        ok: boolean;
+    }>;
+    createPreview(port: number, opts?: CreatePreviewOptions): Promise<Preview>;
+    setLifecycle(opts: SetLifecycleOptions): Promise<Sandbox>;
+}
+
+/**
+ * Pack `dir` as a tar archive for POST /kosa8/v1/templates. Throws when the
+ * Dockerfile is missing, so a bad path fails before anything is sent.
+ */
+declare function tarContext(dir: string, dockerfile?: string): Promise<Buffer>;
+
+/**
+ * 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;
+    /** kosa8 Cloud's stable error code, such as payment_required. */
+    code?: string;
+}
+/** 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;
+    /** kosa8 Cloud's stable error code (payment_required, quota_exceeded, ...). */
+    readonly code?: string;
+    constructor(message: string, options?: Kosa8ErrorOptions);
+}
+/** The daemon could not be reached (no socket, connection refused, ...). */
+declare class Kosa8ConnectionError extends Kosa8Error {
+}
+/**
+ * A call took longer than its timeout. A connection error too, so code that
+ * catches Kosa8ConnectionError keeps catching it.
+ */
+declare class Kosa8TimeoutError extends Kosa8ConnectionError {
+}
+/** 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);
+}
+/** kosa8 Cloud refused new work until a payment method is on file (402). */
+declare class Kosa8PaymentRequiredError extends Kosa8ApiError {
+}
+/** Too many requests or a quota reached (429). */
+declare class Kosa8RateLimitError extends Kosa8ApiError {
+}
+/** 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;
+    code?: string;
+}): Kosa8ApiError;
+
+declare const DEFAULT_CLOUD_URL = "https://api.kosa8.cloud";
+declare const CLOUD_KEY_PREFIX = "k8c_live_";
+interface Kosa8CloudOptions {
+    /** API key. Defaults to the KOSA8_API_KEY environment variable. */
+    apiKey?: string;
+    /** Control-plane address. Defaults to KOSA8_CLOUD_URL, then https://api.kosa8.cloud. */
+    baseUrl?: string;
+    /** Where to read KOSA8_API_KEY and KOSA8_CLOUD_URL from. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** A fetch to use instead of the global one (tests, proxies). */
+    fetch?: typeof fetch;
+    /** Per-request timeout. Default 120 s. */
+    timeoutMs?: number;
+}
+interface CloudSandboxInfo {
+    id: string;
+    state: 'creating' | 'running' | 'sleeping' | 'stopped' | 'deleted' | 'error' | string;
+    template: string;
+    cpus: number;
+    mem_mb: number;
+    source: 'pool' | 'restore' | 'cold' | null;
+    region: string | null;
+    own_host: boolean;
+    created_at: number;
+    started_at: number | null;
+    stopped_at: number | null;
+    deleted_at: number | null;
+    last_error: string | null;
+    running_s: number;
+    asleep_s: number;
+    sleep_bytes: number;
+    cost_usd: number;
+}
+interface CloudCreateOptions {
+    /** Template key, such as base, python or node. Defaults to the org's setting. */
+    template?: string;
+    /** Region id, such as eu-hel1. Defaults to the org's setting (any region). */
+    region?: string;
+    /** Idle seconds before the sandbox sleeps; 0 never. Defaults to the org's setting. */
+    sleepAfterS?: number;
+}
+interface CloudExecOptions {
+    /** Image to run the command in. Defaults to the template's own image. */
+    image?: string;
+    /** Environment variables for the command. */
+    env?: Record<string, string>;
+}
+interface CloudExecResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** Set when the sandbox was asleep and woke for this command. */
+    wokeMs?: number;
+}
+interface CloudInvocation {
+    id: string;
+    function: string;
+    function_id: string;
+    version: number;
+    trigger: 'api' | 'web' | 'map' | 'cron' | string;
+}
+interface CloudInvokeResult<T = unknown> {
+    invocation: CloudInvocation | null;
+    /** False when the handler raised; `error` then says what. */
+    ok: boolean;
+    result?: T;
+    error?: {
+        type: string;
+        message: string;
+    };
+    logs?: string;
+    source?: 'pool' | 'restore' | null;
+    timings_ms?: {
+        start: number | null;
+        run: number | null;
+        host_total: number | null;
+        total: number;
+    };
+}
+interface CloudFunctionSpec {
+    runtime: 'python3.12' | 'node22' | string;
+    code: string;
+    env?: Record<string, string>;
+    timeout_s?: number;
+    web?: 'off' | 'public' | 'key' | string;
+    schedule?: string | null;
+    [k: string]: unknown;
+}
+type Json = Record<string, unknown>;
+/** A client for the kosa8 Cloud control plane. */
+declare class Kosa8Cloud {
+    readonly baseUrl: string;
+    readonly sandboxes: CloudSandboxes;
+    readonly functions: CloudFunctions;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options?: Kosa8CloudOptions);
+    /** The org, the key in use and, for a member's key, the member. */
+    me(): Promise<Json>;
+    /** This month's usage, bill estimate and whether work is paused for payment. */
+    usage(): Promise<Json>;
+    /** @internal */
+    request<T = Json>(method: string, path: string, body?: unknown): Promise<T>;
+}
+declare class CloudSandboxes {
+    private readonly cloud;
+    constructor(cloud: Kosa8Cloud);
+    /** Start a sandbox; resolves once it is running. */
+    create(opts?: CloudCreateOptions): Promise<CloudSandbox>;
+    /** The org's sandboxes; with all, deleted ones too. */
+    list(opts?: {
+        all?: boolean;
+    }): Promise<CloudSandbox[]>;
+    get(id: string): Promise<CloudSandbox>;
+}
+/** One cloud sandbox. `info` is its state as of the last call. */
+declare class CloudSandbox {
+    private readonly cloud;
+    info: CloudSandboxInfo;
+    constructor(cloud: Kosa8Cloud, info: CloudSandboxInfo);
+    get id(): string;
+    private path;
+    /**
+     * Run a command and wait for it. A string runs through `sh -c`. A
+     * sleeping sandbox wakes for it.
+     */
+    exec(cmd: string | string[], opts?: CloudExecOptions): Promise<CloudExecResult>;
+    /** Snapshot it and free its VM; it then costs only snapshot storage. */
+    sleep(): Promise<this>;
+    /** Restore a sleeping sandbox, files and all. */
+    wake(): Promise<this>;
+    refresh(): Promise<this>;
+    delete(): Promise<void>;
+}
+declare class CloudFunctions {
+    private readonly cloud;
+    constructor(cloud: Kosa8Cloud);
+    /** Deploy (create or replace) a function; every deploy bumps its version. */
+    deploy(name: string, spec: CloudFunctionSpec): Promise<Json>;
+    list(): Promise<Json[]>;
+    get(name: string): Promise<Json>;
+    delete(name: string): Promise<void>;
+    /** Call it once. A handler that raises resolves with ok: false, not a throw. */
+    invoke<T = unknown>(name: string, event?: unknown): Promise<CloudInvokeResult<T>>;
+    /** One call per event, results in input order. */
+    map<T = unknown>(name: string, events: unknown[], opts?: {
+        concurrency?: number;
+    }): Promise<{
+        function: string;
+        version: number;
+        count: number;
+        succeeded: number;
+        failed: number;
+        total_ms: number;
+        results: CloudInvokeResult<T>[];
+    }>;
+}
+
+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 BuildTemplateOptions, CLOUD_KEY_PREFIX, type CallOptions, type CaptureSpec, type Checkpoint, CheckpointBook, type CheckpointOptions, type CheckpointResult, type CheckpointStore, type CloudCreateOptions, type CloudExecOptions, type CloudExecResult, type CloudFunctionSpec, CloudFunctions, type CloudInvocation, type CloudInvokeResult, CloudSandbox, type CloudSandboxInfo, CloudSandboxes, type CodeArtifact, type CodeResult, type Container, type CreatePreviewOptions, type CreateSandboxOptions, type CreateSandboxResult, type CreateSessionOptions, DEFAULT_CLOUD_URL, type DeleteSandboxResult, type DeleteSnapshotResult, type EgressPolicy, type EgressPolicyString, type EgressStatus, type ExecOptions, type ExecResult, type ExploreBranch, type ExploreOptions, type ExploreResult, FileCheckpointStore, type FileInfo, type ForkOptions, type ForkResult, type Frame, type GitBranch, type GitCommit, type GitCommitOptions, type GitFileStatus, type GitOp, type GitOptions, type GitResult, type GitStatus, type Health, Kosa8ApiError, Kosa8ApprovalRequiredError, Kosa8AuthError, Kosa8BadRequestError, Kosa8CheckpointError, Kosa8Client, type Kosa8ClientOptions, Kosa8Cloud, type Kosa8CloudOptions, Kosa8ConflictError, Kosa8ConnectionError, Kosa8Error, Kosa8NotFoundError, Kosa8PaymentRequiredError, Kosa8PolicyError, Kosa8RateLimitError, Kosa8StreamError, Kosa8TimeoutError, Kosa8UnsupportedError, type Lifecycle, MAX_CHECKPOINTS_PER_SANDBOX, MemoryCheckpointStore, type Mount, type Preview, type RequestOptions, type RestoreOptions, type RestoreResult, type RewindOptions, type RewindResult, type RunCodeOptions, type RunOptions, type Sandbox, SandboxHandle, type SessionExecOptions, type SessionInfo, type SetLifecycleOptions, type ShellOptions, type ShellResult, type Snapshot, type SnapshotSandboxResult, type StartPtyOptions, type StartSandboxResult, type StopSandboxResult, type Template, Transport, type TransportOptions, type WriteFileOptions, defaultSocketPath, defaultWorkerFile, errorFromResponse, resolveEndpoint, tarContext, validateSandboxName };