UNPKG

@bitkyc08/opencodex

Version:

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

346 lines (323 loc) • 16.3 kB
// Schema-aware repair for tool arguments whose serialized representation disagrees // with the declared schema in a way that has exactly one faithful reading. // // Case 1 — integer fields arriving as integral floats (issue #1611). // // Grok serializes integer tool-call arguments through a float representation, so // `yield_time_ms: 120000` leaves the provider as `120000.0`. Codex declares those // fields as Rust integer types, so it rejects the call BEFORE running the tool: // // failed to parse function arguments: invalid type: floating point `120000.0`, expected u64 // // That is a hard failure, not a degradation — the model gets no result and retries // the same float. Nothing on the routed path reconciled argument values against the // declared schema, so the `.0` passed straight through. // // The boundary this file draws is INTENT, not convenience: // - an integral float in an integer-typed field is a representation artifact, and // `120000.0` has exactly one integer reading, so it is repaired; // - `1.5` in an integer field is a genuine disagreement with the schema and is left // alone so it still fails, rather than being truncated into a plausible lie. // // Case 2 — string fields arriving as bare integers (issue #1938). // // Cursor-served models emit `{"cell_id": 4}` where the schema declares // `{"type": "string"}`. Codex rejects the call before the tool runs (invalid type: // integer `4`, expected a string), and the model never self-corrects, so every such // call is a hard failure loop. A safely-integral JSON number in a string-declared // field has exactly one faithful string reading (`4` -> `"4"`), so it is repaired // under the same intent boundary: // - only when the field declares `string` and no numeric type (a // `["integer","string"]` union accepts the number as-is and is left alone); // - a non-integral number (`4.5`) in a string field is a genuine disagreement and // is left alone so it still fails; // - beyond 2^53-1 the parsed value may differ from the serialized text, so the // original bytes stay. // // Anything without a declared `integer`/`string` type is never touched. /** JSON Schema subset we need; provider tool schemas are untrusted input. */ type SchemaNode = Record<string, unknown>; function asSchema(value: unknown): SchemaNode | undefined { return value && typeof value === "object" && !Array.isArray(value) ? value as SchemaNode : undefined; } /** True when the node declares `integer`, including `["integer","null"]` unions. */ function declaresInteger(schema: SchemaNode): boolean { const type = schema.type; if (type === "integer") return true; return Array.isArray(type) && type.includes("integer"); } /** True when the node declares `string`, including `["string","null"]` unions. */ function declaresString(schema: SchemaNode): boolean { const type = schema.type; if (type === "string") return true; return Array.isArray(type) && type.includes("string"); } // Issue #2316: Codex advertises `multi_agent_v1__wait_agent`'s `timeout_ms` as a JSON // Schema `number`, but its Rust runtime deserializes the field as `u64` and rejects // `120000.0` with "invalid type: floating point `120000.0`, expected u64" before the // tool ever runs. The schema lookup is not the problem — the error text comes from // Codex's own deserializer, so the call reached it — the problem is that `number` // alone never authorizes the integral-float repair below. // // This allowlist is deliberately one field wide. It names only what has a live // reproduction against a real `u64`, because the repair is only unambiguous for a // field that cannot legitimately hold a fraction. Generic names (`start`, `end`, // `priority`, `port`) would silently rewrite a third-party tool's fractional value, // so a new entry needs its own evidence, not a plausible-sounding name. // // Cursor's sibling `yield_time_ms` (src/adapters/cursor/tool-definitions.ts) is also // declared `number`; it is NOT included here because no rejection has been captured // against it. It gets its own change when it gets its own reproduction. const U64_NUMBER_FIELDS = new Set(["timeout_ms"]); // Issue #2443 / #2451: Codex Desktop's bare `wait` tool has the same schema/runtime // split for `yield_time_ms` and `max_tokens`. Scope these names to that bare tool so a // third-party or namespaced tool can still use fractional values legitimately. // #2448 allowlisted the hyphenated `yield-time_ms`; live Grok 4.6 calls and the // advertised wait schema both use the underscore form, so that name is the one // with a captured u64 rejection. Cursor still uses the same underscore name on a // namespaced tool; the wait-only map keeps that path byte-identical. const U64_NUMBER_FIELDS_BY_TOOL = new Map<string, ReadonlySet<string>>([ ["wait", new Set(["yield_time_ms", "max_tokens"])], ]); /** True when the node accepts a JSON number (`integer` or `number`), so a numeric * value is already schema-valid and must not be rewritten into a string. */ function declaresNumeric(schema: SchemaNode): boolean { const type = schema.type; if (type === "integer" || type === "number") return true; return Array.isArray(type) && (type.includes("integer") || type.includes("number")); } /** * Resolve a local `$ref` (`#/$defs/Foo`, `#/definitions/Foo`). * * Only same-document refs are followed: a remote ref is not fetchable here, and a * schema we cannot resolve must leave its values untouched rather than guessed at. */ function resolveRef(schema: SchemaNode, root: SchemaNode, seen: Set<string>): SchemaNode | undefined { const ref = schema.$ref; if (typeof ref !== "string" || !ref.startsWith("#/")) return schema; if (seen.has(ref)) return undefined; // cyclic $ref: stop rather than recurse forever seen.add(ref); let node: unknown = root; for (const rawSegment of ref.slice(2).split("/")) { const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~"); const current = asSchema(node); if (!current) return undefined; node = current[segment]; } const resolved = asSchema(node); return resolved ? resolveRef(resolved, root, seen) : undefined; } /** Composition keywords whose branches may carry the integer declaration. */ const COMPOSITION_KEYS = ["anyOf", "oneOf", "allOf"] as const; function compositionBranches(schema: SchemaNode): SchemaNode[] { const branches: SchemaNode[] = []; for (const key of COMPOSITION_KEYS) { const value = schema[key]; if (!Array.isArray(value)) continue; for (const branch of value) { const node = asSchema(branch); if (node) branches.push(node); } } return branches; } /** * A JS number can only represent integers exactly up to 2^53-1. Beyond that a * rewrite would emit a silently different value, so the original text stays. */ function safelyIntegral(value: number): boolean { return Number.isInteger(value) && Math.abs(value) <= Number.MAX_SAFE_INTEGER; } interface CoerceResult { value: unknown; changed: boolean; } interface NumberToken { start: number; raw: string; replacement?: string; } function coerceValue( value: unknown, schema: SchemaNode | undefined, root: SchemaNode, depth: number, numbers: Map<string, NumberToken>, toolName?: string, propertyName?: string, ): CoerceResult { // A hostile or deeply nested schema must not blow the stack. if (depth > 64) return { value, changed: false }; // Only scanner-created placeholders reach numeric coercion. Real strings, including // escaped strings that resemble a placeholder, keep their original type and bytes. const token = typeof value === "string" ? numbers.get(value) : undefined; if (token) { const numeric = Number(token.raw); // Number() can round a non-integral token onto an integer (1e-400 -> 0, or // 9007199254740990.5 -> 9007199254740990). Such a token never counts as integral: // it keeps its bytes so the client sees the value that was actually sent. if (Number.isInteger(numeric) && !tokenDenotesInteger(token.raw)) return { value, changed: false }; const result = coerceValue(numeric, schema, root, depth, numbers, toolName, propertyName); if (result.changed) token.replacement = JSON.stringify(result.value); return result; } const resolved = schema ? resolveRef(schema, root, new Set()) : undefined; if (typeof value === "number") { if (!resolved) return { value, changed: false }; const branches = compositionBranches(resolved); // #2316: a known Codex-native u64 field counts as integer-declared even when the // advertised schema says `number`, but only when the field really is numeric — // an allowlisted name over a string-typed field is a disagreement, not a repair. const nativeU64Field = propertyName !== undefined && ( U64_NUMBER_FIELDS.has(propertyName) || U64_NUMBER_FIELDS_BY_TOOL.get(toolName ?? "")?.has(propertyName) === true ); const nativeU64Declared = nativeU64Field && (declaresNumeric(resolved) || branches.some(declaresNumeric)); const integerDeclared = declaresInteger(resolved) || branches.some(declaresInteger) || nativeU64Declared; if (!integerDeclared && safelyIntegral(value)) { // Issue #1938: a bare integer in a string-only field has exactly one faithful // string reading. A field that also accepts a numeric type keeps the number. const stringDeclared = declaresString(resolved) || branches.some(declaresString); const numericDeclared = declaresNumeric(resolved) || branches.some(declaresNumeric); if (stringDeclared && !numericDeclared) { return { value: String(value), changed: true }; } } // Not an integer field, already an integer, non-integral, or unrepresentable: // in every one of those cases the received value is the right thing to keep. if (!integerDeclared || !safelyIntegral(value)) return { value, changed: false }; // `120000.0` and `120000` are the same JS number; the difference is only in the // serialized text, which is repaired by re-stringifying only this number token. return { value, changed: true }; } if (Array.isArray(value)) { const itemSchema = resolved ? asSchema(resolved.items) : undefined; let changed = false; const next = value.map(entry => { // Array items have no property name of their own; passing the array's key would // let `timeout_ms: [1.5]` inherit the allowlist. Items are judged by schema only. const result = coerceValue(entry, itemSchema, root, depth + 1, numbers, toolName); if (result.changed) changed = true; return result.value; }); return changed ? { value: next, changed } : { value, changed: false }; } const object = asSchema(value); if (!object) return { value, changed: false }; const properties = resolved ? asSchema(resolved.properties) : undefined; const additional = resolved ? asSchema(resolved.additionalProperties) : undefined; let changed = false; const next: Record<string, unknown> = {}; for (const [key, entry] of Object.entries(object)) { const childSchema = asSchema(properties?.[key]) ?? additional; const result = coerceValue(entry, childSchema, root, depth + 1, numbers, toolName, key); if (result.changed) changed = true; next[key] = result.value; } return changed ? { value: next, changed } : { value, changed: false }; } const JSON_STRING_OR_NUMBER = /"(?:[^"\\]|\\.)*"|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/g; const INTEGRAL_FLOAT_TOKEN = /^-?(?:0|[1-9]\d*)\.0+$/; /** True when a JSON number token's exact decimal value is an integer, judged from its text. */ function tokenDenotesInteger(raw: string): boolean { const match = /^-?(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(raw); if (!match) return false; const digits = match[1]! + (match[2] ?? ""); // A zero significand is exactly zero for any exponent, even one Number() cannot hold. if (/^0*$/.test(digits)) return true; const exponent = Number(match[3] ?? "0"); if (!Number.isFinite(exponent)) return false; const point = match[1]!.length + exponent; const fraction = point <= 0 ? digits : digits.slice(point); return /^0*$/.test(fraction); } /** * Mask numbers before schema traversal and retain their original positions. A prefix absent * from every decoded input string (including keys) prevents placeholder collisions. * Applying repairs to the original text also preserves tokens hidden by duplicate keys. */ function maskNumberTokens(json: string): { masked: string; numbers: Map<string, NumberToken> } { // One pass collects the tag that follows the base prefix in every colliding decoded string; // the smallest unused tag then yields a prefix no input string can start with. This stays // linear in the input, unlike growing the prefix and rescanning every string. const base = "\u0000ocx-number:"; const usedTags = new Set<string>(); for (const [raw] of json.matchAll(JSON_STRING_OR_NUMBER)) { if (!raw.startsWith('"')) continue; const value = JSON.parse(raw) as string; if (!value.startsWith(base)) continue; const end = value.indexOf(":", base.length); if (end >= 0) usedTags.add(value.slice(base.length, end)); } let tag = 0; while (usedTags.has(String(tag))) tag += 1; const prefix = `${base}${tag}:`; const numbers = new Map<string, NumberToken>(); const masked = json.replace(JSON_STRING_OR_NUMBER, (raw: string, start: number) => { if (raw.startsWith('"')) return raw; const key = `${prefix}${numbers.size}`; numbers.set(key, { start, raw }); return JSON.stringify(key); }); return { masked, numbers }; } /** * Repair integral floats in a tool-call arguments STRING against the tool's declared * parameter schema, and safe bare integers in string-only fields. When a repair is needed, * safe integral number tokens are normalized as before; non-integral decimals, unsafe integers * and overflowing numbers remain byte-identical, including in duplicate keys and nested arrays, * while safe siblings still get repaired. Strings, duplicate keys and surrounding formatting * retain their bytes. * * Returns the original string unchanged when there is no schema, the payload does not * parse, or nothing needed repair — so an unaffected call keeps its exact bytes and * this stays a no-op for every provider that already emits real integers. */ export function coerceIntegerToolArguments( args: string, parameters: Record<string, unknown> | undefined, toolName?: string, ): string { if (!parameters || !args) return args; // Cheap reject: a payload with no digit cannot need either repair (integral-float // -> integer, or bare-integer -> string). if (!/\d/.test(args)) return args; let parsed: unknown; let numbers: Map<string, NumberToken>; try { // Validate before masking so token substitution cannot turn malformed JSON valid. JSON.parse(args); const masked = maskNumberTokens(args); numbers = masked.numbers; parsed = JSON.parse(masked.masked); } catch { // Malformed or still-streaming arguments are not this function's problem; the // existing paths already handle them. return args; } const root = parameters as SchemaNode; const result = coerceValue(parsed, root, root, 0, numbers, toolName); if (!result.changed) return args; const chunks: string[] = []; let cursor = 0; for (const token of numbers.values()) { // Unrepaired tokens are normalized only when the source text itself is an integral float // (digits, then a fraction of zeros) with a safe value, such as 2.0, matching the previous // re-serialization. Every other token, including 9007199254740990.5 and exponent forms, // keeps its exact source text, so no unrepaired value is rounded. const replacement = token.replacement ?? (INTEGRAL_FLOAT_TOKEN.test(token.raw) && Number.isSafeInteger(Number(token.raw)) ? JSON.stringify(Number(token.raw)) : token.raw); chunks.push(args.slice(cursor, token.start), replacement); cursor = token.start + token.raw.length; } chunks.push(args.slice(cursor)); return chunks.join(""); }