@juspay/neurolink 12.20.1 → 12.21.0

package/dist/server/routes/claudeProxyRoutes.d.ts

@@ -175,6 +175,22 @@ declare function trackUpstreamReadableStream(source: ReadableStream<Uint8Array>)
  * diagnostics the operator wants.
  */
 declare function redactHeadersForBorrower(headers: Record<string, string>): Record<string, string>;
+/**
+ * The model that actually served a fallback turn.
+ *
+ * One request can leave more than one leg's model in metadata: the Codex leg
+ * records its model on the failure path before the chain moves on, and the
+ * configured chain tries Codex first. Choosing by key precedence therefore
+ * billed a Vertex-served turn as the Codex model — the exact misattribution
+ * this file's pricing fix exists to prevent. The account type that reached
+ * `logFinalRequest` is the only authoritative signal for which leg answered,
+ * so select on that and ignore the other leg's leftovers.
+ */
+export declare function resolveServedFallbackModel(metadata: {
+    codexFallbackModel?: unknown;
+    vertexFallbackModel?: unknown;
+}, accountType: string | undefined): string | undefined;
+declare function clearClaudeFallbackTerminalEvidence(ctx: ServerContext): void;
 declare function executeClaudeFallbackTranslation(args: {
     ctx: ServerContext;
     body: ClaudeRequest;
@@ -462,6 +478,7 @@ export declare function isTransientHttpFailure(status: number, errBody: string):
 export declare function isUpstreamOverload(status: number, errBody: string): boolean;
 export declare function redactProviderErrorMessage(message: string): string;
 export declare const __testHooks: {
+    clearClaudeFallbackTerminalEvidence: typeof clearClaudeFallbackTerminalEvidence;
     normalizeQuotaForAccounts: typeof normalizeQuotaForAccounts;
     resolveHomeIndex: typeof resolveHomeIndex;
     maybeResetPrimaryToHome: typeof maybeResetPrimaryToHome;

package/dist/server/routes/claudeProxyRoutes.js

@@ -100,6 +100,16 @@ function resolveRequestLogAccountIdentity(accountLabel, accountType) {
             provider: "anthropic",
         };
     }
+    if (accountType === "vertex") {
+        // A native fallback leg has no OAuth login — the account IS the served
+        // model, e.g. "vertex/claude-opus-4-6". Without this branch `provider`
+        // stays unset, `annotateRequestPricing` falls back to
+        // "openai-compatible", and that resolves to a cross-provider scan which
+        // prices the turn from the *requested* alias in the Anthropic table
+        // instead of the served model in the Vertex one — a 2.5x under-report on
+        // the only leg that bills in real currency.
+        return { accountKey: accountLabel, provider: "vertex" };
+    }
     return {};
 }
 // ---------------------------------------------------------------------------
@@ -3567,11 +3577,29 @@ async function loadClaudeProxyAccounts(args) {
         isClaudeClientRequest: isLikelyClaudeClient(clientHeaders, clientSnapshotBody),
     };
 }
+/**
+ * The model that actually served a fallback turn.
+ *
+ * One request can leave more than one leg's model in metadata: the Codex leg
+ * records its model on the failure path before the chain moves on, and the
+ * configured chain tries Codex first. Choosing by key precedence therefore
+ * billed a Vertex-served turn as the Codex model — the exact misattribution
+ * this file's pricing fix exists to prevent. The account type that reached
+ * `logFinalRequest` is the only authoritative signal for which leg answered,
+ * so select on that and ignore the other leg's leftovers.
+ */
+export function resolveServedFallbackModel(metadata, accountType) {
+    const served = accountType === "vertex"
+        ? metadata.vertexFallbackModel
+        : metadata.codexFallbackModel;
+    return typeof served === "string" && served.length > 0 ? served : undefined;
+}
 function clearClaudeFallbackTerminalEvidence(ctx) {
     for (const key of [
         "codexFallbackAccount",
         "codexFallbackAccountType",
         "codexFallbackModel",
+        "vertexFallbackModel",
         "codexFallbackFailureUsage",
         "codexFallbackDeferredFailure",
         "sdkFallbackFailure",
@@ -4054,6 +4082,19 @@ async function tryConfiguredClaudeFallbackChain(args) {
                 // the caller's pending tool call, which strands every agentic turn.
                 const vertexModel = fallback.model;
                 const vertexAccount = `vertex/${vertexModel}`;
+                // A Codex leg that already failed left its own terminal evidence
+                // behind — its model, account, deferred-failure flag and failure
+                // usage. Every one of those is read again when this turn finalizes:
+                // the model would be logged and priced in place of the Vertex one,
+                // the deferred-failure branch would re-attribute the tracer to
+                // "openai" after the Vertex leg set it, and the failure usage would
+                // merge its reasoning tokens into this turn's counts. Start the leg
+                // clean, the same way a fresh upstream dispatch does.
+                clearClaudeFallbackTerminalEvidence(ctx);
+                // Billing follows the model that served the turn. The request log
+                // otherwise records `body.model` — the alias the client asked for —
+                // and prices Opus-on-Vertex at Sonnet rates.
+                ctx.metadata.vertexFallbackModel = vertexModel;
                 response = await executeVertexAnthropicFallback({
                     body,
                     model: vertexModel,
@@ -6212,18 +6253,24 @@ function createClaudeRequestRuntimeContext(args) {
             recordFinalSuccess(finalAccountLabel, finalAccountType);
         }
         const traceCtx = tracer?.getTraceContext();
+        const servedModel = resolveServedFallbackModel(ctx.metadata, finalAccountType);
         logRequest({
             timestamp: new Date().toISOString(),
             requestId: ctx.requestId,
             method: ctx.method,
             path: ctx.path,
-            model: typeof ctx.metadata.codexFallbackModel === "string"
-                ? ctx.metadata.codexFallbackModel
-                : body.model,
-            ...(typeof ctx.metadata.codexFallbackModel === "string"
+            model: servedModel ?? body.model,
+            ...(servedModel
                 ? {
                     requestedModel: body.model,
-                    inputIncludesCachedTokens: false,
+                    // Codex reports input inclusive of cached tokens; the Vertex
+                    // Anthropic wire reports them separately, exactly as the native
+                    // path does, so the flag stays Codex-only. Keyed off the serving
+                    // account for the same reason `servedModel` is: a failed Codex leg
+                    // leaves its model behind on a turn Vertex went on to serve.
+                    ...(finalAccountType === "vertex"
+                        ? {}
+                        : { inputIncludesCachedTokens: false }),
                 }
                 : {}),
             ...(ctx.metadata.contextPreflight
@@ -8777,6 +8824,7 @@ export function redactProviderErrorMessage(message) {
 // spinning up a full proxy. Keep this surface small.
 // ---------------------------------------------------------------------------
 export const __testHooks = {
+    clearClaudeFallbackTerminalEvidence,
     normalizeQuotaForAccounts,
     resolveHomeIndex,
     maybeResetPrimaryToHome,

package/dist/types/classifierRouter.d.ts

@@ -296,6 +296,10 @@ export type ClassifierRouterInput = {
     requiresVision?: boolean;
     thinkingLevel?: string;
     sessionId?: string;
+    /** Whether this request is tied to a session, independent of the (withheld) session id itself. */
+    sessionBound?: boolean;
+    /** Number of prior conversation messages the caller supplied, when known. */
+    priorMessageCount?: number;
 };
 /** Enriched per-model metadata used while ranking pool members. */
 export type ClassifierModelMeta = {

package/dist/types/cli.d.ts

@@ -1296,6 +1296,18 @@ export type AutoresearchInitArgs = {
     provider?: string;
     model?: string;
 };
+/** Arguments for `neurolink decide` — the third inference type's CLI surface. */
+export type CliDecideArgs = {
+    state?: string;
+    stateFile?: string;
+    questions?: string;
+    questionsFile?: string;
+    provider?: string;
+    model?: string;
+    timeout?: number;
+    format?: "text" | "json";
+    debug?: boolean;
+};
 /** Base options shared across all `neurolink evaluate` subcommands. */
 export type BaseEvaluateArgs = {
     json?: boolean;

package/dist/types/providers.d.ts

@@ -2281,6 +2281,14 @@ export type VertexAnthropicTool = {
     };
     cache_control?: VertexAnthropicCacheControl;
 };
+/**
+ * Supplies the bearer token for a Vertex publisher call.
+ *
+ * Exists so a test can stand in for the Google credential lookup: gaxios
+ * resolves its transport to node-fetch rather than `globalThis.fetch`, so a
+ * test that swaps the global cannot intercept the token exchange.
+ */
+export type VertexAccessTokenProvider = () => Promise<string | null | undefined>;
 /** Input to `applyVertexAnthropicCacheBreakpoints`. */
 export type VertexAnthropicCacheInput = {
     system?: string;

package/dist/types/proxy.d.ts

@@ -42,10 +42,27 @@ export type ModelRouterInterface = {
     getModelMappings?: () => ModelMapping[];
     getPassthroughModels?: () => string[];
 };
+/**
+ * Anthropic prompt-cache breakpoint marker.
+ *
+ * Anthropic caching is explicit: the prefix up to each marker is cached, and a
+ * request carrying none is cached not at all. Four markers is the hard ceiling.
+ */
+export type ClaudeCacheControl = {
+    type: "ephemeral";
+    /**
+     * How long the marked prefix stays cached. The API accepts a 5-minute or a
+     * 1-hour window, priced at 1.25x and 2x base input respectively; omitting it
+     * means 5 minutes. Without this field a caller cannot express the 1-hour
+     * marker at all.
+     */
+    ttl?: "5m" | "1h";
+};
 /** A single text block in a Claude content array. */
 export type ClaudeTextBlock = {
     type: "text";
     text: string;
+    cache_control?: ClaudeCacheControl;
 };
 /** A single image block in a Claude content array. */
 export type ClaudeImageBlock = {
@@ -69,6 +86,7 @@ export type ClaudeToolResultBlock = {
     type: "tool_result";
     tool_use_id: string;
     content: string | ClaudeContentBlock[];
+    cache_control?: ClaudeCacheControl;
 };
 /** A thinking/reasoning block in a Claude content array. */
 export type ClaudeThinkingBlock = {
@@ -86,6 +104,7 @@ export type ClaudeTool = {
     name: string;
     description?: string;
     input_schema: Record<string, unknown>;
+    cache_control?: ClaudeCacheControl;
 };
 /** Metadata attached to a Claude Messages API request. */
 export type ClaudeMetadata = {
@@ -99,10 +118,7 @@ export type ClaudeRequest = {
     model: string;
     messages: ClaudeMessage[];
     max_tokens: number;
-    system?: string | Array<{
-        type: "text";
-        text: string;
-    }>;
+    system?: string | ClaudeTextBlock[];
     temperature?: number;
     top_p?: number;
     top_k?: number;

package/dist/utils/anthropicCacheBreakpoints.d.ts

@@ -1,4 +1,4 @@
-import type { VertexAnthropicCacheInput, VertexAnthropicCacheOutput, VertexAnthropicMessage } from "../types/index.js";
+import type { ClaudeRequest, VertexAnthropicCacheInput, VertexAnthropicCacheOutput, VertexAnthropicMessage } from "../types/index.js";
 /** Anthropic allows at most four `cache_control` breakpoints per request. */
 export declare const ANTHROPIC_MAX_CACHE_BREAKPOINTS = 4;
 /**
@@ -41,3 +41,24 @@ export declare function countAnthropicCacheMarkers(input: {
  * the input array is cloned, never mutated.
  */
 export declare function applyAnthropicHistoryCacheBreakpoints(input: ReadonlyArray<VertexAnthropicMessage>, budget: number): VertexAnthropicMessage[];
+/**
+ * Breakpoint placement for a Claude Messages request the proxy built itself,
+ * rather than one a client authored.
+ *
+ * A request translated from another wire format arrives with no markers at
+ * all, because the format it came from has no way to express one: OpenAI-shaped
+ * callers rely on automatic prefix caching, which Anthropic does not do. A
+ * faithful translation is therefore cached at 0% on every turn, and a caller
+ * that fell back here from an exhausted pool burns the replacement quota faster
+ * than the one it was spared.
+ *
+ * Placement follows Anthropic's `tools → system → messages` rendering: one
+ * marker on the last system block covers tools *and* system in a single
+ * breakpoint, and the rest roll along the tail of the history so a growing
+ * conversation keeps its settled prefix cached. Markers the caller supplied are
+ * counted first and never displaced — this only spends what is left of the
+ * four.
+ *
+ * Pure: inputs are cloned, never mutated.
+ */
+export declare function applyClaudeRequestCacheBreakpoints(request: ClaudeRequest): ClaudeRequest;

package/dist/utils/anthropicCacheBreakpoints.js

@@ -148,3 +148,116 @@ function markLastContentBlock(messages, i) {
     messages[i] = { ...message, content };
     return true;
 }
+/**
+ * Breakpoint placement for a Claude Messages request the proxy built itself,
+ * rather than one a client authored.
+ *
+ * A request translated from another wire format arrives with no markers at
+ * all, because the format it came from has no way to express one: OpenAI-shaped
+ * callers rely on automatic prefix caching, which Anthropic does not do. A
+ * faithful translation is therefore cached at 0% on every turn, and a caller
+ * that fell back here from an exhausted pool burns the replacement quota faster
+ * than the one it was spared.
+ *
+ * Placement follows Anthropic's `tools → system → messages` rendering: one
+ * marker on the last system block covers tools *and* system in a single
+ * breakpoint, and the rest roll along the tail of the history so a growing
+ * conversation keeps its settled prefix cached. Markers the caller supplied are
+ * counted first and never displaced — this only spends what is left of the
+ * four.
+ *
+ * Pure: inputs are cloned, never mutated.
+ */
+export function applyClaudeRequestCacheBreakpoints(request) {
+    const existing = countAnthropicCacheMarkers({
+        system: request.system,
+        tools: request.tools,
+        messages: [],
+    });
+    const inMessages = request.messages.reduce((n, m) => n +
+        (Array.isArray(m.content)
+            ? m.content.filter((b) => "cache_control" in b && b.cache_control)
+                .length
+            : 0), 0);
+    let budget = MAX_BREAKPOINTS - existing - inMessages;
+    if (budget <= 0) {
+        return request;
+    }
+    const out = { ...request };
+    // One marker on the stable head. The last system block is the better anchor
+    // than the last tool, because system renders after tools and so a single
+    // marker there caches both.
+    if (Array.isArray(out.system) && out.system.length > 0 && existing === 0) {
+        const system = out.system.map((b) => ({ ...b }));
+        system[system.length - 1] = {
+            ...system[system.length - 1],
+            cache_control: CLAUDE_EPHEMERAL,
+        };
+        out.system = system;
+        budget--;
+    }
+    else if ((!out.system || (Array.isArray(out.system) && out.system.length === 0)) &&
+        out.tools &&
+        out.tools.length > 0 &&
+        existing === 0) {
+        const tools = out.tools.map((t) => ({ ...t }));
+        tools[tools.length - 1] = {
+            ...tools[tools.length - 1],
+            cache_control: CLAUDE_EPHEMERAL,
+        };
+        out.tools = tools;
+        budget--;
+    }
+    if (budget > 0) {
+        out.messages = applyClaudeHistoryBreakpoints(out.messages, budget);
+    }
+    return out;
+}
+const CLAUDE_EPHEMERAL = { type: "ephemeral" };
+/**
+ * Roll `budget` markers backwards along the history, marking the last content
+ * block of each message that can carry one. Only text and tool_result blocks
+ * accept `cache_control`; a message ending in anything else is skipped without
+ * spending budget.
+ *
+ * A message whose content is a plain string is promoted to the single text
+ * block the marker has to live on. Skipping strings instead would have left an
+ * ordinary conversation with no history breakpoint at all, since the OpenAI
+ * bridge emits every plain-text turn as a string — which is precisely the
+ * growing history this is here to keep cached.
+ */
+function applyClaudeHistoryBreakpoints(input, budget) {
+    const messages = input.map((m) => ({ ...m }));
+    let remaining = Math.max(0, Math.min(budget, MAX_BREAKPOINTS));
+    for (let i = messages.length - 1; i >= 0 && remaining > 0; i--) {
+        const content = messages[i].content;
+        if (typeof content === "string") {
+            if (content.length === 0) {
+                continue;
+            }
+            messages[i] = {
+                ...messages[i],
+                content: [
+                    { type: "text", text: content, cache_control: CLAUDE_EPHEMERAL },
+                ],
+            };
+            remaining--;
+            continue;
+        }
+        if (!Array.isArray(content) || content.length === 0) {
+            continue;
+        }
+        const last = content[content.length - 1];
+        if (last.type !== "text" && last.type !== "tool_result") {
+            continue;
+        }
+        if (last.cache_control) {
+            continue;
+        }
+        const blocks = content.map((b) => ({ ...b }));
+        blocks[blocks.length - 1] = { ...last, cache_control: CLAUDE_EPHEMERAL };
+        messages[i] = { ...messages[i], content: blocks };
+        remaining--;
+    }
+    return messages;
+}

package/dist/utils/logger.d.ts

@@ -19,6 +19,7 @@ declare class NeuroLinkLogger {
     private logs;
     private maxLogs;
     private isDebugMode;
+    private diagnosticsToStderr;
     private eventEmitter?;
     constructor();
     /**
@@ -49,6 +50,14 @@ declare class NeuroLinkLogger {
      * @param level - The minimum log level to process ("debug", "info", "warn", or "error")
      */
     setLogLevel(level: LogLevel): void;
+    /**
+     * Routes debug and info output to stderr instead of stdout. The CLI turns
+     * this on for `--format json`, where stdout carries the payload and any
+     * diagnostic line in it would make the output unparseable.
+     *
+     * @param enabled - True to send debug/info to stderr; false restores stdout
+     */
+    setDiagnosticsToStderr(enabled: boolean): void;
     /**
      * Determines whether a message with the given log level should be processed.
      * This method considers both the configured log level and the current debug mode.
@@ -222,6 +231,7 @@ export declare const logger: {
     table: (data: unknown) => void;
     shouldLog: (level: LogLevel) => boolean;
     setLogLevel: (level: LogLevel) => void;
+    setDiagnosticsToStderr: (enabled: boolean) => void;
     getLogs: (level?: LogLevel) => LogEntry[];
     clearLogs: () => void;
     setEventEmitter: (emitter: {

package/dist/utils/logger.js

@@ -36,11 +36,24 @@ const UPPERCASE_LOG_LEVELS = {
     warn: "WARN",
     error: "ERROR",
 };
+const FORMAT_FLAGS = ["--format", "-f", "--output-format"];
+/**
+ * True when the process was started with JSON output requested. Read from
+ * argv on every write, like the `--debug` check in `shouldLog`: modules log
+ * while they are still being imported, before the CLI middleware that calls
+ * `setDiagnosticsToStderr` has run.
+ */
+function argvRequestsJsonOutput() {
+    const argv = process.argv;
+    return argv.some((arg, index) => (FORMAT_FLAGS.includes(arg) && argv[index + 1] === "json") ||
+        FORMAT_FLAGS.some((flag) => arg === `${flag}=json`));
+}
 class NeuroLinkLogger {
     logLevel = "info";
     logs = [];
     maxLogs = 1000;
     isDebugMode;
+    diagnosticsToStderr = false;
     eventEmitter;
     constructor() {
         // Cache debug mode check to avoid repeated array searches
@@ -86,6 +99,16 @@ class NeuroLinkLogger {
     setLogLevel(level) {
         this.logLevel = level;
     }
+    /**
+     * Routes debug and info output to stderr instead of stdout. The CLI turns
+     * this on for `--format json`, where stdout carries the payload and any
+     * diagnostic line in it would make the output unparseable.
+     *
+     * @param enabled - True to send debug/info to stderr; false restores stdout
+     */
+    setDiagnosticsToStderr(enabled) {
+        this.diagnosticsToStderr = enabled;
+    }
     /**
      * Determines whether a message with the given log level should be processed.
      * This method considers both the configured log level and the current debug mode.
@@ -209,9 +232,10 @@ class NeuroLinkLogger {
      * @param data - Optional additional data to log.
      */
     outputToConsole(level, prefix, message, data) {
+        const toStderr = this.diagnosticsToStderr || argvRequestsJsonOutput();
         const logMethod = {
-            debug: console.debug,
-            info: console.info,
+            debug: toStderr ? console.error : console.debug,
+            info: toStderr ? console.error : console.info,
             warn: console.warn,
             error: console.error,
         }[level];
@@ -467,6 +491,7 @@ export const logger = {
     shouldLog: (level) => neuroLinkLogger.shouldLog(level),
     // Expose structured logging methods
     setLogLevel: (level) => neuroLinkLogger.setLogLevel(level),
+    setDiagnosticsToStderr: (enabled) => neuroLinkLogger.setDiagnosticsToStderr(enabled),
     getLogs: (level) => neuroLinkLogger.getLogs(level),
     clearLogs: () => neuroLinkLogger.clearLogs(),
     setEventEmitter: (emitter) => neuroLinkLogger.setEventEmitter(emitter),

package/dist/utils/pricing.js

@@ -78,8 +78,28 @@ const PRICING = {
     // Anthropic (direct API) — updated March 2026
     anthropic: {
         // Claude 5 family. Rates from platform.claude.com/docs/en/about-claude/pricing
-        // (checked 2026-08-21). Cache multipliers are the documented ones: a 5-minute
-        // cache write is 1.25x base input, a cache hit 0.1x.
+        // (checked 2026-09-23). A 5-minute cache write is 1.25x base input. The cache
+        // hit multiplier is 0.1x for most models but 0.05x on Opus 5.5 and 0.025x on
+        // Fable/Mythos 5.1, so those three are listed in full rather than left to the
+        // longest-prefix fallback — which would silently quote the 5.0 family's rates.
+        "claude-fable-5-1": {
+            input: 10.0 / 1_000_000,
+            output: 50.0 / 1_000_000,
+            cacheRead: 0.25 / 1_000_000,
+            cacheCreation: 12.5 / 1_000_000,
+        },
+        "claude-mythos-5-1": {
+            input: 10.0 / 1_000_000,
+            output: 50.0 / 1_000_000,
+            cacheRead: 0.25 / 1_000_000,
+            cacheCreation: 12.5 / 1_000_000,
+        },
+        "claude-opus-5-5": {
+            input: 4.0 / 1_000_000,
+            output: 20.0 / 1_000_000,
+            cacheRead: 0.2 / 1_000_000,
+            cacheCreation: 5.0 / 1_000_000,
+        },
         "claude-fable-5": {
             input: 10.0 / 1_000_000,
             output: 50.0 / 1_000_000,
@@ -226,6 +246,53 @@ const PRICING = {
     },
     // Google Vertex AI — Claude models on Vertex (same pricing, @ date suffix)
     vertex: {
+        // Claude 5 family. Absent here until now, so a Vertex leg serving any of
+        // them resolved to no rate at all and booked the turn at $0 — on the one
+        // provider in the chain that bills in real currency.
+        // `isVertexAnthropicModel` admits every `claude-*` id, so the whole
+        // family needs an entry, not only the ones the chain names today.
+        "claude-fable-5-1": {
+            input: 10.0 / 1_000_000,
+            output: 50.0 / 1_000_000,
+            cacheRead: 0.25 / 1_000_000,
+            cacheCreation: 12.5 / 1_000_000,
+        },
+        "claude-mythos-5-1": {
+            input: 10.0 / 1_000_000,
+            output: 50.0 / 1_000_000,
+            cacheRead: 0.25 / 1_000_000,
+            cacheCreation: 12.5 / 1_000_000,
+        },
+        "claude-fable-5": {
+            input: 10.0 / 1_000_000,
+            output: 50.0 / 1_000_000,
+            cacheRead: 1.0 / 1_000_000,
+            cacheCreation: 12.5 / 1_000_000,
+        },
+        "claude-mythos-5": {
+            input: 10.0 / 1_000_000,
+            output: 50.0 / 1_000_000,
+            cacheRead: 1.0 / 1_000_000,
+            cacheCreation: 12.5 / 1_000_000,
+        },
+        "claude-opus-5-5": {
+            input: 4.0 / 1_000_000,
+            output: 20.0 / 1_000_000,
+            cacheRead: 0.2 / 1_000_000,
+            cacheCreation: 5.0 / 1_000_000,
+        },
+        "claude-opus-5": {
+            input: 5.0 / 1_000_000,
+            output: 25.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+            cacheCreation: 6.25 / 1_000_000,
+        },
+        "claude-sonnet-5": {
+            input: 2.0 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.2 / 1_000_000,
+            cacheCreation: 2.5 / 1_000_000,
+        },
         "claude-sonnet-4-6": {
             input: 3.0 / 1_000_000,
             output: 15.0 / 1_000_000,