UNPKG

@bitkyc08/opencodex

Version:

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

500 lines (474 loc) • 23.9 kB
import { assistantReplayContent } from "../../responses/assistant-replay"; /** * Core-owned registration slot for the optional advisor subsystem (src/advisor). * * This file is the ONLY thing the core Responses path knows about the advisor. It holds the * structural plan interface and the event-stream guard — pure protocol machinery over * src/types — and imports nothing from src/advisor at runtime. The optional subsystem registers * a factory through advisor-plan-slot at host activation; an advisor-disabled install therefore executes no advisor * code and imports no advisor module (same seam discipline as src/lab). * * Guard semantics (mirrors guardTerminalEventStream): * - synthetic `advisor` tool-call events are HELD — the Codex client never sees the tool, the * call, or its arguments; * - on a clean `done`, each held call is consulted through the plan, the advice is appended as a * paired assistant-toolCall + toolResult message pair, and the worker is re-dispatched via the * SAME continuation machinery the terminal guard uses; * - real (non-advisor) tool calls end interception for the leg: the turn belongs to the client; * - usage from intercepted legs is merged into the final terminal event so worker accounting * stays complete; the advisor's own usage is a separate loopback request and never merges here; * - consultations and worker continuations have separate hard per-request bounds. Exhaustion * removes the tool; one final limit-result continuation is allowed, then a typed error ends it. */ import type { AdapterEvent, OcxAssistantContentPart, OcxAssistantMessage, OcxMessage, OcxParsedRequest, OcxTool, OcxToolResultMessage, OcxUsage, } from "../../types"; import { createToolChoiceResolver, namespacedToolName, normalizeDeclaredToolName, toolChoiceAliases, toolChoiceToolPredicate } from "../../types"; import { UNDECLARED_TOOL_CALL_ERROR_CODE } from "../../lib/errors"; import { jsonStringPartsUtf8Bytes, jsonUtf8Bytes } from "../../lib/json-byte-size"; import { isTranslatorBudgetExceededError, releaseTranslatedEvent, TRANSLATOR_MAX_CALL_ARGUMENT_BYTES, TranslatorBudgetExceededError, type TranslatorBudget } from "../../lib/translator-budget"; import { AdvisorRetention } from "./advisor-retention"; import { clipAdvisorQuestion } from "./advisor-question"; export const ADVISOR_TOOL_NAME = "advisor"; export function advisorToolAllowed( parsed: OcxParsedRequest, advisorTool: Pick<OcxTool, "name" | "namespace"> = { name: ADVISOR_TOOL_NAME }, ): boolean { const { explicitRootFunctionChoices, toolChoice } = parsed.options; if (explicitRootFunctionChoices && !explicitRootFunctionChoices.includes(advisorTool.name)) return false; return toolChoiceToolPredicate(toolChoice, [...(parsed.context.tools ?? []), advisorTool])(advisorTool); } type AdvisorCallDisposition = "synthetic" | "refused" | { clientWireName: string } | undefined; const ROOT_ADVISOR_ALIASES = toolChoiceAliases({ namespace: "functions", name: ADVISOR_TOOL_NAME }); /** Resolve provider echoes before interpreting them as synthetic or caller-owned Advisor calls. */ export function createAdvisorCallResolver( parsed: OcxParsedRequest, syntheticAllowed: boolean, callerCatalog = parsed.context.tools ?? [], ): (name: string) => AdvisorCallDisposition { // Keep the original identities recognizable even when a worker leg removes tools. const knownAdvisorNames = new Set([ADVISOR_TOOL_NAME]); for (const tool of callerCatalog) { if (tool.advisor || tool.name !== ADVISOR_TOOL_NAME) continue; for (const name of toolChoiceAliases(tool)) knownAdvisorNames.add(name); if (!tool.namespace) for (const name of ROOT_ADVISOR_ALIASES) knownAdvisorNames.add(name); } if (knownAdvisorNames.size === 1) { return name => name === ADVISOR_TOOL_NAME ? (syntheticAllowed ? "synthetic" : "refused") : undefined; } const { explicitClientToolChoices, toolChoice } = parsed.options; const catalog = parsed.context.tools ?? []; const effectiveChoiceAllows = toolChoiceToolPredicate(toolChoice, catalog); const availableClients = catalog.filter(tool => !tool.advisor && effectiveChoiceAllows(tool)); const emittedNames = createToolChoiceResolver(availableClients); const wireTools = new Map(availableClients.map(tool => [namespacedToolName(tool.namespace, tool.name), tool])); const selectedNames = explicitClientToolChoices?.length ? createToolChoiceResolver(callerCatalog) : undefined; return name => { if (name === ADVISOR_TOOL_NAME && syntheticAllowed) return "synthetic"; const emittedName = name.startsWith("default.") && emittedNames.candidateCount(name) === 0 ? normalizeDeclaredToolName(name, knownAdvisorNames) : name; if (!knownAdvisorNames.has(emittedName)) return undefined; // An exact wire identity wins over compatibility aliases. Bare and dotted echoes // need a unique candidate, and the reserved functions wrapper only denotes a root tool. let tool = wireTools.get(emittedName); if (!tool) { const candidates = emittedNames.candidates(emittedName); if (candidates.length === 1) { tool = wireTools.get(namespacedToolName(candidates[0].namespace, candidates[0].name)); } else if (candidates.length === 0 && ROOT_ADVISOR_ALIASES.includes(emittedName)) { tool = wireTools.get(ADVISOR_TOOL_NAME); } } if (!tool) return "refused"; if (tool.name !== ADVISOR_TOOL_NAME) return undefined; const selected = explicitClientToolChoices === undefined || explicitClientToolChoices.some(choice => choice.type === (tool.freeform ? "custom" : "function") && (choice.namespace === undefined ? selectedNames?.selects(tool, choice.name) : choice.namespace === (tool.namespace ?? "") && choice.name === tool.name)); return selected ? { clientWireName: namespacedToolName(tool.namespace, tool.name) } : "refused"; }; } /** Hard bound on advisor consultations per worker request (recursion guard). */ export const MAX_ADVISOR_CONSULTATIONS_PER_REQUEST = 3; /** At most one final worker continuation after consultation exhaustion. */ export const MAX_ADVISOR_CONTINUATIONS_PER_REQUEST = MAX_ADVISOR_CONSULTATIONS_PER_REQUEST + 1; /** Per-leg retention caps for rebuilding the assistant message (see terminal-guard's bounded retention). */ const MAX_LEG_TEXT_CHARS = 16 * 1_024; const MAX_LEG_THINKING_CHARS = 16 * 1_024; /** Outcome of one consultation, as the plan reports it to the guard. */ export interface AdvisorConsultOutcome { ok: boolean; /** Formatted, wrapper-marked advice text ready to hand to the worker. */ content: string; isError: boolean; /** The consultation was cancelled by the caller (client abort) — not a provider failure. */ cancelled?: boolean; /** * Operator config blocked the consultation before any outbound call. Not a provider * failure: preflight must release a claim instead of recording a cooldown. */ blocked?: "consent" | "settings" | "budget" | "limit"; } /** The structural plan the optional advisor subsystem registers per request. */ export interface AdvisorPlan { /** Synchronous admission: invalid question-only calls do not reserve a consultation. */ shouldCountManualConsultation?(question: string | undefined): boolean; /** * Run one consultation for the current conversation state. Implementations own dedup, * logging, and usage accounting; the guard only consumes the outcome. */ consult( parsed: OcxParsedRequest, reason: "manual", question: string | undefined, abortSignal?: AbortSignal, ): Promise<AdvisorConsultOutcome>; /** * Runtime-owned text for a failed or limited consultation. The guard never composes failure * prose itself: the implementation neutralizes untrusted text so no guard path can emit * something the provenance detector would read as genuine advice. */ formatUnavailable(kind: "manual" | "limit", error: string): string; } export interface AdvisorSidecarCall { id: string; name: string; question?: string; providerMetadata?: import("../../types").OcxProviderOpaqueToolCallMetadata; } /** * Shares continuation/consultation bounds between the normal guard and fetch sidecar loops. * Each leg is reserved before any expert await, while repeated calls receive one bounded limit * result instead of starting another consultation. The tool result preserves the worker call id. */ export function createAdvisorSidecarStep(plan: AdvisorPlan) { let consultations = 0; let continuations = 0; let finalContinuationUsed = false; return { beginLeg(): Extract<AdapterEvent, { type: "error" }> | undefined { const final = consultations >= MAX_ADVISOR_CONSULTATIONS_PER_REQUEST; if (continuations >= MAX_ADVISOR_CONTINUATIONS_PER_REQUEST || finalContinuationUsed) { return { type: "error", status: 502, errorType: "advisor_continuation_limit", message: "Advisor worker continuation limit reached; no further worker calls were sent.", }; } continuations += 1; finalContinuationUsed ||= final; return undefined; }, async consultCall(parsed: OcxParsedRequest, call: AdvisorSidecarCall, abortSignal?: AbortSignal) { let outcome: AdvisorConsultOutcome; // An invalid question-only call is refused by the plan without a consultation, so it // neither reserves nor exhausts the allowance; the continuation bound still applies. const counts = plan.shouldCountManualConsultation?.(call.question) !== false; if (counts && consultations >= MAX_ADVISOR_CONSULTATIONS_PER_REQUEST) { outcome = { ok: false, isError: true, content: plan.formatUnavailable("limit", "consultation limit reached for this request"), }; } else { if (counts) consultations += 1; try { outcome = await plan.consult(parsed, "manual", call.question, abortSignal); } catch (error) { if (isTranslatorBudgetExceededError(error)) throw error; outcome = { ok: false, isError: true, content: plan.formatUnavailable("manual", error instanceof Error ? error.message : String(error)), }; } } return { outcome, message: advisorToolResult(call, outcome, Date.now()) }; }, exhausted(): boolean { return consultations >= MAX_ADVISOR_CONSULTATIONS_PER_REQUEST; }, }; } export type AdvisorSidecarStep = ReturnType<typeof createAdvisorSidecarStep>; interface HeldAdvisorCall { id: string; name: string; args: string[]; argumentBytes: number; question?: string; closed: boolean; providerMetadata?: import("../../types").OcxProviderOpaqueToolCallMetadata; } function parseAdvisorArgs(call: HeldAdvisorCall, retention: AdvisorRetention): { question?: string } { // Reserve both the joined input and parsed JSON before either is materialized. return retention.copy(call.argumentBytes * 2 + 4, () => parseAdvisorQuestionArgs(call.args.join(""))); } export function parseAdvisorQuestionArgs(argsBuf: string): { question?: string } { if (argsBuf.trim() === "") return {}; try { const parsed: unknown = JSON.parse(argsBuf); if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) { const question = (parsed as { question?: unknown }).question; const text = typeof question === "string" ? clipAdvisorQuestion(question) : ""; if (text) return { question: text }; } } catch { /* malformed args → no focus question */ } return {}; } function assistantMessageFromLeg( events: readonly AdapterEvent[], held: readonly HeldAdvisorCall[], timestamp: number, retention: AdvisorRetention, ): OcxAssistantMessage | undefined { const content = assistantReplayContent(events); for (const call of held) { if (!call.closed) continue; const args = parseAdvisorArgs(call, retention); call.question = args.question; content.push({ type: "toolCall", id: call.id, name: call.name, arguments: args, ...(call.providerMetadata ? { providerMetadata: call.providerMetadata } : {}), }); } if (content.length === 0) return undefined; return { role: "assistant", content, timestamp }; } function advisorToolResult( call: AdvisorSidecarCall, outcome: AdvisorConsultOutcome, timestamp: number, ): OcxToolResultMessage { return { role: "toolResult", toolCallId: call.id, toolName: ADVISOR_TOOL_NAME, content: outcome.content, isError: outcome.isError, timestamp, }; } export interface AdvisorGuardOptions { parsed: OcxParsedRequest; plan: AdvisorPlan; firstEvents: AsyncIterable<AdapterEvent>; /** Independent guard ownership within the optional shared request budget. */ translatorBudget?: TranslatorBudget; /** One bounded worker continuation re-dispatch (same machinery as the terminal guard). */ continuation: (parsed: OcxParsedRequest) => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>; } /** * Wrap a worker event stream with advisor interception. Registered on the parsed request as * `_advisorGuard` by the sidecar planner; adapter delivery applies it when present. */ export function createAdvisorStreamGuard(options: AdvisorGuardOptions): AsyncGenerator<AdapterEvent> { const guard = createAdvisorGuard(options.plan); return guard(options); } export function createAdvisorGuard(plan: AdvisorPlan): NonNullable<OcxParsedRequest["_advisorGuard"]> { // Shared across invocations of this request's guard, including an empty-completion retry. const sidecar = createAdvisorSidecarStep(plan); return async function* guardAdvisorStream(options: Omit<AdvisorGuardOptions, "plan">): AsyncGenerator<AdapterEvent> { let parsed = options.parsed; const callerCatalog = parsed.context.tools ?? []; let accumulatedUsage: OcxUsage | undefined; let source: AsyncIterable<AdapterEvent> = options.firstEvents; const retention = new AdvisorRetention(options.translatorBudget); try { while (true) { // A continuation or reused guard may have a narrower choice than the original turn. const resolveAdvisorCall = createAdvisorCallResolver(parsed, advisorToolAllowed(parsed), callerCatalog); const held: HeldAdvisorCall[] = []; const legEvents: AdapterEvent[] = []; let legTextChars = 0; let legThinkingChars = 0; let pending: HeldAdvisorCall | null = null; // While a tool call is open, its delta/end events belong to that call. Advisor calls are // held from the output; real calls pass through untouched. let holdingCurrent = false; let hasRealToolCall = false; let hasIncompleteToolCall = false; let terminalConsumed = false; let terminalEvent: Extract<AdapterEvent, { type: "done" }> | undefined; let bufferedRefusal: Extract<AdapterEvent, { type: "error" }> | undefined; for await (const event of source) { if (bufferedRefusal) { // Non-streaming delivery has already parsed the response. Discard its suffix while // preserving the reported worker usage; never drain a live stream after a refusal. const terminal = event.type === "done" || event.type === "incomplete" || event.type === "error"; if (terminal) accumulatedUsage = retention.usage(accumulatedUsage, event.usage); if (options.translatorBudget) releaseTranslatedEvent(event, options.translatorBudget); if (terminal) { yield accumulatedUsage ? { ...bufferedRefusal, usage: accumulatedUsage } : bufferedRefusal; return; } continue; } if (event.type === "tool_call_start") { const disposition = resolveAdvisorCall(event.name); if (disposition === "refused") { if (options.translatorBudget) releaseTranslatedEvent(event, options.translatorBudget); const refusal: Extract<AdapterEvent, { type: "error" }> = { type: "error", status: 502, errorType: "upstream_error", code: UNDECLARED_TOOL_CALL_ERROR_CODE, message: "routed provider emitted an Advisor call outside the current request's tool choice", ...(accumulatedUsage ? { usage: accumulatedUsage } : {}) }; if (parsed.stream) { yield refusal; return; } bufferedRefusal = refusal; continue; } if (pending) { held.push(pending); pending = null; } holdingCurrent = disposition === "synthetic"; if (!holdingCurrent) { // The parser flattens the reserved functions namespace into the root catalog. if (typeof disposition === "object" && disposition.clientWireName === ADVISOR_TOOL_NAME && ROOT_ADVISOR_ALIASES.includes(event.name)) event.name = disposition.clientWireName; hasRealToolCall = true; // No continuation can use this leg. Real-tool arguments are never copied. held.length = legEvents.length = 0; retention.releaseLeg(); } else { if (!hasRealToolCall) { retention.retain(event, true); pending = { id: event.id, name: event.name, args: [], argumentBytes: 0, closed: false, ...(event.providerMetadata ? { providerMetadata: event.providerMetadata } : {}) }; } continue; } } else if (event.type === "tool_call_delta") { if (pending) { const bytes = jsonStringPartsUtf8Bytes([event.arguments], TRANSLATOR_MAX_CALL_ARGUMENT_BYTES + 2) - 2; if (bytes > TRANSLATOR_MAX_CALL_ARGUMENT_BYTES - pending.argumentBytes) { throw new TranslatorBudgetExceededError("tool_args", TRANSLATOR_MAX_CALL_ARGUMENT_BYTES); } retention.retain(event); pending.argumentBytes += bytes; pending.args.push(event.arguments); } if (holdingCurrent) continue; } else if (event.type === "tool_call_end") { hasIncompleteToolCall ||= event.incomplete === true; if (pending) { retention.retain(event); pending.closed = !event.incomplete; if (pending.name === ADVISOR_TOOL_NAME) held.push(pending); pending = null; } if (holdingCurrent) { holdingCurrent = false; continue; } } else if (event.type === "done") { if (!hasRealToolCall) retention.retain(event); if (pending) { held.push(pending); pending = null; } terminalEvent = event; terminalConsumed = true; break; } else if (event.type === "incomplete" || event.type === "error") { // A broken leg cannot safely anchor a continuation: surface the terminal as-is. if (pending) { pending = null; } accumulatedUsage = retention.usage(accumulatedUsage, event.usage); yield accumulatedUsage ? { ...event, usage: accumulatedUsage } : event; return; } else { // Retain (bounded) the leg's visible content so the rebuilt assistant message is complete. if (event.type === "text_delta") { legTextChars += event.text.length; // Empty deltas add nothing to the rebuilt message; non-empty ones are bounded by the cap. if (!hasRealToolCall && event.text !== "" && legTextChars <= MAX_LEG_TEXT_CHARS) { retention.retain(event, false, false); legEvents.push(event); } } else if (event.type === "thinking_delta") { legThinkingChars += event.thinking.length; if (!hasRealToolCall && event.thinking !== "" && legThinkingChars <= MAX_LEG_THINKING_CHARS) { retention.retain(event, false, false); legEvents.push(event); } } else if ( event.type === "thinking_signature" || event.type === "redacted_thinking" ) { if (!hasRealToolCall) { retention.retain(event); legEvents.push(event); } } } yield event; } if (bufferedRefusal) { yield bufferedRefusal; return; } const advisorCalls = held.filter(call => call.name === ADVISOR_TOOL_NAME && call.closed); const shouldIntercept = terminalConsumed && terminalEvent?.stopReason !== "max_tokens" && terminalEvent?.stopReason !== "content_filter" && advisorCalls.length > 0 && !hasRealToolCall && !hasIncompleteToolCall; if (!shouldIntercept) { // Plain leg: surface the terminal with merged usage from any earlier intercepted legs. if (terminalEvent) { accumulatedUsage = retention.usage(accumulatedUsage, terminalEvent.usage); yield accumulatedUsage ? { ...terminalEvent, usage: accumulatedUsage } : terminalEvent; } return; } // Consume this leg's done — the continuation replaces it. accumulatedUsage = retention.usage(accumulatedUsage, terminalEvent?.usage); const continuationError = sidecar.beginLeg(); if (continuationError) { yield accumulatedUsage ? { ...continuationError, usage: accumulatedUsage } : continuationError; return; } const timestamp = Date.now(); const assistant = retention.history(retention.replayReservation(), () => assistantMessageFromLeg(legEvents, advisorCalls, timestamp, retention)); const messages: OcxMessage[] = [...parsed.context.messages]; if (assistant) messages.push(assistant); for (const call of advisorCalls) { // Later calls in the same leg must see what came before them: the rebuilt worker turn // and every earlier advisor result in this leg's accumulated messages. const consultParsed: OcxParsedRequest = { ...parsed, context: { ...parsed.context, messages }, }; const consulted = await sidecar.consultCall(consultParsed, call); messages.push(retention.history(jsonUtf8Bytes(consulted.outcome) + jsonUtf8Bytes(call.id) + 256, () => consulted.message)!); } const exhausted = sidecar.exhausted(); const tools = exhausted ? parsed.context.tools?.filter(tool => !tool.advisor && tool.name !== ADVISOR_TOOL_NAME) : parsed.context.tools; const choice = parsed.options.toolChoice; const nextParsed: OcxParsedRequest = { ...parsed, context: { ...parsed.context, messages, tools }, options: exhausted && ((typeof choice === "object" && choice !== null && "name" in choice && choice.name === ADVISOR_TOOL_NAME) || (choice === "required" && !tools?.length)) ? { ...parsed.options, toolChoice: "auto" } : parsed.options, }; parsed = nextParsed; // All replay owners were admitted while the raw leg was still live. held.length = legEvents.length = advisorCalls.length = 0; pending = null; terminalEvent = undefined; retention.releaseLeg(); yield { type: "assistant_boundary" }; try { source = await options.continuation(parsed); } catch (error) { if (isTranslatorBudgetExceededError(error)) throw error; yield { type: "error", message: error instanceof Error ? error.message : String(error), ...(accumulatedUsage ? { usage: accumulatedUsage } : {}), }; return; } } } catch (error) { if (!isTranslatorBudgetExceededError(error)) throw error; yield { type: "error", status: 502, errorType: "upstream_error", code: "translation_buffer_limit", message: "upstream translation buffer exceeded the safe limit", ...(accumulatedUsage ? { usage: accumulatedUsage } : {}) }; } finally { retention.release(); } }; }