Generalize browser automation hosting beyond the desktop app (#1878)

* feat(browser): generalize browser automation hosts

Rename the browser automation client capability to a host-neutral payload, advertise supported commands, and route tab-scoped commands by browserId affinity so future browser hosts can register without another protocol shape change.

* fix(browser): harden browser host registration

Reject unusable browser host capabilities, clean up pending requests when a host registration is replaced, and defer list_tabs affinity updates until every host in the aggregation succeeds.

* fix(browser): preserve host tab affinity across reconnects

Keep stranded tab ownership tied to the disconnected host so the same host can reclaim open tabs after reconnect, and tolerate future command names in browser_host capability payloads while retaining only known commands.

packages/protocol/src/browser-automation/capabilities.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import {
+  BROWSER_AUTOMATION_COMMAND_NAMES,
+  type BrowserAutomationCommandName,
+} from "./rpc-schemas.js";
+
+const KNOWN_BROWSER_AUTOMATION_COMMAND_NAMES = new Set<string>(BROWSER_AUTOMATION_COMMAND_NAMES);
+
+export const BrowserAutomationHostCapabilitySchema = z
+  .object({
+    supportedCommands: z.array(z.string().min(1)).transform((commands, context) => {
+      const supportedCommands: BrowserAutomationCommandName[] = [];
+      const seen = new Set<BrowserAutomationCommandName>();
+
+      for (const command of commands) {
+        if (!isKnownBrowserAutomationCommandName(command) || seen.has(command)) {
+          continue;
+        }
+        seen.add(command);
+        supportedCommands.push(command);
+      }
+
+      if (supportedCommands.length === 0) {
+        context.addIssue({
+          code: "custom",
+          message: "supportedCommands must include at least one known browser automation command",
+        });
+        return z.NEVER;
+      }
+
+      return supportedCommands;
+    }),
+    hostKind: z.string().min(1).default("browser host"),
+  })
+  .passthrough();
+
+export type BrowserAutomationHostCapability = z.infer<typeof BrowserAutomationHostCapabilitySchema>;
+
+function isKnownBrowserAutomationCommandName(value: string): value is BrowserAutomationCommandName {
+  return KNOWN_BROWSER_AUTOMATION_COMMAND_NAMES.has(value);
+}

packages/protocol/src/browser-automation/rpc-schemas.test.ts

@@ -564,8 +564,8 @@ describe("browser automation execute RPC schemas", () => {
         requestId: "req-error",
         ok: false,
         error: {
-          code: "browser_no_desktop",
-          message: "No desktop browser automation client is connected.",
+          code: "browser_no_host",
+          message: "No browser automation host is connected.",
         },
       },
     });
@@ -574,8 +574,8 @@ describe("browser automation execute RPC schemas", () => {
       requestId: "req-error",
       ok: false,
       error: {
-        code: "browser_no_desktop",
-        message: "No desktop browser automation client is connected.",
+        code: "browser_no_host",
+        message: "No browser automation host is connected.",
         retryable: false,
       },
     });

packages/protocol/src/browser-automation/rpc-schemas.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 
 export const BrowserAutomationErrorCodeSchema = z.enum([
   "browser_disabled",
-  "browser_no_desktop",
+  "browser_no_host",
   "browser_tab_not_found",
   "browser_tab_closed",
   "browser_timeout",
@@ -20,6 +20,29 @@ const BROWSER_AUTOMATION_BROWSER_ID_MESSAGE =
 const BROWSER_AUTOMATION_WAIT_CONDITION_MESSAGE =
   "browser_wait requires exactly one of text or url";
 
+export const BROWSER_AUTOMATION_COMMAND_NAMES = [
+  "list_tabs",
+  "new_tab",
+  "snapshot",
+  "click",
+  "fill",
+  "wait",
+  "type",
+  "keypress",
+  "navigate",
+  "back",
+  "forward",
+  "reload",
+  "screenshot",
+  "upload",
+  "select",
+  "hover",
+  "drag",
+  "logs",
+] as const;
+
+export const BrowserAutomationCommandNameSchema = z.enum(BROWSER_AUTOMATION_COMMAND_NAMES);
+
 export const BrowserAutomationBrowserIdSchema = z
   .string({ error: () => BROWSER_AUTOMATION_BROWSER_ID_MESSAGE })
   .min(1, BROWSER_AUTOMATION_BROWSER_ID_MESSAGE)
@@ -399,6 +422,7 @@ export const BrowserAutomationExecuteResponseSchema = z.object({
 });
 
 export type BrowserAutomationErrorCode = z.infer<typeof BrowserAutomationErrorCodeSchema>;
+export type BrowserAutomationCommandName = z.infer<typeof BrowserAutomationCommandNameSchema>;
 export type BrowserAutomationCommand = z.infer<typeof BrowserAutomationCommandSchema>;
 export type BrowserAutomationResult = z.infer<typeof BrowserAutomationResultSchema>;
 export type BrowserAutomationConsoleLogEntry = z.infer<