@juspay/neurolink 12.36.0 → 12.37.0

package/dist/proxy/argumentParsing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parses a Codex tool call's raw argument text into the record a Claude
+ * `tool_use.input` needs, kind-aware: a `function` tool's `arguments` is
+ * JSON-Schema-shaped JSON text; a `custom` tool has no JSON at all — only the
+ * raw grammar-constrained string that `mapCodexCustomToolToClaude`'s
+ * single-field `input_schema` (`codexOutboundFallback.ts` §3.4) expects
+ * wrapped as `{ input: raw }`. Centralized so both call sites (a
+ * `function_call` item's `arguments` and a `custom_tool_call` item's `input`)
+ * go through the same rule rather than two hand-rolled wrappings.
+ */
+import type { CodexNativeToolKind } from "../types/index.js";
+export declare function parseToolArguments(raw: string, kind: CodexNativeToolKind): Record<string, unknown>;

package/dist/proxy/argumentParsing.js

@@ -0,0 +1,23 @@
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function parseToolArguments(raw, kind) {
+    if (kind === "custom") {
+        return { input: raw };
+    }
+    // Empty arguments is the documented zero-argument-call shape, not
+    // malformed input — it must not be wrapped as `{ input: "" }`.
+    if (raw === "") {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (isPlainRecord(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // fall through — not JSON at all (e.g. a stray shell-command string)
+    }
+    return { input: raw };
+}

package/dist/proxy/codexOutboundFallback.d.ts

@@ -8,14 +8,17 @@
  * own target/model selection, response/stream translation back to Codex wire
  * format, tool execution, or dispatch/HTTP.
  *
- * `parallel_tool_calls` is parsed and validated but not yet consumed here —
- * `mapCodexToolChoiceToClaude` stays the base bijection this PR ships.
- * Threading it into `tool_choice.disable_parallel_tool_use` (and the matching
- * `ClaudeRequest.tool_choice` type change) is the tool-call-fidelity build-order
- * PR's explicit modification to this same function, not a gap in this one.
+ * `parallel_tool_calls` feeds `tool_choice.disable_parallel_tool_use` in
+ * `mapCodexToolChoiceToClaude`, and tool declarations are flattened through
+ * `inlineJsonSchema` (dropping `strict` and degrading a circular `$ref` to a
+ * bare `{type:"object"}`) — the tool-call-fidelity PR's changes to this file.
+ * A `toolKindByName` map is also returned alongside the translated request,
+ * so response serialization (which sees only Claude's `name`+`input` on a
+ * `tool_use` block, no kind discriminator) knows which declared tools were
+ * `custom` rather than `function`.
  */
 import type { ClaudeRequest } from "../types/index.js";
-import type { CodexNativeRequest, CodexTranslationError } from "../types/index.js";
+import type { CodexNativeRequest, CodexNativeToolKind, CodexTranslationError } from "../types/index.js";
 export declare function parseCodexNativeRequest(raw: unknown): {
     ok: true;
     value: CodexNativeRequest;
@@ -29,6 +32,7 @@ export declare function translateCodexRequestToClaude(request: CodexNativeReques
 }): {
     ok: true;
     value: ClaudeRequest;
+    toolKindByName: ReadonlyMap<string, CodexNativeToolKind>;
 } | {
     ok: false;
     error: CodexTranslationError;

package/dist/proxy/codexOutboundFallback.js

@@ -1,4 +1,8 @@
 import { resolveClaudeMaxTokens } from "../utils/tokenLimits.js";
+import { inlineJsonSchema } from "../utils/schemaConversion.js";
+import { parseToolArguments } from "./argumentParsing.js";
+import { recordCodexOutboundSchemaDegraded, recordCodexOutboundUnsupportedField, } from "./proxyTracer.js";
+import { CODEX_STREAM_MAX_TOOL_CALLS, CODEX_STREAM_SIZE_CEILING_BYTES, } from "./streamLimits.js";
 // ---------------------------------------------------------------------------
 // §3.1 parseCodexNativeRequest — the untrusted-JSON -> typed boundary.
 // ---------------------------------------------------------------------------
@@ -122,29 +126,82 @@ export function parseCodexNativeRequest(raw) {
 // ---------------------------------------------------------------------------
 // §3.3 tool_choice — exact inversion of codexFallback.ts's convertClaudeRequestToCodex.
 // ---------------------------------------------------------------------------
-function mapCodexToolChoiceToClaude(choice) {
-    if (choice === undefined) {
-        return undefined;
+// Absent tool_choice and "auto" both mean the same thing to Codex, and both
+// now map to an *explicit* `{type:"auto"}` (previously: `undefined` for the
+// absent case) so `disable_parallel_tool_use` always has a field on the
+// output to attach to, regardless of whether the source request bothered to
+// say "auto" out loud. `parallel_tool_calls: false` is inert on `"none"` —
+// there is nothing running in parallel to disable.
+function mapCodexToolChoiceToClaude(choice, parallelToolCalls) {
+    const disable = parallelToolCalls === false;
+    if (choice === undefined || choice === "auto") {
+        return disable
+            ? { type: "auto", disable_parallel_tool_use: true }
+            : { type: "auto" };
     }
     if (choice === "required") {
-        return { type: "any" };
-    }
-    if (choice === "auto") {
-        return { type: "auto" };
+        return disable
+            ? { type: "any", disable_parallel_tool_use: true }
+            : { type: "any" };
     }
     if (choice === "none") {
         return { type: "none" };
     }
-    return { type: "tool", name: choice.name };
+    return disable
+        ? { type: "tool", name: choice.name, disable_parallel_tool_use: true }
+        : { type: "tool", name: choice.name };
 }
 // ---------------------------------------------------------------------------
 // §3.4 Tools: flattened across namespaces, split by each declaration's own type.
 // ---------------------------------------------------------------------------
+/**
+ * Detection-only walk of a schema's `$ref` chain, independent of
+ * `inlineJsonSchema`'s own flattening — the actual flattening stays fully
+ * delegated to that function unmodified (never reimplemented here), so this
+ * only answers "would a ref chain revisit itself" for the schemaDegraded
+ * counter's benefit.
+ */
+function hasCircularRef(schema, defs, seen = new Set()) {
+    if (typeof schema.$ref === "string" && schema.$ref.startsWith("#/")) {
+        if (seen.has(schema.$ref)) {
+            return true;
+        }
+        const key = schema.$ref.split("/").pop();
+        const target = defs && key ? defs[key] : undefined;
+        return target
+            ? hasCircularRef(target, defs, new Set(seen).add(schema.$ref))
+            : false;
+    }
+    const properties = isRecord(schema.properties)
+        ? Object.values(schema.properties)
+        : [];
+    const items = Array.isArray(schema.items)
+        ? schema.items
+        : isRecord(schema.items)
+            ? [schema.items]
+            : [];
+    return [...properties, ...items].some((value) => isRecord(value) && hasCircularRef(value, defs, seen));
+}
 function mapCodexFunctionToolToClaude(tool) {
+    const reasons = [];
+    const defs = (tool.parameters.definitions ?? tool.parameters.$defs);
+    if (defs && hasCircularRef(tool.parameters, defs)) {
+        reasons.push("circular_ref_flattened");
+    }
+    const input_schema = inlineJsonSchema(tool.parameters);
+    if (tool.strict) {
+        // Anthropic tool declarations have no `strict`-mode equivalent, so the
+        // flag is dropped rather than silently passed through as an unknown key.
+        reasons.push("strict_mode_flag_dropped");
+    }
     return {
-        name: tool.name,
-        ...(tool.description ? { description: tool.description } : {}),
-        input_schema: tool.parameters,
+        tool: {
+            name: tool.name,
+            ...(tool.description ? { description: tool.description } : {}),
+            input_schema,
+        },
+        kind: "function",
+        reasons,
     };
 }
 function mapCodexCustomToolToClaude(tool) {
@@ -152,23 +209,27 @@ function mapCodexCustomToolToClaude(tool) {
     // The model is no longer grammar-constrained after this mapping — needs
     // product sign-off before shipping (§10 of the design).
     return {
-        name: tool.name,
-        description: [
-            tool.description,
-            `Grammar (${tool.format.syntax}):\n${tool.format.definition}`,
-        ]
-            .filter((s) => Boolean(s))
-            .join("\n\n"),
-        input_schema: {
-            type: "object",
-            properties: {
-                input: {
-                    type: "string",
-                    description: "Raw command text, constrained by the grammar in this tool's description.",
+        tool: {
+            name: tool.name,
+            description: [
+                tool.description,
+                `Grammar (${tool.format.syntax}):\n${tool.format.definition}`,
+            ]
+                .filter((s) => Boolean(s))
+                .join("\n\n"),
+            input_schema: {
+                type: "object",
+                properties: {
+                    input: {
+                        type: "string",
+                        description: "Raw command text, constrained by the grammar in this tool's description.",
+                    },
                 },
+                required: ["input"],
             },
-            required: ["input"],
         },
+        kind: "custom",
+        reasons: ["custom_tool_wrapped"],
     };
 }
 function mapCodexToolDeclarationToClaude(tool) {
@@ -182,10 +243,14 @@ function mapCodexToolDeclarationToClaude(tool) {
 }
 function buildClaudeTools(additionalTools) {
     if (!additionalTools) {
-        return undefined;
+        return { tools: undefined, toolKindByName: new Map(), reasons: [] };
     }
-    const tools = additionalTools.tools.flatMap((namespace) => namespace.tools.map(mapCodexToolDeclarationToClaude));
-    return tools.length > 0 ? tools : undefined;
+    const mapped = additionalTools.tools.flatMap((namespace) => namespace.tools.map(mapCodexToolDeclarationToClaude));
+    return {
+        tools: mapped.length > 0 ? mapped.map((m) => m.tool) : undefined,
+        toolKindByName: new Map(mapped.map((m) => [m.tool.name, m.kind])),
+        reasons: mapped.flatMap((m) => m.reasons.map((reason) => ({ toolName: m.tool.name, reason }))),
+    };
 }
 // ---------------------------------------------------------------------------
 // §3.5 Reasoning: reasoning.effort -> thinking.
@@ -210,19 +275,23 @@ function mapCodexReasoningToThinking(reasoning, resolvedMaxTokens) {
     return { type: "enabled", budget_tokens };
 }
 // ---------------------------------------------------------------------------
-// §3.6 Non-JSON function_call.arguments — never throws.
+// §3.6 Non-JSON function_call.arguments — never throws. Parsing itself is
+// `parseToolArguments` (argumentParsing.ts); this is a cheap, separate,
+// redundant check purely so a malformed (non-empty, non-record) arguments
+// string can be reported via the unsupportedFieldTotal counter without
+// polluting that pure function's return shape with a degrade flag.
 // ---------------------------------------------------------------------------
-function parseInboundToolArguments(raw) {
+function isMalformedFunctionArguments(raw) {
+    if (raw === "") {
+        return false;
+    }
     try {
         const parsed = JSON.parse(raw);
-        if (isRecord(parsed)) {
-            return parsed;
-        }
+        return !isRecord(parsed);
     }
     catch {
-        // fall through — not JSON at all (e.g. exec's raw shell command)
+        return true;
     }
-    return { input: raw };
 }
 // ---------------------------------------------------------------------------
 // §3.7 Content parts, with the image data-URI fix.
@@ -299,8 +368,8 @@ function coalesceCodexInputToClaudeMessages(items) {
                 // A custom tool is declared with a single `input` string (§3.4), so
                 // its raw call text maps onto that field unchanged.
                 input: item.type === "function_call"
-                    ? parseInboundToolArguments(item.arguments)
-                    : { input: item.input },
+                    ? parseToolArguments(item.arguments, "function")
+                    : parseToolArguments(item.input, "custom"),
             });
             continue;
         }
@@ -342,6 +411,32 @@ function hasFreshSessionPreamble(items) {
     return items[0]?.type === "additional_tools";
 }
 // ---------------------------------------------------------------------------
+// Tool-call history ceilings — the same streamLimits.ts numbers the response
+// leg enforces, so a history is never accepted that the reply could not carry.
+// ---------------------------------------------------------------------------
+function toolHistoryText(item) {
+    switch (item.type) {
+        case "function_call":
+            return item.arguments;
+        case "custom_tool_call":
+            return item.input;
+        case "function_call_output":
+        case "custom_tool_call_output":
+            return item.output;
+        default:
+            return undefined;
+    }
+}
+function describeOversizedToolHistory(items) {
+    const calls = items.filter((item) => item.type === "function_call" || item.type === "custom_tool_call").length;
+    if (calls > CODEX_STREAM_MAX_TOOL_CALLS) {
+        return `the history carries ${calls} tool calls, over the limit of ${CODEX_STREAM_MAX_TOOL_CALLS}`;
+    }
+    return items.some((item) => (toolHistoryText(item)?.length ?? 0) > CODEX_STREAM_SIZE_CEILING_BYTES)
+        ? `a tool call's arguments or output exceed the limit of ${CODEX_STREAM_SIZE_CEILING_BYTES} characters`
+        : undefined;
+}
+// ---------------------------------------------------------------------------
 // Inputs Codex accepts but the Messages API rejects — fail loud, never guess.
 // ---------------------------------------------------------------------------
 function describeUntranslatableItem(item, provider) {
@@ -423,6 +518,13 @@ function lastAssistantMessageUsesTool(messages) {
 // §3.2 translateCodexRequestToClaude — the full field-by-field mapping.
 // ---------------------------------------------------------------------------
 export function translateCodexRequestToClaude(request, target) {
+    const oversized = describeOversizedToolHistory(request.input);
+    if (oversized) {
+        return {
+            ok: false,
+            error: { code: "REQUEST_TOO_LARGE", message: oversized },
+        };
+    }
     // Read from client_metadata, not top-level session_id/thread_id: the real
     // capture carries neither at top level (only nested in client_metadata),
     // which is why CodexNativeRequest has no top-level fields for them.
@@ -451,9 +553,9 @@ export function translateCodexRequestToClaude(request, target) {
     const additionalTools = request.input
         .filter((item) => item.type === "additional_tools")
         .at(-1);
-    const tools = buildClaudeTools(additionalTools);
-    const toolChoice = mapCodexToolChoiceToClaude(request.tool_choice);
-    const forcesTool = toolChoice?.type === "any" || toolChoice?.type === "tool";
+    const { tools, toolKindByName, reasons: schemaReasons, } = buildClaudeTools(additionalTools);
+    const toolChoice = mapCodexToolChoiceToClaude(request.tool_choice, request.parallel_tool_calls);
+    const forcesTool = toolChoice.type === "any" || toolChoice.type === "tool";
     if (forcesTool && !tools) {
         return {
             ok: false,
@@ -463,7 +565,7 @@ export function translateCodexRequestToClaude(request, target) {
             },
         };
     }
-    if (toolChoice?.type === "tool" &&
+    if (toolChoice.type === "tool" &&
         !tools?.some((tool) => tool.name === toolChoice.name)) {
         return {
             ok: false,
@@ -507,9 +609,27 @@ export function translateCodexRequestToClaude(request, target) {
         ...(systemBlocks.length > 0 ? { system: systemBlocks } : {}),
         ...(tools ? { tools } : {}),
         // The Messages API accepts tool_choice only alongside tools.
-        ...(toolChoice && tools ? { tool_choice: toolChoice } : {}),
+        ...(tools ? { tool_choice: toolChoice } : {}),
         ...(thinking ? { thinking } : {}),
         stream: request.stream ?? true,
     };
-    return { ok: true, value: claudeRequest };
+    // Recorded only once translation has fully succeeded, so a request that is
+    // rejected earlier (malformed tool_choice, untranslatable content, a
+    // pairing gap) never fires a degrade counter for work that was discarded.
+    for (const reason of schemaReasons) {
+        recordCodexOutboundSchemaDegraded({
+            toolName: reason.toolName,
+            reason: reason.reason,
+        });
+    }
+    for (const item of request.input) {
+        if (item.type === "function_call" &&
+            isMalformedFunctionArguments(item.arguments)) {
+            recordCodexOutboundUnsupportedField({
+                field: "function_call.arguments",
+                reason: "malformed_arguments_wrapped",
+            });
+        }
+    }
+    return { ok: true, value: claudeRequest, toolKindByName };
 }

package/dist/proxy/codexResponsesFormat.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Wire-format translation: Anthropic `ClaudeResponse` shape -> the Codex
+ * Responses shape a native Codex client expects.
+ *
+ * Pure wire-format only — no account selection, retry policy, or transport.
+ * Mirrors `claudeFormat.ts`'s role for the opposite direction: that module
+ * serializes NeuroLink's internal result into Claude SSE, this one serializes
+ * an already-Claude-shaped result into Codex SSE (or one JSON envelope).
+ */
+import type { ClaudeContentBlock, ClaudeResponse, ClaudeUsage, CodexNativeToolKind, CodexResponseEnvelope, CodexResponseItem, CodexResponseUsage } from "../types/index.js";
+/** Same idiom as `generateToolUseId` (`claudeFormat.ts`), Codex's own prefix. */
+export declare function generateCodexResponseId(): string;
+/** Item ids are prefixed by kind so a client can tell message/tool items apart at a glance. */
+export declare function generateCodexItemId(kind: "message" | "function_call" | "custom_tool_call"): string;
+/**
+ * Reuse the Anthropic `tool_use.id` (`toolu_...`) verbatim as the Codex `call_id`.
+ * No id-mapping table exists anywhere in this codebase's translation modules, and
+ * nothing on the way in validates `call_id` format — see the design doc's §5 for
+ * the full reasoning and its one unresolved edge (a real, non-fallback Codex
+ * backend rejecting a non-`call_`-prefixed id on a later turn).
+ */
+export declare function codexCallIdFromToolUseId(toolUseId: string): string;
+/**
+ * Absent cache fields are omitted rather than zeroed (never conflate "not
+ * observed" with "observed as zero" — the field's own doc comment on
+ * `CodexResponseUsage` states this contract).
+ */
+export declare function synthesizeCodexUsage(usage: ClaudeUsage): CodexResponseUsage;
+/**
+ * Shared by the streaming serializer's non-failure item close and the
+ * non-streaming path (`serializeCodexResponse`), so item shape is defined
+ * once. Always produces a "completed" item — the streaming failure path
+ * (an item closed "incomplete" mid-turn) builds its item directly, since it
+ * must preserve the raw accumulated text/argument bytes rather than a value
+ * reconstructed through this function.
+ */
+export declare function buildCodexResponseItem(block: ClaudeContentBlock, itemId: string, toolKindByName?: ReadonlyMap<string, CodexNativeToolKind>): CodexResponseItem | null;
+/** Non-streaming path: `§7` of the design — the document root IS a `CodexResponseEnvelope`. */
+export declare function serializeCodexResponse(result: ClaudeResponse, requestModel: string, toolKindByName?: ReadonlyMap<string, CodexNativeToolKind>): CodexResponseEnvelope;
+/**
+ * Push-based streaming serializer. A genuinely incremental tool-call-argument
+ * path (`openToolCall`/`pushToolCallArgsDelta`/`closeToolCall`) forwards each
+ * raw `input_json_delta` chunk as it arrives rather than buffering the whole
+ * call before emitting anything — `partial_json` is not individually valid
+ * JSON, so a serializer that validated per-chunk could not do this.
+ */
+export declare class CodexResponsesStreamSerializer {
+    private readonly model;
+    private readonly toolKindByName;
+    private state;
+    private readonly responseId;
+    private outputIndex;
+    private openKind;
+    private openItemId;
+    private textAccum;
+    private argsAccum;
+    private toolCallId;
+    private toolName;
+    private readonly closedItems;
+    private terminalEnvelope;
+    constructor(model: string, toolKindByName?: ReadonlyMap<string, CodexNativeToolKind>);
+    start(): Generator<string>;
+    pushDelta(text: string): Generator<string>;
+    /** Opens the tool-call item header at content_block_start, before any argument text
+     *  is known — mirrors what content_block_start already gives us (id, name). A tool
+     *  the request declared `custom` opens as a `custom_tool_call` item. */
+    openToolCall(toolUseId: string, name: string): Generator<string>;
+    /** Forwards one raw partial_json fragment as-is — no JSON.parse here, because a lone
+     *  fragment is not required to be valid JSON on its own. A custom call's fragments
+     *  are the `{"input":"..."}` wrapper, not client text, so they are only buffered;
+     *  `closeToolCall` emits the unwrapped input once the whole wrapper is known. */
+    pushToolCallArgsDelta(rawChunk: string): Generator<string>;
+    /**
+     * Public close for a tool-use block at `content_block_stop`. A no-op when no
+     * tool-call item is open, so a driver can call it unconditionally.
+     * Validates the accumulated arguments once, here — the one place validity
+     * is required. Throws on malformed JSON; the caller must catch and route to
+     * `emitFailure` (never swallowed, never retried after this point).
+     */
+    closeToolCall(): Generator<string>;
+    /**
+     * Public close for a text block at `content_block_stop`, mirroring
+     * `closeToolCall`'s role for the message item. A no-op when no message item
+     * is open, so a driver can call it unconditionally alongside `closeToolCall`
+     * without first inspecting which kind is currently open.
+     */
+    closeTextBlock(): Generator<string>;
+    finish(stopReason: string | null, usage: ClaudeUsage): Generator<string, CodexResponseEnvelope>;
+    /**
+     * Post-commit terminal path. Closes any open item as "incomplete" — now
+     * representable via `CodexResponseItemStatus` — then emits a single
+     * `response.failed`. Idempotent: a second call after this one already ran
+     * returns the same envelope without emitting further frames, so a driver
+     * that reaches it defensively from more than one place never double-emits.
+     */
+    emitFailure(_status: number, message: string, code?: string): Generator<string, CodexResponseEnvelope>;
+    private assertNotTerminal;
+    /**
+     * The custom-kind close: nothing was streamed live, so one input delta
+     * carries the whole unwrapped input, then its done event. Lenient where the
+     * function path throws: the wrapper is Claude's own output for the
+     * single-field schema `mapCodexCustomToolToClaude` declared, so a parse
+     * failure is an internal bug, and the raw accumulated text is emitted rather
+     * than failing the turn over it.
+     */
+    private closeCustomToolCall;
+    private openMessage;
+    /** Closes whichever item is currently open, as "incomplete" when `failed`. */
+    private closeOpenItem;
+    /**
+     * The failure-close counterpart to `closeToolCall`. Arguments are carried
+     * verbatim from `argsAccum` and never re-validated — `JSON.parse` is not
+     * called on the failure path, and no `function_call_arguments.done` is
+     * emitted, since the arguments never reached a validated, complete state.
+     */
+    private closeFailedFunctionCall;
+    /**
+     * The failure close for a custom call. Its accumulated bytes are Anthropic's
+     * JSON wrapper, not the client's grammar text, so `input` is the unwrapped
+     * string when the wrapper already parses and "" otherwise — an incomplete
+     * item is never executed. No input done event, as on the function path.
+     */
+    private closeFailedCustomToolCall;
+    private closeMessageItem;
+}