@juspay/neurolink 9.92.3 → 9.93.1

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

@@ -25,7 +25,7 @@ import { createRawStreamCapture } from "../../proxy/rawStreamCapture.js";
 import { relocateClientSystemIntoMessages } from "../../proxy/systemRelocation.js";
 import { logBodyCapture, logRequest, logRequestAttempt, } from "../../proxy/requestLogger.js";
 import { createSSEInterceptor } from "../../proxy/sseInterceptor.js";
-import { createStreamTerminalOutcomeTracker, mergeStreamTerminalOutcome, } from "../../proxy/streamOutcome.js";
+import { createStreamTerminalOutcomeTracker, mergeStreamTerminalOutcome, preflightAnthropicStream, } from "../../proxy/streamOutcome.js";
 import { isPermanentRefreshFailure, needsRefresh, persistTokens, refreshToken, } from "../../proxy/tokenRefresh.js";
 import { buildProxyTranslationPlan, parseRetryAfterMs, } from "../../proxy/routingPolicy.js";
 import { writeJsonSnapshotAtomically } from "../../proxy/snapshotPersistence.js";
@@ -2182,7 +2182,7 @@ function buildClaudeAnthropicFailureResponse(args) {
     });
 }
 async function handleAnthropicSuccessfulResponse(args) {
-    const { ctx, body, account, accountState, response, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { ctx, body, account, accountState, response, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, } = args;
     accountState.consecutiveRefreshFailures = 0;
     logger.always(`[proxy] ← ${response.status} account=${account.label}`);
     const quota = parseQuotaHeaders(response.headers);
@@ -2222,6 +2222,7 @@ async function handleAnthropicSuccessfulResponse(args) {
             attemptNumber,
             finalBodyStr,
             upstreamSpan,
+            logAttempt,
             logProxyBody,
             logFinalRequest,
         });
@@ -2241,7 +2242,7 @@ async function handleAnthropicSuccessfulResponse(args) {
     });
 }
 async function handleAnthropicStreamingSuccessResponse(args) {
-    const { account, accountState: _accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { account, accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logAttempt, logProxyBody, logFinalRequest, } = args;
     if (!response.body) {
         upstreamSpan?.end();
         tracer?.setError("stream_error", "No response body from upstream");
@@ -2265,44 +2266,129 @@ async function handleAnthropicStreamingSuccessResponse(args) {
         return { response: clientError };
     }
     const reader = response.body.getReader();
-    let firstChunk;
-    try {
-        firstChunk = await reader.read();
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+    const preflight = await preflightAnthropicStream(reader);
+    if (preflight.kind === "transport_error") {
+        const message = describeTransportError(preflight.error);
+        const partialBody = Buffer.concat(preflight.chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
         logger.always(`[proxy] stream failed before first chunk account=${account.label}: ${message}; trying next account`);
         recordAttemptError(account.label, account.type, 502);
+        logAttempt(502, "stream_error", message, { retryable: true });
         tracer?.recordRetry(account.label, "stream_before_first_chunk");
         upstreamSpan?.end();
         logProxyBody({
             phase: "upstream_response",
             headers: responseHeaders,
-            body: message,
-            bodySize: Buffer.byteLength(message, "utf8"),
+            body: partialBody,
+            bodySize: Buffer.byteLength(partialBody, "utf8"),
             contentType: responseHeaders["content-type"] ?? "text/event-stream",
             account: account.label,
             accountType: account.type,
             attempt: attemptNumber,
-            responseStatus: 502,
+            responseStatus: response.status,
             durationMs: Date.now() - fetchStartMs,
+            metadata: { logicalStatus: 502, transportError: message },
         });
-        return { retryNextAccount: true };
+        return {
+            retryNextAccount: true,
+            failure: { message, rateLimit: false },
+        };
     }
-    if (firstChunk.done || !firstChunk.value || firstChunk.value.length === 0) {
+    if (preflight.kind === "empty") {
         await reader.cancel().catch(() => {
             // Best-effort release before rotating to another account.
         });
         logger.always(`[proxy] ← empty stream from account=${account.label}, trying next`);
+        recordAttemptError(account.label, account.type, 502);
+        logAttempt(502, "empty_stream", "Empty upstream stream", {
+            retryable: true,
+        });
         tracer?.recordRetry(account.label, "empty_stream");
         upstreamSpan?.end();
-        return { retryNextAccount: true };
+        logProxyBody({
+            phase: "upstream_response",
+            headers: responseHeaders,
+            body: "",
+            bodySize: 0,
+            contentType: responseHeaders["content-type"] ?? "text/event-stream",
+            account: account.label,
+            accountType: account.type,
+            attempt: attemptNumber,
+            responseStatus: response.status,
+            durationMs: Date.now() - fetchStartMs,
+            metadata: { logicalStatus: 502, upstreamErrorType: "empty_stream" },
+        });
+        return {
+            retryNextAccount: true,
+            failure: { message: "Empty upstream stream", rateLimit: false },
+        };
+    }
+    if (preflight.kind === "sse_error") {
+        await reader.cancel().catch(() => {
+            // Best-effort release before rotating to another account.
+        });
+        const bodyText = Buffer.concat(preflight.chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
+        const isRateLimit = preflight.errorType === "rate_limit_error";
+        const logicalStatus = isRateLimit ? 429 : 502;
+        const quota = parseQuotaHeaders(responseHeaders);
+        const now = Date.now();
+        if (isRateLimit) {
+            const cooldownPlan = planCooldownFor429(quota, parseRetryAfterMs(responseHeaders["retry-after"] ?? null), now, getUnifiedRateLimitStatus(responseHeaders));
+            accountState.quota = quota ?? accountState.quota;
+            const rateLimitKind = cooldownPlan.reason === "transient" ? "transient" : "quota";
+            if (!accountState.coolingUntil ||
+                cooldownPlan.coolingUntil > accountState.coolingUntil) {
+                accountState.coolingUntil = cooldownPlan.coolingUntil;
+                accountState.coolingReason = cooldownPlan.reason;
+                await saveAccountCooldown(account.key, cooldownPlan.coolingUntil, cooldownPlan.reason).catch(() => {
+                    // Non-fatal: routing already has the in-memory cooldown.
+                });
+            }
+            recordAttemptError(account.label, account.type, 429, rateLimitKind);
+            logAttempt(429, "rate_limit_error", preflight.message, {
+                retryable: true,
+                rateLimitKind,
+                cooldownReason: cooldownPlan.reason,
+            });
+        }
+        else {
+            recordAttemptError(account.label, account.type, logicalStatus);
+            logAttempt(logicalStatus, preflight.errorType, preflight.message, {
+                retryable: true,
+            });
+        }
+        logger.always(`[proxy] immediate SSE ${preflight.errorType} account=${account.label}: ${preflight.message}; rotating before client commit`);
+        tracer?.recordRetry(account.label, isRateLimit
+            ? "stream_rate_limit_before_commit"
+            : "stream_error_before_commit");
+        upstreamSpan?.end();
+        logProxyBody({
+            phase: "upstream_response",
+            headers: responseHeaders,
+            body: bodyText,
+            bodySize: Buffer.byteLength(bodyText, "utf8"),
+            contentType: responseHeaders["content-type"] ?? "text/event-stream",
+            account: account.label,
+            accountType: account.type,
+            attempt: attemptNumber,
+            responseStatus: response.status,
+            durationMs: Date.now() - fetchStartMs,
+            metadata: {
+                logicalStatus,
+                upstreamErrorType: preflight.errorType,
+            },
+        });
+        return {
+            retryNextAccount: true,
+            failure: { message: preflight.message, rateLimit: isRateLimit },
+        };
     }
     const streamOutcomeTracker = createStreamTerminalOutcomeTracker();
     let mainStreamClosed = false;
     const remainingStream = new ReadableStream({
         start(controller) {
-            controller.enqueue(firstChunk.value);
+            for (const chunk of preflight.chunks) {
+                controller.enqueue(chunk);
+            }
         },
         async pull(controller) {
             if (mainStreamClosed) {
@@ -2865,10 +2951,12 @@ async function handleAnthropicAuthRetry(args) {
         await clearAuthCooldownAfterRefresh(account, accountState);
         headers.authorization = `Bearer ${account.token}`;
         const retryAttemptNumber = allocateAttemptNumber();
+        const retryAttemptStartedAt = Date.now();
         recordAttempt(account.label, account.type);
         const retryLogAttempt = (status, errorType, errorMessage, extra) => logAttempt(status, errorType, errorMessage, {
             ...extra,
             attempt: retryAttemptNumber,
+            attemptDurationMs: Date.now() - retryAttemptStartedAt,
         });
         const retryBodyStr = buildUpstreamBody(account.token).bodyStr;
         const retryFetchStartMs = Date.now();
@@ -3062,7 +3150,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;
         }
@@ -3420,7 +3511,9 @@ function createClaudeRequestRuntimeContext(args) {
 }
 function createAnthropicAttemptLogger(args) {
     const { ctx, body, toolCount, requestStart, tracer, account, attemptNumber } = args;
+    const attemptStartedAt = Date.now();
     return (status, errorType, errorMessage, extra) => {
+        const attemptCompletedAt = Date.now();
         const traceCtx = tracer?.getTraceContext();
         logRequestAttempt({
             timestamp: new Date().toISOString(),
@@ -3434,9 +3527,11 @@ function createAnthropicAttemptLogger(args) {
             account: account.label,
             accountType: account.type,
             responseStatus: status,
-            responseTimeMs: Date.now() - requestStart,
+            responseTimeMs: attemptCompletedAt - requestStart,
+            attemptDurationMs: extra?.attemptDurationMs ?? attemptCompletedAt - attemptStartedAt,
             ...(errorType ? { errorType } : {}),
             ...(errorMessage ? { errorMessage } : {}),
+            ...(extra?.errorCode ? { errorCode: extra.errorCode } : {}),
             ...(extra?.inputTokens !== undefined
                 ? { inputTokens: extra.inputTokens }
                 : {}),
@@ -3651,19 +3746,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,
@@ -4083,10 +4186,16 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 attemptNumber: loopState.attemptNumber,
                 finalBodyStr: preparedAttempt.finalBodyStr,
                 upstreamSpan,
+                logAttempt,
                 logProxyBody,
                 logFinalRequest,
             });
             if ("retryNextAccount" in successResult) {
+                if (successResult.failure) {
+                    loopState.lastError = successResult.failure.message;
+                    loopState.sawRateLimit ||= successResult.failure.rateLimit;
+                    loopState.sawTransientFailure ||= !successResult.failure.rateLimit;
+                }
                 continue accountLoop;
             }
             return successResult.response;
@@ -4469,16 +4578,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 +4596,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/cli.d.ts

@@ -791,6 +791,13 @@ export type ProxyStatusArgs = {
     format?: "text" | "json";
     quiet?: boolean;
 };
+/** Arguments accepted by `neurolink proxy analyze` */
+export type ProxyAnalyzeArgs = {
+    logsDir?: string;
+    since?: string;
+    format?: "text" | "json";
+    quiet?: boolean;
+};
 /** Arguments accepted by hidden `neurolink proxy guard` command */
 export type ProxyGuardArgs = {
     host?: string;

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;
@@ -458,9 +460,14 @@ export type RequestAttemptLogEntry = {
     account: string;
     accountType: string;
     responseStatus: number;
+    /** End-to-end request age when this attempt completed. */
     responseTimeMs: number;
+    /** Time spent in this specific account attempt. */
+    attemptDurationMs?: 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,8 +521,12 @@ 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 for nested retries whose attempt starts after this logger. */
+    attemptDurationMs?: number;
     /** Override used when one account selection performs an OAuth retry fetch. */
     attempt?: number;
 }) => void;
@@ -552,9 +563,40 @@ export type LoadedClaudeAccountContext = {
 };
 export type AnthropicSuccessResult = {
     retryNextAccount: true;
+    failure?: {
+        message: string;
+        rateLimit: boolean;
+    };
 } | {
     response: Response | unknown;
 };
+/** Result of buffering only enough upstream SSE to make a retry-safe decision. */
+export type AnthropicStreamPreflightResult = {
+    kind: "ready";
+    chunks: Uint8Array[];
+} | {
+    kind: "empty";
+    chunks: Uint8Array[];
+} | {
+    kind: "transport_error";
+    chunks: Uint8Array[];
+    error: unknown;
+} | {
+    kind: "sse_error";
+    chunks: Uint8Array[];
+    errorType: string;
+    message: string;
+};
+/** One complete Server-Sent Event extracted from an incremental buffer. */
+export type ParsedSSEEvent = {
+    event: string;
+    data: string;
+};
+/** Complete SSE events plus the trailing partial frame. */
+export type ParsedSSEBuffer = {
+    events: ParsedSSEEvent[];
+    remainder: string;
+};
 export type AnthropicAuthRetryResult = {
     response?: Response | unknown;
     continueLoop: boolean;
@@ -804,6 +846,8 @@ export type ProxyReadinessState = {
     startTimeMs: number;
     acceptingConnections: boolean;
     ready: boolean;
+    /** True only while the updater is draining inference traffic. */
+    drainingForUpdate: boolean;
     readyAtMs?: number;
 };
 /** Structured response returned by the proxy /health endpoint. */
@@ -811,6 +855,7 @@ export type ProxyHealthResponse = {
     status: "ok" | "starting";
     ready: boolean;
     acceptingConnections: boolean;
+    drainingForUpdate: boolean;
     strategy: string;
     passthrough: boolean;
     version: string;
@@ -945,6 +990,198 @@ 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>;
+};
+/** Percentile summary used by offline proxy log analysis. */
+export type ProxyLatencySummary = {
+    count: number;
+    p50: number | null;
+    p95: number | null;
+    p99: number | null;
+    max: number | null;
+};
+/** Per-account request and rate-limit totals reconstructed from JSONL logs. */
+export type ProxyAnalysisAccount = {
+    account: string;
+    accountType: string;
+    attempts: number;
+    attemptErrors: number;
+    finalRequests: number;
+    finalErrors: number;
+    transientRateLimits: number;
+    quotaRateLimits: number;
+    unclassifiedRateLimits: number;
+};
+/** Offline report generated from proxy request, attempt, and lifecycle logs. */
+export type ProxyAnalysisReport = {
+    generatedAt: string;
+    since: string;
+    logsDir: string;
+    files: {
+        lifecycle: number;
+        requests: number;
+        attempts: number;
+    };
+    coverage: {
+        lifecycle: boolean;
+        finalRequests: boolean;
+        attempts: boolean;
+        attemptLatency: boolean;
+        cacheUsage: boolean;
+    };
+    dataQuality: {
+        linesRead: number;
+        malformedLines: number;
+        unsupportedLifecycleLines: number;
+        lifecycleSequenceGaps: number;
+        lifecycleSequenceDuplicates: number;
+    };
+    lifecycle: {
+        accepted: number;
+        headers: number;
+        firstChunks: number;
+        terminal: number;
+        unsettled: number;
+        terminalOutcomes: Record<string, number>;
+        errorTypes: Record<string, number>;
+        errorCodes: Record<string, number>;
+    };
+    requests: {
+        completed: number;
+        success: number;
+        errors: number;
+        finalRateLimits: number;
+        recoveredAfterRetry: number;
+        errorTypes: Record<string, number>;
+        errorCodes: Record<string, number>;
+    };
+    attempts: {
+        total: number;
+        errors: number;
+        errorTypes: Record<string, number>;
+        errorCodes: Record<string, number>;
+    };
+    rateLimits: {
+        attemptRateLimits: number;
+        transient: number;
+        quota: number;
+        unclassified: number;
+    };
+    latencyMs: {
+        headers: ProxyLatencySummary;
+        firstChunk: ProxyLatencySummary;
+        terminal: ProxyLatencySummary;
+        finalRequest: ProxyLatencySummary;
+        attempt: ProxyLatencySummary;
+        singleAttemptDelta: ProxyLatencySummary;
+    };
+    cache: {
+        requestsWithUsage: number;
+        requestsWithCacheRead: number;
+        cacheReadTokens: number;
+        cacheCreationTokens: number;
+        inputTokens: number;
+        requestHitRate: number | null;
+    };
+    accounts: ProxyAnalysisAccount[];
+};
+/** Inputs for the offline proxy JSONL analyzer. */
+export type ProxyAnalysisOptions = {
+    logsDir?: string;
+    since?: string;
+    nowMs?: number;
+};
+/** Attempt timing retained while joining offline proxy log records. */
+export type ProxyAnalysisAttemptRecord = {
+    count: number;
+    hadError: boolean;
+    totalDurationMs: number;
+    durationCount: number;
+};
+/** Final request fields retained while joining offline proxy log records. */
+export type ProxyAnalysisFinalRequestRecord = {
+    status: number;
+    durationMs: number | null;
+    account: string;
+    accountType: string;
+    inputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheCreationTokens: number | null;
+    errorType: string | null;
+    errorCode: string | null;
+};
 /** Request metadata retained by the HTTP adapter for terminal error logging. */
 export type RuntimeRequestMetadata = {
     requestId: string;
@@ -954,6 +1191,10 @@ export type RuntimeRequestMetadata = {
     model: string;
     stream: boolean;
     toolCount: number;
+    /** Admission decision captured before an updater drain can race the route. */
+    rejectForUpdate?: boolean;
+    terminalErrorType?: string;
+    terminalErrorCode?: string;
 };
 /** Accumulated upstream body capture from a raw stream. */
 export type RawStreamCapture = {
@@ -1119,6 +1360,14 @@ export type UpdateState = {
     lastUpdateVersion: string | null;
     /** Installed by the updater but not yet confirmed as the running version. */
     pendingRestartVersion: string | null;
+    /** Why an available update has not yet reached a safe install/restart boundary. */
+    deferredUpdate: {
+        version: string;
+        since: string;
+        updatedAt: string;
+        reason: "waiting_for_quiet" | "draining" | "drain_timeout" | "drain_unavailable" | "activity_unavailable";
+        activeRequests: number | null;
+    } | null;
     /** Last updater failure, retained until a successful update or replacement. */
     lastFailure: {
         at: string;
@@ -1127,6 +1376,26 @@ export type UpdateState = {
         message: string;
     } | null;
 };
+/** Result from waiting for a non-disruptive updater execution window. */
+export type ProxyUpdateWindowResult = {
+    ready: boolean;
+    draining: boolean;
+    reason?: "stopping" | "parent_stopped" | "drain_failed" | "drain_timeout";
+};
+/** Dependencies and timing controls for the updater's safe-window coordinator. */
+export type ProxyUpdateWindowOptions = {
+    quietThresholdMs: number;
+    quietWaitMs: number;
+    drainWaitMs: number;
+    pollIntervalMs: number;
+    getActivity: () => Promise<ProxyRuntimeActivity | null>;
+    setDraining: (draining: boolean) => Promise<boolean>;
+    isStopping: () => boolean;
+    isParentAlive: () => boolean;
+    onPhase?: (phase: "waiting_for_quiet" | "draining" | "drain_timeout", activity: ProxyRuntimeActivity | null) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+};
 /** Result of validating a newly installed CLI through the stable trampoline. */
 export type InstalledVersionValidation = {
     version?: string;

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;