@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
text/typescript
/** 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,
};