@juspay/neurolink 9.92.2 → 9.93.0

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

@@ -53,11 +53,6 @@ const BLOCKED_UPSTREAM_HEADERS = new Set([
 let primaryAccountIndex = 0;
 /** Track account count so we can reset primaryAccountIndex when it changes. */
 let lastKnownAccountCount = 0;
-/** Stable account key used by legacy fixed-config route factories. Runtime
- *  config providers pass the request generation's primary key explicitly.
- *  When undefined, home semantics retain insertion-order behavior. */
-let configuredPrimaryAccountKey;
-let configuredAccountAllowlist;
 const MAX_AUTH_RETRIES = 5;
 const MAX_TRANSIENT_SAME_ACCOUNT_RETRIES = 2;
 const TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS = [250, 1_000];
@@ -129,7 +124,7 @@ function advancePrimaryIfCurrent(accountKey, enabledCount, primaryAccountKey) {
  *  no key is configured or the key cannot be matched (account disabled/
  *  removed). The resolution is per-request because enabledAccounts membership
  *  can shift between requests. */
-function resolveHomeIndex(enabledAccounts, primaryAccountKey = configuredPrimaryAccountKey) {
+function resolveHomeIndex(enabledAccounts, primaryAccountKey) {
     if (!primaryAccountKey) {
         return 0;
     }
@@ -140,7 +135,7 @@ function resolveHomeIndex(enabledAccounts, primaryAccountKey = configuredPrimary
  *  primaryAccountIndex back to its index so traffic returns to the preferred
  *  account once its rate limit window expires. Called at the start of each
  *  request. Home is resolved fresh per call via resolveHomeIndex. */
-function maybeResetPrimaryToHome(enabledAccounts, primaryAccountKey = configuredPrimaryAccountKey) {
+function maybeResetPrimaryToHome(enabledAccounts, primaryAccountKey) {
     if (enabledAccounts.length <= 1) {
         return;
     }
@@ -463,28 +458,30 @@ function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToler
 }
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
- * spend the window that expires SOONEST first, so its about-to-reset
- * allowance isn't wasted, then move to accounts with longer-dated resets.
+ * spend the overall weekly allowance that expires SOONEST first, so quota
+ * cannot disappear while traffic is consuming a newer weekly window. The 5h
+ * window remains an availability boundary: a session at its soft limit is
+ * temporarily demoted until that session resets.
  *
  * Priority among usable accounts:
  *   1. no quota data yet — probe first: one request reveals its windows and
  *      self-corrects the ordering. (Ranking unknowns last would starve them
  *      forever: never picked → never observed → never comparable.)
  *   2. session headroom before session-saturated (>= soft limit or
- *      "throttled") — saturated accounts then follow the same bucketed
- *      session ordering below: soonest back in service first, weekly
- *      deciding same-bucket ties.
- *   3. soonest SESSION (5h) reset — the capacity expiring soonest; compared
- *      in tolerance buckets so near-simultaneous resets count as equal.
- *   4. soonest WEEKLY (7d) reset — decides between same-bucket sessions.
- *   5. highest weekly utilization — finish off the one closest to done
+ *      "throttled") — do not re-hammer an urgent weekly account while its 5h
+ *      capacity is temporarily unavailable.
+ *   3. soonest WEEKLY (7d) reset — consume the oldest overall allowance
+ *      before it expires.
+ *   4. soonest SESSION (5h) reset — decides equal-weekly or fresh-weekly ties,
+ *      using tolerance buckets for comparator stability.
+ *   5. highest weekly utilization — finish off the one closest to done.
  *   6. configured primary account, then insertion order
- * An account with NO ticking session window (fresh, not yet started) has
- * nothing expiring and sorts after ticking windows in step 3.
+ * Saturated pairs are ordered by soonest 5h recovery first, then weekly reset,
+ * because neither can consume more quota until session capacity returns.
  * Cooling/rejected accounts sort last, soonest-back-to-service first, as
  * last resort.
  */
-function orderAccountsByQuota(accounts, now, primaryKey = configuredPrimaryAccountKey, sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs()) {
+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);
@@ -503,14 +500,21 @@ function orderAccountsByQuota(accounts, now, primaryKey = configuredPrimaryAccou
         if (ma.saturated !== mb.saturated) {
             return ma.saturated ? 1 : -1;
         }
-        // Saturated pairs fall through to the same bucketed session ordering:
-        // soonest-back-in-service at bucket granularity, weekly deciding ties —
-        // honoring the configured tolerance instead of exact-epoch comparison.
-        if (ma.sessionResetBucket !== mb.sessionResetBucket) {
-            return ma.sessionResetBucket - mb.sessionResetBucket;
+        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;
+            }
         }
-        if (ma.weeklyReset !== mb.weeklyReset) {
-            return ma.weeklyReset - mb.weeklyReset;
+        else {
+            if (ma.weeklyReset !== mb.weeklyReset) {
+                return ma.weeklyReset - mb.weeklyReset;
+            }
+            if (ma.sessionResetBucket !== mb.sessionResetBucket) {
+                return ma.sessionResetBucket - mb.sessionResetBucket;
+            }
         }
         if (ma.weeklyUsed !== mb.weeklyUsed) {
             return mb.weeklyUsed - ma.weeklyUsed;
@@ -1538,7 +1542,7 @@ async function handleClaudePassthroughJsonResponse(args) {
     return responseJson;
 }
 async function loadClaudeProxyAccounts(args) {
-    const { ctx, body, tracer, requestStartTime, accountStrategy, primaryAccountKey = configuredPrimaryAccountKey, accountAllowlist = configuredAccountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, } = args;
+    const { ctx, body, tracer, requestStartTime, accountStrategy, primaryAccountKey, accountAllowlist, quotaRoutingEnabled = isQuotaRoutingEnabled(), sessionSoftLimit = getSessionSoftLimit(), sessionResetToleranceMs = getSessionResetToleranceMs(), buildLoggedClaudeError, } = args;
     const fs = await import("fs");
     const os = await import("os");
     const accounts = [];
@@ -1722,10 +1726,16 @@ async function loadClaudeProxyAccounts(args) {
     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 window resets
-        // soonest first (max utilization), proactively skipping any whose window is
-        // rejected until its reset. Supersedes the static home/primary index.
+        // 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
@@ -3052,7 +3062,10 @@ async function handleAnthropicAuthRetry(args) {
                 : String(retryFetchErr);
             authRetryError = `network error on retry ${authRetry + 1}: ${message}`;
             currentLastError = authRetryError;
-            retryLogAttempt(502, "network_error", message, { retryable: true });
+            retryLogAttempt(502, "network_error", message, {
+                retryable: isRetryableNetworkError(retryFetchErr),
+                errorCode: getErrorCode(retryFetchErr) ?? "unknown",
+            });
             logger.debug(`[proxy] ${authRetryError}`);
             break;
         }
@@ -3427,6 +3440,7 @@ function createAnthropicAttemptLogger(args) {
             responseTimeMs: Date.now() - requestStart,
             ...(errorType ? { errorType } : {}),
             ...(errorMessage ? { errorMessage } : {}),
+            ...(extra?.errorCode ? { errorCode: extra.errorCode } : {}),
             ...(extra?.inputTokens !== undefined
                 ? { inputTokens: extra.inputTokens }
                 : {}),
@@ -3641,19 +3655,27 @@ async function fetchAnthropicAccountResponse(args) {
         });
     }
     catch (fetchErr) {
-        if (!isRetryableNetworkError(fetchErr)) {
-            throw fetchErr;
-        }
+        const retryable = isRetryableNetworkError(fetchErr);
+        // Every dispatched upstream request is an attempt, including terminal
+        // transport failures. Record it once before preserving the throw behavior.
         sawNetworkError = true;
         recordAttemptError(account.label, account.type, 502);
         const errorCode = getErrorCode(fetchErr) ?? "unknown";
         const errorMessage = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
         lastError = errorMessage;
-        logger.always(`[proxy] fetch error account=${account.label} code=${errorCode} (retryable): ${errorMessage}`);
-        logAttempt(502, "network_error", errorMessage);
+        logger.always(`[proxy] fetch error account=${account.label} code=${errorCode} (${retryable ? "retryable" : "terminal"}): ${errorMessage}`);
+        logAttempt(502, "network_error", errorMessage, {
+            retryable,
+            errorCode,
+        });
         tracer?.setError("network_error", errorMessage);
-        tracer?.recordRetry(account.label, "network_error");
+        if (retryable) {
+            tracer?.recordRetry(account.label, "network_error");
+        }
         currentUpstreamSpan?.end();
+        if (!retryable) {
+            throw fetchErr;
+        }
         return {
             continueLoop: true,
             retrySameAccount: true,
@@ -3791,15 +3813,6 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         attemptNumber: 0,
     };
     const acctSelectionSpan = tracer?.startAccountSelection();
-    // Try to return to the home primary account if its cooling has expired.
-    // Skipped under quota routing, where the fill order is derived per-request
-    // from live quota (soonest-reset-first) rather than a static home index.
-    const usingQuotaOrder = accountStrategy === "fill-first" &&
-        enabledAccounts.length > 1 &&
-        quotaRoutingEnabled;
-    if (!usingQuotaOrder) {
-        maybeResetPrimaryToHome(enabledAccounts, primaryAccountKey);
-    }
     // Never re-hammer accounts with a known active cooldown. When every account
     // is cooling, report the earliest persisted retry time without an upstream
     // call; restarting the proxy must not erase or bypass this quarantine.
@@ -4174,10 +4187,6 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
     const runtimeConfigProvider = isClaudeProxyRouteRuntimeOptions(accountAllowlistOrRuntimeOptions)
         ? accountAllowlistOrRuntimeOptions.runtimeConfigProvider
         : undefined;
-    configuredPrimaryAccountKey = primaryAccountKey;
-    configuredAccountAllowlist = accountAllowlist
-        ? new Set(accountAllowlist)
-        : undefined;
     return {
         prefix: `${basePath}/v1`,
         routes: [
@@ -4472,16 +4481,13 @@ function describeTransportError(error) {
  */
 function isRetryableNetworkError(error) {
     const code = getErrorCode(error);
-    // Check non-retryable codes FIRST — before the string-based heuristic
-    // which could false-positive on error messages containing these strings.
-    const NON_RETRYABLE_CODES = ["ENOTFOUND"];
-    if (code && NON_RETRYABLE_CODES.includes(code)) {
-        return false;
-    }
     if (code &&
         [
             "ECONNREFUSED",
             "ECONNRESET",
+            // The Anthropic host is fixed, so ENOTFOUND can be a transient resolver
+            // outage. Keep it inside the existing bounded same-account retry budget.
+            "ENOTFOUND",
             "ETIMEDOUT",
             "EHOSTUNREACH",
             "UND_ERR_CONNECT_TIMEOUT",
@@ -4493,13 +4499,9 @@ function isRetryableNetworkError(error) {
     }
     const message = error instanceof Error ? error.message : String(error);
     const normalized = message.toLowerCase();
-    // Exclude ENOTFOUND from string-based heuristic — DNS failures are permanent
-    // and rotating accounts won't help since they all hit the same host.
-    if (normalized.includes("enotfound")) {
-        return false;
-    }
     return (normalized.includes("econnrefused") ||
         normalized.includes("econnreset") ||
+        normalized.includes("enotfound") ||
         normalized.includes("etimedout") ||
         normalized.includes("timed out") ||
         normalized.includes("connection error") ||
@@ -4608,14 +4610,6 @@ export const __testHooks = {
         const state = accountRuntimeState.get(key);
         return state ? { ...state } : undefined;
     },
-    setConfiguredPrimaryAccountKey: (key) => {
-        configuredPrimaryAccountKey = key;
-    },
-    getConfiguredPrimaryAccountKey: () => configuredPrimaryAccountKey,
-    setConfiguredAccountAllowlist: (allowlist) => {
-        configuredAccountAllowlist = allowlist ? new Set(allowlist) : undefined;
-    },
-    getConfiguredAccountAllowlist: () => configuredAccountAllowlist ? [...configuredAccountAllowlist] : undefined,
     setPrimaryAccountIndex: (index) => {
         primaryAccountIndex = index;
     },
@@ -4631,8 +4625,6 @@ export const __testHooks = {
         transientCooldownAdmissionSchedules.clear();
         primaryAccountIndex = 0;
         lastKnownAccountCount = 0;
-        configuredPrimaryAccountKey = undefined;
-        configuredAccountAllowlist = undefined;
     },
     polyfillOAuthBody: (bodyStr, isClaudeClientRequest) => polyfillOAuthBody(bodyStr, "test-account-token", null, isClaudeClientRequest),
     isAntiAbuseConstruction429,

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

@@ -437,6 +437,8 @@ export type RequestLogEntry = {
     responseTimeMs: number;
     errorType?: string;
     errorMessage?: string;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
@@ -461,6 +463,8 @@ export type RequestAttemptLogEntry = {
     responseTimeMs: number;
     errorType?: string;
     errorMessage?: string;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     /** Whether this failed attempt may be retried without changing the request. */
     retryable?: boolean;
     /** Distinguishes short-lived admission throttles from exhausted quota windows. */
@@ -514,6 +518,8 @@ export type AnthropicAttemptLogger = (status: number, errorType?: string, errorM
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
     retryable?: boolean;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     rateLimitKind?: "transient" | "quota";
     cooldownReason?: "transient" | "session" | "weekly" | "unified";
     /** Override used when one account selection performs an OAuth retry fetch. */
@@ -945,6 +951,80 @@ export type ProxyRuntimeActivity = {
     activeRequests: number;
     lastActivityAt: string | null;
 };
+/** Terminal state observed while the HTTP adapter relays a response body. */
+export type ProxyResponseTerminalOutcome = "completed" | "bodyless" | "client_cancelled" | "stream_error";
+/** Non-blocking callbacks for response lifecycle metadata. */
+export type ProxyResponseTrackingObserver = {
+    onFirstChunk?: (details: {
+        /** Decoded response-body bytes observed by the adapter. */
+        observedBodyBytes: number;
+        responseChunks: 1;
+    }) => void;
+    onTerminal?: (details: {
+        outcome: ProxyResponseTerminalOutcome;
+        /** Decoded response-body bytes observed by the adapter. */
+        observedBodyBytes: number;
+        responseChunks: number;
+    }) => void;
+};
+/** Versioned lifecycle event names persisted by the proxy adapter. */
+export type ProxyLifecycleEventName = "request_accepted" | "response_headers" | "response_first_chunk" | "request_terminal";
+/** Client-facing terminal classifications recorded by lifecycle metadata. */
+export type ProxyLifecycleTerminalOutcome = ProxyResponseTerminalOutcome | "handler_error";
+/** Content-free lifecycle event accepted by the bounded metadata logger. */
+export type ProxyLifecycleEventInput = {
+    event: ProxyLifecycleEventName;
+    requestId: string;
+    method: string;
+    path: string;
+    model?: string;
+    stream?: boolean;
+    toolCount?: number;
+    sessionHash?: string;
+    requestBytes?: number;
+    responseStatus?: number;
+    /** Decoded response-body bytes observed by the adapter. */
+    observedBodyBytes?: number;
+    responseChunks?: number;
+    elapsedMs?: number;
+    terminalOutcome?: ProxyLifecycleTerminalOutcome;
+    errorType?: string;
+    errorCode?: string;
+    timestampMs?: number;
+    monotonicMs?: number;
+};
+/** Data-quality counters for the bounded lifecycle metadata sink. */
+export type ProxyLifecycleLoggerSnapshot = {
+    enabled: boolean;
+    schemaVersion: number;
+    processInstanceId: string;
+    nextSequence: number;
+    attempted: number;
+    enqueued: number;
+    written: number;
+    dropped: number;
+    queueDrops: number;
+    invalidDrops: number;
+    writeDrops: number;
+    writeFailures: number;
+    pending: number;
+    inFlight: number;
+    flushing: boolean;
+};
+/** Lifecycle logger configuration. Queue overrides are used by stress tests. */
+export type ProxyLifecycleLoggerOptions = {
+    enabled: boolean;
+    logDir?: string;
+    queueCapacity?: number;
+    batchSize?: number;
+    flushIntervalMs?: number;
+};
+/** Serialized lifecycle line awaiting a bounded batch write. */
+export type QueuedProxyLifecycleEvent = {
+    logDir: string;
+    date: string;
+    record: Record<string, unknown>;
+};
 /** Request metadata retained by the HTTP adapter for terminal error logging. */
 export type RuntimeRequestMetadata = {
     requestId: string;
@@ -954,6 +1034,8 @@ export type RuntimeRequestMetadata = {
     model: string;
     stream: boolean;
     toolCount: number;
+    terminalErrorType?: string;
+    terminalErrorCode?: string;
 };
 /** Accumulated upstream body capture from a raw stream. */
 export type RawStreamCapture = {

package/dist/proxy/proxyActivity.d.ts

@@ -1,8 +1,8 @@
-import type { ProxyActivitySnapshot } from "../types/index.js";
+import type { ProxyActivitySnapshot, ProxyResponseTrackingObserver } from "../types/index.js";
 /** Track one client-facing proxy request until its response body settles. */
 export declare function beginProxyRequest(): () => void;
 export declare function getProxyActivitySnapshot(): ProxyActivitySnapshot;
 export declare function isProxyActivityQuiet(snapshot: ProxyActivitySnapshot, quietThresholdMs: number, nowMs?: number): boolean;
 /** Keep activity open until the response body completes, errors, or is cancelled. */
-export declare function trackProxyResponse(response: Response, finishRequest: () => void): Response;
+export declare function trackProxyResponse(response: Response, finishRequest: () => void, observer?: ProxyResponseTrackingObserver): Response;
 export declare function resetProxyActivityForTests(): void;

package/dist/proxy/proxyActivity.js

@@ -1,8 +1,24 @@
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { logger } from "../utils/logger.js";
+const PROXY_RESPONSE_CANCEL_TIMEOUT_MS = 1_000;
 let activeRequests = 0;
 let lastActivityAtMs = null;
 function touchActivity() {
     lastActivityAtMs = Date.now();
 }
+function safelyNotifyObserver(callback) {
+    try {
+        callback?.();
+    }
+    catch (error) {
+        // Observability must never alter response handling.
+        if (logger.shouldLog("debug")) {
+            logger.debug("[proxy] response lifecycle observer failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
 /** Track one client-facing proxy request until its response body settles. */
 export function beginProxyRequest() {
     activeRequests += 1;
@@ -33,35 +49,59 @@ export function isProxyActivityQuiet(snapshot, quietThresholdMs, nowMs = Date.no
     return nowMs - snapshot.lastActivityAt.getTime() >= quietThresholdMs;
 }
 /** Keep activity open until the response body completes, errors, or is cancelled. */
-export function trackProxyResponse(response, finishRequest) {
+export function trackProxyResponse(response, finishRequest, observer) {
     if (!response.body) {
         finishRequest();
+        safelyNotifyObserver(() => observer?.onTerminal?.({
+            outcome: "bodyless",
+            observedBodyBytes: 0,
+            responseChunks: 0,
+        }));
         return response;
     }
     const reader = response.body.getReader();
+    let observedBodyBytes = 0;
+    let responseChunks = 0;
+    let settled = false;
+    const settle = (outcome) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        finishRequest();
+        safelyNotifyObserver(() => observer?.onTerminal?.({
+            outcome,
+            observedBodyBytes,
+            responseChunks,
+        }));
+    };
     const trackedBody = new ReadableStream({
         async pull(controller) {
             try {
                 const { value, done } = await reader.read();
                 if (done) {
-                    finishRequest();
+                    settle("completed");
                     controller.close();
                     return;
                 }
                 controller.enqueue(value);
+                observedBodyBytes += value.byteLength;
+                responseChunks += 1;
+                if (responseChunks === 1) {
+                    safelyNotifyObserver(() => observer?.onFirstChunk?.({
+                        observedBodyBytes,
+                        responseChunks: 1,
+                    }));
+                }
             }
             catch (error) {
-                finishRequest();
+                settle("stream_error");
                 controller.error(error);
             }
         },
         async cancel(reason) {
-            try {
-                await reader.cancel(reason);
-            }
-            finally {
-                finishRequest();
-            }
+            settle("client_cancelled");
+            await withTimeout(reader.cancel(reason), PROXY_RESPONSE_CANCEL_TIMEOUT_MS, "Timed out cancelling the upstream proxy response");
         },
     });
     return new Response(trackedBody, {

package/dist/proxy/proxyLifecycle.d.ts

@@ -0,0 +1,8 @@
+import type { ProxyLifecycleEventInput, ProxyLifecycleLoggerOptions, ProxyLifecycleLoggerSnapshot } from "../types/index.js";
+export declare function hashProxyLifecycleSessionId(sessionId: string | undefined): string | undefined;
+export declare function configureProxyLifecycleLogger(options: ProxyLifecycleLoggerOptions): void;
+/** Enqueue fixed-size lifecycle metadata without awaiting filesystem work. */
+export declare function logProxyLifecycleEvent(input: ProxyLifecycleEventInput): void;
+export declare function flushProxyLifecycleEvents(): Promise<void>;
+export declare function getProxyLifecycleLoggerSnapshot(): ProxyLifecycleLoggerSnapshot;
+export declare function resetProxyLifecycleLoggerForTests(): void;