@bitkyc08/opencodex 2.8.0 → 2.9.0

package/src/adapters/cursor/native-exec-mcp.ts

@@ -22,7 +22,7 @@ import {
   type ReadMcpResourceExecArgs,
 } from "./gen/agent_pb";
 import type { McpCallResult } from "./mcp-manager";
-import { CursorMcpManager } from "./mcp-manager";
+import { CursorMcpManager, decodedBase64Length } from "./mcp-manager";
 import { errorText } from "./native-exec-common";
 import type { CursorNativeToolDeps } from "./native-exec-tools";
 import { encodeCursorInputSchema } from "./tool-definitions";
@@ -62,7 +62,7 @@ export function mcpDepsFromManager(manager: CursorMcpManager): CursorNativeToolD
         }
         const result = await manager.callTool(name, decodeMcpArgs(args.args));
         return create(McpResultSchema, {
-          result: { case: "success", value: create(McpSuccessSchema, { isError: result.isError, content: toContentItems(result) }) },
+          result: { case: "success", value: create(McpSuccessSchema, { isError: result.isError, content: toContentItems(result, manager) }) },
         });
       } catch (err) {
         return create(McpResultSchema, { result: { case: "error", value: create(McpErrorSchema, { error: errorText(err) }) } });
@@ -112,7 +112,9 @@ function decodeMcpArgs(raw: { [key: string]: Uint8Array }): Record<string, unkno
   return decodeCursorArgsMap(raw);
 }
 
-function toContentItems(result: McpCallResult): McpToolResultContentItem[] {
+function toContentItems(result: McpCallResult, manager: CursorMcpManager): McpToolResultContentItem[] {
+  const decodedBytes = result.content.reduce((sum, block) => sum + (block.type === "image" && typeof block.data === "string" ? decodedBase64Length(block.data) : 0), 0);
+  manager.assertDecodedResultBudget(result, decodedBytes);
   return result.content.map(block => {
     // Promote real image payloads to McpImageContent so the model receives the actual bytes,
     // not a "[image]" placeholder. Non-text, non-image blocks (audio/resource) still degrade

package/src/adapters/cursor/native-exec-shell.ts

@@ -19,9 +19,67 @@ import {
   type ExecServerMessage,
 } from "./gen/agent_pb";
 import { errorText, execBytes, execStreamCloseBytes } from "./native-exec-common";
+import {
+  createAdmissionGate,
+  type AdmissionLease,
+  type AdmissionMetrics,
+} from "../../lib/admission";
+
+export const CURSOR_BACKGROUND_SHELL_MAX_LIVE = 8;
+export const CURSOR_BACKGROUND_SHELL_IDLE_MS = 5 * 60_000;
+export const CURSOR_BACKGROUND_SHELL_ABSOLUTE_MS = 30 * 60_000;
+export const CURSOR_BACKGROUND_SHELL_TERM_GRACE_MS = 2_000;
+
+type BackgroundShellTerminationReason = "session_close" | "idle" | "absolute" | "shutdown";
+type BackgroundShellTimer = ReturnType<typeof setTimeout>;
+
+export interface BackgroundShellTerminationReport {
+  attempted: number;
+  closed: number;
+  unresolved: number;
+  killFailures: number;
+}
+
+export interface BackgroundShellRuntime {
+  spawn: typeof spawn;
+  now(): number;
+  setTimer(callback: () => void, delayMs: number): BackgroundShellTimer;
+  clearTimer(timer: BackgroundShellTimer): void;
+  kill(child: ChildProcessWithoutNullStreams, signal?: NodeJS.Signals): boolean;
+}
+
+interface BackgroundShellEntry {
+  shellId: number;
+  sessionId: string;
+  child: ChildProcessWithoutNullStreams;
+  admissionLease: AdmissionLease;
+  outputLength: number;
+  startedAt: number;
+  lastActivityAt: number;
+  idleTimer?: BackgroundShellTimer;
+  absoluteTimer?: BackgroundShellTimer;
+  terminating: Promise<BackgroundShellTerminationReport> | null;
+  closePromise: Promise<void>;
+  confirmClose(): void;
+}
 
-const backgroundShells = new Map<number, { child: ChildProcessWithoutNullStreams; outputLength: number }>();
+const defaultBackgroundShellRuntime: BackgroundShellRuntime = {
+  spawn,
+  now: () => Date.now(),
+  setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimer: timer => clearTimeout(timer),
+  kill: (child, signal) => child.kill(signal),
+};
+
+let backgroundShellRuntime = defaultBackgroundShellRuntime;
+let backgroundShellGate = createAdmissionGate("cursor_background_shells", CURSOR_BACKGROUND_SHELL_MAX_LIVE);
+const backgroundShells = new Map<number, BackgroundShellEntry>();
 let nextShellId = 1;
+let backgroundShellShutdownStarted = false;
+let idleTerminations = 0;
+let absoluteTerminations = 0;
+let unresolvedKills = 0;
+let killFailures = 0;
 
 /** Rejection text when Cursor-native shell is denied by policy (issue #604). */
 export function nativeShellDisabledMessage(): string {
@@ -212,23 +270,242 @@ export function rejectBackgroundShellSpawnExecForPolicy(execMsg: ExecServerMessa
   }));
 }
 
-export function backgroundShellSpawnExec(execMsg: ExecServerMessage): Uint8Array {
+function backgroundShellSpawnError(
+  execMsg: ExecServerMessage,
+  command: string,
+  workingDirectory: string,
+  error: string,
+): Uint8Array {
+  return execBytes(execMsg, "backgroundShellSpawnResult", create(BackgroundShellSpawnResultSchema, {
+    result: {
+      case: "error",
+      value: create(BackgroundShellSpawnErrorSchema, { command, workingDirectory, error }),
+    },
+  }));
+}
+
+function clearBackgroundShellTimers(entry: BackgroundShellEntry): void {
+  if (entry.idleTimer) backgroundShellRuntime.clearTimer(entry.idleTimer);
+  if (entry.absoluteTimer) backgroundShellRuntime.clearTimer(entry.absoluteTimer);
+  entry.idleTimer = undefined;
+  entry.absoluteTimer = undefined;
+}
+
+function confirmBackgroundShellClose(entry: BackgroundShellEntry): void {
+  if (backgroundShells.get(entry.shellId) !== entry) return;
+  clearBackgroundShellTimers(entry);
+  backgroundShells.delete(entry.shellId);
+  entry.admissionLease.release();
+  entry.confirmClose();
+}
+
+function unrefTimer(timer: BackgroundShellTimer): void {
+  timer.unref?.();
+}
+
+function armBackgroundShellIdleTimer(entry: BackgroundShellEntry): void {
+  if (entry.idleTimer) backgroundShellRuntime.clearTimer(entry.idleTimer);
+  entry.idleTimer = backgroundShellRuntime.setTimer(() => {
+    entry.idleTimer = undefined;
+    void terminateBackgroundShell(entry, "idle");
+  }, CURSOR_BACKGROUND_SHELL_IDLE_MS);
+  unrefTimer(entry.idleTimer);
+}
+
+function armBackgroundShellAbsoluteTimer(entry: BackgroundShellEntry): void {
+  entry.absoluteTimer = backgroundShellRuntime.setTimer(() => {
+    entry.absoluteTimer = undefined;
+    void terminateBackgroundShell(entry, "absolute");
+  }, CURSOR_BACKGROUND_SHELL_ABSOLUTE_MS);
+  unrefTimer(entry.absoluteTimer);
+}
+
+function noteBackgroundShellActivity(entry: BackgroundShellEntry, bytes = 0): void {
+  if (backgroundShells.get(entry.shellId) !== entry) return;
+  entry.outputLength += bytes;
+  entry.lastActivityAt = backgroundShellRuntime.now();
+  // Once termination has begun the lifecycle timers are cleared for good:
+  // late pipe output must update byte accounting only, never re-arm idle,
+  // or a quarantined shell gets a fresh five-minute timer that can fire a
+  // second kill attempt and distort the lifecycle counters.
+  if (!entry.terminating) armBackgroundShellIdleTimer(entry);
+}
+
+function waitForBackgroundShellClose(entry: BackgroundShellEntry): Promise<boolean> {
+  if (backgroundShells.get(entry.shellId) !== entry) return Promise.resolve(true);
+  return new Promise(resolveWait => {
+    let settled = false;
+    // Deliberately REF'D: this is the bounded kill-grace wait that shutdown
+    // drain awaits. Bun on Windows / under `bun test --isolate` can starve
+    // unref'd timers when a pending promise is the only other work, which
+    // would leave drainAndShutdown waiting forever (same class as oauth
+    // serializeMutation wait timers). The timer self-clears within the
+    // 2-second grace window (or earlier on close), so a ref cannot keep the
+    // process alive beyond that bound.
+    const timer = backgroundShellRuntime.setTimer(() => {
+      if (settled) return;
+      settled = true;
+      resolveWait(false);
+    }, CURSOR_BACKGROUND_SHELL_TERM_GRACE_MS);
+    void entry.closePromise.then(() => {
+      if (settled) return;
+      settled = true;
+      backgroundShellRuntime.clearTimer(timer);
+      resolveWait(true);
+    });
+  });
+}
+
+function tryKillBackgroundShell(entry: BackgroundShellEntry, signal?: NodeJS.Signals): boolean {
+  try {
+    return backgroundShellRuntime.kill(entry.child, signal);
+  } catch {
+    return false;
+  }
+}
+
+async function terminateBackgroundShell(
+  entry: BackgroundShellEntry,
+  reason: BackgroundShellTerminationReason,
+): Promise<BackgroundShellTerminationReport> {
+  if (entry.terminating) return entry.terminating;
+  if (backgroundShells.get(entry.shellId) !== entry) {
+    return { attempted: 0, closed: 0, unresolved: 0, killFailures: 0 };
+  }
+  if (reason === "idle") idleTerminations += 1;
+  if (reason === "absolute") absoluteTerminations += 1;
+  entry.terminating = (async () => {
+    clearBackgroundShellTimers(entry);
+    try { entry.child.stdin.end(); } catch { /* best-effort direct-child shutdown */ }
+    try { entry.child.stdout.resume(); } catch { /* keep draining when supported */ }
+    try { entry.child.stderr.resume(); } catch { /* keep draining when supported */ }
+
+    let attemptKillFailures = 0;
+    if (!tryKillBackgroundShell(entry)) attemptKillFailures += 1;
+    let closed = await waitForBackgroundShellClose(entry);
+    if (!closed && backgroundShells.get(entry.shellId) !== entry) closed = true;
+    if (!closed) {
+      if (!tryKillBackgroundShell(entry, "SIGKILL")) attemptKillFailures += 1;
+      closed = await waitForBackgroundShellClose(entry);
+      if (!closed && backgroundShells.get(entry.shellId) !== entry) closed = true;
+    }
+    killFailures += attemptKillFailures;
+    if (!closed) unresolvedKills += 1;
+    return {
+      attempted: 1,
+      closed: closed ? 1 : 0,
+      unresolved: closed ? 0 : 1,
+      killFailures: attemptKillFailures,
+    };
+  })();
+  try {
+    return await entry.terminating;
+  } finally {
+    if (backgroundShells.get(entry.shellId) === entry) entry.terminating = null;
+  }
+}
+
+function sumTerminationReports(reports: readonly BackgroundShellTerminationReport[]): BackgroundShellTerminationReport {
+  return reports.reduce((total, report) => ({
+    attempted: total.attempted + report.attempted,
+    closed: total.closed + report.closed,
+    unresolved: total.unresolved + report.unresolved,
+    killFailures: total.killFailures + report.killFailures,
+  }), { attempted: 0, closed: 0, unresolved: 0, killFailures: 0 });
+}
+
+export function beginBackgroundShellShutdown(): void {
+  backgroundShellShutdownStarted = true;
+}
+
+export function backgroundShellAdmissionMetrics(): Readonly<AdmissionMetrics> {
+  return backgroundShellGate.metrics();
+}
+
+export function backgroundShellLifecycleMetrics(): {
+  idleTerminations: number;
+  absoluteTerminations: number;
+  unresolvedKills: number;
+  killFailures: number;
+} {
+  return { idleTerminations, absoluteTerminations, unresolvedKills, killFailures };
+}
+
+export async function terminateBackgroundShellsForSession(
+  sessionId: string,
+): Promise<BackgroundShellTerminationReport> {
+  const owned = [...backgroundShells.values()].filter(entry => entry.sessionId === sessionId);
+  return sumTerminationReports(await Promise.all(owned.map(entry => terminateBackgroundShell(entry, "session_close"))));
+}
+
+export async function terminateAllBackgroundShells(): Promise<BackgroundShellTerminationReport> {
+  const entries = [...backgroundShells.values()];
+  return sumTerminationReports(await Promise.all(entries.map(entry => terminateBackgroundShell(entry, "shutdown"))));
+}
+
+export function setBackgroundShellRuntimeForTests(runtime: Partial<BackgroundShellRuntime>): void {
+  backgroundShellRuntime = { ...defaultBackgroundShellRuntime, ...runtime };
+}
+
+export async function resetBackgroundShellStateForTests(): Promise<void> {
+  const report = await terminateAllBackgroundShells();
+  if (report.unresolved !== 0 || backgroundShells.size !== 0 || backgroundShellGate.metrics().active !== 0) {
+    throw new Error("cannot reset background shell state before every direct child confirms close");
+  }
+  backgroundShellRuntime = defaultBackgroundShellRuntime;
+  backgroundShellGate = createAdmissionGate("cursor_background_shells", CURSOR_BACKGROUND_SHELL_MAX_LIVE);
+  nextShellId = 1;
+  backgroundShellShutdownStarted = false;
+  idleTerminations = 0;
+  absoluteTerminations = 0;
+  unresolvedKills = 0;
+  killFailures = 0;
+}
+
+export function backgroundShellSpawnExec(execMsg: ExecServerMessage, sessionId: string): Uint8Array {
   if (execMsg.message.case !== "backgroundShellSpawnArgs") throw new Error("invalid background shell exec");
   const args = execMsg.message.value;
   const cwd = resolve(args.workingDirectory || process.cwd());
+  if (!sessionId) return backgroundShellSpawnError(execMsg, args.command, cwd, "background shell session owner required");
+  if (backgroundShellShutdownStarted) return backgroundShellSpawnError(execMsg, args.command, cwd, "background shell shutdown in progress");
+  const admissionLease = backgroundShellGate.tryAcquire();
+  if (!admissionLease) return backgroundShellSpawnError(execMsg, args.command, cwd, "background shell limit reached");
+  let child: ChildProcessWithoutNullStreams;
   try {
-    const child = spawn(args.command, { cwd, shell: true });
-    const shellId = nextShellId++;
-    backgroundShells.set(shellId, { child, outputLength: 0 });
+    child = backgroundShellRuntime.spawn(args.command, { cwd, shell: true });
+  } catch (err) {
+    admissionLease.release();
+    return backgroundShellSpawnError(execMsg, args.command, cwd, errorText(err));
+  }
+
+  const shellId = nextShellId++;
+  let confirmClose!: () => void;
+  const closePromise = new Promise<void>(resolveClose => { confirmClose = resolveClose; });
+  const now = backgroundShellRuntime.now();
+  const entry: BackgroundShellEntry = {
+    shellId,
+    sessionId,
+    child,
+    admissionLease,
+    outputLength: 0,
+    startedAt: now,
+    lastActivityAt: now,
+    terminating: null,
+    closePromise,
+    confirmClose,
+  };
+  try {
+    child.on("close", () => confirmBackgroundShellClose(entry));
+    child.on("error", () => { /* error alone never confirms direct-child termination */ });
+    backgroundShells.set(shellId, entry);
     child.stdout.on("data", chunk => {
-      const shell = backgroundShells.get(shellId);
-      if (shell) shell.outputLength += Buffer.byteLength(String(chunk));
+      noteBackgroundShellActivity(entry, Buffer.byteLength(String(chunk)));
     });
     child.stderr.on("data", chunk => {
-      const shell = backgroundShells.get(shellId);
-      if (shell) shell.outputLength += Buffer.byteLength(String(chunk));
+      noteBackgroundShellActivity(entry, Buffer.byteLength(String(chunk)));
     });
-    child.on("close", () => backgroundShells.delete(shellId));
+    armBackgroundShellIdleTimer(entry);
+    armBackgroundShellAbsoluteTimer(entry);
     return execBytes(execMsg, "backgroundShellSpawnResult", create(BackgroundShellSpawnResultSchema, {
       result: {
         case: "success",
@@ -236,9 +513,8 @@ export function backgroundShellSpawnExec(execMsg: ExecServerMessage): Uint8Array
       },
     }));
   } catch (err) {
-    return execBytes(execMsg, "backgroundShellSpawnResult", create(BackgroundShellSpawnResultSchema, {
-      result: { case: "error", value: create(BackgroundShellSpawnErrorSchema, { command: args.command, workingDirectory: cwd, error: errorText(err) }) },
-    }));
+    void terminateBackgroundShell(entry, "session_close");
+    return backgroundShellSpawnError(execMsg, args.command, cwd, errorText(err));
   }
 }
 
@@ -249,7 +525,7 @@ export function rejectWriteShellStdinExecForPolicy(execMsg: ExecServerMessage):
   }));
 }
 
-export function writeShellStdinExec(execMsg: ExecServerMessage): Uint8Array {
+export function writeShellStdinExec(execMsg: ExecServerMessage, sessionId: string): Uint8Array {
   if (execMsg.message.case !== "writeShellStdinArgs") throw new Error("invalid shell stdin exec");
   const args = execMsg.message.value;
   const shell = backgroundShells.get(args.shellId);
@@ -258,8 +534,14 @@ export function writeShellStdinExec(execMsg: ExecServerMessage): Uint8Array {
       result: { case: "error", value: create(WriteShellStdinErrorSchema, { error: `Unknown shell id ${args.shellId}` }) },
     }));
   }
+  if (shell.sessionId !== sessionId) {
+    return execBytes(execMsg, "writeShellStdinResult", create(WriteShellStdinResultSchema, {
+      result: { case: "error", value: create(WriteShellStdinErrorSchema, { error: "shell belongs to another session" }) },
+    }));
+  }
   const before = shell.outputLength;
   shell.child.stdin.write(args.chars);
+  noteBackgroundShellActivity(shell);
   return execBytes(execMsg, "writeShellStdinResult", create(WriteShellStdinResultSchema, {
     result: { case: "success", value: create(WriteShellStdinSuccessSchema, { shellId: args.shellId, terminalFileLengthBeforeInputWritten: before }) },
   }));