@juspay/neurolink 10.6.5 → 10.7.1

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -433,29 +433,101 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
     const sessionReset = resetEpochToMs(q?.sessionResetAt, now);
     const sessionTicking = sessionReset !== undefined;
     const weeklyTicking = weeklyReset !== undefined;
-    const sessionUsed = sessionTicking ? (q?.sessionUsed ?? 0) : 0;
-    const weeklyUsed = weeklyTicking ? (q?.weeklyUsed ?? -1) : q ? 0 : -1;
-    const sessionStatus = sessionTicking
-        ? (q?.sessionStatus ?? "unknown")
-        : "allowed";
-    const weeklyStatus = weeklyTicking
-        ? (q?.weeklyStatus ?? "unknown")
-        : "allowed";
+    const sessionUsed = q ? (sessionTicking ? (q.sessionUsed ?? 0) : 0) : null;
+    const weeklyUsed = q ? (weeklyTicking ? (q.weeklyUsed ?? null) : 0) : null;
+    const sessionStatus = q
+        ? sessionTicking
+            ? (q.sessionStatus ?? "unknown")
+            : "allowed"
+        : null;
+    const weeklyStatus = q
+        ? weeklyTicking
+            ? (q.weeklyStatus ?? "unknown")
+            : "allowed"
+        : null;
     const saturated = sessionStatus === "throttled" ||
-        (sessionTicking && sessionUsed >= sessionSoftLimit);
+        (sessionTicking && (sessionUsed ?? 0) >= sessionSoftLimit);
+    const quotaLastUpdated = q && Number.isFinite(q.lastUpdated) ? q.lastUpdated : null;
     return {
         usable: !coolingActive &&
             weeklyStatus !== "rejected" &&
             sessionStatus !== "rejected",
         saturated,
         hasQuota: !!q,
+        quotaLastUpdated,
+        quotaAgeMs: quotaLastUpdated === null ? null : Math.max(0, now - quotaLastUpdated),
+        coolingActive,
+        coolingReason: st?.coolingReason ?? null,
         coolingUntil: st?.coolingUntil ?? 0,
+        unifiedStatus: q?.unifiedStatus ?? null,
+        overageStatus: q?.overageStatus ?? null,
+        sessionStatus,
+        sessionUsed,
         sessionResetBucket: sessionTicking
             ? Math.floor(sessionReset / sessionResetToleranceMs)
             : Number.POSITIVE_INFINITY,
         sessionReset: sessionReset ?? Number.POSITIVE_INFINITY,
+        weeklyStatus,
         weeklyReset: weeklyReset ?? Number.POSITIVE_INFINITY,
         weeklyUsed,
+        weeklyUsedForSort: weeklyUsed ?? -1,
+    };
+}
+function compareAccountRoutingFactors(a, b, metricsByKey, primaryKey) {
+    const ma = metricsByKey.get(a.key);
+    const mb = metricsByKey.get(b.key);
+    if (!ma || !mb) {
+        return [0, "insertion_order"];
+    }
+    if (ma.usable !== mb.usable) {
+        return [ma.usable ? -1 : 1, "availability"];
+    }
+    if (!ma.usable && !mb.usable) {
+        const au = ma.coolingUntil || Number.POSITIVE_INFINITY;
+        const bu = mb.coolingUntil || Number.POSITIVE_INFINITY;
+        return [
+            au === bu ? 0 : au - bu,
+            au === bu ? "insertion_order" : "cooldown_recovery",
+        ];
+    }
+    if (ma.hasQuota !== mb.hasQuota) {
+        return [ma.hasQuota ? 1 : -1, "quota_probe"];
+    }
+    if (ma.saturated !== mb.saturated) {
+        return [ma.saturated ? 1 : -1, "session_headroom"];
+    }
+    if (ma.saturated && mb.saturated) {
+        if (ma.sessionResetBucket !== mb.sessionResetBucket) {
+            return [ma.sessionResetBucket - mb.sessionResetBucket, "session_reset"];
+        }
+        if (ma.weeklyReset !== mb.weeklyReset) {
+            return [ma.weeklyReset - mb.weeklyReset, "weekly_reset"];
+        }
+    }
+    else {
+        if (ma.weeklyReset !== mb.weeklyReset) {
+            return [ma.weeklyReset - mb.weeklyReset, "weekly_reset"];
+        }
+        if (ma.sessionResetBucket !== mb.sessionResetBucket) {
+            return [ma.sessionResetBucket - mb.sessionResetBucket, "session_reset"];
+        }
+    }
+    if (ma.weeklyUsedForSort !== mb.weeklyUsedForSort) {
+        return [mb.weeklyUsedForSort - ma.weeklyUsedForSort, "weekly_utilization"];
+    }
+    if (primaryKey && (a.key === primaryKey) !== (b.key === primaryKey)) {
+        return [a.key === primaryKey ? -1 : 1, "configured_primary"];
+    }
+    return [0, "insertion_order"];
+}
+function orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs) {
+    const metricsByKey = new Map(accounts.map((account) => [
+        account.key,
+        accountSortMetrics(account.key, now, sessionSoftLimit, sessionResetToleranceMs),
+    ]));
+    return {
+        orderedAccounts: [...accounts].sort((a, b) => compareAccountRoutingFactors(a, b, metricsByKey, primaryKey)[0]),
+        metricsByKey,
     };
 }
 /**
@@ -484,48 +556,153 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
  * last resort.
  */
 function orderAccountsByQuota(accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs()) {
-    const metrics = (key) => accountSortMetrics(key, now, sessionSoftLimit, sessionResetToleranceMs);
-    return [...accounts].sort((a, b) => {
-        const ma = metrics(a.key);
-        const mb = metrics(b.key);
-        if (ma.usable !== mb.usable) {
-            return ma.usable ? -1 : 1;
-        }
-        if (!ma.usable && !mb.usable) {
-            const au = ma.coolingUntil || Number.POSITIVE_INFINITY;
-            const bu = mb.coolingUntil || Number.POSITIVE_INFINITY;
-            return au - bu;
-        }
-        if (ma.hasQuota !== mb.hasQuota) {
-            return ma.hasQuota ? 1 : -1;
+    return orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs).orderedAccounts;
+}
+function buildRoutingDecision(args) {
+    const { accounts, orderedAccounts, metricsByKey, evaluatedAt, strategy, primaryKey, quotaRoutingEnabled, quotaOrdered, sessionSoftLimit, sessionResetToleranceMs, rotationOffset, } = args;
+    const sourceIndexes = new Map(accounts.map((account, index) => [account.key, index]));
+    const configuredPrimaryMatched = !!primaryKey && accounts.some((account) => account.key === primaryKey);
+    const candidates = [];
+    for (const account of orderedAccounts) {
+        const metrics = metricsByKey.get(account.key);
+        if (!metrics) {
+            logger.warn(`[proxy] routing evidence omitted because metrics are missing for account=${account.label}`);
+            return undefined;
         }
-        if (ma.saturated !== mb.saturated) {
-            return ma.saturated ? 1 : -1;
+        candidates.push({
+            account: account.label,
+            accountType: account.type,
+            sourceIndex: sourceIndexes.get(account.key) ?? candidates.length,
+            rank: candidates.length,
+            configuredPrimary: !!primaryKey && account.key === primaryKey,
+            usable: metrics.usable,
+            saturated: metrics.saturated,
+            quotaObserved: metrics.hasQuota,
+            quotaLastUpdated: metrics.quotaLastUpdated,
+            quotaAgeMs: metrics.quotaAgeMs,
+            coolingActive: metrics.coolingActive,
+            coolingReason: metrics.coolingReason,
+            coolingUntil: metrics.coolingUntil > 0 && Number.isFinite(metrics.coolingUntil)
+                ? metrics.coolingUntil
+                : null,
+            unifiedStatus: metrics.unifiedStatus,
+            overageStatus: metrics.overageStatus,
+            sessionStatus: metrics.sessionStatus,
+            sessionUsed: metrics.sessionUsed,
+            sessionResetAt: Number.isFinite(metrics.sessionReset)
+                ? metrics.sessionReset
+                : null,
+            sessionResetBucket: Number.isFinite(metrics.sessionResetBucket)
+                ? metrics.sessionResetBucket
+                : null,
+            weeklyStatus: metrics.weeklyStatus,
+            weeklyUsed: metrics.weeklyUsed,
+            weeklyResetAt: Number.isFinite(metrics.weeklyReset)
+                ? metrics.weeklyReset
+                : null,
+        });
+    }
+    const initialAccount = orderedAccounts[0];
+    let mode;
+    let selectionReason;
+    if (orderedAccounts.length === 1) {
+        mode = "single_account";
+        selectionReason = "single_account";
+    }
+    else if (quotaOrdered) {
+        mode = "quota";
+        selectionReason = compareAccountRoutingFactors(orderedAccounts[0], orderedAccounts[1], metricsByKey, primaryKey)[1];
+    }
+    else if (strategy === "round-robin") {
+        mode = "round_robin";
+        selectionReason = "round_robin";
+    }
+    else {
+        mode = "primary";
+        selectionReason =
+            configuredPrimaryMatched && initialAccount?.key === primaryKey
+                ? "configured_primary"
+                : "insertion_order";
+    }
+    return {
+        schemaVersion: 1,
+        evaluatedAt: new Date(evaluatedAt).toISOString(),
+        strategy,
+        mode,
+        selectionReason,
+        quotaRoutingEnabled,
+        quotaInputsUsed: quotaOrdered,
+        sessionSoftLimit,
+        sessionResetToleranceMs,
+        configuredPrimaryAccount: primaryKey ?? null,
+        configuredPrimaryMatched,
+        rotationOffset,
+        initialAccount: initialAccount?.label ?? "",
+        candidates,
+    };
+}
+function selectClaudeProxyAccountOrder(args) {
+    const { enabledAccounts, accountStrategy, primaryAccountKey, quotaRoutingEnabled, sessionSoftLimit, sessionResetToleranceMs, setRoutingDecision, } = args;
+    let orderedAccounts = [...enabledAccounts];
+    const evaluatedAt = Date.now();
+    let metricsByKey;
+    let rotationOffset = 0;
+    const quotaOrdered = accountStrategy === "fill-first" &&
+        orderedAccounts.length > 1 &&
+        quotaRoutingEnabled;
+    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);
+        orderedAccounts = quotaOrder.orderedAccounts;
+        metricsByKey = quotaOrder.metricsByKey;
+        if (logger.shouldLog("debug")) {
+            logger.debug(`[proxy] quota-ordered fill sequence: ${orderedAccounts
+                .map((account) => account.label)
+                .join(" → ")}`);
         }
-        if (ma.saturated && mb.saturated) {
-            if (ma.sessionResetBucket !== mb.sessionResetBucket) {
-                return ma.sessionResetBucket - mb.sessionResetBucket;
-            }
-            if (ma.weeklyReset !== mb.weeklyReset) {
-                return ma.weeklyReset - mb.weeklyReset;
-            }
+    }
+    else {
+        if (accountStrategy === "round-robin" &&
+            orderedAccounts.length !== lastKnownAccountCount) {
+            primaryAccountIndex = resolveHomeIndex(orderedAccounts, primaryAccountKey);
+            lastKnownAccountCount = orderedAccounts.length;
         }
-        else {
-            if (ma.weeklyReset !== mb.weeklyReset) {
-                return ma.weeklyReset - mb.weeklyReset;
+        if (orderedAccounts.length > 1) {
+            rotationOffset = primaryAccountIndex % orderedAccounts.length;
+            if (accountStrategy === "round-robin") {
+                primaryAccountIndex =
+                    (primaryAccountIndex + 1) % orderedAccounts.length;
             }
-            if (ma.sessionResetBucket !== mb.sessionResetBucket) {
-                return ma.sessionResetBucket - mb.sessionResetBucket;
+            if (rotationOffset > 0) {
+                const head = orderedAccounts.splice(0, rotationOffset);
+                orderedAccounts.push(...head);
             }
         }
-        if (ma.weeklyUsed !== mb.weeklyUsed) {
-            return mb.weeklyUsed - ma.weeklyUsed;
-        }
-        if (primaryKey && (a.key === primaryKey) !== (b.key === primaryKey)) {
-            return a.key === primaryKey ? -1 : 1;
-        }
-        return 0;
+        metricsByKey = new Map(enabledAccounts.map((account) => [
+            account.key,
+            accountSortMetrics(account.key, evaluatedAt, sessionSoftLimit, sessionResetToleranceMs),
+        ]));
+    }
+    const routingDecision = buildRoutingDecision({
+        accounts: enabledAccounts,
+        orderedAccounts,
+        metricsByKey,
+        evaluatedAt,
+        strategy: accountStrategy,
+        primaryKey: primaryAccountKey,
+        quotaRoutingEnabled,
+        quotaOrdered,
+        sessionSoftLimit,
+        sessionResetToleranceMs,
+        rotationOffset,
     });
+    if (routingDecision) {
+        setRoutingDecision(routingDecision);
+    }
+    return orderedAccounts;
 }
 // ---------------------------------------------------------------------------
 // OAuth polyfill helpers (extracted to reduce block nesting)
@@ -1447,7 +1624,7 @@ async function handleClaudePassthroughJsonResponse(args) {
     return responseJson;
 }
 async function loadClaudeProxyAccounts(args) {
-    const { ctx, body, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, } = args;
+    const { ctx, body, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, setRoutingDecision, } = args;
     const fs = await import("fs");
     const os = await import("os");
     const accounts = [];
@@ -1616,45 +1793,15 @@ async function loadClaudeProxyAccounts(args) {
         tracer?.end(401, Date.now() - requestStartTime);
         return { response: buildLoggedClaudeError(401, reauthMsg) };
     }
-    let orderedAccounts = [...enabledAccounts];
-    const quotaOrdered = accountStrategy === "fill-first" &&
-        orderedAccounts.length > 1 &&
-        quotaRoutingEnabled;
-    if (!quotaOrdered && accountStrategy === "fill-first") {
-        // Apply the request-scoped home before deriving this request's order. A
-        // hot-reloaded primary change must not lag by one request. Round-robin
-        // deliberately skips this reset so its rotating index remains strict.
-        maybeResetPrimaryToHome(enabledAccounts, primaryAccountKey);
-    }
-    if (quotaOrdered) {
-        // Fill-first with a smart fill order: spend the account whose weekly window
-        // expires soonest while temporarily demoting sessions without headroom.
-        // Supersedes the static home/primary index.
-        orderedAccounts = orderAccountsByQuota(enabledAccounts, Date.now(), primaryAccountKey, sessionSoftLimit, sessionResetToleranceMs);
-        if (logger.shouldLog("debug")) {
-            logger.debug(`[proxy] quota-ordered fill sequence: ${orderedAccounts
-                .map((a) => a.label)
-                .join(" → ")}`);
-        }
-    }
-    else {
-        if (accountStrategy === "round-robin" &&
-            orderedAccounts.length !== lastKnownAccountCount) {
-            primaryAccountIndex = resolveHomeIndex(orderedAccounts, primaryAccountKey);
-            lastKnownAccountCount = orderedAccounts.length;
-        }
-        if (orderedAccounts.length > 1) {
-            const idx = primaryAccountIndex % orderedAccounts.length;
-            if (accountStrategy === "round-robin") {
-                primaryAccountIndex =
-                    (primaryAccountIndex + 1) % orderedAccounts.length;
-            }
-            if (idx > 0) {
-                const head = orderedAccounts.splice(0, idx);
-                orderedAccounts.push(...head);
-            }
-        }
-    }
+    const orderedAccounts = selectClaudeProxyAccountOrder({
+        enabledAccounts,
+        accountStrategy,
+        primaryAccountKey,
+        quotaRoutingEnabled,
+        sessionSoftLimit,
+        sessionResetToleranceMs,
+        setRoutingDecision,
+    });
     const normalizedAnthropicBody = normalizeClaudeRequestForAnthropic(body);
     const bodyStr = JSON.stringify(normalizedAnthropicBody);
     const requestStart = Date.now();
@@ -3345,6 +3492,14 @@ function createClaudeRequestRuntimeContext(args) {
                 : {}),
         });
     };
+    let routingDecision;
+    const setRoutingDecision = (decision) => {
+        if (routingDecision) {
+            logger.debug(`[claude-proxy] ignored duplicate routing decision for request ${ctx.requestId}`);
+            return;
+        }
+        routingDecision = decision;
+    };
     let finalRequestLogged = false;
     const logFinalRequest = (status, accountLabel, accountType, errorType, errorMessage, extra) => {
         if (finalRequestLogged) {
@@ -3404,6 +3559,7 @@ function createClaudeRequestRuntimeContext(args) {
             ...(traceCtx
                 ? { traceId: traceCtx.traceId, spanId: traceCtx.spanId }
                 : {}),
+            ...(routingDecision ? { routingDecision } : {}),
         });
     };
     const buildLoggedClaudeError = (status, message, errorType, extra) => {
@@ -3435,6 +3591,7 @@ function createClaudeRequestRuntimeContext(args) {
         logProxyBody,
         logFinalRequest,
         buildLoggedClaudeError,
+        setRoutingDecision,
     };
 }
 function createAnthropicAttemptLogger(args) {
@@ -3803,7 +3960,7 @@ function shouldAttemptClaudeFallback(loopState) {
     return loopState.invalidRequestFailure === null;
 }
 async function handleAnthropicRoutedClaudeRequest(args) {
-    const { ctx, body, modelRouter, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
+    const { ctx, body, modelRouter, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, logProxyBody, logFinalRequest, setRoutingDecision, } = args;
     const parsedRequest = parseClaudeRequest(body);
     const loadedAccounts = await loadClaudeProxyAccounts({
         ctx,
@@ -3817,6 +3974,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         sessionSoftLimit,
         sessionResetToleranceMs,
         buildLoggedClaudeError,
+        setRoutingDecision,
     });
     if ("response" in loadedAccounts) {
         return loadedAccounts.response;
@@ -4293,7 +4451,7 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                     };
                     const clientRequestBody = JSON.stringify(body);
                     // 3. Create request runtime context (tracer, loggers, error builder)
-                    const { tracer, requestStartTime, logProxyBody, logFinalRequest, buildLoggedClaudeError, } = createClaudeRequestRuntimeContext({
+                    const { tracer, requestStartTime, logProxyBody, logFinalRequest, buildLoggedClaudeError, setRoutingDecision, } = createClaudeRequestRuntimeContext({
                         ctx,
                         body,
                         clientRequestBody,
@@ -4333,6 +4491,7 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                                 buildLoggedClaudeError,
                                 logProxyBody,
                                 logFinalRequest,
+                                setRoutingDecision,
                             });
                         }
                         else {
@@ -4726,6 +4885,23 @@ export const __testHooks = {
     getStreamFailureDetails,
     trackUpstreamReadableStream,
     orderAccountsByQuota,
+    buildQuotaRoutingDecision: (accounts, now, primaryKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs()) => {
+        const order = orderAccountsByQuotaWithMetrics(accounts, now, primaryKey, sessionSoftLimit, sessionResetToleranceMs);
+        return buildRoutingDecision({
+            accounts,
+            orderedAccounts: order.orderedAccounts,
+            metricsByKey: order.metricsByKey,
+            evaluatedAt: now,
+            strategy: "fill-first",
+            primaryKey,
+            quotaRoutingEnabled: true,
+            quotaOrdered: accounts.length > 1,
+            sessionSoftLimit,
+            sessionResetToleranceMs,
+            rotationOffset: 0,
+        });
+    },
+    buildRoutingDecision,
     resetEpochToMs,
     seedRuntimeQuotasFromDisk,
     reconcileEligibleAccountRuntimeState,

package/dist/lib/types/proxy.d.ts

@@ -18,6 +18,7 @@ import type { Hono } from "hono";
 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 { RouteDeprecation } from "./server.js";
 /**
@@ -423,6 +424,70 @@ export type LoadProxyConfigOptions = {
     /** Custom environment object (defaults to process.env) */
     env?: Record<string, string | undefined>;
 };
+export type ProxyAccountRoutingStrategy = (typeof PROXY_ACCOUNT_ROUTING_STRATEGIES)[number];
+export type ProxyAccountRoutingMode = (typeof PROXY_ACCOUNT_ROUTING_MODES)[number];
+export type ProxyAccountRoutingReason = (typeof PROXY_ACCOUNT_ROUTING_REASONS)[number];
+export type ProxyAccountType = (typeof PROXY_ACCOUNT_TYPES)[number];
+export type ProxyAccountRoutingCandidate = {
+    account: string;
+    accountType: ProxyAccountType;
+    sourceIndex: number;
+    rank: number;
+    configuredPrimary: boolean;
+    usable: boolean;
+    saturated: boolean;
+    quotaObserved: boolean;
+    quotaLastUpdated: number | null;
+    quotaAgeMs: number | null;
+    coolingActive: boolean;
+    coolingReason: AccountCoolingReason | null;
+    coolingUntil: number | null;
+    unifiedStatus: string | null;
+    overageStatus: string | null;
+    sessionStatus: string | null;
+    sessionUsed: number | null;
+    sessionResetAt: number | null;
+    sessionResetBucket: number | null;
+    weeklyStatus: string | null;
+    weeklyUsed: number | null;
+    weeklyResetAt: number | null;
+};
+export type ProxyAccountRoutingDecision = {
+    schemaVersion: 1;
+    evaluatedAt: string;
+    strategy: ProxyAccountRoutingStrategy;
+    mode: ProxyAccountRoutingMode;
+    selectionReason: ProxyAccountRoutingReason;
+    quotaRoutingEnabled: boolean;
+    quotaInputsUsed: boolean;
+    sessionSoftLimit: number;
+    sessionResetToleranceMs: number;
+    configuredPrimaryAccount: string | null;
+    configuredPrimaryMatched: boolean;
+    rotationOffset: number;
+    initialAccount: string;
+    candidates: ProxyAccountRoutingCandidate[];
+};
+export type ProxyAccountSortMetrics = {
+    usable: boolean;
+    saturated: boolean;
+    hasQuota: boolean;
+    quotaLastUpdated: number | null;
+    quotaAgeMs: number | null;
+    coolingActive: boolean;
+    coolingReason: AccountCoolingReason | null;
+    coolingUntil: number;
+    unifiedStatus: string | null;
+    overageStatus: string | null;
+    sessionStatus: string | null;
+    sessionUsed: number | null;
+    sessionResetBucket: number;
+    sessionReset: number;
+    weeklyStatus: string | null;
+    weeklyReset: number;
+    weeklyUsed: number | null;
+    weeklyUsedForSort: number;
+};
 export type RequestLogEntry = {
     timestamp: string;
     requestId: string;
@@ -447,6 +512,8 @@ export type RequestLogEntry = {
     traceId?: string;
     /** OTel span ID for correlation with distributed traces */
     spanId?: string;
+    /** Exact secret-free inputs and result of initial account selection. */
+    routingDecision?: ProxyAccountRoutingDecision;
 };
 export type RequestAttemptLogEntry = {
     timestamp: string;
@@ -515,6 +582,9 @@ export type ClaudeRequestRuntimeContext = {
     logFinalRequest: ClaudeFinalRequestLogger;
     buildLoggedClaudeError: ClaudeLoggedErrorBuilder;
 };
+export type RoutedClaudeRequestRuntimeContext = ClaudeRequestRuntimeContext & {
+    setRoutingDecision: (decision: ProxyAccountRoutingDecision) => void;
+};
 export type AnthropicAttemptLogger = (status: number, errorType?: string, errorMessage?: string, extra?: {
     inputTokens?: number;
     outputTokens?: number;
@@ -838,7 +908,7 @@ export type AccountQuota = {
  *  - "unified"   : top-level unified limit rejected — cool for retry-after.
  *  - "transient" : short per-minute/burst 429 — cool for retry-after only.
  *  - "auth"      : transient refresh failure with bounded backoff. */
-export type AccountCoolingReason = "weekly" | "session" | "unified" | "transient" | "auth";
+export type AccountCoolingReason = (typeof ACCOUNT_COOLING_REASONS)[number];
 /** Restart-safe cooldown snapshot for one account. */
 export type PersistedAccountCooldown = {
     coolingUntil: number;
@@ -872,7 +942,7 @@ export type ProxyPassthroughAccount = {
     token: string;
     refreshToken?: string;
     expiresAt?: number;
-    type: "oauth" | "api_key";
+    type: ProxyAccountType;
     persistTarget?: TokenPersistTarget;
 };
 /** Dependencies for creating Claude proxy routes. */
@@ -1190,6 +1260,7 @@ export type ProxyAnalysisReport = {
         attempts: boolean;
         attemptLatency: boolean;
         cacheUsage: boolean;
+        routingDecisions: boolean;
     };
     dataQuality: {
         linesRead: number;
@@ -1211,6 +1282,11 @@ export type ProxyAnalysisReport = {
             writeFailures: number;
             truncatedCaptures: number;
         };
+        routingDecisions: {
+            valid: number;
+            invalid: number;
+            absent: number;
+        };
     };
     lifecycle: {
         accepted: number;
@@ -1259,6 +1335,17 @@ export type ProxyAnalysisReport = {
         inputTokens: number;
         requestHitRate: number | null;
     };
+    routing: {
+        modes: Record<string, number>;
+        selectionReasons: Record<string, number>;
+        initialAccounts: Record<string, number>;
+        finalAccountChanges: number;
+        finalOutsideCandidateSet: number;
+        /** Number of routing decisions aggregated before sampling records. */
+        totalRecords: number;
+        /** Most recent bounded sample retained for offline inspection. */
+        records: ProxyAnalysisRoutingRecord[];
+    };
     accounts: ProxyAnalysisAccount[];
 };
 /** Inputs for the offline proxy JSONL analyzer. */
@@ -1276,6 +1363,7 @@ export type ProxyAnalysisAttemptRecord = {
 };
 /** Final request fields retained while joining offline proxy log records. */
 export type ProxyAnalysisFinalRequestRecord = {
+    timestamp: string;
     status: number;
     durationMs: number | null;
     account: string;
@@ -1285,6 +1373,16 @@ export type ProxyAnalysisFinalRequestRecord = {
     cacheCreationTokens: number | null;
     errorType: string | null;
     errorCode: string | null;
+    routingDecision: ProxyAccountRoutingDecision | null;
+};
+/** Validated account-routing evidence joined to a final request log. */
+export type ProxyAnalysisRoutingRecord = {
+    requestId: string;
+    timestamp: string;
+    responseStatus: number;
+    finalAccount: string;
+    finalAccountType: string;
+    decision: ProxyAccountRoutingDecision;
 };
 /** Request metadata retained by the HTTP adapter for terminal error logging. */
 export type RuntimeRequestMetadata = {

package/dist/proxy/accountCooldown.js

@@ -2,15 +2,10 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { AsyncMutex } from "../utils/asyncMutex.js";
+import { ACCOUNT_COOLING_REASONS } from "./routingEvidence.js";
 import { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
 const COOLDOWN_FILE = "account-cooldowns.json";
-const VALID_REASONS = new Set([
-    "weekly",
-    "session",
-    "unified",
-    "transient",
-    "auth",
-]);
+const VALID_REASONS = new Set(ACCOUNT_COOLING_REASONS);
 let customCooldownFilePath = null;
 let cacheLoaded = false;
 let cacheLoadPromise = null;