@juspay/neurolink 9.41.0 → 9.42.1

package/dist/lib/telemetry/telemetryService.d.ts

@@ -11,6 +11,7 @@ export declare class TelemetryService {
     private tracerProvider?;
     private enabled;
     private initialized;
+    private usingExternalTracerProvider;
     private meter?;
     private tracer?;
     private aiRequestCounter?;
@@ -29,6 +30,8 @@ export declare class TelemetryService {
     private constructor();
     static getInstance(): TelemetryService;
     private isTelemetryEnabled;
+    private hasExternalTracerProvider;
+    private adoptExternalTracerProvider;
     private initializeTelemetry;
     private initializeMetrics;
     initialize(): Promise<void>;

package/dist/lib/telemetry/telemetryService.js

@@ -9,6 +9,7 @@ export class TelemetryService {
     tracerProvider;
     enabled = false;
     initialized = false;
+    usingExternalTracerProvider = false;
     meter;
     tracer;
     // Optional Metrics (only created when enabled)
@@ -43,11 +44,52 @@ export class TelemetryService {
         return TelemetryService.instance;
     }
     isTelemetryEnabled() {
-        return (process.env.NEUROLINK_TELEMETRY_ENABLED === "true" ||
+        return (this.hasExternalTracerProvider() ||
+            process.env.NEUROLINK_TELEMETRY_ENABLED === "true" ||
             process.env.OTEL_EXPORTER_OTLP_ENDPOINT !== undefined);
     }
+    hasExternalTracerProvider() {
+        try {
+            const provider = trace.getTracerProvider();
+            if (!provider) {
+                return false;
+            }
+            const providerName = provider.constructor?.name || "";
+            if (providerName &&
+                providerName !== "ProxyTracerProvider" &&
+                providerName !== "NoopTracerProvider") {
+                return true;
+            }
+            const delegate = typeof provider.getDelegate === "function"
+                ? provider.getDelegate()
+                : provider._delegate;
+            const delegateName = delegate?.constructor?.name || "";
+            return Boolean(delegateName && delegateName !== "NoopTracerProvider");
+        }
+        catch (error) {
+            logger.warn("[Telemetry] Failed checking for external TracerProvider", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    adoptExternalTracerProvider(reason) {
+        this.usingExternalTracerProvider = true;
+        this.tracerProvider = undefined;
+        this.meter = metrics.getMeter("neurolink-ai");
+        this.tracer = trace.getTracer("neurolink-ai");
+        this.initializeMetrics();
+        logger.debug("[Telemetry] Reusing externally managed TracerProvider", {
+            reason,
+            endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+        });
+    }
     initializeTelemetry() {
         try {
+            if (this.hasExternalTracerProvider()) {
+                this.adoptExternalTracerProvider("global tracer provider already registered");
+                return;
+            }
             const resource = resourceFromAttributes({
                 [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "neurolink-ai",
                 [ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || "3.0.1",
@@ -61,13 +103,23 @@ export class TelemetryService {
                 resource,
                 spanProcessors: [new BatchSpanProcessor(exporter)],
             });
-            trace.setGlobalTracerProvider(this.tracerProvider);
             this.meter = metrics.getMeter("neurolink-ai");
-            this.tracer = trace.getTracer("neurolink-ai");
+            this.tracer = this.tracerProvider.getTracer("neurolink-ai");
             this.initializeMetrics();
-            logger.debug("[Telemetry] Initialized with endpoint:", process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+            logger.debug("[Telemetry] Initialized local telemetry exporter", {
+                endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+                globalTracerProviderOwnedBy: "observability/instrumentation",
+            });
         }
         catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const isDuplicateRegistration = errorMessage.includes("duplicate registration") ||
+                errorMessage.includes("already registered") ||
+                errorMessage.includes("already set");
+            if (isDuplicateRegistration && this.hasExternalTracerProvider()) {
+                this.adoptExternalTracerProvider("duplicate global tracer registration detected");
+                return;
+            }
             logger.error("[Telemetry] Failed to initialize:", error);
             this.enabled = false;
         }
@@ -105,6 +157,16 @@ export class TelemetryService {
         if (!this.enabled) {
             return;
         }
+        if (this.usingExternalTracerProvider) {
+            this.initialized = true;
+            logger.debug("[Telemetry] External TracerProvider already initialized by host");
+            return;
+        }
+        if (!this.tracerProvider) {
+            this.initialized = true;
+            logger.debug("[Telemetry] Tracer provider already prepared during constructor");
+            return;
+        }
         try {
             // Register AsyncLocalStorage context manager for proper parent-child
             // span relationships across async boundaries (required for startActiveSpan)
@@ -308,7 +370,9 @@ export class TelemetryService {
     }
     // Cleanup
     async shutdown() {
-        if (this.enabled && this.tracerProvider) {
+        if (this.enabled &&
+            this.tracerProvider &&
+            !this.usingExternalTracerProvider) {
             try {
                 await this.tracerProvider.shutdown();
                 this.initialized = false;

package/dist/lib/types/cli.d.ts

@@ -763,6 +763,8 @@ export type ProxyStartArgs = {
     quiet?: boolean;
     debug?: boolean;
     config?: string;
+    envFile?: string;
+    passthrough?: boolean;
 };
 /** Arguments accepted by `neurolink proxy status` */
 export type ProxyStatusArgs = {
@@ -779,6 +781,11 @@ export type ProxyGuardArgs = {
     pollIntervalMs?: number;
     quiet?: boolean;
 };
+/** Arguments accepted by `neurolink proxy telemetry <subcommand>` */
+export type ProxyTelemetryArgs = {
+    action?: "setup" | "start" | "stop" | "status" | "logs" | "import-dashboard";
+    quiet?: boolean;
+};
 /** A fallback chain entry (serialisable subset of FallbackEntry) */
 export type FallbackInfo = {
     provider: string;
@@ -791,12 +798,15 @@ export type ProxyState = {
     host: string;
     strategy: string;
     startTime: string;
+    envFile?: string;
     /** Fallback chain from proxy config (persisted at start time) */
     fallbackChain?: FallbackInfo[];
     /** Optional fail-open guard PID that reverts Claude settings if proxy dies */
     guardPid?: 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 */
+    passthrough?: boolean;
 };
 /** Stored credentials for an authenticated provider. */
 export type StoredCredentials = {

package/dist/lib/types/proxyTypes.d.ts

@@ -13,6 +13,8 @@
  * - src/lib/proxy/accountQuota.ts (quota type)
  * - src/lib/server/routes/claudeProxyRoutes.ts (runtime state, deps)
  */
+import type { Span } from "@opentelemetry/api";
+import type { ProxyTracer } from "../proxy/proxyTracer.js";
 /**
  * Type describing the ModelRouter contract.
  * Defined here to avoid a circular dependency between types and implementation.
@@ -239,10 +241,11 @@ export type ParsedClaudeRequest = {
         role: string;
         content: string;
     }>;
-    /** Tools in NeuroLink-compatible shape (name -> { description, parameters }). */
+    /** Tools translated to AI SDK-compatible shape for provider fallback. */
     tools: Record<string, {
-        description: string;
-        parameters: Record<string, unknown>;
+        description?: string;
+        inputSchema: unknown;
+        execute?: (...args: unknown[]) => unknown;
     }>;
     /**
      * Tool choice mapping from Claude format.
@@ -360,6 +363,14 @@ export type TlsFingerprintOptions = {
     /** Whether the stub should log a warning that it is a no-op. */
     warnOnUse?: boolean;
 };
+/**
+ * Proxy operating mode:
+ * - "full"        — managed accounts, retry, rotation, polyfill (default)
+ * - "passthrough" — no polyfill/retry/rotation, but body is still parsed and re-serialized
+ * - "transparent" — zero-mutation byte relay: raw body forwarded as-is, minimal header filtering,
+ *                   SSE interceptor for cache metrics only (bytes pass through unmodified)
+ */
+export type ProxyMode = "full" | "passthrough" | "transparent";
 export type RouteResult = {
     provider: string | null;
     model: string;
@@ -421,21 +432,165 @@ export type RequestLogEntry = {
     errorMessage?: string;
     inputTokens?: number;
     outputTokens?: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+    /** OTel trace ID for correlation with distributed traces */
+    traceId?: string;
+    /** OTel span ID for correlation with distributed traces */
+    spanId?: string;
+};
+export type RequestAttemptLogEntry = {
+    timestamp: string;
+    requestId: string;
+    attempt: number;
+    method: string;
+    path: string;
+    model: string;
+    stream: boolean;
+    toolCount: number;
+    account: string;
+    accountType: string;
+    responseStatus: number;
+    responseTimeMs: number;
+    errorType?: string;
+    errorMessage?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+    /** OTel trace ID for correlation with distributed traces */
+    traceId?: string;
+    /** OTel span ID for correlation with distributed traces */
+    spanId?: string;
+};
+export type ProxyBodyCaptureInput = {
+    phase: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    bodySize?: number;
+    contentType?: string;
+    responseStatus?: number;
+    durationMs?: number;
+    account?: string;
+    accountType?: string;
+    attempt?: number;
+    metadata?: Record<string, unknown>;
+};
+export type ProxyBodyCaptureLogger = (capture: ProxyBodyCaptureInput) => void;
+export type ClaudeFinalRequestLogger = (status: number, accountLabel: string, accountType: string, errorType?: string, errorMessage?: string, extra?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+}) => void;
+export type ClaudeLoggedErrorBuilder = (status: number, message: string, errorType?: string, extra?: {
+    account?: string;
+    accountType?: string;
+    attempt?: number;
+}) => ClaudeErrorResponse;
+export type ClaudeRequestRuntimeContext = {
+    tracer?: ProxyTracer;
+    requestStartTime: number;
+    logProxyBody: ProxyBodyCaptureLogger;
+    logFinalRequest: ClaudeFinalRequestLogger;
+    buildLoggedClaudeError: ClaudeLoggedErrorBuilder;
+};
+export type AnthropicAttemptLogger = (status: number, errorType?: string, errorMessage?: string, extra?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+}) => void;
+export type AnthropicLoopState = {
+    lastError: unknown;
+    sawRateLimit: boolean;
+    sawNetworkError: boolean;
+    sawTransientFailure: boolean;
+    invalidRequestFailure: {
+        status: number;
+        body: string;
+        contentType?: string;
+    } | null;
+    authFailureMessage: string | null;
+    attemptNumber: number;
+};
+export type AnthropicUpstreamBody = {
+    bodyStr: string;
+    sessionId?: string;
+};
+export type AnthropicUpstreamBodyBuilder = (token: string) => AnthropicUpstreamBody;
+export type LoadedClaudeAccountContext = {
+    accounts: ProxyPassthroughAccount[];
+    enabledAccounts: ProxyPassthroughAccount[];
+    orderedAccounts: ProxyPassthroughAccount[];
+    bodyStr: string;
+    requestStart: number;
+    toolCount: number;
+    url: string;
+    clientHeaders: Record<string, string | undefined>;
+    isClaudeClientRequest: boolean;
+};
+export type AnthropicSuccessResult = {
+    retryNextAccount: true;
+} | {
+    response: Response | unknown;
+};
+export type AnthropicAuthRetryResult = {
+    response?: Response | unknown;
+    continueLoop: boolean;
+    lastError: unknown;
+    authFailureMessage: string | null;
+    sawRateLimit: boolean;
+    sawTransientFailure: boolean;
+    sawNetworkError: boolean;
+    upstreamSpan?: Span;
+};
+export type AnthropicNonOkResult = {
+    response?: Response | unknown;
+    continueLoop: boolean;
+    lastError: unknown;
+    authFailureMessage: string | null;
+    sawTransientFailure: boolean;
+    invalidRequestFailure: {
+        status: number;
+        body: string;
+        contentType?: string;
+    } | null;
+    upstreamSpan?: Span;
+};
+export type PreparedAnthropicAccountAttempt = {
+    continueLoop: boolean;
+    lastError: unknown;
+    authFailureMessage: string | null;
+    headers?: Record<string, string>;
+    buildUpstreamBody?: AnthropicUpstreamBodyBuilder;
+    finalBodyStr?: string;
+    fetchStartMs?: number;
+    upstreamSpan?: Span;
+};
+export type AnthropicUpstreamFetchResult = {
+    continueLoop: boolean;
+    response?: Response;
+    lastError: unknown;
+    sawRateLimit: boolean;
+    sawNetworkError: boolean;
+    upstreamSpan?: Span;
 };
 export type AccountStats = {
     label: string;
     type: string;
-    requestCount: number;
+    attemptCount: number;
     successCount: number;
     errorCount: number;
     rateLimitCount: number;
-    lastRequestAt: number;
+    lastAttemptAt: number;
     lastErrorAt?: number;
     currentBackoffLevel: number;
     coolingUntil?: number;
 };
 export type ProxyStats = {
     startedAt: number;
+    totalAttempts: number;
     totalRequests: number;
     totalSuccess: number;
     totalErrors: number;

package/dist/lib/types/streamTypes.d.ts

@@ -1,16 +1,16 @@
-import type { Tool } from "ai";
+import type { LanguageModel, StepResult, Tool, ToolChoice } from "ai";
 import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "../index.js";
 import type { RAGConfig } from "../rag/types.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
-import type { MiddlewareFactoryOptions, OnFinishCallback, OnErrorCallback, OnChunkCallback } from "../types/middlewareTypes.js";
+import type { MiddlewareFactoryOptions, OnChunkCallback, OnErrorCallback, OnFinishCallback } from "../types/middlewareTypes.js";
 import type { TokenUsage } from "./analytics.js";
 import type { JsonValue, UnknownRecord } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage } from "./conversation.js";
+import type { AdditionalMemoryUser } from "./generateTypes.js";
 import type { AIModelProviderConfig } from "./providers.js";
 import type { TTSChunk, TTSOptions } from "./ttsTypes.js";
-import type { AdditionalMemoryUser } from "./generateTypes.js";
 import type { StandardRecord, ValidationSchema } from "./typeAliases.js";
 /**
  * Progress tracking and metadata for streaming operations
@@ -326,12 +326,34 @@ export type StreamOptions = {
     abortSignal?: AbortSignal;
     disableTools?: boolean;
     maxSteps?: number;
+    /**
+     * Tool choice configuration for streaming generation.
+     * Mirrors generate() so translated/fallback requests can preserve forced tool use.
+     */
+    toolChoice?: ToolChoice<Record<string, Tool>>;
+    /**
+     * Optional callback that runs before each stream step in a multi-step generation.
+     */
+    prepareStep?: (options: {
+        steps: StepResult<Record<string, Tool>>[];
+        stepNumber: number;
+        maxSteps: number;
+        model: LanguageModel;
+    }) => PromiseLike<{
+        toolChoice?: ToolChoice<Record<string, Tool>>;
+        activeTools?: Record<string, Tool>;
+    } | undefined>;
     /** Include only these tools by name (whitelist). If set, only matching tools are available. */
     toolFilter?: string[];
     /** Exclude these tools by name (blacklist). Applied after toolFilter. */
     excludeTools?: string[];
     /** Disable tool result caching for this request (overrides global mcp.cache.enabled) */
     disableToolCache?: boolean;
+    /**
+     * Disable NeuroLink's internal provider fallback for this request.
+     * Used by the Claude proxy so the proxy itself can own fallback order.
+     */
+    disableInternalFallback?: boolean;
     /**
      * Skip injecting tool schemas into the system prompt.
      * When true, tools are ONLY passed natively via the provider's `tools` parameter,

package/dist/lib/utils/messageBuilder.js

@@ -775,6 +775,7 @@ async function processUnifiedFilesArray(options, maxSize, provider) {
         return;
     }
     const totalFiles = options.input.files.length;
+    const files = options.input.files;
     return withSpan({
         name: "neurolink.file.process_all",
         tracer: tracers.file,
@@ -787,8 +788,8 @@ async function processUnifiedFilesArray(options, maxSize, provider) {
         options.input.text = options.input.text || "";
         let includedCount = 0;
         const fileRegistry = options.fileRegistry;
-        for (let fileIdx = 0; fileIdx < options.input.files.length; fileIdx++) {
-            const file = options.input.files[fileIdx];
+        for (let fileIdx = 0; fileIdx < files.length; fileIdx++) {
+            const file = files[fileIdx];
             const filename = extractFilename(file, fileIdx);
             try {
                 // ─── Lazy file registration path ──────────────────────────────

package/dist/lib/utils/providerHealth.d.ts

@@ -30,6 +30,7 @@ export declare class ProviderHealthChecker {
      * Check connectivity to provider endpoints
      */
     private static checkConnectivity;
+    private static getConnectivityHeaders;
     /**
      * Check model availability (if possible without making API calls)
      */
@@ -98,6 +99,20 @@ export declare class ProviderHealthChecker {
      * Check Azure OpenAI configuration
      */
     private static checkAzureConfig;
+    private static getLiteLLMBaseUrl;
+    private static getLiteLLMModelsUrl;
+    private static getConfiguredLiteLLMModel;
+    private static getOllamaBaseUrl;
+    private static getOllamaTagsUrl;
+    private static getConfiguredOllamaModel;
+    private static fetchJsonWithTimeout;
+    private static normalizeModelList;
+    private static hasRequestedModel;
+    private static getOllamaAvailableModels;
+    private static getLiteLLMAvailableModels;
+    private static checkOllamaAvailability;
+    private static checkLiteLLMAvailability;
+    private static checkLiteLLMConfig;
     /**
      * Check Ollama configuration
      */
@@ -169,6 +184,10 @@ export declare class ProviderHealthChecker {
      * Clear health cache for a provider or all providers
      */
     static clearHealthCache(providerName?: AIProviderName): void;
+    static checkFallbackProviderAvailability(providerName: string, model: string): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
     /**
      * Get the best healthy provider from a list of options (NON-BLOCKING)
      * Prioritizes healthy providers over configured but unhealthy ones