@juspay/neurolink 12.20.1 → 12.20.2

package/dist/proxy/codexFallback.d.ts

@@ -23,21 +23,39 @@ export declare class CodexFallbackStreamError extends Error {
     constructor(payload: Record<string, unknown>, eventType: string, usage?: CodexFallbackResult["usage"]);
 }
 /**
- * Stable per-conversation routing key for OpenAI prompt caching.
+ * Routing key that pins a request to the cache already holding its prefix.
  *
  * Anthropic caching is explicit — the client marks breakpoints and the provider
  * honours them. OpenAI caching is automatic: a prefix is reused only when the
  * request lands on infrastructure already holding it, and `prompt_cache_key` is
- * what pins a conversation to one. Without it this hop takes its chances on
- * routing, which is the worst case for a fallback that arrives in bursts
- * separated by long gaps.
+ * what pins a request to one. Without it this hop takes its chances on routing,
+ * which is the worst case for a fallback that arrives in bursts separated by
+ * long gaps.
  *
- * Claude Code carries its session id inside `metadata.user_id`, alongside
- * account and device identifiers. Only the session id is read, and it is
- * hashed, so no account or device identifier reaches the upstream. When no
- * session id can be recovered the field is omitted rather than filled with
- * something shared: a key common to every conversation would pin unrelated
+ * The key must therefore describe the *prefix*, not the caller. Keying it by
+ * session id gives every session a private namespace, so N agents that share
+ * one system prompt and tool set each pay that shared prefix in full rather
+ * than paying it once — the cost is linear in fan-out width and invisible,
+ * because each request looks individually well-behaved. Across 42 captured
+ * fallback bodies the prefixes collapse to 10 distinct values, the largest
+ * shared by 12 requests belonging to different sessions.
+ *
+ * So derive the key from the prefix itself: the instructions and the tool
+ * declarations, which are exactly the leading bytes the upstream caches and
+ * the only part stable across a conversation's turns. Identical prefixes then
+ * share one cache across sessions and subagents, a prefix that genuinely
+ * differs still gets its own key so nothing unrelated contends, and turns
+ * within one session keep sharing a key because neither input changes between
+ * them.
+ *
+ * A request carrying neither instructions nor tools has no prefix worth
+ * pinning, and falls back to the session id so its turns at least stay
+ * together. With neither available the field is omitted rather than filled
+ * with something shared: a key common to every request would pin unrelated
  * prefixes onto one cache instead of separating them.
+ *
+ * The digest covers only content already sent upstream in `instructions` and
+ * `tools`; no account, device or session identifier reaches the wire.
  */
 export declare function codexPromptCacheKey(body: ClaudeRequest): string | undefined;
 /** Convert a Claude Messages request into the ChatGPT Codex Responses shape. */

package/dist/proxy/codexFallback.js

@@ -237,23 +237,95 @@ function convertClaudeMessage(role, content) {
     return input;
 }
 /**
- * Stable per-conversation routing key for OpenAI prompt caching.
+ * Routing key that pins a request to the cache already holding its prefix.
  *
  * Anthropic caching is explicit — the client marks breakpoints and the provider
  * honours them. OpenAI caching is automatic: a prefix is reused only when the
  * request lands on infrastructure already holding it, and `prompt_cache_key` is
- * what pins a conversation to one. Without it this hop takes its chances on
- * routing, which is the worst case for a fallback that arrives in bursts
- * separated by long gaps.
+ * what pins a request to one. Without it this hop takes its chances on routing,
+ * which is the worst case for a fallback that arrives in bursts separated by
+ * long gaps.
  *
- * Claude Code carries its session id inside `metadata.user_id`, alongside
- * account and device identifiers. Only the session id is read, and it is
- * hashed, so no account or device identifier reaches the upstream. When no
- * session id can be recovered the field is omitted rather than filled with
- * something shared: a key common to every conversation would pin unrelated
+ * The key must therefore describe the *prefix*, not the caller. Keying it by
+ * session id gives every session a private namespace, so N agents that share
+ * one system prompt and tool set each pay that shared prefix in full rather
+ * than paying it once — the cost is linear in fan-out width and invisible,
+ * because each request looks individually well-behaved. Across 42 captured
+ * fallback bodies the prefixes collapse to 10 distinct values, the largest
+ * shared by 12 requests belonging to different sessions.
+ *
+ * So derive the key from the prefix itself: the instructions and the tool
+ * declarations, which are exactly the leading bytes the upstream caches and
+ * the only part stable across a conversation's turns. Identical prefixes then
+ * share one cache across sessions and subagents, a prefix that genuinely
+ * differs still gets its own key so nothing unrelated contends, and turns
+ * within one session keep sharing a key because neither input changes between
+ * them.
+ *
+ * A request carrying neither instructions nor tools has no prefix worth
+ * pinning, and falls back to the session id so its turns at least stay
+ * together. With neither available the field is omitted rather than filled
+ * with something shared: a key common to every request would pin unrelated
  * prefixes onto one cache instead of separating them.
+ *
+ * The digest covers only content already sent upstream in `instructions` and
+ * `tools`; no account, device or session identifier reaches the wire.
  */
 export function codexPromptCacheKey(body) {
+    const prefix = codexCachePrefix(body);
+    if (prefix !== undefined) {
+        return createHash("sha256").update(prefix).digest("hex");
+    }
+    const sessionId = codexSessionId(body);
+    if (sessionId !== undefined) {
+        return createHash("sha256").update(sessionId).digest("hex");
+    }
+    return undefined;
+}
+/**
+ * How much of the instructions the key covers.
+ *
+ * Claude Code's system prompt is not byte-stable: measured across live 16,722
+ * character prompts, the first 14,768 characters (88.3%) are identical and the
+ * divergence sits in a trailing session-memory section that is rewritten every
+ * turn. Hashing the whole thing therefore produces a fresh key per request —
+ * the opposite of pinning. Hashing a bounded head instead tracks the part the
+ * upstream can actually reuse, since its cache is built forward from the first
+ * token.
+ *
+ * 8192 is below the observed divergence point with margin, and the error is
+ * asymmetric: too long only costs sharing, while too short pins genuinely
+ * unrelated prefixes onto one cache where they evict each other.
+ *
+ * The bound only helps a prompt long enough to have a tail beyond it. A
+ * shorter prompt is hashed whole, so a churning section inside it would move
+ * the key every turn — where keying by session used to hold still. Measured on
+ * the same corpus, that does not happen: 85 of 92 prompts carrying a system
+ * block sit under this bound, and within a session they resolve to a handful
+ * of keys rather than one per request (28 requests to 4 keys, 17 to 2, 31 to
+ * 2) — those are distinct agents, not one agent churning. Identifying the
+ * stable section structurally would remove the assumption, and is worth doing
+ * if a prompt ever proves otherwise.
+ */
+const CACHE_KEY_PREFIX_CHARS = 8192;
+/**
+ * The leading, turn-stable bytes of a Codex request: a bounded head of the
+ * instructions plus the tool names, which distinguish one agent's tool surface
+ * from another's when their instructions open identically. Descriptions and
+ * schemas are deliberately left out — they sit behind the instructions in the
+ * prefix, so two requests agreeing on this much already share a cacheable head
+ * worth routing together.
+ */
+function codexCachePrefix(body) {
+    const head = (buildSystemInstructions(body) ?? "").slice(0, CACHE_KEY_PREFIX_CHARS);
+    const toolNames = (body.tools ?? []).map((tool) => tool.name).join("\u0000");
+    if (!head && !toolNames) {
+        return undefined;
+    }
+    return `${head}\u0001${toolNames}`;
+}
+/** Claude Code carries its session id inside `metadata.user_id`. */
+function codexSessionId(body) {
     const raw = body.metadata?.user_id;
     if (typeof raw !== "string" || raw.length === 0) {
         return undefined;
@@ -270,10 +342,9 @@ export function codexPromptCacheKey(body) {
     }
     const fields = parsed;
     const sessionId = fields.session_id ?? fields.parent_session_id;
-    if (typeof sessionId !== "string" || sessionId.length === 0) {
-        return undefined;
-    }
-    return createHash("sha256").update(sessionId).digest("hex");
+    return typeof sessionId === "string" && sessionId.length > 0
+        ? sessionId
+        : undefined;
 }
 /** Convert a Claude Messages request into the ChatGPT Codex Responses shape. */
 export function convertClaudeRequestToCodex(body, model, reasoningEffort) {

package/dist/proxy/openaiFormat.js

@@ -11,6 +11,7 @@
 import { jsonSchema, tool } from "../utils/tool.js";
 import { randomBytes } from "crypto";
 import { normalizeJsonSchemaObject } from "../utils/schemaConversion.js";
+import { applyClaudeRequestCacheBreakpoints } from "../utils/anthropicCacheBreakpoints.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -603,7 +604,13 @@ export function convertOpenAIToClaudeRequest(openai) {
             ? openai.stop
             : [openai.stop];
     }
-    return result;
+    // An OpenAI-shaped caller has no way to ask for caching: its provider does it
+    // automatically from the first token, so the format carries no equivalent of
+    // `cache_control`. Translating faithfully therefore produces a request
+    // Anthropic caches at 0% on every turn — and a caller that arrives here after
+    // its own pool ran dry would burn the replacement quota faster than the one
+    // it was spared. Synthesise the breakpoints the caller could not express.
+    return applyClaudeRequestCacheBreakpoints(result);
 }
 /**
  * Convert a non-streaming Claude Messages response to an OpenAI Chat

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/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

@@ -42,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 = {
@@ -69,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 = {
@@ -86,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 = {
@@ -99,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;

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;

package/dist/utils/anthropicCacheBreakpoints.js

@@ -148,3 +148,116 @@ function markLastContentBlock(messages, i) {
     messages[i] = { ...message, content };
     return true;
 }
+/**
+ * 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 function applyClaudeRequestCacheBreakpoints(request) {
+    const existing = countAnthropicCacheMarkers({
+        system: request.system,
+        tools: request.tools,
+        messages: [],
+    });
+    const inMessages = request.messages.reduce((n, m) => n +
+        (Array.isArray(m.content)
+            ? m.content.filter((b) => "cache_control" in b && b.cache_control)
+                .length
+            : 0), 0);
+    let budget = MAX_BREAKPOINTS - existing - inMessages;
+    if (budget <= 0) {
+        return request;
+    }
+    const out = { ...request };
+    // One marker on the stable head. The last system block is the better anchor
+    // than the last tool, because system renders after tools and so a single
+    // marker there caches both.
+    if (Array.isArray(out.system) && out.system.length > 0 && existing === 0) {
+        const system = out.system.map((b) => ({ ...b }));
+        system[system.length - 1] = {
+            ...system[system.length - 1],
+            cache_control: CLAUDE_EPHEMERAL,
+        };
+        out.system = system;
+        budget--;
+    }
+    else if ((!out.system || (Array.isArray(out.system) && out.system.length === 0)) &&
+        out.tools &&
+        out.tools.length > 0 &&
+        existing === 0) {
+        const tools = out.tools.map((t) => ({ ...t }));
+        tools[tools.length - 1] = {
+            ...tools[tools.length - 1],
+            cache_control: CLAUDE_EPHEMERAL,
+        };
+        out.tools = tools;
+        budget--;
+    }
+    if (budget > 0) {
+        out.messages = applyClaudeHistoryBreakpoints(out.messages, budget);
+    }
+    return out;
+}
+const CLAUDE_EPHEMERAL = { type: "ephemeral" };
+/**
+ * Roll `budget` markers backwards along the history, marking the last content
+ * block of each message that can carry one. Only text and tool_result blocks
+ * accept `cache_control`; a message ending in anything else is skipped without
+ * spending budget.
+ *
+ * A message whose content is a plain string is promoted to the single text
+ * block the marker has to live on. Skipping strings instead would have left an
+ * ordinary conversation with no history breakpoint at all, since the OpenAI
+ * bridge emits every plain-text turn as a string — which is precisely the
+ * growing history this is here to keep cached.
+ */
+function applyClaudeHistoryBreakpoints(input, budget) {
+    const messages = input.map((m) => ({ ...m }));
+    let remaining = Math.max(0, Math.min(budget, MAX_BREAKPOINTS));
+    for (let i = messages.length - 1; i >= 0 && remaining > 0; i--) {
+        const content = messages[i].content;
+        if (typeof content === "string") {
+            if (content.length === 0) {
+                continue;
+            }
+            messages[i] = {
+                ...messages[i],
+                content: [
+                    { type: "text", text: content, cache_control: CLAUDE_EPHEMERAL },
+                ],
+            };
+            remaining--;
+            continue;
+        }
+        if (!Array.isArray(content) || content.length === 0) {
+            continue;
+        }
+        const last = content[content.length - 1];
+        if (last.type !== "text" && last.type !== "tool_result") {
+            continue;
+        }
+        if (last.cache_control) {
+            continue;
+        }
+        const blocks = content.map((b) => ({ ...b }));
+        blocks[blocks.length - 1] = { ...last, cache_control: CLAUDE_EPHEMERAL };
+        messages[i] = { ...messages[i], content: blocks };
+        remaining--;
+    }
+    return messages;
+}