@juspay/neurolink 12.24.1 → 12.25.1

package/dist/server/routes/claudeProxyRoutes.js

@@ -24,7 +24,8 @@ import { fetchCodexAccountUsage, listCodexAccountsForUsage, resolveProxyStatusAc
 import { AccountQuotaRefreshCoordinator } from "../../proxy/accountQuotaRefreshCoordinator.js";
 import { ProviderTransportCoordinator } from "../../proxy/providerTransportCoordinator.js";
 import { MAX_COOLDOWN_MS_BY_REASON } from "../../proxy/routingEvidence.js";
-import { compareExpiryFirst, rankAccounts, } from "../../proxy/accountRanking.js";
+import { applyAffinityAndPrimary, applySpill, compareExpiryFirst, isPrecedenceEligible, rankAccounts, } from "../../proxy/accountRanking.js";
+import { sessionAffinity } from "../../proxy/sessionAffinity.js";
 import { buildProxyLimitHeaders, summarizePoolHeadroom, } from "../../proxy/quotaHeaders.js";
 import { buildClaudeError, ClaudeStreamSerializer, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
 import { getProxyUpstreamFailure } from "../../proxy/proxyFailureDetails.js";
@@ -1506,17 +1507,24 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
         weeklyUsedForSort: weeklyUsed ?? -1,
     };
 }
-function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, requestedModel) {
-    const metricsByKey = new Map(accounts.map((account) => [
+function buildAccountSortMetricsByKey(accounts, now, sessionSoftLimit, sessionResetToleranceMs, requestedModel) {
+    return new Map(accounts.map((account) => [
         account.key,
         accountSortMetrics(account.key, now, sessionSoftLimit, sessionResetToleranceMs, requestedModel),
     ]));
-    const { orderedAccounts } = rankAccounts({
+}
+function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, options) {
+    const policy = options?.policy;
+    const metricsByKey = buildAccountSortMetricsByKey(accounts, now, sessionSoftLimit, sessionResetToleranceMs, options?.requestedModel);
+    const { orderedAccounts, reason, affinitySkippedReason } = rankAccounts({
         accounts,
         metricsByKey,
         primaryKey,
+        ranking: policy?.ranking,
+        affinityKey: policy?.affinityKey,
+        preferPrimary: policy?.preferPrimary,
     });
-    return { orderedAccounts, metricsByKey };
+    return { orderedAccounts, metricsByKey, reason, affinitySkippedReason };
 }
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
@@ -1543,7 +1551,7 @@ function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftL
  * last resort.
  */
 function orderAccountsByQuota(accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), requestedModel) {
-    return orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, requestedModel).orderedAccounts;
+    return orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, { requestedModel }).orderedAccounts;
 }
 function scheduleAdaptiveQuotaRefreshes(accounts, orderedAccounts, sessionSoftLimit, routingMetrics) {
     for (const account of accounts) {
@@ -1673,7 +1681,9 @@ function buildRoutingDecision(args) {
     }
     else if (quotaOrdered) {
         mode = "quota";
-        selectionReason = compareExpiryFirst(orderedAccounts[0], orderedAccounts[1], metricsByKey, primaryKey)[1];
+        selectionReason =
+            args.policySelectionReason ??
+                compareExpiryFirst(orderedAccounts[0], orderedAccounts[1], metricsByKey, primaryKey)[1];
     }
     else if (strategy === "round-robin") {
         mode = "round_robin";
@@ -1682,9 +1692,10 @@ function buildRoutingDecision(args) {
     else {
         mode = "primary";
         selectionReason =
-            configuredPrimaryMatched && initialAccount?.key === primaryKey
-                ? "configured_primary"
-                : "insertion_order";
+            args.policySelectionReason ??
+                (configuredPrimaryMatched && initialAccount?.key === primaryKey
+                    ? "configured_primary"
+                    : "insertion_order");
     }
     return {
         schemaVersion: 1,
@@ -1701,10 +1712,54 @@ function buildRoutingDecision(args) {
         rotationOffset,
         initialAccount: initialAccount?.label ?? "",
         candidates,
+        ...(args.policy ? { policy: args.policy } : {}),
+        ...(args.affinity ? { affinity: args.affinity } : {}),
+        ...(args.spill ? { spill: args.spill } : {}),
     };
 }
+// A policy error can repeat on every request, so each (site, error) pair is
+// logged once. Keyed per pair rather than once per worker, so a later,
+// unrelated failure still reaches the log. Insertion order is eviction order.
+const MAX_LOGGED_ROUTING_POLICY_ERRORS = 32;
+const loggedRoutingPolicyErrors = new Set();
+function logRoutingPolicyErrorOnce(error, fallbackOrder) {
+    const message = error instanceof Error ? error.message : String(error);
+    const signature = JSON.stringify([
+        fallbackOrder,
+        error instanceof Error ? error.name : typeof error,
+        message,
+    ]);
+    if (loggedRoutingPolicyErrors.has(signature)) {
+        return;
+    }
+    loggedRoutingPolicyErrors.add(signature);
+    if (loggedRoutingPolicyErrors.size > MAX_LOGGED_ROUTING_POLICY_ERRORS) {
+        const oldest = loggedRoutingPolicyErrors.values().next().value;
+        if (oldest !== undefined) {
+            loggedRoutingPolicyErrors.delete(oldest);
+        }
+    }
+    logger.always(`[proxy] routing policy threw; falling back to ${fallbackOrder}: ${message}`);
+}
+// Test-only: makes maybeSpill() throw before its own guard, including on a
+// "session_affinity" first choice it would otherwise skip. That is the only
+// deterministic way to reach the policy catch after a genuine reorder, since
+// the policy steps return the input order unchanged when nothing applies.
+let forceSpillThrowForTests = false;
+// Test-only: make the selection-time affinity lookup, or the post-serve
+// binding re-check, throw. Each enters its own policy catch without reaching
+// into the binding store, so the store can stay frozen.
+let forceAffinityLookupThrowForTests = false;
+let forceBindRecheckThrowForTests = false;
 function selectClaudeProxyAccountOrder(args) {
-    const { enabledAccounts, accountStrategy, primaryAccountKey, quotaRoutingEnabled, sessionSoftLimit, sessionResetToleranceMs, requestedModel, setRoutingDecision, } = args;
+    const { enabledAccounts, accountStrategy, quotaRoutingEnabled, sessionSoftLimit, sessionResetToleranceMs, requestedModel, sessionId, ranking, preferPrimary, sessionAffinityEnabled, sessionAffinityIdleTtlMs, spillInflight, setRoutingDecision, } = args;
+    // The configured primary arrives normalized (lower-cased, prefixed), while
+    // account keys keep the token store's spelling, and every primary check
+    // below compares with ===. Resolve it to the loaded account's own key once.
+    const configuredPrimaryKey = args.primaryAccountKey;
+    const primaryAccountKey = configuredPrimaryKey === undefined
+        ? undefined
+        : (enabledAccounts.find((account) => anthropicAccountKeysEqual(account.key, configuredPrimaryKey))?.key ?? configuredPrimaryKey);
     let orderedAccounts = [...enabledAccounts];
     const evaluatedAt = Date.now();
     let metricsByKey;
@@ -1712,14 +1767,111 @@ function selectClaudeProxyAccountOrder(args) {
     const quotaOrdered = accountStrategy === "fill-first" &&
         orderedAccounts.length > 1 &&
         quotaRoutingEnabled;
+    // strategy: round-robin ignores every routing policy key.
+    const policiesApply = accountStrategy === "fill-first" && orderedAccounts.length > 1;
+    const policy = policiesApply
+        ? {
+            ranking,
+            preferPrimary,
+            sessionAffinity: sessionAffinityEnabled,
+            sessionAffinityIdleTtlMs,
+            spillInflight,
+        }
+        : undefined;
+    let policySelectionReason;
+    let affinity;
+    let spill;
+    const resolveAffinityKey = () => {
+        if (!sessionAffinityEnabled || !sessionId) {
+            return undefined;
+        }
+        if (forceAffinityLookupThrowForTests) {
+            throw new Error("forced failure for affinity lookup throw test");
+        }
+        return sessionAffinity.get(sessionId, evaluatedAt, sessionAffinityIdleTtlMs);
+    };
+    const buildAffinityEvidence = (boundAccountKey, applied, skippedFromPrecedence) => ({
+        sessionBound: !!boundAccountKey,
+        boundAccount: (boundAccountKey &&
+            enabledAccounts.find((account) => account.key === boundAccountKey)
+                ?.label) ??
+            null,
+        applied,
+        skippedReason: !sessionAffinityEnabled
+            ? "disabled"
+            : !sessionId
+                ? "no_session"
+                : !boundAccountKey
+                    ? "expired"
+                    : applied
+                        ? null
+                        : skippedFromPrecedence,
+    });
+    const labelOf = (accountKey) => enabledAccounts.find((account) => account.key === accountKey)?.label ??
+        accountKey;
+    const maybeSpill = (order, reason, metrics) => {
+        if (forceSpillThrowForTests) {
+            throw new Error("forced failure for spill throw test");
+        }
+        // Spill never splits a bound session, but a preferred-primary first
+        // choice has no binding and can still be relieved.
+        if (spillInflight <= 0 || reason === "session_affinity") {
+            return undefined;
+        }
+        const inflightByKey = new Map(order.map((account) => [account.key, getAccountInflight(account.key)]));
+        const spillResult = applySpill({
+            orderedAccounts: order,
+            inflightByKey,
+            metricsByKey: metrics,
+            spillInflight,
+        });
+        const move = spillResult.spill;
+        if (!move) {
+            return undefined;
+        }
+        return {
+            orderedAccounts: spillResult.orderedAccounts,
+            spill: {
+                from: labelOf(move.from),
+                to: labelOf(move.to),
+                inflight: move.inflight,
+            },
+        };
+    };
     if (!quotaOrdered && accountStrategy === "fill-first") {
         // A hot-reloaded primary change must apply to this request.
         maybeResetPrimaryToHome(enabledAccounts, primaryAccountKey);
     }
     if (quotaOrdered) {
-        const quotaOrder = orderAccountsByQuotaWithMetrics(enabledAccounts, evaluatedAt, primaryAccountKey, sessionSoftLimit, sessionResetToleranceMs, requestedModel);
-        orderedAccounts = quotaOrder.orderedAccounts;
-        metricsByKey = quotaOrder.metricsByKey;
+        // Metrics are not a policy step: a throw here propagates, as it did
+        // before the policies existed, instead of reading as a policy failure.
+        metricsByKey = buildAccountSortMetricsByKey(enabledAccounts, evaluatedAt, sessionSoftLimit, sessionResetToleranceMs, requestedModel);
+        try {
+            const boundAccountKey = resolveAffinityKey();
+            const quotaOrder = rankAccounts({
+                accounts: enabledAccounts,
+                metricsByKey,
+                primaryKey: primaryAccountKey,
+                ranking,
+                affinityKey: boundAccountKey,
+                preferPrimary,
+            });
+            const spilled = maybeSpill(quotaOrder.orderedAccounts, quotaOrder.reason, metricsByKey);
+            const affinityEvidence = buildAffinityEvidence(boundAccountKey, quotaOrder.reason === "session_affinity", quotaOrder.affinitySkippedReason);
+            orderedAccounts = spilled?.orderedAccounts ?? quotaOrder.orderedAccounts;
+            policySelectionReason = spilled ? "spill_inflight" : quotaOrder.reason;
+            affinity = affinityEvidence;
+            spill = spilled?.spill;
+        }
+        catch (error) {
+            logRoutingPolicyErrorOnce(error, "expiry-first order");
+            orderedAccounts = rankAccounts({
+                accounts: enabledAccounts,
+                metricsByKey,
+                primaryKey: primaryAccountKey,
+            }).orderedAccounts;
+            policySelectionReason = "routing_policy_error";
+        }
         if (logger.shouldLog("debug")) {
             logger.debug(`[proxy] quota-ordered fill sequence: ${orderedAccounts
                 .map((account) => account.label)
@@ -1743,10 +1895,36 @@ function selectClaudeProxyAccountOrder(args) {
                 orderedAccounts.push(...head);
             }
         }
-        metricsByKey = new Map(enabledAccounts.map((account) => [
-            account.key,
-            accountSortMetrics(account.key, evaluatedAt, sessionSoftLimit, sessionResetToleranceMs, requestedModel),
-        ]));
+        metricsByKey = buildAccountSortMetricsByKey(enabledAccounts, evaluatedAt, sessionSoftLimit, sessionResetToleranceMs, requestedModel);
+        // Quota routing off: the rotation above stays the base order, and
+        // affinity/prefer-primary/spill still apply on top of it. Nothing is
+        // assigned until every policy step has succeeded, so a throw leaves the
+        // pre-policy order in place.
+        if (policiesApply) {
+            try {
+                const boundAccountKey = resolveAffinityKey();
+                const precedence = applyAffinityAndPrimary({
+                    orderedAccounts,
+                    metricsByKey,
+                    affinityKey: boundAccountKey,
+                    primaryKey: primaryAccountKey,
+                    preferPrimary,
+                });
+                const spilled = maybeSpill(precedence.orderedAccounts, precedence.reason, metricsByKey);
+                const affinityEvidence = buildAffinityEvidence(boundAccountKey, precedence.reason === "session_affinity", precedence.affinitySkippedReason);
+                orderedAccounts =
+                    spilled?.orderedAccounts ?? precedence.orderedAccounts;
+                policySelectionReason = spilled
+                    ? "spill_inflight"
+                    : (precedence.reason ?? undefined);
+                affinity = affinityEvidence;
+                spill = spilled?.spill;
+            }
+            catch (error) {
+                logRoutingPolicyErrorOnce(error, "pre-policy order");
+                policySelectionReason = "routing_policy_error";
+            }
+        }
     }
     const routingDecision = buildRoutingDecision({
         accounts: enabledAccounts,
@@ -1760,12 +1938,50 @@ function selectClaudeProxyAccountOrder(args) {
         sessionSoftLimit,
         sessionResetToleranceMs,
         rotationOffset,
+        policySelectionReason,
+        policy,
+        affinity,
+        spill,
     });
     if (routingDecision) {
         setRoutingDecision(routingDecision);
     }
     return { orderedAccounts, metricsByKey };
 }
+/**
+ * Records that a session's request was served. A session keeps its current
+ * binding only when this request never tried the bound account and that
+ * account is still eligible: a request that overflowed its bound account's
+ * admission cap onto another account must not move the session off its warm
+ * prompt cache. Otherwise the serving account becomes the binding. Tried
+ * outranks eligible because an account that failed this request can look
+ * eligible again by now: a short 429 cooldown can lapse while the next
+ * account is still answering.
+ */
+function bindSessionAfterServe(args) {
+    const now = Date.now();
+    // This runs after the response has already been served (and, on the
+    // stream path, after admission-lease ownership has transferred to the
+    // stream): a throw here must never drop that response or leak the lease,
+    // so eligibility re-checks fall back to binding the serving account.
+    let accountKey = args.servingAccountKey;
+    try {
+        if (forceBindRecheckThrowForTests) {
+            throw new Error("forced failure for bind recheck throw test");
+        }
+        const boundKey = sessionAffinity.get(args.sessionId, now, args.idleTtlMs);
+        if (boundKey !== undefined &&
+            !args.attemptedAccountKeys.has(boundKey) &&
+            args.enabledAccounts.some((account) => account.key === boundKey) &&
+            isPrecedenceEligible(accountSortMetrics(boundKey, now, args.sessionSoftLimit, args.sessionResetToleranceMs, args.requestedModel))) {
+            accountKey = boundKey;
+        }
+    }
+    catch (error) {
+        logRoutingPolicyErrorOnce(error, "serving-account binding");
+    }
+    sessionAffinity.bind(args.sessionId, accountKey, now);
+}
 // ---------------------------------------------------------------------------
 // OAuth polyfill helpers (extracted to reduce block nesting)
 // ---------------------------------------------------------------------------
@@ -3254,7 +3470,7 @@ function earliestShareRecoverySeconds(views, now) {
     return Math.max(1, Math.round((Math.min(...resets) - now) / 1000));
 }
 async function loadClaudeProxyAccounts(args) {
-    const { ctx, body, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), setRoutingDecision, } = args;
+    const { ctx, body, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), ranking = "expiry-first", preferPrimary = false, sessionAffinityEnabled = false, sessionAffinityIdleTtlMs = 3_600_000, spillInflight = 0, setRoutingDecision, } = args;
     const fs = await import("fs");
     const os = await import("os");
     const accounts = [];
@@ -3510,6 +3726,13 @@ async function loadClaudeProxyAccounts(args) {
             },
         };
     }
+    // Resolved ahead of account selection (rather than after, as before) so
+    // sessionId is available to selectClaudeProxyAccountOrder for session
+    // affinity. normalizeClaudeRequestForAnthropic below returns a
+    // shallow clone and never mutates `body`, so extracting earlier sees
+    // exactly the same snapshot extractSnapshotBody always saw.
+    const clientHeaders = ctx.headers ?? {};
+    const clientSnapshotBody = extractSnapshotBody(body);
     const { orderedAccounts, metricsByKey } = selectClaudeProxyAccountOrder({
         enabledAccounts,
         accountStrategy,
@@ -3518,6 +3741,12 @@ async function loadClaudeProxyAccounts(args) {
         sessionSoftLimit,
         sessionResetToleranceMs,
         requestedModel: typeof body.model === "string" ? body.model : undefined,
+        sessionId: clientSnapshotBody?.sessionId,
+        ranking,
+        preferPrimary,
+        sessionAffinityEnabled,
+        sessionAffinityIdleTtlMs,
+        spillInflight,
         setRoutingDecision,
     });
     if (accountStrategy === "fill-first" &&
@@ -3530,8 +3759,6 @@ async function loadClaudeProxyAccounts(args) {
     const requestStart = Date.now();
     const toolCount = Array.isArray(body.tools) ? body.tools.length : 0;
     const url = "https://api.anthropic.com/v1/messages?beta=true";
-    const clientHeaders = ctx.headers ?? {};
-    const clientSnapshotBody = extractSnapshotBody(body);
     return {
         accounts,
         enabledAccounts,
@@ -3542,6 +3769,7 @@ async function loadClaudeProxyAccounts(args) {
         url,
         clientHeaders,
         isClaudeClientRequest: isLikelyClaudeClient(clientHeaders, clientSnapshotBody),
+        sessionId: clientSnapshotBody?.sessionId,
     };
 }
 /**
@@ -4658,7 +4886,7 @@ async function handleAnthropicStreamingSuccessResponse(args) {
             responseStatus: 502,
             durationMs: Date.now() - requestStartTime,
         });
-        return { response: clientError };
+        return { response: clientError, served: false };
     }
     const reader = response.body.getReader();
     const preflight = await preflightAnthropicStream(reader);
@@ -4695,6 +4923,7 @@ async function handleAnthropicStreamingSuccessResponse(args) {
                 errorType: "stream_error",
                 message,
             }),
+            served: false,
         };
     }
     if (preflight.kind === "empty") {
@@ -4858,7 +5087,7 @@ async function handleAnthropicStreamingSuccessResponse(args) {
         logFinalRequest,
     });
     void telemetryDone.then(() => onStreamTerminal?.(), () => onStreamTerminal?.());
-    return { response: result, holdsAccountAdmission: true };
+    return { response: result, holdsAccountAdmission: true, served: true };
 }
 function getStreamFailureDetails(outcome) {
     if (outcome.kind === "upstream_error") {
@@ -5235,7 +5464,7 @@ async function handleAnthropicJsonSuccessResponse(args) {
             cacheReadTokens: noTracerUsage?.cache_read_input_tokens,
         });
     }
-    return { response: responseJson };
+    return { response: responseJson, served: true };
 }
 async function handleAnthropicSuccessfulNonStreamRetryResponse(args) {
     const { ctx, account, accountState, requestedModel, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, } = args;
@@ -5330,7 +5559,7 @@ async function handleAnthropicSuccessfulNonStreamRetryResponse(args) {
     return retryJson;
 }
 async function handleAnthropicAuthRetry(args) {
-    const { ctx, body, account, accountState, headers, buildUpstreamBody, url, enabledAccounts, orderedAccounts, tracer, requestStartTime, allocateAttemptNumber, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, lastError, authFailureMessage, entitlementFailure, sawRateLimit, sawTransientFailure, sawNetworkError, } = args;
+    const { ctx, body, account, accountState, headers, buildUpstreamBody, url, enabledAccounts, orderedAccounts, tracer, requestStartTime, allocateAttemptNumber, upstreamSpan, logAttempt, logProxyBody, onStreamTerminal, logFinalRequest, lastError, authFailureMessage, entitlementFailure, sawRateLimit, sawTransientFailure, sawNetworkError, bindServedSession, } = args;
     recordAttemptError(account.label, account.type, 401);
     logAttempt(401, "authentication_error", "received 401 from Anthropic", {
         retryable: true,
@@ -5432,6 +5661,10 @@ async function handleAnthropicAuthRetry(args) {
                             logProxyBody,
                             logFinalRequest,
                         }),
+                        // handleAnthropicSuccessfulNonStreamRetryResponse is only ever
+                        // called when retryResp.ok — unlike the streaming path, it has
+                        // no terminal-error return sharing this shape.
+                        served: true,
                     };
                 if ("retryNextAccount" in successResult) {
                     const failure = successResult.failure;
@@ -5450,6 +5683,9 @@ async function handleAnthropicAuthRetry(args) {
                         upstreamSpan: undefined,
                     };
                 }
+                if (bindServedSession && successResult.served) {
+                    bindServedSession(account.key);
+                }
                 return {
                     response: successResult.response,
                     holdsAccountAdmission: successResult.holdsAccountAdmission,
@@ -6750,7 +6986,7 @@ function buildDeferredClaudeAccountFailureResponse(args) {
     return buildLoggedClaudeError(failure.status, failure.message, failure.errorType);
 }
 async function handleAnthropicRoutedClaudeRequest(args) {
-    const { ctx, body, modelRouter, configGeneration, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, logProxyBody, logFinalRequest, setRoutingDecision, } = args;
+    const { ctx, body, modelRouter, configGeneration, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), ranking = "expiry-first", preferPrimary = false, sessionAffinityEnabled = false, sessionAffinityIdleTtlMs = 3_600_000, spillInflight = 0, buildLoggedClaudeError, logProxyBody, logFinalRequest, setRoutingDecision, } = args;
     const parsedRequest = parseClaudeRequest(body);
     const configuredFallbackPlan = buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, modelRouter?.getFallbackChain() ?? [], body.model, parsedRequest);
     const hasConfiguredFallback = configuredFallbackPlan.attempts
@@ -6765,6 +7001,11 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         quotaRoutingEnabled,
         sessionSoftLimit,
         sessionResetToleranceMs,
+        ranking,
+        preferPrimary,
+        sessionAffinityEnabled,
+        sessionAffinityIdleTtlMs,
+        spillInflight,
         setRoutingDecision,
     });
     if ("failure" in loadedAccounts) {
@@ -6826,7 +7067,27 @@ async function handleAnthropicRoutedClaudeRequest(args) {
             buildLoggedClaudeError,
         });
     }
-    const { accounts, enabledAccounts, orderedAccounts, bodyStr, requestStart, toolCount, url, clientHeaders, isClaudeClientRequest, } = loadedAccounts;
+    const { accounts, enabledAccounts, orderedAccounts, bodyStr, requestStart, toolCount, url, clientHeaders, isClaudeClientRequest, sessionId, } = loadedAccounts;
+    // Accounts this request sent an upstream attempt to; one skipped only for
+    // its admission cap is not among them.
+    const attemptedAccountKeys = new Set();
+    // Only fill-first over more than one account reads a binding (see
+    // selectClaudeProxyAccountOrder), so nothing else records one.
+    const bindServedSession = sessionAffinityEnabled &&
+        sessionId &&
+        accountStrategy === "fill-first" &&
+        enabledAccounts.length > 1
+        ? (servingAccountKey) => bindSessionAfterServe({
+            sessionId,
+            servingAccountKey,
+            attemptedAccountKeys,
+            enabledAccounts,
+            idleTtlMs: sessionAffinityIdleTtlMs,
+            sessionSoftLimit,
+            sessionResetToleranceMs,
+            requestedModel: typeof body.model === "string" ? body.model : undefined,
+        })
+        : undefined;
     // Snapshot the operator policy once. Reading the module value later would let
     // a concurrent /limits call or a hot config reload change this request's
     // answer partway through its own account loop.
@@ -6999,6 +7260,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                     }
                     continue accountLoop;
                 }
+                attemptedAccountKeys.add(account.key);
                 let admissionTransferredToStream = false;
                 try {
                     let fetchResult;
@@ -7164,6 +7426,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                             sawRateLimit: loopState.sawRateLimit,
                             sawTransientFailure: loopState.sawTransientFailure,
                             sawNetworkError: loopState.sawNetworkError,
+                            bindServedSession,
                         });
                         loopState.lastError = authRetryResult.lastError;
                         loopState.authFailureMessage = authRetryResult.authFailureMessage;
@@ -7281,6 +7544,9 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                     }
                     admissionTransferredToStream =
                         successResult.holdsAccountAdmission === true;
+                    if (bindServedSession && successResult.served) {
+                        bindServedSession(account.key);
+                    }
                     return successResult.response;
                 }
                 finally {
@@ -7539,6 +7805,11 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                         sessionSoftLimit: getSessionSoftLimit(),
                         sessionResetToleranceMs: getSessionResetToleranceMs(),
                         useOverage: "auto",
+                        accountRanking: "expiry-first",
+                        preferPrimary: false,
+                        sessionAffinity: false,
+                        sessionAffinityIdleTtlMs: 3_600_000,
+                        spillInflight: 0,
                     };
                     setOveragePolicy(requestRouting.useOverage);
                     const requestModelRouter = requestRouting.modelRouter;
@@ -7612,6 +7883,11 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                                 quotaRoutingEnabled: requestRouting.quotaRoutingEnabled,
                                 sessionSoftLimit: requestRouting.sessionSoftLimit,
                                 sessionResetToleranceMs: requestRouting.sessionResetToleranceMs,
+                                ranking: requestRouting.accountRanking,
+                                preferPrimary: requestRouting.preferPrimary,
+                                sessionAffinityEnabled: requestRouting.sessionAffinity,
+                                sessionAffinityIdleTtlMs: requestRouting.sessionAffinityIdleTtlMs,
+                                spillInflight: requestRouting.spillInflight,
                                 buildLoggedClaudeError,
                                 logProxyBody,
                                 logFinalRequest,
@@ -8822,8 +9098,8 @@ export const __testHooks = {
     scheduleAdaptiveQuotaRefreshes,
     scheduleHandoffQuotaRefresh,
     getQuotaRefreshState: (key) => accountQuotaRefreshCoordinator.getState(key),
-    buildQuotaRoutingDecision: (accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), requestedModel) => {
-        const order = orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, requestedModel);
+    buildQuotaRoutingDecision: (accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), options) => {
+        const order = orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs, options);
         return buildRoutingDecision({
             accounts,
             orderedAccounts: order.orderedAccounts,
@@ -8836,6 +9112,7 @@ export const __testHooks = {
             sessionSoftLimit,
             sessionResetToleranceMs,
             rotationOffset: 0,
+            policySelectionReason: order.reason,
         });
     },
     buildRoutingDecision,
@@ -8862,10 +9139,28 @@ export const __testHooks = {
         accountAdmissionStates.clear();
         accountQuotaRefreshCoordinator.clear();
         providerTransportCoordinator.clear();
+        loggedRoutingPolicyErrors.clear();
+        forceSpillThrowForTests = false;
+        forceAffinityLookupThrowForTests = false;
+        forceBindRecheckThrowForTests = false;
         primaryAccountIndex = 0;
         lastKnownAccountCount = 0;
     },
     polyfillOAuthBody: (bodyStr, isClaudeClientRequest) => polyfillOAuthBody(bodyStr, "test-account-token", null, isClaudeClientRequest),
+    // Pins the sessionId path loadClaudeProxyAccounts resolves ahead of
+    // account selection and feeds into selectClaudeProxyAccountOrder for
+    // session affinity.
+    extractSnapshotBodySessionIdForTests: (body) => extractSnapshotBody(body)?.sessionId,
+    selectClaudeProxyAccountOrderForTests: selectClaudeProxyAccountOrder,
+    setForceSpillThrowForTests: (value) => {
+        forceSpillThrowForTests = value;
+    },
+    setForceAffinityLookupThrowForTests: (value) => {
+        forceAffinityLookupThrowForTests = value;
+    },
+    setForceBindRecheckThrowForTests: (value) => {
+        forceBindRecheckThrowForTests = value;
+    },
     isAntiAbuseConstruction429,
     fetchAnthropicAccountResponse,
     finalizeAnthropicTerminalFetchError,

package/dist/types/proxy.d.ts

@@ -534,6 +534,9 @@ export type ProxyAccountRoutingDecision = {
     rotationOffset: number;
     initialAccount: string;
     candidates: ProxyAccountRoutingCandidate[];
+    policy?: ProxyRoutingPolicySnapshot;
+    affinity?: ProxyAccountRoutingAffinityEvidence;
+    spill?: ProxyAccountRoutingSpillEvidence;
 };
 export type ProxyAccountSortMetrics = {
     usable: boolean;
@@ -578,6 +581,36 @@ export type ProxyAccountSortMetrics = {
     scopedUsedForSort: number;
     scopedSaturated: boolean;
 };
+export type ProxyAccountRankingPolicy = "expiry-first" | "headroom-first";
+export type ProxyAccountRoutingAffinitySkipReason = "unusable" | "session_saturated" | "expired" | "no_session" | "disabled";
+/** The five routing.* values in effect for one request, as reported on the decision. */
+export type ProxyRoutingPolicySnapshot = {
+    ranking: ProxyAccountRankingPolicy;
+    preferPrimary: boolean;
+    sessionAffinity: boolean;
+    sessionAffinityIdleTtlMs: number;
+    spillInflight: number;
+};
+export type ProxyAccountRoutingAffinityEvidence = {
+    sessionBound: boolean;
+    boundAccount: string | null;
+    applied: boolean;
+    skippedReason: ProxyAccountRoutingAffinitySkipReason | null;
+};
+export type ProxyAccountRoutingSpillEvidence = {
+    from: string;
+    to: string;
+    inflight: number;
+};
+/** Why the precedence step skipped a bound account it could see. */
+export type ProxyAffinityPrecedenceSkipReason = Extract<ProxyAccountRoutingAffinitySkipReason, "unusable" | "session_saturated">;
+/** The reasons a precedence step (affinity, then prefer-primary) places rank 0. */
+export type ProxyAccountPrecedenceReason = Extract<ProxyAccountRoutingReason, "session_affinity" | "preferred_primary">;
+/**
+ * A spill decision in account keys; the route reports it with account labels
+ * as ProxyAccountRoutingSpillEvidence.
+ */
+export type ProxyAccountSpillMove = ProxyAccountRoutingSpillEvidence;
 export type RequestLogEntry = {
     /** Whether model identifies observed serving output rather than a routing target. */
     servingModelStatus?: "observed" | "unavailable";
@@ -1075,6 +1108,7 @@ export type LoadedClaudeAccountContext = {
     url: string;
     clientHeaders: Record<string, string | undefined>;
     isClaudeClientRequest: boolean;
+    sessionId?: string;
 };
 export type AnthropicSuccessResult = {
     retryNextAccount: true;
@@ -1086,6 +1120,15 @@ export type AnthropicSuccessResult = {
 } | {
     response: Response | unknown;
     holdsAccountAdmission?: boolean;
+    /**
+     * True only when an Anthropic account genuinely produced this response.
+     * False for a same-shaped terminal error synthesized locally (e.g. no
+     * upstream body, or the stream failing before its first chunk) — these
+     * reuse the `{ response }` shape because the client still gets a
+     * response, but no account served anything, so session affinity must
+     * not bind on them.
+     */
+    served: boolean;
 };
 /** A release handle for one in-flight request admitted to an OAuth account. */
 export type AccountAdmissionLease = {
@@ -3119,6 +3162,11 @@ export type ProxyRequestRoutingSnapshot = {
     /** Operator policy on spending paid extra usage once a subscription window is
      *  spent. Only "never" can override the provider's own signal. */
     useOverage: ProxyOveragePolicy;
+    accountRanking: ProxyAccountRankingPolicy;
+    preferPrimary: boolean;
+    sessionAffinity: boolean;
+    sessionAffinityIdleTtlMs: number;
+    spillInflight: number;
 };
 /** Operator policy for paid extra usage. */
 export type ProxyOveragePolicy = "auto" | "always" | "never";