@iislee/opencodex 2.11.0

package/src/lib/test-home-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * Fail-closed protection for the user's REAL OpenCodex home while tests run.
+ *
+ * A management-route unit test once passed an in-memory fixture config to a handler
+ * that persisted it through the process-global writer, replacing a live 41KB,
+ * ten-provider `~/.opencodex/config.json` with an 874-byte fixture on a real machine.
+ * Credentials survived only because the store files are separate; the providers were
+ * recoverable only because an unrelated backup snapshot happened to exist.
+ * (devlog `_plan/260730_codex_rs_upstream_v2_live_handoff/070`.)
+ *
+ * Two properties matter more than breadth here:
+ *
+ * 1. It must be INERT in production. Guessing "am I a test?" from ecosystem variables
+ *    like NODE_ENV would brick `NODE_ENV=test ocx ...` for a user who did nothing
+ *    wrong — worse than the bug it prevents. Arming requires OCX_TEST_HOME_GUARD=1,
+ *    which only this repository's test preload sets.
+ * 2. It must fail CLOSED for code nobody has written yet. So it denies ONE path — the
+ *    captured production home — instead of allow-listing known-good test directories.
+ *    An allowlist would have to be opted into, and the test that forgets is exactly
+ *    how this incident happened.
+ */
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { realpathSync } from "node:fs";
+
+const GUARD_ENV = "OCX_TEST_HOME_GUARD";
+/**
+ * Set by `scripts/test.ts` to the ORIGINAL home before it hands the child a rewritten
+ * HOME. On that path `homedir()` already points at the sandbox by the time this module
+ * loads, so the true home is only knowable from this hand-off.
+ */
+const REAL_HOME_ENV = "OCX_REAL_HOME";
+
+/**
+ * Resolve symlinks so two spellings of one location compare equal — macOS hands out
+ * `/var/folders/...` whose realpath is `/private/var/folders/...` — and so a path that
+ * merely *points* at the protected home cannot slip past a string comparison. A path
+ * that does not exist yet canonicalizes through its nearest existing ancestor, which is
+ * the common case for a config file about to be created.
+ */
+function canonicalize(path: string): string {
+  let current = resolve(path);
+  const unresolved: string[] = [];
+  for (;;) {
+    try {
+      return join(realpathSync.native(current), ...unresolved.reverse());
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return resolve(path);
+      unresolved.push(current.slice(parent.length + 1));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Captured ONCE at module load, before any harness replaces HOME/USERPROFILE. Reading
+ * `homedir()` later would return the sandbox and leave the real home unprotected — the
+ * guard would be perfectly inverted while its tests still looked green.
+ */
+const PROTECTED_HOME = canonicalize(
+  join(process.env[REAL_HOME_ENV]?.trim() || homedir(), ".opencodex"),
+);
+
+/** The production home this process protects. Exported for the guard's own tests. */
+export function protectedHomeForTests(): string {
+  return PROTECTED_HOME;
+}
+
+export function isTestHomeGuardArmed(): boolean {
+  return process.env[GUARD_ENV] === "1";
+}
+
+/**
+ * Throw when an armed test process is about to write the real OpenCodex home.
+ *
+ * Call FIRST inside a writer, before any mkdir/chmod/write, so a rejected write leaves
+ * nothing behind. Silent no-op when disarmed (production) or when `dir` is any other
+ * location, including a suite's own `mkdtemp` fixture — no registration required, which
+ * is what keeps the 54 existing suites that write config working untouched.
+ */
+export function assertNotRealHomeUnderTest(dir: string): void {
+  if (!isTestHomeGuardArmed()) return;
+  if (canonicalize(dir) !== PROTECTED_HOME) return;
+  throw new Error(
+    `refusing to write the real OpenCodex home (${PROTECTED_HOME}) from a test process. `
+    + "Point OPENCODEX_HOME at a temp directory for this test, or inject persistence "
+    + "instead of calling the global writer (see devlog 260730_codex_rs_upstream_v2_live_handoff/070).",
+  );
+}

package/src/lib/token-estimate.ts

@@ -0,0 +1,69 @@
+/**
+ * Heuristic token-estimation sidecar.
+ *
+ * Some providers (notably kiro / CodeWhisperer) return no token usage in their stream, so Codex's
+ * usage display and auto-compact (which read response.completed.usage) never engage. This module
+ * provides a cheap, dependency-free char-based estimate to fill that gap.
+ *
+ * Grounding (web): 1 token ~= 4 chars for English prose; empirical model ratios are ~Claude 3.5,
+ * ~GPT 3.6, ~Gemini 3.8 chars/token (within ~10%). Code / JSON / tool-args (the dominant Codex
+ * traffic) pack MORE tokens per char, so a lower chars-per-token ratio is used for those models.
+ * Over-counting fails safe (auto-compact fires earlier); under-counting risks context overflow.
+ */
+
+/** Generic English-prose fallback ratio (chars per token). */
+const DEFAULT_CHARS_PER_TOKEN = 4;
+
+/**
+ * Kiro routes code/JSON-heavy agent traffic whose true ratio is ~3.0-3.3 chars/token. 3.5 keeps a
+ * small safety margin (slight over-count) without wildly inflating; tune toward 3.3 if overflow is
+ * ever observed. All kiro models are text LLMs, so a single ratio applies to the whole family.
+ */
+const KIRO_CHARS_PER_TOKEN = 3.5;
+
+const KIRO_MODEL_PREFIXES = ["kiro", "claude", "deepseek", "minimax", "glm", "qwen"];
+
+/** Model-aware chars-per-token ratio. Unknown models fall back to the generic English ratio. */
+export function charsPerToken(modelId?: string): number {
+  if (!modelId) return DEFAULT_CHARS_PER_TOKEN;
+  const id = modelId.toLowerCase();
+  if (KIRO_MODEL_PREFIXES.some(p => id.startsWith(p))) return KIRO_CHARS_PER_TOKEN;
+  return DEFAULT_CHARS_PER_TOKEN;
+}
+
+/**
+ * CJK-aware ratio (devlog 260712 B3, audit R2#7): Korean/Chinese/Japanese text packs
+ * roughly one token per 1.5-3 chars, so a CJK-heavy blob estimated at English ratios
+ * badly undercounts. When >30% of chars are CJK, clamp DOWN to 2.5 chars/token —
+ * `min(model ratio, 2.5)` so per-model ratios (Claude 3.5, Kiro family) never rise.
+ */
+const CJK_CHARS_PER_TOKEN = 2.5;
+const CJK_RATIO_THRESHOLD = 0.3;
+// Hangul syllables/jamo, CJK unified ideographs (+ext A), hiragana/katakana.
+const CJK_RE = /[\uAC00-\uD7A3\u1100-\u11FF\u3130-\u318F\u4E00-\u9FFF\u3400-\u4DBF\u3040-\u30FF]/;
+
+function cjkRatio(text: string): number {
+  if (text.length === 0) return 0;
+  // Sample long blobs for O(1) cost: every char up to 2k, then a stride.
+  const stride = text.length > 2048 ? Math.ceil(text.length / 2048) : 1;
+  let cjk = 0;
+  let sampled = 0;
+  for (let i = 0; i < text.length; i += stride) {
+    sampled++;
+    if (CJK_RE.test(text[i]!)) cjk++;
+  }
+  return sampled === 0 ? 0 : cjk / sampled;
+}
+
+/**
+ * Estimate the token count of a text blob. Pure and deterministic.
+ * Returns 0 for empty/whitespace-free-empty input; otherwise ceil(length / ratio), min 1.
+ */
+export function estimateTokens(text: string, modelId?: string): number {
+  if (!text) return 0;
+  const len = text.length;
+  if (len === 0) return 0;
+  let ratio = charsPerToken(modelId);
+  if (cjkRatio(text) > CJK_RATIO_THRESHOLD) ratio = Math.min(ratio, CJK_CHARS_PER_TOKEN);
+  return Math.max(1, Math.ceil(len / ratio));
+}

package/src/lib/translator-budget.ts

@@ -0,0 +1,356 @@
+export const TRANSLATOR_MAX_CALL_ARGUMENT_BYTES = 2 * 1024 * 1024;
+export const TRANSLATOR_MAX_TURN_BYTES = 32 * 1024 * 1024;
+export const TRANSLATOR_MAX_SSE_EVENT_BYTES = 32 * 1024 * 1024;
+export const CURSOR_MAX_CONNECT_FRAME_BYTES = 32 * 1024 * 1024;
+export const CURSOR_MAX_EFFECTIVE_CONNECT_PAYLOAD_BYTES = 16 * 1024 * 1024;
+export const CURSOR_TRANSPORT_MAX_BUFFERED_BYTES = 32 * 1024 * 1024;
+export const CURSOR_TRANSPORT_RESUME_BYTES = 16 * 1024 * 1024;
+export const CURSOR_MAX_PENDING_FRAMES = 1024;
+export const CURSOR_PENDING_FRAMES_RESUME = 512;
+export const MAX_PENDING_IMAGE_FULFILLMENTS = 64;
+export const MAX_PENDING_OAUTH_MUTATIONS = 128;
+
+export type TranslatorBufferKind =
+  | "tool_args"
+  | "retained_collectors"
+  | "live_transient"
+  | "reasoning"
+  | "item_ids"
+  | "tool_search_sources"
+  | "cursor_transport"
+  | "cursor_kv"
+  | "request_copies";
+
+export type ExternallyCappedKind = "passthrough_serialization" | "mcp_payload";
+
+export class TranslatorBudgetExceededError extends Error {
+  readonly code = "translation_buffer_limit";
+
+  constructor(readonly kind: TranslatorBufferKind, readonly limitBytes: number) {
+    super(`translator ${kind} buffer exceeded ${limitBytes} bytes`);
+    this.name = "TranslatorBudgetExceededError";
+  }
+}
+
+export function isTranslatorBudgetExceededError(error: unknown): error is TranslatorBudgetExceededError {
+  return error instanceof TranslatorBudgetExceededError
+    || (error instanceof Error && (error as { code?: unknown }).code === "translation_buffer_limit");
+}
+
+export interface TranslatorBudgetSnapshot {
+  currentBytes: number;
+  highWaterBytes: number;
+  activeCalls: number;
+  overflows: number;
+}
+
+export interface TranslatorBudgetOptions {
+  maxCallArgumentBytes?: number;
+  maxTurnBytes?: number;
+}
+
+export interface TranslatorTransientReservation {
+  commitRetained(): void;
+  release(): void;
+}
+
+export interface TranslatorBudget {
+  openCall(id: string): void;
+  closeCall(id: string): void;
+  reserveTransient(
+    bytes: number,
+    scope: { kind: TranslatorBufferKind; callId?: string },
+  ): TranslatorTransientReservation;
+  chargeRetained(delta: number, scope: { kind: TranslatorBufferKind; callId?: string }): void;
+  releaseRetained(bytes: number, scope: { kind: TranslatorBufferKind; callId?: string }): void;
+  observeAcceptedRequestCopy(bytes: number): () => void;
+  observeExternallyCapped(kind: ExternallyCappedKind, bytes: number): () => void;
+  snapshot(): TranslatorBudgetSnapshot;
+  dispose(): void;
+}
+
+const retainedEventOwnership = new WeakMap<object, { budget: TranslatorBudget; bytes: number }>();
+
+/**
+ * Charge a materialized adapter-event batch and attach its lease to the events themselves.
+ * A copied event array (for example terminal-guard collection) preserves the event objects, so
+ * the response builder can consume each source lease immediately after its replacement lands.
+ */
+export function retainTranslatedEventBatch<T extends object>(events: T[], budget: TranslatorBudget): void {
+  if (events.length === 0) return;
+  const serialized = events.map(event => JSON.stringify(event));
+  const totalBytes = Buffer.byteLength(`[${serialized.join(",")}]`);
+  budget.chargeRetained(totalBytes, { kind: "retained_collectors" });
+  for (let index = 0; index < events.length; index++) {
+    const delimiterBytes = index === events.length - 1 ? 2 : 1;
+    retainedEventOwnership.set(events[index]!, {
+      budget,
+      bytes: Buffer.byteLength(serialized[index]!) + delimiterBytes,
+    });
+  }
+}
+
+/** Transfer one charged adapter event to the response builder's newly materialized owner. */
+export function releaseTranslatedEvent(event: object, budget: TranslatorBudget): void {
+  const ownership = retainedEventOwnership.get(event);
+  if (!ownership || ownership.budget !== budget) return;
+  retainedEventOwnership.delete(event);
+  budget.releaseRetained(ownership.bytes, { kind: "retained_collectors" });
+}
+
+const liveBudgets = new Set<Budget>();
+let aggregateCurrentBytes = 0;
+let aggregateActiveCalls = 0;
+let aggregateHighWaterBytes = 0;
+let aggregateOverflows = 0;
+
+function normalizeBytes(bytes: number): number {
+  return Number.isFinite(bytes) && bytes > 0 ? Math.floor(bytes) : 0;
+}
+
+function observeAggregate(): void {
+  aggregateHighWaterBytes = Math.max(aggregateHighWaterBytes, aggregateCurrentBytes);
+}
+
+class Budget implements TranslatorBudget {
+  private readonly calls = new Map<string, { logicalBytes: number; physicalBytes: number }>();
+  private readonly charged = new Map<TranslatorBufferKind, number>();
+  private hardChargedBytes = 0;
+  private observedBytes = 0;
+  private currentBytes = 0;
+  private highWaterBytes = 0;
+  private overflowCount = 0;
+  private disposed = false;
+
+  constructor(
+    private readonly maxCallArgumentBytes: number,
+    private readonly maxTurnBytes: number,
+  ) {}
+
+  private chargedBytes(): number {
+    return this.hardChargedBytes;
+  }
+
+  observedCurrentBytes(): number {
+    return this.currentBytes;
+  }
+
+  private changed(): void {
+    const nextBytes = this.hardChargedBytes + this.observedBytes;
+    aggregateCurrentBytes += nextBytes - this.currentBytes;
+    this.currentBytes = nextBytes;
+    this.highWaterBytes = Math.max(this.highWaterBytes, nextBytes);
+    observeAggregate();
+  }
+
+  private reject(kind: TranslatorBufferKind, limitBytes: number): never {
+    this.overflowCount += 1;
+    aggregateOverflows += 1;
+    throw new TranslatorBudgetExceededError(kind, limitBytes);
+  }
+
+  private admit(kind: TranslatorBufferKind, bytes: number): number {
+    const admitted = normalizeBytes(bytes);
+    if (this.chargedBytes() + admitted > this.maxTurnBytes) this.reject(kind, this.maxTurnBytes);
+    return admitted;
+  }
+
+  openCall(id: string): void {
+    if (!this.calls.has(id)) {
+      this.calls.set(id, { logicalBytes: 0, physicalBytes: 0 });
+      aggregateActiveCalls += 1;
+    }
+  }
+
+  closeCall(id: string): void {
+    const call = this.calls.get(id);
+    if (!call) return;
+    this.hardChargedBytes = Math.max(0, this.hardChargedBytes - call.physicalBytes);
+    this.calls.delete(id);
+    aggregateActiveCalls = Math.max(0, aggregateActiveCalls - 1);
+    this.changed();
+  }
+
+  reserveTransient(
+    bytes: number,
+    scope: { kind: TranslatorBufferKind; callId?: string },
+  ): TranslatorTransientReservation {
+    const admitted = normalizeBytes(bytes);
+    if (scope.callId && admitted > this.maxCallArgumentBytes) {
+      this.reject("tool_args", this.maxCallArgumentBytes);
+    }
+    this.admit(scope.kind, admitted);
+    this.charged.set(scope.kind, (this.charged.get(scope.kind) ?? 0) + admitted);
+    this.hardChargedBytes += admitted;
+    this.changed();
+    let state: "reserved" | "committed" | "released" = "reserved";
+    return {
+      commitRetained: () => {
+        if (state !== "reserved") return;
+        state = "committed";
+        if (!scope.callId) return;
+        const call = this.calls.get(scope.callId) ?? { logicalBytes: 0, physicalBytes: 0 };
+        this.charged.set(scope.kind, Math.max(0, (this.charged.get(scope.kind) ?? 0) - admitted));
+        call.logicalBytes = admitted;
+        call.physicalBytes += admitted;
+        this.calls.set(scope.callId, call);
+        this.changed();
+      },
+      release: () => {
+        if (state !== "reserved") return;
+        state = "released";
+        this.charged.set(scope.kind, Math.max(0, (this.charged.get(scope.kind) ?? 0) - admitted));
+        this.hardChargedBytes = Math.max(0, this.hardChargedBytes - admitted);
+        this.changed();
+      },
+    };
+  }
+
+  chargeRetained(delta: number, scope: { kind: TranslatorBufferKind; callId?: string }): void {
+    const admitted = normalizeBytes(delta);
+    if (scope.callId) {
+      const call = this.calls.get(scope.callId) ?? { logicalBytes: 0, physicalBytes: 0 };
+      if (call.logicalBytes + admitted > this.maxCallArgumentBytes) {
+        this.reject("tool_args", this.maxCallArgumentBytes);
+      }
+      this.admit(scope.kind, admitted);
+      call.logicalBytes += admitted;
+      call.physicalBytes += admitted;
+      this.calls.set(scope.callId, call);
+    } else {
+      this.admit(scope.kind, admitted);
+      this.charged.set(scope.kind, (this.charged.get(scope.kind) ?? 0) + admitted);
+    }
+    this.hardChargedBytes += admitted;
+    this.changed();
+  }
+
+  releaseRetained(bytes: number, scope: { kind: TranslatorBufferKind; callId?: string }): void {
+    const released = normalizeBytes(bytes);
+    if (scope.callId) {
+      const call = this.calls.get(scope.callId);
+      if (call) {
+        const actual = Math.min(released, call.physicalBytes);
+        call.physicalBytes -= actual;
+        this.hardChargedBytes = Math.max(0, this.hardChargedBytes - actual);
+      }
+    } else {
+      const current = this.charged.get(scope.kind) ?? 0;
+      const actual = Math.min(released, current);
+      this.charged.set(scope.kind, current - actual);
+      this.hardChargedBytes = Math.max(0, this.hardChargedBytes - actual);
+    }
+    this.changed();
+  }
+
+  private observe(bytes: number): () => void {
+    const observed = normalizeBytes(bytes);
+    this.observedBytes += observed;
+    this.changed();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.observedBytes = Math.max(0, this.observedBytes - observed);
+      this.changed();
+    };
+  }
+
+  observeAcceptedRequestCopy(bytes: number): () => void {
+    return this.observe(bytes);
+  }
+
+  observeExternallyCapped(_kind: ExternallyCappedKind, bytes: number): () => void {
+    return this.observe(bytes);
+  }
+
+  snapshot(): TranslatorBudgetSnapshot {
+    return {
+      currentBytes: this.observedCurrentBytes(),
+      highWaterBytes: this.highWaterBytes,
+      activeCalls: this.calls.size,
+      overflows: this.overflowCount,
+    };
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    aggregateActiveCalls = Math.max(0, aggregateActiveCalls - this.calls.size);
+    aggregateCurrentBytes = Math.max(0, aggregateCurrentBytes - this.currentBytes);
+    this.calls.clear();
+    this.charged.clear();
+    this.hardChargedBytes = 0;
+    this.observedBytes = 0;
+    this.currentBytes = 0;
+    liveBudgets.delete(this);
+    observeAggregate();
+  }
+}
+
+export function createTranslatorBudget(options: TranslatorBudgetOptions = {}): TranslatorBudget {
+  const budget = new Budget(
+    options.maxCallArgumentBytes ?? TRANSLATOR_MAX_CALL_ARGUMENT_BYTES,
+    options.maxTurnBytes ?? TRANSLATOR_MAX_TURN_BYTES,
+  );
+  liveBudgets.add(budget);
+  observeAggregate();
+  return budget;
+}
+
+export function translatorObservedBufferSnapshot(): {
+  currentBytes: number;
+  highWaterBytes: number;
+  active: number;
+} {
+  return {
+    currentBytes: aggregateCurrentBytes,
+    highWaterBytes: aggregateHighWaterBytes,
+    active: aggregateActiveCalls,
+  };
+}
+
+/** Internal diagnostics used by focused tests; never registered with app-owned memory. */
+export function translatorObservedOverflowCount(): number {
+  return aggregateOverflows;
+}
+
+/** Clears process-wide translator diagnostics and disposes leaked test budgets. */
+export function resetTranslatorAggregateForTests(): void {
+  for (const budget of liveBudgets) budget.dispose();
+  aggregateCurrentBytes = 0;
+  aggregateActiveCalls = 0;
+  aggregateHighWaterBytes = 0;
+  aggregateOverflows = 0;
+}
+
+export function finalizeTranslatorBudgetResponse(response: Response, budget: TranslatorBudget): Response {
+  if (!response.body) {
+    budget.dispose();
+    return response;
+  }
+  const reader = response.body.getReader();
+  let finalized = false;
+  const finalize = () => {
+    if (finalized) return;
+    finalized = true;
+    budget.dispose();
+  };
+  return new Response(new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          finalize();
+          controller.close();
+        } else controller.enqueue(result.value);
+      } catch (error) {
+        finalize();
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      try { await reader.cancel(reason); } finally { finalize(); }
+    },
+  }), { status: response.status, statusText: response.statusText, headers: response.headers });
+}