@juspay/neurolink 10.9.0 → 10.10.0

package/dist/cli/commands/proxy.js

@@ -45,6 +45,8 @@ const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/obse
 const PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS = 5_000;
 const LEGACY_STATUS_ACCOUNT_CACHE_TTL_MS = 5_000;
 const PROXY_STATUS_TOKEN_READ_TIMEOUT_MS = 2_000;
+const PROXY_STATUS_RECONCILE_TIMEOUT_MS = 750;
+const PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS = 750;
 let legacyStatusAccountCache;
 // Allowed drift between a pid's OS-reported start time and the persisted
 // ProxySupervisorState.startTime before processLooksLikeProxySupervisor
@@ -1495,9 +1497,34 @@ export async function createProxyStartApp(params) {
                 toolRegistry: params.neurolink.getToolRegistry(),
                 timestamp: Date.now(),
                 metadata: {},
+                // Route handlers publish limit/quota headers here. Only the streaming
+                // paths build their own Response (and set headers directly); every
+                // JSON and error path returns a plain object, so without this the
+                // headers had nowhere to go. Applied to each c.json() return below.
+                responseHeaders: {},
+            };
+            /** Copy handler-published headers onto the outgoing response. */
+            const applyResponseHeaders = () => {
+                for (const [key, value] of Object.entries(ctx.responseHeaders)) {
+                    c.header(key, value);
+                }
             };
             const result = await route.handler(ctx);
             if (result instanceof Response) {
+                // Streaming responses own their headers; merge in anything the
+                // handler published on the context that the Response lacks. A Response
+                // obtained from fetch() carries immutable headers, so this is
+                // best-effort — the body must still reach the client either way.
+                try {
+                    for (const [key, value] of Object.entries(ctx.responseHeaders)) {
+                        if (!result.headers.has(key)) {
+                            result.headers.set(key, value);
+                        }
+                    }
+                }
+                catch {
+                    // Immutable header guard — skip enrichment, keep the response.
+                }
                 return result;
             }
             if (result &&
@@ -1542,6 +1569,7 @@ export async function createProxyStartApp(params) {
                 });
                 return new Response(responseStream, {
                     headers: {
+                        ...ctx.responseHeaders,
                         "Content-Type": "text/event-stream",
                         "Cache-Control": "no-cache",
                         Connection: "keep-alive",
@@ -1554,6 +1582,7 @@ export async function createProxyStartApp(params) {
                 const httpResult = result;
                 const status = httpResult.httpStatus ?? 200;
                 delete httpResult.httpStatus;
+                applyResponseHeaders();
                 return c.json(result, status);
             }
             if (result &&
@@ -1562,8 +1591,10 @@ export async function createProxyStartApp(params) {
                 result.type === "error") {
                 const errorResult = result;
                 const status = mapClaudeErrorTypeToStatus(errorResult.error?.type);
+                applyResponseHeaders();
                 return c.json(result, status);
             }
+            applyResponseHeaders();
             return c.json(result ?? {});
         });
     }
@@ -1592,9 +1623,20 @@ export async function createProxyStartApp(params) {
         const activeAccountAllowlist = runtimeConfig
             ? runtimeConfig.accountAllowlist
             : params.accountAllowlist;
-        const { getReconciledUsageSnapshot, getUsageStatsPersistenceStatus } = await import("../../lib/proxy/usageStats.js");
+        const { getReconciledUsageSnapshot, getUsageSnapshot, getUsageStatsPersistenceStatus, } = await import("../../lib/proxy/usageStats.js");
         const { loadAccountCooldowns } = await import("../../lib/proxy/accountCooldown.js");
-        const usageSnapshot = await getReconciledUsageSnapshot();
+        let usageSnapshot = getUsageSnapshot();
+        let snapshotSource = "memory";
+        try {
+            usageSnapshot = await withTimeout(getReconciledUsageSnapshot(), PROXY_STATUS_RECONCILE_TIMEOUT_MS, "[proxy] /status usage reconciliation timed out");
+            snapshotSource = "reconciled";
+        }
+        catch (error) {
+            // Status must not become an outage amplifier when a cross-process lock or
+            // a slow filesystem stalls reconciliation. The process-local snapshot is
+            // coherent and its source is explicit to callers.
+            logger.debug(`[proxy] /status using memory stats snapshot: ${error instanceof Error ? error.message : String(error)}`);
+        }
         const { stats, terminalErrors } = usageSnapshot;
         const terminalErrorDetailsComparable = usageSnapshot.statsVersion === usageSnapshot.terminalErrorsVersion;
         const lastTerminalError = terminalErrors.recent.at(-1) ?? null;
@@ -1608,40 +1650,52 @@ export async function createProxyStartApp(params) {
         const supervisorState = loadProxySupervisorState();
         const rollingSupervisorRunning = isRollingHandoffCapable(supervisorState);
         const updateState = loadUpdateState();
-        const cooldowns = await loadAccountCooldowns();
+        const cooldowns = await withTimeout(loadAccountCooldowns(), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status cooldown inspection timed out").catch((error) => {
+            logger.debug(`[proxy] /status using empty cooldown snapshot: ${error instanceof Error ? error.message : String(error)}`);
+            return {};
+        });
         const storedAccountKeys = new Set();
         const storedAccountExpirations = new Map();
         const disabledAccountKeys = new Set();
         let accountInventoryLoaded = false;
         try {
             const { tokenStore } = await import("../../lib/auth/tokenStore.js");
-            const storedKeys = await tokenStore.listByPrefix("anthropic:");
+            const storedKeys = await withTimeout(tokenStore.listByPrefix("anthropic:"), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status account enumeration timed out");
             for (const key of storedKeys) {
-                const normalizedKey = normalizeAnthropicAccountKey(key);
-                storedAccountKeys.add(normalizedKey);
+                storedAccountKeys.add(normalizeAnthropicAccountKey(key));
             }
-            await Promise.all(storedKeys.map(async (key) => {
-                const normalizedKey = normalizeAnthropicAccountKey(key);
-                try {
-                    const tokens = await withTimeout(tokenStore.peekTokens(key), PROXY_STATUS_TOKEN_READ_TIMEOUT_MS, "[proxy] /status token inspection timed out");
-                    if (tokens) {
-                        storedAccountExpirations.set(normalizedKey, tokens.expiresAt);
+            // Once account names are known, preserve them even when optional token
+            // metadata is slow. That keeps the status table useful and avoids
+            // incorrectly presenting known accounts as removed.
+            accountInventoryLoaded = true;
+            const inventory = await withTimeout((async () => {
+                const tokenExpirations = await Promise.all(storedKeys.map(async (key) => {
+                    try {
+                        const tokens = await withTimeout(tokenStore.peekTokens(key), PROXY_STATUS_TOKEN_READ_TIMEOUT_MS, "[proxy] /status token inspection timed out");
+                        return tokens ? [key, tokens.expiresAt] : undefined;
                     }
+                    catch (error) {
+                        logger.debug(`[proxy] /status: failed to inspect token metadata for ${normalizeAnthropicAccountKey(key)}: ${error instanceof Error ? error.message : String(error)}`);
+                        return undefined;
+                    }
+                }));
+                const disabledKeys = await tokenStore.listDisabled();
+                return { tokenExpirations, disabledKeys };
+            })(), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status account metadata timed out");
+            for (const expiration of inventory.tokenExpirations) {
+                if (expiration) {
+                    storedAccountExpirations.set(normalizeAnthropicAccountKey(expiration[0]), expiration[1]);
                 }
-                catch (err) {
-                    logger.debug(`[proxy] /status: failed to inspect token metadata for ${normalizedKey}: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }));
-            for (const key of await tokenStore.listDisabled()) {
+            }
+            for (const key of inventory.disabledKeys) {
                 disabledAccountKeys.add(normalizeAnthropicAccountKey(key));
             }
-            accountInventoryLoaded = true;
         }
         catch (err) {
             logger.debug(`[proxy] /status: failed to resolve account cooldown labels: ${err instanceof Error ? err.message : String(err)}`);
         }
         const legacyAccountLabel = accountInventoryLoaded
-            ? await resolveLegacyStatusAccountLabel(storedAccountKeys.size)
+            ? await withTimeout(resolveLegacyStatusAccountLabel(storedAccountKeys.size), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status legacy account inspection timed out").catch(() => null)
             : null;
         const now = Date.now();
         const health = buildProxyHealthResponse(readiness, {
@@ -1649,7 +1703,12 @@ export async function createProxyStartApp(params) {
             passthrough: activePassthrough,
             version: PROXY_VERSION,
         });
-        const primaryAccount = await resolveStatusPrimaryAccount(activeProxyConfig);
+        const primaryAccount = await withTimeout(resolveStatusPrimaryAccount(activeProxyConfig), PROXY_STATUS_ACCOUNT_INVENTORY_TIMEOUT_MS, "[proxy] /status primary account inspection timed out").catch(() => ({
+            configured: activeProxyConfig?.routing?.primaryAccount?.trim() || null,
+            key: null,
+            label: null,
+            source: "fallback",
+        }));
         const activeUpdaterPid = supervisorState?.updaterPid ?? runtimeState?.updaterPid;
         const accountRows = Object.values(stats.accounts).map((account) => {
             const normalizedKey = normalizeAnthropicAccountKey(account.label);
@@ -1813,6 +1872,7 @@ export async function createProxyStartApp(params) {
                 terminalErrorDetailsComparable,
                 terminalErrorDetailsMissing,
                 terminalErrorDetailsExcess,
+                snapshotSource,
                 accounts: accountRows,
                 primaryAccount,
                 persistence: getUsageStatsPersistenceStatus(),

package/dist/lib/providers/anthropic/client.d.ts

@@ -1,6 +1,6 @@
 import { type AIProviderName } from "../../constants/enums.js";
 import { BaseProvider } from "../../core/baseProvider.js";
-import type { AnthropicProviderConfig, StreamOptions, StreamResult, ValidationSchema, EnhancedGenerateResult, TextGenerationOptions, AnthropicAuthMethod, AnthropicResponseMetadata, ClaudeSubscriptionTier, ClaudeUsageInfo } from "../../types/index.js";
+import type { AnthropicProviderConfig, StreamOptions, StreamResult, ValidationSchema, EnhancedGenerateResult, TextGenerationOptions, AnthropicAuthMethod, AnthropicRateLimitInfo, AnthropicResponseMetadata, ClaudeSubscriptionTier, ClaudeUsageInfo } from "../../types/index.js";
 import type { LanguageModel } from "../../types/index.js";
 /**
  * Anthropic Provider v2 - BaseProvider Implementation
@@ -103,12 +103,18 @@ export declare class AnthropicProvider extends BaseProvider {
      */
     getLastResponseMetadata(): AnthropicResponseMetadata | null;
     /**
-     * Update response metadata from API response headers.
-     * This should be called after each API request to track rate limits.
-     * @param headers - Response headers from the API
-     * @param requestId - Optional request ID
+     * Update response metadata from a captured limit snapshot.
+     *
+     * Takes already-parsed rate-limit info rather than raw headers: parsing now
+     * lives in `rateLimitCapture`, which is the only layer that sees the raw
+     * response and understands both header families (unified subscription
+     * windows and legacy per-tier counters).
+     *
+     * @param rateLimit - Parsed rate-limit figures
+     * @param requestId - Optional Anthropic request ID
+     * @param usageUpdate - Optional token counts to fold into usage tracking
      */
-    protected updateResponseMetadata(headers: Headers | Record<string, string>, requestId?: string, usageUpdate?: {
+    protected updateResponseMetadata(rateLimit: AnthropicRateLimitInfo, requestId?: string, usageUpdate?: {
         inputTokens?: number;
         outputTokens?: number;
     }): void;
@@ -127,7 +133,16 @@ export declare class AnthropicProvider extends BaseProvider {
      * BaseProvider so that expired tokens are renewed automatically.
      */
     generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
-    protected executeStream(options: StreamOptions, _analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    /**
+     * Fold a captured snapshot into the provider's usage bookkeeping and log it.
+     *
+     * `updateResponseMetadata` had no callers before this — the metadata it
+     * maintains, and the public `getLastResponseMetadata()` / `getUsageInfo()`
+     * that read it, were never populated by anything.
+     */
+    private recordLimitSnapshot;
+    protected executeStream(options: StreamOptions, analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    private executeStreamInCaptureScope;
     isAvailable(): Promise<boolean>;
     getModel(): LanguageModel;
 }

package/dist/lib/providers/anthropic/client.js

@@ -11,6 +11,7 @@ import { streamAnalyticsCollector } from "../../core/streamAnalytics.js";
 import { getModelCapabilities, getRecommendedModelForTier, isModelAvailableForTier, } from "../../models/anthropicModels.js";
 import { createOAuthFetch } from "../../proxy/oauthFetch.js";
 import { createProxyFetch } from "../../proxy/proxyFetch.js";
+import { getCapturedLimitSnapshot, getCapturedResponseHeaders, logClaudeLimitSnapshot, runInLimitCaptureScope, setLimitSpanAttributes, withLimitCapture, wrapFetchWithLimitCapture, } from "./rateLimitCapture.js";
 import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
 import { logger } from "../../utils/logger.js";
 import { redactUrlCredentials } from "../../utils/logSanitize.js";
@@ -166,35 +167,10 @@ const detectAuthMethod = (oauthToken) => {
     });
     return method;
 };
-/**
- * Parse rate limit information from Anthropic API response headers.
- * @param headers - Response headers from Anthropic API
- * @returns Parsed rate limit information
- */
-const parseRateLimitHeaders = (headers) => {
-    const getHeader = (name) => {
-        if (headers instanceof Headers) {
-            return headers.get(name);
-        }
-        return headers[name] || headers[name.toLowerCase()] || null;
-    };
-    const parseNumber = (value) => {
-        if (!value) {
-            return undefined;
-        }
-        const num = parseInt(value, 10);
-        return isNaN(num) ? undefined : num;
-    };
-    return {
-        requestsLimit: parseNumber(getHeader("anthropic-ratelimit-requests-limit")),
-        requestsRemaining: parseNumber(getHeader("anthropic-ratelimit-requests-remaining")),
-        requestsReset: getHeader("anthropic-ratelimit-requests-reset") || undefined,
-        tokensLimit: parseNumber(getHeader("anthropic-ratelimit-tokens-limit")),
-        tokensRemaining: parseNumber(getHeader("anthropic-ratelimit-tokens-remaining")),
-        tokensReset: getHeader("anthropic-ratelimit-tokens-reset") || undefined,
-        retryAfter: parseNumber(getHeader("retry-after")),
-    };
-};
+// Rate-limit header parsing lives in `rateLimitCapture.ts`, which sees the raw
+// fetch Response and understands both header families (unified subscription
+// windows and the legacy per-tier counters). The module-private copy that used
+// to sit here parsed only the legacy family and had no callers.
 // ───────────────────────────────────────────────────────────────────────────
 // Native Messages-API conversion helpers (NeuroLink/V3 shapes → Anthropic)
 // ───────────────────────────────────────────────────────────────────────────
@@ -590,7 +566,10 @@ export class AnthropicProvider extends BaseProvider {
             client = new Anthropic({
                 apiKey: "oauth-authenticated", // Placeholder, actual auth is in fetch wrapper
                 // Note: No headers passed - fetch wrapper sets oauth-2025-04-20 beta header
-                fetch: oauthFetch,
+                // Limit capture wraps the OAuth fetch so subscription quota headers
+                // (anthropic-ratelimit-unified-*) are recorded on every request —
+                // streaming and non-streaming alike.
+                fetch: wrapFetchWithLimitCapture(oauthFetch),
                 timeout: ANTHROPIC_CLIENT_TIMEOUT_MS,
                 // The SDK's built-in retry honors Retry-After hints without any
                 // upper bound (a 429 with retry-after: 8549 sleeps 2.4h per retry,
@@ -642,7 +621,10 @@ export class AnthropicProvider extends BaseProvider {
                 apiKey: apiKeyToUse,
                 defaultHeaders: headers,
                 ...(normalizedBaseURL && { baseURL: normalizedBaseURL }),
-                fetch: createProxyFetch(),
+                // Same capture as the OAuth branch: works for direct API-key traffic
+                // (legacy requests/tokens counters) and for the NeuroLink Claude proxy
+                // (verbatim unified quota plus x-neurolink-* account/pool state).
+                fetch: wrapFetchWithLimitCapture(createProxyFetch()),
                 timeout: ANTHROPIC_CLIENT_TIMEOUT_MS,
                 // See the OAuth-path client above: unbounded Retry-After sleeps in
                 // the SDK's retry loop must never stall fallback orchestration.
@@ -971,24 +953,22 @@ export class AnthropicProvider extends BaseProvider {
         return this.lastResponseMetadata;
     }
     /**
-     * Update response metadata from API response headers.
-     * This should be called after each API request to track rate limits.
-     * @param headers - Response headers from the API
-     * @param requestId - Optional request ID
+     * Update response metadata from a captured limit snapshot.
+     *
+     * Takes already-parsed rate-limit info rather than raw headers: parsing now
+     * lives in `rateLimitCapture`, which is the only layer that sees the raw
+     * response and understands both header families (unified subscription
+     * windows and legacy per-tier counters).
+     *
+     * @param rateLimit - Parsed rate-limit figures
+     * @param requestId - Optional Anthropic request ID
+     * @param usageUpdate - Optional token counts to fold into usage tracking
      */
-    updateResponseMetadata(headers, requestId, usageUpdate) {
+    updateResponseMetadata(rateLimit, requestId, usageUpdate) {
         this.lastResponseMetadata = {
-            rateLimit: parseRateLimitHeaders(headers),
-            requestId: requestId ||
-                (headers instanceof Headers
-                    ? headers.get("x-request-id") || undefined
-                    : headers["x-request-id"]),
-            serverTiming: headers instanceof Headers
-                ? headers.get("server-timing") || undefined
-                : headers["server-timing"],
+            rateLimit,
+            ...(requestId ? { requestId } : {}),
         };
-        // Update usage tracking
-        const rateLimit = this.lastResponseMetadata.rateLimit;
         if (this.usageInfo) {
             this.usageInfo.requestCount++;
             this.usageInfo.messagesUsed++;
@@ -1254,7 +1234,10 @@ export class AnthropicProvider extends BaseProvider {
                     response: {
                         id: response.id,
                         modelId: response.model,
-                        headers: {},
+                        // Real response headers, captured by the fetch wrapper. This used
+                        // to be a hardcoded `{}`, which silently discarded every
+                        // rate-limit and quota header Anthropic returns.
+                        headers: getCapturedResponseHeaders() ?? {},
                         body: response,
                     },
                 };
@@ -1305,9 +1288,41 @@ export class AnthropicProvider extends BaseProvider {
      */
     async generate(optionsOrPrompt, analysisSchema) {
         await this.refreshAuthIfNeeded();
-        return super.generate(optionsOrPrompt, analysisSchema);
+        // Open a per-request capture scope around the whole turn. Scoping here
+        // rather than on the instance is what makes it concurrency-safe: several
+        // generate() calls can be in flight on one provider instance, and an
+        // instance field would attribute one call's limits to another.
+        const { result, snapshot } = await withLimitCapture(() => super.generate(optionsOrPrompt, analysisSchema));
+        if (result && snapshot) {
+            this.recordLimitSnapshot(snapshot);
+            result.limits = snapshot;
+            if (result.analytics) {
+                result.analytics.limits = snapshot;
+            }
+        }
+        return result;
+    }
+    /**
+     * Fold a captured snapshot into the provider's usage bookkeeping and log it.
+     *
+     * `updateResponseMetadata` had no callers before this — the metadata it
+     * maintains, and the public `getLastResponseMetadata()` / `getUsageInfo()`
+     * that read it, were never populated by anything.
+     */
+    recordLimitSnapshot(snapshot) {
+        this.updateResponseMetadata(snapshot.rateLimit, snapshot.requestId);
+        setLimitSpanAttributes(snapshot);
+        logClaudeLimitSnapshot(snapshot, this.modelName);
+    }
+    async executeStream(options, analysisSchema) {
+        // The capture scope must outlive this call: the SSE loop keeps running in
+        // the background after executeStream returns, and its per-step HTTP
+        // requests are what carry the limit headers. AsyncLocalStorage.run
+        // propagates into every continuation started inside, so the whole stream
+        // lifetime shares one slot.
+        return runInLimitCaptureScope(() => this.executeStreamInCaptureScope(options, analysisSchema));
     }
-    async executeStream(options, _analysisSchema) {
+    async executeStreamInCaptureScope(options, _analysisSchema) {
         // Refresh OAuth token if needed before making any API request.
         await this.refreshAuthIfNeeded();
         this.validateStreamOptions(options);
@@ -1758,15 +1773,25 @@ export class AnthropicProvider extends BaseProvider {
             // stream consumers and session cost tracking saw no usage at all.
             // Chained off finishPromise so requestDuration reflects the DRAINED
             // stream, not the milliseconds it took to construct this result object.
-            analytics: finishPromise.then(() => streamAnalyticsCollector.createAnalytics(this.providerName, modelId, {
-                textStream: (async function* () { })(),
-                usage: usagePromise,
-                finishReason: finishPromise,
-            }, Date.now() - streamStartTime, {
-                requestId: options.requestId ??
-                    `${this.providerName}-stream-${Date.now()}`,
-                streamingMode: true,
-            })),
+            analytics: finishPromise.then(async () => {
+                const analytics = await streamAnalyticsCollector.createAnalytics(this.providerName, modelId, {
+                    textStream: (async function* () { })(),
+                    usage: usagePromise,
+                    finishReason: finishPromise,
+                }, Date.now() - streamStartTime, {
+                    requestId: options.requestId ??
+                        `${this.providerName}-stream-${Date.now()}`,
+                    streamingMode: true,
+                });
+                // Still inside the capture scope opened by executeStream, so this sees
+                // the limits reported by the last upstream step of the stream.
+                const snapshot = getCapturedLimitSnapshot();
+                if (snapshot && analytics) {
+                    this.recordLimitSnapshot(snapshot);
+                    analytics.limits = snapshot;
+                }
+                return analytics;
+            }),
         };
     }
     async isAvailable() {

package/dist/lib/providers/anthropic/rateLimitCapture.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Anthropic rate-limit / quota header capture.
+ *
+ * Anthropic returns limit state on the response headers of every request:
+ * `anthropic-ratelimit-unified-*` for subscription (OAuth) accounts,
+ * `anthropic-ratelimit-{requests,tokens}-*` for API-key accounts. The NeuroLink
+ * Claude proxy forwards those verbatim and adds `x-neurolink-*` for what only
+ * it knows (which account served the request, pool headroom, whether the
+ * numbers are live or a carried-over snapshot).
+ *
+ * None of it used to reach the SDK: `doGenerate` returned a hardcoded empty
+ * header bag and the streaming loop never looked. The capture point here is the
+ * `fetch` the Anthropic SDK is constructed with — it is invoked exactly once
+ * per HTTP request on BOTH the streaming and non-streaming paths, so a single
+ * wrapper covers everything without touching the SSE loop or switching the
+ * non-streaming call to `.withResponse()`.
+ *
+ * Scoping is per-request via AsyncLocalStorage rather than a field on the
+ * provider: a provider instance is shared across concurrent calls, so an
+ * instance field would race and attribute one request's limits to another.
+ *
+ * @module providers/anthropic/rateLimitCapture
+ */
+import type { AnthropicRateLimitInfo, ClaudeLimitSnapshot } from "../../types/index.js";
+/**
+ * Parse both Anthropic rate-limit header families into a single shape.
+ *
+ * Which family is present depends on the account type, so every field is
+ * optional and absence is normal rather than an error.
+ */
+export declare function parseAnthropicLimitHeaders(headers: Headers): AnthropicRateLimitInfo;
+/**
+ * Build a snapshot from a response, or undefined when the response carries
+ * neither Anthropic rate-limit headers nor NeuroLink proxy metadata.
+ */
+export declare function buildLimitSnapshot(headers: Headers, status: number, now?: number): ClaudeLimitSnapshot | undefined;
+/**
+ * Wrap a fetch so every response's limit headers are captured into the
+ * enclosing `withLimitCapture` scope. A no-op outside such a scope.
+ *
+ * Capture never alters the response and never throws — a parsing failure must
+ * not be able to break a request that the provider would otherwise complete.
+ */
+export declare function wrapFetchWithLimitCapture(inner: typeof fetch): typeof fetch;
+/**
+ * Run `body` in a capture scope and return its result alongside whatever limit
+ * snapshot the underlying HTTP request(s) produced.
+ */
+export declare function withLimitCapture<T>(body: () => Promise<T>): Promise<{
+    result: T;
+    snapshot?: ClaudeLimitSnapshot;
+}>;
+/**
+ * Current scope's snapshot, if any. Lets a long-running loop (the streaming
+ * path) read limits mid-flight without unwinding the scope.
+ */
+export declare function getCapturedLimitSnapshot(): ClaudeLimitSnapshot | undefined;
+/** Raw headers of the most recent captured response in this scope. */
+export declare function getCapturedResponseHeaders(): Record<string, string> | undefined;
+/** Enter a capture scope without wrapping a single call — for streaming, where
+ *  the scope must outlive the function that opened it. */
+export declare function runInLimitCaptureScope<T>(body: () => T): T;
+/**
+ * Attach limit state to the currently active OTel span.
+ *
+ * Uses the active span rather than threading one down from the generation
+ * layer: that layer is provider-agnostic and should not learn about Anthropic
+ * quota headers just to record them. The active span during a turn is the one
+ * already carrying `gen_ai.usage.*` and `neurolink.cost`, so "what did this
+ * cost" and "how much is left" answer from the same trace.
+ */
+export declare function setLimitSpanAttributes(snapshot: ClaudeLimitSnapshot): void;
+/**
+ * Emit one structured line per request describing remaining capacity.
+ *
+ * Leads with headroom ("how much is left") because that is the figure an
+ * operator acts on; the raw utilization stays available on the snapshot for
+ * anything computing against it. Escalates to WARN when the session window is
+ * nearly spent or the provider has already flagged the account as
+ * throttled/rejected.
+ */
+export declare function logClaudeLimitSnapshot(snapshot: ClaudeLimitSnapshot, model?: string, now?: number): void;