machine-bridge-mcp 1.1.5 → 1.2.1

package/src/local/browser-operation-service.mjs

@@ -0,0 +1,325 @@
+import {
+  clampInt, normalizeBrowserAction, normalizeBrowserSelector, normalizeBrowserWait, normalizeFormAction,
+  normalizeInputMode, normalizeNavigationWait, normalizeTabCommand, optionalInteger, optionalString,
+  validateNavigationUrl,
+} from "./browser-command.mjs";
+
+const MAX_SOURCE_BYTES = 4 * 1024 * 1024;
+const MAX_FORM_FIELDS = 200;
+const MAX_FIELD_VALUE_CHARS = 128 * 1024;
+const MAX_FORM_VALUE_BYTES = 4 * 1024 * 1024;
+const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
+
+export class BrowserOperationService {
+  constructor({
+    authorizeTool,
+    ensureStarted,
+    request,
+    bridgeStatus,
+    extensionPath,
+    expectedExtensionVersion,
+    runProcess,
+    readResourceText,
+    readResourceBinary,
+  }) {
+    this.authorizeTool = authorizeTool;
+    this.ensureStarted = ensureStarted;
+    this.request = request;
+    this.bridgeStatus = bridgeStatus;
+    this.extensionPath = extensionPath;
+    this.expectedExtensionVersion = expectedExtensionVersion;
+    this.runProcess = runProcess;
+    this.readResourceText = readResourceText;
+    this.readResourceBinary = readResourceBinary;
+  }
+
+  async status(context = {}) {
+    this.authorizeTool("browser_status");
+    await this.ensureStarted(context);
+    const bridge = this.bridgeStatus();
+    const extension = bridge.extensionInfo;
+    return {
+      available: true,
+      connected: bridge.extensionConnected,
+      broker_role: bridge.brokerRole,
+      endpoint: `ws://127.0.0.1:${bridge.port}/extension`,
+      pairing_url: `http://127.0.0.1:${bridge.port}/pair`,
+      extension_path: this.extensionPath,
+      expected_extension_version: this.expectedExtensionVersion,
+      extension_protocol: extension?.protocol || null,
+      extension_version: extension?.version || "",
+      extension_capabilities: extension?.capabilities || [],
+      extension_reload_required: bridge.extensionReloadRequired,
+      supported_browsers: ["Chrome", "Chromium", "Microsoft Edge", "Brave", "Vivaldi", "other Chromium browsers with Manifest V3"],
+      controls_existing_profile: true,
+      controls_extension_profile: true,
+      launches_browser_process: false,
+      launches_separate_automation_profile: false,
+      profile_identity_verifiable: false,
+      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: {
+        loopback_only: true,
+        bearer_pairing_token: true,
+        arbitrary_extension_code_from_mcp: false,
+        resource_values_returned_to_model: false,
+      },
+    };
+  }
+
+  async pair(args = {}, context = {}) {
+    this.authorizeTool("pair_browser_extension");
+    const status = await this.status(context);
+    if (args.open !== false) {
+      const command = process.platform === "darwin"
+        ? { cmd: "open", argv: [status.pairing_url] }
+        : process.platform === "win32"
+          ? { cmd: "cmd.exe", argv: ["/d", "/s", "/c", "start", "", status.pairing_url] }
+          : { cmd: "xdg-open", argv: [status.pairing_url] };
+      await this.runProcess(command.cmd, command.argv, 30_000, false, 128 * 1024, context);
+    }
+    return {
+      ...status,
+      opened_pairing_page: args.open !== false,
+      setup_steps: [
+        "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.",
+      ],
+    };
+  }
+
+  async listTabs(args = {}, context = {}) {
+    this.authorizeTool("browser_list_tabs");
+    return this.request("list_tabs", {
+      currentWindow: args.current_window === true,
+      includePinned: args.include_pinned !== false,
+    }, clampInt(args.timeout_seconds, 30, 1, 120), context);
+  }
+
+  async manageTabs(args = {}, context = {}) {
+    this.authorizeTool("browser_manage_tabs");
+    return this.request("manage_tabs", normalizeTabCommand(args), clampInt(args.timeout_seconds, 30, 1, 120), context);
+  }
+
+  async wait(args = {}, context = {}) {
+    this.authorizeTool("browser_wait");
+    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 = {}) {
+    this.authorizeTool("browser_get_source");
+    return this.request("get_source", {
+      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
+      frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
+      allFrames: args.all_frames === true,
+      maxBytes: clampInt(args.max_bytes, 1024 * 1024, 1, MAX_SOURCE_BYTES),
+    }, clampInt(args.timeout_seconds, 30, 1, 120), context);
+  }
+
+  async inspectPage(args = {}, context = {}) {
+    this.authorizeTool("browser_inspect_page");
+    return this.request("inspect_page", {
+      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
+      frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
+      allFrames: args.all_frames !== false,
+      maxElements: clampInt(args.max_elements, 300, 1, 1000),
+      includeValues: args.include_values === true,
+    }, clampInt(args.timeout_seconds, 30, 1, 120), context);
+  }
+
+  async act(args = {}, context = {}) {
+    this.authorizeTool("browser_action");
+    const action = normalizeBrowserAction(args.action);
+    const rawUrl = optionalString(args.url, "url", 32768);
+    const payload = {
+      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
+      frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
+      action,
+      selector: normalizeBrowserSelector(args.selector, action),
+      url: action === "navigate" ? validateNavigationUrl(rawUrl) : "",
+      value: null,
+      key: optionalString(args.key, "key", 100),
+      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", "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",
+      value_exposed: false,
+    };
+  }
+
+  async fillForm(args = {}, context = {}) {
+    this.authorizeTool("browser_fill_form");
+    if (!Array.isArray(args.fields) || !args.fields.length) throw new Error("fields must be a non-empty array");
+    if (args.fields.length > MAX_FORM_FIELDS) throw new Error(`fields contains more than ${MAX_FORM_FIELDS} entries`);
+    const fields = [];
+    let totalValueBytes = 0;
+    for (let index = 0; index < args.fields.length; index += 1) {
+      const input = args.fields[index];
+      if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`fields[${index}] must be an object`);
+      const allowed = new Set(["selector", "value", "value_resource", "action", "sensitive"]);
+      for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`unknown fields[${index}] property: ${key}`);
+      let value = input.value === undefined ? null : boundedValue(input.value, `fields[${index}].value`);
+      if (input.value_resource !== undefined) {
+        if (value !== null) throw new Error(`fields[${index}] value and value_resource are mutually exclusive`);
+        value = boundedValue(await this.readResourceText(validateResource(input.value_resource)), `fields[${index}].value_resource`);
+      }
+      if (value !== null) {
+        totalValueBytes += Buffer.byteLength(value);
+        if (totalValueBytes > MAX_FORM_VALUE_BYTES) throw new Error("form field values exceed 4 MiB total");
+      }
+      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,
+        action,
+        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: normalizeNavigationWait(args.wait_for),
+      elementTimeoutMs: elementTimeoutSeconds * 1000,
+    }, clampInt(args.timeout_seconds, Math.max(60, elementTimeoutSeconds + 5), 1, 180), context);
+  }
+
+  async uploadFiles(args = {}, context = {}) {
+    this.authorizeTool("browser_upload_files");
+    if (!Array.isArray(args.resources) || !args.resources.length || args.resources.length > 8) {
+      throw new Error("resources must contain 1 to 8 registered resource names");
+    }
+    const filenames = optionalStringArray(args.filenames, "filenames", 8, 255);
+    const mimeTypes = optionalStringArray(args.mime_types, "mime_types", 8, 200);
+    if (filenames.length > args.resources.length || mimeTypes.length > args.resources.length) {
+      throw new Error("filenames and mime_types cannot contain more entries than resources");
+    }
+    const files = [];
+    let total = 0;
+    for (const raw of args.resources) {
+      const name = validateResource(raw);
+      const resource = this.readResourceBinary(name);
+      total += resource.buffer.length;
+      if (total > 5 * 1024 * 1024) throw new Error("browser upload resources exceed 5 MiB total");
+      const suppliedFilename = filenames[files.length];
+      const derivedFilename = resource.path.split(/[\\/]/).pop() || name;
+      files.push({
+        filename: normalizeUploadFilename(suppliedFilename || derivedFilename, { derived: !suppliedFilename }),
+        mime: normalizeMimeType(mimeTypes[files.length] || "application/octet-stream"),
+        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,
+      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 };
+  }
+
+  async screenshot(args = {}, context = {}) {
+    this.authorizeTool("browser_screenshot");
+    const result = await this.request("screenshot", {
+      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
+      format: args.format === "jpeg" ? "jpeg" : "png",
+      quality: clampInt(args.quality, 90, 1, 100),
+    }, clampInt(args.timeout_seconds, 30, 1, 120), context);
+    const data = String(result.data || "");
+    const match = /^data:(image\/(?:png|jpeg));base64,([A-Za-z0-9+/=]+)$/.exec(data);
+    if (!match) throw new Error("browser extension returned an invalid screenshot");
+    return {
+      $mcp: {
+        content: [{ type: "image", data: match[2], mimeType: match[1] }],
+        structuredContent: {
+          tab_id: result.tab_id,
+          url: result.url,
+          title: result.title,
+          mime_type: match[1],
+        },
+      },
+    };
+  }
+}
+
+function normalizeUploadFilename(value, { derived = false } = {}) {
+  let name = String(value || "");
+  if (derived) name = name.replace(/[\u0000-\u001f\u007f/\\]+/g, "_").trim();
+  if (!name || name === "." || name === ".." || name.length > 255 || /[\u0000-\u001f\u007f/\\]/.test(name)) {
+    if (derived) return "upload.bin";
+    throw new Error("filenames entries must be safe single-component filenames of at most 255 characters");
+  }
+  return name;
+}
+
+function normalizeMimeType(value) {
+  const mime = String(value || "").trim().toLowerCase();
+  if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mime) || mime.length > 200) {
+    throw new Error("mime_types entries must be valid media types");
+  }
+  return mime;
+}
+
+function optionalStringArray(value, label, maxItems, maxLength) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.length > maxItems) throw new Error(`${label} must be an array with at most ${maxItems} entries`);
+  return value.map((item, index) => {
+    if (typeof item !== "string" || item.includes("\0") || !item.length || item.length > maxLength) {
+      throw new Error(`${label}[${index}] must be a non-empty string of at most ${maxLength} characters`);
+    }
+    return item;
+  });
+}
+
+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`);
+  }
+  return string;
+}
+
+function validateResource(value) {
+  const name = String(value || "").trim();
+  if (!RESOURCE_NAME.test(name)) throw new Error("value_resource is invalid");
+  return name;
+}

package/src/local/call-registry.mjs

@@ -1,24 +1,59 @@
+// @ts-check
+
 import { randomBytes } from "node:crypto";
 import { performance } from "node:perf_hooks";
 import { BridgeError } from "./errors.mjs";
 
+/** @typedef {ReturnType<typeof setTimeout>} TimerHandle */
+/**
+ * @typedef {{
+ *   id: string,
+ *   tool: string,
+ *   origin: string,
+ *   startedAt: number,
+ *   deadlineAt: number | null,
+ *   controller: AbortController,
+ *   cancelReason: string,
+ *   timer: TimerHandle | null,
+ * }} CallRecord
+ */
+/**
+ * @typedef {{
+ *   maximum?: unknown,
+ *   now?: () => number,
+ *   scheduler?: {setTimeout: typeof setTimeout, clearTimeout: typeof clearTimeout},
+ *   onCancel?: (record: CallRecord) => void,
+ *   onFinish?: (record: CallRecord) => void,
+ * }} CallRegistryOptions
+ */
+/**
+ * @typedef {{callId?: unknown, tool?: unknown, origin?: unknown, timeoutMs?: unknown}} OpenCallInput
+ */
+/** @typedef {{signal?: AbortSignal, callId?: unknown}} CancellationContext */
+
 export class CallRegistry {
+  /** @param {CallRegistryOptions} [options] */
   constructor(options = {}) {
     this.maximum = positiveInteger(options.maximum, 16);
     this.now = typeof options.now === "function" ? options.now : () => performance.now();
     this.scheduler = options.scheduler || { setTimeout, clearTimeout };
     this.onCancel = typeof options.onCancel === "function" ? options.onCancel : () => {};
     this.onFinish = typeof options.onFinish === "function" ? options.onFinish : () => {};
+    /** @type {Map<string, CallRecord>} */
     this.calls = new Map();
   }
 
+  /** @param {OpenCallInput} [input] */
   open({ callId = "", tool = "", origin = "local", timeoutMs = 0 } = {}) {
     const id = String(callId || `call_${randomBytes(16).toString("hex")}`);
     if (this.calls.has(id)) throw new BridgeError("conflict", "duplicate in-flight call id");
-    if (this.calls.size >= this.maximum) throw new BridgeError("limit_exceeded", `too many concurrent tool calls (${this.maximum})`, { retryable: true });
+    if (this.calls.size >= this.maximum) {
+      throw new BridgeError("limit_exceeded", `too many concurrent tool calls (${this.maximum})`, { retryable: true });
+    }
     const controller = new AbortController();
     const startedAt = this.now();
     const timeout = positiveInteger(timeoutMs, 0);
+    /** @type {CallRecord} */
     const record = {
       id,
       tool: String(tool || ""),
@@ -44,6 +79,7 @@ export class CallRegistry {
     });
   }
 
+  /** @param {unknown} callId @param {unknown} [reason] @param {string} [code] */
   cancel(callId, reason = "cancelled", code = "cancelled") {
     const record = this.calls.get(String(callId || ""));
     if (!record || record.controller.signal.aborted) return false;
@@ -53,6 +89,7 @@ export class CallRegistry {
     return true;
   }
 
+  /** @param {unknown} callId */
   finish(callId) {
     const id = String(callId || "");
     const record = this.calls.get(id);
@@ -63,6 +100,7 @@ export class CallRegistry {
     return true;
   }
 
+  /** @param {unknown} origin @param {unknown} [reason] */
   cancelOrigin(origin, reason = "transport disconnected") {
     const expected = String(origin || "");
     let cancelled = 0;
@@ -73,6 +111,7 @@ export class CallRegistry {
     return cancelled;
   }
 
+  /** @param {unknown} [reason] */
   cancelAll(reason = "runtime stopped") {
     for (const id of [...this.calls.keys()]) {
       this.cancel(id, reason);
@@ -80,6 +119,7 @@ export class CallRegistry {
     }
   }
 
+  /** @param {unknown} callId */
   context(callId) {
     const record = this.calls.get(String(callId || ""));
     if (!record) return null;
@@ -93,6 +133,7 @@ export class CallRegistry {
     };
   }
 
+  /** @param {CancellationContext} [context] */
   throwIfCancelled(context = {}) {
     const signal = context.signal || this.calls.get(String(context.callId || ""))?.controller.signal;
     if (!signal?.aborted) return;
@@ -103,6 +144,7 @@ export class CallRegistry {
 
   snapshot() {
     const now = this.now();
+    /** @type {Record<string, number>} */
     const byOrigin = {};
     let oldestMs = 0;
     for (const call of this.calls.values()) {
@@ -118,6 +160,7 @@ export class CallRegistry {
   }
 }
 
+/** @param {unknown} value @param {number} fallback */
 function positiveInteger(value, fallback) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;

package/src/local/capability-ranking.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 const TOKEN_STOP_WORDS = new Set(["the", "and", "for", "with", "from", "this", "that", "use", "using", "into", "of", "to", "a", "an", "in", "on", "is", "are", "or", "及", "和", "的", "了", "在", "用", "使用", "进行", "根据"]);
 const ENGLISH_TOKEN_CANONICAL = new Map([
   ["created", "create"], ["creating", "create"], ["creation", "create"], ["creator", "create"],
@@ -9,6 +10,7 @@ const ENGLISH_TOKEN_CANONICAL = new Map([
   ["factcheck", "verify"], ["fact-check", "verify"], ["testing", "test"], ["tests", "test"],
   ["building", "build"], ["built", "build"], ["deployment", "deploy"], ["deployed", "deploy"],
 ]);
+/** @type {ReadonlyArray<readonly [RegExp, readonly string[]]>} */
 const HAN_TOKEN_ALIASES = Object.freeze([
   [/创建|新建|编写/u, ["create", "creator"]],
   [/改进|优化|更新|维护/u, ["improve", "update"]],
@@ -29,10 +31,14 @@ const HAN_TOKEN_ALIASES = Object.freeze([
   [/安全|漏洞/u, ["security", "audit"]],
 ]);
 
+/**
+ * @param {{name: string, description: string, argv: string[], searchTerms?: string}} command
+ */
 export function commandMatchText(command) {
   return `${command.name} ${command.description} ${command.argv.join(" ")} ${command.searchTerms || ""}`;
 }
 
+/** @param {unknown} task @param {unknown} candidate @param {unknown} [identity] */
 export function relevanceScore(task, candidate, identity = "") {
   const taskTokens = tokenize(task);
   const candidateTokens = tokenize(candidate);
@@ -51,6 +57,10 @@ export function relevanceScore(task, candidate, identity = "") {
   return score;
 }
 
+/**
+ * @param {unknown} task
+ * @param {{commandsAvailable: boolean, commandRelevant: boolean, skillRelevant: boolean}} options
+ */
 export function recommendTools(task, { commandsAvailable, commandRelevant, skillRelevant }) {
   const lower = String(task || "").toLowerCase();
   const tools = ["agent_context"];
@@ -64,6 +74,7 @@ export function recommendTools(task, { commandsAvailable, commandRelevant, skill
   return [...new Set(tools)];
 }
 
+/** @param {unknown} value @returns {Set<string>} */
 export function tokenize(value) {
   const text = String(value || "").toLowerCase();
   const tokens = new Set();
@@ -86,6 +97,7 @@ export function tokenize(value) {
   return tokens;
 }
 
+/** @param {unknown} value */
 function comparableText(value) {
   return String(value || "")
     .toLowerCase()
@@ -94,6 +106,7 @@ function comparableText(value) {
     .replace(/\s+/g, " ");
 }
 
+/** @param {Set<string>} tokens @param {unknown} raw */
 function addToken(tokens, raw) {
   const token = String(raw || "").replace(/^[.-]+|[.-]+$/g, "");
   if (token.length < 2 || TOKEN_STOP_WORDS.has(token)) return;

package/src/local/cli-local-admin.mjs

@@ -25,17 +25,17 @@ export function createLocalAdminCommands(dependencies) {
   });
 }
 
-const RESOURCE_ACTION_HANDLERS = Object.freeze({
-  list: resourceListAction,
-  add: resourceAddAction,
-  "generate-ssh-key": resourceGenerateSshKeyAction,
-  remove: resourceRemoveAction,
-  check: resourceCheckAction,
-});
+const RESOURCE_ACTION_HANDLERS = new Map([
+  ["list", resourceListAction],
+  ["add", resourceAddAction],
+  ["generate-ssh-key", resourceGenerateSshKeyAction],
+  ["remove", resourceRemoveAction],
+  ["check", resourceCheckAction],
+]);
 
 async function resourceCommand(args, { chooseWorkspace }) {
   const action = String(args._[0] || "list").toLowerCase();
-  const handler = RESOURCE_ACTION_HANDLERS[action];
+  const handler = RESOURCE_ACTION_HANDLERS.get(action);
   if (!handler) throw new Error(`Unknown resource action: ${action}`);
   const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
   const state = loadState(workspace, { stateDir: args.stateDir });
@@ -155,7 +155,7 @@ async function resourceRemoveAction({ args, workspace, state }) {
 
 function resourceCheckAction({ args, state }) {
   const name = validateResourceName(args._[1]);
-  const resource = state.resources[name];
+  const resource = Object.hasOwn(state.resources, name) ? state.resources[name] : null;
   if (!resource) throw new Error(`local resource is not registered: ${name}`);
   const inspected = inspectResourceFile(resource.path, { allowInsecurePermissions: resource.allowInsecurePermissions === true });
   const result = publicResourceInspection(name, inspected, { includePath: args.showPaths === true });
@@ -181,15 +181,47 @@ function publicResourceInspection(name, inspected, { includePath = false, ...ext
   };
 }
 
-async function browserCommand(args, { chooseWorkspace }) {
+const BROWSER_ACTION_HANDLERS = new Map([
+  ["path", browserPathAction],
+  ["status", browserStatusAction],
+  ["setup", browserPairAction],
+  ["pair", browserPairAction],
+]);
+
+async function browserCommand(args, dependencies) {
   const action = String(args._[0] || "status").toLowerCase();
+  const handler = BROWSER_ACTION_HANDLERS.get(action);
+  if (!handler) throw new Error(`Unknown browser action: ${action}`);
+  return handler(args, dependencies);
+}
+
+function browserPathAction(args) {
   const extensionPath = resolve(packageRoot, "browser-extension");
-  if (action === "path") {
-    if (args.json) console.log(JSON.stringify({ extension_path: extensionPath }, null, 2));
-    else console.log(extensionPath);
+  if (args.json) console.log(JSON.stringify({ extension_path: extensionPath }, null, 2));
+  else console.log(extensionPath);
+}
+
+async function browserStatusAction(args, { chooseWorkspace }) {
+  const context = await browserCommandContext(args, chooseWorkspace);
+  renderBrowserStatus(context.result, args.json === true);
+}
+
+async function browserPairAction(args, { chooseWorkspace }) {
+  const context = await browserCommandContext(args, chooseWorkspace);
+  if (!context.result.running) throw new Error("browser bridge is not reachable; keep machine-mcp running and retry");
+  await openExternal(context.pairingUrl);
+  if (args.json) {
+    console.log(JSON.stringify({ ...context.result, pairing_page_opened: true }, null, 2));
     return;
   }
-  if (!["status", "setup", "pair"].includes(action)) throw new Error(`Unknown browser action: ${action}`);
+  console.log(`Extension path: ${context.extensionPath}`);
+  console.log("Load this directory in the Chromium profile you use every day; Machine Bridge does not install it into Playwright or a separate automation profile.");
+  console.log("Enable Developer mode, choose Load unpacked, and reload the extension after each Machine Bridge upgrade.");
+  console.log(`Pairing page opened: ${context.pairingUrl}`);
+}
+
+async function browserCommandContext(args, chooseWorkspace) {
+  const extensionPath = resolve(packageRoot, "browser-extension");
   const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
   const state = loadState(workspace, { stateDir: args.stateDir });
   const pairingFile = join(state.paths.stateRoot, "browser-bridge.json");
@@ -197,6 +229,13 @@ async function browserCommand(args, { chooseWorkspace }) {
     throw new Error("browser bridge is not initialized; start machine-mcp once, then run this command again");
   }
   ownerOnlyFile(pairingFile);
+  const pairing = readBrowserPairingState(pairingFile);
+  const pairingUrl = `http://127.0.0.1:${pairing.port}/pair`;
+  const health = await readBrowserHealth(`http://127.0.0.1:${pairing.port}/healthz`);
+  return { extensionPath, pairingUrl, result: browserStatusResult(health, extensionPath, pairingUrl) };
+}
+
+function readBrowserPairingState(pairingFile) {
   let pairing;
   try {
     pairing = JSON.parse(readBoundedRegularFileSync(pairingFile, 64 * 1024).toString("utf8"));
@@ -206,12 +245,17 @@ async function browserCommand(args, { chooseWorkspace }) {
   const port = Number(pairing.port);
   if (!/^[A-Za-z0-9_-]{32,100}$/.test(String(pairing.token || ""))) throw new Error("browser bridge state contains an invalid token");
   if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("browser bridge state contains an invalid port");
-  const pairingUrl = `http://127.0.0.1:${port}/pair`;
-  const healthUrl = `http://127.0.0.1:${port}/healthz`;
-  const health = await fetch(healthUrl, { signal: AbortSignal.timeout(2000), cache: "no-store" })
+  return { port };
+}
+
+function readBrowserHealth(healthUrl) {
+  return fetch(healthUrl, { signal: AbortSignal.timeout(2000), cache: "no-store" })
     .then(async (response) => response.ok ? await response.json() : null)
     .catch(() => null);
-  const result = {
+}
+
+function browserStatusResult(health, extensionPath, pairingUrl) {
+  return {
     running: health?.ok === true && health?.broker === "machine-bridge-browser",
     connected: health?.broker === "machine-bridge-browser" && health?.connected === true,
     extension_path: extensionPath,
@@ -227,28 +271,20 @@ async function browserCommand(args, { chooseWorkspace }) {
     profile_identity_verifiable: health?.profile_identity_verifiable === true,
     token_exposed: false,
   };
-  if (action === "status") {
-    if (args.json) console.log(JSON.stringify(result, null, 2));
-    else {
-      console.log(`Browser bridge: ${result.running ? "running" : "not reachable"}`);
-      console.log(`Extension: ${result.connected ? "connected" : result.extension_reload_required ? "reload required" : "not connected"}`);
-      if (result.expected_extension_version) console.log(`Expected extension build: ${result.expected_extension_version}`);
-      if (result.extension_version || result.extension_protocol) console.log(`Connected extension build: ${result.extension_version || "unknown"} (protocol ${result.extension_protocol ?? "unknown"})`);
-      console.log(`Browser profile: ${result.controls_extension_profile ? "the Chromium profile where this extension is installed" : "unknown"}`);
-      if (result.controls_extension_profile) console.log(`Profile provenance: Machine Bridge did not launch the browser; daily-vs-isolated profile identity is not machine-verifiable.`);
-      console.log(`Extension path: ${extensionPath}`);
-    }
+}
+
+function renderBrowserStatus(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
     return;
   }
-  if (!result.running) throw new Error("browser bridge is not reachable; keep machine-mcp running and retry");
-  await openExternal(pairingUrl);
-  if (args.json) console.log(JSON.stringify({ ...result, pairing_page_opened: true }, null, 2));
-  else {
-    console.log(`Extension path: ${extensionPath}`);
-    console.log("Load this directory in the Chromium profile you use every day; Machine Bridge does not install it into Playwright or a separate automation profile.");
-    console.log("Enable Developer mode, choose Load unpacked, and reload the extension after each Machine Bridge upgrade.");
-    console.log(`Pairing page opened: ${pairingUrl}`);
-  }
+  console.log(`Browser bridge: ${result.running ? "running" : "not reachable"}`);
+  console.log(`Extension: ${result.connected ? "connected" : result.extension_reload_required ? "reload required" : "not connected"}`);
+  if (result.expected_extension_version) console.log(`Expected extension build: ${result.expected_extension_version}`);
+  if (result.extension_version || result.extension_protocol) console.log(`Connected extension build: ${result.extension_version || "unknown"} (protocol ${result.extension_protocol ?? "unknown"})`);
+  console.log(`Browser profile: ${result.controls_extension_profile ? "the Chromium profile where this extension is installed" : "unknown"}`);
+  if (result.controls_extension_profile) console.log("Profile provenance: Machine Bridge did not launch the browser; daily-vs-isolated profile identity is not machine-verifiable.");
+  console.log(`Extension path: ${result.extension_path}`);
 }
 
 function openExternal(target) {