@btraut/browser-bridge 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -8,6 +8,19 @@ The format is based on "Keep a Changelog", and this project adheres to Semantic
 
 _TBD_
 
+## [0.7.1] - 2026-02-11
+
+### Fixed
+
+- Diagnostics doctor: stop failing by default when `session_id` is omitted, treat detached debugger as expected idle behavior, and downgrade stale drive/inspect errors to warnings.
+- Core error latching: clear drive/inspect/debugger `last_error` state after successful operations so recovered sessions report healthy diagnostics.
+
+## [0.7.0] - 2026-02-10
+
+### Fixed
+
+- MCP adapter: avoid SDK `_zod` crashes on tool calls by registering object-shaped output schemas and flagging `ok: false` envelopes as MCP errors.
+
 ## [0.6.1] - 2026-02-10
 
 ### Added

package/README.md

@@ -82,6 +82,21 @@ What makes it different:
 - **Recovery-first**: sessions have an explicit state machine with `session.recover()` and `diagnostics doctor`.
 - **Inspect beyond screenshots**: DOM snapshots (AX + HTML) and `inspect dom-diff` to detect page changes.
 
+## 🆚 Feature Comparison
+
+| Category | Browser Bridge | Playwright MCP | agent-browser | mcp-chrome | Claude Code + Chrome |
+| --- | --- | --- | --- | --- | --- |
+| Uses your real, already-logged-in Chrome (tabs/cookies) | ✅ | ❌ | ❌ | ✅ | ✅ |
+| Visible browser (not headless) | ✅ | ✅ | ❌ | ✅ | ✅ |
+| Per-site permission prompts / allowlist | ✅ | ❌ | ❌ | ❌ | ✅ |
+| Drive/Inspect split (inspect without racing input) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Token-efficient inspection (element refs, bounded output, cleanup) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Structured errors + retry hints | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Explicit recovery + doctor-style diagnostics | ✅ | ❌ | ❌ | ❌ | ❌ |
+| DOM diff (change detection) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| HAR / network export | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Open source | ✅ | ✅ | ✅ | ✅ | ❌ |
+
 ## 🔒 Site Permissions (Drive Actions)
 
 Browser Bridge is intentionally safe: **drive actions** (`drive.navigate`, click, type, etc.) require **per-site approval**. `inspect.*` is not gated, so agents can inspect first and only ask for permission when it's time to click/type.

package/dist/api.js

@@ -848,6 +848,10 @@ var DriveController = class {
     this.lastError = error;
     this.lastErrorAt = (/* @__PURE__ */ new Date()).toISOString();
   }
+  clearLastError() {
+    this.lastError = void 0;
+    this.lastErrorAt = void 0;
+  }
   async execute(sessionId, action, params, timeoutMs) {
     return await driveMutex.runExclusive(async () => {
       try {
@@ -888,6 +892,7 @@ var DriveController = class {
             timeoutMs
           );
           if (response.status === "ok") {
+            this.clearLastError();
             return {
               ok: true,
               result: response.result
@@ -2800,6 +2805,7 @@ var InspectService = class {
     });
   }
   markInspectConnected(sessionId) {
+    this.clearLastError();
     try {
       const session = this.registry.require(sessionId);
       if (session.state === "INIT" /* INIT */ || session.state === "DRIVE_READY" /* DRIVE_READY */) {
@@ -2814,6 +2820,10 @@ var InspectService = class {
     this.lastError = error;
     this.lastErrorAt = (/* @__PURE__ */ new Date()).toISOString();
   }
+  clearLastError() {
+    this.lastError = void 0;
+    this.lastErrorAt = void 0;
+  }
   buildUnavailableError() {
     return new InspectError(
       "INSPECT_UNAVAILABLE",
@@ -2888,7 +2898,6 @@ var successEnvelopeSchema = (result) => import_zod.z.object({
   ok: import_zod.z.literal(true),
   result
 });
-var apiEnvelopeSchema = (result) => import_zod.z.union([successEnvelopeSchema(result), ErrorEnvelopeSchema]);
 
 // packages/shared/src/schemas.ts
 var import_zod2 = require("zod");
@@ -3475,10 +3484,20 @@ var registerArtifactsRoutes = (router, options = {}) => {
 };
 
 // packages/core/src/diagnostics.ts
+var STALE_ERROR_THRESHOLD_MS = 2 * 60 * 1e3;
+var getErrorAgeMs = (timestamp) => {
+  const parsed = Date.parse(timestamp);
+  if (!Number.isFinite(parsed)) {
+    return void 0;
+  }
+  return Math.max(0, Date.now() - parsed);
+};
 var buildDiagnosticReport = (sessionId, context = {}) => {
   const extensionConnected = context.extension?.connected ?? false;
   const debuggerAttached = context.debugger?.attached ?? false;
   const sessionState = context.sessionState;
+  const hasSessionId = Boolean(sessionId);
+  const warnings = [];
   const checks = [
     {
       name: "extension.connected",
@@ -3487,13 +3506,13 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
     },
     {
       name: "debugger.attached",
-      ok: debuggerAttached,
-      message: debuggerAttached ? "Debugger is attached." : "Debugger is not attached."
+      ok: true,
+      message: debuggerAttached ? "Debugger is attached." : "Debugger is not attached (inspect is idle)."
     },
     {
       name: "session.state",
-      ok: Boolean(sessionState),
-      message: sessionState ? `Session state is ${sessionState}.` : sessionId ? "Session state unavailable." : "Session id not provided.",
+      ok: hasSessionId ? Boolean(sessionState) : true,
+      message: sessionState ? `Session state is ${sessionState}.` : hasSessionId ? "Session state unavailable." : "Session id not provided.",
       details: {
         session_id: sessionId || null,
         state: sessionState ?? "UNKNOWN"
@@ -3501,26 +3520,42 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
     }
   ];
   if (context.driveLastError) {
+    const ageMs = getErrorAgeMs(context.driveLastError.at);
+    const isStale = ageMs !== void 0 && ageMs > STALE_ERROR_THRESHOLD_MS;
+    if (isStale) {
+      warnings.push(
+        `Ignoring stale drive error (${Math.round(ageMs / 1e3)}s old): ${context.driveLastError.message}`
+      );
+    }
     checks.push({
       name: "drive.last_error",
-      ok: false,
+      ok: isStale,
       message: context.driveLastError.message,
       details: {
         code: context.driveLastError.code,
         retryable: context.driveLastError.retryable,
-        at: context.driveLastError.at
+        at: context.driveLastError.at,
+        ...ageMs !== void 0 ? { age_ms: ageMs } : {}
       }
     });
   }
   if (context.inspectLastError) {
+    const ageMs = getErrorAgeMs(context.inspectLastError.at);
+    const isStale = ageMs !== void 0 && ageMs > STALE_ERROR_THRESHOLD_MS;
+    if (isStale) {
+      warnings.push(
+        `Ignoring stale inspect error (${Math.round(ageMs / 1e3)}s old): ${context.inspectLastError.message}`
+      );
+    }
     checks.push({
       name: "inspect.last_error",
-      ok: false,
+      ok: isStale,
       message: context.inspectLastError.message,
       details: {
         code: context.inspectLastError.code,
         retryable: context.inspectLastError.retryable,
-        at: context.inspectLastError.at
+        at: context.inspectLastError.at,
+        ...ageMs !== void 0 ? { age_ms: ageMs } : {}
       }
     });
   }
@@ -3579,6 +3614,7 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
         loop_detected: context.recoveryMetrics.loopDetected
       } : {}
     } : void 0,
+    ...warnings.length > 0 ? { warnings } : {},
     notes: ["Diagnostics include runtime status; some checks may be stubbed."]
   };
   return report;
@@ -4272,6 +4308,7 @@ var DebuggerBridge = class {
       }
       state.attached = true;
       this.touch(tabId, state);
+      this.clearLastError();
       return { ok: true, result: { attached: true } };
     } catch (error) {
       const info = this.handleBridgeError(error);
@@ -4299,6 +4336,7 @@ var DebuggerBridge = class {
         return { ok: false, error };
       }
       this.markDetached(tabId);
+      this.clearLastError();
       return { ok: true, result: { attached: false } };
     } catch (error) {
       const info = this.handleBridgeError(error);
@@ -4331,6 +4369,7 @@ var DebuggerBridge = class {
         return { ok: false, error };
       }
       this.touch(tabId, this.ensureTab(tabId));
+      this.clearLastError();
       return { ok: true, result: response.result };
     } catch (error) {
       const info = this.handleBridgeError(error);
@@ -4416,6 +4455,10 @@ var DebuggerBridge = class {
     this.lastError = error;
     this.lastErrorAt = (/* @__PURE__ */ new Date()).toISOString();
   }
+  clearLastError() {
+    this.lastError = void 0;
+    this.lastErrorAt = void 0;
+  }
   handleBridgeError(error) {
     if (error instanceof ExtensionBridgeError) {
       const info2 = toDriveError(error);
@@ -4620,9 +4663,11 @@ var createCoreClient = (options = {}) => {
 var toToolResult = (payload) => {
   const content = [{ type: "text", text: JSON.stringify(payload) }];
   if (payload && typeof payload === "object") {
+    const isErrorEnvelope = ErrorEnvelopeSchema.safeParse(payload).success;
     return {
       content,
-      structuredContent: payload
+      structuredContent: payload,
+      isError: isErrorEnvelope
     };
   }
   return { content };
@@ -4635,7 +4680,7 @@ var toInternalErrorEnvelope = (error) => ({
     retryable: false
   }
 });
-var envelope = (schema) => apiEnvelopeSchema(schema);
+var envelope = (schema) => successEnvelopeSchema(schema);
 var TOOL_DEFINITIONS = [
   {
     name: "session.create",