@vellumai/assistant 0.6.5 → 0.7.0

package/src/tools/browser/browser-execution.ts

@@ -75,22 +75,22 @@ const log = getLogger("headless-browser");
 
 // ── Constants ────────────────────────────────────────────────────────
 
-export const NAVIGATE_TIMEOUT_MS = 15_000;
+const NAVIGATE_TIMEOUT_MS = 15_000;
 
-export const ACTION_TIMEOUT_MS = 10_000;
+const ACTION_TIMEOUT_MS = 10_000;
 
-export const MAX_WAIT_MS = 30_000;
+const MAX_WAIT_MS = 30_000;
 
-export const MAX_EXTRACT_LENGTH = 50_000;
+const MAX_EXTRACT_LENGTH = 50_000;
 
 type StatusCheckMode = BrowserStatusMode;
 
 const MODE_TRADEOFFS: Record<StatusCheckMode, string[]> = {
   [BROWSER_STATUS_MODE.EXTENSION]: [
     "This is the preferred approach for all things browser-use.",
-    "It requires a one-time install of the Vellum Assistant Chrome Extension.",
+    "On macOS, the host browser proxy is provisioned automatically via the desktop client's SSE bridge — no extension install required.",
+    "When the Chrome extension is also installed, it takes priority for direct WebSocket routing to the user's Chrome session.",
     "More secure than relying on Chrome's native remote debugging functionality.",
-    "Requires the Vellum extension to be paired and actively connected.",
   ],
   [BROWSER_STATUS_MODE.CDP_INSPECT]: [
     "This is the second-best approach for all things browser-use, after the native Vellum Assistant Chrome Extension.",
@@ -190,9 +190,10 @@ export function parseBrowserMode(
 const REMEDIATION_HINTS: Record<string, string[]> = {
   // Extension backend
   "extension:transport_error": [
-    "Ensure the Vellum browser extension is installed and enabled.",
-    "Check that the extension WebSocket connection is active (extension popup → status).",
-    "Try reconnecting the extension or reloading the extension service worker.",
+    "Ensure the Vellum browser extension is installed and enabled, or that the macOS desktop client is running for host browser proxy mode.",
+    "For extension mode: check that the extension WebSocket connection is active (extension popup → status).",
+    "For macOS host browser proxy: verify the desktop client is running and has an active SSE connection to the assistant.",
+    "Try reconnecting the extension or restarting the desktop client.",
   ],
   // cdp-inspect backend — discovery-level failures
   "cdp-inspect:unreachable": [
@@ -358,7 +359,7 @@ function isRestrictedChromePageProbeError(error: CdpError): boolean {
  * The returned client is wrapped so its first successful `send()`
  * writes the resolved kind back to the conversation memo.
  */
-export function acquireCdpClientWithMode(
+function acquireCdpClientWithMode(
   input: Record<string, unknown>,
   context: ToolContext,
 ):
@@ -513,7 +514,7 @@ export type ResolvedElement =
  * or when an `element_id` is provided but the snapshot map is
  * empty/stale.
  */
-export function resolveElement(
+function resolveElement(
   conversationId: string,
   input: Record<string, unknown>,
 ): { resolved: ResolvedElement | null; error: string | null } {
@@ -2098,6 +2099,43 @@ function extensionSetupActions(): string[] {
   ];
 }
 
+function macOSHostBrowserSetupActions(): string[] {
+  return [
+    "Ensure the Vellum desktop app is running and connected to the assistant.",
+    "Open Google Chrome on the desktop machine so the host browser proxy can attach.",
+    "If the desktop client is not running, launch it and wait for the SSE connection to establish.",
+  ];
+}
+
+function macOSHostBrowserReconnectActions(): string[] {
+  return [
+    "Verify the Vellum desktop app is still running and has an active network connection.",
+    "If the desktop client was recently restarted, send a new message to re-establish the SSE bridge.",
+    "Ensure Chrome is open on the desktop machine for the host browser proxy to target.",
+  ];
+}
+
+function macOSHostBrowserProbeFailureActions(error: CdpError): string[] {
+  const actions: string[] = [
+    "Ensure Google Chrome is running on the desktop machine.",
+  ];
+  const message = error.message.toLowerCase();
+  if (message.includes("timeout") || message.includes("timed out")) {
+    actions.push(
+      "The desktop client may be unresponsive — try restarting the Vellum desktop app.",
+    );
+  }
+  if (message.includes("transport") || message.includes("disconnected")) {
+    actions.push(
+      "The SSE bridge between the assistant and the desktop client appears broken. Send a new message to re-establish the connection.",
+    );
+  }
+  actions.push(
+    "Switch Chrome to a regular http(s) tab (not chrome://...) and retry.",
+  );
+  return dedupeStrings(actions);
+}
+
 function cdpInspectSetupActions(): string[] {
   return [
     "Update Chrome to the latest version by going to chrome://settings/help",
@@ -2141,7 +2179,7 @@ function probeFailureActions(mode: StatusCheckMode, error: CdpError): string[] {
       )
     ) {
       actions.push(
-        "Ensure this extension ID is present in meta/browser-extension/chrome-extension-allowlist.json and restart the assistant.",
+        "Ensure this extension ID is present in chrome-extension-allowlist.local.json in $GATEWAY_SECURITY_DIR and restart the assistant.",
       );
     }
     if (
@@ -2247,20 +2285,55 @@ async function checkExtensionModeStatus(
 ): Promise<BrowserStatusModeResult> {
   const proxyBound = Boolean(context.hostBrowserProxy);
   const proxyConnected = context.hostBrowserProxy?.isAvailable() ?? false;
+  const isMacOS = context.transportInterface === "macos";
+  const registryClients = context.connectedBrowserClients ?? [];
+  const extensionClients = registryClients.filter(
+    (c) => c.interfaceId === "chrome-extension",
+  );
 
   if (!proxyBound) {
+    // No proxy bound to this conversation, but the client registry may
+    // show a connected chrome-extension client with host_browser capability.
+    // Report that so `assistant browser status` from the CLI is accurate.
+    if (extensionClients.length > 0) {
+      return {
+        mode: BROWSER_STATUS_MODE.EXTENSION,
+        available: false,
+        verified: "preflight",
+        autoCandidate,
+        summary:
+          "Extension mode: a Chrome extension client is connected but no host browser proxy is bound to this conversation. " +
+          "Extension browser operations will be available within a conversation turn initiated from the extension.",
+        userActions: [],
+        tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
+        details: {
+          proxyBound,
+          proxyConnected,
+          connectedExtensionClients: extensionClients,
+          transport: "extension-ws",
+        },
+      };
+    }
+
     return {
       mode: BROWSER_STATUS_MODE.EXTENSION,
       available: false,
       verified: "preflight",
       autoCandidate,
-      summary:
-        "Extension mode is unavailable: no host browser proxy is bound to this conversation.",
-      userActions: extensionSetupActions(),
+      summary: isMacOS
+        ? "Extension mode is unavailable: the macOS host browser proxy is not bound to this conversation. Ensure the desktop client is connected."
+        : "Extension mode is unavailable: no host browser proxy is bound to this conversation.",
+      userActions: isMacOS
+        ? macOSHostBrowserSetupActions()
+        : extensionSetupActions(),
       tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
       details: {
         proxyBound,
         proxyConnected,
+        transport:
+          isMacOS && !context.hostBrowserRegistryRouted
+            ? "macos-sse"
+            : "extension-ws",
       },
     };
   }
@@ -2271,13 +2344,20 @@ async function checkExtensionModeStatus(
       available: false,
       verified: "preflight",
       autoCandidate,
-      summary:
-        "Extension mode is unavailable: the extension transport is currently disconnected.",
-      userActions: extensionSetupActions(),
+      summary: isMacOS
+        ? "Extension mode is unavailable: the macOS host browser proxy is bound but the SSE transport is currently disconnected. Verify the desktop client is running and connected."
+        : "Extension mode is unavailable: the extension transport is currently disconnected.",
+      userActions: isMacOS
+        ? macOSHostBrowserReconnectActions()
+        : extensionSetupActions(),
       tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
       details: {
         proxyBound,
         proxyConnected,
+        transport:
+          isMacOS && !context.hostBrowserRegistryRouted
+            ? "macos-sse"
+            : "extension-ws",
       },
     };
   }
@@ -2292,13 +2372,19 @@ async function checkExtensionModeStatus(
       available: true,
       verified: "active_probe",
       autoCandidate,
-      summary: "Extension mode is ready and responded to an active CDP probe.",
+      summary: isMacOS
+        ? "Extension mode is ready via macOS host browser proxy and responded to an active CDP probe."
+        : "Extension mode is ready and responded to an active CDP probe.",
       userActions: [],
       tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
       details: {
         proxyBound,
         proxyConnected,
         backendKind: probe.backendKind,
+        transport:
+          isMacOS && !context.hostBrowserRegistryRouted
+            ? "macos-sse"
+            : "extension-ws",
       },
     };
   }
@@ -2309,8 +2395,9 @@ async function checkExtensionModeStatus(
       available: true,
       verified: "active_probe",
       autoCandidate,
-      summary:
-        "Extension mode transport is connected, but the active Chrome tab is a restricted chrome:// page. Switch to a regular website tab if browser actions fail.",
+      summary: isMacOS
+        ? "Extension mode transport is connected via macOS host browser proxy, but the active Chrome tab is a restricted chrome:// page. Switch to a regular website tab if browser actions fail."
+        : "Extension mode transport is connected, but the active Chrome tab is a restricted chrome:// page. Switch to a regular website tab if browser actions fail.",
       userActions: [
         "Switch Chrome to a regular http(s) tab (not chrome://...) and retry.",
       ],
@@ -2322,6 +2409,10 @@ async function checkExtensionModeStatus(
         errorCode: probe.error.code,
         diagnostic: probe.diagnostic,
         attemptDiagnostics: probe.error.attemptDiagnostics ?? [],
+        transport:
+          isMacOS && !context.hostBrowserRegistryRouted
+            ? "macos-sse"
+            : "extension-ws",
       },
     };
   }
@@ -2331,11 +2422,12 @@ async function checkExtensionModeStatus(
     available: false,
     verified: "active_probe",
     autoCandidate,
-    summary: `Extension mode probe failed: ${probe.error.message}`,
-    userActions: probeFailureActions(
-      BROWSER_STATUS_MODE.EXTENSION,
-      probe.error,
-    ),
+    summary: isMacOS
+      ? `Extension mode probe failed via macOS host browser proxy: ${probe.error.message}`
+      : `Extension mode probe failed: ${probe.error.message}`,
+    userActions: isMacOS
+      ? macOSHostBrowserProbeFailureActions(probe.error)
+      : probeFailureActions(BROWSER_STATUS_MODE.EXTENSION, probe.error),
     tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
     details: {
       proxyBound,
@@ -2343,6 +2435,10 @@ async function checkExtensionModeStatus(
       errorCode: probe.error.code,
       diagnostic: probe.diagnostic,
       attemptDiagnostics: probe.error.attemptDiagnostics ?? [],
+      transport:
+        isMacOS && !context.hostBrowserRegistryRouted
+          ? "macos-sse"
+          : "extension-ws",
     },
   };
 }

package/src/tools/browser/browser-manager.ts

@@ -561,10 +561,7 @@ class BrowserManager {
    * any prior value so an explicit `browser_mode` override on one call
    * becomes the default for subsequent `auto`-mode calls.
    */
-  setPreferredBackendKind(
-    conversationId: string,
-    kind: CdpClientKind,
-  ): void {
+  setPreferredBackendKind(conversationId: string, kind: CdpClientKind): void {
     this.preferredBackendKinds.set(conversationId, kind);
   }
 
@@ -953,7 +950,3 @@ class BrowserManager {
 }
 
 export const browserManager = new BrowserManager();
-
-export function isAuthenticatedForDomain(domain: string): boolean {
-  return authSessionCache.isAuthenticated(domain);
-}

package/src/tools/browser/cdp-client/__tests__/extension-cdp-client.test.ts

@@ -356,4 +356,234 @@ describe("ExtensionCdpClient", () => {
     expect(err.message).toBe("CDP call aborted");
     expect(err.cdpMethod).toBe("Browser.getVersion");
   });
+
+  // ── Structured transport error classification ────────────────────────
+
+  test("structured error with code 'transport_error' is classified as transport_error", async () => {
+    const errorBody = {
+      code: "transport_error",
+      message: "Extension WebSocket disconnected",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-transport-1");
+
+    let caught: unknown;
+    try {
+      await client.send("Page.navigate", { url: "https://example.com" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("transport_error");
+    expect(err.message).toBe("Extension WebSocket disconnected");
+    expect(err.cdpMethod).toBe("Page.navigate");
+    expect(err.cdpParams).toEqual({ url: "https://example.com" });
+    expect(err.underlying).toEqual(errorBody);
+  });
+
+  test("structured error with code 'unreachable' is classified as transport_error", async () => {
+    const errorBody = {
+      code: "unreachable",
+      message: "Host browser not reachable",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-transport-2");
+
+    let caught: unknown;
+    try {
+      await client.send("Runtime.evaluate", { expression: "1+1" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("transport_error");
+    expect(err.message).toBe("Host browser not reachable");
+    expect(err.underlying).toEqual(errorBody);
+  });
+
+  test("structured error with code 'timeout' is classified as transport_error", async () => {
+    const errorBody = {
+      code: "timeout",
+      message: "CDP call timed out",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-transport-3");
+
+    let caught: unknown;
+    try {
+      await client.send("Page.captureScreenshot");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("transport_error");
+    expect(err.message).toBe("CDP call timed out");
+    expect(err.underlying).toEqual(errorBody);
+  });
+
+  test("structured error with code 'non_loopback' is classified as transport_error", async () => {
+    const errorBody = {
+      code: "non_loopback",
+      message: "Only loopback addresses are allowed",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-transport-4");
+
+    let caught: unknown;
+    try {
+      await client.send("Browser.getVersion");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("transport_error");
+    expect(err.message).toBe("Only loopback addresses are allowed");
+    expect(err.underlying).toEqual(errorBody);
+  });
+
+  // ── Command-level CDP errors remain cdp_error ────────────────────────
+
+  test("structured error with numeric code (CDP JSON-RPC) remains cdp_error", async () => {
+    const errorBody = {
+      code: -32000,
+      message: "Cannot find context with specified id",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-cdp-1");
+
+    let caught: unknown;
+    try {
+      await client.send("Runtime.evaluate", { expression: "boom" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("cdp_error");
+    expect(err.message).toBe("Cannot find context with specified id");
+  });
+
+  test("structured error with unknown string code remains cdp_error", async () => {
+    const errorBody = {
+      code: "some_unknown_code",
+      message: "Unrecognized error",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-cdp-2");
+
+    let caught: unknown;
+    try {
+      await client.send("Page.navigate", { url: "https://example.com" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("cdp_error");
+    expect(err.message).toBe("Unrecognized error");
+  });
+
+  test("structured error without code field remains cdp_error", async () => {
+    const errorBody = {
+      message: "Something went wrong",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-cdp-3");
+
+    let caught: unknown;
+    try {
+      await client.send("DOM.getDocument");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("cdp_error");
+    expect(err.message).toBe("Something went wrong");
+  });
+
+  test("structured error with code: null remains cdp_error", async () => {
+    const errorBody = {
+      code: null,
+      message: "Null code error",
+    };
+    const { proxy } = fakeProxy(async () => ({
+      content: JSON.stringify(errorBody),
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-cdp-4");
+
+    let caught: unknown;
+    try {
+      await client.send("Browser.getVersion");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("cdp_error");
+  });
+
+  test("plain-text isError content still throws cdp_error (no failover)", async () => {
+    const { proxy } = fakeProxy(async () => ({
+      content: "Connection lost unexpectedly",
+      isError: true,
+    }));
+
+    const client = createExtensionCdpClient(proxy, "conv-cdp-5");
+
+    let caught: unknown;
+    try {
+      await client.send("Page.navigate", { url: "https://example.com" });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(CdpError);
+    const err = caught as CdpError;
+    expect(err.code).toBe("cdp_error");
+    expect(err.message).toBe("Connection lost unexpectedly");
+    expect(err.underlying).toBe("Connection lost unexpectedly");
+  });
 });