@juspay/neurolink 12.34.3 → 12.35.1

package/dist/proxy/proxyIR.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Exhaustiveness enforcement for the translation IR.
+ *
+ * A translation layer fails quietly: an unhandled content part or event variant
+ * becomes a missing tool call, and the only symptom is the next hop rejecting a
+ * request nobody can explain. `assertProxyIRExhaustive` makes that a compile
+ * error instead. Passing a value whose type is not `never` does not type-check,
+ * so a new IR variant breaks every `switch` that has not handled it.
+ *
+ * It throws at runtime as well, because the compile-time guarantee only holds for
+ * values that really are typed. A wire payload narrowed from `unknown` can reach a
+ * default branch at runtime, and failing loudly there beats translating a request
+ * with a silently dropped element.
+ */
+import type { ProxyIRContentPart, ProxyIRResponseEvent, ProxyIRTerminalOutcome, ProxyIRUnmappableValue } from "../types/index.js";
+/**
+ * Refuse an unhandled IR variant.
+ *
+ * `context` names the switch that failed, since the value alone rarely says which
+ * of several exhaustive switches over the same union let it through.
+ */
+export declare function assertProxyIRExhaustive(value: never, context: string): never;
+/** Mark a wire value no codec could represent, preserving it for the caller. */
+export declare function proxyIRUnmappable(sourceKind: string, reason: string, raw: unknown): ProxyIRUnmappableValue;
+/** Narrow a collected codec result to the unmappable marker. */
+export declare function isProxyIRUnmappable(value: unknown): value is ProxyIRUnmappableValue;
+/**
+ * Name a content part for a diagnostic.
+ *
+ * This lives in `src` rather than in the suite that asserts on it because
+ * `tsconfig.json` excludes `test`: an exhaustive switch written only in a test
+ * gives no compile-time guarantee at all. These describers are the shipped
+ * consumers that pin every union, so adding an IR variant fails `tsc --noEmit`
+ * here before it can reach a codec that silently drops it.
+ *
+ * Deliberately excludes the payload of text, thinking and tool arguments: a
+ * describer's output reaches logs and span attributes, and prompt content does
+ * not belong there.
+ */
+export declare function describeProxyIRPart(part: ProxyIRContentPart): string;
+/** Name a stream event for a diagnostic, without its payload. */
+export declare function describeProxyIRResponseEvent(event: ProxyIRResponseEvent): string;
+/** Name a terminal outcome, keeping an unmodelled upstream stop reason visible. */
+export declare function describeProxyIRTerminalOutcome(outcome: ProxyIRTerminalOutcome): string;

package/dist/proxy/proxyIR.js

@@ -0,0 +1,127 @@
+/**
+ * Exhaustiveness enforcement for the translation IR.
+ *
+ * A translation layer fails quietly: an unhandled content part or event variant
+ * becomes a missing tool call, and the only symptom is the next hop rejecting a
+ * request nobody can explain. `assertProxyIRExhaustive` makes that a compile
+ * error instead. Passing a value whose type is not `never` does not type-check,
+ * so a new IR variant breaks every `switch` that has not handled it.
+ *
+ * It throws at runtime as well, because the compile-time guarantee only holds for
+ * values that really are typed. A wire payload narrowed from `unknown` can reach a
+ * default branch at runtime, and failing loudly there beats translating a request
+ * with a silently dropped element.
+ */
+/**
+ * Refuse an unhandled IR variant.
+ *
+ * `context` names the switch that failed, since the value alone rarely says which
+ * of several exhaustive switches over the same union let it through.
+ */
+export function assertProxyIRExhaustive(value, context) {
+    throw new Error(`[proxy-ir] ${context} did not handle variant: ${describeProxyIRVariant(value)}`);
+}
+/**
+ * Describe a value for the exhaustiveness error without assuming its shape.
+ *
+ * The parameter is `never` at the call site, so nothing about it can be trusted
+ * here: it may be a primitive, or an object with no discriminant at all — and an
+ * untagged object is exactly the shape a malformed wire payload takes. Reviewed
+ * finding (PR #1826): serializing that object's fields defeated the point of a
+ * log/span-safe diagnostic, since the object can carry the same text or tool
+ * arguments the typed describers deliberately withhold. The fallback is now a
+ * fixed, shape-only marker — never the object's own content — for every
+ * untagged case, not only the ones this file happens to call today.
+ */
+function describeProxyIRVariant(value) {
+    if (value === null || typeof value !== "object") {
+        return String(value);
+    }
+    const record = value;
+    for (const discriminant of ["kind", "status", "source", "format"]) {
+        const tag = record[discriminant];
+        if (typeof tag === "string") {
+            return `${discriminant}=${tag}`;
+        }
+    }
+    return "[object without recognized discriminant]";
+}
+/** Mark a wire value no codec could represent, preserving it for the caller. */
+export function proxyIRUnmappable(sourceKind, reason, raw) {
+    return { proxyIRUnmappable: true, sourceKind, reason, raw };
+}
+/** Narrow a collected codec result to the unmappable marker. */
+export function isProxyIRUnmappable(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        value.proxyIRUnmappable === true);
+}
+/**
+ * Name a content part for a diagnostic.
+ *
+ * This lives in `src` rather than in the suite that asserts on it because
+ * `tsconfig.json` excludes `test`: an exhaustive switch written only in a test
+ * gives no compile-time guarantee at all. These describers are the shipped
+ * consumers that pin every union, so adding an IR variant fails `tsc --noEmit`
+ * here before it can reach a codec that silently drops it.
+ *
+ * Deliberately excludes the payload of text, thinking and tool arguments: a
+ * describer's output reaches logs and span attributes, and prompt content does
+ * not belong there.
+ */
+export function describeProxyIRPart(part) {
+    switch (part.kind) {
+        case "text":
+            return `text(${part.text.length}b)`;
+        case "thinking":
+            return `thinking(${part.text.length}b)`;
+        case "image":
+            return `image(${part.encoding})`;
+        case "tool_call":
+            return `tool_call(${part.toolName})`;
+        case "tool_result":
+            return `tool_result(${part.content.length} parts${part.isError ? ", error" : ""})`;
+        case "unmapped":
+            return `unmapped(${part.sourceKind}: ${part.reason})`;
+        default:
+            return assertProxyIRExhaustive(part, "describeProxyIRPart");
+    }
+}
+/** Name a stream event for a diagnostic, without its payload. */
+export function describeProxyIRResponseEvent(event) {
+    switch (event.kind) {
+        case "text_delta":
+            return `text_delta(${event.text.length}b)`;
+        case "thinking_delta":
+            return `thinking_delta(${event.text.length}b)`;
+        case "tool_call_start":
+            return `tool_call_start(${event.toolName})`;
+        case "tool_call_arguments_delta":
+            return `tool_call_arguments_delta(${event.partialArguments.length}b)`;
+        case "tool_call_done":
+            return "tool_call_done";
+        case "item_done":
+            return "item_done";
+        case "usage":
+            return "usage";
+        case "terminal":
+            return `terminal(${describeProxyIRTerminalOutcome(event.outcome)})`;
+        default:
+            return assertProxyIRExhaustive(event, "describeProxyIRResponseEvent");
+    }
+}
+/** Name a terminal outcome, keeping an unmodelled upstream stop reason visible. */
+export function describeProxyIRTerminalOutcome(outcome) {
+    switch (outcome.status) {
+        case "completed":
+            return outcome.finishReason === "other"
+                ? `completed:${outcome.rawFinishReason}`
+                : `completed:${outcome.finishReason}`;
+        case "failed":
+            return `failed:${outcome.error.code}`;
+        case "incomplete":
+            return `incomplete:${outcome.reason}`;
+        default:
+            return assertProxyIRExhaustive(outcome, "describeProxyIRTerminalOutcome");
+    }
+}

package/dist/telemetry/telemetryService.d.ts

@@ -20,6 +20,14 @@ export declare class TelemetryService {
     private requestCount;
     private totalResponseTime;
     private responseTimeCount;
+    private static readonly MAX_PENDING_CALLS;
+    private pendingCalls;
+    private isReady;
+    private droppedPendingCallWarned;
+    /** The in-flight (or already-settled) async init. Never rejects — see
+     * initializeTelemetry()'s catch block, which always resolves normally.
+     * `initialize()`/`shutdown()` await it so they don't race construction. */
+    private readyPromise?;
     private constructor();
     static getInstance(): TelemetryService;
     private isTelemetryEnabled;
@@ -27,6 +35,11 @@ export declare class TelemetryService {
     private adoptExternalTracerProvider;
     private initializeTelemetry;
     private initializeMetrics;
+    private bufferPendingCall;
+    /** Instruments now exist — drain anything buffered while we waited, in
+     * order, then flip fully sync for every call after this one. */
+    private markReady;
+    private discardPendingCalls;
     initialize(): Promise<void>;
     /**
      * @deprecated Vercel AI SDK's experimental_telemetry creates ai.generateText/ai.streamText
@@ -36,13 +49,21 @@ export declare class TelemetryService {
      */
     traceAIRequest<T>(provider: string, operation: () => Promise<T>, operationType?: string): Promise<T>;
     recordAIRequest(provider: string, model: string, tokens: number, duration: number, cost?: number): void;
+    private emitAIRequest;
     recordAIError(provider: string, error: Error): void;
+    private emitAIError;
     recordMCPToolCall(toolName: string, duration: number, success: boolean): void;
+    private emitMCPToolCall;
     recordConnection(type: "websocket" | "sse" | "http"): void;
+    private emitConnection;
     recordConnectionClosed(type: "websocket" | "sse" | "http"): void;
+    private emitConnectionClosed;
     recordResponseTime(endpoint: string, method: string, duration: number): void;
+    private emitResponseTime;
     recordCustomMetric(name: string, value: number, labels?: Record<string, string>): void;
+    private emitCustomMetric;
     recordCustomHistogram(name: string, value: number, labels?: Record<string, string>): void;
+    private emitCustomHistogram;
     getHealthMetrics(): Promise<HealthMetrics>;
     isEnabled(): boolean;
     getStatus(): {

package/dist/telemetry/telemetryService.js

@@ -1,8 +1,4 @@
 import { context, metrics, trace, } from "@opentelemetry/api";
-import { BasicTracerProvider, BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
 import { logger } from "../utils/logger.js";
 export class TelemetryService {
     static instance;
@@ -27,17 +23,52 @@ export class TelemetryService {
     requestCount = 0;
     totalResponseTime = 0;
     responseTimeCount = 0;
+    // Async-init readiness + buffering. Instruments above are constructed by
+    // an async initializeTelemetry() that the constructor fires but does not
+    // await (see getInstance()'s comment). A recording call can therefore
+    // legitimately arrive while telemetry is enabled but the instruments
+    // don't exist yet — that is NOT the same as telemetry being disabled, so
+    // it must not be dropped silently. `pendingCalls` buffers the OTEL side
+    // effect of such a call (never the whole method — see each recordX
+    // method's emitX split) until `markReady()` drains it. The cap and
+    // rate-limited warning below exist only for a pathological case (init
+    // that never resolves); the common case drains within milliseconds.
+    static MAX_PENDING_CALLS = 200;
+    pendingCalls = [];
+    isReady = false;
+    droppedPendingCallWarned = false;
+    /** The in-flight (or already-settled) async init. Never rejects — see
+     * initializeTelemetry()'s catch block, which always resolves normally.
+     * `initialize()`/`shutdown()` await it so they don't race construction. */
+    readyPromise;
     constructor() {
         // Check if telemetry is enabled
         this.enabled = this.isTelemetryEnabled();
         if (this.enabled) {
-            this.initializeTelemetry();
+            // initializeTelemetry() is async — it dynamically imports the OTel
+            // SDK packages and constructs the tracer/meter/instruments — but it
+            // is fired here WITHOUT an await. The constructor itself must stay
+            // fully synchronous and non-yielding, because getInstance() below is
+            // a plain, synchronous check-then-assign with no await in between.
+            // That is only race-free as long as nothing here yields control back
+            // to the event loop before `TelemetryService.instance` is assigned.
+            // Awaiting anything in the constructor (or making getInstance()
+            // async) would let two concurrent getInstance() callers both observe
+            // "not yet assigned" and each construct their own instance — the
+            // exact double-construction race that
+            // observability/instrumentation.ts's initializeOpenTelemetry() already
+            // hit and had to fix with a shared in-flight promise (see the
+            // "Initialize OpenTelemetry once and let concurrent callers share the
+            // work" comment there). Do not reintroduce it here.
+            this.readyPromise = this.initializeTelemetry();
         }
         else {
             logger.debug("[Telemetry] Disabled - set NEUROLINK_TELEMETRY_ENABLED=true or configure OTEL_EXPORTER_OTLP_ENDPOINT to enable");
         }
     }
     static getInstance() {
+        // Synchronous check-then-assign — see the constructor's comment above
+        // for why this must never gain an await before the assignment.
         if (!TelemetryService.instance) {
             TelemetryService.instance = new TelemetryService();
         }
@@ -84,12 +115,19 @@ export class TelemetryService {
             endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
         });
     }
-    initializeTelemetry() {
+    async initializeTelemetry() {
         try {
             if (this.hasExternalTracerProvider()) {
                 this.adoptExternalTracerProvider("global tracer provider already registered");
+                this.markReady();
                 return;
             }
+            const [{ BasicTracerProvider, BatchSpanProcessor }, { OTLPTraceExporter }, { resourceFromAttributes }, { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION },] = await Promise.all([
+                import("@opentelemetry/sdk-trace-base"),
+                import("@opentelemetry/exporter-trace-otlp-http"),
+                import("@opentelemetry/resources"),
+                import("@opentelemetry/semantic-conventions"),
+            ]);
             const resource = resourceFromAttributes({
                 [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "neurolink-ai",
                 [ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || "3.0.1",
@@ -106,6 +144,7 @@ export class TelemetryService {
             this.meter = metrics.getMeter("neurolink-ai");
             this.tracer = this.tracerProvider.getTracer("neurolink-ai");
             this.initializeMetrics();
+            this.markReady();
             logger.debug("[Telemetry] Initialized local telemetry exporter", {
                 endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
                 globalTracerProviderOwnedBy: "observability/instrumentation",
@@ -118,10 +157,16 @@ export class TelemetryService {
                 errorMessage.includes("already set");
             if (isDuplicateRegistration && this.hasExternalTracerProvider()) {
                 this.adoptExternalTracerProvider("duplicate global tracer registration detected");
+                this.markReady();
                 return;
             }
             logger.error("[Telemetry] Failed to initialize:", error);
             this.enabled = false;
+            // No instruments exist and none ever will for this instance — there
+            // is nothing left to drain a buffered call against, so the buffer is
+            // cleared rather than drained. Every recording method's `!this.enabled`
+            // guard now makes it a no-op anyway.
+            this.discardPendingCalls();
         }
     }
     initializeMetrics() {
@@ -153,10 +198,57 @@ export class TelemetryService {
             description: "Response time in milliseconds",
         });
     }
+    // ============================================================
+    // Pending-call buffer (see the field comment above pendingCalls)
+    // ============================================================
+    bufferPendingCall(call) {
+        if (this.pendingCalls.length >= TelemetryService.MAX_PENDING_CALLS) {
+            // Drop the oldest, not the newest — recent calls are more likely to
+            // still matter to whoever is about to read a dashboard.
+            this.pendingCalls.shift();
+            if (!this.droppedPendingCallWarned) {
+                this.droppedPendingCallWarned = true;
+                logger.warn(`[Telemetry] Pending metric buffer exceeded ${TelemetryService.MAX_PENDING_CALLS} entries — dropping the oldest buffered call(s). Logged once, not per drop: telemetry initialization may be unusually slow or stalled.`);
+            }
+        }
+        this.pendingCalls.push(call);
+    }
+    /** Instruments now exist — drain anything buffered while we waited, in
+     * order, then flip fully sync for every call after this one. */
+    markReady() {
+        this.isReady = true;
+        if (this.pendingCalls.length === 0) {
+            return;
+        }
+        const buffered = this.pendingCalls;
+        this.pendingCalls = [];
+        for (const call of buffered) {
+            try {
+                call();
+            }
+            catch (error) {
+                logger.warn("[Telemetry] A buffered metric call failed during drain:", error);
+            }
+        }
+    }
+    discardPendingCalls() {
+        this.pendingCalls = [];
+    }
     async initialize() {
         if (!this.enabled) {
             return;
         }
+        // The tracer/meter/instruments are constructed asynchronously (see the
+        // constructor's comment). Wait for that to settle before inspecting
+        // usingExternalTracerProvider/tracerProvider below, so this method's
+        // behavior doesn't depend on how many event-loop ticks have passed
+        // since getInstance() was called — without this, a caller invoking
+        // initialize() right after getInstance() would almost always observe
+        // `!this.tracerProvider` and return early, silently skipping the
+        // AsyncLocalStorageContextManager registration below.
+        if (this.readyPromise) {
+            await this.readyPromise;
+        }
         if (this.usingExternalTracerProvider) {
             this.initialized = true;
             logger.debug("[Telemetry] External TracerProvider already initialized by host");
@@ -227,7 +319,21 @@ export class TelemetryService {
         this.requestCount++;
         this.totalResponseTime += duration;
         this.responseTimeCount++;
-        if (!this.enabled || !this.aiRequestCounter) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!this.isReady) {
+            // Instruments aren't constructed yet — buffer the OTEL side effect
+            // only (emitAIRequest), never this whole method: the runtime
+            // counters above must fire exactly once per call, not again when the
+            // buffer drains.
+            this.bufferPendingCall(() => this.emitAIRequest(provider, model, tokens, duration, cost));
+            return;
+        }
+        this.emitAIRequest(provider, model, tokens, duration, cost);
+    }
+    emitAIRequest(provider, model, tokens, duration, cost) {
+        if (!this.aiRequestCounter) {
             return;
         }
         const labels = { provider, model };
@@ -241,7 +347,17 @@ export class TelemetryService {
     recordAIError(provider, error) {
         // Track runtime metrics
         this.errorCount++;
-        if (!this.enabled || !this.aiProviderErrors) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!this.isReady) {
+            this.bufferPendingCall(() => this.emitAIError(provider, error));
+            return;
+        }
+        this.emitAIError(provider, error);
+    }
+    emitAIError(provider, error) {
+        if (!this.aiProviderErrors) {
             return;
         }
         this.aiProviderErrors.add(1, {
@@ -251,7 +367,17 @@ export class TelemetryService {
         });
     }
     recordMCPToolCall(toolName, duration, success) {
-        if (!this.enabled || !this.mcpToolCalls) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!this.isReady) {
+            this.bufferPendingCall(() => this.emitMCPToolCall(toolName, duration, success));
+            return;
+        }
+        this.emitMCPToolCall(toolName, duration, success);
+    }
+    emitMCPToolCall(toolName, duration, success) {
+        if (!this.mcpToolCalls) {
             return;
         }
         this.mcpToolCalls.add(1, {
@@ -263,7 +389,17 @@ export class TelemetryService {
     recordConnection(type) {
         // Track runtime metrics
         this.activeConnectionCount++;
-        if (!this.enabled || !this.connectionCounter) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!this.isReady) {
+            this.bufferPendingCall(() => this.emitConnection(type));
+            return;
+        }
+        this.emitConnection(type);
+    }
+    emitConnection(type) {
+        if (!this.connectionCounter) {
             return;
         }
         this.connectionCounter.add(1, { connection_type: type });
@@ -271,7 +407,17 @@ export class TelemetryService {
     recordConnectionClosed(type) {
         // Track runtime metrics
         this.activeConnectionCount = Math.max(0, this.activeConnectionCount - 1);
-        if (!this.enabled || !this.connectionCounter) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!this.isReady) {
+            this.bufferPendingCall(() => this.emitConnectionClosed(type));
+            return;
+        }
+        this.emitConnectionClosed(type);
+    }
+    emitConnectionClosed(type) {
+        if (!this.connectionCounter) {
             return;
         }
         // Optionally record disconnection metrics if needed
@@ -284,7 +430,17 @@ export class TelemetryService {
         // Track runtime metrics
         this.totalResponseTime += duration;
         this.responseTimeCount++;
-        if (!this.enabled || !this.responseTimeHistogram) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!this.isReady) {
+            this.bufferPendingCall(() => this.emitResponseTime(endpoint, method, duration));
+            return;
+        }
+        this.emitResponseTime(endpoint, method, duration);
+    }
+    emitResponseTime(endpoint, method, duration) {
+        if (!this.responseTimeHistogram) {
             return;
         }
         this.responseTimeHistogram.record(duration, {
@@ -295,7 +451,17 @@ export class TelemetryService {
     }
     // Custom Metrics
     recordCustomMetric(name, value, labels) {
-        if (!this.enabled || !this.meter) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!this.isReady) {
+            this.bufferPendingCall(() => this.emitCustomMetric(name, value, labels));
+            return;
+        }
+        this.emitCustomMetric(name, value, labels);
+    }
+    emitCustomMetric(name, value, labels) {
+        if (!this.meter) {
             return;
         }
         const counter = this.meter.createCounter(`custom_${name}`, {
@@ -304,7 +470,17 @@ export class TelemetryService {
         counter.add(value, labels || {});
     }
     recordCustomHistogram(name, value, labels) {
-        if (!this.enabled || !this.meter) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!this.isReady) {
+            this.bufferPendingCall(() => this.emitCustomHistogram(name, value, labels));
+            return;
+        }
+        this.emitCustomHistogram(name, value, labels);
+    }
+    emitCustomHistogram(name, value, labels) {
+        if (!this.meter) {
             return;
         }
         const histogram = this.meter.createHistogram(`custom_${name}_histogram`, {
@@ -370,6 +546,16 @@ export class TelemetryService {
     }
     // Cleanup
     async shutdown() {
+        // See initialize()'s comment: wait for the async instrument
+        // construction to settle before deciding whether there is a
+        // tracerProvider to shut down. Without this, a shutdown() called
+        // immediately after getInstance() would see no tracerProvider yet and
+        // no-op, while construction — which is already in flight — finishes
+        // moments later and leaves a live exporter (with its background flush
+        // timers) behind with nothing left to ever shut it down.
+        if (this.readyPromise) {
+            await this.readyPromise;
+        }
         if (this.enabled &&
             this.tracerProvider &&
             !this.usingExternalTracerProvider) {

package/dist/types/index.d.ts

@@ -55,6 +55,7 @@ export * from "./providerCatalog.js";
 export * from "./providerCatalog.generated.js";
 export * from "./providers.js";
 export * from "./proxy.js";
+export * from "./proxyIR.js";
 export * from "./proxyClient.js";
 export * from "./proxyContext.js";
 export * from "./rag.js";

package/dist/types/index.js

@@ -59,6 +59,7 @@ export * from "./providerCatalog.js";
 export * from "./providerCatalog.generated.js";
 export * from "./providers.js";
 export * from "./proxy.js";
+export * from "./proxyIR.js";
 export * from "./proxyClient.js";
 export * from "./proxyContext.js";
 export * from "./rag.js";