@hotcell/daemon 0.1.0

package/dist/fc-check.js

@@ -0,0 +1,113 @@
+/**
+ * Firecracker host-agnostic check. Exercises the pieces of the `firecracker`
+ * driver that need no `/dev/kvm` — the API-call builders, the vsock CONNECT
+ * handshake parser, and the driver's fail-fast `ping`/`hostInfo` — so the
+ * Linux-specific code is validated on any host (incl. this Mac / CI). The live
+ * boot is gated behind `smoke:fc` on a KVM box. Run: `npm run check:fc`.
+ */
+import assert from "node:assert/strict";
+import { buildFcApiCalls, buildSnapshotCreateCall, buildSnapshotLoadCall, FC_DEFAULT_BOOT_ARGS, FC_PAUSE_VM, FC_START_ACTION, parseVsockHandshake, } from "./driver/fc-api.js";
+import { FirecrackerDriver } from "./driver/firecracker.js";
+let passed = 0;
+const ok = (l) => {
+    passed++;
+    console.log(`  ✓ ${l}`);
+};
+async function main() {
+    // 1. API calls fully configure a VM in the right order with the right shapes.
+    const calls = buildFcApiCalls({
+        kernelPath: "/k/vmlinux",
+        rootfsPath: "/k/rootfs.img",
+        workspacePath: "/k/ws.img",
+        vcpus: 2,
+        memMib: 512,
+        vsockUds: "/k/v.sock",
+    });
+    assert.deepEqual(calls.map((c) => c.path), ["/boot-source", "/machine-config", "/drives/rootfs", "/drives/workspace", "/vsock"], "API calls cover boot/machine/drives/vsock in order");
+    const boot = calls[0].body;
+    assert.equal(boot.kernel_image_path, "/k/vmlinux");
+    assert.equal(boot.boot_args, FC_DEFAULT_BOOT_ARGS);
+    const mc = calls[1].body;
+    assert.equal(mc.vcpu_count, 2);
+    assert.equal(mc.mem_size_mib, 512);
+    // The root device is /dev/vda (ro), the workspace /dev/vdb (rw) — matches the
+    // shared guest init that mounts /dev/vdb at /workspace.
+    const rootDrive = calls[2].body;
+    assert.equal(rootDrive.is_root_device, true);
+    assert.equal(rootDrive.is_read_only, true);
+    const wsDrive = calls[3].body;
+    assert.equal(wsDrive.is_root_device, false);
+    assert.equal(wsDrive.is_read_only, false);
+    const vsock = calls[4].body;
+    assert.equal(vsock.uds_path, "/k/v.sock");
+    assert.equal(vsock.guest_cid, 3);
+    ok("buildFcApiCalls: correct order, shapes, and vda(ro)/vdb(rw) drive layout");
+    assert.equal(FC_START_ACTION.body.action_type, "InstanceStart");
+    ok("FC_START_ACTION boots the VM");
+    // 1b. Snapshot API calls: pause → create(Full) → load(File mem backend, resume).
+    assert.equal(FC_PAUSE_VM.method, "PATCH");
+    assert.equal(FC_PAUSE_VM.path, "/vm");
+    assert.equal(FC_PAUSE_VM.body.state, "Paused");
+    const snapCreate = buildSnapshotCreateCall("/s/x.vmstate", "/s/x.mem");
+    assert.equal(snapCreate.path, "/snapshot/create");
+    const scBody = snapCreate.body;
+    assert.equal(scBody.snapshot_type, "Full");
+    assert.equal(scBody.snapshot_path, "/s/x.vmstate");
+    assert.equal(scBody.mem_file_path, "/s/x.mem");
+    const snapLoad = buildSnapshotLoadCall("/s/x.vmstate", "/s/x.mem");
+    assert.equal(snapLoad.path, "/snapshot/load");
+    const slBody = snapLoad.body;
+    assert.equal(slBody.snapshot_path, "/s/x.vmstate");
+    assert.equal(slBody.mem_backend.backend_type, "File");
+    assert.equal(slBody.mem_backend.backend_path, "/s/x.mem");
+    assert.equal(slBody.resume_vm, true);
+    ok("snapshot API calls: PATCH /vm Paused → /snapshot/create(Full) → /snapshot/load(resume)");
+    // 2. Custom boot args (e.g. the pidsLimit cmdline) pass through.
+    const withPids = buildFcApiCalls({
+        kernelPath: "/k",
+        rootfsPath: "/r",
+        workspacePath: "/w",
+        vcpus: 1,
+        memMib: 256,
+        vsockUds: "/v",
+        bootArgs: `${FC_DEFAULT_BOOT_ARGS} hotcell.pids=64 sbx.pids=64`,
+    });
+    assert.match(withPids[0].body.boot_args, /hotcell\.pids=64/);
+    ok("custom boot args (pidsLimit cmdline) flow through");
+    // 3. vsock handshake parser: incomplete → null; OK line → split leftover; bad → not ok.
+    assert.equal(parseVsockHandshake(Buffer.from("OK 1024")), null, "no newline yet → null");
+    const okParse = parseVsockHandshake(Buffer.from("OK 1024\nHELLOBYTES"));
+    assert.ok(okParse && okParse.ok, "OK line parses as ok");
+    assert.equal(okParse.leftover.toString(), "HELLOBYTES", "post-handshake bytes preserved");
+    const badParse = parseVsockHandshake(Buffer.from("CONNECTION RESET\n"));
+    assert.ok(badParse && !badParse.ok, "non-OK line parses as not ok");
+    ok("vsock CONNECT handshake parser: incomplete / ok+leftover / failure");
+    // 4. Driver fail-fast on a non-KVM host (this Mac): ping names /dev/kvm.
+    const driver = new FirecrackerDriver({
+        fcBin: "firecracker",
+        kernel: "/nonexistent/vmlinux",
+        rootfs: "helpers/hotcell-vz/guest/rootfs.img",
+        stateDir: "/tmp/hotcell-fc-check",
+        diskGb: 8,
+        imageCacheDir: "/tmp/hotcell-fc-check/images",
+    });
+    assert.equal(driver.name, "firecracker");
+    if (process.platform !== "linux") {
+        await assert.rejects(() => driver.ping(), /\/dev\/kvm/, "ping fails fast with a /dev/kvm message off-KVM");
+        ok("ping fails fast naming /dev/kvm (host without KVM)");
+    }
+    else {
+        ok("ping skipped (on Linux — may have /dev/kvm; live boot is smoke:fc)");
+    }
+    // 5. hostInfo works anywhere (os fallback when /proc is absent).
+    const host = await driver.hostInfo();
+    assert.ok(host.memoryMb > 0, "hostInfo reports memory");
+    assert.ok(host.cpus > 0, "hostInfo reports cpus");
+    ok(`hostInfo: ${host.memoryMb}MB / ${host.cpus} cpus`);
+    console.log(`\nfc-check: ${passed} checks passed (host-agnostic; live boot gated on KVM)`);
+}
+main().then(() => process.exit(0), (err) => {
+    console.error("fc-check FAILED:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=fc-check.js.map

package/dist/fc-check.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { BackupRegistry } from "./backups.js";
+import { Capacity } from "./capacity.js";
+import { loadConfig } from "./config.js";
+import { DriverRouter } from "./driver/router.js";
+import { startReaper } from "./lifecycle.js";
+import { configureLogger, log } from "./logger.js";
+import { MetricsHistory, startSampler } from "./metrics.js";
+import { configureTracing, stopTracing } from "./tracing.js";
+import { SandboxStore } from "./store.js";
+import { createApiServer } from "./api/server.js";
+import { createProxyServer } from "./proxy/server.js";
+import { buildProviders, createEgressProxy } from "./proxy/egress.js";
+import { loadModelPrices } from "./pricing.js";
+import { ensureEgressFirewall } from "./net/firewall.js";
+async function main() {
+    const config = loadConfig();
+    configureLogger({ level: config.logLevel, format: config.logFormat });
+    configureTracing({
+        serviceName: "sbd",
+        otlpEndpoint: config.otlpEndpoint,
+        ringSize: config.traceRing,
+    });
+    const store = new SandboxStore(config.dbPath);
+    // Per-sandbox driver router: dispatches each sandbox's ops to the runtime
+    // driver it was created with (container ↔ applevz), defaulting to SBX_DRIVER.
+    const driver = new DriverRouter(config, store, config.driver);
+    const backups = new BackupRegistry(config.backupDir);
+    const history = new MetricsHistory(config.metricsHistory);
+    // Fail fast with a friendly message if the selected driver isn't available
+    // (Docker not running, or a microVM driver requested without host support).
+    try {
+        await driver.ping();
+    }
+    catch (err) {
+        log.error(`driver "${driver.name}" is not available`, { error: String(err) });
+        if (driver.name === "container") {
+            log.error("start Docker (or colima / Apple 'container') and retry");
+        }
+        process.exit(1);
+    }
+    // Host capacity for the meter + admission control (best-effort detection).
+    const host = await driver.hostInfo().catch(() => null);
+    const capacity = new Capacity(store, config, host, history);
+    if (host) {
+        log.info("host capacity", {
+            memoryMb: host.memoryMb,
+            cpus: host.cpus,
+            admission: capacity.enforced ? "enforce" : "off",
+        });
+    }
+    const server = createApiServer({ config, driver, store, backups, history, capacity });
+    server.listen(config.port, config.host, () => {
+        log.info("daemon listening", {
+            url: `http://${config.host}:${config.port}`,
+            driver: driver.name,
+            image: config.defaultImage,
+            auth: config.apiKey ? "on" : "off",
+            otlp: config.otlpEndpoint || "off",
+        });
+    });
+    const proxy = createProxyServer({ config, driver, store });
+    proxy.listen(config.proxyPort, config.proxyHost, () => {
+        log.info("preview proxy listening", {
+            url: `http://${config.proxyHost}:${config.proxyPort}`,
+            previews: `http://<id>-<port>.localhost:${config.proxyPort}/`,
+        });
+    });
+    // Egress credential proxy (LLM gateway): injects provider keys into outbound
+    // calls and meters them. Runs whenever a port is configured; routes 404 until
+    // provider keys (SBX_PROVIDER_KEY_*) are set.
+    // Install the host default-deny egress firewall (Linux + SBX_EGRESS_ENFORCE only;
+    // advisory no-op otherwise). Best-effort: logs and continues if it can't.
+    await ensureEgressFirewall(config);
+    const providers = buildProviders(config);
+    const prices = loadModelPrices(config.modelPricesPath);
+    const egress = config.egressPort > 0 ? createEgressProxy({ config, store, providers, prices }) : undefined;
+    egress?.listen(config.egressPort, config.egressHost, () => {
+        log.info("egress proxy listening", {
+            url: `http://${config.egressHost}:${config.egressPort}`,
+            providers: Object.keys(providers).length ? Object.keys(providers).join(",") : "none configured",
+        });
+    });
+    // Idle reaper: auto-pause sandboxes left idle past their sleepAfterMs.
+    const reaper = config.reapIntervalMs > 0
+        ? startReaper({ driver, store, intervalMs: config.reapIntervalMs })
+        : undefined;
+    // Metrics sampler: integrate per-sandbox CPU/mem usage for the cost meter.
+    const sampler = config.metricsIntervalMs > 0
+        ? startSampler({ driver, store, history, intervalMs: config.metricsIntervalMs })
+        : undefined;
+    const shutdown = async () => {
+        log.info("shutting down");
+        if (reaper)
+            clearInterval(reaper);
+        if (sampler)
+            clearInterval(sampler);
+        await driver.shutdown().catch(() => { }); // tear down the VZ warm pool, if any
+        stopTracing();
+        egress?.close();
+        proxy.close();
+        server.close(() => {
+            store.close();
+            process.exit(0);
+        });
+    };
+    process.on("SIGINT", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
+}
+main().catch((err) => {
+    log.error("fatal", { error: String(err?.stack ?? err) });
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/kernels.d.ts

@@ -0,0 +1,22 @@
+/**
+ * In-sandbox code-interpreter kernels.
+ *
+ * Each code context runs one of these as a long-lived background process. A
+ * kernel keeps a persistent namespace (so variables/imports survive across
+ * `runCode` calls, Jupyter-style) and serves one cell at a time over a pair of
+ * named pipes in its context directory:
+ *
+ *   - reads a sequence number from `in.fifo`
+ *   - executes `cell-<seq>.code`
+ *   - writes a JSON `cell-<seq>.result.json` ({ stdout, stderr, results, error })
+ *   - signals completion by writing a line to `out.fifo`
+ *
+ * The daemon coordinates a single round-trip per call (see runCode in the API),
+ * so cells on one context are serialized.
+ */
+export type KernelLanguage = "python" | "javascript";
+export declare function kernelFor(language: KernelLanguage): {
+    filename: string;
+    source: string;
+    command: (dir: string) => string;
+};

package/dist/kernels.js

@@ -0,0 +1,134 @@
+/**
+ * In-sandbox code-interpreter kernels.
+ *
+ * Each code context runs one of these as a long-lived background process. A
+ * kernel keeps a persistent namespace (so variables/imports survive across
+ * `runCode` calls, Jupyter-style) and serves one cell at a time over a pair of
+ * named pipes in its context directory:
+ *
+ *   - reads a sequence number from `in.fifo`
+ *   - executes `cell-<seq>.code`
+ *   - writes a JSON `cell-<seq>.result.json` ({ stdout, stderr, results, error })
+ *   - signals completion by writing a line to `out.fifo`
+ *
+ * The daemon coordinates a single round-trip per call (see runCode in the API),
+ * so cells on one context are serialized.
+ */
+export function kernelFor(language) {
+    if (language === "python") {
+        return {
+            filename: "kernel.py",
+            source: PYTHON_KERNEL,
+            command: (dir) => `python3 -u ${dir}/kernel.py`,
+        };
+    }
+    return {
+        filename: "kernel.js",
+        source: JS_KERNEL,
+        command: (dir) => `node ${dir}/kernel.js`,
+    };
+}
+const PYTHON_KERNEL = String.raw `
+import sys, os, json, ast, io, traceback, contextlib
+
+CTX_DIR = os.path.dirname(os.path.abspath(__file__))
+IN = os.path.join(CTX_DIR, "in.fifo")
+OUT = os.path.join(CTX_DIR, "out.fifo")
+
+# Persistent namespace shared across cells.
+ns = {"__name__": "__main__"}
+
+def run_cell(code):
+    stdout, stderr = io.StringIO(), io.StringIO()
+    results = []
+    error = None
+    try:
+        tree = ast.parse(code)
+        last = tree.body[-1] if tree.body else None
+        with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            if isinstance(last, ast.Expr):
+                # Run everything but the trailing expression, then eval it so its
+                # value becomes a result (mirrors a notebook cell).
+                head = ast.Module(body=tree.body[:-1], type_ignores=[])
+                exec(compile(head, "<cell>", "exec"), ns)
+                value = eval(compile(ast.Expression(last.value), "<cell>", "eval"), ns)
+                if value is not None:
+                    results.append({"type": "text", "text": repr(value)})
+            else:
+                exec(compile(tree, "<cell>", "exec"), ns)
+    except Exception:
+        error = traceback.format_exc()
+    return {"stdout": stdout.getvalue(), "stderr": stderr.getvalue(),
+            "results": results, "error": error}
+
+while True:
+    with open(IN) as f:
+        seq = f.read().strip()
+    if not seq:
+        continue
+    try:
+        with open(os.path.join(CTX_DIR, "cell-%s.code" % seq)) as cf:
+            code = cf.read()
+        result = run_cell(code)
+    except Exception:
+        result = {"stdout": "", "stderr": "", "results": [],
+                  "error": traceback.format_exc()}
+    with open(os.path.join(CTX_DIR, "cell-%s.result.json" % seq), "w") as rf:
+        json.dump(result, rf)
+    with open(OUT, "w") as of:
+        of.write("done\n")
+`;
+const JS_KERNEL = String.raw `
+const fs = require("fs");
+const path = require("path");
+const vm = require("vm");
+const util = require("util");
+
+const CTX_DIR = __dirname;
+const IN = path.join(CTX_DIR, "in.fifo");
+const OUT = path.join(CTX_DIR, "out.fifo");
+
+// Persistent context shared across cells (var/global assignments survive).
+const sandbox = { require, process, Buffer, setTimeout, clearTimeout };
+sandbox.global = sandbox;
+const context = vm.createContext(sandbox);
+
+function fmt(v) {
+  return typeof v === "string" ? v : util.inspect(v, { depth: 4 });
+}
+
+function runCell(code) {
+  let stdout = "", stderr = "";
+  const results = [];
+  let error = null;
+  sandbox.console = {
+    log: (...a) => { stdout += a.map(fmt).join(" ") + "\n"; },
+    info: (...a) => { stdout += a.map(fmt).join(" ") + "\n"; },
+    error: (...a) => { stderr += a.map(fmt).join(" ") + "\n"; },
+    warn: (...a) => { stderr += a.map(fmt).join(" ") + "\n"; },
+  };
+  try {
+    const value = vm.runInContext(code, context, { filename: "<cell>" });
+    if (value !== undefined) results.push({ type: "text", text: fmt(value) });
+  } catch (e) {
+    error = (e && e.stack) ? String(e.stack) : String(e);
+  }
+  return { stdout, stderr, results, error };
+}
+
+for (;;) {
+  const seq = fs.readFileSync(IN, "utf8").trim();
+  if (!seq) continue;
+  let result;
+  try {
+    const code = fs.readFileSync(path.join(CTX_DIR, "cell-" + seq + ".code"), "utf8");
+    result = runCell(code);
+  } catch (e) {
+    result = { stdout: "", stderr: "", results: [],
+               error: (e && e.stack) ? String(e.stack) : String(e) };
+  }
+  fs.writeFileSync(path.join(CTX_DIR, "cell-" + seq + ".result.json"), JSON.stringify(result));
+  fs.writeFileSync(OUT, "done\n");
+}
+`;
+//# sourceMappingURL=kernels.js.map

package/dist/kernels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernels.js","sourceRoot":"","sources":["../src/kernels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,UAAU,SAAS,CAAC,QAAwB;IAKhD,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO;YACL,QAAQ,EAAE,WAAW;YACrB,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,GAAG,YAAY;SAChD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,WAAW;QACrB,MAAM,EAAE,SAAS;QACjB,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,GAAG,YAAY;KAC1C,CAAC;AACJ,CAAC;AAED,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiD/B,CAAC;AAEF,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD3B,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,49 @@
+import type { Driver } from "./driver/types.js";
+import type { SandboxStore } from "./store.js";
+import type { SandboxRecord } from "./types.js";
+/**
+ * Lifecycle FSM transitions and the idle reaper.
+ *
+ *   created ─▶ running ──(idle > sleepAfterMs, or POST /pause)──▶ paused ──(any op)──▶ running
+ *                  │                                                  │
+ *                  └────────────── stop (manual) ────────────────────┴──▶ stopped ──(start)──▶ running
+ *
+ * A `paused` sandbox has had its compute freed but keeps its workspace, so the
+ * next operation transparently resumes it. Pause comes in two strengths, picked
+ * automatically per sandbox: on microVM drivers that support it, pause is a
+ * **memory snapshot** (guest RAM + devices saved; background processes come back
+ * alive on resume — nothing is lost by pausing); otherwise it's the cold
+ * stop-with-volume (workspace survives, processes don't). A `stopped` sandbox is
+ * user-intent and is never auto-resumed nor auto-paused.
+ */
+/**
+ * Pause a running sandbox, preferring a memory snapshot (fast resume, live
+ * state preserved) and falling back to a cold stop. Runtime state (tracked
+ * processes, exposed ports) is only dropped on a cold pause — after a snapshot
+ * pause it stays valid, because resume restores those processes live.
+ */
+export declare function pauseSandbox(driver: Driver, store: SandboxStore, record: SandboxRecord): Promise<void>;
+/**
+ * Resume a paused (or stopped) sandbox: recreate its container, reattaching the
+ * persistent volume, and mark it running + active.
+ */
+export declare function resumeSandbox(driver: Driver, store: SandboxStore, record: SandboxRecord): Promise<void>;
+/**
+ * Auto-pause sandboxes that have been idle past their `sleepAfterMs`. A sandbox
+ * advertising a service (an exposed port) or running a tracked background
+ * process is paused only when the driver can **memory-snapshot** it — the
+ * processes come back alive, and the preview proxy wakes a paused sandbox on
+ * inbound traffic, so nothing is lost by hibernating. On cold-pause drivers
+ * such sandboxes are skipped, since pausing would kill that work.
+ * Returns the ids that were paused.
+ */
+export declare function reapIdle(driver: Driver, store: SandboxStore, now?: number): Promise<string[]>;
+/**
+ * Start the periodic idle reaper. Returns the interval handle (unref'd so it
+ * won't keep the process alive); pass it to `clearInterval` on shutdown.
+ */
+export declare function startReaper(opts: {
+    driver: Driver;
+    store: SandboxStore;
+    intervalMs: number;
+}): NodeJS.Timeout;

package/dist/lifecycle.js

@@ -0,0 +1,111 @@
+import { log } from "./logger.js";
+/**
+ * Lifecycle FSM transitions and the idle reaper.
+ *
+ *   created ─▶ running ──(idle > sleepAfterMs, or POST /pause)──▶ paused ──(any op)──▶ running
+ *                  │                                                  │
+ *                  └────────────── stop (manual) ────────────────────┴──▶ stopped ──(start)──▶ running
+ *
+ * A `paused` sandbox has had its compute freed but keeps its workspace, so the
+ * next operation transparently resumes it. Pause comes in two strengths, picked
+ * automatically per sandbox: on microVM drivers that support it, pause is a
+ * **memory snapshot** (guest RAM + devices saved; background processes come back
+ * alive on resume — nothing is lost by pausing); otherwise it's the cold
+ * stop-with-volume (workspace survives, processes don't). A `stopped` sandbox is
+ * user-intent and is never auto-resumed nor auto-paused.
+ */
+/**
+ * Pause a running sandbox, preferring a memory snapshot (fast resume, live
+ * state preserved) and falling back to a cold stop. Runtime state (tracked
+ * processes, exposed ports) is only dropped on a cold pause — after a snapshot
+ * pause it stays valid, because resume restores those processes live.
+ */
+export async function pauseSandbox(driver, store, record) {
+    let hibernated = false;
+    if (typeof driver.snapshot === "function" && (driver.canSnapshot?.(record.id) ?? true)) {
+        try {
+            await driver.snapshot(record.id);
+            hibernated = true;
+        }
+        catch (err) {
+            log.warn("snapshot pause failed; falling back to a cold stop", {
+                sandbox: record.id,
+                error: String(err),
+            });
+        }
+    }
+    if (!hibernated) {
+        await driver.stop(record.id);
+        store.clearRuntimeState(record.id); // processes/ports died with the compute
+    }
+    record.status = "paused";
+    store.add(record);
+}
+/**
+ * Resume a paused (or stopped) sandbox: recreate its container, reattaching the
+ * persistent volume, and mark it running + active.
+ */
+export async function resumeSandbox(driver, store, record) {
+    await driver.start({
+        id: record.id,
+        image: record.image,
+        driver: record.driver,
+        env: record.env,
+        labels: record.labels,
+        persist: record.persist,
+        limits: record.limits,
+    });
+    record.status = "running";
+    record.lastActivityAt = new Date().toISOString();
+    store.add(record);
+}
+/**
+ * Auto-pause sandboxes that have been idle past their `sleepAfterMs`. A sandbox
+ * advertising a service (an exposed port) or running a tracked background
+ * process is paused only when the driver can **memory-snapshot** it — the
+ * processes come back alive, and the preview proxy wakes a paused sandbox on
+ * inbound traffic, so nothing is lost by hibernating. On cold-pause drivers
+ * such sandboxes are skipped, since pausing would kill that work.
+ * Returns the ids that were paused.
+ */
+export async function reapIdle(driver, store, now = Date.now()) {
+    const paused = [];
+    for (const record of store.list()) {
+        if (record.status !== "running")
+            continue;
+        if (!record.sleepAfterMs || record.sleepAfterMs <= 0)
+            continue;
+        const hasService = store.listExposed(record.id).length > 0;
+        const hasLiveProcs = store.listProcesses(record.id).some((p) => p.status === "running");
+        if ((hasService || hasLiveProcs) && !driver.canSnapshot?.(record.id))
+            continue;
+        if (now - Date.parse(record.lastActivityAt) < record.sleepAfterMs)
+            continue;
+        try {
+            await pauseSandbox(driver, store, record);
+            paused.push(record.id);
+        }
+        catch (err) {
+            log.warn("reaper failed to pause sandbox", { sandbox: record.id, error: String(err) });
+        }
+    }
+    return paused;
+}
+/**
+ * Start the periodic idle reaper. Returns the interval handle (unref'd so it
+ * won't keep the process alive); pass it to `clearInterval` on shutdown.
+ */
+export function startReaper(opts) {
+    const { driver, store, intervalMs } = opts;
+    const timer = setInterval(() => {
+        reapIdle(driver, store)
+            .then((ids) => {
+            if (ids.length)
+                log.info("auto-paused idle sandboxes", { ids });
+        })
+            .catch((err) => log.error("reaper error", { error: String(err) }));
+    }, intervalMs);
+    timer.unref?.();
+    return timer;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,16 @@
+import type { LogFormat, LogLevel } from "./config.js";
+export type LogFields = Record<string, unknown>;
+export interface Logger {
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    /** Derive a logger that stamps `fields` onto every line (e.g. a request id). */
+    child(fields: LogFields): Logger;
+}
+/** Process-wide logger. Replaced by `configureLogger`; defaults are quiet-ish. */
+export declare let log: Logger;
+export declare function configureLogger(opts: {
+    level: LogLevel;
+    format: LogFormat;
+}): Logger;