@yansigit/opencodex 2.31.0

package/src/claude/desktop-profile.ts

@@ -0,0 +1,263 @@
+import { createHash } from "node:crypto";
+import type {
+  OcxClaudeDesktopAssignment,
+  OcxClaudeDesktopFamily,
+  OcxClaudeDesktopProfile,
+} from "../types";
+
+export const DESKTOP_FAMILIES = ["opus", "fable", "sonnet", "haiku"] as const;
+export type DesktopFamily = OcxClaudeDesktopFamily;
+export type DesktopProfile = OcxClaudeDesktopProfile;
+
+export interface DesktopProfileModel {
+  route: string;
+  label: string;
+  contextWindow?: number;
+}
+
+export interface RenderedDesktopModel extends DesktopProfileModel {
+  name: string;
+  family: DesktopFamily;
+  isFamilyDefault: boolean;
+  supports1m: boolean;
+}
+
+const DATE_ALIAS = /^claude-opus-4-8-(2026\d{4})$/;
+const DAY_COUNT_2026 = 365;
+
+export class DesktopProfileError extends Error {
+  constructor(message: string, readonly path = "profile") {
+    super(`${path}: ${message}`);
+    this.name = "DesktopProfileError";
+  }
+}
+
+export function emptyDesktopProfile(): DesktopProfile {
+  return {
+    version: 1,
+    assignments: {},
+    defaults: { opus: null, fable: null, sonnet: null, haiku: null },
+  };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertExactKeys(value: Record<string, unknown>, keys: readonly string[], path: string): void {
+  const allowed = new Set(keys);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new DesktopProfileError(`unknown field "${key}"`, path);
+  }
+}
+
+/**
+ * Applied-state markers survive every profile rebuild.
+ *
+ * `parseDesktopProfile`, `reconcileDesktopProfile` and `moveDesktopRoute` each construct a
+ * fresh `{ version, assignments, defaults }`, and the management routes persist whatever they
+ * return. Without this carry-through, saving an assignment — or merely dragging a model to
+ * another family — would erase the fingerprint the apply route wrote, and the GUI would report
+ * "not applied" for a config that is applied on disk.
+ */
+function appliedMarkers(source: { appliedFingerprint?: unknown; appliedAt?: unknown }): {
+  appliedFingerprint?: string;
+  appliedAt?: string;
+} {
+  return {
+    ...(typeof source.appliedFingerprint === "string" ? { appliedFingerprint: source.appliedFingerprint } : {}),
+    ...(typeof source.appliedAt === "string" ? { appliedAt: source.appliedAt } : {}),
+  };
+}
+
+function isFamily(value: unknown): value is DesktopFamily {
+  return typeof value === "string" && (DESKTOP_FAMILIES as readonly string[]).includes(value);
+}
+
+function routeModelId(route: string): string {
+  const slash = route.indexOf("/");
+  return slash >= 0 ? route.slice(slash + 1) : route;
+}
+
+function isRealAnthropicRoute(route: string): boolean {
+  return route.startsWith("anthropic/claude-");
+}
+
+function validDateAlias(alias: string): boolean {
+  const match = DATE_ALIAS.exec(alias);
+  if (!match) return false;
+  const year = Number(match[1]!.slice(0, 4));
+  const month = Number(match[1]!.slice(4, 6));
+  const day = Number(match[1]!.slice(6, 8));
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+
+export function parseDesktopProfile(value: unknown): DesktopProfile {
+  if (!isPlainObject(value)) throw new DesktopProfileError("must be an object");
+  // `appliedFingerprint`/`appliedAt` are written back by the apply route once a profile
+  // reaches Claude Desktop (see server/management/agent-settings-routes.ts). Rejecting them
+  // here made every reload after the first apply fail with `unknown field`.
+  assertExactKeys(value, ["version", "assignments", "defaults", "appliedFingerprint", "appliedAt"], "profile");
+  if (value.version !== 1) throw new DesktopProfileError("version must be 1", "profile.version");
+  if (!isPlainObject(value.assignments)) throw new DesktopProfileError("must be an object", "profile.assignments");
+  if (!isPlainObject(value.defaults)) throw new DesktopProfileError("must be an object", "profile.defaults");
+  assertExactKeys(value.defaults, DESKTOP_FAMILIES, "profile.defaults");
+  if (value.appliedFingerprint !== undefined && typeof value.appliedFingerprint !== "string") {
+    throw new DesktopProfileError("must be a string", "profile.appliedFingerprint");
+  }
+  if (value.appliedAt !== undefined && typeof value.appliedAt !== "string") {
+    throw new DesktopProfileError("must be a string", "profile.appliedAt");
+  }
+
+  const assignments: Record<string, OcxClaudeDesktopAssignment> = {};
+  const aliases = new Set<string>();
+  for (const [route, raw] of Object.entries(value.assignments)) {
+    if (!route.trim() || !route.includes("/")) throw new DesktopProfileError("route must be provider/model", `profile.assignments.${route || "<empty>"}`);
+    if (!isPlainObject(raw)) throw new DesktopProfileError("must be an object", `profile.assignments.${route}`);
+    assertExactKeys(raw, ["family", "alias"], `profile.assignments.${route}`);
+    if (!isFamily(raw.family)) throw new DesktopProfileError("unknown family", `profile.assignments.${route}.family`);
+    if (typeof raw.alias !== "string" || !raw.alias) throw new DesktopProfileError("must be a non-empty string", `profile.assignments.${route}.alias`);
+    if (isRealAnthropicRoute(route)) {
+      if (raw.alias !== routeModelId(route)) throw new DesktopProfileError("real Anthropic routes must keep their exact model id", `profile.assignments.${route}.alias`);
+    } else if (!validDateAlias(raw.alias)) {
+      throw new DesktopProfileError("must be a valid claude-opus-4-8-2026MMDD alias", `profile.assignments.${route}.alias`);
+    }
+    if (aliases.has(raw.alias)) throw new DesktopProfileError(`duplicate alias "${raw.alias}"`, `profile.assignments.${route}.alias`);
+    aliases.add(raw.alias);
+    assignments[route] = { family: raw.family, alias: raw.alias };
+  }
+
+  const defaults = {} as DesktopProfile["defaults"];
+  for (const family of DESKTOP_FAMILIES) {
+    const route = value.defaults[family];
+    if (route !== null && typeof route !== "string") throw new DesktopProfileError("must be a route or null", `profile.defaults.${family}`);
+    const members = Object.keys(assignments).filter(key => assignments[key]!.family === family).sort();
+    if (members.length === 0) {
+      if (route !== null) throw new DesktopProfileError("must be null for an empty family", `profile.defaults.${family}`);
+      defaults[family] = null;
+      continue;
+    }
+    if (typeof route !== "string" || !assignments[route] || assignments[route]!.family !== family) {
+      throw new DesktopProfileError("must reference a member of this family", `profile.defaults.${family}`);
+    }
+    defaults[family] = route;
+  }
+  return { version: 1, assignments, defaults, ...appliedMarkers(value) };
+}
+
+function dayOfYearAlias(dayIndex: number): string {
+  const date = new Date(Date.UTC(2026, 0, dayIndex + 1));
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  return `claude-opus-4-8-${y}${m}${d}`;
+}
+
+function routeStartDay(route: string): number {
+  return createHash("sha256").update(route).digest().readUInt32BE(0) % DAY_COUNT_2026;
+}
+
+function allocateAlias(route: string, used: Set<string>): string {
+  if (isRealAnthropicRoute(route)) return routeModelId(route);
+  const start = routeStartDay(route);
+  for (let offset = 0; offset < DAY_COUNT_2026; offset += 1) {
+    const alias = dayOfYearAlias((start + offset) % DAY_COUNT_2026);
+    if (!used.has(alias)) return alias;
+  }
+  throw new DesktopProfileError("all 365 encoded date slots are occupied", `profile.assignments.${route}.alias`);
+}
+
+export function reconcileDesktopProfile(
+  stored: unknown,
+  models: readonly DesktopProfileModel[],
+): DesktopProfile {
+  const profile = stored === undefined || stored === null ? emptyDesktopProfile() : parseDesktopProfile(stored);
+  const assignments: DesktopProfile["assignments"] = Object.fromEntries(
+    Object.entries(profile.assignments).map(([route, assignment]) => [route, { ...assignment }]),
+  );
+  const used = new Set(Object.values(assignments).map(value => value.alias));
+  for (const model of [...models].sort((a, b) => a.route.localeCompare(b.route))) {
+    if (assignments[model.route]) continue;
+    const alias = allocateAlias(model.route, used);
+    used.add(alias);
+    assignments[model.route] = { family: "opus", alias };
+  }
+  const defaults = { ...profile.defaults };
+  for (const family of DESKTOP_FAMILIES) {
+    const members = Object.keys(assignments).filter(route => assignments[route]!.family === family).sort();
+    const current = defaults[family];
+    defaults[family] = current && assignments[current]?.family === family ? current : (members[0] ?? null);
+  }
+  return parseDesktopProfile({ version: 1, assignments, defaults, ...appliedMarkers(profile) });
+}
+
+export function moveDesktopRoute(
+  profile: DesktopProfile,
+  route: string,
+  family: DesktopFamily,
+  makeDefault = false,
+): DesktopProfile {
+  const parsed = parseDesktopProfile(profile);
+  const current = parsed.assignments[route];
+  if (!current) throw new DesktopProfileError("route is not assigned", `profile.assignments.${route}`);
+  const oldFamily = current.family;
+  if (oldFamily === family) {
+    return makeDefault ? setDesktopFamilyDefault(parsed, family, route) : parsed;
+  }
+  const assignments = { ...parsed.assignments, [route]: { ...current, family } };
+  const defaults = { ...parsed.defaults };
+  if (defaults[oldFamily] === route) {
+    defaults[oldFamily] = Object.keys(assignments).filter(key => key !== route && assignments[key]!.family === oldFamily).sort()[0] ?? null;
+  }
+  const destinationMembers = Object.keys(assignments).filter(key => assignments[key]!.family === family).sort();
+  if (makeDefault || !defaults[family] || assignments[defaults[family]!]?.family !== family) defaults[family] = route;
+  if (!defaults[family] && destinationMembers.length > 0) defaults[family] = destinationMembers[0]!;
+  return parseDesktopProfile({ version: 1, assignments, defaults, ...appliedMarkers(parsed) });
+}
+
+export function setDesktopFamilyDefault(
+  profile: DesktopProfile,
+  family: DesktopFamily,
+  route: string | null,
+): DesktopProfile {
+  const parsed = parseDesktopProfile(profile);
+  const members = Object.keys(parsed.assignments).filter(key => parsed.assignments[key]!.family === family);
+  if (route === null && members.length > 0) throw new DesktopProfileError("cannot clear a non-empty family default", `profile.defaults.${family}`);
+  if (route !== null && parsed.assignments[route]?.family !== family) throw new DesktopProfileError("route is not a member of this family", `profile.defaults.${family}`);
+  return parseDesktopProfile({ ...parsed, defaults: { ...parsed.defaults, [family]: route } });
+}
+
+export function renderDesktopProfile(
+  profile: DesktopProfile,
+  models: readonly DesktopProfileModel[],
+): RenderedDesktopModel[] {
+  const parsed = parseDesktopProfile(profile);
+  const modelByRoute = new Map(models.map(model => [model.route, model]));
+  const activeByFamily = new Map<DesktopFamily, string[]>();
+  for (const family of DESKTOP_FAMILIES) activeByFamily.set(family, []);
+  for (const [route, assignment] of Object.entries(parsed.assignments)) {
+    if (modelByRoute.has(route)) activeByFamily.get(assignment.family)!.push(route);
+  }
+  for (const routes of activeByFamily.values()) routes.sort();
+  const effectiveDefaults = {} as Record<DesktopFamily, string | null>;
+  for (const family of DESKTOP_FAMILIES) {
+    const active = activeByFamily.get(family)!;
+    const stored = parsed.defaults[family];
+    effectiveDefaults[family] = stored && active.includes(stored) ? stored : (active[0] ?? null);
+  }
+  const defaultOrder = DESKTOP_FAMILIES.map(family => effectiveDefaults[family]).filter((route): route is string => !!route);
+  const defaultSet = new Set(defaultOrder);
+  const rest = Object.keys(parsed.assignments).filter(route => modelByRoute.has(route) && !defaultSet.has(route)).sort();
+  return [...defaultOrder, ...rest].map(route => {
+    const model = modelByRoute.get(route)!;
+    const assignment = parsed.assignments[route]!;
+    return {
+      ...model,
+      name: assignment.alias,
+      family: assignment.family,
+      isFamilyDefault: effectiveDefaults[assignment.family] === route,
+      supports1m: typeof model.contextWindow === "number" && model.contextWindow >= 1_000_000,
+    };
+  });
+}

package/src/claude/gateway-cache.ts

@@ -0,0 +1,107 @@
+/**
+ * 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";
+import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "../lib/service-secrets";
+import type { OcxConfig } from "../types";
+
+export interface GatewayModelRow {
+  id: string;
+  display_name?: string;
+}
+
+export interface GatewayModelCacheRefreshOptions {
+  timeoutMs?: number;
+  configDir?: string;
+  admissionConfig?: Pick<OcxConfig, "apiKeys">;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** 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));
+    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;
+  }
+}
+
+/**
+ * Hardened service-token file, the same precedence `ocx opencode` uses. A service
+ * install writes the admission token to disk rather than the interactive environment,
+ * so an interactive `ocx claude` with neither env token nor configured key would
+ * otherwise still get a 401 and keep a stale picker list.
+ */
+function serviceFileToken(env: NodeJS.ProcessEnv): string | null {
+  const lookup = env.OCX_API_TOKEN_FILE?.trim()
+    ? env
+    : { ...env, OCX_API_TOKEN_FILE: serviceApiTokenFilePath() };
+  return loadServiceTokenFromFile(lookup as Record<string, string | undefined>);
+}
+
+/** Fetch the anthropic-flavor /v1/models from the local proxy and write the cache. */
+export async function refreshGatewayModelCacheFromProxy(
+  port: number,
+  options: GatewayModelCacheRefreshOptions = {},
+): Promise<string | null> {
+  try {
+    const headers = new Headers({ "anthropic-version": "2023-06-01" });
+    // A wildcard/non-loopback listener requires data-plane admission even for a
+    // request sent to its local 127.0.0.1 address. Reuse the same dedicated
+    // credential domain as /v1/models admission; never place it in Authorization,
+    // which can belong to an upstream provider on other data-plane surfaces.
+    const envToken = (options.env ?? process.env).OPENCODEX_API_AUTH_TOKEN?.trim();
+    const configuredToken = options.admissionConfig?.apiKeys
+      ?.find(entry => entry.key.trim().length > 0)
+      ?.key.trim();
+    const admissionToken = envToken || serviceFileToken(options.env ?? process.env) || configuredToken;
+    if (admissionToken) headers.set("x-opencodex-api-key", admissionToken);
+
+    // ?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,
+      signal: AbortSignal.timeout(options.timeoutMs ?? 3_000),
+    });
+    if (!res.ok) return null;
+    const body = await res.json() as { data?: unknown };
+    if (!Array.isArray(body.data)) return null;
+    const models: GatewayModelRow[] = 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, options.configDir);
+  } catch {
+    return null;
+  }
+}

package/src/claude/inbound-debug.ts

@@ -0,0 +1,163 @@
+/**
+ * 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";
+import { retainedUtf8Bytes, truncateRetainedUtf8 } from "../lib/admission";
+import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
+
+export interface ClaudeInboundDebugEntry {
+  /** Monotonic capture id — unique even when several entries share Date.now(). */
+  id: number;
+  at: number;
+  endpoint: "messages" | "count_tokens";
+  model: string;
+  resolvedModel?: string;
+  stream?: boolean;
+  maxTokens?: number;
+  thinkingType?: string;
+  thinkingBudgetTokens?: number;
+  outputConfigEffort?: string;
+  metadataKeys?: string[];
+  metadataKeysDropped?: number;
+  rowTruncated?: true;
+  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 MAX_DIAGNOSTIC_VALUE_BYTES = 8 * 1024;
+const MAX_CLAUDE_INBOUND_METADATA_KEYS = 64;
+const MAX_CLAUDE_INBOUND_ROW_BYTES = 32 * 1024;
+const ring: ClaudeInboundDebugEntry[] = [];
+let ringBytes = 0;
+const salt = randomBytes(16).toString("hex");
+let lastEnabled = false;
+let nextCaptureId = 0;
+
+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;
+}
+
+function entryBytes(entry: ClaudeInboundDebugEntry): number {
+  return retainedUtf8Bytes(JSON.stringify(entry));
+}
+
+function removeOldest(): number {
+  const removed = ring.shift();
+  if (!removed) return 0;
+  const bytes = entryBytes(removed);
+  ringBytes -= bytes;
+  return bytes;
+}
+
+/** 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) clearClaudeInboundDebug(); // 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 metadataNames = metadata ? Object.keys(metadata) : [];
+  const entry: ClaudeInboundDebugEntry = {
+    id: ++nextCaptureId,
+    at: Date.now(),
+    endpoint,
+    model: truncateRetainedUtf8(typeof body.model === "string" ? body.model : "unknown", MAX_DIAGNOSTIC_VALUE_BYTES),
+    ...(resolvedModel ? { resolvedModel: truncateRetainedUtf8(resolvedModel, MAX_DIAGNOSTIC_VALUE_BYTES) } : {}),
+    ...(typeof body.stream === "boolean" ? { stream: body.stream } : {}),
+    ...(typeof body.max_tokens === "number" ? { maxTokens: body.max_tokens } : {}),
+    ...(thinking && typeof thinking.type === "string" ? { thinkingType: truncateRetainedUtf8(thinking.type, MAX_DIAGNOSTIC_VALUE_BYTES) } : {}),
+    ...(thinking && typeof thinking.budget_tokens === "number" ? { thinkingBudgetTokens: thinking.budget_tokens } : {}),
+    ...(outputConfig && typeof outputConfig.effort === "string" ? { outputConfigEffort: truncateRetainedUtf8(outputConfig.effort, MAX_DIAGNOSTIC_VALUE_BYTES) } : {}),
+    ...(metadata ? { metadataKeys: metadataNames.slice(0, MAX_CLAUDE_INBOUND_METADATA_KEYS).map(key => truncateRetainedUtf8(key, MAX_DIAGNOSTIC_VALUE_BYTES)) } : {}),
+    ...(metadataNames.length > MAX_CLAUDE_INBOUND_METADATA_KEYS ? { metadataKeysDropped: metadataNames.length - MAX_CLAUDE_INBOUND_METADATA_KEYS } : {}),
+    hasMetadataUserId: userId !== undefined,
+    hasSystem: system !== undefined,
+    ...(anthropicBeta ? { anthropicBeta: truncateRetainedUtf8(anthropicBeta, MAX_DIAGNOSTIC_VALUE_BYTES) } : {}),
+    ...(userId !== undefined ? { userIdTag: tag(userId) } : {}),
+    ...(system !== undefined ? { systemTag: tag(system) } : {}),
+  };
+  while (entryBytes(entry) > MAX_CLAUDE_INBOUND_ROW_BYTES && entry.metadataKeys?.length) {
+    entry.metadataKeys.pop();
+    entry.metadataKeysDropped = (entry.metadataKeysDropped ?? 0) + 1;
+    entry.rowTruncated = true;
+  }
+  for (const key of ["anthropicBeta", "resolvedModel", "outputConfigEffort", "thinkingType"] as const) {
+    if (entryBytes(entry) <= MAX_CLAUDE_INBOUND_ROW_BYTES) break;
+    if (entry[key] !== undefined) {
+      delete entry[key];
+      entry.rowTruncated = true;
+    }
+  }
+  ring.push(entry);
+  ringBytes += entryBytes(entry);
+  if (ring.length > RING_LIMIT) removeOldest();
+  enforceAppOwnedMemoryBudget();
+}
+
+/** 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;
+  ringBytes = 0;
+  lastEnabled = false;
+}
+
+export function claudeInboundDebugMetrics(): { entries: number; bytes: number; oldestAt: number | null } {
+  return { entries: ring.length, bytes: ringBytes, oldestAt: ring[0]?.at ?? null };
+}
+
+export function evictOldestClaudeInboundForBudget(): number {
+  return removeOldest();
+}