machine-bridge-mcp 3.0.0-beta.21 → 3.0.0-beta.26

package/src/local/state.mjs

@@ -27,6 +27,7 @@ const MAX_MARKER_BYTES = 4096;
 const STARTUP_LOCK_MAX_AGE_MS = 2 * 60 * 60 * 1000;
 const MALFORMED_LOCK_GRACE_MS = 60_000;
 const MAINTENANCE_LOCK_MAX_AGE_MS = 2 * 60 * 60 * 1000;
+const MACHINE_SERVICE_LOCK_MAX_AGE_MS = 2 * 60 * 60 * 1000;
 
 export function expandHome(input = "") {
   if (!input || input === "~") return os.homedir();
@@ -34,6 +35,12 @@ export function expandHome(input = "") {
   return input;
 }
 
+function expandHomeFrom(input, home) {
+  if (!input || input === "~") return home;
+  if (input.startsWith("~/")) return path.join(home, input.slice(2));
+  return input;
+}
+
 export function resolveWorkspace(input = process.cwd()) {
   const resolved = path.resolve(expandHome(input));
   return realpathSync.native ? realpathSync.native(resolved) : realpathSync(resolved);
@@ -49,13 +56,16 @@ export function ensureWorkspaceDirectory(input) {
   return resolveWorkspace(requested);
 }
 
-export function defaultStateRoot() {
-  if (process.platform === "win32") {
-    const base = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+export function defaultStateRoot(options = {}) {
+  const platform = String(options.platform || process.platform);
+  const home = path.resolve(String(options.home || os.homedir()));
+  const environment = options.environment && typeof options.environment === "object" ? options.environment : process.env;
+  if (platform === "win32") {
+    const base = environment.APPDATA ? expandHomeFrom(String(environment.APPDATA), home) : path.join(home, "AppData", "Roaming");
     return path.join(base, appName);
   }
-  if (process.env.XDG_STATE_HOME) return path.join(expandHome(process.env.XDG_STATE_HOME), appName);
-  return path.join(os.homedir(), ".local", "state", appName);
+  if (environment.XDG_STATE_HOME) return path.join(expandHomeFrom(String(environment.XDG_STATE_HOME), home), appName);
+  return path.join(home, ".local", "state", appName);
 }
 
 
@@ -272,6 +282,57 @@ function lockPathForState(state, name) {
   return path.join(profileDir, name);
 }
 
+export function machineServiceControlRoot(options = {}) {
+  const home = path.resolve(String(options.home || os.homedir()));
+  if (options.controlRoot) return path.resolve(expandHomeFrom(String(options.controlRoot), home));
+  if (String(options.platform || process.platform) === "win32") {
+    const environment = options.environment && typeof options.environment === "object" ? options.environment : process.env;
+    const base = environment.APPDATA ? expandHomeFrom(String(environment.APPDATA), home) : path.join(home, "AppData", "Roaming");
+    return path.join(base, `${appName}-control`);
+  }
+  return path.join(home, ".local", "state", `${appName}-control`);
+}
+
+export function machineServiceLockPath(options = {}) {
+  return path.join(machineServiceControlRoot(options), "service-operation.lock");
+}
+
+export function acquireMachineServiceLock(metadata = {}, options = {}) {
+  const root = machineServiceControlRoot(options);
+  ensureOwnerOnlyDir(root);
+  assertNoForeignMaintenance(root);
+  const operation = typeof metadata.operation === "string" && /^[a-z][a-z0-9._-]{0,63}$/.test(metadata.operation)
+    ? metadata.operation
+    : "service-operation";
+  return acquireProcessLock(machineServiceLockPath({ controlRoot: root }), {
+    workspace: { path: "" },
+    paths: { profileDir: root, stateRoot: root },
+  }, "machine-service", { operation }, { maxAgeMs: MACHINE_SERVICE_LOCK_MAX_AGE_MS });
+}
+
+export async function acquireMachineServiceLockWithWait(options = {}) {
+  const timeoutMs = boundedPositiveInteger(options.timeoutMs, 30_000);
+  const pollMs = boundedPositiveInteger(options.pollMs, 100);
+  const logger = options.logger || { info() {} };
+  const metadata = { operation: options.operation };
+  let lock = acquireMachineServiceLock(metadata, options);
+  if (lock.acquired) return lock;
+  const ownerPid = lock.owner?.pid ? `pid ${lock.owner.pid}` : "another process";
+  logger.info?.(`waiting for ${ownerPid} to finish the current machine-service operation`);
+  const deadline = createMonotonicDeadline(timeoutMs);
+  while (!deadline.expired()) {
+    await new Promise((resolvePromise) => { setTimeout(resolvePromise, Math.min(pollMs, Math.max(1, deadline.remainingMs()))); });
+    lock = acquireMachineServiceLock(metadata, options);
+    if (lock.acquired) {
+      logger.info?.("the previous machine-service operation finished; continuing");
+      return lock;
+    }
+  }
+  const pid = lock.owner?.pid ? `pid ${lock.owner.pid}` : "unknown pid";
+  const operation = typeof lock.owner?.operation === "string" ? ` (${lock.owner.operation})` : "";
+  throw new Error(`another machine-service operation did not finish within ${Math.ceil(timeoutMs / 1000)} seconds (${pid}${operation}); inspect the process before retrying`);
+}
+
 export function acquireMaintenanceLock(stateRoot, metadata = {}) {
   const root = path.resolve(expandHome(stateRoot));
   if (!existsSync(root)) throw new Error("cannot acquire maintenance lock for a missing state root");
@@ -316,7 +377,7 @@ function assertNoForeignMaintenance(stateRoot) {
 
 export function acquireDaemonLock(state, metadata = {}) {
   assertNoForeignMaintenance(state?.paths?.stateRoot);
-  const details = {};
+  const details = { startupReady: false, startupReadyAt: null };
   if (metadata?.mode === "foreground" || metadata?.mode === "service") details.mode = metadata.mode;
   if (typeof metadata?.version === "string" && /^[0-9A-Za-z.+_-]{1,64}$/.test(metadata.version)) details.version = metadata.version;
   return acquireProcessLock(daemonLockPathForState(state), state, "daemon", details, { maxAgeMs: Number.POSITIVE_INFINITY });
@@ -371,12 +432,17 @@ function acquireProcessLock(lockPath, state, purpose, details = {}, options = {}
       createExclusiveFileSync(lockPath, `${JSON.stringify(payload, null, 2)}
 `, { mode: 0o600 });
       ownerOnlyFile(lockPath);
-      return {
+      const lock = {
         acquired: true,
         path: lockPath,
         owner: payload,
+        update(patch) {
+          lock.owner = updateProcessLock(lockPath, token, patch);
+          return lock.owner;
+        },
         release() { releaseProcessLock(lockPath, token); },
       };
+      return lock;
     } catch (error) {
       if (error?.code !== "EEXIST") throw error;
       const snapshot = readProcessLockSnapshot(lockPath);
@@ -452,6 +518,37 @@ function sameLockIdentity(left, right) {
   return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs;
 }
 
+function updateProcessLock(lockPath, token, patch) {
+  if (!isPlainRecord(patch)) throw new TypeError("process lock update must be a plain record");
+  const allowed = new Set(["startupReady", "startupReadyAt"]);
+  for (const key of Object.keys(patch)) {
+    if (!allowed.has(key)) throw new Error(`process lock field is immutable: ${key}`);
+  }
+  if (patch.startupReady !== true) {
+    throw new TypeError("process lock startup readiness can only be published as true");
+  }
+  if (typeof patch.startupReadyAt !== "string" || !Number.isFinite(Date.parse(patch.startupReadyAt))) {
+    throw new TypeError("process lock startupReadyAt update must be an ISO timestamp");
+  }
+  const snapshot = readProcessLockSnapshot(lockPath);
+  if (!snapshot?.owner || snapshot.owner.token !== token || snapshot.owner.pid !== process.pid) {
+    throw new Error("process lock ownership changed before update");
+  }
+  if (snapshot.owner.purpose !== "daemon") {
+    throw new Error("only daemon locks can publish startup readiness");
+  }
+  if (snapshot.owner.startupReady === true || snapshot.owner.startupReadyAt !== null) {
+    throw new Error("process lock startup readiness was already published");
+  }
+  const updated = { ...snapshot.owner, startupReady: true, startupReadyAt: patch.startupReadyAt };
+  const content = `${JSON.stringify(updated, null, 2)}
+`;
+  if (Buffer.byteLength(content) > MAX_LOCK_BYTES) throw new Error("process lock update exceeds the size limit");
+  replaceFileAtomicallySync(lockPath, content, { mode: 0o600 });
+  ownerOnlyFile(lockPath);
+  return updated;
+}
+
 function releaseProcessLock(lockPath, token) {
   let snapshot;
   try { snapshot = readProcessLockSnapshot(lockPath); } catch { return; }

package/src/local/stdio.mjs

@@ -1,34 +1,49 @@
 import { readFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { LocalRuntime } from "./runtime.mjs";
+import { validateToolArguments } from "./tool-executor.mjs";
 import { classifyOperationalError, createLogger } from "./log.mjs";
 import { publicError } from "./errors.mjs";
 import {
   MCP_INSTRUCTIONS,
-  MCP_PROTOCOL_VERSION,
-  MCP_SUPPORTED_PROTOCOL_VERSIONS,
   SERVER_NAME,
   rpcError,
   rpcResult,
   toolResult,
   toolsForPolicy,
 } from "./tools.mjs";
+import {
+  MCP_LEGACY_PROTOCOL_VERSION, MCP_LEGACY_PROTOCOL_VERSIONS, MCP_MODERN_PROTOCOL_VERSION,
+  MCP_MODERN_PROTOCOL_VERSIONS, McpProtocolError, isModernMcpRequest, modernCacheableResult,
+  modernDiscoverResult, serverImplementation, validateModernRequestMetadata,
+} from "../shared/mcp-protocol.mjs";
+import {
+  acceptedSubscriptionFilter, subscriptionAcknowledgedNotification, subscriptionCompleteResult, validateSubscriptionFilter,
+} from "../shared/mcp-subscriptions.mjs";
 
 const MAX_LINE_BYTES = 8 * 1024 * 1024;
 const MAX_PENDING_TOOL_CALLS = 32;
 const PACKAGE_VERSION = String(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version);
+const MCP_SERVER_INFO = Object.freeze(serverImplementation({
+  name: SERVER_NAME, title: "Machine Bridge MCP", version: PACKAGE_VERSION,
+  description: "Workspace-scoped local coding tools over MCP stdio or authenticated remote relay.",
+}));
+const MCP_SERVER_CAPABILITIES = Object.freeze({ tools: Object.freeze({ listChanged: false }) });
+const MCP_DISCOVERY_TTL_MS = 300_000;
+const MCP_TOOL_LIST_TTL_MS = 300_000;
+const MODERN_LIMIT_EXCEEDED = -31900;
 
 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, browserStateRoot });
   const pending = new Map();
-  let negotiatedVersion = MCP_PROTOCOL_VERSION;
-  let initialized = false;
-
+  let legacyInitialized = false;
+  let legacyVersion = MCP_LEGACY_PROTOCOL_VERSION;
   const writes = new Set();
   const send = (message) => {
     if (message === null || message === undefined) return;
-    const line = `${JSON.stringify(message)}\n`;
+    const line = `${JSON.stringify(message)}
+`;
     const promise = new Promise((resolvePromise, rejectPromise) => {
       process.stdout.write(line, (error) => error ? rejectPromise(error) : resolvePromise());
     }).catch((error) => {
@@ -52,52 +67,113 @@ 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 (await handleControlMessage(message)) return;
-    if (!initialized) {
-      send(rpcError(message.id, -32002, "Server is not initialized"));
+    if (!message) return;
+    if (typeof message.method !== "string") {
+      send(rpcError(message.id, -32600, "Clients must not send JSON-RPC responses"));
+      return;
+    }
+    if (message.method === "notifications/cancelled") {
+      cancelRequest(message);
+      return;
+    }
+    if (isModernMcpRequest(message)) {
+      let context;
+      try {
+        context = validateModernRequestMetadata(message, MCP_MODERN_PROTOCOL_VERSIONS);
+      } catch (error) {
+        if (error instanceof McpProtocolError) {
+          send(rpcError(message.id, error.code, error.message, error.data));
+          return;
+        }
+        throw error;
+      }
+      await handleModernMessage(message, context.version);
       return;
     }
-    await handleInitializedMessage(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, await initializationResult(negotiatedVersion, runtime)));
-      return true;
-    }
-    if (message.method === "notifications/initialized") return true;
-    if (message.method === "notifications/cancelled") {
-      const requestId = asObject(message.params).requestId;
-      const callId = pending.get(jsonRpcIdKey(requestId));
-      if (callId) runtime.cancelCall(callId, "MCP cancellation notification");
-      return true;
+      await initializeLegacy(message);
+      return;
     }
+    if (message.method === "notifications/initialized") return;
     if (message.method === "logging/setLevel" || message.method === "ping") {
       send(rpcResult(message.id, {}));
-      return true;
+      return;
+    }
+    if (!legacyInitialized) {
+      send(rpcError(message.id, -32002, "Server is not initialized"));
+      return;
+    }
+    await handleLegacyMessage(message);
+  }
+
+  async function initializeLegacy(message) {
+    const requested = asObject(message.params).protocolVersion;
+    legacyVersion = typeof requested === "string" && MCP_LEGACY_PROTOCOL_VERSIONS.includes(requested)
+      ? requested
+      : MCP_LEGACY_PROTOCOL_VERSION;
+    legacyInitialized = true;
+    send(rpcResult(message.id, await legacyInitializationResult(legacyVersion, runtime)));
+  }
+
+  function cancelRequest(message) {
+    const requestId = asObject(message.params).requestId;
+    const callId = pending.get(jsonRpcIdKey(requestId));
+    if (callId) runtime.cancelCall(callId, "MCP cancellation notification");
+  }
+
+  async function handleModernMessage(message, protocolVersion) {
+    if (!("id" in message) || message.id === null) {
+      if (!message.method.startsWith("notifications/")) {
+        send(rpcError(null, -32600, "Modern MCP requests require a non-null request id"));
+      }
+      return;
+    }
+    if (message.method === "server/discover") {
+      send(rpcResult(message.id, modernDiscoverResult({
+        supportedVersions: MCP_MODERN_PROTOCOL_VERSIONS,
+        capabilities: MCP_SERVER_CAPABILITIES,
+        instructions: MCP_INSTRUCTIONS,
+        ttlMs: MCP_DISCOVERY_TTL_MS,
+        serverInfo: MCP_SERVER_INFO,
+      })));
+      return;
+    }
+    if (message.method === "tools/list") {
+      send(rpcResult(message.id, modernCacheableResult(
+        { tools: toolsForPolicy(policy) },
+        { ttlMs: MCP_TOOL_LIST_TTL_MS, cacheScope: "private", serverInfo: MCP_SERVER_INFO },
+      )));
+      return;
+    }
+    if (message.method === "subscriptions/listen") {
+      const requested = subscriptionFilterOrError(asObject(message.params).notifications, message.id, send);
+      if (!requested) return;
+      const accepted = acceptedSubscriptionFilter(requested, MCP_SERVER_CAPABILITIES);
+      send(subscriptionAcknowledgedNotification(message.id, accepted));
+      send(rpcResult(message.id, subscriptionCompleteResult(message.id, MCP_SERVER_INFO)));
+      return;
+    }
+    if (message.method === "tools/call") {
+      await handleToolCall(message, protocolVersion);
+      return;
     }
-    return false;
+    send(rpcError(message.id, -32601, "Method not found"));
   }
 
-  async function handleInitializedMessage(message) {
+  async function handleLegacyMessage(message) {
     if (message.method === "tools/list") {
       send(rpcResult(message.id, { tools: toolsForPolicy(policy) }));
       return;
     }
     if (message.method === "tools/call") {
-      await handleToolCall(message);
+      await handleToolCall(message, legacyVersion);
       return;
     }
-    send(rpcError(message.id, -32601, `Method not found: ${message.method}`));
+    send(rpcError(message.id, -32601, "Method not found"));
   }
 
-  async function handleToolCall(message) {
+  async function handleToolCall(message, protocolVersion) {
     if (!("id" in message) || message.id === null) {
       send(rpcError(null, -32600, "tools/call requires a non-null request id"));
       return;
@@ -108,28 +184,51 @@ export async function runStdioServer({ workspace, policy, logLevel = "info", job
       send(rpcError(message.id, -32602, "tools/call requires a tool name"));
       return;
     }
-    const args = asObject(params.arguments);
+    if (!toolsForPolicy(policy).some((tool) => tool.name === name)) {
+      send(rpcError(message.id, -32602, "Unknown or unavailable tool"));
+      return;
+    }
+    const rawArgs = params.arguments === undefined ? {} : params.arguments;
+    const validation = validateToolArguments(name, rawArgs);
+    if (!validation.known || !validation.valid) {
+      send(rpcError(message.id, -32602, !validation.known
+        ? "Unknown tool"
+        : "Tool arguments do not match the input schema", validation.valid ? undefined : {
+          validation_issues: validation.issues,
+        }));
+      return;
+    }
+    const args = rawArgs;
+    const modern = protocolVersion === MCP_MODERN_PROTOCOL_VERSION;
     if (pending.size >= MAX_PENDING_TOOL_CALLS) {
-      send(rpcError(message.id, -32000, "Too many concurrent tool calls"));
+      send(rpcError(message.id, modern ? MODERN_LIMIT_EXCEEDED : -32000, "Too many concurrent tool calls"));
       return;
     }
-    const callId = `stdio_${randomBytes(16).toString("hex")}`;
     const key = jsonRpcIdKey(message.id);
     if (key && pending.has(key)) {
       send(rpcError(message.id, -32600, "Duplicate in-flight JSON-RPC request id"));
       return;
     }
+    const callId = `stdio_${randomBytes(16).toString("hex")}`;
     if (key) pending.set(key, callId);
     try {
       const result = await runtime.executeTool(name, args, { callId, origin: "stdio" });
-      send(rpcResult(message.id, toolResult(result)));
+      send(rpcResult(message.id, toolResult(result, false, protocolVersion, MCP_SERVER_INFO)));
     } catch (error) {
-      send(rpcResult(message.id, toolResult({ error: publicError(error) }, true)));
+      send(rpcResult(message.id, toolResult({ error: publicError(error) }, true, protocolVersion, MCP_SERVER_INFO)));
     } finally {
       if (key) pending.delete(key);
     }
   }
+}
 
+function subscriptionFilterOrError(value, requestId, send) {
+  try { return validateSubscriptionFilter(value); }
+  catch (error) {
+    if (!(error instanceof McpProtocolError)) throw error;
+    send(rpcError(requestId, error.code, error.message, error.data));
+    return null;
+  }
 }
 
 function parseJsonRpcLine(line, send) {
@@ -145,7 +244,7 @@ function parseJsonRpcLine(line, send) {
   return message;
 }
 
-async function initializationResult(protocolVersion, runtime) {
+async function legacyInitializationResult(protocolVersion, runtime) {
   const bootstrap = await runtime.sessionBootstrap({ path: "." }).catch((error) => {
     runtime.logger?.debug?.("session bootstrap unavailable during initialize", { error_class: classifyOperationalError(error) });
     return null;
@@ -154,12 +253,7 @@ async function initializationResult(protocolVersion, runtime) {
   return {
     protocolVersion,
     capabilities: { tools: { listChanged: false }, logging: {} },
-    serverInfo: {
-      name: SERVER_NAME,
-      title: "Machine Bridge MCP",
-      version: PACKAGE_VERSION,
-      description: "Workspace-scoped local coding tools over MCP stdio or authenticated remote relay.",
-    },
+    serverInfo: MCP_SERVER_INFO,
     instructions: `${MCP_INSTRUCTIONS}${localInstructions}`,
   };
 }

package/src/local/system-network-route.mjs

@@ -0,0 +1,76 @@
+// @ts-check
+
+const TUNNEL_INTERFACE = /^(?:utun|tun|tap|ppp|ipsec|wg|gif|stf)/i;
+const LOOPBACK_INTERFACE = /^lo\d*$/i;
+const PHYSICAL_INTERFACE = /^(?:en|eth|wlan|wl|wifi|wi-fi)\d*$/i;
+
+/** @typedef {{code?: number, stdout?: string}} FixedProcessResult */
+/** @typedef {(command: string, args: string[], timeoutMs: number, capture: boolean, maxOutputBytes: number, context: unknown) => Promise<FixedProcessResult>} FixedInternalRunner */
+/**
+ * @typedef {{
+ *   platform?: string,
+ *   runFixedInternal?: FixedInternalRunner,
+ *   classifyError?: (error: unknown) => string,
+ *   context?: unknown,
+ * }} SystemNetworkRouteOptions
+ */
+
+/** @param {SystemNetworkRouteOptions} [options] */
+export async function systemNetworkRouteCheck({
+  platform = process.platform,
+  runFixedInternal,
+  classifyError = () => "unavailable",
+  context = {},
+} = {}) {
+  try {
+    const route = await inspectSystemNetworkRoute({ platform, runFixedInternal, context });
+    return route.supported && route.available ? {
+      layer: "system-network-route",
+      ok: true,
+      route_class: route.route_class,
+      operating_system_interception: route.operating_system_interception === true,
+    } : {
+      layer: "system-network-route",
+      ok: false,
+      skipped: true,
+      error_class: route.supported ? "unavailable" : "unsupported_platform",
+    };
+  } catch (error) {
+    return {
+      layer: "system-network-route",
+      ok: false,
+      skipped: true,
+      error_class: classifyError(error),
+    };
+  }
+}
+
+/** @param {SystemNetworkRouteOptions} [options] */
+export async function inspectSystemNetworkRoute({
+  platform = process.platform,
+  runFixedInternal,
+  context = {},
+} = {}) {
+  if (platform !== "darwin" || typeof runFixedInternal !== "function") return { supported: false };
+  const result = await runFixedInternal("/sbin/route", ["-n", "get", "default"], 5_000, true, 16 * 1024, context);
+  if (result?.code !== 0) return { supported: true, available: false };
+  const match = String(result.stdout || "").match(/^\s*interface:\s*(\S+)\s*$/mi);
+  if (!match) return { supported: true, available: false };
+  const routeClass = classifySystemRouteInterface(match[1]);
+  return {
+    supported: true,
+    available: true,
+    route_class: routeClass,
+    operating_system_interception: routeClass === "tunnel-or-vpn",
+  };
+}
+
+/** @param {unknown} value */
+export function classifySystemRouteInterface(value) {
+  const name = String(value || "").trim();
+  if (!name) return "unknown";
+  if (TUNNEL_INTERFACE.test(name)) return "tunnel-or-vpn";
+  if (LOOPBACK_INTERFACE.test(name)) return "loopback";
+  if (PHYSICAL_INTERFACE.test(name)) return "physical-or-other";
+  return "other";
+}

package/src/local/tool-executor.mjs

@@ -1,7 +1,15 @@
 import { performance } from "node:perf_hooks";
-import { errorCode, normalizeBridgeError } from "./errors.mjs";
+import catalog from "../shared/tool-catalog.json" with { type: "json" };
+import { compileToolArgumentValidators } from "../shared/tool-argument-validation.mjs";
+import { BridgeError, errorCode, normalizeBridgeError } from "./errors.mjs";
 import { normalizeToolResult } from "./tool-result-boundary.mjs";
 
+const TOOL_ARGUMENTS = compileToolArgumentValidators(catalog);
+
+export function validateToolArguments(tool, value) {
+  return TOOL_ARGUMENTS.validate(tool, value);
+}
+
 export class ToolExecutor {
   constructor(options = {}) {
     this.handlers = options.handlers || {};
@@ -18,11 +26,12 @@ export class ToolExecutor {
       lifecycleMiddleware(this.callRegistry),
       observabilityMiddleware(this.observability, this.securityAudit, this.logger, this.safeMessage, this.slowMs),
       authorizeMiddleware(this.policyGate, this.accountAccessGate, this.operationAuthorizer),
+      validateArgumentsMiddleware(),
     ], invokeHandler(this.handlers));
   }
 
   execute(tool, args = {}, request = {}) {
-    return this.pipeline({ tool: String(tool || ""), args: isRecord(args) ? args : {}, request });
+    return this.pipeline({ tool: String(tool || ""), args, request });
   }
 }
 
@@ -48,6 +57,19 @@ function authorizeMiddleware(policyGate, accountAccessGate, operationAuthorizer)
   };
 }
 
+function validateArgumentsMiddleware() {
+  return async (operation, next) => {
+    const result = TOOL_ARGUMENTS.validate(operation.tool, operation.args);
+    if (!result.known) throw new BridgeError("not_found", `unknown tool: ${operation.tool}`);
+    if (!result.valid) {
+      throw new BridgeError("invalid_request", `tool arguments do not match the input schema: ${operation.tool}`, {
+        details: { tool: operation.tool, validation_issues: result.issues },
+      });
+    }
+    return next(operation);
+  };
+}
+
 function lifecycleMiddleware(callRegistry) {
   return async (operation, next) => {
     const context = callRegistry.open({
@@ -138,7 +160,3 @@ function safeByteLength(value) {
 function shortCallId(value) {
   return String(value || "").slice(0, 20);
 }
-
-function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}

package/src/local/tools.mjs

@@ -1,5 +1,6 @@
 import serverMetadata from "../shared/server-metadata.json" with { type: "json" };
 import { projectMcpResult } from "../shared/result-projection.mjs";
+import { MCP_LEGACY_PROTOCOL_VERSION, resultForProtocol } from "../shared/mcp-protocol.mjs";
 export {
   DEFAULT_POLICY_PROFILE,
   DEFAULT_POLICY_REVISION,
@@ -27,13 +28,13 @@ export const MCP_PROTOCOL_VERSION = String(serverMetadata.protocolVersion);
 export const MCP_SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(serverMetadata.supportedProtocolVersions.map((value) => String(value)));
 export const MCP_INSTRUCTIONS = Object.freeze(serverMetadata.instructions.map((value) => String(value))).join("\n");
 
-export function toolResult(value, isError = false) {
+export function toolResult(value, isError = false, protocolVersion = MCP_LEGACY_PROTOCOL_VERSION, serverInfo) {
   const special = specialMcpResult(value);
-  if (special) return { ...special, isError };
+  if (special) return resultForProtocol(protocolVersion, { ...special, isError }, { serverInfo });
   const projection = projectMcpResult(value);
   const result = { content: [{ type: "text", text: projection.text }], isError };
-  if (projection.structuredContent) result.structuredContent = projection.structuredContent;
-  return result;
+  if (projection.hasStructuredContent) result.structuredContent = structuredClone(projection.structuredContent);
+  return resultForProtocol(protocolVersion, result, { serverInfo });
 }
 
 export function rpcResult(id, result) {
@@ -51,7 +52,7 @@ function specialMcpResult(value) {
   const special = value && typeof value === "object" && !Array.isArray(value) ? value.$mcp : null;
   if (!special || typeof special !== "object" || !Array.isArray(special.content)) return null;
   const result = { content: structuredClone(special.content) };
-  if (special.structuredContent && typeof special.structuredContent === "object" && !Array.isArray(special.structuredContent)) {
+  if (Object.prototype.hasOwnProperty.call(special, "structuredContent")) {
     result.structuredContent = structuredClone(special.structuredContent);
   }
   return result;

package/src/local/windows-service-convergence.mjs

@@ -0,0 +1,49 @@
+// @ts-check
+
+import { waitForStableActiveStatus } from "./service-convergence.mjs";
+
+/** @typedef {{ statusAttempts?: unknown, statusDelayMs?: unknown, stableSamples?: unknown, sleep?: (milliseconds: number) => Promise<void> }} WindowsConvergenceOptions */
+/** @typedef {Record<string, unknown> & { active?: boolean }} WindowsStatus */
+
+/** @param {() => WindowsStatus | Promise<WindowsStatus>} readStatus @param {WindowsConvergenceOptions} [options] */
+export async function stableWindowsStatus(readStatus, options = {}) {
+  if (typeof readStatus !== "function") throw new TypeError("Windows status reader is required");
+  return waitForStableActiveStatus(readStatus, {
+    attempts: boundedPositiveInteger(options.statusAttempts, 10),
+    delayMs: boundedPositiveInteger(options.statusDelayMs, 100),
+    stableSamples: boundedPositiveInteger(options.stableSamples, 5),
+    sleep: typeof options.sleep === "function" ? options.sleep : undefined,
+  });
+}
+
+/** @param {() => WindowsStatus | Promise<WindowsStatus>} readStatus @param {(status: WindowsStatus) => boolean} predicate @param {WindowsConvergenceOptions} [options] */
+export async function waitForWindowsStatus(readStatus, predicate, options = {}) {
+  if (typeof readStatus !== "function") throw new TypeError("Windows status reader is required");
+  if (typeof predicate !== "function") throw new TypeError("Windows status predicate is required");
+  const attempts = boundedPositiveInteger(options.statusAttempts, 10);
+  const delayMs = boundedPositiveInteger(options.statusDelayMs, 100);
+  const sleep = typeof options.sleep === "function"
+    ? options.sleep
+    : (/** @type {number} */ milliseconds) => new Promise(resolve => { setTimeout(resolve, milliseconds); });
+  let status = await readStatus();
+  for (let index = 1; index < attempts && !predicate(status); index += 1) {
+    await sleep(delayMs);
+    status = await readStatus();
+  }
+  return status;
+}
+
+/** @param {WindowsConvergenceOptions} [options] */
+export function windowsStatusWaitOptions(options = {}) {
+  return {
+    attempts: boundedPositiveInteger(options.statusAttempts, 10),
+    delayMs: boundedPositiveInteger(options.statusDelayMs, 100),
+    sleep: typeof options.sleep === "function" ? options.sleep : undefined,
+  };
+}
+
+/** @param {unknown} value @param {number} fallback */
+export function boundedPositiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}