@buildautomaton/cli 0.1.26 → 0.1.28

package/dist/cli.js

@@ -25064,7 +25064,7 @@ var {
 } = import_index.default;
 
 // src/cli-version.ts
-var CLI_VERSION = "0.1.26".length > 0 ? "0.1.26" : "0.0.0-dev";
+var CLI_VERSION = "0.1.28".length > 0 ? "0.1.28" : "0.0.0-dev";
 
 // src/cli/defaults.ts
 var DEFAULT_API_URL = process.env.BUILDAUTOMATON_API_URL ?? "https://api.buildautomaton.com";
@@ -25352,6 +25352,17 @@ function createCliE2eeRuntime(key) {
       const merged = { ...message, ...parsed };
       delete merged.ee;
       return merged;
+    },
+    decryptEnvelopeToBuffer(envelope) {
+      if (envelope.k !== key.id) throw new Error(`E2EE key mismatch: ${envelope.k}`);
+      const sealed = Buffer.from(base64UrlDecode(envelope.c));
+      if (sealed.length < 16) throw new Error("Invalid E2EE payload.");
+      const ciphertext = sealed.subarray(0, sealed.length - 16);
+      const tag = sealed.subarray(sealed.length - 16);
+      const nonce = Buffer.from(base64UrlDecode(envelope.n));
+      const decipher = createDecipheriv("aes-256-gcm", rawKey, nonce);
+      decipher.setAuthTag(tag);
+      return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
     }
   };
 }
@@ -25627,6 +25638,12 @@ function sendWsMessage(ws, payload) {
   }
 }
 
+// src/connection/heartbeat/constants.ts
+var BRIDGE_APP_HEARTBEAT_INTERVAL_MS = 1e4;
+var BRIDGE_HEARTBEAT_SEQ_MAX = 2147483646;
+var BRIDGE_HEARTBEAT_MISSED_ACKS_BEFORE_RECONNECT = 4;
+var BRIDGE_HEARTBEAT_RTT_SAMPLE_MAX = 5;
+
 // ../../node_modules/.pnpm/open@10.2.0/node_modules/open/index.js
 import process7 from "node:process";
 import { Buffer as Buffer2 } from "node:buffer";
@@ -26605,14 +26622,18 @@ function runPendingAuth(options) {
   }
   function connect() {
     const url2 = buildPendingBridgeUrl(apiUrl, connectionId);
+    let pendingHbSeq = -1;
     ws = createWsBridge({
       url: url2,
       onOpen: () => {
         clearQuietOnOpen();
+        pendingHbSeq = -1;
         sendWsMessage(ws, { type: "identify", role: "cli", cliVersion: CLI_VERSION });
         keepaliveInterval = setInterval(() => {
           if (resolved || !ws || ws.readyState !== 1) return;
-          sendWsMessage(ws, { type: "ping", timestamp: Date.now() });
+          pendingHbSeq = pendingHbSeq >= BRIDGE_HEARTBEAT_SEQ_MAX ? 0 : pendingHbSeq + 1;
+          const hb = { t: "h", s: pendingHbSeq };
+          sendWsMessage(ws, hb);
         }, PENDING_KEEPALIVE_MS);
         if (browserFallback) {
           clearTimeout(browserFallback);
@@ -32252,6 +32273,96 @@ function augmentPromptResultAuthFields(agentType, errorText) {
   return { agentAuthRequired: true, agentType };
 }
 
+// src/agents/acp/fetch-session-attachments.ts
+function metaSaysEncrypted(meta) {
+  if (!meta) return false;
+  const e = meta.encrypted;
+  return e === true || e === "true" || e === 1;
+}
+function warnIfDecodedImageMagicUnexpected(buf, mimeType, idShort) {
+  const m = mimeType.toLowerCase();
+  if (!m.startsWith("image/") || buf.length < 4) return;
+  const b0 = buf[0];
+  const b1 = buf[1];
+  const b2 = buf[2];
+  const b3 = buf[3];
+  let looksOk = false;
+  if (m.includes("png") && b0 === 137 && b1 === 80 && b2 === 78 && b3 === 71) looksOk = true;
+  else if ((m.includes("jpeg") || m.includes("jpg")) && b0 === 255 && b1 === 216 && b2 === 255) looksOk = true;
+  else if (m.includes("gif") && b0 === 71 && b1 === 73 && b2 === 70) looksOk = true;
+  else if (m.includes("webp") && buf.length >= 12 && buf.subarray(0, 4).toString("ascii") === "RIFF" && buf.subarray(8, 12).toString("ascii") === "WEBP")
+    looksOk = true;
+  else if (!/(png|jpe?g|gif|webp)/i.test(m)) looksOk = true;
+  if (!looksOk) {
+    logDebug(
+      `[Agent] Attachment ${idShort} (${mimeType}): decoded bytes do not match common image signatures \u2014 wrong E2EE key, corrupt blob, or metadata mismatch. First 12 bytes (hex): ${buf.subarray(0, Math.min(12, buf.length)).toString("hex")}`
+    );
+  }
+}
+async function fetchSessionAttachmentPayloadsForAgent(params) {
+  const { attachments, sessionId, cloudApiBaseUrl, getCloudAccessToken, e2ee, log: log2 } = params;
+  const token = getCloudAccessToken();
+  if (!token) {
+    return { ok: false, error: "Missing cloud access token; cannot download attachments." };
+  }
+  const wantedCount = attachments.filter((a) => typeof a.attachmentId === "string" && a.attachmentId.trim() !== "").length;
+  if (wantedCount === 0) {
+    return { ok: false, error: "No valid attachment ids in prompt." };
+  }
+  const base = cloudApiBaseUrl.replace(/\/+$/, "");
+  const out = [];
+  for (const a of attachments) {
+    const id = typeof a.attachmentId === "string" ? a.attachmentId.trim() : "";
+    if (!id) continue;
+    const metaUrl = `${base}/api/sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(id)}/meta`;
+    const blobUrl = `${base}/api/sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(id)}/blob`;
+    const metaRes = await fetch(metaUrl, { headers: { Authorization: `Bearer ${token}` } });
+    if (!metaRes.ok) {
+      const t = await metaRes.text().catch(() => "");
+      log2(`[Agent] Attachment meta fetch failed ${metaRes.status}: ${t.slice(0, 200)}`);
+      return { ok: false, error: `Could not load attachment (${id.slice(0, 8)}\u2026): ${metaRes.status}` };
+    }
+    const meta = await metaRes.json().catch(() => null);
+    const mimeType = typeof meta?.mimeType === "string" && meta.mimeType.trim() ? meta.mimeType.trim() : a.mimeType;
+    const blobRes = await fetch(blobUrl, { headers: { Authorization: `Bearer ${token}` } });
+    if (!blobRes.ok) {
+      const t = await blobRes.text().catch(() => "");
+      log2(`[Agent] Attachment blob fetch failed ${blobRes.status}: ${t.slice(0, 200)}`);
+      return { ok: false, error: `Could not load attachment data (${id.slice(0, 8)}\u2026): ${blobRes.status}` };
+    }
+    const buf = Buffer.from(await blobRes.arrayBuffer());
+    let imageBytes;
+    const encrypted = metaSaysEncrypted(meta);
+    if (encrypted) {
+      if (!e2ee) {
+        return { ok: false, error: "Encrypted attachments require E2EE keys on this bridge." };
+      }
+      const k = typeof meta?.k === "string" ? meta.k : "";
+      const n = typeof meta?.n === "string" ? meta.n : "";
+      if (!k || !n) {
+        return { ok: false, error: "Invalid encrypted attachment metadata (missing key id or nonce)." };
+      }
+      const c = base64UrlEncode(buf);
+      imageBytes = e2ee.decryptEnvelopeToBuffer({ k, n, c });
+    } else {
+      imageBytes = buf;
+    }
+    warnIfDecodedImageMagicUnexpected(imageBytes, mimeType, id.slice(0, 8));
+    logDebug(
+      `[Agent] Loaded prompt image ${id.slice(0, 8)}\u2026: ${imageBytes.length} bytes, mime=${mimeType}, ${encrypted ? "E2EE decrypted" : "plaintext from storage"}`
+    );
+    const dataBase64 = imageBytes.toString("base64");
+    out.push({ mimeType, dataBase64 });
+  }
+  if (out.length !== wantedCount) {
+    return {
+      ok: false,
+      error: `Expected ${wantedCount} image attachment(s) but only loaded ${out.length} (check attachment ids and empty rows).`
+    };
+  }
+  return { ok: true, images: out };
+}
+
 // src/agents/acp/send-prompt-to-agent.ts
 async function sendPromptToAgent(options) {
   const {
@@ -32269,10 +32380,49 @@ async function sendPromptToAgent(options) {
     sessionChangeSummaryFilePaths,
     cloudApiBaseUrl,
     getCloudAccessToken,
-    e2ee
+    e2ee,
+    attachments
   } = options;
   try {
-    const result = await handle.sendPrompt(promptText, {});
+    let sendOpts = {};
+    if (attachments && attachments.length > 0) {
+      if (!sessionId || !cloudApiBaseUrl || !getCloudAccessToken) {
+        sendResult2({
+          type: "prompt_result",
+          id: promptId,
+          ...sessionId ? { sessionId } : {},
+          ...runId ? { runId } : {},
+          success: false,
+          error: "Prompt includes images but the bridge is not configured with a cloud API URL and token to fetch them.",
+          ...followUpCatalogPromptId != null && followUpCatalogPromptId !== "" ? { followUpCatalogPromptId } : {},
+          ...augmentPromptResultAuthFields(agentType, "missing cloud for images download")
+        });
+        return;
+      }
+      const resolved = await fetchSessionAttachmentPayloadsForAgent({
+        attachments,
+        sessionId,
+        cloudApiBaseUrl,
+        getCloudAccessToken,
+        e2ee,
+        log: log2
+      });
+      if (!resolved.ok) {
+        sendResult2({
+          type: "prompt_result",
+          id: promptId,
+          ...sessionId ? { sessionId } : {},
+          ...runId ? { runId } : {},
+          success: false,
+          error: resolved.error,
+          ...followUpCatalogPromptId != null && followUpCatalogPromptId !== "" ? { followUpCatalogPromptId } : {},
+          ...augmentPromptResultAuthFields(agentType, resolved.error)
+        });
+        return;
+      }
+      sendOpts = { images: resolved.images };
+    }
+    const result = await handle.sendPrompt(promptText, sendOpts);
     if (sessionId && runId && sendSessionUpdate && agentCwd && result.success) {
       await collectTurnGitDiffFromPreTurnSnapshot({
         sessionId,
@@ -32714,13 +32864,16 @@ function parseAcpInitAgentCapabilities(initResult) {
   const canLoad = agentCapabilities?.loadSession === true;
   const sessionCaps = agentCapabilities?.sessionCapabilities;
   const canResume = Boolean(sessionCaps?.resume);
-  return { canResume, canLoad };
+  const promptCaps = agentCapabilities?.promptCapabilities;
+  const promptSupportsImage = promptCaps?.image === true;
+  return { canResume, canLoad, promptSupportsImage };
 }
 
 // src/agents/acp/clients/shared/bootstrap-acp-wire-session.ts
 async function bootstrapAcpWireSession(transport, ctx, initializeRequest) {
   const initResult = await transport.initialize(initializeRequest);
-  const { canResume, canLoad } = parseAcpInitAgentCapabilities(initResult);
+  const { canResume, canLoad, promptSupportsImage } = parseAcpInitAgentCapabilities(initResult);
+  ctx.agentPromptImageSupported = promptSupportsImage;
   await transport.afterInitialize?.();
   const established = await establishAcpSessionWithTransport(transport, ctx, canResume, canLoad);
   const sessionId = established.sessionId;
@@ -32811,11 +32964,27 @@ function normalizeAcpPromptTurnFailure(err, stderrCaptureText) {
 }
 
 // src/agents/acp/clients/shared/send-acp-prompt-via-transport.ts
-async function sendAcpPromptViaTransport(transport, ctx, sessionId, promptText) {
+async function sendAcpPromptViaTransport(transport, ctx, sessionId, promptText, images) {
+  if (images && images.length > 0 && !ctx.agentPromptImageSupported) {
+    await new Promise((r) => setImmediate(r));
+    return normalizeAcpPromptTurnFailure(
+      new Error(
+        "This agent does not advertise image support in ACP (missing agentCapabilities.promptCapabilities.image). Remove images or use an agent that supports prompt images."
+      ),
+      ctx.getStderrText()
+    );
+  }
+  const textBlock = promptText.trim() !== "" ? promptText : images?.length ? " " : "";
+  const prompt = [{ type: "text", text: textBlock }];
+  if (images && images.length > 0) {
+    for (const im of images) {
+      prompt.push({ type: "image", mimeType: im.mimeType, data: im.data });
+    }
+  }
   try {
     const response = await transport.prompt({
       sessionId,
-      prompt: [{ type: "text", text: promptText }]
+      prompt
     });
     await new Promise((r2) => setImmediate(r2));
     const r = response;
@@ -32991,15 +33160,17 @@ async function createSdkStdioAcpClient(options) {
         const established = await bootstrapAcpWireSession(transport, sessionCtx, {
           protocolVersion: PROTOCOL_VERSION2,
           clientCapabilities: {
-            fs: { readTextFile: true, writeTextFile: true }
+            fs: { readTextFile: true, writeTextFile: true },
+            prompt: { image: true }
           },
           clientInfo: { name: "buildautomaton-cli", version: "0.1.0" }
         });
         const sessionId = established.sessionId;
         settleResolve({
           sessionId,
-          async sendPrompt(prompt, _options) {
-            return sendAcpPromptViaTransport(transport, sessionCtx, sessionId, prompt);
+          async sendPrompt(prompt, options2) {
+            const imgs = options2?.images?.map((im) => ({ type: "image", mimeType: im.mimeType, data: im.dataBase64 }));
+            return sendAcpPromptViaTransport(transport, sessionCtx, sessionId, prompt, imgs);
           },
           async cancel() {
             for (const [id, entry] of [...pendingPermissionReplies.entries()]) {
@@ -33367,14 +33538,19 @@ async function createCursorAcpClient(options) {
         });
         const established = await bootstrapAcpWireSession(transport, sessionCtx, {
           protocolVersion: 1,
-          clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: false },
+          clientCapabilities: {
+            fs: { readTextFile: true, writeTextFile: true },
+            terminal: false,
+            prompt: { image: true }
+          },
           clientInfo: { name: "buildautomaton-cli", version: "0.1.0" }
         });
         const sessionId = established.sessionId;
         resolve18({
           sessionId,
-          async sendPrompt(prompt, _options) {
-            return sendAcpPromptViaTransport(transport, sessionCtx, sessionId, prompt);
+          async sendPrompt(prompt, options2) {
+            const imgs = options2?.images?.map((im) => ({ type: "image", mimeType: im.mimeType, data: im.dataBase64 }));
+            return sendAcpPromptViaTransport(transport, sessionCtx, sessionId, prompt, imgs);
           },
           async cancel() {
             cancelPendingPermissionRequests2();
@@ -34405,7 +34581,8 @@ async function createAcpManager(options) {
       sessionChangeSummaryFilePaths,
       cloudApiBaseUrl,
       getCloudAccessToken,
-      e2ee
+      e2ee,
+      attachments
     } = opts;
     const preferredForPrompt = agentType ?? backendFallbackAgentType ?? null;
     pendingCancelRunId = void 0;
@@ -34476,7 +34653,8 @@ async function createAcpManager(options) {
         sessionChangeSummaryFilePaths,
         cloudApiBaseUrl,
         getCloudAccessToken,
-        e2ee
+        e2ee,
+        attachments
       });
     }
     void run().finally(() => {
@@ -37614,6 +37792,7 @@ function reportGitRepos(getWs, log2) {
 var API_TO_BRIDGE_MESSAGE_TYPES = [
   "auth_token",
   "bridge_identified",
+  "ha",
   "dev_servers_config",
   "server_control",
   "agent_config",
@@ -37642,6 +37821,10 @@ function parseApiToBridgeMessage(data, log2) {
     }
     return null;
   }
+  if (t === "ha") {
+    const s = data.s;
+    if (typeof s !== "number" || !Number.isFinite(s)) return null;
+  }
   return data;
 }
 
@@ -37682,6 +37865,13 @@ var handleBridgeIdentified = (msg, deps) => {
   });
 };
 
+// src/connection/heartbeat/ack.ts
+var handleBridgeHeartbeatAck = (msg, deps) => {
+  const raw = msg.s;
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return;
+  deps.onBridgeHeartbeatAck?.(Math.trunc(raw));
+};
+
 // src/agents/acp/from-bridge/handle-bridge-agent-config.ts
 function handleBridgeAgentConfig(msg, { acpManager }) {
   if (!Array.isArray(msg.agents) || msg.agents.length === 0) return;
@@ -37848,7 +38038,8 @@ function dispatchLocalPrompt(next, deps) {
     ...Array.isArray(pl.sessionChangeSummaryFilePaths) ? { sessionChangeSummaryFilePaths: pl.sessionChangeSummaryFilePaths } : {},
     ...Array.isArray(pl.sessionChangeSummaryFileSnapshots) ? { sessionChangeSummaryFileSnapshots: pl.sessionChangeSummaryFileSnapshots } : {},
     ...typeof pl.agentType === "string" && pl.agentType.trim() ? { agentType: pl.agentType.trim() } : {},
-    ...pl.agentConfig != null && typeof pl.agentConfig === "object" && !Array.isArray(pl.agentConfig) && Object.keys(pl.agentConfig).length > 0 ? { agentConfig: pl.agentConfig } : {}
+    ...pl.agentConfig != null && typeof pl.agentConfig === "object" && !Array.isArray(pl.agentConfig) && Object.keys(pl.agentConfig).length > 0 ? { agentConfig: pl.agentConfig } : {},
+    ...Array.isArray(pl.attachments) && pl.attachments.length > 0 ? { attachments: pl.attachments } : {}
   };
   handleBridgePrompt(msg, deps);
 }
@@ -38115,15 +38306,30 @@ function resolveChangeSummaryPromptForAgent(params) {
 }
 
 // src/agents/acp/from-bridge/handle-bridge-prompt.ts
+function parseBridgeAttachments(msg) {
+  const raw = msg.attachments;
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const x of raw) {
+    if (x === null || typeof x !== "object" || Array.isArray(x)) continue;
+    const o = x;
+    const id = typeof o.attachmentId === "string" ? o.attachmentId.trim() : "";
+    if (!id) continue;
+    const mt = typeof o.mimeType === "string" && o.mimeType.trim() ? o.mimeType.trim() : "application/octet-stream";
+    out.push({ attachmentId: id, mimeType: mt });
+  }
+  return out;
+}
 function handleBridgePrompt(msg, deps) {
   const { getWs, log: log2, acpManager, sessionWorktreeManager } = deps;
   const rawPrompt = msg.prompt;
   const promptText = typeof rawPrompt === "string" ? rawPrompt : rawPrompt != null ? String(rawPrompt) : "";
+  const attachments = parseBridgeAttachments(msg);
   const sessionId = msg.sessionId;
   const runId = typeof msg.runId === "string" ? msg.runId : void 0;
   const promptId = typeof msg.id === "string" ? msg.id : void 0;
   const { sendBridgeMessage, sendResult: sendResult2, sendSessionUpdate } = createBridgePromptSenders(deps, getWs);
-  if (!promptText.trim()) {
+  if (!promptText.trim() && attachments.length === 0) {
     log2(
       `[Bridge service] Prompt ignored: empty or missing prompt text (session ${typeof msg.sessionId === "string" ? msg.sessionId.slice(0, 8) : "\u2014"}\u2026, run ${typeof msg.runId === "string" ? msg.runId.slice(0, 8) : "\u2014"}\u2026).`
     );
@@ -38190,7 +38396,8 @@ function handleBridgePrompt(msg, deps) {
       sessionChangeSummaryFilePaths: pathsForUpload,
       cloudApiBaseUrl: deps.cloudApiBaseUrl,
       getCloudAccessToken: deps.getCloudAccessToken,
-      e2ee: deps.e2ee
+      e2ee: deps.e2ee,
+      ...attachments.length > 0 ? { attachments } : {}
     });
   }
   void sessionWorktreeManager.resolveSessionParentPathForPrompt(sessionId, { isNewSession, sessionParent, sessionParentPath }).then((cwd) => preambleAndPrompt(cwd)).catch((err) => {
@@ -39008,6 +39215,9 @@ function dispatchBridgeMessage(msg, deps) {
     case "bridge_identified":
       handleBridgeIdentified(msg, deps);
       break;
+    case "ha":
+      handleBridgeHeartbeatAck(msg, deps);
+      break;
     case "dev_servers_config":
       handleDevServersConfig(msg, deps);
       break;
@@ -39063,9 +39273,17 @@ function dispatchBridgeMessage(msg, deps) {
 }
 
 // src/routing/handle-bridge-message.ts
+function normalizeInboundBridgeWebSocketJson(data) {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) return data;
+  const o = data;
+  if (o.t === "ha" && typeof o.s === "number" && Number.isFinite(o.s)) {
+    return { type: "ha", s: Math.trunc(o.s) };
+  }
+  return data;
+}
 function handleBridgeMessage(data, deps) {
   if (!deps.getWs()) return;
-  const msg = parseApiToBridgeMessage(data, deps.log);
+  const msg = parseApiToBridgeMessage(normalizeInboundBridgeWebSocketJson(data), deps.log);
   if (!msg) return;
   setImmediate(() => {
     dispatchBridgeMessage(msg, deps);
@@ -39113,7 +39331,8 @@ function createMainBridgeWebSocketLifecycle(params) {
     persistTokens,
     onAuthInvalid,
     e2ee,
-    identifyReportedPaths
+    identifyReportedPaths,
+    bridgeHeartbeat
   } = params;
   let authRefreshInFlight = false;
   function handleOpen() {
@@ -39145,6 +39364,7 @@ function createMainBridgeWebSocketLifecycle(params) {
     }
   }
   function handleClose(code, reason) {
+    bridgeHeartbeat?.stop();
     try {
       const was = state.currentWs;
       state.currentWs = null;
@@ -39179,6 +39399,7 @@ function createMainBridgeWebSocketLifecycle(params) {
       } catch {
       }
     }
+    bridgeHeartbeat?.stop();
     const prev = state.currentWs;
     if (prev) {
       prev.removeAllListeners();
@@ -39270,6 +39491,92 @@ function createMainBridgeWebSocketLifecycle(params) {
   return { connect };
 }
 
+// src/connection/heartbeat/controller.ts
+function meanRttMs(samples) {
+  if (samples.length === 0) return void 0;
+  let sum = 0;
+  for (const x of samples) sum += x;
+  return sum / samples.length;
+}
+function createBridgeHeartbeatController(params) {
+  const { getWs, log: log2 } = params;
+  let interval = null;
+  let seqCursor = -1;
+  let awaitingSeq = null;
+  let sentAtMs = 0;
+  let missed = 0;
+  const rttSamples = [];
+  function clearTimer() {
+    if (interval != null) {
+      clearInterval(interval);
+      interval = null;
+    }
+  }
+  function nextSeq() {
+    seqCursor = seqCursor >= BRIDGE_HEARTBEAT_SEQ_MAX ? 0 : seqCursor + 1;
+    return seqCursor;
+  }
+  function tick() {
+    const ws = getWs();
+    if (!ws || ws.readyState !== wrapper_default.OPEN) return;
+    if (awaitingSeq !== null) {
+      missed++;
+      if (missed >= BRIDGE_HEARTBEAT_MISSED_ACKS_BEFORE_RECONNECT) {
+        try {
+          log2("[Bridge service] Heartbeat missed repeatedly; reconnecting\u2026");
+        } catch {
+        }
+        clearTimer();
+        awaitingSeq = null;
+        missed = 0;
+        rttSamples.length = 0;
+        safeCloseWebSocket(ws);
+        return;
+      }
+    }
+    const seq = nextSeq();
+    const mean = meanRttMs(rttSamples);
+    const payload = mean !== void 0 && Number.isFinite(mean) ? { t: "h", s: seq, m: Math.round(mean) } : { t: "h", s: seq };
+    sendWsMessage(ws, payload);
+    awaitingSeq = seq;
+    sentAtMs = Date.now();
+  }
+  return {
+    start() {
+      clearTimer();
+      awaitingSeq = null;
+      missed = 0;
+      seqCursor = -1;
+      rttSamples.length = 0;
+      interval = setInterval(tick, BRIDGE_APP_HEARTBEAT_INTERVAL_MS);
+    },
+    stop() {
+      clearTimer();
+      awaitingSeq = null;
+      missed = 0;
+      rttSamples.length = 0;
+    },
+    onAck(seq) {
+      if (awaitingSeq === null) return;
+      if (!Number.isFinite(seq)) return;
+      const ack = Math.trunc(seq);
+      const pending = awaitingSeq;
+      if (ack < pending) return;
+      if (ack === pending) {
+        const rtt = Date.now() - sentAtMs;
+        if (Number.isFinite(rtt) && rtt >= 0 && rtt < 6e5) {
+          rttSamples.push(rtt);
+          if (rttSamples.length > BRIDGE_HEARTBEAT_RTT_SAMPLE_MAX) {
+            rttSamples.splice(0, rttSamples.length - BRIDGE_HEARTBEAT_RTT_SAMPLE_MAX);
+          }
+        }
+      }
+      awaitingSeq = null;
+      missed = 0;
+    }
+  };
+}
+
 // src/connection/create-bridge-connection.ts
 async function createBridgeConnection(options) {
   const { apiUrl, workspaceId, justAuthenticated, onAuthInvalid, persistTokens } = options;
@@ -39309,13 +39616,18 @@ async function createBridgeConnection(options) {
   }
   const e2ee = options.e2eCertificate ? createCliE2eeRuntime(options.e2eCertificate) : void 0;
   const devServerManager = new DevServerManager({ getWs, log: logFn, getBridgeRoot, e2ee });
-  const onBridgeIdentified = createOnBridgeIdentified({
+  const bridgeHeartbeat = createBridgeHeartbeatController({ getWs, log: logFn });
+  const baseOnBridgeIdentified = createOnBridgeIdentified({
     devServerManager,
     firehoseServerUrl,
     workspaceId,
     state,
     logFn
   });
+  const onBridgeIdentified = (msg) => {
+    baseOnBridgeIdentified(msg);
+    bridgeHeartbeat.start();
+  };
   const sendLocalSkillsReport = createSendLocalSkillsReport(getWs, logFn);
   const reportAutoDetectedAgents = createReportAutoDetectedAgents(getWs, logFn);
   const messageDeps = {
@@ -39324,6 +39636,9 @@ async function createBridgeConnection(options) {
     acpManager,
     sessionWorktreeManager,
     onBridgeIdentified,
+    onBridgeHeartbeatAck: (seq) => {
+      bridgeHeartbeat.onAck(seq);
+    },
     sendLocalSkillsReport,
     reportAutoDetectedAgents,
     devServerManager,
@@ -39347,13 +39662,15 @@ async function createBridgeConnection(options) {
     persistTokens,
     onAuthInvalid,
     e2ee,
-    identifyReportedPaths
+    identifyReportedPaths,
+    bridgeHeartbeat
   });
   connect();
   const stopFileIndexWatcher = startFileIndexWatcher(getBridgeRoot());
   return {
     close: async () => {
       stopFileIndexWatcher();
+      bridgeHeartbeat.stop();
       await closeBridgeConnection(state, acpManager, devServerManager, logFn);
     }
   };