@juspay/neurolink 12.20.2 → 12.21.1

package/dist/proxy/vertexAnthropicFallback.js

@@ -13,6 +13,8 @@
  * here because nothing reshapes them.
  */
 import { GoogleAuth } from "google-auth-library";
+import { logger } from "../utils/logger.js";
+import { isTransientNetworkError } from "./proxyFetch.js";
 /** Vertex pins the Anthropic API version in the body, not a header. */
 const VERTEX_ANTHROPIC_VERSION = "vertex-2023-10-16";
 const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
@@ -68,7 +70,114 @@ export function mapVertexOutputConfig(value) {
     const { effort: _unsupported, ...rest } = value;
     return Object.keys(rest).length > 0 ? rest : undefined;
 }
-/** Strip what Vertex rejects and pin the API version it requires. */
+/**
+ * Vertex's message schema is exactly `{ role, content }`. Claude Code 2.1.x
+ * also puts `output_config` on its system "directive" turn, which the
+ * first-party API accepts and Vertex refuses: "messages.1.output_config:
+ * Extra inputs are not permitted".
+ */
+const VERTEX_MESSAGE_KEYS = new Set(["role", "content"]);
+/**
+ * Claude Code stamps its version into a system block as
+ * `x-anthropic-billing-header: cc_version=…`. That is first-party billing
+ * plumbing; on Vertex it only triggers a client-version check against the
+ * fallback model, which the client never asked for ("Claude Code 2.1.278 does
+ * not support this model"). It also sits first in `system` and varies with the
+ * client build, entrypoint and subagent flag, so identical conversations from
+ * different builds could never share a Vertex prompt cache while it stayed.
+ *
+ * Matched as a prefix, not anywhere in the text: the generator
+ * (`buildStableClaudeCodeBillingHeader`) always emits it first, and a looser
+ * match would delete a caller's own block that merely mentions the header.
+ */
+const BILLING_HEADER_MARKER = "x-anthropic-billing-header";
+/**
+ * How each mid-conversation tool change reads once it is plain text: the prefix
+ * when the tool is named, and a sentence for a reference with no usable name.
+ */
+const TOOL_CHANGE_TEXT = {
+    tool_addition: {
+        named: "Tool now available: ",
+        unnamed: "A tool became available.",
+    },
+    tool_removal: {
+        named: "Tool no longer available: ",
+        unnamed: "A tool was withdrawn.",
+    },
+};
+/**
+ * A change references a tool rather than defining one: `tool_reference` and
+ * `mcp_tool_reference` carry a `name`, and an MCP toolset reference carries
+ * only its `server_name`.
+ */
+function toolChangeText(type, tool) {
+    const wording = TOOL_CHANGE_TEXT[type];
+    const label = !record(tool)
+        ? ""
+        : typeof tool.name === "string" && tool.name.trim()
+            ? tool.name.trim()
+            : typeof tool.server_name === "string"
+                ? tool.server_name.trim()
+                : "";
+    return label ? `${wording.named}${label}` : wording.unnamed;
+}
+/**
+ * Vertex rejects the `tool_addition` and `tool_removal` tags that offer or
+ * withdraw a tool mid-conversation. Each one becomes a text block in the same
+ * position, so the notice survives and the array never empties. Only the
+ * message's own content array is touched: nested `tool_result` content stays
+ * exactly as sent.
+ */
+function rewriteToolChanges(content) {
+    if (!Array.isArray(content)) {
+        return content;
+    }
+    let changed = false;
+    const mapped = content.map((block) => {
+        if (!record(block) ||
+            typeof block.type !== "string" ||
+            !Object.hasOwn(TOOL_CHANGE_TEXT, block.type)) {
+            return block;
+        }
+        changed = true;
+        return {
+            type: "text",
+            text: toolChangeText(block.type, block.tool),
+            ...(block.cache_control !== undefined
+                ? { cache_control: block.cache_control }
+                : {}),
+        };
+    });
+    return changed ? mapped : content;
+}
+function isEmptyContent(content) {
+    return (content === undefined ||
+        content === "" ||
+        (Array.isArray(content) && content.length === 0));
+}
+/**
+ * Move a `cache_control` set on the message itself onto its last content
+ * block, which caches the same prefix, since Vertex accepts only `role` and
+ * `content` on a message. String content becomes one text block to carry it.
+ * A breakpoint with no block to land on, or whose block already has one, is
+ * reported rather than dropped silently.
+ */
+function carryMessageBreakpoint(content, marker) {
+    if (marker === undefined) {
+        return content;
+    }
+    if (typeof content === "string" && content !== "") {
+        return [{ type: "text", text: content, cache_control: marker }];
+    }
+    const last = Array.isArray(content) ? content.at(-1) : undefined;
+    if (Array.isArray(content) &&
+        record(last) &&
+        last.cache_control === undefined) {
+        return [...content.slice(0, -1), { ...last, cache_control: marker }];
+    }
+    warnDroppedBreakpoint("a message-level cache_control");
+    return content;
+}
 /**
  * Vertex refuses `role: "system"` messages outright — "role 'system' is not
  * supported on this model" — where the first-party Messages API accepts them
@@ -82,25 +191,156 @@ export function mapVertexOutputConfig(value) {
  * instead, which keeps both the text and the position. Consecutive same-role
  * turns are accepted, so this never produces an invalid sequence.
  */
-function normalizeVertexRoles(messages) {
+function normalizeVertexMessage(message) {
+    if (!record(message)) {
+        return message;
+    }
+    const role = message.role === "system" ? "user" : message.role;
+    const content = carryMessageBreakpoint(rewriteToolChanges(message.content), message.cache_control);
+    const onlyKnownKeys = Object.keys(message).every((key) => VERTEX_MESSAGE_KEYS.has(key));
+    if (onlyKnownKeys && role === message.role && content === message.content) {
+        return message;
+    }
+    return { role, ...("content" in message ? { content } : {}) };
+}
+/** Index of the last `role: "user"` message, or -1 when there is none. */
+function lastUserIndex(messages) {
+    return messages.findLastIndex((message) => record(message) && message.role === "user");
+}
+/**
+ * A turn-scoped system message (`clear_at: "next_user_message"`) renders only
+ * while no user message comes after it — one carrying only `tool_result`
+ * counts — and renders nothing once one does. Sent to Vertex as a user turn it
+ * would keep speaking after it should have gone quiet.
+ */
+function isClearedTurnScopedMessage(message, index, lastUser) {
+    return (record(message) &&
+        message.role === "system" &&
+        message.clear_at === "next_user_message" &&
+        index < lastUser);
+}
+/**
+ * A system turn left with no content carries nothing once its extra keys are
+ * gone — the directive-only form is `content: []` plus `output_config`, whose
+ * effort is resolved at the top level — so it is dropped rather than sent as
+ * an empty user turn. So is a turn-scoped message that has already cleared.
+ */
+function normalizeVertexMessages(messages) {
     if (!Array.isArray(messages)) {
         return messages;
     }
+    const lastUser = lastUserIndex(messages);
     let changed = false;
-    const mapped = messages.map((message) => {
-        if (!record(message) || message.role !== "system") {
-            return message;
+    const normalized = messages.flatMap((message, index) => {
+        if (isClearedTurnScopedMessage(message, index, lastUser)) {
+            changed = true;
+            return [];
         }
-        changed = true;
-        return { ...message, role: "user" };
+        const next = normalizeVertexMessage(message);
+        if (next !== message) {
+            changed = true;
+        }
+        if (record(message) &&
+            message.role === "system" &&
+            record(next) &&
+            isEmptyContent(next.content)) {
+            return [];
+        }
+        return [next];
     });
-    return changed ? mapped : messages;
+    return changed ? normalized : messages;
+}
+/**
+ * The effort in force for the turn being answered. A per-message directive
+ * "takes effect from the next user turn and holds until a later message changes
+ * it", so the governing one is the last directive before the final user
+ * message; one after it belongs to a turn not yet taken. It overrides only the
+ * settings it names. Vertex has no per-message effort, so this becomes the
+ * request's top-level `output_config`.
+ */
+function resolveOutputConfig(topLevel, messages) {
+    if (!Array.isArray(messages)) {
+        return topLevel;
+    }
+    const lastUser = lastUserIndex(messages);
+    const directive = messages
+        .slice(0, Math.max(lastUser, 0))
+        .findLast((message) => record(message) &&
+        message.role === "system" &&
+        record(message.output_config));
+    if (!record(directive) || !record(directive.output_config)) {
+        return topLevel;
+    }
+    return {
+        ...(record(topLevel) ? topLevel : {}),
+        ...directive.output_config,
+    };
+}
+function isBillingBlock(block) {
+    return (record(block) &&
+        typeof block.text === "string" &&
+        block.text.trimStart().startsWith(BILLING_HEADER_MARKER));
+}
+function warnDroppedBreakpoint(source) {
+    logger.warn(`[proxy] Vertex fallback could not keep the cache_control breakpoint on ${source}`);
+}
+/**
+ * Remove the billing block without losing a cache breakpoint it carried: the
+ * marker moves onto the block that takes its place. When there is no such
+ * block, or that block already has its own marker, the loss is reported rather
+ * than passed over, because this path bills in real currency.
+ */
+function stripBillingBlock(system) {
+    if (!Array.isArray(system) || !system.some(isBillingBlock)) {
+        return system;
+    }
+    const kept = [];
+    let carried;
+    for (const block of system) {
+        if (isBillingBlock(block)) {
+            if (record(block) && block.cache_control !== undefined) {
+                if (carried !== undefined) {
+                    warnDroppedBreakpoint("the Claude Code billing block");
+                }
+                carried = block.cache_control;
+            }
+            continue;
+        }
+        if (carried !== undefined && record(block)) {
+            if (block.cache_control === undefined) {
+                kept.push({ ...block, cache_control: carried });
+            }
+            else {
+                warnDroppedBreakpoint("the Claude Code billing block");
+                kept.push(block);
+            }
+            carried = undefined;
+            continue;
+        }
+        kept.push(block);
+    }
+    if (carried !== undefined) {
+        warnDroppedBreakpoint("the Claude Code billing block");
+    }
+    return kept.length > 0 ? kept : undefined;
 }
+/**
+ * Strip what Vertex rejects and pin the API version it requires.
+ *
+ * Prompt caching constrains every rewrite here. Anthropic caches only up to an
+ * explicit `cache_control` marker, at most four per request, over a prefix
+ * rendered `tools → system → messages`; anything removed or inserted before a
+ * marker invalidates it and everything after. So: never drop a marker, never
+ * reorder `system`, and keep each rewrite deterministic so consecutive turns
+ * share a prefix. Vertex holds its own cache, apart from the first-party one,
+ * so nothing here can disturb first-party hits.
+ */
 export function buildVertexAnthropicPayload(body) {
     const dropped = new Set(UNSUPPORTED_FIELDS);
     const payload = Object.fromEntries(Object.entries(body).filter(([key]) => !dropped.has(key)));
-    if ("output_config" in payload) {
-        const mapped = mapVertexOutputConfig(payload.output_config);
+    const outputConfig = resolveOutputConfig(payload.output_config, payload.messages);
+    if (outputConfig !== undefined) {
+        const mapped = mapVertexOutputConfig(outputConfig);
         if (mapped === undefined) {
             delete payload.output_config;
         }
@@ -109,7 +349,16 @@ export function buildVertexAnthropicPayload(body) {
         }
     }
     if ("messages" in payload) {
-        payload.messages = normalizeVertexRoles(payload.messages);
+        payload.messages = normalizeVertexMessages(payload.messages);
+    }
+    if ("system" in payload) {
+        const system = stripBillingBlock(payload.system);
+        if (system === undefined) {
+            delete payload.system;
+        }
+        else {
+            payload.system = system;
+        }
     }
     return { ...payload, anthropic_version: VERTEX_ANTHROPIC_VERSION };
 }
@@ -159,12 +408,56 @@ async function vertexAccessToken() {
 export function setVertexAccessTokenProviderForTests(provider) {
     accessTokenProviderForTests = provider;
 }
+const DNS_FAILURE_CODES = new Set([
+    "ENOTFOUND",
+    "EAI_AGAIN",
+]);
+const DNS_FAILURE_MESSAGE = /\bgetaddrinfo (ENOTFOUND|EAI_AGAIN)\b/;
+const TOKEN_RETRY_DELAY_MS = 250;
+/**
+ * A resolver failure while reaching Google's token endpoint. The shared proxy
+ * classifier leaves DNS codes out, since elsewhere one can mean a mistyped
+ * host, but this endpoint is fixed and its failures on 2026-09-23 were blips
+ * reported only in the message text ("getaddrinfo ENOTFOUND
+ * oauth2.googleapis.com").
+ */
+function isDnsFailure(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && record(current); depth++) {
+        if ((typeof current.code === "string" &&
+            DNS_FAILURE_CODES.has(current.code)) ||
+            (typeof current.message === "string" &&
+                DNS_FAILURE_MESSAGE.test(current.message))) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * Run once more after a short pause when the first attempt hit a transient
+ * network failure: anything the shared proxy classifier retries, plus a DNS
+ * blip. One retry absorbs a blip without hiding a real outage: a second
+ * failure, or any other error, surfaces unchanged.
+ */
+export async function withTransientNetworkRetry(run, delayMs = TOKEN_RETRY_DELAY_MS) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (!isTransientNetworkError(error) && !isDnsFailure(error)) {
+            throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        return run();
+    }
+}
 /**
  * Send one Anthropic-shaped request to Vertex and return the upstream response
  * untouched, so the caller can stream its bytes straight to the client.
  */
 export async function dispatchVertexAnthropicPassthrough(request) {
-    const token = await vertexAccessToken();
+    const token = await withTransientNetworkRetry(() => vertexAccessToken());
     if (!token) {
         throw new Error("Vertex passthrough could not obtain a Google access token; " +
             "check Application Default Credentials for this project");

package/dist/routing/classifierStrategies.js

@@ -295,6 +295,9 @@ export async function classifyJev(input, decide, timeoutMs, candidates, threshol
     // are already assembled by the caller. Sending them costs almost nothing
     // and they are exactly what distinguishes a long tool-using request from a
     // short conversational one.
+    // Continuity is sent as `session_bound` / `prior_messages`, never as the
+    // raw sessionId: the id is an opaque identifier that tells a third-party
+    // model nothing, so it stays in-process.
     const result = await decide({
         state: {
             request: (input.prompt ?? "").slice(0, 8000),
@@ -302,6 +305,10 @@ export async function classifyJev(input, decide, timeoutMs, candidates, threshol
             has_tools_available: input.hasTools ?? false,
             request_includes_images: input.requiresVision ?? false,
             caller_requested_thinking: input.thinkingLevel ?? "none",
+            session_bound: input.sessionBound ?? false,
+            ...(typeof input.priorMessageCount === "number"
+                ? { prior_messages: input.priorMessageCount }
+                : {}),
         },
         questions,
         timeoutMs,

package/dist/server/routes/codexProxyRoutes.js

@@ -143,6 +143,34 @@ function buildCodexErrorResponse(status, message, code) {
         },
     }), { status, headers: { "content-type": "application/json" } });
 }
+/**
+ * Build a terminal Codex Responses SSE stream for a quota-exhaustion failure
+ * that never reached an upstream request (every pooled account is cooling).
+ * A bare non-2xx status with no body reads to the Codex CLI as a dropped
+ * connection, so it shows "Reconnecting... waiting for network" forever
+ * instead of a real error. Emitting a well-formed `response.failed` event —
+ * the same terminal shape the CLI already parses out of a live stream —
+ * lets it render the actual failure instead.
+ */
+function buildCodexQuotaExhaustedResponse(message, retryAfterSec) {
+    const payload = {
+        type: "response.failed",
+        response: {
+            error: {
+                type: "insufficient_quota",
+                code: "insufficient_quota",
+                message,
+            },
+        },
+    };
+    const headers = {
+        "content-type": "text/event-stream",
+    };
+    if (retryAfterSec !== undefined) {
+        headers["retry-after"] = String(retryAfterSec);
+    }
+    return new Response(`event: response.failed\ndata: ${JSON.stringify(payload)}\n\n`, { status: 200, headers });
+}
 /**
  * Load the Codex account pool from the token store, refreshing expired OAuth
  * tokens and hydrating cooldown + quota state from disk.
@@ -654,18 +682,10 @@ async function executeCodexResponsesRequest(ctx) {
                 errorType: "all_accounts_cooling",
                 errorMessage: "All Codex accounts are rate-limited",
             });
-            return new Response(JSON.stringify({
-                error: {
-                    type: "rate_limit_error",
-                    message: "All Codex accounts are currently rate-limited",
-                },
-            }), {
-                status: 429,
-                headers: {
-                    "content-type": "application/json",
-                    "retry-after": String(retryAfterSec),
-                },
-            });
+            const resetAt = soonest ? new Date(soonest).toISOString() : undefined;
+            return buildCodexQuotaExhaustedResponse(resetAt
+                ? `Codex quota exhausted: all accounts are rate-limited. Resets at ${resetAt}.`
+                : "Codex quota exhausted: all accounts are rate-limited.", retryAfterSec);
         }
         let attempt = 0;
         let lastErrorMessage = "All Codex accounts failed";

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/codex.d.ts

@@ -119,6 +119,9 @@ export type CodexProxyStatusAccountIdentity = {
 } | {
     provider: "codex";
     key: string;
+} | {
+    provider: "vertex";
+    key: string;
 } | {
     provider: "other";
     key: null;

package/dist/types/proxy.d.ts

@@ -3221,7 +3221,7 @@ export type StatusStats = {
     accounts?: {
         /** Provider-qualified key; null for explicitly unattributed legacy rows. */
         key?: string | null;
-        provider?: "anthropic" | "codex" | "other" | "unknown";
+        provider?: "anthropic" | "codex" | "vertex" | "other" | "unknown";
         label: string;
         type: string;
         attempts?: number;

package/dist/types/proxyClient.d.ts

@@ -187,8 +187,11 @@ export type CliAccountsRow = {
     /**
      * Which pool engine owns this login. Absent on plumbing rows. Consumers
      * that key a list by row must key by `key`, not `label` — see above.
+     *
+     * `"vertex"` is not a login: native fallback legs are keyed by served
+     * model, with no OAuth account behind them, so they carry no token state.
      */
-    provider?: "anthropic" | "codex";
+    provider?: "anthropic" | "codex" | "vertex";
     /**
      * What this row actually is. Only "account" rows are real logins; the proxy
      * also tracks internal and translation pseudo-accounts, which have no quota

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),