@bubblebrain-ai/bubble 0.0.44 → 0.0.45

package/dist/agent.js

@@ -13,7 +13,7 @@ import { buildContextUsageSnapshot } from "./context/usage.js";
 import { isContextOverflowError } from "./context/overflow.js";
 import { computeRetryDelayMs, isProviderStreamInterruption, MAX_STREAM_INTERRUPTION_RETRIES, sleepBeforeRetry, } from "./network/retry.js";
 import { projectMessages } from "./context/projector.js";
-import { aggressivePruneMessages, markStableCurrentToolResultsForCache } from "./context/prune.js";
+import { aggressivePruneMessages, markStableCurrentToolResultsForCache, markToolResultCacheStable } from "./context/prune.js";
 import { truncateToolOutputForModel } from "./context/tool-output-truncate.js";
 import { buildDeferredToolsReminder, buildToolFreezeReminder, reminderForMode } from "./prompt/reminders.js";
 import { HookBus } from "./orchestrator/hooks.js";
@@ -1312,13 +1312,17 @@ export class Agent {
                                 limit: truncatedOutput.limit,
                             },
                         }, traceContext);
-                        this.appendMessage({
+                        const toolMessage = {
                             role: "tool",
                             toolCallId: tc.id,
                             content: truncatedOutput.content,
                             metadata: result.metadata,
                             isError: result.isError,
-                        });
+                        };
+                        // Stamp before appending: appendMessage persists to the session log
+                        // synchronously, so a mark added on a later turn never reaches disk.
+                        markToolResultCacheStable(tc.name, toolMessage);
+                        this.appendMessage(toolMessage);
                         this.compactResidentHistory();
                         flushGovernorReminders();
                         this.onToolResult?.(tc.name, result);

package/dist/context/prune.d.ts

@@ -1,10 +1,26 @@
-import type { Message } from "../types.js";
+import type { Message, ToolMessage } from "../types.js";
 export declare function pruneMessages<T extends Message>(messages: T[]): T[];
+/**
+ * Stamp a tool result as "projected in full" at the moment it is appended.
+ *
+ * markStableCurrentToolResultsForCache does the same thing one turn later, which
+ * is too late for the session log: the message is serialized to disk when it is
+ * appended, so a mark added afterwards never reaches the file and a resumed
+ * session re-prunes history the model had already been shown in full.
+ */
+export declare function markToolResultCacheStable(toolName: string, message: ToolMessage): void;
 export declare function markStableCurrentToolResultsForCache(messages: Message[]): void;
 /**
  * Aggressive variant of pruneMessages: drops the content of every prunable
  * tool output except the latest unresolved tool turn that the model still
  * needs to reason over. Used as a last-resort microcompact pass when a
  * standard prune hasn't reclaimed enough budget.
+ *
+ * Deliberately ignores `cacheStableProjection`, unlike pruneMessages. Honouring
+ * it here would make this a no-op — every result that has been sent once is
+ * marked — which is fine for the prefix cache and fatal for the two callers that
+ * depend on it: context-overflow (HTTP 400) recovery and the hard resident-memory
+ * limit. Losing the cache is the correct trade when the alternative is a run that
+ * cannot recover.
  */
 export declare function aggressivePruneMessages<T extends Message>(messages: T[]): T[];

package/dist/context/prune.js

@@ -54,6 +54,22 @@ export function pruneMessages(messages) {
         };
     });
 }
+/**
+ * Stamp a tool result as "projected in full" at the moment it is appended.
+ *
+ * markStableCurrentToolResultsForCache does the same thing one turn later, which
+ * is too late for the session log: the message is serialized to disk when it is
+ * appended, so a mark added afterwards never reaches the file and a resumed
+ * session re-prunes history the model had already been shown in full.
+ */
+export function markToolResultCacheStable(toolName, message) {
+    if (!shouldPruneToolResult(toolName, message.content))
+        return;
+    message.metadata = {
+        ...message.metadata,
+        [CACHE_STABLE_PROJECTION_KEY]: CACHE_STABLE_FULL_PROJECTION,
+    };
+}
 export function markStableCurrentToolResultsForCache(messages) {
     const protectedToolCallIds = collectProtectedToolCallIds(messages);
     if (protectedToolCallIds.size === 0)
@@ -101,6 +117,13 @@ function isCacheStableFullToolResult(message) {
  * tool output except the latest unresolved tool turn that the model still
  * needs to reason over. Used as a last-resort microcompact pass when a
  * standard prune hasn't reclaimed enough budget.
+ *
+ * Deliberately ignores `cacheStableProjection`, unlike pruneMessages. Honouring
+ * it here would make this a no-op — every result that has been sent once is
+ * marked — which is fine for the prefix cache and fatal for the two callers that
+ * depend on it: context-overflow (HTTP 400) recovery and the hard resident-memory
+ * limit. Losing the cache is the correct trade when the alternative is a run that
+ * cannot recover.
  */
 export function aggressivePruneMessages(messages) {
     const toolNameByCallId = new Map();
@@ -128,7 +151,15 @@ export function aggressivePruneMessages(messages) {
 function collectProtectedToolCallIds(messages) {
     for (let index = messages.length - 1; index >= 0; index--) {
         const message = messages[index];
-        if (message.role === "tool" || message.role === "system" || message.role === "meta") {
+        // A trailing user message is steered input (or a resumed session's new
+        // instruction), not the end of the tool batch. Stopping on it left the
+        // just-finished batch unmarked forever, so it stayed a live prune candidate
+        // and later batches rewrote its content mid-history — which both loses tool
+        // output the model may still need and invalidates the provider prefix cache.
+        if (message.role === "tool"
+            || message.role === "system"
+            || message.role === "meta"
+            || message.role === "user") {
             continue;
         }
         if (message.role === "assistant" && message.toolCalls && message.toolCalls.length > 0) {

package/dist/model-pricing.d.ts

@@ -6,6 +6,13 @@ export interface ModelPricing {
     currency: PricingCurrency;
     inputCacheHitPerMillion: number;
     inputCacheMissPerMillion: number;
+    /**
+     * Rate for tokens written INTO the cache, when the provider charges a premium
+     * for it (Anthropic: 1.25x base input for the 5-minute TTL). Optional —
+     * without it, cache writes are billed at the plain miss rate, which is what
+     * every provider modelled here did before Anthropic caching was enabled.
+     */
+    inputCacheWritePerMillion?: number;
     outputPerMillion: number;
     effectiveUntil?: string;
     original?: {

package/dist/model-pricing.js

@@ -1,12 +1,56 @@
 export const MODEL_PRICING = [
+    // Anthropic cache multipliers off base input: read 0.1x, 5-minute write 1.25x.
     {
         providerId: "anthropic",
         modelId: "claude-fable-5",
         currency: "USD",
-        inputCacheHitPerMillion: 10,
+        inputCacheHitPerMillion: 1,
         inputCacheMissPerMillion: 10,
+        inputCacheWritePerMillion: 12.5,
         outputPerMillion: 50,
     },
+    {
+        providerId: "anthropic",
+        modelId: "claude-opus-4-8",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.5,
+        inputCacheMissPerMillion: 5,
+        inputCacheWritePerMillion: 6.25,
+        outputPerMillion: 25,
+    },
+    {
+        providerId: "anthropic",
+        modelId: "claude-sonnet-5",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.2,
+        inputCacheMissPerMillion: 2,
+        inputCacheWritePerMillion: 2.5,
+        outputPerMillion: 10,
+        effectiveUntil: "2026-08-31T23:59:00Z",
+        original: {
+            inputCacheHitPerMillion: 0.3,
+            inputCacheMissPerMillion: 3,
+            outputPerMillion: 15,
+        },
+    },
+    {
+        providerId: "anthropic",
+        modelId: "claude-sonnet-4-6",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.3,
+        inputCacheMissPerMillion: 3,
+        inputCacheWritePerMillion: 3.75,
+        outputPerMillion: 15,
+    },
+    {
+        providerId: "anthropic",
+        modelId: "claude-haiku-4-5",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.1,
+        inputCacheMissPerMillion: 1,
+        inputCacheWritePerMillion: 1.25,
+        outputPerMillion: 5,
+    },
     {
         providerId: "deepseek",
         modelId: "deepseek-v4-flash",
@@ -52,8 +96,16 @@ export function calculateUsageCost(providerId, modelId, usage) {
     const miss = hasCacheBreakdown
         ? usage.promptCacheMissTokens ?? Math.max(0, usage.promptTokens - hit)
         : usage.promptTokens;
+    // `miss` already contains the cache-write tokens (see mergeAnthropicUsage),
+    // so writes must be netted out before being re-priced — adding a write term
+    // on top of the untouched miss term would bill them at miss + write.
+    const write = pricing.inputCacheWritePerMillion !== undefined
+        ? Math.min(usage.cacheCreationTokens ?? 0, miss)
+        : 0;
+    const missOnly = miss - write;
     const cost = (hit / 1_000_000) * pricing.inputCacheHitPerMillion
-        + (miss / 1_000_000) * pricing.inputCacheMissPerMillion
+        + (write / 1_000_000) * (pricing.inputCacheWritePerMillion ?? pricing.inputCacheMissPerMillion)
+        + (missOnly / 1_000_000) * pricing.inputCacheMissPerMillion
         + (usage.completionTokens / 1_000_000) * pricing.outputPerMillion;
     return {
         currency: pricing.currency,

package/dist/print-output.d.ts

@@ -10,9 +10,23 @@
 import type { AgentEvent } from "./types.js";
 export type PrintOutputFormat = "plain" | "json";
 export declare function parseOutputFormat(raw: string | undefined): PrintOutputFormat | undefined;
+/**
+ * Anthropic's usage decomposition, which the field names already claimed to
+ * follow: the four token buckets are DISJOINT and sum to `total_tokens`.
+ *
+ *   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+ *     + output_tokens === total_tokens
+ *
+ * `input_tokens` is therefore the uncached remainder only — it does NOT include
+ * cache reads. It used to carry the whole prompt total, which was harmless while
+ * cache reads were a flat few thousand tokens per turn, but message-level prompt
+ * caching makes reads 70-90% of the prompt, and a harness that priced
+ * `input_tokens` at the full input rate would then overstate cost ~2x.
+ */
 export interface PrintUsageSummary {
     input_tokens: number;
     cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
     output_tokens: number;
     reasoning_tokens: number;
     total_tokens: number;

package/dist/print-output.js

@@ -23,6 +23,7 @@ export class PrintRunCollector {
     usage = {
         input_tokens: 0,
         cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
         output_tokens: 0,
         reasoning_tokens: 0,
         total_tokens: 0,
@@ -57,8 +58,17 @@ export class PrintRunCollector {
     }
     addUsage(usage) {
         this.usageReported = true;
-        this.usage.input_tokens += usage.promptTokens ?? 0;
-        this.usage.cache_read_input_tokens += usage.promptCacheHitTokens ?? 0;
+        const prompt = usage.promptTokens ?? 0;
+        const cacheRead = usage.promptCacheHitTokens ?? 0;
+        // promptCacheMissTokens already includes creation, so creation has to be
+        // netted out of the uncached remainder rather than added alongside it.
+        const cacheCreation = usage.cacheCreationTokens ?? 0;
+        const uncached = usage.promptCacheMissTokens !== undefined
+            ? Math.max(0, usage.promptCacheMissTokens - cacheCreation)
+            : Math.max(0, prompt - cacheRead - cacheCreation);
+        this.usage.input_tokens += uncached;
+        this.usage.cache_read_input_tokens += cacheRead;
+        this.usage.cache_creation_input_tokens += cacheCreation;
         this.usage.output_tokens += usage.completionTokens ?? 0;
         this.usage.reasoning_tokens += usage.reasoningTokens ?? 0;
         this.usage.total_tokens += usage.totalTokens

package/dist/provider-anthropic.d.ts

@@ -36,6 +36,7 @@ interface AnthropicSystemBlock {
 type AnthropicContentBlock = {
     type: "text";
     text: string;
+    cache_control?: AnthropicCacheControl;
 } | {
     type: "image";
     source: {
@@ -46,6 +47,7 @@ type AnthropicContentBlock = {
         media_type: string;
         data: string;
     };
+    cache_control?: AnthropicCacheControl;
 } | {
     type: "thinking";
     thinking: string;
@@ -58,11 +60,13 @@ type AnthropicContentBlock = {
     id: string;
     name: string;
     input: Record<string, unknown>;
+    cache_control?: AnthropicCacheControl;
 } | {
     type: "tool_result";
     tool_use_id: string;
     content: string;
     is_error?: boolean;
+    cache_control?: AnthropicCacheControl;
 };
 interface AnthropicMessage {
     role: "user" | "assistant";
@@ -83,6 +87,28 @@ export declare function buildAnthropicRequest(options: AnthropicProviderOptions,
     thinkingLevel?: ThinkingLevel;
     stream?: boolean;
 }): AnthropicRequest;
+/**
+ * Roll prompt-cache breakpoints along the conversation so each turn's context is
+ * read back on the next turn instead of being re-billed as fresh input.
+ *
+ * Two breakpoints, and both are load-bearing:
+ *
+ * - the **tail** (last block of the last message) writes the entry that the next
+ *   request reads;
+ * - the **anchor** reads it. It goes on the message just before the final
+ *   assistant message — which is exactly where the previous request ended, since
+ *   consecutive agent-loop requests differ by one `[assistant, tool results]`
+ *   step. Landing on the written position directly is what makes this correct
+ *   for any turn size: Anthropic only looks back 20 content blocks from a
+ *   breakpoint to find a prior write, and a turn with many parallel tool calls
+ *   easily exceeds that (1 + 2N blocks for N calls). Measured on Opus 4.8 with
+ *   30 parallel calls: tail-only and a fixed-distance anchor both collapse to an
+ *   8.6% hit rate, while this anchor holds 77%.
+ *
+ * Mutates `messages` (built fresh per request by toAnthropicMessages) and
+ * returns how many breakpoints it used, never more than `budget`.
+ */
+export declare function placeMessageCacheBreakpoints(messages: AnthropicMessage[], budget: number): number;
 export declare function resolveAnthropicMaxTokens(options: AnthropicProviderOptions, model: string): number;
 export declare function supportsAnthropicPromptCache(options: AnthropicProviderOptions, model: string): boolean;
 export declare function toAnthropicMessages(messages: ProviderMessage[], echoThinking?: boolean): {

package/dist/provider-anthropic.js

@@ -12,6 +12,8 @@ const ANTHROPIC_LONG_OUTPUT_MAX_TOKENS = 64000;
 const MINIMAX_M3_MAX_TOKENS = 128000;
 const MINIMAX_M2_MAX_TOKENS = 64000;
 const ANTHROPIC_PROMPT_CACHE_CONTROL = { type: "ephemeral" };
+/** Hard API limit: a 5th cache_control breakpoint is a 400, not a warning. */
+const ANTHROPIC_MAX_CACHE_BREAKPOINTS = 4;
 const MINIMAX_PROMPT_CACHE_MODELS = new Set([
     "minimax-m2.7",
     "minimax-m2.7-highspeed",
@@ -89,11 +91,30 @@ export function buildAnthropicRequest(options, messages, chatOptions) {
         description: tool.description,
         input_schema: tool.parameters,
     }));
+    // Anthropic caps a request at 4 cache_control breakpoints and rejects the
+    // fifth outright, so the static ones are counted and the message region only
+    // ever gets what is left.
+    let staticBreakpoints = 0;
     if (enablePromptCache && tools && tools.length > 0) {
         tools[tools.length - 1] = {
             ...tools[tools.length - 1],
             cache_control: ANTHROPIC_PROMPT_CACHE_CONTROL,
         };
+        staticBreakpoints += 1;
+    }
+    if (enablePromptCache && system) {
+        staticBreakpoints += 1;
+    }
+    // Message-region breakpoints go to the official endpoint only. `baseURL` is
+    // user-editable persisted config, so a corporate gateway can keep
+    // providerId "anthropic" while pointing elsewhere — the URL check is the only
+    // trustworthy signal. Streaming only: complete() has no next turn to read the
+    // entry back.
+    if (enablePromptCache
+        && chatOptions.stream === true
+        && isOfficialAnthropicBaseUrl(options.baseURL)
+        && !messageCacheKillSwitchEnabled()) {
+        placeMessageCacheBreakpoints(anthropicMessages, ANTHROPIC_MAX_CACHE_BREAKPOINTS - staticBreakpoints);
     }
     const effectiveThinkingLevel = normalizeThinkingLevel(chatOptions.thinkingLevel ?? options.thinkingLevel ?? "off", getAvailableThinkingLevels(options.providerId || "", chatOptions.model));
     const body = {
@@ -126,6 +147,95 @@ export function buildAnthropicRequest(options, messages, chatOptions) {
     }
     return body;
 }
+/**
+ * Attach `cache_control` to the last cacheable block of `message`.
+ *
+ * Returns false when the message has nothing markable (empty block array, or a
+ * body made only of thinking blocks, where `cache_control` is not permitted).
+ */
+function markLastCacheableBlock(message) {
+    if (typeof message.content === "string") {
+        if (!message.content)
+            return false;
+        // A breakpoint needs a block to sit on. Wrapping is safe: the API keys the
+        // cache on canonicalised content, so the same message reverting to a bare
+        // string on a later turn still matches this entry.
+        message.content = [{
+                type: "text",
+                text: message.content,
+                cache_control: ANTHROPIC_PROMPT_CACHE_CONTROL,
+            }];
+        return true;
+    }
+    const blocks = message.content;
+    for (let index = blocks.length - 1; index >= 0; index--) {
+        const block = blocks[index];
+        if (block.type === "thinking" || block.type === "redacted_thinking")
+            continue;
+        blocks[index] = { ...block, cache_control: ANTHROPIC_PROMPT_CACHE_CONTROL };
+        return true;
+    }
+    return false;
+}
+/**
+ * Roll prompt-cache breakpoints along the conversation so each turn's context is
+ * read back on the next turn instead of being re-billed as fresh input.
+ *
+ * Two breakpoints, and both are load-bearing:
+ *
+ * - the **tail** (last block of the last message) writes the entry that the next
+ *   request reads;
+ * - the **anchor** reads it. It goes on the message just before the final
+ *   assistant message — which is exactly where the previous request ended, since
+ *   consecutive agent-loop requests differ by one `[assistant, tool results]`
+ *   step. Landing on the written position directly is what makes this correct
+ *   for any turn size: Anthropic only looks back 20 content blocks from a
+ *   breakpoint to find a prior write, and a turn with many parallel tool calls
+ *   easily exceeds that (1 + 2N blocks for N calls). Measured on Opus 4.8 with
+ *   30 parallel calls: tail-only and a fixed-distance anchor both collapse to an
+ *   8.6% hit rate, while this anchor holds 77%.
+ *
+ * Mutates `messages` (built fresh per request by toAnthropicMessages) and
+ * returns how many breakpoints it used, never more than `budget`.
+ */
+export function placeMessageCacheBreakpoints(messages, budget) {
+    // One-shot prompts (complete(): compaction, titles, memory) are excluded by
+    // the caller's streaming gate, not here — a single-message first turn is a
+    // real agent turn and marking its tail costs nothing, since writes are billed
+    // from the highest hit to the last breakpoint regardless of how many sit in
+    // between.
+    if (budget <= 0 || messages.length === 0)
+        return 0;
+    let used = 0;
+    const tailIndex = messages.length - 1;
+    if (budget - used >= 2) {
+        let lastAssistantIndex = -1;
+        for (let index = tailIndex; index >= 0; index--) {
+            if (messages[index].role === "assistant") {
+                lastAssistantIndex = index;
+                break;
+            }
+        }
+        const anchorIndex = lastAssistantIndex - 1;
+        // An assistant at the anchor position means consecutive assistant messages
+        // merged, so this is not the previous request's boundary and the distance
+        // back is unbounded — skip rather than guess.
+        if (anchorIndex >= 0
+            && anchorIndex < tailIndex
+            && messages[anchorIndex].role !== "assistant"
+            && markLastCacheableBlock(messages[anchorIndex])) {
+            used += 1;
+        }
+    }
+    if (budget - used >= 1 && markLastCacheableBlock(messages[tailIndex])) {
+        used += 1;
+    }
+    return used;
+}
+function messageCacheKillSwitchEnabled() {
+    const raw = process.env.BUBBLE_ANTHROPIC_MESSAGE_CACHE;
+    return raw === "0" || raw === "false";
+}
 export function resolveAnthropicMaxTokens(options, model) {
     // MiniMax needs a large output budget so thinking doesn't starve the answer.
     if (isMiniMaxProvider(options)) {
@@ -650,9 +760,18 @@ function mergeAnthropicUsage(current, raw) {
     let promptCacheMissTokens = current?.promptCacheMissTokens;
     let cacheCreationTokens = current?.cacheCreationTokens;
     if (hasPromptUsage) {
-        const inputTokens = rawInput ?? promptCacheMissTokens ?? promptTokens;
+        // Every field carries forward: a message_delta may report one of the three
+        // without the others, and defaulting a missing one to 0 would deflate
+        // promptTokens — which is the compaction anchor (agent lastInputTokens),
+        // so an undercount makes the agent compact later than it should.
+        // promptCacheMissTokens already includes cache creation, so the prior
+        // uncached remainder has to net it back out before being reused.
+        const priorUncachedInput = promptCacheMissTokens !== undefined
+            ? Math.max(0, promptCacheMissTokens - (cacheCreationTokens ?? 0))
+            : promptTokens;
+        const inputTokens = rawInput ?? priorUncachedInput;
         const cacheRead = rawCacheRead ?? promptCacheHitTokens ?? 0;
-        const cacheCreation = rawCacheCreation ?? 0;
+        const cacheCreation = rawCacheCreation ?? cacheCreationTokens ?? 0;
         promptTokens = inputTokens + cacheRead + cacheCreation;
         promptCacheHitTokens = cacheRead;
         promptCacheMissTokens = inputTokens + cacheCreation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bubblebrain-ai/bubble",
-  "version": "0.0.44",
+  "version": "0.0.45",
   "description": "A terminal coding agent",
   "type": "module",
   "engines": {