UNPKG

@bitkyc08/opencodex

Version:

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

150 lines (131 loc) • 7.99 kB
/** * The seam between the Responses pipeline and Remote Link activity holds (design T4 section 5). * * A link turn carries an observer: a link WebSocket passes one in handleResponses options, and every relayed HTTP * Responses request carries a short-lived random token header the link relay registered. The * pipeline reports the expanded input right after continuation expansion and before any upstream * I/O, and the final request log reports the terminal status and whether the terminal came from the * upstream. No content leaves this module: observers hash what they need. Nothing here runs for a * request that carries no observer. * * While the link WebSocket feature is on, an observer also describes the request for the request log * (design T4 section 9.1): its transport and hashed thread and turn refs. This module records the * continuation outcome on the log context as `link`, so the final row carries it. */ import type { LinkContinuationReason, LinkRequestLogCarrier, LinkTransport } from "../usage/link-log-fields"; /** What a link observer contributes to the request log; null when it describes nothing. */ export interface LinkTurnLogFields { transport: LinkTransport; first: boolean; threadRef?: string; turnRef?: string } export interface LinkTurnObserver { /** * The request body after continuation expansion. chain "unexpanded" means previous_response_id was * left for the upstream: the body is only a delta, so it is never a fingerprint and never matches one. */ expanded(body: unknown, chain?: LinkTurnChain): void; /** Expansion failed (continuation miss); a capture cannot be made. */ expansionFailed(): void; /** The turn's final request log: its terminal status, and "synthetic" when the proxy made it. */ terminal(status: string | undefined, source: string | undefined): void; /** Request-log fields; present only while the link WebSocket feature is on. */ logFields?(body: unknown): LinkTurnLogFields | null; /** * Set by every relayed link turn, HTTP or WebSocket, whether or not the link WebSocket feature is on (#8601): the * turn's upstream body is read only as its client drains, so a stalled link reader holds about one upstream chunk * instead of the pipeline's inspection read-ahead. Only logFields depends on the feature switch. */ pacedReads?: boolean; } /** The continuation outcome preparation saw: expanded locally, left for the upstream, or none sent. */ export type LinkTurnChain = "chained" | "unexpanded" | "none"; export const LINK_TURN_HEADER = "x-opencodex-link-turn"; /** A paced link turn's upstream chunks are relayed in slices of at most this size, so each relay stage holds one slice. */ export const LINK_PACED_SLICE_BYTES = 256 * 1024; const byToken = new Map<string, LinkTurnObserver>(); const byLog = new WeakMap<object, LinkTurnObserver>(); /** Contexts that pace for a link turn bound elsewhere (a combo child's); never notified of the terminal. */ const pacingByLog = new WeakMap<object, LinkTurnObserver>(); /** Registers an observer for one relayed request; the caller sets the returned token as LINK_TURN_HEADER. */ export function registerLinkTurnToken(observer: LinkTurnObserver): string { const bytes = new Uint8Array(16); crypto.getRandomValues(bytes); const token = [...bytes].map(byte => byte.toString(16).padStart(2, "0")).join(""); byToken.set(token, observer); return token; } /** Drops a token the pipeline never claimed (a request refused before preparation). */ export function releaseLinkTurnToken(token: string): void { byToken.delete(token); } /** Registered tokens no pipeline has claimed or the relay released yet (bounded by requests in flight). */ export function pendingLinkTurnTokens(): number { return byToken.size; } function claim(explicit: LinkTurnObserver | undefined, req: Request): LinkTurnObserver | undefined { const token = req.headers.get(LINK_TURN_HEADER); if (token !== null) { // Never forwarded: the header exists only between the link relay and this point. try { req.headers.delete(LINK_TURN_HEADER); } catch { /* immutable headers carry nothing further */ } } if (explicit) return explicit; if (!token) return undefined; const observer = byToken.get(token); byToken.delete(token); return observer; } function describe(observer: LinkTurnObserver, logCtx: object, body: unknown, outcome: { continuation: "chained" | "full" | "miss"; reason?: LinkContinuationReason } | ((first: boolean) => { continuation: "full"; reason: LinkContinuationReason })): void { let fields: LinkTurnLogFields | null = null; try { fields = observer.logFields?.(body) ?? null; } catch { fields = null; } if (!fields) return; const resolved = typeof outcome === "function" ? outcome(fields.first) : outcome; (logCtx as LinkRequestLogCarrier).link = { transport: fields.transport, continuation: resolved.continuation, ...(resolved.reason ? { continuationReason: resolved.reason } : {}), ...(fields.threadRef ? { threadRef: fields.threadRef } : {}), ...(fields.turnRef ? { turnRef: fields.turnRef } : {}), }; } /** * Right after continuation expansion succeeded, before upstream I/O. An unexpanded continuation goes * to an upstream that owns the history (chained) unless preparation refuses it (markLinkTurnMissing). */ export function observeLinkTurnExpansion(explicit: LinkTurnObserver | undefined, req: Request, logCtx: object, body: unknown, chain: LinkTurnChain = "none"): void { const observer = claim(explicit, req); if (!observer) return; byLog.set(logCtx, observer); describe(observer, logCtx, body, chain === "none" ? (first: boolean) => ({ continuation: "full" as const, reason: first ? "first" as const : "client" as const }) : { continuation: "chained" }); try { observer.expanded(body, chain); } catch { /* an observer never breaks the turn */ } } /** Continuation expansion failed: a miss with the replay failure's reason. */ export function failLinkTurnExpansion(explicit: LinkTurnObserver | undefined, req: Request, logCtx: object, body?: unknown, reason?: LinkContinuationReason): void { const observer = claim(explicit, req); if (!observer) return; byLog.set(logCtx, observer); describe(observer, logCtx, body, { continuation: "miss", ...(reason ? { reason } : {}) }); try { observer.expansionFailed(); } catch { /* an observer never breaks the turn */ } } /** Preparation refused an unexpanded continuation (the history is nowhere): a miss, reason missing. */ export function markLinkTurnMissing(logCtx: object): void { const link = (logCtx as LinkRequestLogCarrier).link; if (link) (logCtx as LinkRequestLogCarrier).link = { ...link, continuation: "miss", continuationReason: "missing" }; } /** Whether a link turn bound to this context reads its upstream only as its client drains; false for every other request. */ export function linkTurnPacesReads(logCtx: object): boolean { return (byLog.get(logCtx) ?? pacingByLog.get(logCtx))?.pacedReads === true; } /** * A combo child runs the pipeline on a log context of its own, after the combo observed the turn on its parent's. The child * reads its upstream as the parent's link turn does; the terminal notice stays with the parent's final log, so it fires once. */ export function bindLinkTurnChild(parentLogCtx: object, childLogCtx: object): void { const observer = byLog.get(parentLogCtx) ?? pacingByLog.get(parentLogCtx); if (observer) pacingByLog.set(childLogCtx, observer); } /** Called by the final request log of every turn; a no-op unless a link turn bound this context. */ export function notifyLinkTurnFinal(logCtx: object, status: string | undefined): void { const observer = byLog.get(logCtx); if (!observer) return; byLog.delete(logCtx); const source = (logCtx as { terminalSource?: unknown }).terminalSource; try { observer.terminal(status, typeof source === "string" ? source : undefined); } catch { /* never breaks logging */ } }