@bitkyc08/opencodex 2.7.8 → 2.7.9-preview.20260712

package/src/lib/debug-settings.ts

@@ -4,6 +4,8 @@
  * Usage capture: `ocx debug usage on|off|status|reset|logs [-f]` (or OPENCODEX_USAGE_DEBUG=1).
  * Injection log: `ocx debug injection on|off|status|reset` (or OCX_INJECTION_DEBUG=1) —
  * multi-agent guidance-injection console lines, default OFF.
+ * Claude inbound capture: `ocx debug claude on|off|status|reset` (or OCX_CLAUDE_DEBUG=1) —
+ * allowlist-scalar ring of inbound Anthropic request metadata, default OFF.
  * `/api/debug` and `ocx debug` override env defaults without restart.
  */
 
@@ -11,6 +13,7 @@ export const DEBUG_ENV = {
   debug: "OCX_DEBUG",
   usage: "OPENCODEX_USAGE_DEBUG",
   injection: "OCX_INJECTION_DEBUG",
+  claude: "OCX_CLAUDE_DEBUG",
 } as const;
 
 /** Legacy env var that still enables provider debug logging. */
@@ -22,6 +25,7 @@ export interface DebugSettingsView {
   enabled: boolean;
   usage: boolean;
   injection: boolean;
+  claude: boolean;
   runtimeOverride: Partial<Record<DebugFlag, boolean>>;
   env: Record<DebugFlag, boolean>;
 }
@@ -57,22 +61,30 @@ export function isInjectionDebugEnabled(): boolean {
   return envFlag(DEBUG_ENV.injection);
 }
 
+/** Claude inbound request capture (default OFF; GUI toggle / API / CLI). */
+export function isClaudeDebugEnabled(): boolean {
+  if (runtimeOverride.claude !== undefined) return runtimeOverride.claude;
+  return envFlag(DEBUG_ENV.claude);
+}
+
 export function getDebugSettings(): DebugSettingsView {
   return {
     enabled: isDebugEnabled(),
     usage: isUsageDebugEnabled(),
     injection: isInjectionDebugEnabled(),
+    claude: isClaudeDebugEnabled(),
     runtimeOverride: { ...runtimeOverride },
     env: {
       debug: envFlag(DEBUG_ENV.debug) || legacyDebugEnvEnabled(),
       usage: envFlag(DEBUG_ENV.usage),
       injection: envFlag(DEBUG_ENV.injection),
+      claude: envFlag(DEBUG_ENV.claude),
     },
   };
 }
 
 export function setDebugSettings(partial: Partial<Record<DebugFlag, boolean>>): DebugSettingsView {
-  for (const key of ["debug", "usage", "injection"] as const) {
+  for (const key of ["debug", "usage", "injection", "claude"] as const) {
     if (partial[key] !== undefined) runtimeOverride[key] = partial[key];
   }
   return getDebugSettings();
@@ -84,7 +96,7 @@ export function clearDebugSetting(flag: DebugFlag): DebugSettingsView {
 }
 
 export function clearDebugSettings(): DebugSettingsView {
-  for (const key of ["debug", "usage", "injection"] as const) {
+  for (const key of ["debug", "usage", "injection", "claude"] as const) {
     delete runtimeOverride[key];
   }
   return getDebugSettings();

package/src/lib/token-estimate.ts

@@ -31,6 +31,30 @@ export function charsPerToken(modelId?: string): number {
   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.
@@ -39,5 +63,7 @@ export function estimateTokens(text: string, modelId?: string): number {
   if (!text) return 0;
   const len = text.length;
   if (len === 0) return 0;
-  return Math.max(1, Math.ceil(len / charsPerToken(modelId)));
+  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/providers/registry.ts

@@ -199,7 +199,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     authKind: "oauth",
     featured: false,
     dashboardPreset: true,
-    note: "Experimental Cursor bridge. Live transport and live model discovery are enabled after a standalone PKCE browser login via 'ocx login cursor'; native read/write/delete/shell/fetch execution stays disabled unless you set \"unsafeAllowNativeLocalExec\": true on providers.cursor in ~/.opencodex/config.json (dashboard: Providers → Cursor → Edit JSON) for a trusted local experiment.",
+    note: "Experimental Cursor bridge. Live transport and live model discovery are enabled after a standalone PKCE browser login via 'ocx login cursor'; native read/write/delete/shell/fetch execution stays disabled unless you set \"nativeLocalExec\": \"on\" (always) or \"codex-sandbox\" (only for requests declaring the Codex danger-full-access sandbox; the declaration is caller-controlled prose the proxy cannot verify, and the auth-free loopback bind admits any process on this host, including other local users — enable only where every data-plane client is trusted) — legacy \"unsafeAllowNativeLocalExec\": true still means \"on\" — on providers.cursor in ~/.opencodex/config.json (dashboard: Providers → Cursor → Edit JSON) for a trusted local experiment.",
     models: cursorModelIds(CURSOR_STATIC_MODELS),
     liveModels: true,
     defaultModel: "auto",

package/src/server/auth-cors.ts

@@ -73,7 +73,7 @@ export function corsHeaders(req?: Request, config?: OcxConfig): Record<string, s
   return {
     "Access-Control-Allow-Origin": allowOrigin,
     "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-OpenCodex-API-Key",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-OpenCodex-API-Key, X-Api-Key, Anthropic-Version, Anthropic-Beta",
     "Vary": "Origin",
   };
 }
@@ -140,7 +140,9 @@ export function isProxyAdmissionSecret(token: string, config: OcxConfig): boolea
 export function hasValidApiAuth(req: Request, config: OcxConfig): boolean {
   if (!isApiAuthRequired(config)) return true;
   const actual = req.headers.get("x-opencodex-api-key")?.trim()
-    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim()
+    // Anthropic-SDK clients (Claude Code with ANTHROPIC_API_KEY) authenticate via x-api-key.
+    || req.headers.get("x-api-key")?.trim();
   if (!actual) return false;
   return isProxyAdmissionSecret(actual, config);
 }

package/src/server/claude-messages.ts

@@ -0,0 +1,494 @@
+/**
+ * Anthropic Messages inbound (/v1/messages + /v1/messages/count_tokens) for Claude Code.
+ *
+ * Translate-and-replay (devlog/260711_claude_inbound/010): the Anthropic request is
+ * converted to a /v1/responses body and replayed through handleResponses on an
+ * internal Request, so routing/OAuth/account-pool/failover/sidecars are inherited
+ * unchanged. The Responses output (SSE or JSON) is converted back to Anthropic shape.
+ */
+import { FORWARD_HEADERS } from "../adapters/openai-responses";
+import { AnthropicRequestError, anthropicToResponsesTranslation, extractOcxRouteDirective, resolveInboundModel, type ClaudeCacheKeySource } from "../claude/inbound";
+import { stripOneMillionMarker } from "../claude/context-windows";
+import { captureClaudeInbound } from "../claude/inbound-debug";
+import {
+  anthropicErrorBody,
+  anthropicErrorResponse,
+  collectAnthropicMessage,
+  responsesJsonToAnthropicMessage,
+  responsesSseToAnthropicSse,
+} from "../claude/outbound";
+import { estimateTokens } from "../lib/token-estimate";
+import { routeModel } from "../router";
+import type { OcxConfig } from "../types";
+import { readJsonRequestBody } from "./request-decompress";
+import { addFinalRequestLog, httpStatusForTerminalStatus, type RequestLogContext, type RequestLogEntry } from "./request-log";
+import { responseWithDeferredRequestLog } from "./relay";
+import { handleResponses } from "./responses";
+
+type Rec = Record<string, unknown>;
+
+function isRec(v: unknown): v is Rec {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function claudeInboundDisabled(config: OcxConfig): Response | null {
+  if (config.claudeCode?.enabled === false) {
+    return anthropicErrorResponse(403, "Claude inbound is disabled (GUI: Claude ON toggle / config.claudeCode.enabled)", "permission_error");
+  }
+  return null;
+}
+
+async function readAnthropicBody(req: Request): Promise<unknown> {
+  try {
+    return await readJsonRequestBody(req);
+  } catch (err) {
+    throw new AnthropicRequestError(err instanceof Error && err.message ? err.message : "Invalid JSON body");
+  }
+}
+
+// ── Native Anthropic passthrough (subscription OAuth pierce) ──────────────────────
+// When Claude Code runs with ONLY ANTHROPIC_BASE_URL set (subscription mode — the
+// connectors warning stays off), it sends its OWN claude.ai OAuth Bearer to us.
+// Requests for genuine claude/anthropic models that no alias/modelMap claims are
+// forwarded VERBATIM to api.anthropic.com with the caller's credential and all
+// end-to-end headers, so betas/thinking signatures/billing identity stay native.
+// (Evidence: teamclaude --no-mitm + Vercel gateway docs, devlog 003/060.)
+
+const PASSTHROUGH_STRIP_HEADERS = new Set([
+  "connection", "keep-alive", "transfer-encoding", "upgrade", "te", "trailer",
+  "proxy-authenticate", "proxy-authorization", "host", "content-length",
+  "accept-encoding", "x-opencodex-api-key", "origin",
+]);
+
+function hasAnthropicNativeCredential(req: Request): boolean {
+  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim() ?? "";
+  const apiKey = req.headers.get("x-api-key")?.trim() ?? "";
+  return bearer.startsWith("sk-ant-") || apiKey.startsWith("sk-ant-");
+}
+
+function wantsNativePassthrough(req: Request, config: OcxConfig, model: unknown): model is string {
+  if (config.claudeCode?.nativePassthrough === false) return false;
+  if (typeof model !== "string" || !/^(claude|anthropic)/i.test(model)) return false;
+  if (!hasAnthropicNativeCredential(req)) return false;
+  // An alias or modelMap hit means the user asked for a ROUTED model: translate instead.
+  return resolveInboundModel(model, config.claudeCode) === model;
+}
+
+/** Format a 32-hex cache key as a uuid-shaped session id (version/variant nibbles forced). */
+function uuidFromHex(hex32: string): string {
+  const h = (hex32 + "0".repeat(32)).slice(0, 32);
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
+function anthropicUsageToOcx(usage: Rec | undefined): { inputTokens: number; outputTokens: number; cachedInputTokens?: number; cacheReadInputTokens?: number; cacheCreationInputTokens?: number } | undefined {
+  if (!usage) return undefined;
+  const num = (v: unknown) => typeof v === "number" ? v : 0;
+  const hasCache = usage.cache_read_input_tokens !== undefined || usage.cache_creation_input_tokens !== undefined;
+  const read = num(usage.cache_read_input_tokens);
+  const write = num(usage.cache_creation_input_tokens);
+  // Anthropic input_tokens excludes cache read/write; normalize to the canonical
+  // inclusive convention (types.ts OcxUsage / devlog 070). cached = READS only.
+  return {
+    inputTokens: num(usage.input_tokens) + read + write,
+    outputTokens: num(usage.output_tokens),
+    ...(hasCache ? {
+      cachedInputTokens: read,
+      cacheReadInputTokens: read,
+      cacheCreationInputTokens: write,
+    } : {}),
+  };
+}
+
+/** Tap an Anthropic-vocabulary SSE stream for the request log (usage + terminal). */
+function tapAnthropicSseForLog(
+  upstream: ReadableStream<Uint8Array>,
+  logCtx: RequestLogContext,
+  finalize: (status: number, meta: { closeReason: "terminal" | "client_cancel" }) => void,
+): ReadableStream<Uint8Array> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let usageAcc: Rec = {};
+  const inspect = (chunk: Uint8Array) => {
+    buffer += decoder.decode(chunk, { stream: true });
+    let sep: number;
+    while ((sep = buffer.indexOf("\n\n")) !== -1) {
+      const frame = buffer.slice(0, sep);
+      buffer = buffer.slice(sep + 2);
+      const dataLine = frame.split("\n").filter(l => l.startsWith("data: ")).map(l => l.slice(6)).join("");
+      if (!dataLine) continue;
+      let data: unknown;
+      try { data = JSON.parse(dataLine); } catch { continue; }
+      if (!isRec(data)) continue;
+      if (data.type === "message_start" && isRec(data.message) && isRec(data.message.usage)) {
+        usageAcc = { ...usageAcc, ...data.message.usage };
+      } else if (data.type === "message_delta" && isRec(data.usage)) {
+        usageAcc = { ...usageAcc, ...data.usage };
+      }
+    }
+  };
+  const reader = upstream.getReader();
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          logCtx.usage = anthropicUsageToOcx(Object.keys(usageAcc).length > 0 ? usageAcc : undefined);
+          finalize(200, { closeReason: "terminal" });
+          controller.close();
+          return;
+        }
+        inspect(value);
+        controller.enqueue(value);
+      } catch (err) {
+        finalize(200, { closeReason: "terminal" });
+        try { controller.error(err); } catch { /* torn down */ }
+      }
+    },
+    cancel(reason) {
+      finalize(499, { closeReason: "client_cancel" });
+      reader.cancel(reason).catch(() => {});
+    },
+  });
+}
+
+async function anthropicNativePassthrough(
+  req: Request,
+  config: OcxConfig,
+  logCtx: RequestLogContext,
+  logIds: { requestId: string; start: number } | undefined,
+  body: Rec,
+  pathname: string,
+): Promise<Response> {
+  const model = typeof body.model === "string" ? body.model : "unknown";
+  logCtx.model = model;
+  logCtx.provider = "anthropic-native";
+  logCtx.requestedModel = model;
+  let logged = false;
+  const finalize = (status: number, meta: { closeReason: "terminal" | "client_cancel" | "non_stream" }) => {
+    if (!logIds || logged) return;
+    logged = true;
+    addFinalRequestLog(logIds.requestId, logIds.start, logCtx, status, meta);
+  };
+
+  const base = (config.claudeCode?.anthropicBaseUrl ?? "https://api.anthropic.com").replace(/\/$/, "");
+  const search = new URL(req.url).search;
+  const headers = new Headers();
+  req.headers.forEach((value, name) => {
+    if (!PASSTHROUGH_STRIP_HEADERS.has(name.toLowerCase())) headers.set(name, value);
+  });
+  headers.set("content-type", "application/json");
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(`${base}${pathname}${search}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: req.signal,
+    });
+  } catch (err) {
+    finalize(502, { closeReason: "non_stream" });
+    return anthropicErrorResponse(502, `anthropic passthrough failed: ${err instanceof Error ? err.message : String(err)}`, "api_error");
+  }
+
+  const contentType = upstream.headers.get("content-type") ?? "application/json";
+  if (upstream.ok && contentType.includes("text/event-stream") && upstream.body) {
+    return new Response(tapAnthropicSseForLog(upstream.body, logCtx, finalize), {
+      status: upstream.status,
+      headers: {
+        "Content-Type": contentType,
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+      },
+    });
+  }
+  // Non-stream (count_tokens, errors, stream:false): relay verbatim, log on the spot.
+  const text = await upstream.text();
+  if (upstream.ok) {
+    try {
+      const parsed = JSON.parse(text) as { usage?: Rec };
+      if (isRec(parsed?.usage)) logCtx.usage = anthropicUsageToOcx(parsed.usage);
+    } catch { /* count_tokens etc. */ }
+  }
+  finalize(upstream.status, { closeReason: "non_stream" });
+  const retryAfter = upstream.headers.get("retry-after");
+  return new Response(text, {
+    status: upstream.status,
+    headers: { "Content-Type": contentType, ...(retryAfter ? { "Retry-After": retryAfter } : {}) },
+  });
+}
+
+export async function handleClaudeMessages(
+  req: Request,
+  config: OcxConfig,
+  logCtx: RequestLogContext,
+  logIds?: { requestId: string; start: number },
+): Promise<Response> {
+  logCtx.surface = "claude";
+  const disabled = claudeInboundDisabled(config);
+  if (disabled) {
+    if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, 403, { closeReason: "non_stream" });
+    return disabled;
+  }
+
+  let anthropicBody: unknown;
+  let internalBody: Rec;
+  let cacheKeySource: ClaudeCacheKeySource = null;
+  try {
+    anthropicBody = await readAnthropicBody(req);
+    // Defensive [1m] strip (devlog 138): clients normally remove the context-variant
+    // marker themselves; the 1M signal we act on is the anthropic-beta header.
+    // Case-insensitive — the CLI matches /\[1m\]/i (audit 021 #7).
+    if (isRec(anthropicBody) && typeof anthropicBody.model === "string") {
+      anthropicBody.model = stripOneMillionMarker(anthropicBody.model);
+    }
+    // ocx-route override (devlog 072): injected agent bodies pin their model via a
+    // system-prompt directive because 2.1.207 ignores custom ids in agent
+    // frontmatter. Must run BEFORE the native-passthrough branch — the CLI sends
+    // these subagent turns under a fallback claude model id.
+    if (isRec(anthropicBody)) {
+      const routeOverride = extractOcxRouteDirective(anthropicBody);
+      if (routeOverride && typeof anthropicBody.model === "string") {
+        anthropicBody.model = stripOneMillionMarker(routeOverride);
+      }
+    }
+    // Debug capture (opt-in allowlist scalars) BEFORE the passthrough branch so
+    // native, routed, and disabled-alias paths are all observable (devlog 130 B1).
+    captureClaudeInbound(
+      "messages",
+      anthropicBody,
+      isRec(anthropicBody) && typeof anthropicBody.model === "string"
+        ? resolveInboundModel(anthropicBody.model, config.claudeCode)
+        : undefined,
+      req.headers.get("anthropic-beta") ?? undefined,
+    );
+    if (isRec(anthropicBody) && wantsNativePassthrough(req, config, anthropicBody.model)) {
+      return await anthropicNativePassthrough(req, config, logCtx, logIds, anthropicBody, "/v1/messages");
+    }
+    const translation = anthropicToResponsesTranslation(anthropicBody, config.claudeCode);
+    internalBody = translation.body;
+    cacheKeySource = translation.cacheKeySource;
+  } catch (err) {
+    const status = err instanceof AnthropicRequestError ? 400 : 500;
+    if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, status, { closeReason: "non_stream" });
+    return anthropicErrorResponse(status, err instanceof Error ? err.message : String(err));
+  }
+
+  const requestedModel = (anthropicBody as Rec).model as string;
+  const stream = internalBody.stream === true;
+  // Routed adapters only support streamed turns; always stream internally and fold
+  // the translated Anthropic SSE into a message JSON for non-streaming clients.
+  internalBody.stream = true;
+
+  // Native ChatGPT passthrough (openai-responses forward) accepts only Codex-shaped
+  // bodies: it 400s on sampling params ("Unsupported parameter: max_output_tokens",
+  // verified live 2026-07-11). Strip them for that route; routed providers keep them.
+  let nativeRoute = false;
+  try {
+    const route = routeModel(config, internalBody.model as string);
+    if (route.provider.adapter === "openai-responses") {
+      nativeRoute = true;
+      delete internalBody.max_output_tokens;
+      delete internalBody.temperature;
+      delete internalBody.top_p;
+      delete internalBody.stop;
+      delete internalBody.user;
+    }
+    // Estimated-usage adapters (cursor/kiro) report no per-turn input tokens; stash a
+    // request-side estimate so the log's in:0 rows get a floor. NEVER set this for
+    // accurate-usage adapters — the request-log merge is max(reported, estimate) and
+    // would overwrite real usage (audit 133 R1#7).
+    if (route.provider.adapter === "cursor" || route.provider.adapter === "kiro") {
+      const raw = anthropicBody as Rec;
+      const parts: string[] = [];
+      if (raw.system !== undefined) parts.push(typeof raw.system === "string" ? raw.system : JSON.stringify(raw.system));
+      if (raw.messages !== undefined) parts.push(JSON.stringify(raw.messages));
+      if (raw.tools !== undefined) parts.push(JSON.stringify(raw.tools));
+      logCtx.usageLogInputTokens = Math.max(1, estimateTokens(parts.join("\n"), requestedModel));
+    }
+    // Effort safety valve (devlog 136 B6, audit 139 R2#2): opus-shaped aliases make
+    // every routed model look like a reasoning model to Claude clients, so a forced
+    // effort (CLAUDE_CODE_ALWAYS_ENABLE_EFFORT) would leak reasoning params to routes
+    // that affirmatively expose NO effort control. Strip only on a definitive [] from
+    // supportedLadderFor; unknown (undefined) passes through untouched.
+    if (internalBody.reasoning !== undefined) {
+      const { supportedLadderFor } = await import("./effort-policy");
+      const ladder = supportedLadderFor({ provider: route.provider, modelId: route.modelId });
+      if (ladder !== undefined && ladder.length === 0) delete internalBody.reasoning;
+    }
+  } catch { /* unknown model: let handleResponses shape the 404 */ }
+
+  const headers = new Headers({ "content-type": "application/json" });
+  for (const name of FORWARD_HEADERS) {
+    // The caller's bearer is the proxy admission token (ocx claude placeholder), never a
+    // ChatGPT credential — forwarding it upstream turns into {"detail":"Unauthorized"}.
+    if (name === "authorization") continue;
+    const value = req.headers.get(name);
+    if (value) headers.set(name, value);
+  }
+  if (nativeRoute) {
+    // No forwarded ChatGPT auth exists on this surface. Attach the main codex login
+    // (read-only auth.json token); account-pool rotation still overrides downstream.
+    const { getMainAccountToken } = await import("../codex/main-account");
+    const token = getMainAccountToken();
+    if (token) {
+      headers.set("authorization", `Bearer ${token.accessToken}`);
+      headers.set("chatgpt-account-id", token.chatgptAccountId);
+    }
+    // ChatGPT-backend prompt-cache affinity rides the session_id HEADER (codex
+    // clients always send their session uuid; devlog 090 follow-up: body-level
+    // prompt_cache_key alone still yielded cached_tokens:0). Claude Code never sends
+    // the header, so synthesize a stable per-session uuid from the same cache key —
+    // but ONLY for a real per-session key (metadata.user_id). The system-hash fallback
+    // key is shared across Desktop conversations, and a shared session_id's backend
+    // semantics are unproven (audit 133 R2#3): body prompt_cache_key only there.
+    if (cacheKeySource === "metadata" && !headers.has("session_id") && typeof internalBody.prompt_cache_key === "string") {
+      headers.set("session_id", uuidFromHex(internalBody.prompt_cache_key));
+    }
+  }
+  const internalReq = new Request("http://localhost/v1/responses", {
+    method: "POST",
+    headers,
+    body: JSON.stringify(internalBody),
+  });
+
+  // Request-log wiring mirrors the /v1/responses route: native passthrough finalizes
+  // via the terminal callbacks; routed streams get the Responses-vocabulary log tap
+  // BEFORE translation (the translated Anthropic stream has no response.completed
+  // frame, so tapping it records a bogus 502 with no usage/cache detail).
+  let nativeLogged = false;
+  const finalizeNativeLog = (status: number, meta: { terminalStatus?: RequestLogEntry["terminalStatus"]; closeReason: "terminal" | "client_cancel" }) => {
+    if (!logIds || nativeLogged) return;
+    nativeLogged = true;
+    addFinalRequestLog(logIds.requestId, logIds.start, logCtx, status, meta);
+  };
+  const upstream = await handleResponses(internalReq, config, logCtx, {
+    abortSignal: req.signal,
+    onNativePassthroughTerminal: status => finalizeNativeLog(httpStatusForTerminalStatus(status), { terminalStatus: status, closeReason: "terminal" }),
+    onNativePassthroughCancel: () => finalizeNativeLog(499, { closeReason: "client_cancel" }),
+  });
+  const response = logIds ? responseWithDeferredRequestLog(upstream, logIds.requestId, logIds.start, logCtx) : upstream;
+
+  if (!response.ok) {
+    // Re-shape the OpenAI-style error envelope into the Anthropic one, preserving status.
+    let message = `upstream error (${response.status})`;
+    try {
+      const text = await response.text();
+      try {
+        const parsed = JSON.parse(text) as { error?: { message?: string; type?: string } | string; message?: string };
+        const nested = typeof parsed?.error === "object" && parsed.error ? parsed.error.message : undefined;
+        const flat = typeof parsed?.error === "string" ? parsed.error : parsed?.message;
+        message = nested || flat || (text ? `upstream error (${response.status}): ${text.slice(0, 400)}` : message);
+      } catch {
+        if (text) message = `upstream error (${response.status}): ${text.slice(0, 400)}`;
+      }
+    } catch { /* keep fallback message */ }
+    const retryAfter = response.headers.get("retry-after");
+    const out = new Response(JSON.stringify(anthropicErrorBody(response.status, message)), {
+      status: response.status,
+      headers: { "Content-Type": "application/json", ...(retryAfter ? { "Retry-After": retryAfter } : {}) },
+    });
+    return out;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("text/event-stream") && response.body) {
+    const anthropicSse = responsesSseToAnthropicSse(response.body, requestedModel);
+    if (stream) {
+      return new Response(anthropicSse, {
+        status: 200,
+        headers: {
+          "Content-Type": "text/event-stream; charset=utf-8",
+          "Cache-Control": "no-cache",
+          "Connection": "keep-alive",
+        },
+      });
+    }
+    const message = await collectAnthropicMessage(anthropicSse, requestedModel);
+    const isError = (message as Rec).type === "error";
+    return new Response(JSON.stringify(message), {
+      status: isError ? 502 : 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  // Defensive: some passthrough paths may answer JSON despite stream:true.
+  let json: unknown;
+  try {
+    json = await response.json();
+  } catch {
+    return anthropicErrorResponse(502, "internal replay returned a non-JSON response", "api_error");
+  }
+  const status = (json as Rec)?.status;
+  if (status === "failed") {
+    const error = (json as { error?: { message?: string } }).error;
+    return anthropicErrorResponse(502, error?.message ?? "upstream request failed", "api_error");
+  }
+  const message = responsesJsonToAnthropicMessage(json, requestedModel);
+  if (!stream) {
+    return new Response(JSON.stringify(message), { status: 200, headers: { "Content-Type": "application/json" } });
+  }
+  // Streaming client + JSON upstream: synthesize a minimal valid Anthropic stream.
+  const encoder = new TextEncoder();
+  const frames: string[] = [];
+  const emit = (name: string, data: Rec) => frames.push(`event: ${name}\ndata: ${JSON.stringify(data)}\n\n`);
+  emit("message_start", { type: "message_start", message: { ...message, content: [], stop_reason: null, usage: { input_tokens: 0, output_tokens: 0 } } });
+  const blocks = Array.isArray((message as Rec).content) ? (message as Rec).content as Rec[] : [];
+  blocks.forEach((block, index) => {
+    emit("content_block_start", { type: "content_block_start", index, content_block: block });
+    emit("content_block_stop", { type: "content_block_stop", index });
+  });
+  emit("message_delta", { type: "message_delta", delta: { stop_reason: (message as Rec).stop_reason ?? "end_turn", stop_sequence: null }, usage: (message as Rec).usage ?? {} });
+  emit("message_stop", { type: "message_stop" });
+  return new Response(encoder.encode(frames.join("")), {
+    status: 200,
+    headers: { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-cache" },
+  });
+}
+
+/** Documented approximation: serialize system+messages+tools, run the char estimator. */
+export async function handleClaudeCountTokens(req: Request, config: OcxConfig): Promise<Response> {
+  const disabled = claudeInboundDisabled(config);
+  if (disabled) return disabled;
+
+  let body: unknown;
+  try {
+    body = await readAnthropicBody(req);
+  } catch (err) {
+    if (err instanceof AnthropicRequestError) return anthropicErrorResponse(400, err.message);
+    return anthropicErrorResponse(500, err instanceof Error ? err.message : String(err));
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return anthropicErrorResponse(400, "request body must be a JSON object");
+  }
+  const raw = body as Rec;
+  if (typeof raw.model !== "string" || raw.model.length === 0) {
+    return anthropicErrorResponse(400, "model is required");
+  }
+  let model = raw.model;
+  // Case-insensitive [1m] strip (audit 021 #7 — the CLI matches /\[1m\]/i).
+  const stripped = stripOneMillionMarker(model);
+  if (stripped !== model) {
+    model = stripped;
+    raw.model = model;
+  }
+  // ocx-route override (devlog 072): keep count_tokens consistent with messages.
+  const countRoute = extractOcxRouteDirective(raw);
+  if (countRoute) {
+    model = stripOneMillionMarker(countRoute);
+    raw.model = model;
+  }
+  captureClaudeInbound("count_tokens", raw, resolveInboundModel(model, config.claudeCode), req.headers.get("anthropic-beta") ?? undefined);
+  if (wantsNativePassthrough(req, config, model)) {
+    return await anthropicNativePassthrough(req, config, { model, provider: "anthropic-native", surface: "claude" }, undefined, raw, "/v1/messages/count_tokens");
+  }
+  const parts: string[] = [];
+  if (raw.system !== undefined) parts.push(typeof raw.system === "string" ? raw.system : JSON.stringify(raw.system));
+  if (raw.messages !== undefined) parts.push(JSON.stringify(raw.messages));
+  if (raw.tools !== undefined) parts.push(JSON.stringify(raw.tools));
+  const inputTokens = Math.max(1, estimateTokens(parts.join("\n"), model));
+  return new Response(JSON.stringify({ input_tokens: inputTokens }), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}