@hotcell/daemon 0.1.0

package/dist/agent-check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent-check.js

@@ -0,0 +1,105 @@
+/**
+ * Docker-free, VM-free check of the host↔guest agent protocol. Runs the real Go
+ * `sbx-agent` over a unix socket (its dev transport) and drives it through the TS
+ * `AgentConn` client — validating the wire protocol end-to-end on macOS with no
+ * microVM. The same client + protocol then carry every Driver op once the VZ
+ * helper relays a guest vsock to a unix socket. Run: `npm run check:agent`.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync } from "node:fs";
+import { createServer as createHttpServer } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import { setTimeout as sleep } from "node:timers/promises";
+import { AgentConn } from "./driver/agent.js";
+async function main() {
+    const bin = process.env.HOTCELL_AGENT_BIN ?? "/tmp/hotcell-agent-check";
+    const dir = mkdtempSync(join(tmpdir(), "hotcell-agent-"));
+    const sock = join(dir, "agent.sock");
+    const egressTargetSock = join(dir, "egress-target.sock");
+    const proc = spawn(bin, [], {
+        env: {
+            ...process.env,
+            HOTCELL_AGENT_LISTEN: `unix://${sock}`,
+            // Egress relay test override: instead of vsock (no VM here), the agent
+            // dials this unix socket, where the check hosts a mock gateway.
+            HOTCELL_EGRESS_DIAL: `unix://${egressTargetSock}`,
+        },
+        stdio: ["ignore", "ignore", "inherit"],
+    });
+    let passed = 0;
+    const ok = (label) => {
+        passed++;
+        console.log(`  ✓ ${label}`);
+    };
+    try {
+        for (let i = 0; i < 50 && !existsSync(sock); i++)
+            await sleep(100);
+        assert.ok(existsSync(sock), "agent unix socket should appear");
+        const conn = await AgentConn.connect({ path: sock });
+        assert.equal(conn.hello?.agent, "hotcell-agent", "Hello identifies the agent");
+        assert.equal(conn.hello?.proto, 1, "proto version");
+        ok(`Hello received (version ${conn.hello?.version})`);
+        // exec: stdout + stderr + exit code (cwd set since the guest default /workspace
+        // doesn't exist on the mac host running this check).
+        let out = "";
+        let err = "";
+        const code = await conn.exec("echo out-line && echo err-line >&2 && exit 3", { cwd: dir }, (e) => {
+            if (e.type === "stdout")
+                out += e.data;
+            if (e.type === "stderr")
+                err += e.data;
+        });
+        assert.equal(code, 3, "exec exit code");
+        assert.match(out, /out-line/, "exec stdout");
+        assert.match(err, /err-line/, "exec stderr");
+        ok("exec: stdout/stderr streaming + exit code");
+        // writeFile / readFile round-trip.
+        await conn.writeFile(join(dir, "f.txt"), "data-123");
+        assert.equal(await conn.readFile(join(dir, "f.txt")), "data-123");
+        ok("writeFile + readFile round-trip");
+        // mkdir + listFiles.
+        await conn.mkdir(join(dir, "sub"), true);
+        const files = await conn.listFiles(dir);
+        assert.ok(files.some((f) => f.name === "f.txt"), "listFiles sees the file");
+        assert.ok(files.some((f) => f.name === "sub" && f.isDirectory), "listFiles sees the dir");
+        ok("mkdir + listFiles");
+        // env overlay: setEnv then read it back via exec.
+        await conn.setEnv({ SBX_TEST_VAR: "xyz" });
+        let envOut = "";
+        await conn.exec("echo $SBX_TEST_VAR", { cwd: dir }, (e) => {
+            if (e.type === "stdout")
+                envOut += e.data;
+        });
+        assert.match(envOut, /xyz/, "setEnv applies to subsequent exec");
+        ok("setEnv overlay applies to exec");
+        // stats returns (a stub off-Linux, but the RPC round-trips).
+        assert.ok(await conn.stats(), "stats RPC returns");
+        ok("stats RPC");
+        // Egress relay: the agent listens on guest-loopback and forwards each
+        // connection out its dialer (vsock in production; HOTCELL_EGRESS_DIAL here).
+        // The check hosts the "gateway": an HTTP server on the dialed unix socket.
+        const gateway = createHttpServer((_req, res) => res.end("egress-pong"));
+        await new Promise((r) => gateway.listen(egressTargetSock, r));
+        const egressPort = 47521;
+        await conn.egressListen(egressPort);
+        const pong = await fetch(`http://127.0.0.1:${egressPort}/anything`);
+        assert.equal(await pong.text(), "egress-pong", "egress relay round-trip");
+        await conn.egressListen(egressPort); // idempotent re-arm (driver re-sends per boot)
+        const pong2 = await fetch(`http://127.0.0.1:${egressPort}/again`);
+        assert.equal(await pong2.text(), "egress-pong", "relay still serves after re-arm");
+        await new Promise((r) => gateway.close(() => r()));
+        ok("egress relay: loopback listener → dialer → mock gateway round-trip (idempotent)");
+        conn.close();
+        console.log(`\nagent-check: ${passed} checks passed`);
+    }
+    finally {
+        proc.kill();
+    }
+}
+main().then(() => process.exit(0), (err) => {
+    console.error("agent-check FAILED:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=agent-check.js.map

package/dist/agent-check.js.map

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

package/dist/api/server.d.ts

@@ -0,0 +1,64 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { BackupRegistry } from "../backups.js";
+import { type Config } from "../config.js";
+import type { Driver } from "../driver/types.js";
+import type { Capacity } from "../capacity.js";
+import type { MetricsHistory } from "../metrics.js";
+import { SandboxStore } from "../store.js";
+interface Deps {
+    config: Config;
+    driver: Driver;
+    store: SandboxStore;
+    backups: BackupRegistry;
+    history?: MetricsHistory;
+    capacity?: Capacity;
+}
+/**
+ * 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 declare function createApiServer(deps: Deps): import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+export {};