@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
194 lines (185 loc) • 10.5 kB
text/typescript
import { currentTurnWireToolCatalogBody } from "../responses-undeclared-tool-guard";
import { sessionLaneIdFromRequest } from "../request-log-conversation";
import { codeModeRenderedToolNames } from "./code-mode-collab-surface";
import { CODE_MODE_EXEC_TOOL_NAME } from "../../types";
/**
* Eager MCP definitions at which a Codex request is diagnosed as carrying an expanded catalog.
* Routed catalog rows advertise deferred discovery, so a Codex client with current model metadata
* keeps MCP tools deferred; one whose metadata is missing or stale expands every MCP tool into the
* request. The request is still forwarded unchanged: this is a diagnostic, never an admission
* rule, because an eager catalog stays a valid request (ADR-0022).
*/
export const EAGER_CODEX_MCP_TOOL_WARNING_THRESHOLD = 64;
/**
* Sessions already warned, least recently sent first. Bounded so a long-lived proxy cannot grow
* it without limit: the dedupe covers this many sessions and no more, so an operator running more
* sessions than that can see one repeat warning. Recency refreshes on every request a session
* sends, so the session being evicted is the one that has been idle longest.
*/
export const WARNED_SESSION_LIMIT = 1024;
const warnedSessions = new Map<string, true>();
/** Logical requests already warned without a session identity; weak so completed requests leave no trace. */
const warnedAnonymousRequests = new WeakSet<object>();
const CODEX_CLIENT_IDENTITY = /^(?:codex|codex_cli_rs|codex_app|codex_work_desktop|codexless_agent|Codex Desktop)(?:\/|$)/i;
// This optional diagnostic has a request-wide work/storage budget, not an admission limit.
const MAX_DIAGNOSTIC_ITEMS = 4_096;
const MAX_DIAGNOSTIC_CHARACTERS = 1 << 20;
interface DiagnosticBudget { items: number; characters: number }
function reserveDiagnosticBudget(budget: DiagnosticBudget, items: number, characters = 0): boolean {
if (items > budget.items || characters > budget.characters) return false;
budget.items -= items;
budget.characters -= characters;
return true;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
/**
* Which wire surface a request is being counted for. Compaction sends its history as `input` rather
* than as declarations, so only its top-level `tools` are this request's catalog.
*/
export function eagerCodexToolCatalogSurface(
body: unknown,
compactionRecoveryKind: string | undefined,
): "responses" | "compact" {
if (compactionRecoveryKind === "compaction-v1") return "compact";
const input = isRecord(body) && Array.isArray(body.input) ? body.input : [];
// An oversized unknown surface is skipped by the count's input budget too.
if (input.length > MAX_DIAGNOSTIC_ITEMS) return "responses";
return input.some(item => isRecord(item) && item.type === "compaction_trigger") ? "compact" : "responses";
}
function collectEagerMcpTools(specs: unknown[], names: Set<string>, budget: DiagnosticBudget, namespace?: string): boolean {
if (!reserveDiagnosticBudget(budget, specs.length)) return false;
for (const spec of specs) {
if (!isRecord(spec) || spec.defer_loading === true) continue;
// Codex namespaces are one level deep. A namespace nested inside another is not a Codex
// declaration, and recursing into caller-shaped depth could exhaust the stack.
if (spec.type === "namespace" && typeof spec.name === "string" && Array.isArray(spec.tools)) {
if (namespace === undefined && !collectEagerMcpTools(spec.tools, names, budget, spec.name)) return false;
continue;
}
const tool = isRecord(spec.function) ? spec.function : spec;
if (tool.defer_loading === true || typeof tool.name !== "string") continue;
// `functions` is the reserved unnamespaced group (as in the undeclared-tool guard and parser),
// so an MCP tool declared inside it keeps its own `mcp__` name.
const prefix = namespace && namespace !== "functions" ? namespace : undefined;
const isMcp = prefix === undefined ? tool.name.startsWith("mcp__")
: prefix === "mcp" || prefix === "mcp_" || prefix.startsWith("mcp__");
if (isMcp) {
// Charge every occurrence, including duplicates, before concatenation or Set hashing.
const length = tool.name.length + (prefix === undefined ? 0 : prefix.length + 2);
if (!reserveDiagnosticBudget(budget, 0, length)) return false;
names.add(prefix === undefined ? tool.name : `${prefix}__${tool.name}`);
}
// Code Mode renders each enabled, non-deferred nested tool into the exec description. Codex
// sends exec bare or, on Responses Lite, inside its `functions` namespace.
if ((namespace === undefined || namespace === "functions") && spec.type === "custom"
&& tool.name === CODE_MODE_EXEC_TOOL_NAME && typeof tool.description === "string") {
// Reserving the complete description bounds parsing, copies and all names it can render.
if (!reserveDiagnosticBudget(budget, 0, tool.description.length)) return false;
const rendered = codeModeRenderedToolNames(tool.name, tool.description);
if (!reserveDiagnosticBudget(budget, rendered.length)) return false;
for (const nested of rendered) {
if (nested.startsWith("mcp__")) names.add(nested);
}
}
}
return true;
}
/**
* Responses Lite `additional_tools` the client sent for this request.
*
* Codex does not express "current turn" by position: a window resends its base catalog at the head
* of `input` on every request and appends an incremental `additional_tools` update wherever the
* change happened, including after a replayed tool call. Both are live declarations that this
* request pays for, so every client-sent item counts. Only what the proxy itself replayed from
* stored continuation state is history, and `currentTurnWireToolCatalogBody` removes it before
* this runs.
*/
function clientSentAdditionalTools(input: unknown[]): unknown[][] {
const groups: unknown[][] = [];
for (const item of input) {
if (isRecord(item) && item.type === "additional_tools" && Array.isArray(item.tools)) groups.push(item.tools);
}
return groups;
}
/**
* Eager MCP definitions a canonical Codex client declared for this request, or 0 for any other
* client. `replayPrefixLength` is the leading input the proxy restored from stored continuation
* state; those items are history and grant no declaration for this turn. Compaction reads only
* top-level `tools`: its `input` is history. Exceeding the diagnostic budget returns 0 rather
* than a partial count; it neither rejects nor rewrites the request.
*/
export function eagerCodexMcpToolCount(
body: unknown,
headers: Headers,
surface: "responses" | "compact" = "responses",
replayPrefixLength?: number,
): number {
if (!headers.has("x-codex-turn-metadata")
&& !CODEX_CLIENT_IDENTITY.test(headers.get("originator") ?? "")
&& !CODEX_CLIENT_IDENTITY.test(headers.get("user-agent") ?? "")) return 0;
if (!isRecord(body)) return 0;
const budget = { items: MAX_DIAGNOSTIC_ITEMS, characters: MAX_DIAGNOSTIC_CHARACTERS };
const input = surface === "responses" && Array.isArray(body.input) ? body.input : undefined;
if (input !== undefined && !reserveDiagnosticBudget(budget, input.length)) return 0;
// Bound replay scans/copies before invoking the shared helper, and never spread unrelated
// request fields or inspect compaction history just to compute an optional diagnostic.
const current = currentTurnWireToolCatalogBody({ tools: body.tools, input }, replayPrefixLength);
if (!isRecord(current)) return 0;
const names = new Set<string>();
if (Array.isArray(current.tools) && !collectEagerMcpTools(current.tools, names, budget)) return 0;
if (surface === "responses" && Array.isArray(current.input)) {
for (const tools of clientSentAdditionalTools(current.input)) {
if (!collectEagerMcpTools(tools, names, budget)) return 0;
}
}
return names.size;
}
/**
* Warn once per session when a Codex request carries an eagerly expanded MCP catalog. Only the
* count and the threshold are logged; tool names, bodies and session identifiers are not.
*
* A request without a session identity has no session to warn once per, so the
* `logicalRequest` scope stands in for one: each logical request warns, and a retry, combo child
* or compaction replay that shares the scope does not repeat it. Callers that omit the scope fall
* back to the session only.
*/
export function warnEagerCodexToolCatalog(
body: unknown,
headers: Headers,
options: { surface?: "responses" | "compact"; replayPrefixLength?: number; logicalRequest?: object } = {},
): void {
const surface = options.surface ?? "responses";
const session = sessionLaneIdFromRequest(headers);
if (session !== undefined && warnedSessions.has(session)) {
// Refresh recency on every request the session sends, eager or not, so an active session is
// never the one evicted next. An already-warned session needs no count at all.
warnedSessions.delete(session);
warnedSessions.set(session, true);
return;
}
// A diagnostic must never change the request it observes: any failure while counting a
// malformed body skips the warning and lets the request continue exactly as before.
let count: number;
try { count = eagerCodexMcpToolCount(body, headers, surface, options.replayPrefixLength); } catch { return; }
if (count < EAGER_CODEX_MCP_TOOL_WARNING_THRESHOLD) return;
if (session !== undefined) {
while (warnedSessions.size >= WARNED_SESSION_LIMIT) {
const oldest = warnedSessions.keys().next().value;
if (oldest === undefined) break;
warnedSessions.delete(oldest);
}
warnedSessions.set(session, true);
} else if (options.logicalRequest !== undefined) {
if (warnedAnonymousRequests.has(options.logicalRequest)) return;
warnedAnonymousRequests.add(options.logicalRequest);
}
console.warn(
`[codex-catalog] Codex sent ${count} eager MCP tool definitions (warning threshold ${EAGER_CODEX_MCP_TOOL_WARNING_THRESHOLD}) `
+ "instead of deferred tool discovery; its model metadata may be missing or stale. The request was forwarded unchanged. "
+ "Restart Codex to reload the catalog ('ocx system codex-restart --yes'; it interrupts running turns). "
+ "Shown once per session, or once per request "
+ "when the client sends no session identity.",
);
}