machine-bridge-mcp 1.2.9 → 1.2.11

package/scripts/release-acceptance.mjs

@@ -1,6 +1,5 @@
 import { createHash } from "node:crypto";
 import {
-  lstatSync,
   mkdtempSync,
   readFileSync,
   rmSync,
@@ -8,6 +7,7 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
+import { readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
 
 export const ACCEPTANCE_SCHEMA_VERSION = 1;
 export const ACCEPTANCE_POLICY_VERSION = "1.2.8";
@@ -15,6 +15,7 @@ export const AGENT_VERIFIED_ACCEPTANCE_VERSION = "1.2.9";
 export const ACCEPTANCE_CONFIRMATION = "owner-started-agent-verified-local-candidate";
 export const LEGACY_ACCEPTANCE_CONFIRMATION = "repository-owner-local-test";
 const MAX_ACCEPTANCE_BYTES = 64 * 1024;
+const MAX_RELEASE_TARBALL_BYTES = 64 * 1024 * 1024;
 
 export function requiresLocalAcceptance(version) {
   return compareVersions(parseVersion(version), parseVersion(ACCEPTANCE_POLICY_VERSION)) >= 0;
@@ -76,20 +77,25 @@ export function packProject(root, destination) {
 
 export function readAcceptance(root, version) {
   const path = acceptancePath(root, version);
-  const stat = lstatSync(path);
-  if (stat.isSymbolicLink() || !stat.isFile()) {
-    throw new Error(`release acceptance record must be a regular file: ${path}`);
-  }
-  if (stat.size > MAX_ACCEPTANCE_BYTES) {
-    throw new Error(`release acceptance record exceeds ${MAX_ACCEPTANCE_BYTES} bytes`);
+  let bytes;
+  try {
+    bytes = readBoundedRegularFileSync(
+      path, MAX_ACCEPTANCE_BYTES, "release acceptance record",
+      { verifyPathIdentity: true },
+    );
+  } catch (error) {
+    const message = String(error?.message || error);
+    if (message.includes("exceeds")) throw new Error(`release acceptance record exceeds ${MAX_ACCEPTANCE_BYTES} bytes`);
+    if (message.includes("regular file") || message.includes("symbolic link") || message.includes("identity changed")) {
+      throw new Error(`release acceptance record must be a regular file: ${path}`);
+    }
+    throw error;
   }
-  let value;
   try {
-    value = JSON.parse(readFileSync(path, "utf8"));
+    return JSON.parse(bytes.toString("utf8"));
   } catch (error) {
     throw new Error(`release acceptance record is not valid JSON: ${error.message}`);
   }
-  return value;
 }
 
 export function verifyAcceptanceRecord(record, metadata) {
@@ -134,9 +140,19 @@ export function verifyCurrentReleaseAcceptance(root) {
 }
 
 export function verifyTarball(path, metadata) {
-  const stat = lstatSync(path);
-  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("release candidate tarball is not a regular file");
-  const bytes = readFileSync(path);
+  let bytes;
+  try {
+    bytes = readBoundedRegularFileSync(
+      path, MAX_RELEASE_TARBALL_BYTES, "release candidate tarball",
+      { verifyPathIdentity: true },
+    );
+  } catch (error) {
+    const message = String(error?.message || error);
+    if (message.includes("regular file") || message.includes("symbolic link") || message.includes("identity changed")) {
+      throw new Error("release candidate tarball is not a regular file");
+    }
+    throw error;
+  }
   const shasum = createHash("sha1").update(bytes).digest("hex");
   const integrity = `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
   if (shasum !== metadata.shasum || integrity !== metadata.integrity) {

package/scripts/run-checks.mjs

@@ -1,29 +1,19 @@
-import { spawnSync } from "node:child_process";
-import { performance } from "node:perf_hooks";
 import { checkTasks } from "./check-plan.mjs";
+import { runVerificationPlan } from "./check-runner.mjs";
 
 const mode = process.argv[2] || "full";
 const tasks = checkTasks(mode);
-const npmCli = process.env.npm_execpath;
-if (!npmCli) throw new Error("check runner must run through npm so npm_execpath is available");
-const planStartedAt = performance.now();
 
-console.log(`running ${mode} verification plan (${tasks.length} tasks)`);
-for (const [index, task] of tasks.entries()) {
-  const taskStartedAt = performance.now();
-  console.log(`\n[${index + 1}/${tasks.length}] npm run ${task}`);
-  const result = spawnSync(process.execPath, [npmCli, "run", task], {
-    cwd: process.cwd(),
-    env: process.env,
-    stdio: "inherit",
+try {
+  await runVerificationPlan({
+    mode,
+    tasks,
+    npmCli: process.env.npm_execpath,
+    verbose: process.env.MBM_CHECK_VERBOSE === "1",
   });
-  const elapsedSeconds = ((performance.now() - taskStartedAt) / 1000).toFixed(1);
-  if (result.error) throw result.error;
-  if (result.status !== 0) {
-    console.error(`verification task failed after ${elapsedSeconds}s: ${task}`);
-    process.exit(result.status || 1);
+} catch (error) {
+  if (error?.message && !String(error.message).startsWith("verification task failed:")) {
+    console.error(error.message);
   }
-  console.log(`completed ${task} in ${elapsedSeconds}s`);
+  process.exit(Number(error?.exitCode) || 1);
 }
-const totalSeconds = ((performance.now() - planStartedAt) / 1000).toFixed(1);
-console.log(`\n${mode} verification plan passed in ${totalSeconds}s`);

package/src/local/bounded-output.mjs

@@ -39,12 +39,29 @@ export class BoundedOutput {
   }
 
   get truncatedBytes() {
-    return Math.max(0, this.totalBytes - this.maximum);
+    if (this.full) return 0;
+    const head = decodeUtf8Boundary(this.head, "head");
+    const tail = decodeUtf8Boundary(this.tail, "tail");
+    return Math.max(0, this.totalBytes - head.bytes - tail.bytes);
   }
 
   text() {
     if (this.full) return this.full.toString("utf8");
-    const marker = `\n\n[truncated ${this.truncatedBytes} bytes; preserved beginning and end]\n\n`;
-    return `${this.head.toString("utf8")}${marker}${this.tail.toString("utf8")}`;
+    const head = decodeUtf8Boundary(this.head, "head");
+    const tail = decodeUtf8Boundary(this.tail, "tail");
+    const omitted = Math.max(0, this.totalBytes - head.bytes - tail.bytes);
+    const marker = `\n\n[truncated ${omitted} bytes; preserved beginning and end]\n\n`;
+    return `${head.text}${marker}${tail.text}`;
   }
 }
+
+function decodeUtf8Boundary(buffer, side) {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  for (let trim = 0; trim <= Math.min(3, buffer.length); trim += 1) {
+    const slice = side === "head"
+      ? buffer.subarray(0, buffer.length - trim)
+      : buffer.subarray(trim);
+    try { return { text: decoder.decode(slice), bytes: slice.length }; } catch { /* try the next code-point boundary */ }
+  }
+  return { text: new TextDecoder("utf-8").decode(buffer), bytes: buffer.length };
+}

package/src/local/errors.mjs

@@ -54,6 +54,7 @@ export function publicError(error, options = {}) {
     code: normalized.code,
     message: normalized.expose ? normalized.message : defaultMessage(normalized.code),
     retryable: normalized.retryable,
+    ...(normalized.expose && normalized.details ? { details: normalized.details } : {}),
   };
 }
 
@@ -61,7 +62,10 @@ export function remoteBridgeError(value, fallbackMessage = "remote operation fai
   if (isRecord(value)) {
     const code = normalizeErrorCode(value.code);
     const message = typeof value.message === "string" && value.message ? value.message : fallbackMessage;
-    return new BridgeError(code, message, { retryable: value.retryable === true });
+    return new BridgeError(code, message, {
+      retryable: value.retryable === true,
+      details: isRecord(value.details) ? value.details : undefined,
+    });
   }
   return new BridgeError("execution_failed", fallbackMessage);
 }

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;
 }