machine-bridge-mcp 0.9.0 → 0.10.0

package/docs/AGENT_CONTEXT.md

@@ -1,74 +1,67 @@
-# Agent context, local skills, and registered commands
+# Session instructions, skills, commands, and capability discovery
 
-The default compatibility target is the current OpenAI Codex guidance for repository instructions and filesystem skills.
+Machine Bridge provides a static MCP bootstrap surface for Codex-style instructions and filesystem skills. The catalog remains stable while local instructions, skills, commands, applications, and browser state are discovered at call time.
 
-Machine Bridge exposes a stable agent bootstrap layer so an MCP client can use repository instructions and local workflows without requiring one dynamically named MCP tool per skill or command.
+This approximates a local coding agent without pretending that the MCP server owns the model loop. The host can filter tools, require confirmation, truncate context, or decline calls before they reach Machine Bridge.
 
-The default discovery rules intentionally track current Codex conventions where practical. Machine Bridge also adds a JSON manifest for custom instruction priority, additional skill roots, and named local commands.
+## MCP tools
 
-This does not make a remote MCP session identical to a locally installed coding agent. The MCP host can independently filter tools, require confirmation, truncate results, or decline calls before they reach Machine Bridge. The bridge cannot alter or bypass those host decisions.
+- `session_bootstrap` returns the current global/session instruction text and refresh fingerprint.
+- `agent_context` returns the complete target-specific instruction chain, skill summaries, and command registry.
+- `resolve_task_capabilities` rescans and ranks skills/commands for the current task, optionally loading the best skill; the runtime also adds application and browser capability metadata.
+- `list_local_skills` searches discovered `SKILL.md` bundles.
+- `load_local_skill` returns one skill entrypoint and bounded file inventory without execution.
+- `list_local_commands` returns effective registered commands.
+- `run_local_command` executes a registered direct-argv command when policy permits.
 
-## Tool model
+Both stdio and remote Worker connection initialization attempt `session_bootstrap`. Its instruction text is appended to the MCP `initialize` result. Because a host may reuse one MCP connection across conversations, the explicit tool and per-task `resolve_task_capabilities` call remain necessary to refresh and reapply instructions reliably.
 
-Five tools form the agent-context surface:
+## Global `model_instructions_file`
 
-- `agent_context` discovers effective instructions, skill summaries, and registered commands for a target path;
-- `list_local_skills` searches discovered `SKILL.md` or `skill.md` bundles;
-- `load_local_skill` returns one skill entrypoint plus a bounded relative file inventory;
-- `list_local_commands` returns the effective command registry;
-- `run_local_command` executes one registered command as a direct argv process.
+The user-level configuration is:
 
-The server instructions tell MCP clients to call `agent_context` before substantive workspace work. This is behavioral guidance, not a protocol-enforced precondition. Every file, Git, mutation, and process tool therefore retains its own policy enforcement.
-
-## Instruction scope and precedence
-
-For a target path, Machine Bridge chooses the nearest ancestor containing `.git` as the project scope root. If no Git marker is found, a target inside the configured workspace uses the workspace root; an unrestricted target outside the workspace uses the target directory.
+```text
+~/.config/machine-bridge-mcp/agent.json
+```
 
-The default instruction candidates, in priority order, are:
+Example:
 
 ```json
-[
-  "AGENTS.override.md",
-  "AGENTS.md"
-]
+{
+  "version": 1,
+  "model_instructions_file": "~/.config/machine-bridge-mcp/MODEL.md"
+}
 ```
 
-Discovery then works as follows:
-
-1. under unrestricted policy, read the first non-empty candidate in `CODEX_HOME` or `~/.codex`;
-2. walk from the project scope root to the target directory;
-3. in each directory, apply its optional `.machine-bridge/agent.json` first;
-4. select only the first non-empty instruction candidate in that directory;
-5. concatenate selected files from global to root to leaf, so later directories have higher precedence.
-
-Empty candidates are skipped. Only one instruction file is selected per directory. This matches the important Codex override behavior: `AGENTS.override.md` suppresses `AGENTS.md` in the same directory, while deeper directories override broader guidance.
+The file is loaded before repository guidance for every session and every target path. It must be a non-empty, regular, non-symbolic-link UTF-8 file and is bounded by the hard instruction-file limit. Relative values are resolved from the user's home directory.
 
-The combined instruction budget defaults to 32 KiB. Once the budget would be exceeded, discovery stops and returns `instructions_truncated: true`. A manifest can raise or lower the budget within the hard 2 MiB ceiling.
+`model_instructions_file` is global-only. A project `.machine-bridge/agent.json` cannot set or override it. It is read even under workspace-confined profiles because the user explicitly designated it as session configuration. Under those profiles, other user-manifest fields that would widen filesystem/skill/command scope are ignored; project instruction and command policy remains confined.
 
-Global instruction discovery is disabled under workspace-confined profiles because reading `~/.codex` would otherwise bypass the profile's direct-filesystem boundary. Project instructions still work in every profile.
+In remote mode, the selected instruction text necessarily traverses the user's Cloudflare Worker and the authorized MCP host as part of initialization. Do not put credentials or private data in an instruction file.
 
-## Custom instruction priority
+## Repository instruction precedence
 
-A manifest may replace the candidate list. The list is priority order, not a list of files to concatenate from the same directory:
+For a target path, Machine Bridge chooses the nearest Git ancestor as scope root, falling back to the configured workspace or target directory. The default candidate priority in each directory is:
 
 ```json
-{
-  "version": 1,
-  "instruction_files": [
-    "LOCAL.override.md",
-    "AGENTS.override.md",
-    "AGENTS.md",
-    ".github/agent-guidance.md"
-  ],
-  "instruction_max_bytes": 65536
-}
+[
+  "AGENTS.override.md",
+  "AGENTS.md"
+]
 ```
 
-For each directory, Machine Bridge selects the first non-empty file in that list. Candidate paths must be relative and their canonical targets must remain inside the directory being inspected.
+Order:
+
+1. `model_instructions_file`, when configured;
+2. under unrestricted policy, the first non-empty candidate in `CODEX_HOME` or `~/.codex`;
+3. project scope root through the target directory;
+4. in each directory, apply `.machine-bridge/agent.json`, then select its first non-empty candidate.
+
+Only one candidate contributes per directory. Deeper files have higher precedence. Empty files are skipped. The repository/global candidate budget defaults to 32 KiB and can be configured up to the hard 2 MiB ceiling. The separately designated model-instructions file retains its own file-size ceiling.
 
-## Configuration format
+## Project manifest
 
-A project configuration lives at `.machine-bridge/agent.json`. Relative skill roots and command working directories are resolved against the directory containing `.machine-bridge`, not against the hidden configuration directory itself.
+A project manifest lives at `.machine-bridge/agent.json`:
 
 ```json
 {
@@ -85,122 +78,63 @@ A project configuration lives at `.machine-bridge/agent.json`. Relative skill ro
   ],
   "commands": {
     "check": {
-      "description": "Run the repository validation suite.",
+      "description": "Run repository validation.",
       "argv": ["npm", "run", "check"],
       "cwd": ".",
       "timeout_seconds": 600,
       "allow_extra_args": false
-    },
-    "test-file": {
-      "description": "Run one test file selected by the caller.",
-      "argv": ["node", "--test"],
-      "cwd": ".",
-      "timeout_seconds": 120,
-      "allow_extra_args": true
     }
   }
 }
 ```
 
-Supported top-level fields are:
-
-- `version`: required and currently fixed at `1`;
-- `instruction_files`: non-empty priority-ordered relative candidates;
-- `instruction_max_bytes`: combined instruction budget from 1 KiB through 2 MiB;
-- `skill_roots`: explicit skill directories; when present, this replaces inherited/default roots;
-- `commands`: named command definitions merged with inherited commands.
-
-Configuration is evaluated from global to project root to target directory. A deeper definition replaces the inherited value. A deeper command value of `null` removes that command:
-
-```json
-{
-  "version": 1,
-  "commands": {
-    "deploy": null
-  }
-}
-```
-
-Unknown fields are rejected so misspellings do not silently weaken the intended workflow.
+Supported project fields are `version`, `instruction_files`, `instruction_max_bytes`, `skill_roots`, and `commands`. Unknown fields fail closed. Deeper manifests replace inherited instruction/skill settings, override commands by name, and can delete a command with `null`.
 
-Under unrestricted policy only, `~/.config/machine-bridge-mcp/agent.json` acts as the initial user-level manifest. Relative paths in that file are resolved from the user's home directory.
+## Skill discovery and live refresh
 
-## Skill discovery
+Without explicit `skill_roots`, discovery scans:
 
-Without an explicit `skill_roots` setting, Machine Bridge uses Codex-compatible filesystem locations:
-
-- `<target>/.agents/skills`;
-- every ancestor's `.agents/skills` through the project root;
+- target-to-root `.agents/skills` directories;
 - under unrestricted policy, `~/.agents/skills`;
 - under unrestricted policy on Unix-like systems, `/etc/codex/skills`.
 
-An explicit `skill_roots` list can add compatibility with other layouts, such as `.codex/skills`, or narrow discovery to selected directories.
-
-Machine Bridge recursively finds directories containing `SKILL.md` or `skill.md`. The entrypoint must contain simple YAML front matter with non-empty `name` and `description` fields:
+A skill directory contains `SKILL.md` or `skill.md` with simple front matter:
 
 ```markdown
 ---
 name: release-review
 description: Review a release without publishing it.
 ---
-
-# Workflow
-
-...
 ```
 
-Invalid skills are skipped and reported in `skill_warnings` or `warnings`; one malformed bundle does not prevent valid skills from loading.
-
-Symlinked skill folders are followed, matching Codex behavior. Under workspace-confined profiles, the canonical symlink target must remain inside the workspace. Skill entrypoint files themselves may not be symbolic links. Directory traversal, cycles, entry count, depth, content, and returned file inventory are bounded.
-
-## Progressive disclosure
+The entrypoint requires non-empty `name` and `description`. Invalid bundles are skipped with bounded warnings. Symlinked skill directories are followed after canonical policy validation; symbolic-link entrypoint files are rejected. Traversal, depth, entries, summaries, content, and inventory are bounded.
 
-`agent_context` initially returns only skill metadata: name, description, path, ID, size, and hash. Its skill summary list has an 8,000-character budget and a caller-selected count limit. Descriptions are shortened first and excess skills are omitted with `skills_truncated: true`.
+No persistent skill index is trusted as authoritative. `agent_context`, `list_local_skills`, and `resolve_task_capabilities` rescan the effective roots. A refresh fingerprint changes when instruction hashes, skill hashes, command definitions, or relevant configuration changes. Newly created or edited skills are therefore visible without restarting the daemon or changing the MCP tool catalog.
 
-`load_local_skill` accepts a stable opaque ID, an unambiguous exact name, or a displayed entrypoint path. It returns:
+## Progressive disclosure and task selection
 
-- the full bounded UTF-8 `SKILL.md` content;
-- metadata and a content hash;
-- a bounded relative inventory of files in the skill directory.
+`agent_context` returns bounded skill metadata. `load_local_skill` returns full instructions only for one selected bundle. `resolve_task_capabilities` tokenizes the current task, ranks skill names/descriptions and command names/descriptions/argv, returns matches with scores, and loads the leading skill only when its relevance threshold is met.
 
-Loading a skill never executes its scripts. The model must inspect the instructions and then invoke an ordinary bridge tool, a registered command, or a managed job. This keeps documentation loading separate from executable authority.
+This ranking is deterministic local assistance, not semantic certainty. The model must still evaluate whether the selected skill applies. Machine Bridge does not execute skill scripts implicitly and does not fabricate a dynamically named MCP tool per skill.
 
-## Registered command execution
+## Registered commands
 
-`run_local_command` is available only when direct process execution is enabled (`agent` or `full`, including equivalent custom policies). It does not invoke a shell. Manifest `argv` elements and caller-supplied arguments remain distinct process arguments, so characters such as `;`, `$()`, pipes, and redirections are not interpreted by a shell.
+`run_local_command` uses direct argv spawning rather than a shell. The manifest controls working directory, timeout ceiling, and whether caller arguments are accepted. A caller may reduce but not increase the timeout.
 
-The manifest remains authoritative:
+Registered commands are workflow aliases, not an approval boundary or sandbox. Package scripts, interpreters, compilers, and executables retain local-user authority. Use `review` or `edit`, or external VM/container isolation, for untrusted content.
 
-- caller arguments are rejected unless `allow_extra_args` is true;
-- a caller can reduce the timeout but cannot increase it beyond `timeout_seconds`;
-- the working directory is canonicalized and remains subject to active path policy;
-- the command receives the isolated or full environment selected by the Machine Bridge profile.
+## Recommended host workflow
 
-Registered commands are workflow aliases, not a sandbox or approval boundary. Repository-controlled package scripts, interpreters, compilers, and executables can run arbitrary code with the local user's authority. Use `edit` or `review`, or external VM/container isolation, for untrusted repositories.
+1. consume MCP initialization instructions;
+2. call `resolve_task_capabilities` with the complete user task and target path;
+3. apply returned global/project instructions;
+4. follow the selected skill only after checking relevance;
+5. prefer registered commands for stable workflows;
+6. use structured application/browser tools where applicable;
+7. inspect before mutation or submission and report operations performed.
 
-For arbitrary one-off execution, existing tools remain available according to policy:
-
-- `run_process` for direct argv execution;
-- `exec_command` for shell syntax under shell-enabled policy;
-- `start_job` for durable multi-step work;
-- `stage_job` for local operator review and later approval.
-
-## Recommended remote workflow
-
-A remote coding task should normally follow this sequence:
-
-1. call `agent_context` with the file or directory being changed;
-2. apply returned instructions in precedence order;
-3. load only skills relevant to the task;
-4. inspect files before editing;
-5. prefer a registered command for validation or a standard workflow;
-6. use direct or shell execution only when the registry does not cover the operation;
-7. report files changed and commands run.
-
-This approximates local coding-agent context loading while keeping MCP transport, local policy, and host policy as explicit independent boundaries.
+Machine Bridge can automatically discover, refresh, rank, and load capabilities. Actual invocation remains a host/model decision. This boundary cannot be removed by server architecture alone.
 
 ## Security and failure behavior
 
-Agent configuration, instruction content, skill traversal, skill summaries, skill inventory, command count, argv size, timeouts, and process output are bounded. Invalid JSON, unknown fields, escaping paths, ambiguous skill names, invalid skill metadata, and missing commands fail explicitly or produce bounded warnings.
-
-Instruction and skill contents are untrusted operational text. They may contain prompt injection or unsafe command guidance. Machine Bridge exposes the content; it does not certify or approve it.
+Instruction and skill text is untrusted operational content and may contain prompt injection or destructive guidance. The bridge exposes it but does not certify it. Paths, files, roots, counts, byte budgets, argv, timeouts, and result sizes are bounded. Escaping paths, ambiguous skill names, malformed metadata, invalid configuration, and missing commands fail explicitly or produce bounded warnings.

package/docs/ARCHITECTURE.md

@@ -32,20 +32,35 @@ A canonical workspace receives an independent profile, Worker name, secret set,
 - process-session buffers and stdin lifecycle;
 - layered fixed runtime diagnostics;
 - local resource aliases and detached managed-job coordination;
-- agent-context discovery and registered-command execution coordination;
+- session/bootstrap instruction discovery, live capability ranking, and registered-command execution coordination;
+- structured local application and existing-profile browser automation coordination;
 - mutation serialization;
 - child-process tracking and cancellation;
 - output, traversal, concurrency, and time limits.
 
 `RelayConnection` owns remote WebSocket transport, authenticated `hello_ack` readiness, heartbeat liveness, reconnect backoff, and outage logging. Stdio mode invokes `LocalRuntime` directly without that adapter.
 
-### Agent context manager
+### Agent context and capability resolver
 
-`AgentContextManager` is a local domain module beneath `LocalRuntime`. It discovers the nearest Git/workspace scope, applies optional user configuration and hierarchical `.machine-bridge/agent.json` files, selects the first non-empty instruction candidate in each global/root-to-target scope, discovers bounded Codex-style `.agents/skills` metadata, and resolves registered commands. The runtime remains responsible for canonical path policy and process execution.
+`AgentContextManager` discovers the nearest Git/workspace scope, applies the user configuration and hierarchical `.machine-bridge/agent.json` files, selects global/root-to-target instructions, discovers bounded filesystem skills, and resolves registered commands. A global `model_instructions_file` is a separate user-designated session source and cannot be overridden by a project.
 
-The MCP surface is deliberately static: `agent_context`, `list_local_skills`, `load_local_skill`, `list_local_commands`, and `run_local_command`. Skills and commands do not become dynamically named MCP tools. This avoids host-side catalog caching/filtering problems and keeps one schema contract across Worker and stdio transports. Initial skill delivery is metadata-only and budgeted; loading a skill is read-only and execution requires a separate ordinary tool call. Registered commands use direct argv spawning and inherit the active runtime environment policy.
+`session_bootstrap` is requested during both stdio and remote MCP initialization. The Worker delegates this read to the connected daemon with a short bounded timeout; failure falls back to static server instructions rather than blocking initialization indefinitely. `resolve_task_capabilities` performs a fresh deterministic scan and ranks skill/command metadata for the current task. Application and browser capability metadata is added by `LocalRuntime`.
 
-See [Agent context, local skills, and registered commands](AGENT_CONTEXT.md) for precedence and configuration semantics.
+The MCP catalog remains static: local skills and commands do not become dynamically named tools. This avoids stale host catalog caches and keeps Worker/stdio schema parity. Progressive disclosure separates discovery, instruction loading, and execution authority. A refresh fingerprint is descriptive rather than a cache-validity guarantee.
+
+See [Session instructions, skills, commands, and capability discovery](AGENT_CONTEXT.md).
+
+### Application automation manager
+
+`AppAutomationManager` owns installed-application discovery, OS launching, and structured UI automation. macOS inspection/actions execute fixed JXA implementation code through `osascript` and expose only typed selectors/actions. The caller cannot provide script source. OS Accessibility/TCC remains an independent boundary.
+
+### Browser extension and machine broker
+
+`BrowserBridgeManager` owns a loopback HTTP/WebSocket broker. The first runtime for the machine-level state root becomes broker owner; additional workspaces and stdio runtimes authenticate to `/runtime` and proxy through the same extension socket. This preserves one extension pairing while allowing multiple local MCP runtimes.
+
+The packaged Manifest V3 extension runs in the user's existing Chromium profile. Its service worker is transport/orchestration only; a fixed packaged `page-automation.js` module is injected into selected frames to expose DOM operations in the correct execution world. It supports accessible frames, open Shadow DOM roots, structured actions, multi-field forms, resource-backed file inputs, and screenshots. The extension never receives arbitrary caller-provided code. The broker validates loopback hostnames, extension origin, bearer subprotocols, message sizes, concurrency, and timeouts. Pairing material is owner-only and omitted from MCP/log output.
+
+See [Local application and browser automation](LOCAL_AUTOMATION.md).
 
 ### Managed job runner
 
@@ -105,6 +120,9 @@ flowchart LR
   L[Local MCP client] -->|stdio JSON-RPC| R
   R -->|canonical workspace tools| F[Selected workspace]
   R -->|optional direct/shell processes| P[Local user / OS / network]
+  R -->|structured Accessibility actions| A[Local applications]
+  R -->|authenticated loopback broker| B[Existing-profile browser extension]
+  B -->|DOM and visible UI authority| WB[Web pages and browser tabs]
   R -->|durable accepted plan| J[Detached managed-job runner]
   J -->|private copies| LR[Local resource files]
   J -->|argv/stdin/env| P
@@ -124,7 +142,7 @@ Remote OAuth determines which client may call tools. Local stdio access relies o
 4. The user verifies client name and redirect URI and enters the connection password.
 5. The Worker creates a five-minute code bound to client, redirect, resource, scope, and PKCE challenge.
 6. A valid verifier exchanges the one-time code for an expiring bearer token; only its hash is stored.
-7. The MCP client initializes and negotiates a supported protocol version.
+7. The MCP client initializes and negotiates a supported protocol version. When the daemon advertises `session_bootstrap`, the Worker requests bounded local instructions and appends them to the initialization result; failure degrades to static instructions.
 8. `tools/list` is derived from the active daemon handshake; without a daemon, only `server_info` is advertised.
 9. `tools/call` receives a random relay call ID and is bound to the current socket and authenticated client request key.
 10. The runtime validates policy and arguments, executes the tool, and returns a bounded result.
@@ -137,7 +155,7 @@ Duplicate in-flight JSON-RPC IDs for the same access token are rejected so cance
 ## Stdio request lifecycle
 
 1. The local client launches `machine-mcp stdio` with a workspace and profile.
-2. The server negotiates one of the supported MCP versions.
+2. The server negotiates one of the supported MCP versions and appends bounded local `session_bootstrap` instructions when available.
 3. Tool discovery is generated from the same catalog and policy used by remote mode.
 4. Each call receives an internal random call ID used only for cancellation and process tracking.
 5. Input is parsed as incrementally bounded newline-delimited JSON-RPC, so an oversized line is discarded before unbounded buffering and the next line can still be processed. Results are emitted as JSON-RPC on stdout; logs remain on stderr.
@@ -194,7 +212,7 @@ The Worker also treats a new connection as a bounded candidate until it authenti
 
 ## Persistence
 
-Local state and global config are owner-only, versioned, size-bounded, and written through temporary files, flushes, and atomic rename. State, managed-job manager, and detached runner commits share a bounded retrying atomic-replace primitive for transient Windows `EPERM`, `EACCES`, `EBUSY`, and `ENOTEMPTY` sharing failures. Managed-job manager and detached runner use one shared no-follow, size-bounded regular-file reader; transition and recovery locks use one PID-lock primitive with bounded stale-lock reclamation and optional runner handoff. Malformed or oversized state becomes a bounded-count `.corrupt-*` backup. Resource paths are omitted from redacted status output. Custom roots are adopted only when empty or recognizable as legacy Machine Bridge state.
+Local state and global config are owner-only, versioned, size-bounded, and written through temporary files, flushes, and atomic rename. Machine-level browser pairing state is owner-only and shared across workspace runtimes through the local broker; its bearer token is not part of workspace state responses. State, managed-job manager, and detached runner commits share a bounded retrying atomic-replace primitive for transient Windows `EPERM`, `EACCES`, `EBUSY`, and `ENOTEMPTY` sharing failures. Managed-job manager and detached runner use one shared no-follow, size-bounded regular-file reader; transition and recovery locks use one PID-lock primitive with bounded stale-lock reclamation and optional runner handoff. Malformed or oversized state becomes a bounded-count `.corrupt-*` backup. Resource paths are omitted from redacted status output. Custom roots are adopted only when empty or recognizable as legacy Machine Bridge state.
 
 Active managed jobs persist an owner-only plan, status, runner PID, and bounded runner diagnostics. Terminal jobs delete the full plan and retain only bounded status/redacted results for up to seven days. This balances crash cleanup with minimization of scripts, stdin, argv, environment overrides, and resource source paths.
 
@@ -219,5 +237,7 @@ Cloudflare sampling is size control rather than an audit log. The project intent
 - guaranteed finally cleanup across permanent power, disk, credential, network, or endpoint-security failure;
 - bypassing MCP-host, connector, operating-system, or endpoint-security policy;
 - PTY/terminal emulation;
-- model-level prompt-injection prevention;
+- model-level prompt-injection prevention or semantic validation of browser/application actions;
+- universal desktop UI automation beyond the implemented OS Accessibility backend;
+- scripting browser-internal/enterprise-blocked pages or inaccessible cross-origin frames;
 - multi-user tenancy in one Worker deployment.

package/docs/CLIENTS.md

@@ -52,6 +52,14 @@ It is therefore an optional compatibility and reuse surface, not a replacement f
 
 The MCP specification defines stdio and Streamable HTTP as standard transports. In stdio, the host launches the server as a subprocess and exchanges newline-delimited JSON-RPC through stdin/stdout. Streamable HTTP runs the server independently behind an HTTP endpoint.
 
+## Automatic capability selection
+
+MCP server instructions and `resolve_task_capabilities` give the host a current view of global/project instructions, skills, registered commands, applications, and browser capability. The resolver rescans rather than relying on a stale dynamic tool list and can return the best matching skill instructions in one call.
+
+The host still owns the agent loop. ChatGPT web may use the recommendation automatically, ask for confirmation, expose only part of the catalog, or ignore server instructions. No MCP implementation can guarantee automatic invocation from the server side. Machine Bridge models that limitation explicitly instead of treating a recommendation as execution.
+
+For browser tasks, the remote host reaches the local extension through the Worker and daemon. The extension controls the existing Chromium profile; it is not a separate Playwright profile.
+
 ## Generate local configuration
 
 The default profile is `full`:

package/docs/ENGINEERING.md

@@ -9,7 +9,10 @@ This document records project-wide decisions that must survive individual fixes,
 3. **Machine Bridge authority and host authority are separate.** `full` removes Machine Bridge's own policy, path, shell, and environment restrictions. It cannot override an MCP host, connector gateway, operating system, endpoint-security product, cloud IAM, remote authentication, or `sudo`.
 4. **Publication surfaces contain no real environment metadata.** Source, tests, fixtures, examples, release notes, filenames, package contents, tags, and release assets use synthetic identifiers and reserved example domains.
 5. **Secrets are never operational log data.** Tool arguments, command text, stdin, stdout, stderr, file content, OAuth bodies, credentials, and local resource values are not logged.
-6. **A release is one version across all surfaces.** Package metadata, Worker version, Git tag, GitHub Release, npm version, documentation, and deployed health version must agree before a release is considered complete.
+6. **A release is one version across all surfaces.** Package metadata, Worker version, browser-extension version/name, Git tag, GitHub Release, npm version, documentation, and deployed health version must agree before a release is considered complete.
+7. **Generic local automation is structured, not arbitrary evaluation.** Browser/application features may expose broad user authority under canonical `full`, but must not accept caller-provided JavaScript, AppleScript, JXA, or extension code.
+8. **Daily-browser integration uses the existing profile.** The supported primary browser path is the packaged authenticated extension and machine-level loopback broker, preserving current tabs/login state; a separate automation profile is not an equivalent replacement.
+9. **Pairing and resource secrets are not conversation or log data.** Tokens and injected local-resource values must not be returned, embedded in URLs, or written to operational logs.
 
 A proposed change that conflicts with an invariant requires an explicit owner decision and corresponding documentation update. It must not be hidden inside an unrelated refactor.
 
@@ -158,6 +161,7 @@ A thorough review asks:
 - Are all success, failure, cancellation, timeout, disconnect, restart, and recovery branches bounded and tested?
 - Are logs actionable, rate-limited, and privacy-preserving?
 - Are persistent files atomic, owner-only, size-bounded, and symlink-aware?
+- Can browser/app automation be expressed without arbitrary evaluation, and are pairing/resource values absent from results and logs?
 - Can a stale PID, stale socket, duplicate request, partial write, or ambiguous remote response violate integrity?
 - Are package, CI, Worker, service, and release behavior tested on every supported platform?
 - Does the complete diff contain any real identifier, path, host, account, or credential-shaped value?

package/docs/LOCAL_AUTOMATION.md

@@ -0,0 +1,111 @@
+# Local application and browser automation
+
+Machine Bridge exposes two structured local-automation backends under the canonical `full` profile:
+
+1. operating-system application discovery and macOS Accessibility actions;
+2. a Chromium extension connected to a loopback broker for the user's existing browser profile, windows, tabs, cookies, and login state.
+
+Neither backend accepts arbitrary caller-supplied AppleScript, JavaScript, or browser-extension code. The MCP surface is a bounded set of typed discovery, inspection, action, form, screenshot, and file-upload operations.
+
+## Why the browser backend is an extension
+
+Launching a separate automation browser is predictable but loses the user's ordinary profile, active tabs, existing login state, browser extensions, and familiar window. Machine Bridge therefore uses a packaged Manifest V3 extension as the primary backend. It is loaded once into the user's Chromium-family browser and paired with a loopback-only local broker.
+
+The extension works with the current profile and supports:
+
+- listing existing tabs;
+- reading the current serialized DOM HTML from the main frame or accessible subframes;
+- discovering interactive controls, labels, roles, placeholders, and field metadata across accessible frames and open Shadow DOM roots;
+- structured navigation, click, focus, fill, select, check, uncheck, key press, and form submission;
+- multi-field complex form filling in one operation, bounded to 200 fields and 4 MiB of aggregate text;
+- populating file inputs from registered local resource files;
+- visible-tab screenshots.
+
+Current support targets Chrome, Chromium, Microsoft Edge, Brave, Vivaldi, and compatible Chromium browsers. After upgrading Machine Bridge, reload the unpacked extension from the browser extensions page so its packaged scripts match the new runtime. Browser-internal pages, extension stores, some PDF/plugin viewers, cross-origin frames denied to the extension, and pages restricted by enterprise policy may not be scriptable.
+
+## One-time browser setup
+
+Keep `machine-mcp` running, then use either the MCP tool `pair_browser_extension` or the local CLI:
+
+```sh
+machine-mcp browser setup
+```
+
+The command prints the packaged extension directory and opens the local pairing page. In the browser:
+
+1. open the extensions page;
+2. enable Developer mode;
+3. choose **Load unpacked** and select the printed `browser-extension` directory;
+4. return to the local pairing page.
+
+The first pairing completes automatically. If the extension is already paired to different local state, the page asks for an explicit user gesture: click the Machine Bridge extension icon while the pairing page is active to confirm replacement. This prevents another localhost page from silently overwriting an established pairing. The extension badge shows `ON` when connected; clicking the icon from another page opens the saved local pairing/status page.
+
+`Load unpacked` is the self-hosted/development installation path. A mass-market release should package the same extension source as a signed Chrome Web Store and/or Microsoft Edge Add-ons build, so ordinary users install it through the browser store without enabling Developer mode. This repository change does not publish a store listing.
+
+The content script reads pairing material only from the loopback page and stores it in browser-local extension storage. Check status with:
+
+```sh
+machine-mcp browser status
+machine-mcp browser path
+```
+
+The broker is machine-global rather than workspace-global. One local owner listens on the loopback port, and additional Machine Bridge runtimes authenticate to that broker and proxy requests through the same extension connection. This prevents multiple workspaces or stdio clients from repeatedly stealing the browser connection.
+
+## Browser tools
+
+- `browser_status` reports broker role, extension connection, supported operations, pairing URL, and extension path without returning the pairing token.
+- `pair_browser_extension` opens the local pairing page and returns setup steps.
+- `browser_list_tabs` lists current tabs.
+- `browser_get_source` returns bounded current DOM HTML for selected frames.
+- `browser_inspect_page` returns bounded interactive-element metadata.
+- `browser_action` performs one structured navigation or DOM action. Navigation accepts absolute `http`, `https`, or `file` URLs; script/data schemes are rejected.
+- `browser_fill_form` fills up to 200 fields and can submit once.
+- `browser_upload_files` sets a file input from up to eight registered local resources.
+- `browser_screenshot` returns native MCP image content.
+
+Selectors can use CSS, ID, field name, label text, visible text, ARIA/implicit role, placeholder, and a zero-based match index. The fixed page module traverses open Shadow DOM roots; closed shadow roots remain inaccessible. For frame-specific work, inspect all frames first and then pass `frame_id` to an action.
+
+## Sensitive form values and files
+
+Ordinary `value` arguments travel through the MCP host, the Worker in remote mode, and the local daemon. For passwords, tokens, personal data, or uploaded files, register a local resource from the terminal:
+
+```sh
+machine-mcp resource add account-password /path/to/owner-only/password.txt
+machine-mcp resource add application-pdf /path/to/document.pdf
+```
+
+Then use `value_resource` for a text field or `resources` for `browser_upload_files`. The local daemon reads the resource only when executing the operation. Results report the alias and outcome, not the resource content. This reduces model-context and result exposure, but the destination page receives the value by design and can transmit it according to its own behavior.
+
+## Application tools
+
+- `list_local_applications` discovers installed applications or launchers.
+- `open_local_application` opens an application, URL, or document through the OS launcher.
+- `inspect_local_application` returns a bounded macOS Accessibility tree.
+- `operate_local_application` performs a structured Accessibility action.
+
+macOS UI inspection and actions require Accessibility permission for the Node/Machine Bridge process. Application discovery and opening are available on supported desktop platforms; structured UI inspection currently targets macOS. The application backend uses fixed JXA implementation code. The caller selects only an application, structured selector, action, and optional bounded value. `include_values` never returns values for secure-text roles or controls whose metadata indicates passwords, tokens, one-time codes, or payment-card secrets.
+
+## Capability discovery and automatic selection
+
+`resolve_task_capabilities` rescans instruction files, skills, registered commands, and relevant local automation metadata on every call. It ranks matching skills and commands, optionally loads the best skill, and recommends browser/application tools when the task indicates them.
+
+This is the strongest reliable server-side automation boundary available through MCP: discovery, refresh, ranking, and progressive skill loading are automatic. The MCP host still owns the model loop and decides whether a recommended tool is exposed, approved, or invoked. Machine Bridge cannot force ChatGPT web or another host to make a call that the host declines.
+
+## Security model
+
+The browser extension has broad page access because generic source inspection and complex forms require it. An authorized `full` client can read pages visible to the extension and perform user-visible actions with the user's logged-in authority. A malicious webpage can contain prompt-injection text, deceptive controls, or actions with financial, legal, account, or privacy consequences.
+
+The implementation reduces avoidable risk as follows:
+
+- all browser/app tools are `full`-only;
+- no arbitrary evaluation or caller-provided script source is accepted;
+- loopback HTTP validates `Host`; extension WebSockets require a random bearer subprotocol and a `chrome-extension://` origin;
+- runtime-to-broker connections require a separate authenticated subprotocol;
+- the pairing token is stored owner-only, embedded only in the non-cacheable local pairing page, and omitted from MCP results and logs;
+- an established extension pairing cannot be silently replaced by another localhost page; replacement requires clicking the extension action on the active pairing page;
+- arguments, form values, page source, screenshots, and results are not operational log data;
+- message, source, form-field, upload, traversal, concurrency, proxy-route, and timeout limits are enforced;
+- MCP cancellation clears local and broker pending state and propagates a cancellation signal to the extension; an action already delivered to a page or application may still have completed;
+- resource-backed text and files are not returned after injection.
+
+These controls do not turn the browser into a sandbox and do not validate business intent. Inspect the page and final values before high-impact submissions. Host confirmation and narrow profiles remain independent controls.

package/docs/LOGGING.md

@@ -78,10 +78,18 @@ The implementation omits:
 - file, patch, image, and temporary-file content;
 - OAuth request bodies;
 - connection passwords, daemon secrets, authorization codes, and access tokens;
-- registered resource values and source paths.
+- registered resource values and source paths;
+- browser pairing tokens, page URLs/source, DOM metadata, form values, uploaded file bytes, and screenshots;
+- application names, Accessibility trees, selectors, and entered values.
 
 Unexpected infrastructure failures are reduced to coarse error classes in normal logs. Client-facing tool errors may contain more detail according to the active path-display policy, but those details are not copied into operational logs.
 
+## Local automation events
+
+Browser broker ownership, extension connection, and persistent unavailability are infrastructure state. Ordinary tab/source/action/form/upload/screenshot calls remain per-tool debug events and never log their arguments or results. Pairing tokens are excluded from all structured fields.
+
+Application discovery and Accessibility operations follow the same rule: permission or runtime failures are classified, while app names, UI trees, selectors, and values are not operational log data.
+
 ## Bounding and redaction
 
 Messages, strings, object depth, object key counts, array item counts, and serialized field payloads are bounded. Control characters and Unicode display controls are neutralized. Fields with secret-like names, path-like keys, and known token formats are recursively redacted.

package/docs/OPERATIONS.md

@@ -30,6 +30,33 @@ A brief relay interruption is retried automatically and is visible only with `--
 
 Use `--verbose` only when close codes, close reasons, heartbeat timeouts, and retry delays are needed for diagnosis. A close code of 1006 means the transport ended without a normal close handshake; it does not by itself identify the cause.
 
+## Browser extension setup and diagnosis
+
+The full-profile daemon starts the loopback browser broker automatically. Install/pair the packaged extension once:
+
+```sh
+machine-mcp browser setup
+machine-mcp browser status
+```
+
+`browser setup` prints the unpacked-extension path and opens the local pairing page. Load that directory from the Chromium extensions page with Developer mode enabled. The pairing page contains the token only in non-cacheable loopback HTML; the CLI and MCP result do not print it. A first pairing is automatic. When local pairing state was reset or moved, click the extension icon on the active pairing page to authorize replacing the extension's previous broker configuration.
+
+Diagnosis:
+
+| Result | Interpretation |
+|---|---|
+| broker not reachable | no full-profile runtime owns the machine broker, state is stale, or a local security product blocked loopback listening |
+| broker running, extension disconnected | extension not loaded/enabled, pairing not completed, browser profile not running, or MV3 worker reconnect failed |
+| tab list works but page action fails | restricted browser-internal page, inaccessible frame, stale selector, page navigation, enterprise policy, or page script interference |
+| `frame_id` action fails | frame was replaced or is not accessible; inspect frames again |
+| resource-backed upload fails | resource unavailable/too large, input is not `type=file`, page replaced the input, or the site rejects the file |
+
+The machine-level broker permits multiple workspace daemons/stdio clients to share one extension. A second runtime becomes an authenticated broker client rather than selecting a new port or replacing the extension. Its owner-only `browser-bridge.json` pairing record is a recognized state-root entry, so validated uninstall can remove the complete Machine Bridge state root without treating the pairing record as unrelated data. Restarting every runtime is not normally required after adding a skill or changing a form page; capability and DOM discovery are live.
+
+## macOS application automation
+
+Application UI inspection/actions require Accessibility permission for the Node/Machine Bridge process. Grant it in macOS Privacy & Security, then retry `inspect_local_application`. Opening applications does not require the same Accessibility authority. If an app changes UI hierarchy or localizes labels, inspect again and use role/identifier/index selectors instead of assuming a stale title.
+
 ## Logs
 
 Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. A service-style `--daemon-only` start that finds the same workspace daemon already running is an idempotent no-op: it exits successfully without repeating warnings or readiness output; explicit policy/secret/change requests still report that changes were not applied. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.
@@ -131,6 +158,9 @@ Defense-in-depth limits include:
 - managed-job timeout: 1–3,600 seconds per step;
 - managed-job output: 64 KiB per stream and 256 KiB total captured across one job;
 - registered resources: 64, 1 MiB each, 8 MiB referenced per job;
+- browser source: 4 MiB; browser WebSocket messages: 8 MiB; pending browser requests: 32 per runtime;
+- browser forms: 200 fields, 128 KiB per text value, and 4 MiB aggregate text; upload: eight resources and 5 MiB total;
+- application Accessibility inspection: 500 elements and depth 12; action text: 4,000 characters;
 - job-scoped temporary files: 16 files, 512 KiB total content.
 
 ## Upgrade behavior

package/docs/PRIVACY.md

@@ -34,7 +34,8 @@ Before committing or publishing:
 - inspect the complete staged diff, including tests, snapshots, examples, release notes, and generated metadata;
 - use reserved example domains and neutral aliases;
 - run `npm run privacy:check`, `npm run check`, and `npm pack --dry-run`;
-- treat paths, host aliases, usernames, and codenames as private metadata even when they are not authentication secrets.
+- treat paths, host aliases, usernames, codenames, real browser URLs/page captures, application names tied to a user, and form data as private metadata even when they are not authentication secrets;
+- keep browser pairing-state files and captured source/screenshots out of fixtures, documentation, support logs, and release assets.
 
 The scanner is heuristic. It cannot identify every personal or organizational name, transformed value, image, archive, binary fixture, or data already present in Git history.