@juspay/neurolink 12.28.4 → 12.29.0

package/dist/utils/logger.js

@@ -13,6 +13,19 @@
  * - Structured data support for complex objects
  * - Tabular data display
  */
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * Identifies which NeuroLink instance is emitting, for the async operation
+ * currently on the stack. Populated by `runInInstanceScope()` — which the SDK
+ * entry points (`generate`, `stream`, `generateText`) wrap their bodies in —
+ * so a log call anywhere beneath them can be attributed without every call
+ * site threading an instance through.
+ *
+ * Empty for logs emitted outside any call (construction, background MCP
+ * reconnects, module init). Those stay unattributed rather than being charged
+ * to whichever instance happens to hold the global sink.
+ */
+const instanceLogScope = new AsyncLocalStorage();
 // OTel trace context for log correlation (optional — gracefully no-ops if OTel not initialized)
 let traceApi = null;
 let traceApiPromise = null;
@@ -48,6 +61,30 @@ function argvRequestsJsonOutput() {
     return argv.some((arg, index) => (FORMAT_FLAGS.includes(arg) && argv[index + 1] === "json") ||
         FORMAT_FLAGS.some((flag) => arg === `${flag}=json`));
 }
+/**
+ * Best-effort isolated copy of a log call's `data` payload for one consumer.
+ * `NeuroLinkLogger.log()` hands the same call's data to every scoped emitter
+ * for the active instance plus the process-wide sink — a designed, supported
+ * multi-consumer configuration — so a copy per consumer is what keeps one
+ * consumer's in-place mutation (e.g. redacting a field before forwarding it)
+ * from silently corrupting what a sibling consumer, or stored log history,
+ * observes. Non-object values need no copy — they are already by-value.
+ * Values `structuredClone` cannot handle (functions, etc.) are handed through
+ * unchanged rather than dropped: isolation is not achievable for those
+ * without lossy serialization, so that narrow case keeps the old
+ * shared-reference behavior instead of losing the payload.
+ */
+function cloneLogData(data) {
+    if (data === null || typeof data !== "object") {
+        return data;
+    }
+    try {
+        return structuredClone(data);
+    }
+    catch {
+        return data;
+    }
+}
 class NeuroLinkLogger {
     logLevel = "info";
     logs = [];
@@ -55,6 +92,7 @@ class NeuroLinkLogger {
     isDebugMode;
     diagnosticsToStderr = false;
     eventEmitter;
+    scopedEmitters = new Map();
     constructor() {
         // Cache debug mode check to avoid repeated array searches
         this.isDebugMode =
@@ -90,6 +128,75 @@ class NeuroLinkLogger {
         }
         this.eventEmitter = undefined;
     }
+    /**
+     * Runs `fn` with every log call beneath it attributed to `instanceId`.
+     *
+     * Nesting is safe and expected: a host turn that delegates to a worker ends
+     * up with the worker's id on top for the duration of the worker's call, and
+     * the host's id restored afterwards. Re-entering with the same id is a
+     * no-op in effect.
+     *
+     * @param instanceId - Identifier of the emitting NeuroLink instance
+     * @param fn - Work to run inside the scope
+     * @returns Whatever `fn` returns
+     */
+    runInInstanceScope(instanceId, fn) {
+        return instanceLogScope.run(instanceId, fn);
+    }
+    /**
+     * The instance id currently attributed, or undefined outside any scope.
+     */
+    getInstanceScope() {
+        return instanceLogScope.getStore();
+    }
+    /**
+     * Subscribes `emitter` to log events emitted by one instance only.
+     *
+     * Unlike {@link setEventEmitter} — a single process-wide sink that receives
+     * everything — a scoped emitter receives only events logged inside that
+     * instance's {@link runInInstanceScope}. Several emitters may share an id.
+     *
+     * @param instanceId - Instance whose events this emitter should receive
+     * @param emitter - The sink to subscribe
+     */
+    addScopedEventEmitter(instanceId, emitter) {
+        const existing = this.scopedEmitters.get(instanceId);
+        if (existing) {
+            existing.add(emitter);
+            return;
+        }
+        this.scopedEmitters.set(instanceId, new Set([emitter]));
+    }
+    /**
+     * Unsubscribes a scoped emitter. Must be called when the owning instance is
+     * disposed, or the emitter — and everything it closes over — is retained by
+     * the process-global logger for the lifetime of the process.
+     *
+     * @param instanceId - Instance the emitter was registered against
+     * @param emitter - The sink to unsubscribe
+     */
+    removeScopedEventEmitter(instanceId, emitter) {
+        const existing = this.scopedEmitters.get(instanceId);
+        if (!existing) {
+            return;
+        }
+        existing.delete(emitter);
+        if (existing.size === 0) {
+            this.scopedEmitters.delete(instanceId);
+        }
+    }
+    /**
+     * Drops every scoped emitter registered against an instance.
+     *
+     * Called from `NeuroLink.dispose()`: the registry lives on the
+     * process-global logger, so an instance that goes away without clearing its
+     * own entry would keep its sinks — and their closures — reachable forever.
+     *
+     * @param instanceId - Instance whose sinks should be dropped
+     */
+    clearScopedEventEmitters(instanceId) {
+        this.scopedEmitters.delete(instanceId);
+    }
     /**
      * Sets the minimum log level that will be processed and output.
      * Log messages with a level lower than this will be ignored.
@@ -274,18 +381,50 @@ class NeuroLinkLogger {
             timestamp: new Date(),
             data,
         };
-        // Emit log event if emitter is configured
-        if (this.eventEmitter) {
-            try {
-                this.eventEmitter.emit("log-event", {
-                    level,
-                    message,
-                    timestamp: new Date().getTime(),
-                    data,
-                });
+        // Emit to the per-instance sinks for whichever instance is on the stack,
+        // then to the process-wide sink. The two are independent: a scoped sink
+        // never sees another instance's events, and the global sink still sees
+        // everything, so existing setEventEmitter() consumers are unaffected.
+        //
+        // Several emitters may be registered for the same instance id (see
+        // addScopedEventEmitter's own JSDoc), and the global sink always runs
+        // alongside them — so one call's `data` object is, by design, handed to
+        // more than one consumer. Each consumer below gets its OWN clone rather
+        // than the shared `data` reference, so an in-place mutation by one (e.g.
+        // a bridge redacting a field before forwarding it) cannot corrupt what a
+        // sibling consumer sees or what `entry` — which keeps the original,
+        // unmodified `data` — stores for `getLogs()`.
+        const scopeId = instanceLogScope.getStore();
+        const scoped = scopeId === undefined ? undefined : this.scopedEmitters.get(scopeId);
+        if (scoped || this.eventEmitter) {
+            const timestampMs = entry.timestamp.getTime();
+            if (scoped) {
+                for (const emitter of scoped) {
+                    try {
+                        emitter.emit("log-event", {
+                            level,
+                            message,
+                            timestamp: timestampMs,
+                            data: cloneLogData(data),
+                        });
+                    }
+                    catch {
+                        // Silently ignore emitter errors to avoid disrupting logging
+                    }
+                }
             }
-            catch {
-                // Silently ignore emitter errors to avoid disrupting logging
+            if (this.eventEmitter) {
+                try {
+                    this.eventEmitter.emit("log-event", {
+                        level,
+                        message,
+                        timestamp: timestampMs,
+                        data: cloneLogData(data),
+                    });
+                }
+                catch {
+                    // Silently ignore emitter errors to avoid disrupting logging
+                }
             }
         }
         // Store log entry
@@ -496,6 +635,12 @@ export const logger = {
     clearLogs: () => neuroLinkLogger.clearLogs(),
     setEventEmitter: (emitter) => neuroLinkLogger.setEventEmitter(emitter),
     clearEventEmitter: (ifEmitter) => neuroLinkLogger.clearEventEmitter(ifEmitter),
+    // Per-instance routing (see NeuroLinkLogger.runInInstanceScope)
+    runInInstanceScope: (instanceId, fn) => neuroLinkLogger.runInInstanceScope(instanceId, fn),
+    getInstanceScope: () => neuroLinkLogger.getInstanceScope(),
+    addScopedEventEmitter: (instanceId, emitter) => neuroLinkLogger.addScopedEventEmitter(instanceId, emitter),
+    removeScopedEventEmitter: (instanceId, emitter) => neuroLinkLogger.removeScopedEventEmitter(instanceId, emitter),
+    clearScopedEventEmitters: (instanceId) => neuroLinkLogger.clearScopedEventEmitters(instanceId),
 };
 /**
  * MCP compatibility exports - all use the same unified logger instance.

package/dist/utils/providerHealth.d.ts

@@ -8,8 +8,53 @@ export declare class ProviderHealthChecker {
     private static healthCache;
     private static readonly DEFAULT_TIMEOUT;
     private static readonly DEFAULT_CACHE_AGE;
+    /**
+     * Fixed backoff window for the circuit breaker below, in milliseconds.
+     * Deliberately NOT the per-call `maxCacheAge` option: `consecutiveFailures`
+     * is a single process-wide map keyed only by provider name, shared by every
+     * caller (e.g. `checkFallbackProviderAvailability` hard-codes a 15s
+     * `maxCacheAge` for its own health-status cache). Evicting the breaker
+     * entry using whichever caller happens to read it next would let a
+     * short-TTL caller silently erase a backoff another caller is relying on
+     * — see `checkProviderHealth`. This constant governs breaker expiry alone
+     * and is intentionally independent of `maxCacheAge`/`DEFAULT_CACHE_AGE`.
+     */
+    private static readonly CIRCUIT_BREAKER_RESET_MS;
     private static readonly CONSECUTIVE_FAILURE_THRESHOLD;
+    /**
+     * Circuit breaker state, keyed by provider.
+     *
+     * `count` is a count of consecutive failed CONNECTIVITY PROBES (plus the
+     * rare case of the check itself throwing) — never of "the provider is
+     * unconfigured". Those are different facts and only one of them is worth
+     * backing off from. A missing credential is a free, local, determinate
+     * answer that costs nothing to re-derive and flips the instant an env var
+     * is set; treating it as a failure is what let a sweep of ~38 providers
+     * (issue #1305 grew it from 8) blacklist every provider the machine
+     * happens not to have credentials for, after which the sweep reported
+     * `isConfigured: false` and no `responseTime` for a provider that was
+     * merely unconfigured — and kept reporting it after the key was supplied.
+     *
+     * `lastFailureAt` bounds how long a run of failures is held against a
+     * provider; see `checkProviderHealth`.
+     */
     private static consecutiveFailures;
+    /**
+     * Hard cap on simultaneous per-provider checks inside
+     * `checkAllProvidersHealth`. Issue #1305: the sweep used to cover only 8
+     * of ~38 registered providers; now every non-opted-out descriptor is
+     * included (see `excludeFromHealthSweep`). Firing all ~38 at once via a
+     * single `Promise.allSettled` would be harmless by default
+     * (`includeConnectivityTest` defaults to false, so most calls never
+     * leave the process), but a caller who opts into
+     * `includeConnectivityTest: true` would otherwise open up to ~38
+     * concurrent outbound HTTP connections to that many different vendors in
+     * one burst. A worker pool keeps that bounded without reducing coverage
+     * — every provider is still checked, just not all in the same instant,
+     * and without the latency a fixed batch would add (see
+     * `checkAllProvidersHealth`).
+     */
+    private static readonly MAX_CONCURRENT_HEALTH_CHECKS;
     /**
      * Validate and return a safe failure threshold value
      */
@@ -236,7 +281,26 @@ export declare class ProviderHealthChecker {
      */
     static getBestHealthyProvider(preferredProviders?: string[]): Promise<string | null>;
     /**
-     * Get health status for all registered providers
+     * Get health status for all registered providers.
+     *
+     * Membership: every descriptor in PROVIDER_DESCRIPTORS EXCEPT those that
+     * explicitly opt out via `excludeFromHealthSweep` (none currently do).
+     * Before issue #1305's fix, membership was implicit opt-IN via
+     * `defaultHealthSweepPriority`, which only 8 of ~38 descriptors carried —
+     * every other registered provider was silently invisible to this sweep,
+     * including anything a caller had actually configured and could use.
+     *
+     * Order: `defaultHealthSweepPriority` still decides ORDER for the
+     * providers that set it (lower = first — order is behaviour for
+     * first-healthy-wins callers like `getBestHealthyProvider`); everything
+     * else sorts after them, in PROVIDER_DESCRIPTORS's own declaration order
+     * (Array.prototype.sort is stable, so ties never reshuffle).
+     *
+     * Checks run through a worker pool of at most
+     * MAX_CONCURRENT_HEALTH_CHECKS, so a full sweep of every provider can't
+     * fire dozens of concurrent requests at once when a caller opts into
+     * `includeConnectivityTest`, and no check waits on a slower one beside
+     * it.
      */
     static checkAllProvidersHealth(options?: ProviderHealthCheckOptions): Promise<ProviderHealthStatusOptions[]>;
     /**