@vellumai/assistant 0.6.5 → 0.6.6

package/src/tools/browser/__tests__/browser-status.test.ts

@@ -163,4 +163,193 @@ describe("executeBrowserStatus", () => {
     expect(extension.verified).toBe("active_probe");
     expect(extension.details.restrictedActiveTab).toBe(true);
   });
+
+  // ── macOS host-browser proxy mode tests ─────────────────────────────
+
+  test("macOS: reports host browser proxy as available when proxy is bound and connected", async () => {
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        transportInterface: "macos",
+        hostBrowserProxy: {
+          isAvailable: () => true,
+        } as ToolContext["hostBrowserProxy"],
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    const extension = payload.modes.find(
+      (m: { mode: string }) => m.mode === BROWSER_STATUS_MODE.EXTENSION,
+    );
+    expect(extension).toBeDefined();
+    expect(extension.available).toBe(true);
+    expect(extension.verified).toBe("active_probe");
+    expect(extension.summary).toContain("macOS host browser proxy");
+    expect(extension.details.transport).toBe("macos-sse");
+  });
+
+  test("macOS: reports transport as extension-ws when hostBrowserRegistryRouted is true", async () => {
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        transportInterface: "macos",
+        hostBrowserRegistryRouted: true,
+        hostBrowserProxy: {
+          isAvailable: () => true,
+        } as ToolContext["hostBrowserProxy"],
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    const extension = payload.modes.find(
+      (m: { mode: string }) => m.mode === BROWSER_STATUS_MODE.EXTENSION,
+    );
+    expect(extension).toBeDefined();
+    expect(extension.available).toBe(true);
+    expect(extension.details.transport).toBe("extension-ws");
+  });
+
+  test("macOS: reports proxy unbound with macOS-specific actions when no proxy is present", async () => {
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        transportInterface: "macos",
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    const extension = payload.modes.find(
+      (m: { mode: string }) => m.mode === BROWSER_STATUS_MODE.EXTENSION,
+    );
+    expect(extension).toBeDefined();
+    expect(extension.available).toBe(false);
+    expect(extension.summary).toContain("macOS host browser proxy");
+    expect(extension.summary).toContain("desktop client");
+    expect(extension.details.transport).toBe("macos-sse");
+    // macOS-specific user actions should mention the desktop app, not the extension
+    expect(
+      extension.userActions.some((a: string) => a.includes("desktop app")),
+    ).toBe(true);
+  });
+
+  test("macOS: reports proxy disconnected with reconnect actions when proxy is bound but not available", async () => {
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        transportInterface: "macos",
+        hostBrowserProxy: {
+          isAvailable: () => false,
+        } as ToolContext["hostBrowserProxy"],
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    const extension = payload.modes.find(
+      (m: { mode: string }) => m.mode === BROWSER_STATUS_MODE.EXTENSION,
+    );
+    expect(extension).toBeDefined();
+    expect(extension.available).toBe(false);
+    expect(extension.summary).toContain("macOS host browser proxy");
+    expect(extension.summary).toContain("SSE transport");
+    expect(extension.details.transport).toBe("macos-sse");
+    // Should suggest reconnection, not extension install
+    expect(
+      extension.userActions.some((a: string) => a.includes("desktop app")),
+    ).toBe(true);
+  });
+
+  test("macOS: probe failure diagnostics include transport-specific remediation", async () => {
+    probeOutcomes[BROWSER_STATUS_MODE.EXTENSION] = "fail";
+    probeErrors[BROWSER_STATUS_MODE.EXTENSION] = new CdpError(
+      "transport_error",
+      "transport disconnected before response",
+    );
+
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        transportInterface: "macos",
+        hostBrowserProxy: {
+          isAvailable: () => true,
+        } as ToolContext["hostBrowserProxy"],
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    const extension = payload.modes.find(
+      (m: { mode: string }) => m.mode === BROWSER_STATUS_MODE.EXTENSION,
+    );
+    expect(extension).toBeDefined();
+    expect(extension.available).toBe(false);
+    expect(extension.summary).toContain("macOS host browser proxy");
+    // Should have remediation actions mentioning SSE bridge
+    expect(
+      extension.userActions.some((a: string) => a.includes("SSE bridge")),
+    ).toBe(true);
+  });
+
+  test("recommendation order follows auto candidate precedence for macOS with available extension proxy", async () => {
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        transportInterface: "macos",
+        hostBrowserProxy: {
+          isAvailable: () => true,
+        } as ToolContext["hostBrowserProxy"],
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    // Extension is the top auto candidate and is available, so it should be recommended
+    expect(payload.recommendedMode).toBe(BROWSER_STATUS_MODE.EXTENSION);
+    expect(payload.autoCandidateOrder[0]).toBe(BROWSER_STATUS_MODE.EXTENSION);
+  });
+
+  test("recommendation falls to cdp-inspect when macOS proxy is unavailable", async () => {
+    // Extension probe fails
+    probeOutcomes[BROWSER_STATUS_MODE.EXTENSION] = "fail";
+    probeErrors[BROWSER_STATUS_MODE.EXTENSION] = new CdpError(
+      "transport_error",
+      "proxy not connected",
+    );
+
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        transportInterface: "macos",
+        // No proxy bound, so extension unavailable
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    // Extension is unavailable (no proxy), so recommendation should fall to next available
+    expect(payload.recommendedMode).toBe(BROWSER_STATUS_MODE.CDP_INSPECT);
+  });
+
+  test("macOS: restricted chrome:// page probe includes macOS transport details", async () => {
+    probeOutcomes[BROWSER_STATUS_MODE.EXTENSION] = "fail";
+    probeErrors[BROWSER_STATUS_MODE.EXTENSION] = new CdpError(
+      "cdp_error",
+      "Cannot access a chrome:// URL",
+    );
+
+    const result = await executeBrowserStatus(
+      {},
+      makeContext({
+        transportInterface: "macos",
+        hostBrowserProxy: {
+          isAvailable: () => true,
+        } as ToolContext["hostBrowserProxy"],
+      }),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    const extension = payload.modes.find(
+      (m: { mode: string }) => m.mode === BROWSER_STATUS_MODE.EXTENSION,
+    );
+    expect(extension).toBeDefined();
+    expect(extension.available).toBe(true);
+    expect(extension.summary).toContain("macOS host browser proxy");
+    expect(extension.details.transport).toBe("macos-sse");
+  });
 });

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

@@ -88,9 +88,9 @@ 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": [
@@ -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",
@@ -2247,6 +2285,7 @@ async function checkExtensionModeStatus(
 ): Promise<BrowserStatusModeResult> {
   const proxyBound = Boolean(context.hostBrowserProxy);
   const proxyConnected = context.hostBrowserProxy?.isAvailable() ?? false;
+  const isMacOS = context.transportInterface === "macos";
 
   if (!proxyBound) {
     return {
@@ -2254,13 +2293,20 @@ async function checkExtensionModeStatus(
       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 +2317,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 +2345,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 +2368,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 +2382,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 +2395,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 +2408,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/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");
+  });
 });