UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

453 lines (423 loc) • 21.7 kB
/** Privacy-bounded, process-local cache diagnostics. Enable with OPENCODEX_CACHE_DEBUG=1. */ import { createHmac, randomBytes } from "node:crypto"; import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { codexConversationIdentity } from "../codex/lineage"; import { getConfigDir } from "../config"; import { recordOwnedConfigPath } from "../lib/config-ownership"; import type { CacheTelemetryProvenance } from "./log"; const CACHE_DEBUG_KEY = randomBytes(32); const MAX_BLOCKS = 128; const MAX_DRAFTS = 512; const SESSION_HEADERS = ["session_id", "session-id", "thread-id", "x-session-id"] as const; type SessionHeaders = Record<typeof SESSION_HEADERS[number], TaggedPresence>; export const CACHE_DEBUG_MAX_LINES = 200; export const CACHE_DEBUG_KEEP_LINES = 100; export type PromptCacheKeySource = "caller" | "metadata-derived" | "system-derived" | "proxy-synthesized"; export interface TaggedPresence { present: boolean; tag?: string; source?: PromptCacheKeySource } export interface TaggedSequence { present: boolean; count: number; tags: string[]; truncated?: true } export interface PrefixFingerprint { instructions: TaggedSequence; tools: TaggedSequence; messages: TaggedSequence; unsupported?: true; } type PrefixSection = "instructions" | "tools" | "messages"; export type PrefixComparison = | { status: "first" | "equal" } | { status: "append-only" | "different" | "truncated"; section: PrefixSection; index: number } | { status: "uncomparable"; reason: "missing-session" | "missing-observation" | "unsupported-shape" }; export interface CacheDiagnosticDraft { promptCacheKey?: { inbound?: TaggedPresence; outbound?: TaggedPresence }; session?: { inboundHeader?: TaggedPresence; outboundHeader?: TaggedPresence; inboundHeaders?: SessionHeaders; outboundHeaders?: SessionHeaders; }; prefix?: { inbound?: PrefixFingerprint; outbound?: PrefixFingerprint }; /** The shared Pool key derivation's result, not a binding lookup or selection decision. */ accountAffinity?: { inbound?: TaggedPresence; outbound?: TaggedPresence }; } export interface CacheDiagnosticFinalFacts { requestId: string; logicalRequestId?: string; protocol: "responses" | "chat" | "messages"; provider: string; model: string; accountLogLabel?: string; affinityMove?: string; affinityReason?: string; /** * The cache counter exactly as the upstream usage object carried it, read before any * client-wire defaulting. Undefined means the upstream object had no cache counter at * all, which keeps a measured zero distinct from an absent-then-defaulted zero. */ rawCacheCounterValue?: number; normalizedCacheValue?: number; cacheProvenance: CacheTelemetryProvenance; draft?: CacheDiagnosticDraft; } const drafts = new Map<string, CacheDiagnosticDraft>(); const bodyDrafts = new WeakMap<object, CacheDiagnosticDraft>(); // Internal only: neither the caller principal nor its tag belongs in the diagnostic record. const callerScopes = new WeakMap<object, string>(); interface PreviousObservation { prefix?: CacheDiagnosticDraft["prefix"]; promptCacheKey?: CacheDiagnosticDraft["promptCacheKey"]; account: TaggedPresence; } // Finalization order, process-local only. Keys include the diagnostic destination so changing // OPENCODEX_HOME cannot join histories. Neither keys nor values retain raw session/account data. const previousObservations = new Map<string, PreviousObservation>(); // Retention epoch: every on/off transition starts a new one. Nothing observed in an earlier epoch // may be compared, merged or written after it, so turning diagnostics off forgets the history. let diagnosticGeneration = 0; let lastEnabled = false; const draftGenerations = new WeakMap<object, number>(); export function isCacheDiagnosticEnabled(): boolean { const enabled = process.env.OPENCODEX_CACHE_DEBUG === "1"; if (enabled !== lastEnabled) { lastEnabled = enabled; diagnosticGeneration++; drafts.clear(); previousObservations.clear(); } return enabled; } function stamp<T extends object>(draft: T): T { draftGenerations.set(draft, diagnosticGeneration); return draft; } /** A draft stamped in an earlier epoch; unstamped partial observations are not drafts. */ function staleDraft(value: unknown): boolean { if (!value || typeof value !== "object") return false; const generation = draftGenerations.get(value); return generation !== undefined && generation !== diagnosticGeneration; } export function cacheDiagnosticPath(): string { return join(getConfigDir(), "cache-debug.jsonl"); } function tag(domain: string, value: string): string { return createHmac("sha256", CACHE_DEBUG_KEY) .update(domain).update("\0").update(value).digest("hex").slice(0, 12); } export function tagCacheDiagnosticValue(domain: string, value: string): string { return tag(`cache-debug:${domain}`, value); } function canonicalJson(value: unknown): string { if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null"; if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`; const record = value as Record<string, unknown>; return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`; } function taggedPresence(value: unknown, domain: string, source?: PromptCacheKeySource): TaggedPresence { if (typeof value !== "string" || value.length === 0) return { present: false }; return { present: true, tag: tag(domain, value), ...(source ? { source } : {}) }; } function accountAffinityKey(headers: HeadersInit): TaggedPresence { // codexPoolAffinityKey is exactly this read-only identity projection. Import its leaf // derivation, not auth-context (which brings credential resolution and routing with it). // Parent-only inputs may consult existing TTL-bounded lineage; this call records nothing. const normalized = headers instanceof Headers ? headers : new Headers(headers); return taggedPresence(codexConversationIdentity(normalized)?.conversationKey, "cache-debug:codex-pool-affinity-key"); } function sessionHeaders(headers: HeadersInit): SessionHeaders { const normalized = headers instanceof Headers ? headers : new Headers(headers); return Object.fromEntries(SESSION_HEADERS.map(name => { const value = normalized.get(name); return [name, value === null ? { present: false } : { present: true, tag: tag("cache-debug:session-header", value), }]; })) as SessionHeaders; } function sessionPresence(headers: SessionHeaders): TaggedPresence { const values = SESSION_HEADERS.filter(name => headers[name].present).map(name => [name, headers[name].tag]); return values.length === 0 ? { present: false } : { present: true, tag: tag("cache-debug:session-headers", canonicalJson(values)) }; } function sequence(blocks: unknown[], domain: string): TaggedSequence { const bounded = blocks.slice(0, MAX_BLOCKS); return { present: blocks.length > 0, count: blocks.length, tags: bounded.map(block => tag(domain, canonicalJson(block))), ...(blocks.length > MAX_BLOCKS ? { truncated: true as const } : {}), }; } function requestBlocks(body: Record<string, unknown>): { instructions: unknown[]; messages: unknown[] } { const instructions = body.instructions; // Build fresh rows: pushes below must never mutate an array-valued instructions field // in the live request body. Include the source so moving text between fields is visible. const instructionRows: unknown[] = instructions === undefined || instructions === null ? [] : (Array.isArray(instructions) ? instructions : [instructions]) .map(content => ({ source: "instructions", content })); if (body.system !== undefined && body.system !== null) { instructionRows.push(...(Array.isArray(body.system) ? body.system : [body.system]) .map(content => ({ source: "system", content }))); } const input = typeof body.input === "string" ? [body.input] : Array.isArray(body.input) ? body.input : Array.isArray(body.messages) ? body.messages : []; // Keep every input/messages row in wire order, including system/developer updates. // Extracting those roles into instructions misclassifies a genuine tail append as a // top-level prefix rewrite. Whole-row tags still detect role, position and content edits. return { instructions: instructionRows, messages: input }; } export function prefixFingerprint(body: unknown): PrefixFingerprint { const record = body && typeof body === "object" && !Array.isArray(body) ? body as Record<string, unknown> : {}; const tools = Array.isArray(record.tools) ? record.tools : []; const blocks = requestBlocks(record); const unsupported = !body || typeof body !== "object" || Array.isArray(body) || (record.input !== undefined && typeof record.input !== "string" && !Array.isArray(record.input)) || (record.messages !== undefined && !Array.isArray(record.messages)) || (record.tools !== undefined && !Array.isArray(record.tools)); return { instructions: sequence(blocks.instructions, "cache-debug:prefix:instructions"), tools: sequence(tools, "cache-debug:prefix:tools"), messages: sequence(blocks.messages, "cache-debug:prefix:messages"), ...(unsupported ? { unsupported: true as const } : {}), }; } function comparePrefixes(before?: PrefixFingerprint, after?: PrefixFingerprint): PrefixComparison { if (!before || !after) return { status: "uncomparable", reason: "missing-observation" }; if (before.unsupported || after.unsupported) return { status: "uncomparable", reason: "unsupported-shape" }; for (const section of ["instructions", "tools", "messages"] as const) { const left = before[section]; const right = after[section]; const compared = Math.min(left.tags.length, right.tags.length); for (let index = 0; index < compared; index += 1) { if (left.tags[index] !== right.tags[index]) return { status: "different", section, index }; } // A hidden difference here could precede any difference in later sections. Do not // infer equality, append-only, or an exact first divergence from an unobserved tail. if (compared < Math.min(left.count, right.count)) return { status: "truncated", section, index: compared }; if (left.count !== right.count) { // Only message-tail growth is append-only. Growing instructions/tools changes the // cache prefix before the conversation even when all existing section tags match. return { status: section === "messages" && right.count > left.count ? "append-only" : "different", section, index: compared }; } } return { status: "equal" }; } type PresenceComparison = "first" | "equal" | "changed" | "uncomparable"; function comparePresence(before?: TaggedPresence, after?: TaggedPresence): PresenceComparison { if (!before || !after) return "uncomparable"; return before.present === after.present && before.tag === after.tag ? "equal" : "changed"; } function continuation(facts: CacheDiagnosticFinalFacts, draft: CacheDiagnosticDraft, account: TaggedPresence) { const headers = draft.session?.inboundHeaders; // Diagnostic correlation ONLY, not the account affinity identity or proof of a binding. // All available inbound identifiers participate. Do not use prompt_cache_key (which may // legitimately rotate), synthesized outbound IDs, or unrelated affinity headers as identity. const identity = headers && SESSION_HEADERS.filter(name => headers[name].present && headers[name].tag !== tag("cache-debug:session-header", "")) .map(name => [name, headers[name].tag]); const callerScope = callerScopes.get(draft); const key = identity?.length && callerScope ? tag("cache-debug:history", canonicalJson([ getConfigDir(), callerScope, facts.protocol, facts.model, identity, ])) : undefined; const previous = key ? previousObservations.get(key) : undefined; const compare = (side: "inbound" | "outbound"): PrefixComparison => { if (!identity?.length) return { status: "uncomparable", reason: "missing-session" }; if (!callerScope) return { status: "uncomparable", reason: "missing-observation" }; const current = draft.prefix?.[side]; if (!current) return { status: "uncomparable", reason: "missing-observation" }; if (current.unsupported) return { status: "uncomparable", reason: "unsupported-shape" }; return previous ? comparePrefixes(previous.prefix?.[side], current) : { status: "first" }; }; const presence = (side: "inbound" | "outbound"): PresenceComparison => !key || !draft.promptCacheKey?.[side] ? "uncomparable" : !previous ? "first" : comparePresence(previous.promptCacheKey?.[side], draft.promptCacheKey?.[side]); const result = { inbound: compare("inbound"), outbound: compare("outbound"), promptCacheKey: { inbound: presence("inbound"), outbound: presence("outbound") }, account: !key ? "uncomparable" : !previous ? "first" : comparePresence(previous.account, account), }; if (key) { previousObservations.delete(key); previousObservations.set(key, { prefix: { ...draft.prefix }, promptCacheKey: { ...draft.promptCacheKey }, account, }); while (previousObservations.size > MAX_DRAFTS) previousObservations.delete(previousObservations.keys().next().value!); } return result; } export function observe(requestId: string, observation: Partial<CacheDiagnosticDraft>): CacheDiagnosticDraft { if (!isCacheDiagnosticEnabled() || staleDraft(observation)) return {}; const draft = drafts.get(requestId) ?? stamp({}); Object.assign(draft, observation); const callerScope = callerScopes.get(observation); if (callerScope) callerScopes.set(draft, callerScope); drafts.delete(requestId); drafts.set(requestId, draft); while (drafts.size > MAX_DRAFTS) drafts.delete(drafts.keys().next().value!); return draft; } export function observeInbound( body: unknown, headers: Headers, source: PromptCacheKeySource = "caller", admissionPrincipal?: string, ): CacheDiagnosticDraft { if (!isCacheDiagnosticEnabled()) return {}; try { const record = body && typeof body === "object" && !Array.isArray(body) ? body as Record<string, unknown> : {}; const inboundHeaders = sessionHeaders(headers); const draft: CacheDiagnosticDraft = stamp({ promptCacheKey: { inbound: taggedPresence(record.prompt_cache_key, "cache-debug:prompt-cache-key", source) }, session: { inboundHeader: sessionPresence(inboundHeaders), inboundHeaders }, prefix: { inbound: prefixFingerprint(body) }, accountAffinity: { inbound: accountAffinityKey(headers) }, }); // Admission owns caller identity; bridges may remove or replace Authorization. // No trusted principal (including unauthenticated loopback) means no history join. if (admissionPrincipal) callerScopes.set(draft, tag("cache-debug:caller-scope", admissionPrincipal)); if (body && typeof body === "object") bodyDrafts.set(body, draft); return draft; } catch { return {}; } } /** * Alias a later form of the same request body (for example after previous-response * expansion) to an existing draft, so the outbound observation at the adapter seam can * find it. The inbound fingerprint intentionally stays the literal pre-expansion body. */ export function rebindCacheDiagnosticBodyAlias(body: unknown, draft: CacheDiagnosticDraft | undefined): void { if (!isCacheDiagnosticEnabled() || !draft) return; if (staleDraft(draft)) return; if (body && typeof body === "object") bodyDrafts.set(body, draft); } export function observeOutbound( inboundBody: unknown, outboundBody: unknown, headers: HeadersInit, source: PromptCacheKeySource = "proxy-synthesized", ): void { if (!isCacheDiagnosticEnabled()) return; try { if (!inboundBody || typeof inboundBody !== "object") return; const draft = bodyDrafts.get(inboundBody); if (!draft || staleDraft(draft)) return; const record = outboundBody && typeof outboundBody === "object" && !Array.isArray(outboundBody) ? outboundBody as Record<string, unknown> : {}; const outbound = taggedPresence(record.prompt_cache_key, "cache-debug:prompt-cache-key", source); const inboundKey = draft.promptCacheKey?.inbound; if (outbound.present && inboundKey && outbound.tag === inboundKey.tag) { outbound.source = inboundKey.source; } (draft.promptCacheKey ??= {}).outbound = outbound; const outboundHeaders = sessionHeaders(headers); Object.assign(draft.session ??= {}, { outboundHeader: sessionPresence(outboundHeaders), outboundHeaders }); (draft.prefix ??= {}).outbound = prefixFingerprint(outboundBody); (draft.accountAffinity ??= {}).outbound = accountAffinityKey(headers); } catch { /* diagnostics must never affect request handling */ } } function ensureDir(): void { const dir = getConfigDir(); recordOwnedConfigPath(dir, cacheDiagnosticPath()); mkdirSync(dir, { recursive: true, mode: 0o700 }); try { chmodSync(dir, 0o700); } catch { /* best-effort */ } } function trimRollingFile(path: string): void { const lines = readFileSync(path, "utf8").split(/\r?\n/).filter(Boolean); if (lines.length <= CACHE_DEBUG_MAX_LINES) return; writeFileSync(path, `${lines.slice(-CACHE_DEBUG_KEEP_LINES).join("\n")}\n`, { encoding: "utf8", mode: 0o600 }); try { chmodSync(path, 0o600); } catch { /* best-effort */ } } export function appendFinalCacheDiagnostic(facts: CacheDiagnosticFinalFacts): void { if (!isCacheDiagnosticEnabled()) return; if (staleDraft(facts.draft)) { drafts.delete(facts.requestId); return; } try { const draft = facts.draft ? observe(facts.requestId, facts.draft) : drafts.get(facts.requestId) ?? {}; drafts.delete(facts.requestId); const inboundKey = draft.promptCacheKey?.inbound; const outboundKey = draft.promptCacheKey?.outbound; const inboundPrefix = draft.prefix?.inbound; const outboundPrefix = draft.prefix?.outbound; const comparison = comparePrefixes(inboundPrefix, outboundPrefix); // Only explicit account facts are evidence; never infer an account from provider text. const account = taggedPresence(facts.accountLogLabel, "cache-debug:account-log-label"); const record = { version: 1 as const, ts: Date.now(), requestId: facts.requestId, ...(facts.logicalRequestId ? { logicalRequestId: facts.logicalRequestId } : {}), protocol: facts.protocol, provider: facts.provider, model: facts.model, promptCacheKey: { inbound: inboundKey ?? { present: false }, outbound: outboundKey ?? { present: false }, ...(inboundKey?.present && outboundKey?.present ? { equal: inboundKey.tag === outboundKey.tag } : {}), }, accountAffinity: { derivation: "codexConversationIdentity", evidence: "derived-key-not-binding", // Missing observation stays omitted, distinct from an observed absent key. ...draft.accountAffinity, }, session: { purpose: "diagnostic-correlation-only", inboundHeader: draft.session?.inboundHeader ?? { present: false }, outboundHeader: draft.session?.outboundHeader ?? { present: false }, inboundHeaders: draft.session?.inboundHeaders, outboundHeaders: draft.session?.outboundHeaders, }, prefix: { inbound: inboundPrefix, outbound: outboundPrefix, comparison, ...(comparison.status === "different" || comparison.status === "append-only" ? { firstDivergentBlock: { section: comparison.section, index: comparison.index } } : {}), }, continuation: continuation(facts, draft, account), route: { provider: facts.provider, model: facts.model, ...(account.present ? { accountTag: account.tag } : {}), // Preserve reported route labels, never infer key presence or an actual binding // from them: even `new_bind` can be reported when no affinity key was derived. ...(facts.affinityMove ? { affinityMove: facts.affinityMove } : {}), ...(facts.affinityReason ? { affinityReason: facts.affinityReason } : {}), }, cache: { rawUpstream: facts.rawCacheCounterValue !== undefined ? { present: true, value: facts.rawCacheCounterValue } : { present: false }, normalized: { present: facts.normalizedCacheValue !== undefined, ...(facts.normalizedCacheValue !== undefined ? { value: facts.normalizedCacheValue } : {}), provenance: facts.cacheProvenance, }, }, }; ensureDir(); const path = cacheDiagnosticPath(); appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 }); try { chmodSync(path, 0o600); } catch { /* best-effort */ } if (existsSync(path)) trimRollingFile(path); } catch { /* diagnostics must never affect request handling */ } } const CACHE_DIAGNOSTIC_HOOK = Symbol.for("opencodex.cache-diagnostic.v1"); interface CacheDiagnosticHooks { enabled(): boolean; observeInbound(body: unknown, headers: Headers, source: PromptCacheKeySource, admissionPrincipal?: string): CacheDiagnosticDraft; rebind(body: unknown, draft: CacheDiagnosticDraft | undefined): void; finalize(facts: CacheDiagnosticFinalFacts): void; } (globalThis as Record<symbol, CacheDiagnosticHooks | undefined>)[CACHE_DIAGNOSTIC_HOOK] = { enabled: isCacheDiagnosticEnabled, observeInbound, rebind: rebindCacheDiagnosticBodyAlias, finalize: appendFinalCacheDiagnostic, };