UNPKG

@bitkyc08/opencodex

Version:

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

376 lines (348 loc) • 14.1 kB
/** * Observed protocol path for one request (PF-02). * * SERVER SIDE: the dashboard never imports this file; it reads the finished `ProtocolTraceV1` * through `dto.ts`. Marks live in WeakMaps keyed by the request log context and by the live * attempt objects, so neither `RequestLogContext` nor the persisted attempt row grows a field, * and a context that is never finalized takes its marks with it. * * Every function here is side-effect free apart from its own WeakMap and never throws into the * request path: a trace is diagnostics, and a request must not fail because its trace could not * be recorded. Nothing conversation-derived is kept — only fixed vocabulary. * * Shadow plan (PF-12): when `protocols.rollout.shadowPlan` is on, the ingress records the * dispatch-basis plan input for the request (`src/protocols/shadow-plan.ts`); at finalize the * plan is computed with the pure planner and compared with the observed trace, and a * disagreement sets `planMismatch`. Nothing is recorded with the switch off, so the trace is * unchanged, and a failed comparison leaves the trace as observed. */ import { PROTOCOL_CONTRACT_VERSION, isProtocolReasonCode, upstreamWireForAdapter, type DeliveryMode, type Protocol, type ProtocolHop, type ProtocolReasonCode, type UpstreamWire, } from "./contract"; import { PROTOCOL_DTO_LIMITS, PROTOCOL_TRACE_SCHEMA_VERSION, type ProtocolAttemptTraceV1, type ProtocolTraceV1 } from "./dto"; import { featureEffectsForPath, isProtocolFeature, type ProtocolFeature } from "./features"; import { deliveryModeForLane, requestPathForLane, responsePathForLane, type ProtocolLane } from "./path"; import { planProtocol, type ProtocolPlanInput } from "./plan"; import { shadowPlanMismatch } from "./shadow"; /** Features are computed inside the mark, so a thrown feature scan is contained there too. */ export type ProtocolFeatureSource = Iterable<ProtocolFeature> | (() => Iterable<ProtocolFeature>); interface EntryMark { kind: "entry"; inbound: Protocol; lane: ProtocolLane; reasonCodes: ProtocolReasonCode[]; features: ProtocolFeature[]; } interface BlockedMark { kind: "blocked"; inbound: Protocol; reasonCodes: ProtocolReasonCode[]; features: ProtocolFeature[]; } interface AttemptMark { mode: Exclude<DeliveryMode, "blocked">; requestPath: ProtocolHop[]; responsePath?: ProtocolHop[]; } /** The attempt fields the trace reads. `PersistedUsageAttempt` satisfies it. */ export interface ProtocolTraceAttempt { ordinal: number; adapter: string; } const requestMarks = new WeakMap<object, EntryMark | BlockedMark | { kind: "gemini-native" }>(); const attemptMarks = new WeakMap<object, AttemptMark>(); const shadowInputs = new WeakMap<object, ProtocolPlanInput>(); const suppressedContexts = new WeakSet<object>(); /** Suppress diagnostics for an internal protocol bridge while preserving request behavior. */ export function suppressProtocolTrace(logCtx: object): void { suppressedContexts.add(logCtx); requestMarks.delete(logCtx); shadowInputs.delete(logCtx); } export function protocolTraceSuppressed(logCtx: object): boolean { return suppressedContexts.has(logCtx); } function boundedReasons(codes: Iterable<ProtocolReasonCode>): ProtocolReasonCode[] { const out: ProtocolReasonCode[] = []; for (const code of codes) { if (!isProtocolReasonCode(code) || out.includes(code)) continue; out.push(code); if (out.length >= PROTOCOL_DTO_LIMITS.reasonCodes) break; } return out; } function collectFeatures(source: ProtocolFeatureSource | undefined): ProtocolFeature[] { if (source === undefined) return []; const iterable = typeof source === "function" ? source() : source; const out: ProtocolFeature[] = []; for (const feature of iterable) { if (isProtocolFeature(feature) && !out.includes(feature)) out.push(feature); if (out.length >= PROTOCOL_DTO_LIMITS.featureEffects) break; } return out; } /** * Record which lane a Chat or Messages ingress chose. A later mark replaces an earlier one: * the last decision before the send is the one that describes it. */ export function markProtocolEntry( logCtx: object, mark: { inbound: Protocol; lane: ProtocolLane; reasonCodes?: Iterable<ProtocolReasonCode>; features?: ProtocolFeatureSource }, ): void { if (protocolTraceSuppressed(logCtx)) return; try { requestMarks.set(logCtx, { kind: "entry", inbound: mark.inbound, lane: mark.lane, reasonCodes: boundedReasons(mark.reasonCodes ?? []), features: collectFeatures(mark.features), }); } catch { /* a trace must never fail the request it describes */ } } /** Record an actual native Gemini send without inspecting the payload. */ export function markNativeGeminiProtocol(logCtx: object): void { if (protocolTraceSuppressed(logCtx)) return; try { requestMarks.set(logCtx, { kind: "gemini-native" }); } catch { /* a trace must never fail the request it describes */ } } /** Features the request's entry or blocked mark recorded, for the shadow plan input. */ export function protocolMarkFeatures(logCtx: object): readonly ProtocolFeature[] | undefined { if (protocolTraceSuppressed(logCtx)) return undefined; try { const mark = requestMarks.get(logCtx); return mark && mark.kind !== "gemini-native" ? [...mark.features] : undefined; } catch { return undefined; } } /** * Record the dispatch-basis plan input the shadow comparison runs at finalize. The input holds * fixed vocabulary and the provider and model names the server already exposes, nothing else. */ export function markProtocolShadowPlanInput(logCtx: object, input: ProtocolPlanInput): void { if (protocolTraceSuppressed(logCtx)) return; try { shadowInputs.set(logCtx, input); } catch { /* a trace must never fail the request it describes */ } } /** Record a refusal made before any upstream send. */ export function markProtocolBlocked( logCtx: object, mark: { inbound: Protocol; reasonCodes: Iterable<ProtocolReasonCode>; features?: ProtocolFeatureSource }, ): void { if (protocolTraceSuppressed(logCtx)) return; try { requestMarks.set(logCtx, { kind: "blocked", inbound: mark.inbound, reasonCodes: boundedReasons(mark.reasonCodes), features: collectFeatures(mark.features), }); } catch { /* a trace must never fail the request it describes */ } } /** * Add a reason to the request's entry mark: a combo candidate skipped before any send (PF-07). * No-op without an entry mark, and a blocked mark is never reopened. */ export function addProtocolEntryReason(logCtx: object, code: ProtocolReasonCode): void { if (protocolTraceSuppressed(logCtx)) return; try { const mark = requestMarks.get(logCtx); if (mark?.kind !== "entry") return; mark.reasonCodes = boundedReasons([...mark.reasonCodes, code]); } catch { /* a trace must never fail the request it describes */ } } /** * Record the path one physical attempt actually took, overriding the lane-derived one. For a * send site that knows its path better than the ingress lane does. */ export function markAttemptProtocolPath( attempt: object, mark: { mode: Exclude<DeliveryMode, "blocked">; requestPath: readonly ProtocolHop[]; responsePath?: readonly ProtocolHop[] }, ): void { try { if (mark.requestPath.length === 0 || mark.requestPath.length > PROTOCOL_DTO_LIMITS.pathHops) return; const responsePath = mark.responsePath && mark.responsePath.length > 0 && mark.responsePath.length <= PROTOCOL_DTO_LIMITS.pathHops ? [...mark.responsePath] : undefined; attemptMarks.set(attempt, { mode: mark.mode, requestPath: [...mark.requestPath], ...(responsePath ? { responsePath } : {}), }); } catch { /* a trace must never fail the request it describes */ } } function isReverse(a: readonly ProtocolHop[], b: readonly ProtocolHop[]): boolean { return a.length === b.length && a.every((hop, index) => hop === b[b.length - 1 - index]); } interface ResolvedPath { upstream: UpstreamWire; mode: Exclude<DeliveryMode, "blocked">; requestPath: ProtocolHop[]; responsePath: ProtocolHop[]; } function pathFor(inbound: Protocol, lane: ProtocolLane, upstream: UpstreamWire): ResolvedPath { return { upstream, mode: deliveryModeForLane(inbound, lane, upstream), requestPath: requestPathForLane(inbound, lane, upstream), responsePath: responsePathForLane(inbound, lane, upstream), }; } function attemptPath(inbound: Protocol, lane: ProtocolLane, attempt: ProtocolTraceAttempt): ResolvedPath { // A native Chat or Messages lane sends the ingress wire itself, whatever the adapter id says; // Responses has no lane and follows its adapter. const upstream = lane === "native" && inbound !== "responses" ? inbound : upstreamWireForAdapter(attempt.adapter); const derived = pathFor(inbound, lane, upstream); const mark = attemptMarks.get(attempt); if (!mark) return derived; return { upstream, mode: mark.mode, requestPath: [...mark.requestPath], responsePath: mark.responsePath ? [...mark.responsePath] : [...mark.requestPath].reverse(), }; } /** A reason code the path itself implies, so a trace is never reason-less. */ function pathReason(path: ResolvedPath): ProtocolReasonCode { if (path.upstream === "other") return "upstream-other"; if (path.mode === "native") return "same-wire-native"; if (path.mode === "legacy-bridge") return "not-migrated"; return path.requestPath.includes("ir") ? "cross-wire-ir" : "cross-wire-codec"; } /** The context fields the trace reads at finalize. */ export type ProtocolTraceContext = object & { inboundProtocol?: Protocol; provider?: string; model?: string }; /** * Derive the observed trace at finalize. `attempts` are the live attempt objects (the ones * `markAttemptProtocolPath` was keyed by), not detached copies. * * - blocked mark: `blocked`, empty paths. * - Responses inbound without a mark: the final adapter's wire decides the path. * - Chat or Messages: the entry lane decides, through `path.ts`. * - no attempt and no native or blocked mark: `undefined`; nothing is guessed. * * With a shadow plan input recorded, a disagreeing plan adds `planMismatch: true`. */ export function protocolTraceForRequest( logCtx: ProtocolTraceContext, attempts: readonly ProtocolTraceAttempt[] | undefined, ): ProtocolTraceV1 | undefined { if (protocolTraceSuppressed(logCtx)) return undefined; const trace = observedTrace(logCtx, attempts); return trace ? withShadowPlan(logCtx, trace) : undefined; } /** * Compare the recorded dispatch plan with the observed trace. Pure and local: the planner reads * only the recorded input. Any throw leaves the observed trace as it was. */ function withShadowPlan(logCtx: ProtocolTraceContext, trace: ProtocolTraceV1): ProtocolTraceV1 { try { const input = shadowInputs.get(logCtx); if (!input) return trace; const settled = { ...(typeof logCtx.provider === "string" ? { provider: logCtx.provider } : {}), ...(typeof logCtx.model === "string" ? { model: logCtx.model } : {}), }; return shadowPlanMismatch(planProtocol(input), trace, settled) ? { ...trace, planMismatch: true } : trace; } catch { return trace; } } function observedTrace( logCtx: ProtocolTraceContext, attempts: readonly ProtocolTraceAttempt[] | undefined, ): ProtocolTraceV1 | undefined { try { const mark = requestMarks.get(logCtx); if (mark?.kind === "gemini-native") { return { v: PROTOCOL_TRACE_SCHEMA_VERSION, inbound: "gemini", upstream: "gemini", mode: "native", requestPath: ["gemini", "gemini"], responsePath: ["gemini", "gemini"], reasonCodes: ["same-wire-native"], contractVersion: PROTOCOL_CONTRACT_VERSION, }; } if (mark?.kind === "blocked") { return { v: PROTOCOL_TRACE_SCHEMA_VERSION, inbound: mark.inbound, mode: "blocked", requestPath: [], responsePath: [], reasonCodes: mark.reasonCodes, contractVersion: PROTOCOL_CONTRACT_VERSION, }; } let inbound: Protocol; let lane: ProtocolLane; if (mark) { inbound = mark.inbound; lane = mark.lane; } else if (logCtx.inboundProtocol === "responses") { inbound = "responses"; lane = "native"; } else { return undefined; } const live = (attempts ?? []).filter(attempt => Number.isInteger(attempt.ordinal) && attempt.ordinal > 0); const kept = live.slice(-PROTOCOL_DTO_LIMITS.attempts); const attemptPaths = kept.map(attempt => ({ attempt, path: attemptPath(inbound, lane, attempt) })); let final: ResolvedPath; const last = attemptPaths.at(-1); if (last) final = last.path; else if (mark && lane === "native") final = pathFor(inbound, lane, inbound); else return undefined; const reasonCodes = boundedReasons([...(mark?.reasonCodes ?? []), pathReason(final)]); const features = mark?.features ?? []; const effects = features.length > 0 ? featureEffectsForPath(inbound, final.requestPath, features).effects.slice(0, PROTOCOL_DTO_LIMITS.featureEffects) : []; const attemptTraces: ProtocolAttemptTraceV1[] = attemptPaths.map(({ attempt, path }) => ({ ordinal: attempt.ordinal, upstream: path.upstream, mode: path.mode, requestPath: path.requestPath, ...(isReverse(path.requestPath, path.responsePath) ? {} : { responsePath: path.responsePath }), })); return { v: PROTOCOL_TRACE_SCHEMA_VERSION, inbound, mode: final.mode, upstream: final.upstream, requestPath: final.requestPath, responsePath: final.responsePath, reasonCodes, ...(effects.length > 0 ? { featureEffects: effects.map(effect => ({ ...effect })) } : {}), ...(attemptTraces.length > 0 ? { attempts: attemptTraces } : {}), contractVersion: PROTOCOL_CONTRACT_VERSION, }; } catch { return undefined; } }