@juspay/neurolink 12.24.0 → 12.25.0

package/dist/proxy/routingEvidence.d.ts

@@ -1,7 +1,7 @@
 /** Schema-v1 routing evidence values shared by emitters and offline readers. */
 export declare const PROXY_ACCOUNT_ROUTING_STRATEGIES: readonly ["round-robin", "fill-first"];
 export declare const PROXY_ACCOUNT_ROUTING_MODES: readonly ["quota", "primary", "round_robin", "single_account"];
-export declare const PROXY_ACCOUNT_ROUTING_REASONS: readonly ["single_account", "round_robin", "configured_primary", "insertion_order", "availability", "cooldown_recovery", "quota_evidence", "quota_probe", "session_headroom", "scoped_headroom", "session_reset", "weekly_reset", "weekly_utilization", "scoped_utilization"];
+export declare const PROXY_ACCOUNT_ROUTING_REASONS: readonly ["single_account", "round_robin", "configured_primary", "insertion_order", "availability", "cooldown_recovery", "quota_evidence", "quota_probe", "session_headroom", "scoped_headroom", "session_reset", "weekly_reset", "weekly_utilization", "scoped_utilization", "headroom", "session_affinity", "preferred_primary", "spill_inflight", "routing_policy_error"];
 export declare const PROXY_ACCOUNT_TYPES: readonly ["oauth", "api_key"];
 export declare const ACCOUNT_COOLING_REASONS: readonly ["weekly", "session", "unified", "transient", "auth"];
 /**

package/dist/proxy/routingEvidence.js

@@ -26,6 +26,11 @@ export const PROXY_ACCOUNT_ROUTING_REASONS = [
     "weekly_reset",
     "weekly_utilization",
     "scoped_utilization",
+    "headroom",
+    "session_affinity",
+    "preferred_primary",
+    "spill_inflight",
+    "routing_policy_error",
 ];
 export const PROXY_ACCOUNT_TYPES = ["oauth", "api_key"];
 export const ACCOUNT_COOLING_REASONS = [

package/dist/proxy/runtimeConfig.js

@@ -229,6 +229,11 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         .digest("hex")
         .slice(0, 16);
     const useOverage = routing?.useOverage ?? "auto";
+    const accountRanking = routing?.accountRanking ?? "expiry-first";
+    const preferPrimary = routing?.preferPrimary ?? false;
+    const sessionAffinity = routing?.sessionAffinity ?? false;
+    const sessionAffinityIdleTtlMs = routing?.sessionAffinityIdleTtlMs ?? 3_600_000;
+    const spillInflight = routing?.spillInflight ?? 0;
     const fingerprintSource = JSON.stringify({
         strategy,
         passthrough: options.passthrough,
@@ -239,6 +244,11 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         sessionSoftLimit,
         sessionResetToleranceMs,
         useOverage,
+        accountRanking,
+        preferPrimary,
+        sessionAffinity,
+        sessionAffinityIdleTtlMs,
+        spillInflight,
     });
     const configHash = createHash("sha256")
         .update(fingerprintSource)
@@ -259,6 +269,11 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
             sessionSoftLimit,
             sessionResetToleranceMs,
             useOverage,
+            accountRanking,
+            preferPrimary,
+            sessionAffinity,
+            sessionAffinityIdleTtlMs,
+            spillInflight,
         }),
         configFilePresent,
         envFilePresent,

package/dist/proxy/sessionAffinity.d.ts

@@ -0,0 +1,23 @@
+/** Bind a session to the account that just served it, refreshing its idle clock. */
+export declare function bind(sessionId: string, accountKey: string, now: number): void;
+/**
+ * The account a session is bound to, or undefined if unbound or idle-expired.
+ * A read never refreshes the binding — only a served request (bind) does,
+ * since the idle TTL counts from the session's last served request.
+ */
+export declare function get(sessionId: string, now: number, idleTtlMs: number): string | undefined;
+export declare function clear(): void;
+export declare function size(): number;
+/**
+ * Sessions whose binding has not idle-expired. Expired entries are dropped
+ * here as on read, since otherwise they would linger until the cap evicted
+ * them.
+ */
+export declare function countActive(now: number, idleTtlMs: number): number;
+export declare const sessionAffinity: Readonly<{
+    bind: typeof bind;
+    get: typeof get;
+    clear: typeof clear;
+    size: typeof size;
+    countActive: typeof countActive;
+}>;

package/dist/proxy/sessionAffinity.js

@@ -0,0 +1,62 @@
+const MAX_BOUND_SESSIONS = 5_000;
+// Per-record shape is an inline type on the Map's generic parameter rather
+// than a named `type` alias: it is a private, single-use implementation
+// detail with no external consumer, so it does not belong in
+// src/lib/types/ (CLAUDE.md rule 2 targets shared type definitions).
+const bindings = new Map();
+/** Bind a session to the account that just served it, refreshing its idle clock. */
+export function bind(sessionId, accountKey, now) {
+    // Delete-then-set moves the entry to the end of Map iteration order, which
+    // is what makes that order double as least-recently-bound-first for the
+    // cap eviction below.
+    bindings.delete(sessionId);
+    bindings.set(sessionId, { accountKey, lastServedAt: now });
+    if (bindings.size > MAX_BOUND_SESSIONS) {
+        const oldestKey = bindings.keys().next().value;
+        if (oldestKey !== undefined) {
+            bindings.delete(oldestKey);
+        }
+    }
+}
+/**
+ * The account a session is bound to, or undefined if unbound or idle-expired.
+ * A read never refreshes the binding — only a served request (bind) does,
+ * since the idle TTL counts from the session's last served request.
+ */
+export function get(sessionId, now, idleTtlMs) {
+    const record = bindings.get(sessionId);
+    if (!record) {
+        return undefined;
+    }
+    if (now - record.lastServedAt > idleTtlMs) {
+        bindings.delete(sessionId);
+        return undefined;
+    }
+    return record.accountKey;
+}
+export function clear() {
+    bindings.clear();
+}
+export function size() {
+    return bindings.size;
+}
+/**
+ * Sessions whose binding has not idle-expired. Expired entries are dropped
+ * here as on read, since otherwise they would linger until the cap evicted
+ * them.
+ */
+export function countActive(now, idleTtlMs) {
+    for (const [sessionId, record] of bindings) {
+        if (now - record.lastServedAt > idleTtlMs) {
+            bindings.delete(sessionId);
+        }
+    }
+    return bindings.size;
+}
+export const sessionAffinity = Object.freeze({
+    bind,
+    get,
+    clear,
+    size,
+    countActive,
+});

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

@@ -2,7 +2,7 @@ import { buildTranslationOptions } from "../../proxy/proxyTranslationEngine.js";
 import { ProxyTracer } from "../../proxy/proxyTracer.js";
 import { isPermanentRefreshFailure } from "../../proxy/tokenRefresh.js";
 import type { ProxyAccountDirectoryOverride } from "../../types/index.js";
-import type { AccountAllowlist, AccountAdmissionLease, JsonObject, AccountCooldownPlan, AccountQuota, AccountQuotaWindow, AccountUsageFetchResult, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicEntitlementFailure, AnthropicInvalidRequestFailure, AnthropicLoopState, AnthropicScopedExhaustion, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamBody, AnthropicUpstreamBodyBuilder, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyLimitsRefreshResponse, ProxyQuotaCooldownUpdate, ProxyOveragePolicy, ProxyPassthroughAccount, QueuedAccountAdmission, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
+import type { AccountAllowlist, AccountAdmissionLease, JsonObject, AccountCooldownPlan, AccountQuota, AccountQuotaWindow, AccountUsageFetchResult, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicEntitlementFailure, AnthropicInvalidRequestFailure, AnthropicLoopState, AnthropicScopedExhaustion, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamBody, AnthropicUpstreamBodyBuilder, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRankingPolicy, ProxyAccountRoutingAffinityEvidence, ProxyAccountRoutingDecision, ProxyAccountRoutingReason, ProxyAccountRoutingSpillEvidence, ProxyAccountSortMetrics, ProxyAffinityPrecedenceSkipReason, ProxyBodyCaptureLogger, ProxyLimitsRefreshResponse, ProxyQuotaCooldownUpdate, ProxyOveragePolicy, ProxyPassthroughAccount, ProxyRoutingPolicySnapshot, QueuedAccountAdmission, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
 declare function tryAcquireAccountAdmission(accountKey: string, capacity: number | undefined, generation?: number): AccountAdmissionLease | undefined;
 /** Current in-flight request count for one account, unlimited or capped. */
 declare function getAccountInflight(accountKey: string): number;
@@ -121,9 +121,18 @@ declare function evaluateScopedExhaustion(accounts: ProxyPassthroughAccount[], r
     eligible: ProxyPassthroughAccount[];
     exhaustion: AnthropicScopedExhaustion | null;
 };
-declare function orderAccountsByQuotaWithMetrics(accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit: number, sessionResetToleranceMs: number, requestedModel?: string): {
+declare function orderAccountsByQuotaWithMetrics(accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit: number, sessionResetToleranceMs: number, options?: {
+    requestedModel?: string;
+    policy?: {
+        ranking?: ProxyAccountRankingPolicy;
+        affinityKey?: string;
+        preferPrimary?: boolean;
+    };
+}): {
     orderedAccounts: ProxyPassthroughAccount[];
     metricsByKey: Map<string, ProxyAccountSortMetrics>;
+    reason: ProxyAccountRoutingReason;
+    affinitySkippedReason: ProxyAffinityPrecedenceSkipReason | null;
 };
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
@@ -164,7 +173,30 @@ declare function buildRoutingDecision(args: {
     sessionSoftLimit: number;
     sessionResetToleranceMs: number;
     rotationOffset: number;
+    policySelectionReason?: ProxyAccountRoutingReason;
+    policy?: ProxyRoutingPolicySnapshot;
+    affinity?: ProxyAccountRoutingAffinityEvidence;
+    spill?: ProxyAccountRoutingSpillEvidence;
 }): ProxyAccountRoutingDecision | undefined;
+declare function selectClaudeProxyAccountOrder(args: {
+    enabledAccounts: ProxyPassthroughAccount[];
+    accountStrategy: "round-robin" | "fill-first";
+    primaryAccountKey: string | undefined;
+    quotaRoutingEnabled: boolean;
+    sessionSoftLimit: number;
+    sessionResetToleranceMs: number;
+    requestedModel?: string;
+    sessionId?: string;
+    ranking: ProxyAccountRankingPolicy;
+    preferPrimary: boolean;
+    sessionAffinityEnabled: boolean;
+    sessionAffinityIdleTtlMs: number;
+    spillInflight: number;
+    setRoutingDecision: (decision: ProxyAccountRoutingDecision) => void;
+}): {
+    orderedAccounts: ProxyPassthroughAccount[];
+    metricsByKey: Map<string, ProxyAccountSortMetrics>;
+};
 declare function trackUpstreamReadableStream(source: ReadableStream<Uint8Array>): {
     stream: ReadableStream<Uint8Array>;
     outcome: Promise<StreamTerminalOutcome>;
@@ -314,6 +346,7 @@ declare function handleAnthropicAuthRetry(args: {
     sawRateLimit: boolean;
     sawTransientFailure: boolean;
     sawNetworkError: boolean;
+    bindServedSession?: (servingAccountKey: string) => void;
 }): Promise<AnthropicAuthRetryResult>;
 declare function finalizeAnthropicTerminalFetchError(args: {
     terminalError: NonNullable<AnthropicUpstreamFetchResult["terminalError"]>;
@@ -506,7 +539,14 @@ export declare const __testHooks: {
     scheduleAdaptiveQuotaRefreshes: typeof scheduleAdaptiveQuotaRefreshes;
     scheduleHandoffQuotaRefresh: typeof scheduleHandoffQuotaRefresh;
     getQuotaRefreshState: (key: string) => import("../../index.js").ProxyQuotaRefreshRuntimeState;
-    buildQuotaRoutingDecision: (accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number, requestedModel?: string) => ProxyAccountRoutingDecision | undefined;
+    buildQuotaRoutingDecision: (accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number, options?: {
+        requestedModel?: string;
+        policy?: {
+            ranking?: ProxyAccountRankingPolicy;
+            affinityKey?: string;
+            preferPrimary?: boolean;
+        };
+    }) => ProxyAccountRoutingDecision | undefined;
     buildRoutingDecision: typeof buildRoutingDecision;
     resetEpochToMs: typeof resetEpochToMs;
     seedRuntimeQuotasFromDisk: typeof seedRuntimeQuotasFromDisk;
@@ -520,6 +560,11 @@ export declare const __testHooks: {
         bodyStr: string;
         sessionId?: string;
     };
+    extractSnapshotBodySessionIdForTests: (body: unknown) => string | undefined;
+    selectClaudeProxyAccountOrderForTests: typeof selectClaudeProxyAccountOrder;
+    setForceSpillThrowForTests: (value: boolean) => void;
+    setForceAffinityLookupThrowForTests: (value: boolean) => void;
+    setForceBindRecheckThrowForTests: (value: boolean) => void;
     isAntiAbuseConstruction429: typeof isAntiAbuseConstruction429;
     fetchAnthropicAccountResponse: typeof fetchAnthropicAccountResponse;
     finalizeAnthropicTerminalFetchError: typeof finalizeAnthropicTerminalFetchError;