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

package/src/local/stdio.mjs

@@ -1,29 +1,38 @@
-import { readFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { LocalRuntime } from "./runtime.mjs";
+import { packageVersion } from "./package-identity.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_PROTOCOL_VERSIONS, MCP_REMOVED_PROTOCOL_MESSAGE, McpProtocolError, cacheableResult,
+  discoverResult, emptySubscriptionAcknowledgement, serverImplementation, subscriptionCompleteResult,
+  validateRequestMetadata, validateSubscriptionRequest,
+} from "../shared/mcp-protocol.mjs";
 
 const MAX_LINE_BYTES = 8 * 1024 * 1024;
-const PACKAGE_VERSION = String(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version);
+const MAX_PENDING_TOOL_CALLS = 32;
+const MCP_SERVER_INFO = Object.freeze(serverImplementation({
+  name: SERVER_NAME, title: "Machine Bridge MCP", version: packageVersion,
+  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 MCP_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;
-
   const writes = new Set();
   const send = (message) => {
     if (message === null || message === undefined) return;
@@ -47,84 +56,124 @@ export async function runStdioServer({ workspace, policy, logLevel = "info", job
   });
   for (const callId of pending.values()) runtime.cancelCall(callId, "stdio input closed");
   await Promise.allSettled([...writes]);
-  runtime.stop();
+  await runtime.stop();
 
   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;
     }
-    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;
+      cancelRequest(message);
+      return;
     }
-    if (message.method === "logging/setLevel" || message.method === "ping") {
-      send(rpcResult(message.id, {}));
-      return true;
+    if (message.method === "initialize") {
+      send(rpcError(message.id, -32601, MCP_REMOVED_PROTOCOL_MESSAGE, { supported: [...MCP_PROTOCOL_VERSIONS] }));
+      return;
     }
-    return false;
+    try {
+      validateRequestMetadata(message, MCP_PROTOCOL_VERSIONS);
+    } catch (error) {
+      if (error instanceof McpProtocolError) {
+        send(rpcError(message.id, error.code, error.message, error.data));
+        return;
+      }
+      throw error;
+    }
+    await handleMessage(message);
   }
 
-  async function handleInitializedMessage(message) {
+  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 handleMessage(message) {
+    if (!("id" in message) || message.id === null) {
+      if (!message.method.startsWith("notifications/")) {
+        send(rpcError(null, -32600, "MCP requests require a non-null request id"));
+      }
+      return;
+    }
+    if (message.method === "server/discover") {
+      send(rpcResult(message.id, discoverResult({
+        supportedVersions: MCP_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, { tools: toolsForPolicy(policy) }));
+      send(rpcResult(message.id, cacheableResult(
+        { tools: toolsForPolicy(policy) },
+        { ttlMs: MCP_TOOL_LIST_TTL_MS, cacheScope: "private", serverInfo: MCP_SERVER_INFO },
+      )));
+      return;
+    }
+    if (message.method === "subscriptions/listen") {
+      try {
+        validateSubscriptionRequest(message);
+        send(emptySubscriptionAcknowledgement(message.id));
+        send(rpcResult(message.id, subscriptionCompleteResult(message.id, MCP_SERVER_INFO)));
+      } catch (error) {
+        if (error instanceof McpProtocolError) send(rpcError(message.id, error.code, error.message, error.data));
+        else throw error;
+      }
       return;
     }
     if (message.method === "tools/call") {
       await handleToolCall(message);
       return;
     }
-    send(rpcError(message.id, -32601, `Method not found: ${message.method}`));
+    send(rpcError(message.id, -32601, "Method not found"));
   }
 
   async function handleToolCall(message) {
-    if (!("id" in message) || message.id === null) {
-      send(rpcError(null, -32600, "tools/call requires a non-null request id"));
-      return;
-    }
     const params = asObject(message.params);
     const name = typeof params.name === "string" ? params.name : "";
     if (!name) {
       send(rpcError(message.id, -32602, "tools/call requires a tool name"));
       return;
     }
-    const args = asObject(params.arguments);
-    const callId = `stdio_${randomBytes(16).toString("hex")}`;
+    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;
+    }
+    if (pending.size >= MAX_PENDING_TOOL_CALLS) {
+      send(rpcError(message.id, MCP_LIMIT_EXCEEDED, "Too many concurrent tool calls"));
+      return;
+    }
     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)));
+      const result = await runtime.executeTool(name, rawArgs, { callId, origin: "stdio" });
+      send(rpcResult(message.id, toolResult(result, false, MCP_SERVER_INFO)));
     } catch (error) {
-      send(rpcResult(message.id, toolResult({ error: publicError(error) }, true)));
+      send(rpcResult(message.id, toolResult({ error: publicError(error) }, true, MCP_SERVER_INFO)));
     } finally {
       if (key) pending.delete(key);
     }
   }
-
 }
 
 function parseJsonRpcLine(line, send) {
@@ -140,25 +189,6 @@ function parseJsonRpcLine(line, send) {
   return message;
 }
 
-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: {} },
-    serverInfo: {
-      name: SERVER_NAME,
-      title: "Machine Bridge MCP",
-      version: PACKAGE_VERSION,
-      description: "Workspace-scoped local coding tools over MCP stdio or authenticated remote relay.",
-    },
-    instructions: `${MCP_INSTRUCTIONS}${localInstructions}`,
-  };
-}
-
 function consumeBoundedJsonLines(stream, { maxLineBytes, onLine, onOversize }) {
   return new Promise((resolvePromise, rejectPromise) => {
     let chunks = [];

package/src/local/support-state-projection.mjs

@@ -0,0 +1,30 @@
+// @ts-check
+
+/** @typedef {{provider?: unknown}} DeviceIdentitySummaryInput */
+/** @typedef {{url?: unknown, mcpServerUrl?: unknown, name?: unknown, deviceIdentity?: DeviceIdentitySummaryInput, pendingDeviceIdentity?: unknown, previousDeviceIdentities?: unknown[], oauthTokenVersion?: unknown}} WorkerSummaryInput */
+
+/** @param {{schemaVersion?: unknown, policy?: Record<string, unknown>, worker?: WorkerSummaryInput, resources?: Record<string, unknown>}} state */
+export function supportStateProjection(state) {
+  const worker = state?.worker && typeof state.worker === "object" ? state.worker : {};
+  const currentIdentity = worker.deviceIdentity && typeof worker.deviceIdentity === "object" ? worker.deviceIdentity : null;
+  const previous = Array.isArray(worker.previousDeviceIdentities) ? worker.previousDeviceIdentities : [];
+  const resources = state?.resources && typeof state.resources === "object" && !Array.isArray(state.resources) ? state.resources : {};
+  const policy = state?.policy && typeof state.policy === "object" ? state.policy : {};
+  return {
+    schema_version: Number.isSafeInteger(state?.schemaVersion) ? state.schemaVersion : null,
+    policy: {
+      profile: typeof policy.profile === "string" ? policy.profile : null,
+      origin: typeof policy.origin === "string" ? policy.origin : null,
+      revision: Number.isSafeInteger(policy.revision) ? policy.revision : null,
+    },
+    worker: {
+      configured: Boolean(worker.url || worker.mcpServerUrl || worker.name || currentIdentity),
+      endpoint_configured: Boolean(worker.url || worker.mcpServerUrl),
+      oauth_token_version_configured: Boolean(worker.oauthTokenVersion),
+      device_root_provider: currentIdentity ? String(currentIdentity.provider || "portable-jwk-v1") : null,
+      pending_device_root: Boolean(worker.pendingDeviceIdentity),
+      retired_device_root_count: previous.length,
+    },
+    resource_count: Object.keys(resources).length,
+  };
+}

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/systemd-removal.mjs

@@ -0,0 +1,20 @@
+export function systemdRemovalDecision({ definitionPresent, disableCode, status }) {
+  const state = String(status?.state || "unknown");
+  const active = status?.active;
+  if (active === true || ["activating", "deactivating", "reloading", "maintenance"].includes(state)) {
+    return { removable: false, alreadyAbsent: false, reason: "service_active_or_transitioning" };
+  }
+  const safelyInactive = active === false && ["inactive", "failed"].includes(state);
+  const safelyAbsent = definitionPresent !== true && active === false && state === "unknown";
+  if (!safelyInactive && !safelyAbsent) {
+    return { removable: false, alreadyAbsent: false, reason: "status_unavailable" };
+  }
+  if (definitionPresent === true && Number(disableCode) !== 0) {
+    return { removable: false, alreadyAbsent: false, reason: "disable_failed" };
+  }
+  return {
+    removable: true,
+    alreadyAbsent: definitionPresent !== true,
+    reason: definitionPresent === true ? "disabled" : "already_absent",
+  };
+}

package/src/local/tool-executor.mjs

@@ -1,5 +1,18 @@
 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 { isRemoteDurableProcessTool, remoteDurableProcessTimeoutSeconds } from "../shared/foreground-timeout.mjs";
+import { BridgeError, errorCode, normalizeBridgeError } from "./errors.mjs";
+import { resourceAdmissionLogFields } from "./resource-admission-diagnostics.mjs";
+import { normalizeToolResult } from "./tool-result-boundary.mjs";
+import { createSecurityAuditFailureReporter } from "./security-audit-warning.mjs";
+import { enqueueSecurityAudit } from "./security-audit-dispatch.mjs";
+
+const TOOL_ARGUMENTS = compileToolArgumentValidators(catalog);
+
+export function validateToolArguments(tool, value) {
+  return TOOL_ARGUMENTS.validate(tool, value);
+}
 
 export class ToolExecutor {
   constructor(options = {}) {
@@ -9,18 +22,22 @@ export class ToolExecutor {
     this.accountAccessGate = options.accountAccessGate;
     this.operationAuthorizer = options.operationAuthorizer;
     this.observability = options.observability;
+    this.securityAudit = options.securityAudit || null;
     this.logger = options.logger || console;
+    this.onAuthorizedRelayActivityStart = typeof options.onAuthorizedRelayActivityStart === "function" ? options.onAuthorizedRelayActivityStart : null;
+    this.onAuthorizedRelayActivityEnd = typeof options.onAuthorizedRelayActivityEnd === "function" ? options.onAuthorizedRelayActivityEnd : null;
     this.safeMessage = typeof options.safeMessage === "function" ? options.safeMessage : (error) => String(error?.message || error || "operation failed");
     this.slowMs = Number.isFinite(Number(options.slowMs)) ? Math.max(1, Number(options.slowMs)) : 30_000;
     this.pipeline = composeMiddleware([
       lifecycleMiddleware(this.callRegistry),
-      observabilityMiddleware(this.observability, this.logger, this.safeMessage, this.slowMs),
-      authorizeMiddleware(this.policyGate, this.accountAccessGate, this.operationAuthorizer),
-    ], invokeHandler(this.handlers));
+      observabilityMiddleware(this.observability, this.securityAudit, this.logger, this.safeMessage, this.slowMs),
+      authorizeMiddleware(this.policyGate, this.accountAccessGate, this.operationAuthorizer, this.callRegistry),
+      validateArgumentsMiddleware(),
+    ], invokeHandler(this.handlers, this.onAuthorizedRelayActivityStart, this.onAuthorizedRelayActivityEnd));
   }
 
   execute(tool, args = {}, request = {}) {
-    return this.pipeline({ tool: String(tool || ""), args: isRecord(args) ? args : {}, request });
+    return this.pipeline({ tool: String(tool || ""), args, request });
   }
 }
 
@@ -28,19 +45,52 @@ export function composeMiddleware(middleware, terminal) {
   return middleware.reduceRight((next, current) => (operation) => current(operation, next), terminal);
 }
 
-function authorizeMiddleware(policyGate, accountAccessGate, operationAuthorizer) {
+function authorizeMiddleware(policyGate, accountAccessGate, operationAuthorizer, callRegistry) {
   return async (operation, next) => {
     policyGate.assert(operation.tool);
     if (operation.context.origin === "relay") {
-      const role = operation.request.authorization?.role;
+      const authorization = operation.request.authorization;
+      const role = authorization?.role;
       if (!role) throw new Error("relay tool call is missing an account role");
       accountAccessGate.assert(role, operation.tool);
-      await operationAuthorizer?.authorize(operation);
+      operation.context.authority = accountAccessGate.authority(authorization, policyGate.policy, "relay");
+      callRegistry.bindPrincipal(operation.context.callId, operation.context.authority.principal);
+      const decision = await operationAuthorizer?.authorize(operation);
+      if (decision) operation.context.operationAuthorization = decision;
+    } else {
+      operation.context.authority = accountAccessGate.authority({}, policyGate.policy, "local");
+      callRegistry.bindPrincipal(operation.context.callId, operation.context.authority.principal);
+    }
+    return next(operation);
+  };
+}
+
+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 && !validRelayDurableProcessSchemaExtension(operation, result.issues)) {
+      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 validRelayDurableProcessSchemaExtension(operation, issues) {
+  if (operation.context.origin !== "relay" || !isRemoteDurableProcessTool(operation.tool) || !Array.isArray(issues) || !issues.length) {
+    return false;
+  }
+  if (issues.some((issue) => issue?.instancePath !== "/timeout_seconds" || issue?.keyword !== "maximum")) return false;
+  try {
+    remoteDurableProcessTimeoutSeconds(operation.args?.timeout_seconds);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function lifecycleMiddleware(callRegistry) {
   return async (operation, next) => {
     const context = callRegistry.open({
@@ -52,16 +102,18 @@ function lifecycleMiddleware(callRegistry) {
     operation.context = { ...operation.request.context, ...context };
     try {
       callRegistry.throwIfCancelled(operation.context);
-      const result = await next(operation);
-      callRegistry.throwIfCancelled(operation.context);
-      return result;
+      // Handler return is the local settlement point. Cooperative handlers observe cancellation
+      // before or during cancellable work; a later signal must not retroactively relabel a
+      // completed side effect as cancelled after observability/audit already recorded completion.
+      return await next(operation);
     } finally {
       callRegistry.finish(context.callId);
     }
   };
 }
 
-function observabilityMiddleware(observability, logger, safeMessage, slowMs) {
+function observabilityMiddleware(observability, securityAudit, logger, safeMessage, slowMs) {
+  const auditFailureReporter = createSecurityAuditFailureReporter(logger);
   return async (operation, next) => {
     const started = performance.now();
     observability.start(operation.tool);
@@ -71,41 +123,54 @@ function observabilityMiddleware(observability, logger, safeMessage, slowMs) {
       origin: operation.context.origin,
     }, "Tool call started");
     try {
-      const result = await next(operation);
+      const normalizedResult = normalizeToolResult(await next(operation));
+      const result = normalizedResult.value;
       const durationMs = performance.now() - started;
       const slow = durationMs >= slowMs;
       observability.finish(operation.tool, { status: "completed", durationMs, slow });
+      enqueueSecurityAudit(securityAudit, operation, { outcome: "completed", durationMs, outputBytes: normalizedResult.bytes }, auditFailureReporter);
       logger.event?.("debug", slow ? "tool.call.slow" : "tool.call.completed", {
         call_id: shortCallId(operation.context.callId), tool: operation.tool, origin: operation.context.origin, duration_ms: durationMs,
+        authority_role: operation.context.authority?.principal?.role || "local",
+        risk_category: operation.context.operationAuthorization?.category || "ordinary",
       }, slow ? "Tool call completed slowly" : "Tool call completed");
       return result;
     } catch (error) {
-      const normalized = normalizeBridgeError(error, { safeMessage: () => safeMessage(error, operation.args) });
+      const normalized = normalizeBridgeError(error, { safeMessage: () => safeMessage(error, operation.args, operation.context) });
       const durationMs = performance.now() - started;
       const code = errorCode(normalized);
       const status = code === "cancelled" ? "cancelled" : code === "timeout" ? "timeout" : "failed";
       observability.finish(operation.tool, { status, durationMs, errorCode: code, slow: durationMs >= slowMs });
+      enqueueSecurityAudit(securityAudit, operation, { outcome: status, durationMs, errorCode: code }, auditFailureReporter);
+      const resourceAdmission = resourceAdmissionLogFields(normalized);
       logger.event?.("debug", "tool.call.failed", {
         call_id: shortCallId(operation.context.callId), tool: operation.tool, origin: operation.context.origin,
         duration_ms: durationMs, error_code: code, retryable: normalized.retryable,
+        authority_role: operation.context.authority?.principal?.role || "local",
+        risk_category: operation.context.operationAuthorization?.category || "ordinary",
+        ...resourceAdmission,
       }, "Tool call failed");
       throw normalized;
     }
   };
 }
 
-function invokeHandler(handlers) {
+function invokeHandler(handlers, onAuthorizedRelayActivityStart, onAuthorizedRelayActivityEnd) {
   return async (operation) => {
     const handler = handlers[operation.tool];
     if (typeof handler !== "function") throw new Error(`runtime handler is missing for tool: ${operation.tool}`);
-    return handler(operation.args, operation.context);
+    const relayActivity = operation.context.origin === "relay";
+    if (relayActivity) bestEffortActivityHook(onAuthorizedRelayActivityStart);
+    try { return await handler(operation.args, operation.context); }
+    finally { if (relayActivity) bestEffortActivityHook(onAuthorizedRelayActivityEnd); }
   };
 }
 
-function shortCallId(value) {
-  return String(value || "").slice(0, 20);
+function bestEffortActivityHook(callback) {
+  try { callback?.(); } catch { /* Auxiliary power-management hooks must not change tool settlement. */ }
 }
 
-function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+function shortCallId(value) {
+  return String(value || "").slice(0, 20);
 }

package/src/local/tool-result-boundary.mjs

@@ -0,0 +1,51 @@
+import { Buffer } from "node:buffer";
+import { BridgeError } from "./errors.mjs";
+
+export const MAX_TOOL_RESULT_BYTES = 7 * 1024 * 1024;
+
+export function normalizeToolResult(value, options = {}) {
+  const maximumBytes = positiveInteger(options.maximumBytes, MAX_TOOL_RESULT_BYTES);
+  let serialized;
+  try {
+    serialized = JSON.stringify(value, rejectUnsupportedJsonValue);
+  } catch (error) {
+    if (error instanceof BridgeError) throw error;
+    throw new BridgeError("internal_error", "tool returned a result that could not be serialized", {
+      cause: error instanceof Error ? error : undefined,
+      expose: false,
+    });
+  }
+  if (typeof serialized !== "string") {
+    throw new BridgeError("internal_error", "tool returned an unsupported result", { expose: false });
+  }
+  const bytes = Buffer.byteLength(serialized);
+  if (bytes > maximumBytes) {
+    throw new BridgeError("limit_exceeded", "tool result exceeded the relay response limit", {
+      retryable: false,
+      details: { maximum_bytes: maximumBytes, actual_bytes: bytes },
+    });
+  }
+  try {
+    return Object.freeze({ value: JSON.parse(serialized), bytes });
+  } catch (error) {
+    throw new BridgeError("internal_error", "tool result normalization failed", {
+      cause: error instanceof Error ? error : undefined,
+      expose: false,
+    });
+  }
+}
+
+function rejectUnsupportedJsonValue(_key, current) {
+  if (typeof current === "bigint" || typeof current === "function" || typeof current === "symbol" || typeof current === "undefined") {
+    throw new BridgeError("internal_error", "tool returned a non-JSON value", { expose: false });
+  }
+  if (typeof current === "number" && !Number.isFinite(current)) {
+    throw new BridgeError("internal_error", "tool returned a non-finite number", { expose: false });
+  }
+  return current;
+}
+
+function positiveInteger(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}

package/src/local/toolchain-operation-lock.mjs

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { resolve } from "node:path";
+import { filesystemIdentity, sameFilesystemIdentity } from "./filesystem-identity.mjs";
+import { withOwnerStateLock } from "./owner-state-lock.mjs";
+import { assertStateMaintenanceAvailable, expandHome, machineServiceControlRoot } from "./state.mjs";
+
+const LOCK_PURPOSE = "toolchain-operation";
+
+export function withToolchainOperationLock(stateRoot, callback, options = {}) {
+  if (typeof callback !== "function") throw new TypeError("toolchain operation lock requires a callback");
+  const root = resolve(expandHome(stateRoot));
+  assertStateMaintenanceAvailable(root);
+  const generation = stateGeneration(root);
+  const key = process.platform === "win32" ? root.toLowerCase() : root;
+  const digest = createHash("sha256").update(key).digest("hex").slice(0, 16);
+  return withOwnerStateLock(machineServiceControlRoot(options), async () => {
+    assertStateMaintenanceAvailable(root);
+    const current = stateGeneration(root);
+    if (!sameFilesystemIdentity(generation, current)) {
+      throw new Error("state root changed while waiting for private-toolchain ownership; retry from current state");
+    }
+    return callback();
+  }, {
+    purpose: LOCK_PURPOSE,
+    fileName: `toolchain-operation-${digest}.lock`,
+    label: "private toolchain operation",
+    timeoutMs: options.timeoutMs ?? 30_000,
+  });
+}
+
+function stateGeneration(root) {
+  let info;
+  try { info = lstatSync(root, { bigint: true }); }
+  catch (error) {
+    if (error?.code === "ENOENT") throw new Error("state root must exist before a persistent private-toolchain operation", { cause: error });
+    throw error;
+  }
+  if (info.isSymbolicLink() || !info.isDirectory()) throw new Error("state root must be a real directory before a persistent private-toolchain operation");
+  return filesystemIdentity(info, "private-toolchain state root");
+}