@juspay/neurolink 9.92.2 → 9.93.0

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

@@ -10,6 +10,7 @@
  * (generate/stream), with an optional ModelRouter for model remapping.
  */
 import type { CommandModule } from "yargs";
+import type { Hono } from "hono";
 import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxyStatusArgs, ProxyTelemetryArgs } from "../../lib/types/index.js";
 import { ProxyRuntimeConfigStore } from "../../lib/proxy/runtimeConfig.js";
 export declare function mapClaudeErrorTypeToStatus(errorType?: string): number;
@@ -25,7 +26,7 @@ export declare function createProxyStartApp(params: {
     accountAllowlist: AccountAllowlist | undefined;
     runtimeConfigStore?: ProxyRuntimeConfigStore;
 }): Promise<{
-    app: import("hono").Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
     readiness: import("../../lib/types/proxy.js").ProxyReadinessState;
 }>;
 export declare const proxyStartCommand: CommandModule<object, ProxyStartArgs>;

package/dist/cli/commands/proxy.js

@@ -16,11 +16,13 @@ import chalk from "chalk";
 import ora from "ora";
 import { buildProxyHealthResponse, createProxyReadinessState, markProxyReady, waitForProxyReadiness, } from "../../lib/proxy/proxyHealth.js";
 import { logger } from "../../lib/utils/logger.js";
+import { withTimeout } from "../../lib/utils/async/withTimeout.js";
 import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
 import { configureProxyKeepAliveDispatcher } from "../../lib/proxy/proxyDispatcher.js";
 import { ProxyRuntimeConfigStore } from "../../lib/proxy/runtimeConfig.js";
 import { anthropicAccountKeysEqual, createAccountAllowlist, ENV_ANTHROPIC_ACCOUNT_KEY, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, normalizeAnthropicAccountKey, shouldLoadFallbackCredential, } from "../../lib/proxy/accountSelection.js";
 import { beginProxyRequest, getProxyActivitySnapshot, trackProxyResponse, } from "../../lib/proxy/proxyActivity.js";
+import { flushProxyLifecycleEvents, getProxyLifecycleLoggerSnapshot, hashProxyLifecycleSessionId, logProxyLifecycleEvent, } from "../../lib/proxy/proxyLifecycle.js";
 import { describeInstallFailure, getGlobalInstallArgs, resolveGlobalInstaller, validateInstalledVersion, } from "../../lib/proxy/globalInstaller.js";
 import { startUpdaterWorkerSupervisor } from "../../lib/proxy/updaterSupervisor.js";
 import { abandonPendingUpdate, isVersionSuppressed, loadUpdateState, recordCheck, recordSuccessfulUpdate, recordUpdateFailure, recordUpdateInstalled, suppressVersion, } from "../../lib/proxy/updateState.js";
@@ -31,6 +33,7 @@ import packageJson from "../../../package.json" with { type: "json" };
 const _require = createRequire(import.meta.url);
 const PROXY_VERSION = packageJson.version;
 const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/observability/manage-local-openobserve.sh", import.meta.url));
+const PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS = 5_000;
 // =============================================================================
 // STATE MANAGEMENT
 // =============================================================================
@@ -643,6 +646,20 @@ export function mapClaudeErrorTypeToStatus(errorType) {
             return 502;
     }
 }
+function getProxyRuntimeErrorCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 3; depth += 1) {
+        if (!current || typeof current !== "object") {
+            return undefined;
+        }
+        const code = current.code;
+        if (typeof code === "string") {
+            return code;
+        }
+        current = current.cause;
+    }
+    return undefined;
+}
 async function ensureProxyStartAllowed(spinner) {
     const ignoreLaunchd = process.env.NEUROLINK_PROXY_IGNORE_LAUNCHD === "1" ||
         process.env.NEUROLINK_PROXY_IGNORE_LAUNCHD === "true";
@@ -710,6 +727,125 @@ async function createProxyNeurolinkRuntime(logsDir) {
     cleanupLogs(7, 500);
     return { neurolink, cleanupLogs };
 }
+function registerProxyRequestTracking(app, requestMetadata) {
+    app.use("/v1/*", async (c, next) => {
+        const startedMonotonicMs = performance.now();
+        const contentLengthHeader = c.req.raw.headers.get("content-length");
+        const rawContentLength = contentLengthHeader === null ? Number.NaN : Number(contentLengthHeader);
+        const requestBytes = Number.isFinite(rawContentLength) && rawContentLength >= 0
+            ? rawContentLength
+            : undefined;
+        const sessionId = c.req.raw.headers.get("x-neurolink-session-id") ??
+            c.req.raw.headers.get("x-claude-code-session-id") ??
+            undefined;
+        const sessionHash = hashProxyLifecycleSessionId(sessionId);
+        const metadata = {
+            requestId: crypto.randomUUID(),
+            method: c.req.method,
+            path: c.req.path,
+            startedAt: Date.now(),
+            model: "-",
+            stream: false,
+            toolCount: 0,
+        };
+        requestMetadata.set(c.req.raw, metadata);
+        const finishActivity = beginProxyRequest();
+        const finish = () => {
+            finishActivity();
+            requestMetadata.delete(c.req.raw);
+        };
+        // 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 next();
+            const responseStatus = c.res.status;
+            logProxyLifecycleEvent({
+                event: "response_headers",
+                requestId: metadata.requestId,
+                method: metadata.method,
+                path: metadata.path,
+                model: metadata.model,
+                stream: metadata.stream,
+                toolCount: metadata.toolCount,
+                sessionHash,
+                requestBytes,
+                responseStatus,
+                elapsedMs: performance.now() - startedMonotonicMs,
+            });
+            c.res = trackProxyResponse(c.res, finish, {
+                onFirstChunk: ({ observedBodyBytes, responseChunks }) => {
+                    logProxyLifecycleEvent({
+                        event: "response_first_chunk",
+                        requestId: metadata.requestId,
+                        method: metadata.method,
+                        path: metadata.path,
+                        model: metadata.model,
+                        stream: metadata.stream,
+                        toolCount: metadata.toolCount,
+                        sessionHash,
+                        requestBytes,
+                        responseStatus,
+                        observedBodyBytes,
+                        responseChunks,
+                        elapsedMs: performance.now() - startedMonotonicMs,
+                    });
+                },
+                onTerminal: ({ outcome, observedBodyBytes, responseChunks }) => {
+                    logProxyLifecycleEvent({
+                        event: "request_terminal",
+                        requestId: metadata.requestId,
+                        method: metadata.method,
+                        path: metadata.path,
+                        model: metadata.model,
+                        stream: metadata.stream,
+                        toolCount: metadata.toolCount,
+                        sessionHash,
+                        requestBytes,
+                        responseStatus,
+                        observedBodyBytes,
+                        responseChunks,
+                        elapsedMs: performance.now() - startedMonotonicMs,
+                        terminalOutcome: outcome,
+                        errorType: metadata.terminalErrorType,
+                        errorCode: metadata.terminalErrorCode,
+                    });
+                },
+            });
+        }
+        catch (error) {
+            // Keep metadata available to app.onError, which records the client-facing
+            // failure with the same request ID before deleting the WeakMap entry.
+            finishActivity();
+            logProxyLifecycleEvent({
+                event: "request_terminal",
+                requestId: metadata.requestId,
+                method: metadata.method,
+                path: metadata.path,
+                model: metadata.model,
+                stream: metadata.stream,
+                toolCount: metadata.toolCount,
+                sessionHash,
+                requestBytes,
+                elapsedMs: performance.now() - startedMonotonicMs,
+                terminalOutcome: "handler_error",
+                errorType: error instanceof Error ? error.name : "unknown_error",
+                errorCode: getProxyRuntimeErrorCode(error),
+            });
+            throw error;
+        }
+    });
+}
 export async function createProxyStartApp(params) {
     const { createClaudeProxyRoutes } = await import("../../lib/server/routes/claudeProxyRoutes.js");
     const { createOpenAIProxyRoutes } = await import("../../lib/server/routes/openaiProxyRoutes.js");
@@ -719,7 +855,9 @@ export async function createProxyStartApp(params) {
     const app = new Hono();
     const readiness = createProxyReadinessState();
     const requestMetadata = new WeakMap();
-    const recordRuntimeError = async (metadata, status, errorType, errorMessage, clientMessage = errorMessage, clientErrorType = errorType) => {
+    const recordRuntimeError = async (metadata, status, errorType, errorMessage, options) => {
+        const clientMessage = options?.clientMessage ?? errorMessage;
+        const clientErrorType = options?.clientErrorType ?? errorType;
         recordFinalError(status);
         await Promise.all([
             logRequest({
@@ -736,6 +874,7 @@ export async function createProxyStartApp(params) {
                 responseTimeMs: Date.now() - metadata.startedAt,
                 errorType,
                 errorMessage,
+                ...(options?.errorCode ? { errorCode: options.errorCode } : {}),
             }),
             logBodyCapture({
                 timestamp: new Date().toISOString(),
@@ -769,7 +908,13 @@ export async function createProxyStartApp(params) {
             stream: false,
             toolCount: 0,
         };
-        await recordRuntimeError(metadata, 502, "unhandled_proxy_error", errMsg, "Proxy internal error", "api_error");
+        metadata.terminalErrorType = "unhandled_proxy_error";
+        metadata.terminalErrorCode = getProxyRuntimeErrorCode(err);
+        await recordRuntimeError(metadata, 502, "unhandled_proxy_error", errMsg, {
+            clientMessage: "Proxy internal error",
+            clientErrorType: "api_error",
+            errorCode: metadata.terminalErrorCode,
+        });
         requestMetadata.delete(c.req.raw);
         return c.json({
             type: "error",
@@ -779,31 +924,7 @@ export async function createProxyStartApp(params) {
             },
         }, 502);
     });
-    app.use("/v1/*", async (c, next) => {
-        const metadata = {
-            requestId: crypto.randomUUID(),
-            method: c.req.method,
-            path: c.req.path,
-            startedAt: Date.now(),
-            model: "-",
-            stream: false,
-            toolCount: 0,
-        };
-        requestMetadata.set(c.req.raw, metadata);
-        const finishActivity = beginProxyRequest();
-        const finish = () => {
-            finishActivity();
-            requestMetadata.delete(c.req.raw);
-        };
-        try {
-            await next();
-            c.res = trackProxyResponse(c.res, finish);
-        }
-        catch (error) {
-            finishActivity();
-            throw error;
-        }
-    });
+    registerProxyRequestTracking(app, requestMetadata);
     const runtimeConfigStore = params.runtimeConfigStore;
     const runtimeConfigProvider = runtimeConfigStore
         ? () => runtimeConfigStore.getSnapshot()
@@ -1042,6 +1163,9 @@ export async function createProxyStartApp(params) {
                     lastActivityAt: activity.lastActivityAt?.toISOString() ?? null,
                 };
             })(),
+            observability: {
+                lifecycle: getProxyLifecycleLoggerSnapshot(),
+            },
             autoUpdate: {
                 enabled: isProxyAutoUpdateEnabled(),
                 updaterPid: runtimeState?.updaterPid ?? null,
@@ -1339,6 +1463,12 @@ function registerProxyShutdownHandlers(params) {
             exitCode = 1;
             logger.error(`[proxy] failed to drain server during shutdown: ${error instanceof Error ? error.message : String(error)}`);
         }
+        try {
+            await withTimeout(flushProxyLifecycleEvents(), PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "Timed out flushing proxy lifecycle metadata during shutdown");
+        }
+        catch (error) {
+            logger.debug(`[proxy] lifecycle metadata flush failed during shutdown: ${error instanceof Error ? error.message : String(error)}`);
+        }
         try {
             const { flushOpenTelemetry, shutdownOpenTelemetry } = await import("../../lib/services/server/ai/observability/instrumentation.js");
             await flushOpenTelemetry();

package/dist/lib/proxy/proxyActivity.d.ts

@@ -1,8 +1,8 @@
-import type { ProxyActivitySnapshot } from "../types/index.js";
+import type { ProxyActivitySnapshot, ProxyResponseTrackingObserver } from "../types/index.js";
 /** Track one client-facing proxy request until its response body settles. */
 export declare function beginProxyRequest(): () => void;
 export declare function getProxyActivitySnapshot(): ProxyActivitySnapshot;
 export declare function isProxyActivityQuiet(snapshot: ProxyActivitySnapshot, quietThresholdMs: number, nowMs?: number): boolean;
 /** Keep activity open until the response body completes, errors, or is cancelled. */
-export declare function trackProxyResponse(response: Response, finishRequest: () => void): Response;
+export declare function trackProxyResponse(response: Response, finishRequest: () => void, observer?: ProxyResponseTrackingObserver): Response;
 export declare function resetProxyActivityForTests(): void;

package/dist/lib/proxy/proxyActivity.js

@@ -1,8 +1,24 @@
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { logger } from "../utils/logger.js";
+const PROXY_RESPONSE_CANCEL_TIMEOUT_MS = 1_000;
 let activeRequests = 0;
 let lastActivityAtMs = null;
 function touchActivity() {
     lastActivityAtMs = Date.now();
 }
+function safelyNotifyObserver(callback) {
+    try {
+        callback?.();
+    }
+    catch (error) {
+        // Observability must never alter response handling.
+        if (logger.shouldLog("debug")) {
+            logger.debug("[proxy] response lifecycle observer failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
 /** Track one client-facing proxy request until its response body settles. */
 export function beginProxyRequest() {
     activeRequests += 1;
@@ -33,35 +49,59 @@ export function isProxyActivityQuiet(snapshot, quietThresholdMs, nowMs = Date.no
     return nowMs - snapshot.lastActivityAt.getTime() >= quietThresholdMs;
 }
 /** Keep activity open until the response body completes, errors, or is cancelled. */
-export function trackProxyResponse(response, finishRequest) {
+export function trackProxyResponse(response, finishRequest, observer) {
     if (!response.body) {
         finishRequest();
+        safelyNotifyObserver(() => observer?.onTerminal?.({
+            outcome: "bodyless",
+            observedBodyBytes: 0,
+            responseChunks: 0,
+        }));
         return response;
     }
     const reader = response.body.getReader();
+    let observedBodyBytes = 0;
+    let responseChunks = 0;
+    let settled = false;
+    const settle = (outcome) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        finishRequest();
+        safelyNotifyObserver(() => observer?.onTerminal?.({
+            outcome,
+            observedBodyBytes,
+            responseChunks,
+        }));
+    };
     const trackedBody = new ReadableStream({
         async pull(controller) {
             try {
                 const { value, done } = await reader.read();
                 if (done) {
-                    finishRequest();
+                    settle("completed");
                     controller.close();
                     return;
                 }
                 controller.enqueue(value);
+                observedBodyBytes += value.byteLength;
+                responseChunks += 1;
+                if (responseChunks === 1) {
+                    safelyNotifyObserver(() => observer?.onFirstChunk?.({
+                        observedBodyBytes,
+                        responseChunks: 1,
+                    }));
+                }
             }
             catch (error) {
-                finishRequest();
+                settle("stream_error");
                 controller.error(error);
             }
         },
         async cancel(reason) {
-            try {
-                await reader.cancel(reason);
-            }
-            finally {
-                finishRequest();
-            }
+            settle("client_cancelled");
+            await withTimeout(reader.cancel(reason), PROXY_RESPONSE_CANCEL_TIMEOUT_MS, "Timed out cancelling the upstream proxy response");
         },
     });
     return new Response(trackedBody, {

package/dist/lib/proxy/proxyLifecycle.d.ts

@@ -0,0 +1,8 @@
+import type { ProxyLifecycleEventInput, ProxyLifecycleLoggerOptions, ProxyLifecycleLoggerSnapshot } from "../types/index.js";
+export declare function hashProxyLifecycleSessionId(sessionId: string | undefined): string | undefined;
+export declare function configureProxyLifecycleLogger(options: ProxyLifecycleLoggerOptions): void;
+/** Enqueue fixed-size lifecycle metadata without awaiting filesystem work. */
+export declare function logProxyLifecycleEvent(input: ProxyLifecycleEventInput): void;
+export declare function flushProxyLifecycleEvents(): Promise<void>;
+export declare function getProxyLifecycleLoggerSnapshot(): ProxyLifecycleLoggerSnapshot;
+export declare function resetProxyLifecycleLoggerForTests(): void;