@juspay/neurolink 10.6.5 → 10.7.1

package/dist/cli/commands/proxyAnalyze.js

@@ -42,6 +42,17 @@ function printAnalysis(report) {
         logger.always(chalk.yellow("    Rate limits: unavailable"));
     }
     logger.always("");
+    logger.always(chalk.bold("  Account Routing"));
+    if (report.coverage.routingDecisions) {
+        logger.always(`    Decisions: ${report.routing.totalRecords} (${report.routing.records.length} retained), modes: ${JSON.stringify(report.routing.modes)}`);
+        logger.always(`    Selection reasons: ${JSON.stringify(report.routing.selectionReasons)}`);
+        logger.always(`    Initial accounts: ${JSON.stringify(report.routing.initialAccounts)}`);
+        logger.always(`    Final account changed after retry: ${report.routing.finalAccountChanges}, outside candidate set: ${report.routing.finalOutsideCandidateSet}`);
+    }
+    else {
+        logger.always(chalk.yellow("    Routing decisions: unavailable (legacy or no logs)"));
+    }
+    logger.always("");
     logger.always(chalk.bold("  Latency (ms)"));
     const latencyHeader = `${"METRIC".padEnd(22)} ${"COUNT".padStart(7)} ${"P50".padStart(9)} ${"P95".padStart(9)} ${"P99".padStart(9)} ${"MAX".padStart(9)}`;
     logger.always(`    ${chalk.gray(latencyHeader)}`);
@@ -68,6 +79,7 @@ function printAnalysis(report) {
     logger.always("");
     logger.always(chalk.bold("  Data Quality"));
     logger.always(`    ${report.dataQuality.linesRead} lines scanned, ${report.dataQuality.malformedLines} malformed, ${report.dataQuality.unsupportedLifecycleLines} unsupported lifecycle, ${report.dataQuality.lifecycleSequenceGaps} sequence gaps, ${report.dataQuality.lifecycleSequenceDuplicates} duplicates`);
+    logger.always(`    Routing decisions: ${report.dataQuality.routingDecisions.valid} valid, ${report.dataQuality.routingDecisions.invalid} invalid, ${report.dataQuality.routingDecisions.absent} absent`);
     for (const [stream, range] of Object.entries(report.dataQuality.streams)) {
         if (range.observedFrom) {
             logger.always(`    ${stream}: ${range.observedFrom} to ${range.observedTo}${range.startsAtOrBeforeRequestedWindow ? "" : chalk.yellow(" (starts after requested window)")}`);

package/dist/lib/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;

package/dist/lib/proxy/proxyAnalysis.js

@@ -3,6 +3,7 @@ import { lstat, readdir, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { ACCOUNT_COOLING_REASONS, PROXY_ACCOUNT_TYPES, PROXY_ACCOUNT_ROUTING_MODES, PROXY_ACCOUNT_ROUTING_REASONS, PROXY_ACCOUNT_ROUTING_STRATEGIES, } from "./routingEvidence.js";
 const LIFECYCLE_FILE_PATTERN = /^proxy-lifecycle-\d{4}-\d{2}-\d{2}\.jsonl$/;
 const REQUEST_FILE_PATTERN = /^proxy-\d{4}-\d{2}-\d{2}\.jsonl$/;
 const ATTEMPT_FILE_PATTERN = /^proxy-attempts-\d{4}-\d{2}-\d{2}\.jsonl$/;
@@ -14,6 +15,13 @@ const LIFECYCLE_EVENTS = new Set([
     "response_first_chunk",
     "request_terminal",
 ]);
+const ROUTING_STRATEGIES = new Set(PROXY_ACCOUNT_ROUTING_STRATEGIES);
+const ROUTING_MODES = new Set(PROXY_ACCOUNT_ROUTING_MODES);
+const ROUTING_REASONS = new Set(PROXY_ACCOUNT_ROUTING_REASONS);
+const ROUTING_ACCOUNT_TYPES = new Set(PROXY_ACCOUNT_TYPES);
+const COOLING_REASONS = new Set(ACCOUNT_COOLING_REASONS);
+const MAX_RETAINED_ROUTING_RECORDS = 200;
+const MAX_ROUTING_RECORDS_BEFORE_COMPACTION = MAX_RETAINED_ROUTING_RECORDS * 2;
 function isContainedPath(root, candidate) {
     const candidateRelative = relative(root, candidate);
     return (candidateRelative.length > 0 &&
@@ -45,6 +53,130 @@ function finiteNumber(value) {
 function stringValue(value) {
     return typeof value === "string" && value.length > 0 ? value : null;
 }
+function isNullableString(value) {
+    return value === null || (typeof value === "string" && value.length > 0);
+}
+function isNullableFiniteNumber(value) {
+    return value === null || finiteNumber(value) !== null;
+}
+function routingCandidateValue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const candidate = value;
+    const requiredBooleanFields = [
+        "configuredPrimary",
+        "usable",
+        "saturated",
+        "quotaObserved",
+        "coolingActive",
+    ];
+    const requiredNullableNumberFields = [
+        "quotaLastUpdated",
+        "quotaAgeMs",
+        "coolingUntil",
+        "sessionUsed",
+        "sessionResetAt",
+        "sessionResetBucket",
+        "weeklyUsed",
+        "weeklyResetAt",
+    ];
+    const requiredNullableStringFields = [
+        "unifiedStatus",
+        "overageStatus",
+        "sessionStatus",
+        "weeklyStatus",
+    ];
+    if (!stringValue(candidate.account) ||
+        typeof candidate.accountType !== "string" ||
+        !ROUTING_ACCOUNT_TYPES.has(candidate.accountType) ||
+        !Number.isInteger(candidate.sourceIndex) ||
+        candidate.sourceIndex < 0 ||
+        !Number.isInteger(candidate.rank) ||
+        candidate.rank < 0 ||
+        requiredBooleanFields.some((field) => typeof candidate[field] !== "boolean") ||
+        requiredNullableNumberFields.some((field) => !isNullableFiniteNumber(candidate[field])) ||
+        requiredNullableStringFields.some((field) => !isNullableString(candidate[field])) ||
+        !(candidate.coolingReason === null ||
+            (typeof candidate.coolingReason === "string" &&
+                COOLING_REASONS.has(candidate.coolingReason)))) {
+        return null;
+    }
+    return {
+        account: candidate.account,
+        accountType: candidate.accountType,
+        sourceIndex: candidate.sourceIndex,
+        rank: candidate.rank,
+        configuredPrimary: candidate.configuredPrimary,
+        usable: candidate.usable,
+        saturated: candidate.saturated,
+        quotaObserved: candidate.quotaObserved,
+        quotaLastUpdated: candidate.quotaLastUpdated,
+        quotaAgeMs: candidate.quotaAgeMs,
+        coolingActive: candidate.coolingActive,
+        coolingReason: candidate.coolingReason,
+        coolingUntil: candidate.coolingUntil,
+        unifiedStatus: candidate.unifiedStatus,
+        overageStatus: candidate.overageStatus,
+        sessionStatus: candidate.sessionStatus,
+        sessionUsed: candidate.sessionUsed,
+        sessionResetAt: candidate.sessionResetAt,
+        sessionResetBucket: candidate.sessionResetBucket,
+        weeklyStatus: candidate.weeklyStatus,
+        weeklyUsed: candidate.weeklyUsed,
+        weeklyResetAt: candidate.weeklyResetAt,
+    };
+}
+function routingDecisionValue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const decision = value;
+    const candidates = Array.isArray(decision.candidates)
+        ? decision.candidates.map(routingCandidateValue)
+        : [];
+    if (decision.schemaVersion !== 1 ||
+        !stringValue(decision.evaluatedAt) ||
+        !Number.isFinite(Date.parse(String(decision.evaluatedAt))) ||
+        typeof decision.strategy !== "string" ||
+        !ROUTING_STRATEGIES.has(decision.strategy) ||
+        typeof decision.mode !== "string" ||
+        !ROUTING_MODES.has(decision.mode) ||
+        typeof decision.selectionReason !== "string" ||
+        !ROUTING_REASONS.has(decision.selectionReason) ||
+        typeof decision.quotaRoutingEnabled !== "boolean" ||
+        typeof decision.quotaInputsUsed !== "boolean" ||
+        finiteNumber(decision.sessionSoftLimit) === null ||
+        decision.sessionSoftLimit <= 0 ||
+        decision.sessionSoftLimit > 1 ||
+        !Number.isInteger(decision.sessionResetToleranceMs) ||
+        decision.sessionResetToleranceMs <= 0 ||
+        !isNullableString(decision.configuredPrimaryAccount) ||
+        typeof decision.configuredPrimaryMatched !== "boolean" ||
+        !Number.isInteger(decision.rotationOffset) ||
+        decision.rotationOffset < 0 ||
+        !stringValue(decision.initialAccount) ||
+        candidates.length === 0 ||
+        candidates.some((candidate) => candidate === null)) {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        evaluatedAt: decision.evaluatedAt,
+        strategy: decision.strategy,
+        mode: decision.mode,
+        selectionReason: decision.selectionReason,
+        quotaRoutingEnabled: decision.quotaRoutingEnabled,
+        quotaInputsUsed: decision.quotaInputsUsed,
+        sessionSoftLimit: decision.sessionSoftLimit,
+        sessionResetToleranceMs: decision.sessionResetToleranceMs,
+        configuredPrimaryAccount: decision.configuredPrimaryAccount,
+        configuredPrimaryMatched: decision.configuredPrimaryMatched,
+        rotationOffset: decision.rotationOffset,
+        initialAccount: decision.initialAccount,
+        candidates: candidates,
+    };
+}
 function percentile(sorted, fraction) {
     if (sorted.length === 0) {
         return null;
@@ -204,6 +336,63 @@ function summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByR
         singleAttemptDelta,
     };
 }
+function summarizeRouting(finalRequests) {
+    const modes = {};
+    const selectionReasons = {};
+    const initialAccounts = {};
+    const retainedRecords = [];
+    let totalRecords = 0;
+    let finalAccountChanges = 0;
+    let finalOutsideCandidateSet = 0;
+    for (const [requestId, request] of finalRequests) {
+        const decision = request.routingDecision;
+        if (!decision) {
+            continue;
+        }
+        increment(modes, decision.mode);
+        increment(selectionReasons, decision.selectionReason);
+        increment(initialAccounts, decision.initialAccount);
+        const finalCandidate = decision.candidates.some((candidate) => candidate.account === request.account &&
+            candidate.accountType === request.accountType);
+        if (!finalCandidate) {
+            finalOutsideCandidateSet += 1;
+        }
+        else if (decision.initialAccount !== request.account) {
+            finalAccountChanges += 1;
+        }
+        totalRecords += 1;
+        retainedRecords.push({
+            record: {
+                requestId,
+                timestamp: request.timestamp,
+                responseStatus: request.status,
+                finalAccount: request.account,
+                finalAccountType: request.accountType,
+                decision,
+            },
+            timestampMs: Date.parse(request.timestamp),
+            sequence: totalRecords,
+        });
+        if (retainedRecords.length > MAX_ROUTING_RECORDS_BEFORE_COMPACTION) {
+            retainedRecords.sort((left, right) => left.timestampMs - right.timestampMs ||
+                left.sequence - right.sequence);
+            retainedRecords.splice(0, retainedRecords.length - MAX_RETAINED_ROUTING_RECORDS);
+        }
+    }
+    retainedRecords.sort((left, right) => left.timestampMs - right.timestampMs || left.sequence - right.sequence);
+    const records = retainedRecords
+        .slice(-MAX_RETAINED_ROUTING_RECORDS)
+        .map(({ record }) => record);
+    return {
+        modes,
+        selectionReasons,
+        initialAccounts,
+        finalAccountChanges,
+        finalOutsideCandidateSet,
+        totalRecords,
+        records,
+    };
+}
 async function discoverLogFiles(logsDir) {
     const entries = await readdir(logsDir, { withFileTypes: true }).catch((error) => {
         throw new Error(`Unable to read proxy logs at ${logsDir}: ${error.message}`);
@@ -400,6 +589,9 @@ export async function analyzeProxyLogs(options) {
     }
     const finalRequests = new Map();
     const terminalStreamErrors = new Set();
+    let validRoutingDecisions = 0;
+    let invalidRoutingDecisions = 0;
+    let absentRoutingDecisions = 0;
     for (const filePath of requestFiles) {
         linesRead += await readJsonLines(filePath, (record) => {
             const timestamp = observeTimestamp("requests", record);
@@ -418,7 +610,21 @@ export async function analyzeProxyLogs(options) {
             if (status === null || !stringValue(record.method)) {
                 return;
             }
+            const hasRoutingDecision = Object.prototype.hasOwnProperty.call(record, "routingDecision");
+            const routingDecision = hasRoutingDecision
+                ? routingDecisionValue(record.routingDecision)
+                : null;
+            if (routingDecision) {
+                validRoutingDecisions += 1;
+            }
+            else if (hasRoutingDecision) {
+                invalidRoutingDecisions += 1;
+            }
+            else {
+                absentRoutingDecisions += 1;
+            }
             finalRequests.set(requestId, {
+                timestamp: new Date(timestamp).toISOString(),
                 status,
                 durationMs: finiteNumber(record.responseTimeMs),
                 account: stringValue(record.account) ?? "unknown",
@@ -428,6 +634,7 @@ export async function analyzeProxyLogs(options) {
                 cacheCreationTokens: finiteNumber(record.cacheCreationTokens),
                 errorType: stringValue(record.errorType),
                 errorCode: stringValue(record.errorCode),
+                routingDecision,
             });
         }, () => {
             malformedLines += 1;
@@ -498,6 +705,7 @@ export async function analyzeProxyLogs(options) {
     }
     const artifactsReferenced = artifactsPresent + artifactsMissing;
     const finalSummary = summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByRequest, accounts);
+    const routingSummary = summarizeRouting(finalRequests);
     return {
         generatedAt: new Date(nowMs).toISOString(),
         since: new Date(sinceMs).toISOString(),
@@ -514,6 +722,7 @@ export async function analyzeProxyLogs(options) {
             attempts: totalAttempts > 0,
             attemptLatency: attemptLatency.length > 0,
             cacheUsage: finalSummary.cache.requestsWithUsage > 0,
+            routingDecisions: routingSummary.totalRecords > 0,
         },
         dataQuality: {
             linesRead,
@@ -538,6 +747,11 @@ export async function analyzeProxyLogs(options) {
                 writeFailures,
                 truncatedCaptures,
             },
+            routingDecisions: {
+                valid: validRoutingDecisions,
+                invalid: invalidRoutingDecisions,
+                absent: absentRoutingDecisions,
+            },
         },
         lifecycle: {
             accepted: accepted.size,
@@ -572,6 +786,7 @@ export async function analyzeProxyLogs(options) {
             singleAttemptDelta: summarizeLatency(finalSummary.singleAttemptDelta),
         },
         cache: finalSummary.cache,
+        routing: routingSummary,
         accounts: [...accounts.values()].sort((left, right) => right.attempts - left.attempts),
     };
 }

package/dist/lib/proxy/requestLogger.js

@@ -236,6 +236,17 @@ function emitOtlpLogRecord(entry) {
                 // Account info
                 "account.name": entry.account,
                 "account.type": entry.accountType,
+                // Compact routing summary. Full candidate evidence stays in JSONL.
+                ...(entry.routingDecision && {
+                    "routing.mode": entry.routingDecision.mode,
+                    "routing.strategy": entry.routingDecision.strategy,
+                    "routing.selection_reason": entry.routingDecision.selectionReason,
+                    "routing.initial_account": entry.routingDecision.initialAccount,
+                    "routing.candidate_count": entry.routingDecision.candidates.length,
+                    "routing.final_account_changed": entry.routingDecision.initialAccount !== entry.account &&
+                        entry.routingDecision.candidates.some((candidate) => candidate.account === entry.account &&
+                            candidate.accountType === entry.accountType),
+                }),
                 // Token usage (when available)
                 ...(entry.inputTokens !== undefined && {
                     "ai.input_tokens": entry.inputTokens,

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

@@ -0,0 +1,6 @@
+/** 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_probe", "session_headroom", "session_reset", "weekly_reset", "weekly_utilization"];
+export declare const PROXY_ACCOUNT_TYPES: readonly ["oauth", "api_key"];
+export declare const ACCOUNT_COOLING_REASONS: readonly ["weekly", "session", "unified", "transient", "auth"];

package/dist/lib/proxy/routingEvidence.js

@@ -0,0 +1,33 @@
+/** Schema-v1 routing evidence values shared by emitters and offline readers. */
+export const PROXY_ACCOUNT_ROUTING_STRATEGIES = [
+    "round-robin",
+    "fill-first",
+];
+export const PROXY_ACCOUNT_ROUTING_MODES = [
+    "quota",
+    "primary",
+    "round_robin",
+    "single_account",
+];
+export const PROXY_ACCOUNT_ROUTING_REASONS = [
+    "single_account",
+    "round_robin",
+    "configured_primary",
+    "insertion_order",
+    "availability",
+    "cooldown_recovery",
+    "quota_probe",
+    "session_headroom",
+    "session_reset",
+    "weekly_reset",
+    "weekly_utilization",
+];
+export const PROXY_ACCOUNT_TYPES = ["oauth", "api_key"];
+export const ACCOUNT_COOLING_REASONS = [
+    "weekly",
+    "session",
+    "unified",
+    "transient",
+    "auth",
+];
+//# sourceMappingURL=routingEvidence.js.map

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

@@ -12,7 +12,7 @@
 import { buildTranslationOptions } from "../../proxy/proxyTranslationEngine.js";
 import { ProxyTracer } from "../../proxy/proxyTracer.js";
 import { isPermanentRefreshFailure } from "../../proxy/tokenRefresh.js";
-import type { AccountAllowlist, AccountCooldownPlan, AccountQuota, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicLoopState, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyBodyCaptureLogger, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
+import type { AccountAllowlist, AccountCooldownPlan, AccountQuota, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicLoopState, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
 /** Resolve the configured primary's stable key to its current index in the
  *  request's enabledAccounts list. Returns 0 (insertion-order fallback) when
  *  no key is configured or the key cannot be matched (account disabled/
@@ -85,6 +85,19 @@ declare function seedRuntimeQuotasFromDisk(accounts: ProxyPassthroughAccount[]):
  * last resort.
  */
 declare function orderAccountsByQuota(accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number): ProxyPassthroughAccount[];
+declare function buildRoutingDecision(args: {
+    accounts: ProxyPassthroughAccount[];
+    orderedAccounts: ProxyPassthroughAccount[];
+    metricsByKey: ReadonlyMap<string, ProxyAccountSortMetrics>;
+    evaluatedAt: number;
+    strategy: "round-robin" | "fill-first";
+    primaryKey: string | undefined;
+    quotaRoutingEnabled: boolean;
+    quotaOrdered: boolean;
+    sessionSoftLimit: number;
+    sessionResetToleranceMs: number;
+    rotationOffset: number;
+}): ProxyAccountRoutingDecision | undefined;
 declare function trackUpstreamReadableStream(source: ReadableStream<Uint8Array>): {
     stream: ReadableStream<Uint8Array>;
     outcome: Promise<StreamTerminalOutcome>;
@@ -279,6 +292,8 @@ export declare const __testHooks: {
     getStreamFailureDetails: typeof getStreamFailureDetails;
     trackUpstreamReadableStream: typeof trackUpstreamReadableStream;
     orderAccountsByQuota: typeof orderAccountsByQuota;
+    buildQuotaRoutingDecision: (accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number) => ProxyAccountRoutingDecision | undefined;
+    buildRoutingDecision: typeof buildRoutingDecision;
     resetEpochToMs: typeof resetEpochToMs;
     seedRuntimeQuotasFromDisk: typeof seedRuntimeQuotasFromDisk;
     reconcileEligibleAccountRuntimeState: typeof reconcileEligibleAccountRuntimeState;