@juspay/neurolink 12.34.0 → 12.34.1

package/dist/mcp/externalServerManager.js

@@ -7,7 +7,6 @@
  * - Tool discovery and registration
  */
 import { EventEmitter } from "events";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { mcpLogger } from "../utils/logger.js";
 import { MCPClientFactory } from "./mcpClientFactory.js";
 import { ToolDiscoveryService } from "./toolDiscoveryService.js";
@@ -1063,6 +1062,7 @@ export class ExternalServerManager extends EventEmitter {
             instance.client = clientResult.client;
             instance.transportInstance = clientResult.transport;
             instance.process = clientResult.process || null;
+            const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
             instance.pid =
                 clientResult.transport instanceof StdioClientTransport
                     ? (clientResult.transport.pid ?? undefined)

package/dist/mcp/mcpClientFactory.d.ts

@@ -4,7 +4,7 @@
  * Supports stdio, SSE, WebSocket, and HTTP transports
  * Enhanced with retry, rate limiting, and OAuth 2.1 support
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { ClientCapabilities } from "@modelcontextprotocol/sdk/types.js";
 import type { ChildProcess } from "child_process";

package/dist/mcp/mcpClientFactory.js

@@ -4,11 +4,6 @@
  * Supports stdio, SSE, WebSocket, and HTTP transports
  * Enhanced with retry, rate limiting, and OAuth 2.1 support
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { mcpLogger } from "../utils/logger.js";
 import { globalCircuitBreakerManager } from "./mcpCircuitBreaker.js";
 import { CircuitBreakerOpenError } from "../types/index.js";
@@ -209,6 +204,7 @@ export class MCPClientFactory {
         const transport = transportResult.transport;
         try {
             // Create client
+            const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
             const client = new Client(this.NEUROLINK_IMPLEMENTATION, {
                 capabilities: this.DEFAULT_CAPABILITIES,
             });
@@ -296,6 +292,7 @@ export class MCPClientFactory {
         if (!config.command) {
             throw new Error(`Command is required for stdio transport`);
         }
+        const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
         const transport = new StdioClientTransport({
             command: config.command,
             args: config.args || [],
@@ -333,6 +330,7 @@ export class MCPClientFactory {
         });
         try {
             const url = new URL(config.url);
+            const { SSEClientTransport } = await import("@modelcontextprotocol/sdk/client/sse.js");
             const transport = new SSEClientTransport(url);
             return { transport };
         }
@@ -352,6 +350,7 @@ export class MCPClientFactory {
         });
         try {
             const url = new URL(config.url);
+            const { WebSocketClientTransport } = await import("@modelcontextprotocol/sdk/client/websocket.js");
             const transport = new WebSocketClientTransport(url);
             return { transport };
         }
@@ -402,6 +401,7 @@ export class MCPClientFactory {
             const requestInit = {
                 headers: Object.keys(headers).length > 0 ? headers : undefined,
             };
+            const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
             const transport = new StreamableHTTPClientTransport(url, {
                 requestInit,
                 fetch: fetchWithEnhancements,

package/dist/neurolink.js

@@ -2804,11 +2804,15 @@ Current user's request: ${currentInput}`;
         try {
             const langfuseConfig = this.observabilityConfig?.langfuse;
             if (langfuseConfig?.enabled) {
-                void initializeOpenTelemetry(langfuseConfig).catch((err) => {
+                try {
+                    await initializeOpenTelemetry(langfuseConfig);
+                }
+                catch (err) {
                     logger.error("[NeuroLink] OpenTelemetry initialization failed", {
                         error: err instanceof Error ? err.message : String(err),
                     });
-                });
+                    return;
+                }
                 logger.debug("[NeuroLink] Langfuse observability initialized via public method");
             }
             else {

package/dist/proxy/vertexAnthropicFallback.d.ts

@@ -12,6 +12,7 @@
  * `tool_use`, `tool_result`, `cache_control` and thinking blocks all survive
  * here because nothing reshapes them.
  */
+import type { GoogleAuth } from "google-auth-library";
 import type { VertexAccessTokenProvider, UsageContext, VertexPassthroughTerminal, VertexAnthropicPassthroughRequest, VertexAnthropicPassthroughTarget } from "../types/index.js";
 /**
  * Translate `output_config` for Vertex.
@@ -40,6 +41,13 @@ export declare function buildVertexAnthropicPayload(body: Readonly<Record<string
  * caller's `stream` flag selects the verb rather than changing the body.
  */
 export declare function buildVertexAnthropicUrl(target: VertexAnthropicPassthroughTarget): string;
+/** Exported only for continuous-test-suite-vertex-anthropic-fallback.ts,
+ * which proves concurrent callers share one instance. Not part of the
+ * package's public surface — this module isn't re-exported from index.ts. */
+export declare function auth(): Promise<GoogleAuth>;
+/** Test-only: isolates the concurrency proof from cache state any earlier
+ * test in the same process may have left behind. */
+export declare function resetAuthCacheForTests(): void;
 /**
  * Replace the Google credential lookup, for tests only.
  *

package/dist/proxy/vertexAnthropicFallback.js

@@ -12,7 +12,6 @@
  * `tool_use`, `tool_result`, `cache_control` and thinking blocks all survive
  * here because nothing reshapes them.
  */
-import { GoogleAuth } from "google-auth-library";
 import { logger } from "../utils/logger.js";
 import { isTransientNetworkError } from "./proxyFetch.js";
 /** Vertex pins the Anthropic API version in the body, not a header. */
@@ -379,16 +378,41 @@ export function buildVertexAnthropicUrl(target) {
     return (`https://${host}/v1/projects/${target.projectId}/locations/` +
         `${target.location}/publishers/anthropic/models/${target.model}:${verb}`);
 }
-let cachedAuth;
-function auth() {
-    cachedAuth ??= new GoogleAuth({ scopes: [CLOUD_PLATFORM_SCOPE] });
-    return cachedAuth;
+// google-auth-library is only needed once a Vertex fallback request actually
+// needs a Google access token, so it's loaded with `await import(...)` instead
+// of a static import. The module promise is cached at module scope, and the
+// resulting client instance is cached separately, exactly as before.
+let googleAuthModulePromise;
+function loadGoogleAuth() {
+    if (!googleAuthModulePromise) {
+        googleAuthModulePromise = import("google-auth-library");
+    }
+    return googleAuthModulePromise;
+}
+// Cache the PROMISE, not the resolved client: the guard below runs to
+// completion before any await, so two calls entering before the first
+// resolves both see the same in-flight promise instead of each racing to
+// construct — and return — its own GoogleAuth instance.
+let cachedAuthPromise;
+/** Exported only for continuous-test-suite-vertex-anthropic-fallback.ts,
+ * which proves concurrent callers share one instance. Not part of the
+ * package's public surface — this module isn't re-exported from index.ts. */
+export function auth() {
+    if (!cachedAuthPromise) {
+        cachedAuthPromise = loadGoogleAuth().then(({ GoogleAuth }) => new GoogleAuth({ scopes: [CLOUD_PLATFORM_SCOPE] }));
+    }
+    return cachedAuthPromise;
+}
+/** Test-only: isolates the concurrency proof from cache state any earlier
+ * test in the same process may have left behind. */
+export function resetAuthCacheForTests() {
+    cachedAuthPromise = undefined;
 }
 let accessTokenProviderForTests;
 async function vertexAccessToken() {
     return accessTokenProviderForTests
         ? accessTokenProviderForTests()
-        : auth().getAccessToken();
+        : (await auth()).getAccessToken();
 }
 /**
  * Replace the Google credential lookup, for tests only.

package/dist/services/server/ai/observability/instrumentation.d.ts

@@ -7,9 +7,9 @@
  * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
  */
 import { trace, type Span as ApiSpan } from "@opentelemetry/api";
-import { LoggerProvider } from "@opentelemetry/sdk-logs";
-import { type SpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import type { LoggerProvider } from "@opentelemetry/sdk-logs";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import type { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import type { LangfuseConfig, LangfuseContext } from "../../../../types/index.js";
 /**
  * True when a span is an internal NeuroLink wrapper that should NOT be sent to
@@ -38,18 +38,11 @@ export declare function langfuseShouldExportSpan({ otelSpan, }: {
     };
 }): boolean;
 /**
- * Initialize OpenTelemetry with Langfuse span processor
+ * Initialize OpenTelemetry once and let concurrent callers share the work.
  *
- * This connects Vercel AI SDK's experimental_telemetry to Langfuse by:
- * 1. Creating LangfuseSpanProcessor with Langfuse credentials
- * 2. Creating a NodeTracerProvider with service metadata and span processor
- * 3. Registering the provider globally for AI SDK to use
- *
- * NEW: If useExternalTracerProvider is true or autoDetectExternalProvider detects
- * an existing provider, steps 2 and 3 are skipped. The span processors are still
- * created and can be retrieved via getSpanProcessors().
- *
- * @param config - Langfuse configuration passed from parent application
+ * NeuroLink constructors intentionally start this asynchronously. Keeping the
+ * in-flight promise here lets another constructor join it and lets an immediate
+ * flush or shutdown wait for the same initialization before touching providers.
  */
 export declare function initializeOpenTelemetry(config: LangfuseConfig): Promise<void>;
 /**

package/dist/services/server/ai/observability/instrumentation.js

@@ -7,23 +7,17 @@
  * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
  */
 import { metrics, SpanStatusCode, trace, } from "@opentelemetry/api";
-import { W3CTraceContextPropagator } from "@opentelemetry/core";
-import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { MeterProvider, PeriodicExportingMetricReader, } from "@opentelemetry/sdk-metrics";
-import { BatchLogRecordProcessor, LoggerProvider, } from "@opentelemetry/sdk-logs";
-import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
 import { AsyncLocalStorage } from "async_hooks";
 import { extractMcpErrorText } from "../../../../utils/mcpErrorText.js";
 import { logger } from "../../../../utils/logger.js";
 import { tryImport } from "../../../../utils/tryImport.js";
 import { LANGFUSE_ATTR } from "../../../../telemetry/attributes.js";
 const LOG_PREFIX = "[OpenTelemetry]";
-function createOtelResource(config, serviceName) {
+async function createOtelResource(config, serviceName) {
+    const [{ resourceFromAttributes }, { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION },] = await Promise.all([
+        import("@opentelemetry/resources"),
+        import("@opentelemetry/semantic-conventions"),
+    ]);
     return resourceFromAttributes({
         [ATTR_SERVICE_NAME]: serviceName,
         [ATTR_SERVICE_VERSION]: config.release || "v1.0.0",
@@ -32,13 +26,19 @@ function createOtelResource(config, serviceName) {
 }
 /**
  * Configure OTLP metrics and logs with bounded serialization batches for
- * request-serving processes.
+ * request-serving processes. Initialization awaits this so a caller may flush
+ * or shut down immediately after it returns without racing providers that have
+ * not been constructed yet. Signal-specific failures stay non-fatal here.
  */
-function initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName) {
+async function initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName) {
     if (!otlpEndpoint) {
         return;
     }
     try {
+        const [{ OTLPMetricExporter }, { MeterProvider, PeriodicExportingMetricReader },] = await Promise.all([
+            import("@opentelemetry/exporter-metrics-otlp-http"),
+            import("@opentelemetry/sdk-metrics"),
+        ]);
         const metricExporter = new OTLPMetricExporter({
             url: `${otlpEndpoint}/v1/metrics`,
         });
@@ -68,6 +68,10 @@ function initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName) {
         });
     }
     try {
+        const [{ OTLPLogExporter }, { BatchLogRecordProcessor, LoggerProvider }] = await Promise.all([
+            import("@opentelemetry/exporter-logs-otlp-http"),
+            import("@opentelemetry/sdk-logs"),
+        ]);
         const logExporter = new OTLPLogExporter({
             url: `${otlpEndpoint}/v1/logs`,
         });
@@ -101,6 +105,7 @@ let meterProvider = null;
 let loggerProvider = null;
 let langfuseProcessor = null;
 let isInitialized = false;
+let initializationPromise = null;
 let isCredentialsValid = false;
 let currentConfig = null;
 let usingExternalProvider = false;
@@ -637,8 +642,8 @@ async function initializeExternalOpenTelemetryMode(config, resource, otlpEndpoin
                 ? await createLangfuseProcessor(config)
                 : null;
         usingExternalProvider = true;
+        await initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName);
         isInitialized = true;
-        initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName);
         try {
             const globalProvider = trace.getTracerProvider();
             const provider = globalProvider;
@@ -759,6 +764,10 @@ async function initializeStandaloneOpenTelemetryMode(config, resource, otlpEndpo
         }
         if (otlpEndpoint) {
             try {
+                const [{ OTLPTraceExporter }, { BatchSpanProcessor }] = await Promise.all([
+                    import("@opentelemetry/exporter-trace-otlp-http"),
+                    import("@opentelemetry/sdk-trace-base"),
+                ]);
                 const otlpExporter = new OTLPTraceExporter({
                     url: `${otlpEndpoint}/v1/traces`,
                 });
@@ -782,13 +791,17 @@ async function initializeStandaloneOpenTelemetryMode(config, resource, otlpEndpo
                 });
             }
         }
+        const [{ NodeTracerProvider }, { W3CTraceContextPropagator }] = await Promise.all([
+            import("@opentelemetry/sdk-trace-node"),
+            import("@opentelemetry/core"),
+        ]);
         tracerProvider = new NodeTracerProvider({ resource, spanProcessors });
         tracerProvider.register({
             propagator: new W3CTraceContextPropagator(),
         });
         usingExternalProvider = false;
+        await initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName);
         isInitialized = true;
-        initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName);
         logger.info(`${LOG_PREFIX} Observability initialized`, {
             baseUrl: config.baseUrl || "https://cloud.langfuse.com",
             environment: config.environment || "dev",
@@ -820,6 +833,39 @@ async function initializeStandaloneOpenTelemetryMode(config, resource, otlpEndpo
         throw error;
     }
 }
+/**
+ * Initialize OpenTelemetry once and let concurrent callers share the work.
+ *
+ * NeuroLink constructors intentionally start this asynchronously. Keeping the
+ * in-flight promise here lets another constructor join it and lets an immediate
+ * flush or shutdown wait for the same initialization before touching providers.
+ */
+export async function initializeOpenTelemetry(config) {
+    if (isInitialized) {
+        currentConfig = config;
+        logger.debug(`${LOG_PREFIX} Already initialized, config updated`, {
+            usingExternalProvider,
+            hasLangfuseProcessor: !!langfuseProcessor,
+            hasTraceNameFormat: typeof config.traceNameFormat === "function",
+        });
+        return;
+    }
+    if (initializationPromise) {
+        await initializationPromise;
+        currentConfig = config;
+        return;
+    }
+    const pending = initializeOpenTelemetryOnce(config);
+    initializationPromise = pending;
+    try {
+        await pending;
+    }
+    finally {
+        if (initializationPromise === pending) {
+            initializationPromise = null;
+        }
+    }
+}
 /**
  * Initialize OpenTelemetry with Langfuse span processor
  *
@@ -834,20 +880,7 @@ async function initializeStandaloneOpenTelemetryMode(config, resource, otlpEndpo
  *
  * @param config - Langfuse configuration passed from parent application
  */
-export async function initializeOpenTelemetry(config) {
-    // Guard against multiple initializations — but always update config
-    // so that later NeuroLink instances can change traceNameFormat,
-    // autoDetectOperationName, and other configuration preferences
-    // without re-initializing the OTEL infrastructure.
-    if (isInitialized) {
-        currentConfig = config;
-        logger.debug(`${LOG_PREFIX} Already initialized, config updated`, {
-            usingExternalProvider,
-            hasLangfuseProcessor: !!langfuseProcessor,
-            hasTraceNameFormat: typeof config.traceNameFormat === "function",
-        });
-        return;
-    }
+async function initializeOpenTelemetryOnce(config) {
     // FIRST: Check for external provider mode - bypasses enabled check
     // NOTE: When autoDetectExternalProvider is true, we trust the flag directly rather than
     // calling hasExternalTracerProvider(). This is because Neurolink may bundle its own copy
@@ -862,7 +895,7 @@ export async function initializeOpenTelemetry(config) {
     const langfuseRequested = config?.enabled === true;
     const hasLangfuseCreds = !!config.publicKey && !!config.secretKey;
     const serviceName = process.env.OTEL_SERVICE_NAME || "neurolink";
-    const resource = createOtelResource(config, serviceName);
+    const resource = await createOtelResource(config, serviceName);
     if (shouldUseExternal) {
         await initializeExternalOpenTelemetryMode(config, resource, otlpEndpoint, serviceName, langfuseRequested, hasLangfuseCreds);
         return;
@@ -873,6 +906,15 @@ export async function initializeOpenTelemetry(config) {
  * Flush all pending spans to Langfuse
  */
 export async function flushOpenTelemetry() {
+    if (initializationPromise) {
+        try {
+            await initializationPromise;
+        }
+        catch {
+            // Initialization owns its error logging; a failed init leaves nothing
+            // initialized, so the check below skips the flush as it always has.
+        }
+    }
     if (!isInitialized) {
         logger.debug(`${LOG_PREFIX} Not initialized, skipping flush`);
         return;
@@ -951,8 +993,14 @@ export async function flushOpenTelemetry() {
  * Shutdown OpenTelemetry and Langfuse span processor
  */
 export async function shutdownOpenTelemetry() {
-    if (!isInitialized) {
-        return;
+    if (initializationPromise) {
+        try {
+            await initializationPromise;
+        }
+        catch {
+            // Initialization owns its error logging. Continue so any provider it
+            // created before failing is still shut down below.
+        }
     }
     try {
         // Only shutdown tracerProvider if we created it

package/dist/utils/redis.js

@@ -3,7 +3,6 @@
  * Helper functions for Redis storage operations
  */
 import { randomUUID } from "crypto";
-import { createClient } from "redis";
 import { logger } from "./logger.js";
 const SESSION_ONLY_PREFIX = "session-only:";
 /** Characters that end the authority (`user:pass@host:port`) of a URL in text. */
@@ -195,6 +194,9 @@ export async function createRedisClient(config) {
     if (config.password && !config.url) {
         clientOptions.password = config.password;
     }
+    // Imported here, not at the top: the redis client is ~590 modules, a quarter
+    // of everything importing the SDK loaded, and most callers never connect.
+    const { createClient } = await import("redis");
     // Create client with secured options
     const client = createClient(clientOptions);
     client.on("error", (err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.34.0",
+  "version": "12.34.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": {
@@ -274,6 +274,7 @@
     "test:aistudio-loop-characterization": "tsx test/continuous-test-suite-aistudio-loop-characterization.ts",
     "test:docs-mcp": "pnpm exec tsx test/continuous-test-suite-docs-mcp.ts",
     "test:docs-search-index": "pnpm exec tsx test/continuous-test-suite-docs-search-index.ts",
+    "test:import-cost": "pnpm exec tsx test/continuous-test-suite-import-cost.ts",
     "test:vertex-claude-characterization": "tsx test/continuous-test-suite-vertex-claude-characterization.ts",
     "test:toolfree-guard-overhead": "pnpm exec tsx test/continuous-test-suite-toolfree-guard-overhead.ts",
     "test:file-tool-roots": "pnpm exec tsx test/continuous-test-suite-file-tool-roots.ts",