@hotcell/daemon 0.1.0

package/dist/driver/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/driver/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,yDAAyD;AACzD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,CAAU,CAAC;AAE7E;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,iBAAiB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,MAAc;IAC5D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,WAAW;YACd,OAAO,IAAI,eAAe,CAAC,SAAS,EAAE;gBACpC,OAAO,EAAE,MAAM,CAAC,aAAa;gBAC7B,OAAO,EAAE,MAAM,CAAC,aAAa;gBAC7B,MAAM,EAAE,MAAM,CAAC,YAAY;gBAC3B,GAAG,EAAE,MAAM,CAAC,iBAAiB;aAC9B,CAAC,CAAC;QACL,KAAK,aAAa;YAChB,OAAO,IAAI,iBAAiB,CAAC;gBAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,MAAM,CAAC,QAAQ;gBACvB,MAAM,EAAE,MAAM,CAAC,QAAQ;gBACvB,QAAQ,EAAE,MAAM,CAAC,UAAU;gBAC3B,MAAM,EAAE,MAAM,CAAC,QAAQ;gBACvB,aAAa,EAAE,MAAM,CAAC,eAAe;gBACrC,QAAQ,EAAE,MAAM,CAAC,UAAU;gBAC3B,+DAA+D;gBAC/D,SAAS,EAAE,MAAM,CAAC,YAAY;gBAC9B,uDAAuD;gBACvD,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,UAAU,EAAE,MAAM,CAAC,IAAI;aACxB,CAAC,CAAC;QACL,KAAK,SAAS;YACZ,OAAO,IAAI,aAAa,CAAC;gBACvB,UAAU,EAAE,MAAM,CAAC,YAAY;gBAC/B,MAAM,EAAE,MAAM,CAAC,QAAQ;gBACvB,MAAM,EAAE,MAAM,CAAC,QAAQ;gBACvB,QAAQ,EAAE,MAAM,CAAC,UAAU;gBAC3B,MAAM,EAAE,MAAM,CAAC,QAAQ;gBACvB,aAAa,EAAE,MAAM,CAAC,eAAe;gBACrC,QAAQ,EAAE,MAAM,CAAC,UAAU;gBAC3B,uDAAuD;gBACvD,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,UAAU,EAAE,MAAM,CAAC,IAAI;aACxB,CAAC,CAAC;QACL;YACE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,gBAAgB,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxF,CAAC;AACH,CAAC"}

package/dist/driver/router.d.ts

@@ -0,0 +1,82 @@
+import type { Config } from "../config.js";
+import type { SandboxStore } from "../store.js";
+import type { ExecEvent, ExecOptions, FileChangeEvent, FileInfo, ListFilesOptions, MkdirOptions, ReadFileOptions, StartProcessOptions, WaitForPortOptions, WatchOptions, WriteFileOptions } from "../types.js";
+import type { CreateOptions, Driver, HostInfo, ProcessLiveness, SandboxStats, StartProcessResult, TcpBridge, TerminalOptions, TerminalSession } from "./types.js";
+/**
+ * Per-sandbox driver router. Implements the `Driver` surface but, instead of
+ * doing the work itself, dispatches each call to the runtime driver that backs
+ * the addressed sandbox — so a single daemon can run container sandboxes and
+ * Apple VZ microVM sandboxes side by side ("swap the isolation tier per sandbox,
+ * change nothing else"). Every existing `driver.<op>(id, …)` call site keeps
+ * working unchanged; the routing happens here.
+ *
+ * The sandbox→driver mapping is the record's `driver` field (set at create from
+ * the request, persisted in the store). `create`/`start` carry the choice on
+ * their `CreateOptions`; id-addressed ops read it back from the store. An unset
+ * or unknown value falls back to the daemon default driver. Driver instances are
+ * built lazily by name and cached, so an unused driver is never constructed.
+ */
+export declare class DriverRouter implements Driver {
+    private readonly config;
+    private readonly store;
+    private readonly defaultName;
+    readonly name: string;
+    private instances;
+    constructor(config: Config, store: SandboxStore, defaultName: string);
+    /** Get (constructing + caching on first use) the driver instance for a name. */
+    private instance;
+    /** The driver backing an existing sandbox (from its record), or the default. */
+    private forId;
+    /** The driver chosen for a create/start (opts wins, then the record, then default). */
+    private forOpts;
+    create(opts: CreateOptions): Promise<void>;
+    start(opts: CreateOptions): Promise<void>;
+    stop(id: string): Promise<void>;
+    /** Fast-pause via the backing driver, or `stop` when it doesn't support
+     *  snapshots — so callers can always call `snapshot` through the router and
+     *  get the strongest pause the sandbox's isolation tier offers. */
+    snapshot(id: string): Promise<void>;
+    /** Whether the backing driver can memory-snapshot this sandbox right now. */
+    canSnapshot(id: string): boolean;
+    destroy(id: string): Promise<void>;
+    exec(id: string, command: string, opts: ExecOptions, onEvent: (e: ExecEvent) => void): Promise<number>;
+    writeFile(id: string, opts: WriteFileOptions): Promise<void>;
+    readFile(id: string, opts: ReadFileOptions): Promise<string>;
+    mkdir(id: string, opts: MkdirOptions): Promise<void>;
+    listFiles(id: string, opts: ListFilesOptions): Promise<FileInfo[]>;
+    watchFiles(id: string, path: string, opts: WatchOptions & {
+        signal: AbortSignal;
+    }, onEvent: (e: FileChangeEvent) => void): Promise<void>;
+    startProcess(id: string, procId: string, command: string, opts: StartProcessOptions): Promise<StartProcessResult>;
+    listProcesses(id: string, procs: Array<{
+        procId: string;
+        pid: number;
+    }>): Promise<ProcessLiveness[]>;
+    killProcess(id: string, pid: number, signal?: string): Promise<void>;
+    streamProcessLogs(id: string, logPath: string, opts: {
+        follow: boolean;
+        signal: AbortSignal;
+    }, onData: (chunk: string) => void): Promise<void>;
+    waitForPort(id: string, port: number, opts: WaitForPortOptions): Promise<boolean>;
+    openTcpBridge(id: string, port: number, host: string): Promise<TcpBridge>;
+    openTerminal(id: string, opts: TerminalOptions): Promise<TerminalSession>;
+    createBackup(id: string, tarPath: string): Promise<{
+        bytes: number;
+    }>;
+    restoreBackup(id: string, tarPath: string): Promise<void>;
+    stats(id: string): Promise<SandboxStats>;
+    /** Ping the default driver — the daemon's fail-fast startup check. Other
+     *  drivers are validated lazily when a sandbox first selects them. */
+    ping(): Promise<void>;
+    /**
+     * Host capacity for admission control. All drivers describe the same physical
+     * host, but each sees it differently — Docker Desktop on macOS reports its own
+     * VM's memory, not the Mac's — so ask every instantiated driver and take the
+     * most complete view (max). Committed-memory accounting is already
+     * driver-agnostic (it sums per-sandbox caps from the store).
+     */
+    hostInfo(): Promise<HostInfo>;
+    /** Best-effort teardown of any driver-held background resources (e.g. the VZ
+     *  warm pool's pre-booted spare VMs) on daemon shutdown. */
+    shutdown(): Promise<void>;
+}

package/dist/driver/router.js

@@ -0,0 +1,159 @@
+import { createNamedDriver } from "./index.js";
+/**
+ * Per-sandbox driver router. Implements the `Driver` surface but, instead of
+ * doing the work itself, dispatches each call to the runtime driver that backs
+ * the addressed sandbox — so a single daemon can run container sandboxes and
+ * Apple VZ microVM sandboxes side by side ("swap the isolation tier per sandbox,
+ * change nothing else"). Every existing `driver.<op>(id, …)` call site keeps
+ * working unchanged; the routing happens here.
+ *
+ * The sandbox→driver mapping is the record's `driver` field (set at create from
+ * the request, persisted in the store). `create`/`start` carry the choice on
+ * their `CreateOptions`; id-addressed ops read it back from the store. An unset
+ * or unknown value falls back to the daemon default driver. Driver instances are
+ * built lazily by name and cached, so an unused driver is never constructed.
+ */
+export class DriverRouter {
+    config;
+    store;
+    defaultName;
+    name;
+    instances = new Map();
+    constructor(config, store, defaultName) {
+        this.config = config;
+        this.store = store;
+        this.defaultName = defaultName;
+        this.name = defaultName;
+    }
+    /** Get (constructing + caching on first use) the driver instance for a name. */
+    instance(name) {
+        const key = name || this.defaultName;
+        let d = this.instances.get(key);
+        if (!d) {
+            d = createNamedDriver(key, this.config);
+            this.instances.set(key, d);
+        }
+        return d;
+    }
+    /** The driver backing an existing sandbox (from its record), or the default. */
+    forId(id) {
+        return this.instance(this.store.get(id)?.driver);
+    }
+    /** The driver chosen for a create/start (opts wins, then the record, then default). */
+    forOpts(opts) {
+        return this.instance(opts.driver ?? this.store.get(opts.id)?.driver);
+    }
+    // --- lifecycle (choice carried on opts) -----------------------------------
+    create(opts) {
+        return this.forOpts(opts).create(opts);
+    }
+    start(opts) {
+        return this.forOpts(opts).start(opts);
+    }
+    stop(id) {
+        return this.forId(id).stop(id);
+    }
+    /** Fast-pause via the backing driver, or `stop` when it doesn't support
+     *  snapshots — so callers can always call `snapshot` through the router and
+     *  get the strongest pause the sandbox's isolation tier offers. */
+    snapshot(id) {
+        const d = this.forId(id);
+        return typeof d.snapshot === "function" ? d.snapshot(id) : d.stop(id);
+    }
+    /** Whether the backing driver can memory-snapshot this sandbox right now. */
+    canSnapshot(id) {
+        const d = this.forId(id);
+        return typeof d.snapshot === "function" && (d.canSnapshot ? d.canSnapshot(id) : true);
+    }
+    destroy(id) {
+        return this.forId(id).destroy(id);
+    }
+    // --- id-addressed ops (driver resolved from the record) -------------------
+    exec(id, command, opts, onEvent) {
+        return this.forId(id).exec(id, command, opts, onEvent);
+    }
+    writeFile(id, opts) {
+        return this.forId(id).writeFile(id, opts);
+    }
+    readFile(id, opts) {
+        return this.forId(id).readFile(id, opts);
+    }
+    mkdir(id, opts) {
+        return this.forId(id).mkdir(id, opts);
+    }
+    listFiles(id, opts) {
+        return this.forId(id).listFiles(id, opts);
+    }
+    watchFiles(id, path, opts, onEvent) {
+        return this.forId(id).watchFiles(id, path, opts, onEvent);
+    }
+    startProcess(id, procId, command, opts) {
+        return this.forId(id).startProcess(id, procId, command, opts);
+    }
+    listProcesses(id, procs) {
+        return this.forId(id).listProcesses(id, procs);
+    }
+    killProcess(id, pid, signal) {
+        return this.forId(id).killProcess(id, pid, signal);
+    }
+    streamProcessLogs(id, logPath, opts, onData) {
+        return this.forId(id).streamProcessLogs(id, logPath, opts, onData);
+    }
+    waitForPort(id, port, opts) {
+        return this.forId(id).waitForPort(id, port, opts);
+    }
+    openTcpBridge(id, port, host) {
+        return this.forId(id).openTcpBridge(id, port, host);
+    }
+    openTerminal(id, opts) {
+        return this.forId(id).openTerminal(id, opts);
+    }
+    createBackup(id, tarPath) {
+        return this.forId(id).createBackup(id, tarPath);
+    }
+    restoreBackup(id, tarPath) {
+        return this.forId(id).restoreBackup(id, tarPath);
+    }
+    stats(id) {
+        return this.forId(id).stats(id);
+    }
+    // --- host-level (default driver) ------------------------------------------
+    /** Ping the default driver — the daemon's fail-fast startup check. Other
+     *  drivers are validated lazily when a sandbox first selects them. */
+    ping() {
+        return this.instance(this.defaultName).ping();
+    }
+    /**
+     * Host capacity for admission control. All drivers describe the same physical
+     * host, but each sees it differently — Docker Desktop on macOS reports its own
+     * VM's memory, not the Mac's — so ask every instantiated driver and take the
+     * most complete view (max). Committed-memory accounting is already
+     * driver-agnostic (it sums per-sandbox caps from the store).
+     */
+    async hostInfo() {
+        const drivers = new Set([this.instance(this.defaultName), ...this.instances.values()]);
+        let best = { memoryMb: 0, cpus: 0 };
+        for (const d of drivers) {
+            try {
+                const h = await d.hostInfo();
+                best = { memoryMb: Math.max(best.memoryMb, h.memoryMb), cpus: Math.max(best.cpus, h.cpus) };
+            }
+            catch {
+                /* an unavailable driver (e.g. Docker down) shouldn't break capacity */
+            }
+        }
+        if (best.memoryMb === 0)
+            return this.instance(this.defaultName).hostInfo();
+        return best;
+    }
+    /** Best-effort teardown of any driver-held background resources (e.g. the VZ
+     *  warm pool's pre-booted spare VMs) on daemon shutdown. */
+    async shutdown() {
+        for (const d of this.instances.values()) {
+            const drain = d.drainPool;
+            if (typeof drain === "function")
+                await drain.call(d).catch(() => { });
+        }
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/driver/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/driver/router.ts"],"names":[],"mappings":"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"}

package/dist/driver/types.d.ts

@@ -0,0 +1,234 @@
+import type { ExecEvent, ExecOptions, FileChangeEvent, FileInfo, ListFilesOptions, MkdirOptions, ReadFileOptions, ResourceLimits, StartProcessOptions, WaitForPortOptions, WatchOptions, WriteFileOptions } from "../types.js";
+export type { ResourceLimits } from "../types.js";
+/** A live bidirectional byte stream bridged to a port inside a sandbox. */
+export interface TcpBridge {
+    /** Raw duplex carrying bytes to/from the in-container TCP relay. */
+    stream: NodeJS.ReadWriteStream;
+    /** Tear down the bridge and the in-container relay process. */
+    close(): void;
+}
+/** Options for opening an interactive terminal (PTY) inside a sandbox. */
+export interface TerminalOptions {
+    /** Initial terminal width in columns. */
+    cols?: number;
+    /** Initial terminal height in rows. */
+    rows?: number;
+    cwd?: string;
+    env?: Record<string, string>;
+}
+/**
+ * A live interactive shell (PTY) inside a sandbox. `stream` is a raw duplex:
+ * write bytes to send keystrokes to the shell's stdin, read bytes to receive its
+ * terminal output (already TTY-cooked, no Docker stream framing). This is the
+ * interactive-exec primitive the in-sandbox agent (Phase 3) and the dashboard
+ * terminal both build on.
+ */
+export interface TerminalSession {
+    stream: NodeJS.ReadWriteStream;
+    /** Inform the PTY of a new client window size. */
+    resize(cols: number, rows: number): void;
+    /** Tear down the shell and its exec. */
+    close(): void;
+}
+/** Result of launching a background process. */
+export interface StartProcessResult {
+    procId: string;
+    pid: number;
+    logPath: string;
+}
+/** Liveness view of a tracked background process. */
+export interface ProcessLiveness {
+    procId: string;
+    pid: number;
+    running: boolean;
+}
+/** A point-in-time resource snapshot for a running sandbox. */
+export interface SandboxStats {
+    /** Instantaneous CPU usage as a percent of one core (can exceed 100). */
+    cpuPercent: number;
+    /** Cumulative CPU time the container has consumed, in nanoseconds (resets on
+     * container recreation). The cost meter integrates the delta of this. */
+    cpuTotalUsageNs: number;
+    /** Number of CPUs visible to the container (CPU% is over all of them). */
+    onlineCpus: number;
+    /** Resident memory in bytes (page cache excluded where the runtime reports it). */
+    memBytes: number;
+    /** Memory limit in bytes (0 if unlimited/unknown). */
+    memLimitBytes: number;
+    /** Cumulative network bytes received across all interfaces. */
+    netRxBytes: number;
+    /** Cumulative network bytes transmitted across all interfaces. */
+    netTxBytes: number;
+    /** Number of processes/threads in the container. */
+    pids: number;
+    /** ISO timestamp the snapshot was taken. */
+    sampledAt: string;
+}
+export interface CreateOptions {
+    id: string;
+    image: string;
+    /**
+     * Runtime driver to back this sandbox (per-sandbox isolation selection). The
+     * `DriverRouter` reads it to dispatch `create`/`start`; later id-addressed ops
+     * resolve the driver from the sandbox record. Empty → the daemon default.
+     */
+    driver?: string;
+    env?: Record<string, string>;
+    labels?: Record<string, string>;
+    /**
+     * Back `/workspace` with a named volume so files outlive the container. With
+     * persistence the container is cattle: `stop` removes it, `start` recreates it,
+     * and the workspace survives. Defaults to true.
+     */
+    persist?: boolean;
+    /**
+     * Ordered shell commands run once, after the container starts at create time
+     * (e.g. `npm i kimiflare`). Best-effort: a non-zero exit is logged, not fatal.
+     * Not re-run on resume — with persistence the workspace already has the result.
+     */
+    setup?: string[];
+    /**
+     * Git repository URL cloned into `/workspace` at create time (before `setup`),
+     * so an agent comes up with the code in place. Private repos: embed a token in
+     * the URL (`https://<token>@github.com/owner/repo.git`). A clone failure fails
+     * create (unlike best-effort `setup`).
+     */
+    repo?: string;
+    /** Branch/tag to check out when cloning `repo` (default: the repo's default branch). */
+    repoRef?: string;
+    /** Hard CPU/memory/PID caps for the sandbox (resolved effective values). */
+    limits?: ResourceLimits;
+}
+/**
+ * Runtime-driver interface — the core abstraction of sbx.
+ *
+ * Phase 0 ships the `container` driver (Docker Engine API). Future drivers
+ * (`firecracker` on Linux, `applevz` on macOS) implement this same surface so
+ * the daemon, SDK, and CLI are unchanged when you swap isolation tiers.
+ *
+ * Drivers are addressed by the public sandbox `id`; they derive their own
+ * backing-resource name from it and stay otherwise stateless.
+ */
+export interface Driver {
+    readonly name: string;
+    /** Provision and start a sandbox (creating its persistent volume if needed). */
+    create(opts: CreateOptions): Promise<void>;
+    /**
+     * Stop a sandbox, freeing its compute. With persistence the container is
+     * removed but its workspace volume is kept, so `start` can recreate it with
+     * the data intact. In-container processes do not survive a stop.
+     */
+    stop(id: string): Promise<void>;
+    /**
+     * (Re)create and start a sandbox's container, reattaching its persistent
+     * volume. Used to resume a stopped sandbox; the workspace is preserved.
+     */
+    start(opts: CreateOptions): Promise<void>;
+    /**
+     * Optional fast-pause: save the sandbox's full live state (guest RAM + device
+     * state) to disk and free its compute, such that the next `start` resumes
+     * **without a kernel boot** — background processes/servers come back live.
+     * Only microVM drivers can implement this; callers must feature-detect
+     * (`typeof driver.snapshot === "function"`) and fall back to `stop`, whose
+     * contract (workspace survives, processes don't) is the lowest common
+     * denominator. Implementations must sync the guest fs first so a restore
+     * failure can safely degrade to a cold boot with the workspace intact.
+     */
+    snapshot?(id: string): Promise<void>;
+    /**
+     * Whether `snapshot` can fast-pause this sandbox *right now* (VM live, host
+     * OS supports save/restore). Callers use this to pick pause semantics up
+     * front — e.g. the idle reaper only pauses a sandbox with running background
+     * processes when they'll survive the resume.
+     */
+    canSnapshot?(id: string): boolean;
+    /**
+     * Run a command inside the sandbox, streaming output via `onEvent`.
+     * Resolves with the process exit code.
+     */
+    exec(id: string, command: string, opts: ExecOptions, onEvent: (e: ExecEvent) => void): Promise<number>;
+    /** Write a file inside the sandbox. */
+    writeFile(id: string, opts: WriteFileOptions): Promise<void>;
+    /** Read a file from the sandbox, returning its UTF-8 contents. */
+    readFile(id: string, opts: ReadFileOptions): Promise<string>;
+    /** Create a directory inside the sandbox. */
+    mkdir(id: string, opts: MkdirOptions): Promise<void>;
+    /** List files and directories at the given path. */
+    listFiles(id: string, opts: ListFilesOptions): Promise<FileInfo[]>;
+    /**
+     * Watch a path (recursively) for file changes, invoking `onEvent` per change
+     * until `opts.signal` aborts. Resolves when watching stops.
+     */
+    watchFiles(id: string, path: string, opts: WatchOptions & {
+        signal: AbortSignal;
+    }, onEvent: (e: FileChangeEvent) => void): Promise<void>;
+    /**
+     * Launch a detached background process. `procId` is daemon-supplied so the
+     * in-container logfile is deterministic. Resolves once the process is spawned.
+     */
+    startProcess(id: string, procId: string, command: string, opts: StartProcessOptions): Promise<StartProcessResult>;
+    /** Report liveness for the given in-container PIDs. */
+    listProcesses(id: string, procs: Array<{
+        procId: string;
+        pid: number;
+    }>): Promise<ProcessLiveness[]>;
+    /** Send a signal to a process group (default TERM). */
+    killProcess(id: string, pid: number, signal?: string): Promise<void>;
+    /** Stream a process logfile to `onData`; `follow` tails it until aborted. */
+    streamProcessLogs(id: string, logPath: string, opts: {
+        follow: boolean;
+        signal: AbortSignal;
+    }, onData: (chunk: string) => void): Promise<void>;
+    /** Block until a TCP port is listening inside the sandbox, or timeout. */
+    waitForPort(id: string, port: number, opts: WaitForPortOptions): Promise<boolean>;
+    /**
+     * Open a raw bidirectional byte bridge to `host:port` inside the sandbox.
+     * Used by the preview-URL proxy; goes through the Docker socket so it works
+     * even where container IPs are unreachable from the host (macOS Docker Desktop).
+     */
+    openTcpBridge(id: string, port: number, host: string): Promise<TcpBridge>;
+    /**
+     * Open an interactive shell (PTY) inside the sandbox. Returns a duplex byte
+     * stream (write = stdin, read = terminal output) plus resize/close controls.
+     * Backs the dashboard's live terminal over WebSocket. The sandbox must be live.
+     */
+    openTerminal(id: string, opts: TerminalOptions): Promise<TerminalSession>;
+    /**
+     * Archive the sandbox's `/workspace` to a tar file at `tarPath` on the daemon
+     * host. Returns the number of bytes written. The sandbox must be running.
+     */
+    createBackup(id: string, tarPath: string): Promise<{
+        bytes: number;
+    }>;
+    /**
+     * Replace the sandbox's `/workspace` with the contents of the tar at
+     * `tarPath`. Existing workspace contents are cleared first. The sandbox must
+     * be running; the backup may originate from a different sandbox.
+     */
+    restoreBackup(id: string, tarPath: string): Promise<void>;
+    /**
+     * Permanently destroy the sandbox and free its resources, including its
+     * persistent workspace volume. This is irreversible — use `stop` to pause.
+     */
+    destroy(id: string): Promise<void>;
+    /**
+     * Snapshot the sandbox's live resource usage (CPU, memory, network, pids).
+     * The sandbox must be running.
+     */
+    stats(id: string): Promise<SandboxStats>;
+    /** Liveness check for the underlying runtime (e.g. Docker daemon reachable). */
+    ping(): Promise<void>;
+    /**
+     * Total host capacity available to the runtime — total memory (MiB) and CPU
+     * count. Backs the capacity meter + admission control. For the container
+     * driver this is the Docker host/VM's `MemTotal` / `NCPU`.
+     */
+    hostInfo(): Promise<HostInfo>;
+}
+/** Total host capacity as seen by the runtime. */
+export interface HostInfo {
+    /** Total memory available to the runtime, in MiB. */
+    memoryMb: number;
+    /** Number of CPUs available to the runtime. */
+    cpus: number;
+}

package/dist/driver/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/driver/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/driver/types.ts"],"names":[],"mappings":""}

package/dist/driver/unsupported.d.ts

@@ -0,0 +1,50 @@
+import type { CreateOptions, Driver, HostInfo, ProcessLiveness, SandboxStats, StartProcessResult, TcpBridge, TerminalOptions, TerminalSession } from "./types.js";
+import type { ExecEvent, ExecOptions, FileChangeEvent, FileInfo, ListFilesOptions, MkdirOptions, ReadFileOptions, StartProcessOptions, WaitForPortOptions, WatchOptions, WriteFileOptions } from "../types.js";
+/**
+ * Base class for runtime drivers that are part of the architecture but not yet
+ * built (the Phase 3 microVM drivers). It implements the whole `Driver` surface
+ * so the seam — driver selection, the daemon/SDK/CLI layering — is real and
+ * compiles today; every operation throws a clear "not implemented" error, and
+ * each concrete subclass overrides `ping()` to explain what host support it needs.
+ *
+ * When a microVM driver is actually implemented (on a KVM Linux box / a Mac with
+ * Virtualization.framework) it stops extending this and implements the methods
+ * for real — nothing else in the codebase changes.
+ */
+export declare abstract class UnsupportedDriver implements Driver {
+    abstract readonly name: string;
+    /** Subclasses throw a host-specific "this driver needs X" error here. */
+    abstract ping(): Promise<void>;
+    protected fail(op: string): never;
+    create(_opts: CreateOptions): Promise<void>;
+    stop(_id: string): Promise<void>;
+    start(_opts: CreateOptions): Promise<void>;
+    exec(_id: string, _command: string, _opts: ExecOptions, _onEvent: (e: ExecEvent) => void): Promise<number>;
+    writeFile(_id: string, _opts: WriteFileOptions): Promise<void>;
+    readFile(_id: string, _opts: ReadFileOptions): Promise<string>;
+    mkdir(_id: string, _opts: MkdirOptions): Promise<void>;
+    listFiles(_id: string, _opts: ListFilesOptions): Promise<FileInfo[]>;
+    watchFiles(_id: string, _path: string, _opts: WatchOptions & {
+        signal: AbortSignal;
+    }, _onEvent: (e: FileChangeEvent) => void): Promise<void>;
+    startProcess(_id: string, _procId: string, _command: string, _opts: StartProcessOptions): Promise<StartProcessResult>;
+    listProcesses(_id: string, _procs: Array<{
+        procId: string;
+        pid: number;
+    }>): Promise<ProcessLiveness[]>;
+    killProcess(_id: string, _pid: number, _signal?: string): Promise<void>;
+    streamProcessLogs(_id: string, _logPath: string, _opts: {
+        follow: boolean;
+        signal: AbortSignal;
+    }, _onData: (chunk: string) => void): Promise<void>;
+    waitForPort(_id: string, _port: number, _opts: WaitForPortOptions): Promise<boolean>;
+    openTcpBridge(_id: string, _port: number, _host: string): Promise<TcpBridge>;
+    openTerminal(_id: string, _opts: TerminalOptions): Promise<TerminalSession>;
+    createBackup(_id: string, _tarPath: string): Promise<{
+        bytes: number;
+    }>;
+    restoreBackup(_id: string, _tarPath: string): Promise<void>;
+    destroy(_id: string): Promise<void>;
+    stats(_id: string): Promise<SandboxStats>;
+    hostInfo(): Promise<HostInfo>;
+}

package/dist/driver/unsupported.js

@@ -0,0 +1,81 @@
+/**
+ * Base class for runtime drivers that are part of the architecture but not yet
+ * built (the Phase 3 microVM drivers). It implements the whole `Driver` surface
+ * so the seam — driver selection, the daemon/SDK/CLI layering — is real and
+ * compiles today; every operation throws a clear "not implemented" error, and
+ * each concrete subclass overrides `ping()` to explain what host support it needs.
+ *
+ * When a microVM driver is actually implemented (on a KVM Linux box / a Mac with
+ * Virtualization.framework) it stops extending this and implements the methods
+ * for real — nothing else in the codebase changes.
+ */
+export class UnsupportedDriver {
+    fail(op) {
+        throw new Error(`driver "${this.name}" does not implement ${op} yet — it is a planned ` +
+            `Phase 3 microVM driver (see docs/plan.md). Use SBX_DRIVER=container.`);
+    }
+    async create(_opts) {
+        this.fail("create");
+    }
+    async stop(_id) {
+        this.fail("stop");
+    }
+    async start(_opts) {
+        this.fail("start");
+    }
+    async exec(_id, _command, _opts, _onEvent) {
+        this.fail("exec");
+    }
+    async writeFile(_id, _opts) {
+        this.fail("writeFile");
+    }
+    async readFile(_id, _opts) {
+        this.fail("readFile");
+    }
+    async mkdir(_id, _opts) {
+        this.fail("mkdir");
+    }
+    async listFiles(_id, _opts) {
+        this.fail("listFiles");
+    }
+    async watchFiles(_id, _path, _opts, _onEvent) {
+        this.fail("watchFiles");
+    }
+    async startProcess(_id, _procId, _command, _opts) {
+        this.fail("startProcess");
+    }
+    async listProcesses(_id, _procs) {
+        this.fail("listProcesses");
+    }
+    async killProcess(_id, _pid, _signal) {
+        this.fail("killProcess");
+    }
+    async streamProcessLogs(_id, _logPath, _opts, _onData) {
+        this.fail("streamProcessLogs");
+    }
+    async waitForPort(_id, _port, _opts) {
+        this.fail("waitForPort");
+    }
+    async openTcpBridge(_id, _port, _host) {
+        this.fail("openTcpBridge");
+    }
+    async openTerminal(_id, _opts) {
+        this.fail("openTerminal");
+    }
+    async createBackup(_id, _tarPath) {
+        this.fail("createBackup");
+    }
+    async restoreBackup(_id, _tarPath) {
+        this.fail("restoreBackup");
+    }
+    async destroy(_id) {
+        this.fail("destroy");
+    }
+    async stats(_id) {
+        this.fail("stats");
+    }
+    async hostInfo() {
+        this.fail("hostInfo");
+    }
+}
+//# sourceMappingURL=unsupported.js.map

package/dist/driver/unsupported.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsupported.js","sourceRoot":"","sources":["../../src/driver/unsupported.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;GAUG;AACH,MAAM,OAAgB,iBAAiB;IAM3B,IAAI,CAAC,EAAU;QACvB,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,CAAC,IAAI,wBAAwB,EAAE,yBAAyB;YACrE,sEAAsE,CACzE,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAoB;QAC/B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,KAAoB;QAC9B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC;IACD,KAAK,CAAC,IAAI,CACR,GAAW,EACX,QAAgB,EAChB,KAAkB,EAClB,QAAgC;QAEhC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IACD,KAAK,CAAC,SAAS,CAAC,GAAW,EAAE,KAAuB;QAClD,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACzB,CAAC;IACD,KAAK,CAAC,QAAQ,CAAC,GAAW,EAAE,KAAsB;QAChD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACxB,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,KAAmB;QAC1C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC;IACD,KAAK,CAAC,SAAS,CAAC,GAAW,EAAE,KAAuB;QAClD,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACzB,CAAC;IACD,KAAK,CAAC,UAAU,CACd,GAAW,EACX,KAAa,EACb,KAA6C,EAC7C,QAAsC;QAEtC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,CAAC,YAAY,CAChB,GAAW,EACX,OAAe,EACf,QAAgB,EAChB,KAA0B;QAE1B,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,CAAC,aAAa,CACjB,GAAW,EACX,MAA8C;QAE9C,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC7B,CAAC;IACD,KAAK,CAAC,WAAW,CAAC,GAAW,EAAE,IAAY,EAAE,OAAgB;QAC3D,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC3B,CAAC;IACD,KAAK,CAAC,iBAAiB,CACrB,GAAW,EACX,QAAgB,EAChB,KAA+C,EAC/C,OAAgC;QAEhC,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACjC,CAAC;IACD,KAAK,CAAC,WAAW,CAAC,GAAW,EAAE,KAAa,EAAE,KAAyB;QACrE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC3B,CAAC;IACD,KAAK,CAAC,aAAa,CAAC,GAAW,EAAE,KAAa,EAAE,KAAa;QAC3D,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC7B,CAAC;IACD,KAAK,CAAC,YAAY,CAAC,GAAW,EAAE,KAAsB;QACpD,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,CAAC,YAAY,CAAC,GAAW,EAAE,QAAgB;QAC9C,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,CAAC,aAAa,CAAC,GAAW,EAAE,QAAgB;QAC/C,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC7B,CAAC;IACD,KAAK,CAAC,OAAO,CAAC,GAAW;QACvB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACvB,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,GAAW;QACrB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC;IACD,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACxB,CAAC;CACF"}