@cjhyy/code-shell-core 0.9.3 → 0.9.5

package/dist/engine/engine.d.ts

@@ -317,6 +317,14 @@ export declare class Engine {
      * in-process AgentServer to decide whether to wire an interactive askUser.
      */
     isHeadless(): boolean;
+    /**
+     * A background_notification park only makes sense where the Session can be
+     * woken by the completion later (server refuses headless; sub-agent sessions
+     * are not in chatManager) — everywhere else honouring it would end the run
+     * early and orphan the background result. A reply_committed boundary is
+     * synchronous and never suppressed.
+     */
+    private suppressesRunYield;
     get permissionMode(): NonNullable<EngineConfig["permissionMode"]>;
     get planMode(): boolean;
     /**

package/dist/engine/engine.js

@@ -804,6 +804,16 @@ export class Engine {
     isHeadless() {
         return this.config.headless === true;
     }
+    /**
+     * A background_notification park only makes sense where the Session can be
+     * woken by the completion later (server refuses headless; sub-agent sessions
+     * are not in chatManager) — everywhere else honouring it would end the run
+     * early and orphan the background result. A reply_committed boundary is
+     * synchronous and never suppressed.
+     */
+    suppressesRunYield(reason) {
+        return (reason === "background_notification" && (this.isHeadless() || this.config.isSubAgent === true));
+    }
     get permissionMode() {
         return this.permissionController.permissionMode;
     }
@@ -2172,18 +2182,12 @@ export class Engine {
             publishGoalJudgeContext: (context) => {
                 publishGoalJudgeContext(context);
             },
-            // A background_notification yield parks the run until the Session is
-            // woken by the completion notification. Only a top-level interactive
-            // session can be woken (server refuses headless; sub-agent sessions
-            // are not in chatManager) — everywhere else honouring the yield would
-            // end the run early and orphan the background result, so the loop
-            // never sees the request and the model keeps its full turn.
-            ...(this.isHeadless() || this.config.isSubAgent === true
-                ? {}
-                : {
-                    peekToolRunYield: () => toolCtx.runYield?.peek?.(),
-                    consumeToolRunYield: () => toolCtx.runYield?.consume(),
-                }),
+            // A background_notification yield is visible only where the Session
+            // can be woken later. A committed host reply is a synchronous terminal
+            // boundary, so it must remain visible in headless and sub-agent runs.
+            // One predicate serves peek and consume so they can never disagree.
+            peekToolRunYield: (reason) => !this.suppressesRunYield(reason) && toolCtx.runYield?.peek(reason) === true,
+            consumeToolRunYield: (reason) => !this.suppressesRunYield(reason) && toolCtx.runYield?.consume(reason) === true,
             ctxOverheadStore: {
                 get: (s) => this.ctxOverheadBySid.get(s) ?? 0,
                 set: (s, n) => {

package/dist/engine/model-facade.d.ts

@@ -2,11 +2,14 @@
  * Model call facade — wraps LLM client with transcript integration.
  */
 import type { LLMClientBase } from "../llm/client-base.js";
+import type { PromptCacheRequestContext } from "../llm/prompt-cache.js";
 import type { Message, ToolDefinition, LLMResponse, StreamCallback } from "../types.js";
 import { Transcript } from "../session/transcript.js";
 import { type PromptPrefixFingerprint } from "./prompt-cache-diagnostics.js";
 export interface ModelCallRecordingOptions {
     sensitiveToolResultRedactions?: ReadonlyMap<string, string>;
+    /** Cache boundary metadata; scopeId is filled from the active session. */
+    promptCache?: Omit<PromptCacheRequestContext, "scopeId">;
 }
 /**
  * Prompt-cache hit rate for one request, as CC computes it:

package/dist/engine/model-facade.js

@@ -89,6 +89,7 @@ export class ModelFacade {
                     }
                 },
                 signal,
+                promptCache: { scopeId: sid, ...recordingOptions?.promptCache },
             });
         }
         catch (err) {
@@ -144,6 +145,7 @@ export class ModelFacade {
                 tools,
                 stream: false,
                 signal,
+                promptCache: { scopeId: sid, ...recordingOptions?.promptCache },
             });
         }
         catch (err) {

package/dist/engine/run-tooling.js

@@ -10,7 +10,7 @@ import { applyDynamicToolDef } from "./dynamic-tool-defs.js";
 /** engine.ts L1485-1522 —— ToolContext 组装(spawner、agentDefinitions、base 由调用方传入)。 */
 export function buildRunToolContext(args) {
     const { options, profile, profileParams } = args;
-    let pendingRunYield;
+    const pendingRunYield = new Set();
     // sessionId is filled in after the session bundle is resolved below
     // (the session may be cold-started or resumed). Until then this is
     // intentionally shaped as a mutable local; we treat it as immutable
@@ -40,16 +40,16 @@ export function buildRunToolContext(args) {
             toolCtx.cwd = nextCwd;
         },
         runYield: {
+            // Reasons accumulate independently — a batch may both commit a host
+            // reply and launch background work; the turn loop decides precedence.
             request(reason) {
-                pendingRunYield ??= reason;
+                pendingRunYield.add(reason);
             },
-            peek() {
-                return pendingRunYield;
+            peek(reason) {
+                return pendingRunYield.has(reason);
             },
-            consume() {
-                const reason = pendingRunYield;
-                pendingRunYield = undefined;
-                return reason;
+            consume(reason) {
+                return pendingRunYield.delete(reason);
             },
         },
         skillAllowlist: options?.skillAllowlist !== undefined

package/dist/engine/streaming-tool-queue.d.ts

@@ -17,12 +17,15 @@ import type { ToolCall, ToolResult } from "../types.js";
 import type { ToolExecutor } from "../tool-system/executor.js";
 export declare class StreamingToolQueue {
     private readonly executor;
+    private readonly pendingUnsafeSkipReason?;
     private readonly pending;
     private readonly unsafeQueue;
     private readonly callOrder;
     private readonly toolNameById;
     private draining;
-    constructor(executor: ToolExecutor);
+    constructor(executor: ToolExecutor, options?: {
+        pendingUnsafeSkipReason?: () => string | undefined;
+    });
     /**
      * Enqueue a tool from the completed response. Concurrency-safe tools start
      * immediately within this post-response phase; unsafe tools are queued for

package/dist/engine/streaming-tool-queue.js

@@ -15,13 +15,15 @@
  */
 export class StreamingToolQueue {
     executor;
+    pendingUnsafeSkipReason;
     pending = new Map();
     unsafeQueue = [];
     callOrder = [];
     toolNameById = new Map();
     draining = false;
-    constructor(executor) {
+    constructor(executor, options) {
         this.executor = executor;
+        this.pendingUnsafeSkipReason = options?.pendingUnsafeSkipReason;
     }
     /**
      * Enqueue a tool from the completed response. Concurrency-safe tools start
@@ -62,8 +64,21 @@ export class StreamingToolQueue {
         this.draining = true;
         const resultMap = new Map();
         // Execute unsafe tools sequentially. A rejection here must not stop the
-        // remaining unsafe tools from running.
+        // remaining unsafe tools from running. A trusted terminal boundary may,
+        // however, skip calls that have not started yet. We still synthesize one
+        // result per call so tool_use/tool_result history remains structurally
+        // complete even though the run will stop after this batch.
         for (const call of this.unsafeQueue) {
+            const skipReason = this.pendingUnsafeSkipReason?.();
+            if (skipReason) {
+                resultMap.set(call.id, {
+                    id: call.id,
+                    toolName: call.toolName,
+                    error: `Tool execution skipped: ${skipReason}`,
+                    isError: true,
+                });
+                continue;
+            }
             const p = this.executor.executeSingle(call);
             this.pending.set(call.id, p);
             resultMap.set(call.id, await this.toResult(call.id, call.toolName, p));

package/dist/engine/turn-loop.d.ts

@@ -150,10 +150,10 @@ export interface TurnLoopDeps {
      * built-in judge closure; it is never added to the public on_stop context.
      */
     publishGoalJudgeContext?: (context: GoalJudgeRuntimeContext) => void;
-    /** Inspect a trusted tool's pending run yield without clearing it. */
-    peekToolRunYield?: () => import("../tool-system/context.js").ToolRunYieldReason | undefined;
-    /** Consume a trusted tool's request to yield until an async notification. */
-    consumeToolRunYield?: () => import("../tool-system/context.js").ToolRunYieldReason | undefined;
+    /** Whether a trusted tool has a specific run boundary pending (not cleared). */
+    peekToolRunYield?: (reason: import("../tool-system/context.js").ToolRunYieldReason) => boolean;
+    /** Consume a specific pending run boundary; true if it was pending. */
+    consumeToolRunYield?: (reason: import("../tool-system/context.js").ToolRunYieldReason) => boolean;
 }
 export interface TurnLoopResult {
     text: string;
@@ -287,7 +287,16 @@ export declare class TurnLoop {
     private finalizeModelTurn;
     private prepareMessagesForModel;
     private stripVolatileContextMessages;
-    private appendVolatileContextMessages;
+    /**
+     * Keep volatile context out of compaction/summarization without moving it on
+     * every model round. If context management is a no-op, return the original
+     * array so the provider sees a strictly append-only prompt. A real rewrite
+     * (dedupe/compaction/truncation) already invalidates the old prefix, so start
+     * a fresh append-only segment with the volatile snapshot at the new tail.
+     */
+    private restoreVolatileAfterContextManagement;
+    private manageContextMessages;
+    private manageContextMessagesSync;
     private markPendingImagesConsumed;
     private redactConsumedSensitiveToolResults;
     private modelCallRecordingOptions;

package/dist/engine/turn-loop.js

@@ -340,10 +340,36 @@ export class TurnLoop {
         });
         return changed ? stripped : messages;
     }
-    appendVolatileContextMessages(messages) {
-        if (this.volatileContextMessages.size === 0)
-            return messages;
-        return [...this.stripVolatileContextMessages(messages), ...this.volatileContextMessages];
+    /**
+     * Keep volatile context out of compaction/summarization without moving it on
+     * every model round. If context management is a no-op, return the original
+     * array so the provider sees a strictly append-only prompt. A real rewrite
+     * (dedupe/compaction/truncation) already invalidates the old prefix, so start
+     * a fresh append-only segment with the volatile snapshot at the new tail.
+     */
+    restoreVolatileAfterContextManagement(original, stableInput, managedStable) {
+        const unchanged = stableInput.length === managedStable.length &&
+            stableInput.every((message, index) => managedStable[index] === message);
+        if (unchanged)
+            return original;
+        const volatile = original.filter((message) => this.volatileContextMessages.has(message));
+        return [...managedStable, ...volatile];
+    }
+    async manageContextMessages(messages) {
+        if (this.volatileContextMessages.size === 0) {
+            return this.deps.contextManager.manageAsync(messages, this.config.signal);
+        }
+        const stable = this.stripVolatileContextMessages(messages);
+        const managed = await this.deps.contextManager.manageAsync(stable, this.config.signal);
+        return this.restoreVolatileAfterContextManagement(messages, stable, managed);
+    }
+    manageContextMessagesSync(messages) {
+        if (this.volatileContextMessages.size === 0) {
+            return this.deps.contextManager.manage(messages);
+        }
+        const stable = this.stripVolatileContextMessages(messages);
+        const managed = this.deps.contextManager.manage(stable);
+        return this.restoreVolatileAfterContextManagement(messages, stable, managed);
     }
     markPendingImagesConsumed(messages) {
         if (this.pendingImageMessages.size === 0)
@@ -367,11 +393,15 @@ export class TurnLoop {
         this.sensitiveToolResultRedactions.clear();
         return redacted;
     }
-    modelCallRecordingOptions() {
-        if (this.sensitiveToolResultRedactions.size === 0)
-            return undefined;
+    modelCallRecordingOptions(messages) {
+        const volatileIndex = messages.findIndex((message) => this.volatileContextMessages.has(message));
         return {
-            sensitiveToolResultRedactions: new Map(this.sensitiveToolResultRedactions),
+            ...(this.sensitiveToolResultRedactions.size > 0
+                ? { sensitiveToolResultRedactions: new Map(this.sensitiveToolResultRedactions) }
+                : {}),
+            promptCache: {
+                stablePrefixMessageCount: volatileIndex >= 0 ? volatileIndex : messages.length,
+            },
         };
     }
     trackFreshImageMessage(message) {
@@ -657,7 +687,6 @@ export class TurnLoop {
                 // pendingImageMessages are preserved through this next model request.
                 const hasPendingSensitiveToolResults = this.sensitiveToolResultRedactions.size > 0;
                 messages = this.prepareMessagesForModel(messages);
-                messages = this.stripVolatileContextMessages(messages);
                 if (hasPendingSensitiveToolResults) {
                     tlog.info("turn.sensitive_tool_result_context_management_skipped", {
                         cat: "turn",
@@ -666,7 +695,7 @@ export class TurnLoop {
                 }
                 else {
                     // Context management (async — may trigger LLM summarization)
-                    messages = await this.deps.contextManager.manageAsync(messages, this.config.signal);
+                    messages = await this.manageContextMessages(messages);
                     // manageAsync can itself issue an LLM summarization call lasting several
                     // seconds; if the signal aborted during it, stop here rather than
                     // proceeding into the (expensive) main model call. Belt to the loop-top
@@ -710,7 +739,6 @@ export class TurnLoop {
                     messages = this.redactConsumedSensitiveToolResults(messages);
                     return { text: finalText, reason: "completed", messages };
                 }
-                messages = this.appendVolatileContextMessages(messages);
                 // Model call (with streaming fallback and max_output_tokens continuation)
                 this.config.onStream?.({
                     type: "stream_request_start",
@@ -721,7 +749,15 @@ export class TurnLoop {
                 this.streamedToolIds.clear();
                 // Tool queue is created before the call, but enqueue happens only after
                 // the complete LLMResponse is available below.
-                const streamingQueue = new StreamingToolQueue(this.deps.toolExecutor);
+                const streamingQueue = new StreamingToolQueue(this.deps.toolExecutor, {
+                    // Once a trusted reply tool commits the authoritative host response,
+                    // later sequential calls from the same model batch must not execute.
+                    // Concurrency-safe calls may already be running; drain still awaits
+                    // those so the transcript remains complete.
+                    pendingUnsafeSkipReason: () => this.deps.peekToolRunYield?.("reply_committed")
+                        ? "an authoritative host reply was already committed"
+                        : undefined,
+                });
                 let response;
                 try {
                     response = await this.callModelWithFallback(messages, assistantMessageId);
@@ -891,7 +927,8 @@ export class TurnLoop {
                             },
                         ];
                         try {
-                            const contResponse = await this.deps.model.call(this.deps.systemPrompt, this.prepareMessagesForModel(contMessages), this.deps.tools, this.config.onStream, this.config.signal);
+                            const preparedContinuationMessages = this.prepareMessagesForModel(contMessages);
+                            const contResponse = await this.deps.model.call(this.deps.systemPrompt, preparedContinuationMessages, this.deps.tools, this.config.onStream, this.config.signal, this.modelCallRecordingOptions(preparedContinuationMessages));
                             // Continuations are separate provider responses, so preserve the
                             // same structural tool_use invariant before processing this one.
                             if (contResponse.toolCalls.length > 0) {
@@ -995,7 +1032,7 @@ export class TurnLoop {
                     // answered before parking the run. Keep the tool's yield request
                     // pending across that extra model round, then park once the model
                     // has replied and there is still no background result to consume.
-                    if (this.deps.consumeToolRunYield?.() === "background_notification") {
+                    if (this.deps.consumeToolRunYield?.("background_notification")) {
                         tlog.info("turn.background_notification_wait_after_steer", { cat: "turn" });
                         messages = this.redactConsumedSensitiveToolResults(messages);
                         return {
@@ -1272,30 +1309,47 @@ export class TurnLoop {
                 // Tool results just pushed; recompute ctx so the bar updates *before*
                 // the next model round-trip — large tool outputs can move it sharply.
                 this.emitCtxFromMessages(messages);
-                // A trusted tool launched asynchronous work whose completion is routed
-                // back into this Session. End this run at the tool boundary instead of
-                // asking the model for another step with no new evidence; the queued
-                // completion notification will wake the Session and continue normally.
-                // This precedes complete_goal so a single batch cannot launch unfinished
-                // background work and simultaneously claim the enclosing Goal is done.
-                if (this.deps.peekToolRunYield?.() === "background_notification") {
+                // A trusted tool marked a run boundary. reply_committed: the
+                // authoritative user-facing reply is recorded — another model request
+                // could only produce duplicate tools or stray assistant text.
+                // background_notification: async work was launched whose completion
+                // notification will wake this Session, so the run parks instead of
+                // asking the model for another step with no new evidence. One batch
+                // may pend both; the park wins so the completion finds a parked run.
+                const replyCommitted = this.deps.peekToolRunYield?.("reply_committed") === true;
+                const backgroundWait = this.deps.peekToolRunYield?.("background_notification") === true;
+                if (replyCommitted || backgroundWait) {
                     // Close the current model turn before a queued steer re-drives it;
                     // interrupt-and-redrive swaps the turn signal at this boundary.
                     this.finalizeModelTurn();
                     if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
+                        // A user message arrived while the batch was executing. The
+                        // committed reply answered the previous content only — lift the
+                        // reply barrier so the re-driven round can answer the new message
+                        // (the host itself rejects duplicate authoritative replies), and
+                        // keep any background park pending across the extra round.
+                        if (replyCommitted)
+                            this.deps.consumeToolRunYield?.("reply_committed");
                         continue;
                     }
-                }
-                if (this.deps.peekToolRunYield?.() === "background_notification" &&
-                    this.deps.consumeToolRunYield?.() === "background_notification") {
-                    tlog.info("turn.background_notification_wait", { cat: "turn" });
-                    messages = this.redactConsumedSensitiveToolResults(messages);
-                    return {
-                        text: finalText,
-                        reason: "completed",
-                        messages,
-                        completionKind: "background_wait",
-                    };
+                    // Park before complete_goal so a single batch cannot launch
+                    // unfinished background work and simultaneously claim the enclosing
+                    // Goal is done.
+                    if (backgroundWait && this.deps.consumeToolRunYield?.("background_notification")) {
+                        tlog.info("turn.background_notification_wait", { cat: "turn" });
+                        messages = this.redactConsumedSensitiveToolResults(messages);
+                        return {
+                            text: finalText,
+                            reason: "completed",
+                            messages,
+                            completionKind: "background_wait",
+                        };
+                    }
+                    if (replyCommitted && this.deps.consumeToolRunYield?.("reply_committed")) {
+                        tlog.info("turn.reply_committed_stop", { cat: "turn" });
+                        messages = this.redactConsumedSensitiveToolResults(messages);
+                        return { text: finalText, reason: "completed", messages };
+                    }
                 }
                 // Goal mode P0: explicit completion. If the model called complete_goal,
                 // it has DECLARED the goal done — short-circuit to "completed" WITHOUT
@@ -1496,7 +1550,7 @@ export class TurnLoop {
             });
         }
         else {
-            messages = this.deps.contextManager.manage(messages);
+            messages = this.manageContextMessagesSync(messages);
         }
         if (this.goalControlStopRequested) {
             messages = this.redactConsumedSensitiveToolResults(messages);
@@ -1512,8 +1566,9 @@ export class TurnLoop {
                 messages = this.redactConsumedSensitiveToolResults(messages);
                 return { text: finalText, reason: "completed", messages };
             }
-            const summaryResponse = await this.deps.model.call(this.deps.systemPrompt, this.prepareMessagesForModel(messages), [], // No tools available for summary turn
-            this.config.onStream, this.config.signal, this.modelCallRecordingOptions());
+            const summaryMessages = this.prepareMessagesForModel(messages);
+            const summaryResponse = await this.deps.model.call(this.deps.systemPrompt, summaryMessages, [], // No tools available for summary turn
+            this.config.onStream, this.config.signal, this.modelCallRecordingOptions(summaryMessages));
             if (summaryResponse.usage?.promptTokens !== undefined) {
                 this.recordResponseUsage(summaryResponse.usage, "primary", false);
             }
@@ -1591,7 +1646,7 @@ export class TurnLoop {
             }
             : undefined;
         try {
-            return await this.deps.model.call(this.deps.systemPrompt, messages, this.deps.tools, wrappedStream, this.config.signal, this.modelCallRecordingOptions());
+            return await this.deps.model.call(this.deps.systemPrompt, messages, this.deps.tools, wrappedStream, this.config.signal, this.modelCallRecordingOptions(messages));
         }
         catch (err) {
             // If it's a context or rate limit error, don't fallback — propagate
@@ -1637,7 +1692,7 @@ export class TurnLoop {
                 error: err.message,
             });
             // Retry without streaming
-            return await this.deps.model.callWithoutStreaming(this.deps.systemPrompt, messages, this.deps.tools, this.config.signal, this.modelCallRecordingOptions());
+            return await this.deps.model.callWithoutStreaming(this.deps.systemPrompt, messages, this.deps.tools, this.config.signal, this.modelCallRecordingOptions(messages));
         }
     }
     get currentTurn() {

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.9.3";
+export declare const VERSION = "0.9.5";
 export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionKind, SessionWorkspace, SessionProjectBinding, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, TurnCompletionKind, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export type { GoalConfig, GoalLifecycleConfig, GoalLifecyclePhase, GoalLifecycleTerminalReason, GoalLifecycleV1, } from "./goal/lifecycle.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, CompositionError, SandboxUnavailableError, } from "./exceptions.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.9.3";
+export const VERSION = "0.9.5";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, CompositionError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Composition (AgentModule / ResolvedComposition) ─────────────

package/dist/llm/prompt-cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Provider-neutral prompt-cache planning.
+ *
+ * This module owns the semantic cache policy (session affinity and reusable
+ * prefix boundaries). Provider clients only translate the plan to their wire
+ * format: OpenAI `prompt_cache_*` fields or Anthropic `cache_control` blocks.
+ */
+export type PromptCacheStrategy = "openai-explicit" | "openai-implicit" | "anthropic-explicit" | "provider-managed";
+export type PromptCacheBreakpoint = "system" | "tools" | "stable-history" | "rolling-history";
+export interface PromptCacheRequestContext {
+    /** Stable run/session namespace used for provider cache affinity. */
+    scopeId?: string;
+    /**
+     * Number of source messages before the first volatile context message.
+     * Providers use this to retain a reusable durable-history breakpoint while
+     * also advancing a rolling breakpoint over the append-only in-run tail.
+     */
+    stablePrefixMessageCount?: number;
+}
+export interface PromptCachePolicy {
+    strategy: PromptCacheStrategy;
+    layoutVersion: string;
+    breakpoints: readonly PromptCacheBreakpoint[];
+    /** Opaque and <=64 chars, as required by OpenAI's prompt_cache_key. */
+    cacheKey?: string;
+    /** GPT-5.6+ explicit-cache request mode. */
+    promptCacheOptions?: {
+        mode: "explicit";
+        ttl: "30m";
+    };
+}
+export interface ResolvePromptCachePolicyInput {
+    provider: string;
+    providerKind?: string;
+    model: string;
+    request?: PromptCacheRequestContext;
+    /** Sticky compatibility fallback after an endpoint rejects explicit fields. */
+    explicitDisabled?: boolean;
+}
+/**
+ * Produce a privacy-preserving stable affinity key without leaking a raw
+ * session id to the provider. The prefix plus 48 hex chars is 51 characters.
+ */
+export declare function createPromptCacheKey(scopeId: string, namespace: string): string;
+/** Resolve one cache policy from the actual provider route and model family. */
+export declare function resolvePromptCachePolicy(input: ResolvePromptCachePolicyInput): PromptCachePolicy;
+/** Deduplicate semantic boundaries while preserving their left-to-right order. */
+export declare function uniquePromptCacheBreakpointIndexes(indexes: readonly (number | undefined)[]): number[];

package/dist/llm/prompt-cache.js

@@ -0,0 +1,100 @@
+/**
+ * Provider-neutral prompt-cache planning.
+ *
+ * This module owns the semantic cache policy (session affinity and reusable
+ * prefix boundaries). Provider clients only translate the plan to their wire
+ * format: OpenAI `prompt_cache_*` fields or Anthropic `cache_control` blocks.
+ */
+import { createHash } from "node:crypto";
+const OPENAI_EXPLICIT_BREAKPOINTS = ["system", "stable-history", "rolling-history"];
+const ANTHROPIC_BREAKPOINTS = ["system", "tools", "stable-history", "rolling-history"];
+const OPENROUTER_ANTHROPIC_BREAKPOINTS = ["system", "stable-history", "rolling-history"];
+function normalizedModel(model) {
+    return model.replace(/^~/, "");
+}
+function isAnthropicModel(model) {
+    return /^anthropic\/claude-/i.test(normalizedModel(model));
+}
+function isOpenAIModel(model) {
+    const normalized = normalizedModel(model);
+    return /^openai\//i.test(normalized) || /^(?:gpt-|o\d)/i.test(normalized);
+}
+/** GPT-5.6 and later 5.x releases support explicit prompt-cache breakpoints. */
+function supportsOpenAIExplicitCaching(model) {
+    const normalized = normalizedModel(model).replace(/^openai\//i, "");
+    const match = /^gpt-5\.(\d+)(?:[-.]|$)/i.exec(normalized);
+    return match !== null && Number(match[1]) >= 6;
+}
+/**
+ * Produce a privacy-preserving stable affinity key without leaking a raw
+ * session id to the provider. The prefix plus 48 hex chars is 51 characters.
+ */
+export function createPromptCacheKey(scopeId, namespace) {
+    const digest = createHash("sha256")
+        .update("codeshell-prompt-cache-v1\0")
+        .update(namespace)
+        .update("\0")
+        .update(scopeId)
+        .digest("hex")
+        .slice(0, 48);
+    return `cs:${digest}`;
+}
+/** Resolve one cache policy from the actual provider route and model family. */
+export function resolvePromptCachePolicy(input) {
+    const kind = (input.providerKind ?? input.provider).toLowerCase();
+    const model = normalizedModel(input.model);
+    const key = input.request?.scopeId
+        ? createPromptCacheKey(input.request.scopeId, `${kind}:${model}`)
+        : undefined;
+    if (input.provider === "anthropic" || kind === "anthropic") {
+        return {
+            strategy: "anthropic-explicit",
+            layoutVersion: "system-tools-stable-rolling-v2",
+            breakpoints: ANTHROPIC_BREAKPOINTS,
+        };
+    }
+    if (kind === "openrouter" && isAnthropicModel(model)) {
+        return {
+            strategy: "anthropic-explicit",
+            // OpenRouter/Anthropic includes tools in the system-prefix cache entry,
+            // so a separate tool marker is unnecessary and preserves one slot.
+            layoutVersion: "system-stable-rolling-v2",
+            breakpoints: OPENROUTER_ANTHROPIC_BREAKPOINTS,
+        };
+    }
+    const openAIRoute = kind === "openai" || (kind === "openrouter" && isOpenAIModel(model));
+    if (openAIRoute && supportsOpenAIExplicitCaching(model) && input.explicitDisabled !== true) {
+        return {
+            strategy: "openai-explicit",
+            layoutVersion: "system-stable-rolling-v1",
+            breakpoints: OPENAI_EXPLICIT_BREAKPOINTS,
+            ...(key ? { cacheKey: key } : {}),
+            promptCacheOptions: { mode: "explicit", ttl: "30m" },
+        };
+    }
+    if (openAIRoute) {
+        return {
+            strategy: "openai-implicit",
+            layoutVersion: "implicit-affinity-v1",
+            breakpoints: [],
+            ...(key ? { cacheKey: key } : {}),
+        };
+    }
+    return {
+        strategy: "provider-managed",
+        layoutVersion: "append-only-v1",
+        breakpoints: [],
+    };
+}
+/** Deduplicate semantic boundaries while preserving their left-to-right order. */
+export function uniquePromptCacheBreakpointIndexes(indexes) {
+    const seen = new Set();
+    const result = [];
+    for (const index of indexes) {
+        if (index === undefined || index < 0 || seen.has(index))
+            continue;
+        seen.add(index);
+        result.push(index);
+    }
+    return result;
+}

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

@@ -16,6 +16,7 @@ export declare class AnthropicClient extends LLMClientBase {
      */
     private _capability;
     private get capability();
+    private promptCachePolicy;
     getPromptCacheConfigIdentity(): Readonly<Record<string, unknown>>;
     /**
      * Translate the resolved ReasoningSetting into Anthropic's `thinking` field,
@@ -44,7 +45,9 @@ export declare class AnthropicClient extends LLMClientBase {
     private nonStreamMessage;
     private streamMessage;
     private processResponse;
+    private buildSystem;
     private buildMessages;
+    private markAnthropicCacheBreakpoint;
     private convertTools;
     private handleApiError;
 }