@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
325 lines (303 loc) • 16 kB
text/typescript
/**
* V1 collaboration evidence nested inside Codex's code-mode `exec` tool (#6844).
*
* In code-mode-only turns codex-rs does not put the collaboration tools on the wire. When they are
* ENABLED it renders each one into the custom `exec` description instead
* (code-mode-protocol/src/description.rs, build_exec_tool_description): a top-level heading line,
* the tool's own description, then an "exec tool declaration:" ts fence holding
* "declare const tools: { <name>(args: ...): Promise<...>; };". A namespaced tool is flattened to
* <namespace>__<name> (tools/src/code_mode.rs, code_mode_name_for_tool_name), and V1 always
* registers under the fixed namespace multi_agent_v1, so a rendered V1 surface reads
* multi_agent_v1__spawn_agent.
*
* That rendering is the only proof of V1 inside exec itself. When the model supports tool search,
* codex-rs registers V1 as DEFERRED and leaves it out of the description entirely, and every
* OpenCodex catalog row advertises tool search. Such a turn carries no V1 evidence here; a bare
* exec, the ALL_TOOLS mention, and the saved OpenCodex mode prove nothing about the conversation
* (codex-rs pins the version per session). The deferred case has its own, separate evidence source
* in deferred-collab-surface.ts, which uses this file's genuine-exec check as a host guard.
*
* A tool description is copied into exec verbatim, so one that reproduces a complete top-level V1
* section is indistinguishable from the host's own rendering. This parser cannot authenticate the
* host; it only refuses everything short of that exact shape.
*/
import { CODE_MODE_EXEC_TOOL_NAME, declaresCodeModeExec, type OcxTool } from "../../types";
export type CodeModeV1Evidence = "v1" | "ambiguous" | null;
/** What a request's code-mode exec proves about collaboration, before any combination policy. */
export interface CodeModeExecAnalysis {
/** A codex-rs code-mode exec is declared: bare, freeform, template-led, no bare shell bridge. */
genuineExec: boolean;
/** That exec renders a complete multi_agent_v1__spawn_agent section. */
renderedV1: boolean;
/** That exec mentions a spawn_agent or V2 companion that is not V1's, quoted or not. */
foreignCollabClaim: boolean;
}
/** First line of codex-rs EXEC_DESCRIPTION_TEMPLATE; an overridden or foreign exec fails closed. */
const CODE_MODE_EXEC_TEMPLATE_HEADER = "Run JavaScript code to orchestrate/compose tool calls";
const MULTI_AGENT_V1_SPAWN = "multi_agent_v1__spawn_agent";
const SPAWN = "spawn_agent";
const V2_COMPANIONS = ["send_message", "followup_task", "interrupt_agent", "list_agents"] as const;
const DECLARATION_LEAD = "exec tool declaration:";
const TOOL_HEADING = /^### `([A-Za-z_$][\w$]*)`(?: \(`([^`]+)`\))?$/;
const DECLARATION_FENCE = "```ts";
// CommonMark fences: up to three spaces of indentation, three or more backticks or tildes. A fence
// closes only on the same character, at least as long, with nothing but whitespace after it.
const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
interface Fence { char: string; length: number }
function openedFence(line: string): Fence | undefined {
const match = FENCE_OPEN.exec(line);
if (!match) return undefined;
const run = match[1]!;
// A backtick fence's info string may not contain a backtick (that line is inline code).
if (run[0] === "`" && match[2]!.includes("`")) return undefined;
return { char: run[0]!, length: run.length };
}
function closesFence(line: string, fence: Fence): boolean {
const match = FENCE_CLOSE.exec(line);
return match !== null && match[1]![0] === fence.char && match[1]!.length >= fence.length;
}
function isCodeModeExec(tool: OcxTool): boolean {
return tool.name === CODE_MODE_EXEC_TOOL_NAME && !tool.namespace && tool.freeform === true
&& typeof tool.description === "string"
&& tool.description.startsWith(CODE_MODE_EXEC_TEMPLATE_HEADER);
}
/** A nested tool rendered as a heading plus its own declaration; `raw` is the pre-normalization name. */
interface RenderedTool { name: string; raw: string }
/** The declaration fence codex-rs opens: three backticks and "ts". */
const DECLARATION_FENCE_SHAPE: Fence = { char: "`", length: 3 };
const DECLARATION_PREFIX = "declare const tools: { ";
const PROMISE_SEPARATOR = "): Promise<";
const DECLARATION_SUFFIX = ">; };";
// Bounds keep a caller-controlled description linear work: a rendered listing is a heading, a
// description, and a small declaration per tool, so anything this large cannot be the codex-rs
// shape this parser exists to recognize.
const MAX_DESCRIPTION_LENGTH = 1 << 20;
const MAX_DECLARATION_LENGTH = 64 * 1024;
const isSpace = (ch: string | undefined): boolean => ch === undefined || /\s/.test(ch);
/**
* The declared tool name when body is a complete declaration as render_code_mode_sample emits it,
* single- or multi-line, else undefined. Fixed boundaries plus one forward scan that balances the
* parameter list's brackets and the return type's generics: no backtracking, so a fence body full
* of candidate separators stays linear work.
*/
function completeDeclarationName(body: readonly string[]): string | undefined {
const text = body.join("\n");
if (text.length > MAX_DECLARATION_LENGTH) return undefined;
if (!text.startsWith(DECLARATION_PREFIX) || !text.endsWith(DECLARATION_SUFFIX)) return undefined;
const signature = text.slice(DECLARATION_PREFIX.length, -DECLARATION_SUFFIX.length);
const openParen = signature.indexOf("(");
const name = openParen > 0 ? signature.slice(0, openParen) : "";
if (!/^[A-Za-z_$][\w$]*$/.test(name)) return undefined;
// A named, typed parameter (`args` for functions, `input` for freeform) and a non-empty return type.
const rest = signature.slice(openParen + 1);
const typed = rest.startsWith("args: ") ? 6 : rest.startsWith("input: ") ? 7 : -1;
if (typed < 0 || isSpace(rest[typed])) return undefined;
// Quoted text and comments are opaque to delimiter matching. Each skip advances
// past its text once; an unterminated region cannot contain a closing declaration.
const isOpaqueTypeText = (at: number): boolean => {
const ch = rest[at];
return ch === '"' || ch === "'" || ch === "`"
|| ch === "/" && (rest[at + 1] === "/" || rest[at + 1] === "*");
};
const skipTypeText = (at: number): number | undefined => {
const quote = rest[at]!;
if (quote === "/" && rest[at + 1] === "/") {
let i = at + 2;
while (i < rest.length && rest[i] !== "\n" && rest[i] !== "\r"
&& rest[i] !== "\u2028" && rest[i] !== "\u2029") i += 1;
return i < rest.length ? i : undefined;
}
if (quote === "/" && rest[at + 1] === "*") {
const end = rest.indexOf("*/", at + 2);
return end < 0 ? undefined : end + 1;
}
let i = at + 1;
while (i < rest.length) {
const ch = rest[i]!;
if (ch === "\\") i += 2;
else if (ch === quote) return i;
else i += 1;
}
return undefined;
};
// The parameter list ends at the ')' that balances the opening '(': a ')' nested inside the
// parameter's own type (e.g. `args: (a: string) => Promise<void>`) cannot pose as the separator.
// The type must also say something before that ')': `args: )` or `args: /* note */)` names no type.
let depth = 1;
let close = -1;
let typeContent = false;
for (let at = typed; at < rest.length; at += 1) {
const ch = rest[at]!;
if (isOpaqueTypeText(at)) {
if (ch !== "/") typeContent = true; // a quoted literal is a type, a comment is not
const end = skipTypeText(at);
if (end === undefined) return undefined;
at = end;
continue;
}
if (ch === "(" || ch === "[" || ch === "{") depth += 1;
else if (ch === ")" || ch === "]" || ch === "}") depth -= 1;
if (depth === 0) { close = at; break; }
if (!isSpace(ch)) typeContent = true;
}
if (close < 0 || !typeContent || !rest.startsWith(PROMISE_SEPARATOR, close)) return undefined;
const head = rest[close + PROMISE_SEPARATOR.length];
if (head === ">" || isSpace(head)) return undefined;
// The return type runs to the stripped suffix, which already supplied exactly one '>' for the
// Promise's '<': generic depth must stay positive to the end and land at exactly 1 — a '>' that
// reaches zero ('Promise<unknown>; garbage') is surplus text, a depth left above 1
// ('Promise<Map<string, unknown') never closed its own generic, and a '=>' arrow never counts.
let generic = 1;
for (let at = close + PROMISE_SEPARATOR.length; at < rest.length; at += 1) {
const ch = rest[at]!;
if (isOpaqueTypeText(at)) {
const end = skipTypeText(at);
if (end === undefined) return undefined;
at = end;
continue;
}
if (ch === "<") generic += 1;
else if (ch === ">" && rest[at - 1] !== "=") generic -= 1;
if (generic === 0) return undefined;
}
return generic === 1 ? name : undefined;
}
/** codex-rs normalize_code_mode_identifier: invalid identifier characters become `_`. */
function normalizeCodeModeIdentifier(raw: string): string {
let identifier = "";
for (const [index, ch] of [...raw].entries()) {
const valid = index === 0 ? /[A-Za-z_$]/.test(ch) : /[A-Za-z0-9_$]/.test(ch);
identifier += valid ? ch : "_";
}
return identifier === "" ? "_" : identifier;
}
/** A heading as render_tool_heading emits it: a raw suffix only when normalization changed the name. */
function renderedHeading(match: RegExpExecArray): RenderedTool | undefined {
const name = match[1]!;
const raw = match[2];
if (raw === undefined) return { name, raw: name };
return raw !== name && normalizeCodeModeIdentifier(raw) === name ? { name, raw } : undefined;
}
/**
* Nested tools whose top-level heading is followed by the complete declaration codex-rs renders for
* the same name. A section ends at its own declaration, not at the next heading, because tool and
* namespace descriptions (V1 spawn's guidance, a configured usage hint) carry their own Markdown,
* including example headings and example declarations. Pending headings form a stack: a
* declaration is owned by the outermost pending heading with its name, which is removed together
* with anything opened after it; a declaration nobody owns is an example and leaves the stack
* alone. Lines inside a quoted fence can neither open a section nor declare a tool.
*/
function renderedNestedTools(description: string): RenderedTool[] {
if (description.length > MAX_DESCRIPTION_LENGTH) return [];
const lines = description.split("\n");
const rendered: RenderedTool[] = [];
const pending: RenderedTool[] = [];
// Ascending indexes into `pending` per name, so a declaration finds its owner in one lookup
// instead of rescanning every pending heading.
const pendingByName = new Map<string, number[]>();
const dropPendingTo = (length: number): void => {
while (pending.length > length) {
const removed = pending.pop()!;
const indexes = pendingByName.get(removed.name)!;
indexes.pop();
if (indexes.length === 0) pendingByName.delete(removed.name);
}
};
let fence: Fence | undefined;
for (let i = 0; i < lines.length; i += 1) {
const line = lines[i]!;
if (fence) {
if (closesFence(line, fence)) fence = undefined;
continue;
}
const match = TOOL_HEADING.exec(line);
if (match) {
const heading = renderedHeading(match);
if (heading) {
const indexes = pendingByName.get(heading.name);
if (indexes) indexes.push(pending.length); else pendingByName.set(heading.name, [pending.length]);
pending.push(heading);
}
continue;
}
if (line === DECLARATION_LEAD && lines[i + 1] === DECLARATION_FENCE) {
let close = i + 2;
while (close < lines.length && !closesFence(lines[close]!, DECLARATION_FENCE_SHAPE)) close += 1;
if (close >= lines.length) return rendered; // unterminated: nothing after it is structure
const body = lines.slice(i + 2, close);
// The outermost pending heading with the declared name owns it, so a same-name heading quoted
// inside the tool's own description cannot take over the genuine section.
const declared = completeDeclarationName(body);
const owner = declared === undefined ? -1 : pendingByName.get(declared)?.[0] ?? -1;
if (owner >= 0) {
rendered.push(pending[owner]!);
dropPendingTo(owner);
}
i = close;
continue;
}
fence = openedFence(line);
}
return rendered;
}
/**
* Nested tools a codex-rs code-mode exec renders, read from its wire form: a top-level custom
* `exec` whose description opens with the template header. Each name needs a heading followed by
* its own declaration, so an example or quoted text in the description renders nothing.
*/
export function codeModeRenderedToolNames(name: unknown, description: unknown): string[] {
if (name !== CODE_MODE_EXEC_TOOL_NAME || typeof description !== "string"
|| !description.startsWith(CODE_MODE_EXEC_TEMPLATE_HEADER)) return [];
return renderedNestedTools(description).map(tool => tool.name);
}
/** A nested name that claims a collaboration surface other than V1's. */
function isForeignCollabName(name: string): boolean {
if (name.startsWith("mcp__")) return false; // MCP server tools are never native collaboration
if (name === MULTI_AGENT_V1_SPAWN) return false;
if (name === SPAWN || name.endsWith("__" + SPAWN)) return true;
return V2_COMPANIONS.some(companion => name === companion || name.endsWith("__" + companion));
}
/** Every name a heading or declaration line mentions, quoted or not. */
function mentionedToolNames(description: string): string[] {
const names: string[] = [];
for (const line of description.split("\n")) {
const heading = TOOL_HEADING.exec(line);
if (heading) {
names.push(heading[1]!);
if (heading[2] !== undefined) names.push(heading[2]);
}
for (const match of line.matchAll(/declare const tools: \{ ([A-Za-z_$][\w$]*)\(/g)) names.push(match[1]!);
}
return names;
}
/**
* Reads every genuine code-mode exec once. The two collaboration halves are deliberately
* asymmetric. V1 evidence needs a rendered section (a heading followed by its complete
* declaration). The contradiction check reads every heading and declaration line, inside fences or
* not and whoever "owns" it, so text copied into the listing can only push a turn toward null; it
* cannot hide another surface. The contradiction is reported even without rendered V1, because
* deferred V1 evidence must also yield to a rendered foreign surface.
*/
export function analyzeCodeModeExec(tools: readonly OcxTool[] | undefined): CodeModeExecAnalysis {
const analysis: CodeModeExecAnalysis = { genuineExec: false, renderedV1: false, foreignCollabClaim: false };
if (!tools || tools.length === 0) return analysis;
if (!declaresCodeModeExec(new Set(tools.filter(tool => !tool.namespace).map(tool => tool.name)))) return analysis;
for (const tool of tools) {
if (!isCodeModeExec(tool)) continue;
analysis.genuineExec = true;
// A rendered V1 spawn heading carries no raw-name suffix: the identifier needs no normalization.
if (renderedNestedTools(tool.description).some(rendered => rendered.raw === MULTI_AGENT_V1_SPAWN)) analysis.renderedV1 = true;
if (mentionedToolNames(tool.description).some(isForeignCollabName)) analysis.foreignCollabClaim = true;
}
return analysis;
}
/**
* "v1" when a genuine code-mode exec renders the V1 spawn tool and nothing that claims another
* collaboration surface; "ambiguous" when it renders both; null when it proves nothing.
*/
export function codeModeV1Evidence(tools: readonly OcxTool[] | undefined): CodeModeV1Evidence {
const analysis = analyzeCodeModeExec(tools);
if (!analysis.renderedV1) return null;
return analysis.foreignCollabClaim ? "ambiguous" : "v1";
}