@juspay/neurolink 12.27.0 → 12.27.1

package/dist/proxy/proxyTracer.d.ts

@@ -127,6 +127,15 @@ export declare function recordFallbackAttempt(attrs: {
     errorMessage?: string;
     durationMs: number;
 }): void;
+/** Reset leg-health state between tests. */
+export declare const __fallbackLegHealthTestHooks: {
+    threshold: number;
+    maxTrackedLegs: number;
+    trackedCount: () => number;
+    reset: () => void;
+    streakOf: (legKey: string) => number;
+    isReported: (legKey: string) => boolean;
+};
 export { ProxyTracer };
 /** Standard SERVER span covers every proxy door, including parsing and admission failures. */
 export declare function startProxyHttpTrace(metadata: RuntimeRequestMetadata, headers: Record<string, string>): {

package/dist/proxy/proxyTracer.js

@@ -757,7 +757,96 @@ class ProxyTracer {
         return this.bridge.injectContext({}, trace.setSpan(context.active(), this.rootSpan));
     }
 }
+/**
+ * Consecutive failures a configured fallback leg may accumulate before the
+ * proxy says so out loud.
+ *
+ * A leg that is attempted and never succeeds is invisible today: the counters
+ * record every attempt and every failure, but nothing reads them back, so the
+ * condition surfaces only if an operator happens to query telemetry. Meanwhile
+ * every request falls through to the next leg, which can bill on a different
+ * account at a different rate, so the first symptom is a cost change rather
+ * than an error. Twenty is low enough to catch a dead leg within seconds of
+ * sustained traffic and high enough that ordinary account rotation or a brief
+ * cooldown never trips it.
+ */
+const DEAD_FALLBACK_LEG_THRESHOLD = 20;
+/**
+ * Upper bound on tracked legs.
+ *
+ * Not every key comes from the configured chain. The auto-provider path records
+ * `auto-provider/<requested model>`, and the requested model is whatever the
+ * caller asked for, so a client that fails requests under varying model names
+ * mints a new key each time. Without a bound these collections grow for the
+ * lifetime of the process. The cap is far above any real fallback chain, so a
+ * genuine leg is never evicted in practice.
+ */
+const MAX_TRACKED_FALLBACK_LEGS = 256;
+/** Consecutive failures per `provider/model`, reset by any success. */
+const fallbackFailureStreaks = new Map();
+/** Legs already reported, so a dead leg is stated once and not once per turn. */
+const reportedDeadFallbackLegs = new Set();
+/**
+ * Record a streak, evicting the least recently touched leg past the cap.
+ *
+ * `Map` and `Set` iterate in insertion order and re-setting an existing key does
+ * not move it, so a key is deleted before being re-added. That makes recency the
+ * eviction order and keeps a leg that is actively failing from being dropped in
+ * favour of a stale one.
+ */
+function touchFallbackLegStreak(legKey, streak) {
+    fallbackFailureStreaks.delete(legKey);
+    fallbackFailureStreaks.set(legKey, streak);
+    while (fallbackFailureStreaks.size > MAX_TRACKED_FALLBACK_LEGS) {
+        const oldest = fallbackFailureStreaks.keys().next();
+        if (oldest.done) {
+            break;
+        }
+        fallbackFailureStreaks.delete(oldest.value);
+        reportedDeadFallbackLegs.delete(oldest.value);
+    }
+}
+/**
+ * Report a fallback leg that has stopped serving, and its recovery.
+ *
+ * Deliberately keyed per leg rather than globally: a second leg going dark must
+ * still be reported while the first is known dead.
+ */
+function trackFallbackLegHealth(legKey, status, errorMessage) {
+    if (status === "success") {
+        fallbackFailureStreaks.delete(legKey);
+        if (reportedDeadFallbackLegs.delete(legKey)) {
+            logger.always(`[proxy] fallback ${legKey} is serving again after being reported dead`);
+        }
+        return;
+    }
+    const streak = (fallbackFailureStreaks.get(legKey) ?? 0) + 1;
+    touchFallbackLegStreak(legKey, streak);
+    if (streak < DEAD_FALLBACK_LEG_THRESHOLD) {
+        return;
+    }
+    if (reportedDeadFallbackLegs.has(legKey)) {
+        return;
+    }
+    // Marked reported only once the report is out. Marking first meant a throwing
+    // logger — swallowed by the caller's catch — silenced the leg permanently,
+    // which is the one outcome this whole mechanism exists to prevent.
+    logger.always(`[proxy] fallback ${legKey} has failed ${streak} consecutive attempts with ` +
+        `no success — this leg is not serving. Traffic is falling through to the ` +
+        `next leg in the chain, which may bill differently. Check the account's ` +
+        `quota and credentials` +
+        (errorMessage ? `; last error: ${errorMessage.slice(0, 200)}` : ""));
+    reportedDeadFallbackLegs.add(legKey);
+}
 export function recordFallbackAttempt(attrs) {
+    // Leg health is tracked outside the metrics try/catch: a telemetry failure
+    // must not be the reason an operator never hears that a leg is dead.
+    try {
+        trackFallbackLegHealth(`${attrs.provider}/${attrs.model}`, attrs.status, attrs.errorMessage);
+    }
+    catch {
+        // Never let health reporting break a request.
+    }
     try {
         const m = getProxyMetrics();
         const labels = { provider: attrs.provider, model: attrs.model };
@@ -776,6 +865,18 @@ export function recordFallbackAttempt(attrs) {
         // metrics are best-effort
     }
 }
+/** Reset leg-health state between tests. */
+export const __fallbackLegHealthTestHooks = {
+    threshold: DEAD_FALLBACK_LEG_THRESHOLD,
+    maxTrackedLegs: MAX_TRACKED_FALLBACK_LEGS,
+    trackedCount: () => fallbackFailureStreaks.size,
+    reset: () => {
+        fallbackFailureStreaks.clear();
+        reportedDeadFallbackLegs.clear();
+    },
+    streakOf: (legKey) => fallbackFailureStreaks.get(legKey) ?? 0,
+    isReported: (legKey) => reportedDeadFallbackLegs.has(legKey),
+};
 export { ProxyTracer };
 /** Standard SERVER span covers every proxy door, including parsing and admission failures. */
 export function startProxyHttpTrace(metadata, headers) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.27.0",
+  "version": "12.27.1",
   "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": {