@juspay/neurolink 9.92.3 → 9.93.0

package/dist/lib/proxy/proxyLifecycle.js

@@ -0,0 +1,333 @@
+import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { logger } from "../utils/logger.js";
+const SCHEMA_VERSION = 1;
+const DEFAULT_QUEUE_CAPACITY = 10_000;
+const DEFAULT_BATCH_SIZE = 256;
+const DEFAULT_FLUSH_INTERVAL_MS = 25;
+const LIFECYCLE_APPEND_TIMEOUT_MS = 2_000;
+const MAX_SHORT_FIELD_LENGTH = 256;
+const SESSION_KEY_FILE = ".proxy-lifecycle-session-key";
+let loggerEnabled = false;
+let lifecycleLogDir;
+let queueCapacity = DEFAULT_QUEUE_CAPACITY;
+let batchSize = DEFAULT_BATCH_SIZE;
+let flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS;
+let processInstanceId = randomUUID();
+let sessionHashKey = randomBytes(32);
+let nextSequence = 1;
+let attempted = 0;
+let enqueued = 0;
+let written = 0;
+let dropped = 0;
+let queueDrops = 0;
+let invalidDrops = 0;
+let writeDrops = 0;
+let writeFailures = 0;
+let inFlight = 0;
+let queue = [];
+let flushTimer;
+let flushInFlight;
+function positiveInteger(value, fallback) {
+    return Number.isInteger(value) && (value ?? 0) > 0
+        ? value
+        : fallback;
+}
+function clip(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    return value.length <= MAX_SHORT_FIELD_LENGTH
+        ? value
+        : value.slice(0, MAX_SHORT_FIELD_LENGTH);
+}
+function finiteNonNegative(value) {
+    return value !== undefined && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
+function nonNegativeInteger(value) {
+    const finite = finiteNonNegative(value);
+    return finite === undefined ? undefined : Math.floor(finite);
+}
+function formatTimestamp(timestampMs) {
+    const candidate = typeof timestampMs === "number" && Number.isFinite(timestampMs)
+        ? timestampMs
+        : Date.now();
+    const date = new Date(candidate);
+    return Number.isFinite(date.getTime())
+        ? date.toISOString()
+        : new Date().toISOString();
+}
+function readPersistedSessionHashKey(path) {
+    try {
+        const key = Buffer.from(readFileSync(path, "utf8").trim(), "base64");
+        if (key.length !== 32) {
+            throw new Error("persisted lifecycle session key must contain 32 bytes");
+        }
+        chmodSync(path, 0o600);
+        return key;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function resolveSessionHashKey(logDir) {
+    const configuredSecret = process.env.NEUROLINK_PROXY_SESSION_SECRET?.trim();
+    if (configuredSecret) {
+        return createHash("sha256").update(configuredSecret).digest();
+    }
+    const keyPath = join(logDir, SESSION_KEY_FILE);
+    const existing = readPersistedSessionHashKey(keyPath);
+    if (existing) {
+        return existing;
+    }
+    const generated = randomBytes(32);
+    try {
+        writeFileSync(keyPath, generated.toString("base64"), {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        return generated;
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            const concurrentlyCreated = readPersistedSessionHashKey(keyPath);
+            if (concurrentlyCreated) {
+                return concurrentlyCreated;
+            }
+        }
+        throw error;
+    }
+}
+export function hashProxyLifecycleSessionId(sessionId) {
+    if (!sessionId) {
+        return undefined;
+    }
+    return createHmac("sha256", sessionHashKey)
+        .update(sessionId)
+        .digest("hex")
+        .slice(0, 24);
+}
+function clearScheduledFlush() {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = undefined;
+    }
+}
+function scheduleFlush() {
+    if (flushTimer || flushInFlight || queue.length === 0) {
+        return;
+    }
+    flushTimer = setTimeout(() => {
+        flushTimer = undefined;
+        void startFlush();
+    }, flushIntervalMs);
+    flushTimer.unref?.();
+}
+async function flushBatch() {
+    if (queue.length === 0) {
+        return;
+    }
+    const batch = queue.splice(0, batchSize);
+    inFlight += batch.length;
+    try {
+        const byPath = new Map();
+        for (const item of batch) {
+            const path = join(item.logDir, `proxy-lifecycle-${item.date}.jsonl`);
+            const lines = byPath.get(path) ?? [];
+            lines.push(`${JSON.stringify(item.record)}\n`);
+            byPath.set(path, lines);
+        }
+        for (const [path, lines] of byPath) {
+            try {
+                // This best-effort telemetry sink intentionally avoids fsync so request
+                // throughput is not coupled to storage latency. Loss is surfaced by
+                // writeDrops/writeFailures rather than delaying proxy responses.
+                await withTimeout(appendFile(path, lines.join(""), { mode: 0o600 }), LIFECYCLE_APPEND_TIMEOUT_MS, "Timed out writing proxy lifecycle metadata");
+                written += lines.length;
+            }
+            catch (error) {
+                dropped += lines.length;
+                writeDrops += lines.length;
+                writeFailures += 1;
+                logger.warn("[proxy] lifecycle metadata write failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    finally {
+        inFlight = Math.max(0, inFlight - batch.length);
+    }
+}
+function startFlush() {
+    if (flushInFlight) {
+        return flushInFlight;
+    }
+    const currentFlush = flushBatch();
+    flushInFlight = currentFlush;
+    void currentFlush.then(() => {
+        if (flushInFlight === currentFlush) {
+            flushInFlight = undefined;
+        }
+        scheduleFlush();
+    }, () => {
+        if (flushInFlight === currentFlush) {
+            flushInFlight = undefined;
+        }
+        scheduleFlush();
+    });
+    return currentFlush;
+}
+export function configureProxyLifecycleLogger(options) {
+    clearScheduledFlush();
+    loggerEnabled = false;
+    lifecycleLogDir = undefined;
+    queueCapacity = positiveInteger(options.queueCapacity, DEFAULT_QUEUE_CAPACITY);
+    batchSize = positiveInteger(options.batchSize, DEFAULT_BATCH_SIZE);
+    flushIntervalMs = positiveInteger(options.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS);
+    if (options.enabled && options.logDir) {
+        try {
+            mkdirSync(options.logDir, { recursive: true, mode: 0o700 });
+            sessionHashKey = resolveSessionHashKey(options.logDir);
+            lifecycleLogDir = options.logDir;
+            loggerEnabled = true;
+        }
+        catch (error) {
+            logger.warn("[proxy] lifecycle metadata logging disabled", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // Queued records retain their enqueue-time destination. Reconfiguration is
+    // therefore atomic for new events while an in-flight or pending batch safely
+    // drains to its original directory.
+    scheduleFlush();
+}
+/** Enqueue fixed-size lifecycle metadata without awaiting filesystem work. */
+export function logProxyLifecycleEvent(input) {
+    if (!loggerEnabled || !lifecycleLogDir) {
+        return;
+    }
+    try {
+        attempted += 1;
+        const sequence = nextSequence++;
+        if (queue.length >= queueCapacity) {
+            dropped += 1;
+            queueDrops += 1;
+            return;
+        }
+        const timestamp = formatTimestamp(input.timestampMs);
+        const monotonicMs = finiteNonNegative(input.monotonicMs) ?? performance.now();
+        const toolCount = nonNegativeInteger(input.toolCount);
+        const requestBytes = nonNegativeInteger(input.requestBytes);
+        const responseStatus = nonNegativeInteger(input.responseStatus);
+        const observedBodyBytes = nonNegativeInteger(input.observedBodyBytes);
+        const responseChunks = nonNegativeInteger(input.responseChunks);
+        const elapsedMs = finiteNonNegative(input.elapsedMs);
+        const model = clip(input.model);
+        const sessionHash = clip(input.sessionHash);
+        const terminalOutcome = clip(input.terminalOutcome);
+        const errorType = clip(input.errorType);
+        const errorCode = clip(input.errorCode);
+        const record = {
+            schemaVersion: SCHEMA_VERSION,
+            timestamp,
+            monotonicMs: Number(monotonicMs.toFixed(3)),
+            processInstanceId,
+            sequence,
+            event: clip(input.event) ?? "unknown",
+            requestId: clip(input.requestId) ?? "unknown",
+            method: clip(input.method) ?? "unknown",
+            path: clip(input.path) ?? "unknown",
+            ...(model !== undefined ? { model } : {}),
+            ...(input.stream !== undefined ? { stream: input.stream } : {}),
+            ...(toolCount !== undefined ? { toolCount } : {}),
+            ...(sessionHash !== undefined ? { sessionHash } : {}),
+            ...(requestBytes !== undefined ? { requestBytes } : {}),
+            ...(responseStatus !== undefined ? { responseStatus } : {}),
+            ...(observedBodyBytes !== undefined ? { observedBodyBytes } : {}),
+            ...(responseChunks !== undefined ? { responseChunks } : {}),
+            ...(elapsedMs !== undefined
+                ? { elapsedMs: Number(elapsedMs.toFixed(3)) }
+                : {}),
+            ...(terminalOutcome !== undefined ? { terminalOutcome } : {}),
+            ...(errorType !== undefined ? { errorType } : {}),
+            ...(errorCode !== undefined ? { errorCode } : {}),
+        };
+        queue.push({
+            logDir: lifecycleLogDir,
+            date: String(record.timestamp).slice(0, 10),
+            record,
+        });
+        enqueued += 1;
+        scheduleFlush();
+    }
+    catch {
+        dropped += 1;
+        invalidDrops += 1;
+    }
+}
+export async function flushProxyLifecycleEvents() {
+    clearScheduledFlush();
+    while (queue.length > 0 || flushInFlight) {
+        if (flushInFlight) {
+            await flushInFlight;
+        }
+        else {
+            await startFlush();
+        }
+        clearScheduledFlush();
+    }
+}
+export function getProxyLifecycleLoggerSnapshot() {
+    return {
+        enabled: loggerEnabled,
+        schemaVersion: SCHEMA_VERSION,
+        processInstanceId,
+        nextSequence,
+        attempted,
+        enqueued,
+        written,
+        dropped,
+        queueDrops,
+        invalidDrops,
+        writeDrops,
+        writeFailures,
+        pending: queue.length,
+        inFlight,
+        flushing: flushInFlight !== undefined,
+    };
+}
+export function resetProxyLifecycleLoggerForTests() {
+    clearScheduledFlush();
+    loggerEnabled = false;
+    lifecycleLogDir = undefined;
+    queueCapacity = DEFAULT_QUEUE_CAPACITY;
+    batchSize = DEFAULT_BATCH_SIZE;
+    flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS;
+    processInstanceId = randomUUID();
+    sessionHashKey = randomBytes(32);
+    nextSequence = 1;
+    attempted = 0;
+    enqueued = 0;
+    written = 0;
+    dropped = 0;
+    queueDrops = 0;
+    invalidDrops = 0;
+    writeDrops = 0;
+    writeFailures = 0;
+    inFlight = 0;
+    queue = [];
+    flushInFlight = undefined;
+}
+//# sourceMappingURL=proxyLifecycle.js.map

package/dist/lib/proxy/requestLogger.js

@@ -15,6 +15,7 @@ import { promisify } from "util";
 import { gzip as gzipCallback } from "zlib";
 import { OtelBridge } from "../observability/otelBridge.js";
 import { SeverityNumber } from "@opentelemetry/api-logs";
+import { configureProxyLifecycleLogger } from "./proxyLifecycle.js";
 let logDir = null;
 let logEnabled = false;
 /**
@@ -45,8 +46,11 @@ 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;
 export function initRequestLogger(enabled = true, customLogsDir) {
+    // Lifecycle metadata deliberately shares the request logger's enablement,
+    // directory permissions, retention boundary, and operator privacy control.
     logEnabled = enabled;
     if (!enabled) {
+        configureProxyLifecycleLogger({ enabled: false });
         return;
     }
     try {
@@ -55,10 +59,12 @@ export function initRequestLogger(enabled = true, customLogsDir) {
             mkdirSync(logDir, { recursive: true, mode: 0o700 });
         }
         chmodSync(logDir, 0o700);
+        configureProxyLifecycleLogger({ enabled: true, logDir });
     }
     catch (err) {
         logEnabled = false;
         logDir = null;
+        configureProxyLifecycleLogger({ enabled: false });
         logger.warn(`[proxy] Request logging disabled — failed to create log directory: ${err instanceof Error ? err.message : String(err)}`);
     }
 }

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -3062,7 +3062,10 @@ async function handleAnthropicAuthRetry(args) {
                 : String(retryFetchErr);
             authRetryError = `network error on retry ${authRetry + 1}: ${message}`;
             currentLastError = authRetryError;
-            retryLogAttempt(502, "network_error", message, { retryable: true });
+            retryLogAttempt(502, "network_error", message, {
+                retryable: isRetryableNetworkError(retryFetchErr),
+                errorCode: getErrorCode(retryFetchErr) ?? "unknown",
+            });
             logger.debug(`[proxy] ${authRetryError}`);
             break;
         }
@@ -3437,6 +3440,7 @@ function createAnthropicAttemptLogger(args) {
             responseTimeMs: Date.now() - requestStart,
             ...(errorType ? { errorType } : {}),
             ...(errorMessage ? { errorMessage } : {}),
+            ...(extra?.errorCode ? { errorCode: extra.errorCode } : {}),
             ...(extra?.inputTokens !== undefined
                 ? { inputTokens: extra.inputTokens }
                 : {}),
@@ -3651,19 +3655,27 @@ async function fetchAnthropicAccountResponse(args) {
         });
     }
     catch (fetchErr) {
-        if (!isRetryableNetworkError(fetchErr)) {
-            throw fetchErr;
-        }
+        const retryable = isRetryableNetworkError(fetchErr);
+        // Every dispatched upstream request is an attempt, including terminal
+        // transport failures. Record it once before preserving the throw behavior.
         sawNetworkError = true;
         recordAttemptError(account.label, account.type, 502);
         const errorCode = getErrorCode(fetchErr) ?? "unknown";
         const errorMessage = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
         lastError = errorMessage;
-        logger.always(`[proxy] fetch error account=${account.label} code=${errorCode} (retryable): ${errorMessage}`);
-        logAttempt(502, "network_error", errorMessage);
+        logger.always(`[proxy] fetch error account=${account.label} code=${errorCode} (${retryable ? "retryable" : "terminal"}): ${errorMessage}`);
+        logAttempt(502, "network_error", errorMessage, {
+            retryable,
+            errorCode,
+        });
         tracer?.setError("network_error", errorMessage);
-        tracer?.recordRetry(account.label, "network_error");
+        if (retryable) {
+            tracer?.recordRetry(account.label, "network_error");
+        }
         currentUpstreamSpan?.end();
+        if (!retryable) {
+            throw fetchErr;
+        }
         return {
             continueLoop: true,
             retrySameAccount: true,
@@ -4469,16 +4481,13 @@ function describeTransportError(error) {
  */
 function isRetryableNetworkError(error) {
     const code = getErrorCode(error);
-    // Check non-retryable codes FIRST — before the string-based heuristic
-    // which could false-positive on error messages containing these strings.
-    const NON_RETRYABLE_CODES = ["ENOTFOUND"];
-    if (code && NON_RETRYABLE_CODES.includes(code)) {
-        return false;
-    }
     if (code &&
         [
             "ECONNREFUSED",
             "ECONNRESET",
+            // The Anthropic host is fixed, so ENOTFOUND can be a transient resolver
+            // outage. Keep it inside the existing bounded same-account retry budget.
+            "ENOTFOUND",
             "ETIMEDOUT",
             "EHOSTUNREACH",
             "UND_ERR_CONNECT_TIMEOUT",
@@ -4490,13 +4499,9 @@ function isRetryableNetworkError(error) {
     }
     const message = error instanceof Error ? error.message : String(error);
     const normalized = message.toLowerCase();
-    // Exclude ENOTFOUND from string-based heuristic — DNS failures are permanent
-    // and rotating accounts won't help since they all hit the same host.
-    if (normalized.includes("enotfound")) {
-        return false;
-    }
     return (normalized.includes("econnrefused") ||
         normalized.includes("econnreset") ||
+        normalized.includes("enotfound") ||
         normalized.includes("etimedout") ||
         normalized.includes("timed out") ||
         normalized.includes("connection error") ||

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

@@ -437,6 +437,8 @@ export type RequestLogEntry = {
     responseTimeMs: number;
     errorType?: string;
     errorMessage?: string;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
@@ -461,6 +463,8 @@ export type RequestAttemptLogEntry = {
     responseTimeMs: number;
     errorType?: string;
     errorMessage?: string;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     /** Whether this failed attempt may be retried without changing the request. */
     retryable?: boolean;
     /** Distinguishes short-lived admission throttles from exhausted quota windows. */
@@ -514,6 +518,8 @@ export type AnthropicAttemptLogger = (status: number, errorType?: string, errorM
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
     retryable?: boolean;
+    /** Low-level transport code such as ETIMEDOUT or EADDRNOTAVAIL. */
+    errorCode?: string;
     rateLimitKind?: "transient" | "quota";
     cooldownReason?: "transient" | "session" | "weekly" | "unified";
     /** Override used when one account selection performs an OAuth retry fetch. */
@@ -945,6 +951,80 @@ export type ProxyRuntimeActivity = {
     activeRequests: number;
     lastActivityAt: string | null;
 };
+/** Terminal state observed while the HTTP adapter relays a response body. */
+export type ProxyResponseTerminalOutcome = "completed" | "bodyless" | "client_cancelled" | "stream_error";
+/** Non-blocking callbacks for response lifecycle metadata. */
+export type ProxyResponseTrackingObserver = {
+    onFirstChunk?: (details: {
+        /** Decoded response-body bytes observed by the adapter. */
+        observedBodyBytes: number;
+        responseChunks: 1;
+    }) => void;
+    onTerminal?: (details: {
+        outcome: ProxyResponseTerminalOutcome;
+        /** Decoded response-body bytes observed by the adapter. */
+        observedBodyBytes: number;
+        responseChunks: number;
+    }) => void;
+};
+/** Versioned lifecycle event names persisted by the proxy adapter. */
+export type ProxyLifecycleEventName = "request_accepted" | "response_headers" | "response_first_chunk" | "request_terminal";
+/** Client-facing terminal classifications recorded by lifecycle metadata. */
+export type ProxyLifecycleTerminalOutcome = ProxyResponseTerminalOutcome | "handler_error";
+/** Content-free lifecycle event accepted by the bounded metadata logger. */
+export type ProxyLifecycleEventInput = {
+    event: ProxyLifecycleEventName;
+    requestId: string;
+    method: string;
+    path: string;
+    model?: string;
+    stream?: boolean;
+    toolCount?: number;
+    sessionHash?: string;
+    requestBytes?: number;
+    responseStatus?: number;
+    /** Decoded response-body bytes observed by the adapter. */
+    observedBodyBytes?: number;
+    responseChunks?: number;
+    elapsedMs?: number;
+    terminalOutcome?: ProxyLifecycleTerminalOutcome;
+    errorType?: string;
+    errorCode?: string;
+    timestampMs?: number;
+    monotonicMs?: number;
+};
+/** Data-quality counters for the bounded lifecycle metadata sink. */
+export type ProxyLifecycleLoggerSnapshot = {
+    enabled: boolean;
+    schemaVersion: number;
+    processInstanceId: string;
+    nextSequence: number;
+    attempted: number;
+    enqueued: number;
+    written: number;
+    dropped: number;
+    queueDrops: number;
+    invalidDrops: number;
+    writeDrops: number;
+    writeFailures: number;
+    pending: number;
+    inFlight: number;
+    flushing: boolean;
+};
+/** Lifecycle logger configuration. Queue overrides are used by stress tests. */
+export type ProxyLifecycleLoggerOptions = {
+    enabled: boolean;
+    logDir?: string;
+    queueCapacity?: number;
+    batchSize?: number;
+    flushIntervalMs?: number;
+};
+/** Serialized lifecycle line awaiting a bounded batch write. */
+export type QueuedProxyLifecycleEvent = {
+    logDir: string;
+    date: string;
+    record: Record<string, unknown>;
+};
 /** Request metadata retained by the HTTP adapter for terminal error logging. */
 export type RuntimeRequestMetadata = {
     requestId: string;
@@ -954,6 +1034,8 @@ export type RuntimeRequestMetadata = {
     model: string;
     stream: boolean;
     toolCount: number;
+    terminalErrorType?: string;
+    terminalErrorCode?: string;
 };
 /** Accumulated upstream body capture from a raw stream. */
 export type RawStreamCapture = {

package/dist/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/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/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;