machine-bridge-mcp 0.9.0 → 0.10.0

package/src/local/cli.mjs

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
 import path, { join, resolve } from "node:path";
@@ -11,6 +12,7 @@ import { activeManagedJobs, inspectResourceFile, loadManagedJobPlan, ManagedJobM
 import { runWrangler } from "./shell.mjs";
 import { generateRegisteredSshKey } from "./resource-operations.mjs";
 import { runFullAccessTest } from "./full-access-test.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
 import {
   acquireDaemonLock,
   acquireStartupLock,
@@ -58,6 +60,7 @@ const COMMAND_HANDLERS = Object.freeze({
   autostart: serviceCommand,
   "rotate-secrets": rotateSecretsCommand,
   resource: resourceCommand,
+  browser: browserCommand,
   job: jobCommand,
   uninstall: uninstallCommand,
 });
@@ -94,6 +97,7 @@ const COMMAND_OPTIONS = {
   service: new Set(["workspace", "stateDir", "quiet"]),
   autostart: new Set(["workspace", "stateDir", "quiet"]),
   resource: new Set(["workspace", "stateDir", "allowInsecurePermissions", "showPaths", "json"]),
+  browser: new Set(["workspace", "stateDir", "json"]),
   job: new Set(["workspace", "stateDir", "json", "yes"]),
   uninstall: new Set(["stateDir", "keepWorker", "yes"]),
 };
@@ -149,6 +153,10 @@ const ACTION_POSITIONAL_RULES = Object.freeze({
     const action = String(args._[0] || "list");
     return { max: RESOURCE_POSITIONAL_LIMITS[action] ?? 1, tooMany: `resource ${action} received too many positional arguments` };
   },
+  browser(args) {
+    const action = String(args._[0] || "status");
+    return { max: 1, tooMany: `browser ${action} received too many positional arguments` };
+  },
   job(args) {
     const action = String(args._[0] || "list");
     return { max: JOB_POSITIONAL_LIMITS[action] ?? 1, tooMany: `job ${action} received too many positional arguments` };
@@ -426,6 +434,7 @@ function createRemoteRuntime({ args, workspace, state, daemonLock, logger }) {
     jobRoot: join(state.paths.profileDir, "jobs"),
     resources: state.resources,
     resourceStatePath: state.paths.statePath,
+    browserStateRoot: state.paths.stateRoot,
     onSuperseded: () => {
       daemonLock.release();
       process.exit(0);
@@ -537,6 +546,7 @@ async function stdioCommand(args) {
     jobRoot: join(state.paths.profileDir, "jobs"),
     resources: state.resources,
     resourceStatePath: state.paths.statePath,
+    browserStateRoot: state.paths.stateRoot,
   });
 }
 
@@ -698,6 +708,78 @@ function publicResourceInspection(name, inspected, { includePath = false, ...ext
   };
 }
 
+async function browserCommand(args) {
+  const action = String(args._[0] || "status").toLowerCase();
+  const extensionPath = resolve(packageRoot, "browser-extension");
+  if (action === "path") {
+    if (args.json) console.log(JSON.stringify({ extension_path: extensionPath }, null, 2));
+    else console.log(extensionPath);
+    return;
+  }
+  if (!["status", "setup", "pair"].includes(action)) throw new Error(`Unknown browser action: ${action}`);
+  const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
+  const state = loadState(workspace, { stateDir: args.stateDir });
+  const pairingFile = join(state.paths.stateRoot, "browser-bridge.json");
+  if (!existsSync(pairingFile)) {
+    throw new Error("browser bridge is not initialized; start machine-mcp once, then run this command again");
+  }
+  ownerOnlyFile(pairingFile);
+  let pairing;
+  try {
+    pairing = JSON.parse(readBoundedRegularFileSync(pairingFile, 64 * 1024).toString("utf8"));
+  } catch {
+    throw new Error("browser bridge state is invalid; restart machine-mcp to repair it");
+  }
+  const port = Number(pairing.port);
+  if (!/^[A-Za-z0-9_-]{32,100}$/.test(String(pairing.token || ""))) throw new Error("browser bridge state contains an invalid token");
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("browser bridge state contains an invalid port");
+  const pairingUrl = `http://127.0.0.1:${port}/pair`;
+  const healthUrl = `http://127.0.0.1:${port}/healthz`;
+  const health = await fetch(healthUrl, { signal: AbortSignal.timeout(2000), cache: "no-store" })
+    .then(async (response) => response.ok ? await response.json() : null)
+    .catch(() => null);
+  const result = {
+    running: health?.ok === true && health?.broker === "machine-bridge-browser",
+    connected: health?.broker === "machine-bridge-browser" && health?.connected === true,
+    extension_path: extensionPath,
+    pairing_url: pairingUrl,
+    token_exposed: false,
+  };
+  if (action === "status") {
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(`Browser bridge: ${result.running ? "running" : "not reachable"}`);
+      console.log(`Extension: ${result.connected ? "connected" : "not connected"}`);
+      console.log(`Extension path: ${extensionPath}`);
+    }
+    return;
+  }
+  if (!result.running) throw new Error("browser bridge is not reachable; keep machine-mcp running and retry");
+  await openExternal(pairingUrl);
+  if (args.json) console.log(JSON.stringify({ ...result, pairing_page_opened: true }, null, 2));
+  else {
+    console.log(`Extension path: ${extensionPath}`);
+    console.log("Load this directory once from the Chromium extensions page with Developer mode enabled.");
+    console.log(`Pairing page opened: ${pairingUrl}`);
+  }
+}
+
+function openExternal(target) {
+  const command = process.platform === "darwin"
+    ? { file: "open", args: [target] }
+    : process.platform === "win32"
+      ? { file: "cmd.exe", args: ["/d", "/s", "/c", "start", "", target] }
+      : { file: "xdg-open", args: [target] };
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command.file, command.args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.once("spawn", () => {
+      child.unref();
+      resolvePromise();
+    });
+    child.once("error", rejectPromise);
+  });
+}
+
 async function jobCommand(args) {
   const action = String(args._[0] || "list").toLowerCase();
   const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
@@ -1367,6 +1449,9 @@ Commands:
   rotate-secrets    Rotate MCP password and daemon secret in local state
   resource generate-ssh-key NAME [PATH]
                     Generate/reuse an Ed25519 key locally and register its private file by alias
+  browser status    Show browser-extension bridge and connection status
+  browser setup     Print the extension path and open the local pairing page
+  browser path      Print the packaged unpacked-extension directory
   uninstall         Delete known Worker(s), remove autostart and local state
 
 Start options:

package/src/local/runtime.mjs

@@ -11,10 +11,13 @@ import { MAX_COMMAND_BYTES, ProcessSessionManager, terminateProcessTree, validat
 export { MAX_COMMAND_BYTES } from "./process-sessions.mjs";
 import { allToolNames, assertCanonicalFullPolicy, isCanonicalFullPolicy, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, normalizePolicy, POLICY_PROFILES, SERVER_NAME, toolNamesForPolicy } from "./tools.mjs";
 import { classifyOperationalError } from "./log.mjs";
-import { ManagedJobManager } from "./managed-jobs.mjs";
+import { inspectResourceFile, ManagedJobManager } from "./managed-jobs.mjs";
 import { generateRegisteredSshKey } from "./resource-operations.mjs";
 import { expandHome } from "./state.mjs";
 import { AgentContextManager } from "./agent-context.mjs";
+import { AppAutomationManager } from "./app-automation.mjs";
+import { BrowserBridgeManager } from "./browser-bridge.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
 
 export const MAX_WRITE_BYTES = 5 * 1024 * 1024;
 const MAX_WS_MESSAGE_BYTES = 8 * 1024 * 1024;
@@ -28,11 +31,26 @@ const SLOW_TOOL_CALL_MS = 30_000;
 const RUNTIME_TOOL_HANDLERS = Object.freeze({
   server_info: (runtime) => runtime.runtimeInfo(),
   project_overview: (runtime, _args, context) => runtime.projectOverview(context),
+  session_bootstrap: (runtime, args, context) => runtime.sessionBootstrap(args, context),
   agent_context: (runtime, args, context) => runtime.agentContextManager.agentContext(args, context),
+  resolve_task_capabilities: (runtime, args, context) => runtime.resolveTaskCapabilities(args, context),
   list_local_skills: (runtime, args, context) => runtime.agentContextManager.listLocalSkills(args, context),
   load_local_skill: (runtime, args, context) => runtime.agentContextManager.loadLocalSkill(args, context),
   list_local_commands: (runtime, args, context) => runtime.agentContextManager.listLocalCommands(args, context),
   run_local_command: (runtime, args, context) => runtime.runLocalCommand(args, context),
+  list_local_applications: (runtime, args, context) => runtime.appAutomationManager.listApplications(args, context),
+  open_local_application: (runtime, args, context) => runtime.appAutomationManager.openApplication(args, context),
+  inspect_local_application: (runtime, args, context) => runtime.appAutomationManager.inspectApplication(args, context),
+  operate_local_application: (runtime, args, context) => runtime.appAutomationManager.operateApplication(args, context),
+  browser_status: (runtime, _args, context) => runtime.browserBridgeManager.status(context),
+  pair_browser_extension: (runtime, args, context) => runtime.browserBridgeManager.pair(args, context),
+  browser_list_tabs: (runtime, args, context) => runtime.browserBridgeManager.listTabs(args, context),
+  browser_get_source: (runtime, args, context) => runtime.browserBridgeManager.getSource(args, context),
+  browser_inspect_page: (runtime, args, context) => runtime.browserBridgeManager.inspectPage(args, context),
+  browser_action: (runtime, args, context) => runtime.browserBridgeManager.act(args, context),
+  browser_fill_form: (runtime, args, context) => runtime.browserBridgeManager.fillForm(args, context),
+  browser_screenshot: (runtime, args, context) => runtime.browserBridgeManager.screenshot(args, context),
+  browser_upload_files: (runtime, args, context) => runtime.browserBridgeManager.uploadFiles(args, context),
   list_roots: (runtime) => runtime.listRoots(),
   list_dir: (runtime, args, context) => runtime.listDir(args.path || ".", context),
   list_files: (runtime, args, context) => runtime.listFiles(args.path || ".", clampInt(args.max_files, 1000, 1, 10000), context),
@@ -67,7 +85,7 @@ export function runtimeToolHandlerNames() {
 }
 
 export class LocalRuntime {
-  constructor({ workerUrl = "", secret = "", expectedRelayVersion = "", workspace, policy, logger = console, onSuperseded = null, onFatal = null, jobRoot = "", resources = {}, resourceStatePath = "", recoverJobs = true }) {
+  constructor({ workerUrl = "", secret = "", expectedRelayVersion = "", workspace, policy, logger = console, onSuperseded = null, onFatal = null, jobRoot = "", resources = {}, resourceStatePath = "", browserStateRoot = "", agentHome = process.env.HOME || process.env.USERPROFILE || "", codexHome = process.env.CODEX_HOME || "", recoverJobs = true }) {
     const remoteWorkerUrl = workerUrl ? String(workerUrl) : "";
     const remoteSecret = secret || "";
     this.workspaceInput = resolve(workspace || process.cwd());
@@ -113,6 +131,26 @@ export class LocalRuntime {
       displayPath: (value) => this.displayPath(value),
       resolveExistingPath: (value) => this.resolveExistingPath(value),
       throwIfCancelled: (context) => this.throwIfCancelled(context),
+      home: agentHome,
+      codexHome,
+    });
+    const runProcess = (cmd, argv, timeoutMs, allowFailure, maxOutputBytes, context, cwd, stdin) => this.runProcess(cmd, argv, timeoutMs, allowFailure, maxOutputBytes, context, cwd, stdin);
+    const readResourceText = (name) => this.readLocalResourceText(name);
+    const readResourceBinary = (name) => this.readLocalResourceBinary(name);
+    this.appAutomationManager = new AppAutomationManager({
+      policy: this.policy,
+      displayPath: (value) => this.displayPath(value),
+      runProcess,
+      readResourceText,
+      throwIfCancelled: (context) => this.throwIfCancelled(context),
+    });
+    this.browserBridgeManager = new BrowserBridgeManager({
+      policy: this.policy,
+      stateRoot: browserStateRoot,
+      runProcess,
+      readResourceText,
+      readResourceBinary,
+      throwIfCancelled: (context) => this.throwIfCancelled(context),
     });
     this.relay = createRelayConnection(this, {
       workerUrl: remoteWorkerUrl,
@@ -170,8 +208,13 @@ export class LocalRuntime {
     };
   }
 
-  start() {
+  async start() {
     if (!this.relay) throw new Error("remote daemon start requires a Worker URL and daemon secret");
+    if (this.policy.profile === "full") {
+      void this.browserBridgeManager.ensureStarted().catch((error) => {
+        this.logger.warn?.("browser bridge did not start; browser tools remain unavailable", { error_class: classifyOperationalError(error) });
+      });
+    }
     return this.relay.start();
   }
 
@@ -179,6 +222,7 @@ export class LocalRuntime {
     this.relay?.stop();
     this.terminateActiveProcesses("SIGKILL");
     this.processSessionManager.clear();
+    this.browserBridgeManager?.stop();
     rmSync(this.runtimeDir, { recursive: true, force: true });
   }
 
@@ -277,6 +321,7 @@ export class LocalRuntime {
   cancelCall(callId, reason = "cancelled") {
     this.cancelledCalls.add(callId);
     this.processSessionManager.notifyCancellation();
+    this.browserBridgeManager?.cancelCall(callId);
     for (const child of this.callProcesses.get(callId) || []) terminateProcessTree(child, "SIGTERM");
     const children = [...(this.callProcesses.get(callId) || [])];
     if (children.length) {
@@ -738,6 +783,57 @@ export class LocalRuntime {
     };
   }
 
+
+  async sessionBootstrap(args = {}, context = {}) {
+    const bootstrap = await this.agentContextManager.sessionBootstrap(args, context);
+    bootstrap.local_automation = {
+      applications: this.appAutomationManager.capabilities(),
+      browser: this.policy.profile === "full" ? {
+        existing_profile: true,
+        extension_bridge: true,
+        status_tool: "browser_status",
+      } : null,
+    };
+    return bootstrap;
+  }
+
+  async resolveTaskCapabilities(args = {}, context = {}) {
+    const result = await this.agentContextManager.resolveTaskCapabilities(args, context);
+    const task = String(args.task || "");
+    if (/app|application|gui|window|应用|软件|窗口|界面/i.test(task) && this.policy.profile === "full") {
+      const applications = await this.appAutomationManager.listApplications({ query: "", max_results: 500 }, context).catch(() => ({ applications: [] }));
+      const lower = task.toLowerCase();
+      result.application_matches = applications.applications
+        .map((application) => ({ application, score: applicationMatchScore(lower, application) }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || left.application.name.localeCompare(right.application.name))
+        .slice(0, 20)
+        .map(({ application, score }) => ({ ...application, score }));
+    } else {
+      result.application_matches = [];
+    }
+    result.browser_backend = this.policy.profile === "full" ? { tool: "browser_status", existing_profile: true, extension_bridge: true } : null;
+    return result;
+  }
+
+  readLocalResourceBinary(name) {
+    const registry = this.managedJobManager.currentResources();
+    const resource = registry[name];
+    if (!resource) throw new Error(`unknown local resource: ${name}`);
+    const inspected = inspectResourceFile(resource.path, { allowInsecurePermissions: resource.allowInsecurePermissions === true });
+    if (inspected.size > 1024 * 1024) throw new Error("local resource exceeds 1 MiB browser injection limit");
+    return { buffer: readBoundedRegularFileSync(resource.path, 1024 * 1024), path: resource.path, size: inspected.size };
+  }
+
+  readLocalResourceText(name) {
+    const { buffer } = this.readLocalResourceBinary(name);
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+    } catch {
+      throw new Error(`local resource is not valid UTF-8 text: ${name}`);
+    }
+  }
+
   async runDirectProcess(args, context = {}) {
     if (this.policy.execMode !== "direct" && this.policy.execMode !== "shell") throw new Error("run_process is disabled by daemon policy");
     const argv = validateArgv(args.argv);
@@ -785,9 +881,10 @@ export class LocalRuntime {
     }
   }
 
-  async runProcess(cmd, args, timeoutMs, allowFailure = false, maxOutputBytes = 512 * 1024, context = {}, cwd = this.workspace) {
+  async runProcess(cmd, args, timeoutMs, allowFailure = false, maxOutputBytes = 512 * 1024, context = {}, cwd = this.workspace, stdin = null) {
     this.throwIfCancelled(context);
     return new Promise((resolvePromise, reject) => {
+      if (stdin !== null && Buffer.byteLength(String(stdin)) > 1024 * 1024) throw new Error("process stdin exceeds 1 MiB");
       const child = spawn(cmd, args, {
         cwd,
         env: executionEnv(this.workspace, { fullEnv: this.policy.minimalEnv === false, runtimeDir: this.runtimeDir }),
@@ -795,6 +892,10 @@ export class LocalRuntime {
         windowsHide: true,
       });
       this.activeProcesses.add(child);
+      if (stdin !== null) {
+        child.stdin.on("error", () => {});
+        child.stdin.end(String(stdin));
+      }
       if (context.callId) {
         const set = this.callProcesses.get(context.callId) || new Set();
         set.add(child);
@@ -965,6 +1066,15 @@ export class LocalRuntime {
   }
 }
 
+function applicationMatchScore(task, application) {
+  const name = String(application.name || "").toLowerCase();
+  const id = String(application.id || "").toLowerCase();
+  if (!name) return 0;
+  if (task.includes(name)) return 10 + Math.min(name.length, 20);
+  const words = name.split(/[^\p{L}\p{N}]+/u).filter((word) => word.length >= 2);
+  return words.reduce((score, word) => score + (task.includes(word) ? 2 : 0), id && task.includes(id) ? 5 : 0);
+}
+
 function policyMatchesNamedProfile(policy) {
   const named = POLICY_PROFILES[policy.profile];
   if (!named) return false;

package/src/local/state.mjs

@@ -361,7 +361,7 @@ function assertValidStateMarker(marker, options = {}) {
 }
 
 function hasOnlyStateEntries(entries) {
-  const allowed = new Set([STATE_MARKER, "config.json", "profiles", "logs"]);
+  const allowed = new Set([STATE_MARKER, "config.json", "browser-bridge.json", "profiles", "logs"]);
   return entries.every((entry) => allowed.has(entry) || /^config\.json\.corrupt-\d+(?:-[a-f0-9]{8})?$/.test(entry));
 }
 

package/src/local/stdio.mjs

@@ -17,9 +17,9 @@ const MAX_LINE_BYTES = 8 * 1024 * 1024;
 const SLOW_TOOL_CALL_MS = 30_000;
 const PACKAGE_VERSION = String(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version);
 
-export async function runStdioServer({ workspace, policy, logLevel = "info", jobRoot = "", resources = {}, resourceStatePath = "" }) {
+export async function runStdioServer({ workspace, policy, logLevel = "info", jobRoot = "", resources = {}, resourceStatePath = "", browserStateRoot = "" }) {
   const logger = createLogger({ component: "stdio", level: logLevel, stderrOnly: true, color: false });
-  const runtime = new LocalRuntime({ workspace, policy, logger, jobRoot, resources, resourceStatePath });
+  const runtime = new LocalRuntime({ workspace, policy, logger, jobRoot, resources, resourceStatePath, browserStateRoot });
   const pending = new Map();
   let negotiatedVersion = MCP_PROTOCOL_VERSION;
   let initialized = false;
@@ -52,7 +52,7 @@ export async function runStdioServer({ workspace, policy, logLevel = "info", job
   async function handleLine(line) {
     const message = parseJsonRpcLine(line, send);
     if (!message || typeof message.method !== "string") return;
-    if (handleControlMessage(message)) return;
+    if (await handleControlMessage(message)) return;
     if (!initialized) {
       send(rpcError(message.id, -32002, "Server is not initialized"));
       return;
@@ -60,14 +60,14 @@ export async function runStdioServer({ workspace, policy, logLevel = "info", job
     await handleInitializedMessage(message);
   }
 
-  function handleControlMessage(message) {
+  async function handleControlMessage(message) {
     if (message.method === "initialize") {
       const requested = asObject(message.params).protocolVersion;
       negotiatedVersion = typeof requested === "string" && MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
         ? requested
         : MCP_PROTOCOL_VERSION;
       initialized = true;
-      send(rpcResult(message.id, initializationResult(negotiatedVersion)));
+      send(rpcResult(message.id, await initializationResult(negotiatedVersion, runtime)));
       return true;
     }
     if (message.method === "notifications/initialized") return true;
@@ -148,7 +148,12 @@ function parseJsonRpcLine(line, send) {
   return message;
 }
 
-function initializationResult(protocolVersion) {
+async function initializationResult(protocolVersion, runtime) {
+  const bootstrap = await runtime.sessionBootstrap({ path: "." }).catch((error) => {
+    runtime.logger?.debug?.("session bootstrap unavailable during initialize", { error_class: classifyOperationalError(error) });
+    return null;
+  });
+  const localInstructions = bootstrap?.instructions ? `\n\n--- LOCAL SESSION INSTRUCTIONS ---\n${bootstrap.instructions}` : "";
   return {
     protocolVersion,
     capabilities: { tools: { listChanged: false }, logging: {} },
@@ -158,7 +163,7 @@ function initializationResult(protocolVersion) {
       version: PACKAGE_VERSION,
       description: "Workspace-scoped local coding tools over MCP stdio or authenticated remote relay.",
     },
-    instructions: MCP_INSTRUCTIONS,
+    instructions: `${MCP_INSTRUCTIONS}${localInstructions}`,
   };
 }
 

package/src/shared/server-metadata.json

@@ -8,7 +8,10 @@
   ],
   "instructions": [
     "You are connected to a local workspace through machine-bridge-mcp.",
-    "For substantive workspace tasks, call agent_context for the relevant target path before editing or executing. Apply returned instruction files in precedence order, load only relevant local skills, and prefer registered local commands for repeatable workflows.",
+    "At the start of each substantive local task, call resolve_task_capabilities with the current user request and target path. Apply the returned session/project instructions, follow the automatically selected relevant skill when present, and prefer registered local commands for repeatable workflows.",
+    "The MCP initialize response automatically appends the configured global model_instructions_file and current root instruction chain when the local daemon is reachable; session_bootstrap exposes the same material explicitly.",
+    "For existing-browser work, use the paired Machine Bridge browser extension. It operates the user current Chromium profile and tabs, can inspect DOM/source, fill complex forms, and inject sensitive text from registered local resources without returning those values.",
+    "For local application work, use structured application discovery and Accessibility actions. Arbitrary caller-supplied AppleScript or JavaScript is intentionally not accepted.",
     "Remote mode uses a Cloudflare relay; stdio mode runs on the local machine. File and command operations execute on the user's local runtime, not in the Worker.",
     "Filesystem scope and path display follow the active local policy; the default full profile is unrestricted.",
     "Filename sensitivity is not classified by this server; the MCP host, connector gateway, local OS, or endpoint-security software may enforce additional independent rules.",