@animalabs/membrane 0.5.79 → 0.5.81

package/src/floating-cache-marker.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Floating cache marker: incremental prompt caching inside the native
+ * tool loop (see the doctrine block in buildNativeToolRequest).
+ *
+ * Context strategies place breakpoints once per turn at compile time; the
+ * tool loop rebuilds the request every round with an append-only suffix
+ * the strategy never saw. The float rides the newest message using only
+ * the RESIDUAL breakpoint budget — upstream markers are never displaced.
+ * Motivating incident: qa-ops 2026-08-20, ~5.3M uncached tokens in 18min
+ * from two subagents whose single marker sat at message 2 of 61.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { Membrane } from './membrane.js';
+import type { NormalizedRequest, NormalizedMessage } from './types/index.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const text = (t: string) => ({ type: 'text' as const, text: t });
+
+const user = (t: string, bp = false): NormalizedMessage => ({
+  participant: 'User',
+  content: [text(t)],
+  ...(bp ? { cacheBreakpoint: true } : {}),
+});
+
+const assistantToolCall = (id: string): NormalizedMessage => ({
+  participant: 'Claude',
+  content: [
+    text('running a tool'),
+    { type: 'tool_use' as const, id, name: 'shell', input: { cmd: 'ls' } },
+  ],
+});
+
+const toolResults = (id: string, bp = false): NormalizedMessage => ({
+  participant: 'User',
+  content: [{ type: 'tool_result' as const, toolUseId: id, content: 'ok' }],
+  ...(bp ? { cacheBreakpoint: true } : {}),
+});
+
+/** A turn: marked kickoff + `rounds` completed tool rounds. */
+function turn(rounds: number, kickoffMarked = true): NormalizedMessage[] {
+  const messages: NormalizedMessage[] = [user('do the thing', kickoffMarked)];
+  for (let i = 1; i <= rounds; i++) {
+    messages.push(assistantToolCall(`t${i}`), toolResults(`t${i}`));
+  }
+  return messages;
+}
+
+function makeRequest(overrides: Partial<NormalizedRequest> = {}): NormalizedRequest {
+  return {
+    messages: [],
+    system: 'You are a test agent.',
+    config: { model: 'claude-sonnet-5', maxTokens: 128 },
+    tools: [{ name: 'shell', description: 'run a command', inputSchema: { type: 'object' } }],
+    promptCaching: true,
+    cacheTtl: '1h',
+    assistantParticipant: 'Claude',
+    ...overrides,
+  } as NormalizedRequest;
+}
+
+function build(request: NormalizedRequest, messages: NormalizedMessage[], rebuild: boolean, membrane?: Membrane) {
+  const m = membrane ?? new Membrane({ name: 'anthropic' } as any);
+  return (m as any).buildNativeToolRequest(request, messages, rebuild);
+}
+
+/** Total cache_control instances across the whole wire request. */
+function totalMarkers(pr: any): number {
+  let n = 0;
+  pr.messages.forEach((m: any) =>
+    (Array.isArray(m.content) ? m.content : []).forEach((b: any) => { if (b.cache_control) n++; }));
+  if (Array.isArray(pr.tools)) pr.tools.forEach((t: any) => { if (t.cache_control) n++; });
+  if (Array.isArray(pr.system)) pr.system.forEach((b: any) => { if (b.cache_control) n++; });
+  return n;
+}
+
+/** [messageIndex, blockIndex] of every message-level cache_control, plus tools/system markers. */
+function markers(pr: any): { messages: Array<[number, number]>; onTools: boolean; onSystem: boolean } {
+  const msgs: Array<[number, number]> = [];
+  pr.messages.forEach((m: any, mi: number) => {
+    (Array.isArray(m.content) ? m.content : []).forEach((b: any, bi: number) => {
+      if (b.cache_control) msgs.push([mi, bi]);
+    });
+  });
+  const onTools = Array.isArray(pr.tools) && pr.tools.some((t: any) => t.cache_control);
+  const onSystem = Array.isArray(pr.system) && pr.system.some((b: any) => b.cache_control);
+  return { messages: msgs, onTools, onSystem };
+}
+
+const last = (pr: any) => pr.messages.length - 1;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('floating cache marker', () => {
+  it('does not float on the turn\'s first build', () => {
+    const pr = build(makeRequest(), turn(1), false);
+    // Only the strategy's kickoff marker; the round's suffix is unmarked.
+    expect(markers(pr).messages).toEqual([[0, 0]]);
+  });
+
+  it('floats onto the newest message on a tool-loop rebuild', () => {
+    const pr = build(makeRequest(), turn(1), true);
+    const m = markers(pr);
+    // Kickoff marker intact + float on the final tool_result envelope.
+    expect(m.messages).toContainEqual([0, 0]);
+    expect(m.messages).toContainEqual([last(pr), 0]);
+    // Fallback stays suppressed: message markers exist.
+    expect(m.onTools).toBe(false);
+    expect(m.onSystem).toBe(false);
+  });
+
+  it('keeps the previous round\'s endpoint marked when budget allows', () => {
+    const pr = build(makeRequest(), turn(2), true);
+    const m = markers(pr);
+    // kickoff + previous round's results envelope + newest envelope.
+    expect(m.messages).toEqual([[0, 0], [last(pr) - 2, 0], [last(pr), 0]]);
+  });
+
+  it('never stacks a second marker on an already-marked final message', () => {
+    const messages = turn(2);
+    (messages[messages.length - 1] as any).cacheBreakpoint = true;
+    const pr = build(makeRequest(), messages, true);
+    const m = markers(pr);
+    const onFinal = m.messages.filter(([mi]) => mi === last(pr));
+    expect(onFinal).toHaveLength(1);
+    // Budget not consumed by the dedupe: previous endpoint still floated.
+    expect(m.messages).toContainEqual([last(pr) - 2, 0]);
+  });
+
+  it('withholds the float (with one warning) when upstream markers fill all 4 slots', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const messages = turn(3);
+    // Mark every results envelope: 1 kickoff + 3 results = 4 upstream markers.
+    for (const msg of messages) {
+      if ((msg.content[0] as any).type === 'tool_result') (msg as any).cacheBreakpoint = true;
+    }
+    const membrane = new Membrane({ name: 'anthropic' } as any);
+    const pr = build(makeRequest(), messages, true, membrane);
+    expect(markers(pr).messages).toHaveLength(4);
+    expect(warn).toHaveBeenCalledTimes(1);
+    // Warn-once: a second rebuild does not warn again.
+    build(makeRequest(), messages, true, membrane);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('warns again after the rate-limit interval instead of latching for the process lifetime', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const clock = vi.spyOn(Date, 'now');
+    clock.mockReturnValue(1_000_000);
+
+    const messages = turn(3);
+    for (const msg of messages) {
+      if ((msg.content[0] as any).type === 'tool_result') (msg as any).cacheBreakpoint = true;
+    }
+    const membrane = new Membrane({ name: 'anthropic' } as any);
+
+    build(makeRequest(), messages, true, membrane);
+    build(makeRequest(), messages, true, membrane);
+    expect(warn).toHaveBeenCalledTimes(1);
+
+    // A long-lived Membrane must not go permanently quiet about an
+    // over-budget wire: past the interval the condition reports again, and
+    // says how many occurrences it swallowed meanwhile.
+    clock.mockReturnValue(1_000_000 + 61_000);
+    build(makeRequest(), messages, true, membrane);
+    expect(warn).toHaveBeenCalledTimes(2);
+    expect(String(warn.mock.calls[1]![0])).toContain('1 further occurrences suppressed');
+  });
+
+  it('floats from the residuum left after the tools/system fallback on markerless requests', () => {
+    const pr = build(makeRequest(), turn(2, false), true);
+    const m = markers(pr);
+    // Fallback spent 2 (tools + system) → residuum 2 → newest + previous endpoint.
+    expect(m.onTools).toBe(true);
+    expect(m.onSystem).toBe(true);
+    expect(m.messages).toEqual([[last(pr) - 2, 0], [last(pr), 0]]);
+  });
+
+  it('steps back off a trailing thinking block', () => {
+    const messages = turn(1);
+    messages.push({
+      participant: 'Claude',
+      content: [text('partial'), { type: 'thinking' as const, thinking: 'hmm', signature: 'sig' }],
+    } as NormalizedMessage);
+    const pr = build(makeRequest(), messages, true);
+    const m = markers(pr);
+    // Marker lands on the text block, not the thinking block.
+    const finalMarks = m.messages.filter(([mi]) => mi === last(pr));
+    expect(finalMarks).toHaveLength(1);
+    const [, bi] = finalMarks[0]!;
+    expect((pr.messages[last(pr)].content[bi] as any).type).toBe('text');
+  });
+
+  it('stands down entirely when the normalizer synthesized a [pending] tool_result', () => {
+    // Trailing orphan tool_use → normalizer synthesizes its [pending]
+    // result, whose bytes change when the real result lands.
+    const messages = [user('go', true), assistantToolCall('t1')];
+    const pr = build(makeRequest(), messages, true);
+    // Only the kickoff marker; nothing floated at or past the synthetic.
+    expect(markers(pr).messages).toEqual([[0, 0]]);
+  });
+
+  it('respects request-level opt-out', () => {
+    const pr = build(makeRequest({ floatingCacheMarker: false }), turn(1), true);
+    expect(markers(pr).messages).toEqual([[0, 0]]);
+  });
+
+  it('emits no cache_control at all when promptCaching is off', () => {
+    const pr = build(makeRequest({ promptCaching: false }), turn(1), true);
+    const m = markers(pr);
+    expect(m.messages).toEqual([]);
+    expect(m.onTools).toBe(false);
+    expect(m.onSystem).toBe(false);
+  });
+
+  it('counts pre-marked system blocks against the residual budget (never exceeds 4 on the wire)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // System is a block array with one block already carrying cache_control —
+    // invisible to the running message tally, but a real wire marker.
+    const premarkedSystem = [
+      { type: 'text', text: 'You are a test agent.', cache_control: { type: 'ephemeral' } },
+      { type: 'text', text: 'Addendum.' },
+    ] as any;
+    // 3 message markers + pre-marked system = 4 on the wire: no room to float.
+    const full = turn(2);
+    for (const msg of full) {
+      if ((msg.content[0] as any).type === 'tool_result') (msg as any).cacheBreakpoint = true;
+    }
+    const prFull = build(makeRequest({ system: premarkedSystem }), full, true);
+    expect(totalMarkers(prFull)).toBe(4);
+    expect(warn).toHaveBeenCalledTimes(1);
+    // 2 message markers + pre-marked system = 3: exactly one slot left — the
+    // float takes the newest message and stops.
+    const partial = turn(2);
+    (partial[2] as any).cacheBreakpoint = true; // first round's results envelope
+    const prPartial = build(makeRequest({ system: premarkedSystem }), partial, true);
+    expect(totalMarkers(prPartial)).toBe(4);
+    expect(markers(prPartial).messages).toContainEqual([last(prPartial), 0]);
+  });
+
+  it('counts an overlapping block-level + message-level marker once (one physical marker)', () => {
+    // A stale block-level cache_control on the very block the message's
+    // cacheBreakpoint lands on is ONE wire marker, not two. Two such
+    // messages must leave residuum 2, not 0.
+    const staleMarked = (t: string): NormalizedMessage => ({
+      participant: 'User',
+      content: [{ type: 'text', text: t, cache_control: { type: 'ephemeral' } } as any],
+      cacheBreakpoint: true,
+    });
+    // Results envelope whose message-level breakpoint lands on a text block
+    // that already carries stale cache_control — tool pairing stays intact.
+    const overlapResults = (id: string): NormalizedMessage => ({
+      participant: 'User',
+      content: [
+        { type: 'tool_result' as const, toolUseId: id, content: 'ok' },
+        { type: 'text', text: 'operator note', cache_control: { type: 'ephemeral' } } as any,
+      ],
+      cacheBreakpoint: true,
+    });
+    const messages = [staleMarked('do the thing'),
+      assistantToolCall('t1'), overlapResults('t1'),
+      assistantToolCall('t2'), toolResults('t2')];
+    // 2 physical wire markers (the old tally saw 4 and withheld everything).
+    const pr = build(makeRequest(), messages, true);
+    const m = markers(pr);
+    // Float not withheld: newest message marked; previous endpoint already
+    // carries its own marker (dedupe, no slot spent).
+    expect(m.messages).toContainEqual([last(pr), 0]);
+    expect(totalMarkers(pr)).toBeLessThanOrEqual(4);
+  });
+
+  it('floated markers carry the request cacheTtl', () => {
+    const pr = build(makeRequest(), turn(1), true);
+    const [mi, bi] = markers(pr).messages.find(([i]) => i === last(pr))!;
+    expect((pr.messages[mi].content[bi] as any).cache_control).toEqual({ type: 'ephemeral', ttl: '1h' });
+  });
+});

package/src/formatters/anthropic-xml.ts

@@ -34,6 +34,8 @@ import {
   type ToolDefinitionForPrompt,
 } from '../utils/tool-parser.js';
 import { IncrementalXmlParser } from '../utils/stream-parser.js';
+import { clampCacheMarkers } from '../utils/cache-marker-budget.js';
+import { lastCacheableBlockIndex } from './native.js';
 import { isAcceptedImageMediaType, strippedImagePlaceholder } from '../utils/image-media.js';
 
 // ============================================================================
@@ -118,9 +120,13 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
   readonly name = 'anthropic-xml';
   readonly usesPrefill = true;
 
+  /** See PrefillFormatter.configuredToolMode — undefined when the caller left the mode to Membrane. */
+  readonly configuredToolMode: 'xml' | 'native' | undefined;
+
   private config: Required<AnthropicXmlFormatterConfig>;
 
   constructor(config: AnthropicXmlFormatterConfig = {}) {
+    this.configuredToolMode = config.toolMode;
     this.config = {
       toolMode: config.toolMode ?? 'xml',
       toolInjectionMode: config.toolInjectionMode ?? 'conversation',
@@ -149,6 +155,10 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
       hasCacheMarker,
     } = options;
 
+    // Membrane resolves the mode per request and passes it here; the
+    // constructor-time mode is the fallback for direct callers only.
+    const toolMode = options.toolMode ?? this.config.toolMode;
+
     // Build cache_control object (with optional TTL for extended caching)
     const cacheControl: Record<string, unknown> = { type: 'ephemeral' };
     if (cacheTtl) {
@@ -165,42 +175,66 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
     // message continues the same turn, so it must not get a fresh label.
     let lastWasToolResults = false;
 
-    // Track cache markers applied
-    let cacheMarkersApplied = 0;
 
     // Calculate tool injection point
     const totalMessages = messages.length;
     const toolInjectionIndex = Math.max(0, totalMessages - this.config.toolInjectionPosition);
     let toolsInjected = false;
     const hasToolsForConversation =
-      this.config.toolMode === 'xml' &&
+      toolMode === 'xml' &&
       this.config.toolInjectionMode === 'conversation' &&
       tools &&
       tools.length > 0;
     const toolsText = hasToolsForConversation ? this.formatToolsForInjection(tools!) : '';
 
-    // Build system content
-    let systemText = typeof systemPrompt === 'string' ? systemPrompt : '';
-    if (Array.isArray(systemPrompt)) {
-      systemText = systemPrompt
-        .filter((b): b is ContentBlock & { type: 'text' } => b.type === 'text')
-        .map(b => b.text)
-        .join('\n');
-    }
+    // Build system content. A caller-supplied system ARRAY keeps its block
+    // structure and its per-block cache_control: `request.system` explicitly
+    // accepts caller-marked blocks, and flattening them into one text block
+    // discarded every marker the caller placed (three in, one out) — the
+    // caller's stable prefixes then re-paid full input price forever.
+    const callerSystemBlocks = Array.isArray(systemPrompt)
+      ? systemPrompt
+          .filter((b): b is ContentBlock & { type: 'text' } => b.type === 'text')
+          .map((b) => {
+            const callerMarker = (b as unknown as { cache_control?: unknown }).cache_control;
+            const block: Record<string, unknown> = { type: 'text', text: b.text };
+            if (callerMarker) block.cache_control = callerMarker;
+            return block;
+          })
+      : undefined;
+    const systemBlocks = callerSystemBlocks?.length ? callerSystemBlocks : undefined;
+
+    let systemText = typeof systemPrompt === 'string'
+      ? systemPrompt
+      : (systemBlocks?.map((b) => b.text as string).join('\n') ?? '');
 
     // Inject tools into system if configured
-    if (this.config.toolMode === 'xml' && this.config.toolInjectionMode === 'system' && tools?.length) {
+    if (toolMode === 'xml' && this.config.toolInjectionMode === 'system' && tools?.length) {
       const toolsXml = this.formatToolDefinitionsXml(tools);
       systemText = this.injectToolsIntoSystem(systemText, toolsXml);
+      if (systemBlocks) {
+        // Append to the LAST block only — appending to the join would
+        // collapse the array and take every earlier block's marker with it.
+        const tail = systemBlocks[systemBlocks.length - 1]!;
+        tail.text = this.injectToolsIntoSystem(tail.text as string, toolsXml);
+      }
     }
 
     // Build system content with optional cache control
     let systemContent: unknown;
-    if (systemText) {
+    if (systemBlocks) {
+      // The caller's own markers are authoritative: adding one beside them
+      // spends a slot the caller already allocated.
+      const callerMarkedAny = systemBlocks.some((b) => b.cache_control);
+      if (promptCaching && !callerMarkedAny) {
+        const bpIdx = lastCacheableBlockIndex(systemBlocks);
+        if (bpIdx >= 0) systemBlocks[bpIdx]!.cache_control = cacheControl;
+      }
+      systemContent = systemBlocks;
+    } else if (systemText) {
       const systemBlock: Record<string, unknown> = { type: 'text', text: systemText };
       if (promptCaching) {
         systemBlock.cache_control = cacheControl;
-        cacheMarkersApplied++;
       }
       systemContent = [systemBlock];
     }
@@ -210,7 +244,6 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
       const prefixBlock: Record<string, unknown> = { type: 'text', text: contextPrefix };
       if (promptCaching) {
         prefixBlock.cache_control = cacheControl;
-        cacheMarkersApplied++;
       }
       providerMessages.push({
         role: 'assistant',
@@ -276,7 +309,6 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
           const content = currentConversation.join(joiner);
           const contentBlock: Record<string, unknown> = { type: 'text', text: content };
           contentBlock.cache_control = cacheControl;
-          cacheMarkersApplied++;
           providerMessages.push({
             role: 'assistant',
             content: [contentBlock],
@@ -344,7 +376,6 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
         const content = currentConversation.join(joiner);
         const contentBlock: Record<string, unknown> = { type: 'text', text: content };
         contentBlock.cache_control = cacheControl;
-        cacheMarkersApplied++;
         providerMessages.push({
           role: 'assistant',
           content: [contentBlock],
@@ -396,7 +427,6 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
         };
         if (promptCaching) {
           cliSystemBlock.cache_control = cacheControl;
-          cacheMarkersApplied++;
         }
         systemContent = [cliSystemBlock];
         providerMessages.unshift({
@@ -416,10 +446,22 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
     const stopSequences = this.buildStopSequences(messages, assistantParticipant, options);
 
     // Native tools if configured
-    const nativeTools = this.config.toolMode === 'native' && tools?.length
+    const nativeTools = toolMode === 'native' && tools?.length
       ? this.convertToNativeTools(tools)
       : undefined;
 
+    // Budget. Five sites above attach cache_control (system, contextPrefix,
+    // hasCacheMarker flush, cacheBreakpoint flush, CLI-simulation system) and
+    // multiple cacheBreakpoints are documented input, so a prefill turn with
+    // three marked messages reaches five markers — one over Anthropic's hard
+    // limit, which rejects the request outright. Clamping here, once, on the
+    // finished artifacts is the only count that can see all five sites; the
+    // reported tally is that same recount, so it can never drift from the wire.
+    const budget = clampCacheMarkers(
+      { messages: providerMessages, system: systemContent, tools: nativeTools },
+      'anthropic-xml'
+    );
+
     return {
       messages: providerMessages,
       systemContent,
@@ -428,7 +470,7 @@ export class AnthropicXmlFormatter implements PrefillFormatter {
         : undefined,
       stopSequences,
       nativeTools,
-      cacheMarkersApplied,
+      cacheMarkersApplied: budget.total,
     };
   }
 

package/src/formatters/normalize-tool-pairs.ts

@@ -43,6 +43,55 @@ import type { NormalizeEvent } from './types.js';
  */
 export type ProviderBlock = Record<string, unknown> & { type: string };
 
+/**
+ * Does this repair REWRITE prefix bytes, or only re-shape envelopes?
+ *
+ * The two `true` entries are placeholders that get rewritten again the moment
+ * the real pairing arrives — the synthetic `[pending]` result when its
+ * tool_result lands, the textified orphan when its tool_use does — so a cache
+ * breakpoint placed at or past one caches a prefix that is about to change,
+ * poisoning every subsequent read.
+ *
+ * EVERY kind is listed, and the type is a `Record` over the whole union
+ * precisely so the compiler forces that: a new `NormalizeEvent` kind is a
+ * missing-property error here until someone decides which side it falls on.
+ * The previous shape (`[...] satisfies Array<NormalizeEvent['kind']>`) only
+ * checked that the listed kinds were REAL, and a `satisfies` on an array
+ * accepts any subset — so a new prefix-rewriting repair could be added to the
+ * union, never listed, and silently escape the cache gate below while the
+ * comment claimed a compile error that did not exist.
+ *
+ * NOTE FOR COMPOSE: the `stray_tool_result_textified` kind landing from the
+ * stray-orphan lane belongs here as `true` — it rewrites prefix bytes for the
+ * same reason `orphan_tool_result_textified` does.
+ */
+const NORMALIZE_EVENT_REWRITES_PREFIX: Record<NormalizeEvent['kind'], boolean> = {
+  block_re_roled: false,
+  tool_result_hoisted: false,
+  interloper_deferred: false,
+  synthetic_pending_result: true,
+  orphan_tool_result_textified: true,
+  pending_in_flight: false,
+  cache_suppressed_for_synthetic: false,
+  leading_user_synthesized: false,
+};
+
+function deriveKindsThatRewritePrefix(): ReadonlySet<NormalizeEvent['kind']> {
+  const kinds = Object.entries(NORMALIZE_EVENT_REWRITES_PREFIX)
+    .filter(([, rewritesPrefix]) => rewritesPrefix)
+    .map(([kind]) => kind as NormalizeEvent['kind']);
+  return new Set(kinds);
+}
+
+/**
+ * The repairs that rewrite prefix bytes, derived from the exhaustive
+ * classification above. Consumers gate cache placement on this SET rather
+ * than on a single kind, so a normalizer that grows another prefix-rewriting
+ * repair is covered at every cache site by classifying it once.
+ */
+export const PREFIX_REWRITING_NORMALIZE_EVENT_KINDS: ReadonlySet<NormalizeEvent['kind']> =
+  deriveKindsThatRewritePrefix();
+
 export interface NormalizeOptions {
   /** See `BuildOptions.pendingToolCallIds`. */
   pendingToolCallIds?: ReadonlySet<string>;

package/src/formatters/types.ts

@@ -49,6 +49,16 @@ export interface BuildOptions {
   /** Tool definitions to include */
   tools?: ToolDefinition[];
 
+  /**
+   * The tool mode Membrane RESOLVED for this request (see
+   * `Membrane.resolveToolMode`), which already accounts for `request.toolMode`,
+   * the formatter's own configured mode, and provider/formatter derivation.
+   * A formatter that supports both shapes must build for THIS mode; its
+   * constructor-time mode is only the fallback for direct `buildMessages`
+   * callers that resolve nothing.
+   */
+  toolMode?: 'xml' | 'native';
+
   /** Whether thinking is enabled */
   thinking?: { enabled: boolean; budgetTokens?: number };
 
@@ -163,6 +173,18 @@ export interface BuildResult {
   /** Number of cache control markers applied (for Anthropic prompt caching) */
   cacheMarkersApplied?: number;
 
+  /**
+   * Offset into the turn's accumulated assistant text at which the CURRENT
+   * last message of `messages` begins. Zero (or absent) for an ordinary
+   * build: the whole accumulated document is the trailing assistant prefill.
+   *
+   * A split-turn image injection persists its three messages here and moves
+   * this watermark to the image seam, so later continuations replace only
+   * the trailing assistant message and never re-flatten the pre-image text
+   * over the user turn that carries the image.
+   */
+  accumulatedBaseOffset?: number;
+
   /**
    * `false` only when the tool-pair normalizer detected a trailing
    * unmatched tool_use whose id is in `pendingToolCallIds` — i.e. the
@@ -258,6 +280,16 @@ export interface PrefillFormatter {
   /** Whether this formatter uses prefill (vs native pass-through) */
   readonly usesPrefill: boolean;
 
+  /**
+   * The tool mode this formatter instance was EXPLICITLY constructed with, if
+   * any. Read by `Membrane.resolveToolMode` as the fallback under an explicit
+   * `request.toolMode`: a formatter that can build either shape carries its
+   * caller's configured choice here so resolution honors it instead of
+   * re-deriving one from the formatter's name. Left undefined by formatters
+   * that build exactly one shape.
+   */
+  readonly configuredToolMode?: 'xml' | 'native';
+
   // ==========================================================================
   // REQUEST BUILDING
   // ==========================================================================

package/src/index.ts

@@ -24,3 +24,16 @@ export * from './formatters/index.js';
 
 // Context management
 export * from './context/index.js';
+
+// Prompt-cache keepalive (Anthropic 1h cache)
+export {
+  CacheKeepalive,
+  ineligibleReason as cacheKeepaliveIneligibleReason,
+  lineageKey as cacheLineageKey,
+} from './cache-keepalive.js';
+export type {
+  CacheKeepaliveConfig,
+  KeepaliveEvent,
+  KeepaliveLane,
+  KeepaliveSend,
+} from './cache-keepalive.js';