@bitkyc08/opencodex 2.7.7 → 2.7.9-preview.20260712

package/src/claude/context-windows.ts

@@ -0,0 +1,189 @@
+/**
+ * Claude-surface context-window map + effective model-env computation
+ * (devlog/260712_cli_context_cache/010 B2, audit R2#1/R3#1/R3#4/R4#3).
+ *
+ * The map registers EVERY selector form a Claude Code model slot might store —
+ * bare native slug, provider/id, desktop3p alias, legacy claude-ocx-* alias —
+ * with first-wins dedupe (mirrors the desktop3p registry collision policy).
+ * Values are authoritative context windows only (native override table /
+ * adapter-reported CatalogModel.contextWindow); nothing is guessed.
+ */
+import { aliasForNative, aliasForRoute } from "./alias";
+import { desktop3pAlias } from "./desktop-3p";
+import { nativeOpenAiContextWindow, type CatalogModel } from "../codex/catalog";
+
+const ONE_MILLION = 1_000_000;
+
+/** Auto-context defaults (devlog 260712 020, user-approved). */
+export const AUTO_COMPACT_WINDOW_DEFAULT = 350_000;
+export const AUTO_CONTEXT_FLOOR = 200_000;
+/** Binary-verified accepted range for CLAUDE_CODE_AUTO_COMPACT_WINDOW (2.1.207: pSo=1e5, yDs=1e6). */
+export const AUTO_COMPACT_WINDOW_MIN = 100_000;
+export const AUTO_COMPACT_WINDOW_MAX = ONE_MILLION;
+
+/** Case-insensitive [1m] marker helpers — the CLI matches /\[1m\]/i (audit 021 #7). */
+const ONE_M_MARKER_RE = /\[1m\]$/i;
+export function hasOneMillionMarker(value: string): boolean {
+  return ONE_M_MARKER_RE.test(value);
+}
+export function stripOneMillionMarker(value: string): string {
+  return value.replace(ONE_M_MARKER_RE, "");
+}
+
+export interface AutoContextMode {
+  enabled: boolean;
+  /** Effective CLAUDE_CODE_AUTO_COMPACT_WINDOW value (tokens). */
+  compactWindow: number;
+}
+
+export const AUTO_CONTEXT_OFF: AutoContextMode = { enabled: false, compactWindow: AUTO_COMPACT_WINDOW_DEFAULT };
+
+interface AutoContextConfigSlice {
+  autoContext?: boolean;
+  autoCompactWindow?: number;
+  maxContextTokens?: number;
+}
+
+function inAutoCompactRange(value: number): boolean {
+  return Number.isInteger(value) && value >= AUTO_COMPACT_WINDOW_MIN && value <= AUTO_COMPACT_WINDOW_MAX;
+}
+
+/**
+ * Resolve the auto-context mode from claudeCode config. Disabled when the user
+ * turned it off OR when the legacy maxContextTokens override is set — that pair
+ * (MAX_CONTEXT_TOKENS + DISABLE_COMPACT) takes rule-1 precedence inside the CLI,
+ * making both AUTO_COMPACT_WINDOW and [1m] accounting inert.
+ *
+ * `envOverride` is the raw CLAUDE_CODE_AUTO_COMPACT_WINDOW the USER already
+ * exported (user-wins injection keeps it): a valid value drives the marking
+ * predicate so marker and threshold never separate (audit 021 #2); an invalid
+ * value disables auto marking entirely (the CLI would ignore it, leaving marked
+ * sub-1M models without their safety net). Out-of-range CONFIG values fall back
+ * to the 350k default (the management API rejects them; this guards hand-edits).
+ */
+export function resolveAutoContext(claudeCode: AutoContextConfigSlice | undefined, envOverride?: string): AutoContextMode {
+  if (claudeCode?.autoContext === false) return AUTO_CONTEXT_OFF;
+  const maxCtx = claudeCode?.maxContextTokens;
+  if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) return AUTO_CONTEXT_OFF;
+  if (typeof envOverride === "string" && envOverride !== "") {
+    const parsed = Number(envOverride);
+    return inAutoCompactRange(parsed) ? { enabled: true, compactWindow: parsed } : AUTO_CONTEXT_OFF;
+  }
+  const raw = claudeCode?.autoCompactWindow;
+  const compactWindow = typeof raw === "number" && inAutoCompactRange(raw) ? raw : AUTO_COMPACT_WINDOW_DEFAULT;
+  return { enabled: true, compactWindow };
+}
+
+/**
+ * [1m]-marking predicate. Windows >= 1M always mark (CLI accounts exactly 1M).
+ * Auto-context additionally marks windows > 200k that can safely host the compact
+ * window — marking a model whose real window is BELOW the compact window would put
+ * the compaction safety net behind the real API limit (mid-session 400s).
+ */
+export function shouldMarkOneMillion(window: number | undefined, auto: AutoContextMode): boolean {
+  if (typeof window !== "number" || window <= 0) return false;
+  if (window >= ONE_MILLION) return true;
+  return auto.enabled && window > AUTO_CONTEXT_FLOOR && window >= auto.compactWindow;
+}
+
+export function buildClaudeContextWindows(
+  nativeSlugs: readonly string[],
+  routedModels: readonly CatalogModel[],
+): Record<string, number> {
+  const out: Record<string, number> = {};
+  const put = (key: string | null, value: number) => {
+    if (!key) return;
+    if (out[key] === undefined) out[key] = value; // first-wins (registry policy)
+  };
+  for (const slug of nativeSlugs) {
+    const window = nativeOpenAiContextWindow(slug);
+    if (typeof window !== "number" || window <= 0) continue;
+    put(slug, window);
+    put(desktop3pAlias("native", slug), window);
+    put(aliasForNative(slug), window);
+  }
+  // Bare routed ids are registered only when unambiguous across providers (audit
+  // 021 #5) — natives are registered first, so a native slug always wins the bare key.
+  const bareCounts = new Map<string, number>();
+  for (const m of routedModels) bareCounts.set(m.id, (bareCounts.get(m.id) ?? 0) + 1);
+  for (const m of routedModels) {
+    const window = m.contextWindow;
+    if (typeof window !== "number" || window <= 0) continue;
+    // Anthropic passthrough guard (audit 021 #3): canonical claude ids ride the
+    // subscription passthrough — marking a sub-1M one would strap [1m]/1M-beta onto
+    // a model that cannot host it. Register anthropic rows only at >=1M.
+    if (m.provider === "anthropic" && window < ONE_MILLION) continue;
+    put(`${m.provider}/${m.id}`, window);
+    put(desktop3pAlias(m.provider, m.id), window);
+    put(aliasForRoute(m.provider, m.id), window);
+    if (bareCounts.get(m.id) === 1) put(m.id, window);
+  }
+  return out;
+}
+
+/** Strip a trailing [1m] marker before map lookup (selector may already carry it). */
+function bareSelector(value: string): string {
+  return stripOneMillionMarker(value);
+}
+
+/**
+ * Apply the [1m] context-variant marker to a model selector when its authoritative
+ * window is >= 1M (Claude Code accounts exactly 1M for the marker; compaction stays
+ * alive) — or, in auto-context mode, when the window clears the marking predicate
+ * above. Already-marked selectors pass through; unknown selectors stay untouched.
+ */
+export function withOneMillionMarker(selector: string | undefined, windows: Record<string, number>, auto: AutoContextMode = AUTO_CONTEXT_OFF): string | undefined {
+  if (!selector) return selector;
+  if (hasOneMillionMarker(selector)) return selector;
+  const window = windows[bareSelector(selector)];
+  return shouldMarkOneMillion(window, auto) ? `${selector}[1m]` : selector;
+}
+
+export interface ClaudeTierModels {
+  opus?: string;
+  sonnet?: string;
+  haiku?: string;
+  fable?: string;
+}
+
+/**
+ * The exact env map Claude Code consumes for model slots (audit R4#4):
+ * ANTHROPIC_MODEL + the four tier defaults + the legacy small-fast alias.
+ * effective-haiku contract (audit R1#8): tierModels.haiku ?? smallFastModel, one
+ * value injected into BOTH haiku variables.
+ */
+export function effectiveModelEnv(
+  claudeCode: { model?: string; smallFastModel?: string; tierModels?: ClaudeTierModels; autoContext?: boolean; autoCompactWindow?: number; maxContextTokens?: number } | undefined,
+  windows: Record<string, number>,
+  autoOverride?: AutoContextMode,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const auto = autoOverride ?? resolveAutoContext(claudeCode);
+  const set = (name: string, value: string | undefined) => {
+    const marked = withOneMillionMarker(value, windows, auto);
+    if (marked) out[name] = marked;
+  };
+  set("ANTHROPIC_MODEL", claudeCode?.model);
+  set("ANTHROPIC_DEFAULT_OPUS_MODEL", claudeCode?.tierModels?.opus);
+  set("ANTHROPIC_DEFAULT_SONNET_MODEL", claudeCode?.tierModels?.sonnet);
+  set("ANTHROPIC_DEFAULT_FABLE_MODEL", claudeCode?.tierModels?.fable);
+  const effectiveHaiku = claudeCode?.tierModels?.haiku ?? claudeCode?.smallFastModel;
+  set("ANTHROPIC_DEFAULT_HAIKU_MODEL", effectiveHaiku);
+  set("ANTHROPIC_SMALL_FAST_MODEL", effectiveHaiku);
+  return out;
+}
+
+/** Shared 3s bounded acquisition (audit R4#3) for context-window sources. */
+export async function boundedContextWindows(
+  acquire: () => Promise<Record<string, number>>,
+  timeoutMs = 3_000,
+): Promise<Record<string, number> | null> {
+  try {
+    return await Promise.race([
+      acquire(),
+      new Promise<null>(resolve => setTimeout(() => resolve(null), timeoutMs)),
+    ]);
+  } catch {
+    return null;
+  }
+}

package/src/claude/desktop-3p.ts

@@ -0,0 +1,254 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface Desktop3pModelEntry {
+  name: string;
+  labelOverride: string;
+  anthropicFamilyTier: "opus";
+  isFamilyDefault?: boolean;
+  /**
+   * Desktop's documented 1M-context capability assertion. Set ONLY from an
+   * authoritative routed contextWindow >= 1M — never guessed (devlog 136 B5).
+   */
+  supports1m?: true;
+}
+
+/**
+ * static (default, Pro-verified devlog 138): pinned inferenceModels with
+ * modelDiscoveryEnabled:false — a static list OVERRIDES discovery (no merge), so
+ * this is the deterministic shape. hybrid keeps discovery:true alongside the list
+ * (claude-code-router's version-defensive pattern). discovery: /v1/models only.
+ */
+export type Desktop3pConfigMode = "hybrid" | "discovery" | "static";
+
+export interface Desktop3pRoutedModel {
+  provider: string;
+  id: string;
+  /** Authoritative context window (CatalogModel.contextWindow); optional. */
+  contextWindow?: number;
+}
+
+const SUPPORTS_1M_THRESHOLD = 1_000_000;
+
+/** CLI arg parsing for `ocx claude desktop` mode flags (mutually exclusive). */
+export function parseDesktop3pModeArgs(flags: string[]): { mode: Desktop3pConfigMode } | { error: string } {
+  const known = new Map<string, Desktop3pConfigMode>([
+    ["--static", "static"],
+    ["--hybrid", "hybrid"],
+    ["--discovery-only", "discovery"],
+  ]);
+  const unknown = flags.filter(a => !known.has(a));
+  if (unknown.length > 0) return { error: `알 수 없는 옵션: ${unknown.join(" ")} (지원: --static, --hybrid, --discovery-only)` };
+  const picked = [...new Set(flags.map(a => known.get(a)!))];
+  if (picked.length > 1) return { error: "모드 옵션은 하나만 쓸 수 있습니다 (--static | --hybrid | --discovery-only)." };
+  return { mode: picked[0] ?? "static" };
+}
+
+interface Desktop3pMetadataEntry {
+  id: string;
+  name: string;
+  [key: string]: unknown;
+}
+
+interface Desktop3pMetadata {
+  appliedId?: string;
+  entries: Desktop3pMetadataEntry[];
+  [key: string]: unknown;
+}
+
+let desktop3pRegistry = new Map<string, string>();
+
+/** Derive a stable letter-first, three-character base36 code from a route key. */
+export function deriveDesktop3pCode(route: string): string {
+  const hash = createHash("sha256").update(route).digest();
+  const n = hash.readUInt32BE(0) % 33696;
+  const first = String.fromCharCode(97 + Math.floor(n / 1296));
+  const rest = (n % 1296).toString(36).padStart(2, "0");
+  return first + rest;
+}
+
+/**
+ * Alias for one proxy model. Real Anthropic models pass through unchanged (they must
+ * keep hitting the sk-ant native passthrough); everything else gets a Claude-shaped
+ * `claude-opus-4-8-{code}` id. Opus 4.8 is chosen deliberately: Desktop's effort
+ * selector is an allowlist keyed on exact supported model ids (Opus 4.8/4.7/4.6,
+ * Sonnet 4.6 — devlog 131), and 4.6+ canonical ids are dateless, so the letter-first
+ * 3-char suffix can never collide with a real id or a legacy date suffix.
+ */
+export function desktop3pAlias(provider: string, modelId: string): string {
+  if (provider === "anthropic" && modelId.startsWith("claude-")) return modelId;
+  return `claude-opus-4-8-${deriveDesktop3pCode(`${provider}/${modelId}`)}`;
+}
+
+/** Pre-rename alias shape (claude-opus-4-{code}) — still decoded for stale Desktop configs. */
+export function legacyDesktop3pAlias(provider: string, modelId: string): string {
+  return `claude-opus-4-${deriveDesktop3pCode(`${provider}/${modelId}`)}`;
+}
+
+function displayModelId(modelId: string): string {
+  return modelId
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map(part => {
+      const lower = part.toLowerCase();
+      if (lower === "gpt" || lower === "glm" || lower === "ai") return lower.toUpperCase();
+      return part.charAt(0).toUpperCase() + part.slice(1);
+    })
+    .join(" ");
+}
+
+function collectDesktop3pModels(
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+): { models: Desktop3pModelEntry[]; registry: Map<string, string> } {
+  const registry = new Map<string, string>();
+  const models: Desktop3pModelEntry[] = [];
+  const candidates: Desktop3pRoutedModel[] = [
+    ...nativeSlugs.map(id => ({ provider: "native", id })),
+    ...routedModels,
+  ];
+
+  for (const { provider, id, contextWindow } of candidates) {
+    const route = `${provider}/${id}`;
+    const alias = desktop3pAlias(provider, id);
+    const supports1m = typeof contextWindow === "number" && contextWindow >= SUPPORTS_1M_THRESHOLD
+      ? { supports1m: true as const }
+      : {};
+    if (alias === id) {
+      // Real Anthropic model: keep it OUT of the decode registry — registering it would
+      // make resolveInboundModel() non-identity and kill the sk-ant native passthrough
+      // (audit 133 #1). It still appears in the static Desktop model list below.
+      models.push({
+        name: alias,
+        labelOverride: `${displayModelId(id)} (${provider})`,
+        anthropicFamilyTier: "opus",
+        ...supports1m,
+      });
+      continue;
+    }
+    const existingRoute = registry.get(alias);
+    if (existingRoute !== undefined) {
+      console.warn(`[opencodex] Claude Desktop 3P alias collision: ${alias} maps to both ${existingRoute} and ${route}; skipping ${route}`);
+      continue;
+    }
+
+    registry.set(alias, route);
+    // Back-compat decode for Desktop configs written before the opus-4-8 rename.
+    const legacy = legacyDesktop3pAlias(provider, id);
+    if (!registry.has(legacy)) registry.set(legacy, route);
+    models.push({
+      name: alias,
+      labelOverride: `${displayModelId(id)} (${provider})`,
+      anthropicFamilyTier: "opus",
+      ...supports1m,
+    });
+  }
+
+  if (models[0]) models[0].isFamilyDefault = true;
+  return { models, registry };
+}
+
+/** Build and install the registry used to decode Desktop aliases. */
+export function buildDesktop3pRegistry(
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+): Map<string, string> {
+  const { registry } = collectDesktop3pModels(nativeSlugs, routedModels);
+  desktop3pRegistry = registry;
+  return registry;
+}
+
+/** Generate Claude Desktop 3P model entries from the proxy's available models. */
+export function generateDesktop3pModels(
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+): Desktop3pModelEntry[] {
+  const { models, registry } = collectDesktop3pModels(nativeSlugs, routedModels);
+  desktop3pRegistry = registry;
+  return models;
+}
+
+/** Resolve an alias using the most recently generated Desktop model registry. */
+export function resolveDesktop3pAlias(alias: string): string | null {
+  return desktop3pRegistry.get(alias) ?? null;
+}
+
+/**
+ * Generate the complete Claude Desktop 3P gateway config.
+ *
+ * Default mode is "static" (Pro-verified, devlog 138): the static list is the ONLY
+ * channel for supports1m/tier pins and it overrides discovery anyway (no merge), so
+ * discovery stays off for determinism. supports1m makes Desktop offer a separate 1M
+ * row; selecting it sends the bare id + `anthropic-beta: context-1m-2025-08-07`.
+ */
+export function generateDesktop3pConfig(
+  port: number,
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+  apiKey = "ocx",
+  mode: Desktop3pConfigMode = "static",
+): object {
+  const base = {
+    inferenceProvider: "gateway",
+    inferenceCredentialKind: "static",
+    inferenceGatewayBaseUrl: `http://127.0.0.1:${port}`,
+    inferenceGatewayApiKey: apiKey,
+  };
+  if (mode === "discovery") {
+    // Build/refresh the decode registry even though no static list is emitted.
+    buildDesktop3pRegistry(nativeSlugs, routedModels);
+    return { ...base, modelDiscoveryEnabled: true };
+  }
+  return {
+    ...base,
+    modelDiscoveryEnabled: mode === "hybrid",
+    inferenceModels: generateDesktop3pModels(nativeSlugs, routedModels),
+  };
+}
+
+function parseMetadata(path: string): Desktop3pMetadata {
+  if (!existsSync(path)) return { entries: [] };
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<Desktop3pMetadata>;
+  if (!Array.isArray(parsed.entries)) throw new Error("Claude Desktop 3P _meta.json has no entries array");
+  return { ...parsed, entries: parsed.entries };
+}
+
+/** Write and apply the opencodex config in Claude Desktop 3P's config library. */
+export function writeDesktop3pConfig(
+  port: number,
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+  apiKey?: string,
+  mode: Desktop3pConfigMode = "static",
+): { written: boolean; path: string; reason?: string } {
+  const libraryPath = join(homedir(), "Library", "Application Support", "Claude-3p", "configLibrary");
+  const metadataPath = join(libraryPath, "_meta.json");
+  let configPath = libraryPath;
+
+  try {
+    mkdirSync(libraryPath, { recursive: true, mode: 0o700 });
+    const metadata = parseMetadata(metadataPath);
+    const existing = metadata.entries.find(entry => entry?.name === "opencodex" && typeof entry.id === "string");
+    const id = existing?.id ?? randomUUID();
+    configPath = join(libraryPath, `${id}.json`);
+    const entry: Desktop3pMetadataEntry = existing ? { ...existing, id, name: "opencodex" } : { id, name: "opencodex" };
+    const entries = existing
+      ? metadata.entries.map(current => current === existing ? entry : current)
+      : [...metadata.entries, entry];
+
+    writeFileSync(configPath, JSON.stringify(generateDesktop3pConfig(port, nativeSlugs, routedModels, apiKey, mode), null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    writeFileSync(metadataPath, JSON.stringify({ ...metadata, appliedId: id, entries }, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    return { written: true, path: configPath };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { written: false, path: configPath, reason };
+  }
+}

package/src/claude/gateway-cache.ts

@@ -0,0 +1,70 @@
+/**
+ * Claude Code gateway-model cache writer (devlog 260712 030).
+ *
+ * Claude Code 2.1.207 refreshes ~/.claude/cache/gateway-models.json ONLY when it
+ * holds a credential (q5l(): `if(!ANTHROPIC_AUTH_TOKEN && !apiKey) return`). Our
+ * subscription-preserving launch deliberately sets no token, so the CLI can never
+ * refresh its picker list itself — it reads whatever cache exists. We therefore
+ * pre-write the cache in the exact on-disk schema the CLI uses:
+ *   { baseUrl, fetchedAt, models: [{ id, display_name? }] }  (mode 0600)
+ * mirroring its `/^(claude|anthropic)/i` usable-id filter. The picker validates
+ * only `baseUrl === ANTHROPIC_BASE_URL`, so a foreign base URL is simply ignored.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface GatewayModelRow {
+  id: string;
+  display_name?: string;
+}
+
+/** Claude Code config dir (CLAUDE_CONFIG_DIR override honored, like the CLI). */
+export function claudeConfigDir(): string {
+  const custom = process.env.CLAUDE_CONFIG_DIR;
+  return custom && custom.length > 0 ? custom : join(homedir(), ".claude");
+}
+
+/** Write the cache file; returns its path or null (best-effort, never throws). */
+export function writeGatewayModelCache(baseUrl: string, models: readonly GatewayModelRow[], configDir = claudeConfigDir()): string | null {
+  try {
+    // Mirror the CLI's usable-id filter so our file matches what it would cache.
+    const usable = models.filter(m => /^(claude|anthropic)/i.test(m.id));
+    if (usable.length === 0) return null;
+    const cacheDir = join(configDir, "cache");
+    mkdirSync(cacheDir, { recursive: true });
+    const path = join(cacheDir, "gateway-models.json");
+    const payload = {
+      baseUrl,
+      fetchedAt: Date.now(),
+      models: usable.map(m => (m.display_name === undefined ? { id: m.id } : { id: m.id, display_name: m.display_name })),
+    };
+    writeFileSync(path, JSON.stringify(payload), { encoding: "utf8", mode: 0o600 });
+    return path;
+  } catch {
+    return null;
+  }
+}
+
+/** Fetch the anthropic-flavor /v1/models from the local proxy and write the cache. */
+export async function refreshGatewayModelCacheFromProxy(port: number, timeoutMs = 3_000, configDir?: string): Promise<string | null> {
+  try {
+    // ?ids=cli pins the readable claude-ocx id family deterministically (audit 051
+    // #5): the cache prewrite must not depend on UA sniffing.
+    const res = await fetch(`http://127.0.0.1:${port}/v1/models?limit=1000&ids=cli`, {
+      headers: { "anthropic-version": "2023-06-01" },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    const body = await res.json() as { data?: Array<Record<string, unknown>> };
+    const models: GatewayModelRow[] = (Array.isArray(body.data) ? body.data : [])
+      .filter(m => typeof m.id === "string" && (m.id as string).length > 0)
+      .map(m => ({
+        id: m.id as string,
+        display_name: typeof m.display_name === "string" ? m.display_name : undefined,
+      }));
+    return writeGatewayModelCache(`http://127.0.0.1:${port}`, models, configDir);
+  } catch {
+    return null;
+  }
+}

package/src/claude/inbound-debug.ts

@@ -0,0 +1,114 @@
+/**
+ * Claude inbound debug capture (devlog/260711_claude_inbound/130 B1).
+ *
+ * Opt-in ring (last 20) of ALLOWLIST SCALARS from inbound Anthropic requests so the
+ * user can watch live what Claude Desktop/Code actually sends per effort-slider
+ * position (thinking.type / output_config.effort) and whether metadata.user_id
+ * exists (prompt-cache affinity, H1/H2).
+ *
+ * Privacy contract (audit 133 R1#6/R2#3): no prompt text, no raw objects, no stable
+ * hashes. The only identity-ish values are 8-char HMAC tags salted with a
+ * process-random key — comparable for equality WITHIN one proxy run, useless as a
+ * cross-run fingerprint. Capture is gated on the `claude` debug flag and the ring is
+ * cleared when the flag turns off.
+ */
+import { createHmac, randomBytes } from "node:crypto";
+import { isClaudeDebugEnabled } from "../lib/debug-settings";
+
+export interface ClaudeInboundDebugEntry {
+  at: number;
+  endpoint: "messages" | "count_tokens";
+  model: string;
+  resolvedModel?: string;
+  stream?: boolean;
+  maxTokens?: number;
+  thinkingType?: string;
+  thinkingBudgetTokens?: number;
+  outputConfigEffort?: string;
+  metadataKeys?: string[];
+  hasMetadataUserId: boolean;
+  hasSystem: boolean;
+  /** Raw anthropic-beta header (comma list) — carries context-1m / effort betas. */
+  anthropicBeta?: string;
+  /** Ephemeral equality tags (process-salted HMAC, 8 chars) — run-local identity only. */
+  userIdTag?: string;
+  systemTag?: string;
+}
+
+const RING_LIMIT = 20;
+const ring: ClaudeInboundDebugEntry[] = [];
+const salt = randomBytes(16).toString("hex");
+let lastEnabled = false;
+
+function tag(value: string): string {
+  return createHmac("sha256", salt).update(value).digest("hex").slice(0, 8);
+}
+
+type Rec = Record<string, unknown>;
+
+function isRec(v: unknown): v is Rec {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function systemText(system: unknown): string | undefined {
+  if (typeof system === "string") return system.length > 0 ? system : undefined;
+  if (Array.isArray(system)) {
+    const parts = system
+      .filter((b): b is Rec => isRec(b) && b.type === "text" && typeof b.text === "string")
+      .map(b => b.text as string);
+    return parts.length > 0 ? parts.join("\n\n") : undefined;
+  }
+  return undefined;
+}
+
+/** Record one inbound request. No-op (and ring flush) when the claude debug flag is off. */
+export function captureClaudeInbound(
+  endpoint: "messages" | "count_tokens",
+  body: unknown,
+  resolvedModel?: string,
+  anthropicBeta?: string,
+): void {
+  const enabled = isClaudeDebugEnabled();
+  if (!enabled) {
+    if (lastEnabled) ring.length = 0; // flag turned off: drop captured entries
+    lastEnabled = false;
+    return;
+  }
+  lastEnabled = true;
+  if (!isRec(body)) return;
+  const thinking = isRec(body.thinking) ? body.thinking : undefined;
+  const outputConfig = isRec(body.output_config) ? body.output_config : undefined;
+  const metadata = isRec(body.metadata) ? body.metadata : undefined;
+  const userId = metadata && typeof metadata.user_id === "string" ? metadata.user_id : undefined;
+  const system = systemText(body.system);
+  const entry: ClaudeInboundDebugEntry = {
+    at: Date.now(),
+    endpoint,
+    model: typeof body.model === "string" ? body.model : "unknown",
+    ...(resolvedModel ? { resolvedModel } : {}),
+    ...(typeof body.stream === "boolean" ? { stream: body.stream } : {}),
+    ...(typeof body.max_tokens === "number" ? { maxTokens: body.max_tokens } : {}),
+    ...(thinking && typeof thinking.type === "string" ? { thinkingType: thinking.type } : {}),
+    ...(thinking && typeof thinking.budget_tokens === "number" ? { thinkingBudgetTokens: thinking.budget_tokens } : {}),
+    ...(outputConfig && typeof outputConfig.effort === "string" ? { outputConfigEffort: outputConfig.effort } : {}),
+    ...(metadata ? { metadataKeys: Object.keys(metadata) } : {}),
+    hasMetadataUserId: userId !== undefined,
+    hasSystem: system !== undefined,
+    ...(anthropicBeta ? { anthropicBeta } : {}),
+    ...(userId !== undefined ? { userIdTag: tag(userId) } : {}),
+    ...(system !== undefined ? { systemTag: tag(system) } : {}),
+  };
+  ring.push(entry);
+  if (ring.length > RING_LIMIT) ring.shift();
+}
+
+/** Newest-first snapshot for /api/claude/inbound-debug. */
+export function getClaudeInboundDebugEntries(): ClaudeInboundDebugEntry[] {
+  return [...ring].reverse();
+}
+
+/** Test isolation / explicit clear. */
+export function clearClaudeInboundDebug(): void {
+  ring.length = 0;
+  lastEnabled = false;
+}