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