UNPKG

@bitkyc08/opencodex

Version:

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

510 lines (475 loc) • 24 kB
/** * Codex V2 conversation lineage: root, parent, child, grandchild (#4546, wp8). * * The pool affinity key used to prefer `x-codex-parent-thread-id`, which collapsed two different * identities into one map. A root bound under `app:HMAC(session, thread)` while every child bound * under the RAW parent id, so siblings shared one binding entry unrelated to the root's, and a * grandchild keyed on its own parent landed on a key nobody had ever bound. The proxy therefore * treated one workflow as unrelated strangers even while the provider saw a single prompt-cache * family. * * This module records the real relation -- each thread's own conversation key, its immediate * parent's thread id, and the transitive root -- scoped per authenticated caller, bounded, and * process-local like the binding map it feeds. * * What it is for, and what it is not for: * * - FIRST PLACEMENT. Largely subsumed by cohort keying (#4780): a member of a tree that any * other member has already bound resolves to that same binding, so there is nothing to place. * `pickLineageServingAccount` in ./routing remains for the one case cohort keying cannot * unify -- a session-less chain whose parent is not recorded in this scope -- and is gated on * the parent's key actually differing from this request's. * - COST ATTRIBUTION. {@link codexThreadLineageLookup} and {@link codexLineageRootForRequest} * answer which root workflow a conversation belongs to, so a grandchild's spend aggregates * onto the root. No budget is implemented here. * - WORKER CLASSIFICATION, exposed but not rewired. Admission classifies header-only today: a * request naming a parent plus a distinct `thread-id` is worker traffic, and a request without * `thread-id` is interactive even when it belongs to a recorded fan-out. * {@link codexLineageWorkflowLane} is the lineage-backed answer a later lane consumes. * * Scope is an HMAC of the caller's Authorization header under a process-local key, the same * posture as the affinity key itself. Two callers presenting identical thread ids can never read * each other's lineage, and no raw identifier or durable hash is stored. * * LIFETIME, stated plainly because the word "affinity" invites the opposite assumption: none of * this survives the process. The binding map is in memory, and the HMAC key above is fresh random * bytes taken at module load, so a restart does not merely forget the table -- it makes yesterday's * keys unreproducible. This is a warm-start hint for the life of one proxy process, never durable * account ownership, and nothing here should be read as a promise to a conversation that outlives * a restart. * * The one upgrade that is neither a fresh start nor an untouched process is a code swap under a * live conversation, where the binding map is still populated with entries made under the * pre-#4546 RAW parent key. Silently rebinding those cold is the exact defect this module exists * to prevent, so a request that names a parent carries {@link CodexThreadLineage.legacyConversationKey} * -- the key the old rule would have returned -- and routing adopts that binding once under the new * key and retires the legacy entry. It is a one-way migration, not a second lookup path. */ import { createHmac, randomBytes } from "node:crypto"; import { retainedUtf8Bytes } from "../lib/admission"; const CODEX_LINEAGE_COMPONENT_MAX_BYTES = 512; const CODEX_LINEAGE_KEY = randomBytes(32); /** * Mirrors `CODEX_THREAD_AFFINITY_IDLE_TTL_MS` in ./routing. Deliberately duplicated rather than * imported: lineage is a leaf module, and a value import from the routing module that consumes it * would turn an erased type-only edge into a real cycle. */ export const CODEX_LINEAGE_IDLE_TTL_MS = 24 * 60 * 60_000; /** Records per authenticated scope, on the order of the binding map's own 2048-entry cap. */ export const CODEX_LINEAGE_MAX_ENTRIES = 2048; /** Distinct authenticated callers retained. Without this the scope map is the unbounded one. */ export const CODEX_LINEAGE_MAX_SCOPES = 64; /** Sibling hints kept per parent, most recently used first. */ export const CODEX_LINEAGE_MAX_SIBLINGS = 8; const LOCAL_LINEAGE_SCOPE = "local"; export type CodexWorkflowLane = "worker" | "interactive"; interface CodexLineageRecord { threadId: string; /** This thread's own pool binding key, byte-identical to what `codexPoolAffinityKey` returns. */ conversationKey: string; /** Immediate parent's raw thread id, retained once seen even if a later turn omits the header. */ parentThreadId?: string; /** Topmost ancestor's conversation key: a grandchild resolves to the root's, not its parent's. */ rootSessionKey: string; lastUsedAt: number; } interface CodexLineageScope { /** threadId -> record, iterated oldest-first so TTL pruning and eviction stay amortised O(1). */ records: Map<string, CodexLineageRecord>; /** conversationKey -> threadId, so cost attribution is a lookup instead of a scan. */ threadIdByConversationKey: Map<string, string>; /** parentThreadId -> child thread ids, most recent first, capped. */ childThreadIdsByParent: Map<string, string[]>; lastUsedAt: number; } /** * What placement and cost attribution are allowed to see. `parentConversationKey` is the parent's * OWN binding key -- either recorded, or derived from the shared session when the parent has not * been seen yet -- never the raw header value the old affinity key returned. */ export interface CodexThreadLineage { readonly conversationKey: string; readonly rootSessionKey: string; readonly parentThreadId?: string; readonly parentConversationKey?: string; /** * The key the pre-#4546 rule would have returned for this request -- the RAW parent id -- when * that differs from the key it binds under now. Present so routing can adopt a binding left by * the old rule exactly once; see the lifetime note at the top of this file. */ readonly legacyConversationKey?: string; /** Siblings under the same declared parent, most recently used first. */ readonly siblingConversationKeys: readonly string[]; } /** The identity the pool affinity key and the lineage record are both derived from. */ export interface CodexConversationIdentity { readonly conversationKey: string; /** Thread id this request records under: its own, or the parent's on a parent-only request. */ readonly recordThreadId: string; readonly sessionId?: string; readonly parentThreadId?: string; /** Raw parent id, i.e. the key the pre-#4546 rule returned for this request. */ readonly legacyConversationKey?: string; /** True only when the request names a parent distinct from its own thread. */ readonly declaresParent: boolean; } const lineageByScope = new Map<string, CodexLineageScope>(); /** A record is only evidence while it is live; an idle-expired one answers like no record. */ function liveLineageRecord( scope: CodexLineageScope | undefined, threadId: string, now: number, ): CodexLineageRecord | undefined { const record = scope?.records.get(threadId); return record !== undefined && now - record.lastUsedAt <= CODEX_LINEAGE_IDLE_TTL_MS ? record : undefined; } function boundedLineageComponent(value: string | null): string | undefined { const normalized = value?.trim(); if (!normalized) return undefined; if (retainedUtf8Bytes(normalized) > CODEX_LINEAGE_COMPONENT_MAX_BYTES) return undefined; return normalized; } /** * The single derivation behind both the pool affinity key and lineage records. Keeping it here, * rather than duplicated at the call site, is what guarantees a record's `conversationKey` is * byte-identical to the key the thread actually binds under. */ export function codexConversationKeyFor(familyId: string, threadId: string): string { return `app:${createHmac("sha256", CODEX_LINEAGE_KEY) .update("opencodex-app-pool-affinity-v1\0") .update(familyId) .update("\0") .update(threadId) .digest("base64url")}`; } /** * The cohort anchor's key: the same string on both sides of the derivation. * * A cohort is identified by one value the whole tree shares, so the key is that value keyed * against itself rather than against a member. Using {@link codexConversationKeyFor} keeps one * derivation in the module, which is what guarantees a lineage record's `conversationKey` stays * byte-identical to the key the thread actually binds under. */ function cohortKeyFromAnchor(sessionId: string | undefined, fallbackAnchor: string): string { const anchor = sessionId ?? fallbackAnchor; return codexConversationKeyFor(anchor, anchor); } /** * The cohort this request belongs to, or undefined when it names no cohort at all. * * The session IS the cohort, which is exactly how upstream keys the prompt cache: * `prompt_cache_key()` returns `responses_metadata.session_id` (or `{source}:{parent_thread_id}` * for an internal session), and `AgentControl.session_id` is the root thread's id, shared with * every sub-agent spawned from that root. Two requests carrying the same `prompt_cache_key` must * not be served by different accounts, and keying on the session is what makes that structural * rather than a hint (#4780). * * Without a session there is nothing in the headers that names the tree, so the cohort is * whatever the parent is already bound to. That lookup is what keeps a chain of parent-only * turns converging on one key: anchoring each depth on its own parent would split the cohort * again at every hop. When the parent has not been seen in this scope the parent id anchors it, * which is the same key that parent derives for itself. */ function cohortConversationKey( headers: Headers, sessionId: string | undefined, parentThreadId: string | undefined, now: number, ): string | undefined { if (sessionId !== undefined) return cohortKeyFromAnchor(sessionId, sessionId); if (parentThreadId === undefined) return undefined; const recorded = liveLineageRecord( lineageByScope.get(codexLineageScopeKey(headers)), parentThreadId, now, ); return recorded?.conversationKey ?? cohortKeyFromAnchor(undefined, parentThreadId); } /** * Resolve a request's conversation identity, or undefined when it carries no bindable thread * identity at all. * * The set of requests that produce NO key is deliberately unchanged, through both #4546 and * #4780: a bare `thread-id` with neither a session nor a parent stays unbound, exactly as the * Desktop fallback required both halves of its pair. Only the VALUE moves. * * Every member of one tree resolves to the SAME key, because the cohort is the binding unit * (#4780): * * - root (`session-id` + `thread-id`) -> the session's cohort key; * - child and grandchild (parent + own `thread-id`) -> the same cohort key, since they carry the * same session; * - parent-only (no `thread-id`) -> the same cohort key, derived from the session or, without * one, read from the parent's record. * * THIS IS NOT A REVERT OF #4546 wp8, and reading it as one would flip it straight back. wp8 * fixed a real incoherence: a child keyed under the RAW parent id, which is a different identity * from the root's own `app:HMAC(session, thread)` binding, so siblings shared an entry unrelated * to the root's and a grandchild keying on its own parent landed on a key nobody had ever bound. * A cohort key cannot produce that, because the root's own binding IS the cohort key: there is * one identity for the tree rather than two competing ones. What wp8 additionally gave each * thread -- a binding of its own -- is what #4780 deliberately gives up, and the reason is that * upstream never agreed to it: `prompt_cache_key` is keyed on the session the whole tree shares, * so a proxy that splits the tree makes every split member assert a warm prefix that is cold on * its account. * * The parent-only case keeps the trap it always had. Such a turn belongs to the parent's * conversation, so it must land on the binding the parent is already using. With a session in * hand that is immediate, since both derive the same cohort key. Without one, the recorded key * wins and the parent id anchors the fallback; the raw parent id is never the answer. */ export function codexConversationIdentity( headers: Headers, now = Date.now(), ): CodexConversationIdentity | undefined { const threadId = boundedLineageComponent(headers.get("thread-id")); const sessionId = boundedLineageComponent(headers.get("session-id")); const parentThreadId = boundedLineageComponent(headers.get("x-codex-parent-thread-id")); if (threadId === undefined) { if (parentThreadId === undefined) return undefined; const parentOnlyKey = cohortConversationKey(headers, sessionId, parentThreadId, now); if (parentOnlyKey === undefined) return undefined; return { conversationKey: parentOnlyKey, recordThreadId: parentThreadId, ...(sessionId !== undefined ? { sessionId } : {}), legacyConversationKey: parentThreadId, declaresParent: false, }; } const conversationKey = cohortConversationKey(headers, sessionId, parentThreadId, now); if (conversationKey === undefined) return undefined; return { conversationKey, recordThreadId: threadId, ...(sessionId !== undefined ? { sessionId } : {}), ...(parentThreadId !== undefined ? { parentThreadId } : {}), ...(parentThreadId !== undefined ? { legacyConversationKey: parentThreadId } : {}), declaresParent: parentThreadId !== undefined && parentThreadId !== threadId, }; } /** * Which authenticated caller this request's lineage belongs to. The bearer is never stored; an * unauthenticated (loopback-trusted) request lands in the single local scope. */ export function codexLineageScopeKey(headers: Headers): string { const authorization = headers.get("authorization")?.trim(); if (!authorization) return LOCAL_LINEAGE_SCOPE; return `auth:${createHmac("sha256", CODEX_LINEAGE_KEY) .update("opencodex-lineage-scope-v1\0") .update(authorization) .digest("base64url")}`; } function dropLineageRecord(scope: CodexLineageScope, threadId: string): void { const record = scope.records.get(threadId); if (record === undefined) return; scope.records.delete(threadId); if (scope.threadIdByConversationKey.get(record.conversationKey) === threadId) { scope.threadIdByConversationKey.delete(record.conversationKey); } if (record.parentThreadId === undefined) return; const siblings = scope.childThreadIdsByParent.get(record.parentThreadId); if (siblings === undefined) return; const remaining = siblings.filter(id => id !== threadId); if (remaining.length === 0) scope.childThreadIdsByParent.delete(record.parentThreadId); else scope.childThreadIdsByParent.set(record.parentThreadId, remaining); } /** Records are held in least-recently-used order, so the expired ones are a prefix. */ function pruneLineageScope(scope: CodexLineageScope, now: number): void { for (const [threadId, record] of scope.records) { if (now - record.lastUsedAt <= CODEX_LINEAGE_IDLE_TTL_MS) break; dropLineageRecord(scope, threadId); } while (scope.records.size > CODEX_LINEAGE_MAX_ENTRIES) { const oldest = scope.records.keys().next(); if (oldest.done === true) break; dropLineageRecord(scope, oldest.value); } } function pruneLineageScopes(now: number): void { for (const [scopeKey, scope] of lineageByScope) { if (now - scope.lastUsedAt <= CODEX_LINEAGE_IDLE_TTL_MS) break; lineageByScope.delete(scopeKey); } while (lineageByScope.size > CODEX_LINEAGE_MAX_SCOPES) { const oldest = lineageByScope.keys().next(); if (oldest.done === true) break; lineageByScope.delete(oldest.value); } } function touchLineageScope(scopeKey: string, now: number): CodexLineageScope { const existing = lineageByScope.get(scopeKey); const scope: CodexLineageScope = existing ?? { records: new Map<string, CodexLineageRecord>(), threadIdByConversationKey: new Map<string, string>(), childThreadIdsByParent: new Map<string, string[]>(), lastUsedAt: now, }; if (existing !== undefined) lineageByScope.delete(scopeKey); scope.lastUsedAt = now; lineageByScope.set(scopeKey, scope); pruneLineageScopes(now); pruneLineageScope(scope, now); return scope; } /** * The lineage view for one identity inside one scope, computed without writing anything. * * A parent seen for the first time through one of its children is derived rather than invented: * the child knows the shared session, so HMAC(session, parent) reproduces the key the parent * binds under. Once the parent has actually been recorded, its own key wins. * * Depth is transitive by construction -- a grandchild inherits its parent's resolved root instead * of re-deriving one hop -- so a workflow never scatters across several roots. */ function lineageFor( scope: CodexLineageScope | undefined, identity: CodexConversationIdentity, now: number, ): CodexThreadLineage { const previous = liveLineageRecord(scope, identity.recordThreadId, now); // A turn that omits the parent header does not orphan a thread whose parent is already known. // That retention is the whole of the lineage-backed worker answer below. const parentThreadId = identity.declaresParent ? identity.parentThreadId : previous?.parentThreadId; const parentRecord = parentThreadId !== undefined ? liveLineageRecord(scope, parentThreadId, now) : undefined; const parentConversationKey = parentThreadId === undefined ? undefined : parentRecord?.conversationKey ?? cohortKeyFromAnchor(identity.sessionId, parentThreadId); const rootSessionKey = parentConversationKey === undefined ? identity.conversationKey : parentRecord?.rootSessionKey ?? parentConversationKey; const siblingConversationKeys: string[] = []; if (parentThreadId !== undefined && scope !== undefined) { for (const siblingThreadId of scope.childThreadIdsByParent.get(parentThreadId) ?? []) { if (siblingThreadId === identity.recordThreadId) continue; const sibling = liveLineageRecord(scope, siblingThreadId, now); if (sibling !== undefined) siblingConversationKeys.push(sibling.conversationKey); } } // Only a key the old rule would have produced AND that this request no longer uses is a // migration candidate. A root's key is unchanged, so it never carries one. const legacyConversationKey = identity.legacyConversationKey !== undefined && identity.legacyConversationKey !== identity.conversationKey ? identity.legacyConversationKey : undefined; return { conversationKey: identity.conversationKey, rootSessionKey, ...(parentThreadId !== undefined ? { parentThreadId } : {}), ...(parentConversationKey !== undefined ? { parentConversationKey } : {}), ...(legacyConversationKey !== undefined ? { legacyConversationKey } : {}), siblingConversationKeys, }; } /** * Read this request's lineage without recording it. * * A preview must see what the final resolution will see, but it must not be the thing that * creates the record: preview runs before auth has decided whether this request may hold Pool * state at all, and a record written there would outlive a decision to hold none. */ export function resolveCodexThreadLineage( headers: Headers, now = Date.now(), ): CodexThreadLineage | undefined { const identity = codexConversationIdentity(headers, now); if (identity === undefined) return undefined; return lineageFor(lineageByScope.get(codexLineageScopeKey(headers)), identity, now); } /** Record this request's thread relation and return the resolved lineage. */ export function recordCodexThreadLineage( headers: Headers, now = Date.now(), ): CodexThreadLineage | undefined { const identity = codexConversationIdentity(headers, now); if (identity === undefined) return undefined; const scope = touchLineageScope(codexLineageScopeKey(headers), now); const lineage = lineageFor(scope, identity, now); const parentThreadId = lineage.parentThreadId; // Re-insert rather than mutate: the records map doubles as the LRU order. dropLineageRecord(scope, identity.recordThreadId); scope.records.set(identity.recordThreadId, { threadId: identity.recordThreadId, conversationKey: identity.conversationKey, ...(parentThreadId !== undefined ? { parentThreadId } : {}), rootSessionKey: lineage.rootSessionKey, lastUsedAt: now, }); scope.threadIdByConversationKey.set(identity.conversationKey, identity.recordThreadId); if (parentThreadId !== undefined) { const siblings = (scope.childThreadIdsByParent.get(parentThreadId) ?? []) .filter(id => id !== identity.recordThreadId); siblings.unshift(identity.recordThreadId); scope.childThreadIdsByParent.set(parentThreadId, siblings.slice(0, CODEX_LINEAGE_MAX_SIBLINGS)); } pruneLineageScope(scope, now); return lineage; } /** * Cost-attribution lookup for other layers: which root workflow owns this conversation key. * Scoped like the records, so a caller can only ever resolve inside its own scope, and read-only * -- reading a lineage for accounting must not extend its lifetime. */ export function codexThreadLineageLookup( conversationKey: string, scopeKey: string, now = Date.now(), ): { conversationKey: string; rootSessionKey: string; parentThreadId?: string } | undefined { const scope = lineageByScope.get(scopeKey); if (scope === undefined) return undefined; const threadId = scope.threadIdByConversationKey.get(conversationKey); if (threadId === undefined) return undefined; const record = scope.records.get(threadId); if (record === undefined || now - record.lastUsedAt > CODEX_LINEAGE_IDLE_TTL_MS) return undefined; return { conversationKey: record.conversationKey, rootSessionKey: record.rootSessionKey, ...(record.parentThreadId !== undefined ? { parentThreadId: record.parentThreadId } : {}), }; } /** * The root a request's spend belongs to, for a caller holding headers rather than a key. An * unrecorded conversation is its own root, so this never answers null for a bindable request and * an accounting layer has no reason to invent one. */ export function codexLineageRootForRequest(headers: Headers, now = Date.now()): string | undefined { const identity = codexConversationIdentity(headers, now); if (identity === undefined) return undefined; return codexThreadLineageLookup(identity.conversationKey, codexLineageScopeKey(headers), now) ?.rootSessionKey ?? identity.conversationKey; } /** * The lineage-backed worker/interactive answer. * * Admission classifies header-only today: a request is worker traffic only when it names a parent * AND a distinct `thread-id`, so a fan-out turn that stopped sending the parent header reads as * interactive. This keeps that rule and adds what the headers could not say -- a thread already * recorded with a parent is worker traffic. Nothing here changes admission; a later lane consumes * it. */ export function codexLineageWorkflowLane(headers: Headers, now = Date.now()): CodexWorkflowLane { const threadId = boundedLineageComponent(headers.get("thread-id")); const parentThreadId = boundedLineageComponent(headers.get("x-codex-parent-thread-id")); if (parentThreadId !== undefined && threadId !== undefined && threadId !== parentThreadId) { return "worker"; } if (threadId === undefined) return "interactive"; const record = lineageByScope.get(codexLineageScopeKey(headers))?.records.get(threadId); return record !== undefined && now - record.lastUsedAt <= CODEX_LINEAGE_IDLE_TTL_MS && record.parentThreadId !== undefined ? "worker" : "interactive"; } /** Test-only reset; production state is process-local and dies with the process. */ export function clearCodexThreadLineageForTests(): void { lineageByScope.clear(); }