@juspay/neurolink 10.12.7 → 10.12.9

package/dist/types/proxy.d.ts

@@ -430,6 +430,21 @@ export type ProxyAccountRoutingStrategy = (typeof PROXY_ACCOUNT_ROUTING_STRATEGI
 export type ProxyAccountRoutingMode = (typeof PROXY_ACCOUNT_ROUTING_MODES)[number];
 export type ProxyAccountRoutingReason = (typeof PROXY_ACCOUNT_ROUTING_REASONS)[number];
 export type ProxyAccountType = (typeof PROXY_ACCOUNT_TYPES)[number];
+export type ProxyQuotaFreshness = "unknown" | "fresh" | "stale_known" | "refresh_due";
+export type ProxyQuotaRefreshReason = "startup_unknown" | "handoff_prewarm" | "ambiguous_snapshot" | "manual";
+export type ProxyQuotaSaturationKind = "none" | "soft" | "hard";
+export type ProxyTransportScope = "shared_provider_transport" | "connection_transport" | "account_specific";
+export type ProxyNetworkTransportScope = Exclude<ProxyTransportScope, "account_specific">;
+export type ProxyProviderTransportProbeOutcome = "recovered" | "failed" | "abandoned";
+export type ProxyProviderTransportPermit = {
+    allowed: true;
+    probe: boolean;
+    generation: number;
+} | {
+    allowed: false;
+    errorCode: string | null;
+    transportScope: ProxyNetworkTransportScope;
+};
 export type ProxyAccountRoutingCandidate = {
     account: string;
     accountType: ProxyAccountType;
@@ -440,6 +455,15 @@ export type ProxyAccountRoutingCandidate = {
     saturated: boolean;
     quotaObserved: boolean;
     quotaStale: boolean;
+    quotaFreshness?: ProxyQuotaFreshness;
+    refreshNeeded?: boolean;
+    refreshReason?: ProxyQuotaRefreshReason | null;
+    refreshInFlight?: boolean;
+    lastRefreshAttemptAt?: number | null;
+    lastRefreshSuccessAt?: number | null;
+    nextRefreshEligibleAt?: number | null;
+    saturationKind?: ProxyQuotaSaturationKind;
+    softLimitOverrideReason?: "overage" | "weekly_expiry" | null;
     quotaLastUpdated: number | null;
     quotaAgeMs: number | null;
     coolingActive: boolean;
@@ -478,7 +502,17 @@ export type ProxyAccountSortMetrics = {
     usable: boolean;
     saturated: boolean;
     hasQuota: boolean;
+    quotaEvidenceRank: number;
     quotaStale: boolean;
+    quotaFreshness: ProxyQuotaFreshness;
+    refreshNeeded: boolean;
+    refreshReason: ProxyQuotaRefreshReason | null;
+    refreshInFlight: boolean;
+    lastRefreshAttemptAt: number | null;
+    lastRefreshSuccessAt: number | null;
+    nextRefreshEligibleAt: number | null;
+    saturationKind: ProxyQuotaSaturationKind;
+    softLimitOverrideReason: "overage" | "weekly_expiry" | null;
     quotaLastUpdated: number | null;
     quotaAgeMs: number | null;
     coolingActive: boolean;
@@ -514,6 +548,8 @@ export type RequestLogEntry = {
     errorMessage?: string;
     /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
     errorCode?: string;
+    /** Whether changing credentials can affect this transport failure. */
+    transportScope?: ProxyTransportScope;
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
@@ -545,6 +581,8 @@ export type RequestAttemptLogEntry = {
     errorMessage?: string;
     /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
     errorCode?: string;
+    /** Whether changing credentials can affect this transport failure. */
+    transportScope?: ProxyTransportScope;
     /** Whether this failed attempt may be retried without changing the request. */
     retryable?: boolean;
     /** Distinguishes short-lived admission throttles from exhausted quota windows. */
@@ -579,11 +617,15 @@ export type ClaudeFinalRequestLogger = (status: number, accountLabel: string, ac
     outputTokens?: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+    errorCode?: string;
+    transportScope?: ProxyTransportScope;
 }) => void;
 export type ClaudeLoggedErrorBuilder = (status: number, message: string, errorType?: string, extra?: {
     account?: string;
     accountType?: string;
     attempt?: number;
+    errorCode?: string;
+    transportScope?: ProxyTransportScope;
 }) => ClaudeErrorResponse;
 export type ClaudeRequestRuntimeContext = {
     tracer?: ProxyTracer;
@@ -603,6 +645,7 @@ export type AnthropicAttemptLogger = (status: number, errorType?: string, errorM
     retryable?: boolean;
     /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
     errorCode?: string;
+    transportScope?: ProxyTransportScope;
     rateLimitKind?: "transient" | "quota";
     cooldownReason?: "transient" | "session" | "weekly" | "unified";
     /** Override for nested retries whose attempt starts after this logger. */
@@ -624,6 +667,8 @@ export type AnthropicLoopState = {
     authCooldownMessage: string | null;
     fallbackFailureMessage?: string;
     attemptNumber: number;
+    lastTransportErrorCode?: string;
+    lastTransportScope?: ProxyNetworkTransportScope;
 };
 export type AnthropicUpstreamBody = {
     bodyStr: string;
@@ -765,6 +810,8 @@ export type TransientRateLimitRetryBudget = {
 export type AnthropicUpstreamFetchResult = {
     continueLoop: boolean;
     retrySameAccount?: boolean;
+    transportScope?: ProxyNetworkTransportScope;
+    errorCode?: string;
     /** When set, the caller should wait this many ms before retrying (from upstream retry-after). */
     retryAfterMs?: number;
     /** Set on a genuine 429: how long / why to cool this account before rotating. */
@@ -1033,6 +1080,35 @@ export type AccountUsageFetchResult = {
     error: string;
     status?: number;
 };
+export type ProxyQuotaRefreshRuntimeState = {
+    inFlight: boolean;
+    lastAttemptAt?: number;
+    lastSuccessAt?: number;
+    nextEligibleAt?: number;
+    consecutiveFailures: number;
+    lastFailureReason?: string;
+    lastCompletedTrigger?: string;
+    coalesced: number;
+};
+export type ProxyQuotaRefreshMetrics = {
+    attempted: number;
+    succeeded: number;
+    failed: number;
+    coalesced: number;
+    backoffSuppressed: number;
+    triggerDeduplicated: number;
+};
+export type ProxyQuotaRefreshRunResult = {
+    kind: "completed";
+    result: AccountUsageFetchResult;
+    /** Lower bound for the freshness of the returned usage snapshot. */
+    startedAt: number;
+} | {
+    kind: "backoff";
+    nextEligibleAt: number;
+} | {
+    kind: "not_due";
+};
 /** Per-account result inside a GET /limits response. */
 export type ProxyLimitsAccountResult = {
     /** Account label (quota-store key). */
@@ -1053,6 +1129,8 @@ export type ProxyLimitsRefreshResponse = {
     /** True when served from stored state without contacting Anthropic. */
     snapshot: boolean;
     results: ProxyLimitsAccountResult[];
+    /** Process-local refresh activity; contains no credentials or response body. */
+    refreshMetrics?: ProxyQuotaRefreshMetrics;
 };
 /**
  * Provenance of the quota numbers attached to a single proxy response.
@@ -1518,6 +1596,7 @@ export type ProxyAnalysisReport = {
         errors: number;
         errorTypes: Record<string, number>;
         errorCodes: Record<string, number>;
+        transportScopes: Record<string, number>;
     };
     rateLimits: {
         attemptRateLimits: number;

package/dist/types/utilities.d.ts

@@ -279,3 +279,32 @@ export type JsonCoercionResult = {
      */
     truncated: boolean;
 };
+/**
+ * Decision returned by `recoverScalarRoot`. Each caller applies it to its own
+ * result shape and logger prefix, preserving its existing warning behaviour:
+ *
+ *   - `empty`     — the text is a JSON-encoded empty string (an EMPTY
+ *                   completion, not a recovered scalar). Callers normalize to a
+ *                   true empty.
+ *   - `accepted`  — a scalar root the caller's schema accepts; safe to publish
+ *                   as `structuredData`.
+ *   - `rejected`  — a scalar root the caller's schema rejects (e.g. a raw
+ *                   string under an object schema — the shape a truncated
+ *                   response degrades to). Do NOT publish it.
+ *   - `nullish`   — the text is the JSON literals `null`/`undefined`; there is
+ *                   no structured value to publish.
+ *   - `not-json`  — the text is not JSON at all.
+ */
+export type ScalarRecoveryDecision = {
+    kind: "empty";
+} | {
+    kind: "accepted";
+    value: unknown;
+} | {
+    kind: "rejected";
+    value: unknown;
+} | {
+    kind: "nullish";
+} | {
+    kind: "not-json";
+};

package/dist/utils/json/coerce.d.ts

@@ -1,4 +1,24 @@
-import type { JsonCoercionResult, ValidationSchema } from "../../types/index.js";
+import type { JsonCoercionResult, ScalarRecoveryDecision, ValidationSchema } from "../../types/index.js";
+/**
+ * Does `value` satisfy `schema`? A schema we cannot validate with (absent, or
+ * without a Zod-style `safeParse`) accepts everything — callers use this as a
+ * gate, not as proof, so an unknown schema must never block a value.
+ *
+ * Exists so the consumers of coerceJsonToSchema can refuse to publish a
+ * recovered value as `structuredData` when the caller's schema rejects it —
+ * e.g. a raw *string* under an object schema, which is the shape a truncated
+ * response degrades to.
+ */
+export declare function schemaAccepts(schema: ValidationSchema | undefined, value: unknown): boolean;
+/**
+ * Recover a JSON *scalar* root (string/number/boolean) from model text. The
+ * object/array case is handled by `coerceJsonToSchema`; this covers the
+ * residual scalar root after that path returns null. Encapsulates the JSON
+ * parsing, the empty-string normalization, and the `schemaAccepts` gate so the
+ * same policy cannot drift between consumers (`neurolink.recoverStructuredData`
+ * and `GenerationHandler.coerceTextMode`).
+ */
+export declare function recoverScalarRoot(text: string, schema: ValidationSchema | undefined): ScalarRecoveryDecision;
 /**
  * Try to produce canonical JSON from `text`. Returns null when no JSON object
  * could be recovered (caller should then keep the raw text).

package/dist/utils/json/coerce.js

@@ -23,6 +23,48 @@ import { nextBalancedJsonSpan } from "./extract.js";
 function hasSafeParse(schema) {
     return typeof schema.safeParse === "function";
 }
+/**
+ * Does `value` satisfy `schema`? A schema we cannot validate with (absent, or
+ * without a Zod-style `safeParse`) accepts everything — callers use this as a
+ * gate, not as proof, so an unknown schema must never block a value.
+ *
+ * Exists so the consumers of coerceJsonToSchema can refuse to publish a
+ * recovered value as `structuredData` when the caller's schema rejects it —
+ * e.g. a raw *string* under an object schema, which is the shape a truncated
+ * response degrades to.
+ */
+export function schemaAccepts(schema, value) {
+    if (!schema || !hasSafeParse(schema)) {
+        return true;
+    }
+    return schema.safeParse(value).success;
+}
+/**
+ * Recover a JSON *scalar* root (string/number/boolean) from model text. The
+ * object/array case is handled by `coerceJsonToSchema`; this covers the
+ * residual scalar root after that path returns null. Encapsulates the JSON
+ * parsing, the empty-string normalization, and the `schemaAccepts` gate so the
+ * same policy cannot drift between consumers (`neurolink.recoverStructuredData`
+ * and `GenerationHandler.coerceTextMode`).
+ */
+export function recoverScalarRoot(text, schema) {
+    try {
+        const scalar = JSON.parse(text);
+        if (scalar === "") {
+            return { kind: "empty" };
+        }
+        if (scalar === null || scalar === undefined) {
+            return { kind: "nullish" };
+        }
+        if (schemaAccepts(schema, scalar)) {
+            return { kind: "accepted", value: scalar };
+        }
+        return { kind: "rejected", value: scalar };
+    }
+    catch {
+        return { kind: "not-json" };
+    }
+}
 /**
  * Parse `candidate` as JSON, repairing common escaping mistakes on failure.
  * Returns the parsed value plus whether jsonrepair had to alter the text.
@@ -51,6 +93,34 @@ function parseOrRepair(candidate) {
 }
 /** Bounds the recursive nested-string unwrap against pathological inputs. */
 const MAX_NESTED_UNWRAP_DEPTH = 6;
+/** Bounds the structural back-off when salvaging a truncated root object. */
+const MAX_SALVAGE_TRIMS = 8;
+/**
+ * Last-resort recovery for output cut off mid-JSON: walk the unclosed root span
+ * backwards to successively earlier structural boundaries (`,` / `}` / `]`) and
+ * re-attempt parse+repair at each one. Truncation can land somewhere jsonrepair
+ * cannot close on its own (inside an escape, a half-written key, a dangling
+ * separator); dropping back to the last completed field gives it a repairable
+ * prefix. Returns a PARTIAL object — the fields the model did finish — so a
+ * truncated response degrades to an incomplete object rather than to raw text.
+ */
+function salvageTruncatedRoot(span) {
+    let candidate = span;
+    for (let i = 0; i < MAX_SALVAGE_TRIMS && candidate.length > 1; i++) {
+        const cut = Math.max(candidate.lastIndexOf(","), candidate.lastIndexOf("}"), candidate.lastIndexOf("]"));
+        if (cut <= 0) {
+            break;
+        }
+        candidate = candidate.slice(0, cut);
+        const outcome = parseOrRepair(candidate);
+        if (outcome !== undefined &&
+            outcome.value !== null &&
+            typeof outcome.value === "object") {
+            return outcome.value;
+        }
+    }
+    return undefined;
+}
 /**
  * Recursively replace any string-valued field whose content is itself a JSON
  * object/array with the parsed value. Models sometimes double-encode a NESTED
@@ -135,30 +205,54 @@ export function coerceJsonToSchema(text, schema) {
     //  3. first "{" or "[" to end of text (TRUNCATED output —
     //     finishReason=length — where the closing bracket was cut off;
     //     jsonrepair closes it)
-    // `truncated` marks the first-open-to-end candidate: it is only reachable
-    // when no balanced span and no first-to-last span matched, i.e. there was no
-    // closing bracket at all — the signature of token-truncated output.
+    // `truncated` marks a candidate that could only come from output cut short:
+    // the first-open-to-end span, and — when the ROOT bracket never closes —
+    // every other candidate too, since all of them are then partial views of an
+    // unfinished document.
+    //
+    // `rootAligned` marks candidates that start at the document's first opening
+    // bracket, i.e. at the real root. Candidates are ordered root-aligned FIRST.
+    // On truncated output the root brace never balances, so the balanced scan
+    // walks on and matches brackets that live INSIDE a string value (`[step 1]`
+    // in a shell script, say) — a syntactically fine but semantically bogus
+    // array. Preferring the root keeps the partial real object ahead of that.
     const candidates = [];
+    const openIndexes = [text.indexOf("{"), text.indexOf("[")].filter((i) => i >= 0);
+    const firstOpen = openIndexes.length > 0 ? Math.min(...openIndexes) : -1;
+    let rootClosed = false;
     let searchFrom = 0;
     for (;;) {
         const found = nextBalancedJsonSpan(text, searchFrom);
         if (!found) {
             break;
         }
-        candidates.push({ text: found.span, truncated: false });
+        const start = found.end - found.span.length;
+        if (start === firstOpen) {
+            rootClosed = true;
+        }
+        candidates.push({
+            text: found.span,
+            truncated: false,
+            rootAligned: start === firstOpen,
+        });
         searchFrom = found.end;
     }
-    const openIndexes = [text.indexOf("{"), text.indexOf("[")].filter((i) => i >= 0);
-    const firstOpen = openIndexes.length > 0 ? Math.min(...openIndexes) : -1;
+    // No balanced span starts at the root bracket → the document is unclosed.
+    const rootUnclosed = firstOpen >= 0 && !rootClosed;
     const lastClose = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
     if (firstOpen >= 0 && lastClose > firstOpen) {
         candidates.push({
             text: text.slice(firstOpen, lastClose + 1),
-            truncated: false,
+            truncated: rootUnclosed,
+            rootAligned: true,
         });
     }
     if (firstOpen >= 0) {
-        candidates.push({ text: text.slice(firstOpen), truncated: true });
+        candidates.push({
+            text: text.slice(firstOpen),
+            truncated: true,
+            rootAligned: true,
+        });
     }
     // JSON-string-literal wrapper: some providers double-encode and return the
     // object as a JSON *string* (e.g. `"{\"k\":1}"`). Unwrap one layer and add
@@ -174,7 +268,11 @@ export function coerceJsonToSchema(text, schema) {
                     if (!innerSpan) {
                         break;
                     }
-                    candidates.push({ text: innerSpan.span, truncated: false });
+                    candidates.push({
+                        text: innerSpan.span,
+                        truncated: false,
+                        rootAligned: false,
+                    });
                     innerFrom = innerSpan.end;
                 }
             }
@@ -183,11 +281,20 @@ export function coerceJsonToSchema(text, schema) {
             // not a string literal — ignore
         }
     }
+    // Stable partition: root-aligned candidates first. Only the ORDER changes —
+    // no candidate is dropped — so the multi-object "prefer the most complete
+    // schema-valid candidate" selection below is unaffected (it is order
+    // independent), while the unschema'd first-parseable-wins path and the
+    // `firstValid` fallback now favour the document's real root.
+    const ordered = [
+        ...candidates.filter((c) => c.rootAligned),
+        ...candidates.filter((c) => !c.rootAligned),
+    ];
     let firstValid;
     const schemaValid = [];
     const hasSchema = !!(schema && hasSafeParse(schema));
     const seen = new Set();
-    for (const candidate of candidates) {
+    for (const candidate of ordered) {
         if (seen.has(candidate.text)) {
             continue;
         }
@@ -202,6 +309,7 @@ export function coerceJsonToSchema(text, schema) {
             value: outcome.value,
             repaired: outcome.repaired,
             truncated: candidate.truncated,
+            rootAligned: candidate.rootAligned,
         };
         if (firstValid === undefined) {
             firstValid = record;
@@ -229,6 +337,7 @@ export function coerceJsonToSchema(text, schema) {
                     value: unwrapped.value,
                     repaired: true,
                     truncated: candidate.truncated,
+                    rootAligned: candidate.rootAligned,
                 });
             }
             else if (
@@ -247,6 +356,7 @@ export function coerceJsonToSchema(text, schema) {
                     value: outcome.value[0],
                     repaired: true,
                     truncated: candidate.truncated,
+                    rootAligned: candidate.rootAligned,
                 });
             }
         }
@@ -261,7 +371,34 @@ export function coerceJsonToSchema(text, schema) {
             ? cur
             : best)
         : undefined;
-    const chosen = schemaMatch ?? firstValid;
+    let chosen = schemaMatch ?? firstValid;
+    // Salvage the root when the document is unclosed AND nothing trustworthy came
+    // out of it: either nothing parsed at all, or the only parseable candidate is
+    // a bracket pair scraped from INSIDE a string value (not root-aligned, not
+    // schema-valid) — the `["step 1"]`-from-a-shell-script case. Backing off to
+    // the last completed field yields a PARTIAL OBJECT flagged `truncated`,
+    // instead of a bogus value or raw text degrading to a string.
+    if (rootUnclosed &&
+        schemaMatch === undefined &&
+        (chosen === undefined || !chosen.rootAligned)) {
+        const salvaged = salvageTruncatedRoot(text.slice(firstOpen));
+        if (salvaged !== undefined) {
+            logger.debug("[coerceJsonToSchema] salvaged a partial truncated object", {
+                textLength: text.length,
+            });
+            chosen = {
+                value: salvaged,
+                repaired: true,
+                truncated: true,
+                rootAligned: true,
+            };
+        }
+        else if (chosen !== undefined) {
+            // Nothing salvageable, but we still know the output was truncated —
+            // never report a candidate scraped from a truncated document as complete.
+            chosen = { ...chosen, truncated: true };
+        }
+    }
     if (chosen === undefined) {
         return null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "10.12.7",
+  "version": "10.12.9",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -135,6 +135,7 @@
     "test:file-detector-magic-bytes": "npx tsx test/continuous-test-suite-file-detector-magic-bytes.ts",
     "test:json": "npx tsx test/continuous-test-suite-json.ts",
     "test:json-e2e": "npx tsx test/continuous-test-suite-json-e2e.ts",
+    "test:coerce-truncation": "npx tsx test/continuous-test-suite-coerce-truncation.ts",
     "test:workflow": "npx tsx test/continuous-test-suite-workflow.ts",
     "test:hitl": "npx tsx test/continuous-test-suite-hitl.ts",
     "test:analytics": "npx tsx test/continuous-test-suite-analytics.ts",