@juspay/neurolink 12.20.0 → 12.20.2

package/dist/proxy/updateCoordinator.js

@@ -1,3 +1,41 @@
+/**
+ * Parse serving identity conservatively from `/status`. A rolling status is
+ * trusted only when the worker-local fields agree with the supervisor snapshot.
+ */
+export function parseProxyServingWorkerIdentity(payload, rollingSupervisor) {
+    if (!payload || typeof payload !== "object") {
+        return null;
+    }
+    const value = payload;
+    if (typeof value.version !== "string" ||
+        !/^\d+\.\d+\.\d+$/.test(value.version) ||
+        !Number.isSafeInteger(value.pid) ||
+        Number(value.pid) <= 0) {
+        return null;
+    }
+    if (!rollingSupervisor) {
+        return { version: value.version, pid: Number(value.pid), generation: null };
+    }
+    const active = value.autoUpdate?.rolling?.active;
+    if (!active ||
+        active.version !== value.version ||
+        active.pid !== value.pid ||
+        !Number.isSafeInteger(active.generation) ||
+        Number(active.generation) <= 0) {
+        return null;
+    }
+    return {
+        version: value.version,
+        pid: Number(value.pid),
+        generation: Number(active.generation),
+    };
+}
+/** A long-running update may mutate live selection only for its original worker. */
+export function isSameProxyServingWorker(expected, current) {
+    return (current?.version === expected.version &&
+        current.pid === expected.pid &&
+        current.generation === expected.generation);
+}
 /**
  * A replacement updater starts from the newly installed package. The registry
  * then reports no newer version even when its launchd parent still runs the
@@ -72,6 +110,8 @@ function isQuiet(activity, quietThresholdMs, nowMs) {
 }
 /**
  * Prefer a naturally quiet window, then briefly drain new inference traffic.
+ * Automatic supervisor refresh uses allowBusyDrain=false: it fences admission
+ * only after a quiet observation and never waits for busy workers behind it.
  * Existing requests are never interrupted; a bounded drain failure is returned
  * to the caller so admission can be reopened and retried later.
  */
@@ -89,16 +129,43 @@ export async function waitForProxyUpdateWindow(options) {
         }
         const activity = await options.getActivity();
         if (activity && isQuiet(activity, options.quietThresholdMs, now())) {
-            return { ready: true, draining: false };
+            if (options.allowBusyDrain !== false) {
+                return { ready: true, draining: false };
+            }
+            break;
         }
         options.onPhase?.("waiting_for_quiet", activity);
         await wait(options.pollIntervalMs);
     }
+    if (options.allowBusyDrain === false) {
+        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())) {
+            options.onPhase?.("waiting_for_quiet", activity);
+            return { ready: false, draining: false, reason: "busy" };
+        }
+    }
     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" };
     }
+    if (options.allowBusyDrain === false) {
+        // The worker's idle fence closes the observation/admission race. Any new
+        // cross-generation activity means resume immediately, never hold a busy
+        // service behind maintenance responses for the normal drain timeout.
+        const activity = await options.getActivity();
+        if (activity && isProxyRuntimeSettled(activity)) {
+            return { ready: true, draining: true };
+        }
+        const resumed = await options.setDraining(false);
+        return { ready: false, draining: !resumed, reason: "busy" };
+    }
     const drainDeadline = now() + options.drainWaitMs;
     while (now() < drainDeadline) {
         if (options.isStopping()) {

package/dist/proxy/updateState.d.ts

@@ -67,3 +67,5 @@ export declare function reconcileRunningUpdate(runningVersion: string, stateFile
  * @param stateFilePath - Override path for testing
  */
 export declare function recordCheck(latestVersion: string, stateFilePath?: string): void;
+/** Preserve the last successful registry version when discovery fails. */
+export declare function recordCheckFailure(message: string, stateFilePath?: string): void;

package/dist/proxy/updateState.js

@@ -124,6 +124,12 @@ export function loadUpdateState(stateFilePath) {
         return {
             ...getDefaultUpdateState(),
             ...candidate,
+            lastCheckAttemptAt: typeof candidate.lastCheckAttemptAt === "string"
+                ? candidate.lastCheckAttemptAt
+                : undefined,
+            lastCheckError: typeof candidate.lastCheckError === "string"
+                ? candidate.lastCheckError.slice(0, 1_000)
+                : null,
             suppressedVersions: candidate.suppressedVersions ?? {},
             // Backfill order matters for state files written before `installedVersion`
             // existed. Back then `recordUpdateInstalled()` set ONLY
@@ -303,6 +309,15 @@ export function reconcileRunningUpdate(runningVersion, stateFilePath) {
 export function recordCheck(latestVersion, stateFilePath) {
     const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
     state.lastCheckAt = new Date().toISOString();
+    state.lastCheckAttemptAt = state.lastCheckAt;
+    state.lastCheckError = null;
     state.lastCheckVersion = latestVersion;
     saveUpdateState(state, stateFilePath);
 }
+/** Preserve the last successful registry version when discovery fails. */
+export function recordCheckFailure(message, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.lastCheckAttemptAt = new Date().toISOString();
+    state.lastCheckError = message.slice(0, 1_000);
+    saveUpdateState(state, stateFilePath);
+}

package/dist/proxy/vertexAnthropicFallback.d.ts

@@ -12,7 +12,7 @@
  * `tool_use`, `tool_result`, `cache_control` and thinking blocks all survive
  * here because nothing reshapes them.
  */
-import type { UsageContext, VertexPassthroughTerminal, VertexAnthropicPassthroughRequest, VertexAnthropicPassthroughTarget } from "../types/index.js";
+import type { VertexAccessTokenProvider, UsageContext, VertexPassthroughTerminal, VertexAnthropicPassthroughRequest, VertexAnthropicPassthroughTarget } from "../types/index.js";
 /**
  * Translate `output_config` for Vertex.
  *
@@ -29,6 +29,22 @@ export declare function buildVertexAnthropicPayload(body: Readonly<Record<string
  * caller's `stream` flag selects the verb rather than changing the body.
  */
 export declare function buildVertexAnthropicUrl(target: VertexAnthropicPassthroughTarget): string;
+/**
+ * Replace the Google credential lookup, for tests only.
+ *
+ * Without this seam the two-leg fallback chain cannot be driven end to end.
+ * The rest of the hop is reachable — `dispatchVertexAnthropicPassthrough`
+ * calls the global `fetch`, which a test can replace — but the credential
+ * lookup goes through gaxios, and gaxios resolves its transport to
+ * `(await import("node-fetch")).default` rather than `globalThis.fetch`. A
+ * test that swaps the global therefore cannot intercept the token exchange,
+ * and on a machine with no Application Default Credentials the leg throws
+ * before it ever reaches the model. That left the one path that bills in real
+ * currency with no end-to-end coverage at all.
+ *
+ * Pass `undefined` to restore the real credential lookup.
+ */
+export declare function setVertexAccessTokenProviderForTests(provider: VertexAccessTokenProvider | undefined): void;
 /**
  * Send one Anthropic-shaped request to Vertex and return the upstream response
  * untouched, so the caller can stream its bytes straight to the client.

package/dist/proxy/vertexAnthropicFallback.js

@@ -135,12 +135,36 @@ function auth() {
     cachedAuth ??= new GoogleAuth({ scopes: [CLOUD_PLATFORM_SCOPE] });
     return cachedAuth;
 }
+let accessTokenProviderForTests;
+async function vertexAccessToken() {
+    return accessTokenProviderForTests
+        ? accessTokenProviderForTests()
+        : auth().getAccessToken();
+}
+/**
+ * Replace the Google credential lookup, for tests only.
+ *
+ * Without this seam the two-leg fallback chain cannot be driven end to end.
+ * The rest of the hop is reachable — `dispatchVertexAnthropicPassthrough`
+ * calls the global `fetch`, which a test can replace — but the credential
+ * lookup goes through gaxios, and gaxios resolves its transport to
+ * `(await import("node-fetch")).default` rather than `globalThis.fetch`. A
+ * test that swaps the global therefore cannot intercept the token exchange,
+ * and on a machine with no Application Default Credentials the leg throws
+ * before it ever reaches the model. That left the one path that bills in real
+ * currency with no end-to-end coverage at all.
+ *
+ * Pass `undefined` to restore the real credential lookup.
+ */
+export function setVertexAccessTokenProviderForTests(provider) {
+    accessTokenProviderForTests = provider;
+}
 /**
  * Send one Anthropic-shaped request to Vertex and return the upstream response
  * untouched, so the caller can stream its bytes straight to the client.
  */
 export async function dispatchVertexAnthropicPassthrough(request) {
-    const token = await auth().getAccessToken();
+    const token = await vertexAccessToken();
     if (!token) {
         throw new Error("Vertex passthrough could not obtain a Google access token; " +
             "check Application Default Credentials for this project");

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

@@ -175,6 +175,22 @@ declare function trackUpstreamReadableStream(source: ReadableStream<Uint8Array>)
  * diagnostics the operator wants.
  */
 declare function redactHeadersForBorrower(headers: Record<string, string>): Record<string, string>;
+/**
+ * The model that actually served a fallback turn.
+ *
+ * One request can leave more than one leg's model in metadata: the Codex leg
+ * records its model on the failure path before the chain moves on, and the
+ * configured chain tries Codex first. Choosing by key precedence therefore
+ * billed a Vertex-served turn as the Codex model — the exact misattribution
+ * this file's pricing fix exists to prevent. The account type that reached
+ * `logFinalRequest` is the only authoritative signal for which leg answered,
+ * so select on that and ignore the other leg's leftovers.
+ */
+export declare function resolveServedFallbackModel(metadata: {
+    codexFallbackModel?: unknown;
+    vertexFallbackModel?: unknown;
+}, accountType: string | undefined): string | undefined;
+declare function clearClaudeFallbackTerminalEvidence(ctx: ServerContext): void;
 declare function executeClaudeFallbackTranslation(args: {
     ctx: ServerContext;
     body: ClaudeRequest;
@@ -462,6 +478,7 @@ export declare function isTransientHttpFailure(status: number, errBody: string):
 export declare function isUpstreamOverload(status: number, errBody: string): boolean;
 export declare function redactProviderErrorMessage(message: string): string;
 export declare const __testHooks: {
+    clearClaudeFallbackTerminalEvidence: typeof clearClaudeFallbackTerminalEvidence;
     normalizeQuotaForAccounts: typeof normalizeQuotaForAccounts;
     resolveHomeIndex: typeof resolveHomeIndex;
     maybeResetPrimaryToHome: typeof maybeResetPrimaryToHome;

package/dist/server/routes/claudeProxyRoutes.js

@@ -100,6 +100,16 @@ function resolveRequestLogAccountIdentity(accountLabel, accountType) {
             provider: "anthropic",
         };
     }
+    if (accountType === "vertex") {
+        // A native fallback leg has no OAuth login — the account IS the served
+        // model, e.g. "vertex/claude-opus-4-6". Without this branch `provider`
+        // stays unset, `annotateRequestPricing` falls back to
+        // "openai-compatible", and that resolves to a cross-provider scan which
+        // prices the turn from the *requested* alias in the Anthropic table
+        // instead of the served model in the Vertex one — a 2.5x under-report on
+        // the only leg that bills in real currency.
+        return { accountKey: accountLabel, provider: "vertex" };
+    }
     return {};
 }
 // ---------------------------------------------------------------------------
@@ -3567,11 +3577,29 @@ async function loadClaudeProxyAccounts(args) {
         isClaudeClientRequest: isLikelyClaudeClient(clientHeaders, clientSnapshotBody),
     };
 }
+/**
+ * The model that actually served a fallback turn.
+ *
+ * One request can leave more than one leg's model in metadata: the Codex leg
+ * records its model on the failure path before the chain moves on, and the
+ * configured chain tries Codex first. Choosing by key precedence therefore
+ * billed a Vertex-served turn as the Codex model — the exact misattribution
+ * this file's pricing fix exists to prevent. The account type that reached
+ * `logFinalRequest` is the only authoritative signal for which leg answered,
+ * so select on that and ignore the other leg's leftovers.
+ */
+export function resolveServedFallbackModel(metadata, accountType) {
+    const served = accountType === "vertex"
+        ? metadata.vertexFallbackModel
+        : metadata.codexFallbackModel;
+    return typeof served === "string" && served.length > 0 ? served : undefined;
+}
 function clearClaudeFallbackTerminalEvidence(ctx) {
     for (const key of [
         "codexFallbackAccount",
         "codexFallbackAccountType",
         "codexFallbackModel",
+        "vertexFallbackModel",
         "codexFallbackFailureUsage",
         "codexFallbackDeferredFailure",
         "sdkFallbackFailure",
@@ -4054,6 +4082,19 @@ async function tryConfiguredClaudeFallbackChain(args) {
                 // the caller's pending tool call, which strands every agentic turn.
                 const vertexModel = fallback.model;
                 const vertexAccount = `vertex/${vertexModel}`;
+                // A Codex leg that already failed left its own terminal evidence
+                // behind — its model, account, deferred-failure flag and failure
+                // usage. Every one of those is read again when this turn finalizes:
+                // the model would be logged and priced in place of the Vertex one,
+                // the deferred-failure branch would re-attribute the tracer to
+                // "openai" after the Vertex leg set it, and the failure usage would
+                // merge its reasoning tokens into this turn's counts. Start the leg
+                // clean, the same way a fresh upstream dispatch does.
+                clearClaudeFallbackTerminalEvidence(ctx);
+                // Billing follows the model that served the turn. The request log
+                // otherwise records `body.model` — the alias the client asked for —
+                // and prices Opus-on-Vertex at Sonnet rates.
+                ctx.metadata.vertexFallbackModel = vertexModel;
                 response = await executeVertexAnthropicFallback({
                     body,
                     model: vertexModel,
@@ -6212,18 +6253,24 @@ function createClaudeRequestRuntimeContext(args) {
             recordFinalSuccess(finalAccountLabel, finalAccountType);
         }
         const traceCtx = tracer?.getTraceContext();
+        const servedModel = resolveServedFallbackModel(ctx.metadata, finalAccountType);
         logRequest({
             timestamp: new Date().toISOString(),
             requestId: ctx.requestId,
             method: ctx.method,
             path: ctx.path,
-            model: typeof ctx.metadata.codexFallbackModel === "string"
-                ? ctx.metadata.codexFallbackModel
-                : body.model,
-            ...(typeof ctx.metadata.codexFallbackModel === "string"
+            model: servedModel ?? body.model,
+            ...(servedModel
                 ? {
                     requestedModel: body.model,
-                    inputIncludesCachedTokens: false,
+                    // Codex reports input inclusive of cached tokens; the Vertex
+                    // Anthropic wire reports them separately, exactly as the native
+                    // path does, so the flag stays Codex-only. Keyed off the serving
+                    // account for the same reason `servedModel` is: a failed Codex leg
+                    // leaves its model behind on a turn Vertex went on to serve.
+                    ...(finalAccountType === "vertex"
+                        ? {}
+                        : { inputIncludesCachedTokens: false }),
                 }
                 : {}),
             ...(ctx.metadata.contextPreflight
@@ -8777,6 +8824,7 @@ export function redactProviderErrorMessage(message) {
 // spinning up a full proxy. Keep this surface small.
 // ---------------------------------------------------------------------------
 export const __testHooks = {
+    clearClaudeFallbackTerminalEvidence,
     normalizeQuotaForAccounts,
     resolveHomeIndex,
     maybeResetPrimaryToHome,

package/dist/types/cli.d.ts

@@ -1044,6 +1044,24 @@ export type TelemetryStatsArgs = TelemetryCommandArgs & {
     byModel?: boolean;
     byProvider?: boolean;
 };
+/** Staging-only native collector migration; never activates a service. */
+export type TelemetryNativePrepareArgs = {
+    collectorConfig: string;
+    output: string;
+    queueDirectory: string;
+    compactionDirectory: string;
+    bodyPort: number;
+    bodyStream?: string;
+    metadataQueueMib: number;
+    bodyQueueMib: number;
+    diskQuotaMib: number;
+    metadataRetentionDays: number;
+    bodyRetentionDays: number;
+};
+export type TelemetryNativeValidateArgs = {
+    directory: string;
+    collectorBin: string;
+};
 /** Available exporter names */
 export type ExporterName = "langfuse" | "langsmith" | "otel" | "datadog" | "sentry" | "braintrust" | "arize" | "posthog" | "laminar";
 /** Observability command arguments */

package/dist/types/providers.d.ts

@@ -2281,6 +2281,14 @@ export type VertexAnthropicTool = {
     };
     cache_control?: VertexAnthropicCacheControl;
 };
+/**
+ * Supplies the bearer token for a Vertex publisher call.
+ *
+ * Exists so a test can stand in for the Google credential lookup: gaxios
+ * resolves its transport to node-fetch rather than `globalThis.fetch`, so a
+ * test that swaps the global cannot intercept the token exchange.
+ */
+export type VertexAccessTokenProvider = () => Promise<string | null | undefined>;
 /** Input to `applyVertexAnthropicCacheBreakpoints`. */
 export type VertexAnthropicCacheInput = {
     system?: string;

package/dist/types/proxy.d.ts

@@ -16,6 +16,11 @@ import type { ProxyContextEvidence, ProxyPreparedContext } from "./proxyContext.
  * - src/lib/server/routes/claudeProxyRoutes.ts (runtime state, deps)
  */
 import type { Counter, Histogram, Span } from "@opentelemetry/api";
+import type { LogRecordExporter } from "@opentelemetry/sdk-logs";
+/** HTTP exporter with an explicit bounded-shutdown cancellation boundary. */
+export type ProxyOtlpLogTransport = LogRecordExporter & {
+    abortPending: () => void;
+};
 import type { Hono } from "hono";
 import type { Ora } from "ora";
 import type { MCPToolRegistry } from "../mcp/toolRegistry.js";
@@ -37,10 +42,27 @@ export type ModelRouterInterface = {
     getModelMappings?: () => ModelMapping[];
     getPassthroughModels?: () => string[];
 };
+/**
+ * Anthropic prompt-cache breakpoint marker.
+ *
+ * Anthropic caching is explicit: the prefix up to each marker is cached, and a
+ * request carrying none is cached not at all. Four markers is the hard ceiling.
+ */
+export type ClaudeCacheControl = {
+    type: "ephemeral";
+    /**
+     * How long the marked prefix stays cached. The API accepts a 5-minute or a
+     * 1-hour window, priced at 1.25x and 2x base input respectively; omitting it
+     * means 5 minutes. Without this field a caller cannot express the 1-hour
+     * marker at all.
+     */
+    ttl?: "5m" | "1h";
+};
 /** A single text block in a Claude content array. */
 export type ClaudeTextBlock = {
     type: "text";
     text: string;
+    cache_control?: ClaudeCacheControl;
 };
 /** A single image block in a Claude content array. */
 export type ClaudeImageBlock = {
@@ -64,6 +86,7 @@ export type ClaudeToolResultBlock = {
     type: "tool_result";
     tool_use_id: string;
     content: string | ClaudeContentBlock[];
+    cache_control?: ClaudeCacheControl;
 };
 /** A thinking/reasoning block in a Claude content array. */
 export type ClaudeThinkingBlock = {
@@ -81,6 +104,7 @@ export type ClaudeTool = {
     name: string;
     description?: string;
     input_schema: Record<string, unknown>;
+    cache_control?: ClaudeCacheControl;
 };
 /** Metadata attached to a Claude Messages API request. */
 export type ClaudeMetadata = {
@@ -94,10 +118,7 @@ export type ClaudeRequest = {
     model: string;
     messages: ClaudeMessage[];
     max_tokens: number;
-    system?: string | Array<{
-        type: "text";
-        text: string;
-    }>;
+    system?: string | ClaudeTextBlock[];
     temperature?: number;
     top_p?: number;
     top_k?: number;
@@ -726,6 +747,49 @@ export type ProxyBodyDeliveryResult = {
     maxChunkExportMs?: number;
     reason?: string;
 };
+/** One-hop reference to identical redacted bytes from the same request. */
+export type ProxyBodyCaptureReference = {
+    captureId: string;
+    requestId: string;
+    bodySha256: string;
+    redactedBodyBytes: number;
+    /** Source export settlement time, used to bound backend reconstruction. */
+    exportedAt: string;
+};
+export type ProxyBodyCapturePublication = {
+    delivery?: ProxyBodyDeliveryResult | {
+        status: "reference";
+        reason: "identical_redacted_payload";
+    } | {
+        status: "policy_excluded";
+        reason: "body_byte_budget_exhausted" | "body_byte_budget_invalid";
+    };
+    reference?: ProxyBodyCaptureReference;
+};
+export type ProxyBodyCapturePolicyOptions = {
+    bytesPerMinute?: string;
+    deduplicate?: boolean;
+    now?: () => number;
+};
+export type ProxyBodyCapturePolicySnapshot = {
+    deduplicationEnabled: boolean;
+    maxReferences: number;
+    referenceTtlMs: number;
+    references: number;
+    byteBudgetPerMinute: number | null;
+    invalidByteBudget: boolean;
+    availableBytes: number | null;
+    submittedBytes: number;
+    deduplicatedCaptures: number;
+    deduplicatedBytes: number;
+    policyExcludedCaptures: number;
+    policyExcludedBytes: number;
+};
+export type ProxyBodyDeduplicationEntry = {
+    reference: ProxyBodyCaptureReference;
+    expiresAt: number;
+    acknowledged: Promise<boolean>;
+};
 /** One bounded body publication, tracked across exporter callbacks. */
 export type ProxyBodyPublicationProgress = {
     acknowledged: number;
@@ -828,6 +892,7 @@ export type ProxyRequestLoggerSnapshot = {
     diskEnabled?: boolean;
     otel?: ReturnType<typeof import("../proxy/otelLogSink.js").getProxyOtelLogSnapshot>;
     bodyCapture?: ProxyBodyCaptureWorkerSnapshot;
+    bodyCapturePolicy?: ProxyBodyCapturePolicySnapshot;
     enabled: boolean;
     requests: ProxyRequestLogSinkSnapshot;
     attempts: ProxyRequestLogSinkSnapshot;
@@ -2563,6 +2628,20 @@ export type UpdateCheckResult = {
     currentVersion: string;
     latestVersion: string;
     updateAvailable: boolean;
+} & ({
+    checkSucceeded: true;
+    checkError?: never;
+} | {
+    checkSucceeded: false;
+    checkError: string;
+    updateAvailable: false;
+});
+/** Immutable identity of the worker an update attempt is allowed to replace. */
+export type ProxyServingWorkerIdentity = {
+    version: string;
+    pid: number;
+    /** Rolling generation; null only for a legacy single-process service. */
+    generation: number | null;
 };
 /** Result of one local proxy health probe by the updater or fail-open guard. */
 export type ProxyHealthProbe = {
@@ -2587,6 +2666,9 @@ export type SuppressedVersion = {
 export type UpdateState = {
     lastCheckAt: string;
     lastCheckVersion: string;
+    /** Last attempt is distinct from the last successful registry observation. */
+    lastCheckAttemptAt?: string;
+    lastCheckError?: string | null;
     suppressedVersions: Record<string, SuppressedVersion>;
     /**
      * Last package version whose stable trampoline was successfully validated.
@@ -2621,7 +2703,7 @@ export type UpdateState = {
 export type ProxyUpdateWindowResult = {
     ready: boolean;
     draining: boolean;
-    reason?: "stopping" | "parent_stopped" | "drain_failed" | "drain_timeout";
+    reason?: "stopping" | "parent_stopped" | "drain_failed" | "drain_timeout" | "busy";
 };
 /** Dependencies and timing controls for the updater's safe-window coordinator. */
 export type ProxyUpdateWindowOptions = {
@@ -2629,6 +2711,8 @@ export type ProxyUpdateWindowOptions = {
     quietWaitMs: number;
     drainWaitMs: number;
     pollIntervalMs: number;
+    /** Automatic supervisor refresh must defer instead of draining busy traffic. */
+    allowBusyDrain?: boolean;
     getActivity: () => Promise<ProxyRuntimeActivity | null>;
     setDraining: (draining: boolean) => Promise<boolean>;
     isStopping: () => boolean;
@@ -2705,6 +2789,10 @@ export type ProxyWorkerControlMessage = {
 } | {
     type: "proxy-worker:shutdown";
     generation: number;
+} | {
+    type: "proxy-worker:socket-offer";
+    generation: number;
+    socketId: string;
 } | {
     type: "proxy-worker:socket-commit";
     generation: number;
@@ -2720,6 +2808,10 @@ export type ProxyWorkerStatusMessage = {
     pid: number;
     version: string;
     processInstanceId?: string;
+    /** New supervisors defer sending descriptors until commit. */
+    socketOfferProtocol?: "control-before-handle";
+    /** New workers confirm descriptor adoption before a generation drains. */
+    socketCommitProtocol?: "worker-ack";
 } | {
     type: "proxy-worker:drained";
     generation: number;
@@ -2738,6 +2830,11 @@ export type ProxyWorkerStatusMessage = {
     generation: number;
     pid: number;
     socketId: string;
+} | {
+    type: "proxy-worker:socket-committed";
+    generation: number;
+    pid: number;
+    socketId: string;
 } | {
     type: "proxy-worker:replacement-requested";
     generation: number;
@@ -2755,8 +2852,12 @@ export type TransferableProxySocket = Pick<import("node:net").Socket, "destroy"
 export type DetachableTransferableProxySocket = TransferableProxySocket & Pick<import("node:net").Socket, "off">;
 export type RollingWorkerHandle = {
     pid: number;
+    /** Combined offer and commit budget, before any retry. Defaults to 60s. */
+    socketTransferTimeoutMs?: number;
     sendControl: (message: ProxyWorkerControlMessage) => void;
-    sendSocket: (generation: number, socket: TransferableProxySocket, callback: (error?: Error | null) => void) => void;
+    sendSocket: (generation: number, socket: TransferableProxySocket, callback: (error?: Error | null) => void, 
+    /** Absolute admission deadline shared by queueing and any safe retry. */
+    deadlineAt?: number) => void;
     terminate: (signal?: NodeJS.Signals) => void;
     onMessage: (listener: (message: ProxyWorkerStatusMessage) => void) => () => void;
     onExit: (listener: (code: number | null, signal: string | null) => void) => () => void;
@@ -2853,6 +2954,9 @@ export type RollingProxyServerOptions = {
     shutdownTimeoutMs?: number;
     recoveryDelayMs?: number;
     maxRecoveryDelayMs?: number;
+    /** Backoff after failed pressure-induced replacement, while old worker serves. */
+    stallReplacementDelayMs?: number;
+    maxStallReplacementDelayMs?: number;
     onStateChange?: (snapshot: RollingWorkerSupervisorSnapshot) => void;
     onEvent?: (event: RollingWorkerSupervisorEvent) => void;
     log?: (message: string) => void;
@@ -2879,8 +2983,12 @@ export type RollingCandidateWorker = RollingManagedWorker & {
     activationRequested: boolean;
     settle: (error?: Error) => void;
 };
-export type RollingQueuedSocket = {
+export type RollingSocketAdmission = {
     socket: TransferableProxySocket;
+    deadlineAt: number;
+    retried: boolean;
+};
+export type RollingQueuedSocket = RollingSocketAdmission & {
     timeout: NodeJS.Timeout;
 };
 export type SocketWorkerRuntime = {
@@ -2896,6 +3004,8 @@ export type SocketWorkerRuntime = {
 };
 export type SocketWorkerRuntimeOptions = {
     onDrained?: () => void;
+    /** Bound for a committed socket's first HTTP request while draining. */
+    firstRequestGraceMs?: number;
 };
 /** Shape of the dynamically-imported js-yaml module. `dump` is optional —
  *  read-only consumers (proxy config loader) only need `load`; writers

package/dist/utils/anthropicCacheBreakpoints.d.ts

@@ -1,4 +1,4 @@
-import type { VertexAnthropicCacheInput, VertexAnthropicCacheOutput, VertexAnthropicMessage } from "../types/index.js";
+import type { ClaudeRequest, VertexAnthropicCacheInput, VertexAnthropicCacheOutput, VertexAnthropicMessage } from "../types/index.js";
 /** Anthropic allows at most four `cache_control` breakpoints per request. */
 export declare const ANTHROPIC_MAX_CACHE_BREAKPOINTS = 4;
 /**
@@ -41,3 +41,24 @@ export declare function countAnthropicCacheMarkers(input: {
  * the input array is cloned, never mutated.
  */
 export declare function applyAnthropicHistoryCacheBreakpoints(input: ReadonlyArray<VertexAnthropicMessage>, budget: number): VertexAnthropicMessage[];
+/**
+ * Breakpoint placement for a Claude Messages request the proxy built itself,
+ * rather than one a client authored.
+ *
+ * A request translated from another wire format arrives with no markers at
+ * all, because the format it came from has no way to express one: OpenAI-shaped
+ * callers rely on automatic prefix caching, which Anthropic does not do. A
+ * faithful translation is therefore cached at 0% on every turn, and a caller
+ * that fell back here from an exhausted pool burns the replacement quota faster
+ * than the one it was spared.
+ *
+ * Placement follows Anthropic's `tools → system → messages` rendering: one
+ * marker on the last system block covers tools *and* system in a single
+ * breakpoint, and the rest roll along the tail of the history so a growing
+ * conversation keeps its settled prefix cached. Markers the caller supplied are
+ * counted first and never displaced — this only spends what is left of the
+ * four.
+ *
+ * Pure: inputs are cloned, never mutated.
+ */
+export declare function applyClaudeRequestCacheBreakpoints(request: ClaudeRequest): ClaudeRequest;