@juspay/neurolink 13.8.5 → 13.8.7

package/dist/server/routes/claudeProxyRoutes.js

@@ -56,7 +56,7 @@ import { verifySharePayload } from "../../proxy/shareSigning.js";
 import { availableCoins, readSharePoolWindowUsage, readShareWindowUsage, recordShareWindowDelta, settleShareUsage, usageToCoins, } from "../../proxy/shareLedger.js";
 import { accountsInGrantScope, filterAccountsForGrant, isModelAllowed, isWithinSchedule, shareRefusalStatus, summarizeAccountExclusions, } from "../../proxy/sharePolicy.js";
 import { createStreamTerminalOutcomeTracker, mergeStreamTerminalOutcome, preflightAnthropicStream, } from "../../proxy/streamOutcome.js";
-import { isPermanentRefreshFailure, needsRefresh, persistTokens, refreshToken, refreshTokenFromLatest, } from "../../proxy/tokenRefresh.js";
+import { isPermanentRefreshFailure, needsInlineRefresh, persistTokens, refreshToken, refreshTokenFromLatest, } from "../../proxy/tokenRefresh.js";
 import { buildProxyTranslationPlan, parseRetryAfterMs, } from "../../proxy/routingPolicy.js";
 import { normalizeMaxInflightPerAccount } from "../../proxy/modelRouter.js";
 import { writeJsonSnapshotAtomically } from "../../proxy/snapshotPersistence.js";
@@ -166,10 +166,21 @@ const AUTH_REFRESH_MAX_COOLDOWN_MS = 5 * 60 * 1000;
  *  to cover the full lifecycle of streaming responses, including extended
  *  thinking from Opus models (which can exceed 5 minutes for large contexts). */
 const UPSTREAM_FETCH_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+/** Per-address connect attempt budget. Node's 250ms default turns one SYN that
+ *  needs a retransmit into ETIMEDOUT on a host whose AAAA record has no route,
+ *  because the IPv6 fallback then fails instantly. */
+const UPSTREAM_CONNECT_ATTEMPT_TIMEOUT_MS = 2_000;
+const UPSTREAM_CONNECT_TIMEOUT_MS = 10_000;
+/** Idle upstream sockets are kept this long. undici's 4s default reopened TCP
+ *  and TLS after nearly every pause between turns; Anthropic was measured
+ *  keeping idle sockets open past 300s, so 30s reuses them with margin. */
+const UPSTREAM_KEEP_ALIVE_TIMEOUT_MS = 30_000;
+const UPSTREAM_KEEP_ALIVE_MAX_TIMEOUT_MS = 10 * 60 * 1000;
 // Context checks and spending reservations belong immediately before dispatch.
 import { prepareProxyRequestContext, ProxyContextPreflightError, } from "../../proxy/proxyContextPreflight.js";
 import { reserveProxyTokenBudget, getProxyTokenBudgetError, getProxyTokenBudgetSessionKey, } from "../../proxy/proxyTokenBudget.js";
 import { observeAnthropicBudgetResponse } from "../../proxy/anthropicBudgetResponse.js";
+import { fetchProxyAware } from "../../proxy/proxyFetch.js";
 import { readCacheCreation1hTokens, oneHourCacheWriteFields, } from "../../proxy/proxyTokenUsage.js";
 function prepareAnthropicWire(ctx, bodyStr) {
     const body = JSON.parse(bodyStr);
@@ -209,13 +220,30 @@ async function getAnthropicUpstreamDispatcher() {
     }
     anthropicUpstreamDispatcherPromise ??= (async () => {
         try {
-            const { Agent: UndiciAgent } = await import("undici");
+            const { Agent: UndiciAgent, buildConnector } = await import("undici");
+            const connectUpstream = buildConnector({
+                timeout: UPSTREAM_CONNECT_TIMEOUT_MS,
+                autoSelectFamily: true,
+                autoSelectFamilyAttemptTimeout: UPSTREAM_CONNECT_ATTEMPT_TIMEOUT_MS,
+            });
             // Node's global fetch applies Undici's 300s default headers timeout
             // before the route's 15-minute abort signal. Keep both transport
             // deadlines aligned with the proxy contract.
             const agent = new UndiciAgent({
                 headersTimeout: UPSTREAM_FETCH_TIMEOUT_MS,
                 bodyTimeout: UPSTREAM_FETCH_TIMEOUT_MS,
+                keepAliveTimeout: UPSTREAM_KEEP_ALIVE_TIMEOUT_MS,
+                keepAliveMaxTimeout: UPSTREAM_KEEP_ALIVE_MAX_TIMEOUT_MS,
+                // A completed connect is the earliest proof the provider transport is
+                // back, so it releases requests parked behind a recovery probe.
+                connect: (options, callback) => {
+                    connectUpstream(options, (...result) => {
+                        if (result[0] === null) {
+                            providerTransportCoordinator.reportConnectionEstablished();
+                        }
+                        callback(...result);
+                    });
+                },
             });
             anthropicUpstreamDispatcher = agent;
             return agent;
@@ -265,10 +293,12 @@ async function fetchAnthropicUpstream(url, init, ctx, accountKey, dispatch) {
             attempt: dispatch.attemptNumber,
             metadata: { upstreamMethod: "POST", upstreamUrl: url },
         });
-        const response = await fetch(url, {
+        const response = await fetchProxyAware(url, {
             ...init,
             body: dispatchedBody,
-            dispatcher: upstreamDispatcher,
+        }, upstreamDispatcher, {
+            headersTimeout: UPSTREAM_FETCH_TIMEOUT_MS,
+            bodyTimeout: UPSTREAM_FETCH_TIMEOUT_MS,
         });
         return observeAnthropicBudgetResponse(response, lease, () => {
             ctx.metadata.tokenBudget = lease.snapshot;
@@ -983,6 +1013,12 @@ async function seedRuntimeQuotasFromDisk(accounts) {
 const MIN_USAGE_REFETCH_INTERVAL_MS = 15_000;
 const lastUsageFetchAt = new Map();
 let limitsRefreshInFlight = null;
+/** Status lines and dashboards poll `/limits` more often than requests arrive.
+ *  A sweep finished this recently is still current: usage is refetched at most
+ *  every MIN_USAGE_REFETCH_INTERVAL_MS anyway, and each sweep takes the token
+ *  store lock that `/v1/messages` waits on. */
+const LIMITS_RESULT_REUSE_MS = 2_000;
+let lastLimitsRefresh;
 const USAGE_REFRESH_CONCURRENCY = 4;
 async function applyAccountUsageResult(account, fetchResult, observedAt, prior) {
     if (fetchResult.ok === false) {
@@ -2220,10 +2256,6 @@ function snapshotsMatch(existing, next) {
 async function persistClaudeSnapshot(accountLabel, snapshot) {
     const snapshotPath = getSnapshotPath(accountLabel);
     await writeJsonSnapshotAtomically(snapshotPath, snapshot, 0o600);
-    snapshotCache.set(getSnapshotSafeLabel(accountLabel), {
-        snapshot,
-        loadedAt: Date.now(),
-    });
 }
 async function maybeRefreshClaudeSnapshot(accountLabel, accountKey, headers, bodyStr) {
     const existing = await loadClaudeSnapshot(accountLabel);
@@ -2254,19 +2286,22 @@ async function maybeRefreshClaudeSnapshot(accountLabel, accountKey, headers, bod
     if (snapshotsMatch(existing, next)) {
         return existing;
     }
-    try {
-        await persistClaudeSnapshot(accountLabel, next);
-    }
-    catch (error) {
+    // The request reads the snapshot from this cache, so it can go upstream now;
+    // the file only matters to a later process start. Writes to one account's
+    // file are already serialized, so the newest snapshot still lands last, and
+    // proxy shutdown awaits flushSnapshotWrites() so a graceful exit keeps it.
+    // A hard kill can still lose it, as a failed write always could; the next
+    // Claude Code request recaptures it.
+    snapshotCache.set(getSnapshotSafeLabel(accountLabel), {
+        snapshot: next,
+        loadedAt: Date.now(),
+    });
+    void persistClaudeSnapshot(accountLabel, next).catch((error) => {
         logger.warn("[proxy] failed to persist Claude snapshot", {
             accountLabel,
             error: error instanceof Error ? error.message : String(error),
         });
-        snapshotCache.set(getSnapshotSafeLabel(accountLabel), {
-            snapshot: next,
-            loadedAt: Date.now(),
-        });
-    }
+    });
     return next;
 }
 /**
@@ -4331,9 +4366,9 @@ function getCodexFallbackInvalidRequestFailure(error) {
     };
 }
 async function tryConfiguredClaudeFallbackChain(args) {
-    const { ctx, body, parsedFallbackRequest, fallbackPlan: providedFallbackPlan, modelRouter, tracer, requestStartTime, logProxyBody, logFinalRequest, } = args;
+    const { ctx, body, getParsedFallbackRequest, fallbackPlan: providedFallbackPlan, modelRouter, tracer, requestStartTime, logProxyBody, logFinalRequest, } = args;
     const fallbackPlan = providedFallbackPlan ??
-        buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, modelRouter?.getFallbackChain() ?? [], body.model, parsedFallbackRequest);
+        buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, modelRouter?.getFallbackChain() ?? [], body.model);
     ctx.metadata.fallbackPlan = fallbackPlan.attempts
         .slice(1)
         .map(({ provider, model, reasoningEffort }) => ({
@@ -4445,6 +4480,25 @@ async function tryConfiguredClaudeFallbackChain(args) {
                     lastFallbackError = `[${fallback.provider}/${fallback.model}] unavailable: ${reason}`;
                     continue;
                 }
+                let parsedFallbackRequest;
+                try {
+                    parsedFallbackRequest = getParsedFallbackRequest();
+                }
+                catch (parseError) {
+                    // A body the translator cannot read fails the same way on every
+                    // provider, so report it as the client's error and stop here.
+                    const reason = sanitizeForLog(parseError instanceof Error
+                        ? parseError.message
+                        : String(parseError), 300);
+                    terminalFailure = {
+                        status: 400,
+                        message: `Request could not be translated for provider fallback: ${reason}`,
+                        errorType: "invalid_request_error",
+                        retryable: false,
+                    };
+                    lastFallbackError = `[${fallback.provider}/${fallback.model}] untranslatable request: ${reason}`;
+                    break;
+                }
                 const options = buildProxyFallbackOptions(parsedFallbackRequest, {
                     provider: fallback.provider,
                     model: fallback.model,
@@ -6615,7 +6669,7 @@ function createClaudeRequestRuntimeContext(args) {
     };
 }
 function createAnthropicAttemptLogger(args) {
-    const { ctx, body, toolCount, requestStart, tracer, account, attemptNumber } = args;
+    const { ctx, body, toolCount, requestStart, tracer, account, attemptNumber, transportWaitMs, } = args;
     const attemptStartedAt = Date.now();
     const accountIdentity = resolveRequestLogAccountIdentity(account.label, account.type);
     return (status, errorType, errorMessage, extra) => {
@@ -6651,6 +6705,7 @@ function createAnthropicAttemptLogger(args) {
             responseStatus: status,
             responseTimeMs: attemptCompletedAt - requestStart,
             attemptDurationMs: extra?.attemptDurationMs ?? attemptCompletedAt - attemptStartedAt,
+            ...(transportWaitMs > 0 ? { transportWaitMs } : {}),
             ...(errorType ? { errorType } : {}),
             ...(errorMessage ? { errorMessage } : {}),
             ...(extra?.errorCode ? { errorCode: extra.errorCode } : {}),
@@ -6690,7 +6745,7 @@ async function prepareAnthropicAccountAttempt(args) {
     const { ctx, account, accountState, bodyStr, clientHeaders, isClaudeClientRequest, url, tracer, attemptNumber, currentLastError, currentAuthFailureMessage, logAttempt, logProxyBody: _logProxyBody, } = args;
     let lastError = currentLastError;
     let authFailureMessage = currentAuthFailureMessage;
-    if (needsRefresh(account)) {
+    if (needsInlineRefresh(account)) {
         const refreshed = await refreshTokenFromLatest(account, account.persistTarget);
         if (refreshed.success) {
             if (account.persistTarget) {
@@ -7038,7 +7093,10 @@ function buildDeferredClaudeAccountFailureResponse(args) {
 }
 async function handleAnthropicRoutedClaudeRequest(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);
+    // Only the provider fallback legs read the parsed form, and it walks the
+    // whole history, so the native path should not pay for it up front.
+    let parsedRequest;
+    const getParsedRequest = () => (parsedRequest ??= parseClaudeRequest(body));
     // Loop prevention for the Codex-outbound-fallback leg (stage-c-trigger.md
     // §3): a request that reached this handler AS a Codex-outbound fallback
     // loopback call must never be offered a fallback chain that routes back
@@ -7079,7 +7137,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
     }
     const configuredFallbackPlan = buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, isCodexOutboundFallbackLeg
         ? (modelRouter?.getFallbackChain() ?? []).filter((entry) => entry.provider !== "codex")
-        : (modelRouter?.getFallbackChain() ?? []), body.model, parsedRequest);
+        : (modelRouter?.getFallbackChain() ?? []), body.model);
     const hasConfiguredFallback = configuredFallbackPlan.attempts
         .slice(1)
         .some((attempt) => Boolean(attempt.provider && attempt.model));
@@ -7111,7 +7169,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         const configuredFallbackResult = await tryConfiguredClaudeFallbackChain({
             ctx,
             body,
-            parsedFallbackRequest: parsedRequest,
+            getParsedFallbackRequest: getParsedRequest,
             fallbackPlan: configuredFallbackPlan,
             modelRouter,
             tracer,
@@ -7258,7 +7316,10 @@ async function handleAnthropicRoutedClaudeRequest(args) {
             let transientSameAccountRetries = 0;
             let rateLimitSameAccountRetries = 0;
             while (true) {
+                const transportWaitStartedAt = performance.now();
                 const transportPermit = await providerTransportCoordinator.acquire(ctx.abortSignal);
+                // Rounded so the healthy fast path (microseconds) records nothing.
+                const transportWaitMs = Math.round(performance.now() - transportWaitStartedAt);
                 if (transportPermit.allowed === false) {
                     loopState.sawNetworkError = true;
                     loopState.lastTransportErrorCode =
@@ -7300,6 +7361,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                     tracer,
                     account,
                     attemptNumber: loopState.attemptNumber,
+                    transportWaitMs,
                 });
                 const preparedAttempt = await prepareAnthropicAccountAttempt({
                     ctx,
@@ -7677,7 +7739,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         const configuredFallbackResult = await tryConfiguredClaudeFallbackChain({
             ctx,
             body,
-            parsedFallbackRequest: parsedRequest,
+            getParsedFallbackRequest: getParsedRequest,
             fallbackPlan: configuredFallbackPlan,
             modelRouter,
             tracer,
@@ -8502,10 +8564,28 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                     }, async () => {
                         // Single-flight: concurrent full refreshes share one sweep.
                         if (!snapshotOnly && !accountFilter) {
+                            // Identity is the right key: the runtime config store hands
+                            // out one frozen snapshot per config generation, so the same
+                            // Set comes back until a reload, which should miss.
+                            if (lastLimitsRefresh &&
+                                lastLimitsRefresh.accountAllowlist === effectiveAllowlist &&
+                                Date.now() - lastLimitsRefresh.completedAt <
+                                    LIMITS_RESULT_REUSE_MS) {
+                                return lastLimitsRefresh.result;
+                            }
                             if (!limitsRefreshInFlight) {
                                 limitsRefreshInFlight = refreshAccountLimits({
                                     accountAllowlist: effectiveAllowlist,
-                                }).finally(() => {
+                                })
+                                    .then((result) => {
+                                    lastLimitsRefresh = {
+                                        completedAt: Date.now(),
+                                        accountAllowlist: effectiveAllowlist,
+                                        result,
+                                    };
+                                    return result;
+                                })
+                                    .finally(() => {
                                     limitsRefreshInFlight = null;
                                 });
                             }
@@ -9183,6 +9263,7 @@ export const __testHooks = {
     clearLimitsRefreshStateForTests: () => {
         lastUsageFetchAt.clear();
         limitsRefreshInFlight = null;
+        lastLimitsRefresh = undefined;
         accountQuotaRefreshCoordinator.clear();
     },
     setAccountDirectoryForTests: (override) => {

package/dist/server/routes/codexProxyRoutes.js

@@ -45,6 +45,7 @@ import { recordAttempt, recordAttemptError, recordFinalError, recordFinalSuccess
 import { raceWithAbort } from "../../utils/async/withTimeout.js";
 import { sanitizeForLog } from "../../utils/logSanitize.js";
 import { logger } from "../../utils/logger.js";
+import { fetchProxyAware } from "../../proxy/proxyFetch.js";
 const CODEX_UPSTREAM_TIMEOUT_MS = 15 * 60 * 1000; // 15 min, matches Claude path
 const DEFAULT_TRANSIENT_COOLDOWN_MS = 60_000;
 const MAX_TRANSIENT_COOLDOWN_MS = 15 * 60 * 1000;
@@ -1810,7 +1811,7 @@ loopbackPort, internalDispatch) {
                         upstreamUrl: CODEX_RESPONSES_URL,
                     });
                     state.budgetDispatched = true;
-                    upstream = await fetch(CODEX_RESPONSES_URL, {
+                    upstream = await fetchProxyAware(CODEX_RESPONSES_URL, {
                         method: "POST",
                         headers: upstreamHeaders,
                         body: state.bodyStr,
@@ -1990,7 +1991,7 @@ async function handleCodexModelsRequest(ctx) {
         for (;;) {
             let upstream;
             try {
-                upstream = await fetch(url, {
+                upstream = await fetchProxyAware(url, {
                     method: "GET",
                     headers: buildCodexUpstreamHeaders(ctx.headers ?? {}, account),
                     // Bound the upstream call, as the responses route does. Without a

package/dist/types/proxy.d.ts

@@ -992,6 +992,9 @@ export type RequestAttemptLogEntry = {
     responseTimeMs: number;
     /** Time spent in this specific account attempt. */
     attemptDurationMs?: number;
+    /** Time this attempt waited on the shared transport-recovery gate before
+     *  dispatch. Not part of `attemptDurationMs`; omitted when zero. */
+    transportWaitMs?: number;
     errorType?: string;
     errorMessage?: string;
     /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
@@ -2045,6 +2048,11 @@ export type ProxyEnvironmentSnapshot = {
     socksProxy?: string;
     noProxy?: string;
 };
+/** Transport deadlines for a proxied upstream request. */
+export type ProxyTimeouts = {
+    headersTimeout?: number;
+    bodyTimeout?: number;
+};
 /** Result of a traffic-quiet check. */
 export type QuietStatus = {
     isQuiet: boolean;

package/docs-site/static/search-index.json

@@ -2412,13 +2412,13 @@
 {"objectID":"44f9341fa01636183996f6966d6a698da57d335712c3aa020dfbf6673c3e1e77","title":"Account selection (fill-first)","url":"/docs/features/claude-proxy-troubleshooting#account-selection-fill-first","content":"Account selection (fill-first)","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy Troubleshooting","lvl2":"Account selection (fill-first)","lvl3":""}},
 {"objectID":"cf94af0f8a5039f675a3063e0b06af390d10d2cc678e8ee4b6c3d242cef7dc6a","title":"Exponential backoff progression","url":"/docs/features/claude-proxy-troubleshooting#exponential-backoff-progression","content":"For repeated 429 errors on the same account:\n\n| Backoff Level | Cooldown Duration |\n| ------------- | ----------------- |\n| 0             | 1 second          |\n| 1             | 2 seconds         |\n| 2             | 4 seconds         |\n| 3             | 8 seconds         |\n| 4             | 16 seconds        |\n| 5             | 32 seconds        |\n| ...           | ...               |\n| Max           | 10 minutes (cap)  |\n\nThe backoff level resets to zero on a successful request.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy Troubleshooting","lvl2":"Exponential backoff progression","lvl3":""}},
 {"objectID":"464f36b0cd0b7d8db6ad2b4b9618a37434a8270960aa06b24ef167febc873c33","title":"Quick Reference","url":"/docs/features/claude-proxy-troubleshooting#quick-reference","content":"| Symptom                         | Likely Cause                         | First Step                                      |\n| ------------------------------- | ------------------------------------ | ----------------------------------------------- |\n| 400 invalid_request_error       | Missing cloaking (bare curl)         | Use Claude Code, not curl                       |\n| credit balance too low          | API key with no credits in pool      | Remove ANTHROPIC_API_KEY or add credits       |\n| Extra inputs not permitted      | Missing beta headers                 | Rebuild with pnpm run build:cli               |\n| Slow first request (30s)        | MCP server init                      | Verify NEUROLINK_SKIP_MCP=true                |\n| Token expired                   | Auto-refresh missed                  | neurolink auth login anthropic --method oauth |\n| Refresh rate limited            | Too many refresh attempts            | Wait 30s, then re-login                         |\n| Accounts disabled until re-auth | Expired refresh tokens (15 failures) | neurolink auth login anthropic --method oauth |\n| Claude Code bypassing proxy     | ANTHROPIC_BASE_URL not set         | neurolink proxy setup, restart Claude Code    |\n| Raw bytes in stream             | Old build with Hono encoding bug     | Rebuild with pnpm run build:cli               |\n| Tools broken / 0 chunks         | MCP tool merging (old build)         | Rebuild; verify passthrough mode in logs        |\n| No account rotation             | Fill-first is working as designed    | Check debug logs for 429 + rotation             |","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy Troubleshooting","lvl2":"Quick Reference","lvl3":""}},
-{"objectID":"25fe74322f0fa35cad27d8d2c45cc5572e20c3c0295caacca6a0946123f28030","title":"Claude Proxy","url":"/docs/features/claude-proxy","content":"Claude Proxy\n\nNeuroLink includes a Claude-API-compatible proxy server that sits between Claude Code and Anthropic. It pools multiple Claude accounts, handles rate-limit failover automatically, refreshes OAuth tokens on demand before they expire, and falls back to other providers when all Claude accounts are exhausted.\n\nOverview\n\nWhy use the proxy?\n\nClaude Code supports only one Anthropic account at a time. If you hit a rate limit, you wait. If your token expires mid-session, you re-authenticate manually. The NeuroLink proxy solves these problems:\nMulti-account pooling -- Combine multiple Claude Pro/Max subscriptions for higher aggregate throughput.\nAutomatic token refresh -- OAuth tokens are refreshed before they expire (pre-request check + 401 retry).\nRate-limit failover -- When one account hits a 429, the proxy immediately tries the next account with exponential backoff.\nMulti-provider fallback -- When all Claude accounts are exhausted, requests are routed to alternative providers (Gemini, OpenAI, etc.) through NeuroLink's provider layer.\nTransparent to Claude Code -- Set ANTHROPIC_BASE_URL and Claude Code works normally. The proxy auto-configures this on start.\n\nHow it works at a glance\n\nQuick Start\n\nIf you do not already have the CLI installed, install it first:\n\nThen continue with the proxy setup steps below.\n\nOne-command setup\n\nThis command:\nChecks for existing authenticated accounts\nRuns OAuth login if no valid accounts exist\nInstalls the proxy as a launchd service (macOS) that auto-restarts on crash or reboot\nAuto-configures Claude Code to use the proxy\n\nUse --no-service to skip service installation and start the proxy in the foreground instead:\n\nManual setup\n\nRestart the serving worker\n\nrestart starts a replacement worker while the existing worker continues serving.\nThe supervisor switches new connections only after the replacement acknowledges\nreadiness and activation, then lets requests on the previous worker finish.\nYou do not need to run the check separately: restart includes it.\n\nThe command verifies admission, worker identity/version, socket-transfer counters\nand preservation of request-log disk/OTel settings. It does not generate a model\nrequest. A failed candidate has a 120-second readiness limit; the serving worker\nis retained. Concurrent restarts, pending updates and additional restarts while\nan older worker is still draining are refused. A disconnected terminal does not\ncancel the supervisor-owned operation or close admission.\n\nUse --format json for scripts. Exit zero means the check or activation was\nverified. activated_unverified means the replacement activated but a subsequent\ncheck failed; inspect neurolink proxy status before another operation. A lost\ncontrol connection leaves the outcome unknown, rather than triggering a forced\nservice restart.\n\nThe JSON contract is CliProxyRestartOutput: an authenticated supervisor result\nor { \"ok\": false, \"phase\": \"unverified\", \"message\": \"...\" } when the CLI cannot\nreceive or authenticate that result. The latter exits nonzero and deliberately\nomits supervisor/worker fields that could not be verified. It does not mean the\nreplacement failed or was rolled back. Control-server errors after binding are\nreported through the supervisor logger without stopping the serving listener.\n\nThis requires a running supervisor that advertises restart-control support.\nOlder supervisors must first receive a separately planned service activation;\ninstalling a newer CLI alone does not add the capability to an existing process.\nThe command refuses an unsupported supervisor without signalling it.\n\nThe listener and supervisor remain running, so this command does not apply changed\nlaunchd stdout/stderr destinations or replace supervisor/updater code. Those need\na service activation with its own interruption budget. proxy install is service\nsetup, not a routine restart command. The restart command does not rewrite the\nlauncher, environment, routing configuration or update history. Local OTel\ninitialization is checked; collector/backend delivery still needs telemetry\nverification.\n\nHow It Works\n\nRequest Flow\n\nEvery request from Claude Code flows through the proxy in one of two modes:\n\nPassthrough mode (Claude to Claude): The request body is forwarded directly to api.anthropic.com with only the authentication headers modified. This preserves multi-turn conversation history, thinking content, cache control, and tool definitions exactly as Claude Code sent them. No lossy conversion through an intermediate format.\n\nTranslation mode (Claude to other provider): When model routing directs a request to a non-Anthropic provider, the proxy parses the Claude Messages API request into NeuroLink's internal format, calls neurolink.generate() or neurolink.stream(), and serializes the result back into Claude Messages API format (including SSE streaming events). For streaming, the proxy emits SSE keep-alive comments (: keep-alive) every 15 seconds during idle periods to prevent connection","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"","lvl3":""}},
+{"objectID":"25fe74322f0fa35cad27d8d2c45cc5572e20c3c0295caacca6a0946123f28030","title":"Claude Proxy","url":"/docs/features/claude-proxy","content":"Claude Proxy\n\nNeuroLink includes a Claude-API-compatible proxy server that sits between Claude Code and Anthropic. It pools multiple Claude accounts, handles rate-limit failover automatically, refreshes OAuth tokens on demand before they expire, and falls back to other providers when all Claude accounts are exhausted.\n\nOverview\n\nWhy use the proxy?\n\nClaude Code supports only one Anthropic account at a time. If you hit a rate limit, you wait. If your token expires mid-session, you re-authenticate manually. The NeuroLink proxy solves these problems:\nMulti-account pooling -- Combine multiple Claude Pro/Max subscriptions for higher aggregate throughput.\nAutomatic token refresh -- OAuth tokens are refreshed before they expire (pre-request check + 401 retry).\nRate-limit failover -- When one account hits a 429, the proxy immediately tries the next account with exponential backoff.\nMulti-provider fallback -- When all Claude accounts are exhausted, requests are routed to alternative providers (Gemini, OpenAI, etc.) through NeuroLink's provider layer.\nTransparent to Claude Code -- Set ANTHROPIC_BASE_URL and Claude Code works normally. The proxy auto-configures this on start.\n\nHow it works at a glance\n\nQuick Start\n\nIf you do not already have the CLI installed, install it first:\n\nThen continue with the proxy setup steps below.\n\nOne-command setup\n\nThis command:\nChecks for existing authenticated accounts\nRuns OAuth login if no valid accounts exist\nInstalls the proxy as a launchd service (macOS) that auto-restarts on crash or reboot\nAuto-configures Claude Code to use the proxy\n\nUse --no-service to skip service installation and start the proxy in the foreground instead:\n\nManual setup\n\nFor deployments that require an outbound HTTP proxy, set HTTPS_PROXY and/or\nHTTP_PROXY in the environment of the neurolink proxy process before starting\nit. ALL_PROXY is used when no scheme-specific proxy is set, and NO_PROXY\nbypasses the proxy for matching hosts. These settings cover Anthropic, Codex,\nand Vertex passthrough forwards, OAuth requests, and quota polling. When a\nconfigured proxy fails, these requests fail instead of retrying directly.\n\nRestart the serving worker\n\nrestart starts a replacement worker while the existing worker continues serving.\nThe supervisor switches new connections only after the replacement acknowledges\nreadiness and activation, then lets requests on the previous worker finish.\nYou do not need to run the check separately: restart includes it.\n\nThe command verifies admission, worker identity/version, socket-transfer counters\nand preservation of request-log disk/OTel settings. It does not generate a model\nrequest. A failed candidate has a 120-second readiness limit; the serving worker\nis retained. Concurrent restarts, pending updates and additional restarts while\nan older worker is still draining are refused. A disconnected terminal does not\ncancel the supervisor-owned operation or close admission.\n\nUse --format json for scripts. Exit zero means the check or activation was\nverified. activated_unverified means the replacement activated but a subsequent\ncheck failed; inspect neurolink proxy status before another operation. A lost\ncontrol connection leaves the outcome unknown, rather than triggering a forced\nservice restart.\n\nThe JSON contract is CliProxyRestartOutput: an authenticated supervisor result\nor { \"ok\": false, \"phase\": \"unverified\", \"message\": \"...\" } when the CLI cannot\nreceive or authenticate that result. The latter exits nonzero and deliberately\nomits supervisor/worker fields that could not be verified. It does not mean the\nreplacement failed or was rolled back. Control-server errors after binding are\nreported through the supervisor logger without stopping the serving listener.\n\nThis requires a running supervisor that advertises restart-control support.\nOlder supervisors must first receive a separately planned service activation;\ninstalling a newer CLI alone does not add the capability to an existing process.\nThe command refuses an unsupported supervisor without signalling it.\n\nThe listener and supervisor remain running, so this command does not apply changed\nlaunchd stdout/stderr destinations or replace supervisor/updater code. Those need\na service activation with its own interruption budget. proxy install is service\nsetup, not a routine restart command. The restart command does not rewrite the\nlauncher, environment, routing configuration or update history. Local OTel\ninitialization is checked; collector/backend delivery still needs telemetry\nverification.\n\nHow It Works\n\nRequest Flow\n\nEvery request from Claude Code flows through the proxy in one of two modes:\n\nPassthrough mode (Claude to Claude): The request body is forwarded directly to api.anthropic.com with only the authentication headers modified. This preserves multi-turn conversation history, thinking content, cache control, and tool definitions exactly as Claude Code sent them. No lossy conversion through an intermediate format.\n\nTranslation mod","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"","lvl3":""}},
 {"objectID":"cd6d13f50f433e6c99d05f1b6836b42b1abae54a3e97303ffd5dfcc94117e1f2","title":"Claude Proxy","url":"/docs/features/claude-proxy#claude-proxy","content":"NeuroLink includes a Claude-API-compatible proxy server that sits between Claude Code and Anthropic. It pools multiple Claude accounts, handles rate-limit failover automatically, refreshes OAuth tokens on demand before they expire, and falls back to other providers when all Claude accounts are exhausted.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Claude Proxy","lvl3":""}},
 {"objectID":"00d0e565d5c6b476beb49291259ad3d6d29245039e72ea47d84d223d42fdde68","title":"Why use the proxy?","url":"/docs/features/claude-proxy#why-use-the-proxy","content":"Claude Code supports only one Anthropic account at a time. If you hit a rate limit, you wait. If your token expires mid-session, you re-authenticate manually. The NeuroLink proxy solves these problems:\nMulti-account pooling -- Combine multiple Claude Pro/Max subscriptions for higher aggregate throughput.\nAutomatic token refresh -- OAuth tokens are refreshed before they expire (pre-request check + 401 retry).\nRate-limit failover -- When one account hits a 429, the proxy immediately tries the next account with exponential backoff.\nMulti-provider fallback -- When all Claude accounts are exhausted, requests are routed to alternative providers (Gemini, OpenAI, etc.) through NeuroLink's provider layer.\nTransparent to Claude Code -- Set ANTHROPIC_BASE_URL and Claude Code works normally. The proxy auto-configures this on start.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Why use the proxy?","lvl3":""}},
 {"objectID":"7a61989dbd73cbd8be85bf44e571333710956232acabc0df383e9c0309cb31ff","title":"How it works at a glance","url":"/docs/features/claude-proxy#how-it-works-at-a-glance","content":"How it works at a glance","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"How it works at a glance","lvl3":""}},
 {"objectID":"4fff8ce3b2980c189940fe8f3dbd7fb99c961dd3e73af086a911631f0c0f6186","title":"Quick Start","url":"/docs/features/claude-proxy#quick-start","content":"If you do not already have the CLI installed, install it first:\n\nThen continue with the proxy setup steps below.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Quick Start","lvl3":""}},
 {"objectID":"ec115266d6030cdba9743aaa9f04d18cfcce5b0e7a0bfa777bf0b8d6ca51d764","title":"One-command setup","url":"/docs/features/claude-proxy#one-command-setup","content":"This command:\nChecks for existing authenticated accounts\nRuns OAuth login if no valid accounts exist\nInstalls the proxy as a launchd service (macOS) that auto-restarts on crash or reboot\nAuto-configures Claude Code to use the proxy\n\nUse --no-service to skip service installation and start the proxy in the foreground instead:","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"One-command setup","lvl3":""}},
-{"objectID":"485846ce8d40e93dd7e3ada58798719e3694cbf411b4d41571c075d887900eb3","title":"Manual setup","url":"/docs/features/claude-proxy#manual-setup","content":"Manual setup","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Manual setup","lvl3":""}},
+{"objectID":"485846ce8d40e93dd7e3ada58798719e3694cbf411b4d41571c075d887900eb3","title":"Manual setup","url":"/docs/features/claude-proxy#manual-setup","content":"For deployments that require an outbound HTTP proxy, set HTTPS_PROXY and/or\nHTTP_PROXY in the environment of the neurolink proxy process before starting\nit. ALL_PROXY is used when no scheme-specific proxy is set, and NO_PROXY\nbypasses the proxy for matching hosts. These settings cover Anthropic, Codex,\nand Vertex passthrough forwards, OAuth requests, and quota polling. When a\nconfigured proxy fails, these requests fail instead of retrying directly.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Manual setup","lvl3":""}},
 {"objectID":"8c067e169758adc810089db64e417d6dc960a750ae8c038d6737eb45306fd9d8","title":"Restart the serving worker","url":"/docs/features/claude-proxy#restart-the-serving-worker","content":"restart starts a replacement worker while the existing worker continues serving.\nThe supervisor switches new connections only after the replacement acknowledges\nreadiness and activation, then lets requests on the previous worker finish.\nYou do not need to run the check separately: restart includes it.\n\nThe command verifies admission, worker identity/version, socket-transfer counters\nand preservation of request-log disk/OTel settings. It does not generate a model\nrequest. A failed candidate has a 120-second readiness limit; the serving worker\nis retained. Concurrent restarts, pending updates and additional restarts while\nan older worker is still draining are refused. A disconnected terminal does not\ncancel the supervisor-owned operation or close admission.\n\nUse --format json for scripts. Exit zero means the check or activation was\nverified. activated_unverified means the replacement activated but a subsequent\ncheck failed; inspect neurolink proxy status before another operation. A lost\ncontrol connection leaves the outcome unknown, rather than triggering a forced\nservice restart.\n\nThe JSON contract is CliProxyRestartOutput: an authenticated supervisor result\nor { \"ok\": false, \"phase\": \"unverified\", \"message\": \"...\" } when the CLI cannot\nreceive or authenticate that result. The latter exits nonzero and deliberately\nomits supervisor/worker fields that could not be verified. It does not mean the\nreplacement failed or was rolled back. Control-server errors after binding are\nreported through the supervisor logger without stopping the serving listener.\n\nThis requires a running supervisor that advertises restart-control support.\nOlder supervisors must first receive a separately planned service activation;\ninstalling a newer CLI alone does not add the capability to an existing process.\nThe command refuses an unsupported supervisor without signalling it.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Restart the serving worker","lvl3":""}},
 {"objectID":"d3f2f492ba79c35c567408642c86e730a966688e4993622fd4d81190772246e8","title":"Request Flow","url":"/docs/features/claude-proxy#request-flow","content":"Every request from Claude Code flows through the proxy in one of two modes:\n\nPassthrough mode (Claude to Claude): The request body is forwarded directly to api.anthropic.com with only the authentication headers modified. This preserves multi-turn conversation history, thinking content, cache control, and tool definitions exactly as Claude Code sent them. No lossy conversion through an intermediate format.\n\nTranslation mode (Claude to other provider): When model routing directs a request to a non-Anthropic provider, the proxy parses the Claude Messages API request into NeuroLink's internal format, calls neurolink.generate() or neurolink.stream(), and serializes the result back into Claude Messages API format (including SSE streaming events). For streaming, the proxy emits SSE keep-alive comments (: keep-alive) every 15 seconds during idle periods to prevent connection timeouts.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Request Flow","lvl3":""}},
 {"objectID":"d5e5f137807efbff5800106aa9777b782e2a973ddf98f31877f1f139acd785aa","title":"Trace And Session Context","url":"/docs/features/claude-proxy#trace-and-session-context","content":"If the caller sends W3C trace headers (traceparent, tracestate) or NeuroLink session headers (x-neurolink-session-id, x-neurolink-user-id, x-neurolink-conversation-id), the proxy links its spans to the caller trace and preserves that session/user/conversation context in proxy traces and logs.","hierarchy":{"lvl0":"Features","lvl1":"Claude Proxy","lvl2":"Trace And Session Context","lvl3":""}},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "13.8.5",
+  "version": "13.8.7",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {
@@ -230,6 +230,7 @@
     "test:local-usage": "pnpm exec tsx test/continuous-test-suite-local-usage.ts",
     "test:dynamic": "pnpm exec tsx test/continuous-test-suite-dynamic.ts",
     "test:proxy": "pnpm exec tsx test/continuous-test-suite-proxy.ts",
+    "test:proxy-egress": "pnpm exec tsx test/continuous-test-suite-proxy-egress.ts",
     "test:proxy-connect-retry": "pnpm exec tsx test/continuous-test-suite-proxy-connect-retry.ts",
     "test:proxy-reliability": "node scripts/run-proxy-reliability.mjs",
     "test:proxy-telemetry": "pnpm exec tsx test/continuous-test-suite-proxy-telemetry.ts",