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