@yansigit/opencodex 2.31.0

package/src/lib/state-store-registrations.ts

@@ -0,0 +1,119 @@
+import {
+  getConfigDir,
+  reconcileConfigWarningMemos,
+  sweepDeadOcxStartProcessCache,
+} from "../config";
+import { reconcileCodexReauthState } from "../codex/account-runtime-state";
+import { reconcileCatalogWarningMemos } from "../codex/catalog/aggregation";
+import { reconcileProviderFetchWarnings } from "../codex/catalog/provider-fetch";
+import { reconcileModelCacheGeneration } from "../codex/model-cache";
+import { reconcilePoolRotationState } from "../codex/pool-rotation";
+import { reconcileCodexQuotaAccounts } from "../codex/quota";
+import {
+  listLiveCodexAccountIds,
+  reconcileCodexRoutingHealth,
+} from "../codex/routing";
+import { sweepExpiredSubagentModelHealth } from "../codex/subagent-model-fallback";
+import {
+  reconcileComboTargetCooldowns,
+  sweepExpiredComboTargetCooldowns,
+} from "../combos/failover";
+import { reconcileComboWarningMemos } from "../combos/request";
+import { reconcileComboRotationState } from "../combos/resolve";
+import { listLiveComboTargetKeys } from "../combos/types";
+import {
+  listLiveConfigOwnershipRoots,
+  reconcileConfigOwnershipRoots,
+} from "./config-ownership";
+import { reconcileGcpAdcTokens, sweepExpiredGcpAdcTokens } from "./gcp-adc";
+import {
+  reconcileOAuthFlowState,
+  sweepExpiredXaiPermanentFailureVerdicts,
+} from "../oauth";
+import { sweepExpiredAnthropicRoutingHealth } from "../oauth/anthropic-routing";
+import { sweepExpiredAntigravityRoutingHealth } from "../oauth/antigravity-routing";
+import { listLiveOAuthAccountKeys, reconcileOAuthReauthState } from "../oauth/store";
+import { reconcileGuardianBackoff } from "../oauth/token-guardian";
+import { sweepExpiredApiKeyCooldowns } from "../providers/key-failover";
+import { reconcileProviderRequestPacing } from "../providers/request-pacing";
+import { sweepAbandonedResponseStateTemps, sweepExpiredResponseStates } from "../responses/state";
+import { sweepExpiredAntigravityReplay } from "../adapters/google-antigravity-replay";
+import { reconcileProviderAccountQuotaRows } from "../providers/quota";
+import { reconcileRouterWarningMemos } from "../router";
+import type { OcxConfig } from "../types";
+import {
+  type GenerationContext,
+  reconcileStateGeneration,
+  registerStateStore,
+  setGenerationContextBuilder,
+  type StateStoreRegistration,
+} from "./state-store-sweeper";
+
+let liveServerConfig: OcxConfig | null = null;
+
+export function setLiveStateStoreConfig(config: OcxConfig): void {
+  liveServerConfig = config;
+}
+
+export function reconcileLiveStateStores() {
+  if (!liveServerConfig) return { storesVisited: 0, rowsRemoved: 0 };
+  return reconcileStateGeneration(buildGenerationContext());
+}
+
+export function buildGenerationContext(): GenerationContext {
+  if (!liveServerConfig) throw new Error("live server config is not installed");
+  const providerNames = new Set(Object.keys(liveServerConfig.providers));
+  return {
+    generation: 0,
+    providerNames,
+    comboIds: new Set(Object.keys(liveServerConfig.combos ?? {})),
+    comboTargets: listLiveComboTargetKeys(liveServerConfig),
+    codexAccountIds: listLiveCodexAccountIds(liveServerConfig),
+    oauthAccountKeys: listLiveOAuthAccountKeys(providerNames),
+    configRoots: listLiveConfigOwnershipRoots(getConfigDir()),
+  };
+}
+
+export const STATE_STORE_REGISTRATIONS = [
+  { name: "subagent-model-health", sweepExpired: sweepExpiredSubagentModelHealth },
+  { name: "api-key-cooldowns", sweepExpired: sweepExpiredApiKeyCooldowns },
+  { name: "provider-request-pacing", reconcileGeneration: reconcileProviderRequestPacing },
+  {
+    name: "combo-target-cooldowns",
+    sweepExpired: sweepExpiredComboTargetCooldowns,
+    reconcileGeneration: reconcileComboTargetCooldowns,
+  },
+  { name: "anthropic-routing-health", sweepExpired: sweepExpiredAnthropicRoutingHealth },
+  { name: "antigravity-routing-health", sweepExpired: sweepExpiredAntigravityRoutingHealth },
+  { name: "xai-refresh-verdicts", sweepExpired: sweepExpiredXaiPermanentFailureVerdicts },
+  {
+    name: "responses-continuation",
+    sweepExpired: sweepExpiredResponseStates,
+    // Disk reclaim rides the liveness tick, not the TTL tick: sweepExpiredOnWrite puts
+    // sweepExpired on hot write paths, where a directory scan does not belong.
+    sweepLiveness: sweepAbandonedResponseStateTemps,
+  },
+  { name: "antigravity-replay", sweepExpired: sweepExpiredAntigravityReplay },
+  { name: "config-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileConfigWarningMemos(context.generation) },
+  { name: "catalog-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileCatalogWarningMemos(context.generation) },
+  { name: "provider-fetch-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileProviderFetchWarnings(context.generation) },
+  { name: "combo-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileComboWarningMemos(context.generation) },
+  { name: "router-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileRouterWarningMemos(context.generation) },
+  { name: "codex-quota", reconcileGeneration: reconcileCodexQuotaAccounts },
+  { name: "provider-quota-history", reconcileGeneration: reconcileProviderAccountQuotaRows },
+  { name: "codex-routing-health", reconcileGeneration: reconcileCodexRoutingHealth },
+  { name: "model-cache-history", reconcileGeneration: reconcileModelCacheGeneration },
+  { name: "pool-rotation", reconcileGeneration: reconcilePoolRotationState },
+  { name: "combo-rotation", reconcileGeneration: reconcileComboRotationState },
+  { name: "guardian-backoff", reconcileGeneration: reconcileGuardianBackoff },
+  { name: "codex-reauth", reconcileGeneration: reconcileCodexReauthState },
+  { name: "oauth-reauth", reconcileGeneration: reconcileOAuthReauthState },
+  { name: "gcp-adc", sweepExpired: sweepExpiredGcpAdcTokens, reconcileGeneration: reconcileGcpAdcTokens },
+  { name: "config-ownership", reconcileGeneration: reconcileConfigOwnershipRoots },
+  { name: "oauth-flow-state", reconcileGeneration: reconcileOAuthFlowState },
+  { name: "ocx-start-process-cache", sweepLiveness: sweepDeadOcxStartProcessCache },
+] satisfies readonly StateStoreRegistration[];
+
+for (const registration of STATE_STORE_REGISTRATIONS) registerStateStore(registration);
+
+setGenerationContextBuilder(buildGenerationContext);

package/src/lib/state-store-sweeper.ts

@@ -0,0 +1,184 @@
+export const STATE_SWEEP_INTERVAL_MS = 60_000;
+
+export interface GenerationContext {
+  generation: number;
+  providerNames: ReadonlySet<string>;
+  comboIds: ReadonlySet<string>;
+  comboTargets: ReadonlySet<string>;
+  codexAccountIds: ReadonlySet<string>;
+  oauthAccountKeys: ReadonlySet<string>;
+  configRoots: ReadonlySet<string>;
+}
+
+export interface StateStoreRegistration {
+  name: string;
+  sweepExpired?: (now: number) => number;
+  sweepLiveness?: () => number;
+  reconcileGeneration?: (context: GenerationContext) => number;
+}
+
+export interface StateSweepAfterTickRegistration {
+  name: string;
+  afterTick(): void;
+}
+
+export interface StateSweepResult {
+  storesVisited: number;
+  rowsRemoved: number;
+}
+
+export interface StateStoreSweeperOptions {
+  /** Override the 60 s interval (tests only; production uses the default). */
+  intervalMs?: number;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+const registrations = new Map<string, StateStoreRegistration>();
+const afterTickRegistrations = new Map<string, StateSweepAfterTickRegistration>();
+let configGeneration = 0;
+let attemptSequence = 0;
+let generationContextBuilder: (() => GenerationContext) | null = null;
+let reconciliationRetryPending = false;
+let interval: ReturnType<typeof setInterval> | null = null;
+
+function logCallbackFailure(name: string): void {
+  console.warn(`[state-store-sweeper] ${name} failed`);
+}
+
+export function registerStateStore(registration: StateStoreRegistration): () => void {
+  registrations.set(registration.name, registration);
+  return () => {
+    if (registrations.get(registration.name) === registration) {
+      registrations.delete(registration.name);
+    }
+  };
+}
+
+export function registerStateSweepAfterTick(registration: StateSweepAfterTickRegistration): () => void {
+  afterTickRegistrations.set(registration.name, registration);
+  return () => {
+    if (afterTickRegistrations.get(registration.name) === registration) {
+      afterTickRegistrations.delete(registration.name);
+    }
+  };
+}
+
+function runCallbacks(
+  callback: (registration: StateStoreRegistration) => (() => number) | undefined,
+): StateSweepResult {
+  let storesVisited = 0;
+  let rowsRemoved = 0;
+  for (const registration of registrations.values()) {
+    const invoke = callback(registration);
+    if (!invoke) continue;
+    storesVisited += 1;
+    try {
+      rowsRemoved += invoke();
+    } catch {
+      logCallbackFailure(registration.name);
+    }
+  }
+  return { storesVisited, rowsRemoved };
+}
+
+export function sweepExpired(now = Date.now()): StateSweepResult {
+  return runCallbacks(registration => registration.sweepExpired
+    ? () => registration.sweepExpired!(now)
+    : undefined);
+}
+
+export function sweepExpiredOnWrite(now = Date.now()): StateSweepResult {
+  const result = sweepExpired(now);
+  if (reconciliationRetryPending && generationContextBuilder) {
+    try {
+      reconcileStateGeneration(generationContextBuilder());
+    } catch {
+      // The builder reads authoritative live owners. Keep the single retry pending
+      // until a later successful owner write can obtain a complete context.
+    }
+  }
+  return result;
+}
+
+export function sweepLiveness(): StateSweepResult {
+  return runCallbacks(registration => registration.sweepLiveness);
+}
+
+function runAfterTickCallbacks(): void {
+  for (const registration of afterTickRegistrations.values()) {
+    try {
+      registration.afterTick();
+    } catch {
+      logCallbackFailure(registration.name);
+    }
+  }
+}
+
+export function captureConfigGeneration(): number {
+  return configGeneration;
+}
+
+export function setGenerationContextBuilder(build: () => GenerationContext): void {
+  generationContextBuilder = build;
+}
+
+export function reconcileStateGeneration(context: GenerationContext): StateSweepResult {
+  const candidateGeneration = ++attemptSequence;
+  const candidateContext: GenerationContext = {
+    ...context,
+    generation: candidateGeneration,
+  };
+
+  let storesVisited = 0;
+  let rowsRemoved = 0;
+  let failed = false;
+  for (const registration of registrations.values()) {
+    if (!registration.reconcileGeneration) continue;
+    storesVisited += 1;
+    try {
+      rowsRemoved += registration.reconcileGeneration(candidateContext);
+    } catch {
+      failed = true;
+      logCallbackFailure(registration.name);
+    }
+  }
+  if (failed) {
+    reconciliationRetryPending = true;
+  } else {
+    configGeneration = candidateGeneration;
+    reconciliationRetryPending = false;
+  }
+  return { storesVisited, rowsRemoved };
+}
+
+export function startStateStoreSweeper(
+  options: StateStoreSweeperOptions = {},
+): { stop(): void } {
+  stopStateStoreSweeper();
+  const now = options.now ?? Date.now;
+  interval = setInterval(() => {
+    sweepExpired(now());
+    sweepLiveness();
+    runAfterTickCallbacks();
+  }, options.intervalMs ?? STATE_SWEEP_INTERVAL_MS);
+  interval.unref?.();
+  return { stop: stopStateStoreSweeper };
+}
+
+export function stopStateStoreSweeper(): void {
+  if (!interval) return;
+  clearInterval(interval);
+  interval = null;
+}
+
+/** Test-only reset for module-global registrations, generation, and lifecycle state. */
+export function resetStateStoreSweeperForTests(): void {
+  stopStateStoreSweeper();
+  registrations.clear();
+  afterTickRegistrations.clear();
+  configGeneration = 0;
+  attemptSequence = 0;
+  generationContextBuilder = null;
+  reconciliationRetryPending = false;
+}

package/src/lib/system-restart-contract.ts

@@ -0,0 +1,73 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { isLocalAttestationSecret } from "./local-management-attestation";
+
+export const SYSTEM_RESTART_METHOD = "POST";
+export const SYSTEM_RESTART_PATH = "/api/system/restart";
+export const SYSTEM_RESTART_CAPABILITY_VERSION = "v1";
+export const SYSTEM_RESTART_EXPECTED_PID_HEADER = "x-opencodex-restart-expected-pid";
+export const SYSTEM_RESTART_NONCE_HEADER = "x-opencodex-restart-nonce";
+export const SYSTEM_RESTART_CAPABILITY_HEADER = "x-opencodex-restart-capability";
+
+/** Fixed drain and replacement budgets shared by the server, CLI, and tray. */
+export const MEMORY_DRAIN_RESTART_MS = 60_000;
+export const REPLACEMENT_READY_TIMEOUT_MS = 70_000;
+
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+
+export type ExpectedSystemRestartPid =
+  | { kind: "absent" }
+  | { kind: "invalid" }
+  | { kind: "present"; pid: number };
+
+export function parseExpectedSystemRestartPid(value: string | null): ExpectedSystemRestartPid {
+  if (value === null) return { kind: "absent" };
+  if (!/^[1-9]\d*$/.test(value)) return { kind: "invalid" };
+  const pid = Number(value);
+  return Number.isSafeInteger(pid) ? { kind: "present", pid } : { kind: "invalid" };
+}
+
+function restartCapabilityPayload(
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+): string | null {
+  if (!BASE64URL_256.test(nonce)) return null;
+  if (method !== SYSTEM_RESTART_METHOD || path !== SYSTEM_RESTART_PATH) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  return `opencodex-system-restart-v1\n${nonce}\n${method}\n${path}\n${pid}\n${port}`;
+}
+
+/** Process-scoped, operation-only authorization. It is not a reusable management credential. */
+export function createSystemRestartCapability(
+  secret: string,
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+): string | null {
+  if (!isLocalAttestationSecret(secret)) return null;
+  const payload = restartCapabilityPayload(nonce, method, path, pid, port);
+  if (!payload) return null;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifySystemRestartCapability(
+  secret: string,
+  nonce: string | null,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  capability: string | null,
+): boolean {
+  if (!nonce || !capability || !BASE64URL_256.test(capability)) return false;
+  const expected = createSystemRestartCapability(secret, nonce, method, path, pid, port);
+  if (!expected) return false;
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(capability);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+}

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,86 @@
+/**
+ * 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;
+}
+
+/**
+ * Cap an estimated token count at a model's context window (codex-router PR #140).
+ *
+ * A request the provider answered cannot have exceeded the window, so the estimate is never
+ * allowed to claim it did: the estimate only ever substitutes a reported-zero (or missing)
+ * input count, and a value above the window would be provably false. Positive or missing
+ * reported counts are never rewritten here — this bounds the heuristic estimate itself.
+ * Non-positive or non-integer windows (unknown model) leave the estimate untouched.
+ */
+export function capEstimateAtContextWindow(estimate: number, contextWindow: number | undefined): number {
+  return typeof contextWindow === "number" && Number.isInteger(contextWindow) && contextWindow > 0
+    ? Math.min(estimate, contextWindow)
+    : estimate;
+}
+
+/**
+ * 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.
+ * When `contextWindow` is a positive integer the estimate is capped at it: a request the
+ * provider answered cannot have exceeded the window, so the estimate must not claim it did.
+ */
+export function estimateTokens(text: string, modelId?: string, contextWindow?: number): 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 capEstimateAtContextWindow(Math.max(1, Math.ceil(len / ratio)), contextWindow);
+}