@juspay/neurolink 12.12.9 → 12.12.10

package/dist/cli/commands/proxy.d.ts

@@ -60,6 +60,10 @@ export declare function isRollingHandoffCapable(state: ProxySupervisorState | nu
 export declare function processLooksLikeProxySupervisor(pid: number, expectedStartTimeIso?: string): Promise<boolean>;
 export declare function probeProxyHealth(host: string, port: number, timeoutMs: number): Promise<ProxyHealthProbe>;
 export declare function mapClaudeErrorTypeToStatus(errorType?: string): number;
+/**
+ * Assemble proxy routes with shared admission, runtime error accounting,
+ * and response tracking.
+ */
 export declare function createProxyStartApp(params: {
     neurolink: ProxyNeurolinkRuntime["neurolink"];
     modelRouter: ModelRouterInterface | undefined;

package/dist/cli/commands/proxy.js

@@ -27,11 +27,12 @@ import { startProxyLogCleanupScheduler } from "../../proxy/logCleanupScheduler.j
 import { anthropicAccountKeysEqual, createAccountAllowlist, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, normalizeAnthropicAccountKey, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
 import { resolveProxyStatusAccountIdentity } from "../../proxy/codexAccountUsage.js";
 import { beginProxyRequest, getProxyActivitySnapshot, observeProxyFinalLog, takeProxyResponseObservers, trackProxyResponse, } from "../../proxy/proxyActivity.js";
-import { flushProxyLifecycleEvents, getProxyLifecycleLoggerSnapshot, hashProxyLifecycleSessionId, logProxyLifecycleEvent, } from "../../proxy/proxyLifecycle.js";
+import { configureProxyLifecycleLogger, flushProxyLifecycleEvents, persistProxyLifecycleAcceptance, getProxyLifecycleLoggerSnapshot, hashProxyLifecycleSessionId, logProxyLifecycleEvent, } from "../../proxy/proxyLifecycle.js";
 import { describeInstallFailure, getGlobalInstallArgs, isTransientInstallFailure, resolveGlobalInstaller, validateInstalledVersion, } from "../../proxy/globalInstaller.js";
 import { startUpdaterWorkerSupervisor } from "../../proxy/updaterSupervisor.js";
 import { openProxyWorkerLog } from "../../proxy/workerLog.js";
 import { startRollingProxyServer } from "../../proxy/rollingProxyServer.js";
+import { isProxyAuxiliaryRequest } from "../../proxy/proxyRequestKind.js";
 import { spawnProxySocketWorker } from "../../proxy/rollingWorkerProcess.js";
 import { PROXY_ROLLING_SUPERVISOR_ENV, PROXY_SOCKET_WORKER_ENV, } from "../../proxy/rollingWorkerProtocol.js";
 import { attachSocketWorkerProcess } from "../../proxy/socketWorkerRuntime.js";
@@ -1056,7 +1057,12 @@ function redactStatusPrimaryAccount(primary) {
         source: primary.source,
     };
 }
+/**
+ * Confirm durable admission and reconcile route finals with the actual
+ * response transport lifecycle.
+ */
 function registerProxyRequestTracking(app, requestMetadata, readiness) {
+    /** Persist admission before dispatch and observe the response through termination. */
     const trackingHandler = async (c, next) => {
         const startedMonotonicMs = performance.now();
         const contentLengthHeader = c.req.raw.headers.get("content-length");
@@ -1097,17 +1103,16 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
         // The route adapter populates model/stream/toolCount after parsing. Omit
         // them at acceptance instead of publishing misleading placeholder values;
         // subsequent events carry the parsed metadata under the same request ID.
-        logProxyLifecycleEvent({
-            event: "request_accepted",
-            requestId: metadata.requestId,
-            method: metadata.method,
-            path: metadata.path,
-            sessionHash,
-            requestBytes,
-            elapsedMs: 0,
-            monotonicMs: startedMonotonicMs,
-        });
         try {
+            await persistProxyLifecycleAcceptance({
+                requestId: metadata.requestId,
+                method: metadata.method,
+                path: metadata.path,
+                sessionHash,
+                requestBytes,
+                elapsedMs: 0,
+                monotonicMs: startedMonotonicMs,
+            });
             await next();
             const responseStatus = c.res.status;
             logProxyLifecycleEvent({
@@ -1180,6 +1185,7 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                         accountingTimedOut = true;
                     }
                     const final = metadata.terminalResult;
+                    const auxiliary = isProxyAuxiliaryRequest(metadata.method, metadata.path);
                     const terminalOutcome = final?.terminalOutcome ??
                         (outcome === "stream_error" ||
                             metadata.terminalErrorType === "stream_error"
@@ -1188,7 +1194,9 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                                 ? "client_cancelled"
                                 : responseStatus >= 400
                                     ? "handler_error"
-                                    : "unknown");
+                                    : auxiliary
+                                        ? outcome
+                                        : "unknown");
                     logProxyLifecycleEvent({
                         event: "request_terminal",
                         timestampMs: terminalTimestampMs,
@@ -1210,7 +1218,9 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                         transportOutcome: outcome,
                         outcomeSource: final
                             ? "final_request"
-                            : responseStatus >= 400
+                            : responseStatus >= 400 ||
+                                (auxiliary &&
+                                    (outcome === "completed" || outcome === "bodyless"))
                                 ? "http_status"
                                 : terminalOutcome === "unknown"
                                     ? "unknown"
@@ -1219,7 +1229,7 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                             ? "timeout"
                             : accountingFailed
                                 ? "observer_error"
-                                : final
+                                : final || auxiliary
                                     ? "complete"
                                     : "missing_final",
                         errorType: final?.errorType ?? metadata.terminalErrorType,
@@ -1270,6 +1280,10 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
     app.use("/v1beta/*", trackingHandler);
     app.use("/backend-api/*", trackingHandler);
 }
+/**
+ * Assemble proxy routes with shared admission, runtime error accounting,
+ * and response tracking.
+ */
 export async function createProxyStartApp(params) {
     const { createClaudeProxyRoutes } = await import("../../server/routes/claudeProxyRoutes.js");
     const { createOpenAIProxyRoutes } = await import("../../server/routes/openaiProxyRoutes.js");
@@ -1356,9 +1370,13 @@ export async function createProxyStartApp(params) {
             stream: false,
             toolCount: 0,
         };
-        metadata.terminalErrorType = "unhandled_proxy_error";
         metadata.terminalErrorCode = getProxyRuntimeErrorCode(err);
-        await recordRuntimeError(metadata, 502, "unhandled_proxy_error", errMsg, {
+        const telemetryUnavailable = metadata.terminalErrorCode === "PROXY_TELEMETRY_UNAVAILABLE";
+        const status = telemetryUnavailable ? 503 : 502;
+        metadata.terminalErrorType = telemetryUnavailable
+            ? "telemetry_unavailable"
+            : "unhandled_proxy_error";
+        await recordRuntimeError(metadata, status, metadata.terminalErrorType, errMsg, {
             clientMessage: "Proxy internal error",
             clientErrorType: "api_error",
             errorCode: metadata.terminalErrorCode,
@@ -1370,7 +1388,7 @@ export async function createProxyStartApp(params) {
                 type: "api_error",
                 message: "Proxy internal error",
             },
-        }, 502);
+        }, status);
     });
     app.post("/internal/update-control", async (c) => {
         const suppliedToken = c.req.header("x-neurolink-update-token");
@@ -2270,6 +2288,7 @@ function startProxyBackgroundMaintenance(logsDir, getAccountAllowlist) {
     const logCleanupScheduler = startProxyLogCleanupScheduler({ logsDir });
     return { refreshInterval, logCleanupScheduler };
 }
+/** Register signal handlers and return the shared, idempotent drain-and-flush operation. */
 function registerProxyShutdownHandlers(params) {
     let shutdownStarted = false;
     /**
@@ -2329,6 +2348,7 @@ function registerProxyShutdownHandlers(params) {
             }
         });
     };
+    /** Stop background work, drain connections, and flush pending telemetry before exit. */
     const shutdown = async (signal, options) => {
         if (shutdownStarted) {
             return;
@@ -2359,7 +2379,9 @@ function registerProxyShutdownHandlers(params) {
         const [usageStatsFlushResult, lifecycleFlushResult, requestLogsFlushResult,] = await Promise.allSettled([
             withTimeout(usageStatsFlush, PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "Timed out flushing proxy usage statistics during shutdown"),
             withTimeout(flushProxyLifecycleEvents(), PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "Timed out flushing proxy lifecycle metadata during shutdown"),
-            withTimeout(requestLogsFlush, PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "Timed out flushing proxy request logs during shutdown"),
+            // This flush owns a separate bounded budget covering the body worker
+            // deadline plus index/OTLP publication; do not truncate it to five seconds.
+            requestLogsFlush,
         ]);
         if (usageStatsFlushResult.status === "rejected") {
             const error = usageStatsFlushResult.reason;
@@ -2413,6 +2435,7 @@ function registerProxyShutdownHandlers(params) {
     }
     return shutdown;
 }
+/** Start the HTTP runtime and connect its worker, configuration, and shutdown lifecycles. */
 async function startProxyRuntime(params) {
     const socketWorker = isProxySocketWorkerProcess();
     const { createAdaptorServer, serve } = await import("@hono/node-server");
@@ -2716,6 +2739,7 @@ async function startProxyRuntime(params) {
         attachSocketWorkerProcess(server, {
             generation: getProxyWorkerGeneration(),
             version: PROXY_VERSION,
+            processInstanceId: getProxyLifecycleLoggerSnapshot().processInstanceId,
             onActivated: () => {
                 persistInitialProxyState();
                 void reconcileActivatedUpdate();
@@ -2726,6 +2750,10 @@ async function startProxyRuntime(params) {
         });
     }
 }
+/**
+ * Run the stable listener and journal worker incidents independently of
+ * serving-process exits.
+ */
 async function runLaunchdProxySupervisor(argv, spinner) {
     await ensureProxyStartAllowed(spinner);
     const entryScript = process.argv[1];
@@ -2736,8 +2764,20 @@ async function runLaunchdProxySupervisor(argv, spinner) {
     const port = argv.port ?? 55669;
     const workerArgs = process.argv.slice(2);
     const supervisorStartedAt = new Date().toISOString();
+    configureProxyLifecycleLogger({
+        enabled: true,
+        logDir: join(homedir(), ".neurolink", "logs"),
+        filePrefix: "proxy-supervisor",
+    });
     let currentUpdaterPid;
     const rollingServer = await startRollingProxyServer({
+        onEvent: (event) => logProxyLifecycleEvent({
+            event: "supervisor_event",
+            requestId: "-",
+            method: "-",
+            path: "-",
+            supervisorEvent: event,
+        }),
         host,
         port,
         initialVersion: PROXY_VERSION,
@@ -2817,6 +2857,7 @@ async function runLaunchdProxySupervisor(argv, spinner) {
     }
     logger.always(`[proxy-supervisor] listening on ${host}:${rollingServer.address.port} workerPid=${rollingServer.snapshot().active?.pid ?? "unknown"} version=${PROXY_VERSION}`);
     let stopping = false;
+    /** Drain the rolling workers and flush the supervisor journal before clearing ownership. */
     const shutdown = async (signal) => {
         if (stopping) {
             return;
@@ -2826,6 +2867,7 @@ async function runLaunchdProxySupervisor(argv, spinner) {
         process.off("SIGUSR2", activatePendingUpdate);
         updaterSupervisor.stop();
         await rollingServer.close();
+        await flushProxyLifecycleEvents().catch((error) => logger.warn(String(error)));
         const supervisorState = loadProxySupervisorState();
         if (supervisorState?.pid === process.pid) {
             clearProxySupervisorState();

package/dist/cli/commands/proxyAnalyze.js

@@ -5,6 +5,10 @@ function formatLatency(label, summary) {
     const value = (amount) => amount === null ? "-" : amount.toFixed(1);
     return `${label.padEnd(22)} ${String(summary.count).padStart(7)} ${value(summary.p50).padStart(9)} ${value(summary.p95).padStart(9)} ${value(summary.p99).padStart(9)} ${value(summary.max).padStart(9)}`;
 }
+/**
+ * Render the offline evidence report without converting missing outcomes
+ * into inferred success.
+ */
 function printAnalysis(report) {
     logger.always("");
     logger.always(chalk.bold.cyan("NeuroLink Proxy Analysis"));
@@ -33,8 +37,11 @@ function printAnalysis(report) {
         }
     }
     logger.always(report.coverage.lifecycle
-        ? `    Lifecycle: ${report.lifecycle.accepted} accepted, ${report.lifecycle.terminal} terminal, ${report.lifecycle.unsettled} unsettled`
+        ? `    Lifecycle: ${report.lifecycle.accepted} accepted (${report.lifecycle.auxiliaryRequests} auxiliary), ${report.lifecycle.terminal} terminal, ${report.lifecycle.unsettled} unsettled (${report.lifecycle.unconfirmedAtWorkerExit.length} unconfirmed at worker exit)`
         : chalk.yellow("    Lifecycle: unavailable (no lifecycle metadata)"));
+    if (report.runtime.samples > 0) {
+        logger.always(`    Runtime: ${report.runtime.samples} samples, max event-loop delay ${report.runtime.maxEventLoopDelayMs ?? "unknown"}ms, max CPU ${report.runtime.maxCpuPercentOneCore?.toFixed(1) ?? "unknown"}% of one core, max host load ${report.runtime.maxHostLoad1m ?? "unknown"}`);
+    }
     if (report.coverage.attempts) {
         const finalRateLimits = report.coverage.finalRequests
             ? `${report.requests.finalRateLimits} final`

package/dist/proxy/bodyCaptureProcessing.d.ts

@@ -0,0 +1,22 @@
+import type { ProxyBodyCaptureEntry, ProcessedProxyBodyCapture } from "../types/index.js";
+/**
+ * Split redacted text into byte-bounded OTLP chunks without splitting
+ * encoded characters.
+ */
+export declare function splitUtf8StringByBytes(input: string, maxBytes: number): string[];
+/** Shared pure redaction for replay; serving paths invoke it in the worker. */
+export declare function prepareProxyBodyForLogging(body: unknown): {
+    value?: string;
+    bytes?: number;
+    truncated: boolean;
+};
+/**
+ * Expose the same header-redaction policy to replay and metadata
+ * consumers.
+ */
+export declare function redactProxyHeadersForLogging(headers: Record<string, string> | undefined): Record<string, string> | undefined;
+/**
+ * Process a capture in the worker and retain redacted output when artifact
+ * persistence fails.
+ */
+export declare function processProxyBodyCapture(entry: ProxyBodyCaptureEntry, logDir: string): Promise<ProcessedProxyBodyCapture>;

package/dist/proxy/bodyCaptureProcessing.js

@@ -0,0 +1,219 @@
+import { join } from "node:path";
+import { mkdir, chmod, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { promisify } from "node:util";
+import { gzip as gzipCallback } from "node:zlib";
+const REQUEST_LOG_IO_TIMEOUT_MS = 5_000;
+/** Maximum redacted body bytes persisted per capture entry. */
+const MAX_CAPTURED_BODY_BYTES = 1024 * 1024;
+const BODY_TRUNCATION_MARKER = "\n...[TRUNCATED]";
+const gzip = promisify(gzipCallback);
+/** Headers whose values must always be redacted. */
+const SENSITIVE_HEADER_NAMES = new Set([
+    "authorization",
+    "proxy-authorization",
+    "x-api-key",
+    "cookie",
+    "set-cookie",
+]);
+/** Pattern that matches header names likely to contain secrets. */
+const SENSITIVE_HEADER_PATTERN = /token|secret|key|password|credential/i;
+/** JSON keys whose values should be redacted in request/response bodies. */
+const SENSITIVE_BODY_KEYS = /("(?:password|access_token|refresh_token|api_key|apiKey|secret|authorization|token|credential|x-api-key)"\s*:\s*)"(?:[^"\\]|\\.)*"/gi;
+/**
+ * Copy headers while removing credential values, including custom
+ * secret-bearing header names.
+ */
+function redactHeaders(headers) {
+    if (!headers) {
+        return headers;
+    }
+    const redacted = {};
+    for (const [key, value] of Object.entries(headers)) {
+        const lower = key.toLowerCase();
+        if (SENSITIVE_HEADER_NAMES.has(lower) ||
+            SENSITIVE_HEADER_PATTERN.test(lower)) {
+            redacted[key] = "[REDACTED]";
+        }
+        else {
+            redacted[key] = value;
+        }
+    }
+    return redacted;
+}
+const SENSITIVE_BODY_KEY = /^(?:password|access_token|refresh_token|api_key|apiKey|secret|authorization|token|credential|x-api-key)$/i;
+/** Redact every value under a sensitive key, including objects and arrays. */
+function redactBody(body) {
+    if (body === undefined || body === null) {
+        return undefined;
+    }
+    let value = body;
+    if (typeof body === "string") {
+        try {
+            value = JSON.parse(body);
+        }
+        catch {
+            // Non-JSON bodies (including SSE transcripts) keep the legacy fallback.
+            return body.replace(SENSITIVE_BODY_KEYS, '$1"[REDACTED]"');
+        }
+    }
+    return JSON.stringify(value, (key, nested) => SENSITIVE_BODY_KEY.test(key) ? "[REDACTED]" : nested);
+}
+/**
+ * Restrict request and phase identifiers to characters safe for artifact
+ * path components.
+ */
+function sanitizePhase(phase) {
+    return phase.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+/**
+ * Hash the redacted artifact body so offline reconstruction can verify its
+ * contents.
+ */
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/**
+ * Measure persisted UTF-8 bytes rather than JavaScript UTF-16 character
+ * counts.
+ */
+function utf8ByteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+/**
+ * Reserve space for the truncation marker and cut only at a UTF-8 code
+ * point boundary.
+ */
+function truncateUtf8String(input, maxBytes, marker = BODY_TRUNCATION_MARKER) {
+    const inputBytes = utf8ByteLength(input);
+    if (inputBytes <= maxBytes) {
+        return { value: input, bytes: inputBytes, truncated: false };
+    }
+    const markerBytes = utf8ByteLength(marker);
+    if (maxBytes <= markerBytes) {
+        return { value: marker, bytes: markerBytes, truncated: true };
+    }
+    const buffer = Buffer.from(input, "utf8");
+    let end = maxBytes - markerBytes;
+    while (end > 0 && (buffer[end] & 0xc0) === 0x80) {
+        end -= 1;
+    }
+    const value = buffer.subarray(0, end).toString("utf8");
+    const truncatedValue = `${value}${marker}`;
+    return {
+        value: truncatedValue,
+        bytes: utf8ByteLength(truncatedValue),
+        truncated: true,
+    };
+}
+/**
+ * Split redacted text into byte-bounded OTLP chunks without splitting
+ * encoded characters.
+ */
+export function splitUtf8StringByBytes(input, maxBytes) {
+    if (!input) {
+        return [""];
+    }
+    const chunks = [];
+    const buffer = Buffer.from(input, "utf8");
+    for (let start = 0; start < buffer.length;) {
+        let end = Math.min(start + Math.max(4, maxBytes), buffer.length);
+        while (end < buffer.length && (buffer[end] & 0xc0) === 0x80) {
+            end -= 1;
+        }
+        chunks.push(buffer.subarray(start, end).toString("utf8"));
+        start = end;
+    }
+    return chunks;
+}
+/**
+ * Apply structural redaction before enforcing the per-artifact byte
+ * ceiling.
+ */
+function prepareRedactedBody(body) {
+    const redacted = redactBody(body);
+    if (redacted === undefined) {
+        return { truncated: false };
+    }
+    return truncateUtf8String(redacted, MAX_CAPTURED_BODY_BYTES);
+}
+/**
+ * Write a private gzip artifact with a unique name and return its
+ * redacted-body digest.
+ */
+async function writeBodyArtifact(logDir, entry, redactedHeaders, redactedBody, bodyTruncated) {
+    if (redactedBody === undefined) {
+        return {};
+    }
+    const dateStr = new Date(entry.timestamp).toISOString().split("T")[0];
+    const bodyDir = join(logDir, "bodies", dateStr, sanitizePhase(entry.requestId));
+    await mkdir(bodyDir, { recursive: true, mode: 0o700 });
+    await chmod(bodyDir, 0o700);
+    const fileName = `${randomUUID()}-${sanitizePhase(entry.phase)}` +
+        (entry.attempt !== undefined ? `-attempt-${entry.attempt}` : "") +
+        `.json.gz`;
+    const bodyPath = join(bodyDir, fileName);
+    const payload = JSON.stringify({
+        timestamp: entry.timestamp,
+        requestId: entry.requestId,
+        phase: entry.phase,
+        model: entry.model,
+        stream: entry.stream,
+        account: entry.account,
+        accountType: entry.accountType,
+        attempt: entry.attempt,
+        responseStatus: entry.responseStatus,
+        durationMs: entry.durationMs,
+        contentType: entry.contentType,
+        headers: redactedHeaders,
+        body: redactedBody,
+        traceId: entry.traceId,
+        spanId: entry.spanId,
+        metadata: entry.metadata,
+    });
+    const compressed = await gzip(payload);
+    await writeFile(bodyPath, compressed, {
+        mode: 0o600,
+        signal: AbortSignal.timeout(REQUEST_LOG_IO_TIMEOUT_MS),
+    });
+    return {
+        bodyPath,
+        bodySha256: sha256(redactedBody),
+        redactedBodyBytes: utf8ByteLength(redactedBody),
+        storedFileBytes: compressed.byteLength,
+        redactedBody,
+        bodyTruncated,
+    };
+}
+/** Shared pure redaction for replay; serving paths invoke it in the worker. */
+export function prepareProxyBodyForLogging(body) {
+    return prepareRedactedBody(body);
+}
+/**
+ * Expose the same header-redaction policy to replay and metadata
+ * consumers.
+ */
+export function redactProxyHeadersForLogging(headers) {
+    return redactHeaders(headers);
+}
+/**
+ * Process a capture in the worker and retain redacted output when artifact
+ * persistence fails.
+ */
+export async function processProxyBodyCapture(entry, logDir) {
+    const headers = redactHeaders(entry.headers);
+    const prepared = prepareRedactedBody(entry.body);
+    let stored;
+    try {
+        stored = await writeBodyArtifact(logDir, entry, headers, prepared.value, prepared.truncated);
+    }
+    catch {
+        stored = {
+            redactedBody: prepared.value,
+            redactedBodyBytes: prepared.bytes,
+            bodyTruncated: prepared.truncated,
+            bodyWriteFailed: true,
+        };
+    }
+    return { headers, stored };
+}

package/dist/proxy/bodyCaptureWorker.d.ts

@@ -0,0 +1,16 @@
+import type { ProcessedProxyBodyCapture, ProxyBodyCaptureEntry, ProxyBodyCaptureWorkerSnapshot } from "../types/index.js";
+export declare const PROXY_BODY_CAPTURE_DEADLINE_MS = 20000;
+/** Bounded bulk capture. Failures are indexed; never fall back to blocking work. */
+export declare function captureProxyBody(entry: ProxyBodyCaptureEntry, logDir: string, consume: (result: ProcessedProxyBodyCapture) => Promise<void>): Promise<void>;
+/**
+ * Return independent counters for processing, rejection, failure, and
+ * retained publication work.
+ */
+export declare function getBodyCaptureWorkerSnapshot(): ProxyBodyCaptureWorkerSnapshot;
+/** Isolated tests point at a separately executed built worker. */
+export declare const __bodyCaptureWorkerTestHooks: {
+    /**
+     * Reset an isolated worker after capture publications drain, optionally selecting a fixture entry.
+     */
+    reset(url?: URL): Promise<void>;
+};