machine-bridge-mcp 1.2.9 → 1.2.11

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-relay.mjs

@@ -18,12 +18,14 @@ export function createRuntimeRelayConnection(runtime, { workerUrl, secret, expec
     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();
@@ -37,6 +39,20 @@ export function createRuntimeRelayConnection(runtime, { workerUrl, secret, expec
   });
 }
 
+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 : "";

package/src/local/runtime.mjs

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { realpathSync, rmSync } from "node:fs";
 import { lstat, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
@@ -30,7 +31,8 @@ import { AccountAccessGate } from "./account-access.mjs";
 import { buildProjectOverview, buildRuntimeInfo } from "./runtime-reporting.mjs";
 import { diagnoseRuntime as runRuntimeDiagnostics } from "./runtime-diagnostics.mjs";
 import { bindRuntimeToolHandlers, runtimeToolHandlerNames as registeredRuntimeToolHandlerNames } from "./runtime-tool-handlers.mjs";
-import { createRuntimeRelayConnection, normalizeRelayToolCall } from "./runtime-relay.mjs";
+import { createRuntimeRelayConnection, normalizeRelayResumeCalls, normalizeRelayToolCall } from "./runtime-relay.mjs";
+import { RelayCallRecovery } from "./relay-call-recovery.mjs";
 import { assertContainedPath, createRuntimeDir, redactRuntimeErrorMessage, stateRootFromProfileStatePath } from "./runtime-paths.mjs";
 import {
   resolveTaskCapabilities as resolveRuntimeTaskCapabilities,
@@ -59,8 +61,10 @@ export class LocalRuntime {
     this.processTracker = new ProcessTracker();
     this.lifecycle = new LifecycleController("local runtime");
     this.observability = new RuntimeObservability();
+    this.relayInstanceId = `daemon_${randomBytes(18).toString("base64url")}`;
     this.activeRelayCalls = new Set();
     this.suppressedRelayResults = new Map();
+    this.relayResumeSessionId = 0;
     this.callRegistry = new CallRegistry({
       maximum: MAX_CONCURRENT_TOOL_CALLS,
       onCancel: (record) => {
@@ -131,6 +135,7 @@ export class LocalRuntime {
       resolveLocalCommand: (args, context) => this.agentContextManager.resolveLocalCommand(args, context),
       displayPath: (value) => this.displayPath(value),
       throwIfCancelled: (context) => this.throwIfCancelled(context),
+      retainCompletedOutput: (value) => this.processSessionManager.retainCompletedOutput(value),
     });
     this.gitService = new GitService({
       resolveExistingPath: (value) => this.resolveExistingPath(value),
@@ -171,10 +176,16 @@ export class LocalRuntime {
       slowMs: SLOW_TOOL_CALL_MS,
     });
     this.relay = createRuntimeRelayConnection(this, {
-      workerUrl: remoteWorkerUrl,
-      secret: remoteSecret,
-      expectedVersion: expectedRelayVersion,
-      onFatal,
+      workerUrl: remoteWorkerUrl, secret: remoteSecret, expectedVersion: expectedRelayVersion, onFatal,
+    });
+    this.relayCallRecovery = new RelayCallRecovery({
+      logger: this.logger,
+      send: (value) => this.send(value),
+      isRecoverable: () => Boolean(this.relay && !this.relay.status?.().closed),
+      activeCallIds: () => this.activeRelayCalls,
+      suppressCall: (callId, reason) => this.suppressedRelayResults.set(callId, reason),
+      cancelOrigin: (reason) => this.callRegistry.cancelOrigin("relay", reason),
+      terminate: () => this.terminateActiveProcesses("SIGTERM", true),
     });
   }
 
@@ -219,6 +230,7 @@ export class LocalRuntime {
     if (!this.lifecycle.beginStop()) return;
     try {
       this.relay?.stop();
+      this.relayCallRecovery.stop();
       this.callRegistry.cancelAll("runtime stopped");
       this.terminateActiveProcesses("SIGKILL");
       this.processSessionManager.clear();
@@ -243,7 +255,7 @@ export class LocalRuntime {
       this.handleRelayProtocolViolation("invalid_server_message");
       return;
     }
-    if (this.handleRelayControlMessage(message)) return;
+    if (this.handleRelayControlMessage(message, relayContext)) return;
     if (message.type === "relay_probe") {
       if (isRelayReadyContext(relayContext, this.relay)) return this.handleRelayProtocolViolation("unexpected_relay_probe");
       this.handleRelayProbe(message, relayContext);
@@ -251,20 +263,38 @@ export class LocalRuntime {
     }
     if (message.type !== "tool_call") return this.handleRelayProtocolViolation("unexpected_server_message_type");
     if (!isRelayReadyContext(relayContext, this.relay)) return this.handleRelayProtocolViolation("tool_call_before_ready");
-    await this.handleRelayToolCall(message, relayContext);
+    await this.handleRelayToolCall(message);
   }
 
-  handleRelayControlMessage(message) {
+  handleRelayControlMessage(message, relayContext = {}) {
     if (message.type === "welcome") {
       this.relay?.observeWelcome(message);
       return true;
     }
     if (message.type === "hello_ack") {
+      this.relayResumeSessionId = 0;
       this.relay?.acknowledge(message);
       return true;
     }
+    if (message.type === "resume_calls") {
+      const sessionId = Number(relayContext.sessionId) || 0;
+      const resume = normalizeRelayResumeCalls(message);
+      if (!resume.ok || !sessionId || relayContext.authenticated !== true || relayContext.ready === true) {
+        this.handleRelayProtocolViolation("invalid_resume_calls");
+        return true;
+      }
+      this.reconcileRelayCalls(resume.ids);
+      this.relayResumeSessionId = sessionId;
+      return true;
+    }
     if (message.type === "ready_ack") {
+      const sessionId = Number(relayContext.sessionId) || 0;
+      if (!sessionId || sessionId !== this.relayResumeSessionId) {
+        this.handleRelayProtocolViolation("resume_calls_required");
+        return true;
+      }
       this.relay?.confirmReady(message);
+      this.relayResumeSessionId = 0;
       return true;
     }
     if (message.type === "pong") return true;
@@ -291,12 +321,12 @@ export class LocalRuntime {
     const id = typeof message?.id === "string" && /^probe_[A-Za-z0-9_-]{8,240}$/.test(message.id) ? message.id : "";
     const relaySessionId = Number(relayContext.sessionId) || 0;
     if (!id || !relaySessionId) return this.handleRelayProtocolViolation("invalid_relay_probe");
-    this.deliverRelayToolResult({ type: "relay_probe_result", id }, relaySessionId);
+    const outcome = this.relay?.sendForSession?.({ type: "relay_probe_result", id }, relaySessionId);
+    if (!outcome?.ok) this.handleRelayProtocolViolation("relay_probe_delivery_failed");
   }
 
-  async handleRelayToolCall(message, relayContext = {}) {
+  async handleRelayToolCall(message) {
     const envelope = normalizeRelayToolCall(message);
-    const relaySessionId = Number(relayContext.sessionId) || 0;
     if (!envelope.ok) {
       this.logger.warn?.("Received an invalid tool request from the relay; the request was rejected.");
       this.logger.event?.("debug", "relay.tool_call.invalid", {
@@ -307,7 +337,7 @@ export class LocalRuntime {
         id: envelope.id,
         ok: false,
         error: { code: "invalid_request", message: "invalid tool_call envelope", retryable: false },
-      }, relaySessionId);
+      });
       return;
     }
     if (this.activeRelayCalls.has(envelope.id)) {
@@ -335,31 +365,15 @@ export class LocalRuntime {
         }, "Discarded a tool result because the caller was no longer waiting");
         return;
       }
-      this.deliverRelayToolResult(response, relaySessionId);
+      this.deliverRelayToolResult(response);
     } finally {
       this.activeRelayCalls.delete(envelope.id);
       this.suppressedRelayResults.delete(envelope.id);
     }
   }
 
-  deliverRelayToolResult(response, relaySessionId = 0) {
-    const sessionId = Number(relaySessionId) || 0;
-    const outcome = this.relay?.sendForSession
-      ? this.relay.sendForSession(response, sessionId)
-      : (this.send(response) ? { ok: true, reason: "sent" } : { ok: false, reason: "transport_unavailable" });
-    if (outcome?.ok) return true;
-    const reason = String(outcome?.reason || "transport_unavailable");
-    const missingSession = reason === "session_ended" && sessionId <= 0;
-    this.logger.event?.(missingSession ? "error" : "debug", "relay.tool_result.discarded", {
-      call_id: shortCallId(response?.id), reason, relay_session_id: sessionId,
-      active_session_id: Number(this.relay?.currentSessionId?.() || 0),
-    }, missingSession
-      ? "Discarded a tool result because the relay session id was missing from the inbound tool_call context"
-      : reason === "send_failed"
-        ? "Could not send a tool result because the relay transport failed"
-        : "Discarded a tool result because its relay session had ended");
-    if (reason === "send_failed") this.relay?.interrupt?.("relay_transport_error");
-    return false;
+  deliverRelayToolResult(response) {
+    return this.relayCallRecovery.deliver(response);
   }
 
   finishCall(callId) {
@@ -373,18 +387,25 @@ export class LocalRuntime {
 
   cancelRelayCall(callId, suppressionReason = "caller_cancelled") {
     const id = String(callId);
+    const discardedResult = this.relayCallRecovery.discard(id);
     if (this.activeRelayCalls.has(id)) this.suppressedRelayResults.set(id, suppressionReason);
-    return this.cancelCall(id, "remote cancellation");
+    return this.cancelCall(id, "remote cancellation") || discardedResult;
+  }
+
+  reconcileRelayCalls(resumedCallIds) {
+    this.relayCallRecovery.reconcile(
+      resumedCallIds,
+      (callId) => this.cancelRelayCall(callId, "caller_no_longer_waiting"),
+    );
   }
 
   handleRelayDisconnect() {
-    for (const callId of this.activeRelayCalls) this.suppressedRelayResults.set(callId, "relay_disconnected");
-    const cancelled = this.callRegistry.cancelOrigin("relay", "remote relay disconnected");
-    this.terminateActiveProcesses("SIGTERM", true);
-    if (cancelled > 0) {
-      this.logger.event?.("debug", "relay.calls.cancelled_on_disconnect", { cancelled_calls: cancelled },
-        "Cancelled in-flight tool calls after the relay connection ended");
-    }
+    this.relayResumeSessionId = 0;
+    this.relayCallRecovery.disconnected();
+  }
+
+  handleRelayReady() {
+    this.relayCallRecovery.ready();
   }
 
   async executeTool(tool, args, context = {}) {

package/src/local/secure-file.mjs

@@ -16,6 +16,11 @@ export function openRegularFileSync(file, flags, options = {}) {
   try {
     const info = fstatSync(fd);
     if (!info.isFile()) throw new Error(`${label} is not a regular file`);
+    if (options.verifyPathIdentity === true) {
+      const pathInfo = lstatSync(file);
+      if (pathInfo.isSymbolicLink() || !pathInfo.isFile()) throw new Error(`${label} must be a regular file and not a symbolic link`);
+      if (!sameFileIdentity(info, pathInfo)) throw new Error(`${label} identity changed while opening`);
+    }
     if (Number.isInteger(options.chmod)) setDescriptorMode(fd, options.chmod);
     return { fd, info };
   } catch (error) {
@@ -37,15 +42,19 @@ export function chmodRegularFileSync(file, mode, label = "path") {
   return withRegularFileSync(file, fsConstants.O_RDONLY, { label, chmod: mode }, () => undefined);
 }
 
-export function readBoundedRegularFileSync(file, maxBytes, label = "path") {
-  return readBoundedRegularFileWithInfoSync(file, maxBytes, label).buffer;
+export function readBoundedRegularFileSync(file, maxBytes, label = "path", options = {}) {
+  return readBoundedRegularFileWithInfoSync(file, maxBytes, label, options).buffer;
 }
 
-export function readBoundedRegularFileWithInfoSync(file, maxBytes, label = "path") {
+export function readBoundedRegularFileWithInfoSync(file, maxBytes, label = "path", options = {}) {
   const limit = Number(maxBytes);
   if (!Number.isSafeInteger(limit) || limit < 0) throw new Error("maximum file size must be a non-negative safe integer");
-  return withRegularFileSync(file, fsConstants.O_RDONLY, { label }, (fd, info) => {
+  return withRegularFileSync(file, fsConstants.O_RDONLY, {
+    label,
+    verifyPathIdentity: options.verifyPathIdentity === true,
+  }, (fd, info) => {
     if (info.size > limit) throw new Error(`file exceeds ${limit} bytes`);
+    options.afterOpen?.({ fd, info });
     const buffer = Buffer.alloc(info.size);
     let offset = 0;
     while (offset < buffer.length) {
@@ -104,3 +113,14 @@ function setDescriptorMode(fd, mode) {
     if (process.platform !== "win32") throw error;
   }
 }
+
+function sameFileIdentity(left, right) {
+  const leftDevice = Number(left.dev);
+  const rightDevice = Number(right.dev);
+  const leftInode = Number(left.ino);
+  const rightInode = Number(right.ino);
+  if ([leftDevice, rightDevice, leftInode, rightInode].every((value) => Number.isSafeInteger(value) && value >= 0)) {
+    return leftDevice === rightDevice && leftInode === rightInode;
+  }
+  return true;
+}

package/src/local/tools.mjs

@@ -1,4 +1,5 @@
 import serverMetadata from "../shared/server-metadata.json" with { type: "json" };
+import { projectMcpResult } from "../shared/result-projection.mjs";
 export {
   DEFAULT_POLICY_PROFILE,
   DEFAULT_POLICY_REVISION,
@@ -28,10 +29,9 @@ export const MCP_INSTRUCTIONS = Object.freeze(serverMetadata.instructions.map((v
 export function toolResult(value, isError = false) {
   const special = specialMcpResult(value);
   if (special) return { ...special, isError };
-  const structuredContent = toStructuredContent(value);
-  const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
-  const result = { content: [{ type: "text", text }], isError };
-  if (structuredContent) result.structuredContent = structuredContent;
+  const projection = projectMcpResult(value);
+  const result = { content: [{ type: "text", text: projection.text }], isError };
+  if (projection.structuredContent) result.structuredContent = projection.structuredContent;
   return result;
 }
 
@@ -55,8 +55,3 @@ function specialMcpResult(value) {
   }
   return result;
 }
-
-function toStructuredContent(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  return value;
-}

package/src/shared/result-projection.d.mts

@@ -0,0 +1,6 @@
+export const MCP_TEXT_PROJECTION_KEY: "$mcpText";
+export function mirroredResultText(value: unknown): string;
+export function projectMcpResult(value: unknown): {
+  text: string;
+  structuredContent: Record<string, unknown> | null;
+};

package/src/shared/result-projection.json

@@ -0,0 +1,4 @@
+{
+  "maxMirroredJsonBytes": 16384,
+  "maximumSummaryKeys": 8
+}

package/src/shared/result-projection.mjs

@@ -0,0 +1,50 @@
+// @ts-check
+
+import resultProjection from "./result-projection.json" with { type: "json" };
+
+export const MCP_TEXT_PROJECTION_KEY = "$mcpText";
+
+/**
+ * Keep MCP text content useful for human-only clients without duplicating a
+ * large object that is already present in structuredContent.
+ * @param {unknown} value
+ */
+export function mirroredResultText(value) {
+  if (typeof value === "string") return value;
+  const serialized = JSON.stringify(value, null, 2);
+  if (typeof serialized !== "string") return String(value ?? "");
+  const bytes = new TextEncoder().encode(serialized).byteLength;
+  if (bytes <= Number(resultProjection.maxMirroredJsonBytes)) return serialized;
+  const object = asObject(value);
+  const keys = Object.keys(object)
+    .slice(0, Number(resultProjection.maximumSummaryKeys))
+    .map((key) => key.replace(/[\r\n\t]+/g, " ").slice(0, 80));
+  const fields = keys.length ? ` Fields: ${keys.join(", ")}.` : "";
+  return `Structured result is ${bytes} bytes and is available in structuredContent.${fields}`;
+}
+
+/**
+ * Extract an optional domain-provided text projection while keeping the
+ * authoritative structured object single-copy and marker-free.
+ * @param {unknown} value
+ */
+export function projectMcpResult(value) {
+  const object = asObject(value);
+  if (Object.prototype.hasOwnProperty.call(object, MCP_TEXT_PROJECTION_KEY)
+      && typeof object[MCP_TEXT_PROJECTION_KEY] === "string") {
+    const structuredContent = { ...object };
+    const text = String(structuredContent[MCP_TEXT_PROJECTION_KEY]).slice(0, 4096);
+    delete structuredContent[MCP_TEXT_PROJECTION_KEY];
+    return { text, structuredContent };
+  }
+  return {
+    text: mirroredResultText(value),
+    structuredContent: value && typeof value === "object" && !Array.isArray(value) ? value : null,
+  };
+}
+
+/** @param {unknown} value */
+function asObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value;
+}

package/src/shared/server-metadata.json

@@ -24,6 +24,7 @@
     "Managed-job resource redaction is defense in depth, not a guarantee against transformed or partial secret output. Use capture_output=discard for steps that may echo credentials.",
     "Do not use shell encoding, renaming, or alternate tools to bypass host or platform safety policy.",
     "run_process avoids shell parsing but is not an OS sandbox. exec_command is exposed only in shell mode and has the local user's authority.",
+    "For commands that may produce substantial output, prefer start_process/read_process or use the output_session_id returned by a truncated run_process, run_local_command, or exec_command result. Read output in bounded pages instead of repeatedly requesting a larger one-shot response.",
     "Per-tool success, failure, cancellation, and timing events are debug-only; default logs contain lifecycle and infrastructure events, not a tool-call transcript.",
     "Inspect before editing, prefer read_file line ranges, edit_file, or apply_patch over whole-file replacement, and report commands that were run."
   ]

package/src/shared/tool-catalog.json

@@ -1230,7 +1230,7 @@
   {
     "name": "run_local_command",
     "title": "Run registered local command",
-    "description": "Run an effective manifest or automatic package-script command through its fixed argv, cwd, timeout ceiling, and extra-argument policy.",
+    "description": "Run an effective manifest or automatic package-script command through its fixed argv, cwd, timeout ceiling, and extra-argument policy. Large stdout/stderr is previewed inline and retained temporarily for paged read_process continuation.",
     "availability": "direct-exec",
     "annotations": {
       "readOnlyHint": false,
@@ -1665,7 +1665,7 @@
   {
     "name": "run_process",
     "title": "Run process directly",
-    "description": "Execute an argv array without a command shell. This avoids shell parsing but does not sandbox the executable or code it launches.",
+    "description": "Execute an argv array without a command shell. This avoids shell parsing but does not sandbox the executable or code it launches. Large stdout/stderr is previewed inline and retained temporarily for paged read_process continuation.",
     "availability": "direct-exec",
     "annotations": {
       "readOnlyHint": false,
@@ -1737,7 +1737,7 @@
   {
     "name": "read_process",
     "title": "Read process session",
-    "description": "Read bounded stdout and stderr deltas from a server-managed process session, optionally waiting briefly for new output.",
+    "description": "Read bounded stdout and stderr deltas from a running process session or a recently completed one-shot command continuation, optionally waiting briefly for new output.",
     "availability": "direct-exec",
     "annotations": {
       "readOnlyHint": true,
@@ -2382,7 +2382,7 @@
   {
     "name": "exec_command",
     "title": "Execute shell command",
-    "description": "Execute a shell command with workspace cwd. This is not a sandbox and has the operating-system authority of the local user.",
+    "description": "Execute a shell command with workspace cwd. This is not a sandbox and has the operating-system authority of the local user. Large stdout/stderr is previewed inline and retained temporarily for paged read_process continuation.",
     "availability": "shell-exec",
     "annotations": {
       "readOnlyHint": false,

package/src/worker/daemon-sockets.ts

@@ -7,6 +7,7 @@ export interface DaemonAttachment {
   connectedAt: string;
   lastSeenAt?: string;
   probeId?: string;
+  instanceId?: string;
   policy?: DaemonPolicy;
   tools?: string[];
 }
@@ -29,6 +30,7 @@ export class DaemonSocketRegistry {
       connectedAt: sanitizeMetadataText(candidate.connectedAt, 64) ?? "",
       lastSeenAt: sanitizeMetadataText(candidate.lastSeenAt, 64),
       probeId: sanitizeProbeId(candidate.probeId),
+      instanceId: sanitizeDaemonInstanceId(candidate.instanceId),
       policy,
       tools: sanitizeDaemonTools(candidate.tools, policy),
     };
@@ -54,12 +56,13 @@ export class DaemonSocketRegistry {
     socket.serializeAttachment({ role: "candidate", connectedAt } satisfies DaemonAttachment);
   }
 
-  beginProbe(socket: WebSocket, values: { connectedAt: string; probeId: string; policy: DaemonPolicy; tools: string[] }): void {
+  beginProbe(socket: WebSocket, values: { connectedAt: string; probeId: string; instanceId: string; policy: DaemonPolicy; tools: string[] }): void {
     socket.serializeAttachment({
       role: "probing",
       connectedAt: values.connectedAt,
       lastSeenAt: values.connectedAt,
       probeId: values.probeId,
+      instanceId: values.instanceId,
       policy: values.policy,
       tools: values.tools,
     } satisfies DaemonAttachment);
@@ -89,6 +92,7 @@ export class DaemonSocketRegistry {
       role: "expired",
       connectedAt: attachment.connectedAt,
       lastSeenAt: attachment.lastSeenAt,
+      instanceId: attachment.instanceId,
     } satisfies DaemonAttachment);
   }
 
@@ -105,3 +109,8 @@ function sanitizeProbeId(value: unknown): string | undefined {
   if (typeof value !== "string" || !/^probe_[A-Za-z0-9_-]{8,240}$/.test(value)) return undefined;
   return value;
 }
+
+function sanitizeDaemonInstanceId(value: unknown): string | undefined {
+  if (typeof value !== "string" || !/^daemon_[A-Za-z0-9_-]{16,96}$/.test(value)) return undefined;
+  return value;
+}