machine-bridge-mcp 2.0.0 → 3.0.0-beta.9

package/src/local/relay-diagnostics.mjs

@@ -0,0 +1,65 @@
+export const APPLICATION_PROXY_ROUTE_SCOPE = "application-proxy-selection-only";
+
+export function relayStatusSnapshot(state, now = Date.now()) {
+  const current = Number(now) || 0;
+  return {
+    authenticated: state.authenticated === true,
+    ready: state.ready === true,
+    readiness_probe_delivered: state.readinessProbeDelivered === true,
+    closed: state.closed === true,
+    network_route: state.networkRoute,
+    network_route_scope: state.networkRouteScope,
+    reconnect_attempt: state.reconnectAttempt,
+    outage_active: state.outageStartedAt > 0,
+    outage_count: state.outageCount,
+    outage_started_at: isoTimestamp(state.outageStartedAt),
+    outage_duration_ms: state.outageStartedAt > 0 ? Math.max(0, current - state.outageStartedAt) : 0,
+    last_close_category: state.outageCount > 0 ? state.lastCloseCategory : null,
+    last_close_code: state.outageCount > 0 ? state.lastCloseCode : null,
+    last_transport_error_class: state.outageCount > 0 ? (state.lastTransportErrorClass || null) : null,
+    last_disconnected_at: isoTimestamp(state.lastDisconnectedAt),
+    last_ready_at: isoTimestamp(state.lastReadyAt),
+    last_ready_duration_ms: state.lastReadyDurationMs,
+    last_reconnect_delay_ms: state.lastReconnectDelayMs,
+    next_reconnect_at: isoTimestamp(state.nextReconnectAt),
+    next_reconnect_in_ms: state.nextReconnectAt > 0 ? Math.max(0, state.nextReconnectAt - current) : 0,
+    session_generation: state.sessionGeneration,
+  };
+}
+
+export function relayOutageFields(state, now, cause) {
+  const current = Number(now) || 0;
+  return {
+    event: "relay.outage.active",
+    outage_seconds: roundSeconds(Math.max(0, current - state.outageStartedAt)),
+    attempts: state.outageAttempts,
+    cause,
+    close_category: state.lastCloseCategory,
+    close_code: state.lastCloseCode,
+    network_route: state.networkRoute,
+    network_route_scope: state.networkRouteScope,
+    next_reconnect_in_ms: state.nextReconnectAt > 0 ? Math.max(0, state.nextReconnectAt - current) : 0,
+    ...(state.lastTransportErrorClass ? { error_class: state.lastTransportErrorClass } : {}),
+  };
+}
+
+export function relayRecoveryFields(state, outageMs) {
+  return {
+    event: "relay.outage.recovered",
+    outage_seconds: roundSeconds(outageMs),
+    attempts: state.outageAttempts,
+    close_category: state.lastCloseCategory,
+    close_code: state.lastCloseCode,
+    network_route: state.networkRoute,
+    network_route_scope: state.networkRouteScope,
+    ...(state.lastTransportErrorClass ? { error_class: state.lastTransportErrorClass } : {}),
+  };
+}
+
+function isoTimestamp(value) {
+  return Number(value) > 0 ? new Date(Number(value)).toISOString() : null;
+}
+
+function roundSeconds(milliseconds) {
+  return Math.max(1, Math.round(Number(milliseconds || 0) / 1000));
+}

package/src/local/remote-configuration.mjs

@@ -0,0 +1,48 @@
+import { effectiveLogFormat, effectiveLogLevel } from "./cli-options.mjs";
+import { resolvePolicy } from "./cli-policy.mjs";
+import { ensurePreferredDeviceRoot } from "./device-root-provider.mjs";
+import { createLogger } from "./log.mjs";
+import {
+  ensureWorkerSecrets,
+  promotePendingDeviceIdentity,
+  saveState,
+} from "./state.mjs";
+import { ensureWorkerDeployment } from "./worker-deployment.mjs";
+
+export async function convergeRemoteConfiguration({ args, state }) {
+  const workerName = validateWorkerName(args.workerName);
+  ensureWorkerSecrets(state, {
+    rotateSecrets: Boolean(args.rotateSecrets),
+    deferDeviceRotation: true,
+    workerName,
+    allowWorkerRename: Boolean(args.forceWorker),
+  });
+  if (!state.worker.pendingDeviceIdentity) {
+    const candidate = await ensurePreferredDeviceRoot({
+      profileDir: state.paths.profileDir,
+      workspaceHash: state.workspace.hash,
+      existing: args.rotateSecrets ? null : state.worker.deviceIdentity,
+      rotate: Boolean(args.rotateSecrets),
+    });
+    if (candidate.keyId !== state.worker.deviceIdentity.keyId) state.worker.pendingDeviceIdentity = candidate;
+  }
+  state.policy = resolvePolicy(args, state.policy);
+  state.policy.updatedAt = new Date().toISOString();
+  saveState(state);
+  const logger = createLogger({
+    level: args.json ? "error" : effectiveLogLevel(args),
+    format: effectiveLogFormat(args),
+    component: "worker",
+  });
+  await ensureWorkerDeployment(state, args, { logger });
+  if (promotePendingDeviceIdentity(state)) saveState(state);
+}
+
+export function validateWorkerName(value) {
+  if (value === undefined || value === null || value === false) return undefined;
+  const name = String(value).trim();
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(name)) {
+    throw new Error("--worker-name must be 1-63 lowercase letters, digits, or hyphens, and cannot start or end with a hyphen");
+  }
+  return name;
+}

package/src/local/runtime-activation.mjs

@@ -0,0 +1,141 @@
+export async function activatePersistentRuntime(options = {}) {
+  const required = [
+    "acquireStartupLock",
+    "stopAutostart",
+    "acquireDaemonLock",
+    "prepareRemoteState",
+    "createRuntime",
+    "installAutostart",
+    "startAutostart",
+    "inspectDaemon",
+    "checkWorker",
+  ];
+  for (const name of required) {
+    if (typeof options[name] !== "function") throw new TypeError(`runtime activation requires ${name}`);
+  }
+
+  const startupLock = await options.acquireStartupLock();
+  let startupReleased = false;
+  let daemonLock = null;
+  let candidateRuntime = null;
+  let candidateRelayVerified = false;
+  try {
+    const providerStop = await options.stopAutostart();
+    if (providerStop?.ok === false && providerStop?.active === true) {
+      throw new Error("the existing autostart service could not be stopped before activation");
+    }
+
+    daemonLock = await options.acquireDaemonLock();
+    if (!daemonLock?.acquired) {
+      const owner = daemonLock?.owner || {};
+      if (owner.mode === "foreground") {
+        throw new Error(`a foreground daemon is active (pid ${owner.pid || "unknown"}); stop it explicitly before activation`);
+      }
+      throw new Error(`the existing daemon could not be taken over (pid ${owner.pid || "unknown"})`);
+    }
+
+    const readiness = await options.prepareRemoteState();
+    candidateRuntime = options.createRuntime({ daemonLock, readiness });
+    if (!candidateRuntime || typeof candidateRuntime.start !== "function" || typeof candidateRuntime.stop !== "function") {
+      throw new TypeError("runtime activation candidate must expose start and stop");
+    }
+    await candidateRuntime.start();
+    candidateRelayVerified = true;
+
+    const installed = await options.installAutostart();
+    const terminalError = candidateRuntime.terminalError?.();
+    if (terminalError) throw terminalError;
+    if (installed?.ok === false) {
+      throw new Error(`autostart installation failed (${installed.provider || "unknown"})`);
+    }
+
+    candidateRuntime.stop();
+    candidateRuntime = null;
+    daemonLock.release();
+    daemonLock = null;
+    startupLock.release();
+    startupReleased = true;
+
+    const serviceStart = await options.startAutostart();
+    if (serviceStart?.ok === false) {
+      throw new Error(`autostart start failed (${serviceStart.provider || "unknown"})`);
+    }
+
+    const convergence = await waitForActivatedRuntime({
+      expectedVersion: options.expectedVersion,
+      inspectDaemon: options.inspectDaemon,
+      checkWorker: options.checkWorker,
+      maximumAttempts: options.maximumAttempts,
+      wait: options.wait,
+    });
+    if (!convergence.ok) {
+      throw new Error(`persistent runtime activation did not converge (${convergence.reason})`);
+    }
+    return {
+      ok: true,
+      serviceStart,
+      convergence,
+      candidateRelayVerified,
+    };
+  } catch (error) {
+    const cleanupErrors = [];
+    try { candidateRuntime?.stop?.(); } catch (failure) { cleanupErrors.push(failure); }
+    try { daemonLock?.release?.(); } catch (failure) { cleanupErrors.push(failure); }
+    if (!startupReleased) {
+      try { startupLock.release(); }
+      catch (failure) { cleanupErrors.push(failure); }
+    }
+    if (cleanupErrors.length) {
+      throw new AggregateError(
+        [error, ...cleanupErrors],
+        "persistent runtime activation failed and local cleanup was incomplete; inspect the daemon and service state before retrying",
+      );
+    }
+    throw error;
+  }
+}
+
+export async function waitForActivatedRuntime({
+  inspectDaemon,
+  checkWorker,
+  expectedVersion,
+  maximumAttempts = 240,
+  wait = defaultWait,
+} = {}) {
+  if (typeof inspectDaemon !== "function" || typeof checkWorker !== "function") {
+    throw new TypeError("runtime activation requires daemon and Worker inspectors");
+  }
+  const attempts = boundedAttempts(maximumAttempts);
+  let daemon = null;
+  let worker = null;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    daemon = await inspectDaemon();
+    if (daemon?.alive && daemon?.verified_service_daemon && daemon?.version === expectedVersion) {
+      worker = await checkWorker();
+      if (worker?.ok && worker?.version === expectedVersion) {
+        return { ok: true, attempts: attempt, daemon, worker };
+      }
+    }
+    if (attempt < attempts) await wait(attempt);
+  }
+  const reasons = [];
+  if (!daemon?.alive) reasons.push("daemon_not_running");
+  else if (!daemon?.verified_service_daemon) reasons.push(`daemon_identity_${daemon?.identity_reason || "unverified"}`);
+  else if (daemon?.version !== expectedVersion) reasons.push(`daemon_version_${daemon?.version || "unknown"}`);
+  if (!worker?.ok) reasons.push(`worker_${worker?.error || "not_ready"}`);
+  else if (worker?.version !== expectedVersion) reasons.push(`worker_version_${worker?.version || "unknown"}`);
+  return { ok: false, attempts, daemon, worker, reason: reasons.join(",") || "activation_not_converged" };
+}
+
+function boundedAttempts(value) {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 1200) {
+    throw new Error("runtime activation attempts must be between 1 and 1200");
+  }
+  return parsed;
+}
+
+function defaultWait(attempt) {
+  const delay = Math.min(1_000, 100 + attempt * 25);
+  return new Promise((resolvePromise) => { setTimeout(resolvePromise, delay); });
+}

package/src/local/runtime-diagnostics.mjs

@@ -11,6 +11,7 @@ export async function diagnoseRuntime({
   runProcess,
   probeShell,
   managedJobManager,
+  relayStatus = () => null,
   throwIfCancelled,
 }, context = {}) {
   throwIfCancelled(context);
@@ -24,6 +25,25 @@ export async function diagnoseRuntime({
     detail: `profile=${policy.profile}; exec_mode=${policy.execMode}; unrestricted_paths=${policy.unrestrictedPaths}`,
   }];
 
+  const relay = typeof relayStatus === "function" ? relayStatus() : null;
+  checks.push(relay ? {
+    layer: "remote-relay",
+    ok: relay.ready === true,
+    network_route: relay.network_route || "unknown",
+    network_route_scope: relay.network_route_scope || "unknown",
+    outage_active: relay.outage_active === true,
+    outage_count: Number(relay.outage_count) || 0,
+    last_close_category: relay.last_close_category || null,
+    last_close_code: Number.isFinite(Number(relay.last_close_code)) ? Number(relay.last_close_code) : null,
+    last_transport_error_class: relay.last_transport_error_class || null,
+    last_disconnected_at: relay.last_disconnected_at || null,
+    last_ready_at: relay.last_ready_at || null,
+    last_ready_duration_ms: Number(relay.last_ready_duration_ms) || 0,
+    next_reconnect_in_ms: Number(relay.next_reconnect_in_ms) || 0,
+  } : {
+    layer: "remote-relay", ok: false, skipped: true, transport: "stdio-or-local",
+  });
+
   const probe = join(runtimeDir, `.diagnostic-${process.pid}-${randomBytes(6).toString("hex")}`);
   try {
     await writeFile(probe, "ok\n", { mode: 0o600, flag: "wx" });
@@ -82,6 +102,7 @@ export async function diagnoseRuntime({
     interpretation: {
       tool_call_blocked_before_response: "host/platform or connector gateway",
       diagnostic_reached_daemon_but_spawn_failed: "local OS, endpoint security, shell configuration, or Machine Bridge policy",
+      system_network_stack_scope: "application proxy selection only; an operating-system VPN or TUN may still intercept the relay connection",
       managed_job_accepted_then_later_tools_blocked: "job continues independently; inspect with local CLI or a later read_job call",
     },
     policy,

package/src/local/runtime-relay.mjs

@@ -1,15 +1,15 @@
 import { Buffer } from "node:buffer";
 import { RelayConnection } from "./relay-connection.mjs";
-import { createDaemonAuthentication, createDaemonPreflightHeaders } from "./device-identity.mjs";
+import { createDaemonAuthentication, createDaemonPreflightHeaders, createDeviceSessionIdentity, validateDeviceSessionIdentity } from "./device-identity.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, deviceIdentity, expectedVersion, onFatal }) {
-  if (!workerUrl) return null;
+  if (!workerUrl || !deviceIdentity) return null;
+  const sessionIdentity = deviceIdentity?.certificate ? validateDeviceSessionIdentity(deviceIdentity)
+    : createDeviceSessionIdentity(deviceIdentity, workerUrl, SERVER_NAME, String(expectedVersion || ""));
   return new RelayConnection({
     workerUrl,
     logger: runtime.logger,
@@ -17,7 +17,7 @@ export function createRuntimeRelayConnection(runtime, { workerUrl, deviceIdentit
     expectedServer: SERVER_NAME,
     expectedVersion: String(expectedVersion || ""),
     connectionHeaders: () => createDaemonPreflightHeaders(
-      deviceIdentity,
+      sessionIdentity,
       workerUrl,
       SERVER_NAME,
       String(expectedVersion || ""),
@@ -28,7 +28,7 @@ export function createRuntimeRelayConnection(runtime, { workerUrl, deviceIdentit
       tools: runtime.tools(),
       policy: runtime.policy,
       protocol_versions: MCP_SUPPORTED_PROTOCOL_VERSIONS,
-      authentication: await createDaemonAuthentication(deviceIdentity, welcome, runtime.relayInstanceId),
+      authentication: await createDaemonAuthentication(sessionIdentity, welcome, runtime.relayInstanceId),
     }),
     onMessage: (data, relayContext) => handleRelayData(runtime, data, relayContext),
     onDisconnect: () => runtime.handleRelayDisconnect(),
@@ -90,8 +90,9 @@ function normalizeRelayAuthorization(value) {
   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);
   const clientId = typeof value.client_id === "string" && /^mcp_client_[A-Za-z0-9_-]{43}$/.test(value.client_id) ? value.client_id : "";
+  const familyId = typeof value.family_id === "string" && /^mcp_family_[A-Za-z0-9_-]{43}$/.test(value.family_id) ? value.family_id : "";
   let role;
   try { role = normalizeAccountRole(value.role); } catch { return null; }
-  if (!accountId || !clientId || !Number.isInteger(accountVersion) || accountVersion < 1) return null;
-  return Object.freeze({ account_id: accountId, account_version: accountVersion, client_id: clientId, role });
+  if (!accountId || !clientId || !familyId || !Number.isInteger(accountVersion) || accountVersion < 1) return null;
+  return Object.freeze({ account_id: accountId, account_version: accountVersion, client_id: clientId, family_id: familyId, role });
 }

package/src/local/runtime-reporting.mjs

@@ -77,16 +77,19 @@ export async function buildProjectOverview({
   displayPath,
   policy,
   toolNames,
+  daemonPolicy = policy,
+  daemonToolNames = toolNames,
   capabilityObserver,
   listTopLevel,
-  runProcess,
+  runInternalProcess,
+  gitExecutable,
   safeErrorMessage,
   throwIfCancelled,
 }, context = {}) {
   throwIfCancelled(context);
   const top = await listTopLevel(context).catch((error) => ({ error: safeErrorMessage(error), entries: [] }));
-  const git = await runProcess(
-    "git",
+  const git = await runInternalProcess(
+    gitExecutable(),
     ["-c", "core.fsmonitor=false", "-C", workspace, "rev-parse", "--show-toplevel"],
     10_000,
     true,
@@ -99,6 +102,8 @@ export async function buildProjectOverview({
     gitRoot: git.code === 0 ? displayPath(git.stdout.trim()) : "",
     policy,
     tools: ["server_info", ...toolNames],
+    daemonPolicy,
+    daemonTools: ["server_info", ...daemonToolNames],
     capabilityRouting: capabilityObserver.snapshot(),
     topLevel: top.entries || [],
   };

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

@@ -1,7 +1,7 @@
 import { clampInteger } from "./numbers.mjs";
 
 const RUNTIME_TOOL_HANDLERS = Object.freeze({
-  server_info: (runtime) => runtime.runtimeInfo(),
+  server_info: (runtime, _args, context) => runtime.runtimeInfo(context),
   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),
@@ -25,7 +25,7 @@ const RUNTIME_TOOL_HANDLERS = Object.freeze({
   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_roots: (runtime, _args, context) => runtime.listRoots(context),
   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),
@@ -39,13 +39,13 @@ const RUNTIME_TOOL_HANDLERS = Object.freeze({
   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(),
+  list_local_resources: (runtime, _args, context) => runtime.managedJobManager.listResources(context),
   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),
+  stage_job: (runtime, args, context) => runtime.managedJobManager.stage(args, context),
+  start_job: (runtime, args, context) => runtime.managedJobManager.start(args, context),
+  list_jobs: (runtime, args, context) => runtime.managedJobManager.list(args, context),
+  read_job: (runtime, args, context) => runtime.managedJobManager.read(args, context),
+  cancel_job: (runtime, args, context) => runtime.managedJobManager.cancel(args, context),
   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),