@cjhyy/code-shell-core 0.9.3 → 0.9.4

package/dist/llm/providers/anthropic.js

@@ -9,6 +9,7 @@ import { countTokens } from "../token-counter.js";
 import { capabilitiesFor } from "../capabilities/index.js";
 import { resolveApiKey, resolveHeaders } from "../provider-auth.js";
 import { stripVisionFromHistory } from "../strip-vision.js";
+import { resolvePromptCachePolicy, uniquePromptCacheBreakpointIndexes, } from "../prompt-cache.js";
 /**
  * Anthropic's `max_tokens` is required, so unlike OpenAI we can't omit it when
  * the model's ceiling is unknown. Use a conservative floor in that rare case
@@ -75,12 +76,22 @@ export class AnthropicClient extends LLMClientBase {
         }
         return this._capability;
     }
+    promptCachePolicy(request) {
+        return resolvePromptCachePolicy({
+            provider: this.provider,
+            providerKind: this.config.providerKind,
+            model: this.model,
+            request,
+        });
+    }
     getPromptCacheConfigIdentity() {
+        const cachePolicy = this.promptCachePolicy();
         return {
             ...super.getPromptCacheConfigIdentity(),
-            cacheStrategy: "anthropic-explicit",
-            cacheLayoutVersion: "system-tools-history-v1",
-            breakpointCount: 3,
+            cacheStrategy: cachePolicy.strategy,
+            cacheLayoutVersion: cachePolicy.layoutVersion,
+            cacheBreakpoints: cachePolicy.breakpoints,
+            breakpointCount: cachePolicy.breakpoints.length,
             reasoningShape: this.capability.reasoning,
         };
     }
@@ -133,8 +144,9 @@ export class AnthropicClient extends LLMClientBase {
     }
     async createMessage(options) {
         return this.withRetry(async (requestSignal) => {
-            const messages = this.buildMessages(options.messages);
-            const tools = options.tools ? this.convertTools(options.tools) : undefined;
+            const cachePolicy = this.promptCachePolicy(options.promptCache);
+            const messages = this.buildMessages(options.messages, options.promptCache, cachePolicy);
+            const tools = options.tools ? this.convertTools(options.tools, cachePolicy) : undefined;
             // One span per outbound LLM request. Begin emits debug-level so the
             // info log isn't spammed during normal operation; end emits info with
             // duration_ms + usage so `--debug=llm` already gives a quick latency
@@ -146,6 +158,7 @@ export class AnthropicClient extends LLMClientBase {
                 stream: !!(options.stream && options.onChunk),
                 messageCount: messages.length,
                 toolCount: tools?.length ?? 0,
+                cacheStrategy: cachePolicy.strategy,
             });
             try {
                 const response = options.stream && options.onChunk
@@ -176,13 +189,7 @@ export class AnthropicClient extends LLMClientBase {
             const response = await this.client.messages.create({
                 model: this.model,
                 max_tokens: maxTokens,
-                system: [
-                    {
-                        type: "text",
-                        text: options.systemPrompt,
-                        cache_control: { type: "ephemeral" },
-                    },
-                ],
+                system: this.buildSystem(options.systemPrompt, this.promptCachePolicy(options.promptCache)),
                 messages,
                 ...(tools?.length ? { tools } : {}),
                 ...(thinking ? { thinking } : {}),
@@ -207,13 +214,7 @@ export class AnthropicClient extends LLMClientBase {
             const stream = this.client.messages.stream({
                 model: this.model,
                 max_tokens: maxTokens,
-                system: [
-                    {
-                        type: "text",
-                        text: options.systemPrompt,
-                        cache_control: { type: "ephemeral" },
-                    },
-                ],
+                system: this.buildSystem(options.systemPrompt, this.promptCachePolicy(options.promptCache)),
                 messages,
                 ...(tools?.length ? { tools } : {}),
                 ...(thinking ? { thinking } : {}),
@@ -316,10 +317,27 @@ export class AnthropicClient extends LLMClientBase {
             stopReason: response.stop_reason ?? undefined,
         };
     }
-    buildMessages(messages) {
+    buildSystem(systemPrompt, policy) {
+        return [
+            {
+                type: "text",
+                text: systemPrompt,
+                ...(policy.breakpoints.includes("system")
+                    ? { cache_control: { type: "ephemeral" } }
+                    : {}),
+            },
+        ];
+    }
+    buildMessages(messages, promptCache, policy) {
         messages = stripVisionFromHistory(messages, this.capability.supportsVision);
         const result = [];
-        for (const msg of messages) {
+        const stablePrefixMessageCount = Math.max(0, Math.min(messages.length, promptCache?.stablePrefixMessageCount ?? messages.length));
+        let stablePrefixEndMessage;
+        for (let sourceIndex = 0; sourceIndex < messages.length; sourceIndex++) {
+            if (sourceIndex === stablePrefixMessageCount) {
+                stablePrefixEndMessage = result[result.length - 1];
+            }
+            const msg = messages[sourceIndex];
             if (msg.role === "system")
                 continue;
             const role = msg.role === "tool" ? "user" : msg.role;
@@ -390,40 +408,45 @@ export class AnthropicClient extends LLMClientBase {
                 }
             }
         }
-        // Prompt-cache breakpoint on the history: mark the LAST content block of
-        // the LAST message. The API caches everything up to the marker, so the
-        // stable prefix (all prior turns) is reused; only the growing tail is
-        // re-billed. CC does exactly this (one marker at messages.length - 1) and
-        // warns a second history marker causes KV page eviction. We only ANNOTATE
-        // the tail block — never reorder — so the tool_use/tool_result adjacency
-        // invariant is untouched. A string-content message is lifted to a single
-        // text block so it can carry cache_control. See
-        // docs/todo/prompt-cache-optimization.md.
-        const lastMsg = result[result.length - 1];
-        if (lastMsg) {
-            if (typeof lastMsg.content === "string") {
-                lastMsg.content = [
-                    {
-                        type: "text",
-                        text: lastMsg.content,
-                        cache_control: { type: "ephemeral" },
-                    },
-                ];
-            }
-            else {
-                const lastBlock = lastMsg.content[lastMsg.content.length - 1];
-                // Skip thinking/redacted_thinking blocks: they reject cache_control and
-                // marking them would 400. buildMessages never emits them today (thinking
-                // is a top-level request field, not history content), but guard anyway
-                // so a future block type can't silently break the request.
-                if (lastBlock && lastBlock.type !== "thinking" && lastBlock.type !== "redacted_thinking") {
-                    lastBlock.cache_control = { type: "ephemeral" };
-                }
-            }
+        stablePrefixEndMessage ??= result[result.length - 1];
+        const stablePrefixEndIndex = stablePrefixEndMessage
+            ? result.indexOf(stablePrefixEndMessage)
+            : undefined;
+        const breakpointIndexes = uniquePromptCacheBreakpointIndexes([
+            policy.breakpoints.includes("stable-history") && stablePrefixEndIndex !== undefined
+                ? stablePrefixEndIndex
+                : undefined,
+            policy.breakpoints.includes("rolling-history") ? result.length - 1 : undefined,
+        ]);
+        for (const index of breakpointIndexes) {
+            this.markAnthropicCacheBreakpoint(result[index]);
         }
         return result;
     }
-    convertTools(tools) {
+    markAnthropicCacheBreakpoint(message) {
+        if (!message)
+            return;
+        if (typeof message.content === "string") {
+            message.content = [
+                {
+                    type: "text",
+                    text: message.content,
+                    cache_control: { type: "ephemeral" },
+                },
+            ];
+            return;
+        }
+        for (let index = message.content.length - 1; index >= 0; index--) {
+            const block = message.content[index];
+            // Thinking blocks reject cache_control. Walk backward so a preceding
+            // cacheable text/tool block can still anchor the prefix.
+            if (block.type === "thinking" || block.type === "redacted_thinking")
+                continue;
+            block.cache_control = { type: "ephemeral" };
+            return;
+        }
+    }
+    convertTools(tools, policy) {
         const converted = tools.map((t) => ({
             name: t.name,
             description: t.description,
@@ -436,8 +459,9 @@ export class AnthropicClient extends LLMClientBase {
         // not per-tool); a second marker here would waste a scarce cache_control
         // slot (max 4) and risk KV eviction. See docs/todo/prompt-cache-optimization.md.
         const last = converted[converted.length - 1];
-        if (last)
+        if (last && policy.breakpoints.includes("tools")) {
             last.cache_control = { type: "ephemeral" };
+        }
         return converted;
     }
     handleApiError(err) {

package/dist/llm/providers/openai.d.ts

@@ -52,6 +52,9 @@ export declare class OpenAIClient extends LLMClientBase {
     private readonly dangerouslyAllowBrowser;
     private _forceMaxCompletionTokens;
     private _dropReasoningEffort;
+    /** Compatibility fallbacks for OpenAI-compatible gateways that lag the API. */
+    private _disableExplicitPromptCache;
+    private _disablePromptCacheKey;
     constructor(config: LLMConfig, defaults?: ClientDefaults, runtimeOptions?: {
         dangerouslyAllowBrowser?: boolean;
     });
@@ -66,20 +69,7 @@ export declare class OpenAIClient extends LLMClientBase {
      */
     private _capability;
     private get capability();
-    /**
-     * True when this client routes an Anthropic-family model through OpenRouter's
-     * OpenAI-compatible endpoint. Anthropic caching is EXPLICIT — nothing is
-     * cached unless the request carries `cache_control` breakpoints (verified live
-     * 2026-07-02: plain requests to anthropic/claude-opus-4.7-fast via OpenRouter
-     * report cached_tokens 0 on every repeat; a single system-block breakpoint
-     * turns the whole stable prefix — tools + system — into a cache hit, ~89%
-     * cheaper on the follow-up). OpenAI and other OpenRouter models cache
-     * automatically, so they must NOT get breakpoints. The slug arrives resolved
-     * (e.g. "anthropic/claude-opus-4.7-fast") or as the router alias
-     * ("~anthropic/claude-opus-latest") — both start with an optional "~" then
-     * "anthropic/".
-     */
-    private get isOpenRouterAnthropic();
+    private promptCachePolicy;
     getPromptCacheConfigIdentity(): Readonly<Record<string, unknown>>;
     createMessage(options: CreateMessageOptions): Promise<LLMResponse>;
     /**
@@ -93,20 +83,10 @@ export declare class OpenAIClient extends LLMClientBase {
     private processChoice;
     private buildMessages;
     /**
-     * In-place: add prompt-cache breakpoints for Anthropic-over-OpenRouter.
-     * Mirrors the native anthropic provider (≤4 breakpoints):
-     *   1. System block  — the stable prefix. Anthropic sees tools BEFORE the
-     *      system prompt, so one marker on the system block caches tools too
-     *      (verified live: system-only marker cached 3511/3952 prompt tokens
-     *      including tool defs).
-     *   2. Last message  — one rolling breakpoint so the growing conversation
-     *      history becomes a cached prefix. Not scrolled: as history grows the
-     *      "last message" naturally advances and its tail is the next write.
-     * A string `content` is lifted to a single-element `[{type:"text",...}]`
-     * array so it can carry `cache_control`; OpenRouter accepts this OpenAI
-     * multimodal wire form for text.
+     * Translate semantic prefix boundaries to the active wire format. Both
+     * formats annotate content blocks without reordering messages.
      */
-    private applyAnthropicCacheBreakpoints;
+    private applyPromptCacheBreakpoints;
     private convertTools;
     private handleApiError;
 }

package/dist/llm/providers/openai.js

@@ -16,7 +16,8 @@ import { capabilitiesFor } from "../capabilities/index.js";
 import { clampMaxTokens } from "../clamp-max-tokens.js";
 import { resolveApiKey, resolveHeaders } from "../provider-auth.js";
 import { stripVisionFromHistory } from "../strip-vision.js";
-import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError, } from "../stream-watchdog.js";
+import { resolvePromptCachePolicy, uniquePromptCacheBreakpointIndexes, } from "../prompt-cache.js";
+import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError } from "../stream-watchdog.js";
 /**
  * Extract prompt-cache counts from an OpenAI-compatible usage object.
  *
@@ -74,9 +75,7 @@ export async function runStreamWithWatchdog(stream, opts = {}) {
     // An explicit idleTimeoutMs always activates the watchdog. Otherwise follow
     // disableWatchdog (per-call override) if set, else the env default.
     const watchdogActive = opts.idleTimeoutMs !== undefined ||
-        (opts.disableWatchdog === undefined
-            ? STREAM_WATCHDOG_CONFIG.enabled
-            : !opts.disableWatchdog);
+        (opts.disableWatchdog === undefined ? STREAM_WATCHDOG_CONFIG.enabled : !opts.disableWatchdog);
     const idleTimeoutMs = opts.idleTimeoutMs ?? STREAM_WATCHDOG_CONFIG.idleTimeoutMs;
     let text = "";
     // Fast path: watchdog disabled AND caller did not override → no overhead.
@@ -224,6 +223,9 @@ export class OpenAIClient extends LLMClientBase {
     // succeed. Omitting the field just means "model default reasoning", which is
     // fine for our background/aux calls.
     _dropReasoningEffort = false;
+    /** Compatibility fallbacks for OpenAI-compatible gateways that lag the API. */
+    _disableExplicitPromptCache = false;
+    _disablePromptCacheKey = false;
     constructor(config, defaults, runtimeOptions = {}) {
         super(config, defaults);
         this.dangerouslyAllowBrowser = runtimeOptions.dangerouslyAllowBrowser === true;
@@ -264,30 +266,26 @@ export class OpenAIClient extends LLMClientBase {
         }
         return this._capability;
     }
-    /**
-     * True when this client routes an Anthropic-family model through OpenRouter's
-     * OpenAI-compatible endpoint. Anthropic caching is EXPLICIT — nothing is
-     * cached unless the request carries `cache_control` breakpoints (verified live
-     * 2026-07-02: plain requests to anthropic/claude-opus-4.7-fast via OpenRouter
-     * report cached_tokens 0 on every repeat; a single system-block breakpoint
-     * turns the whole stable prefix — tools + system — into a cache hit, ~89%
-     * cheaper on the follow-up). OpenAI and other OpenRouter models cache
-     * automatically, so they must NOT get breakpoints. The slug arrives resolved
-     * (e.g. "anthropic/claude-opus-4.7-fast") or as the router alias
-     * ("~anthropic/claude-opus-latest") — both start with an optional "~" then
-     * "anthropic/".
-     */
-    get isOpenRouterAnthropic() {
-        return this.config.providerKind === "openrouter" && /^~?anthropic\//.test(this.model);
+    promptCachePolicy(request) {
+        const policy = resolvePromptCachePolicy({
+            provider: this.provider,
+            providerKind: this.config.providerKind,
+            model: this.model,
+            request,
+            explicitDisabled: this._disableExplicitPromptCache,
+        });
+        return this._disablePromptCacheKey && policy.cacheKey
+            ? { ...policy, cacheKey: undefined }
+            : policy;
     }
     getPromptCacheConfigIdentity() {
         const capability = this.capability;
+        const cachePolicy = this.promptCachePolicy();
         return {
             ...super.getPromptCacheConfigIdentity(),
-            cacheStrategy: this.isOpenRouterAnthropic
-                ? "openrouter-anthropic-explicit"
-                : "provider-automatic",
-            cacheLayoutVersion: this.isOpenRouterAnthropic ? "system-history-v1" : "automatic-v1",
+            cacheStrategy: cachePolicy.strategy,
+            cacheLayoutVersion: cachePolicy.layoutVersion,
+            cacheBreakpoints: cachePolicy.breakpoints,
             tokenLimitField: this._forceMaxCompletionTokens
                 ? "max_completion_tokens"
                 : capability.tokenLimitField,
@@ -295,6 +293,8 @@ export class OpenAIClient extends LLMClientBase {
             rejectedParams: [...capability.rejectedParams].sort(),
             forceMaxCompletionTokens: this._forceMaxCompletionTokens,
             dropReasoningEffort: this._dropReasoningEffort,
+            disableExplicitPromptCache: this._disableExplicitPromptCache,
+            disablePromptCacheKey: this._disablePromptCacheKey,
         };
     }
     async createMessage(options) {
@@ -305,7 +305,7 @@ export class OpenAIClient extends LLMClientBase {
             // Per-call reasoning wins; otherwise fall back to provider default
             // (settings.providers[].reasoning, threaded through LLMConfig).
             const reasoning = options.reasoning ?? this.config.reasoning;
-            const messages = this.buildMessages(options.systemPrompt, options.messages, reasoning);
+            const messages = this.buildMessages(options.systemPrompt, options.messages, reasoning, options.promptCache);
             const tools = options.tools?.length ? this.convertTools(options.tools) : undefined;
             const span = logger.span("llm.request", {
                 cat: "llm",
@@ -314,6 +314,7 @@ export class OpenAIClient extends LLMClientBase {
                 stream: !!(options.stream && options.onChunk),
                 messageCount: messages.length,
                 toolCount: tools?.length ?? 0,
+                cacheStrategy: this.promptCachePolicy(options.promptCache).strategy,
             });
             try {
                 const response = options.stream && options.onChunk
@@ -341,6 +342,7 @@ export class OpenAIClient extends LLMClientBase {
      */
     buildRequestBody(options, messages, tools, reasoning, stream) {
         const cap = this.capability;
+        const cachePolicy = this.promptCachePolicy(options.promptCache);
         // Clamp to the model's known output ceiling so a stale catalog value
         // (e.g. 384000 inherited after a hot model switch) can't 400 a
         // smaller-cap model. No known cap → send the value as-is.
@@ -449,10 +451,10 @@ export class OpenAIClient extends LLMClientBase {
         // requested summary level to that object. For the bare `reasoning_effort`
         // shape there's no summary field on chat-completions, so we skip it rather
         // than send an unknown top-level param.
-        if (this.config.reasoningSummary && reasoningBody.reasoning &&
+        if (this.config.reasoningSummary &&
+            reasoningBody.reasoning &&
             typeof reasoningBody.reasoning === "object") {
-            reasoningBody.reasoning.summary =
-                this.config.reasoningSummary;
+            reasoningBody.reasoning.summary = this.config.reasoningSummary;
         }
         // Catalog-driven passthrough params (temperature/top_p/thinking etc, already
         // wire-mapped from the connection's paramValues by applyParams). Filter each
@@ -489,6 +491,12 @@ export class OpenAIClient extends LLMClientBase {
             ...paramBody,
             // service_tier (TODO 7.2): passed through verbatim when configured.
             ...(this.config.serviceTier ? { service_tier: this.config.serviceTier } : {}),
+            ...(options.promptCache && cachePolicy.cacheKey
+                ? { prompt_cache_key: cachePolicy.cacheKey }
+                : {}),
+            ...(options.promptCache && cachePolicy.promptCacheOptions
+                ? { prompt_cache_options: cachePolicy.promptCacheOptions }
+                : {}),
             ...(tools ? { tools } : {}),
             ...(stream ? { stream: true, stream_options: { include_usage: true } } : {}),
         };
@@ -740,7 +748,7 @@ export class OpenAIClient extends LLMClientBase {
             ...(reasoningContent ? { reasoningContent } : {}),
         };
     }
-    buildMessages(systemPrompt, messages, reasoning) {
+    buildMessages(systemPrompt, messages, reasoning, promptCache) {
         const result = [{ role: "system", content: systemPrompt }];
         // Drop historical image blocks when the active model can't accept vision.
         // Engine.run only gates *new* attachments; an image left in history from
@@ -748,6 +756,8 @@ export class OpenAIClient extends LLMClientBase {
         // below and 400s ("unknown variant `image_url`") after a model switch.
         // Identity-preserving on the common path (vision models / no images).
         messages = stripVisionFromHistory(messages, this.capability.supportsVision);
+        const stablePrefixMessageCount = Math.max(0, Math.min(messages.length, promptCache?.stablePrefixMessageCount ?? messages.length));
+        let stablePrefixEndMessage = stablePrefixMessageCount === 0 ? result[0] : undefined;
         // Reasoning-content echo-back contract — driven by capability:
         //   "when-tools"  : backfill an empty placeholder if the prior assistant
         //                   turn doesn't carry one (DeepSeek V4 + tools 400s
@@ -760,11 +770,13 @@ export class OpenAIClient extends LLMClientBase {
         const cap = this.capability;
         const hasTools = messages.some((m) => Array.isArray(m.content) &&
             m.content.some((b) => b.type === "tool_use" || b.type === "tool_result"));
-        const needsReasoningBackfill = reasoning?.mode !== "off" &&
-            cap.echoReasoning === "when-tools" &&
-            hasTools;
+        const needsReasoningBackfill = reasoning?.mode !== "off" && cap.echoReasoning === "when-tools" && hasTools;
         const stripReasoning = cap.echoReasoning === "never";
-        for (const msg of messages) {
+        for (let sourceIndex = 0; sourceIndex < messages.length; sourceIndex++) {
+            if (sourceIndex === stablePrefixMessageCount) {
+                stablePrefixEndMessage = result[result.length - 1];
+            }
+            const msg = messages[sourceIndex];
             if (msg.role === "system")
                 continue;
             if (msg.role === "assistant") {
@@ -948,55 +960,64 @@ export class OpenAIClient extends LLMClientBase {
                 }
             }
         }
+        stablePrefixEndMessage ??= result[result.length - 1];
         const normalized = normalizeOpenAIToolMessagePairs(result);
-        if (this.isOpenRouterAnthropic) {
-            this.applyAnthropicCacheBreakpoints(normalized);
+        const stablePrefixEndIndex = stablePrefixEndMessage
+            ? normalized.indexOf(stablePrefixEndMessage)
+            : undefined;
+        const cachePolicy = this.promptCachePolicy(promptCache);
+        if (promptCache || cachePolicy.strategy === "anthropic-explicit") {
+            this.applyPromptCacheBreakpoints(normalized, cachePolicy, stablePrefixEndIndex !== undefined && stablePrefixEndIndex >= 0
+                ? stablePrefixEndIndex
+                : undefined);
         }
         return normalized;
     }
     /**
-     * In-place: add prompt-cache breakpoints for Anthropic-over-OpenRouter.
-     * Mirrors the native anthropic provider (≤4 breakpoints):
-     *   1. System block  — the stable prefix. Anthropic sees tools BEFORE the
-     *      system prompt, so one marker on the system block caches tools too
-     *      (verified live: system-only marker cached 3511/3952 prompt tokens
-     *      including tool defs).
-     *   2. Last message  — one rolling breakpoint so the growing conversation
-     *      history becomes a cached prefix. Not scrolled: as history grows the
-     *      "last message" naturally advances and its tail is the next write.
-     * A string `content` is lifted to a single-element `[{type:"text",...}]`
-     * array so it can carry `cache_control`; OpenRouter accepts this OpenAI
-     * multimodal wire form for text.
+     * Translate semantic prefix boundaries to the active wire format. Both
+     * formats annotate content blocks without reordering messages.
      */
-    applyAnthropicCacheBreakpoints(messages) {
-        const mark = (m) => {
-            if (!m)
+    applyPromptCacheBreakpoints(messages, policy, stablePrefixEndIndex) {
+        if (policy.strategy !== "anthropic-explicit" && policy.strategy !== "openai-explicit") {
+            return;
+        }
+        const markedMessages = new Set();
+        const mark = (index) => {
+            let cursor = Math.min(index, messages.length - 1);
+            let m;
+            while (cursor >= 0) {
+                const candidate = messages[cursor];
+                if ((typeof candidate.content === "string" && candidate.content.length > 0) ||
+                    (Array.isArray(candidate.content) && candidate.content.length > 0)) {
+                    m = candidate;
+                    break;
+                }
+                cursor--;
+            }
+            if (!m || markedMessages.has(m))
                 return;
+            markedMessages.add(m);
+            const marker = policy.strategy === "anthropic-explicit"
+                ? { cache_control: { type: "ephemeral" } }
+                : { prompt_cache_breakpoint: { mode: "explicit" } };
             // Lift a plain-string content to a text-block array so it can carry the
-            // marker. Non-text content (tool messages, image arrays) already uses an
-            // array of parts — mark the last part instead.
+            // marker. Non-text content already uses an array of parts.
             if (typeof m.content === "string") {
-                m.content = [
-                    { type: "text", text: m.content, cache_control: { type: "ephemeral" } },
-                ];
+                m.content = [{ type: "text", text: m.content, ...marker }];
                 return;
             }
             if (Array.isArray(m.content) && m.content.length > 0) {
-                // cache_control is an Anthropic-via-OpenRouter extension field, not in
-                // the OpenAI content-part union — attach through `unknown`.
                 const last = m.content[m.content.length - 1];
-                last.cache_control = { type: "ephemeral" };
+                Object.assign(last, marker);
             }
         };
-        // 1. System block (always index 0 — buildMessages seeds it first).
-        const sys = messages[0];
-        if (sys && sys.role === "system")
-            mark(sys);
-        // 2. Rolling history breakpoint on the very last message. Skip if it IS the
-        //    system message (no conversation yet) — one breakpoint already covers it.
-        const last = messages[messages.length - 1];
-        if (last && last !== sys)
-            mark(last);
+        const requested = uniquePromptCacheBreakpointIndexes([
+            policy.breakpoints.includes("system") ? 0 : undefined,
+            policy.breakpoints.includes("stable-history") ? stablePrefixEndIndex : undefined,
+            policy.breakpoints.includes("rolling-history") ? messages.length - 1 : undefined,
+        ]);
+        for (const index of requested)
+            mark(index);
     }
     convertTools(tools) {
         return tools.map((t) => ({
@@ -1031,6 +1052,33 @@ export class OpenAIClient extends LLMClientBase {
             // the corrected body — fixing the call that triggered it, not just the
             // next one.
             let selfCorrected = false;
+            // New GPT-5.6 cache fields may reach an OpenAI-compatible gateway before
+            // that gateway supports them. Downgrade sticky-per-client and retry once:
+            // first explicit -> implicit, then omit the affinity key only if that is
+            // also rejected. Native OpenAI keeps the optimized path.
+            if (err.status === 400 && msg.includes("prompt_cache")) {
+                if ((msg.includes("prompt_cache_options") || msg.includes("prompt_cache_breakpoint")) &&
+                    !this._disableExplicitPromptCache) {
+                    this._disableExplicitPromptCache = true;
+                    selfCorrected = true;
+                    logger.warn("llm.prompt_cache_explicit_unsupported", {
+                        cat: "llm",
+                        provider: this.provider,
+                        providerKind: this.config.providerKind,
+                        model: this.model,
+                    });
+                }
+                if (msg.includes("prompt_cache_key") && !this._disablePromptCacheKey) {
+                    this._disablePromptCacheKey = true;
+                    selfCorrected = true;
+                    logger.warn("llm.prompt_cache_key_unsupported", {
+                        cat: "llm",
+                        provider: this.provider,
+                        providerKind: this.config.providerKind,
+                        model: this.model,
+                    });
+                }
+            }
             // o-series / gpt-5+ reject `max_tokens` and demand
             // `max_completion_tokens`. The id-based regex catches the common
             // cases; this is the belt-and-suspenders path for ids that ship
@@ -1095,8 +1143,12 @@ export class OpenAIClient extends LLMClientBase {
 function deepMergeInto(dst, src) {
     for (const [k, v] of Object.entries(src)) {
         const cur = dst[k];
-        if (v && typeof v === "object" && !Array.isArray(v) &&
-            cur && typeof cur === "object" && !Array.isArray(cur)) {
+        if (v &&
+            typeof v === "object" &&
+            !Array.isArray(v) &&
+            cur &&
+            typeof cur === "object" &&
+            !Array.isArray(cur)) {
             deepMergeInto(cur, v);
         }
         else {

package/dist/llm/types.d.ts

@@ -2,6 +2,7 @@
  * LLM-specific internal types.
  */
 import type { Message, ToolDefinition, LLMStreamChunk, TokenUsage } from "../types.js";
+import type { PromptCacheRequestContext } from "./prompt-cache.js";
 export interface CreateMessageOptions {
     systemPrompt: string;
     messages: Message[];
@@ -33,6 +34,8 @@ export interface CreateMessageOptions {
      * the client's capability layer.
      */
     reasoning?: import("./reasoning-setting.js").ReasoningSetting;
+    /** Provider-neutral prompt-cache context supplied by the model facade. */
+    promptCache?: PromptCacheRequestContext;
 }
 export interface LLMUsageTracker {
     records: TokenUsage[];