machine-bridge-mcp 0.8.2 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.10.0 - 2026-07-12
+
+### Session context and capability selection
+
+- Add a global `model_instructions_file` in `~/.config/machine-bridge-mcp/agent.json`. Stdio and remote MCP initialization append the bounded user-designated instructions when the local runtime is reachable; `session_bootstrap` exposes the same content explicitly. Project manifests cannot override the global file.
+- Add `resolve_task_capabilities`, which rescans effective instructions, filesystem skills, and registered commands for every task, returns a refresh fingerprint, ranks relevant capabilities, optionally loads the best skill, and recommends application/browser/file/Git/process tools. Newly added or edited skills are visible without daemon restart or dynamic MCP tool registration. Multilingual tokenization avoids weak single-character Chinese overlap when automatically selecting a skill.
+- Preserve the host boundary: Machine Bridge automates discovery, refresh, ranking, and progressive loading, while the ChatGPT/MCP host still decides whether a tool is exposed, approved, or invoked.
+
+### Existing-profile browser and local applications
+
+- Add a packaged Manifest V3 Chromium extension and authenticated loopback machine broker for the user's existing browser profile, windows, tabs, cookies, extensions, and login state. Multiple workspace or stdio runtimes share one extension connection through authenticated broker clients.
+- Add structured browser tools for tab listing, current DOM source, frame-aware and open-Shadow-DOM interactive-element inspection, navigation/actions, complex multi-field forms, visible screenshots, and resource-backed file inputs. Page operations run through a fixed packaged module injected into the target frame rather than caller-provided or service-worker-closure code. Registered local resources can provide sensitive field text or upload bytes without returning those values through MCP results.
+- Add installed-application discovery/opening and structured macOS Accessibility inspection/actions. The implementation uses fixed JXA code and does not accept caller-supplied JavaScript, AppleScript, JXA, or browser-extension source. Application paths are normalized to process names, selector indices apply to filtered matches, Linux desktop launchers use `gio launch`, Windows discovery prioritizes Start Menu launchers, and secure Accessibility fields never return values.
+- Add `machine-mcp browser status|setup|pair|path` for one-time unpacked-extension setup and diagnosis. Pairing tokens remain in owner-only state and non-cacheable loopback HTML rather than MCP output, browser URL fragments, or operational logs. Established pairing is replacement-locked and requires a browser-action click on the active local pairing page before switching broker state. The extension badge reports connection state and its action opens the saved pairing page; signed browser-store packaging is the intended mass-market distribution path.
+
+### Architecture, security, and verification
+
+- Split agent context, application automation, and browser broker into dedicated local domain modules while retaining one static catalog shared by Worker and stdio. Bound Worker initialization bootstrap to a short failure-tolerant daemon call.
+- Add loopback Host validation, extension-origin checks, authenticated extension/runtime WebSocket subprotocols, bounded messages/concurrency/source/forms/uploads, proxy timeout/cancellation cleanup, restricted-page handling, secret/value/result non-disclosure, and full-profile gating. Treat the owner-only browser pairing file as a recognized state-root entry so safe uninstall remains available.
+- Extend version synchronization to the browser-extension manifest and add broker owner/client proxy, pairing-token, resource-upload, stdio initialization, live skill refresh, and remote initialization regression coverage. Update architecture, security, operations, logging, privacy, testing, client, release, and user documentation.
+
+## 0.9.0 - 2026-07-12
+
+### Agent context and local workflows
+
+- Add `agent_context`, a bounded bootstrap tool with Codex-compatible instruction precedence: unrestricted `CODEX_HOME`/`~/.codex` guidance, then project root-to-target scopes, selecting the first non-empty `AGENTS.override.md` or `AGENTS.md` candidate per directory under a default 32 KiB combined budget. Add hierarchical `.machine-bridge/agent.json` manifests plus an optional unrestricted user manifest at `~/.config/machine-bridge-mcp/agent.json` for custom candidate priority and bounds.
+- Add `list_local_skills` and `load_local_skill` with Codex-style progressive disclosure. Default discovery scans target-to-root `.agents/skills`, unrestricted user/admin roots, and canonicalized symlinked skill directories; invalid metadata is skipped with bounded warnings. Skill loading returns instructions and a relative file inventory without implicitly executing scripts.
+- Add `list_local_commands` and direct-argv `run_local_command`. Nearest manifests can override or remove inherited commands, caller arguments require manifest opt-in, and callers cannot increase the manifest timeout ceiling.
+
+### Architecture, security, and tests
+
+- Extract agent discovery into `AgentContextManager` rather than expanding transport or runtime dispatch responsibilities. Keep a static MCP catalog across Worker and stdio transports so host-side caching and filtering do not require dynamic per-skill tools.
+- Reject escaping instruction/config paths, unknown manifest fields, out-of-policy skill symlink targets, symbolic-link skill entrypoints, ambiguous skill names, oversized content/argv, and execution attempts under non-execution profiles. Document that repository instructions and skills are untrusted content and that registered commands are convenience aliases, not a sandbox or approval boundary.
+- Add regression coverage for global/project override selection, empty-candidate fallback, custom priority, instruction-byte ceilings, target-to-root skill discovery, symlinked skill folders, invalid metadata warnings, command override/removal, literal argument handling without shell parsing, timeout ceilings, path escape denial, and execution-profile denial. Update server instructions, architecture, security, testing, and operator documentation for the new bootstrap workflow.
+
 ## 0.8.2 - 2026-07-11
 
 ### Relay reliability and protocol correctness

package/README.md

@@ -108,6 +108,38 @@ machine-mcp stdio --workspace /path/to/project
 
 The stdio server writes only JSON-RPC messages to stdout and operational logs to stderr. See [docs/CLIENTS.md](docs/CLIENTS.md) for the host/model distinction and transport trade-offs.
 
+## Session instructions, local skills, commands, apps, and browser
+
+Machine Bridge loads a user-selected global instruction file and repository-specific guidance without changing the static MCP catalog. Configure the global file in `~/.config/machine-bridge-mcp/agent.json`:
+
+```json
+{
+  "version": 1,
+  "model_instructions_file": "~/.config/machine-bridge-mcp/MODEL.md"
+}
+```
+
+The file is prepended to MCP initialization instructions for every new stdio or remote session when the local runtime is reachable. `session_bootstrap` exposes the same material explicitly. `agent_context` adds target-specific `AGENTS.override.md`/`AGENTS.md` precedence, and `resolve_task_capabilities` rescans skills and registered commands for the current task, ranks matches, optionally loads the best skill, and recommends relevant local tools.
+
+Skill discovery follows Codex-style progressive disclosure. Default roots are target-to-project `.agents/skills`; unrestricted policy also enables user/admin roots. Newly added or edited skills are found on the next resolver/list call without restarting the daemon. A project can customize instruction candidates, skill roots, and direct-argv registered commands with `.machine-bridge/agent.json`. See [Session instructions, skills, commands, and capability discovery](docs/AGENT_CONTEXT.md).
+
+Under canonical `full`, Machine Bridge also exposes structured local automation:
+
+- installed application discovery/opening and macOS Accessibility inspection/actions;
+- a packaged Chromium extension that controls the user's existing daily browser profile, active tabs, login state, and windows;
+- current DOM source and frame/open-Shadow-DOM inspection, structured page actions, complex multi-field forms, resource-backed secret fields, resource-backed file uploads, and screenshots.
+
+One-time browser setup:
+
+```sh
+machine-mcp browser setup
+machine-mcp browser status
+```
+
+Load the printed unpacked-extension directory once in Chrome, Edge, Brave, Vivaldi, or another compatible Chromium browser. The extension badge reports connection state, and clicking it opens the saved local pairing page. The local pairing token remains in owner-only state and the loopback pairing page; it is not returned through MCP. For a mass-market release, distribute the same extension as a signed browser-store build rather than asking end users to enable Developer mode. See [Local application and browser automation](docs/LOCAL_AUTOMATION.md).
+
+Machine Bridge can discover, refresh, rank, and load capabilities automatically. The ChatGPT/MCP host still owns tool selection and approval, so the server cannot force a host to expose or invoke a recommended skill, command, app, or browser operation.
+
 ## Policy controls
 
 The default is `full`. Narrow or customize it with explicit flags:
@@ -233,6 +265,12 @@ The exact `tools/list` response reflects the active local policy. Definitions co
 
 - `server_info`
 - `project_overview`
+- `session_bootstrap` — session/global instructions and capability refresh metadata
+- `agent_context` — effective instructions, skill summaries, and registered commands for a target path
+- `resolve_task_capabilities` — live skill/command ranking and local automation recommendations
+- `list_local_skills`
+- `load_local_skill` — load instructions and file inventory without implicit execution
+- `list_local_commands`
 - `list_roots`
 - `list_dir`
 - `list_files`
@@ -240,6 +278,23 @@ The exact `tools/list` response reflects the active local policy. Definitions co
 - `view_image` — bounded PNG, JPEG, GIF, or WebP as native MCP image content
 - `search_text`
 
+### Local applications and browser (`full`)
+
+- `list_local_applications`
+- `open_local_application`
+- `inspect_local_application` — bounded macOS Accessibility tree
+- `operate_local_application` — structured Accessibility action, no arbitrary script source
+- `browser_status`
+- `pair_browser_extension`
+- `browser_list_tabs`
+- `browser_get_source` — bounded current DOM HTML, including selected frames
+- `browser_inspect_page`
+- `browser_action`
+- `browser_fill_form`
+- `browser_upload_files` — registered local resources to file inputs
+- `browser_screenshot`
+
+
 ### Mutation
 
 - `write_file` — atomic whole-file write with create-only and SHA-256 checks
@@ -270,6 +325,7 @@ Managed jobs are non-interactive and persist independently of the MCP connection
 
 ### Processes
 
+- `run_local_command` — direct argv execution of a manifest-registered command
 - `run_process` — one-shot argv execution without a shell
 - `start_process`
 - `read_process`
@@ -299,6 +355,7 @@ machine-mcp status
 machine-mcp doctor
 machine-mcp rotate-secrets
 machine-mcp resource add|list|check|remove
+machine-mcp browser status|setup|pair|path
 machine-mcp job submit|inspect|approve|list|read|cancel
 machine-mcp --print-mcp-credentials
 machine-mcp uninstall [--keep-worker] [--yes]
@@ -350,7 +407,7 @@ npm pack --dry-run
 
 `npm run check` covers privacy and release-impact gates, architecture/link invariants, generated Worker types, TypeScript, JavaScript syntax, catalog-to-runtime handler parity, deterministic relay lifecycle and secure-file tests, local path/write/process/state/log/service invariants, Ed25519/RSA generation and key-pair validation, real-machine `full` sandbox acceptance, a clean npm package-manifest/sensitive-artifact check, managed-job integrity/redaction/finally/cancellation/recovery, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with the pinned Node 26/npm 12 baseline; macOS and package-audit jobs also exercise the documented isolated global installation.
 
-See [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
+See [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/LOCAL_AUTOMATION.md](docs/LOCAL_AUTOMATION.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
 
 ## Uninstall
 

package/SECURITY.md

@@ -51,6 +51,28 @@ The default for newly selected workspaces is `full`, which prioritizes ease of u
 
 For untrusted repositories or instructions, run the bridge inside a disposable VM/container or under a dedicated low-privilege OS account. On macOS and Windows, this external isolation is especially important. The project does not claim an in-process OS sandbox.
 
+## Agent instructions, skills, and command manifests
+
+Repository and user instruction files are untrusted content from the model's perspective. `agent_context` returns their text in deterministic precedence order but does not certify correctness or safety. A malicious `AGENTS.md`, custom instruction file, or `SKILL.md` can attempt prompt injection or recommend destructive operations. Use only trusted repositories and skill roots, or isolate the bridge externally.
+
+Skill loading is non-executing. `load_local_skill` returns an entrypoint and bounded file inventory; scripts remain inert until a separate process or command tool is called. Symlinked skill directories are followed only after canonical path-policy validation, while symbolic-link `SKILL.md` entrypoints are rejected. Traversal, cycles, content, summaries, and inventory are bounded.
+
+Registered commands are available only under direct-execution-capable policy. They use argv spawning rather than shell parsing, reject undeclared caller arguments, and enforce the manifest timeout as a ceiling. They are not an approval or sandbox boundary: a repository-controlled package script, interpreter, compiler, or executable can still run arbitrary code with local-user authority. Deeper manifests can override or remove inherited commands, so callers must obtain context for the actual target path rather than assuming the repository-root registry applies everywhere.
+
+The remote MCP host remains an independent boundary. Machine Bridge can advertise these tools, append `model_instructions_file` during initialization, and recommend capabilities through `resolve_task_capabilities`, but it cannot force a host to preserve instructions, expose tools, approve calls, or invoke them.
+
+The global `model_instructions_file` is an explicit user trust decision. It is read for every profile and sent to the authorized host during session initialization; do not place credentials, private records, or content inappropriate for every connected session in it. Project manifests cannot override this global file. Other global manifest fields that would widen local scope are ignored under workspace-confined profiles.
+
+## Browser and application automation
+
+Canonical `full` exposes structured browser and desktop UI authority. The browser extension operates the user's existing Chromium profile, including active login state, and has broad host access so it can inspect arbitrary pages and fill complex forms. An authorized client may therefore read page content, click controls, submit forms, upload registered files, and cause transactions with the user's browser identity. macOS Accessibility actions similarly operate applications with the local user's UI authority.
+
+The browser loopback broker validates loopback `Host`, requires a random owner-only bearer subprotocol, accepts extension sockets only with a `chrome-extension://` origin, and authenticates additional local runtimes separately. Initial extension pairing is trust-on-first-use; after pairing, a different localhost page cannot replace the stored broker unless the user clicks the extension action while the genuine pairing page is active. The pairing token is never returned by MCP or written to operational logs. These controls defend against casual cross-origin and DNS-rebinding access; they do not protect against malicious code already running as the same OS user or a compromised browser extension profile.
+
+Caller-supplied JavaScript, AppleScript, and JXA source are deliberately unsupported. Actions use fixed implementation code and structured selectors. This removes an avoidable arbitrary-evaluation surface but does not make DOM or Accessibility actions safe. Pages can contain prompt injection, misleading labels, hidden consequences, cross-origin frames unavailable to inspection, or state that changes between inspection and submission. High-impact account, financial, legal, medical, publishing, deletion, and purchase actions require contextual review and any host/user confirmation the client provides.
+
+Text and file resources can be injected locally so their contents do not appear in MCP arguments or results. The destination page/application still receives the value, and remote tool metadata/results still traverse the Worker and host. Page source and screenshots can themselves contain secrets. Browser/app tool arguments, source, screenshots, field values, and results are intentionally omitted from operational logs.
+
 ## Filesystem exposure
 
 Direct filesystem scope is profile-dependent. The default `full` profile is unrestricted. The `agent`, `edit`, and `review` profiles confine direct filesystem tools to the canonical selected workspace, including symbolic-link resolution.

package/browser-extension/manifest.json

@@ -0,0 +1,33 @@
+{
+  "manifest_version": 3,
+  "name": "Machine Bridge Browser",
+  "version": "0.10.0",
+  "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
+  "permissions": [
+    "tabs",
+    "scripting",
+    "storage",
+    "alarms"
+  ],
+  "host_permissions": [
+    "<all_urls>"
+  ],
+  "background": {
+    "service_worker": "service-worker.js"
+  },
+  "content_scripts": [
+    {
+      "matches": [
+        "http://127.0.0.1/*"
+      ],
+      "js": [
+        "pairing.js"
+      ],
+      "run_at": "document_idle"
+    }
+  ],
+  "action": {
+    "default_title": "Machine Bridge Browser"
+  },
+  "version_name": "0.10.0"
+}

package/browser-extension/page-automation.js

@@ -0,0 +1,246 @@
+(() => {
+  if (globalThis.__machineBridgePageAutomation) return;
+
+  const INTERACTIVE_SELECTOR = "a,button,input,select,textarea,[role],[contenteditable='true'],summary";
+  const MAX_SHADOW_ROOTS = 200;
+
+  function collectRoots() {
+    const roots = [document];
+    for (let index = 0; index < roots.length && roots.length <= MAX_SHADOW_ROOTS; index += 1) {
+      const root = roots[index];
+      for (const element of root.querySelectorAll("*")) {
+        if (element.shadowRoot && !roots.includes(element.shadowRoot)) roots.push(element.shadowRoot);
+        if (roots.length > MAX_SHADOW_ROOTS) break;
+      }
+    }
+    return roots;
+  }
+
+  function deepQuerySelectorAll(selector) {
+    const results = [];
+    for (const root of collectRoots()) results.push(...root.querySelectorAll(selector));
+    return results;
+  }
+
+  function rootById(element, id) {
+    const root = element.getRootNode?.();
+    if (root && typeof root.getElementById === "function") return root.getElementById(id);
+    return document.getElementById(id);
+  }
+
+  function inspect(params) {
+    const maxElements = Number(params.maxElements) || 300;
+    const includeValues = params.includeValues === true;
+    const all = deepQuerySelectorAll(INTERACTIVE_SELECTOR);
+    const candidates = all.slice(0, maxElements);
+    return {
+      document: {
+        title: document.title,
+        url: location.href,
+        language: document.documentElement.lang || "",
+        forms: deepQuerySelectorAll("form").length,
+        open_shadow_roots: Math.max(0, collectRoots().length - 1),
+      },
+      elements: candidates.map((element, index) => describeElement(element, index, includeValues)),
+      truncated: all.length > candidates.length,
+    };
+  }
+
+  function action(params) {
+    const element = findElement(params.selector);
+    if (!element) throw new Error("no element matched selector");
+    applyOne(element, params.action, params.value, params.key);
+    return { ok: true, element: describeElement(element, 0, false) };
+  }
+
+  function fillForm(params) {
+    const results = [];
+    for (let index = 0; index < params.fields.length; index += 1) {
+      const field = params.fields[index];
+      const element = findElement(field.selector);
+      if (!element) throw new Error(`no element matched fields[${index}] selector`);
+      applyOne(element, field.action, field.value, "");
+      results.push({ index, action: field.action, sensitive: field.sensitive === true, element: describeElement(element, index, false) });
+    }
+    if (params.submit) {
+      const submitter = params.submitSelector ? findElement(params.submitSelector) : deepQuerySelectorAll("button[type='submit'],input[type='submit']")[0];
+      if (submitter) submitter.click();
+      else {
+        const field = params.fields.length ? findElement(params.fields[0].selector) : null;
+        const form = field?.form || field?.closest?.("form") || deepQuerySelectorAll("form")[0];
+        if (!form) throw new Error("no form or submit control found");
+        if (typeof form.requestSubmit === "function") form.requestSubmit();
+        else form.submit();
+      }
+    }
+    return { ok: true, fields: results, submitted: params.submit === true, values_exposed: false };
+  }
+
+  function uploadFiles(params) {
+    const input = findElement(params.selector);
+    if (!(input instanceof HTMLInputElement) || input.type !== "file") throw new Error("matched element is not a file input");
+    const transfer = new DataTransfer();
+    for (const item of params.files) {
+      const binary = atob(item.data);
+      const bytes = new Uint8Array(binary.length);
+      for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+      transfer.items.add(new File([bytes], item.filename, { type: item.mime || "application/octet-stream" }));
+    }
+    input.files = transfer.files;
+    dispatchValueEvents(input);
+    return { ok: true, file_count: transfer.files.length, values_exposed: false };
+  }
+
+  function describeElement(element, index, includeValues) {
+    const tag = element.tagName.toLowerCase();
+    const type = String(element.getAttribute("type") || "").toLowerCase();
+    const sensitive = isSensitiveElement(element, tag, type);
+    const item = {
+      index,
+      tag,
+      type,
+      role: element.getAttribute("role") || implicitRole(element),
+      name: accessibleName(element),
+      id: element.id || "",
+      field_name: element.getAttribute("name") || "",
+      label: labelText(element),
+      placeholder: element.getAttribute("placeholder") || "",
+      disabled: Boolean(element.disabled),
+      checked: "checked" in element ? Boolean(element.checked) : null,
+      selected: tag === "select" ? element.value : null,
+      href: tag === "a" ? element.href : "",
+      sensitive,
+      in_shadow_dom: element.getRootNode?.() instanceof ShadowRoot,
+    };
+    if (includeValues && !sensitive && "value" in element) item.value = String(element.value || "").slice(0, 2000);
+    return item;
+  }
+
+  function isSensitiveElement(element, tag, type) {
+    if (tag !== "input" && tag !== "textarea") return false;
+    if (["password", "hidden"].includes(type)) return true;
+    const autocomplete = String(element.getAttribute("autocomplete") || "").toLowerCase();
+    if (/(?:password|one-time-code|cc-number|cc-csc|cc-exp)/.test(autocomplete)) return true;
+    const identity = `${element.id || ""} ${element.getAttribute("name") || ""} ${element.getAttribute("aria-label") || ""} ${element.getAttribute("placeholder") || ""}`.toLowerCase();
+    return /(?:password|passwd|secret|token|api[-_ ]?key|otp|one[-_ ]?time|verification|cvc|cvv|security[-_ ]?code|card[-_ ]?number)/.test(identity);
+  }
+
+  function applyOne(element, operation, value, key) {
+    element.scrollIntoView({ block: "center", inline: "nearest" });
+    if (operation === "click") { element.click(); return; }
+    if (operation === "focus") { element.focus(); return; }
+    if (operation === "submit") {
+      const form = element.form || element.closest("form");
+      if (!form) throw new Error("matched element is not associated with a form");
+      if (typeof form.requestSubmit === "function") form.requestSubmit(); else form.submit();
+      return;
+    }
+    if (operation === "check" || operation === "uncheck") {
+      if (!("checked" in element)) throw new Error("matched element is not checkable");
+      const wanted = operation === "check";
+      if (Boolean(element.checked) !== wanted) element.click();
+      return;
+    }
+    if (operation === "select") {
+      if (!(element instanceof HTMLSelectElement)) throw new Error("matched element is not a select control");
+      const text = String(value ?? "");
+      const option = [...element.options].find((item) => item.value === text || item.text.trim() === text);
+      if (!option) throw new Error("select option was not found");
+      element.value = option.value;
+      dispatchValueEvents(element);
+      return;
+    }
+    if (operation === "fill") {
+      if (!("value" in element) && !element.isContentEditable) throw new Error("matched element is not editable");
+      element.focus();
+      if (element.isContentEditable) element.textContent = String(value ?? "");
+      else setNativeValue(element, String(value ?? ""));
+      dispatchValueEvents(element);
+      return;
+    }
+    if (operation === "press") {
+      const pressed = String(key || value || "Enter");
+      element.focus();
+      element.dispatchEvent(new KeyboardEvent("keydown", { key: pressed, bubbles: true, composed: true }));
+      element.dispatchEvent(new KeyboardEvent("keyup", { key: pressed, bubbles: true, composed: true }));
+      return;
+    }
+    throw new Error(`unsupported element action: ${operation}`);
+  }
+
+  function setNativeValue(element, value) {
+    const prototype = element instanceof HTMLTextAreaElement
+      ? HTMLTextAreaElement.prototype
+      : element instanceof HTMLSelectElement
+        ? HTMLSelectElement.prototype
+        : HTMLInputElement.prototype;
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, "value");
+    if (descriptor?.set) descriptor.set.call(element, value);
+    else element.value = value;
+  }
+
+  function dispatchValueEvents(element) {
+    element.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
+    element.dispatchEvent(new Event("change", { bubbles: true, composed: true }));
+  }
+
+  function findElement(selector) {
+    let elements = [];
+    if (selector.css) elements = deepQuerySelectorAll(selector.css);
+    else if (selector.id) elements = deepQuerySelectorAll(`[id="${cssEscape(selector.id)}"]`);
+    else elements = deepQuerySelectorAll(INTERACTIVE_SELECTOR);
+    elements = elements.filter((element) => {
+      if (selector.name && element.getAttribute("name") !== selector.name) return false;
+      if (selector.label && !sameText(labelText(element), selector.label)) return false;
+      if (selector.text && !sameText(element.innerText || element.textContent || "", selector.text)) return false;
+      if (selector.role && !sameText(element.getAttribute("role") || implicitRole(element), selector.role)) return false;
+      if (selector.placeholder && !sameText(element.getAttribute("placeholder") || "", selector.placeholder)) return false;
+      return true;
+    });
+    return elements[Number.isInteger(selector.index) ? selector.index : 0] || null;
+  }
+
+  function cssEscape(value) {
+    if (globalThis.CSS?.escape) return globalThis.CSS.escape(String(value));
+    return String(value).replace(/["\\]/g, "\\$&");
+  }
+
+  function sameText(left, right) {
+    return String(left || "").trim().replace(/\s+/g, " ").toLowerCase() === String(right || "").trim().replace(/\s+/g, " ").toLowerCase();
+  }
+
+  function labelText(element) {
+    if (element.labels?.length) return [...element.labels].map((label) => label.innerText || label.textContent || "").join(" ").trim();
+    const parent = element.closest("label");
+    if (parent) return (parent.innerText || parent.textContent || "").trim();
+    const labelledBy = element.getAttribute("aria-labelledby");
+    if (labelledBy) return labelledBy.split(/\s+/).map((id) => rootById(element, id)?.textContent || "").join(" ").trim();
+    return "";
+  }
+
+  function accessibleName(element) {
+    return (element.getAttribute("aria-label") || labelText(element) || element.getAttribute("title") || element.getAttribute("alt") || element.innerText || element.textContent || "")
+      .trim().replace(/\s+/g, " ").slice(0, 500);
+  }
+
+  function implicitRole(element) {
+    const tag = element.tagName.toLowerCase();
+    if (tag === "a" && element.hasAttribute("href")) return "link";
+    if (tag === "button") return "button";
+    if (tag === "textarea") return "textbox";
+    if (tag === "select") return "combobox";
+    if (tag === "input") {
+      const type = String(element.type || "text").toLowerCase();
+      if (["button", "submit", "reset"].includes(type)) return "button";
+      if (type === "checkbox") return "checkbox";
+      if (type === "radio") return "radio";
+      return "textbox";
+    }
+    return "";
+  }
+
+  Object.defineProperty(globalThis, "__machineBridgePageAutomation", {
+    value: Object.freeze({ inspect, action, fillForm, uploadFiles }),
+    configurable: true,
+  });
+})();

package/browser-extension/pairing.js

@@ -0,0 +1,19 @@
+(() => {
+  const marker = document.querySelector('meta[name="machine-bridge-browser-pair"]');
+  const portMeta = document.querySelector('meta[name="machine-bridge-browser-port"]');
+  const tokenMeta = document.querySelector('meta[name="machine-bridge-browser-token"]');
+  if (!marker || !portMeta || !tokenMeta) return;
+  const token = tokenMeta.content;
+  const port = Number(portMeta.content);
+  if (!/^[A-Za-z0-9_-]{32,100}$/.test(token) || !Number.isInteger(port) || port < 1024 || port > 65535) return;
+  chrome.runtime.sendMessage({ type: "pair", endpoint: `ws://127.0.0.1:${port}/extension`, token }, (response) => {
+    const status = document.getElementById("status");
+    if (chrome.runtime.lastError || response?.ok !== true) {
+      if (status) status.textContent = response?.requires_manual_repair
+        ? "This extension is already paired to different local state. Click the Machine Bridge extension icon while this page is active to confirm re-pairing."
+        : "Pairing failed. Confirm the local Machine Bridge runtime is running, then reload this page.";
+      return;
+    }
+    if (status) status.textContent = "Paired. You may close this tab.";
+  });
+})();