UNPKG

@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
/** * 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"; }