@juspay/neurolink 9.92.3 → 9.93.1

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/proxy/sseInterceptor.d.ts

@@ -15,7 +15,15 @@
  *   upstreamResponse.body.pipeThrough(stream).pipeTo(clientWritable);
  *   const data = await telemetry; // resolves on stream end
  */
-import type { SSEInterceptorOptions, SSEInterceptorResult } from "../types/index.js";
+import type { SSEInterceptorOptions, SSEInterceptorResult, ParsedSSEBuffer } from "../types/index.js";
+/**
+ * Incrementally parse SSE events from a growing buffer of text.
+ *
+ * SSE events are separated by a blank line (`\n\n`). Each event consists of
+ * field lines (`event: ...`, `data: ...`). We consume complete events and
+ * return them, leaving any trailing partial event in the buffer.
+ */
+export declare function extractSSEEvents(buffer: string): ParsedSSEBuffer;
 /**
  * Create an SSE interceptor that extracts telemetry from an Anthropic
  * streaming response while passing all bytes through unmodified.

package/dist/lib/proxy/sseInterceptor.js

@@ -35,22 +35,23 @@ const TRUNCATION_MARKER = "...[TRUNCATED]";
  * field lines (`event: ...`, `data: ...`). We consume complete events and
  * return them, leaving any trailing partial event in the buffer.
  */
-function extractSSEEvents(buffer) {
+export function extractSSEEvents(buffer) {
     const events = [];
     // Split on double-newline boundaries. The last segment may be an
     // incomplete event if the chunk was split mid-event.
     let cursor = 0;
     while (cursor < buffer.length) {
-        const boundary = buffer.indexOf("\n\n", cursor);
-        if (boundary === -1) {
+        const boundaryMatch = /\r\n\r\n|\n\n|\r\r/.exec(buffer.slice(cursor));
+        if (!boundaryMatch || boundaryMatch.index === undefined) {
             // No more complete events — everything from cursor onward is partial.
             break;
         }
+        const boundary = cursor + boundaryMatch.index;
         const rawBlock = buffer.slice(cursor, boundary);
-        cursor = boundary + 2; // skip past the \n\n
+        cursor = boundary + boundaryMatch[0].length;
         let eventType = "";
         let dataValue = "";
-        const lines = rawBlock.split("\n");
+        const lines = rawBlock.split(/\r\n|\n|\r/);
         for (const line of lines) {
             if (line.startsWith("event: ")) {
                 eventType = line.slice(7).trim();

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

@@ -1,3 +1,5 @@
-import type { StreamTerminalOutcome, StreamTerminalOutcomeTracker } from "../types/index.js";
+import type { AnthropicStreamPreflightResult, StreamTerminalOutcome, StreamTerminalOutcomeTracker } from "../types/index.js";
+/** Hold only pre-commit SSE frames so immediate upstream errors remain retryable. */
+export declare function preflightAnthropicStream(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<AnthropicStreamPreflightResult>;
 export declare function createStreamTerminalOutcomeTracker(): StreamTerminalOutcomeTracker;
 export declare function mergeStreamTerminalOutcome(outcome: StreamTerminalOutcome, sseErrorMessage?: string): StreamTerminalOutcome;

package/dist/lib/proxy/streamOutcome.js

@@ -1,3 +1,80 @@
+import { extractSSEEvents } from "./sseInterceptor.js";
+const STREAM_PREFLIGHT_MAX_BYTES = 64 * 1024;
+const STREAM_PREFLIGHT_MAX_CHUNKS = 32;
+function parseSSEError(data) {
+    try {
+        const parsed = JSON.parse(data);
+        return {
+            errorType: parsed.error?.type ?? parsed.type ?? "stream_error",
+            message: parsed.error?.message ?? parsed.message ?? "Upstream SSE error",
+        };
+    }
+    catch {
+        return {
+            errorType: "stream_error",
+            message: data.trim() || "Upstream SSE error",
+        };
+    }
+}
+function isSSEErrorEvent(event) {
+    if (event.event === "error") {
+        return true;
+    }
+    try {
+        const parsed = JSON.parse(event.data);
+        return parsed.type === "error" || parsed.error !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** Hold only pre-commit SSE frames so immediate upstream errors remain retryable. */
+export async function preflightAnthropicStream(reader) {
+    const decoder = new TextDecoder();
+    const chunks = [];
+    let parseBuffer = "";
+    let totalBytes = 0;
+    while (totalBytes < STREAM_PREFLIGHT_MAX_BYTES &&
+        chunks.length < STREAM_PREFLIGHT_MAX_CHUNKS) {
+        let result;
+        try {
+            result = await reader.read();
+        }
+        catch (error) {
+            return { kind: "transport_error", chunks, error };
+        }
+        if (result.done) {
+            parseBuffer += decoder.decode();
+            const { events } = extractSSEEvents(parseBuffer);
+            const errorEvent = events.find(isSSEErrorEvent);
+            if (errorEvent) {
+                return { kind: "sse_error", chunks, ...parseSSEError(errorEvent.data) };
+            }
+            return chunks.length > 0
+                ? { kind: "ready", chunks }
+                : { kind: "empty", chunks };
+        }
+        if (!result.value || result.value.length === 0) {
+            continue;
+        }
+        chunks.push(result.value);
+        totalBytes += result.value.byteLength;
+        parseBuffer += decoder.decode(result.value, { stream: true });
+        const parsed = extractSSEEvents(parseBuffer);
+        parseBuffer = parsed.remainder;
+        for (const event of parsed.events) {
+            if (isSSEErrorEvent(event)) {
+                return { kind: "sse_error", chunks, ...parseSSEError(event.data) };
+            }
+            if (event.event !== "ping" && (event.event || event.data)) {
+                return { kind: "ready", chunks };
+            }
+        }
+    }
+    return chunks.length > 0
+        ? { kind: "ready", chunks }
+        : { kind: "empty", chunks };
+}
 export function createStreamTerminalOutcomeTracker() {
     let settled = false;
     let resolveOutcome;

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

@@ -0,0 +1,7 @@
+import type { ProxyUpdateWindowOptions, ProxyUpdateWindowResult } from "../types/index.js";
+/**
+ * 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 declare function waitForProxyUpdateWindow(options: ProxyUpdateWindowOptions): Promise<ProxyUpdateWindowResult>;

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;