viyv-browser-mcp 0.10.0 → 0.10.2

package/dist/index.js

@@ -11762,7 +11762,15 @@ var RECONNECT = {
   /** Max delay (ms) */
   MAX_DELAY: 3e4,
   /** Backoff multiplier */
-  MULTIPLIER: 2
+  MULTIPLIER: 2,
+  /** Symmetric jitter ratio applied to each reconnect delay. ±30% spreads synchronized retries. */
+  JITTER_RATIO: 0.3
+};
+var BRIDGE_READINESS = {
+  /** Max time a pre-handshake tool_call waits for `bridge_status { connected:true }` */
+  TIMEOUT_MS: 8e3,
+  /** Max number of tool_calls queued while the bridge client is below `ready` state */
+  PENDING_QUEUE_MAX: 10
 };
 var BRIDGE = {
   /** TCP port for Native Host bridge (TCP server) */
@@ -11803,6 +11811,35 @@ function matchSubscription(sub, event) {
   return matchEventType(sub.eventTypes, event.eventType) && matchUrlPattern(sub.urlPattern, event.url);
 }
 
+// ../shared/dist/util/jitter.js
+function applyJitter(baseMs, ratio, random = Math.random) {
+  if (!Number.isFinite(baseMs) || baseMs < 0)
+    return 0;
+  if (ratio <= 0)
+    return baseMs;
+  const clampedRatio = Math.min(ratio, 1);
+  const offset = (random() * 2 - 1) * clampedRatio * baseMs;
+  const result = baseMs + offset;
+  return Math.max(0, Math.round(result));
+}
+
+// ../shared/dist/util/exit-reason.js
+function shouldBroadcastClosing(reason) {
+  switch (reason) {
+    case "chrome-sigterm":
+    case "sigint":
+      return false;
+    case "all-empty":
+    case "relay-exhausted":
+    case "shutdown-request":
+      return true;
+    default: {
+      const _exhaustive = reason;
+      return _exhaustive;
+    }
+  }
+}
+
 // src/native-host-updater.ts
 import {
   chmodSync,
@@ -11817,7 +11854,7 @@ import { homedir } from "os";
 import { resolve } from "path";
 import { fileURLToPath } from "url";
 var PKG_VERSION = (() => {
-  if (true) return "0.10.0";
+  if (true) return "0.10.2";
   try {
     const here = fileURLToPath(import.meta.url);
     const pkgPath = resolve(here, "..", "..", "package.json");
@@ -12460,7 +12497,7 @@ function startBridge(options) {
       const DRAIN_TIMEOUT = 5e3;
       const drainAndExit = () => {
         if (requestOrigin.size === 0) {
-          gracefulExit("Bridge shutdown requested for version update");
+          gracefulExit("shutdown-request", "version update");
           return;
         }
         process.stderr.write(
@@ -12471,7 +12508,7 @@ function startBridge(options) {
         const check2 = setInterval(() => {
           if (requestOrigin.size === 0 || Date.now() - start > DRAIN_TIMEOUT) {
             clearInterval(check2);
-            gracefulExit("Bridge shutdown requested for version update");
+            gracefulExit("shutdown-request", "version update");
           }
         }, 200);
       };
@@ -12536,6 +12573,7 @@ function startBridge(options) {
     } else if (type === "browser_event") {
       const agentId = message2.agentId;
       if (agentId) broadcastToAgent(agentId, message2);
+    } else if (type === "sw_keepalive") {
     } else {
       process.stderr.write(`${LOG_PREFIX3} Unknown message type from Chrome: ${type}, dropping
 `);
@@ -12565,19 +12603,22 @@ function startBridge(options) {
   let primaryStdinClosed = false;
   const ORPHAN_TIMEOUT = 6e4;
   let orphanTimer = null;
-  function gracefulExit(reason) {
-    process.stderr.write(`${LOG_PREFIX3} ${reason}, exiting
+  function gracefulExit(reason, detail) {
+    const suffix = detail ? ` (${detail})` : "";
+    process.stderr.write(`${LOG_PREFIX3} exiting reason=${reason}${suffix}
 `);
     if (orphanTimer) {
       clearTimeout(orphanTimer);
       orphanTimer = null;
     }
-    const closingMsg = JSON.stringify({ type: "bridge_closing", timestamp: Date.now() });
-    for (const [, conn] of mcpConnections) {
-      try {
-        conn.socket.write(`${closingMsg}
+    if (shouldBroadcastClosing(reason)) {
+      const closingMsg = JSON.stringify({ type: "bridge_closing", timestamp: Date.now() });
+      for (const [, conn] of mcpConnections) {
+        try {
+          conn.socket.write(`${closingMsg}
 `);
-      } catch {
+        } catch {
+        }
       }
     }
     for (const [, conn] of mcpConnections) {
@@ -12603,7 +12644,7 @@ function startBridge(options) {
       return;
     }
     if (chromeConnections.size === 0 && mcpConnections.size === 0) {
-      gracefulExit("No connections remaining");
+      gracefulExit("all-empty", "no connections remaining");
     }
     if (chromeConnections.size === 0 && mcpConnections.size > 0 && !orphanTimer) {
       process.stderr.write(
@@ -12819,8 +12860,8 @@ function startBridge(options) {
       onError: (e) => onError?.(e)
     });
     notifyChromeConnected(false);
-    process.on("SIGINT", () => gracefulExit("SIGINT received"));
-    process.on("SIGTERM", () => gracefulExit("SIGTERM received"));
+    process.on("SIGINT", () => gracefulExit("sigint"));
+    process.on("SIGTERM", () => gracefulExit("chrome-sigterm"));
     process.stdin.on("end", () => {
       process.stderr.write(`${LOG_PREFIX3} Primary Chrome stdin closed
 `);
@@ -12835,7 +12876,6 @@ function startBridge(options) {
 import { randomUUID as randomUUID5 } from "crypto";
 import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync4, statSync, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
 import http from "http";
-import { createConnection as createConnection2 } from "net";
 import { dirname as dirname2 } from "path";
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
@@ -28249,6 +28289,394 @@ var StreamableHTTPServerTransport = class {
   }
 };
 
+// src/native-host/bridge-client/index.ts
+import { createConnection as createConnection2 } from "net";
+
+// src/native-host/bridge-client/connection-state.ts
+function transition(state, event) {
+  if (event.kind === "stop") return "disconnected";
+  switch (state) {
+    case "disconnected":
+      if (event.kind === "start") return "connecting";
+      return state;
+    case "connecting":
+      if (event.kind === "socket-connected") return "handshaking";
+      if (event.kind === "socket-closed") return "disconnected";
+      return state;
+    case "handshaking":
+      if (event.kind === "bridge-status-true") return "ready";
+      if (event.kind === "bridge-status-false") return "handshaking";
+      if (event.kind === "bridge-closing") return "draining";
+      if (event.kind === "socket-closed") return "disconnected";
+      return state;
+    case "ready":
+      if (event.kind === "bridge-status-false") return "handshaking";
+      if (event.kind === "bridge-closing") return "draining";
+      if (event.kind === "socket-closed") return "disconnected";
+      return state;
+    case "draining":
+      if (event.kind === "socket-closed") return "disconnected";
+      return state;
+    default: {
+      const _exhaustive = state;
+      return _exhaustive;
+    }
+  }
+}
+function isReady(state) {
+  return state === "ready";
+}
+
+// src/native-host/bridge-client/pending-queue.ts
+var PendingQueue = class {
+  constructor(max, ttlMs, timers) {
+    this.max = max;
+    this.ttlMs = ttlMs;
+    this.timers = timers;
+    if (max < 1) throw new Error("PendingQueue max must be >= 1");
+    if (ttlMs < 0) throw new Error("PendingQueue ttlMs must be >= 0");
+  }
+  entries = [];
+  /** Try to enqueue. Returns `true` on success, `false` when rejected (onReject already fired). */
+  enqueue(entry) {
+    if (this.entries.length >= this.max) {
+      entry.onReject("queue-full");
+      return false;
+    }
+    const stored = { ...entry, timer: null };
+    stored.timer = this.timers.setTimer(() => this.expire(stored), this.ttlMs);
+    this.entries.push(stored);
+    return true;
+  }
+  /** Flush every queued entry in FIFO order. */
+  flushAll() {
+    const snapshot = this.entries.splice(0, this.entries.length);
+    for (const entry of snapshot) {
+      this.timers.clearTimer(entry.timer);
+      entry.onFlush(entry.payload);
+    }
+  }
+  /** Reject every queued entry with the given reason. Used on `stop()`. */
+  rejectAll(reason) {
+    const snapshot = this.entries.splice(0, this.entries.length);
+    for (const entry of snapshot) {
+      this.timers.clearTimer(entry.timer);
+      entry.onReject(reason);
+    }
+  }
+  size() {
+    return this.entries.length;
+  }
+  expire(entry) {
+    const idx = this.entries.indexOf(entry);
+    if (idx === -1) return;
+    this.entries.splice(idx, 1);
+    entry.onReject("timeout");
+  }
+};
+
+// src/native-host/bridge-client/index.ts
+var LOG_PREFIX4 = "[viyv-browser:mcp:bridge]";
+var METRIC_PREFIX = "[viyv-browser:mcp:metric]";
+var LINE_TERMINATOR = "\n";
+var BRIDGE_RECONNECT_CAP_MS = 3e3;
+var defaultTimers = {
+  setTimer: (fn, ms) => setTimeout(fn, ms),
+  clearTimer: (h) => clearTimeout(h)
+};
+var defaultSchedule = (fn, ms) => {
+  const h = setTimeout(fn, ms);
+  return () => clearTimeout(h);
+};
+var BridgeClient = class {
+  constructor(options) {
+    this.options = options;
+    this.log = options.log ?? ((line) => process.stderr.write(`${line}
+`));
+    this.metric = options.metric ?? ((line) => process.stderr.write(`${line}
+`));
+    this.now = options.now ?? (() => Date.now());
+    this.schedule = options.schedule ?? defaultSchedule;
+    this.random = options.random ?? Math.random;
+    this.queue = new PendingQueue(
+      BRIDGE_READINESS.PENDING_QUEUE_MAX,
+      BRIDGE_READINESS.TIMEOUT_MS,
+      options.timers ?? defaultTimers
+    );
+  }
+  state = "disconnected";
+  socket = null;
+  reconnectAttempt = 0;
+  cancelReconnect = null;
+  messageHandlers = /* @__PURE__ */ new Set();
+  stateHandlers = /* @__PURE__ */ new Set();
+  queue;
+  /** ms since epoch when the current handshake started; `null` when not measuring. */
+  handshakeStartMs = null;
+  started = false;
+  log;
+  metric;
+  now;
+  schedule;
+  random;
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.apply({ kind: "start" });
+    this.connect();
+  }
+  stop() {
+    this.started = false;
+    this.cancelReconnect?.();
+    this.cancelReconnect = null;
+    this.queue.rejectAll("stopped");
+    if (this.socket && !this.socket.destroyed) {
+      this.socket.destroy();
+    }
+    this.socket = null;
+    this.apply({ kind: "stop" });
+  }
+  /**
+   * Drop the current socket and reconnect immediately. Used by switch_browser
+   * to pivot to a fresh Chrome. Pending tool_calls are drained with the
+   * SWITCH_IN_PROGRESS error by the caller before this is invoked.
+   */
+  forceReconnect() {
+    if (this.socket && !this.socket.destroyed) {
+      this.socket.destroy();
+    }
+    this.socket = null;
+    this.apply({ kind: "socket-closed" });
+    if (this.started) {
+      this.reconnectAttempt = 0;
+      this.scheduleReconnect();
+    }
+  }
+  getState() {
+    return this.state;
+  }
+  isReady() {
+    return isReady(this.state);
+  }
+  /**
+   * Return the socket when it is TCP-live (handshaking, ready, or draining).
+   * Ancillary writes like session_init / session_close tolerate writes during
+   * handshake — the bridge buffers them until Chrome is reachable.
+   * Returns null when the socket is not safe to write to.
+   */
+  getSocket() {
+    if (!this.socket || this.socket.destroyed) return null;
+    if (this.state === "handshaking" || this.state === "ready" || this.state === "draining") {
+      return this.socket;
+    }
+    return null;
+  }
+  onMessage(fn) {
+    this.messageHandlers.add(fn);
+    return () => this.messageHandlers.delete(fn);
+  }
+  onStateChange(fn) {
+    this.stateHandlers.add(fn);
+    return () => this.stateHandlers.delete(fn);
+  }
+  /**
+   * Send a tool_call line. If the bridge is `ready`, writes immediately.
+   * Otherwise enqueues until readiness, failing with `queue-full` if capacity
+   * is exhausted or `timeout` if the handshake takes too long.
+   */
+  enqueueToolCall(line) {
+    return new Promise((resolve3, reject) => {
+      if (this.state === "ready" && this.socket && !this.socket.destroyed) {
+        try {
+          this.socket.write(line.endsWith(LINE_TERMINATOR) ? line : line + LINE_TERMINATOR);
+          resolve3();
+        } catch (err) {
+          reject({ reason: "write-failed", detail: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+      }
+      const enqueued = this.queue.enqueue({
+        payload: {
+          line: line.endsWith(LINE_TERMINATOR) ? line : line + LINE_TERMINATOR,
+          resolve: resolve3,
+          reject
+        },
+        onFlush: (entry) => {
+          if (this.socket && !this.socket.destroyed) {
+            try {
+              this.socket.write(entry.line);
+              entry.resolve();
+            } catch (err) {
+              entry.reject({
+                reason: "write-failed",
+                detail: err instanceof Error ? err.message : String(err)
+              });
+            }
+          } else {
+            entry.reject({ reason: "write-failed", detail: "socket unavailable at flush" });
+          }
+        },
+        onReject: (reason) => {
+          reject({ reason });
+        }
+      });
+      if (enqueued) {
+        this.emitMetric("queue.enqueue", { depth: this.queue.size() });
+      }
+    });
+  }
+  connect() {
+    if (!this.started) return;
+    this.cancelReconnect = null;
+    this.apply({ kind: "start" });
+    if (this.state !== "connecting") {
+      this.forceState("connecting");
+    }
+    const sock = createConnection2({ host: this.options.host, port: this.options.port });
+    this.socket = sock;
+    sock.on("connect", () => {
+      this.handshakeStartMs = this.now();
+      sock.setKeepAlive(true, 3e4);
+      this.reconnectAttempt = 0;
+      this.apply({ kind: "socket-connected" });
+    });
+    sock.on("error", (err) => {
+      this.log(`${LOG_PREFIX4} socket error: ${err.message}`);
+    });
+    sock.on("close", () => {
+      const wasReady = this.state === "ready";
+      if (this.socket === sock) this.socket = null;
+      this.apply({ kind: "socket-closed" });
+      if (wasReady) this.log(`${LOG_PREFIX4} bridge disconnected`);
+      if (this.started) this.scheduleReconnect();
+    });
+    let lineBuffer = "";
+    sock.on("data", (data) => {
+      lineBuffer += data.toString("utf-8");
+      const lines = lineBuffer.split(LINE_TERMINATOR);
+      lineBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line) continue;
+        try {
+          const parsed = JSON.parse(line);
+          this.handleIncoming(parsed);
+        } catch (err) {
+          this.log(
+            `${LOG_PREFIX4} parse error: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+    });
+  }
+  handleIncoming(msg) {
+    if (msg && typeof msg === "object") {
+      const type = msg.type;
+      if (type === "bridge_closing") {
+        this.log(`${LOG_PREFIX4} received bridge_closing, will reconnect`);
+        this.apply({ kind: "bridge-closing" });
+        if (this.socket && !this.socket.destroyed) this.socket.destroy();
+        return;
+      }
+      if (type === "bridge_status") {
+        const connected = msg.connected === true;
+        this.apply({ kind: connected ? "bridge-status-true" : "bridge-status-false" });
+      }
+    }
+    for (const h of this.messageHandlers) {
+      try {
+        h(msg);
+      } catch (err) {
+        this.log(
+          `${LOG_PREFIX4} handler threw: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  scheduleReconnect() {
+    if (!this.started) return;
+    if (this.cancelReconnect) return;
+    this.reconnectAttempt++;
+    const base = Math.min(
+      RECONNECT.INITIAL_DELAY * RECONNECT.MULTIPLIER ** (this.reconnectAttempt - 1),
+      BRIDGE_RECONNECT_CAP_MS
+    );
+    const delay = applyJitter(base, RECONNECT.JITTER_RATIO, this.random);
+    this.emitMetric("reconnect.scheduled", { attempt: this.reconnectAttempt, delayMs: delay });
+    this.log(`${LOG_PREFIX4} reconnect in ${delay}ms (attempt ${this.reconnectAttempt})`);
+    this.cancelReconnect = this.schedule(() => {
+      this.cancelReconnect = null;
+      this.connect();
+    }, delay);
+  }
+  apply(event) {
+    const next = transition(this.state, event);
+    if (next === this.state) return;
+    const prev = this.state;
+    this.state = next;
+    this.emitMetric("state.transition", { from: prev, to: next, event: event.kind });
+    if (next === "ready") {
+      if (this.handshakeStartMs !== null) {
+        this.emitMetric("handshake.complete", {
+          elapsedMs: this.now() - this.handshakeStartMs
+        });
+        this.handshakeStartMs = null;
+      }
+      this.queue.flushAll();
+    }
+    for (const h of this.stateHandlers) {
+      try {
+        h(next, prev);
+      } catch (err) {
+        this.log(
+          `${LOG_PREFIX4} state handler threw: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  /** Force a specific state (used only for recovering from impossible transitions). */
+  forceState(to) {
+    if (this.state === to) return;
+    const prev = this.state;
+    this.state = to;
+    this.emitMetric("state.force", { from: prev, to });
+    for (const h of this.stateHandlers) {
+      try {
+        h(to, prev);
+      } catch {
+      }
+    }
+  }
+  emitMetric(name, fields) {
+    this.metric(
+      `${METRIC_PREFIX} ${name} ${Object.entries(fields).map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`).join(" ")}`
+    );
+  }
+};
+function toolCallRejectionToErrorCode(rej) {
+  switch (rej.reason) {
+    case "queue-full":
+      return {
+        code: "EXTENSION_NOT_CONNECTED",
+        message: "Bridge readiness queue is full; try again shortly"
+      };
+    case "timeout":
+      return {
+        code: "EXTENSION_NOT_CONNECTED",
+        message: "Timed out waiting for bridge readiness"
+      };
+    case "stopped":
+      return {
+        code: "EXTENSION_NOT_CONNECTED",
+        message: "Bridge client was stopped"
+      };
+    case "write-failed":
+      return {
+        code: "EXTENSION_NOT_CONNECTED",
+        message: `Socket write failed: ${rej.detail}`
+      };
+  }
+}
+
 // ../shared/dist/bearer-equals.js
 import { timingSafeEqual } from "crypto";
 function bearerEquals(header, expectedToken) {
@@ -31488,11 +31916,12 @@ abort:
 
 Supported scenario step types: navigate, action, fetch, wait, loop. Loop variable sources: static, previous_fetch, target_options (max nesting 3, max iterations 500, cartesian product across variables).
 
-HttpFetch groundwork (F1 \u2014 executor support lands in F2):
+HttpFetch runtime (F2):
 - Fetch definitions may carry type_name='http_fetch' + http_config instead of DOM extraction fields. Loop-merged params resolve {{var}} in url / body_template with per-value URL-encoding.
 - extractor_code (when set) is eval-equivalent in the page MAIN world \u2014 bundles must originate from the trusted authoring pipeline gated by MCP JWT auth. Extraction precedence: extractor_code > selector > raw responseText.
+- Response shape: results[result_key] = { rows: unknown[] } \u2014 extractor array, selector string[], or [responseText] in raw fallback. Scraper should consume result.data.rows.
+- HTTP 4xx/5xx are forwarded as ok:true with httpStatus populated (caller decides). Network / extractor failures surface as ok:false with prefixed error strings ('fetch failed: ...' / 'extractor threw: ...' / 'scripting failed: ...' / 'async extractor not supported in v1').
 - sm_probe_inline automatically skips http_fetch (no DOM locators to probe).
-- Calling an http_fetch at runtime in this release returns an error; runtime dispatch lands in F2.
 - ScenarioFetchStep.result_key_mode ('overwrite' | 'append' | 'concat', default 'overwrite') controls how results[result_key] accumulates across loop iterations. Runtime dispatch lands in F3; pre-F3 all modes behave as 'overwrite'.
 
 Full reference: docs/inline-sm-execution.md`;
@@ -33774,8 +34203,11 @@ function computeToolTimeout(tool, input) {
 
 // src/server.ts
 var pendingRequests = /* @__PURE__ */ new Map();
-var extensionSocket = null;
+var bridgeClient = null;
 var bridgeUpdateInfo = null;
+function getBridgeSocket() {
+  return bridgeClient?.getSocket() ?? null;
+}
 function readJwtConfigFromEnv() {
   const alg = process.env.VIYV_JWT_ALG ?? "none";
   return {
@@ -33843,8 +34275,9 @@ function bridgeRegisterAgent(agentId, sessionId) {
     bridgeAgentRefs.set(agentId, set);
   }
   set.add(sessionId);
-  if (isFirst && extensionSocket && !extensionSocket.destroyed) {
-    sendSessionInit(extensionSocket, agentId);
+  if (isFirst) {
+    const sock = getBridgeSocket();
+    if (sock) sendSessionInit(sock, agentId);
   }
 }
 function bridgeUnregisterAgent(agentId, sessionId) {
@@ -33853,8 +34286,9 @@ function bridgeUnregisterAgent(agentId, sessionId) {
   set.delete(sessionId);
   if (set.size === 0) {
     bridgeAgentRefs.delete(agentId);
-    if (extensionSocket && !extensionSocket.destroyed) {
-      extensionSocket.write(
+    const sock = getBridgeSocket();
+    if (sock) {
+      sock.write(
         `${JSON.stringify({
           id: randomUUID5(),
           type: "session_close",
@@ -34005,7 +34439,8 @@ async function startMcpServer(agentName, options) {
     setDefaultAgentId(agentName);
   }
   configuredChromeProfile = options?.chromeProfile;
-  connectToBridge();
+  bridgeClient = initBridgeClient();
+  bridgeClient.start();
   if (options?.transport === "sse") {
     const sessions2 = /* @__PURE__ */ new Map();
     const httpServer = http.createServer();
@@ -34043,7 +34478,7 @@ async function startMcpServer(agentName, options) {
       }
       httpServer.close(() => {
       });
-      extensionSocket?.destroy();
+      bridgeClient?.stop();
       process.exit(0);
     };
     process.on("SIGINT", () => {
@@ -34118,7 +34553,7 @@ async function startMcpServer(agentName, options) {
       }
       httpServer.close(() => {
       });
-      extensionSocket?.destroy();
+      bridgeClient?.stop();
       process.exit(0);
     };
     process.on("SIGINT", () => {
@@ -34137,13 +34572,13 @@ async function startMcpServer(agentName, options) {
     );
     process.stdin.on("end", () => {
       process.stderr.write("[viyv-browser:mcp] stdin closed, shutting down\n");
-      extensionSocket?.destroy();
+      bridgeClient?.stop();
       process.exit(0);
     });
     process.on("SIGINT", () => process.exit(0));
     process.on("SIGTERM", () => process.exit(0));
     process.on("exit", () => {
-      extensionSocket?.destroy();
+      bridgeClient?.stop();
     });
   }
 }
@@ -34326,65 +34761,6 @@ function parseJsonBody(req) {
     });
   });
 }
-function connectToBridge() {
-  let retryCount = 0;
-  let bridgeClosingReceived = false;
-  let cleanup = null;
-  function connect() {
-    bridgeClosingReceived = false;
-    const socket = createConnection2({ port: BRIDGE.TCP_PORT, host: BRIDGE.TCP_HOST });
-    socket.on("connect", () => {
-      retryCount = 0;
-      cleanup = setupBridgeConnection(socket, () => {
-        bridgeClosingReceived = true;
-      });
-    });
-    socket.on("error", () => {
-    });
-    socket.on("close", () => {
-      const wasConnected = cleanup !== null;
-      cleanup?.();
-      cleanup = null;
-      if (wasConnected) {
-        process.stderr.write("[viyv-browser:mcp] Bridge disconnected\n");
-      }
-      if (extensionSocket === socket) {
-        extensionSocket = null;
-        setExtensionConnected(false);
-      }
-      for (const [id, pending] of pendingRequests) {
-        clearTimeout(pending.timer);
-        pendingRequests.delete(id);
-        pending.resolve({
-          error: {
-            code: "EXTENSION_NOT_CONNECTED",
-            message: "Bridge disconnected while request was pending"
-          }
-        });
-      }
-      scheduleReconnect();
-    });
-  }
-  function scheduleReconnect() {
-    if (bridgeClosingReceived) {
-      retryCount = 0;
-      setTimeout(connect, RECONNECT.INITIAL_DELAY);
-      return;
-    }
-    retryCount++;
-    const BRIDGE_RECONNECT_CAP = 3e3;
-    const delay = Math.min(
-      RECONNECT.INITIAL_DELAY * RECONNECT.MULTIPLIER ** (retryCount - 1),
-      BRIDGE_RECONNECT_CAP
-    );
-    process.stderr.write(
-      `[viyv-browser:mcp] Reconnecting to bridge in ${delay}ms (attempt ${retryCount})
-`
-    );
-    setTimeout(connect, delay);
-  }
-  connect();
-}
 function sendSessionInit(socket, agentId) {
   const initMsg = {
     id: randomUUID5(),
@@ -34399,65 +34775,79 @@ function sendSessionInit(socket, agentId) {
   socket.write(`${JSON.stringify(initMsg)}
 `);
 }
-function setupBridgeConnection(socket, onBridgeClosing) {
-  process.stderr.write(
-    `[viyv-browser:mcp] Connected to bridge at ${BRIDGE.TCP_HOST}:${BRIDGE.TCP_PORT}
+function initBridgeClient() {
+  const client = new BridgeClient({ host: BRIDGE.TCP_HOST, port: BRIDGE.TCP_PORT });
+  let heartbeatInterval = null;
+  client.onMessage((rawMsg) => {
+    if (!rawMsg || typeof rawMsg !== "object") return;
+    let parsed = rawMsg;
+    if (parsed.type === "compressed" && typeof parsed.data === "string") {
+      try {
+        const decompressed = decompressPayload(parsed.data, true);
+        parsed = JSON.parse(decompressed);
+      } catch (err) {
+        process.stderr.write(
+          `[viyv-browser:mcp] Decompress error: ${err instanceof Error ? err.message : String(err)}
 `
-  );
-  extensionSocket = socket;
-  socket.setKeepAlive(true, 3e4);
-  setExtensionConnected(true);
-  const agentId = getDefaultAgentId();
-  sendSessionInit(socket, agentId);
-  bridgeResyncAgents(socket);
-  const heartbeatInterval = setInterval(() => {
-    if (socket.destroyed) {
-      clearInterval(heartbeatInterval);
-      return;
+        );
+        return;
+      }
     }
-    socket.write(
-      `${JSON.stringify({
-        id: randomUUID5(),
-        type: "session_heartbeat",
-        agentId,
-        timestamp: Date.now()
-      })}
+    handleExtensionMessage(parsed);
+  });
+  client.onStateChange((next, prev) => {
+    if (next === "ready" && prev !== "ready") {
+      process.stderr.write(
+        `[viyv-browser:mcp] Connected to bridge at ${BRIDGE.TCP_HOST}:${BRIDGE.TCP_PORT}
 `
-    );
-  }, TIMEOUTS.HEARTBEAT);
-  let lineBuffer = "";
-  socket.on("data", (data) => {
-    lineBuffer += data.toString("utf-8");
-    const lines = lineBuffer.split("\n");
-    lineBuffer = lines.pop() ?? "";
-    for (const line of lines) {
-      if (!line) continue;
-      try {
-        let parsed = JSON.parse(line);
-        if (parsed.type === "bridge_closing") {
-          process.stderr.write("[viyv-browser:mcp] Received bridge_closing, will reconnect\n");
-          onBridgeClosing();
-          socket.destroy();
-          return;
-        }
-        if (parsed.type === "compressed" && typeof parsed.data === "string") {
-          const decompressed = decompressPayload(parsed.data, true);
-          parsed = JSON.parse(decompressed);
-        }
-        handleExtensionMessage(parsed);
-      } catch (error2) {
-        process.stderr.write(`[viyv-browser:mcp] Parse error: ${error2.message}
-`);
+      );
+      setExtensionConnected(true);
+      const sock = client.getSocket();
+      if (sock) {
+        const agentId = getDefaultAgentId();
+        sendSessionInit(sock, agentId);
+        bridgeResyncAgents(sock);
+        if (heartbeatInterval) clearInterval(heartbeatInterval);
+        heartbeatInterval = setInterval(() => {
+          const s = client.getSocket();
+          if (!s || s.destroyed) {
+            if (heartbeatInterval) {
+              clearInterval(heartbeatInterval);
+              heartbeatInterval = null;
+            }
+            return;
+          }
+          s.write(
+            `${JSON.stringify({
+              id: randomUUID5(),
+              type: "session_heartbeat",
+              agentId,
+              timestamp: Date.now()
+            })}
+`
+          );
+        }, TIMEOUTS.HEARTBEAT);
+      }
+    }
+    if (prev === "ready" && next !== "ready") {
+      setExtensionConnected(false);
+      if (heartbeatInterval) {
+        clearInterval(heartbeatInterval);
+        heartbeatInterval = null;
+      }
+      for (const [id, pending] of pendingRequests) {
+        clearTimeout(pending.timer);
+        pendingRequests.delete(id);
+        pending.resolve({
+          error: {
+            code: "EXTENSION_NOT_CONNECTED",
+            message: "Bridge disconnected while request was pending"
+          }
+        });
       }
     }
   });
-  socket.on("error", (error2) => {
-    process.stderr.write(`[viyv-browser:mcp] Bridge socket error: ${error2.message}
-`);
-  });
-  return () => {
-    clearInterval(heartbeatInterval);
-  };
+  return client;
 }
 function handleExtensionMessage(message2) {
   if (!message2 || typeof message2 !== "object") return;
@@ -34515,9 +34905,10 @@ function handleExtensionMessage(message2) {
       } else {
         setExtensionConnected(true);
         recordHeartbeat();
-        if (extensionSocket && !extensionSocket.destroyed && listSessions().length === 0) {
+        const sockForReinit = getBridgeSocket();
+        if (sockForReinit && listSessions().length === 0) {
           const agentId = getDefaultAgentId();
-          sendSessionInit(extensionSocket, agentId);
+          sendSessionInit(sockForReinit, agentId);
           process.stderr.write(
             `[viyv-browser:mcp] Session re-initialized after Chrome reconnect: ${agentId}
 `
@@ -34533,8 +34924,9 @@ function handleExtensionMessage(message2) {
 `
       );
       bridgeUpdateInfo = { from: bridgeVersion, to: serverVersion };
-      if (extensionSocket && !extensionSocket.destroyed) {
-        extensionSocket.write(
+      const shutdownSock = getBridgeSocket();
+      if (shutdownSock) {
+        shutdownSock.write(
           `${JSON.stringify({ type: "bridge_shutdown_request", timestamp: Date.now() })}
 `
         );
@@ -34664,7 +35056,7 @@ async function callExtensionTool(tool, input) {
   }
   if (tool === "browser_health") {
     const health = getHealthStatus();
-    if (!health.extensionConnected || !extensionSocket || extensionSocket.destroyed) {
+    if (!health.extensionConnected || !getBridgeSocket()) {
       return {
         content: [{ type: "text", text: JSON.stringify(health) }]
       };
@@ -34748,7 +35140,7 @@ async function callExtensionTool(tool, input) {
       }
     }
   }
-  if (!extensionSocket || extensionSocket.destroyed) {
+  if (!bridgeClient) {
     return {
       content: [
         {
@@ -34756,7 +35148,7 @@ async function callExtensionTool(tool, input) {
           text: JSON.stringify({
             error: {
               code: "EXTENSION_NOT_CONNECTED",
-              message: "Chrome Extension is not connected. Please open Chrome and click the Viyv Browser extension icon."
+              message: "Bridge client not initialized"
             }
           })
         }
@@ -34766,31 +35158,10 @@ async function callExtensionTool(tool, input) {
   const requestId = randomUUID5();
   const agentId = getCurrentAgentId(getDefaultAgentId);
   touchSession(agentId);
-  const sock = extensionSocket;
+  const client = bridgeClient;
   const toolTimeout = computeToolTimeout(tool, input);
   return new Promise((resolve3) => {
-    const onError = () => {
-      const pending = pendingRequests.get(requestId);
-      if (pending) {
-        clearTimeout(pending.timer);
-        pendingRequests.delete(requestId);
-        resolve3({
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error: {
-                  code: "EXTENSION_NOT_CONNECTED",
-                  message: "Socket write failed"
-                }
-              })
-            }
-          ]
-        });
-      }
-    };
     const removeErrorListener = () => {
-      sock.removeListener("error", onError);
     };
     const timer = setTimeout(() => {
       pendingRequests.delete(requestId);
@@ -34936,13 +35307,17 @@ async function callExtensionTool(tool, input) {
       `[viyv-browser:mcp] tool_call id=${requestId} agent=${agentId} pid=${ctxLog?.claims?.pid ?? chromeProfile ?? "-"} tool=${tool}
 `
     );
-    const written = sock.write(`${JSON.stringify(request)}
-`);
-    if (!written) {
-      sock.once("drain", () => {
+    client.enqueueToolCall(`${JSON.stringify(request)}
+`).catch((rej) => {
+      const pending = pendingRequests.get(requestId);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      pendingRequests.delete(requestId);
+      const { code, message: message2 } = toolCallRejectionToErrorCode(rej);
+      resolve3({
+        content: [{ type: "text", text: JSON.stringify({ error: { code, message: message2 } }) }]
       });
-    }
-    sock.once("error", onError);
+    });
   });
 }
 async function handleSwitchBrowser() {
@@ -34957,16 +35332,15 @@ async function handleSwitchBrowser() {
       }
     });
   }
-  if (extensionSocket && !extensionSocket.destroyed) {
+  if (bridgeClient) {
     process.stderr.write("[viyv-browser:mcp] switch_browser: closing current connection\n");
-    extensionSocket.destroy();
-    extensionSocket = null;
+    bridgeClient.forceReconnect();
     setExtensionConnected(false);
   }
   process.stderr.write("[viyv-browser:mcp] switch_browser: waiting for bridge reconnection...\n");
   return new Promise((resolve3) => {
     const checkInterval = setInterval(() => {
-      if (extensionSocket && !extensionSocket.destroyed && isExtensionConnected()) {
+      if (bridgeClient?.isReady() && isExtensionConnected()) {
         clearInterval(checkInterval);
         clearTimeout(timer);
         resolve3({