machine-bridge-mcp 1.2.10 → 1.2.11

package/src/local/execution-limits.mjs

@@ -3,6 +3,7 @@ export const MAX_PROCESS_SESSIONS = 8;
 export const MIN_PROCESS_TIMEOUT_SECONDS = 1;
 export const MAX_PROCESS_TIMEOUT_SECONDS = 600;
 export const DEFAULT_PROCESS_OUTPUT_BYTES = 512 * 1024;
+export const PUBLIC_PROCESS_INLINE_OUTPUT_BYTES = 32 * 1024;
 export const MAX_PROCESS_STDIN_BYTES = 1024 * 1024;
 export const MAX_PROCESS_SESSION_OUTPUT_BYTES = 1024 * 1024;
 export const MAX_PROCESS_SESSION_STDIN_BYTES = 64 * 1024;
@@ -16,7 +17,11 @@ export function executionGuardrailsSnapshot() {
     one_shot_processes: {
       timeout_seconds: { minimum: MIN_PROCESS_TIMEOUT_SECONDS, maximum: MAX_PROCESS_TIMEOUT_SECONDS },
       stdin_max_bytes: MAX_PROCESS_STDIN_BYTES,
-      output_max_bytes_per_stream: DEFAULT_PROCESS_OUTPUT_BYTES,
+      output_max_bytes_per_stream: PUBLIC_PROCESS_INLINE_OUTPUT_BYTES,
+      inline_output_max_bytes_per_stream: PUBLIC_PROCESS_INLINE_OUTPUT_BYTES,
+      retained_output_max_bytes_per_stream: MAX_PROCESS_SESSION_OUTPUT_BYTES,
+      continuation_tool: "read_process",
+      continuation_retention: "best-effort-until-session-expiry-or-capacity-eviction",
       process_tree_termination: "sigterm-then-sigkill",
     },
     process_sessions: {

package/src/local/process-execution.mjs

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { basename } from "node:path";
 import { stat } from "node:fs/promises";
 import { BoundedOutput } from "./bounded-output.mjs";
 import { executionEnv, workspaceShellCommand } from "./shell.mjs";
@@ -6,10 +7,21 @@ import { MAX_COMMAND_BYTES, validateArgv } from "./process-contract.mjs";
 import { terminateProcessTreeWithEscalation } from "./process-tree.mjs";
 import { BridgeError } from "./errors.mjs";
 import { clampInteger } from "./numbers.mjs";
+import { ProcessOutputStream } from "./process-output-stream.mjs";
+import { processFailureMessage, publicProcessToolResult } from "./process-result-projection.mjs";
 import {
-  DEFAULT_PROCESS_OUTPUT_BYTES, MAX_PROCESS_STDIN_BYTES, MAX_PROCESS_TIMEOUT_SECONDS, MIN_PROCESS_TIMEOUT_SECONDS,
+  DEFAULT_PROCESS_OUTPUT_BYTES,
+  MAX_PROCESS_SESSION_OUTPUT_BYTES,
+  MAX_PROCESS_STDIN_BYTES,
+  MAX_PROCESS_TIMEOUT_SECONDS,
+  MIN_PROCESS_TIMEOUT_SECONDS,
+  PROCESS_SESSION_RETENTION_MS,
+  PUBLIC_PROCESS_INLINE_OUTPUT_BYTES,
 } from "./execution-limits.mjs";
 
+const PROCESS_OUTPUT_CAPTURE = Symbol("process-output-capture");
+const CONTINUATION_READ_BYTES = 64 * 1024;
+
 function spawnDirectProcess(command, args, options) {
   // Keep the production child_process API call structurally separate from the
   // injectable test seam and enforce non-shell execution at the final boundary.
@@ -23,7 +35,7 @@ function spawnDirectProcess(command, args, options) {
 }
 
 export class ProcessExecutionService {
-  constructor({ workspace, policy, policyGate, runtimeDir, processTracker, resolveExistingPath, resolveLocalCommand, displayPath, throwIfCancelled, spawnProcess = spawnDirectProcess, terminateProcess = terminateProcessTreeWithEscalation }) {
+  constructor({ workspace, policy, policyGate, runtimeDir, processTracker, resolveExistingPath, resolveLocalCommand, displayPath, throwIfCancelled, retainCompletedOutput = null, spawnProcess = spawnDirectProcess, terminateProcess = terminateProcessTreeWithEscalation }) {
     this.workspace = workspace;
     this.policy = policy;
     this.policyGate = policyGate;
@@ -33,6 +45,7 @@ export class ProcessExecutionService {
     this.resolveLocalCommand = resolveLocalCommand;
     this.displayPath = displayPath;
     this.throwIfCancelled = throwIfCancelled;
+    this.retainCompletedOutput = typeof retainCompletedOutput === "function" ? retainCompletedOutput : null;
     this.spawnProcess = spawnProcess;
     this.terminateProcess = terminateProcess;
   }
@@ -42,7 +55,12 @@ export class ProcessExecutionService {
     const argv = validateArgv(args.argv);
     const cwd = await this.resolveExistingPath(args.cwd || ".");
     if (!(await stat(cwd)).isDirectory()) throw new BridgeError("invalid_request", "cwd is not a directory");
-    return this.run(argv[0], argv.slice(1), clampInteger(args.timeout_seconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000, false, DEFAULT_PROCESS_OUTPUT_BYTES, context, cwd);
+    const result = await this.runPublic(
+      argv[0], argv.slice(1),
+      clampInteger(args.timeout_seconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000,
+      context, cwd,
+    );
+    return publicProcessToolResult(result);
   }
 
   async runRegistered(args, context = {}) {
@@ -55,8 +73,8 @@ export class ProcessExecutionService {
       ? command.timeoutSeconds
       : clampInteger(args.timeout_seconds, command.timeoutSeconds, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS);
     const timeoutSeconds = Math.min(requested, command.timeoutSeconds);
-    const result = await this.run(argv[0], argv.slice(1), timeoutSeconds * 1000, false, DEFAULT_PROCESS_OUTPUT_BYTES, context, cwd);
-    return { name: command.name, cwd: this.displayPath(cwd), timeout_seconds: timeoutSeconds, ...result };
+    const result = await this.runPublic(argv[0], argv.slice(1), timeoutSeconds * 1000, context, cwd);
+    return publicProcessToolResult({ name: command.name, cwd: this.displayPath(cwd), timeout_seconds: timeoutSeconds, ...result });
   }
 
   async probeShell(context = {}) {
@@ -70,14 +88,61 @@ export class ProcessExecutionService {
     if (command.includes("\0")) throw new BridgeError("invalid_request", "command contains a NUL byte");
     if (Buffer.byteLength(command) > MAX_COMMAND_BYTES) throw new BridgeError("limit_exceeded", `command exceeds maximum size (${MAX_COMMAND_BYTES} bytes)`);
     const shell = workspaceShellCommand(command);
-    return this.run(shell.cmd, shell.args, clampInteger(timeoutSeconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000, false, DEFAULT_PROCESS_OUTPUT_BYTES, context);
+    const result = await this.runPublic(
+      shell.cmd, shell.args,
+      clampInteger(timeoutSeconds, 120, MIN_PROCESS_TIMEOUT_SECONDS, MAX_PROCESS_TIMEOUT_SECONDS) * 1000,
+      context, this.workspace,
+    );
+    return publicProcessToolResult(result);
   }
 
   terminateAll(signal = "SIGTERM", escalate = false) {
     this.processTracker.terminateAll(signal, escalate);
   }
 
-  async run(cmd, args, timeoutMs, allowFailure = false, maxOutputBytes = DEFAULT_PROCESS_OUTPUT_BYTES, context = {}, cwd = this.workspace, stdin = null) {
+  async runPublic(cmd, args, timeoutMs, context, cwd) {
+    const startedAt = Date.now();
+    const result = await this.run(
+      cmd, args, timeoutMs, true, PUBLIC_PROCESS_INLINE_OUTPUT_BYTES,
+      context, cwd, null, { retainOutput: true },
+    );
+    const capture = result[PROCESS_OUTPUT_CAPTURE];
+    const needsContinuation = result.stdout_truncated_bytes > 0 || result.stderr_truncated_bytes > 0;
+    let continuation = {};
+    if (needsContinuation && capture && this.retainCompletedOutput) {
+      const session = this.retainCompletedOutput({
+        command: basename(cmd), cwd,
+        stdout: capture.stdout, stderr: capture.stderr,
+        exitCode: result.code, startedAt, closedAt: Date.now(),
+      });
+      if (session) {
+        continuation = {
+          output_session_id: session.session_id,
+          output_continuation: {
+            tool: "read_process",
+            session_id: session.session_id,
+            stdout_offset: 0,
+            stderr_offset: 0,
+            max_bytes: CONTINUATION_READ_BYTES,
+            retained_bytes_per_stream: MAX_PROCESS_SESSION_OUTPUT_BYTES,
+            expires_after_ms: PROCESS_SESSION_RETENTION_MS,
+            retention: "best-effort-until-session-expiry-or-capacity-eviction",
+          },
+        };
+      } else {
+        continuation = { output_continuation_unavailable: "process session capacity reached" };
+      }
+    }
+    const publicResult = { ...result, ...continuation };
+    if (result.code !== 0) {
+      throw new BridgeError("execution_failed", processFailureMessage(publicResult), {
+        details: { process: publicResult },
+      });
+    }
+    return publicResult;
+  }
+
+  async run(cmd, args, timeoutMs, allowFailure = false, maxOutputBytes = DEFAULT_PROCESS_OUTPUT_BYTES, context = {}, cwd = this.workspace, stdin = null, options = {}) {
     this.throwIfCancelled(context);
     if (stdin !== null && Buffer.byteLength(String(stdin)) > MAX_PROCESS_STDIN_BYTES) {
       throw new BridgeError("limit_exceeded", "process stdin exceeds 1 MiB");
@@ -86,6 +151,8 @@ export class ProcessExecutionService {
     return new Promise((resolvePromise, rejectPromise) => {
       const stdout = new BoundedOutput(maxOutputBytes);
       const stderr = new BoundedOutput(maxOutputBytes);
+      const retainedStdout = options.retainOutput ? new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES) : null;
+      const retainedStderr = options.retainOutput ? new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES) : null;
       let child;
       try {
         child = this.spawnProcess(cmd, args, {
@@ -147,13 +214,19 @@ export class ProcessExecutionService {
       }, timeoutMs);
       timeoutTimer.unref?.();
 
-      child.stdout?.on?.("data", (chunk) => stdout.append(chunk));
-      child.stderr?.on?.("data", (chunk) => stderr.append(chunk));
+      child.stdout?.on?.("data", (chunk) => {
+        stdout.append(chunk);
+        retainedStdout?.append(chunk);
+      });
+      child.stderr?.on?.("data", (chunk) => {
+        stderr.append(chunk);
+        retainedStderr?.append(chunk);
+      });
 
       child.on("error", (error) => {
         cleanupAfterClose();
         settle(() => {
-          if (allowFailure) resolvePromise(processResult(127, stdout, error.message || stderr.text()));
+          if (allowFailure) resolvePromise(processResult(127, stdout, error.message || stderr.text(), retainedStdout, retainedStderr));
           else rejectPromise(error);
         });
       });
@@ -165,9 +238,9 @@ export class ProcessExecutionService {
           settle(() => rejectPromise(error));
           return;
         }
-        const result = processResult(code, stdout, stderr);
+        const result = processResult(code, stdout, stderr, retainedStdout, retainedStderr);
         if (code === 0 || allowFailure) settle(() => resolvePromise(result));
-        else settle(() => rejectPromise(new BridgeError("execution_failed", result.stderr.trim() || result.stdout.trim() || `${cmd} exited ${code}`)));
+        else settle(() => rejectPromise(new BridgeError("execution_failed", processFailureMessage(result), { details: { process: result } })));
       });
 
       if (signal?.aborted) rejectCancelled();
@@ -175,15 +248,22 @@ export class ProcessExecutionService {
   }
 }
 
-function processResult(code, stdout, stderr) {
+function processResult(code, stdout, stderr, retainedStdout = null, retainedStderr = null) {
   const stderrBuffer = stderr instanceof BoundedOutput ? stderr : null;
-  return {
+  const result = {
     code,
     stdout: stdout instanceof BoundedOutput ? stdout.text() : String(stdout || ""),
     stderr: stderrBuffer ? stderrBuffer.text() : boundedErrorMessage(stderr),
     stdout_truncated_bytes: stdout instanceof BoundedOutput ? stdout.truncatedBytes : 0,
     stderr_truncated_bytes: stderrBuffer ? stderrBuffer.truncatedBytes : 0,
   };
+  if (retainedStdout && retainedStderr) {
+    Object.defineProperty(result, PROCESS_OUTPUT_CAPTURE, {
+      value: { stdout: retainedStdout, stderr: retainedStderr },
+      enumerable: false,
+    });
+  }
+  return result;
 }
 
 export function boundedErrorMessage(error) {

package/src/local/process-output-stream.mjs

@@ -0,0 +1,82 @@
+// @ts-check
+
+/**
+ * Bounded byte stream shared by interactive process sessions and completed
+ * one-shot command continuations. It retains the newest bytes while keeping
+ * monotonic offsets so callers can detect data that aged out of the buffer.
+ */
+export class ProcessOutputStream {
+  /** @param {number} maximumBytes */
+  constructor(maximumBytes) {
+    const maximum = Number(maximumBytes);
+    if (!Number.isSafeInteger(maximum) || maximum < 1) {
+      throw new Error("maximum retained output bytes must be a positive safe integer");
+    }
+    this.maximumBytes = maximum;
+    this.buffer = Buffer.alloc(0);
+    this.baseOffset = 0;
+    this.totalBytes = 0;
+  }
+
+  /** @param {unknown} chunk */
+  append(chunk) {
+    const input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk ?? ""));
+    if (!input.length) return;
+    this.totalBytes += input.length;
+    let combined = this.buffer.length ? Buffer.concat([this.buffer, input]) : Buffer.from(input);
+    if (combined.length > this.maximumBytes) {
+      const dropped = combined.length - this.maximumBytes;
+      combined = combined.subarray(dropped);
+      this.baseOffset += dropped;
+    }
+    this.buffer = combined;
+  }
+
+  /** @param {unknown} requestedOffset @param {unknown} maximumBytes */
+  read(requestedOffset, maximumBytes) {
+    const requested = nonNegativeInteger(requestedOffset);
+    const maximum = positiveInteger(maximumBytes);
+    const clampedOffset = Math.min(requested, this.totalBytes);
+    const effectiveOffset = Math.max(clampedOffset, this.baseOffset);
+    const start = effectiveOffset - this.baseOffset;
+    const slice = this.buffer.subarray(start, Math.min(this.buffer.length, start + maximum));
+    const decoded = decodeProcessBytes(slice);
+    return {
+      ...decoded,
+      requested_offset: requested,
+      start_offset: effectiveOffset,
+      next_offset: effectiveOffset + slice.length,
+      total_offset: this.totalBytes,
+      retained_start_offset: this.baseOffset,
+      truncated_before: requested < this.baseOffset,
+      truncated_after: effectiveOffset + slice.length < this.totalBytes,
+    };
+  }
+}
+
+/** @param {Buffer} bytes */
+function decodeProcessBytes(bytes) {
+  try {
+    return { data: new TextDecoder("utf-8", { fatal: true }).decode(bytes), encoding: "utf8" };
+  } catch {
+    return {
+      data: new TextDecoder("utf-8").decode(bytes),
+      data_base64: bytes.toString("base64"),
+      encoding: "base64",
+    };
+  }
+}
+
+/** @param {unknown} value */
+function nonNegativeInteger(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 0) return 0;
+  return number;
+}
+
+/** @param {unknown} value */
+function positiveInteger(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 1) return 1;
+  return number;
+}

package/src/local/process-result-projection.mjs

@@ -0,0 +1,25 @@
+// @ts-check
+
+import { MCP_TEXT_PROJECTION_KEY } from "../shared/result-projection.mjs";
+
+/** @param {Record<string, any>} value */
+export function publicProcessToolResult(value) {
+  const truncated = Number(value.stdout_truncated_bytes) + Number(value.stderr_truncated_bytes);
+  const continuation = value.output_session_id
+    ? ` Continue with read_process session ${value.output_session_id}.`
+    : truncated > 0 ? " Additional output could not be retained because the process-session limit was reached." : "";
+  const summary = `Process exited with code ${value.code}.${truncated > 0 ? ` ${truncated} inline byte(s) omitted.` : ""}${continuation}`;
+  return { ...value, [MCP_TEXT_PROJECTION_KEY]: summary };
+}
+
+/** @param {Record<string, any>} result */
+export function processFailureMessage(result) {
+  const source = String(result.stderr || result.stdout || `process exited ${result.code}`)
+    .replace(/[\r\n]+/g, " ").trim().slice(0, 2000);
+  const suffix = result.output_session_id
+    ? `; additional output is available through read_process session ${result.output_session_id}`
+    : result.stdout_truncated_bytes > 0 || result.stderr_truncated_bytes > 0
+      ? "; additional output was truncated"
+      : "";
+  return `${source || `process exited ${result.code}`}${suffix}`;
+}

package/src/local/process-sessions.mjs

@@ -7,6 +7,7 @@ import { terminateProcessTree, terminateProcessTreeWithEscalation } from "./proc
 import { createToolAuthorizer } from "./policy.mjs";
 import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
 import { clampInteger } from "./numbers.mjs";
+import { ProcessOutputStream } from "./process-output-stream.mjs";
 import {
   MAX_PROCESS_SESSIONS, MAX_PROCESS_SESSION_OUTPUT_BYTES, MAX_PROCESS_SESSION_STDIN_BYTES, PROCESS_SESSION_RETENTION_MS,
 } from "./execution-limits.mjs";
@@ -40,11 +41,37 @@ export class ProcessSessionManager {
     for (const session of this.sessions.values()) notifySessionWaiters(session);
   }
 
+  retainCompletedOutput({ command, cwd, stdout, stderr, exitCode, startedAt, closedAt = Date.now() }) {
+    this.prune();
+    this.evictExitedForCapacity();
+    if (this.sessions.size >= MAX_PROCESS_SESSIONS) return null;
+    const completedAt = Number.isFinite(Number(closedAt)) ? Number(closedAt) : Date.now();
+    const session = {
+      id: `proc_${randomBytes(24).toString("base64url")}`,
+      child: null,
+      argv0: basename(String(command || "process")),
+      cwd,
+      stdout,
+      stderr,
+      startedAt: Number.isFinite(Number(startedAt)) ? Number(startedAt) : completedAt,
+      lastActivity: completedAt,
+      closedAt: completedAt,
+      exitCode: Number.isInteger(exitCode) ? exitCode : null,
+      signal: null,
+      stdinClosed: true,
+      waiters: new Set(),
+      terminationTimer: null,
+    };
+    this.sessions.set(session.id, session);
+    return this.summary(session);
+  }
+
   async start(args, context = {}) {
     this.authorizeTool("start_process");
     const argv = validateArgv(args.argv);
     const cwd = await this.resolveCwd(args.cwd || ".");
     this.prune();
+    this.evictExitedForCapacity();
     if (this.sessions.size >= MAX_PROCESS_SESSIONS) throw new Error(`process session limit reached (${MAX_PROCESS_SESSIONS})`);
     this.throwIfCancelled(context);
 
@@ -59,8 +86,8 @@ export class ProcessSessionManager {
       child,
       argv0: basename(argv[0]),
       cwd,
-      stdout: createSessionStream(),
-      stderr: createSessionStream(),
+      stdout: new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES),
+      stderr: new ProcessOutputStream(MAX_PROCESS_SESSION_OUTPUT_BYTES),
       startedAt: Date.now(),
       lastActivity: Date.now(),
       closedAt: null,
@@ -74,12 +101,12 @@ export class ProcessSessionManager {
     this.trackChild(child, context.callId);
 
     child.stdout.on("data", (chunk) => {
-      appendSessionStream(session.stdout, chunk);
+      session.stdout.append(chunk);
       session.lastActivity = Date.now();
       notifySessionWaiters(session);
     });
     child.stderr.on("data", (chunk) => {
-      appendSessionStream(session.stderr, chunk);
+      session.stderr.append(chunk);
       session.lastActivity = Date.now();
       notifySessionWaiters(session);
     });
@@ -94,7 +121,7 @@ export class ProcessSessionManager {
     });
 
     child.on("error", (error) => {
-      appendSessionStream(session.stderr, Buffer.from(`${boundedErrorMessage(error)}\n`));
+      session.stderr.append(Buffer.from(`${boundedErrorMessage(error)}\n`));
       session.lastActivity = Date.now();
       notifySessionWaiters(session);
     });
@@ -132,8 +159,8 @@ export class ProcessSessionManager {
     session.lastActivity = Date.now();
     return {
       ...this.summary(session),
-      stdout: readSessionStream(session.stdout, stdoutOffset, maxBytes),
-      stderr: readSessionStream(session.stderr, stderrOffset, maxBytes),
+      stdout: session.stdout.read(stdoutOffset, maxBytes),
+      stderr: session.stderr.read(stderrOffset, maxBytes),
     };
   }
 
@@ -207,6 +234,9 @@ export class ProcessSessionManager {
     for (const [id, session] of this.sessions) {
       if (session.closedAt !== null && session.lastActivity < cutoff) this.sessions.delete(id);
     }
+  }
+
+  evictExitedForCapacity() {
     if (this.sessions.size < MAX_PROCESS_SESSIONS) return;
     const exited = [...this.sessions.values()]
       .filter((session) => session.closedAt !== null)
@@ -240,50 +270,6 @@ function waitForSpawn(child) {
   });
 }
 
-function createSessionStream() {
-  return { buffer: Buffer.alloc(0), baseOffset: 0, totalBytes: 0 };
-}
-
-function appendSessionStream(stream, chunk) {
-  const input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk ?? ""));
-  stream.totalBytes += input.length;
-  let combined = stream.buffer.length ? Buffer.concat([stream.buffer, input]) : Buffer.from(input);
-  if (combined.length > MAX_PROCESS_SESSION_OUTPUT_BYTES) {
-    const dropped = combined.length - MAX_PROCESS_SESSION_OUTPUT_BYTES;
-    combined = combined.subarray(dropped);
-    stream.baseOffset += dropped;
-  }
-  stream.buffer = combined;
-}
-
-function readSessionStream(stream, requestedOffset, maxBytes) {
-  const clampedOffset = Math.min(requestedOffset, stream.totalBytes);
-  const effectiveOffset = Math.max(clampedOffset, stream.baseOffset);
-  const start = effectiveOffset - stream.baseOffset;
-  const slice = stream.buffer.subarray(start, Math.min(stream.buffer.length, start + maxBytes));
-  let data;
-  let dataBase64;
-  let encoding = "utf8";
-  try {
-    data = new TextDecoder("utf-8", { fatal: true }).decode(slice);
-  } catch {
-    data = new TextDecoder("utf-8").decode(slice);
-    dataBase64 = slice.toString("base64");
-    encoding = "base64";
-  }
-  return {
-    data,
-    ...(dataBase64 ? { data_base64: dataBase64 } : {}),
-    encoding,
-    requested_offset: requestedOffset,
-    start_offset: effectiveOffset,
-    next_offset: effectiveOffset + slice.length,
-    total_offset: stream.totalBytes,
-    truncated_before: requestedOffset < stream.baseOffset,
-    truncated_after: effectiveOffset + slice.length < stream.totalBytes,
-  };
-}
-
 function sessionHasOutputAfter(session, stdoutOffset, stderrOffset) {
   return session.stdout.totalBytes > stdoutOffset || session.stderr.totalBytes > stderrOffset;
 }

package/src/local/runtime.mjs

@@ -135,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),

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."
   ]