UNPKG

@bitkyc08/opencodex

Version:

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

417 lines (385 loc) • 18.4 kB
/** * Best-effort chat/session correlation for Logs / usage.jsonl (#330). * Opaque ids only — never persist raw emails or Claude Desktop system-hash fallbacks. */ import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto"; import type { OcxConfig } from "../types"; import { resolveContextPrincipal, type DataPlaneAdmission } from "./auth-cors"; /** Reject absurdly long client strings before hashing (DoS / JSONL bloat). */ export const LOG_CONVERSATION_ID_INPUT_MAX = 4096; /** Persisted / filterable form is always a 32-char hex digest. */ export const LOG_CONVERSATION_ID_LEN = 32; function hasControlChars(value: string): boolean { for (let i = 0; i < value.length; i++) { const code = value.charCodeAt(i); if (code <= 0x1f || code === 0x7f) return true; } return false; } function sanitizeConversationIdInput(raw: string | undefined | null): string | undefined { if (typeof raw !== "string") return undefined; const trimmed = raw.trim(); if (!trimmed) return undefined; // Reject control characters that would break JSONL / UI paste. if (hasControlChars(trimmed)) return undefined; if (trimmed.length > LOG_CONVERSATION_ID_INPUT_MAX) return undefined; return trimmed; } /** * Cap / sanitize a correlation id for persistence. * Always hashes so client-controlled headers cannot land emails or short secrets in usage.jsonl. */ export function normalizeLogConversationId(raw: string | undefined | null): string | undefined { const trimmed = sanitizeConversationIdInput(raw); if (!trimmed) return undefined; return createHash("sha256").update(trimmed).digest("hex").slice(0, LOG_CONVERSATION_ID_LEN); } const CODEX_THREAD_LINK_PREFIX = "codex://threads/"; /** Real thread links stay well under this bound; larger pastes skip unwrapping so per-row matching stays cheap. */ const LOG_CONVERSATION_LINK_MAX = 512; /** * Unwrap a pasted `codex://threads/<id>` deep link to the bare thread id. Codex's * "copy session link" clipboard carries that URI form while clients send the bare id * on the wire, so Logs search accepts either paste without changing what is persisted. * Query/fragment metadata (e.g. `?hostId=…`) belongs to the link, not the id, and is * dropped. The scan is a bounded linear walk — no ambiguous regex — because this runs * per log row on every filter evaluation. */ export function unwrapLogConversationQuery(query: string): string { const trimmed = query.trim(); if ( trimmed.length > LOG_CONVERSATION_LINK_MAX || trimmed.length <= CODEX_THREAD_LINK_PREFIX.length || !trimmed.toLowerCase().startsWith(CODEX_THREAD_LINK_PREFIX) ) { return trimmed; } const rest = trimmed.slice(CODEX_THREAD_LINK_PREFIX.length); const metaIndex = rest.search(/[?#]/); const segment = (metaIndex === -1 ? rest : rest.slice(0, metaIndex)).replace(/\/+$/, ""); // A thread id is a single path segment; deeper paths or embedded whitespace keep the // whole paste as the query, so foreign `codex://` URIs still fail to match. return segment !== "" && !/[/\s]/.test(segment) ? segment : trimmed; } /** * The candidate ids a conversation query may legitimately match. Unwrapping a pasted * `codex://threads/<id>` link must add a match path, not replace one: a client can * literally send a `codex://threads/…` session id, which is hashed whole for storage, * so the untouched paste stays a candidate too. */ export function logConversationQueryCandidates(query: string): string[] { const trimmed = query.trim(); const unwrapped = unwrapLogConversationQuery(trimmed); // A pasted Claude Code metadata.user_id is stored without its per-turn `tk`. const session = trimmed.length > LOG_CONVERSATION_ID_INPUT_MAX ? trimmed : claudeSessionUserId(trimmed); return [...new Set([unwrapped, trimmed, session])]; } /** * Filter match: accept either the persisted digest or the original preimage * (so pasting from Logs detail or the client-facing session id both work). */ export function matchesLogConversationId( stored: string | undefined, query: string | undefined | null, ): boolean { if (!stored) return false; for (const candidate of logConversationQueryCandidates(typeof query === "string" ? query : "")) { if (!candidate) continue; if (stored === candidate) return true; const hashed = normalizeLogConversationId(candidate); if (hashed !== undefined && stored === hashed) return true; } return false; } /** * Codex/Claude/Cursor priority for Responses-shaped requests: * parent thread header > session_id / session-id > thread-id > cursor conversation id. */ export function sessionIdHeaderFromRequest(headers: Headers): string | null { return headers.get("session_id") ?? headers.get("session-id"); } /** * Fixed-size logical turn lane (#820). * * A lane must be as SPECIFIC as the identity available. `codexPoolAffinityKey` used to be the * opposite: it preferred the parent thread, so a whole subagent fan-out shared one entry, and a * lane keyed that way would have put every parallel subagent of one parent into a single lane * and rejected all but the first with 503 — the fan-out is the normal case, not an abuse. * Since #4546 affinity keys every thread as ITSELF and reads the parent only as a first-placement * hint, so the two now agree on the unit. They still derive it differently: a lane is a digest an * operator can match against what the client sent, while an affinity key is an opaque HMAC * precisely so no caller-supplied identifier ends up in Pool state. * * The parent stays a QUALIFIER here, never the lane on its own when a child thread exists: the * pair separates siblings while still keeping one conversation's overlapping turns together. */ export function sessionLaneIdFromRequest(headers: Headers): string | undefined { const parent = normalizeLogConversationId(headers.get("x-codex-parent-thread-id")); const thread = normalizeLogConversationId(headers.get("thread-id")); const session = normalizeLogConversationId(sessionIdHeaderFromRequest(headers)); const specific = thread ?? session; if (parent && specific) return `${parent}\u0000${specific}`; return specific ?? parent; } /** * The affinity lane a request binds under, derived once so every entry path agrees. * * `sessionLaneIdFromRequest` first (explicit thread/session/parent identity), then the * explicit `x-opencode-session` header the Claude-Go handoff and * `getOrAllocateRequestSessionLane` already treat as lane identity, then the log * conversation id — except the Hermes digest, which is log correlation only and must * never affect lanes or routing (#330). This expression used to be inlined at four * entry paths and drifted: three of the four missed the `x-opencode-session` fallback * until PR #7738 aligned them. * * Scope authenticated lanes to the admitted principal with a process-local HMAC. A translated * request carries the principal captured before its caller credential was stripped. Loopback * without a recognized credential retains the existing local lane; an authenticated admission * without a principal cannot bind. The distinct prefix prevents local lanes from colliding. */ const AFFINITY_SCOPE_KEY = randomBytes(32); export function affinityLaneFromRequest( req: Request, slot: LogConversationSlot, config: OcxConfig, admission?: DataPlaneAdmission, capturedPrincipal?: Readonly<{ clientPrincipalId: string | undefined }>, ): string | undefined { const lane = sessionLaneIdFromRequest(req.headers) ?? normalizeLogConversationId(req.headers.get("x-opencode-session")) ?? (slot.conversationIdIsHermesFallback ? undefined : normalizeLogConversationId(slot.conversationId)); if (!lane) return undefined; const principal = capturedPrincipal ? capturedPrincipal.clientPrincipalId : resolveContextPrincipal(req, config, admission); if (principal) return `principal:${createHmac("sha256", AFFINITY_SCOPE_KEY).update(JSON.stringify([principal, lane])).digest("hex")}`; // An authenticated admission with no identity must not join any other caller's lane. if (admission && admission.kind !== "loopback") return undefined; return lane; } function firstSanitizedConversationId( ...values: Array<string | null | undefined> ): string | undefined { for (const value of values) { const sanitized = sanitizeConversationIdInput(value); if (sanitized) return sanitized; } return undefined; } /** * Conversation namespace for reasoning replay. Unlike the persisted log id, this stays the raw * sanitized identity so mixed headers that carry the same conversation still hit one serving * record. The request's own thread-id precedes the parent routing identity: a child agent sends * both, and letting it resolve to the parent's record lets a successful child route overwrite * the parent's serving provenance, which strips the parent's replayed thinking signatures on its * next turn (#8632). The parent header stays the fallback for callers that only carry it. * Do not hash, and do not prefer session_id over a true per-conversation thread/Cursor * identity: session_id can be synthesized from a shared prompt_cache_key. */ export function reasoningReplayConversationIdFromResponsesRequest(input: { clientThreadId?: string; threadIdHeader?: string | null; cursorConversationId?: string; sessionIdHeader?: string | null; }): string | undefined { return firstSanitizedConversationId( input.threadIdHeader, input.clientThreadId, input.cursorConversationId, input.sessionIdHeader, ); } export function conversationIdFromResponsesRequest(input: { clientThreadId?: string; sessionIdHeader?: string | null; threadIdHeader?: string | null; cursorConversationId?: string; }): string | undefined { return normalizeLogConversationId( input.clientThreadId ?? input.sessionIdHeader ?? input.threadIdHeader ?? input.cursorConversationId, ); } /** * Hermes Agent session affinity header for log correlation (#330). * Kept separate from runtime/session identities so it cannot affect lanes or routing. */ export function conversationIdFromHermesHeader(headers: Headers): string | undefined { return normalizeLogConversationId(headers.get("x-hermes-conversation-id")); } /** * Validates and normalizes native header candidates in priority order for logging: * parent-thread -> session_id -> session-id -> thread-id. * Each candidate spelling is evaluated and normalized independently so an empty or * whitespace-only candidate (e.g. empty session_id) cannot suppress a subsequent valid candidate. */ export function nativeLogConversationIdFromHeaders(headers: Headers): string | undefined { return ( normalizeLogConversationId(headers.get("x-codex-parent-thread-id")) ?? normalizeLogConversationId(headers.get("session_id")) ?? normalizeLogConversationId(headers.get("session-id")) ?? normalizeLogConversationId(headers.get("thread-id")) ); } /** The request-log context's conversation slot; structural so callers need not import request-log. */ export interface LogConversationSlot { conversationId?: string; conversationIdIsHermesFallback?: boolean; } /** * Record a native log identity. Fills an empty slot or replaces the log-only Hermes fallback, * so a native id found late (Responses preparation, a Cursor conversation created mid-turn) * still wins. A caller-owned id already in the slot (routed Claude metadata) is kept. */ export function assignNativeLogConversationId(slot: LogConversationSlot, nativeId: string | undefined): void { if (!nativeId || (slot.conversationId && !slot.conversationIdIsHermesFallback)) return; slot.conversationId = nativeId; delete slot.conversationIdIsHermesFallback; } /** Fill an empty slot with the log-only Hermes digest, marked so any native id replaces it. */ export function fillHermesLogConversationFallback(slot: LogConversationSlot, headers: Headers): void { if (slot.conversationId) return; const hermes = conversationIdFromHermesHeader(headers); if (!hermes) return; slot.conversationId = hermes; slot.conversationIdIsHermesFallback = true; } /** * Remote Claude Code adds a per-turn attribution token (`tk`) to its metadata.user_id JSON * blob. Drop it, as Claude Code itself does, so every turn of one session keeps one identity. * Any other user_id, including one that is nothing but `tk`, is returned unchanged. */ export function claudeSessionUserId(userId: string): string { if (!userId.trimStart().startsWith("{")) return userId; try { const parsed: unknown = JSON.parse(userId); if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && "tk" in parsed) { const { tk: _tk, ...rest } = parsed as Record<string, unknown>; if (Object.keys(rest).length > 0) return JSON.stringify(rest); } } catch { /* not JSON */ } return userId; } /** * Claude Code metadata.user_id only — never the system-hash Desktop fallback. * Hashes the session's user_id once (same opacity goal as inbound prompt_cache_key). */ export function conversationIdFromClaudeMetadata( metadata: { user_id?: unknown } | null | undefined, ): string | undefined { if (!metadata || typeof metadata.user_id !== "string") return undefined; // No length guard before stripping tk: an oversized tk still leaves a valid session id, // which also gates Claude routing identity (claude-messages.ts claudeNativeSessionId). return normalizeLogConversationId(claudeSessionUserId(metadata.user_id)); } /** @deprecated Prefer conversationIdFromClaudeMetadata; kept for call-site clarity. */ export function conversationIdFromClaudeCacheKey( cacheKeySource: "metadata" | "system" | null | undefined, promptCacheKey: string | undefined, ): string | undefined { if (cacheKeySource !== "metadata") return undefined; // prompt_cache_key is already sha256(user_id)[:32] from inbound — persist as-is // (do not re-hash) so native and translated paths stay aligned when callers pass // the preimage via conversationIdFromClaudeMetadata instead. const trimmed = sanitizeConversationIdInput(promptCacheKey); if (!trimmed) return undefined; if (trimmed.length === LOG_CONVERSATION_ID_LEN && /^[0-9a-f]+$/i.test(trimmed)) return trimmed.toLowerCase(); return normalizeLogConversationId(trimmed); } export interface ConversationLogTotals { requests: number; totalTokens: number; estimatedCostUsd: number; pricedRequests: number; unpricedRequests: number; unmeteredRequests: number; } type TotalsSource = { totalTokens?: number; usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number }; usageStatus?: string; displayMetrics?: { cost?: | { kind: "value"; estimate: { cost: { total: number } } } | { kind: "unavailable"; reason: string }; }; }; function rowTokenTotal(entry: TotalsSource): number | undefined { if (typeof entry.totalTokens === "number" && Number.isFinite(entry.totalTokens) && entry.totalTokens >= 0) { return entry.totalTokens; } const usageTotal = entry.usage?.totalTokens; if (typeof usageTotal === "number" && Number.isFinite(usageTotal) && usageTotal >= 0) return usageTotal; const input = entry.usage?.inputTokens; const output = entry.usage?.outputTokens; if (typeof input === "number" && typeof output === "number" && Number.isFinite(input) && Number.isFinite(output)) { return Math.max(0, input) + Math.max(0, output); } return undefined; } /** Sum tokens/cost for the currently loaded log slice matching a conversation filter. */ export function summarizeConversationLogs(entries: readonly TotalsSource[]): ConversationLogTotals { let totalTokens = 0; let estimatedCostUsd = 0; let pricedRequests = 0; let unpricedRequests = 0; let unmeteredRequests = 0; for (const entry of entries) { const tokens = rowTokenTotal(entry); if (tokens !== undefined) totalTokens += tokens; if (entry.usageStatus === "unsupported") { unmeteredRequests += 1; continue; } const cost = entry.displayMetrics?.cost; if (cost?.kind === "value" && Number.isFinite(cost.estimate.cost.total) && cost.estimate.cost.total >= 0) { estimatedCostUsd += cost.estimate.cost.total; pricedRequests += 1; continue; } unpricedRequests += 1; } return { requests: entries.length, totalTokens, estimatedCostUsd, pricedRequests, unpricedRequests, unmeteredRequests, }; } /** * Request-scoped Go affinity for requests that carry no conversation identity. * * A sessionless request must still reach OpenCode Go with `x-opencode-session`, because the upstream * began rejecting requests without it on 2026-09-06. It must not reuse one global value either, which * would smear unrelated probes into a single conversation. So the lane is allocated once per admitted * `Request` object and retained for that object's lifetime. * * The identity has to survive every place the proxy rebuilds a `Request`: translation to the internal * Responses shape, compaction, and — the boundary that matters most — the policy fallback retry, where * a second candidate would otherwise be handed a freshly minted lane after a retryable failure. * `linkRequestSessionLane` carries the allocation across those boundaries. */ const requestAllocatedSessionLanes = new WeakMap<Request, string>(); /** * Resolve the session lane for a request: real conversation identity when the client supplied it, * otherwise a per-request value allocated once and reused for retries on the same object. */ export function getOrAllocateRequestSessionLane(req: Request): string { const explicit = sessionLaneIdFromRequest(req.headers) ?? normalizeLogConversationId(req.headers.get("x-opencode-session")); if (explicit) return explicit; const existing = requestAllocatedSessionLanes.get(req); if (existing) return existing; const allocated = randomUUID(); requestAllocatedSessionLanes.set(req, allocated); return allocated; } /** * Carry a source request's lane onto a request the proxy built from it, so a rebuilt request keeps * the conversation it belongs to instead of looking sessionless again. */ export function linkRequestSessionLane(sourceReq: Request, targetReq: Request): void { requestAllocatedSessionLanes.set(targetReq, getOrAllocateRequestSessionLane(sourceReq)); }