machine-bridge-mcp 0.12.2 → 0.14.0

package/src/local/app-automation.mjs

@@ -9,9 +9,10 @@ const MAX_UI_ELEMENTS = 500;
 const MAX_UI_DEPTH = 12;
 const MAX_TEXT_CHARS = 4000;
 const APP_NAME_PATTERN = /^[^\0\r\n]{1,300}$/;
+const DEFAULT_APPLICATION_CACHE_MS = 30_000;
 
 export class AppAutomationManager {
-  constructor({ policy, displayPath, runProcess, readResourceText, throwIfCancelled = () => {}, platform = process.platform, home = homedir(), applicationRoots = null }) {
+  constructor({ policy, displayPath, runProcess, readResourceText, throwIfCancelled = () => {}, platform = process.platform, home = homedir(), applicationRoots = null, applicationCacheMs = DEFAULT_APPLICATION_CACHE_MS, now = () => Date.now() }) {
     this.policy = policy || {};
     this.displayPath = displayPath;
     this.runProcess = runProcess;
@@ -20,6 +21,9 @@ export class AppAutomationManager {
     this.platform = platform;
     this.home = home;
     this.applicationRoots = applicationRoots;
+    this.applicationCacheMs = Math.max(0, Number(applicationCacheMs) || 0);
+    this.now = now;
+    this.applicationCache = null;
   }
 
   capabilities() {
@@ -57,6 +61,16 @@ export class AppAutomationManager {
   }
 
   async discoverApplications(context = {}) {
+    const now = this.now();
+    if (this.applicationCache && now - this.applicationCache.createdAt < this.applicationCacheMs) {
+      return this.applicationCache.result;
+    }
+    const result = await this.scanApplications(context);
+    this.applicationCache = { createdAt: this.now(), result };
+    return result;
+  }
+
+  async scanApplications(context = {}) {
     if (this.platform === "darwin") {
       return listMacApplications(this.applicationRoots || ["/Applications", "/System/Applications", join(this.home, "Applications")], context, this.throwIfCancelled);
     }

package/src/local/browser-bridge.mjs

@@ -7,6 +7,11 @@ import { WebSocket, WebSocketServer } from "ws";
 import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { readBoundedRegularFileSync } from "./secure-file.mjs";
 import { assertStateMaintenanceAvailable, ownerOnlyFile, packageRoot } from "./state.mjs";
+import {
+  clampInt, normalizeBrowserAction, normalizeBrowserSelector, normalizeBrowserWait, normalizeFormAction,
+  normalizeInputMode, normalizeNavigationWait, normalizeTabCommand, optionalInteger, optionalString,
+  validateNavigationUrl,
+} from "./browser-command.mjs";
 
 const DEFAULT_PORT = 39393;
 const MAX_PORT_ATTEMPTS = 10;
@@ -18,6 +23,11 @@ const MAX_FIELD_VALUE_CHARS = 128 * 1024;
 const MAX_FORM_VALUE_BYTES = 4 * 1024 * 1024;
 const PAIRING_FILE = "browser-bridge.json";
 const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
+const BROWSER_EXTENSION_PROTOCOL = 2;
+const EXTENSION_HANDSHAKE_MS = 3_000;
+const REQUIRED_EXTENSION_CAPABILITIES = Object.freeze([
+  "semantic_snapshot_refs", "actionability_waits", "trusted_input", "tab_management", "explicit_waits",
+]);
 
 export class BrowserBridgeManager {
   constructor({ policy, stateRoot = "", runProcess, readResourceText, readResourceBinary, throwIfCancelled = () => {} }) {
@@ -30,10 +40,14 @@ export class BrowserBridgeManager {
     this.server = null;
     this.wss = null;
     this.socket = null;
+    this.pendingExtensionSocket = null;
     this.upstream = null;
     this.runtimeClients = new Set();
     this.proxyRoutes = new Map();
     this.proxyExtensionConnected = false;
+    this.extensionInfo = null;
+    this.proxyExtensionInfo = null;
+    this.proxyExtensionReloadRequired = false;
     this.recoveryTimer = null;
     this.stopping = false;
     this.pending = new Map();
@@ -47,16 +61,26 @@ export class BrowserBridgeManager {
     await this.ensureStarted(context);
     return {
       available: true,
-      connected: this.server ? this.socket?.readyState === 1 : this.proxyExtensionConnected,
+      connected: this.extensionConnected(),
       broker_role: this.server ? "owner" : this.upstream?.readyState === 1 ? "client" : "unavailable",
       endpoint: `ws://127.0.0.1:${this.port}/extension`,
       pairing_url: `http://127.0.0.1:${this.port}/pair`,
       extension_path: this.extensionPath,
+      extension_protocol: this.extensionStatusInfo()?.protocol || null,
+      extension_version: this.extensionStatusInfo()?.version || "",
+      extension_capabilities: this.extensionStatusInfo()?.capabilities || [],
+      extension_reload_required: this.extensionReloadRequired(),
       supported_browsers: ["Chrome", "Chromium", "Microsoft Edge", "Brave", "Vivaldi", "other Chromium browsers with Manifest V3"],
       controls_existing_profile: true,
       uses_existing_tabs_and_login_state: true,
       source_access: true,
+      semantic_snapshot_refs: true,
+      actionability_waits: true,
+      trusted_input: true,
+      input_modes: ["auto", "trusted", "dom"],
       complex_form_fill: true,
+      tab_management: true,
+      explicit_waits: true,
       screenshots: true,
       restricted_pages: ["browser-internal pages", "extension stores", "some PDF/plugin viewers", "pages blocked by enterprise policy"],
       security: {
@@ -86,6 +110,7 @@ export class BrowserBridgeManager {
         "Open the browser extensions page and enable developer mode.",
         "Load the unpacked extension from extension_path once.",
         "Open pairing_url; the installed extension stores the loopback endpoint and token locally.",
+        "After upgrades, reload the unpacked extension and accept any newly requested browser permission.",
       ],
     };
   }
@@ -98,6 +123,16 @@ export class BrowserBridgeManager {
     return response;
   }
 
+  async manageTabs(args = {}, context = {}) {
+    return this.request("manage_tabs", normalizeTabCommand(args), clampInt(args.timeout_seconds, 30, 1, 120), context);
+  }
+
+  async wait(args = {}, context = {}) {
+    const params = normalizeBrowserWait(args);
+    const conditionTimeoutSeconds = clampInt(args.timeout_seconds, 30, 1, 120);
+    return this.request("wait", params, conditionTimeoutSeconds + 5, context);
+  }
+
   async getSource(args = {}, context = {}) {
     const response = await this.request("get_source", {
       tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
@@ -130,17 +165,24 @@ export class BrowserBridgeManager {
       url: action === "navigate" ? validateNavigationUrl(rawUrl) : "",
       value: null,
       key: optionalString(args.key, "key", 100),
-      waitFor: normalizeWait(args.wait_for),
+      waitFor: normalizeNavigationWait(args.wait_for),
+      inputMode: normalizeInputMode(args.input_mode),
+      elementTimeoutMs: clampInt(args.element_timeout_seconds, 10, 1, 60) * 1000,
     };
     if (action !== "navigate" && rawUrl) throw new Error("url is only valid for navigate");
     if (action !== "press" && payload.key) throw new Error("key is only valid for press");
+    if (payload.inputMode === "trusted" && !["click", "double_click", "hover", "press", "type_text"].includes(action)) {
+      throw new Error("input_mode=trusted supports click, double_click, hover, press, and type_text only");
+    }
     if (args.value !== undefined) payload.value = boundedValue(args.value, "value");
     if (args.value_resource !== undefined) {
       if (payload.value !== null) throw new Error("value and value_resource are mutually exclusive");
       payload.value = boundedValue(await this.readResourceText(validateResource(args.value_resource)), "value_resource");
     }
-    if (payload.value !== null && !["fill", "select", "press"].includes(action)) throw new Error(`value is not valid for browser action '${action}'`);
-    const response = await this.request("action", payload, clampInt(args.timeout_seconds, 30, 1, 120), context);
+    if (payload.value !== null && !["fill", "select", "press", "type_text"].includes(action)) throw new Error(`value is not valid for browser action '${action}'`);
+    const pageAction = !["navigate", "reload", "back", "forward"].includes(action);
+    const defaultTimeout = pageAction ? Math.min(120, Math.max(30, payload.elementTimeoutMs / 1000 + 5)) : 30;
+    const response = await this.request("action", payload, clampInt(args.timeout_seconds, defaultTimeout, 1, 120), context);
     return {
       ...response,
       value_source: args.value_resource !== undefined ? "local-resource" : payload.value === null ? "none" : "mcp-argument",
@@ -170,6 +212,7 @@ export class BrowserBridgeManager {
       }
       const action = input.action === undefined ? "fill" : normalizeFormAction(input.action);
       if (value === null && !["check", "uncheck", "click"].includes(action)) throw new Error(`fields[${index}] requires value or value_resource`);
+      if (value !== null && !["fill", "select"].includes(action)) throw new Error(`fields[${index}] value is not valid for action '${action}'`);
       fields.push({
         selector: normalizeBrowserSelector(input.selector, action),
         value,
@@ -177,14 +220,16 @@ export class BrowserBridgeManager {
         sensitive: input.sensitive === true || input.value_resource !== undefined,
       });
     }
+    const elementTimeoutSeconds = clampInt(args.element_timeout_seconds, 10, 1, 60);
     return this.request("fill_form", {
       tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
       frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
       fields,
       submit: args.submit === true,
       submitSelector: args.submit_selector ? normalizeBrowserSelector(args.submit_selector, "click") : null,
-      waitFor: normalizeWait(args.wait_for),
-    }, clampInt(args.timeout_seconds, 60, 1, 180), context);
+      waitFor: normalizeNavigationWait(args.wait_for),
+      elementTimeoutMs: elementTimeoutSeconds * 1000,
+    }, clampInt(args.timeout_seconds, Math.max(60, elementTimeoutSeconds + 5), 1, 180), context);
   }
 
   async uploadFiles(args = {}, context = {}) {
@@ -208,12 +253,14 @@ export class BrowserBridgeManager {
         data: resource.buffer.toString("base64"),
       });
     }
+    const elementTimeoutSeconds = clampInt(args.element_timeout_seconds, 10, 1, 60);
     const result = await this.request("upload_files", {
       tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
       frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
       selector: normalizeBrowserSelector(args.selector, "fill"),
       files,
-    }, clampInt(args.timeout_seconds, 60, 1, 180), context);
+      elementTimeoutMs: elementTimeoutSeconds * 1000,
+    }, clampInt(args.timeout_seconds, Math.max(60, elementTimeoutSeconds + 5), 1, 180), context);
     return { ...result, resource_names: args.resources.map(String), resource_contents_exposed: false };
   }
 
@@ -244,7 +291,7 @@ export class BrowserBridgeManager {
     await this.ensureStarted(context);
     this.throwIfCancelled(context);
     const transport = this.server ? this.socket : this.upstream;
-    const extensionConnected = this.server ? this.socket?.readyState === 1 : this.proxyExtensionConnected;
+    const extensionConnected = this.extensionConnected();
     if (!transport || transport.readyState !== 1 || !extensionConnected) {
       throw new Error("browser extension is not connected; call pair_browser_extension after loading the packaged extension");
     }
@@ -368,12 +415,15 @@ export class BrowserBridgeManager {
         }
         const message = parsed.message;
         if (!settled) {
-          if (message.type !== "hello" || message.role !== "runtime") {
+          if (message.type !== "hello" || message.role !== "runtime" || message.protocol !== 1) {
             closeProtocolSocket(ws, 1002, "runtime hello required");
             return;
           }
           this.upstream = ws;
-          this.proxyExtensionConnected = message.extension_connected === true;
+          const claimedExtension = message.extension_connected === true;
+          this.proxyExtensionInfo = claimedExtension ? normalizeCompatibleExtensionInfo(message.extension_info) : null;
+          this.proxyExtensionConnected = claimedExtension && Boolean(this.proxyExtensionInfo);
+          this.proxyExtensionReloadRequired = message.extension_reload_required === true || (claimedExtension && !this.proxyExtensionInfo);
           finish(true);
           return;
         }
@@ -384,6 +434,8 @@ export class BrowserBridgeManager {
         if (this.upstream === ws) {
           this.upstream = null;
           this.proxyExtensionConnected = false;
+          this.proxyExtensionInfo = null;
+          this.proxyExtensionReloadRequired = false;
           this.rejectPending("browser broker disconnected");
           if (settled) this.scheduleBrokerRecovery();
         }
@@ -406,36 +458,79 @@ export class BrowserBridgeManager {
         }
       });
       ws.on("error", () => {});
-      safeSocketSend(ws, { type: "hello", role: "runtime", protocol: 1, extension_connected: this.socket?.readyState === 1 });
+      safeSocketSend(ws, {
+        type: "hello", role: "runtime", protocol: 1,
+        extension_connected: this.extensionConnected(),
+        extension_info: this.extensionStatusInfo(),
+        extension_reload_required: this.extensionReloadRequired(),
+      });
       return;
     }
-    if (this.socket && this.socket.readyState === 1) this.socket.close(4001, "superseded");
-    this.socket = ws;
+    if (this.pendingExtensionSocket && this.pendingExtensionSocket.readyState === 1) {
+      this.pendingExtensionSocket.close(4001, "superseded by a newer extension candidate");
+    }
+    this.pendingExtensionSocket = ws;
+    this.broadcastRuntimeStatus(this.extensionConnected());
+    ws.extensionReady = false;
+    ws.handshakeTimer = setTimeout(() => closeProtocolSocket(ws, 1002, "extension hello required; reload the extension"), EXTENSION_HANDSHAKE_MS);
+    ws.handshakeTimer.unref?.();
     ws.on("message", (data) => this.handleExtensionMessage(ws, data));
     ws.on("close", () => {
+      clearTimeout(ws.handshakeTimer);
+      if (this.pendingExtensionSocket === ws) {
+        this.pendingExtensionSocket = null;
+        this.broadcastRuntimeStatus(this.extensionConnected());
+        return;
+      }
       if (this.socket !== ws) return;
       this.socket = null;
+      this.extensionInfo = null;
       this.rejectPending("browser extension disconnected");
-      for (const [id, route] of this.proxyRoutes) {
-        clearTimeout(route.timeout);
-        try { route.socket.send(JSON.stringify({ type: "response", id: route.id, ok: false, error: "browser extension disconnected" })); } catch {}
-        this.proxyRoutes.delete(id);
-      }
+      this.rejectProxyRoutes("browser extension disconnected");
       this.broadcastRuntimeStatus(false);
     });
     ws.on("error", () => {});
-    safeSocketSend(ws, { type: "hello", role: "extension", protocol: 1 });
-    this.broadcastRuntimeStatus(true);
+    safeSocketSend(ws, { type: "hello", role: "extension", protocol: BROWSER_EXTENSION_PROTOCOL });
   }
 
   handleExtensionMessage(socket, data) {
-    if (this.socket !== socket) return;
+    if (this.socket !== socket && this.pendingExtensionSocket !== socket) return;
     const parsed = parseBrowserSocketMessage(data);
     if (!parsed.ok) {
       closeProtocolSocket(socket, parsed.code, parsed.reason);
       return;
     }
     const message = parsed.message;
+    if (message.type === "hello") {
+      if (socket.extensionReady) {
+        closeProtocolSocket(socket, 1002, "duplicate extension hello");
+        return;
+      }
+      let info;
+      try { info = parseExtensionHello(message); }
+      catch (error) {
+        closeProtocolSocket(socket, 1002, String(error?.message || error).slice(0, 120));
+        return;
+      }
+      clearTimeout(socket.handshakeTimer);
+      socket.extensionReady = true;
+      if (this.pendingExtensionSocket === socket) this.pendingExtensionSocket = null;
+      const previous = this.socket;
+      this.socket = socket;
+      this.extensionInfo = info;
+      if (previous && previous !== socket) {
+        this.rejectPending("browser extension was replaced; retry the browser request");
+        this.rejectProxyRoutes("browser extension was replaced; retry the browser request");
+        if (previous.readyState === 1) previous.close(4001, "superseded");
+      }
+      this.broadcastRuntimeStatus(true);
+      return;
+    }
+    if (!socket.extensionReady) {
+      closeProtocolSocket(socket, 1002, "extension hello required; reload the extension");
+      return;
+    }
+    if (message.type === "ping") return;
     if (message.type !== "response" || typeof message.id !== "string") {
       closeProtocolSocket(socket, 1002, "invalid extension protocol message");
       return;
@@ -476,7 +571,7 @@ export class BrowserBridgeManager {
       closeProtocolSocket(socket, 1002, "invalid runtime protocol message");
       return;
     }
-    if (!this.socket || this.socket.readyState !== 1) {
+    if (!this.extensionConnected()) {
       safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension is not connected" });
       return;
     }
@@ -511,7 +606,10 @@ export class BrowserBridgeManager {
 
   handleUpstreamMessage(message) {
     if (message.type === "status" && typeof message.extension_connected === "boolean") {
-      this.proxyExtensionConnected = message.extension_connected;
+      const claimedExtension = message.extension_connected === true;
+      this.proxyExtensionInfo = claimedExtension ? normalizeCompatibleExtensionInfo(message.extension_info) : null;
+      this.proxyExtensionConnected = claimedExtension && Boolean(this.proxyExtensionInfo);
+      this.proxyExtensionReloadRequired = message.extension_reload_required === true || (claimedExtension && !this.proxyExtensionInfo);
       if (!this.proxyExtensionConnected) this.rejectPending("browser extension disconnected");
       return true;
     }
@@ -526,7 +624,11 @@ export class BrowserBridgeManager {
   }
 
   broadcastRuntimeStatus(connected) {
-    const message = { type: "status", extension_connected: connected };
+    const message = {
+      type: "status", extension_connected: connected,
+      extension_info: connected ? this.extensionStatusInfo() : null,
+      extension_reload_required: this.extensionReloadRequired(),
+    };
     for (const client of this.runtimeClients) safeSocketSend(client, message);
   }
 
@@ -552,7 +654,7 @@ export class BrowserBridgeManager {
       return;
     }
     if (url.pathname === "/healthz") {
-      sendJson(response, { ok: true, connected: this.socket?.readyState === 1, broker: "machine-bridge-browser" });
+      sendJson(response, { ok: true, connected: this.extensionConnected(), broker: "machine-bridge-browser" });
       return;
     }
     if (url.pathname === "/pair") {
@@ -585,6 +687,14 @@ export class BrowserBridgeManager {
     this.pending.clear();
   }
 
+  rejectProxyRoutes(message) {
+    for (const [id, route] of this.proxyRoutes) {
+      clearTimeout(route.timeout);
+      safeSocketSend(route.socket, { type: "response", id: route.id, ok: false, error: message });
+      this.proxyRoutes.delete(id);
+    }
+  }
+
   stop() {
     this.stopping = true;
     clearTimeout(this.recoveryTimer);
@@ -592,9 +702,15 @@ export class BrowserBridgeManager {
     this.rejectPending("browser bridge stopped");
     try { this.upstream?.close(1001, "runtime stopped"); } catch {}
     try { this.socket?.close(1001, "runtime stopped"); } catch {}
+    try { this.pendingExtensionSocket?.close(1001, "runtime stopped"); } catch {}
     for (const client of this.runtimeClients) try { client.close(1001, "runtime stopped"); } catch {}
     this.upstream = null;
     this.socket = null;
+    this.pendingExtensionSocket = null;
+    this.extensionInfo = null;
+    this.proxyExtensionConnected = false;
+    this.proxyExtensionInfo = null;
+    this.proxyExtensionReloadRequired = false;
     this.runtimeClients.clear();
     for (const route of this.proxyRoutes.values()) clearTimeout(route.timeout);
     this.proxyRoutes.clear();
@@ -604,6 +720,22 @@ export class BrowserBridgeManager {
     this.server = null;
   }
 
+  extensionConnected() {
+    return this.server
+      ? this.socket?.readyState === 1 && Boolean(this.extensionInfo)
+      : this.upstream?.readyState === 1 && this.proxyExtensionConnected && Boolean(this.proxyExtensionInfo);
+  }
+
+  extensionStatusInfo() {
+    return this.server ? this.extensionInfo : this.proxyExtensionInfo;
+  }
+
+  extensionReloadRequired() {
+    return this.server
+      ? this.pendingExtensionSocket?.readyState === 1 && !this.extensionConnected()
+      : this.proxyExtensionReloadRequired;
+  }
+
   assertFull(tool) {
     if (this.policy.profile !== "full" || this.policy.execMode !== "shell" || this.policy.unrestrictedPaths !== true) {
       throw new Error(`${tool} requires the canonical full profile`);
@@ -611,6 +743,35 @@ export class BrowserBridgeManager {
   }
 }
 
+function normalizeCompatibleExtensionInfo(value) {
+  const info = normalizeExtensionInfo(value);
+  if (!info || info.protocol !== BROWSER_EXTENSION_PROTOCOL) return null;
+  if (REQUIRED_EXTENSION_CAPABILITIES.some((capability) => !info.capabilities.includes(capability))) return null;
+  return info;
+}
+
+function parseExtensionHello(message) {
+  if (message.role !== "extension" || message.protocol !== BROWSER_EXTENSION_PROTOCOL) {
+    throw new Error(`extension protocol mismatch; expected ${BROWSER_EXTENSION_PROTOCOL}; reload the extension`);
+  }
+  const info = normalizeExtensionInfo(message);
+  if (!info) throw new Error("invalid extension hello; reload the extension");
+  const missing = REQUIRED_EXTENSION_CAPABILITIES.filter((capability) => !info.capabilities.includes(capability));
+  if (missing.length) throw new Error(`extension capability mismatch; reload the extension (${missing.join(",")})`);
+  return info;
+}
+
+function normalizeExtensionInfo(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const protocol = Number(value.protocol);
+  const version = typeof value.version === "string" && value.version.length <= 100 ? value.version : "";
+  const capabilities = Array.isArray(value.capabilities)
+    ? [...new Set(value.capabilities.filter((entry) => typeof entry === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(entry)))].slice(0, 32)
+    : [];
+  if (!Number.isInteger(protocol) || protocol < 1 || !version) return null;
+  return { protocol, version, capabilities };
+}
+
 async function loadOrCreatePairing(stateRoot) {
   if (!stateRoot) return { token: randomBytes(32).toString("base64url"), port: DEFAULT_PORT };
   assertStateMaintenanceAvailable(stateRoot);
@@ -697,42 +858,6 @@ function sendJson(response, value) {
   response.end(`${JSON.stringify(value)}\n`);
 }
 
-function normalizeBrowserAction(value) {
-  const action = String(value || "").trim();
-  if (!["navigate", "click", "fill", "select", "check", "uncheck", "focus", "press", "submit", "reload", "back", "forward"].includes(action)) {
-    throw new Error("unsupported browser action");
-  }
-  return action;
-}
-
-function normalizeFormAction(value) {
-  const action = String(value || "").trim();
-  if (!["fill", "select", "check", "uncheck", "click"].includes(action)) throw new Error("unsupported form field action");
-  return action;
-}
-
-function normalizeBrowserSelector(value, action) {
-  if (["navigate", "reload", "back", "forward"].includes(action)) return null;
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("selector must be an object");
-  const allowed = new Set(["css", "id", "name", "label", "text", "role", "placeholder", "index"]);
-  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`unknown selector field: ${key}`);
-  const output = {};
-  for (const key of ["css", "id", "name", "label", "text", "role", "placeholder"]) {
-    if (value[key] !== undefined) output[key] = optionalString(value[key], `selector.${key}`, 2000);
-  }
-  if (value.index !== undefined) output.index = optionalInteger(value.index, "selector.index", 0, 10000);
-  if (!Object.keys(output).length) throw new Error("selector requires at least one field");
-  return output;
-}
-
-function validateNavigationUrl(value) {
-  if (!value) throw new Error("navigate requires url");
-  let parsed;
-  try { parsed = new URL(value); } catch { throw new Error("url must be an absolute URL"); }
-  if (!["http:", "https:", "file:"].includes(parsed.protocol)) throw new Error("url protocol must be http, https, or file");
-  return parsed.href;
-}
-
 function normalizeUploadFilename(value, { derived = false } = {}) {
   let name = String(value || "");
   if (derived) name = name.replace(/[\u0000-\u001f\u007f/\\]+/g, "_").trim();
@@ -760,13 +885,6 @@ function optionalStringArray(value, label, maxItems, maxLength) {
   });
 }
 
-function normalizeWait(value) {
-  if (value === undefined || value === null || value === "") return "none";
-  const wait = String(value);
-  if (!["none", "domcontentloaded", "complete"].includes(wait)) throw new Error("wait_for must be none, domcontentloaded, or complete");
-  return wait;
-}
-
 function boundedValue(value, label) {
   const string = String(value);
   if (string.includes("\0") || string.length > MAX_FIELD_VALUE_CHARS) throw new Error(`${label} exceeds the maximum length or contains a NUL byte`);
@@ -778,23 +896,3 @@ function validateResource(value) {
   if (!RESOURCE_NAME.test(name)) throw new Error("value_resource is invalid");
   return name;
 }
-
-function optionalString(value, label, maxLength) {
-  if (value === undefined || value === null || value === "") return "";
-  if (typeof value !== "string" || value.includes("\0") || value.length > maxLength) throw new Error(`${label} must be a string of at most ${maxLength} characters without NUL bytes`);
-  return value;
-}
-
-function optionalInteger(value, label, min, max) {
-  if (value === undefined || value === null || value === "") return null;
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < min || number > max) throw new Error(`${label} must be an integer from ${min} to ${max}`);
-  return number;
-}
-
-function clampInt(value, fallback, min, max) {
-  if (value === undefined || value === null || value === "") return fallback;
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < min || number > max) throw new Error(`expected an integer from ${min} to ${max}`);
-  return number;
-}

package/src/local/browser-command.mjs

@@ -0,0 +1,126 @@
+const NAVIGATION_ACTIONS = new Set(["navigate", "reload", "back", "forward"]);
+const PAGE_ACTIONS = new Set([
+  "click", "double_click", "hover", "fill", "type_text", "select", "check", "uncheck",
+  "focus", "press", "submit", "scroll_into_view",
+]);
+const FORM_ACTIONS = new Set(["fill", "select", "check", "uncheck", "click"]);
+const WAIT_STATES = new Set(["attached", "detached", "visible", "hidden", "enabled", "editable", "checked", "unchecked"]);
+const LOAD_STATES = new Set(["domcontentloaded", "complete"]);
+const INPUT_MODES = new Set(["auto", "trusted", "dom"]);
+
+export function normalizeBrowserAction(value) {
+  const action = String(value || "").trim();
+  if (!NAVIGATION_ACTIONS.has(action) && !PAGE_ACTIONS.has(action)) throw new Error("unsupported browser action");
+  return action;
+}
+
+export function normalizeFormAction(value) {
+  const action = String(value || "").trim();
+  if (!FORM_ACTIONS.has(action)) throw new Error("unsupported form field action");
+  return action;
+}
+
+export function normalizeBrowserSelector(value, action = "") {
+  if (NAVIGATION_ACTIONS.has(action)) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("selector must be an object");
+  const allowed = new Set(["ref", "css", "id", "name", "label", "text", "role", "placeholder", "index"]);
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`unknown selector field: ${key}`);
+  const output = {};
+  if (value.ref !== undefined) {
+    const ref = optionalString(value.ref, "selector.ref", 100);
+    if (ref) output.ref = ref;
+  }
+  for (const key of ["css", "id", "name", "label", "text", "role", "placeholder"]) {
+    if (value[key] === undefined) continue;
+    const normalized = optionalString(value[key], `selector.${key}`, 2000);
+    if (normalized) output[key] = normalized;
+  }
+  if (value.index !== undefined) output.index = optionalInteger(value.index, "selector.index", 0, 10000);
+  if (!Object.keys(output).length) throw new Error("selector requires at least one field");
+  if (output.ref && Object.keys(output).length !== 1) throw new Error("selector.ref cannot be combined with other selector fields");
+  return output;
+}
+
+export function normalizeInputMode(value) {
+  if (value === undefined || value === null || value === "") return "auto";
+  const mode = String(value);
+  if (!INPUT_MODES.has(mode)) throw new Error("input_mode must be auto, trusted, or dom");
+  return mode;
+}
+
+export function normalizeNavigationWait(value) {
+  if (value === undefined || value === null || value === "") return "none";
+  const wait = String(value);
+  if (!["none", ...LOAD_STATES].includes(wait)) throw new Error("wait_for must be none, domcontentloaded, or complete");
+  return wait;
+}
+
+export function normalizeBrowserWait(args = {}) {
+  const selector = args.selector === undefined ? null : normalizeBrowserSelector(args.selector, "wait");
+  const state = args.state === undefined || args.state === null || args.state === ""
+    ? (selector ? "visible" : "")
+    : String(args.state);
+  if (state && !WAIT_STATES.has(state)) throw new Error("state is not a supported browser wait state");
+  if (state && !selector) throw new Error("state requires selector");
+  const text = optionalString(args.text, "text", 4000);
+  const urlContains = optionalString(args.url_contains, "url_contains", 32768);
+  const loadState = args.load_state === undefined || args.load_state === null || args.load_state === "" ? "" : String(args.load_state);
+  if (loadState && !LOAD_STATES.has(loadState)) throw new Error("load_state must be domcontentloaded or complete");
+  if (!selector && !text && !urlContains && !loadState) throw new Error("browser_wait requires selector, text, url_contains, or load_state");
+  const timeoutSeconds = clampInt(args.timeout_seconds, 30, 1, 120);
+  return {
+    tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
+    frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
+    selector,
+    state,
+    text,
+    urlContains,
+    loadState,
+    timeoutMs: timeoutSeconds * 1000,
+  };
+}
+
+export function normalizeTabCommand(args = {}) {
+  const action = String(args.action || "").trim();
+  if (!["new", "activate", "close"].includes(action)) throw new Error("browser tab action must be new, activate, or close");
+  const tabId = optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER);
+  const rawUrl = optionalString(args.url, "url", 32768);
+  if (["activate", "close"].includes(action) && !tabId) throw new Error(`${action} requires tab_id`);
+  if (action !== "new" && rawUrl) throw new Error("url is only valid for new tabs");
+  return {
+    action,
+    tabId,
+    url: rawUrl ? validateNavigationUrl(rawUrl) : "",
+    active: args.active !== false,
+  };
+}
+
+export function validateNavigationUrl(value) {
+  if (!value) throw new Error("navigate requires url");
+  let parsed;
+  try { parsed = new URL(value); } catch { throw new Error("url must be an absolute URL"); }
+  if (!["http:", "https:", "file:"].includes(parsed.protocol)) throw new Error("url protocol must be http, https, or file");
+  return parsed.href;
+}
+
+export function optionalString(value, label, maxLength) {
+  if (value === undefined || value === null || value === "") return "";
+  if (typeof value !== "string" || value.includes("\0") || value.length > maxLength) {
+    throw new Error(`${label} must be a string of at most ${maxLength} characters without NUL bytes`);
+  }
+  return value;
+}
+
+export function optionalInteger(value, label, min, max) {
+  if (value === undefined || value === null || value === "") return null;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < min || number > max) throw new Error(`${label} must be an integer from ${min} to ${max}`);
+  return number;
+}
+
+export function clampInt(value, fallback, min, max) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < min || number > max) throw new Error(`expected an integer from ${min} to ${max}`);
+  return number;
+}