@juspay/neurolink 9.93.0 → 9.93.1

package/dist/lib/proxy/updateCoordinator.js

@@ -0,0 +1,60 @@
+function isQuiet(activity, quietThresholdMs, nowMs) {
+    if (activity.activeRequests > 0) {
+        return false;
+    }
+    if (!activity.lastActivityAt) {
+        return true;
+    }
+    const lastActivityMs = Date.parse(activity.lastActivityAt);
+    return (Number.isFinite(lastActivityMs) &&
+        nowMs - lastActivityMs >= quietThresholdMs);
+}
+/**
+ * Prefer a naturally quiet window, then briefly drain new inference traffic.
+ * Existing requests are never interrupted; a bounded drain failure is returned
+ * to the caller so admission can be reopened and retried later.
+ */
+export async function waitForProxyUpdateWindow(options) {
+    const now = options.now ?? Date.now;
+    const wait = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const quietDeadline = now() + options.quietWaitMs;
+    while (now() < quietDeadline) {
+        if (options.isStopping()) {
+            return { ready: false, draining: false, reason: "stopping" };
+        }
+        if (!options.isParentAlive()) {
+            return { ready: false, draining: false, reason: "parent_stopped" };
+        }
+        const activity = await options.getActivity();
+        if (activity && isQuiet(activity, options.quietThresholdMs, now())) {
+            return { ready: true, draining: false };
+        }
+        options.onPhase?.("waiting_for_quiet", activity);
+        await wait(options.pollIntervalMs);
+    }
+    if (!(await options.setDraining(true))) {
+        // The control response may have been lost after the parent applied it.
+        // Treat state as unknown/draining so the caller always attempts resume.
+        return { ready: false, draining: true, reason: "drain_failed" };
+    }
+    const drainDeadline = now() + options.drainWaitMs;
+    while (now() < drainDeadline) {
+        if (options.isStopping()) {
+            return { ready: false, draining: true, reason: "stopping" };
+        }
+        if (!options.isParentAlive()) {
+            return { ready: false, draining: true, reason: "parent_stopped" };
+        }
+        const activity = await options.getActivity();
+        options.onPhase?.("draining", activity);
+        if (activity?.activeRequests === 0) {
+            return { ready: true, draining: true };
+        }
+        await wait(options.pollIntervalMs);
+    }
+    const activity = await options.getActivity();
+    options.onPhase?.("drain_timeout", activity);
+    return { ready: false, draining: true, reason: "drain_timeout" };
+}
+//# sourceMappingURL=updateCoordinator.js.map

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

@@ -54,6 +54,10 @@ export declare function recordUpdateInstalled(version: string, stateFilePath?: s
 export declare function abandonPendingUpdate(version: string, stateFilePath?: string): boolean;
 /** Persist a stage-specific updater failure so status remains actionable. */
 export declare function recordUpdateFailure(version: string, stage: NonNullable<UpdateState["lastFailure"]>["stage"], message: string, stateFilePath?: string): void;
+/** Persist why a discovered update is waiting without treating it as a failure. */
+export declare function recordUpdateDeferred(version: string, reason: NonNullable<UpdateState["deferredUpdate"]>["reason"], activeRequests: number | null, stateFilePath?: string): void;
+/** Clear matching updater deferral metadata once work can proceed. */
+export declare function clearUpdateDeferral(version?: string, stateFilePath?: string): boolean;
 /** Complete an updater-managed install after a manual or automatic restart. */
 export declare function reconcileRunningUpdate(runningVersion: string, stateFilePath?: string): boolean;
 /**

package/dist/lib/proxy/updateState.js

@@ -56,6 +56,26 @@ function isValidLastFailure(value) {
         UPDATE_FAILURE_STAGES.has(candidate.stage) &&
         typeof candidate.message === "string");
 }
+function isValidDeferredUpdate(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.version === "string" &&
+        typeof candidate.since === "string" &&
+        typeof candidate.updatedAt === "string" &&
+        [
+            "waiting_for_quiet",
+            "draining",
+            "drain_timeout",
+            "drain_unavailable",
+            "activity_unavailable",
+        ].includes(String(candidate.reason)) &&
+        (candidate.activeRequests === null ||
+            (typeof candidate.activeRequests === "number" &&
+                Number.isInteger(candidate.activeRequests) &&
+                candidate.activeRequests >= 0)));
+}
 // ============================================
 // Exported Functions
 // ============================================
@@ -70,6 +90,7 @@ export function getDefaultUpdateState() {
         lastUpdateAt: null,
         lastUpdateVersion: null,
         pendingRestartVersion: null,
+        deferredUpdate: null,
         lastFailure: null,
     };
 }
@@ -106,6 +127,9 @@ export function loadUpdateState(stateFilePath) {
             pendingRestartVersion: typeof candidate.pendingRestartVersion === "string"
                 ? candidate.pendingRestartVersion
                 : null,
+            deferredUpdate: isValidDeferredUpdate(candidate.deferredUpdate)
+                ? candidate.deferredUpdate
+                : null,
             lastFailure: isValidLastFailure(candidate.lastFailure)
                 ? candidate.lastFailure
                 : null,
@@ -185,6 +209,7 @@ export function recordSuccessfulUpdate(version, stateFilePath) {
     state.lastUpdateAt = new Date().toISOString();
     state.lastUpdateVersion = version;
     state.pendingRestartVersion = null;
+    state.deferredUpdate = null;
     state.lastFailure = null;
     delete state.suppressedVersions[version];
     saveUpdateState(state, stateFilePath);
@@ -217,6 +242,32 @@ export function recordUpdateFailure(version, stage, message, stateFilePath) {
     };
     saveUpdateState(state, stateFilePath);
 }
+/** Persist why a discovered update is waiting without treating it as a failure. */
+export function recordUpdateDeferred(version, reason, activeRequests, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    const now = new Date().toISOString();
+    state.deferredUpdate = {
+        version,
+        since: state.deferredUpdate?.version === version
+            ? state.deferredUpdate.since
+            : now,
+        updatedAt: now,
+        reason,
+        activeRequests,
+    };
+    saveUpdateState(state, stateFilePath);
+}
+/** Clear matching updater deferral metadata once work can proceed. */
+export function clearUpdateDeferral(version, stateFilePath) {
+    const state = loadUpdateState(stateFilePath);
+    if (!state?.deferredUpdate ||
+        (version !== undefined && state.deferredUpdate.version !== version)) {
+        return false;
+    }
+    state.deferredUpdate = null;
+    saveUpdateState(state, stateFilePath);
+    return true;
+}
 /** Complete an updater-managed install after a manual or automatic restart. */
 export function reconcileRunningUpdate(runningVersion, stateFilePath) {
     const state = loadUpdateState(stateFilePath);

package/dist/lib/server/routes/claudeProxyRoutes.d.ts

@@ -143,6 +143,7 @@ declare function handleAnthropicStreamingSuccessResponse(args: {
     attemptNumber: number;
     finalBodyStr: string;
     upstreamSpan?: import("@opentelemetry/api").Span;
+    logAttempt: AnthropicAttemptLogger;
     logProxyBody: ProxyBodyCaptureLogger;
     logFinalRequest: (status: number, accountLabel: string, accountType: string, errorType?: string, errorMessage?: string, extra?: {
         inputTokens?: number;

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();
@@ -3423,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(),
@@ -3437,7 +3527,8 @@ 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 } : {}),
@@ -4095,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;

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

@@ -460,7 +460,10 @@ 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. */
@@ -522,6 +525,8 @@ export type AnthropicAttemptLogger = (status: number, errorType?: string, errorM
     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;
@@ -558,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;
@@ -810,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. */
@@ -817,6 +855,7 @@ export type ProxyHealthResponse = {
     status: "ok" | "starting";
     ready: boolean;
     acceptingConnections: boolean;
+    drainingForUpdate: boolean;
     strategy: string;
     passthrough: boolean;
     version: string;
@@ -1025,6 +1064,124 @@ export type QueuedProxyLifecycleEvent = {
     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;
@@ -1034,6 +1191,8 @@ 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;
 };
@@ -1201,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;
@@ -1209,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/proxyAnalysis.d.ts

@@ -0,0 +1,3 @@
+import type { ProxyAnalysisOptions, ProxyAnalysisReport } from "../types/index.js";
+/** Analyze local proxy logs without reading request or response body artifacts. */
+export declare function analyzeProxyLogs(options?: ProxyAnalysisOptions): Promise<ProxyAnalysisReport>;