@runuai/host 0.1.0

package/src/main.ts

@@ -0,0 +1,1156 @@
+#!/usr/bin/env tsx
+
+import "./load-env";
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  request as httpRequest,
+  type ClientRequest,
+  type IncomingMessage,
+  type OutgoingHttpHeaders,
+} from "node:http";
+import { Socket } from "node:net";
+import { join } from "node:path";
+
+import WebSocket, { type RawData } from "ws";
+
+import { env } from "../lib/env";
+import { getDb, migrateHostDb } from "../lib/db";
+import {
+  markCloudError,
+  markConnected,
+  markDisconnected,
+  markReconnecting,
+} from "../lib/cloud-state";
+import { getHostTask } from "../lib/runtime-state";
+import { getOrchestrator } from "../lib/orchestrator";
+import {
+  onConnectClear,
+  onConnectSet,
+  setAuthExpiredHandler,
+} from "../lib/github-tokens";
+import {
+  deleteKey as deleteSshKey,
+  ensureKeyForUser as ensureSshKeyForUser,
+  getPublicKey as getSshPublicKey,
+} from "../lib/ssh";
+import {
+  packageVersion,
+  serviceLogPath,
+  uiAssetsDir,
+  uiPortFilePath,
+} from "./paths";
+import { dockerMemoryBytes, startUiServer } from "./ui/server";
+import { parsePreviewPortRuntimes } from "../lib/preview-ports";
+import { newId } from "../lib/ulid";
+import {
+  capabilities as agentKindCapabilities,
+  onChange as onRegistryChange,
+} from "../lib/agents/registry";
+// Importing the real factory triggers the built-in adapters' register()
+// calls (claude, codex), so the registry is populated before we advertise.
+import "../lib/agents/factory";
+import { ensureStandardImage, standardRuntimes } from "../lib/standard-image";
+import { hostCommands, hostEvents } from "./index";
+import {
+  HostErrorCode,
+  type CloudToHost,
+  type CommandContext,
+  type ChannelEnsureInput,
+  type HostCapabilities,
+  type HostCommandResult,
+  type HostCommands,
+  type HostToCloud,
+  type PermissionDecision,
+  type TaskAgent,
+  type TaskCommandProject,
+  type TaskCommandTask,
+  type TaskDiffInput,
+  type TaskDownInput,
+  type TaskLaunchInput,
+} from "./protocol";
+
+const PING_INTERVAL_MS = 15_000;
+const DEAD_AFTER_MS = 45_000;
+// Reconnect backoff, capped low (~15s) on purpose: cloud deploys drop the
+// bridge for ~30-40s, and an unbounded backoff (the old 60s tail) left the host
+// "disconnected" for up to a minute after the cloud was back, needing a manual
+// restart. Capping at 15s means the host self-heals within ~15s of recovery;
+// the extra retries during a longer outage are one cheap WS connect each.
+const BACKOFF_STEPS_MS = [1_000, 2_000, 4_000, 8_000, 15_000];
+const MAX_WS_BUFFERED_BYTES = 16 * 1024 * 1024;
+
+// Per-message deflate on the bridge WS. Tunnelled payloads are mostly text
+// (JS/HTML/JSON) and compress 3-4x, which matters because every preview/editor
+// stream is multiplexed over this one socket and bounded by the host's upload.
+// `threshold` skips the tiny tunnel.data envelopes (compressing them is pure
+// overhead); context takeover (ws default) keeps a shared dictionary for the
+// big JS chunks.
+const WS_DEFLATE = { threshold: 1024 } as const;
+
+const token = requireEnv("UAI_HOST_TOKEN");
+
+const bridgePort = parsePort(process.env.UAI_HOST_BRIDGE_PORT, 8789);
+const hostId = process.env.UAI_HOST_ID ?? ensureHostId();
+const bridgeUrl =
+  process.env.UAI_CLOUD_URL ?? `ws://127.0.0.1:${bridgePort}/host`;
+
+let ws: WebSocket | null = null;
+let stopping = false;
+let fatal = false;
+let reconnectAttempt = 0;
+let inFlight = 0;
+let shutdownRequested = false;
+let pendingBinaryTunnelId: string | null = null;
+const tunnels = new Map<string, TunnelUpstream>();
+
+interface TunnelUpstream {
+  write(chunk: Buffer): boolean;
+  end(): void;
+  destroy(): void;
+}
+
+interface PausableSource {
+  pause(): unknown;
+  resume(): unknown;
+  destroy(): void;
+}
+
+console.log(`[host-agent] starting host ${hostId}`);
+migrateHostDb();
+// When a task's GitHub token can't be refreshed (revoked, disconnected,
+// expired), surface it in the task channel so the user can re-grant (ADR-027).
+setAuthExpiredHandler((taskId, _userId, reason) => {
+  getOrchestrator().emitSystemNote(
+    taskId,
+    `gh authentication expired (reason: ${reason}). Reconnect GitHub on ` +
+      `Account, then run /retry-gh in this task to restore.`,
+  );
+});
+// Best-effort: build the standard image + asdf volume if missing. Logs and
+// continues on failure (e.g. docker unavailable) so the host still boots.
+void ensureStandardImage();
+connect();
+// Local browser UI (ADR-028) — same single process, alongside the WSS client.
+// Best-effort: a UI bind failure must not take the host service down.
+void startLocalUi();
+
+async function startLocalUi(): Promise<void> {
+  try {
+    const handle = await startUiServer({
+      db: getDb(),
+      uiDir: uiAssetsDir(),
+      portFilePath: uiPortFilePath(),
+      startPort: parsePort(process.env.UAI_HOST_UI_PORT, 5876),
+      version: packageVersion(),
+      cloudUrl: bridgeUrl,
+      hostId,
+      logPath: serviceLogPath(),
+      taskMemory: dockerMemoryBytes,
+    });
+    console.log(`[host-agent] local UI on http://127.0.0.1:${handle.port}`);
+  } catch (err) {
+    console.warn(
+      `[host-agent] local UI failed to start: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+/** Build the current host capability advertisement (ADR-021). */
+function buildCapabilities(): HostCapabilities {
+  return {
+    agentKinds: agentKindCapabilities(),
+    runtimes: standardRuntimes(),
+  };
+}
+
+/**
+ * Re-advertise capabilities on the active connection. Safe to call any time;
+ * a no-op when no socket is connected/open (the next `connect()` re-sends on
+ * auth). Wired to registry changes below — manual trigger for now.
+ */
+function sendCapabilities(): void {
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    send(ws, { kind: "host.capabilities", capabilities: buildCapabilities() });
+  }
+}
+
+onRegistryChange(() => sendCapabilities());
+
+function connect(): void {
+  if (stopping || fatal) return;
+
+  console.log(`[host-agent] connecting ${bridgeUrl}`);
+  const socket = new WebSocket(bridgeUrl, { perMessageDeflate: WS_DEFLATE });
+  ws = socket;
+
+  let lastTraffic = Date.now();
+  let ready = false;
+  let unsubscribe: (() => void) | null = null;
+  let pingTimer: NodeJS.Timeout | null = null;
+  let deadTimer: NodeJS.Timeout | null = null;
+
+  const cleanup = (): void => {
+    if (pingTimer) clearInterval(pingTimer);
+    if (deadTimer) clearInterval(deadTimer);
+    if (unsubscribe) unsubscribe();
+    if (ws === socket) ws = null;
+  };
+
+  socket.on("open", () => {
+    send(socket, { kind: "auth", token, hostId });
+    // Advertise capabilities immediately after auth (ADR-021). The bridge
+    // rejects with close-code 4001 if auth fails, so sending here is harmless
+    // on a bad token and saves a round-trip on a good one. Re-sent on every
+    // reconnect (this handler) and on registry change (onRegistryChange).
+    send(socket, {
+      kind: "host.capabilities",
+      capabilities: buildCapabilities(),
+    });
+    ready = true;
+    reconnectAttempt = 0;
+    markConnected();
+    console.log(`[host-agent] connected as ${hostId}`);
+
+    unsubscribe = hostEvents.subscribe((event) => {
+      if (socket.readyState !== WebSocket.OPEN) return;
+      send(socket, { kind: "event", event });
+    });
+
+    pingTimer = setInterval(() => {
+      if (socket.readyState === WebSocket.OPEN) {
+        send(socket, { kind: "ping", ts: Date.now() });
+      }
+    }, PING_INTERVAL_MS);
+
+    deadTimer = setInterval(() => {
+      if (Date.now() - lastTraffic > DEAD_AFTER_MS) {
+        console.warn("[host-agent] bridge heartbeat timed out");
+        socket.close(4000, "heartbeat timeout");
+      }
+    }, 5_000);
+  });
+
+  socket.on("message", (data, isBinary) => {
+    lastTraffic = Date.now();
+    if (isBinary) {
+      const tunnelId = pendingBinaryTunnelId;
+      pendingBinaryTunnelId = null;
+      if (!tunnelId) return;
+      tunnels.get(tunnelId)?.write(rawDataToBuffer(data));
+      return;
+    }
+
+    const frame = parseCloudFrame(data);
+    if (!frame) return;
+
+    switch (frame.kind) {
+      case "pong":
+        break;
+      case "command":
+        void handleCommand(socket, frame);
+        break;
+      case "tunnel.open":
+        handleTunnelOpen(socket, frame);
+        break;
+      case "tunnel.data":
+        pendingBinaryTunnelId = frame.tunnelId;
+        break;
+      case "tunnel.requestEnd":
+        // Request body complete → finish the upstream request so it can reply.
+        tunnels.get(frame.tunnelId)?.end();
+        break;
+      case "tunnel.close":
+        closeTunnel(socket, frame.tunnelId, frame.reason);
+        break;
+      case "gh.connect.set": {
+        const result = onConnectSet(frame);
+        send(
+          socket,
+          result.ok
+            ? { kind: "gh.connect.ack", userId: frame.userId, ok: true }
+            : {
+                kind: "gh.connect.ack",
+                userId: frame.userId,
+                ok: false,
+                error: result.error ?? "store failed",
+              },
+        );
+        break;
+      }
+      case "gh.connect.clear":
+        onConnectClear(frame.userId);
+        send(socket, { kind: "gh.connect.ack", userId: frame.userId, ok: true });
+        break;
+      case "ssh.key.get":
+      case "ssh.key.ensure":
+      case "ssh.key.delete": {
+        try {
+          let publicKey: string | null;
+          if (frame.kind === "ssh.key.delete") {
+            deleteSshKey(frame.userId);
+            publicKey = null;
+          } else if (frame.kind === "ssh.key.ensure") {
+            publicKey = ensureSshKeyForUser(frame.userId);
+          } else {
+            publicKey = getSshPublicKey(frame.userId);
+          }
+          send(socket, { kind: "ssh.key.ack", userId: frame.userId, ok: true, publicKey });
+        } catch (err) {
+          send(socket, {
+            kind: "ssh.key.ack",
+            userId: frame.userId,
+            ok: false,
+            error: err instanceof Error ? err.message : "ssh key op failed",
+          });
+        }
+        break;
+      }
+    }
+  });
+
+  socket.on("error", (err) => {
+    markCloudError(err.message);
+    if (!stopping) {
+      console.warn(`[host-agent] bridge error: ${err.message}`);
+    }
+  });
+
+  socket.on("close", (code, reason) => {
+    cleanup();
+    const text = reason.toString("utf8");
+    if (code === 4001) {
+      fatal = true;
+      markDisconnected(text || "auth rejected by bridge");
+      console.error(
+        `[host-agent] auth rejected by bridge${text ? `: ${text}` : ""}`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    if (stopping) {
+      markDisconnected();
+      maybeExit();
+      return;
+    }
+    const delay = reconnectDelay();
+    markReconnecting(text || `disconnected${ready ? "" : " before auth"}`);
+    console.warn(
+      `[host-agent] disconnected${ready ? "" : " before auth"}; reconnecting in ${Math.round(delay)}ms`,
+    );
+    setTimeout(connect, delay);
+  });
+}
+
+async function handleCommand(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "command" }>,
+): Promise<void> {
+  inFlight += 1;
+  const ctx: CommandContext = { commandId: frame.commandId };
+  try {
+    const result = await dispatchCommand(ctx, frame.command, frame.args);
+    if (socket.readyState === WebSocket.OPEN) {
+      send(socket, { kind: "result", commandId: frame.commandId, result });
+    }
+  } catch (err) {
+    if (socket.readyState === WebSocket.OPEN) {
+      send(socket, {
+        kind: "result",
+        commandId: frame.commandId,
+        result: {
+          ok: false,
+          code: HostErrorCode.Internal,
+          message: err instanceof Error ? err.message : String(err),
+        },
+      });
+    }
+  } finally {
+    inFlight -= 1;
+    maybeExit();
+  }
+}
+
+function handleTunnelOpen(
+  wsSocket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
+): void {
+  const port = resolveTunnelPort(frame);
+  if (!port) {
+    send(wsSocket, {
+      kind: "tunnel.ack",
+      tunnelId: frame.tunnelId,
+      ok: false,
+      status: 503,
+      message: "target port is not available on this host",
+    });
+    return;
+  }
+
+  if (!frame.upgrade) {
+    handleHttpTunnelOpen(wsSocket, frame, port);
+    return;
+  }
+
+  handleRawTunnelOpen(wsSocket, frame, port);
+}
+
+function handleHttpTunnelOpen(
+  wsSocket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
+  port: number,
+): void {
+  let acked = false;
+  const upstream = httpRequest(
+    {
+      host: "127.0.0.1",
+      port,
+      method: frame.reqLine.method,
+      path: frame.reqLine.url,
+      headers: requestHeaders(frame.reqLine.headers),
+    },
+    (response) => {
+      const headers = responseHeaders(response);
+      send(wsSocket, {
+        kind: "tunnel.ack",
+        tunnelId: frame.tunnelId,
+        ok: true,
+        status: response.statusCode ?? 502,
+        statusText: response.statusMessage || "OK",
+        headers,
+      });
+      acked = true;
+
+      response.on("data", (chunk: Buffer) => {
+        sendTunnelData(wsSocket, frame.tunnelId, chunk, response);
+      });
+      response.on("end", () => {
+        tunnels.delete(frame.tunnelId);
+        send(wsSocket, {
+          kind: "tunnel.close",
+          tunnelId: frame.tunnelId,
+          reason: "upstream ended",
+        });
+      });
+    },
+  );
+
+  tunnels.set(frame.tunnelId, upstream);
+
+  upstream.on("error", (err) => {
+    tunnels.delete(frame.tunnelId);
+    if (!acked) {
+      send(wsSocket, {
+        kind: "tunnel.ack",
+        tunnelId: frame.tunnelId,
+        ok: false,
+        status: 502,
+        message: err.message,
+      });
+      return;
+    }
+    send(wsSocket, {
+      kind: "tunnel.close",
+      tunnelId: frame.tunnelId,
+      reason: err.message,
+    });
+  });
+
+  // NB: do NOT end the request here. The body (if any) arrives as tunnel.data
+  // frames; the cloud sends tunnel.requestEnd once the body is complete, which
+  // ends `upstream` (see the message loop). Ending now would drop request
+  // bodies and deadlock body-reading upstreams.
+}
+
+function handleRawTunnelOpen(
+  wsSocket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
+  port: number,
+): void {
+  const upstream = new Socket();
+  tunnels.set(frame.tunnelId, upstream);
+
+  let acked = false;
+  let responseBuffer = Buffer.alloc(0);
+
+  upstream.on("connect", () => {
+    upstream.write(serializeRequest(frame.reqLine));
+  });
+
+  upstream.on("data", (chunk) => {
+    if (!acked) {
+      responseBuffer = Buffer.concat([responseBuffer, chunk]);
+      const headerEnd = responseBuffer.indexOf("\r\n\r\n");
+      if (headerEnd === -1) return;
+      const head = responseBuffer.subarray(0, headerEnd).toString("latin1");
+      const rest = responseBuffer.subarray(headerEnd + 4);
+      const ack = parseResponseHead(head);
+      send(wsSocket, {
+        kind: "tunnel.ack",
+        tunnelId: frame.tunnelId,
+        ok: true,
+        status: ack.status,
+        statusText: ack.statusText,
+        headers: ack.headers,
+      });
+      acked = true;
+      if (rest.length > 0) sendTunnelData(wsSocket, frame.tunnelId, rest, upstream);
+      return;
+    }
+    sendTunnelData(wsSocket, frame.tunnelId, chunk, upstream);
+  });
+
+  upstream.on("error", (err) => {
+    if (!acked) {
+      send(wsSocket, {
+        kind: "tunnel.ack",
+        tunnelId: frame.tunnelId,
+        ok: false,
+        status: 502,
+        message: err.message,
+      });
+    } else {
+      send(wsSocket, {
+        kind: "tunnel.close",
+        tunnelId: frame.tunnelId,
+        reason: err.message,
+      });
+    }
+    tunnels.delete(frame.tunnelId);
+  });
+
+  upstream.on("close", () => {
+    tunnels.delete(frame.tunnelId);
+    send(wsSocket, {
+      kind: "tunnel.close",
+      tunnelId: frame.tunnelId,
+      reason: "upstream closed",
+    });
+  });
+
+  upstream.connect(port, "127.0.0.1");
+}
+
+function closeTunnel(
+  wsSocket: WebSocket,
+  tunnelId: string,
+  reason: string | undefined,
+): void {
+  const upstream = tunnels.get(tunnelId);
+  tunnels.delete(tunnelId);
+  upstream?.destroy();
+  send(wsSocket, { kind: "tunnel.close", tunnelId, reason });
+}
+
+function resolveTunnelPort(
+  frame: Extract<CloudToHost, { kind: "tunnel.open" }>,
+): number | null {
+  const task = getHostTask(frame.taskId);
+  if (!task) return null;
+  if (frame.target === "editor") return task.codeServerPort ?? null;
+  if (!frame.name) return null;
+  const preview = parsePreviewPortRuntimes(task.previewPorts).find(
+    (port) => port.name === frame.name,
+  );
+  return preview?.hostPort ?? null;
+}
+
+function serializeRequest(reqLine: {
+  method: string;
+  url: string;
+  headers: [string, string][];
+}): Buffer {
+  const lines = [`${reqLine.method} ${reqLine.url} HTTP/1.1`];
+  for (const [name, value] of reqLine.headers) {
+    if (name.toLowerCase() === "connection") {
+      lines.push(`${name}: ${value}`);
+    } else {
+      lines.push(`${name}: ${value}`);
+    }
+  }
+  return Buffer.from(`${lines.join("\r\n")}\r\n\r\n`, "latin1");
+}
+
+function requestHeaders(headers: [string, string][]): OutgoingHttpHeaders {
+  const out: OutgoingHttpHeaders = {};
+  for (const [name, value] of headers) {
+    const lower = name.toLowerCase();
+    if (isHopByHopHeader(lower)) continue;
+    if (lower === "host") {
+      out.host = "127.0.0.1";
+      continue;
+    }
+
+    const existing = out[lower];
+    if (existing === undefined) {
+      out[lower] = value;
+    } else if (Array.isArray(existing)) {
+      existing.push(value);
+    } else {
+      out[lower] = [String(existing), value];
+    }
+  }
+  return out;
+}
+
+function responseHeaders(response: IncomingMessage): [string, string][] {
+  const headers: [string, string][] = [];
+  for (let i = 0; i < response.rawHeaders.length; i += 2) {
+    const name = response.rawHeaders[i];
+    const value = response.rawHeaders[i + 1];
+    if (!name || value === undefined) continue;
+    if (isHopByHopHeader(name.toLowerCase())) continue;
+    headers.push([name, value]);
+  }
+  return headers;
+}
+
+function isHopByHopHeader(name: string): boolean {
+  return (
+    name === "connection" ||
+    name === "keep-alive" ||
+    name === "proxy-authenticate" ||
+    name === "proxy-authorization" ||
+    name === "te" ||
+    name === "trailer" ||
+    name === "transfer-encoding" ||
+    name === "upgrade"
+  );
+}
+
+function parseResponseHead(head: string): {
+  status: number;
+  statusText: string;
+  headers: [string, string][];
+} {
+  const lines = head.split("\r\n");
+  const statusLine = lines.shift() ?? "HTTP/1.1 502 Bad Gateway";
+  const match = /^HTTP\/\d(?:\.\d)?\s+(\d{3})\s*(.*)$/.exec(statusLine);
+  const headers: [string, string][] = [];
+  for (const line of lines) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    headers.push([line.slice(0, idx), line.slice(idx + 1).trimStart()]);
+  }
+  return {
+    status: match ? Number(match[1]) : 502,
+    statusText: match?.[2] || "Bad Gateway",
+    headers,
+  };
+}
+
+function sendTunnelData(
+  wsSocket: WebSocket,
+  tunnelId: string,
+  chunk: Buffer,
+  upstream: PausableSource,
+): void {
+  if (wsSocket.readyState !== WebSocket.OPEN) {
+    upstream.destroy();
+    return;
+  }
+  send(wsSocket, { kind: "tunnel.data", tunnelId });
+  wsSocket.send(chunk);
+  // Backpressure: always send the current chunk (make progress), then if the
+  // socket buffer is high, pause this upstream and resume only once it drains
+  // below the low-water mark — a tight poll instead of a blind fixed sleep, so
+  // throughput tracks the real drain rate. Once paused, no more data events
+  // fire for this upstream, so the loop can't stack.
+  if (wsSocket.bufferedAmount > MAX_WS_BUFFERED_BYTES) {
+    upstream.pause();
+    const resume = (): void => {
+      if (wsSocket.readyState !== WebSocket.OPEN) {
+        upstream.destroy();
+        return;
+      }
+      if (wsSocket.bufferedAmount <= MAX_WS_BUFFERED_BYTES / 2) {
+        upstream.resume();
+      } else {
+        setTimeout(resume, 5);
+      }
+    };
+    setTimeout(resume, 5);
+  }
+}
+
+function dispatchCommand(
+  ctx: CommandContext,
+  command: keyof HostCommands,
+  args: unknown[],
+): Promise<HostCommandResult<unknown>> {
+  switch (command) {
+    case "taskUp":
+      return hostCommands.taskUp(ctx, expectTaskLaunchInput(args, 0));
+    case "taskDown":
+      return hostCommands.taskDown(ctx, expectTaskDownInput(args, 0));
+    case "taskStatus":
+      return hostCommands.taskStatus(ctx, expectString(args, 0));
+    case "channelEnsure":
+      return hostCommands.channelEnsure(ctx, expectChannelEnsureInput(args, 0));
+    case "channelTeardown":
+      return hostCommands.channelTeardown(ctx, expectString(args, 0));
+    case "channelDeliver":
+      return hostCommands.channelDeliver(
+        ctx,
+        expectString(args, 0),
+        expectString(args, 1),
+        expectString(args, 2),
+      );
+    case "channelResolvePermission":
+      return hostCommands.channelResolvePermission(
+        ctx,
+        expectString(args, 0),
+        expectString(args, 1),
+        expectString(args, 2),
+        expectPermissionDecision(args, 3),
+      );
+    case "cloneRepo":
+      return hostCommands.cloneRepo(ctx, expectCloneRepoInput(args, 0));
+    case "taskDiff":
+      return hostCommands.taskDiff(ctx, expectTaskDiffInput(args, 0));
+    case "attachmentWrite":
+      return hostCommands.attachmentWrite(
+        ctx,
+        expectAttachmentWriteInput(args, 0),
+      );
+    case "attachmentRead":
+      return hostCommands.attachmentRead(
+        ctx,
+        expectAttachmentReadInput(args, 0),
+      );
+    case "channelInterrupt":
+      return hostCommands.channelInterrupt(
+        ctx,
+        expectString(args, 0),
+        expectString(args, 1),
+      );
+    case "appendTranscript":
+      return hostCommands.appendTranscript(
+        ctx,
+        expectString(args, 0),
+        expectString(args, 1),
+        expectString(args, 2),
+      );
+  }
+}
+
+function parseCloudFrame(data: RawData): CloudToHost | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data.toString());
+  } catch {
+    console.warn("[host-agent] dropping invalid JSON frame");
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const frame = parsed as Record<string, unknown>;
+  if (frame.kind === "pong" && typeof frame.ts === "number") {
+    return { kind: "pong", ts: frame.ts };
+  }
+  if (
+    frame.kind === "command" &&
+    typeof frame.commandId === "string" &&
+    typeof frame.command === "string" &&
+    Array.isArray(frame.args) &&
+    isHostCommand(frame.command)
+  ) {
+    return {
+      kind: "command",
+      commandId: frame.commandId,
+      command: frame.command,
+      args: frame.args,
+    };
+  }
+  if (
+    frame.kind === "tunnel.open" &&
+    typeof frame.tunnelId === "string" &&
+    (frame.target === "editor" || frame.target === "preview") &&
+    typeof frame.taskId === "string" &&
+    isReqLine(frame.reqLine) &&
+    typeof frame.upgrade === "boolean"
+  ) {
+    return {
+      kind: "tunnel.open",
+      tunnelId: frame.tunnelId,
+      target: frame.target,
+      taskId: frame.taskId,
+      name: typeof frame.name === "string" ? frame.name : undefined,
+      reqLine: frame.reqLine,
+      upgrade: frame.upgrade,
+    };
+  }
+  if (frame.kind === "tunnel.data" && typeof frame.tunnelId === "string") {
+    return { kind: "tunnel.data", tunnelId: frame.tunnelId };
+  }
+  if (frame.kind === "tunnel.requestEnd" && typeof frame.tunnelId === "string") {
+    return { kind: "tunnel.requestEnd", tunnelId: frame.tunnelId };
+  }
+  if (frame.kind === "tunnel.close" && typeof frame.tunnelId === "string") {
+    return {
+      kind: "tunnel.close",
+      tunnelId: frame.tunnelId,
+      reason: typeof frame.reason === "string" ? frame.reason : undefined,
+    };
+  }
+  if (
+    frame.kind === "gh.connect.set" &&
+    typeof frame.userId === "string" &&
+    typeof frame.installationId === "number" &&
+    typeof frame.githubLogin === "string" &&
+    (frame.targetType === "User" || frame.targetType === "Organization") &&
+    typeof frame.refreshToken === "string"
+  ) {
+    return {
+      kind: "gh.connect.set",
+      userId: frame.userId,
+      installationId: frame.installationId,
+      githubLogin: frame.githubLogin,
+      targetType: frame.targetType,
+      refreshToken: frame.refreshToken,
+      refreshTokenExpiresAt:
+        typeof frame.refreshTokenExpiresAt === "number"
+          ? frame.refreshTokenExpiresAt
+          : undefined,
+    };
+  }
+  if (frame.kind === "gh.connect.clear" && typeof frame.userId === "string") {
+    return { kind: "gh.connect.clear", userId: frame.userId };
+  }
+  if (
+    (frame.kind === "ssh.key.get" ||
+      frame.kind === "ssh.key.ensure" ||
+      frame.kind === "ssh.key.delete") &&
+    typeof frame.userId === "string"
+  ) {
+    return { kind: frame.kind, userId: frame.userId };
+  }
+  console.warn("[host-agent] dropping unknown frame");
+  return null;
+}
+
+function isReqLine(value: unknown): value is {
+  method: string;
+  url: string;
+  headers: [string, string][];
+} {
+  if (!value || typeof value !== "object") return false;
+  const row = value as Record<string, unknown>;
+  return (
+    typeof row.method === "string" &&
+    typeof row.url === "string" &&
+    Array.isArray(row.headers) &&
+    row.headers.every(
+      (item) =>
+        Array.isArray(item) &&
+        item.length === 2 &&
+        typeof item[0] === "string" &&
+        typeof item[1] === "string",
+    )
+  );
+}
+
+function send(socket: WebSocket, frame: HostToCloud): void {
+  socket.send(JSON.stringify(frame));
+}
+
+function rawDataToBuffer(data: RawData): Buffer {
+  if (Buffer.isBuffer(data)) return data;
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  if (Array.isArray(data)) return Buffer.concat(data);
+  return Buffer.from(data);
+}
+
+function isHostCommand(command: string): command is keyof HostCommands {
+  // ⚠️ Keep in sync with the HostCommands interface + dispatchCommand. This is a
+  // manual allow-list (TS can't derive it from the type), so a missing entry
+  // silently drops the frame and hangs the cloud command.
+  return [
+    "taskUp",
+    "taskDown",
+    "taskStatus",
+    "channelEnsure",
+    "channelTeardown",
+    "channelDeliver",
+    "channelResolvePermission",
+    "cloneRepo",
+    "taskDiff",
+    "attachmentWrite",
+    "attachmentRead",
+    "channelInterrupt",
+    "appendTranscript",
+  ].includes(command);
+}
+
+function expectString(args: unknown[], index: number): string {
+  const value = args[index];
+  if (typeof value !== "string") {
+    throw new Error(`invalid command args: expected string at ${index}`);
+  }
+  return value;
+}
+
+function expectTaskAgents(value: unknown): TaskAgent[] {
+  if (!Array.isArray(value)) {
+    throw new Error("invalid command args: expected agents array");
+  }
+  return value.map((agent) => {
+    const row = expectRecord(agent, "task agent");
+    const out: TaskAgent = {
+      id: expectStringValue(row.id, "agent.id"),
+      label: expectStringValue(row.label, "agent.label"),
+      kind: expectStringValue(row.kind, "agent.kind"),
+    };
+    if (typeof row.model === "string") out.model = row.model;
+    if (typeof row.defaultPrompt === "string") {
+      out.defaultPrompt = row.defaultPrompt;
+    }
+    if (typeof row.initialPrompt === "string") {
+      out.initialPrompt = row.initialPrompt;
+    }
+    return out;
+  });
+}
+
+function expectPermissionDecision(
+  args: unknown[],
+  index: number,
+): PermissionDecision {
+  const value = args[index];
+  if (!value || typeof value !== "object") {
+    throw new Error(`invalid command args: expected decision at ${index}`);
+  }
+  const decision = value as Record<string, unknown>;
+  if (decision.kind === "accept" || decision.kind === "decline") {
+    return { kind: decision.kind };
+  }
+  throw new Error("invalid permission decision");
+}
+
+function expectCloneRepoInput(
+  args: unknown[],
+  index: number,
+): { url: string; projectId: string } {
+  const value = args[index];
+  if (!value || typeof value !== "object") {
+    throw new Error(`invalid command args: expected clone input at ${index}`);
+  }
+  const input = value as Record<string, unknown>;
+  if (typeof input.url !== "string" || typeof input.projectId !== "string") {
+    throw new Error("invalid clone input");
+  }
+  return {
+    url: input.url,
+    projectId: input.projectId,
+  };
+}
+
+function expectTaskLaunchInput(
+  args: unknown[],
+  index: number,
+): TaskLaunchInput {
+  const input = expectRecord(args[index], "task launch input");
+  const out: TaskLaunchInput = {
+    task: expectTaskCommandTask(input.task),
+    projects: expectTaskCommandProjects(input.projects),
+  };
+  if (typeof input.ownerEmail === "string") out.ownerEmail = input.ownerEmail;
+  if (typeof input.ownerName === "string") out.ownerName = input.ownerName;
+  return out;
+}
+
+function expectTaskDownInput(args: unknown[], index: number): TaskDownInput {
+  const input = expectRecord(args[index], "task down input");
+  return {
+    taskId: expectStringValue(input.taskId, "taskId"),
+    task: expectTaskCommandTask(input.task),
+    projects: expectTaskCommandProjects(input.projects),
+  };
+}
+
+function expectTaskDiffInput(args: unknown[], index: number): TaskDiffInput {
+  const input = expectRecord(args[index], "task diff input");
+  const projectsValue = input.projects;
+  if (!Array.isArray(projectsValue)) throw new Error("invalid diff projects");
+  return {
+    taskId: expectStringValue(input.taskId, "taskId"),
+    projects: projectsValue.map((project) => {
+      const row = expectRecord(project, "diff project");
+      return {
+        id: expectStringValue(row.id, "project.id"),
+        slug: expectStringValue(row.slug, "project.slug"),
+      };
+    }),
+  };
+}
+
+function expectAttachmentWriteInput(
+  args: unknown[],
+  index: number,
+): { taskId: string; filename: string; dataBase64: string } {
+  const input = expectRecord(args[index], "attachment write input");
+  return {
+    taskId: expectStringValue(input.taskId, "taskId"),
+    filename: expectStringValue(input.filename, "filename"),
+    dataBase64: expectStringValue(input.dataBase64, "dataBase64"),
+  };
+}
+
+function expectAttachmentReadInput(
+  args: unknown[],
+  index: number,
+): { taskId: string; filename: string } {
+  const input = expectRecord(args[index], "attachment read input");
+  return {
+    taskId: expectStringValue(input.taskId, "taskId"),
+    filename: expectStringValue(input.filename, "filename"),
+  };
+}
+
+function expectChannelEnsureInput(
+  args: unknown[],
+  index: number,
+): ChannelEnsureInput {
+  const input = expectRecord(args[index], "channel ensure input");
+  const projectsValue = input.projects;
+  if (!Array.isArray(projectsValue)) throw new Error("invalid channel projects");
+  const out: ChannelEnsureInput = {
+    taskId: expectStringValue(input.taskId, "taskId"),
+    agents: expectTaskAgents(input.agents),
+    projects: projectsValue.map((project) => {
+      const row = expectRecord(project, "channel project");
+      return {
+        slug: expectStringValue(row.slug, "slug"),
+        defaultPrompt: expectStringValue(row.defaultPrompt, "defaultPrompt"),
+      };
+    }),
+    branch: expectStringValue(input.branch, "branch"),
+    workspacePath: expectStringValue(input.workspacePath, "workspacePath"),
+    status: expectStringValue(input.status, "status"),
+  };
+  if (typeof input.globalContext === "string") {
+    out.globalContext = input.globalContext;
+  }
+  return out;
+}
+
+function expectTaskCommandTask(value: unknown): TaskCommandTask {
+  const row = expectRecord(value, "task");
+  const out: TaskCommandTask = {
+    id: expectStringValue(row.id, "task.id"),
+    ownerUserId: expectStringValue(row.ownerUserId, "task.ownerUserId"),
+    hostId: expectStringValue(row.hostId, "task.hostId"),
+    name: expectStringValue(row.name, "task.name"),
+    slug: expectStringValue(row.slug, "task.slug"),
+    branch: expectStringValue(row.branch, "task.branch"),
+    status: expectStringValue(row.status, "task.status"),
+    agents: expectTaskAgents(row.agents),
+  };
+  if (typeof row.globalContext === "string") {
+    out.globalContext = row.globalContext;
+  }
+  if (Array.isArray(row.reviewerOrder)) {
+    out.reviewerOrder = row.reviewerOrder.map((id, i) =>
+      expectStringValue(id, `task.reviewerOrder[${i}]`),
+    );
+  }
+  return out;
+}
+
+function expectTaskCommandProjects(value: unknown): TaskCommandProject[] {
+  if (!Array.isArray(value)) throw new Error("invalid projects");
+  return value.map(expectTaskCommandProject);
+}
+
+function expectTaskCommandProject(value: unknown): TaskCommandProject {
+  const row = expectRecord(value, "project");
+  const out: TaskCommandProject = {
+    id: expectStringValue(row.id, "project.id"),
+    ownerUserId: expectStringValue(row.ownerUserId, "project.ownerUserId"),
+    name: expectStringValue(row.name, "project.name"),
+    slug: expectStringValue(row.slug, "project.slug"),
+    repoUrl: expectStringValue(row.repoUrl, "project.repoUrl"),
+    defaultPrompt: expectStringValue(row.defaultPrompt, "project.defaultPrompt"),
+    previewPorts: expectStringValue(row.previewPorts, "project.previewPorts"),
+    env: expectStringValue(row.env, "project.env"),
+    position:
+      typeof row.position === "number" && Number.isInteger(row.position)
+        ? row.position
+        : 0,
+  };
+  if (typeof row.toolVersions === "string") {
+    out.toolVersions = row.toolVersions;
+  }
+  if (typeof row.extra === "string") out.extra = row.extra;
+  return out;
+}
+
+function expectRecord(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`invalid command args: expected ${label}`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function expectStringValue(value: unknown, label: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`invalid command args: expected string ${label}`);
+  }
+  return value;
+}
+
+function ensureHostId(): string {
+  mkdirSync(env.dataDir, { recursive: true, mode: 0o700 });
+  const path = join(env.dataDir, "host-id");
+  if (existsSync(path)) {
+    const existing = readFileSync(path, "utf8").trim();
+    if (existing) return existing;
+  }
+  const id = newId();
+  writeFileSync(path, `${id}\n`, { mode: 0o600 });
+  return id;
+}
+
+function parsePort(raw: string | undefined, fallback: number): number {
+  if (!raw) return fallback;
+  const port = Number(raw);
+  return Number.isInteger(port) && port > 0 && port <= 65535
+    ? port
+    : fallback;
+}
+
+function reconnectDelay(): number {
+  const base =
+    BACKOFF_STEPS_MS[
+      Math.min(reconnectAttempt, BACKOFF_STEPS_MS.length - 1)
+    ] ?? 30_000;
+  reconnectAttempt += 1;
+  const jitter = 0.8 + Math.random() * 0.4;
+  return base * jitter;
+}
+
+function requestShutdown(signal: NodeJS.Signals): void {
+  console.log(`[host-agent] ${signal} received; shutting down`);
+  stopping = true;
+  shutdownRequested = true;
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    ws.close(1001, "host shutting down");
+  }
+  maybeExit();
+}
+
+function maybeExit(): void {
+  if (!shutdownRequested || inFlight > 0) return;
+  process.exit(0);
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    console.error(`[host-agent] ${name} is required`);
+    process.exit(1);
+  }
+  return value;
+}
+
+process.on("SIGINT", requestShutdown);
+process.on("SIGTERM", requestShutdown);