@spunto/build 0.15.0 → 0.17.0

package/README.md

@@ -198,6 +198,59 @@ What dtach doesn't do is remember the screen, so the session is recorded inside
 scripts this module builds, so anything that doesn't come through it is a command injection into
 someone's container.
 
+### `@spunto/build/sandbox-agent` — the agent that lives in the box
+
+A box that carries its own agent needs no Docker socket on the control plane's side: its main
+process runs `bootstrap.sh`, which runs `agent.mjs`, which dials the control plane over a WebSocket
+and serves exec, persistent terminals (dtach + `script(1)` + replay), TCP tunnels, listening ports
+and the project's setup state. The three files ship here **as files**. This package does not read
+them; it says where they are, and you serve them:
+
+```ts
+import { readFileSync } from "node:fs"
+import { SANDBOX_AGENT_FILES, SANDBOX_AGENT_CONTENT_TYPES } from "@spunto/build/sandbox-agent"
+
+app.get("/api/sandboxes/agent.mjs", (c) =>
+  c.body(readFileSync(SANDBOX_AGENT_FILES.agent, "utf8"), 200, { "Content-Type": SANDBOX_AGENT_CONTENT_TYPES.agent }))
+```
+
+`SPUNTO_AGENT_URL`, `SPUNTO_AGENT_CONNECT_URL` and `SPUNTO_NODE` (a Node >= 22 you mounted in the
+box, so nothing is downloaded) point it at any control plane.
+
+### `@spunto/build/agent-protocol` — the wire, written down
+
+The messages both ways (`PlatformMessage`, `AgentMessage`), the project plan, the close codes and
+cadences, and the codec of tunnel frames (`[1][id length][id][payload]`). Additive only: a message
+either side does not know is ignored by the other.
+
+### `@spunto/build/agent-connection` — the control plane's half
+
+`AgentConnection` keeps what waits on one agent (execs, requests, terminals, tunnels) and routes
+the wire's messages to it. It works on a minimal socket that its owner *feeds* — so no WebSocket
+library comes with it:
+
+```ts
+import { AgentConnection } from "@spunto/build/agent-connection"
+
+wss.on("connection", (ws) => ws.once("message", (raw) => {
+  // …authenticate the hello yourself…
+  const conn = new AgentConnection(ws, { label: "Worker", onMessage: (m) => m.type === "project_state" && save(m.state) })
+  ws.on("message", (data, isBinary) => conn.receive(data, isBinary))
+  ws.on("pong", () => conn.heard())
+  ws.on("close", () => conn.closed())
+}))
+
+await conn.exec({ command: "git status", timeoutMs: 30_000 })
+```
+
+### `@spunto/build/commands` — background commands, the scripts
+
+A background command is a directory in the box (`~/.spunto/commands/<id>/`), so it outlives the
+control plane that started it. `startScript`, `pollScript`, `readScript`, `stdinScript` and
+`cancelScript` build the shell; `commandFields` reads what it prints. Run them however you reach the
+box — `docker exec`, or the agent's `exec`. `isCommandId` is a security boundary, like
+`sanitizeSessionName`.
+
 ## The rule
 
 A module belongs in this package only if it imports **no** ORM schema, **no** HTTP framework, **no**
@@ -212,6 +265,10 @@ consumer that imports `./naming` or `./steps` and nothing else should not have a
 installed on its behalf. Import `./spec` without zod and resolution fails loudly, which is the
 right trade for not taxing every other entry point.
 
+**The one place that reads its environment is `./sandbox-agent`** — and it is not module code: those
+are files a control plane serves into a box, where they *are* the process. Nothing in this package
+imports them.
+
 Concretely: **no platform I/O**. No database, no Docker socket, no WebSocket. This package produces
 strings and parses strings. Its only network calls are outbound HTTP on the caller's behalf — a
 public extension registry, and a model vendor's catalogue endpoint when you hand
@@ -226,10 +283,10 @@ degrades instead of throwing.
 
 ## What's deliberately *not* in it
 
-Image script generation (`buildImageScript` & co.), the devcontainer catalogs, the Docker client and
-the terminal bridge — all still duplicated between the two products, all staged for later. The
-reasoning, the measurements and the plan are in
-[RFC 0021](https://github.com/coderhammer/spunto/blob/main/rfc/0021-paquet-partage-build.md).
+The Docker client, the registry of connections and the authentication of an agent — each control
+plane keys and trusts its boxes its own way. The reasoning, the measurements and the plan are in
+[RFC 0021](https://github.com/coderhammer/spunto/blob/main/rfc/0021-paquet-partage-build.md) and
+[RFC 0047](https://github.com/coderhammer/spunto/blob/main/rfc/0047-l-agent-embarque-dans-spunto-build.md).
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Spunto's shared Build engine — the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",
@@ -62,7 +62,26 @@
     "./agent-stream": {
       "types": "./src/agent-stream/index.ts",
       "import": "./src/agent-stream/index.ts"
-    }
+    },
+    "./agent-protocol": {
+      "types": "./src/agent-protocol/index.ts",
+      "import": "./src/agent-protocol/index.ts"
+    },
+    "./agent-connection": {
+      "types": "./src/agent-connection/index.ts",
+      "import": "./src/agent-connection/index.ts"
+    },
+    "./commands": {
+      "types": "./src/commands/index.ts",
+      "import": "./src/commands/index.ts"
+    },
+    "./sandbox-agent": {
+      "types": "./src/sandbox-agent/index.ts",
+      "import": "./src/sandbox-agent/index.ts"
+    },
+    "./sandbox-agent/agent.mjs": "./src/sandbox-agent/agent.mjs",
+    "./sandbox-agent/bootstrap.sh": "./src/sandbox-agent/bootstrap.sh",
+    "./sandbox-agent/runner.sh": "./src/sandbox-agent/runner.sh"
   },
   "files": [
     "src",
@@ -78,6 +97,7 @@
   "devDependencies": {
     "typescript": "^5",
     "vitest": "^4.1.10",
+    "ws": "^8.22.0",
     "zod": "^4.6.5"
   },
   "peerDependencies": {

package/src/agent-connection/index.ts

@@ -0,0 +1,347 @@
+/**
+ * The control plane's half of one in-box agent's connection (RFC 0047 § 3.3): what is waiting on
+ * the agent — execs, requests, terminals, tunnels — and how the wire's messages reach it.
+ *
+ * No WebSocket library in here: the connection works on `AgentSocket`, which the `WebSocket` of
+ * `ws` satisfies as is, and is *fed* by its owner — `receive` for each frame, `heard` for each
+ * pong, `closed` once. Who the agent is (its `hello`, its token) and where connections are kept
+ * (by sandbox, by worker) stay with the app; so does anything about freezing a box, which comes in
+ * through `deadline` and the liveness options.
+ */
+
+import {
+  AGENT_PING_MS,
+  AGENT_SILENCE_MS,
+  decodeTunnelFrame,
+  encodeTunnelFrame,
+  type AgentMessage,
+  type ExecResult,
+  type PlatformMessage,
+} from "../agent-protocol/index"
+
+/** What the connection needs of a socket. `ws`'s `WebSocket` is one. */
+export interface AgentSocket {
+  /** 1 = open, as in the WebSocket standard. */
+  readonly readyState: number
+  readonly bufferedAmount: number
+  send(data: string | Uint8Array): void
+  close(code?: number, reason?: string): void
+  /** Drops the socket without a closing handshake — a peer that is gone never completes one. */
+  terminate?(): void
+  /** A protocol-level ping, answered by a pong the owner reports with `heard()`. */
+  ping?(): void
+}
+
+const OPEN = 1
+
+/** A timer that may be cancelled. The default is a plain `setTimeout`. */
+export type Deadline = { cancel(): void }
+export type DeadlineFactory = (budgetMs: number, onTimeout: () => void) => Deadline
+
+const plainDeadline: DeadlineFactory = (budgetMs, onTimeout) => {
+  const t = setTimeout(onTimeout, budgetMs)
+  return { cancel: () => clearTimeout(t) }
+}
+
+/** `agentGone`: the agent's connection dropped (a resume, a redial) — the session itself lives on. */
+export type TerminalHandlers = { onData: (data: Uint8Array) => void; onExit: (code: number | null, agentGone?: boolean) => void }
+export type TunnelHandlers = { onData: (data: Uint8Array) => void; onClose: (error?: string) => void }
+
+export type AgentConnectionOptions = {
+  /** Timers for execs and requests (a freeze-aware one, for a control plane that freezes boxes). */
+  deadline?: DeadlineFactory
+  /** Every message from the agent, after the connection has handled it — `project_state`, `heartbeat`… */
+  onMessage?: (msg: AgentMessage) => void
+  /** Anything at all came from the agent (a frame, a pong). */
+  onHeard?: () => void
+  liveness?: {
+    /** A connection silent this long is terminated and `onSilent` told. */
+    silenceMs?: number
+    /** Not now: the silence is not counted (a box frozen on purpose). */
+    paused?: () => boolean
+    /** Count the silence from no earlier than this (a box that just came out of a freeze). */
+    since?: () => number
+    onSilent?: () => void
+  }
+  /** The application-level `ping`. 0 turns it off. */
+  pingMs?: number
+  /** Ids of execs and requests. */
+  newId?: () => string
+  /**
+   * What the box is called in the errors this connection rejects with: "Sandbox" gives "Sandbox
+   * agent is not connected", "Sandbox agent disconnected", "Sandbox exec timed out"… — callers
+   * match on those to tell an unreachable box from a failed command.
+   */
+  label?: string
+}
+
+type Pending<T> = { resolve: (r: T) => void; reject: (e: Error) => void; timer: Deadline }
+type Tunnel = TunnelHandlers & { ready?: Pending<void> }
+
+const NodeBuffer = (globalThis as { Buffer?: { from(data: string | Uint8Array, enc?: string): Uint8Array & { toString(enc: string): string } } }).Buffer
+
+/** Base64 of bytes — Node's Buffer where there is one, the platform's `btoa` elsewhere. */
+export function bytesToBase64(bytes: Uint8Array): string {
+  if (NodeBuffer) return NodeBuffer.from(bytes).toString("base64")
+  let bin = ""
+  for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
+  return btoa(bin)
+}
+
+export function base64ToBytes(b64: string): Uint8Array {
+  if (NodeBuffer) return NodeBuffer.from(b64, "base64")
+  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0))
+}
+
+export class AgentConnection {
+  readonly connectedAt = Date.now()
+  lastHeartbeat: Record<string, unknown> | null = null
+  private lastHeardAt = Date.now()
+  private readonly execs = new Map<string, Pending<ExecResult>>()
+  private readonly requests = new Map<string, Pending<unknown>>()
+  private readonly terminals = new Map<string, TerminalHandlers>()
+  private readonly tunnels = new Map<string, Tunnel>()
+  private readonly timers: ReturnType<typeof setInterval>[] = []
+  private readonly deadline: DeadlineFactory
+  private readonly newId: () => string
+  private readonly label: string
+  private ended = false
+
+  constructor(
+    readonly socket: AgentSocket,
+    private readonly options: AgentConnectionOptions = {},
+  ) {
+    this.deadline = options.deadline ?? plainDeadline
+    this.newId = options.newId ?? (() => crypto.randomUUID())
+    this.label = options.label ?? "Box"
+    const pingMs = options.pingMs ?? AGENT_PING_MS
+    if (pingMs > 0) this.timers.push(setInterval(() => this.send({ type: "ping", at: Date.now() }), pingMs))
+    const silenceMs = options.liveness?.silenceMs ?? AGENT_SILENCE_MS
+    const every = Math.min(15_000, Math.max(1_000, Math.floor(silenceMs / 3)))
+    this.timers.push(setInterval(() => this.checkLiveness(silenceMs), every))
+  }
+
+  get online(): boolean {
+    return !this.ended && this.socket.readyState === OPEN
+  }
+
+  /** What the socket still has to write — for the caller's backpressure. */
+  get bufferedAmount(): number {
+    return this.socket.bufferedAmount
+  }
+
+  // ── fed by the owner ─────────────────────────────────────────────────────────────────────
+
+  /** One frame from the agent: text (JSON), or binary (tunnel bytes). */
+  receive(data: Uint8Array | string, isBinary: boolean): void {
+    this.heard()
+    if (isBinary && typeof data !== "string") {
+      const frame = decodeTunnelFrame(data)
+      if (frame) this.tunnels.get(frame.tunnelId)?.onData(frame.payload)
+      return
+    }
+    let msg: AgentMessage
+    try {
+      msg = JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data))
+    } catch {
+      return
+    }
+    this.handle(msg)
+    this.options.onMessage?.(msg)
+  }
+
+  /** A pong, or anything else that says the agent is there. */
+  heard(): void {
+    this.lastHeardAt = Date.now()
+    this.options.onHeard?.()
+  }
+
+  /** The socket closed: everything waiting on it fails now. Idempotent. */
+  closed(): void {
+    if (this.ended) return
+    this.ended = true
+    for (const t of this.timers) clearInterval(t)
+    const gone = () => new Error(`${this.label} agent disconnected`)
+    for (const p of [...this.requests.values(), ...this.execs.values()]) {
+      p.timer.cancel()
+      p.reject(gone())
+    }
+    this.requests.clear()
+    this.execs.clear()
+    for (const t of this.terminals.values()) t.onExit(null, true)
+    this.terminals.clear()
+    for (const t of this.tunnels.values()) {
+      if (t.ready) {
+        t.ready.timer.cancel()
+        t.ready.reject(gone())
+      } else t.onClose(`${this.label.toLowerCase()} agent disconnected`)
+    }
+    this.tunnels.clear()
+  }
+
+  // ── asked by the app ─────────────────────────────────────────────────────────────────────
+
+  send(msg: PlatformMessage): void {
+    if (this.online) this.socket.send(JSON.stringify(msg))
+  }
+
+  /** Drop the connection now (the box is known dead): pending calls fail at once. */
+  drop(): void {
+    if (this.socket.terminate) this.socket.terminate()
+    else this.socket.close()
+    this.closed()
+  }
+
+  /** Run a command in the box, with a login shell, as the project's user. */
+  exec(params: { command: string; cwd?: string; env?: Record<string, string>; timeoutMs?: number }): Promise<ExecResult> {
+    if (!this.online) return Promise.reject(new Error(`${this.label} agent is not connected`))
+    const id = this.newId()
+    const timeoutMs = params.timeoutMs ?? 60_000
+    return new Promise<ExecResult>((resolve, reject) => {
+      // A little longer than the agent's own kill timer, so the normal path is the agent's
+      // `timedOut: true` result rather than this rejection.
+      const timer = this.deadline(timeoutMs + 10_000, () => {
+        this.execs.delete(id)
+        reject(new Error(`${this.label} exec timed out`))
+      })
+      this.execs.set(id, { resolve, reject, timer })
+      this.send({ type: "exec", id, ...params, timeoutMs })
+    })
+  }
+
+  /** A request the agent answers with a `reply` (`sessions`, `ports`). */
+  request<T>(msg: { type: "sessions"; op?: "list" | "create" | "kill"; name?: string } | { type: "ports" }, timeoutMs = 15_000): Promise<T> {
+    if (!this.online) return Promise.reject(new Error(`${this.label} agent is not connected`))
+    const id = this.newId()
+    return new Promise<T>((resolve, reject) => {
+      const timer = this.deadline(timeoutMs, () => {
+        this.requests.delete(id)
+        reject(new Error(`${this.label} agent did not answer`))
+      })
+      this.requests.set(id, { resolve: resolve as (r: unknown) => void, reject, timer })
+      this.send({ ...msg, id } as PlatformMessage)
+    })
+  }
+
+  /**
+   * `session`: the dtach session to attach to (created if absent) — it outlives this connection.
+   * `logs`: the project runner's output, followed — a worker's "container logs".
+   */
+  openTerminal(termId: string, opts: { cols: number; rows: number; session?: string; mode?: "terminal" | "logs" }, handlers: TerminalHandlers): void {
+    if (!this.online) throw new Error(`${this.label} agent is not connected`)
+    this.terminals.set(termId, handlers)
+    this.send({ type: "term_open", termId, cols: opts.cols, rows: opts.rows, session: opts.session ?? "main", mode: opts.mode ?? "terminal" })
+  }
+
+  terminalInput(termId: string, data: Uint8Array): void {
+    this.send({ type: "term_input", termId, data: bytesToBase64(data) })
+  }
+
+  terminalResize(termId: string, cols: number, rows: number): void {
+    this.send({ type: "term_resize", termId, cols, rows })
+  }
+
+  closeTerminal(termId: string): void {
+    this.terminals.delete(termId)
+    this.send({ type: "term_close", termId })
+  }
+
+  /** Resolves once the agent is connected to the port; rejects when nothing listens there. */
+  openTunnel(tunnelId: string, port: number, handlers: TunnelHandlers, timeoutMs = 10_000): Promise<void> {
+    if (!this.online) return Promise.reject(new Error(`${this.label} agent is not connected`))
+    return new Promise<void>((resolve, reject) => {
+      // Not the freeze-aware deadline: a tunnel is a browser waiting, now.
+      const timer = plainDeadline(timeoutMs, () => {
+        this.tunnels.delete(tunnelId)
+        reject(new Error(`${this.label} agent did not open the tunnel`))
+      })
+      this.tunnels.set(tunnelId, { ...handlers, ready: { resolve, reject, timer } })
+      this.send({ type: "tunnel_open", tunnelId, port })
+    })
+  }
+
+  /** Returns the socket's buffered amount, for the caller's backpressure. */
+  sendTunnelData(tunnelId: string, data: Uint8Array): number {
+    if (!this.online) return 0
+    this.socket.send(encodeTunnelFrame(tunnelId, data))
+    return this.socket.bufferedAmount
+  }
+
+  closeTunnel(tunnelId: string): void {
+    if (!this.tunnels.delete(tunnelId)) return
+    this.send({ type: "tunnel_close", tunnelId })
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────────────────────
+
+  private handle(msg: AgentMessage): void {
+    switch (msg.type) {
+      case "exec_result": {
+        const pending = this.execs.get(msg.id)
+        if (!pending) return
+        pending.timer.cancel()
+        this.execs.delete(msg.id)
+        const { type: _t, id: _id, ...result } = msg
+        pending.resolve(result)
+        return
+      }
+      case "reply": {
+        const pending = this.requests.get(msg.id)
+        if (!pending) return
+        pending.timer.cancel()
+        this.requests.delete(msg.id)
+        pending.resolve(msg.result)
+        return
+      }
+      case "term_data":
+        this.terminals.get(msg.termId)?.onData(base64ToBytes(msg.data ?? ""))
+        return
+      case "term_exit": {
+        const t = this.terminals.get(msg.termId)
+        this.terminals.delete(msg.termId)
+        t?.onExit(msg.code ?? null)
+        return
+      }
+      case "tunnel_ready": {
+        const t = this.tunnels.get(msg.tunnelId)
+        if (t?.ready) {
+          t.ready.timer.cancel()
+          t.ready.resolve()
+          t.ready = undefined
+        }
+        return
+      }
+      case "tunnel_close": {
+        const t = this.tunnels.get(msg.tunnelId)
+        this.tunnels.delete(msg.tunnelId)
+        if (t?.ready) {
+          t.ready.timer.cancel()
+          t.ready.reject(new Error(msg.error ?? "tunnel refused"))
+        } else t?.onClose(msg.error)
+        return
+      }
+      case "heartbeat": {
+        const { type: _t, ...rest } = msg
+        this.lastHeartbeat = { ...rest, at: new Date().toISOString() }
+        return
+      }
+      case "probe":
+        // The agent was frozen and asks whether this socket still reaches us.
+        if (this.online) this.socket.send(JSON.stringify({ type: "probe_ack", id: msg.id }))
+        return
+    }
+  }
+
+  private checkLiveness(silenceMs: number): void {
+    if (!this.online || this.options.liveness?.paused?.()) return
+    const silentFor = Date.now() - Math.max(this.lastHeardAt, this.options.liveness?.since?.() ?? 0)
+    if (silentFor > silenceMs) {
+      this.drop()
+      this.options.liveness?.onSilent?.()
+      return
+    }
+    try {
+      this.socket.ping?.()
+    } catch {}
+  }
+}

package/src/agent-protocol/index.ts

@@ -0,0 +1,190 @@
+/**
+ * The wire between a control plane and the agent inside a box (RFC 0035, RFC 0047) — written down
+ * once. `agent.mjs` (`./sandbox-agent`) imports nothing, so these types do not constrain it: the
+ * agent's own tests, run against a fake platform, are what keep the two in step.
+ *
+ * One WebSocket per box, dialed by the agent. JSON text frames both ways, plus binary frames for
+ * tunnel bytes (`encodeTunnelFrame`). The agent authenticates in its first message (`hello`):
+ * Node's built-in WebSocket client cannot set headers.
+ *
+ * **Additive only.** A message either side does not know is ignored by the other — that is what
+ * lets an agent started before a deploy keep talking to the control plane after it. A field is
+ * never renamed nor given a new meaning; a new one is optional.
+ */
+
+// ── Addresses, codes, cadences ───────────────────────────────────────────────────────────────
+
+/** Where the agent dials, under the control plane's URL (`SPUNTO_AGENT_CONNECT_URL` overrides it). */
+export const AGENT_CONNECT_PATH = "/api/sandbox-agent/connect"
+/** Where `bootstrap.sh` fetches the agent, under the control plane's URL (`SPUNTO_AGENT_URL` overrides it). */
+export const AGENT_SCRIPT_PATH = "/api/sandboxes/agent.mjs"
+/** Where a box's main process fetches the bootstrap: `curl -fsSL $SPUNTO_API_URL<path> | sh`. */
+export const AGENT_BOOTSTRAP_PATH = "/api/sandboxes/bootstrap.sh"
+
+/** Close codes the control plane uses, and what the agent does on each. */
+export const AGENT_CLOSE = {
+  /** A newer connection of the same box took over. */
+  replaced: 4000,
+  /** The box was stopped by the platform. */
+  stopped: 4001,
+  /** The first message was not a parseable `hello`. */
+  badHello: 4400,
+  /** The token was refused (or no `hello` came in time): the agent says so and backs off. */
+  tokenRefused: 4401,
+  /** The box is stopped or stopping: the agent retries every few seconds, a start lets it in. */
+  notRunning: 4409,
+} as const
+
+/** The agent's heartbeat. */
+export const AGENT_HEARTBEAT_MS = 15_000
+/** A connection silent this long (no message, no pong) is dead: a box that vanished leaves no FIN. */
+export const AGENT_SILENCE_MS = 60_000
+/** The control plane's application-level `ping`. */
+export const AGENT_PING_MS = 20_000
+/** What a `hello` has to arrive within, once the socket is open. */
+export const AGENT_HELLO_TIMEOUT_MS = 10_000
+
+// ── The project plan ─────────────────────────────────────────────────────────────────────────
+
+/** What the agent is handed at every `hello` when its box belongs to a project. */
+export type ProjectPlan = {
+  type: "project"
+  projectId: string
+  version: number
+  /** Changes whenever the recipe would bake something different: re-bake on the next start. */
+  bakeKey: string
+  /** The image recipe (`buildImageScript`). */
+  bake: string
+  /** The worker script (`buildSetupScript` + `buildStartScript`). */
+  worker: string
+  /** Environment of every process the agent starts (lifecycle, exec, terminals) — secrets included. */
+  env: Record<string, string>
+  /** The user terminals and commands run as once the recipe has created it. */
+  user: string
+  /** The runner script (`./sandbox-agent` runner.sh): recipe once per bake key, then the worker script. */
+  runner: string
+  /** A builder: run the recipe, report `baked`, and nothing else — no user, no clone. */
+  bakeOnly?: boolean
+  /**
+   * The image's own `ENV`, under the box's: a provider that boots the image's files (a microVM)
+   * does not apply it — `PATH` merged, the image's entries first, the rest only if unset.
+   */
+  imageEnv?: Record<string, string>
+}
+
+export const PROJECT_PHASES = ["pending", "baking", "baked", "setting-up", "running", "exited", "failed"] as const
+/**
+ * Where the box is with its project. `running` means the worker script said `ready` for *this*
+ * start, postStart included; `baked` is a builder's end (`bakeOnly`).
+ */
+export type ProjectPhase = (typeof PROJECT_PHASES)[number]
+
+export type ProjectState = {
+  phase: ProjectPhase
+  version: number
+  bakeKey: string
+  /** The runner's exit code, null while it runs or when unknown. */
+  exitCode: number | null
+  /** The worker script's status file (`SetupStatus` of `./types`), as the box wrote it. */
+  worker: unknown
+  logTail: string
+  at: string
+}
+
+// ── Messages ─────────────────────────────────────────────────────────────────────────────────
+
+export type AgentInfo = {
+  agentVersion: string
+  hostname: string
+  platform: string
+  arch: string
+  node: string
+  cpus: number
+  memTotal: number
+  shell: string
+  pty: "python3" | "script" | "none"
+  workspace: string
+}
+
+export type ExecResult = {
+  exitCode: number | null
+  timedOut: boolean
+  error?: string
+  stdout: string
+  stderr: string
+  /** Either stream hit the agent's ceiling (1 MB each): only its head is there. */
+  truncated: boolean
+  durationMs: number
+}
+
+/** A terminal session of the box (a dtach socket), as `sessions` lists them. */
+export type AgentSession = { name: string; windows: number; attached: boolean; createdAt: number }
+/** A TCP port something listens on inside the box. */
+export type AgentPort = { port: number; process?: string }
+
+/** Control plane → agent. */
+export type PlatformMessage =
+  | { type: "welcome"; sandboxId: string }
+  | { type: "ping"; at: number }
+  | { type: "probe_ack"; id: number }
+  | ProjectPlan
+  | { type: "exec"; id: string; command: string; cwd?: string; env?: Record<string, string>; timeoutMs: number }
+  | { type: "exec_cancel"; id: string }
+  /** `session`: the dtach session to attach to, created if absent. `logs`: the runner's output, followed. */
+  | { type: "term_open"; termId: string; cols: number; rows: number; session?: string; mode?: "terminal" | "logs" }
+  /** `data`: base64. */
+  | { type: "term_input"; termId: string; data: string }
+  | { type: "term_resize"; termId: string; cols: number; rows: number }
+  | { type: "term_close"; termId: string }
+  /** Answered by a `reply` whose `result` is `AgentSession[]`. */
+  | { type: "sessions"; id: string; op?: "list" | "create" | "kill"; name?: string }
+  /** Answered by a `reply` whose `result` is `AgentPort[]`. */
+  | { type: "ports"; id: string }
+  | { type: "tunnel_open"; tunnelId: string; port: number }
+  | { type: "tunnel_close"; tunnelId: string }
+
+/** Agent → control plane. */
+export type AgentMessage =
+  | { type: "hello"; token: string; info: AgentInfo }
+  | { type: "heartbeat" }
+  | { type: "pong"; at: number }
+  /** After a resume (SIGUSR1): does this socket still reach the platform? */
+  | { type: "probe"; id: number }
+  | { type: "project_state"; state: ProjectState }
+  | ({ type: "exec_result"; id: string } & ExecResult)
+  | { type: "reply"; id: string; result: unknown }
+  /** `data`: base64. */
+  | { type: "term_data"; termId: string; data: string }
+  | { type: "term_exit"; termId: string; code: number | null }
+  | { type: "tunnel_ready"; tunnelId: string }
+  | { type: "tunnel_close"; tunnelId: string; error?: string }
+
+// ── Tunnel frames ────────────────────────────────────────────────────────────────────────────
+
+/** Tunnel bytes travel as binary frames, both ways: `[1][id length][id][payload]`. */
+export const TUNNEL_FRAME_DATA = 1
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+export function encodeTunnelFrame(tunnelId: string, payload: Uint8Array): Uint8Array {
+  const id = encoder.encode(tunnelId)
+  if (id.length > 255) throw new RangeError(`tunnel id too long (${id.length} bytes)`)
+  const frame = new Uint8Array(2 + id.length + payload.length)
+  frame[0] = TUNNEL_FRAME_DATA
+  frame[1] = id.length
+  frame.set(id, 2)
+  frame.set(payload, 2 + id.length)
+  return frame
+}
+
+/**
+ * The tunnel and payload of a frame, null for anything else. The payload is a view of the frame,
+ * of the frame's own type: a Node `Buffer` in, a `Buffer` out.
+ */
+export function decodeTunnelFrame<T extends Uint8Array>(frame: T): { tunnelId: string; payload: T } | null {
+  if (frame.length < 2 || frame[0] !== TUNNEL_FRAME_DATA) return null
+  const idLen = frame[1]!
+  if (frame.length < 2 + idLen) return null
+  return { tunnelId: decoder.decode(frame.subarray(2, 2 + idLen)), payload: frame.subarray(2 + idLen) as T }
+}