@btraut/browser-bridge 0.12.1 → 0.13.1

package/extension/dist/background.js

@@ -1,3 +1,6 @@
+// packages/shared/src/contract-version.ts
+var DRIVE_WS_PROTOCOL_VERSION = "2026-02-17.1";
+
 // packages/extension/src/error-sanitizer.ts
 var TRAILING_PUNCTUATION_RE = /[.,;:!?]+$/;
 var stripTrailingPunctuation = (value) => {
@@ -97,7 +100,9 @@ var SITE_ALLOWLIST_KEY = "siteAllowlist";
 var PERMISSION_PROMPT_WAIT_MS_KEY = "permissionPromptWaitMs";
 var DEFAULT_PERMISSION_PROMPT_WAIT_MS = 3e4;
 var SITE_PERMISSIONS_MODE_KEY = "sitePermissionsMode";
+var DEBUGGER_CAPABILITY_ENABLED_KEY = "debuggerCapabilityEnabled";
 var DEFAULT_SITE_PERMISSIONS_MODE = "granular";
+var DEFAULT_DEBUGGER_CAPABILITY_ENABLED = false;
 var siteKeyFromUrl = (rawUrl) => {
   if (!rawUrl || typeof rawUrl !== "string") {
     return null;
@@ -199,6 +204,27 @@ var readPermissionPromptWaitMs = async () => {
     );
   });
 };
+var readDebuggerCapabilityEnabled = async () => {
+  return await new Promise((resolve) => {
+    chrome.storage.local.get(
+      [DEBUGGER_CAPABILITY_ENABLED_KEY],
+      (result) => {
+        const raw = result?.[DEBUGGER_CAPABILITY_ENABLED_KEY];
+        if (typeof raw === "boolean") {
+          resolve(raw);
+          return;
+        }
+        try {
+          chrome.storage.local.set({
+            [DEBUGGER_CAPABILITY_ENABLED_KEY]: DEFAULT_DEBUGGER_CAPABILITY_ENABLED
+          });
+        } catch {
+        }
+        resolve(DEFAULT_DEBUGGER_CAPABILITY_ENABLED);
+      }
+    );
+  });
+};
 var isSiteAllowed = async (siteKey) => {
   const key = normalizeSiteKey(siteKey);
   const allowlist = await readAllowlistRaw();
@@ -410,6 +436,54 @@ var PermissionPromptController = class {
   }
 };
 
+// packages/extension/src/drive-reliability.ts
+var TRANSIENT_TAB_CHANNEL_ERROR_PATTERNS = [
+  "receiving end does not exist",
+  "message channel closed before a response was received",
+  "the message port closed before a response was received",
+  "extension port is moved into back/forward cache"
+];
+var TAB_CHANNEL_RETRY_DELAYS_MS = [120, 200, 320, 500, 750, 1e3, 1200];
+var normalizePathname = (pathname) => {
+  if (pathname.length === 0) {
+    return "/";
+  }
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    return pathname.slice(0, -1);
+  }
+  return pathname;
+};
+var isTransientTabChannelError = (message) => {
+  if (typeof message !== "string") {
+    return false;
+  }
+  const normalized = message.toLowerCase();
+  return TRANSIENT_TAB_CHANNEL_ERROR_PATTERNS.some(
+    (pattern) => normalized.includes(pattern)
+  );
+};
+var getTabChannelRetryDelayMs = (attempt) => {
+  if (!Number.isInteger(attempt) || attempt < 1) {
+    return void 0;
+  }
+  return TAB_CHANNEL_RETRY_DELAYS_MS[attempt - 1];
+};
+var isLikelyNavigationCommitted = (requestedUrl, tabUrl) => {
+  if (typeof requestedUrl !== "string" || typeof tabUrl !== "string") {
+    return false;
+  }
+  if (requestedUrl === tabUrl) {
+    return true;
+  }
+  try {
+    const requested = new URL(requestedUrl);
+    const actual = new URL(tabUrl);
+    return requested.origin === actual.origin && normalizePathname(requested.pathname) === normalizePathname(actual.pathname) && requested.search === actual.search;
+  } catch {
+    return requestedUrl === tabUrl;
+  }
+};
+
 // packages/extension/src/connection-state.ts
 var toIso = (ms) => new Date(ms).toISOString();
 var ConnectionStateTracker = class {
@@ -501,9 +575,62 @@ var HISTORY_POST_NAV_DOM_GRACE_TIMEOUT_MS = 2e3;
 var AGENT_TAB_ID_KEY = "agentTabId";
 var AGENT_TAB_GROUP_TITLE = "Browser Bridge";
 var AGENT_TAB_BOOTSTRAP_PATH = "agent-tab.html";
+var AGENT_TAB_FAVICON_ASSET_PATH = "assets/icons/icon-32.png";
+var AGENT_TAB_BRANDING_ACTION = "drive.agent_tab_branding";
+var AGENT_TAB_GROUP_RETRY_DELAYS_MS = [0, 120, 300];
+var AGENT_TAB_BRANDING_TIMEOUT_MS = 1500;
+var BASE_NEGOTIATED_CAPABILITIES = Object.freeze({
+  "drive.navigate": true,
+  "drive.go_back": true,
+  "drive.go_forward": true,
+  "drive.click": true,
+  "drive.hover": true,
+  "drive.select": true,
+  "drive.type": true,
+  "drive.fill_form": true,
+  "drive.drag": true,
+  "drive.handle_dialog": true,
+  "drive.key": true,
+  "drive.key_press": true,
+  "drive.scroll": true,
+  "drive.screenshot": true,
+  "drive.wait_for": true,
+  "drive.tab_list": true,
+  "drive.tab_activate": true,
+  "drive.tab_close": true,
+  "drive.ping": true
+});
+var DEBUGGER_CAPABILITY_ACTIONS = [
+  "debugger.attach",
+  "debugger.detach",
+  "debugger.command"
+];
+var buildNegotiatedCapabilities = (debuggerCapabilityEnabled) => {
+  const capabilities = {
+    ...BASE_NEGOTIATED_CAPABILITIES
+  };
+  for (const action of DEBUGGER_CAPABILITY_ACTIONS) {
+    capabilities[action] = debuggerCapabilityEnabled;
+  }
+  return capabilities;
+};
+var debuggerCapabilityDisabledError = () => {
+  return {
+    code: "ATTACH_DENIED",
+    message: "Debugger capability is disabled. Enable debugger-based inspect in extension options and retry.",
+    retryable: false,
+    details: {
+      reason: "debugger_capability_disabled",
+      next_step: "Open Browser Bridge extension options, enable debugger-based inspect, then retry."
+    }
+  };
+};
 var getAgentTabBootstrapUrl = () => {
   return typeof chrome.runtime?.getURL === "function" ? chrome.runtime.getURL(AGENT_TAB_BOOTSTRAP_PATH) : AGENT_TAB_BOOTSTRAP_PATH;
 };
+var getAgentTabFaviconUrl = () => {
+  return typeof chrome.runtime?.getURL === "function" ? chrome.runtime.getURL(AGENT_TAB_FAVICON_ASSET_PATH) : AGENT_TAB_FAVICON_ASSET_PATH;
+};
 var nowIso = () => (/* @__PURE__ */ new Date()).toISOString();
 var makeEventId = /* @__PURE__ */ (() => {
   let counter = 0;
@@ -872,23 +999,38 @@ var ensureAgentTabGroup = async (tabId, windowId) => {
   if (!chrome.tabGroups || typeof chrome.tabGroups.update !== "function") {
     return;
   }
-  try {
-    const groupId = await wrapChromeCallback(
-      (callback) => chrome.tabs.group(
-        { tabIds: tabId, createProperties: { windowId } },
-        callback
-      )
-    );
-    await wrapChromeVoid(
-      (callback) => chrome.tabGroups.update(
-        groupId,
-        { title: AGENT_TAB_GROUP_TITLE },
-        () => callback()
-      )
-    );
-  } catch (error) {
-    console.debug("Failed to create/update agent tab group.", error);
+  let lastError;
+  for (const retryDelayMs of AGENT_TAB_GROUP_RETRY_DELAYS_MS) {
+    if (retryDelayMs > 0) {
+      await delayMs(retryDelayMs);
+    }
+    try {
+      const groupId = await wrapChromeCallback(
+        (callback) => chrome.tabs.group(
+          { tabIds: tabId, createProperties: { windowId } },
+          callback
+        )
+      );
+      await wrapChromeVoid(
+        (callback) => chrome.tabGroups.update(
+          groupId,
+          { title: AGENT_TAB_GROUP_TITLE },
+          () => callback()
+        )
+      );
+      return;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  console.debug("Failed to create/update agent tab group.", lastError);
+};
+var ensureAgentTabGroupForTab = async (tabId, tab) => {
+  const windowId = tab.windowId;
+  if (typeof windowId !== "number") {
+    return;
   }
+  await ensureAgentTabGroup(tabId, windowId);
 };
 var createAgentWindow = async () => {
   const created = await wrapChromeCallback(
@@ -943,6 +1085,8 @@ var getOrCreateAgentTabId = async () => {
       if (typeof url === "string" && isRestrictedUrl(url)) {
         throw new Error(`Agent tab points at restricted URL: ${url}`);
       }
+      await ensureAgentTabGroupForTab(agentTabId, tab);
+      void refreshAgentTabBranding(agentTabId);
       return agentTabId;
     } catch {
       clearAgentTarget();
@@ -959,6 +1103,8 @@ var getOrCreateAgentTabId = async () => {
       agentTabId = stored;
       ensureLastActiveAt(stored);
       markTabActive(stored);
+      await ensureAgentTabGroupForTab(stored, tab);
+      void refreshAgentTabBranding(stored);
       return stored;
     } catch {
       await writeAgentTabId(null);
@@ -1017,12 +1163,18 @@ var sendToTab = async (tabId, action, params, options) => {
       chrome.tabs.sendMessage(tabId, message, (response) => {
         const error = chrome.runtime.lastError;
         if (error) {
+          const retryable = isTransientTabChannelError(error.message);
           finish({
             ok: false,
             error: {
               code: "EVALUATION_FAILED",
               message: error.message,
-              retryable: false
+              retryable,
+              ...retryable ? {
+                details: {
+                  reason: "transient_tab_channel_error"
+                }
+              } : {}
             }
           });
           return;
@@ -1042,27 +1194,31 @@ var sendToTab = async (tabId, action, params, options) => {
       });
     });
   };
-  const MAX_ATTEMPTS = 5;
-  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+  for (let attempt = 1; ; attempt += 1) {
     const result = await attemptSend();
     if (result.ok) {
       return result;
     }
-    const message = result.error?.message;
-    const isNoReceiver = typeof message === "string" && message.toLowerCase().includes("receiving end does not exist");
-    if (!isNoReceiver || attempt === MAX_ATTEMPTS) {
+    if (!isTransientTabChannelError(result.error?.message)) {
       return result;
     }
-    await delayMs(200);
-  }
-  return {
-    ok: false,
-    error: {
-      code: "INTERNAL",
-      message: "Failed to send message to content script.",
-      retryable: false
+    const retryDelayMs = getTabChannelRetryDelayMs(attempt);
+    if (retryDelayMs === void 0) {
+      return result;
     }
-  };
+    await delayMs(retryDelayMs);
+  }
+};
+var refreshAgentTabBranding = async (tabId) => {
+  const result = await sendToTab(
+    tabId,
+    AGENT_TAB_BRANDING_ACTION,
+    { favicon_url: getAgentTabFaviconUrl() },
+    { timeoutMs: AGENT_TAB_BRANDING_TIMEOUT_MS }
+  );
+  if (!result.ok) {
+    return;
+  }
 };
 var waitForHistoryNavigationSignal = async (tabId, timeoutMs) => {
   return await new Promise((resolve, reject) => {
@@ -1290,6 +1446,11 @@ var DriveSocket = class {
   getConnectionStatus() {
     return this.connection.getStatus();
   }
+  refreshCapabilities() {
+    void this.sendHello().catch((error) => {
+      console.error("DriveSocket refreshCapabilities failed:", error);
+    });
+  }
   handleSocketUnavailable(socket2, reason) {
     if (this.socket !== socket2) {
       return;
@@ -1319,6 +1480,7 @@ var DriveSocket = class {
   async sendHello() {
     const manifest = chrome.runtime.getManifest();
     const endpoint = await readCoreEndpointConfig();
+    const debuggerCapabilityEnabled = await readDebuggerCapabilityEnabled();
     let tabs = [];
     try {
       tabs = await queryTabs();
@@ -1328,6 +1490,8 @@ var DriveSocket = class {
     }
     const params = {
       version: manifest.version,
+      protocol_version: DRIVE_WS_PROTOCOL_VERSION,
+      capabilities: buildNegotiatedCapabilities(debuggerCapabilityEnabled),
       core_host: endpoint.host,
       core_port: endpoint.port,
       core_port_source: endpoint.portSource,
@@ -1402,6 +1566,19 @@ var DriveSocket = class {
       });
     }
   }
+  async refreshDebuggerCapabilityState() {
+    const enabled = await readDebuggerCapabilityEnabled();
+    if (!enabled) {
+      await this.detachAllDebuggerSessions();
+    }
+    this.refreshCapabilities();
+  }
+  async handleDebuggerCapabilityChange(enabled) {
+    if (!enabled) {
+      await this.detachAllDebuggerSessions();
+    }
+    this.refreshCapabilities();
+  }
   async handleRequest(message) {
     let driveMessage = null;
     let gatedSiteKey = null;
@@ -1440,6 +1617,15 @@ var DriveSocket = class {
         return;
       }
       if (message.action.startsWith("debugger.")) {
+        if (!await readDebuggerCapabilityEnabled()) {
+          this.sendMessage({
+            id: message.id,
+            action: message.action,
+            status: "error",
+            error: sanitizeDriveErrorInfo(debuggerCapabilityDisabledError())
+          });
+          return;
+        }
         await this.handleDebuggerRequest(message);
         return;
       }
@@ -1451,8 +1637,6 @@ var DriveSocket = class {
         "drive.navigate",
         "drive.go_back",
         "drive.go_forward",
-        "drive.back",
-        "drive.forward",
         "drive.click",
         "drive.hover",
         "drive.select",
@@ -1629,29 +1813,42 @@ var DriveSocket = class {
             tabId = await getDefaultTabId();
           }
           const waitMode = params.wait === "none" || params.wait === "domcontentloaded" ? params.wait : "domcontentloaded";
+          const domContentLoadedSignal = waitMode === "domcontentloaded" ? waitForDomContentLoaded(tabId, 3e4) : null;
+          const warnings = [];
           await wrapChromeVoid(
             (callback) => chrome.tabs.update(tabId, { url }, () => callback())
           );
           markTabActive(tabId);
-          if (waitMode === "domcontentloaded") {
+          if (domContentLoadedSignal) {
             try {
-              await waitForDomContentLoaded(tabId, 3e4);
+              await domContentLoadedSignal;
             } catch (error) {
-              respondError({
-                code: "TIMEOUT",
-                message: error instanceof Error ? error.message : "Timed out waiting.",
-                retryable: true
-              });
-              return;
+              const tab = await getTab(tabId).catch(() => void 0);
+              if (tab && isLikelyNavigationCommitted(url, tab.url ?? void 0)) {
+                warnings.push(
+                  "Timed out waiting for DOMContentLoaded, but the tab URL already updated to the requested target."
+                );
+              } else {
+                respondError({
+                  code: "TIMEOUT",
+                  message: error instanceof Error ? error.message : "Timed out waiting.",
+                  retryable: true
+                });
+                return;
+              }
             }
           }
-          respondOk({ ok: true });
+          if (tabId === agentTabId) {
+            void refreshAgentTabBranding(tabId);
+          }
+          respondOk({
+            ok: true,
+            ...warnings.length > 0 ? { warnings } : {}
+          });
           return;
         }
         case "drive.go_back":
-        case "drive.back":
-        case "drive.go_forward":
-        case "drive.forward": {
+        case "drive.go_forward": {
           const params = message.params ?? {};
           let tabId = params.tab_id;
           if (tabId !== void 0 && typeof tabId !== "number") {
@@ -1693,11 +1890,18 @@ var DriveSocket = class {
             }
           } catch {
             if (!result.ok) {
-              respondError(result.error);
+              respondError({
+                ...result.error
+              });
               return;
             }
           }
-          respondOk({ ok: true });
+          if (tabId === agentTabId) {
+            void refreshAgentTabBranding(tabId);
+          }
+          respondOk({
+            ok: true
+          });
           return;
         }
         case "drive.tab_list": {
@@ -3082,6 +3286,9 @@ var DriveSocket = class {
     }
   }
   async handleDebuggerEvent(source, method, params) {
+    if (!await readDebuggerCapabilityEnabled()) {
+      return;
+    }
     const tabId = source.tabId;
     if (typeof tabId !== "number") {
       return;
@@ -3100,6 +3307,9 @@ var DriveSocket = class {
       return;
     }
     this.clearDebuggerSession(tabId);
+    if (!await readDebuggerCapabilityEnabled()) {
+      return;
+    }
     this.sendDebuggerEvent({
       tab_id: tabId,
       method: "Debugger.detached",
@@ -3238,6 +3448,15 @@ var DriveSocket = class {
     }
     return null;
   }
+  async detachAllDebuggerSessions() {
+    const tabIds = Array.from(this.debuggerSessions.keys());
+    for (const tabId of tabIds) {
+      const error = await this.detachDebugger(tabId);
+      if (error) {
+        console.warn("DriveSocket detachDebugger failed:", tabId, error);
+      }
+    }
+  }
   async sendDebuggerCommand(tabId, method, params, timeoutMs) {
     return await new Promise((resolve, reject) => {
       let finished = false;
@@ -3368,14 +3587,53 @@ chrome.debugger.onDetach.addListener(
 );
 chrome.runtime.onMessage.addListener(
   (message, _sender, sendResponse) => {
-    if (!message || typeof message !== "object" || message.action !== "drive.connection_status") {
+    if (!message || typeof message !== "object") {
       return void 0;
     }
-    sendResponse({
-      ok: true,
-      result: socket.getConnectionStatus()
+    const action = message.action;
+    if (action === "drive.connection_status") {
+      sendResponse({
+        ok: true,
+        result: socket.getConnectionStatus()
+      });
+      return true;
+    }
+    if (action === "drive.refresh_capabilities") {
+      void socket.refreshDebuggerCapabilityState().then(() => {
+        sendResponse({ ok: true, result: { refreshed: true } });
+      }).catch((error) => {
+        const message2 = error instanceof Error ? error.message : "Failed to refresh capabilities.";
+        sendResponse({ ok: false, error: { message: message2 } });
+      });
+      return true;
+    }
+    return void 0;
+  }
+);
+chrome.storage.onChanged.addListener(
+  (changes, areaName) => {
+    if (areaName !== "local") {
+      return;
+    }
+    const debuggerChange = changes[DEBUGGER_CAPABILITY_ENABLED_KEY];
+    if (!debuggerChange) {
+      return;
+    }
+    if (typeof debuggerChange.newValue === "boolean") {
+      void socket.handleDebuggerCapabilityChange(debuggerChange.newValue).catch((error) => {
+        console.error(
+          "DriveSocket handleDebuggerCapabilityChange failed:",
+          error
+        );
+      });
+      return;
+    }
+    void socket.refreshDebuggerCapabilityState().catch((error) => {
+      console.error(
+        "DriveSocket refreshDebuggerCapabilityState failed:",
+        error
+      );
     });
-    return true;
   }
 );
 socket.start();