@juspay/neurolink 12.14.5 → 12.14.7

package/dist/proxy/otelLogSink.js

@@ -1,5 +1,7 @@
 /* eslint-disable no-console -- This proxy-only sink replaces console methods with OTLP emission. */
 import { inspect } from "node:util";
+import { randomUUID } from "node:crypto";
+import { getProxyRequestTraceContext, proxyLogContext, } from "./proxyTraceContext.js";
 import { setImmediate as yieldToRequests } from "node:timers/promises";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 import { ExportResultCode } from "@opentelemetry/core";
@@ -45,6 +47,52 @@ function createTrackedProcessor(url, capacity, kind) {
         lastAcknowledgedAt: undefined,
         lastFailureAt: undefined,
         highWaterOutstanding: 0,
+        recentFailures: [],
+        failureHistoryEvicted: 0,
+    };
+    const diagnostics = [];
+    let diagnosticScheduled = false;
+    const rememberFailure = (records, reason, error) => {
+        const stringAttribute = (record, name) => {
+            const value = record.attributes[name];
+            return typeof value === "string" ? value.slice(0, 128) : undefined;
+        };
+        const failure = {
+            id: randomUUID(),
+            at: new Date().toISOString(),
+            reason,
+            ...(error ? { error: sanitizeForLog(error.message).slice(0, 256) } : {}),
+            records: records.slice(0, 64).map((record) => ({
+                eventId: stringAttribute(record, "proxy.event_id") ?? "unavailable",
+                kind: stringAttribute(record, "proxy.record_kind"),
+                requestId: stringAttribute(record, "request.id"),
+                captureId: stringAttribute(record, "body.capture_id"),
+            })),
+        };
+        if (state.recentFailures.length === 16) {
+            state.recentFailures.shift();
+            state.failureHistoryEvicted++;
+        }
+        state.recentFailures.push(failure);
+        // A failed diagnostic must not generate another diagnostic recursively.
+        if (records.some((record) => record.attributes["proxy.record_kind"] !== "telemetry_delivery")) {
+            if (diagnostics.length === 16) {
+                diagnostics.shift();
+            }
+            diagnostics.push(failure);
+        }
+    };
+    const publishRecoveredDiagnostics = () => {
+        if (diagnosticScheduled || !diagnostics.length || shuttingDown) {
+            return;
+        }
+        diagnosticScheduled = true;
+        queueMicrotask(() => {
+            diagnosticScheduled = false;
+            for (const failure of diagnostics.splice(0)) {
+                emitProxyOtelEvent("telemetry_delivery", { queue: kind, ...failure });
+            }
+        });
     };
     const transport = new OTLPLogExporter({ url, timeoutMillis: 5000 });
     const exporter = {
@@ -65,10 +113,12 @@ function createTrackedProcessor(url, capacity, kind) {
                 if (result.code === ExportResultCode.SUCCESS) {
                     state.transportAcknowledged += records.length;
                     state.lastAcknowledgedAt = new Date().toISOString();
+                    publishRecoveredDiagnostics();
                 }
                 else {
                     state.exportUnconfirmed += records.length;
                     state.lastFailureAt = new Date().toISOString();
+                    rememberFailure(records, "export_unconfirmed", result.error);
                 }
                 for (const record of records) {
                     unsettled.delete(record);
@@ -109,6 +159,7 @@ function createTrackedProcessor(url, capacity, kind) {
     });
     const processor = {
         onEmit(record) {
+            record.attributes["proxy.event_id"] ??= randomUUID();
             state.attempted++;
             const id = record.attributes?.["body.capture_id"];
             const publication = typeof id === "string" ? bodyPublications.get(id) : undefined;
@@ -117,6 +168,7 @@ function createTrackedProcessor(url, capacity, kind) {
             }
             if (state.outstanding >= capacity) {
                 state.dropped++;
+                rememberFailure([record], "queue_full");
                 if (publication) {
                     publication.dropped++;
                     publication.notify?.();
@@ -355,12 +407,17 @@ export function emitProxyOtelEvent(kind, record) {
         return;
     }
     try {
+        const ids = typeof record.requestId === "string" && !record.traceId
+            ? getProxyRequestTraceContext(record.requestId)
+            : undefined;
+        const correlated = ids ? { ...record, ...ids } : record;
         initializeProxyOtelLogs()
             ?.getLogger("neurolink-proxy-events")
             .emit({
+            context: proxyLogContext(correlated),
             severityNumber: SeverityNumber.INFO,
             severityText: "INFO",
-            body: JSON.stringify(record),
+            body: JSON.stringify(correlated),
             attributes: {
                 "proxy.record_kind": kind,
                 "event.name": `proxy.${kind}`,
@@ -444,6 +501,10 @@ export function getProxyOtelLogSnapshot() {
             kind: q.kind,
             capacity: q.capacity,
             ...q.state,
+            recentFailures: q.state.recentFailures.map((failure) => ({
+                ...failure,
+                records: failure.records.map((record) => ({ ...record })),
+            })),
         })),
     };
 }

package/dist/proxy/proxyTraceContext.d.ts

@@ -0,0 +1,21 @@
+import type { ProxyLogTraceContext } from "../types/index.js";
+/** Correlation belongs to the in-flight HTTP request, not to an async callback. */
+export declare function registerProxyRequestTraceContext(requestId: string, ids: ProxyLogTraceContext): void;
+/** Release once transport and terminal accounting have settled. */
+export declare function releaseProxyRequestTraceContext(requestId: string): void;
+/** Internal fallback records share their parent request's trace. */
+export declare function getProxyRequestTraceContext(requestId: string): ProxyLogTraceContext | undefined;
+/** Retain IDs and sampling flags before deferred processing leaves the request. */
+export declare function resolveProxyLogTraceContext(record: {
+    traceId?: unknown;
+    spanId?: unknown;
+    traceFlags?: unknown;
+    requestId?: unknown;
+}): ProxyLogTraceContext | undefined;
+/** Populate native OTLP correlation, including valid unsampled contexts. */
+export declare function proxyLogContext(record: {
+    traceId?: unknown;
+    spanId?: unknown;
+    traceFlags?: unknown;
+    requestId?: unknown;
+}): import("@opentelemetry/api").Context;

package/dist/proxy/proxyTraceContext.js

@@ -0,0 +1,47 @@
+import { context, ROOT_CONTEXT, trace, isSpanContextValid, } from "@opentelemetry/api";
+const requests = new Map();
+/** Correlation belongs to the in-flight HTTP request, not to an async callback. */
+export function registerProxyRequestTraceContext(requestId, ids) {
+    requests.set(requestId, ids);
+}
+/** Release once transport and terminal accounting have settled. */
+export function releaseProxyRequestTraceContext(requestId) {
+    requests.delete(requestId);
+}
+/** Internal fallback records share their parent request's trace. */
+export function getProxyRequestTraceContext(requestId) {
+    return (requests.get(requestId) ??
+        requests.get(requestId.replace(/:codex-fallback$/, "")));
+}
+/** Retain IDs and sampling flags before deferred processing leaves the request. */
+export function resolveProxyLogTraceContext(record) {
+    const saved = typeof record.requestId === "string"
+        ? getProxyRequestTraceContext(record.requestId)
+        : undefined;
+    const active = trace.getSpanContext(context.active());
+    const ids = typeof record.traceId === "string" && typeof record.spanId === "string"
+        ? { traceId: record.traceId, spanId: record.spanId }
+        : (saved ?? active);
+    if (!ids) {
+        return undefined;
+    }
+    const traceFlags = typeof record.traceFlags === "number" &&
+        Number.isInteger(record.traceFlags) &&
+        record.traceFlags >= 0 &&
+        record.traceFlags <= 255
+        ? record.traceFlags
+        : saved?.traceId === ids.traceId
+            ? saved.traceFlags
+            : active?.traceId === ids.traceId
+                ? active.traceFlags
+                : 0;
+    const result = { ...ids, traceFlags };
+    return isSpanContextValid(result)
+        ? { traceId: result.traceId, spanId: result.spanId, traceFlags }
+        : undefined;
+}
+/** Populate native OTLP correlation, including valid unsampled contexts. */
+export function proxyLogContext(record) {
+    const ids = resolveProxyLogTraceContext(record);
+    return ids ? trace.setSpanContext(ROOT_CONTEXT, ids) : context.active();
+}

package/dist/proxy/proxyTracer.d.ts

@@ -14,7 +14,7 @@
  * - TelemetryService for metrics recording
  */
 import { type Span } from "@opentelemetry/api";
-import type { AccountSelectionContext, ProxyRequestContext, ResponseInfoContext, UpstreamAttemptContext, UsageContext } from "../types/index.js";
+import type { AccountSelectionContext, ProxyRequestContext, ResponseInfoContext, UpstreamAttemptContext, UsageContext, RuntimeRequestMetadata, ProxyLogTraceContext } from "../types/index.js";
 declare class ProxyTracer {
     private readonly rootSpan;
     private readonly proxyTracer;
@@ -34,6 +34,8 @@ declare class ProxyTracer {
     private billingProvider;
     private readonly startTime;
     private readonly isStream;
+    private ended;
+    private recordRequestMetrics;
     private accountEmail?;
     private usage?;
     private mode;
@@ -102,10 +104,7 @@ declare class ProxyTracer {
     /** Record request and/or response body sizes for bandwidth tracking. */
     recordBodySizes(requestBytes?: number, responseBytes?: number): void;
     /** Return the OTel trace/span IDs for this request (for log correlation). */
-    getTraceContext(): {
-        traceId: string;
-        spanId: string;
-    };
+    getTraceContext(): ProxyLogTraceContext;
     /** Return the captured usage (set by setUsage). */
     getUsage(): UsageContext | undefined;
     /** End the root span with final HTTP status and duration, and emit OTEL metrics. */
@@ -126,3 +125,8 @@ export declare function recordFallbackAttempt(attrs: {
     durationMs: number;
 }): void;
 export { ProxyTracer };
+/** Standard SERVER span covers every proxy door, including parsing and admission failures. */
+export declare function startProxyHttpTrace(metadata: RuntimeRequestMetadata, headers: Record<string, string>): {
+    run: <T>(fn: () => T) => T;
+    end: (status: number, outcome: string, errorType?: string) => void;
+};

package/dist/proxy/proxyTracer.js

@@ -13,12 +13,13 @@
  * - calculateCost() from pricing.ts for cost tracking
  * - TelemetryService for metrics recording
  */
-import { SpanStatusCode, context, metrics, trace, } from "@opentelemetry/api";
+import { SpanStatusCode, SpanKind, ROOT_CONTEXT, isSpanContextValid, propagation, context, metrics, trace, } from "@opentelemetry/api";
 import { getTracer, setLangfuseContext, } from "../services/server/ai/observability/instrumentation.js";
 import { OtelBridge } from "../observability/otelBridge.js";
 import { calculateCost } from "../utils/pricing.js";
 import { TelemetryService } from "../telemetry/telemetryService.js";
 import { logger } from "../utils/logger.js";
+import { registerProxyRequestTraceContext, releaseProxyRequestTraceContext, } from "./proxyTraceContext.js";
 const LOG_PREFIX = "[ProxyTracer]";
 // ---------------------------------------------------------------------------
 // OTEL Metric Instruments — lazy singleton
@@ -205,6 +206,8 @@ class ProxyTracer {
     billingProvider;
     startTime;
     isStream;
+    ended = false;
+    recordRequestMetrics = true;
     accountEmail;
     usage;
     mode = "full";
@@ -226,7 +229,7 @@ class ProxyTracer {
         const tracer = getTracer("neurolink.proxy");
         // Extract parent context from incoming headers (Claude Code may send traceparent)
         let parentContext = context.active();
-        if (incomingHeaders) {
+        if (incomingHeaders && !trace.getSpan(context.active())) {
             const bridge = new OtelBridge();
             const extracted = bridge.extractContext(incomingHeaders);
             if (extracted) {
@@ -270,6 +273,7 @@ class ProxyTracer {
             rootSpan.setAttribute("neurolink.conversation_id", nlConversationId);
         }
         const instance = new ProxyTracer(rootSpan, ctx.requestId, ctx.model, ctx.stream, ctx.provider ?? "anthropic");
+        instance.recordRequestMetrics = ctx.recordRequestMetrics !== false;
         // Set Langfuse context (fire-and-forget — non-blocking)
         // Prefer NeuroLink session/user from calling SDK over Claude Code session
         setLangfuseContext({
@@ -607,6 +611,7 @@ class ProxyTracer {
         return {
             traceId: spanCtx.traceId,
             spanId: spanCtx.spanId,
+            traceFlags: spanCtx.traceFlags,
         };
     }
     /** Return the captured usage (set by setUsage). */
@@ -618,6 +623,10 @@ class ProxyTracer {
     // -------------------------------------------------------------------------
     /** End the root span with final HTTP status and duration, and emit OTEL metrics. */
     end(responseStatus, durationMs) {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
         this.rootSpan.setAttributes({
             "http.status_code": responseStatus,
             "proxy.duration_ms": durationMs,
@@ -636,6 +645,9 @@ class ProxyTracer {
             this.rootSpan.setStatus({ code: SpanStatusCode.OK });
         }
         this.rootSpan.end();
+        if (!this.recordRequestMetrics) {
+            return;
+        }
         // ---- Emit OTEL metrics (lazy-init instruments) ----
         const m = getProxyMetrics();
         const labels = {
@@ -745,3 +757,70 @@ export function recordFallbackAttempt(attrs) {
     }
 }
 export { ProxyTracer };
+/** Standard SERVER span covers every proxy door, including parsing and admission failures. */
+export function startProxyHttpTrace(metadata, headers) {
+    try {
+        // Match OtelBridge's existing compatibility policy for HTTP-combined
+        // traceparent values: retain the first injected parent.
+        const normalizedHeaders = { ...headers };
+        if (normalizedHeaders.traceparent?.includes(",")) {
+            normalizedHeaders.traceparent = normalizedHeaders.traceparent
+                .split(",", 1)[0]
+                .trim();
+        }
+        const parent = propagation.extract(ROOT_CONTEXT, normalizedHeaders);
+        const span = getTracer("neurolink.proxy").startSpan("proxy.http.request", {
+            kind: SpanKind.SERVER,
+            attributes: {
+                "http.request.method": metadata.method,
+                "url.path": metadata.path,
+                "proxy.request_id": metadata.requestId,
+            },
+        }, parent);
+        const spanContext = span.spanContext();
+        if (isSpanContextValid(spanContext)) {
+            metadata.traceId = spanContext.traceId;
+            metadata.spanId = spanContext.spanId;
+            metadata.traceFlags = spanContext.traceFlags;
+            registerProxyRequestTraceContext(metadata.requestId, {
+                traceId: spanContext.traceId,
+                spanId: spanContext.spanId,
+                traceFlags: spanContext.traceFlags,
+            });
+        }
+        const active = trace.setSpan(parent, span);
+        let ended = false;
+        return {
+            run: (fn) => context.with(active, fn),
+            end: (status, outcome, errorType) => {
+                if (ended) {
+                    return;
+                }
+                ended = true;
+                try {
+                    span.setAttributes({
+                        "http.response.status_code": status,
+                        "proxy.terminal_outcome": outcome,
+                        ...(errorType ? { "error.type": errorType } : {}),
+                    });
+                    if (status >= 500 ||
+                        outcome === "stream_error" ||
+                        outcome === "unknown") {
+                        span.setStatus({ code: SpanStatusCode.ERROR });
+                    }
+                    span.end();
+                }
+                catch {
+                    // Telemetry must not interrupt transport cleanup.
+                }
+                finally {
+                    releaseProxyRequestTraceContext(metadata.requestId);
+                }
+            },
+        };
+    }
+    catch {
+        releaseProxyRequestTraceContext(metadata.requestId);
+        return { run: (fn) => fn(), end: () => undefined };
+    }
+}

package/dist/proxy/requestLogger.js

@@ -21,6 +21,7 @@ import { SeverityNumber } from "@opentelemetry/api-logs";
 import { configureProxyLifecycleLogger } from "./proxyLifecycle.js";
 import { notifyProxyFinalLog, notifyProxyAttemptLog } from "./proxyActivity.js";
 import { withTimeout } from "../utils/async/withTimeout.js";
+import { resolveProxyLogTraceContext, proxyLogContext, } from "./proxyTraceContext.js";
 let logDir = null;
 let logEnabled = false;
 const pendingLogOperations = new Set();
@@ -184,6 +185,12 @@ export function initRequestLogger(enabled = true, customLogsDir) {
     }
 }
 export async function logRequest(entry) {
+    if (!entry.traceId || entry.traceFlags === undefined) {
+        const traceCtx = resolveProxyLogTraceContext(entry);
+        if (traceCtx) {
+            Object.assign(entry, traceCtx);
+        }
+    }
     entry.terminalOutcome ??=
         entry.errorType === "client_cancelled" || entry.responseStatus === 499
             ? "client_cancelled"
@@ -196,17 +203,6 @@ export async function logRequest(entry) {
     if (!logEnabled || (!logDir && !isProxyOtelOnly())) {
         return;
     }
-    // Only use OtelBridge if traceId not already provided by caller.
-    // Deferred .then() callbacks lose async context, so OtelBridge would
-    // return undefined and overwrite the valid traceId the caller passed.
-    if (!entry.traceId) {
-        const bridge = new OtelBridge();
-        const traceCtx = bridge.getCurrentTraceContext();
-        if (traceCtx) {
-            entry.traceId = traceCtx.traceId;
-            entry.spanId = traceCtx.spanId;
-        }
-    }
     if (isProxyOtelOnly()) {
         await emitOtlpLogRecord(entry);
         return;
@@ -228,12 +224,12 @@ export async function logRequest(entry) {
  * or OTLP-derived dashboard panels.
  */
 export async function logRequestAttempt(entry) {
-    if (!entry.traceId) {
-        const bridge = new OtelBridge();
-        const traceCtx = bridge.getCurrentTraceContext();
+    if (!entry.traceId || entry.traceFlags === undefined) {
+        const traceCtx = resolveProxyLogTraceContext(entry);
         if (traceCtx) {
             entry.traceId = traceCtx.traceId;
             entry.spanId = traceCtx.spanId;
+            entry.traceFlags = traceCtx.traceFlags;
         }
     }
     notifyProxyAttemptLog(entry);
@@ -313,6 +309,7 @@ function emitOtlpLogRecord(entry) {
             : SeverityNumber.INFO;
         const severityText = isError ? (isRateLimit ? "WARN" : "ERROR") : "INFO";
         otelLogger.emit({
+            context: proxyLogContext(entry),
             severityNumber,
             severityText,
             body: isProxyOtelOnly()
@@ -453,6 +450,7 @@ function emitOtlpBodyLogRecord(entry, stored) {
         const captureId = entry.captureId ?? randomUUID();
         const emit = (chunk, chunkIndex, totalChunks) => {
             otelLogger.emit({
+                context: proxyLogContext(entry),
                 severityNumber: (entry.responseStatus ?? 0) >= 400
                     ? SeverityNumber.WARN
                     : SeverityNumber.INFO,
@@ -526,12 +524,16 @@ export async function logBodyCapture(entry) {
     // not something a share token can be read as consenting to. The request is
     // still logged; only the bodies are dropped.
     if (isBorrowedRequest()) {
+        emitProxyOtelEvent("body_capture_index", {
+            timestamp: entry.timestamp,
+            requestId: entry.requestId,
+            captureId: entry.captureId ?? randomUUID(),
+            phase: entry.phase,
+            bodyDelivery: { status: "policy_excluded", reason: "borrowed_traffic" },
+        });
         return;
     }
-    const bridge = new OtelBridge();
-    const traceCtx = entry.traceId && entry.spanId
-        ? { traceId: entry.traceId, spanId: entry.spanId }
-        : bridge.getCurrentTraceContext();
+    const traceCtx = resolveProxyLogTraceContext(entry);
     const destination = logDir;
     // Publication callbacks retain metadata and the bounded redacted result,
     // never the original unbounded body while a sink is slow.
@@ -573,6 +575,7 @@ export async function logBodyCapture(entry) {
             originalRedactedBodyBytes: stored.originalRedactedBodyBytes,
             bodyWriteFailed: stored.bodyWriteFailed,
             captureError: processed.error,
+            captureAdmission: processed.admission,
             captureQueueWaitMs: processed.queueWaitMs,
             captureProcessingMs: processed.processingMs,
             metadata: processed.error ? undefined : metadata.metadata,
@@ -580,12 +583,14 @@ export async function logBodyCapture(entry) {
         if (traceCtx) {
             indexEntry.traceId = traceCtx.traceId;
             indexEntry.spanId = traceCtx.spanId;
+            indexEntry.traceFlags = traceCtx.traceFlags;
         }
         if (isProxyOtelOnly()) {
             const delivery = await emitOtlpBodyLogRecord({
                 ...metadata,
                 traceId: traceCtx?.traceId ?? metadata.traceId,
                 spanId: traceCtx?.spanId ?? metadata.spanId,
+                traceFlags: traceCtx?.traceFlags ?? metadata.traceFlags,
             }, stored);
             indexEntry.bodyDelivery = delivery ?? {
                 status: processed.error
@@ -612,6 +617,7 @@ export async function logBodyCapture(entry) {
             ...metadata,
             traceId: traceCtx?.traceId ?? metadata.traceId,
             spanId: traceCtx?.spanId ?? metadata.spanId,
+            traceFlags: traceCtx?.traceFlags ?? metadata.traceFlags,
         }, stored);
     };
     const operation = trackLogOperation(captureProxyBody(entry, destination, consume));

package/dist/proxy/restartControl.d.ts

@@ -0,0 +1,12 @@
+import type { ProxyRestartControlIdentity, ProxyRestartControlOptions, ProxyRestartResult } from "../types/index.js";
+/**
+ * Own restart completion in the supervisor, so a disconnected CLI cannot leave
+ * admission closed. The control socket is private to the service's OS user.
+ * No update history, launcher, environment file or launchd unit is rewritten.
+ */
+export declare function startProxyRestartControl(options: ProxyRestartControlOptions): Promise<{
+    identity: ProxyRestartControlIdentity;
+    close: () => Promise<void>;
+}>;
+/** Perform one local control operation; never fall back to killing a process. */
+export declare function requestProxyRestart(identity: ProxyRestartControlIdentity, check: boolean): Promise<ProxyRestartResult>;