@opengeni/runtime 0.11.0 → 0.13.3

package/src/mcp-network.ts

@@ -0,0 +1,343 @@
+import type { Settings } from "@opengeni/config";
+import {
+  isNonPublicAddress,
+  pinnedFetch,
+  resolvePinnedDestination,
+  type DnsLookup,
+  type FetchLike,
+} from "@opengeni/network";
+
+export { undiciFetch } from "@opengeni/network";
+
+export const MCP_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+export const MCP_MAX_INBOUND_REQUEST_BYTES = 1024 * 1024;
+export const MCP_MAX_TOOL_DEFINITION_BYTES = 128 * 1024;
+export const MCP_MAX_TOOL_LIST_BYTES = 4 * 1024 * 1024;
+export const MCP_MAX_TOOL_LIST_ENTRIES = 1_000;
+export const MCP_MAX_TOOL_RESULT_BYTES = 1024 * 1024;
+export const MCP_MAX_TOOL_SEARCH_DISCLOSURE_BYTES = 256 * 1024;
+export const MCP_MAX_SELECTED_SERVERS = 64;
+export const MCP_MAX_CONCURRENT_SERVER_OPERATIONS = 8;
+// @openai/agents has a separate lifecycle fence around MCPServer.connect().
+// It defaults to 10 seconds and can otherwise preempt a larger per-server
+// transport timeout before that server finishes its own handshake.
+export const MCP_DEFAULT_OUTER_CONNECT_TIMEOUT_MS = 10_000;
+export const MCP_MAX_AGGREGATE_TOOL_LIST_ENTRIES = 4_096;
+export const MCP_MAX_AGGREGATE_TOOL_LIST_BYTES = 16 * 1024 * 1024;
+export const MCP_MAX_TOOL_SEARCH_SOURCES = 64;
+export const MCP_MAX_TOOL_SEARCH_SOURCE_LABEL_LENGTH = 120;
+export const MCP_MAX_TOOL_SEARCH_DESCRIPTION_BYTES = 16 * 1024;
+
+export class McpPayloadTooLargeError extends Error {
+  constructor(
+    readonly label: string,
+    readonly actualBytes: number,
+    readonly maxBytes: number,
+  ) {
+    super(`${label} exceeds the ${maxBytes}-byte safety limit`);
+    this.name = "McpPayloadTooLargeError";
+  }
+}
+
+export function mcpSerializedSizeBytes(value: unknown): number {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value) ?? "null";
+  } catch {
+    throw new Error("MCP payload is not JSON serializable");
+  }
+  return Buffer.byteLength(serialized);
+}
+
+export function assertMcpPayloadWithinBytes(value: unknown, maxBytes: number, label: string): void {
+  const actualBytes = mcpSerializedSizeBytes(value);
+  if (actualBytes > maxBytes) {
+    throw new McpPayloadTooLargeError(label, actualBytes, maxBytes);
+  }
+}
+
+export function assertMcpToolListWithinBounds<T>(tools: readonly T[]): readonly T[] {
+  if (tools.length > MCP_MAX_TOOL_LIST_ENTRIES) {
+    throw new McpPayloadTooLargeError("MCP tool list", tools.length, MCP_MAX_TOOL_LIST_ENTRIES);
+  }
+  for (const tool of tools) {
+    const toolBytes = mcpSerializedSizeBytes(tool);
+    if (toolBytes > MCP_MAX_TOOL_DEFINITION_BYTES) {
+      throw new McpPayloadTooLargeError(
+        "MCP tool definition",
+        toolBytes,
+        MCP_MAX_TOOL_DEFINITION_BYTES,
+      );
+    }
+  }
+  // Measure the complete JSON array, including brackets and separators. Summing
+  // definitions alone under-counts by one byte per separator plus the array
+  // delimiters and makes the advertised serialized-byte ceiling porous.
+  const totalBytes = mcpSerializedSizeBytes(tools);
+  if (totalBytes > MCP_MAX_TOOL_LIST_BYTES) {
+    throw new McpPayloadTooLargeError("MCP tool list", totalBytes, MCP_MAX_TOOL_LIST_BYTES);
+  }
+  return tools;
+}
+
+export function assertMcpServerSelectionWithinBounds<T>(servers: readonly T[]): readonly T[] {
+  if (servers.length > MCP_MAX_SELECTED_SERVERS) {
+    throw new McpPayloadTooLargeError(
+      "selected MCP server count",
+      servers.length,
+      MCP_MAX_SELECTED_SERVERS,
+    );
+  }
+  return servers;
+}
+
+export function mcpOuterConnectTimeoutMs(
+  configuredTimeouts: readonly (number | undefined)[],
+): number {
+  return Math.max(
+    MCP_DEFAULT_OUTER_CONNECT_TIMEOUT_MS,
+    ...configuredTimeouts.flatMap((timeoutMs) => (timeoutMs === undefined ? [] : [timeoutMs])),
+  );
+}
+
+type McpToolListContribution = {
+  entries: number;
+  bytes: number;
+};
+
+/**
+ * Atomic aggregate accounting shared by every exposed tools/list in one run.
+ * A repeated list for the same source REPLACES its prior contribution, so
+ * cache invalidation/relisting cannot ratchet the budget upward. Failed
+ * replacements leave the previous accounting intact.
+ */
+export class McpAggregateToolListBudget {
+  private readonly contributions = new Map<string, McpToolListContribution>();
+  private totalEntries = 0;
+  private totalBytes = 0;
+
+  constructor(
+    private readonly label = "aggregate MCP tool list",
+    private readonly maxEntries = MCP_MAX_AGGREGATE_TOOL_LIST_ENTRIES,
+    private readonly maxBytes = MCP_MAX_AGGREGATE_TOOL_LIST_BYTES,
+  ) {}
+
+  replace<T>(sourceId: string, tools: readonly T[]): readonly T[] {
+    assertMcpToolListWithinBounds(tools);
+    const contribution = {
+      entries: tools.length,
+      // Conservatively account each server as its complete serialized array.
+      // Summing these arrays slightly over-counts the brackets relative to one
+      // flattened array, which is intentional for a fail-closed hard ceiling.
+      bytes: mcpSerializedSizeBytes(tools),
+    };
+    const previous = this.contributions.get(sourceId) ?? { entries: 0, bytes: 0 };
+    const nextEntries = this.totalEntries - previous.entries + contribution.entries;
+    if (nextEntries > this.maxEntries) {
+      throw new McpPayloadTooLargeError(this.label, nextEntries, this.maxEntries);
+    }
+    const nextBytes = this.totalBytes - previous.bytes + contribution.bytes;
+    if (nextBytes > this.maxBytes) {
+      throw new McpPayloadTooLargeError(this.label, nextBytes, this.maxBytes);
+    }
+    this.contributions.set(sourceId, contribution);
+    this.totalEntries = nextEntries;
+    this.totalBytes = nextBytes;
+    return tools;
+  }
+
+  remove(sourceId: string): void {
+    const previous = this.contributions.get(sourceId);
+    if (!previous) return;
+    this.contributions.delete(sourceId);
+    this.totalEntries -= previous.entries;
+    this.totalBytes -= previous.bytes;
+  }
+
+  snapshot(): Readonly<McpToolListContribution> {
+    return { entries: this.totalEntries, bytes: this.totalBytes };
+  }
+}
+
+/** Stable-order parallel map with a hard in-flight ceiling and fail-stop drain. */
+export async function boundedParallelMap<T, R>(
+  values: readonly T[],
+  concurrency: number,
+  mapper: (value: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new Error("bounded parallel map concurrency must be a positive integer");
+  }
+  if (values.length === 0) return [];
+
+  const results = new Array<R>(values.length);
+  const errors: Array<{ index: number; error: unknown }> = [];
+  let nextIndex = 0;
+  let stopped = false;
+  const worker = async () => {
+    while (!stopped) {
+      const index = nextIndex;
+      if (index >= values.length) return;
+      nextIndex += 1;
+      try {
+        results[index] = await mapper(values[index]!, index);
+      } catch (error) {
+        errors.push({ index, error });
+        stopped = true;
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, () => worker()));
+  if (errors.length > 0) {
+    errors.sort((left, right) => left.index - right.index);
+    throw errors[0]!.error;
+  }
+  return results;
+}
+
+/**
+ * Guard normal MCP traffic with the same deployment policy as OAuth traffic.
+ * The pinned transport resolves and policy-checks the destination after the
+ * caller has composed any credential headers, then performs the final network
+ * call through the vetted Agent. It forces manual redirects, so an
+ * Authorization-bearing request never follows a provider-controlled Location
+ * to an unvalidated host.
+ *
+ * This module is deliberately agent-loop-free. API code imports the explicit
+ * `@opengeni/runtime/mcp-network` leaf rather than the runtime root barrel.
+ */
+export function guardedMcpFetch<TInput extends string | URL | Request>(
+  settings: Pick<Settings, "environment" | "integrationsAllowPrivateNetworkTargets">,
+  fetchImpl: (input: TInput, init?: RequestInit) => Promise<Response>,
+  options: {
+    maxResponseBytes?: number;
+    dnsLookup?: DnsLookup;
+    requireHttpsOutsideLocalTest?: boolean;
+  } = {},
+): (input: TInput, init?: RequestInit) => Promise<Response> {
+  return async (input: TInput, init?: RequestInit) => {
+    const response = await pinnedFetch(input, init, settings, {
+      fetchImpl: fetchImpl as FetchLike,
+      ...(options.dnsLookup ? { dnsLookup: options.dnsLookup } : {}),
+      label: "MCP endpoint",
+      requireHttpsOutsideLocalTest: options.requireHttpsOutsideLocalTest ?? true,
+    });
+    return boundMcpResponseBody(response, options.maxResponseBytes ?? MCP_MAX_RESPONSE_BYTES);
+  };
+}
+
+export function boundMcpResponseBody(response: Response, maxBytes: number): Response {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    void response.body?.cancel().catch(() => undefined);
+    throw new McpPayloadTooLargeError("MCP response", declaredLength, maxBytes);
+  }
+  if (!response.body) {
+    return response;
+  }
+
+  const reader = response.body.getReader();
+  let receivedBytes = 0;
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const chunk = await reader.read();
+        if (chunk.done) {
+          controller.close();
+          return;
+        }
+        receivedBytes += chunk.value.byteLength;
+        if (receivedBytes > maxBytes) {
+          await reader.cancel().catch(() => undefined);
+          controller.error(new McpPayloadTooLargeError("MCP response", receivedBytes, maxBytes));
+          return;
+        }
+        controller.enqueue(chunk.value);
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      await reader.cancel(reason).catch(() => undefined);
+    },
+  });
+  const bounded = new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+  Object.defineProperties(bounded, {
+    redirected: { value: response.redirected },
+    type: { value: response.type },
+    url: { value: response.url },
+  });
+  return bounded;
+}
+
+export async function cancelMcpResponseBody(response: Response): Promise<void> {
+  await response.body?.cancel().catch(() => undefined);
+}
+
+/** Read and rebuild an inbound MCP request before the SDK parses it. */
+export async function boundedMcpRequest(
+  request: Request,
+  maxBytes = MCP_MAX_INBOUND_REQUEST_BYTES,
+): Promise<Request> {
+  const declared = request.headers.get("content-length");
+  if (declared !== null) {
+    const normalized = declared.trim();
+    if (!/^\d+$/.test(normalized)) {
+      await request.body?.cancel().catch(() => undefined);
+      throw new McpPayloadTooLargeError("MCP request", 0, maxBytes);
+    }
+    const declaredBytes = Number(normalized);
+    if (!Number.isSafeInteger(declaredBytes) || declaredBytes > maxBytes) {
+      await request.body?.cancel().catch(() => undefined);
+      throw new McpPayloadTooLargeError("MCP request", declaredBytes, maxBytes);
+    }
+  }
+  if (!request.body) {
+    return request;
+  }
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let receivedBytes = 0;
+  try {
+    for (;;) {
+      const result = await reader.read();
+      if (result.done) break;
+      receivedBytes += result.value.byteLength;
+      if (receivedBytes > maxBytes) {
+        await reader.cancel().catch(() => undefined);
+        throw new McpPayloadTooLargeError("MCP request", receivedBytes, maxBytes);
+      }
+      chunks.push(result.value);
+    }
+  } catch (error) {
+    await reader.cancel().catch(() => undefined);
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+  const body = new Uint8Array(receivedBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new Request(request, { body, headers: request.headers });
+}
+
+export async function assertMcpDestinationAllowed(
+  rawUrl: string,
+  settings: Pick<Settings, "environment" | "integrationsAllowPrivateNetworkTargets">,
+  options: { dnsLookup?: DnsLookup } = {},
+): Promise<void> {
+  await resolvePinnedDestination(rawUrl, settings, {
+    ...(options.dnsLookup ? { dnsLookup: options.dnsLookup } : {}),
+    label: "MCP endpoint",
+    requireHttpsOutsideLocalTest: true,
+  });
+}
+
+export const isNonPublicMcpAddress = isNonPublicAddress;

package/src/sandbox/channel-a.ts

@@ -58,6 +58,21 @@ import type {
   TerminalExecRequest,
   TerminalExecResponse,
 } from "@opengeni/contracts";
+import {
+  isExecSessionLostBanner,
+  parseExecBannerExitCode,
+  parseExecBannerSessionId,
+} from "./exec-banner";
+import {
+  createTurnToolCancellationController,
+  TurnSandboxCommandCancelledError,
+} from "./turn-tool-cancellation";
+
+export {
+  isExecSessionLostBanner,
+  parseExecBannerExitCode,
+  parseExecBannerSessionId,
+} from "./exec-banner";
 
 // ── The minimal session surface Channel A consumes (a structural subset of the
 // SDK's SandboxSession, all optional — capability-probed before use). ─────────
@@ -98,6 +113,21 @@ export type ChannelASession = {
     yieldTimeMs?: number;
     maxOutputTokens?: number;
   }): Promise<string>;
+  writeStdinForProcessMutation?(args: {
+    sessionId: number;
+    chars?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }): Promise<string>;
+  writeStdinForProcessControl?(args: {
+    sessionId: number;
+    chars?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }): Promise<string>;
+  cancelExecCommand?(opId: string): Promise<boolean>;
+  hasRetainedProcess?(providerSessionId: number): boolean;
+  execCommandForProcessControl?(providerSessionId: number, args: ChannelAExecArgs): Promise<string>;
   createEditor?(runAs?: string): ChannelAEditor;
   supportsPty?(): boolean;
 };
@@ -1130,17 +1160,49 @@ export class SandboxChannelAService {
 
   // ════════════════════════ Terminal exec + PTY (A2) ════════════════════════
 
-  /** Run a bounded command, return buffered stdout/stderr + exit code inline. The
-   *  long-running tail (when the process hasn't exited within timeoutMs) keeps
-   *  running in-box; if emitStream is set the buffered output is also published as
-   *  the agent firehose so other viewers see it. */
+  /** Run a bounded command to physical completion and return buffered output.
+   *  A deadline cancels the exact provider operation, proves its process group
+   *  absent, and settles any retained-process admission before returning 124. */
   async terminalExec(req: TerminalExecRequest): Promise<TerminalExecResponse> {
-    const r = await this.run({
-      cmd: req.command,
-      workdir: this.terminalWorkdir(req.cwd),
-      yieldTimeMs: req.timeoutMs,
-    });
-    const running = r.exitCode === null && typeof r.sessionId === "number";
+    const abort = new AbortController();
+    const controller = createTurnToolCancellationController(abort.signal);
+    const timeoutReason = new Error(`Terminal command exceeded ${req.timeoutMs}ms`);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      abort.abort(timeoutReason);
+    }, req.timeoutMs);
+    const terminalWorkdir = this.terminalWorkdir(req.cwd);
+    let r: Awaited<ReturnType<typeof controller.runSandboxCommandStructured>>;
+    try {
+      r = await controller.runSandboxCommandStructured(this.session, {
+        cmd: req.command,
+        ...(terminalWorkdir ? { workdir: terminalWorkdir } : {}),
+        ...(this.runAs ? { runAs: this.runAs } : {}),
+        yieldTimeMs: req.timeoutMs,
+      });
+      if (timedOut) {
+        await controller.waitForQuiescence();
+        r = {
+          stdout: "",
+          stderr: timeoutReason.message,
+          exitCode: 124,
+          wallTimeSeconds: req.timeoutMs / 1_000,
+        };
+      }
+    } catch (error) {
+      controller.cancel(error);
+      await controller.waitForQuiescence();
+      if (!timedOut && !(error instanceof TurnSandboxCommandCancelledError)) throw error;
+      r = {
+        stdout: "",
+        stderr: timeoutReason.message,
+        exitCode: 124,
+        wallTimeSeconds: req.timeoutMs / 1_000,
+      };
+    } finally {
+      clearTimeout(timer);
+    }
     if (req.emitStream && (r.stdout || r.stderr)) {
       const events: { type: SessionEventType; payload: unknown }[] = [];
       const commandId = crypto.randomUUID();
@@ -1160,7 +1222,7 @@ export class SandboxChannelAService {
       stdout: r.stdout,
       stderr: r.stderr,
       exitCode: r.exitCode,
-      running,
+      running: false,
       wallTimeSeconds: r.wallTimeSeconds,
     };
   }
@@ -1200,10 +1262,13 @@ export class SandboxChannelAService {
    *  it as terminal.pty.output.delta). Throws ChannelAUnsupportedError when the
    *  backend has no writeStdin. */
   async ptyWrite(_req: PtyWriteRequest, execSessionId: number, data: string): Promise<string> {
-    if (!this.session.writeStdin) {
+    const write =
+      this.session.writeStdinForProcessMutation?.bind(this.session) ??
+      this.session.writeStdin?.bind(this.session);
+    if (!write) {
       throw new ChannelAUnsupportedError("interactive terminal unsupported on this backend");
     }
-    const out = await this.session.writeStdin({
+    const out = await write({
       sessionId: execSessionId,
       chars: data,
       yieldTimeMs: 250,
@@ -1225,25 +1290,27 @@ export class SandboxChannelAService {
   /** Resize an open PTY (SIGWINCH via stty against the exec-session). The SDK has
    *  no resize method; stty in the same tty session updates the geometry. */
   async ptyResize(req: PtyResizeRequest, execSessionId: number): Promise<void> {
-    if (!this.session.writeStdin) return;
+    const write =
+      this.session.writeStdinForProcessControl?.bind(this.session) ??
+      this.session.writeStdin?.bind(this.session);
+    if (!write) return;
     // Send a stty in-band on the same pty session.
-    await this.session.writeStdin({
+    await write({
       sessionId: execSessionId,
       chars: `stty cols ${req.cols} rows ${req.rows}\n`,
       yieldTimeMs: 50,
     });
   }
 
-  /** Close an open PTY: write exit/EOF. The caller marks the row closed + emits
-   *  terminal.pty.exited. */
-  async ptyClose(_req: PtyCloseRequest, execSessionId: number | null): Promise<void> {
-    if (execSessionId !== null && this.session.writeStdin) {
-      try {
-        await this.session.writeStdin({ sessionId: execSessionId, chars: "", yieldTimeMs: 50 }); // EOF
-      } catch {
-        // best-effort; the row is marked closed regardless.
-      }
-    }
+  /** Ask an open PTY to exit and return the exact provider banner. The routing
+   * session settles durable process authority only when that banner proves this
+   * locator exited or was lost; callers must keep metadata open otherwise. */
+  async ptyClose(_req: PtyCloseRequest, execSessionId: number | null): Promise<string> {
+    const write =
+      this.session.writeStdinForProcessControl?.bind(this.session) ??
+      this.session.writeStdin?.bind(this.session);
+    if (execSessionId === null || !write) return "";
+    return await write({ sessionId: execSessionId, chars: "", yieldTimeMs: 250 }); // EOF
   }
 
   // ──────────────────────────── helpers ──────────────────────────────────────
@@ -1432,52 +1499,6 @@ function isDefinitePathNotFoundError(error: unknown): boolean {
   );
 }
 
-// Detect the Modal "the exec-session you're writing to no longer exists" banner.
-// writeStdin reports a vanished session as a non-throwing string of the shape
-// `write_stdin failed: session not found: <N>` (it does NOT raise). This is a
-// hard cancellation-fence fact, so classify only the complete known banner (or
-// its bare provider fact) carrying the exact tracked numeric id. ID-less,
-// malformed, mismatched, or embellished/ambiguous text must remain fail-closed.
-export function isExecSessionLostBanner(out: string, execSessionId: number): boolean {
-  if (!out || !Number.isSafeInteger(execSessionId) || execSessionId < 0) return false;
-  const match = out.match(/^(?:write_stdin failed: )?session not found: (\d+)$/);
-  // JavaScript's `$` also matches immediately before one final line terminator.
-  // Requiring the regex match to consume the entire string keeps even that
-  // otherwise-special case fail-closed.
-  if (!match || match[0] !== out) return false;
-  // String equality is intentional: parseInt would normalize malformed facts
-  // such as `01` and can round an out-of-range integer into another identity.
-  return match[1] === String(execSessionId);
-}
-
-// Recover the numeric exec-session id the SDK embeds in a formatExecResponse
-// banner for a STILL-RUNNING process (`Process running with session ID <N>`).
-// A finished command emits `Process exited with code <N>` instead (no session
-// id) — that yields null. Only the banner region (before the `Output:` marker)
-// is scanned so a session-id-looking line in the command's own output can't
-// spoof it. This is what makes the interactive PTY work on backends whose only
-// exec surface is execCommand (Modal): without it ptyOpen reports execSessionId
-// = null and every pty/write 409s ("interactive terminal unsupported").
-export function parseExecBannerSessionId(raw: string): number | null {
-  const outputIdx = raw.indexOf("\nOutput:\n");
-  const banner = outputIdx >= 0 ? raw.slice(0, outputIdx) : raw.startsWith("Output:\n") ? "" : raw;
-  const match = banner.match(/Process running with session ID (\d+)/);
-  if (!match) return null;
-  const n = Number.parseInt(match[1]!, 10);
-  return Number.isFinite(n) ? n : null;
-}
-
-/** Recover a completed execCommand fallback's exit status from its banner.
- * Only the banner region is inspected, so command output cannot spoof success. */
-export function parseExecBannerExitCode(raw: string): number | null {
-  const outputIdx = raw.indexOf("\nOutput:\n");
-  const banner = outputIdx >= 0 ? raw.slice(0, outputIdx) : raw.startsWith("Output:\n") ? "" : raw;
-  const match = banner.match(/Process exited with code (-?\d+)/);
-  if (!match) return null;
-  const exitCode = Number.parseInt(match[1]!, 10);
-  return Number.isSafeInteger(exitCode) ? exitCode : null;
-}
-
 function sniffBinary(bytes: Buffer): boolean {
   const n = Math.min(bytes.byteLength, 8192);
   for (let i = 0; i < n; i++) if (bytes[i] === 0) return true;