@juspay/neurolink 12.40.3 → 12.41.0

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

@@ -16,6 +16,14 @@ export { createToolRoutes } from "./toolRoutes.js";
 /**
  * Create all standard routes
  * Convenience method that combines all route groups
+ *
+ * NOTE on the Codex outbound fallback's `anthropic` target: this function
+ * does not thread `loopbackPort`/`internalDispatch` into
+ * `createCodexProxyRoutes`, so that target cannot dispatch when the feature
+ * is enabled through `options.runtimeConfigProvider` here — only the CLI
+ * proxy command wires the in-process loopback directly. Route creation logs
+ * one warning when this gap applies; see `CreateRoutesOptions.runtimeConfigProvider`
+ * and docs/features/codex-proxy-support.md.
  */
 export declare function createAllRoutes(basePath?: string, options?: CreateRoutesOptions): RouteGroup[];
 /**

package/dist/server/routes/index.js

@@ -28,6 +28,14 @@ export { createToolRoutes } from "./toolRoutes.js";
 /**
  * Create all standard routes
  * Convenience method that combines all route groups
+ *
+ * NOTE on the Codex outbound fallback's `anthropic` target: this function
+ * does not thread `loopbackPort`/`internalDispatch` into
+ * `createCodexProxyRoutes`, so that target cannot dispatch when the feature
+ * is enabled through `options.runtimeConfigProvider` here — only the CLI
+ * proxy command wires the in-process loopback directly. Route creation logs
+ * one warning when this gap applies; see `CreateRoutesOptions.runtimeConfigProvider`
+ * and docs/features/codex-proxy-support.md.
  */
 export function createAllRoutes(basePath = "/api", options) {
     const routes = [
@@ -56,7 +64,7 @@ export function createAllRoutes(basePath = "/api", options) {
         routes.push(createOpenAIProxyRoutes(undefined, basePath));
     }
     if (enableCodexProxy) {
-        routes.push(createCodexProxyRoutes(basePath));
+        routes.push(createCodexProxyRoutes(basePath, options?.runtimeConfigProvider));
     }
     if (enableGeminiProxy) {
         routes.push(createGeminiProxyRoutes(undefined, basePath));

package/dist/types/analytics.d.ts

@@ -12,10 +12,35 @@ export type TokenUsage = {
     output: number;
     total: number;
     cacheCreationTokens?: number;
+    /**
+     * The 1-hour-TTL share of `cacheCreationTokens` (a subset, not additive —
+     * Anthropic's `cache_creation.ephemeral_1h_input_tokens` is reported inside
+     * the same `cache_creation_input_tokens` total). Undefined/0 keeps today's
+     * pricing exactly, since `calculateCost` treats every write as 5-minute-TTL
+     * unless told otherwise.
+     */
+    cacheCreation1hTokens?: number;
     cacheReadTokens?: number;
     reasoning?: number;
     cacheSavingsPercent?: number;
 };
+/** Per-token dollar rates for one model in the pricing table. */
+export type ModelPricingRates = {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheCreation?: number;
+    /**
+     * 1-hour TTL cache-write rate (Anthropic's 2x-of-input multiplier),
+     * separate from `cacheCreation`'s 5-minute (1.25x) rate so a 1h-TTL
+     * write is never silently priced at the 5m rate. `calculateCost()`
+     * applies it to `TokenUsage.cacheCreation1hTokens`, the 1h share of the
+     * cache-write total that the Claude route, the Vertex passthrough and
+     * the Codex outbound fallback capture. Set on every Claude model; a
+     * model without it prices that share at `cacheCreation`.
+     */
+    cacheCreation1h?: number;
+};
 /**
  * Error info type for analytics
  */

package/dist/types/codex.d.ts

@@ -362,10 +362,13 @@ export type CodexResponseUsage = {
     input_tokens: number;
     output_tokens: number;
     total_tokens: number;
-    /** Omitted entirely when neither cache field was observed on the Anthropic side. */
+    /** Omitted entirely when no cache field was observed on the Anthropic side. */
     input_tokens_details?: {
         cached_tokens?: number;
         cache_write_tokens?: number;
+        /** The 1-hour-TTL share of `cache_write_tokens` (a subset, not additive);
+         *  sourced from `ClaudeUsage.cacheCreation1hTokens`. Omitted when not observed. */
+        cache_write_1h_tokens?: number;
     };
     /** Always omitted — ClaudeUsage carries no reasoning-token count to source it from. */
     output_tokens_details?: {
@@ -442,3 +445,44 @@ export type CodexResponseStream = {
 };
 /** Which output item kind (if any) `CodexResponsesStreamSerializer` currently has open. */
 export type CodexResponseOpenItemKind = "message" | "function_call" | "custom_tool_call" | null;
+/** The four call sites in `codexProxyRoutes.ts`'s `dispatch()` that can trigger
+ *  an outbound fallback attempt (stage-c-trigger.md §0's corrected line map). */
+export type CodexOutboundFailureClass = "no_accounts" | "pool_exhausted" | "non_retryable_transport" | "loop_fallthrough";
+/** What a single insertion point in `codexProxyRoutes.ts` observed. */
+export type CodexOutboundFailureInput = {
+    failureClass: CodexOutboundFailureClass;
+    /** Present only for `non_retryable_transport`: the transport error code
+     *  (e.g. `ECONNREFUSED`) that was NOT in the retryable allow-list. */
+    transportErrorCode?: string;
+    /** Present only for `loop_fallthrough`: the raw HTTP status the last
+     *  exhausted account attempt ended on (`lastErrorStatus` at the account-loop
+     *  call site). A 401/403 there is a Codex credential failure and stays
+     *  eligible; any other 4xx except 429 rejects the request itself. */
+    lastStatus?: number;
+    /** Present only for `loop_fallthrough`: the error code the last exhausted
+     *  account attempt reported, when it reported one. A code
+     *  `classifyProxyFailureCode` marks non-retryable (content policy, invalid
+     *  request) makes the failure ineligible whatever the status. */
+    lastErrorCode?: string;
+};
+/** `classifyCodexOutboundFailure`'s verdict: whether this failure is eligible
+ *  to attempt an outbound fallback, and why (for tracing/logging only — the
+ *  caller still applies its own config/loop-prevention/depth gates). */
+export type CodexOutboundFallbackDecision = {
+    eligible: boolean;
+    reason: string;
+};
+/** Outcome of one `attemptCodexOutboundFallback` call. `not_attempted` covers
+ *  every gate failure and every target exhausting without success — the
+ *  caller falls through to its own existing (unchanged) error response in
+ *  every one of those cases, so the flag-off / all-targets-failed paths stay
+ *  byte-identical to today. */
+export type CodexOutboundFallbackOutcome = {
+    kind: "not_attempted";
+} | {
+    kind: "request_too_large";
+    message: string;
+} | {
+    kind: "success";
+    response: Response;
+};

package/dist/types/proxy.d.ts

@@ -26,7 +26,7 @@ import type { Ora } from "ora";
 import type { MCPToolRegistry } from "../mcp/toolRegistry.js";
 import type { ProxyTracer } from "../proxy/proxyTracer.js";
 import type { ACCOUNT_COOLING_REASONS, PROXY_ACCOUNT_TYPES, PROXY_ACCOUNT_ROUTING_MODES, PROXY_ACCOUNT_ROUTING_REASONS, PROXY_ACCOUNT_ROUTING_STRATEGIES } from "../proxy/routingEvidence.js";
-import type { FallbackEntry, ModelMapping, ProxyRoutingConfig, CloakingConfig } from "./subscription.js";
+import type { CodexFallbackTarget, FallbackEntry, ModelMapping, ProxyRoutingConfig, CloakingConfig } from "./subscription.js";
 import type { RouteDeprecation } from "./server.js";
 import type { StoredOAuthTokens } from "./auth.js";
 /**
@@ -58,6 +58,14 @@ export type ClaudeCacheControl = {
      */
     ttl?: "5m" | "1h";
 };
+/** TTL override for applyClaudeRequestCacheBreakpoints's breakpoint 1 only. */
+export type ClaudeCacheBreakpointOptions = {
+    ttl?: "5m" | "1h";
+};
+/** Where a Claude-shaped request originated, for cache/cost attribution. */
+export type ProxyRequestOrigin = "native" | "codex-fallback";
+/** Session-affinity routing key for Codex-origin fallback requests. */
+export type CodexAnthropicAffinityKey = `codex-thread:${string}` | `codex-session:${string}` | `codex-prefix:${string}`;
 /** A single text block in a Claude content array. */
 export type ClaudeTextBlock = {
     type: "text";
@@ -147,6 +155,12 @@ export type ClaudeUsage = {
     output_tokens: number;
     cache_creation_input_tokens?: number;
     cache_read_input_tokens?: number;
+    /** The 1-hour-TTL share of `cache_creation_input_tokens` (a subset, not
+     *  additive), read from Anthropic's `usage.cache_creation.ephemeral_1h_input_tokens`.
+     *  Omitted means "none known to be 1h", matching `UsageContext.cacheCreation1hTokens`'s
+     *  own contract — every path that does not observe the breakdown prices exactly
+     *  as before. */
+    cacheCreation1hTokens?: number;
 };
 /** Non-streaming response matching the Claude Messages API. */
 export type ClaudeResponse = {
@@ -679,6 +693,8 @@ export type RequestLogEntry = {
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
+    /** 1h-TTL share of `cacheCreationTokens` (subset); unset when not reported. */
+    cacheCreation1hTokens?: number;
     cacheReadTokens?: number;
     /**
      * Whether the provider reported each cache count. Omitted means observed,
@@ -1010,7 +1026,11 @@ export type RequestAttemptLogEntry = {
     traceFlags?: number;
 };
 /** Additional fields recorded when a Codex response becomes client-final. */
-export type CodexFinalLogExtra = Partial<Pick<RequestLogEntry, "errorType" | "errorMessage" | "errorCode" | "transportScope" | "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "reasoningTokens" | "terminalOutcome" | "firstUsefulOutputMs" | "firstUsefulOutputStatus" | "firstUsefulOutputEvent" | "retryable">>;
+export type CodexFinalLogExtra = Partial<Pick<RequestLogEntry, "errorType" | "errorMessage" | "errorCode" | "transportScope" | "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "cacheCreation1hTokens" | "cacheReadTokensObserved" | "cacheCreationTokensObserved" | "reasoningTokens" | "terminalOutcome" | "firstUsefulOutputMs" | "firstUsefulOutputStatus" | "firstUsefulOutputEvent" | "retryable" | "accountingScope" | "usageOwnerRequestId" | "model" | "provider" | "account" | "accountKey" | "accountType">>;
+/** Who served a Codex turn the outbound fallback handed to a Claude target.
+ *  The outer Codex entry records it, as the OpenAI bridge's does, so the
+ *  final log names the served engine instead of the Codex pool. */
+export type CodexOutboundServedAttribution = Required<Pick<RequestLogEntry, "account" | "accountType" | "provider" | "model">> & Pick<RequestLogEntry, "accountKey">;
 /** Additional fields recorded for each upstream Codex account attempt. */
 export type CodexAttemptLogExtra = Partial<Pick<RequestAttemptLogEntry, "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "reasoningTokens" | "inputIncludesCachedTokens" | "errorType" | "errorMessage" | "errorCode" | "transportScope" | "retryable" | "rateLimitKind" | "cooldownReason" | "quotaResetAt" | "quotaScope">>;
 /** Minimal persistence contract needed by Codex rotating-token refreshes. */
@@ -1044,6 +1064,8 @@ export type ClaudeFinalRequestLogger = (status: number, accountLabel: string, ac
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
+    /** 1h-TTL share of `cacheCreationTokens` (subset); unset when not reported. */
+    cacheCreation1hTokens?: number;
     cacheReadTokens?: number;
     /** False when the provider reported no cache breakdown; see RequestLogEntry. */
     cacheReadTokensObserved?: boolean;
@@ -1075,6 +1097,8 @@ export type AnthropicAttemptLogger = (status: number, errorType?: string, errorM
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
+    /** 1h-TTL share of `cacheCreationTokens` (subset); unset when not reported. */
+    cacheCreation1hTokens?: number;
     cacheReadTokens?: number;
     retryable?: boolean;
     /** The transport failure happened before any request byte was sent. */
@@ -1930,6 +1954,12 @@ export type UsageContext = {
     inputTokens: number;
     outputTokens: number;
     cacheCreationTokens: number;
+    /**
+     * The 1-hour-TTL share of `cacheCreationTokens` (a subset, not additive).
+     * Omitted means "none known to be 1h", so every path that does not read the
+     * upstream `cache_creation` breakdown prices exactly as it did before.
+     */
+    cacheCreation1hTokens?: number;
     cacheReadTokens: number;
     /**
      * Whether the provider actually reported each cache count. Omitted means
@@ -2341,6 +2371,8 @@ export type ProxyAnalysisFinalRequestRecord = {
     outputTokens: number | null;
     cacheReadTokens: number | null;
     cacheCreationTokens: number | null;
+    /** 1h-TTL share of `cacheCreationTokens` (subset); null when not reported. */
+    cacheCreation1hTokens: number | null;
     /**
      * False when the provider reported no cache breakdown. Such a turn is not a
      * cache miss, so it is excluded from the hit-rate denominator rather than
@@ -2667,6 +2699,8 @@ export type SSETelemetry = {
         inputTokens: number;
         outputTokens: number;
         cacheCreationInputTokens: number;
+        /** 1h-TTL share of `cacheCreationInputTokens`; absent when not reported. */
+        cacheCreation1hInputTokens?: number;
         cacheReadInputTokens: number;
         totalTokens: number;
     };
@@ -2713,6 +2747,7 @@ export type TelemetryAccumulator = {
     inputTokens: number;
     outputTokens: number;
     cacheCreationInputTokens: number;
+    cacheCreation1hInputTokens?: number;
     cacheReadInputTokens: number;
     contentBlocks: SSEContentBlock[];
     blockByteCounts: Map<number, number>;
@@ -3239,6 +3274,9 @@ export type ProxyRequestRoutingSnapshot = {
     sessionAffinity: boolean;
     sessionAffinityIdleTtlMs: number;
     spillInflight: number;
+    codexOutboundFallbackEnabled: boolean;
+    codexOutboundFallbackTargets: CodexFallbackTarget[];
+    codexOutboundFallbackModelMappings: ModelMapping[];
 };
 /** Operator policy for paid extra usage. */
 export type ProxyOveragePolicy = "auto" | "always" | "never";

package/dist/types/proxyClient.d.ts

@@ -271,6 +271,8 @@ export type ProxyLedgerEntry = {
     outputTokens: number;
     cacheReadTokens: number;
     cacheCreationTokens: number;
+    /** 1h-TTL share of `cacheCreationTokens` (subset); 0 when not reported. */
+    cacheCreation1hTokens: number;
 };
 /** Incremental read position and accumulated entries for one request-log file. */
 export type ProxyLedgerFileCursor = {

package/dist/types/server.d.ts

@@ -7,6 +7,7 @@ import type { MCPToolRegistry } from "../mcp/toolRegistry.js";
 import type { NeuroLink } from "../neurolink.js";
 import type { JsonObject, JsonValue } from "./common.js";
 import type { ExternalMCPServerStatus } from "./externalMcp.js";
+import type { ProxyRuntimeConfigProvider } from "./proxy.js";
 /**
  * Server adapter configuration
  */
@@ -1080,6 +1081,20 @@ export type CreateRoutesOptions = {
     codexProxy?: boolean;
     /** Enable the Gemini door on its own, for the same reason. */
     geminiProxy?: boolean;
+    /**
+     * Runtime config provider for engines that read it (currently: Codex
+     * outbound fallback). NOTE: this option alone cannot make the Codex
+     * outbound fallback's `anthropic` target reachable — that leg dispatches
+     * through an in-process loopback (`loopbackPort` / `internalDispatch`)
+     * that only `createCodexProxyRoutes`' direct, non-`CreateRoutesOptions`
+     * parameters carry (the CLI's `neurolink proxy start` wires them; this
+     * generic SDK route surface deliberately does not gain a new option for
+     * it). Enabling the feature with an `anthropic` target here logs one
+     * startup warning and then fails every such request at attempt time. A
+     * `vertex`-only configuration is unaffected. See
+     * docs/features/codex-proxy-support.md.
+     */
+    runtimeConfigProvider?: ProxyRuntimeConfigProvider;
 };
 /** Data stream finish event. */
 export type FinishEvent = DataStreamEvent & {

package/dist/types/subscription.d.ts

@@ -984,6 +984,14 @@ export type FallbackEntry = {
     /** Explicit Codex fallback effort. Omit to use the upstream default. */
     reasoningEffort?: CodexReasoningEffort;
 };
+/** One outbound-fallback hop for a native Codex request whose own account pool
+ *  is exhausted. No `reasoningEffort` (unlike FallbackEntry): that knob configures
+ *  a Codex *inbound* leg and has no meaning once the request has left Codex's
+ *  Responses format and become an Anthropic Messages request. */
+export type CodexFallbackTarget = {
+    provider: "anthropic" | "vertex";
+    model: string;
+};
 /** Full proxy routing config */
 export type ProxyRoutingConfig = {
     strategy: "round-robin" | "fill-first";
@@ -1040,6 +1048,20 @@ export type ProxyRoutingConfig = {
     sessionAffinityIdleTtlMs?: number;
     /** For a request without a binding: spill off an account already at N in-flight. 0-100, 0 = off. */
     spillInflight?: number;
+    /** Master flag for native-Codex-request outbound fallback. Independent of
+     *  codexOutboundFallbackTargets so the list can be staged ahead of turning the
+     *  feature on. Default false — the only new key whose absence must reproduce
+     *  byte-identical current behavior. */
+    codexOutboundFallbackEnabled?: boolean;
+    /** Ordered targets tried after Codex's own account pool is exhausted.
+     *  Try-order = array order. Empty/absent with enabled:true is a no-op. */
+    codexOutboundFallbackTargets?: CodexFallbackTarget[];
+    /** Per-incoming-Codex-model override, layered on codexOutboundFallbackTargets.
+     *  Reuses ModelMapping's {from,to,provider}: from = requested Codex model,
+     *  provider = which target this overrides, to = model to send instead of that
+     *  target's plain `model`. Absent for a (from,provider) pair = use the target's
+     *  plain model. */
+    codexOutboundFallbackModelMappings?: ModelMapping[];
 };
 /** Cloaking plugin config */
 export type CloakingConfig = {

package/dist/utils/anthropicCacheBreakpoints.d.ts

@@ -1,4 +1,4 @@
-import type { ClaudeRequest, VertexAnthropicCacheInput, VertexAnthropicCacheOutput, VertexAnthropicMessage } from "../types/index.js";
+import type { ClaudeCacheBreakpointOptions, 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;
 /**
@@ -61,4 +61,4 @@ export declare function applyAnthropicHistoryCacheBreakpoints(input: ReadonlyArr
  *
  * Pure: inputs are cloned, never mutated.
  */
-export declare function applyClaudeRequestCacheBreakpoints(request: ClaudeRequest): ClaudeRequest;
+export declare function applyClaudeRequestCacheBreakpoints(request: ClaudeRequest, options?: ClaudeCacheBreakpointOptions): ClaudeRequest;

package/dist/utils/anthropicCacheBreakpoints.js

@@ -168,7 +168,7 @@ function markLastContentBlock(messages, i) {
  *
  * Pure: inputs are cloned, never mutated.
  */
-export function applyClaudeRequestCacheBreakpoints(request) {
+export function applyClaudeRequestCacheBreakpoints(request, options) {
     const existing = countAnthropicCacheMarkers({
         system: request.system,
         tools: request.tools,
@@ -184,6 +184,7 @@ export function applyClaudeRequestCacheBreakpoints(request) {
         return request;
     }
     const out = { ...request };
+    const breakpointOneMarker = ephemeral(options?.ttl);
     // 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.
@@ -191,7 +192,7 @@ export function applyClaudeRequestCacheBreakpoints(request) {
         const system = out.system.map((b) => ({ ...b }));
         system[system.length - 1] = {
             ...system[system.length - 1],
-            cache_control: CLAUDE_EPHEMERAL,
+            cache_control: breakpointOneMarker,
         };
         out.system = system;
         budget--;
@@ -203,7 +204,7 @@ export function applyClaudeRequestCacheBreakpoints(request) {
         const tools = out.tools.map((t) => ({ ...t }));
         tools[tools.length - 1] = {
             ...tools[tools.length - 1],
-            cache_control: CLAUDE_EPHEMERAL,
+            cache_control: breakpointOneMarker,
         };
         out.tools = tools;
         budget--;
@@ -214,6 +215,16 @@ export function applyClaudeRequestCacheBreakpoints(request) {
     return out;
 }
 const CLAUDE_EPHEMERAL = { type: "ephemeral" };
+/**
+ * Builds the breakpoint-1 marker, honoring a caller-supplied TTL override.
+ * Breakpoints 2-4 (`applyClaudeHistoryBreakpoints`) always use the bare
+ * `CLAUDE_EPHEMERAL` constant instead of this — they roll forward every turn
+ * or two, so paying the 1-hour (2x) rate on a marker about to be superseded
+ * is pure waste; only the stable head benefits from the longer window.
+ */
+function ephemeral(ttl) {
+    return ttl ? { type: "ephemeral", ttl } : CLAUDE_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