machine-bridge-mcp 1.2.8 → 1.2.10

package/src/local/relay-call-recovery.mjs

@@ -0,0 +1,148 @@
+// @ts-check
+
+/** @typedef {{id?: unknown, [key: string]: unknown}} RelayResult */
+/** @typedef {{event?: (level: string, name: string, fields: Record<string, unknown>, message: string) => void, warn?: (message: string) => void}} RecoveryLogger */
+/** @typedef {{setTimeout: (callback: () => void, delay: number) => any, clearTimeout: (handle: any) => void}} RecoveryScheduler */
+/**
+ * @typedef {{
+ *   logger?: RecoveryLogger,
+ *   send?: (value: RelayResult) => boolean,
+ *   isRecoverable?: () => boolean,
+ *   activeCallIds?: () => Iterable<string>,
+ *   suppressCall?: (callId: string, reason: string) => void,
+ *   cancelOrigin?: (reason: string) => number,
+ *   terminate?: () => void,
+ *   graceMs?: unknown,
+ *   scheduler?: RecoveryScheduler,
+ * }} RelayCallRecoveryOptions
+ */
+
+const DEFAULT_RECONNECT_GRACE_MS = 30_000;
+
+export class RelayCallRecovery {
+  /** @param {RelayCallRecoveryOptions} [options] */
+  constructor(options = {}) {
+    /** @type {RecoveryLogger} */
+    this.logger = options.logger || { warn: (message) => console.warn(message) };
+    this.send = typeof options.send === "function" ? options.send : () => false;
+    this.isRecoverable = typeof options.isRecoverable === "function" ? options.isRecoverable : () => false;
+    this.activeCallIds = typeof options.activeCallIds === "function" ? options.activeCallIds : () => [];
+    this.suppressCall = typeof options.suppressCall === "function" ? options.suppressCall : () => {};
+    this.cancelOrigin = typeof options.cancelOrigin === "function" ? options.cancelOrigin : () => 0;
+    this.terminate = typeof options.terminate === "function" ? options.terminate : () => {};
+    this.graceMs = positiveInteger(options.graceMs, DEFAULT_RECONNECT_GRACE_MS);
+    this.scheduler = options.scheduler || { setTimeout, clearTimeout };
+    /** @type {Map<string, RelayResult>} */
+    this.pendingResults = new Map();
+    /** @type {any} */
+    this.reconnectTimer = null;
+  }
+
+  /** @param {RelayResult} response */
+  deliver(response) {
+    const callId = String(response?.id || "");
+    if (this.send(response)) {
+      if (callId) this.pendingResults.delete(callId);
+      return true;
+    }
+    if (callId && this.isRecoverable()) {
+      this.pendingResults.set(callId, response);
+      this.scheduleExpiry();
+      this.logger.event?.("debug", "relay.tool_result.queued", {
+        call_id: shortCallId(callId), queued_results: this.pendingResults.size,
+      }, "Queued a completed tool result while the relay reconnects");
+      return false;
+    }
+    this.logger.event?.("debug", "relay.tool_result.discarded", {
+      call_id: shortCallId(callId), reason: "transport_unavailable",
+    }, "Discarded a tool result because the relay is no longer recoverable");
+    return false;
+  }
+
+  /** @param {unknown} callId */
+  discard(callId) {
+    return this.pendingResults.delete(String(callId));
+  }
+
+  /** @param {Iterable<string>} resumedCallIds @param {(callId: string) => boolean} cancelCall */
+  reconcile(resumedCallIds, cancelCall) {
+    const resumed = new Set(resumedCallIds);
+    let cancelled = 0;
+    let discarded = 0;
+    for (const callId of this.activeCallIds()) {
+      if (!resumed.has(callId) && cancelCall(callId)) cancelled += 1;
+    }
+    for (const callId of [...this.pendingResults.keys()]) {
+      if (!resumed.has(callId) && this.pendingResults.delete(callId)) discarded += 1;
+    }
+    if (cancelled > 0 || discarded > 0) {
+      this.logger.event?.("debug", "relay.calls.reconciled", { cancelled_calls: cancelled, discarded_results: discarded },
+        "Cancelled relay work that no longer had a waiting client after reconnect");
+    }
+  }
+
+  disconnected() {
+    const activeCalls = [...this.activeCallIds()].length;
+    if (activeCalls === 0 && this.pendingResults.size === 0) return;
+    this.scheduleExpiry();
+    this.logger.event?.("debug", "relay.calls.awaiting_reconnect", {
+      active_calls: activeCalls, queued_results: this.pendingResults.size, grace_ms: this.graceMs,
+    }, "Keeping in-flight tool calls alive during a brief relay interruption");
+  }
+
+  ready() {
+    this.clearTimer();
+    let delivered = 0;
+    for (const [callId, response] of [...this.pendingResults]) {
+      if (!this.send(response)) {
+        this.scheduleExpiry();
+        break;
+      }
+      this.pendingResults.delete(callId);
+      delivered += 1;
+    }
+    if (delivered > 0) {
+      this.logger.event?.("info", "relay.tool_results.replayed", { delivered_results: delivered },
+        "Delivered completed tool results after the relay reconnected");
+    }
+  }
+
+  stop() {
+    this.clearTimer();
+    this.pendingResults.clear();
+  }
+
+  scheduleExpiry() {
+    if (this.reconnectTimer) return;
+    this.reconnectTimer = this.scheduler.setTimeout(() => {
+      this.reconnectTimer = null;
+      for (const callId of this.activeCallIds()) this.suppressCall(callId, "relay_reconnect_timeout");
+      const cancelled = this.cancelOrigin("remote relay reconnect grace expired");
+      const discarded = this.pendingResults.size;
+      this.pendingResults.clear();
+      this.terminate();
+      if (cancelled > 0 || discarded > 0) {
+        this.logger.warn?.(`remote relay did not recover within ${this.graceMs / 1000} seconds; cancelled ${cancelled} call(s) and discarded ${discarded} queued result(s)`);
+      }
+    }, this.graceMs);
+    this.reconnectTimer?.unref?.();
+  }
+
+  clearTimer() {
+    if (!this.reconnectTimer) return;
+    this.scheduler.clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
+}
+
+/** @param {unknown} value @param {number} fallback */
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}
+
+/** @param {unknown} value */
+function shortCallId(value) {
+  const text = String(value || "");
+  return text.length <= 18 ? text : `${text.slice(0, 10)}...${text.slice(-5)}`;
+}

package/src/local/relay-connection.mjs

@@ -31,6 +31,7 @@ export class RelayConnection {
     this.expectedVersion = String(options.expectedVersion || "");
     this.onMessage = typeof options.onMessage === "function" ? options.onMessage : () => {};
     this.onDisconnect = typeof options.onDisconnect === "function" ? options.onDisconnect : () => {};
+    this.onReady = typeof options.onReady === "function" ? options.onReady : () => {};
     this.onSuperseded = typeof options.onSuperseded === "function" ? options.onSuperseded : () => {};
     this.onFatal = typeof options.onFatal === "function" ? options.onFatal : () => {};
     this.WebSocketClass = options.WebSocketClass || WebSocket;
@@ -230,8 +231,12 @@ export class RelayConnection {
       }
     }
 
+    const reconnected = this.hasConnected;
     this.hasConnected = true;
     this.resetOutage();
+    try { this.onReady({ reconnected, sessionId: this.activeSessionId }); } catch (error) {
+      this.logger.error?.("relay ready callback failed", { error_class: classifyOperationalError(error) });
+    }
     if (this.connectedOnceResolve) {
       this.connectedOnceResolve(true);
       this.connectedOnceResolve = null;

package/src/local/runtime-paths.mjs

@@ -0,0 +1,107 @@
+// @ts-check
+import { mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/**
+ * @typedef {object} RuntimeRedactionOptions
+ * @property {unknown} error
+ * @property {unknown} toolArgs
+ * @property {string} workspace
+ * @property {string} workspaceInput
+ * @property {string} runtimeDir
+ * @property {string | undefined} home
+ * @property {(value: string) => string} displayPath
+ */
+
+/** @param {string} statePath */
+export function stateRootFromProfileStatePath(statePath) {
+  const absolute = resolve(statePath);
+  if (basename(absolute) !== "state.json") throw new Error("local resource state path is invalid");
+  const profileDir = dirname(absolute);
+  const profilesDir = dirname(profileDir);
+  if (basename(profilesDir) !== "profiles") throw new Error("local resource state path is outside the expected profile layout");
+  return dirname(profilesDir);
+}
+
+/** @param {string} root @param {string} target */
+export function assertContainedPath(root, target) {
+  const rel = relative(root, target);
+  if (rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel))) return;
+  throw new Error("path is outside the configured workspace; restart with --unrestricted-paths to allow it");
+}
+
+export function createRuntimeDir() {
+  const root = mkdtempSync(join(tmpdir(), "machine-bridge-mcp-"));
+  for (const name of ["home", "tmp", "cache"]) mkdirSync(join(root, name), { recursive: true, mode: 0o700 });
+  return root;
+}
+
+/** @param {unknown} message @param {RuntimeRedactionOptions} options */
+export function redactRuntimeErrorMessage(message, {
+  error,
+  toolArgs,
+  workspace,
+  workspaceInput,
+  runtimeDir,
+  home,
+  displayPath,
+}) {
+  let redacted = String(message);
+  for (const prefix of equivalentPathPrefixes(workspace, workspaceInput)) redacted = replacePathPrefix(redacted, prefix, ".");
+  for (const prefix of equivalentPathPrefixes(runtimeDir)) redacted = replacePathPrefix(redacted, prefix, "<runtime>");
+  if (home) redacted = replacePathPrefix(redacted, resolve(home), "<home>");
+  for (const candidate of collectToolPathCandidates(error, toolArgs, workspaceInput)) {
+    const absolute = isAbsolute(candidate) ? resolve(candidate) : resolve(workspaceInput, candidate);
+    const replacement = displayPath(absolute);
+    for (const prefix of equivalentPathPrefixes(candidate, absolute)) redacted = replacePathPrefix(redacted, prefix, replacement);
+  }
+  return redacted;
+}
+
+/** @param {unknown} error @param {unknown} toolArgs @param {string} workspace */
+function collectToolPathCandidates(error, toolArgs, workspace) {
+  /** @type {Set<string>} */
+  const candidates = new Set();
+  const pathError = error && typeof error === "object"
+    ? /** @type {{ path?: unknown, dest?: unknown }} */ (error)
+    : {};
+  for (const value of [pathError.path, pathError.dest]) {
+    if (typeof value === "string" && value) candidates.add(value);
+  }
+  /** @param {unknown} value @param {string} [key] @param {number} [depth] */
+  const visit = (value, key = "", depth = 0) => {
+    if (depth > 5 || value === null || value === undefined) return;
+    if (typeof value === "string") {
+      if (/(?:^|[_-])(?:path|cwd|workspace|root|directory|dir)(?:$|[_-])/i.test(key) && value && !value.includes("\0")) candidates.add(value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value.slice(0, 64)) visit(item, key, depth + 1);
+      return;
+    }
+    if (typeof value !== "object") return;
+    for (const [childKey, child] of Object.entries(/** @type {Record<string, unknown>} */ (value)).slice(0, 128)) {
+      visit(child, childKey, depth + 1);
+    }
+  };
+  visit(toolArgs);
+  candidates.delete(workspace);
+  return [...candidates].sort((left, right) => right.length - left.length);
+}
+
+/** @param {...(string | null | undefined)} values */
+function equivalentPathPrefixes(...values) {
+  const prefixes = new Set(values.filter(Boolean).map((value) => String(value)));
+  for (const value of [...prefixes]) {
+    if (value.startsWith("/private/")) prefixes.add(value.slice("/private".length));
+    else if (value.startsWith("/") && ["/var/", "/tmp/", "/etc/"].some((prefix) => value.startsWith(prefix))) prefixes.add(`/private${value}`);
+  }
+  return [...prefixes].sort((left, right) => right.length - left.length);
+}
+
+/** @param {string} message @param {string} pathValue @param {string} replacement */
+function replacePathPrefix(message, pathValue, replacement) {
+  if (!pathValue) return message;
+  return message.split(pathValue).join(replacement);
+}

package/src/local/runtime-relay.mjs

@@ -0,0 +1,89 @@
+import { Buffer } from "node:buffer";
+import { RelayConnection } from "./relay-connection.mjs";
+import { MCP_SUPPORTED_PROTOCOL_VERSIONS, SERVER_NAME } from "./tools.mjs";
+import { normalizeAccountRole } from "./account-access.mjs";
+import { clampInteger } from "./numbers.mjs";
+import { isPlainRecord } from "./records.mjs";
+
+export const MAX_RELAY_MESSAGE_BYTES = 8 * 1024 * 1024;
+
+export function createRuntimeRelayConnection(runtime, { workerUrl, secret, expectedVersion, onFatal }) {
+  if (!workerUrl) return null;
+  return new RelayConnection({
+    workerUrl,
+    secret,
+    logger: runtime.logger,
+    maxPayload: MAX_RELAY_MESSAGE_BYTES,
+    expectedServer: SERVER_NAME,
+    expectedVersion: String(expectedVersion || ""),
+    helloMessage: () => ({
+      type: "hello",
+      instance_id: runtime.relayInstanceId,
+      tools: runtime.tools(),
+      policy: runtime.policy,
+      protocol_versions: MCP_SUPPORTED_PROTOCOL_VERSIONS,
+    }),
+    onMessage: (data, relayContext) => handleRelayData(runtime, data, relayContext),
+    onDisconnect: () => runtime.handleRelayDisconnect(),
+    onReady: () => runtime.handleRelayReady(),
+    onSuperseded: () => {
+      runtime.terminateActiveProcesses("SIGKILL");
+      runtime.processSessionManager.clear();
+      runtime.onSuperseded?.();
+    },
+    onFatal: (error) => {
+      runtime.terminateActiveProcesses("SIGKILL");
+      runtime.processSessionManager.clear();
+      onFatal?.(error);
+    },
+  });
+}
+
+export function normalizeRelayResumeCalls(message) {
+  if (!Array.isArray(message?.ids) || message.ids.length > 32) return { ok: false, ids: [] };
+  const ids = [];
+  const seen = new Set();
+  for (const value of message.ids) {
+    if (typeof value !== "string" || !/^call_[A-Za-z0-9_-]{8,240}$/.test(value) || seen.has(value)) {
+      return { ok: false, ids: [] };
+    }
+    seen.add(value);
+    ids.push(value);
+  }
+  return { ok: true, ids };
+}
+
+export function normalizeRelayToolCall(message) {
+  const id = typeof message.id === "string" && message.id.length <= 256 ? message.id : "";
+  const tool = typeof message.tool === "string" && message.tool.length <= 128 ? message.tool : "";
+  const argumentsValue = message.arguments === undefined ? {} : message.arguments;
+  const authorization = normalizeRelayAuthorization(message.authorization);
+  if (!id || !tool || !isPlainRecord(argumentsValue) || !authorization) return { ok: false, id };
+  return {
+    ok: true,
+    id,
+    tool,
+    arguments: argumentsValue,
+    authorization,
+    timeoutMs: clampInteger(message.timeout_ms, 60_000, 1000, 610_000),
+  };
+}
+
+function handleRelayData(runtime, data, relayContext = {}) {
+  const raw = typeof data === "string" ? data : Buffer.from(data).toString("utf8");
+  if (Buffer.byteLength(raw) > MAX_RELAY_MESSAGE_BYTES) {
+    runtime.handleRelayProtocolViolation("server_message_too_large");
+    return;
+  }
+  return runtime.handleMessage(raw, relayContext);
+}
+
+function normalizeRelayAuthorization(value) {
+  if (!isPlainRecord(value)) return null;
+  const accountId = typeof value.account_id === "string" && /^acct_[A-Za-z0-9_-]{20,96}$/.test(value.account_id) ? value.account_id : "";
+  const accountVersion = Number(value.account_version);
+  let role;
+  try { role = normalizeAccountRole(value.role); } catch { return null; }
+  if (!accountId || !Number.isInteger(accountVersion) || accountVersion < 1) return null;
+  return Object.freeze({ account_id: accountId, account_version: accountVersion, role });
+}

package/src/local/runtime-tool-handlers.mjs

@@ -0,0 +1,66 @@
+import { clampInteger } from "./numbers.mjs";
+
+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_manage_tabs: (runtime, args, context) => runtime.browserBridgeManager.manageTabs(args, context),
+  browser_wait: (runtime, args, context) => runtime.browserBridgeManager.wait(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 || ".", clampInteger(args.max_files, 1000, 1, 10000), context),
+  read_file: (runtime, args, context) => runtime.readFile(args, context),
+  view_image: (runtime, args, context) => runtime.viewImage(args, context),
+  write_file: (runtime, args, context) => runtime.writeFile(args, context),
+  edit_file: (runtime, args, context) => runtime.editFile(args, context),
+  apply_patch: (runtime, args, context) => runtime.applyPatch(args, context),
+  search_text: (runtime, args, context) => runtime.searchText(args, context),
+  git_status: (runtime, args, context) => runtime.gitStatus(args, context),
+  git_diff: (runtime, args, context) => runtime.gitDiff(args, context),
+  git_log: (runtime, args, context) => runtime.gitLog(args, context),
+  git_show: (runtime, args, context) => runtime.gitShow(args, context),
+  diagnose_runtime: (runtime, _args, context) => runtime.diagnoseRuntime(context),
+  list_local_resources: (runtime) => runtime.managedJobManager.listResources(),
+  generate_ssh_key_resource: (runtime, args, context) => runtime.generateSshKeyResource(args, context),
+  stage_job: (runtime, args) => runtime.managedJobManager.stage(args),
+  start_job: (runtime, args) => runtime.managedJobManager.start(args),
+  list_jobs: (runtime, args) => runtime.managedJobManager.list(args),
+  read_job: (runtime, args) => runtime.managedJobManager.read(args),
+  cancel_job: (runtime, args) => runtime.managedJobManager.cancel(args),
+  run_process: (runtime, args, context) => runtime.runDirectProcess(args, context),
+  start_process: (runtime, args, context) => runtime.processSessionManager.start(args, context),
+  read_process: (runtime, args, context) => runtime.processSessionManager.read(args, context),
+  write_process: (runtime, args, context) => runtime.processSessionManager.write(args, context),
+  kill_process: (runtime, args, context) => runtime.processSessionManager.kill(args, context),
+  exec_command: (runtime, args, context) => runtime.execCommand(args.command, clampInteger(args.timeout_seconds, 120, 1, 600), context),
+});
+
+export function runtimeToolHandlerNames() {
+  return Object.keys(RUNTIME_TOOL_HANDLERS);
+}
+
+export function bindRuntimeToolHandlers(runtime) {
+  return Object.fromEntries(Object.entries(RUNTIME_TOOL_HANDLERS).map(([name, handler]) => [
+    name,
+    (args, context) => handler(runtime, args, context),
+  ]));
+}