@juspay/neurolink 9.87.3 → 9.88.0

package/dist/server/routes/claudeProxyRoutes.js

@@ -31,6 +31,7 @@ import { buildProxyTranslationPlan, parseRetryAfterMs, } from "../../proxy/routi
 import { writeJsonSnapshotAtomically } from "../../proxy/snapshotPersistence.js";
 import { recordAttempt, recordAttemptError, recordFinalError, recordFinalSuccess, } from "../../proxy/usageStats.js";
 import { logger } from "../../utils/logger.js";
+import { withTimeout } from "../../utils/async/withTimeout.js";
 import { ProviderHealthChecker } from "../../utils/providerHealth.js";
 // ---------------------------------------------------------------------------
 // Helpers
@@ -61,6 +62,8 @@ let configuredAccountAllowlist;
 const MAX_AUTH_RETRIES = 5;
 const MAX_TRANSIENT_SAME_ACCOUNT_RETRIES = 2;
 const TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS = [250, 1_000];
+const MAX_FALLBACK_NETWORK_RETRIES = 1;
+const FALLBACK_STREAM_IDLE_TIMEOUT_MS = 2 * 60 * 1000;
 /** Maximum upstream 429 attempts per account before rotating — for a TRANSIENT
  *  burst 429 only (window still "allowed", short retry-after). An exhaustion 429
  *  (5h/7d window "rejected") rotates immediately with zero same-account retries,
@@ -394,45 +397,105 @@ function isQuotaRoutingEnabled() {
     const v = (process.env.NEUROLINK_PROXY_QUOTA_ROUTING ?? "").toLowerCase();
     return v !== "off" && v !== "false" && v !== "0";
 }
-/** Derive the ordering signals for an account from its latest runtime quota. */
-function accountSortMetrics(accountKey, now) {
+/** Session-utilization soft limit above which an account is demoted below
+ *  accounts with headroom (never made unusable). The utilization snapshot is
+ *  always at least one response stale and requests land in concurrent bursts,
+ *  so a small buffer under 100% turns the window-exhaustion handoff proactive
+ *  (scheduled between requests) instead of reactive (a burst of 429s).
+ *  Override with NEUROLINK_PROXY_SESSION_SOFT_LIMIT (0 < x <= 1; 1 disables). */
+function getSessionSoftLimit() {
+    // Number() rejects partially numeric values ("0.5oops") that parseFloat
+    // would silently truncate.
+    const raw = Number(process.env.NEUROLINK_PROXY_SESSION_SOFT_LIMIT ?? "");
+    return Number.isFinite(raw) && raw > 0 && raw <= 1 ? raw : 0.97;
+}
+/** Width of the bucket within which two session resets count as "the same
+ *  time", letting the weekly reset decide. Exact epoch equality never occurs,
+ *  and bucketing (unlike pairwise closeness) keeps the comparator transitive.
+ *  Override with NEUROLINK_PROXY_SESSION_RESET_TOLERANCE_MS. */
+function getSessionResetToleranceMs() {
+    // Number() + isInteger rejects partially numeric values ("900000oops")
+    // that parseInt would silently truncate.
+    const raw = Number(process.env.NEUROLINK_PROXY_SESSION_RESET_TOLERANCE_MS ?? "");
+    return Number.isInteger(raw) && raw > 0 ? raw : 15 * 60 * 1000;
+}
+/**
+ * Derive the ordering signals for an account from its latest runtime quota.
+ *
+ * Reset freshening: a window whose reset epoch has already passed is treated
+ * as FRESH (0 used, "allowed", reset unknown) at read time — stale snapshot
+ * numbers from before the reset can never saturate or reject an account whose
+ * window Anthropic has since renewed. The snapshot itself is refreshed from
+ * live response headers the next time the account serves a request.
+ */
+function accountSortMetrics(accountKey, now, sessionSoftLimit, sessionResetToleranceMs) {
     const st = accountRuntimeState.get(accountKey);
     const q = st?.quota;
     const coolingActive = !!st?.coolingUntil && now < st.coolingUntil;
+    // resetEpochToMs returns undefined for absent OR passed resets, so a
+    // ticking window is exactly "reset !== undefined".
     const weeklyReset = resetEpochToMs(q?.weeklyResetAt, now);
     const sessionReset = resetEpochToMs(q?.sessionResetAt, now);
-    const weeklyRejected = q?.weeklyStatus === "rejected" && weeklyReset !== undefined;
-    const sessionRejected = q?.sessionStatus === "rejected" && sessionReset !== undefined;
+    const sessionTicking = sessionReset !== undefined;
+    const weeklyTicking = weeklyReset !== undefined;
+    const sessionUsed = sessionTicking ? (q?.sessionUsed ?? 0) : 0;
+    const weeklyUsed = weeklyTicking ? (q?.weeklyUsed ?? -1) : q ? 0 : -1;
+    const sessionStatus = sessionTicking
+        ? (q?.sessionStatus ?? "unknown")
+        : "allowed";
+    const weeklyStatus = weeklyTicking
+        ? (q?.weeklyStatus ?? "unknown")
+        : "allowed";
+    const saturated = sessionStatus === "throttled" ||
+        (sessionTicking && sessionUsed >= sessionSoftLimit);
     return {
-        usable: !coolingActive && !weeklyRejected && !sessionRejected,
+        usable: !coolingActive &&
+            weeklyStatus !== "rejected" &&
+            sessionStatus !== "rejected",
+        saturated,
         hasQuota: !!q,
         coolingUntil: st?.coolingUntil ?? 0,
-        weeklyReset: weeklyReset ?? Number.POSITIVE_INFINITY,
+        sessionResetBucket: sessionTicking
+            ? Math.floor(sessionReset / sessionResetToleranceMs)
+            : Number.POSITIVE_INFINITY,
         sessionReset: sessionReset ?? Number.POSITIVE_INFINITY,
-        weeklyUsed: q?.weeklyUsed ?? -1,
+        weeklyReset: weeklyReset ?? Number.POSITIVE_INFINITY,
+        weeklyUsed,
     };
 }
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
- * spend the account whose window refreshes SOONEST first, so its about-to-reset
+ * spend the window that expires SOONEST first, so its about-to-reset
  * allowance isn't wasted, then move to accounts with longer-dated 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. soonest WEEKLY (7d) reset  — the scarce, use-it-or-lose-it ceiling
- *   3. soonest SESSION (5h) reset
- *   4. highest weekly utilization — finish off the one closest to done
- *   5. configured primary account, then insertion order
+ *   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
+ *   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.
  * Cooling/rejected accounts sort last, soonest-back-to-service first, as
  * last resort.
  */
 function orderAccountsByQuota(accounts, now) {
     const primaryKey = configuredPrimaryAccountKey;
+    // Read the env-tunable thresholds once per sort: cheaper than per-compare,
+    // and a mid-sort env change can never make the comparator intransitive.
+    const sessionSoftLimit = getSessionSoftLimit();
+    const sessionResetToleranceMs = getSessionResetToleranceMs();
+    const metrics = (key) => accountSortMetrics(key, now, sessionSoftLimit, sessionResetToleranceMs);
     return [...accounts].sort((a, b) => {
-        const ma = accountSortMetrics(a.key, now);
-        const mb = accountSortMetrics(b.key, now);
+        const ma = metrics(a.key);
+        const mb = metrics(b.key);
         if (ma.usable !== mb.usable) {
             return ma.usable ? -1 : 1;
         }
@@ -444,12 +507,18 @@ function orderAccountsByQuota(accounts, now) {
         if (ma.hasQuota !== mb.hasQuota) {
             return ma.hasQuota ? 1 : -1;
         }
+        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.weeklyReset !== mb.weeklyReset) {
             return ma.weeklyReset - mb.weeklyReset;
         }
-        if (ma.sessionReset !== mb.sessionReset) {
-            return ma.sessionReset - mb.sessionReset;
-        }
         if (ma.weeklyUsed !== mb.weeklyUsed) {
             return mb.weeklyUsed - ma.weeklyUsed;
         }
@@ -1710,25 +1779,55 @@ async function loadClaudeProxyAccounts(args) {
 }
 async function executeClaudeFallbackTranslation(args) {
     const { ctx, body, tracer, requestStartTime, logProxyBody, logFinalRequest, options, providerLabel, } = args;
+    const fallbackAbortController = new AbortController();
+    let streamResult;
+    try {
+        streamResult = await withTimeout(ctx.neurolink.stream({
+            ...options,
+            abortSignal: fallbackAbortController.signal,
+        }), FALLBACK_STREAM_IDLE_TIMEOUT_MS, `Fallback ${providerLabel} initialization timed out after ${FALLBACK_STREAM_IDLE_TIMEOUT_MS}ms`);
+    }
+    catch (error) {
+        fallbackAbortController.abort(error);
+        throw error;
+    }
+    const consumeFallbackStream = async (onText) => {
+        const iterator = streamResult.stream[Symbol.asyncIterator]();
+        let collectedText = "";
+        try {
+            while (true) {
+                const { value: chunk, done } = await withTimeout(iterator.next(), FALLBACK_STREAM_IDLE_TIMEOUT_MS, `Fallback ${providerLabel} stream timed out after ${FALLBACK_STREAM_IDLE_TIMEOUT_MS}ms of inactivity`);
+                if (done) {
+                    return collectedText;
+                }
+                const text = extractText(chunk);
+                if (text) {
+                    collectedText += text;
+                    onText?.(text);
+                }
+            }
+        }
+        catch (error) {
+            fallbackAbortController.abort(error);
+            void iterator.return?.().catch(() => {
+                // Timeout/error already determines the request outcome.
+            });
+            throw error;
+        }
+    };
     if (body.stream) {
-        const streamResult = await ctx.neurolink.stream(options);
         const serializer = new ClaudeStreamSerializer(body.model, 0);
         // Eagerly consume stream so errors fire synchronously and the
         // fallback loop in tryConfiguredClaudeFallbackChain can catch them.
         const frames = [];
-        let collectedText = "";
         for (const frame of serializer.start()) {
             frames.push(frame);
         }
-        for await (const chunk of streamResult.stream) {
-            const text = extractText(chunk);
-            if (text) {
-                collectedText += text;
-                for (const frame of serializer.pushDelta(text)) {
-                    frames.push(frame);
-                }
+        const collectedText = await consumeFallbackStream((text) => {
+            for (const frame of serializer.pushDelta(text)) {
+                frames.push(frame);
             }
-        }
+        });
         const toolCalls = streamResult.toolCalls ?? [];
         if (!hasTranslatedOutput(collectedText, toolCalls)) {
             throw new Error(`Translated provider ${providerLabel} returned no content or tool calls`);
@@ -1773,14 +1872,7 @@ async function executeClaudeFallbackTranslation(args) {
         }
         return sseGenerator();
     }
-    const streamResult = await ctx.neurolink.stream(options);
-    let collectedText = "";
-    for await (const chunk of streamResult.stream) {
-        const text = extractText(chunk);
-        if (text) {
-            collectedText += text;
-        }
-    }
+    const collectedText = await consumeFallbackStream();
     if (!hasTranslatedOutput(collectedText, streamResult.toolCalls)) {
         throw new Error(`Translated provider ${providerLabel} returned no content or tool calls`);
     }
@@ -1813,6 +1905,25 @@ async function executeClaudeFallbackTranslation(args) {
     });
     return clientResponse;
 }
+async function executeClaudeFallbackWithRetry(args) {
+    let lastError;
+    for (let retry = 0; retry <= MAX_FALLBACK_NETWORK_RETRIES; retry += 1) {
+        try {
+            return await executeClaudeFallbackTranslation(args);
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryableNetworkError(error) ||
+                retry === MAX_FALLBACK_NETWORK_RETRIES) {
+                throw error;
+            }
+            const delayMs = TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS[retry] ?? 250;
+            logger.always(`[proxy] retrying fallback=${args.providerLabel} after transient network error (${retry + 1}/${MAX_FALLBACK_NETWORK_RETRIES}) in ${delayMs}ms: ${describeTransportError(error)}`);
+            await sleep(delayMs);
+        }
+    }
+    throw lastError;
+}
 async function tryConfiguredClaudeFallbackChain(args) {
     const { ctx, body, parsedFallbackRequest, modelRouter, tracer, requestStartTime, logProxyBody, logFinalRequest, } = args;
     const chain = modelRouter?.getFallbackChain() ?? [];
@@ -1830,6 +1941,7 @@ async function tryConfiguredClaudeFallbackChain(args) {
         attemptCount: fallbackPlan.attempts.slice(1).length,
         reason: "all_anthropic_accounts_exhausted",
     });
+    let lastFallbackError;
     for (const fallback of fallbackPlan.attempts.slice(1)) {
         if (!fallback.provider || !fallback.model) {
             continue;
@@ -1845,7 +1957,7 @@ async function tryConfiguredClaudeFallbackChain(args) {
                 provider: fallback.provider,
                 model: fallback.model,
             });
-            const response = await executeClaudeFallbackTranslation({
+            const response = await executeClaudeFallbackWithRetry({
                 ctx,
                 body,
                 tracer,
@@ -1895,7 +2007,7 @@ async function tryConfiguredClaudeFallbackChain(args) {
             else if (errMsg.includes("Resource exhausted")) {
                 errorClass = "provider_quota";
             }
-            logger.always(`[proxy] fallback ${fallback.provider}/${fallback.model} failed [${errorClass}]: ${errMsg}`);
+            logger.always(`[proxy] fallback ${fallback.provider}/${fallback.model} failed [${errorClass}]: ${describeTransportError(fallbackErr)}`);
             recordFallbackAttempt({
                 provider: fallback.provider,
                 model: fallback.model,
@@ -1903,23 +2015,25 @@ async function tryConfiguredClaudeFallbackChain(args) {
                 errorMessage: `[${errorClass}] ${errMsg}`,
                 durationMs: Date.now() - fallbackStart,
             });
+            lastFallbackError = `[${fallback.provider}/${fallback.model}] ${describeTransportError(fallbackErr)}`;
         }
     }
-    return { response: null };
+    return { response: null, lastErrorMessage: lastFallbackError };
 }
 async function tryAutoClaudeFallback(args) {
     const { ctx, body, tracer, requestStartTime, logProxyBody, logFinalRequest } = args;
+    const fallbackStart = Date.now();
     try {
         const parsed = parseClaudeRequest(body);
         const plan = buildProxyTranslationPlan({ provider: "anthropic", model: body.model }, [], body.model, parsed);
         logProxyRoutingPlan(logProxyBody, "auto_fallback", plan);
         const autoAttempt = plan.attempts.find((attempt) => attempt.label === "auto-provider");
         if (!autoAttempt) {
-            return null;
+            return { response: null };
         }
         logger.always("[proxy] fallback → auto-provider");
         const options = buildProxyFallbackOptions(parsed);
-        return await executeClaudeFallbackTranslation({
+        const response = await executeClaudeFallbackWithRetry({
             ctx,
             body,
             tracer,
@@ -1929,14 +2043,43 @@ async function tryAutoClaudeFallback(args) {
             options: options,
             providerLabel: "auto-provider",
         });
+        recordFallbackAttempt({
+            provider: "auto-provider",
+            model: body.model,
+            status: "success",
+            durationMs: Date.now() - fallbackStart,
+        });
+        tracer?.setFallbackInfo({
+            triggered: true,
+            provider: "auto-provider",
+            model: body.model,
+            attemptCount: 1,
+            reason: "fallback_success",
+        });
+        return { response };
     }
     catch (fallbackErr) {
-        logger.debug(`[proxy] fallback auto-provider failed: ${fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)}`);
-        return null;
+        const errorMessage = describeTransportError(fallbackErr);
+        logger.always(`[proxy] fallback auto-provider failed: ${errorMessage}`);
+        recordFallbackAttempt({
+            provider: "auto-provider",
+            model: body.model,
+            status: "failure",
+            errorMessage,
+            durationMs: Date.now() - fallbackStart,
+        });
+        tracer?.setFallbackInfo({
+            triggered: true,
+            provider: "auto-provider",
+            model: body.model,
+            attemptCount: 1,
+            reason: "fallback_failure",
+        });
+        return { response: null, lastErrorMessage: errorMessage };
     }
 }
 function buildClaudeAnthropicFailureResponse(args) {
-    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
+    const { tracer, requestStartTime, authFailureMessage, authCooldownMessage, invalidRequestFailure, sawNetworkError, sawTransientFailure, sawRateLimit, lastError, fallbackFailureMessage, orderedAccounts, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
     if (authFailureMessage && !sawRateLimit) {
         tracer?.setError("authentication_error", authFailureMessage);
         tracer?.end(401, Date.now() - requestStartTime);
@@ -1972,20 +2115,26 @@ function buildClaudeAnthropicFailureResponse(args) {
         }
     }
     if ((sawNetworkError || sawTransientFailure) && !sawRateLimit) {
+        const fallbackSuffix = fallbackFailureMessage
+            ? ` Fallback also failed: ${fallbackFailureMessage}`
+            : "";
         const msg = `All Anthropic accounts failed due to transient upstream/network errors. Last error: ${lastError instanceof Error
             ? lastError.message
-            : String(lastError ?? "unknown")}`;
+            : String(lastError ?? "unknown")}.${fallbackSuffix}`;
         tracer?.setError("transient_error", msg.slice(0, 500));
         tracer?.end(502, Date.now() - requestStartTime);
-        return buildLoggedClaudeError(502, msg);
+        return buildLoggedClaudeError(502, msg, fallbackFailureMessage ? "fallback_exhausted" : "transient_error");
     }
     if (!sawRateLimit) {
+        const fallbackSuffix = fallbackFailureMessage
+            ? ` Fallback also failed: ${fallbackFailureMessage}`
+            : "";
         const msg = `All Anthropic accounts failed. Last error: ${lastError instanceof Error
             ? lastError.message
-            : String(lastError ?? "unknown")}`;
+            : String(lastError ?? "unknown")}.${fallbackSuffix}`;
         tracer?.setError("all_accounts_failed", msg.slice(0, 500));
         tracer?.end(502, Date.now() - requestStartTime);
-        return buildLoggedClaudeError(502, msg);
+        return buildLoggedClaudeError(502, msg, fallbackFailureMessage ? "fallback_exhausted" : "all_accounts_failed");
     }
     const now = Date.now();
     const activeRateLimitCooldowns = orderedAccounts
@@ -3904,6 +4053,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
     // repaired by changing providers. Preserve the authoritative Anthropic 400
     // rather than delaying it or returning unrelated fallback output.
     if (shouldAttemptClaudeFallback(loopState)) {
+        let fallbackFailureMessage;
         const configuredFallbackResult = await tryConfiguredClaudeFallbackChain({
             ctx,
             body,
@@ -3917,10 +4067,11 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         if (configuredFallbackResult.response) {
             return configuredFallbackResult.response;
         }
+        fallbackFailureMessage = configuredFallbackResult.lastErrorMessage;
         // Try auto-provider fallback when the configured chain didn't produce a
         // response (either no chain configured, or all entries failed/deduped).
         if (!loopState.sawRateLimit) {
-            const autoFallbackResponse = await tryAutoClaudeFallback({
+            const autoFallbackResult = await tryAutoClaudeFallback({
                 ctx,
                 body,
                 tracer,
@@ -3928,10 +4079,13 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 logProxyBody,
                 logFinalRequest,
             });
-            if (autoFallbackResponse) {
-                return autoFallbackResponse;
+            if (autoFallbackResult.response) {
+                return autoFallbackResult.response;
             }
+            fallbackFailureMessage =
+                autoFallbackResult.lastErrorMessage ?? fallbackFailureMessage;
         }
+        loopState.fallbackFailureMessage = fallbackFailureMessage;
     }
     return buildClaudeAnthropicFailureResponse({
         tracer,
@@ -3943,6 +4097,7 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         sawTransientFailure: loopState.sawTransientFailure,
         sawRateLimit: loopState.sawRateLimit,
         lastError: loopState.lastError,
+        fallbackFailureMessage: loopState.fallbackFailureMessage,
         orderedAccounts,
         buildLoggedClaudeError,
         logProxyBody,
@@ -4268,6 +4423,7 @@ function isRetryableNetworkError(error) {
     return (normalized.includes("econnrefused") ||
         normalized.includes("econnreset") ||
         normalized.includes("etimedout") ||
+        normalized.includes("timed out") ||
         normalized.includes("connection error") ||
         normalized.includes("connect error") ||
         normalized.includes("fetch failed") ||
@@ -4411,4 +4567,6 @@ export const __testHooks = {
     waitForTransientAccountAvailability,
     describeTransportError,
     shouldAttemptClaudeFallback,
+    executeClaudeFallbackWithRetry,
+    buildClaudeAnthropicFailureResponse,
 };

package/dist/server/routes/openaiProxyRoutes.js

@@ -146,12 +146,53 @@ async function handleOpenAIToAnthropicBridge(args) {
             });
             return buildOpenAIErrorResponse(502, "Anthropic loopback returned empty stream body");
         }
-        // Streaming success: log now since the response body is consumed by the
-        // client. Token counts are not visible at this layer (the inner /v1/messages
-        // handler accounts them), so we omit them here.
-        await writeLifecycle(200);
-        const transformed = upstream.body.pipeThrough(createClaudeToOpenAIStreamTransform(body.model));
-        return new Response(transformed, {
+        let terminalStreamError;
+        const transformed = upstream.body.pipeThrough(createClaudeToOpenAIStreamTransform(body.model, {
+            onError: (message) => {
+                terminalStreamError = sanitizeForLog(message);
+            },
+        }));
+        const reader = transformed.getReader();
+        let lifecycleWritten = false;
+        const finishLifecycle = async (status, errorType, errorMessage) => {
+            if (lifecycleWritten) {
+                return;
+            }
+            lifecycleWritten = true;
+            await writeLifecycle(status, { errorType, errorMessage });
+        };
+        const trackedStream = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const { value, done } = await reader.read();
+                    if (done) {
+                        if (terminalStreamError) {
+                            await finishLifecycle(502, "loopback_stream_error", terminalStreamError);
+                        }
+                        else {
+                            await finishLifecycle(200);
+                        }
+                        controller.close();
+                        return;
+                    }
+                    controller.enqueue(value);
+                }
+                catch (error) {
+                    const message = sanitizeForLog(error instanceof Error ? error.message : String(error));
+                    await finishLifecycle(502, "loopback_stream_error", message);
+                    controller.error(error);
+                }
+            },
+            async cancel(reason) {
+                try {
+                    await reader.cancel(reason);
+                }
+                finally {
+                    await finishLifecycle(499, "client_cancelled", "Client cancelled the OpenAI-compatible stream");
+                }
+            },
+        });
+        return new Response(trackedStream, {
             status: 200,
             headers: {
                 "content-type": "text/event-stream",

package/dist/types/cli.d.ts

@@ -800,6 +800,8 @@ export type ProxyGuardArgs = {
     failureThreshold?: number;
     pollIntervalMs?: number;
     quiet?: boolean;
+    /** Run update checks only; never mutate client settings. */
+    updaterOnly?: boolean;
 };
 /** Arguments accepted by `neurolink proxy telemetry <subcommand>` */
 export type ProxyTelemetryArgs = {
@@ -829,6 +831,8 @@ export type ProxyState = {
     accountAllowlist?: string[];
     /** Optional fail-open guard PID that reverts Claude settings if proxy dies */
     guardPid?: number;
+    /** Dedicated updater PID for launchd-managed proxy installations. */
+    updaterPid?: number;
     /** How the proxy was launched — "launchd" if installed as service, "manual" otherwise */
     managedBy?: "launchd" | "manual";
     /** Whether the proxy is running in transparent passthrough mode */

package/dist/types/conversation.d.ts

@@ -451,6 +451,42 @@ export type AgenticLoopReportMetadata = {
         endDate: string;
     };
 };
+/**
+ * Session list item for CLI/API listing
+ * Extends SessionMetadata with additional display information
+ */
+export type SessionListItem = SessionMetadata & {
+    /** User identifier associated with this session */
+    userId?: string;
+    /** Total number of messages in this session */
+    messageCount: number;
+    /** Human-readable time since last activity (e.g., "2 hours ago") */
+    lastActive?: string;
+};
+/**
+ * Complete session export format for backup/analytics
+ * Contains full session data including all messages
+ */
+export type SessionExport = {
+    /** Session identifier */
+    sessionId: string;
+    /** Session title/description */
+    title?: string;
+    /** User identifier */
+    userId?: string;
+    /** When session was created (ISO 8601) */
+    createdAt: string;
+    /** When session was last updated (ISO 8601) */
+    updatedAt: string;
+    /** Complete message history */
+    messages: ChatMessage[];
+    /** Export metadata */
+    exportMetadata?: {
+        exportedAt: string;
+        exportFormat: "json" | "csv";
+        neuroLinkVersion?: string;
+    };
+};
 /**
  * Base conversation metadata (shared fields across all conversation types)
  * Contains essential conversation information without heavy data arrays

package/dist/types/conversationMemoryInterface.d.ts

@@ -3,7 +3,7 @@
  * Both ConversationMemoryManager and RedisConversationMemoryManager
  * should implement this type.
  */
-import type { ChatMessage, ConversationMemoryConfig, ConversationMemoryStats, SessionMemory, StoreConversationTurnOptions } from "./conversation.js";
+import type { ChatMessage, ConversationMemoryConfig, ConversationMemoryStats, SessionListItem, SessionMemory, StoreConversationTurnOptions } from "./conversation.js";
 /**
  * Common type for all conversation memory manager implementations.
  * Provides a consistent API for storing, retrieving, and managing conversation history.
@@ -24,6 +24,10 @@ export type IConversationMemoryManager = {
     clearAllSessions(): Promise<void> | void;
     /** Get memory statistics */
     getStats(): Promise<ConversationMemoryStats> | ConversationMemoryStats;
+    /** List all sessions with metadata (optional - for session management) */
+    listSessions?(userId?: string): Promise<SessionListItem[]>;
+    /** List all sessions with metadata (optional - for session management) */
+    listSessions?(userId?: string): Promise<SessionListItem[]>;
     /** Get raw messages array for a session (no context filtering or summarization) */
     getSessionMessages(sessionId: string, userId?: string): Promise<ChatMessage[]>;
     /** Replace the entire messages array for a session */

package/dist/types/proxy.d.ts

@@ -518,6 +518,7 @@ export type AnthropicLoopState = {
     } | null;
     authFailureMessage: string | null;
     authCooldownMessage: string | null;
+    fallbackFailureMessage?: string;
     attemptNumber: number;
 };
 export type AnthropicUpstreamBody = {
@@ -910,6 +911,26 @@ export type QuietStatus = {
     lastActivityAt: Date | null;
     silenceDurationMs: number;
 };
+/** In-process proxy request activity used to protect streaming restarts. */
+export type ProxyActivitySnapshot = {
+    activeRequests: number;
+    lastActivityAt: Date | null;
+};
+/** Activity payload exposed by the running proxy status endpoint. */
+export type ProxyRuntimeActivity = {
+    activeRequests: number;
+    lastActivityAt: string | null;
+};
+/** Request metadata retained by the HTTP adapter for terminal error logging. */
+export type RuntimeRequestMetadata = {
+    requestId: string;
+    method: string;
+    path: string;
+    startedAt: number;
+    model: string;
+    stream: boolean;
+    toolCount: number;
+};
 /** Accumulated upstream body capture from a raw stream. */
 export type RawStreamCapture = {
     totalBytes: number;
@@ -1073,6 +1094,34 @@ export type UpdateState = {
     lastUpdateAt: string | null;
     lastUpdateVersion: string | null;
 };
+/** Supported global package managers for proxy self-updates. */
+export type GlobalInstallerKind = "npm" | "pnpm";
+/** Result of probing one global package-manager executable. */
+export type GlobalInstallerProbe = {
+    kind: GlobalInstallerKind;
+    bin: string;
+    version?: string;
+    globalRoot?: string;
+    globalBinDir?: string;
+    working: boolean;
+    installable: boolean;
+    matchesCurrentInstall: boolean;
+    reason?: string;
+};
+/** Selected package manager plus all candidates considered. */
+export type GlobalInstallerResolution = {
+    installer?: GlobalInstallerProbe;
+    tried: GlobalInstallerProbe[];
+};
+/** Injectable command runner used by global-installer tests. */
+export type GlobalInstallerExecFile = typeof import("node:child_process").execFileSync;
+/** Overrides used while resolving the global package manager. */
+export type ResolveGlobalInstallerOptions = {
+    entryScript?: string;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    execFileSync?: GlobalInstallerExecFile;
+};
 /** Shape of the dynamically-imported js-yaml module. `dump` is optional —
  *  read-only consumers (proxy config loader) only need `load`; writers
  *  (CLI primary-account commands) check `dump` before calling. */