@hotcell/daemon 0.1.0

package/dist/api/server.js

@@ -0,0 +1,1368 @@
+import { createServer } from "node:http";
+import { previewUrl } from "../config.js";
+import { kernelFor } from "../kernels.js";
+import { pauseSandbox, resumeSandbox } from "../lifecycle.js";
+import { computeCost } from "../cost.js";
+import { log } from "../logger.js";
+import { recentSpans, startSpan } from "../tracing.js";
+import { buildProviders } from "../proxy/egress.js";
+import { DRIVER_NAMES } from "../driver/index.js";
+import { emptyUsage, SandboxStore } from "../store.js";
+import { acceptWebSocket } from "./ws.js";
+import { BodyTooLargeError, errorMessage, readBodyCapped, safeEqual, sendJson, shellEscape, } from "../util.js";
+import { DASHBOARD_HTML } from "../web/dashboard.js";
+/**
+ * Phase 0/1 REST surface:
+ *   GET    /healthz
+ *   POST   /sandboxes                      -> create
+ *   GET    /sandboxes                      -> list
+ *   GET    /sandboxes/:id                  -> get
+ *   DELETE /sandboxes/:id                  -> destroy (removes volume too)
+ *   GET    /sandboxes/:id/metrics          -> live stats + cumulative usage + cost
+ *   POST   /sandboxes/:id/stop             -> stop (remove container, keep volume)
+ *   POST   /sandboxes/:id/pause            -> fast-pause (memory snapshot on microVM drivers; else stop-with-volume); any op auto-resumes
+ *   POST   /sandboxes/:id/start            -> start (recreate container, reattach volume)
+ *   POST   /sandboxes/:id/backups          -> back up /workspace, returns BackupInfo
+ *   GET    /sandboxes/:id/backups          -> list this sandbox's backups
+ *   POST   /sandboxes/:id/restore          -> restore /workspace from {backupId}
+ *   GET    /backups                        -> list all backups
+ *   DELETE /backups/:backupId              -> delete a backup
+ *   POST   /sandboxes/:id/code-contexts        -> create a code-interpreter context
+ *   GET    /sandboxes/:id/code-contexts        -> list code contexts
+ *   DELETE /sandboxes/:id/code-contexts/:ctxId -> destroy a code context
+ *   POST   /sandboxes/:id/run-code             -> run code, returns CodeResult
+ *   POST   /sandboxes/:id/exec             -> run command, stream output as SSE
+ *   POST   /sandboxes/:id/files/write      -> write file
+ *   POST   /sandboxes/:id/files/read       -> read file
+ *   POST   /sandboxes/:id/files/mkdir      -> create directory
+ *   POST   /sandboxes/:id/files/list       -> list directory
+ *   GET    /sandboxes/:id/watch            -> stream file-change events (SSE)
+ *   GET    /sandboxes/:id/terminal         -> interactive PTY shell (WebSocket upgrade)
+ *   GET    /sandboxes/:id/metrics/history  -> recent live-metrics samples (sparklines)
+ *   POST   /sandboxes/:id/egress-tokens         -> mint an egress (LLM gateway) token
+ *   GET    /sandboxes/:id/egress-tokens         -> list egress tokens + provider URLs
+ *   DELETE /sandboxes/:id/egress-tokens/:token  -> revoke an egress token
+ *   GET    /traces                         -> recent finished trace spans
+ *   POST   /sandboxes/:id/processes              -> start background process
+ *   GET    /sandboxes/:id/processes              -> list processes
+ *   DELETE /sandboxes/:id/processes/:procId      -> signal/kill process
+ *   GET    /sandboxes/:id/processes/:procId/logs -> stream logs (SSE)
+ *   POST   /sandboxes/:id/wait-port              -> wait for a TCP port
+ *   POST   /sandboxes/:id/expose                 -> expose a port (preview URL)
+ *   GET    /sandboxes/:id/expose                 -> list exposed ports
+ *   DELETE /sandboxes/:id/expose/:port           -> unexpose a port
+ *   GET    /sandboxes/:id/env                     -> get sandbox env vars
+ *   POST   /sandboxes/:id/env                     -> merge sandbox env vars
+ *   POST   /sandboxes/:id/sessions               -> create a session
+ *   GET    /sandboxes/:id/sessions               -> list sessions
+ *   DELETE /sandboxes/:id/sessions/:sid          -> delete a session
+ *   POST   /sandboxes/:id/sessions/:sid/env      -> merge session env vars
+ */
+export function createApiServer(deps) {
+    const server = createServer((req, res) => {
+        const method = req.method ?? "GET";
+        const rawPath = (req.url ?? "/").split("?")[0];
+        // One server span per request — the create→exec→destroy trace the plan asks
+        // for falls out naturally (route is normalized so ids don't explode names).
+        const span = startSpan(`${method} ${normalizeRoute(rawPath)}`, {
+            "http.method": method,
+            "http.target": rawPath,
+        });
+        const startedMs = Date.now();
+        res.on("finish", () => {
+            span.setAttribute("http.status_code", res.statusCode);
+            if (res.statusCode >= 500)
+                span.setStatus("error");
+            span.end();
+            const line = {
+                method,
+                path: rawPath,
+                status: res.statusCode,
+                durMs: Date.now() - startedMs,
+                traceId: span.traceId,
+            };
+            if (res.statusCode >= 500)
+                log.error("request", line);
+            else
+                log.info("request", line);
+        });
+        handle(req, res, deps).catch((err) => {
+            span.setStatus("error").setAttribute("error", String(err?.message ?? err));
+            if (err instanceof BodyTooLargeError) {
+                return sendJson(res, 413, { error: "request body too large" });
+            }
+            sendJson(res, 500, { error: String(err?.message ?? err) });
+        });
+    });
+    // Live terminal: a WebSocket upgrade bridged to an in-sandbox PTY.
+    server.on("upgrade", (req, socket, head) => {
+        handleTerminalUpgrade(req, socket, head, deps).catch(() => socket.destroy());
+    });
+    return server;
+}
+/** Pull a Bearer token from the Authorization header, if present. */
+function bearerFromHeader(req) {
+    const header = req.headers["authorization"];
+    return typeof header === "string" && header.startsWith("Bearer ")
+        ? header.slice(7)
+        : undefined;
+}
+/**
+ * Handle a WebSocket upgrade for `GET /sandboxes/:id/terminal`: authenticate,
+ * resolve (and auto-resume) the sandbox, open a PTY, and splice bytes both ways.
+ * Inbound binary frames are stdin; inbound text frames are control JSON (resize).
+ * Browsers can't set headers on a WebSocket, so the API key may arrive as `?key=`.
+ */
+async function handleTerminalUpgrade(req, socket, head, deps) {
+    const { config, driver, store } = deps;
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    const match = url.pathname.match(/^\/sandboxes\/([^/]+)\/terminal$/);
+    if (!match) {
+        socket.destroy();
+        return;
+    }
+    if (!isAllowedHost(req, config)) {
+        socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+        socket.destroy();
+        return;
+    }
+    if (config.apiKey) {
+        const provided = url.searchParams.get("key") ?? bearerFromHeader(req);
+        if (!provided || !safeEqual(provided, config.apiKey)) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+    }
+    const id = match[1];
+    const record = store.get(id);
+    if (!record) {
+        socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+        socket.destroy();
+        return;
+    }
+    if (record.status === "stopped") {
+        socket.write("HTTP/1.1 409 Conflict\r\n\r\n");
+        socket.destroy();
+        return;
+    }
+    if (record.status === "paused")
+        await resumeSandbox(driver, store, record);
+    else
+        store.touch(id);
+    const ws = acceptWebSocket(req, socket, head);
+    if (!ws)
+        return;
+    const cols = Number(url.searchParams.get("cols")) || 80;
+    const rows = Number(url.searchParams.get("rows")) || 24;
+    const span = startSpan("WS /sandboxes/:id/terminal", { "sandbox.id": id });
+    let term;
+    try {
+        term = await driver.openTerminal(id, { cols, rows, env: record.env });
+    }
+    catch (err) {
+        ws.send(`\r\n[sbx] failed to open terminal: ${errorMessage(err)}\r\n`);
+        ws.close();
+        span.setStatus("error").end();
+        return;
+    }
+    log.info("terminal opened", { sandbox: id, traceId: span.traceId });
+    term.stream.on("data", (chunk) => ws.send(chunk));
+    term.stream.on("end", () => ws.close());
+    term.stream.on("error", () => ws.close());
+    ws.onMessage((data, isBinary) => {
+        if (isBinary) {
+            term.stream.write(data);
+            store.touch(id);
+            return;
+        }
+        try {
+            const msg = JSON.parse(data.toString("utf8"));
+            if (msg && msg.type === "resize") {
+                term.resize(Number(msg.cols) || cols, Number(msg.rows) || rows);
+            }
+        }
+        catch {
+            // Non-JSON text frames are ignored; keystrokes arrive as binary frames.
+        }
+    });
+    ws.onClose(() => {
+        term.close();
+        span.end();
+        log.info("terminal closed", { sandbox: id });
+    });
+}
+/**
+ * Build the egress-gateway client config for a token: per-provider base URLs the
+ * sandbox points its SDK at, plus suggested env vars. The token is used in place
+ * of each provider's real API key (the daemon swaps it for the real one).
+ */
+function egressConfig(config, advertiseHost) {
+    const base = `http://${advertiseHost ?? config.egressAdvertiseHost}:${config.egressPort}`;
+    const names = Object.keys(buildProviders(config));
+    const ENV_HINT = {
+        openai: { baseUrlEnv: "OPENAI_BASE_URL", keyEnv: "OPENAI_API_KEY" },
+        anthropic: { baseUrlEnv: "ANTHROPIC_BASE_URL", keyEnv: "ANTHROPIC_API_KEY" },
+        openrouter: { baseUrlEnv: "OPENROUTER_BASE_URL", keyEnv: "OPENROUTER_API_KEY" },
+        google: { baseUrlEnv: "GOOGLE_BASE_URL", keyEnv: "GOOGLE_API_KEY" },
+        gemini: { baseUrlEnv: "GEMINI_BASE_URL", keyEnv: "GEMINI_API_KEY" },
+    };
+    // For custom/operator-defined providers, synthesize conventional env names
+    // (`<NAME>_BASE_URL` / `<NAME>_API_KEY`) so auto-wiring still injects something
+    // sensible. Operators can ignore these and wire their SDK by hand.
+    const providers = names.map((name) => {
+        const envName = name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+        const hint = ENV_HINT[name] ?? {
+            baseUrlEnv: `${envName}_BASE_URL`,
+            keyEnv: `${envName}_API_KEY`,
+        };
+        return { name, baseUrl: `${base}/${name}`, ...hint };
+    });
+    return { providers };
+}
+/**
+ * Env vars that point a sandbox's LLM SDKs at the egress gateway, with `token`
+ * standing in for each provider's real key. Injected at create time when a
+ * sandbox opts into egress, so the gateway is drop-in (no in-sandbox config).
+ */
+function egressEnv(config, token, advertiseHost) {
+    const env = {};
+    for (const p of egressConfig(config, advertiseHost).providers) {
+        if (p.baseUrlEnv)
+            env[p.baseUrlEnv] = p.baseUrl;
+        if (p.keyEnv)
+            env[p.keyEnv] = token;
+    }
+    return env;
+}
+/**
+ * Forward-proxy env for a sandbox under egress enforcement: point `HTTP(S)_PROXY`
+ * at the gateway (the token is the proxy credential), and exclude the gateway host
+ * + loopback via `NO_PROXY` so the sandbox's own LLM base-URL calls (which target
+ * the gateway directly, origin-form) don't loop back through the proxy. Lower-case
+ * variants too, since many tools (curl, pip, apt) read those.
+ */
+function proxyEnv(config, token, advertiseHost) {
+    const host = advertiseHost ?? config.egressAdvertiseHost;
+    // Token as BOTH user and password: many clients (pip/urllib3, some others) only
+    // emit `Proxy-Authorization` on a CONNECT when the proxy URL has a non-empty
+    // password. The gateway reads the username half, so the password value is moot.
+    const proxy = `http://${token}:${token}@${host}:${config.egressPort}`;
+    const noProxy = `localhost,127.0.0.1,${host}`;
+    return {
+        HTTP_PROXY: proxy,
+        HTTPS_PROXY: proxy,
+        http_proxy: proxy,
+        https_proxy: proxy,
+        NO_PROXY: noProxy,
+        no_proxy: noProxy,
+    };
+}
+/**
+ * Validate + normalise an egress-token policy from a request body. Accepts the
+ * `ttlMs` sugar (→ `expiresAt = now + ttlMs`). An empty/blank body yields `{}`
+ * (unlimited — the pre-policy default). Returns `{ error }` (→ 400) on bad shape.
+ */
+function parseEgressPolicy(body) {
+    const policy = {};
+    const num = (key) => {
+        const v = body[key];
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+            return null; // null = invalid
+        return v;
+    };
+    const ttlMs = num("ttlMs");
+    if (ttlMs === null)
+        return { error: "ttlMs must be a non-negative number" };
+    if (typeof ttlMs === "number" && ttlMs > 0) {
+        policy.expiresAt = new Date(Date.now() + ttlMs).toISOString();
+    }
+    if (typeof body.expiresAt === "string" && body.expiresAt) {
+        if (Number.isNaN(Date.parse(body.expiresAt)))
+            return { error: "expiresAt must be an ISO timestamp" };
+        policy.expiresAt = body.expiresAt;
+    }
+    const spendCapUsd = num("spendCapUsd");
+    if (spendCapUsd === null)
+        return { error: "spendCapUsd must be a non-negative number" };
+    if (typeof spendCapUsd === "number")
+        policy.spendCapUsd = spendCapUsd;
+    if (body.rateLimit !== undefined) {
+        const r = body.rateLimit;
+        if (typeof r !== "object" || r === null)
+            return { error: "rateLimit must be an object" };
+        const windowMs = r.windowMs;
+        if (typeof windowMs !== "number" || !Number.isFinite(windowMs) || windowMs <= 0) {
+            return { error: "rateLimit.windowMs must be a positive number" };
+        }
+        const rateLimit = { windowMs };
+        for (const k of ["calls", "tokens"]) {
+            const v = r[k];
+            if (v === undefined)
+                continue;
+            if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+                return { error: `rateLimit.${k} must be a non-negative number` };
+            }
+            rateLimit[k] = v;
+        }
+        policy.rateLimit = rateLimit;
+    }
+    for (const key of ["models", "providers"]) {
+        const v = body[key];
+        if (v === undefined)
+            continue;
+        if (!Array.isArray(v) || !v.every((s) => typeof s === "string")) {
+            return { error: `${key} must be an array of strings` };
+        }
+        if (v.length > 0)
+            policy[key] = v;
+    }
+    return { policy };
+}
+/**
+ * Resolve hard resource caps for a new sandbox: each of `memoryMb`/`cpus`/
+ * `pidsLimit` is the per-create body value if given, else the daemon default.
+ * Only active (>0) caps are kept, so an unlimited sandbox has `limits: {}`.
+ * Returns `{ error }` (→ 400) on an invalid value.
+ */
+function resolveLimits(body, config) {
+    const read = (key) => {
+        const v = body[key];
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+            return Number.NaN;
+        return v;
+    };
+    for (const key of ["memoryMb", "cpus", "pidsLimit"]) {
+        if (Number.isNaN(read(key)))
+            return { error: `${key} must be a non-negative number` };
+    }
+    const memoryMb = read("memoryMb") ?? config.defaultMemoryMb;
+    const cpus = read("cpus") ?? config.defaultCpus;
+    const pidsLimit = read("pidsLimit") ?? config.defaultPidsLimit;
+    if (memoryMb > 0 && memoryMb < 6) {
+        return { error: "memoryMb must be at least 6 (Docker minimum)" };
+    }
+    const limits = {};
+    if (memoryMb > 0)
+        limits.memoryMb = memoryMb;
+    if (cpus > 0)
+        limits.cpus = cpus;
+    if (pidsLimit > 0)
+        limits.pidsLimit = pidsLimit;
+    return { limits };
+}
+/** Collapse high-cardinality id segments so span/route names stay bounded. */
+function normalizeRoute(path) {
+    return path
+        .replace(/^\/sandboxes\/[^/]+/, "/sandboxes/:id")
+        .replace(/\/(processes|sessions|code-contexts|expose|backups)\/[^/]+/, "/$1/:sub");
+}
+/**
+ * Enforce the API key when one is configured. `/healthz` and the dashboard HTML
+ * stay open (probes + first paint, so the dashboard can prompt for the key).
+ * Accepts `Authorization: Bearer <key>` or `X-API-Key: <key>`.
+ */
+function isAuthorized(req, config, path) {
+    if (!config.apiKey)
+        return true;
+    // Open: health probes, the dashboard shell, and /info (non-sensitive — it only
+    // reports driver/image/cost-rates and whether auth is on, so the dashboard can
+    // decide to prompt for a key before making authenticated calls).
+    if (path === "/healthz" || path === "/" || path === "/dashboard" || path === "/info") {
+        return true;
+    }
+    const header = req.headers["authorization"];
+    const bearer = typeof header === "string" && header.startsWith("Bearer ")
+        ? header.slice(7)
+        : undefined;
+    const apiKeyHeader = req.headers["x-api-key"];
+    const provided = bearer ?? (typeof apiKeyHeader === "string" ? apiKeyHeader : undefined);
+    return provided !== undefined && safeEqual(provided, config.apiKey);
+}
+/** A host bound to a loopback interface (the dev default). */
+function isLoopbackHost(host) {
+    return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+/**
+ * DNS-rebinding / localhost-CSRF guard: when the daemon is bound to loopback,
+ * only accept requests whose `Host` header is a loopback name, `config.host`, or
+ * an explicit `SBX_ALLOWED_HOSTS` entry — so a website the operator visits can't
+ * drive the API via a rebound DNS name. If bound to a non-loopback interface the
+ * operator has opted into network exposure, so the guard is skipped (they should
+ * set an API key). The preview/egress proxies are separate servers and unaffected.
+ */
+function isAllowedHost(req, config) {
+    if (!isLoopbackHost(config.host))
+        return true;
+    const hostHeader = req.headers["host"];
+    if (typeof hostHeader !== "string")
+        return false;
+    const hostname = hostHeader
+        .replace(/:\d+$/, "") // strip port
+        .replace(/^\[|\]$/g, "") // strip IPv6 brackets
+        .toLowerCase();
+    if (hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1")
+        return true;
+    if (hostname === config.host.toLowerCase())
+        return true;
+    return config.allowedHosts.some((h) => h.toLowerCase() === hostname);
+}
+async function handle(req, res, deps) {
+    const { config, driver, store, backups } = deps;
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    const path = url.pathname;
+    const method = req.method ?? "GET";
+    if (!isAllowedHost(req, config)) {
+        return sendJson(res, 403, { error: "host not allowed" });
+    }
+    if (!isAuthorized(req, config, path)) {
+        res.setHeader("WWW-Authenticate", "Bearer");
+        return sendJson(res, 401, { error: "missing or invalid API key" });
+    }
+    if (method === "GET" && path === "/healthz") {
+        try {
+            await driver.ping();
+            return sendJson(res, 200, { ok: true, driver: driver.name });
+        }
+        catch (err) {
+            return sendJson(res, 503, { ok: false, error: String(err) });
+        }
+    }
+    // Daemon info for the dashboard (cost rates, proxy port, driver, image).
+    if (method === "GET" && path === "/info") {
+        return sendJson(res, 200, {
+            driver: driver.name,
+            drivers: DRIVER_NAMES,
+            defaultImage: config.defaultImage,
+            proxyPort: config.proxyPort,
+            costCpuPerHour: config.costCpuPerHour,
+            costMemGbPerHour: config.costMemGbPerHour,
+            costEgressPerGb: config.costEgressPerGb,
+            defaultSleepAfterMs: config.defaultSleepAfterMs,
+            auth: config.apiKey.length > 0,
+            otlp: config.otlpEndpoint.length > 0,
+            egressPort: config.egressPort,
+            egressProviders: Object.keys(buildProviders(config)),
+            defaultMemoryMb: config.defaultMemoryMb,
+            defaultCpus: config.defaultCpus,
+            defaultPidsLimit: config.defaultPidsLimit,
+        });
+    }
+    const egressTokenIdMatch = path.match(/^\/sandboxes\/([^/]+)\/egress-tokens\/([^/]+)$/);
+    if (method === "DELETE" && egressTokenIdMatch) {
+        if (!store.get(egressTokenIdMatch[1]))
+            return sendJson(res, 404, { error: "not found" });
+        const removed = store.removeEgressToken(egressTokenIdMatch[2]);
+        if (!removed)
+            return sendJson(res, 404, { error: "token not found" });
+        return sendJson(res, 200, { token: egressTokenIdMatch[2], revoked: true });
+    }
+    const egressTokensMatch = path.match(/^\/sandboxes\/([^/]+)\/egress-tokens$/);
+    if (egressTokensMatch) {
+        const id = egressTokensMatch[1];
+        if (!store.get(id))
+            return sendJson(res, 404, { error: "not found" });
+        if (method === "POST") {
+            const body = await readJson(req, config.maxBodyBytes);
+            const parsed = parseEgressPolicy(body);
+            if ("error" in parsed)
+                return sendJson(res, 400, { error: parsed.error });
+            const token = SandboxStore.newEgressToken();
+            store.addEgressToken(token, id, parsed.policy);
+            return sendJson(res, 201, {
+                token,
+                policy: parsed.policy,
+                providers: egressConfig(config).providers,
+            });
+        }
+        if (method === "GET") {
+            const tokens = store.listEgressTokens(id).map((r) => ({
+                token: r.token,
+                policy: r.policy,
+                spendUsd: r.spendUsd,
+                spendRemaining: r.policy.spendCapUsd === undefined
+                    ? null
+                    : Math.max(0, r.policy.spendCapUsd - r.spendUsd),
+            }));
+            return sendJson(res, 200, { tokens, providers: egressConfig(config).providers });
+        }
+    }
+    // Host capacity + admission status (for the dashboard meter + `sb capacity`).
+    if (method === "GET" && path === "/capacity") {
+        if (!deps.capacity)
+            return sendJson(res, 200, { enforced: false });
+        return sendJson(res, 200, deps.capacity.snapshot());
+    }
+    // Recent finished spans, for debugging and the trace view. Newest first.
+    if (method === "GET" && path === "/traces") {
+        const limit = Number(url.searchParams.get("limit") ?? "100") || 100;
+        return sendJson(res, 200, { spans: recentSpans().slice(0, limit) });
+    }
+    // Embedded single-page dashboard (no build step, zero dependencies).
+    if (method === "GET" && (path === "/" || path === "/dashboard")) {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        return void res.end(DASHBOARD_HTML);
+    }
+    if (method === "POST" && path === "/sandboxes") {
+        const body = await readJson(req, config.maxBodyBytes);
+        return createSandbox(res, { config, driver, store, capacity: deps.capacity }, body);
+    }
+    if (method === "GET" && path === "/sandboxes") {
+        return sendJson(res, 200, { sandboxes: store.list() });
+    }
+    const execMatch = path.match(/^\/sandboxes\/([^/]+)\/exec$/);
+    if (method === "POST" && execMatch) {
+        const body = await readJson(req, config.maxBodyBytes);
+        return execInSandbox(res, { driver, store }, execMatch[1], body);
+    }
+    const fileActionMatch = path.match(/^\/sandboxes\/([^/]+)\/files\/(write|read|mkdir|list)$/);
+    if (method === "POST" && fileActionMatch) {
+        const body = await readJson(req, config.maxBodyBytes);
+        return handleFileAction(res, { driver, store }, fileActionMatch[1], fileActionMatch[2], body);
+    }
+    const watchMatch = path.match(/^\/sandboxes\/([^/]+)\/watch$/);
+    if (method === "GET" && watchMatch) {
+        const watchPath = url.searchParams.get("path") ?? "/workspace";
+        const intervalMs = Number(url.searchParams.get("interval") ?? "") || undefined;
+        return watchFiles(req, res, { driver, store }, watchMatch[1], watchPath, intervalMs);
+    }
+    const procLogsMatch = path.match(/^\/sandboxes\/([^/]+)\/processes\/([^/]+)\/logs$/);
+    if (method === "GET" && procLogsMatch) {
+        return streamLogs(req, res, { driver, store }, procLogsMatch[1], procLogsMatch[2], url.searchParams.get("follow") !== "0" &&
+            url.searchParams.has("follow"));
+    }
+    const procIdMatch = path.match(/^\/sandboxes\/([^/]+)\/processes\/([^/]+)$/);
+    if (method === "DELETE" && procIdMatch) {
+        const body = await readJson(req, config.maxBodyBytes);
+        return killProcess(res, { driver, store }, procIdMatch[1], procIdMatch[2], body);
+    }
+    const procMatch = path.match(/^\/sandboxes\/([^/]+)\/processes$/);
+    if (procMatch) {
+        if (method === "POST") {
+            const body = await readJson(req, config.maxBodyBytes);
+            return startProcess(res, { driver, store }, procMatch[1], body);
+        }
+        if (method === "GET") {
+            return listProcesses(res, { driver, store }, procMatch[1]);
+        }
+    }
+    const waitPortMatch = path.match(/^\/sandboxes\/([^/]+)\/wait-port$/);
+    if (method === "POST" && waitPortMatch) {
+        const body = await readJson(req, config.maxBodyBytes);
+        return waitForPort(res, { driver, store }, waitPortMatch[1], body);
+    }
+    const exposePortMatch = path.match(/^\/sandboxes\/([^/]+)\/expose\/(\d+)$/);
+    if (method === "DELETE" && exposePortMatch) {
+        return unexposePort(res, { store }, exposePortMatch[1], Number(exposePortMatch[2]));
+    }
+    const exposeMatch = path.match(/^\/sandboxes\/([^/]+)\/expose$/);
+    if (exposeMatch) {
+        if (method === "POST") {
+            const body = await readJson(req, config.maxBodyBytes);
+            return exposePort(res, { config, driver, store }, exposeMatch[1], body);
+        }
+        if (method === "GET") {
+            const record = store.get(exposeMatch[1]);
+            if (!record)
+                return sendJson(res, 404, { error: "not found" });
+            return sendJson(res, 200, { exposed: store.listExposed(exposeMatch[1]) });
+        }
+    }
+    const sessionEnvMatch = path.match(/^\/sandboxes\/([^/]+)\/sessions\/([^/]+)\/env$/);
+    if (method === "POST" && sessionEnvMatch) {
+        const body = await readJson(req, config.maxBodyBytes);
+        return setSessionEnv(res, { store }, sessionEnvMatch[1], sessionEnvMatch[2], body);
+    }
+    const sessionIdMatch = path.match(/^\/sandboxes\/([^/]+)\/sessions\/([^/]+)$/);
+    if (method === "DELETE" && sessionIdMatch) {
+        return deleteSession(res, { store }, sessionIdMatch[1], sessionIdMatch[2]);
+    }
+    const sessionsMatch = path.match(/^\/sandboxes\/([^/]+)\/sessions$/);
+    if (sessionsMatch) {
+        if (method === "POST") {
+            const body = await readJson(req, config.maxBodyBytes);
+            return createSession(res, { store }, sessionsMatch[1], body);
+        }
+        if (method === "GET") {
+            if (!store.get(sessionsMatch[1])) {
+                return sendJson(res, 404, { error: "not found" });
+            }
+            return sendJson(res, 200, {
+                sessions: store.listSessions(sessionsMatch[1]),
+            });
+        }
+    }
+    const envMatch = path.match(/^\/sandboxes\/([^/]+)\/env$/);
+    if (envMatch) {
+        const record = store.get(envMatch[1]);
+        if (!record)
+            return sendJson(res, 404, { error: "not found" });
+        if (method === "GET") {
+            return sendJson(res, 200, { env: record.env });
+        }
+        if (method === "POST") {
+            const body = await readJson(req, config.maxBodyBytes);
+            const env = body.env ?? {};
+            record.env = { ...record.env, ...env };
+            store.add(record); // write-through the env change
+            return sendJson(res, 200, { env: record.env });
+        }
+    }
+    if (method === "GET" && path === "/backups") {
+        return sendJson(res, 200, { backups: await backups.list() });
+    }
+    const backupIdMatch = path.match(/^\/backups\/([^/]+)$/);
+    if (method === "DELETE" && backupIdMatch) {
+        const removed = await backups.remove(backupIdMatch[1]);
+        if (!removed)
+            return sendJson(res, 404, { error: "backup not found" });
+        return sendJson(res, 200, { backupId: backupIdMatch[1], deleted: true });
+    }
+    const backupsMatch = path.match(/^\/sandboxes\/([^/]+)\/backups$/);
+    if (backupsMatch) {
+        if (method === "POST") {
+            return createBackup(res, deps, backupsMatch[1]);
+        }
+        if (method === "GET") {
+            if (!store.get(backupsMatch[1])) {
+                return sendJson(res, 404, { error: "not found" });
+            }
+            const all = await backups.list();
+            return sendJson(res, 200, {
+                backups: all.filter((b) => b.sandboxId === backupsMatch[1]),
+            });
+        }
+    }
+    const restoreMatch = path.match(/^\/sandboxes\/([^/]+)\/restore$/);
+    if (method === "POST" && restoreMatch) {
+        const body = await readJson(req, config.maxBodyBytes);
+        return restoreBackup(res, deps, restoreMatch[1], body);
+    }
+    const ctxIdMatch = path.match(/^\/sandboxes\/([^/]+)\/code-contexts\/([^/]+)$/);
+    if (method === "DELETE" && ctxIdMatch) {
+        return deleteCodeContext(res, { driver, store }, ctxIdMatch[1], ctxIdMatch[2]);
+    }
+    const ctxMatch = path.match(/^\/sandboxes\/([^/]+)\/code-contexts$/);
+    if (ctxMatch) {
+        if (method === "POST") {
+            const body = await readJson(req, config.maxBodyBytes);
+            return createCodeContext(res, { driver, store }, ctxMatch[1], body);
+        }
+        if (method === "GET") {
+            if (!store.get(ctxMatch[1]))
+                return sendJson(res, 404, { error: "not found" });
+            return sendJson(res, 200, {
+                contexts: store.listContexts(ctxMatch[1]).map(publicContext),
+            });
+        }
+    }
+    const runCodeMatch = path.match(/^\/sandboxes\/([^/]+)\/run-code$/);
+    if (method === "POST" && runCodeMatch) {
+        const body = await readJson(req, config.maxBodyBytes);
+        return runCode(res, { driver, store }, runCodeMatch[1], body);
+    }
+    const historyMatch = path.match(/^\/sandboxes\/([^/]+)\/metrics\/history$/);
+    if (method === "GET" && historyMatch) {
+        if (!store.get(historyMatch[1]))
+            return sendJson(res, 404, { error: "not found" });
+        return sendJson(res, 200, { samples: deps.history?.get(historyMatch[1]) ?? [] });
+    }
+    const metricsMatch = path.match(/^\/sandboxes\/([^/]+)\/metrics$/);
+    if (method === "GET" && metricsMatch) {
+        const live = url.searchParams.get("live") !== "0";
+        return getMetrics(res, { config, driver, store }, metricsMatch[1], live);
+    }
+    const stopMatch = path.match(/^\/sandboxes\/([^/]+)\/stop$/);
+    if (method === "POST" && stopMatch) {
+        return stopSandbox(res, { driver, store }, stopMatch[1]);
+    }
+    const pauseMatch = path.match(/^\/sandboxes\/([^/]+)\/pause$/);
+    if (method === "POST" && pauseMatch) {
+        return pauseSandboxRoute(res, { driver, store }, pauseMatch[1]);
+    }
+    const startMatch = path.match(/^\/sandboxes\/([^/]+)\/start$/);
+    if (method === "POST" && startMatch) {
+        return startSandbox(res, { driver, store }, startMatch[1]);
+    }
+    const idMatch = path.match(/^\/sandboxes\/([^/]+)$/);
+    if (idMatch) {
+        const id = idMatch[1];
+        if (method === "GET") {
+            const record = store.get(id);
+            if (!record)
+                return sendJson(res, 404, { error: "not found" });
+            return sendJson(res, 200, record);
+        }
+        if (method === "DELETE") {
+            const record = store.get(id);
+            if (!record)
+                return sendJson(res, 404, { error: "not found" });
+            await driver.destroy(id);
+            store.remove(id);
+            store.clearSandbox(id);
+            deps.history?.clear(id);
+            return sendJson(res, 200, { id, destroyed: true });
+        }
+    }
+    sendJson(res, 404, { error: `no route for ${method} ${path}` });
+}
+async function createSandbox(res, { config, driver, store, capacity }, body) {
+    const id = SandboxStore.newId();
+    const image = typeof body.image === "string" ? body.image : config.defaultImage;
+    // Per-sandbox isolation selection: pick the runtime driver (default SBX_DRIVER).
+    const driverName = typeof body.driver === "string" && body.driver ? body.driver : config.driver;
+    if (!DRIVER_NAMES.includes(driverName)) {
+        return sendJson(res, 400, {
+            error: `unknown driver "${driverName}" (expected: ${DRIVER_NAMES.join(" | ")})`,
+        });
+    }
+    const labels = body.labels ?? {};
+    const persist = body.persist !== false;
+    const sleepAfterMs = typeof body.sleepAfter === "number" ? body.sleepAfter : config.defaultSleepAfterMs;
+    const setup = Array.isArray(body.setup)
+        ? body.setup.filter((s) => typeof s === "string")
+        : undefined;
+    const repo = typeof body.repo === "string" && body.repo ? body.repo : undefined;
+    const repoRef = typeof body.repoRef === "string" && body.repoRef ? body.repoRef : undefined;
+    // Resolve hard resource caps: per-create value overrides the daemon default.
+    const resolved = resolveLimits(body, config);
+    if ("error" in resolved)
+        return sendJson(res, 400, { error: resolved.error });
+    const limits = resolved.limits;
+    // Admission control: refuse to over-subscribe the host's memory budget.
+    const admitted = capacity?.admit(limits.memoryMb) ?? { ok: true };
+    if (!admitted.ok)
+        return sendJson(res, 503, { error: admitted.reason });
+    // Egress wiring. `egress: true` (or a policy object) opts the sandbox's LLM SDKs
+    // into the gateway (provider base-URL + key env). Independently, when egress
+    // enforcement is ON every sandbox is locked to the gateway, so it also gets a
+    // token + `HTTP(S)_PROXY` so pip/npm/git/apt can reach the allowlist.
+    let egressToken;
+    let egressPolicy = {};
+    let env = body.env ?? {};
+    const wantEgress = body.egress === true || (!!body.egress && typeof body.egress === "object");
+    if (typeof body.egress === "object" && body.egress) {
+        const parsed = parseEgressPolicy(body.egress);
+        if ("error" in parsed)
+            return sendJson(res, 400, { error: parsed.error });
+        egressPolicy = parsed.policy;
+    }
+    if (wantEgress || config.egressEnforce) {
+        egressToken = SandboxStore.newEgressToken();
+        // microVM guests have no NIC: their route to the gateway is the in-guest
+        // loopback relay (agent listener on 127.0.0.1:<egressPort> → vsock → host),
+        // so their env points at localhost instead of the gateway's host address.
+        const advertiseHost = driverName !== "container" ? "127.0.0.1" : undefined;
+        if (wantEgress)
+            env = { ...env, ...egressEnv(config, egressToken, advertiseHost) };
+        if (config.egressEnforce)
+            env = { ...env, ...proxyEnv(config, egressToken, advertiseHost) };
+    }
+    try {
+        await driver.create({ id, image, driver: driverName, env, labels, persist, setup, repo, repoRef, limits });
+    }
+    catch (err) {
+        // Provisioning failed (e.g. repo clone) — tear down the half-built container
+        // so it doesn't orphan, and report the failure instead of leaking it.
+        await driver.destroy(id).catch(() => { });
+        return sendJson(res, 422, { error: `sandbox provisioning failed: ${errorMessage(err)}` });
+    }
+    // Per-sandbox LLM spend ceiling: per-create value (if a valid non-negative
+    // number) overrides the daemon default; 0 = unlimited.
+    const egressSpendCapUsd = typeof body.egressSpendCapUsd === "number" && body.egressSpendCapUsd >= 0
+        ? body.egressSpendCapUsd
+        : config.egressSpendCapUsd;
+    const now = new Date().toISOString();
+    const record = {
+        id,
+        image,
+        status: "running",
+        createdAt: now,
+        driver: driverName,
+        labels,
+        env,
+        persist,
+        lastActivityAt: now,
+        sleepAfterMs,
+        limits,
+        egressSpendCapUsd,
+        usage: emptyUsage(),
+    };
+    store.add(record);
+    if (egressToken)
+        store.addEgressToken(egressToken, id, egressPolicy);
+    sendJson(res, 201, record);
+}
+async function stopSandbox(res, { driver, store }, id) {
+    const record = store.get(id);
+    if (!record)
+        return sendJson(res, 404, { error: "not found" });
+    if (record.status === "stopped")
+        return sendJson(res, 200, record);
+    await driver.stop(id);
+    // Processes and exposed ports die with the container; sessions persist.
+    store.clearRuntimeState(id);
+    record.status = "stopped";
+    store.add(record); // write-through the status change
+    sendJson(res, 200, record);
+}
+async function startSandbox(res, { driver, store }, id) {
+    const record = store.get(id);
+    if (!record)
+        return sendJson(res, 404, { error: "not found" });
+    if (record.status === "running")
+        return sendJson(res, 200, record);
+    await resumeSandbox(driver, store, record);
+    sendJson(res, 200, record);
+}
+/**
+ * Manual fast-pause: the strongest pause the sandbox's driver offers (memory
+ * snapshot on microVM drivers — background processes come back alive; cold
+ * stop-with-volume otherwise). Unlike `stop`, any later operation transparently
+ * resumes the sandbox.
+ */
+async function pauseSandboxRoute(res, { driver, store }, id) {
+    const record = store.get(id);
+    if (!record)
+        return sendJson(res, 404, { error: "not found" });
+    if (record.status === "paused")
+        return sendJson(res, 200, record);
+    if (record.status === "stopped") {
+        return sendJson(res, 409, { error: "sandbox is stopped; start it first" });
+    }
+    await pauseSandbox(driver, store, record);
+    sendJson(res, 200, record);
+}
+/**
+ * Resolve a sandbox that must be live to do work. Records the activity (so the
+ * idle reaper sees recent use), transparently resumes a `paused` sandbox, and
+ * rejects a manually `stopped` one (409 — the user must `start` it). Sends the
+ * error response itself and returns null on failure.
+ */
+async function ensureLive(res, driver, store, id) {
+    const record = store.get(id);
+    if (!record) {
+        sendJson(res, 404, { error: "not found" });
+        return null;
+    }
+    if (record.status === "stopped") {
+        sendJson(res, 409, { error: "sandbox is stopped; start it first" });
+        return null;
+    }
+    if (record.status === "paused") {
+        await resumeSandbox(driver, store, record);
+    }
+    else {
+        store.touch(id);
+    }
+    return record;
+}
+/**
+ * Resource metrics + cost for a sandbox. A live snapshot is included only when
+ * the sandbox is running (a paused/stopped sandbox has no container); the
+ * accumulated usage and cost are always returned. Reading metrics is a passive
+ * query — it does not count as activity nor auto-resume a paused sandbox.
+ */
+async function getMetrics(res, { config, driver, store }, id, includeLive = true) {
+    const record = store.get(id);
+    if (!record)
+        return sendJson(res, 404, { error: "not found" });
+    let live = null;
+    if (includeLive && record.status === "running") {
+        try {
+            live = await driver.stats(id);
+        }
+        catch {
+            // Container may have just gone away; report accumulated usage only.
+        }
+    }
+    return sendJson(res, 200, {
+        status: record.status,
+        live,
+        usage: record.usage,
+        cost: computeCost(record.usage, config),
+    });
+}
+async function createBackup(res, { driver, store, backups }, id) {
+    const record = await ensureLive(res, driver, store, id);
+    if (!record)
+        return;
+    const backupId = SandboxStore.newBackupId();
+    await backups.ensureDir();
+    const { bytes } = await driver.createBackup(id, backups.tarPath(backupId));
+    const info = {
+        backupId,
+        sandboxId: id,
+        createdAt: new Date().toISOString(),
+        bytes,
+    };
+    await backups.save(info);
+    sendJson(res, 201, info);
+}
+async function restoreBackup(res, { driver, store, backups }, id, body) {
+    if (!store.get(id))
+        return sendJson(res, 404, { error: "not found" });
+    const backupId = body.backupId;
+    if (typeof backupId !== "string") {
+        return sendJson(res, 400, { error: "backupId is required" });
+    }
+    const info = await backups.get(backupId);
+    if (!info)
+        return sendJson(res, 404, { error: "backup not found" });
+    if (!(await ensureLive(res, driver, store, id)))
+        return;
+    await driver.restoreBackup(id, backups.tarPath(backupId));
+    sendJson(res, 200, { id, restored: backupId });
+}
+// --- code interpreter ------------------------------------------------------
+/** Run a command, accumulating its streams; never throws on non-zero exit. */
+async function execCapture(driver, id, command) {
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    await driver.exec(id, command, {}, (e) => {
+        if (e.type === "stdout")
+            stdout += e.data;
+        else if (e.type === "stderr")
+            stderr += e.data;
+        else
+            exitCode = e.exitCode;
+    });
+    return { stdout, stderr, exitCode };
+}
+function parseLanguage(value) {
+    return value === "python" || value === "javascript" ? value : undefined;
+}
+/** Provision a kernel: make the context dir + fifos, write it, start it. */
+async function startKernel(driver, store, id, language) {
+    const contextId = SandboxStore.newContextId();
+    const dir = `/workspace/.sbx/ctx-${contextId}`;
+    const setup = await execCapture(driver, id, `mkdir -p ${shellEscape(dir)} && mkfifo ${shellEscape(dir)}/in.fifo ${shellEscape(dir)}/out.fifo`);
+    if (setup.exitCode !== 0) {
+        throw new Error(`failed to set up code context: ${setup.stderr.trim()}`);
+    }
+    const kernel = kernelFor(language);
+    await driver.writeFile(id, { path: `${dir}/${kernel.filename}`, content: kernel.source });
+    const procId = SandboxStore.newProcId();
+    const { pid } = await driver.startProcess(id, procId, kernel.command(dir), {});
+    const ctx = {
+        contextId,
+        language,
+        dir,
+        procId,
+        pid,
+        seq: 0,
+        createdAt: new Date().toISOString(),
+    };
+    store.addContext(id, ctx);
+    return ctx;
+}
+/** Kill a context's kernel and remove its directory. */
+async function teardownKernel(driver, id, ctx) {
+    try {
+        await driver.killProcess(id, ctx.pid, "KILL");
+    }
+    catch {
+        // Kernel may already be gone; the rm below still cleans up.
+    }
+    await execCapture(driver, id, `rm -rf ${shellEscape(ctx.dir)}`);
+}
+async function createCodeContext(res, { driver, store }, id, body) {
+    if (!(await ensureLive(res, driver, store, id)))
+        return;
+    const language = parseLanguage(body.language ?? "python");
+    if (!language) {
+        return sendJson(res, 400, { error: "language must be 'python' or 'javascript'" });
+    }
+    const ctx = await startKernel(driver, store, id, language);
+    sendJson(res, 201, publicContext(ctx));
+}
+async function deleteCodeContext(res, { driver, store }, id, contextId) {
+    const ctx = store.getContext(id, contextId);
+    if (!ctx)
+        return sendJson(res, 404, { error: "context not found" });
+    await teardownKernel(driver, id, ctx);
+    store.removeContext(id, contextId);
+    sendJson(res, 200, { contextId, destroyed: true });
+}
+async function runCode(res, { driver, store }, id, body) {
+    if (!(await ensureLive(res, driver, store, id)))
+        return;
+    const code = body.code;
+    if (typeof code !== "string") {
+        return sendJson(res, 400, { error: "code is required" });
+    }
+    const timeoutMs = typeof body.timeoutMs === "number" ? body.timeoutMs : 30_000;
+    // Resolve the context: an explicit one (persistent), or a throwaway kernel
+    // for a one-off run.
+    let ctx;
+    let ephemeral = false;
+    if (typeof body.contextId === "string") {
+        const found = store.getContext(id, body.contextId);
+        if (!found)
+            return sendJson(res, 404, { error: "context not found" });
+        ctx = found;
+    }
+    else {
+        const language = parseLanguage(body.language ?? "python");
+        if (!language) {
+            return sendJson(res, 400, { error: "language must be 'python' or 'javascript'" });
+        }
+        ctx = await startKernel(driver, store, id, language);
+        ephemeral = true;
+    }
+    try {
+        const result = await runCell(driver, id, ctx, code, timeoutMs);
+        if (!ephemeral)
+            store.addContext(id, ctx); // write-through the bumped seq
+        sendJson(res, 200, result);
+    }
+    finally {
+        if (ephemeral) {
+            await teardownKernel(driver, id, ctx);
+            store.removeContext(id, ctx.contextId);
+        }
+    }
+}
+/** Drive one cell through the kernel's fifo handshake and read its result. */
+async function runCell(driver, id, ctx, code, timeoutMs) {
+    const seq = ++ctx.seq;
+    await driver.writeFile(id, { path: `${ctx.dir}/cell-${seq}.code`, content: code });
+    const seconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+    // Push the seq to the kernel and block until it signals completion. If the
+    // kernel is wedged or the cell runs too long, `timeout` aborts the handshake.
+    const handshake = await execCapture(driver, id, `timeout ${seconds} sh -c 'printf "%s" "${seq}" > ${ctx.dir}/in.fifo && read _ < ${ctx.dir}/out.fifo'`);
+    if (handshake.exitCode === 124 || handshake.exitCode === 137) {
+        return {
+            stdout: "",
+            stderr: "",
+            results: [],
+            error: `code execution timed out after ${seconds}s`,
+        };
+    }
+    const raw = await driver.readFile(id, { path: `${ctx.dir}/cell-${seq}.result.json` });
+    return JSON.parse(raw);
+}
+function publicContext(ctx) {
+    return {
+        contextId: ctx.contextId,
+        language: ctx.language,
+        createdAt: ctx.createdAt,
+    };
+}
+async function execInSandbox(res, { driver, store }, id, body) {
+    const record = await ensureLive(res, driver, store, id);
+    if (!record)
+        return;
+    const command = body.command;
+    if (typeof command !== "string" || command.length === 0) {
+        return sendJson(res, 400, { error: "command is required" });
+    }
+    // Resolve an optional session: it contributes a working directory and an env
+    // overlay, and its cwd follows `cd` across commands. Env precedence (lowest
+    // to highest): sandbox -> session -> request.
+    const requestEnv = body.env ?? {};
+    const requestCwd = typeof body.cwd === "string" ? body.cwd : undefined;
+    let session;
+    if (typeof body.sessionId === "string") {
+        session = store.getSession(id, body.sessionId);
+        if (!session)
+            return sendJson(res, 404, { error: "session not found" });
+    }
+    const env = { ...record.env, ...(session?.env ?? {}), ...requestEnv };
+    const cwd = requestCwd ?? session?.cwd;
+    // For a session, capture the working directory the command leaves behind so a
+    // later `cd` persists. We append a `pwd` write that runs in the same shell as
+    // the user command (newline-delimited so a trailing comment can't swallow it).
+    let runCommand = command;
+    const cwdFile = session ? `/tmp/hotcell-sess-${session.sessionId}.cwd` : null;
+    if (cwdFile) {
+        runCommand =
+            `{\n${command}\n}\n__hc_rc=$?\n` +
+                `pwd > ${cwdFile} 2>/dev/null\nexit $__hc_rc`;
+    }
+    // Stream output as Server-Sent Events.
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    const write = (event) => {
+        res.write(`data: ${JSON.stringify(event)}\n\n`);
+    };
+    try {
+        await driver.exec(id, runCommand, { cwd, env }, write);
+        if (session && cwdFile) {
+            try {
+                const next = (await driver.readFile(id, { path: cwdFile })).trim();
+                if (next && next !== session.cwd) {
+                    session.cwd = next;
+                    store.addSession(id, session); // write-through the cwd change
+                }
+            }
+            catch {
+                // Best-effort cwd capture; keep the previous cwd on failure.
+            }
+        }
+    }
+    catch (err) {
+        write({ type: "stderr", data: String(err) });
+        write({ type: "exit", exitCode: 1 });
+    }
+    finally {
+        res.end();
+    }
+}
+async function watchFiles(req, res, { driver, store }, id, watchPath, intervalMs) {
+    if (!(await ensureLive(res, driver, store, id)))
+        return;
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    // Flush headers immediately with an SSE comment so clients (e.g. fetch) get
+    // the response before the first change event — which may be far in the future.
+    res.write(": watching\n\n");
+    // Stop the watcher when the client disconnects.
+    const controller = new AbortController();
+    req.on("close", () => controller.abort());
+    try {
+        await driver.watchFiles(id, watchPath, { intervalMs, signal: controller.signal }, (event) => res.write(`data: ${JSON.stringify(event)}\n\n`));
+    }
+    catch (err) {
+        res.write(`data: ${JSON.stringify({ type: "error", error: String(err) })}\n\n`);
+    }
+    finally {
+        res.end();
+    }
+}
+async function handleFileAction(res, { driver, store }, id, action, body) {
+    if (!(await ensureLive(res, driver, store, id)))
+        return;
+    const path = typeof body.path === "string" ? body.path : "";
+    if (!path)
+        return sendJson(res, 400, { error: "path is required" });
+    try {
+        switch (action) {
+            case "write": {
+                if (typeof body.content !== "string") {
+                    return sendJson(res, 400, { error: "content is required" });
+                }
+                await driver.writeFile(id, {
+                    path,
+                    content: body.content,
+                    mode: typeof body.mode === "string" ? body.mode : undefined,
+                });
+                return sendJson(res, 200, { ok: true });
+            }
+            case "read": {
+                const content = await driver.readFile(id, { path });
+                return sendJson(res, 200, { content });
+            }
+            case "mkdir": {
+                await driver.mkdir(id, { path, parents: body.parents === true });
+                return sendJson(res, 200, { ok: true });
+            }
+            case "list": {
+                const entries = await driver.listFiles(id, { path });
+                return sendJson(res, 200, { entries });
+            }
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return sendJson(res, 500, { error: message });
+    }
+}
+async function startProcess(res, { driver, store }, id, body) {
+    const record = await ensureLive(res, driver, store, id);
+    if (!record)
+        return;
+    const command = body.command;
+    if (typeof command !== "string" || command.length === 0) {
+        return sendJson(res, 400, { error: "command is required" });
+    }
+    const procId = SandboxStore.newProcId();
+    const opts = {
+        cwd: typeof body.cwd === "string" ? body.cwd : undefined,
+        env: { ...record.env, ...(body.env ?? {}) },
+    };
+    try {
+        const { pid, logPath } = await driver.startProcess(id, procId, command, opts);
+        const proc = {
+            procId,
+            pid,
+            command,
+            status: "running",
+            exitCode: null,
+            startedAt: new Date().toISOString(),
+            logPath,
+        };
+        store.addProcess(id, proc);
+        return sendJson(res, 201, proc);
+    }
+    catch (err) {
+        return sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+async function listProcesses(res, { driver, store }, id) {
+    if (!store.get(id))
+        return sendJson(res, 404, { error: "not found" });
+    const procs = store.listProcesses(id);
+    if (procs.length > 0) {
+        try {
+            const liveness = await driver.listProcesses(id, procs.map((p) => ({ procId: p.procId, pid: p.pid })));
+            const running = new Map(liveness.map((l) => [l.procId, l.running]));
+            for (const p of procs) {
+                if (p.status === "running" && running.get(p.procId) === false) {
+                    p.status = "exited";
+                    store.addProcess(id, p); // write-through the exited status
+                }
+            }
+        }
+        catch {
+            // Liveness refresh is best-effort; fall back to last-known status.
+        }
+    }
+    return sendJson(res, 200, { processes: store.listProcesses(id) });
+}
+async function killProcess(res, { driver, store }, id, procId, body) {
+    if (!store.get(id))
+        return sendJson(res, 404, { error: "not found" });
+    const proc = store.getProcess(id, procId);
+    if (!proc)
+        return sendJson(res, 404, { error: "process not found" });
+    const signal = typeof body.signal === "string" ? body.signal : undefined;
+    try {
+        await driver.killProcess(id, proc.pid, signal);
+        proc.status = "exited";
+        store.addProcess(id, proc); // write-through the exited status
+        return sendJson(res, 200, { ok: true });
+    }
+    catch (err) {
+        return sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+async function streamLogs(req, res, { driver, store }, id, procId, follow) {
+    if (!store.get(id))
+        return sendJson(res, 404, { error: "not found" });
+    const proc = store.getProcess(id, procId);
+    if (!proc)
+        return sendJson(res, 404, { error: "process not found" });
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    const controller = new AbortController();
+    req.on("close", () => controller.abort());
+    try {
+        await driver.streamProcessLogs(id, proc.logPath, { follow, signal: controller.signal }, (data) => res.write(`data: ${JSON.stringify({ type: "log", data })}\n\n`));
+    }
+    catch (err) {
+        res.write(`data: ${JSON.stringify({ type: "log", data: errorMessage(err) })}\n\n`);
+    }
+    finally {
+        res.write(`data: ${JSON.stringify({ type: "end" })}\n\n`);
+        res.end();
+    }
+}
+async function waitForPort(res, { driver, store }, id, body) {
+    if (!(await ensureLive(res, driver, store, id)))
+        return;
+    const port = Number(body.port);
+    if (!Number.isInteger(port) || port <= 0) {
+        return sendJson(res, 400, { error: "port is required" });
+    }
+    try {
+        const ready = await driver.waitForPort(id, port, {
+            timeoutMs: typeof body.timeoutMs === "number" ? body.timeoutMs : undefined,
+            intervalMs: typeof body.intervalMs === "number" ? body.intervalMs : undefined,
+            host: typeof body.host === "string" ? body.host : undefined,
+        });
+        return sendJson(res, 200, { ready });
+    }
+    catch (err) {
+        return sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+async function exposePort(res, { config, driver, store }, id, body) {
+    if (!(await ensureLive(res, driver, store, id)))
+        return;
+    const port = Number(body.port);
+    if (!Number.isInteger(port) || port <= 0) {
+        return sendJson(res, 400, { error: "port is required" });
+    }
+    const exposed = {
+        port,
+        exposeId: `${id}-${port}`,
+        token: typeof body.token === "string" ? body.token : null,
+        createdAt: new Date().toISOString(),
+        url: previewUrl(config, id, port),
+    };
+    store.addExposed(id, exposed);
+    return sendJson(res, 201, exposed);
+}
+function unexposePort(res, { store }, id, port) {
+    if (!store.get(id))
+        return sendJson(res, 404, { error: "not found" });
+    const removed = store.removeExposed(id, port);
+    if (!removed)
+        return sendJson(res, 404, { error: "port not exposed" });
+    return sendJson(res, 200, { ok: true });
+}
+function createSession(res, { store }, id, body) {
+    if (!store.get(id))
+        return sendJson(res, 404, { error: "not found" });
+    const sessionId = typeof body.id === "string" && body.id.length > 0
+        ? body.id
+        : SandboxStore.newSessionId();
+    if (store.getSession(id, sessionId)) {
+        return sendJson(res, 409, { error: "session already exists" });
+    }
+    const session = {
+        sessionId,
+        cwd: typeof body.cwd === "string" ? body.cwd : "/workspace",
+        env: body.env ?? {},
+        createdAt: new Date().toISOString(),
+    };
+    store.addSession(id, session);
+    return sendJson(res, 201, session);
+}
+function setSessionEnv(res, { store }, id, sessionId, body) {
+    if (!store.get(id))
+        return sendJson(res, 404, { error: "not found" });
+    const session = store.getSession(id, sessionId);
+    if (!session)
+        return sendJson(res, 404, { error: "session not found" });
+    const env = body.env ?? {};
+    session.env = { ...session.env, ...env };
+    store.addSession(id, session); // write-through the env change
+    return sendJson(res, 200, session);
+}
+function deleteSession(res, { store }, id, sessionId) {
+    if (!store.get(id))
+        return sendJson(res, 404, { error: "not found" });
+    const removed = store.removeSession(id, sessionId);
+    if (!removed)
+        return sendJson(res, 404, { error: "session not found" });
+    return sendJson(res, 200, { ok: true });
+}
+// --- helpers ---------------------------------------------------------------
+async function readJson(req, maxBytes) {
+    const body = await readBodyCapped(req, maxBytes);
+    if (body.length === 0)
+        return {};
+    try {
+        return JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=server.js.map