@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
text/typescript
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(); }
};
}