machine-bridge-mcp 0.8.2 → 0.10.0

package/browser-extension/service-worker.js

@@ -0,0 +1,406 @@
+let socket = null;
+let reconnectTimer = null;
+let reconnectAttempt = 0;
+let keepaliveTimer = null;
+const MAX_RESULT_BYTES = 7 * 1024 * 1024;
+const activeRequests = new Map();
+
+chrome.runtime.onInstalled.addListener(() => { ensureReconnectAlarm(); void connectFromStorage(); });
+chrome.runtime.onStartup.addListener(() => { ensureReconnectAlarm(); void connectFromStorage(); });
+chrome.alarms.onAlarm.addListener((alarm) => {
+  if (alarm.name === "machine-bridge-reconnect") void connectFromStorage();
+});
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message?.type !== "pair") return false;
+  pairConfiguration(message.endpoint, message.token, { replace: false, senderUrl: sender.url || "" })
+    .then(sendResponse)
+    .catch(() => sendResponse({ ok: false }));
+  return true;
+});
+chrome.action.onClicked.addListener((tab) => void handleActionClick(tab));
+
+async function handleActionClick(tab) {
+  if (tab?.id && /^http:\/\/127\.0\.0\.1:\d+\/pair(?:$|[?#])/.test(String(tab.url || ""))) {
+    await confirmRepairFromTab(tab);
+    return;
+  }
+  const current = await chrome.storage.local.get(["endpoint"]);
+  const pairUrl = pairingUrlFromEndpoint(current.endpoint) || "http://127.0.0.1:39393/pair";
+  await chrome.tabs.create({ url: pairUrl });
+}
+
+function pairingUrlFromEndpoint(endpoint) {
+  const match = /^ws:\/\/127\.0\.0\.1:(\d+)\/extension$/.exec(String(endpoint || ""));
+  return match ? `http://127.0.0.1:${match[1]}/pair` : "";
+}
+
+function setConnectionState(state) {
+  const badge = state === "connected" ? "ON" : state === "connecting" ? "..." : state === "unconfigured" ? "?" : "!";
+  const title = state === "connected"
+    ? "Machine Bridge Browser: connected"
+    : state === "connecting"
+      ? "Machine Bridge Browser: connecting"
+      : state === "unconfigured"
+        ? "Machine Bridge Browser: click to open pairing"
+        : "Machine Bridge Browser: disconnected; click to open pairing";
+  try { ignoreOptionalPromise(chrome.action.setBadgeText({ text: badge })); } catch {}
+  try { ignoreOptionalPromise(chrome.action.setTitle({ title })); } catch {}
+}
+
+function ignoreOptionalPromise(value) {
+  if (value && typeof value.catch === "function") value.catch(() => {});
+}
+
+async function pairConfiguration(rawEndpoint, rawToken, { replace, senderUrl }) {
+  const endpoint = String(rawEndpoint || "");
+  const token = String(rawToken || "");
+  if (!/^http:\/\/127\.0\.0\.1:\d+\/pair(?:$|[?#])/.test(String(senderUrl || ""))) return { ok: false, error: "invalid_pairing_page" };
+  if (!/^ws:\/\/127\.0\.0\.1:\d+\/extension$/.test(endpoint) || !/^[A-Za-z0-9_-]{32,100}$/.test(token)) return { ok: false, error: "invalid_pairing_material" };
+  const current = await chrome.storage.local.get(["endpoint", "token"]);
+  const alreadyPaired = Boolean(current.endpoint && current.token);
+  if (alreadyPaired && !replace && (current.endpoint !== endpoint || current.token !== token)) {
+    return { ok: false, requires_manual_repair: true };
+  }
+  await chrome.storage.local.set({ endpoint, token });
+  setConnectionState("connecting");
+  connect(endpoint, token);
+  return { ok: true, replaced: alreadyPaired && (current.endpoint !== endpoint || current.token !== token) };
+}
+
+async function confirmRepairFromTab(tab) {
+  if (!tab?.id || !/^http:\/\/127\.0\.0\.1:\d+\/pair(?:$|[?#])/.test(String(tab.url || ""))) return;
+  try {
+    const [result] = await chrome.scripting.executeScript({
+      target: { tabId: tab.id },
+      func: () => ({
+        endpoint: `ws://127.0.0.1:${document.querySelector('meta[name="machine-bridge-browser-port"]')?.content || ""}/extension`,
+        token: document.querySelector('meta[name="machine-bridge-browser-token"]')?.content || "",
+      }),
+    });
+    const paired = await pairConfiguration(result?.result?.endpoint, result?.result?.token, { replace: true, senderUrl: tab.url });
+    await chrome.scripting.executeScript({
+      target: { tabId: tab.id },
+      func: (ok) => {
+        const status = document.getElementById("status");
+        if (status) status.textContent = ok ? "Paired. You may close this tab." : "Pairing failed.";
+      },
+      args: [paired.ok === true],
+    });
+  } catch {}
+}
+
+ensureReconnectAlarm();
+void connectFromStorage();
+
+function ensureReconnectAlarm() {
+  chrome.alarms.create("machine-bridge-reconnect", { periodInMinutes: 1 });
+}
+
+async function connectFromStorage() {
+  if (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)) return;
+  const value = await chrome.storage.local.get(["endpoint", "token"]);
+  if (value.endpoint && value.token) {
+    setConnectionState("connecting");
+    connect(value.endpoint, value.token);
+  } else {
+    setConnectionState("unconfigured");
+  }
+}
+
+function connect(endpoint, token) {
+  clearTimeout(reconnectTimer);
+  reconnectTimer = null;
+  if (socket) {
+    try { socket.close(); } catch {}
+  }
+  const ws = new WebSocket(endpoint, [`mbm.${token}`]);
+  socket = ws;
+  ws.onopen = () => {
+    if (socket !== ws) {
+      try { ws.close(); } catch {}
+      return;
+    }
+    reconnectAttempt = 0;
+    setConnectionState("connected");
+    clearInterval(keepaliveTimer);
+    keepaliveTimer = setInterval(() => { if (socket === ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "ping" })); }, 20000);
+  };
+  ws.onmessage = (event) => void handleMessage(ws, event.data);
+  ws.onerror = () => {};
+  ws.onclose = () => {
+    if (socket !== ws) return;
+    clearInterval(keepaliveTimer);
+    keepaliveTimer = null;
+    socket = null;
+    setConnectionState("disconnected");
+    scheduleReconnect(endpoint, token);
+  };
+}
+
+function scheduleReconnect(endpoint, token) {
+  clearTimeout(reconnectTimer);
+  const delay = Math.min(30000, 1000 * 2 ** Math.min(reconnectAttempt++, 5));
+  reconnectTimer = setTimeout(() => connect(endpoint, token), delay);
+}
+
+async function handleMessage(ws, raw) {
+  let message;
+  try { message = JSON.parse(String(raw)); } catch { return; }
+  if (message?.type === "cancel" && typeof message.id === "string") {
+    const state = activeRequests.get(message.id);
+    if (state) state.cancelled = true;
+    return;
+  }
+  if (message?.type !== "request" || typeof message.id !== "string" || typeof message.method !== "string") return;
+  const state = { cancelled: false };
+  activeRequests.set(message.id, state);
+  try {
+    throwIfCancelled(state);
+    const result = await dispatch(message.method, message.params || {});
+    throwIfCancelled(state);
+    sendResponse(ws, message.id, true, result);
+  } catch (error) {
+    if (!state.cancelled) sendResponse(ws, message.id, false, null, String(error?.message || error).slice(0, 2000));
+  } finally {
+    activeRequests.delete(message.id);
+  }
+}
+
+function throwIfCancelled(state) {
+  if (state.cancelled) throw new Error("browser request cancelled");
+}
+
+function sendResponse(ws, id, ok, result, error = "") {
+  if (ws.readyState !== WebSocket.OPEN) return;
+  let payload = JSON.stringify({ type: "response", id, ok, ...(ok ? { result } : { error }) });
+  if (new TextEncoder().encode(payload).byteLength > MAX_RESULT_BYTES) {
+    payload = JSON.stringify({ type: "response", id, ok: false, error: "browser result exceeds maximum size" });
+  }
+  try { ws.send(payload); } catch {}
+}
+
+async function dispatch(method, params) {
+  if (method === "list_tabs") return listTabs(params);
+  if (method === "get_source") return getSource(params);
+  if (method === "inspect_page") return inspectPage(params);
+  if (method === "action") return browserAction(params);
+  if (method === "fill_form") return fillForm(params);
+  if (method === "upload_files") return uploadFiles(params);
+  if (method === "screenshot") return screenshot(params);
+  throw new Error(`unknown browser method: ${method}`);
+}
+
+async function listTabs(params) {
+  const query = params.currentWindow ? { currentWindow: true } : {};
+  const tabs = await chrome.tabs.query(query);
+  return {
+    tabs: tabs
+      .filter((tab) => params.includePinned !== false || !tab.pinned)
+      .map((tab) => ({
+        id: tab.id,
+        window_id: tab.windowId,
+        active: tab.active,
+        pinned: tab.pinned,
+        audible: tab.audible,
+        discarded: tab.discarded,
+        status: tab.status,
+        title: tab.title || "",
+        url: tab.url || "",
+      })),
+  };
+}
+
+function scriptTarget(tabId, frameId, allFrames) {
+  if (Number.isInteger(frameId)) return { tabId, frameIds: [frameId] };
+  if (allFrames) return { tabId, allFrames: true };
+  return { tabId };
+}
+
+async function resolveTab(tabId) {
+  if (Number.isInteger(tabId)) return chrome.tabs.get(tabId);
+  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+  if (!tab?.id) throw new Error("no active browser tab");
+  return tab;
+}
+
+async function getSource(params) {
+  const tab = await resolveTab(params.tabId);
+  assertPageTab(tab);
+  const maxBytes = Number(params.maxBytes) || 1024 * 1024;
+  const executions = await chrome.scripting.executeScript({
+    target: scriptTarget(tab.id, params.frameId, params.allFrames === true),
+    func: (limit) => {
+      const doctype = document.doctype ? `<!DOCTYPE ${document.doctype.name}>\n` : "";
+      const source = `${doctype}${document.documentElement?.outerHTML || ""}`;
+      const encoder = new TextEncoder();
+      const bytes = encoder.encode(source);
+      if (bytes.byteLength <= limit) return { source, bytes: bytes.byteLength, truncated: false, url: location.href };
+      const decoder = new TextDecoder();
+      return { source: decoder.decode(bytes.slice(0, limit)), bytes: bytes.byteLength, truncated: true, url: location.href };
+    },
+    args: [maxBytes],
+  });
+  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", frames: executions.map((item) => ({ frame_id: item.frameId, ...item.result })) };
+}
+
+async function inspectPage(params) {
+  const tab = await resolveTab(params.tabId);
+  assertPageTab(tab);
+  const executions = await executePageAutomation(
+    scriptTarget(tab.id, params.frameId, params.allFrames === true),
+    "inspect",
+    { maxElements: Number(params.maxElements) || 300, includeValues: params.includeValues === true },
+  );
+  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", frames: executions.map((item) => ({ frame_id: item.frameId, ...item.result })) };
+}
+
+async function browserAction(params) {
+  const tab = await resolveTab(params.tabId);
+  if (params.action === "navigate") {
+    if (!params.url) throw new Error("navigate requires url");
+    const waiter = beginTabWait(tab.id, params.waitFor);
+    try {
+      const updated = await chrome.tabs.update(tab.id, { url: params.url });
+      await waiter.promise;
+      return publicTab(await chrome.tabs.get(updated.id));
+    } catch (error) {
+      waiter.cancel();
+      throw error;
+    }
+  }
+  if (params.action === "reload") {
+    const waiter = beginTabWait(tab.id, params.waitFor);
+    try {
+      await chrome.tabs.reload(tab.id);
+      await waiter.promise;
+      return publicTab(await chrome.tabs.get(tab.id));
+    } catch (error) {
+      waiter.cancel();
+      throw error;
+    }
+  }
+  if (params.action === "back" || params.action === "forward") {
+    const waiter = beginTabWait(tab.id, params.waitFor);
+    try {
+      if (params.action === "back") await chrome.tabs.goBack(tab.id);
+      else await chrome.tabs.goForward(tab.id);
+      await waiter.promise;
+      return publicTab(await chrome.tabs.get(tab.id));
+    } catch (error) {
+      waiter.cancel();
+      throw error;
+    }
+  }
+  assertPageTab(tab);
+  const waiter = beginTabWait(tab.id, params.waitFor);
+  let execution;
+  try {
+    [execution] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "action", params);
+    await waiter.promise;
+  } catch (error) {
+    waiter.cancel();
+    throw error;
+  }
+  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", ...execution.result };
+}
+
+async function fillForm(params) {
+  const tab = await resolveTab(params.tabId);
+  assertPageTab(tab);
+  const waiter = beginTabWait(tab.id, params.waitFor);
+  let execution;
+  try {
+    [execution] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "fillForm", params);
+    await waiter.promise;
+  } catch (error) {
+    waiter.cancel();
+    throw error;
+  }
+  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", ...execution.result };
+}
+
+async function uploadFiles(params) {
+  const tab = await resolveTab(params.tabId);
+  assertPageTab(tab);
+  const [execution] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "uploadFiles", params);
+  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", ...execution.result };
+}
+
+async function screenshot(params) {
+  const tab = await resolveTab(params.tabId);
+  await chrome.tabs.update(tab.id, { active: true });
+  await chrome.windows.update(tab.windowId, { focused: true });
+  const data = await chrome.tabs.captureVisibleTab(tab.windowId, {
+    format: params.format === "jpeg" ? "jpeg" : "png",
+    quality: Number(params.quality) || 90,
+  });
+  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", data };
+}
+
+function publicTab(tab) {
+  return { tab_id: tab.id, window_id: tab.windowId, title: tab.title || "", url: tab.url || "", status: tab.status || "" };
+}
+
+function assertPageTab(tab) {
+  const url = String(tab.url || "");
+  if (!/^(https?|file):/i.test(url)) throw new Error("this page cannot be scripted by a browser extension");
+}
+
+function beginTabWait(tabId, mode) {
+  if (!mode || mode === "none") return { promise: Promise.resolve(), cancel() {} };
+  let settled = false;
+  let navigationStarted = false;
+  let pollTimer = null;
+  let timeout = null;
+  let resolveWait;
+  let rejectWait;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolveWait = resolvePromise;
+    rejectWait = rejectPromise;
+  });
+  const cleanup = () => {
+    clearTimeout(timeout);
+    clearTimeout(pollTimer);
+    chrome.tabs.onUpdated.removeListener(listener);
+  };
+  const settle = (error = null) => {
+    if (settled) return;
+    settled = true;
+    cleanup();
+    if (error) rejectWait(error); else resolveWait();
+  };
+  const pollReadyState = async () => {
+    if (settled || !navigationStarted || mode !== "domcontentloaded") return;
+    try {
+      const [execution] = await chrome.scripting.executeScript({ target: { tabId }, func: () => document.readyState });
+      if (["interactive", "complete"].includes(execution?.result)) {
+        settle();
+        return;
+      }
+    } catch {}
+    pollTimer = setTimeout(pollReadyState, 100);
+  };
+  const listener = (updatedId, changeInfo, tab) => {
+    if (updatedId !== tabId || settled) return;
+    if (changeInfo.status === "loading" || typeof changeInfo.url === "string") navigationStarted = true;
+    if (!navigationStarted) return;
+    if (mode === "complete" && (changeInfo.status === "complete" || (typeof changeInfo.url === "string" && tab.status === "complete"))) settle();
+    if (mode === "domcontentloaded") void pollReadyState();
+  };
+  chrome.tabs.onUpdated.addListener(listener);
+  timeout = setTimeout(() => settle(new Error("browser navigation wait timed out")), 30000);
+  return { promise, cancel: () => settle() };
+}
+
+function executePageAutomation(target, method, params) {
+  return chrome.scripting.executeScript({ target, files: ["page-automation.js"] })
+    .then(() => chrome.scripting.executeScript({
+      target,
+      func: (operation, payload) => {
+        const api = globalThis.__machineBridgePageAutomation;
+        if (!api || typeof api[operation] !== "function") throw new Error("page automation module is unavailable");
+        return api[operation](payload);
+      },
+      args: [method, params],
+    }));
+}

package/docs/AGENT_CONTEXT.md

@@ -0,0 +1,140 @@
+# Session instructions, skills, commands, and capability discovery
+
+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.
+
+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.
+
+## MCP tools
+
+- `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.
+
+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.
+
+## Global `model_instructions_file`
+
+The user-level configuration is:
+
+```text
+~/.config/machine-bridge-mcp/agent.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "model_instructions_file": "~/.config/machine-bridge-mcp/MODEL.md"
+}
+```
+
+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.
+
+`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.
+
+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.
+
+## Repository instruction precedence
+
+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
+[
+  "AGENTS.override.md",
+  "AGENTS.md"
+]
+```
+
+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.
+
+## Project manifest
+
+A project manifest lives at `.machine-bridge/agent.json`:
+
+```json
+{
+  "version": 1,
+  "instruction_files": [
+    "PROJECT.override.md",
+    "AGENTS.override.md",
+    "AGENTS.md"
+  ],
+  "instruction_max_bytes": 65536,
+  "skill_roots": [
+    ".agents/skills",
+    ".codex/skills"
+  ],
+  "commands": {
+    "check": {
+      "description": "Run repository validation.",
+      "argv": ["npm", "run", "check"],
+      "cwd": ".",
+      "timeout_seconds": 600,
+      "allow_extra_args": false
+    }
+  }
+}
+```
+
+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`.
+
+## Skill discovery and live refresh
+
+Without explicit `skill_roots`, discovery scans:
+
+- target-to-root `.agents/skills` directories;
+- under unrestricted policy, `~/.agents/skills`;
+- under unrestricted policy on Unix-like systems, `/etc/codex/skills`.
+
+A skill directory contains `SKILL.md` or `skill.md` with simple front matter:
+
+```markdown
+---
+name: release-review
+description: Review a release without publishing it.
+---
+```
+
+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.
+
+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.
+
+## Progressive disclosure and task selection
+
+`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.
+
+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 commands
+
+`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.
+
+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.
+
+## Recommended host workflow
+
+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.
+
+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
+
+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,12 +32,36 @@ 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;
+- 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 and capability resolver
+
+`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.
+
+`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`.
+
+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
 
 `ManagedJobManager` persists bounded per-workspace job envelopes below the owner-only profile directory. `start_job` validates the complete plan, snapshots referenced resource metadata/hashes, writes an owner-only plan/status, and launches `job-runner.mjs` as a detached process with runner-level logs redirected to owner-only files. `stage_job` performs the same acceptance validation but writes a non-running `staged` envelope; only local `job approve` transitions it to queued and launches the runner.
@@ -96,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
@@ -115,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.
@@ -128,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.
@@ -185,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.
 
@@ -210,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?