@iislee/opencodex 2.11.0

package/src/lib/bounded-body.ts

@@ -0,0 +1,202 @@
+/** Maximum number of response-body bytes that may be retained for an error. */
+export const BOUNDED_BODY_MAX_BYTES = 65_536;
+
+/** Default wall-clock and continuous-silence deadlines. */
+export const BOUNDED_BODY_TIMEOUT_MS = 5_000;
+
+export interface BoundedBodyOptions {
+	/** Abort the read with this signal. Its reason is rethrown by identity. */
+	signal?: AbortSignal;
+	/** Total wall-clock deadline. Exposed for focused tests. */
+	totalTimeoutMs?: number;
+	/** Deadline between non-empty raw chunks. Exposed for focused tests. */
+	inactivityTimeoutMs?: number;
+}
+
+export interface BoundedBodyResult {
+	/** UTF-8 text retained from the response. Empty when the size limit was exceeded. */
+	text: string;
+	/** True when EOF was not observed. */
+	truncated: boolean;
+	/** True for either total-deadline or inactivity-deadline expiry. */
+	timedOut: boolean;
+	/** Distinguishes the wall-clock deadline from an inactivity deadline. */
+	totalTimedOut: boolean;
+	/** True only when continuous inactivity caused the timeout. */
+	inactivityTimedOut: boolean;
+	/** True when the body was observed to exceed the byte cap. */
+	oversized: boolean;
+	/** False means callers should use a status-only fallback, not `text`. */
+	displaySafe: boolean;
+}
+
+const TOTAL_TIMEOUT = Symbol("bounded body total timeout");
+const INACTIVITY_TIMEOUT = Symbol("bounded body inactivity timeout");
+
+function timeoutPromise(ms: number, value: symbol): { promise: Promise<symbol>; clear: () => void } {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const promise = new Promise<symbol>((resolve) => {
+		timer = setTimeout(() => resolve(value), Math.max(0, ms));
+	});
+	return {
+		promise,
+		clear: () => {
+			if (timer !== undefined) clearTimeout(timer);
+		},
+	};
+}
+
+function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, reason?: unknown): void {
+	// A hostile/broken stream may reject or never settle cancel(). Neither should
+	// escape as an unhandled rejection or extend this primitive's own deadline.
+	try {
+		void reader.cancel(reason).catch(() => undefined);
+	} catch {
+		// Some stream implementations throw synchronously from cancel().
+	}
+}
+
+function decodeUtf8(chunks: readonly Uint8Array[]): string {
+	const decoder = new TextDecoder();
+	let text = "";
+	for (const chunk of chunks) text += decoder.decode(chunk, { stream: true });
+	// Flush an incomplete trailing UTF-8 sequence deterministically.
+	text += decoder.decode();
+	return text;
+}
+
+/**
+ * Consume the original response body under strict memory and time bounds.
+ *
+ * This deliberately calls `getReader()` on `response.body`: it never clones or
+ * tees the response. Once an over-limit byte is observed, all retained raw data
+ * is discarded so an untrusted prefix can never become a client-facing error.
+ */
+export async function readBoundedResponseBody(
+	response: Response,
+	options: BoundedBodyOptions = {},
+): Promise<BoundedBodyResult> {
+	const signal = options.signal;
+	if (signal?.aborted) throw signal.reason;
+
+	const body = response.body;
+	if (!body) {
+		return {
+			text: "",
+			truncated: false,
+			timedOut: false,
+			totalTimedOut: false,
+			inactivityTimedOut: false,
+			oversized: false,
+			displaySafe: true,
+		};
+	}
+
+	const reader = body.getReader();
+	const chunks: Uint8Array[] = [];
+	let retainedBytes = 0;
+	let mustCancel = false;
+	let cancelReason: unknown;
+	const total = timeoutPromise(options.totalTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS, TOTAL_TIMEOUT);
+	let inactivity = timeoutPromise(
+		options.inactivityTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS,
+		INACTIVITY_TIMEOUT,
+	);
+
+	let rejectForAbort: ((reason: unknown) => void) | undefined;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		rejectForAbort = reject;
+	});
+	const onAbort = () => rejectForAbort?.(signal?.reason);
+	signal?.addEventListener("abort", onAbort, { once: true });
+	// Close the narrow race between the preflight check and listener install.
+	if (signal?.aborted) onAbort();
+
+	try {
+		while (true) {
+			// Attach a rejection handler before racing. If a deadline wins and
+			// cancellation later rejects this read, it remains observed.
+			const read = reader.read();
+			void read.catch(() => undefined);
+			const outcome = await Promise.race([read, total.promise, inactivity.promise, aborted]);
+			// Cancellation owns the body lifetime even when EOF/readability settles in
+			// the same turn. Promise.race otherwise lets array order hide the abort.
+			if (signal?.aborted) {
+				mustCancel = true;
+				cancelReason = signal.reason;
+				throw signal.reason;
+			}
+
+			if (outcome === TOTAL_TIMEOUT || outcome === INACTIVITY_TIMEOUT) {
+				mustCancel = true;
+				cancelReason = new DOMException(
+					outcome === TOTAL_TIMEOUT ? "Error body total timeout" : "Error body inactivity timeout",
+					"TimeoutError",
+				);
+				return {
+					text: decodeUtf8(chunks),
+					truncated: true,
+					timedOut: true,
+					totalTimedOut: outcome === TOTAL_TIMEOUT,
+					inactivityTimedOut: outcome === INACTIVITY_TIMEOUT,
+					oversized: false,
+					displaySafe: false,
+				};
+			}
+
+			const { value, done } = outcome as ReadableStreamReadResult<Uint8Array>;
+			if (done) {
+				return {
+					text: decodeUtf8(chunks),
+					truncated: false,
+					timedOut: false,
+					totalTimedOut: false,
+					inactivityTimedOut: false,
+					oversized: false,
+					displaySafe: true,
+				};
+			}
+
+			if (!value || value.byteLength === 0) continue;
+
+			inactivity.clear();
+			inactivity = timeoutPromise(
+				options.inactivityTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS,
+				INACTIVITY_TIMEOUT,
+			);
+
+			if (value.byteLength > BOUNDED_BODY_MAX_BYTES - retainedBytes) {
+				mustCancel = true;
+				cancelReason = new DOMException("Error body size limit reached", "QuotaExceededError");
+				chunks.length = 0;
+				retainedBytes = 0;
+				return {
+					text: "",
+					truncated: true,
+					timedOut: false,
+					totalTimedOut: false,
+					inactivityTimedOut: false,
+					oversized: true,
+					displaySafe: false,
+				};
+			}
+
+			chunks.push(value);
+			retainedBytes += value.byteLength;
+		}
+	} catch (error) {
+		mustCancel = true;
+		cancelReason = error;
+		throw error;
+	} finally {
+		total.clear();
+		inactivity.clear();
+		signal?.removeEventListener("abort", onAbort);
+		if (mustCancel) cancelWithoutWaiting(reader, cancelReason);
+		try {
+			reader.releaseLock();
+		} catch {
+			// A pending read can keep the lock briefly while cancel settles.
+		}
+	}
+}

package/src/lib/bun-binary-validator.d.mts

@@ -0,0 +1,3 @@
+export declare const REAL_BUN_MIN_BYTES: number;
+
+export declare function isRealBunBinary(path: string): boolean;

package/src/lib/bun-binary-validator.mjs

@@ -0,0 +1,18 @@
+import { existsSync, statSync } from "node:fs";
+
+// The `bun` package leaves a tiny ASCII placeholder at bin/bun.exe until its
+// postinstall downloads the real ~60MB binary. Keep the threshold and the
+// false-on-filesystem-error contract shared by the Node launcher and Bun code.
+export const REAL_BUN_MIN_BYTES = 1_000_000;
+
+/**
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isRealBunBinary(path) {
+  try {
+    return existsSync(path) && statSync(path).size >= REAL_BUN_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}

package/src/lib/bun-runtime.ts

@@ -0,0 +1,71 @@
+/**
+ * Bundled Bun runtime resolution.
+ *
+ * opencodex ships the Bun runtime via the `bun` npm dependency (esbuild-style:
+ * a tiny main package + platform-specific `@oven/bun-*` optionalDependencies,
+ * finalized by the package's own postinstall `node install.js`). The npm `bin`
+ * launcher (bin/ocx.mjs) and the durable service/shim integrations both need a
+ * stable path to that binary. This module is the single source of truth.
+ *
+ * In a from-source dev checkout the `bun` dependency may be absent; callers fall
+ * back to `process.execPath` (which is itself Bun when run via `bun src/cli/index.ts`).
+ */
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { isRealBunBinary } from "./bun-binary-validator.mjs";
+
+export { isRealBunBinary };
+
+const require = createRequire(import.meta.url);
+
+const BUN_OVERRIDE_ENV = "OPENCODEX_BUN_PATH";
+
+export type DurableBunRuntime = {
+  path: string;
+  source: "override" | "bundled" | "process";
+  overrideEnv: typeof BUN_OVERRIDE_ENV;
+};
+
+/**
+ * Absolute path to the bundled Bun binary, or null if the `bun` dependency is
+ * not installed/resolvable (or only the un-downloaded placeholder is present).
+ * The npm `bun` package ships the binary as `bin/bun.exe` on every platform;
+ * we also probe `bin/bun` for forward compatibility.
+ */
+export function bundledBunPath(): string | null {
+  try {
+    const bunDir = dirname(require.resolve("bun/package.json"));
+    for (const name of ["bun.exe", "bun"]) {
+      const p = join(bunDir, "bin", name);
+      if (isRealBunBinary(p)) return p;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function overrideBunPath(): string | null {
+  const value = process.env[BUN_OVERRIDE_ENV]?.trim();
+  if (!value) return null;
+  const resolved = resolve(value);
+  return isRealBunBinary(resolved) ? resolved : null;
+}
+
+export function durableBunRuntime(): DurableBunRuntime {
+  const override = overrideBunPath();
+  if (override) return { path: override, source: "override", overrideEnv: BUN_OVERRIDE_ENV };
+  const bundled = bundledBunPath();
+  if (bundled) return { path: bundled, source: "bundled", overrideEnv: BUN_OVERRIDE_ENV };
+  return { path: process.execPath, source: "process", overrideEnv: BUN_OVERRIDE_ENV };
+}
+
+/**
+ * Bun path to bake into durable artifacts (launchd/systemd/Task Scheduler and
+ * the Codex auto-start shim). Prefer the bundled binary — it lives under the
+ * npm global prefix and survives across `ocx update` — and fall back to the
+ * current runtime, which is Bun when launched normally.
+ */
+export function durableBunPath(): string {
+  return durableBunRuntime().path;
+}

package/src/lib/bun-stream-caps.ts

@@ -0,0 +1,126 @@
+/**
+ * Bun runtime stream-capability gate for eager SSE passthrough (#314).
+ *
+ * The eager bounded relay (src/server/relay-eager.ts) uses a JS async producer
+ * loop — the exact shape of the Bun#32111 use-after-free (fixed upstream by Bun
+ * PR #32120, merged 2026-06-21). No RELEASED Bun version is proven to carry
+ * that fix yet, so `MIN_FIXED_BUN_VERSION` is null: every runtime is
+ * "known-bad" until a bundle-bump commit sets it. Windows no-rewrite traffic
+ * follows this runtime/config decision. Darwin no-rewrite traffic stays on tee
+ * for `auto` regardless of runtime capability and reaches eager relay only via
+ * explicit `streamMode: "eager-relay"` opt-in (see
+ * devlog/_plan/260731_macos_rss_retention/100_darwin_eager_optin.md).
+ *
+ * Prerelease conservatism: a version carrying a prerelease suffix (e.g.
+ * `1.4.0-canary.3`) is NEVER treated as fixed even when its numeric triple
+ * reaches the threshold — canaries are exactly the OPENCODEX_BUN_PATH audience
+ * and may predate the fix commit.
+ */
+
+/**
+ * Bump in the SAME commit that bumps package.json's bundled Bun to a version
+ * verified to include Bun PR #32120. null = no released version is known-fixed.
+ */
+export const MIN_FIXED_BUN_VERSION: string | null = null;
+
+export type StreamMode = "auto" | "legacy-tee" | "eager-relay";
+
+export const STREAM_MODES: readonly StreamMode[] = ["auto", "legacy-tee", "eager-relay"];
+
+export function isStreamMode(value: unknown): value is StreamMode {
+  return typeof value === "string" && (STREAM_MODES as readonly string[]).includes(value);
+}
+
+/** Numeric [major, minor, patch] triple, or null for unparseable input. */
+export function parseBunVersion(version: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/** Compare two version strings numerically; null when either is unparseable. */
+export function compareBunVersions(a: string, b: string): number | null {
+  const pa = parseBunVersion(a);
+  const pb = parseBunVersion(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i]! !== pb[i]!) return pa[i]! - pb[i]!;
+  }
+  return 0;
+}
+
+function hasPrereleaseSuffix(version: string): boolean {
+  return /^\d+\.\d+\.\d+-/.test(version.trim());
+}
+
+/**
+ * True only when `version` is proven to carry the Bun#32120 async-pull cancel
+ * fix. Conservative: unknown, unparseable, prerelease, or no threshold → false.
+ */
+export function bunHasAsyncPullCancelFix(
+  version: string,
+  minFixed: string | null = MIN_FIXED_BUN_VERSION,
+): boolean {
+  if (!minFixed) return false;
+  if (hasPrereleaseSuffix(version)) return false;
+  const cmp = compareBunVersions(version, minFixed);
+  return cmp !== null && cmp >= 0;
+}
+
+export type EagerRelayDecision = {
+  useEagerRelay: boolean;
+  reason: "config-legacy" | "config-eager" | "auto-fixed-runtime" | "auto-known-bad";
+};
+
+/**
+ * Decide the runtime/config SSE client-path capability. `version`/`minFixed`
+ * are injectable for tests; `selectEagerPath` applies platform policy.
+ */
+export function decideEagerRelay(
+  mode: StreamMode,
+  version: string = Bun.version,
+  minFixed: string | null = MIN_FIXED_BUN_VERSION,
+): EagerRelayDecision {
+  if (mode === "legacy-tee") return { useEagerRelay: false, reason: "config-legacy" };
+  if (mode === "eager-relay") return { useEagerRelay: true, reason: "config-eager" };
+  return bunHasAsyncPullCancelFix(version, minFixed)
+    ? { useEagerRelay: true, reason: "auto-fixed-runtime" }
+    : { useEagerRelay: false, reason: "auto-known-bad" };
+}
+
+/**
+ * Apply the two-platform eager-relay policy to the runtime/config capability.
+ * Windows preserves the decision for no-rewrite traffic. Darwin permits only
+ * explicit config opt-in; `auto` remains tee even on a future fixed runtime.
+ * Returns the normalized effective decision, or null when platform policy,
+ * rewrite needs, or a Darwin non-config-eager mode selects tee.
+ */
+export function selectEagerPath(
+  platform: NodeJS.Platform,
+  needsClientRewrite: boolean,
+  mode: StreamMode,
+  version: string = Bun.version,
+  minFixed: string | null = MIN_FIXED_BUN_VERSION,
+): EagerRelayDecision | null {
+  if (needsClientRewrite || (platform !== "win32" && platform !== "darwin")) {
+    return null;
+  }
+
+  const decision = decideEagerRelay(mode, version, minFixed);
+  if (platform === "win32") return decision;
+  return decision.reason === "config-eager" ? decision : null;
+}
+
+/**
+ * #864 transport gate: win32 traffic that needs a client payload rewrite must
+ * use the eager single reader with the rewrite applied inline, because the
+ * alternative tee()+JS-pull chain is the Bun#32111-unsafe path that loses the
+ * terminal SSE block on Windows. Independent of the version-based eager
+ * policy: the pull chain is unsafe on the AFFECTED runtimes by definition.
+ */
+export function isWin32EagerRewrite(
+  platform: NodeJS.Platform,
+  needsClientRewrite: boolean,
+): boolean {
+  return platform === "win32" && needsClientRewrite;
+}