agent-relay-orchestrator 0.10.19 → 0.10.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.10.19",
+  "version": "0.10.21",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -15,7 +15,9 @@
     "start": "bun run src/index.ts",
     "test": "bun test"
   },
-  "dependencies": {},
+  "dependencies": {
+    "agent-relay-sdk": "0.2.2"
+  },
   "devDependencies": {
     "@types/bun": "latest"
   },

package/src/api.ts

@@ -1,8 +1,14 @@
-import { readdirSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import type { ServerWebSocket } from "bun";
+import { proxyArtifactRequest } from "./artifact-proxy";
 import type { OrchestratorConfig } from "./config";
-import { captureSession, listTmuxSessions } from "./tmux";
-import { VERSION } from "./version";
+import type { ProviderProbeCache } from "./provider-probe";
+import { captureSession, captureTerminal, createTerminalGuest, listSessions, sendTerminalInput, resizeTerminal, stopTerminalGuest } from "./spawn";
+import type { TerminalSnapshot } from "./spawn";
+import { VERSION, runtimeMetadata } from "./version";
+import { previewWorkspaceMerge, probeWorkspace, workspaceDiff, workspaceGitState } from "./workspace-probe";
 
 interface DirectoryEntry {
   name: string;
@@ -16,6 +22,76 @@ interface DirectoryListing {
   entries: DirectoryEntry[];
 }
 
+export interface FileEntry {
+  name: string;
+  path: string;
+  type: "file" | "directory" | "symlink";
+  size?: number;
+  modifiedAt?: number;
+}
+
+export interface FileListing {
+  path: string;
+  parent?: string;
+  baseDir: string;
+  entries: FileEntry[];
+}
+
+export interface FileReadResult {
+  path: string;
+  name: string;
+  mediaType: string;
+  encoding: "utf8" | "binary";
+  size: number;
+  modifiedAt?: number;
+  truncated: boolean;
+  content?: string;
+}
+
+export interface FileStatResult {
+  path: string;
+  name: string;
+  type: "file" | "directory";
+  baseDir: string;
+  size?: number;
+  modifiedAt?: number;
+}
+
+const MAX_FILE_PREVIEW_BYTES = 1024 * 1024;
+const DEFAULT_TERMINAL_STREAM_HEARTBEAT_MS = 5_000;
+
+interface TerminalSocketData {
+  kind: "terminal";
+  config: OrchestratorConfig;
+  session: string;
+  timer?: ReturnType<typeof setInterval>;
+  lastSnapshotSignature?: string;
+  lastHeartbeatAt?: number;
+  paused?: boolean;
+}
+
+type TerminalSocket = ServerWebSocket<TerminalSocketData>;
+
+export function terminalSnapshotSignature(snapshot: TerminalSnapshot): string {
+  const hash = createHash("sha1");
+  hash.update(snapshot.session);
+  hash.update("\0");
+  hash.update(snapshot.running ? "1" : "0");
+  hash.update("\0");
+  hash.update(snapshot.agentAlive ? "1" : "0");
+  hash.update("\0");
+  hash.update(String(snapshot.cols ?? ""));
+  hash.update("\0");
+  hash.update(String(snapshot.rows ?? ""));
+  hash.update("\0");
+  hash.update(String(snapshot.cursorX ?? ""));
+  hash.update("\0");
+  hash.update(String(snapshot.cursorY ?? ""));
+  hash.update("\0");
+  hash.update(snapshot.content);
+  return hash.digest("hex");
+}
+
 function listDirectories(requestedPath: string | undefined, baseDir: string): DirectoryListing {
   const base = resolve(baseDir);
   const target = resolve(requestedPath || base);
@@ -44,6 +120,162 @@ function listDirectories(requestedPath: string | undefined, baseDir: string): Di
   };
 }
 
+function createDirectory(parentPath: string, name: string, baseDir: string): DirectoryListing {
+  const base = resolve(baseDir);
+  const parent = resolve(parentPath);
+  const parentRel = relative(base, parent);
+  if (parentRel && (parentRel.startsWith("..") || parentRel.startsWith("/"))) {
+    throw new Error(`Path must be within baseDir: ${baseDir}`);
+  }
+  if (!name || name.includes("/") || name.includes("\\") || name.startsWith(".")) {
+    throw new Error(`Invalid directory name: ${name}`);
+  }
+  const target = join(parent, name);
+  mkdirSync(target, { recursive: true });
+  return listDirectories(target, baseDir);
+}
+
+function resolveInsideBase(requestedPath: string | undefined, baseDir: string): { base: string; target: string } {
+  const base = realpathSync(resolve(baseDir));
+  const candidate = resolve(requestedPath || base);
+  let target: string;
+  try {
+    target = realpathSync(candidate);
+  } catch {
+    throw new Error(`Path does not exist: ${candidate}`);
+  }
+  const rel = relative(base, target);
+  if (rel && (rel.startsWith("..") || rel.startsWith("/"))) {
+    throw new Error(`Path must be within baseDir: ${baseDir}`);
+  }
+  return { base, target };
+}
+
+function parentInsideBase(target: string, base: string): string | undefined {
+  const parent = dirname(target);
+  const parentRel = relative(base, parent);
+  return parentRel && !parentRel.startsWith("..") && !parentRel.startsWith("/") && parent !== target ? parent : undefined;
+}
+
+export function listFiles(requestedPath: string | undefined, baseDir: string): FileListing {
+  const { base, target } = resolveInsideBase(requestedPath, baseDir);
+  const stat = statSync(target);
+  if (!stat.isDirectory()) throw new Error(`Not a directory: ${target}`);
+
+  const entries = readdirSync(target, { withFileTypes: true })
+    .map((entry): FileEntry | null => {
+      const entryPath = join(target, entry.name);
+      let type: FileEntry["type"] = entry.isDirectory() ? "directory" : "file";
+      let statForSize;
+      try {
+        const lst = lstatSync(entryPath);
+        if (lst.isSymbolicLink()) type = "symlink";
+        const resolved = realpathSync(entryPath);
+        const rel = relative(base, resolved);
+        if (rel && (rel.startsWith("..") || rel.startsWith("/"))) return null;
+        statForSize = statSync(resolved);
+        if (type !== "symlink") type = statForSize.isDirectory() ? "directory" : "file";
+      } catch {
+        return null;
+      }
+      return {
+        name: entry.name,
+        path: entryPath,
+        type,
+        ...(statForSize.isFile() ? { size: statForSize.size } : {}),
+        modifiedAt: statForSize.mtimeMs,
+      };
+    })
+    .filter((entry): entry is FileEntry => Boolean(entry))
+    .sort((a, b) => {
+      if (a.type === "directory" && b.type !== "directory") return -1;
+      if (a.type !== "directory" && b.type === "directory") return 1;
+      return a.name.localeCompare(b.name);
+    });
+
+  return {
+    path: target,
+    parent: parentInsideBase(target, base),
+    baseDir: base,
+    entries,
+  };
+}
+
+export function statFilePath(requestedPath: string | undefined, baseDir: string): FileStatResult {
+  if (!requestedPath) throw new Error("path is required");
+  const { base, target } = resolveInsideBase(requestedPath, baseDir);
+  const stat = statSync(target);
+  if (!stat.isFile() && !stat.isDirectory()) throw new Error(`Not a file or directory: ${target}`);
+  return {
+    path: target,
+    name: basename(target),
+    type: stat.isDirectory() ? "directory" : "file",
+    baseDir: base,
+    ...(stat.isFile() ? { size: stat.size } : {}),
+    modifiedAt: stat.mtimeMs,
+  };
+}
+
+export function readFilePreview(requestedPath: string | undefined, baseDir: string): FileReadResult {
+  if (!requestedPath) throw new Error("path is required");
+  const { target } = resolveInsideBase(requestedPath, baseDir);
+  const stat = statSync(target);
+  if (!stat.isFile()) throw new Error(`Not a file: ${target}`);
+
+  const bytesToRead = Math.min(stat.size, MAX_FILE_PREVIEW_BYTES);
+  const buffer = Buffer.alloc(bytesToRead);
+  const fd = openSync(target, "r");
+  try {
+    readSync(fd, buffer, 0, bytesToRead, 0);
+  } finally {
+    closeSync(fd);
+  }
+  const mediaType = mediaTypeForPath(target);
+  const resultBase = {
+    path: target,
+    name: basename(target),
+    mediaType,
+    size: stat.size,
+    modifiedAt: stat.mtimeMs,
+    truncated: stat.size > MAX_FILE_PREVIEW_BYTES,
+  };
+
+  if (isBinaryBuffer(buffer)) {
+    return { ...resultBase, encoding: "binary" };
+  }
+
+  return {
+    ...resultBase,
+    encoding: "utf8",
+    content: new TextDecoder("utf-8", { fatal: true }).decode(buffer),
+  };
+}
+
+function isBinaryBuffer(buffer: Buffer): boolean {
+  if (buffer.includes(0)) return true;
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+function mediaTypeForPath(path: string): string {
+  const name = basename(path).toLowerCase();
+  const ext = extname(path).toLowerCase();
+  if (ext === ".md" || ext === ".markdown") return "text/markdown";
+  if (ext === ".json" || ext === ".jsonl") return "application/json";
+  if (ext === ".yaml" || ext === ".yml") return "application/yaml";
+  if (ext === ".toml") return "application/toml";
+  if (ext === ".html") return "text/html";
+  if (ext === ".css") return "text/css";
+  if (ext === ".js" || ext === ".mjs" || ext === ".cjs") return "text/javascript";
+  if (ext === ".ts" || ext === ".tsx" || ext === ".jsx") return "text/typescript";
+  if (ext === ".txt" || ext === ".log" || ext === ".sh" || name.startsWith(".env")) return "text/plain";
+  return "application/octet-stream";
+}
+
 function json(data: unknown, status = 200): Response {
   return new Response(JSON.stringify(data), {
     status,
@@ -57,39 +289,33 @@ function error(message: string, status = 400): Response {
 
 function authorized(req: Request, config: OrchestratorConfig): boolean {
   if (!config.token) return true;
+  const url = new URL(req.url);
+  if (url.searchParams.get("token") === config.token) return true;
   return req.headers.get("x-agent-relay-token") === config.token;
 }
 
-async function commandVersion(command: string): Promise<string | undefined> {
-  try {
-    const proc = Bun.spawn(["bash", "-lc", `command -v ${command} >/dev/null && ${command} --version | head -n 1`], {
-      stdout: "pipe",
-      stderr: "ignore",
-    });
-    const out = await new Response(proc.stdout).text();
-    return (await proc.exited) === 0 ? out.trim() || undefined : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export function startApiServer(config: OrchestratorConfig): { stop(): void; url: string } {
-  const server = Bun.serve({
+export function startApiServer(config: OrchestratorConfig, probeCache: ProviderProbeCache): { stop(): void; url: string } {
+  const server = Bun.serve<TerminalSocketData>({
     port: config.apiPort,
     hostname: "0.0.0.0",
-    fetch(req) {
+    async fetch(req, server) {
       const url = new URL(req.url);
 
       if (req.method === "OPTIONS") {
         return new Response(null, {
           headers: {
             "Access-Control-Allow-Origin": "*",
-            "Access-Control-Allow-Methods": "GET, OPTIONS",
-            "Access-Control-Allow-Headers": "Content-Type, X-Agent-Relay-Token",
+            "Access-Control-Allow-Methods": "GET, POST, HEAD, DELETE, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type, X-Agent-Relay-Token, X-Artifact-Filename, X-Artifact-Digest, X-Artifact-Kind, X-Artifact-Sensitivity, X-Artifact-Expires-At",
           },
         });
       }
 
+      if (url.pathname === "/api/artifacts" || url.pathname.startsWith("/api/artifacts/")) {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        return proxyArtifactRequest(req, config).catch((e) => error((e as Error).message, 502));
+      }
+
       if (req.method === "GET" && url.pathname === "/api/directories") {
         try {
           const listing = listDirectories(url.searchParams.get("path") || undefined, config.baseDir);
@@ -99,25 +325,116 @@ export function startApiServer(config: OrchestratorConfig): { stop(): void; url:
         }
       }
 
+      if (req.method === "POST" && url.pathname === "/api/directories") {
+        try {
+          const body = await req.json() as { path: string; name: string };
+          if (!body.path || !body.name) return error("path and name are required");
+          const listing = createDirectory(body.path, body.name, config.baseDir);
+          return json(listing, 201);
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/files/list") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          return json(listFiles(url.searchParams.get("path") || undefined, config.baseDir));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/files/read") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          return json(readFilePreview(url.searchParams.get("path") || undefined, config.baseDir));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/files/stat") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          return json(statFilePath(url.searchParams.get("path") || undefined, config.baseDir));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/workspace/probe") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
+          return json(await probeWorkspace(target));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/workspace/state") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
+          return json(workspaceGitState({
+            worktreePath: target,
+            baseRef: url.searchParams.get("baseRef") || undefined,
+            baseSha: url.searchParams.get("baseSha") || undefined,
+          }));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/workspace/diff") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
+          return json(workspaceDiff({
+            worktreePath: target,
+            baseRef: url.searchParams.get("baseRef") || undefined,
+            baseSha: url.searchParams.get("baseSha") || undefined,
+            includePatch: url.searchParams.get("patch") !== "0",
+          }));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/workspace/merge-preview") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
+          const strategy = url.searchParams.get("strategy");
+          return json(previewWorkspaceMerge({
+            worktreePath: target,
+            baseRef: url.searchParams.get("baseRef") || undefined,
+            baseSha: url.searchParams.get("baseSha") || undefined,
+            strategy: strategy === "pr" || strategy === "rebase-ff" || strategy === "auto" ? strategy : undefined,
+          }));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
       if (req.method === "GET" && url.pathname === "/api/providers") {
         return (async () => {
-          const providers = await Promise.all(config.providers.map(async (provider) => {
-            const version = await commandVersion(provider);
-            return { name: provider, available: Boolean(version), version, runnerVersion: VERSION };
-          }));
-          return json({ providers });
+          const snapshot = await probeCache.getSnapshot(url.searchParams.get("refresh") === "1");
+          return json(snapshot);
         })();
       }
 
       if (req.method === "GET" && url.pathname === "/api/sessions") {
-        return (async () => {
-          const sessions = await listTmuxSessions(config.tmuxPrefix);
-          return json({ sessions });
-        })();
+        return json({ sessions: listSessions(config.tmuxPrefix) });
       }
 
       if (req.method === "GET" && url.pathname === "/api/version") {
+        const runtime = runtimeMetadata();
         return json({
+          package: runtime.package,
+          contracts: runtime.contracts,
+          capabilities: runtime.capabilities,
           orchestrator: VERSION,
           runner: VERSION,
           adapters: Object.fromEntries(config.providers.map((provider) => [provider, VERSION])),
@@ -127,15 +444,87 @@ export function startApiServer(config: OrchestratorConfig): { stop(): void; url:
       const logMatch = url.pathname.match(/^\/api\/logs\/([^/]+)$/);
       if (req.method === "GET" && logMatch) {
         if (!authorized(req, config)) return error("unauthorized", 401);
-        return (async () => {
-          try {
-            const session = decodeURIComponent(logMatch[1]!);
-            const lines = Number(url.searchParams.get("lines") || "100");
-            return json(await captureSession(session, config, Number.isFinite(lines) ? lines : 100));
-          } catch (e) {
-            return error((e as Error).message, 400);
-          }
-        })();
+        try {
+          const session = decodeURIComponent(logMatch[1]!);
+          const lines = Number(url.searchParams.get("lines") || "100");
+          return json(captureSession(session, config, Number.isFinite(lines) ? lines : 100, {
+            raw: url.searchParams.get("raw") === "1",
+          }));
+        } catch (e) {
+          return error((e as Error).message, 400);
+        }
+      }
+
+      const terminalMatch = url.pathname.match(/^\/api\/terminal\/([^/]+)$/);
+      if (req.method === "GET" && terminalMatch) {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const session = decodeURIComponent(terminalMatch[1]!);
+          return json(captureTerminal(session, config));
+        } catch (e) {
+          return error((e as Error).message, 400);
+        }
+      }
+
+      const terminalStreamMatch = url.pathname.match(/^\/api\/terminal\/([^/]+)\/stream$/);
+      if (req.method === "GET" && terminalStreamMatch) {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const session = decodeURIComponent(terminalStreamMatch[1]!);
+          captureTerminal(session, config);
+          const upgraded = server.upgrade(req, {
+            data: { kind: "terminal", config, session },
+          });
+          if (!upgraded) return new Response("WebSocket upgrade failed", { status: 400 });
+          return undefined;
+        } catch (e) {
+          return error((e as Error).message, 400);
+        }
+      }
+
+      const terminalInputMatch = url.pathname.match(/^\/api\/terminal\/([^/]+)\/input$/);
+      if (req.method === "POST" && terminalInputMatch) {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const session = decodeURIComponent(terminalInputMatch[1]!);
+          const body = await req.json();
+          return json(sendTerminalInput(session, config, body));
+        } catch (e) {
+          return error((e as Error).message, 400);
+        }
+      }
+
+      const terminalResizeMatch = url.pathname.match(/^\/api\/terminal\/([^/]+)\/resize$/);
+      if (req.method === "POST" && terminalResizeMatch) {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const session = decodeURIComponent(terminalResizeMatch[1]!);
+          const body = await req.json();
+          return json(resizeTerminal(session, config, body));
+        } catch (e) {
+          return error((e as Error).message, 400);
+        }
+      }
+
+      if (req.method === "POST" && url.pathname === "/api/terminal-guests") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const body = await req.json();
+          return json(await createTerminalGuest(cleanTerminalGuestInput(body), config), 201);
+        } catch (e) {
+          return error((e as Error).message, 400);
+        }
+      }
+
+      const terminalGuestMatch = url.pathname.match(/^\/api\/terminal-guests\/([^/]+)$/);
+      if (req.method === "DELETE" && terminalGuestMatch) {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const session = decodeURIComponent(terminalGuestMatch[1]!);
+          return json(stopTerminalGuest(session, config));
+        } catch (e) {
+          return error((e as Error).message, 400);
+        }
       }
 
       if (req.method === "GET" && url.pathname === "/api/health") {
@@ -144,9 +533,122 @@ export function startApiServer(config: OrchestratorConfig): { stop(): void; url:
 
       return error("Not found", 404);
     },
+    websocket: {
+      open(ws) {
+        const socket = ws as unknown as TerminalSocket;
+        if (socket.data?.kind === "terminal") startTerminalSocket(socket);
+      },
+      message(ws, data) {
+        const socket = ws as unknown as TerminalSocket;
+        if (socket.data?.kind === "terminal") handleTerminalSocketMessage(socket, data);
+      },
+      close(ws) {
+        const socket = ws as unknown as TerminalSocket;
+        if (socket.data?.kind === "terminal") stopTerminalSocket(socket);
+      },
+    },
   });
 
   const url = `http://${config.hostname}:${config.apiPort}`;
   console.error(`[orchestrator] API server listening on :${config.apiPort}`);
   return { stop: () => server.stop(), url };
 }
+
+function startTerminalSocket(ws: TerminalSocket): void {
+  sendTerminalSnapshot(ws, true);
+  const intervalMs = Number(process.env.AGENT_RELAY_TERMINAL_STREAM_INTERVAL_MS) || 125;
+  ws.data.timer = setInterval(() => {
+    if (!ws.data.paused) sendTerminalSnapshot(ws, false);
+  }, Math.max(50, intervalMs));
+}
+
+function handleTerminalSocketMessage(ws: TerminalSocket, data: string | Buffer): void {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(typeof data === "string" ? data : data.toString("utf8"));
+  } catch {
+    ws.send(JSON.stringify({ type: "error", error: "invalid terminal socket frame" }));
+    return;
+  }
+
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+  const frame = payload as Record<string, unknown>;
+  try {
+    if (frame.type === "input") {
+      sendTerminalInput(ws.data.session, ws.data.config, { data: typeof frame.data === "string" ? frame.data : "" });
+      sendTerminalSnapshot(ws, true);
+    } else if (frame.type === "resize") {
+      resizeTerminal(ws.data.session, ws.data.config, { cols: frame.cols, rows: frame.rows });
+      sendTerminalSnapshot(ws, true);
+    } else if (frame.type === "pause") {
+      ws.data.paused = frame.paused === true;
+      if (!ws.data.paused) sendTerminalSnapshot(ws, true);
+    } else if (frame.type === "refresh") {
+      sendTerminalSnapshot(ws, true);
+    }
+  } catch (e) {
+    ws.send(JSON.stringify({ type: "error", error: e instanceof Error ? e.message : String(e) }));
+  }
+}
+
+function sendTerminalSnapshot(ws: TerminalSocket, force: boolean): void {
+  try {
+    const snapshot = captureTerminal(ws.data.session, ws.data.config);
+    const signature = terminalSnapshotSignature(snapshot);
+    const changed = force || signature !== ws.data.lastSnapshotSignature;
+    if (!changed) {
+      sendTerminalHeartbeat(ws, snapshot, signature);
+      return;
+    }
+    ws.data.lastSnapshotSignature = signature;
+    ws.data.lastHeartbeatAt = snapshot.capturedAt;
+    ws.send(JSON.stringify({ type: "snapshot", ...snapshot }));
+  } catch (e) {
+    ws.send(JSON.stringify({ type: "error", error: e instanceof Error ? e.message : String(e) }));
+    ws.close();
+  }
+}
+
+function sendTerminalHeartbeat(ws: TerminalSocket, snapshot: TerminalSnapshot, signature: string): void {
+  const heartbeatMs = Math.max(
+    1_000,
+    Number(process.env.AGENT_RELAY_TERMINAL_STREAM_HEARTBEAT_MS) || DEFAULT_TERMINAL_STREAM_HEARTBEAT_MS,
+  );
+  if (ws.data.lastHeartbeatAt && snapshot.capturedAt - ws.data.lastHeartbeatAt < heartbeatMs) return;
+  ws.data.lastHeartbeatAt = snapshot.capturedAt;
+  ws.send(JSON.stringify({
+    type: "heartbeat",
+    session: snapshot.session,
+    running: snapshot.running,
+    cols: snapshot.cols,
+    rows: snapshot.rows,
+    cursorX: snapshot.cursorX,
+    cursorY: snapshot.cursorY,
+    capturedAt: snapshot.capturedAt,
+    signature,
+  }));
+}
+
+function stopTerminalSocket(ws: TerminalSocket): void {
+  if (ws.data.timer) clearInterval(ws.data.timer);
+  ws.data.timer = undefined;
+}
+
+function cleanTerminalGuestInput(value: unknown): { agentId?: string; policyName?: string; spawnRequestId?: string; tmuxSession?: string } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("terminal guest body must be an object");
+  const body = value as Record<string, unknown>;
+  const result = {
+    agentId: stringValue(body.agentId),
+    policyName: stringValue(body.policyName),
+    spawnRequestId: stringValue(body.spawnRequestId),
+    tmuxSession: stringValue(body.tmuxSession),
+  };
+  if (!result.agentId && !result.policyName && !result.spawnRequestId && !result.tmuxSession) {
+    throw new Error("agentId, policyName, spawnRequestId, or tmuxSession required");
+  }
+  return result;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}