machine-bridge-mcp 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.11.0 - 2026-07-12
+
+### Zero-configuration agent working agreements
+
+- Add a package-controlled `machine-bridge://defaults/working-agreements` instruction layer so every stdio and remote MCP session starts with conservative, auditable guidance even when the user and repository provide no `MODEL.md`, `AGENTS.md`, or manifest. The baseline covers inspect-before-editing, minimal coherent changes, preservation of unrelated work, existing-toolchain reuse, tests/documentation synchronization, honest validation reporting, secret handling, safe Git practice, and explicit authorization for publication, deployment, credential rotation, live-data mutation, system-wide installation, and destructive operations.
+- Keep the baseline lower precedence than explicit user and root-to-target project instructions. Expose its source, size, hash, precedence, and optional content through `session_bootstrap`, `agent_context`, and `resolve_task_capabilities`; include its hash in live capability fingerprints. The defaults are behavioral guidance rather than a replacement for Machine Bridge policy, host approvals, operating-system permissions, hooks, sandboxes, or external isolation.
+
+### Bounded automatic project context
+
+- Add `machine-bridge://project-context/current`, regenerated on every relevant context scan from bounded repository metadata: target-relative path, recognized project/build entry files, JavaScript package-manager and lockfile facts, package script names, runtime constraints/version hints, common documentation files, and CI entrypoint filenames. The scanner executes nothing, writes no user or repository files, omits script bodies, dependency values, source/document contents, absolute home paths, and command output, and never claims a declared command was validated.
+- Harden repository-controlled metadata with strict character/count/byte limits, no-follow regular-file reads, safe workflow-name filtering, independent 16 KiB output bounds, and conservative skipping of symbolic links, invalid UTF-8, oversized files, permission failures, and transient metadata races. Add user-global `builtin_instructions` and `automatic_project_context` boolean opt-outs; project manifests cannot disable the user's baseline controls.
+
+### Documentation and verification
+
+- Document the default instruction model, precedence, opt-outs, privacy data surface, security boundary, recommended `AGENTS.md` content, progressive disclosure, and official cross-agent best-practice sources. Update repository automation guidance, shared MCP tool descriptions, initialization instructions, architecture, clients, logging, privacy, security, testing, and package contents.
+- Add regression coverage for no-file defaults, initialization injection over stdio, automatic project refresh/fingerprints, package-manager/lockfile/script/CI discovery, script-body non-disclosure, hostile metadata filtering, global opt-out, project opt-out rejection, precedence, and packaged-module presence.
+
+## 0.10.1 - 2026-07-12
+
+### Foreground startup and upgrade takeover
+
+- Make a normal `machine-mcp` start reliably take over from an active platform autostart daemon: detect whether the service is active, request shutdown, wait up to 15 seconds for the workspace daemon lock to be released, and then continue foreground startup with the newly installed CLI. A failed bounded takeover now exits with explicit `service stop`/`service status` recovery guidance instead of silently leaving the old process in place.
+- Record foreground/background mode and package version in new daemon locks. A genuine lock conflict now identifies the running mode/version when known, explains how to stop it, and no longer prints the misleading `[ok] ready` block when no restart or requested change occurred. Service-style duplicate starts remain silent idempotent successes.
+
+### Global instructions and operator guidance
+
+- Add copy-paste setup instructions for `~/.config/machine-bridge-mcp/agent.json` and the global `MODEL.md`, explain global-versus-project precedence, live rescanning, and when a new MCP conversation/reconnection is needed for initialization-time injection.
+- Document the foreground/background distinction, safe global upgrade sequence, owner-only instruction-file permissions, background log locations, and the exact optional-dependency install command that avoids the development-only `fsevents` warning.
+
+## 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

package/README.md

@@ -51,7 +51,7 @@ Node.js 26 or newer and npm 12 or newer are required. The repository pins the ac
 npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
 ```
 
-Recent npm releases may otherwise warn that Wrangler's native dependencies (`esbuild`, `workerd`, and `sharp`) have install scripts awaiting approval. The scoped command approves the reviewed native script names that npm 12 evaluates during global resolution while `--omit=optional` keeps optional `fsevents` out of the installed runtime. `fsevents` is used for development-time filesystem watching rather than Machine Bridge runtime or deployment. It does not change the user's global npm policy. `machine-mcp doctor` remains the authoritative runtime check.
+Recent npm releases may otherwise warn that Wrangler's native dependencies (`esbuild`, `workerd`, and `sharp`) have install scripts awaiting approval. The scoped command approves the reviewed native script names that npm 12 evaluates during global resolution while `--omit=optional` keeps optional `fsevents` out of the installed runtime. `fsevents` is used for development-time filesystem watching rather than Machine Bridge runtime or deployment. Omitting `--omit=optional` can therefore produce a harmless blocked-script warning for `fsevents@2.3.3`; use the documented command rather than changing global npm policy. `machine-mcp doctor` remains the authoritative runtime check.
 
 From a source checkout, the checked-in exact-version `allowScripts` policy approves the reviewed native dependencies:
 
@@ -79,6 +79,17 @@ On first remote start, the CLI:
 6. starts an outbound-only daemon connection;
 7. prints the Remote MCP URL and connection password.
 
+A normal `machine-mcp` invocation is a foreground start: it remains attached to the terminal and prints `info` logs. If an older autostart daemon is active after a global package upgrade, the CLI stops that service, waits up to 15 seconds for its workspace lock, and then starts the newly installed version in the foreground. A genuine foreground conflict is left untouched and reported with actionable guidance. To run only in the background, use `machine-mcp service start`; inspect its owner-only logs under `~/.local/state/machine-bridge-mcp/logs/`.
+
+Recommended upgrade sequence:
+
+```sh
+npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+machine-mcp --verbose
+```
+
+The global install replaces files on disk but cannot hot-reload an already running Node process; the second command performs the bounded service takeover. If takeover fails, run `machine-mcp service stop`, confirm with `machine-mcp service status`, and retry.
+
 Use the printed values in the MCP client:
 
 ```text
@@ -108,36 +119,58 @@ 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.
 
-## Agent instructions, local skills, and command registry
+## Session instructions, local skills, commands, apps, and browser
+
+Machine Bridge now starts with useful agent guidance even when the user has not created `MODEL.md`, `AGENTS.md`, or `.machine-bridge/agent.json`.
 
-For substantive workspace tasks, clients can call `agent_context` for the relevant file or directory. Its default instruction discovery mirrors Codex: under unrestricted policy it first checks `CODEX_HOME` or `~/.codex`, then walks from the project root to the target directory, selecting the first non-empty `AGENTS.override.md` or `AGENTS.md` in each scope. Deeper guidance has higher precedence, and the default combined budget is 32 KiB.
+Two lower-precedence virtual sources are generated in memory:
 
-Skill discovery also follows Codex-style progressive disclosure. By default, Machine Bridge scans `.agents/skills` from the target directory through the project root; unrestricted policy additionally enables `~/.agents/skills` and, on Unix-like systems, `/etc/codex/skills`. `agent_context` initially returns bounded metadata, while `load_local_skill` returns the selected `SKILL.md` and file inventory without executing anything implicitly.
+- `machine-bridge://defaults/working-agreements` supplies conservative cross-project rules for inspection, scoped changes, preservation of unrelated work, validation, security, Git discipline, and explicit authorization for deployment/publication/destructive operations.
+- `machine-bridge://project-context/current` derives bounded facts from the active repository: target path, common project/build files, package-manager declarations and lockfiles, package script names, runtime constraints, documentation files, and CI entrypoints. It never injects package-script bodies or source contents and does not claim commands were validated.
 
-A project can add custom instruction candidates, explicit skill roots, and registered commands with `.machine-bridge/agent.json`:
+No files are created or modified by this bootstrap. Explicit user and repository instructions load later and therefore override the defaults. `session_bootstrap` supplies the chain during MCP initialization; `agent_context` exposes every source and hash; `resolve_task_capabilities` refreshes project facts, instructions, skills, and commands for the current task.
+
+Optional user-global preferences still live in `~/.config/machine-bridge-mcp/agent.json`:
 
 ```json
 {
   "version": 1,
-  "instruction_files": [
-    "PROJECT.override.md",
-    "AGENTS.override.md",
-    "AGENTS.md"
-  ],
-  "instruction_max_bytes": 65536,
-  "commands": {
-    "check": {
-      "description": "Run repository validation.",
-      "argv": ["npm", "run", "check"],
-      "cwd": ".",
-      "timeout_seconds": 600,
-      "allow_extra_args": false
-    }
-  }
+  "model_instructions_file": "~/.config/machine-bridge-mcp/MODEL.md"
 }
 ```
 
-`instruction_files` is a priority list: each directory contributes only its first non-empty candidate. Deeper manifests override earlier settings and can remove an inherited command with `null`. `run_local_command` executes registered commands as direct argv processes without shell parsing and is available only when direct execution is enabled. See [Agent context, local skills, and registered commands](docs/AGENT_CONTEXT.md) for the complete contract.
+Use `MODEL.md` for preferences not covered by the baseline, such as default language or organization-specific review rules. Repository-specific rules belong in `AGENTS.md`/`AGENTS.override.md`; deeper files take precedence. Keep secrets out of every instruction file.
+
+To disable either automatic layer globally:
+
+```json
+{
+  "version": 1,
+  "builtin_instructions": false,
+  "automatic_project_context": false
+}
+```
+
+Repositories cannot disable these user-level controls. Editing instruction files or project metadata does not require a daemon restart; start a new MCP conversation or reconnect when initialization-time injection must be guaranteed from the beginning.
+
+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, defaults, 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
 
@@ -264,7 +297,9 @@ The exact `tools/list` response reflects the active local policy. Definitions co
 
 - `server_info`
 - `project_overview`
-- `agent_context` — effective instructions, skill summaries, and registered commands for a target path
+- `session_bootstrap` — built-in defaults, automatic project facts, explicit instructions, and refresh metadata
+- `agent_context` — complete default/explicit instruction precedence, 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`
@@ -275,6 +310,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
@@ -335,6 +387,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]
@@ -386,7 +439,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/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.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).
+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

@@ -53,13 +53,27 @@ For untrusted repositories or instructions, run the bridge inside a disposable V
 
 ## 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.
+Machine Bridge prepends a package-controlled built-in working-agreement block and an optional bounded automatic project-context block before repository/user instructions. The built-in block is guidance, not a security boundary. Automatic context reads only recognized root filenames, package-manager/lockfile facts, package script names, runtime constraints, common documentation names, and CI filenames; it does not inject script bodies, dependency values, source contents, or execute discovered commands. Symbolic-link, oversized, invalid-UTF-8, and unsupported metadata is skipped conservatively.
+
+Repository and user instruction files remain 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, filename, script name, or `SKILL.md` can attempt prompt injection or recommend destructive operations. Use only trusted repositories and skill roots, keep host approvals/policy enabled, 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 and instruct the model to bootstrap with `agent_context`, but it cannot force a host to expose or invoke them, and it cannot bypass host confirmation or refusal.
+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 or the global `builtin_instructions`/`automatic_project_context` controls. 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
 

package/browser-extension/manifest.json

@@ -0,0 +1,33 @@
+{
+  "manifest_version": 3,
+  "name": "Machine Bridge Browser",
+  "version": "0.11.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.11.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.";
+  });
+})();