agentradar-cli 0.1.2 → 0.1.3

package/dist/vendor-runner/terminal-bridge.mjs

@@ -0,0 +1,467 @@
+// AgentRadar #133 (M4 live terminal) — the mini-side FEEDER BRIDGE.
+//
+// Opens a persistent OUTBOUND WebSocket to the AgentRadar server (the mini INITIATES; the server never
+// connects inbound — phone-home preserved) and bridges the agent's tmux pane:
+//   - server {attach}  → start `tmux pipe-pane` → stream pane output as {output} frames (+ an initial
+//                        capture-pane so a late viewer sees the current screen).
+//   - server {detach}  → stop piping (idle agents cost nothing).
+//   - pane GEOMETRY    → {hello cols,rows} on connect + {geometry cols,rows} on change while attached (#9).
+//                        The server has no other way to know the pane size, and without it the client
+//                        watch-terminal renders every agent at a hardcoded 120×30.
+//   - server {input}   → `tmux send-keys -l` (VENDOR keystrokes; the server already dropped client input).
+//   - server {resize}  → `tmux resize-window -x -y`.
+// Auth: `Sec-WebSocket-Protocol: agentradar-feeder, <AWP bearer>` (never a ?token= query; never logged).
+//
+// DEPENDENCY-FREE (node builtins only), matching feeder.mjs. Minimal RFC6455 client framing (mask on
+// send; parse unmasked server frames). Reconnects with backoff. Launched by the supervisor alongside
+// feeder.mjs; it NEVER touches the liveness poll loop.
+//
+// SECRET HYGIENE (disc §8/§7b): the bearer + creds are file-staged 0600 and never printed to the pane
+// (#152/#166), so the streamed pane can't leak them. VENDOR NOTE (disc §7b): the client RO view shows the
+// vendor's RAW session — a vendor must NOT print their OWN non-AgentRadar secrets into the pane (the
+// server-side scrubber only masks AgentRadar cred shapes ar_/sk-ant-/Bearer/AKIA).
+
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import os from "node:os";
+import path from "node:path";
+
+const AWP_MCP_ENDPOINT = process.env.AWP_MCP_URL ?? "https://staging.agentradar.com/api/mcp";
+const AWP_BEARER = (() => {
+  const f = process.env.AWP_BEARER_FILE;
+  if (f) {
+    try {
+      return fs.readFileSync(f, "utf8").trim();
+    } catch (e) {
+      console.error(`[bridge] FATAL: AWP_BEARER_FILE unreadable (${f}): ${e.message}`);
+      process.exit(1);
+    }
+  }
+  return process.env.AWP_BEARER ?? "";
+})();
+const TMUX_SESSION = process.env.TMUX_SESSION ?? "agent";
+// Resolve the tmux binary robustly: a bare "tmux" only works if it's on PATH, but the bridge is often
+// launched from a supervisor / LaunchAgent whose PATH excludes e.g. /opt/homebrew/bin — then every tmux
+// call ENOENTs and pipe-pane/send-keys silently no-op (feeder connects but streams nothing). Prefer an
+// explicit TMUX_BIN; else probe common absolute locations; else fall back to bare "tmux".
+const TMUX_BIN = (() => {
+  if (process.env.TMUX_BIN) return process.env.TMUX_BIN;
+  for (const p of ["/opt/homebrew/bin/tmux", "/usr/local/bin/tmux", "/usr/bin/tmux"]) {
+    try {
+      if (fs.existsSync(p)) return p;
+    } catch {
+      /* ignore */
+    }
+  }
+  return "tmux";
+})();
+const RECONNECT_MIN_MS = Number(process.env.BRIDGE_RECONNECT_MIN_MS ?? "1000");
+const RECONNECT_MAX_MS = Number(process.env.BRIDGE_RECONNECT_MAX_MS ?? "15000");
+// #18: the server heartbeat-pings every 30s (#198). If pings STOP the connection is dead even though the OS
+// still reports it ESTABLISHED — an ALB holds the client leg open for the whole target `deregistration_delay`
+// (300s on staging) after the backend task is gone, and nothing on this side notices. Measured: across a
+// staging rollout the bridge sat on a dead socket for ~5 minutes and only reconnected when the ALB finally
+// force-closed it — i.e. a ~5 min live-terminal blackout on EVERY deploy. Watch for ping silence ourselves so
+// recovery is ours, not the load balancer's.
+const SERVER_PING_TIMEOUT_MS = Number(process.env.BRIDGE_PING_TIMEOUT_MS ?? "90000"); // 3× the 30s server ping
+// #9: how often the pane size is re-read WHILE A VIEWER IS ATTACHED. tmux gives us no resize event, so the
+// only way to notice a pane change is to ask. The poll runs only between attach and detach, so an unwatched
+// agent still costs nothing, and a frame is sent only when the size actually CHANGED — an unchanged read is
+// one cheap tmux call and no traffic.
+const GEOMETRY_POLL_MS = Number(process.env.BRIDGE_GEOMETRY_POLL_MS ?? "5000");
+
+/**
+ * #18: run `fn` at most once, however many times the returned function is called.
+ * A socket emits `error` AND THEN `close`, so a teardown registered on both used to run twice and schedule
+ * TWO reconnects — leaving one bridge process holding two independent feeder sockets (observed live).
+ * Exported so the once-only guarantee is unit-tested rather than assumed.
+ */
+export function once(fn) {
+  let called = false;
+  return (...args) => {
+    if (called) return undefined;
+    called = true;
+    return fn(...args);
+  };
+}
+
+// Derive the feeder WS URL from the MCP endpoint: https://host/api/mcp → wss://host/internal/agent-terminal/feeder
+function feederWsUrl() {
+  const u = new URL(AWP_MCP_ENDPOINT);
+  u.protocol = u.protocol === "http:" ? "ws:" : "wss:";
+  u.pathname = "/internal/agent-terminal/feeder";
+  u.search = "";
+  return u;
+}
+
+// ---- minimal RFC6455 frame codec (exported for unit test) ----
+export function encodeFrame(payload, opcode = 0x1) {
+  const data = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), "utf8");
+  const len = data.length;
+  let header;
+  if (len < 126) header = Buffer.alloc(2 + 4);
+  else if (len < 65536) header = Buffer.alloc(4 + 4);
+  else header = Buffer.alloc(10 + 4);
+  header[0] = 0x80 | (opcode & 0x0f); // FIN + opcode
+  let maskOffset;
+  if (len < 126) {
+    header[1] = 0x80 | len; // MASK + len
+    maskOffset = 2;
+  } else if (len < 65536) {
+    header[1] = 0x80 | 126;
+    header.writeUInt16BE(len, 2);
+    maskOffset = 4;
+  } else {
+    header[1] = 0x80 | 127;
+    header.writeUInt32BE(0, 2);
+    header.writeUInt32BE(len, 6);
+    maskOffset = 10;
+  }
+  const mask = randomBytes(4);
+  mask.copy(header, maskOffset);
+  const masked = Buffer.alloc(len);
+  for (let i = 0; i < len; i++) masked[i] = data[i] ^ mask[i & 3];
+  return Buffer.concat([header, masked]);
+}
+
+// Parse as many complete (unmasked, server→client) frames as are buffered. Returns {frames, rest}.
+export function parseFrames(buf) {
+  const frames = [];
+  let off = 0;
+  while (off + 2 <= buf.length) {
+    const b0 = buf[off];
+    const b1 = buf[off + 1];
+    const opcode = b0 & 0x0f;
+    const masked = (b1 & 0x80) !== 0;
+    let len = b1 & 0x7f;
+    let p = off + 2;
+    if (len === 126) {
+      if (p + 2 > buf.length) break;
+      len = buf.readUInt16BE(p);
+      p += 2;
+    } else if (len === 127) {
+      if (p + 8 > buf.length) break;
+      len = Number(buf.readBigUInt64BE(p));
+      p += 8;
+    }
+    const maskKey = masked ? buf.subarray(p, p + 4) : null;
+    if (masked) p += 4;
+    if (p + len > buf.length) break; // incomplete
+    let payload = buf.subarray(p, p + len);
+    if (masked && maskKey) {
+      const out = Buffer.alloc(len);
+      for (let i = 0; i < len; i++) out[i] = payload[i] ^ maskKey[i & 3];
+      payload = out;
+    }
+    frames.push({ opcode, payload });
+    off = p + len;
+  }
+  return { frames, rest: buf.subarray(off) };
+}
+
+let tmuxSpawnWarned = false;
+function tmux(argv) {
+  const r = spawnSync(TMUX_BIN, argv, { encoding: "utf8" });
+  // spawnSync does NOT throw on ENOENT — it returns { error }. Surface it ONCE so a missing/mis-pathed
+  // tmux is visible instead of silently no-op'ing (feeder up, zero output) as it otherwise would.
+  if (r.error && !tmuxSpawnWarned) {
+    tmuxSpawnWarned = true;
+    console.error(`[bridge] FATAL: cannot exec tmux ("${TMUX_BIN}"): ${r.error.message}. Set TMUX_BIN to its absolute path.`);
+  }
+  return r;
+}
+
+/**
+ * #9: the CURRENT pane geometry, or null if tmux could not answer.
+ *
+ * The server has no other way to know this — it only ever sees `output` bytes — so before this existed the
+ * client watch-terminal rendered every agent at a hardcoded 120×30, which is wrong for all three fleet panes
+ * (80×24, 80×24, 104×36). Returning null on any doubt is deliberate: the server ignores a malformed report
+ * and keeps the last known good size, which is strictly better than publishing a guess.
+ */
+function readPaneGeometry() {
+  const r = tmux(["display-message", "-p", "-t", TMUX_SESSION, "#{pane_width}x#{pane_height}"]);
+  if (r.status !== 0) return null;
+  return parsePaneGeometry(r.stdout);
+}
+
+/**
+ * #9: the pure half of readPaneGeometry — parse+validate `tmux display-message` output. Separated so the
+ * validation is unit-testable without a tmux; the invocation half is exercised by the live gate.
+ *
+ * Everything that is not exactly `<digits>x<digits>` returns null, including tmux's own error text. That
+ * matters because tmux writes "can't find session" to STDOUT with a zero-ish status in some versions, so a
+ * status check alone would let a string through.
+ */
+export function parsePaneGeometry(stdout) {
+  if (typeof stdout !== "string") return null;
+  const m = stdout.trim().match(/^(\d+)x(\d+)$/);
+  if (!m) return null;
+  const cols = Number(m[1]);
+  const rows = Number(m[2]);
+  if (!cols || !rows) return null;
+  return { cols, rows };
+}
+
+class TerminalBridge {
+  constructor() {
+    this.sock = null;
+    this.piping = false;
+    this.fifoPath = null;
+    this.fifoStream = null;
+    this.recvBuf = Buffer.alloc(0);
+    this.backoff = RECONNECT_MIN_MS;
+    this.pingTimer = null;
+    // #9: last geometry we told the SERVER about, so we only send a frame when it actually changed.
+    // Reset to null on every (re)connect — a reconnect may land on a different server task with no memory
+    // of this session, so the new peer must be told even if the pane never moved.
+    this.geometry = null;
+    this.geometryTimer = null;
+  }
+
+  /**
+   * #18: (re)arm the dead-peer watchdog. Called on connect and on EVERY inbound byte.
+   *
+   * Deliberately grounded in observed traffic rather than in ping frames specifically. Re-arming only on
+   * pings (0x9) would make this timer's safety depend on a constant in ANOTHER process: #198 currently
+   * pings every connection unconditionally every 30s, but its stated motivation is keeping *idle* sockets
+   * off the ALB idle timeout — so if it ever becomes idle-only, a healthy, actively-streaming bridge would
+   * stop receiving pings and this watchdog would kill it every SERVER_PING_TIMEOUT_MS. Any inbound byte
+   * proves the peer is alive, so there is no cross-process invariant left to break.
+   */
+  armPingWatchdog(socket) {
+    this.clearPingWatchdog();
+    if (!SERVER_PING_TIMEOUT_MS) return; // 0 disables
+    this.pingTimer = setTimeout(() => {
+      console.log(`[bridge] no server ping in ${SERVER_PING_TIMEOUT_MS}ms — treating peer as dead, reconnecting`);
+      try {
+        socket.destroy();
+      } catch {
+        /* the close/error handler drives the reconnect */
+      }
+    }, SERVER_PING_TIMEOUT_MS);
+    if (typeof this.pingTimer.unref === "function") this.pingTimer.unref();
+  }
+
+  clearPingWatchdog() {
+    if (this.pingTimer) {
+      clearTimeout(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+
+  send(obj) {
+    if (!this.sock || this.sock.destroyed) return;
+    try {
+      this.sock.write(encodeFrame(JSON.stringify(obj), 0x1));
+    } catch {
+      /* dead socket; reconnect loop handles it */
+    }
+  }
+
+  /**
+   * #9: tell the server the pane size, but only when it CHANGED (or when `force`, e.g. right after a viewer
+   * attached or after we reconnected). Sending unconditionally would re-broadcast a `ready` frame to every
+   * open browser on every poll tick.
+   */
+  reportGeometry(force = false) {
+    const g = readPaneGeometry();
+    if (!g) return;
+    if (!force && this.geometry && this.geometry.cols === g.cols && this.geometry.rows === g.rows) return;
+    this.geometry = g;
+    this.send({ type: "geometry", cols: g.cols, rows: g.rows });
+  }
+
+  startGeometryPoll() {
+    if (this.geometryTimer) return;
+    this.geometryTimer = setInterval(() => this.reportGeometry(), GEOMETRY_POLL_MS);
+    if (typeof this.geometryTimer.unref === "function") this.geometryTimer.unref();
+  }
+
+  stopGeometryPoll() {
+    if (!this.geometryTimer) return;
+    clearInterval(this.geometryTimer);
+    this.geometryTimer = null;
+  }
+
+  startPipe() {
+    if (this.piping) return;
+    this.piping = true;
+    // #9: a viewer just attached — publish the real pane size before the first bytes, so the client sizes
+    // its grid correctly rather than painting the replay into a fallback grid and re-flowing a moment later.
+    this.reportGeometry(true);
+    this.startGeometryPoll();
+    // Initial screen so a viewer attaching mid-session sees current state.
+    const cap = tmux(["capture-pane", "-ep", "-t", TMUX_SESSION]);
+    if (cap.status === 0 && cap.stdout) this.send({ type: "output", data: cap.stdout });
+    // Stream new output via a fifo that tmux pipe-pane writes into.
+    this.fifoPath = path.join(os.tmpdir(), `ar-bridge-${process.pid}-${Date.now()}.fifo`);
+    spawnSync("mkfifo", [this.fifoPath]);
+    tmux(["pipe-pane", "-t", TMUX_SESSION, `cat >> ${this.fifoPath}`]);
+    this.fifoStream = fs.createReadStream(this.fifoPath);
+    this.fifoStream.on("data", (chunk) => this.send({ type: "output", data: chunk.toString("utf8") }));
+    this.fifoStream.on("error", () => {});
+  }
+
+  stopPipe() {
+    if (!this.piping) return;
+    this.piping = false;
+    this.stopGeometryPoll(); // #9: nobody is watching → stop asking tmux anything
+    tmux(["pipe-pane", "-t", TMUX_SESSION]); // empty command → stop piping
+    if (this.fifoStream) {
+      try {
+        this.fifoStream.destroy();
+      } catch {
+        /* ignore */
+      }
+      this.fifoStream = null;
+    }
+    if (this.fifoPath) {
+      try {
+        fs.unlinkSync(this.fifoPath);
+      } catch {
+        /* ignore */
+      }
+      this.fifoPath = null;
+    }
+  }
+
+  onServerFrame(obj) {
+    switch (obj?.type) {
+      case "attach":
+        this.startPipe();
+        break;
+      case "detach":
+        this.stopPipe();
+        break;
+      case "input":
+        if (typeof obj.data === "string") tmux(["send-keys", "-t", TMUX_SESSION, "-l", obj.data]);
+        break;
+      case "resize":
+        if (Number.isFinite(obj.cols) && Number.isFinite(obj.rows)) {
+          tmux(["resize-window", "-t", TMUX_SESSION, "-x", String(obj.cols), "-y", String(obj.rows)]);
+          // #9: report what tmux ACTUALLY did, not what was asked for. tmux clamps to the smallest attached
+          // client, so the requested size and the resulting pane routinely differ — echoing the request back
+          // would publish a size the pane does not have.
+          this.reportGeometry();
+        }
+        break;
+      default:
+        break;
+    }
+  }
+
+  connect() {
+    const url = feederWsUrl();
+    const key = randomBytes(16).toString("base64");
+    const lib = url.protocol === "wss:" ? https : http;
+    const req = lib.request({
+      hostname: url.hostname,
+      port: url.port || (url.protocol === "wss:" ? 443 : 80),
+      path: url.pathname,
+      method: "GET",
+      headers: {
+        Connection: "Upgrade",
+        Upgrade: "websocket",
+        "Sec-WebSocket-Version": "13",
+        "Sec-WebSocket-Key": key,
+        // Auth rides the subprotocol (never a query param); NEVER logged.
+        "Sec-WebSocket-Protocol": `agentradar-feeder, ${AWP_BEARER}`,
+      },
+    });
+    req.on("upgrade", (res, socket) => {
+      const accept = createHash("sha1")
+        .update(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")
+        .digest("base64");
+      if (res.headers["sec-websocket-accept"] !== accept) {
+        socket.destroy();
+        return;
+      }
+      this.sock = socket;
+      this.backoff = RECONNECT_MIN_MS;
+      console.log("[bridge] connected");
+      this.armPingWatchdog(socket); // #18
+      // #9: a reconnect may land on a different server task, which has no memory of this session — so the
+      // new peer is told the pane size unconditionally, in the very first frame.
+      this.geometry = readPaneGeometry();
+      this.send({
+        type: "hello",
+        session: TMUX_SESSION,
+        ...(this.geometry ? { cols: this.geometry.cols, rows: this.geometry.rows } : {}),
+      });
+      socket.on("data", (buf) => {
+        this.armPingWatchdog(socket); // #18: any inbound byte proves the peer is alive — see armPingWatchdog
+        this.recvBuf = Buffer.concat([this.recvBuf, buf]);
+        const { frames, rest } = parseFrames(this.recvBuf);
+        this.recvBuf = rest;
+        for (const f of frames) {
+          if (f.opcode === 0x8) {
+            socket.end();
+            return;
+          }
+          if (f.opcode === 0x9) {
+            // #198: the server heartbeat-pings idle connections (< ALB idle timeout) so the feeder WS
+            // doesn't go half-open. Reply pong (0xA, echo payload) — else the server terminates us as dead.
+            // (The dead-peer watchdog is re-armed by the `data` handler above, for ANY frame — this branch
+            // deliberately does NOT re-arm, so nothing here couples to the server's ping cadence.)
+            try {
+              socket.write(encodeFrame(f.payload, 0xA));
+            } catch {
+              /* dead socket; reconnect loop handles it */
+            }
+            continue;
+          }
+          if (f.opcode === 0x1) {
+            try {
+              this.onServerFrame(JSON.parse(f.payload.toString("utf8")));
+            } catch {
+              /* ignore malformed */
+            }
+          }
+        }
+      });
+      // #18: `error` is followed by `close` on the same socket, so registering this on BOTH fired it TWICE
+      // and scheduled TWO reconnects — leaving ONE bridge process holding TWO independent feeder sockets.
+      // Observed in production: the Spielberg bridge held two ESTABLISHED sockets to two different ALB IPs.
+      // That is what makes the server-side stale-close bug reachable (a superseded socket closing used to
+      // unbind the live feeder). Fire teardown exactly once per socket.
+      const teardown = once(() => {
+        this.clearPingWatchdog();
+        this.stopPipe();
+        this.sock = null;
+        this.recvBuf = Buffer.alloc(0);
+        this.scheduleReconnect();
+      });
+      socket.on("close", teardown);
+      socket.on("error", teardown);
+    });
+    // A non-upgrade HTTP reply (e.g. 502 during a deploy window, or 200 SPA-fallback if the WS
+    // route isn't wired) fires "response", NOT "upgrade"/"error". Without this handler the bridge
+    // would hang silently (no reconnect). Log the status and back off → reconnect.
+    req.on("response", (res) => {
+      console.log(`[bridge] upgrade refused: HTTP ${res.statusCode} (expected 101) — will retry`);
+      res.resume(); // drain so the socket can free
+      this.scheduleReconnect();
+    });
+    req.on("error", () => this.scheduleReconnect());
+    req.end();
+  }
+
+  scheduleReconnect() {
+    const d = this.backoff;
+    this.backoff = Math.min(this.backoff * 2, RECONNECT_MAX_MS);
+    setTimeout(() => this.connect(), d);
+  }
+}
+
+// Only auto-run when executed directly (not when imported by the unit test).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  if (!AWP_BEARER) {
+    console.error("[bridge] FATAL: no AWP bearer (set AWP_BEARER_FILE or AWP_BEARER)");
+    process.exit(1);
+  }
+  new TerminalBridge().connect();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentradar-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Secure AgentRadar vendor setup and skill installer",
   "type": "module",
   "bin": {
@@ -9,7 +9,9 @@
   "files": [
     "dist/index.js",
     "dist/setup.js",
+    "dist/runner.js",
     "dist/skill-install.js",
+    "dist/vendor-runner/**",
     "dist/agentradar-vendor/SKILL.md",
     "README.md"
   ],
@@ -18,7 +20,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && mkdir -p dist/agentradar-vendor && cp ../../skills/agentradar-vendor/SKILL.md dist/agentradar-vendor/SKILL.md && chmod +x dist/index.js",
+    "build": "tsc && mkdir -p dist/agentradar-vendor dist/vendor-runner/supervisor && cp ../../skills/agentradar-vendor/SKILL.md dist/agentradar-vendor/SKILL.md && cp ../../templates/vendor-runner/feeder.mjs ../../templates/vendor-runner/pane-live.sh ../../templates/vendor-runner/session-frame.mjs ../../templates/vendor-runner/terminal-bridge.mjs dist/vendor-runner/ && cp ../../templates/vendor-runner/supervisor/supervise-agent.sh dist/vendor-runner/supervisor/ && chmod +x dist/index.js dist/vendor-runner/pane-live.sh dist/vendor-runner/supervisor/supervise-agent.sh",
     "clean": "rm -rf dist",
     "prepack": "pnpm run build",
     "typecheck": "tsc --noEmit",