@juspay/neurolink 12.34.3 → 12.35.0

package/dist/proxy/proxyIR.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Exhaustiveness enforcement for the translation IR.
+ *
+ * A translation layer fails quietly: an unhandled content part or event variant
+ * becomes a missing tool call, and the only symptom is the next hop rejecting a
+ * request nobody can explain. `assertProxyIRExhaustive` makes that a compile
+ * error instead. Passing a value whose type is not `never` does not type-check,
+ * so a new IR variant breaks every `switch` that has not handled it.
+ *
+ * It throws at runtime as well, because the compile-time guarantee only holds for
+ * values that really are typed. A wire payload narrowed from `unknown` can reach a
+ * default branch at runtime, and failing loudly there beats translating a request
+ * with a silently dropped element.
+ */
+import type { ProxyIRContentPart, ProxyIRResponseEvent, ProxyIRTerminalOutcome, ProxyIRUnmappableValue } from "../types/index.js";
+/**
+ * Refuse an unhandled IR variant.
+ *
+ * `context` names the switch that failed, since the value alone rarely says which
+ * of several exhaustive switches over the same union let it through.
+ */
+export declare function assertProxyIRExhaustive(value: never, context: string): never;
+/** Mark a wire value no codec could represent, preserving it for the caller. */
+export declare function proxyIRUnmappable(sourceKind: string, reason: string, raw: unknown): ProxyIRUnmappableValue;
+/** Narrow a collected codec result to the unmappable marker. */
+export declare function isProxyIRUnmappable(value: unknown): value is ProxyIRUnmappableValue;
+/**
+ * Name a content part for a diagnostic.
+ *
+ * This lives in `src` rather than in the suite that asserts on it because
+ * `tsconfig.json` excludes `test`: an exhaustive switch written only in a test
+ * gives no compile-time guarantee at all. These describers are the shipped
+ * consumers that pin every union, so adding an IR variant fails `tsc --noEmit`
+ * here before it can reach a codec that silently drops it.
+ *
+ * Deliberately excludes the payload of text, thinking and tool arguments: a
+ * describer's output reaches logs and span attributes, and prompt content does
+ * not belong there.
+ */
+export declare function describeProxyIRPart(part: ProxyIRContentPart): string;
+/** Name a stream event for a diagnostic, without its payload. */
+export declare function describeProxyIRResponseEvent(event: ProxyIRResponseEvent): string;
+/** Name a terminal outcome, keeping an unmodelled upstream stop reason visible. */
+export declare function describeProxyIRTerminalOutcome(outcome: ProxyIRTerminalOutcome): string;

package/dist/proxy/proxyIR.js

@@ -0,0 +1,127 @@
+/**
+ * Exhaustiveness enforcement for the translation IR.
+ *
+ * A translation layer fails quietly: an unhandled content part or event variant
+ * becomes a missing tool call, and the only symptom is the next hop rejecting a
+ * request nobody can explain. `assertProxyIRExhaustive` makes that a compile
+ * error instead. Passing a value whose type is not `never` does not type-check,
+ * so a new IR variant breaks every `switch` that has not handled it.
+ *
+ * It throws at runtime as well, because the compile-time guarantee only holds for
+ * values that really are typed. A wire payload narrowed from `unknown` can reach a
+ * default branch at runtime, and failing loudly there beats translating a request
+ * with a silently dropped element.
+ */
+/**
+ * Refuse an unhandled IR variant.
+ *
+ * `context` names the switch that failed, since the value alone rarely says which
+ * of several exhaustive switches over the same union let it through.
+ */
+export function assertProxyIRExhaustive(value, context) {
+    throw new Error(`[proxy-ir] ${context} did not handle variant: ${describeProxyIRVariant(value)}`);
+}
+/**
+ * Describe a value for the exhaustiveness error without assuming its shape.
+ *
+ * The parameter is `never` at the call site, so nothing about it can be trusted
+ * here: it may be a primitive, or an object with no discriminant at all — and an
+ * untagged object is exactly the shape a malformed wire payload takes. Reviewed
+ * finding (PR #1826): serializing that object's fields defeated the point of a
+ * log/span-safe diagnostic, since the object can carry the same text or tool
+ * arguments the typed describers deliberately withhold. The fallback is now a
+ * fixed, shape-only marker — never the object's own content — for every
+ * untagged case, not only the ones this file happens to call today.
+ */
+function describeProxyIRVariant(value) {
+    if (value === null || typeof value !== "object") {
+        return String(value);
+    }
+    const record = value;
+    for (const discriminant of ["kind", "status", "source", "format"]) {
+        const tag = record[discriminant];
+        if (typeof tag === "string") {
+            return `${discriminant}=${tag}`;
+        }
+    }
+    return "[object without recognized discriminant]";
+}
+/** Mark a wire value no codec could represent, preserving it for the caller. */
+export function proxyIRUnmappable(sourceKind, reason, raw) {
+    return { proxyIRUnmappable: true, sourceKind, reason, raw };
+}
+/** Narrow a collected codec result to the unmappable marker. */
+export function isProxyIRUnmappable(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        value.proxyIRUnmappable === true);
+}
+/**
+ * Name a content part for a diagnostic.
+ *
+ * This lives in `src` rather than in the suite that asserts on it because
+ * `tsconfig.json` excludes `test`: an exhaustive switch written only in a test
+ * gives no compile-time guarantee at all. These describers are the shipped
+ * consumers that pin every union, so adding an IR variant fails `tsc --noEmit`
+ * here before it can reach a codec that silently drops it.
+ *
+ * Deliberately excludes the payload of text, thinking and tool arguments: a
+ * describer's output reaches logs and span attributes, and prompt content does
+ * not belong there.
+ */
+export function describeProxyIRPart(part) {
+    switch (part.kind) {
+        case "text":
+            return `text(${part.text.length}b)`;
+        case "thinking":
+            return `thinking(${part.text.length}b)`;
+        case "image":
+            return `image(${part.encoding})`;
+        case "tool_call":
+            return `tool_call(${part.toolName})`;
+        case "tool_result":
+            return `tool_result(${part.content.length} parts${part.isError ? ", error" : ""})`;
+        case "unmapped":
+            return `unmapped(${part.sourceKind}: ${part.reason})`;
+        default:
+            return assertProxyIRExhaustive(part, "describeProxyIRPart");
+    }
+}
+/** Name a stream event for a diagnostic, without its payload. */
+export function describeProxyIRResponseEvent(event) {
+    switch (event.kind) {
+        case "text_delta":
+            return `text_delta(${event.text.length}b)`;
+        case "thinking_delta":
+            return `thinking_delta(${event.text.length}b)`;
+        case "tool_call_start":
+            return `tool_call_start(${event.toolName})`;
+        case "tool_call_arguments_delta":
+            return `tool_call_arguments_delta(${event.partialArguments.length}b)`;
+        case "tool_call_done":
+            return "tool_call_done";
+        case "item_done":
+            return "item_done";
+        case "usage":
+            return "usage";
+        case "terminal":
+            return `terminal(${describeProxyIRTerminalOutcome(event.outcome)})`;
+        default:
+            return assertProxyIRExhaustive(event, "describeProxyIRResponseEvent");
+    }
+}
+/** Name a terminal outcome, keeping an unmodelled upstream stop reason visible. */
+export function describeProxyIRTerminalOutcome(outcome) {
+    switch (outcome.status) {
+        case "completed":
+            return outcome.finishReason === "other"
+                ? `completed:${outcome.rawFinishReason}`
+                : `completed:${outcome.finishReason}`;
+        case "failed":
+            return `failed:${outcome.error.code}`;
+        case "incomplete":
+            return `incomplete:${outcome.reason}`;
+        default:
+            return assertProxyIRExhaustive(outcome, "describeProxyIRTerminalOutcome");
+    }
+}

package/dist/types/index.d.ts

@@ -55,6 +55,7 @@ export * from "./providerCatalog.js";
 export * from "./providerCatalog.generated.js";
 export * from "./providers.js";
 export * from "./proxy.js";
+export * from "./proxyIR.js";
 export * from "./proxyClient.js";
 export * from "./proxyContext.js";
 export * from "./rag.js";

package/dist/types/index.js

@@ -59,6 +59,7 @@ export * from "./providerCatalog.js";
 export * from "./providerCatalog.generated.js";
 export * from "./providers.js";
 export * from "./proxy.js";
+export * from "./proxyIR.js";
 export * from "./proxyClient.js";
 export * from "./proxyContext.js";
 export * from "./rag.js";

package/dist/types/proxyIR.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Wire-neutral intermediate representation for proxy protocol translation.
+ *
+ * Translation between provider wire formats was previously pairwise and ad hoc:
+ * `codexFallback.ts` converts an Anthropic request into a Codex one and casts a
+ * role to reach Claude Code's inline-system convention inside a converter that is
+ * meant to be neutral. Adding the reverse direction pairwise would double that,
+ * and a third provider would square it.
+ *
+ * So each format gets a codec to and from this IR, and adding a provider is a new
+ * codec rather than new branching. The IR is deliberately not `ClaudeRequest`:
+ * that type is simultaneously the literal Anthropic wire shape, so using it as
+ * the hub makes every other provider's quirks leak into the Anthropic hot path.
+ * `ClaudeRequest` and `ClaudeResponse` stay untouched.
+ *
+ * Every union here is discriminated on a literal `kind`, `status` or `source`, so
+ * `assertProxyIRExhaustive` turns an unhandled variant into a compile error. That
+ * is the point of the IR: a field that cannot be represented must be stated, via
+ * `ProxyIRUnmappedPart`, rather than dropped silently.
+ */
+import type { CodexReasoningEffort } from "./codex.js";
+import type { UsageContext } from "./proxy.js";
+/**
+ * A wire dialect a codec can speak.
+ *
+ * Distinct from `ProxyFormat` ("claude" | "openai" | "gemini"), which selects a
+ * request-translation surface for a different subsystem. These must not be
+ * conflated: this one names the two dialects the fallback codecs translate.
+ */
+export type ProxyIRWireFormat = "anthropic-messages" | "codex-responses";
+/**
+ * Message roles across both dialects.
+ *
+ * `developer` has no Anthropic equivalent and is native Codex's own role for
+ * instruction blocks that sit inside the ordered input array rather than in a
+ * leading system field. It is kept distinct from `system` so a codec targeting
+ * Anthropic can decide where it belongs instead of inheriting a lossy merge.
+ */
+export type ProxyIRRole = "system" | "developer" | "user" | "assistant";
+/**
+ * A request to cache the prefix up to and including the annotated element.
+ *
+ * Only meaningful for Anthropic, whose caching is explicit and breakpoint-driven.
+ * A codec targeting a dialect with automatic caching ignores it, which is correct
+ * rather than lossy: nothing on that wire can carry it.
+ */
+export type ProxyIRCacheHint = {
+    ttl?: "5m" | "1h";
+};
+export type ProxyIRTextPart = {
+    kind: "text";
+    text: string;
+    cacheHint?: ProxyIRCacheHint;
+};
+/** `signature` is reserved for Anthropic's signed thinking blocks and unused today. */
+export type ProxyIRThinkingPart = {
+    kind: "thinking";
+    text: string;
+    signature?: string;
+};
+export type ProxyIRImagePart = {
+    kind: "image";
+    encoding: "base64" | "url";
+    mediaType?: string;
+    data: string;
+};
+/**
+ * A model-emitted call to a tool.
+ *
+ * `argumentsRaw` is authoritative and always present; `argumentsJson` is a
+ * convenience for the common case where the raw text parses. Keeping the raw text
+ * means a call whose arguments are streamed in fragments, or are not valid JSON,
+ * survives translation instead of being normalised into something the next hop
+ * never sent.
+ */
+export type ProxyIRToolCallPart = {
+    kind: "tool_call";
+    callId: string;
+    toolName: string;
+    argumentsRaw: string;
+    argumentsJson?: Record<string, unknown>;
+};
+export type ProxyIRToolResultPart = {
+    kind: "tool_result";
+    callId: string;
+    content: (ProxyIRTextPart | ProxyIRImagePart)[];
+    isError?: boolean;
+    cacheHint?: ProxyIRCacheHint;
+};
+/**
+ * A wire element no codec could represent, carried forward verbatim.
+ *
+ * The alternative is dropping it, which is how a translation layer loses tool
+ * calls: silently, and only visibly as a downstream rejection. `raw` keeps the
+ * original so a renderer can pass it through or a test can assert on it, and
+ * `reason` records why it could not be mapped.
+ */
+export type ProxyIRUnmappedPart = {
+    kind: "unmapped";
+    sourceKind: string;
+    reason: string;
+    raw: unknown;
+};
+export type ProxyIRContentPart = ProxyIRTextPart | ProxyIRThinkingPart | ProxyIRImagePart | ProxyIRToolCallPart | ProxyIRToolResultPart | ProxyIRUnmappedPart;
+/**
+ * One message, with system and developer messages kept in sequence.
+ *
+ * There is no separate bucket for leading instructions: native Codex sends
+ * instruction blocks as ordered `developer` items inside the input array, and
+ * lifting them out would lose their position relative to the conversation. A
+ * codec that needs a leading system field extracts it; the IR does not presume
+ * one exists.
+ */
+export type ProxyIRMessage = {
+    role: ProxyIRRole;
+    content: ProxyIRContentPart[];
+};
+export type ProxyIRFunctionToolDeclaration = {
+    kind: "function";
+    name: string;
+    description?: string;
+    parametersSchema: Record<string, unknown>;
+    cacheHint?: ProxyIRCacheHint;
+};
+/** A tool constrained by a grammar rather than a JSON schema; Codex-only today. */
+export type ProxyIRCustomGrammarToolDeclaration = {
+    kind: "custom_grammar";
+    name: string;
+    description?: string;
+    grammar: string;
+};
+export type ProxyIRToolDeclaration = ProxyIRFunctionToolDeclaration | ProxyIRCustomGrammarToolDeclaration;
+export type ProxyIRToolChoice = {
+    kind: "auto";
+} | {
+    kind: "none";
+} | {
+    kind: "any";
+} | {
+    kind: "named";
+    toolName: string;
+};
+/**
+ * Reasoning configuration, tagged by the dialect that expressed it.
+ *
+ * Anthropic budgets thinking in tokens; Codex selects a named effort level. There
+ * is no faithful numeric mapping between them, so the source is recorded and each
+ * codec decides how to honour the other's form rather than a lossy conversion
+ * happening once, invisibly, in the middle.
+ */
+export type ProxyIRReasoning = {
+    source: "none";
+} | {
+    source: "anthropic_thinking";
+    type: string;
+    budgetTokens?: number;
+} | {
+    source: "codex_effort";
+    effort: CodexReasoningEffort;
+};
+export type ProxyIRRequest = {
+    sourceFormat: ProxyIRWireFormat;
+    sourceModel: string;
+    originSessionId?: string;
+    originThreadId?: string;
+    messages: ProxyIRMessage[];
+    tools: ProxyIRToolDeclaration[];
+    toolChoice?: ProxyIRToolChoice;
+    reasoning: ProxyIRReasoning;
+    stream: boolean;
+    /** Prefix-derived routing hint. Never serialized onto any wire. */
+    promptCachePrefixKey?: string;
+};
+export type ProxyIRRequestTargetOptions = {
+    model: string;
+    reasoningEffort?: CodexReasoningEffort;
+};
+export type ProxyIRProviderError = {
+    code: string;
+    httpStatus?: number;
+    retryable?: boolean;
+    message?: string;
+};
+/**
+ * How a response ended.
+ *
+ * `finishReason: "other"` carries `rawFinishReason` because Anthropic's
+ * `stop_reason` is typed `string | null` on the wire, deliberately open. A closed
+ * union here would make any legitimate but unmodelled stop reason an
+ * exhaustiveness throw at runtime, turning a successful upstream response into a
+ * proxy failure.
+ */
+export type ProxyIRTerminalOutcome = {
+    status: "completed";
+    finishReason: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence";
+} | {
+    status: "completed";
+    finishReason: "other";
+    rawFinishReason: string;
+} | {
+    status: "failed";
+    error: ProxyIRProviderError;
+} | {
+    status: "incomplete";
+    reason: string;
+};
+export type ProxyIRResponseEvent = {
+    kind: "text_delta";
+    text: string;
+} | {
+    kind: "thinking_delta";
+    text: string;
+} | {
+    kind: "tool_call_start";
+    callId: string;
+    toolName: string;
+} | {
+    kind: "tool_call_arguments_delta";
+    callId: string;
+    partialArguments: string;
+} | {
+    kind: "tool_call_done";
+    callId: string;
+} | {
+    kind: "item_done";
+} | {
+    kind: "usage";
+    usage: UsageContext;
+} | {
+    kind: "terminal";
+    outcome: ProxyIRTerminalOutcome;
+};
+export type ProxyIROutputItem = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "thinking";
+    text: string;
+} | {
+    kind: "tool_call";
+    callId: string;
+    toolName: string;
+    argumentsRaw: string;
+    argumentsJson?: Record<string, unknown>;
+};
+export type ProxyIRResponse = {
+    items: ProxyIROutputItem[];
+    usage?: UsageContext;
+    outcome: ProxyIRTerminalOutcome;
+};
+/**
+ * Codec capabilities, kept separate rather than bundled into one interface.
+ *
+ * No dialect needs all four in every direction: for outbound Codex fallback, the
+ * Codex side is only ever parsed from and rendered to, never dispatched to, so a
+ * single monolithic codec type would force stub implementations whose only
+ * possible body is a throw.
+ */
+export type ProxyIRRequestParser<TWireRequest> = {
+    format: ProxyIRWireFormat;
+    parseRequest(wire: TWireRequest): ProxyIRRequest;
+};
+export type ProxyIRRequestBuilder<TWireRequest> = {
+    format: ProxyIRWireFormat;
+    buildRequest(ir: ProxyIRRequest, target: ProxyIRRequestTargetOptions): TWireRequest;
+};
+export type ProxyIRResponseParser = {
+    format: ProxyIRWireFormat;
+    parseBufferedResponse(wireText: string): ProxyIRResponse;
+    parseResponseStream(upstream: Response): AsyncGenerator<ProxyIRResponseEvent, ProxyIRResponse>;
+};
+export type ProxyIRResponseRenderer = {
+    format: ProxyIRWireFormat;
+    renderResponseEvent(event: ProxyIRResponseEvent): string[];
+    renderTerminalOutcome(outcome: ProxyIRTerminalOutcome, usage?: UsageContext): string[];
+};
+/** Marks a value a codec refused to map, for callers that collect rather than throw. */
+export type ProxyIRUnmappableValue = {
+    proxyIRUnmappable: true;
+    sourceKind: string;
+    reason: string;
+    raw: unknown;
+};

package/dist/types/proxyIR.js

@@ -0,0 +1,21 @@
+/**
+ * Wire-neutral intermediate representation for proxy protocol translation.
+ *
+ * Translation between provider wire formats was previously pairwise and ad hoc:
+ * `codexFallback.ts` converts an Anthropic request into a Codex one and casts a
+ * role to reach Claude Code's inline-system convention inside a converter that is
+ * meant to be neutral. Adding the reverse direction pairwise would double that,
+ * and a third provider would square it.
+ *
+ * So each format gets a codec to and from this IR, and adding a provider is a new
+ * codec rather than new branching. The IR is deliberately not `ClaudeRequest`:
+ * that type is simultaneously the literal Anthropic wire shape, so using it as
+ * the hub makes every other provider's quirks leak into the Anthropic hot path.
+ * `ClaudeRequest` and `ClaudeResponse` stay untouched.
+ *
+ * Every union here is discriminated on a literal `kind`, `status` or `source`, so
+ * `assertProxyIRExhaustive` turns an unhandled variant into a compile error. That
+ * is the point of the IR: a field that cannot be represented must be stated, via
+ * `ProxyIRUnmappedPart`, rather than dropped silently.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.34.3",
+  "version": "12.35.0",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {