UNPKG

@bitkyc08/opencodex

Version:

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

302 lines (295 loc) • 19.1 kB
import { CodexWsCorrelation } from "./codex-ws-correlation"; import { NativeSteeringError } from "./native-steering"; import { checkOutboundBodySize } from "./outbound-body-guard"; import type { NativeResponseControl } from "./native-response-control"; import type { NativeSteeringReplayObserver } from "./native-steering-replay"; import { UNDECLARED_TOOL_CALL_ERROR_CODE, undeclaredToolCallMessage, undeclaredToolCallNameInResponse, } from "../responses-undeclared-tool-guard"; import type { ProviderExecutedCallType } from "../responses-undeclared-tool-guard"; import { injectionError, injectionFingerprint, injectionId, injectionRecord as record, injectionResults, isInjectionRequest, MAX_NATIVE_INJECTIONS, MAX_NATIVE_INJECTION_BYTES, MAX_NATIVE_INJECTION_CALLS, NATIVE_INJECTION_ACK_MS, NATIVE_INJECTION_TOOL_MS, type FunctionResult, type InjectionFrame as Frame, } from "./native-injection-protocol"; import { nativeResultKey, nativeResultMatches, nativeResultFingerprint, nativeSavedResults, nativeToolRequirement, type NativeToolRequirement } from "./native-tool-results"; type Call = { requirement: NativeToolRequirement; state: "available" | "queued" | "accepted" | "failed"; result?: string; recoverable?: boolean }; type Submission = { frame: Frame; results: FunctionResult[]; bytes: number }; const ENVELOPE = new Set(["type", "input", "previous_response_id", "stream", "stream_id"]); /** * Injection-only multi-agent owner. Exactly one injection is on the physical wire * at a time because created acknowledgements contain a response ID, not a request * ID. Queued submissions, terminal delivery and caller-owned recovery are distinct. */ export class NativeInjectionChannel implements NativeResponseControl { readonly kind = "injection" as const; relayActive = false; replayFactory?: () => NativeSteeringReplayObserver; private replay?: NativeSteeringReplayObserver; private send?: (frame: Frame) => void; private onFailure?: (error: Error) => void; private currentId?: string; private correlation?: CodexWsCorrelation; private terminal?: Frame; private terminalRecorded = false; private continuationSent = false; private finished = false; private everAttached = false; private readonly seen = new Set<string>(); private readonly calls = new Map<string, Call>(); private callBytes = 0; private readonly queue: Submission[] = []; private queueBytes = 0; private inFlight?: Submission; private lastAckSequence = -1; private ackTimer?: ReturnType<typeof setTimeout>; private idleTimer?: ReturnType<typeof setTimeout>; private readonly settings = new Map<string, string>(); private declaredToolNames?: ReadonlySet<string>; private declaredBareToolNames: ReadonlySet<string> = new Set(); private declaredNamelessCallTypes: ReadonlySet<string> = new Set(); private providerExecutedCallTypes: ReadonlySet<ProviderExecutedCallType> = new Set(); private readonly lane: unknown; /** Pin the original settings and lane; construction never opens a connection. */ constructor(initial: Frame, private readonly idleMs = 300_000, private readonly maxUpstreamBodyBytes?: number, private readonly deadlines = { ackMs: NATIVE_INJECTION_ACK_MS, toolMs: NATIVE_INJECTION_TOOL_MS }) { if (!isInjectionRequest(initial)) injectionError("injection_not_supported", "Native injection requires explicit multi_agent.enabled."); this.lane = initial.stream_id ?? undefined; for (const [key, value] of Object.entries(initial)) if (!ENVELOPE.has(key)) this.settings.set(key, injectionFingerprint(value)); } /** Refuse the exact rebuilt control body before it reaches the retained socket. */ assertOutboundFrame(text: string): void { if (!checkOutboundBodySize(text, this.maxUpstreamBodyBytes).admitted) { injectionError("outbound_body_too_large", "Native injection frame exceeds the configured upstream body limit."); } } /** Report that the real dispatch boundary has selected this owner. */ get attached(): boolean { return this.everAttached; } /** A terminal is not final until submitted results have acknowledgements. */ get ended(): boolean { return this.finished; } /** Mirror the ordinary response guard for native events that bypass its SSE rewrite. */ configureToolAuthorization(active: boolean, names: ReadonlySet<string>, bareNames: ReadonlySet<string>, namelessCallTypes: ReadonlySet<string>, providerExecuted: ReadonlySet<ProviderExecutedCallType>): void { this.declaredToolNames = active ? new Set(names) : undefined; this.declaredBareToolNames = active ? new Set(bareNames) : new Set(); this.declaredNamelessCallTypes = active ? new Set(namelessCallTypes) : new Set(); this.providerExecutedCallTypes = active ? new Set(providerExecuted) : new Set(); } /** Attach once, after routing/auth/admission, retaining no global response-ID lookup. */ attach(send: (frame: Frame) => void, fail: (error: Error) => void): () => void { if (this.everAttached) throw new Error("Native injection transport is already owned."); this.replay = this.replayFactory?.(); this.send = send; this.onFailure = fail; this.everAttached = true; return () => { if (this.send !== send) return; this.send = undefined; this.onFailure = undefined; this.finished = true; clearTimeout(this.ackTimer); clearTimeout(this.idleTimer); this.correlation?.finish(); this.calls.clear(); this.seen.clear(); this.queue.length = 0; this.inFlight = undefined; this.queueBytes = 0; this.callBytes = 0; this.terminal = undefined; this.replay?.dispose(); this.replay = undefined; }; } /** Never reinterpret user steering as a function result, or silently mix beta modes. */ steer(_frame: Frame): never { return injectionError("native_control_mode_mismatch", "This multi-agent turn owns an injection-only channel; start a separate turn for steering."); } /** Abort unknown-delivery state without HTTP fallback, resends or invented acceptance. */ private fail(error?: Error): void { this.finished = true; clearTimeout(this.ackTimer); clearTimeout(this.idleTimer); this.onFailure?.(error ?? new Error("Native injection transport failed or timed out; delivery is unknown. Do not automatically resend or rerun tools.")); } /** Require the same live owner; an unbound or detached channel cannot authorize a send. */ private live(): void { if (!this.send || this.finished) injectionError("injection_not_supported", "No live native injection transport is available on this route."); } private authorize(item: unknown): void { if (!this.declaredToolNames) return; const undeclared = undeclaredToolCallNameInResponse( { output: [item] }, this.declaredToolNames, this.declaredNamelessCallTypes, this.providerExecutedCallTypes, this.declaredBareToolNames, ); if (undeclared !== undefined) { injectionError(UNDECLARED_TOOL_CALL_ERROR_CODE, undeclaredToolCallMessage(undeclared)); } } /** Advertise client-owned function/custom calls and approvals, never hosted execution. */ private advertise(item: unknown): void { this.authorize(item); const requirement = nativeToolRequirement(item); if (!requirement) return; const old = this.calls.get(requirement.key); if (old) { if (old.requirement.identity !== requirement.identity) throw new Error("Native result call identity was reused."); return; } const bytes = Buffer.byteLength(JSON.stringify(requirement)); if (this.calls.size >= MAX_NATIVE_INJECTION_CALLS || this.callBytes + bytes > 256 * 1024) throw new Error("Native injection call budget exceeded."); this.calls.set(requirement.key, { requirement, state: "available" }); this.callBytes += bytes; } /** Queue validated saved results; reserve each call before any possibly synchronous send. */ inject(frame: Frame): void { this.live(); if (frame.type !== "response.inject" || !injectionId(frame.response_id) || Object.keys(frame).some(key => !["type", "response_id", "input", "stream_id"].includes(key))) { injectionError("invalid_injection", "Invalid native injection envelope."); } if (frame.response_id !== this.currentId || (frame.stream_id ?? undefined) !== this.lane || this.continuationSent) { injectionError("injection_response_mismatch", "Injection must target the current response and lane on this connection."); } const results = injectionResults(frame.input); for (const item of results) { const call = this.calls.get(nativeResultKey(item)); if (!call || !nativeResultMatches(item, call.requirement)) injectionError("injection_call_not_found", "The result does not match a completed function call on this connection."); if (call.state !== "available") injectionError("duplicate_injection", "This function result was already submitted; do not replay it."); } const text = JSON.stringify(frame); this.assertOutboundFrame(text); const bytes = Buffer.byteLength(text); if (this.queue.length >= MAX_NATIVE_INJECTIONS || bytes + this.queueBytes > MAX_NATIVE_INJECTION_BYTES) { injectionError("injection_queue_full", "Native injection queue count or byte limit reached; no result was sent."); } // Detach from caller-owned objects before keeping data across asynchronous callbacks. const copy = JSON.parse(text) as Frame; const submission = { frame: copy, results: copy.input as FunctionResult[], bytes }; for (const item of results) this.calls.get(nativeResultKey(item))!.state = "queued"; this.queue.push(submission); this.queueBytes += bytes; this.pump(); } /** Dispatch one queued frame; unrelated output cannot reset its acknowledgement deadline. */ private pump(): void { if (this.inFlight || !this.queue.length || this.finished) return; this.live(); const submission = this.queue[0]; this.inFlight = submission; this.ackTimer = setTimeout(() => this.fail(), this.deadlines.ackMs); this.ackTimer.unref?.(); let rollback: (() => void) | undefined; try { rollback = this.replay?.submitted(submission.frame); this.send!(submission.frame); } catch (error) { if (error instanceof NativeSteeringError) { // A typed refusal is a known non-delivery: unjournal and free the reservation // so a corrected result can be queued again on the same channel. rollback?.(); clearTimeout(this.ackTimer); this.ackTimer = undefined; this.inFlight = undefined; this.queue.shift(); this.queueBytes -= submission.bytes; for (const item of submission.results) { const call = this.calls.get(nativeResultKey(item)); if (call?.state === "queued") call.state = "available"; } throw error; } this.fail(); injectionError("injection_delivery_unknown", "Injection dispatch failed; do not automatically resend or rerun tools."); } } /** Match an acknowledgement to the sole in-flight frame, before releasing the next send. */ private acknowledge(event: Frame): void { const pending = this.inFlight; if (!pending || event.response_id !== this.currentId || !Number.isSafeInteger(event.sequence_number) || (event.sequence_number as number) <= this.lastAckSequence) throw new Error("Native injection acknowledgement identity mismatch."); const failed = event.type === "response.inject.failed"; if (failed && (!record(event.error) || typeof event.error.code !== "string" || injectionFingerprint(event.input) !== injectionFingerprint(pending.results))) throw new Error("Native injection rejection does not match submitted results."); this.replay?.observe(event); this.lastAckSequence = event.sequence_number as number; for (const item of pending.results) { const call = this.calls.get(nativeResultKey(item))!; call.state = failed ? "failed" : "accepted"; // Retain a digest, not another result body, for an explicitly rejected continuation. call.recoverable = failed && record(event.error) && event.error.code === "response_already_completed"; if (call.recoverable) call.result = nativeResultFingerprint(item); } clearTimeout(this.ackTimer); this.ackTimer = undefined; this.inFlight = undefined; this.queue.shift(); this.queueBytes -= pending.bytes; // Do not let a synchronous fake peer publish the next ack before this event is relayed. if (this.queue.length) queueMicrotask(() => { try { this.pump(); } catch (error) { this.fail(error instanceof NativeSteeringError ? error : undefined); } }); } /** Commit terminal replay only when no submitted injection can change its accepted inputs. */ private recordTerminal(): void { if (this.terminal && !this.terminalRecorded) { this.replay?.observe(this.terminal); this.terminalRecorded = true; } } /** Recover saved, explicitly rejected results on the same socket only when the client asks. */ continue(frame: Frame): boolean { if (!this.send || this.finished) return false; if (this.queue.length || this.continuationSent) injectionError("injection_pending", "Wait for every injection acknowledgement before creating another response."); if (!this.terminal && frame.previous_response_id === this.currentId) { injectionError("injection_pending", "Wait for the response terminal before sending saved-result continuations."); } if (!this.terminal || frame.previous_response_id !== this.currentId) return false; if (this.terminal.type !== "response.completed") injectionError("injection_response_failed", "The parent response did not complete successfully."); if ((frame.stream_id ?? undefined) !== this.lane || frame.generate === false) injectionError("invalid_injection", "Use the same lane for an injection continuation."); for (const [key, value] of Object.entries(frame)) { if (!ENVELOPE.has(key) && this.settings.get(key) !== injectionFingerprint(value)) injectionError("injection_settings_changed", "A native injection continuation cannot change the pinned model or settings."); } for (const key of this.settings.keys()) { if (!Object.hasOwn(frame, key)) injectionError("injection_settings_changed", "A native injection continuation cannot change the pinned model or settings."); } const results = nativeSavedResults(frame.input); const required = [...this.calls.entries()].filter(([, call]) => call.state !== "accepted"); if (!required.length || results.length !== required.length) injectionError("invalid_injection", "Supply every outstanding saved tool result exactly once."); for (const item of results) { const call = this.calls.get(nativeResultKey(item)); if (!call || !nativeResultMatches(item, call.requirement) || call.state === "accepted" || call.state === "queued" || (call.state === "failed" && (!call.recoverable || call.result !== nativeResultFingerprint(item)))) { injectionError("invalid_injection", "Continuation input must match unsent or explicitly completion-rejected tool results."); } } if (Buffer.byteLength(JSON.stringify(frame)) > MAX_NATIVE_INJECTION_BYTES) injectionError("invalid_injection", "Native injection continuation exceeds its byte limit."); this.continuationSent = true; let undo: (() => void) | undefined; try { this.recordTerminal(); const copy = JSON.parse(JSON.stringify(frame)) as Frame; undo = this.replay?.submitted(copy); this.send(copy); } catch (error) { // A typed refusal is a known non-delivery: unjournal, release the continuation // slot so a corrected frame can be sent, and keep the code. if (error instanceof NativeSteeringError) { undo?.(); this.continuationSent = false; throw error; } this.fail(); injectionError("injection_delivery_unknown", "Continuation delivery is unknown; do not automatically resend results."); } if (!this.finished) this.armIdle(this.deadlines.ackMs); return true; } /** Manage response/tool liveness independently of the non-resettable acknowledgement timer. */ private armIdle(ms: number): void { clearTimeout(this.idleTimer); this.idleTimer = setTimeout(() => this.fail(), ms); this.idleTimer.unref?.(); } /** Validate ordered upstream events while allowing acknowledgements after a response terminal. */ observe(event: Frame): boolean { if ((event.stream_id ?? undefined) !== this.lane && !(event.type === "error" && event.stream_id == null)) throw new Error("Native injection lane mismatch."); const type = event.type; if (type === "error") { this.finished = true; return true; } if (type === "response.inject.created" || type === "response.inject.failed") this.acknowledge(event); else { if (typeof type === "string" && (type.startsWith("response.inject.") || type.startsWith("response.steer."))) throw new Error("Unsupported native injection control event."); const response = record(event.response) ? event.response : undefined; if (type === "response.created") { if (!injectionId(response?.id) || this.seen.has(response.id) || this.seen.size >= 128) throw new Error("Native injection response identity or chain limit violated."); if (this.currentId && (!this.continuationSent || !this.terminal || this.queue.length || (response.previous_response_id != null && response.previous_response_id !== this.currentId))) throw new Error("Unexpected native injection successor."); this.currentId = response.id; this.seen.add(response.id); this.calls.clear(); this.callBytes = 0; this.terminal = undefined; this.terminalRecorded = false; this.continuationSent = false; this.lastAckSequence = -1; this.correlation?.finish(); this.correlation = new CodexWsCorrelation(true, () => false); } else if (!this.currentId || this.terminal) throw new Error("Unexpected native injection event outside an active response."); this.correlation?.accept({ ...event, stream_id: undefined }); if (type === "response.output_item.added") this.authorize(event.item); if (type === "response.output_item.done") this.advertise(event.item); if (["response.completed", "response.failed", "response.incomplete"].includes(String(type))) { if (!this.currentId || response?.id !== this.currentId) throw new Error("Native injection terminal identity mismatch."); this.terminal = event; if (Array.isArray(response.output)) for (const item of response.output) this.advertise(item); } else this.replay?.observe(event); } const unresolved = [...this.calls.values()].some(call => call.state !== "accepted"); this.finished = Boolean(this.terminal && !this.queue.length && !this.continuationSent && (this.terminal.type !== "response.completed" || !unresolved)); if (this.finished) { this.recordTerminal(); clearTimeout(this.idleTimer); } else this.armIdle(this.continuationSent ? this.deadlines.ackMs : unresolved ? this.deadlines.toolMs : this.idleMs); return this.finished; } }