@animalabs/membrane 0.5.79 → 0.5.80

package/src/cache-keepalive.ts

@@ -0,0 +1,385 @@
+// Prompt-cache keepalive for the Anthropic direct API.
+//
+// WHY
+// ---
+// Anthropic prompt cache entries expire on a TTL (1h for `cache_control.ttl:
+// '1h'`), but **reading an entry restarts its clock** — the docs say the cache
+// "is refreshed for no additional cost each time the cached content is used",
+// and the lifetime is measured from the start of the request that *writes or
+// reads* the entry. Verified empirically 2026-08-22: a 5m entry, poked with a
+// `max_tokens: 0` request every 4 minutes, was still served as a pure read at
+// t+12m (2.4x its nominal TTL), every poke reporting create=0 / read=6617.
+//
+// So an idle agent's context can be held warm indefinitely at cache-READ price
+// (0.1x input) instead of paying a cache-WRITE (2x input) on its next wake.
+// For a ~500k-token resident that is the difference between ~$0.50 and ~$10.00
+// per wake. Measured on fable-cm's 11-day log (2026-08-11..22): 49.7M tokens of
+// cache_creation occurred on turns that followed a >1h idle gap — $944 of write
+// premium that a keepalive converts into ~$308 of reads.
+//
+// HOW
+// ---
+// We snapshot the exact wire request of each real call and replay it verbatim
+// with `max_tokens: 0`, which runs prefill only: content `[]`, stop_reason
+// `max_tokens`, zero output tokens billed, and the cache entry refreshed.
+//
+// ⚠️ THE REPLAY MUST BE BYTE-IDENTICAL ABOVE THE LAST BREAKPOINT.
+// Prompt caching is a prefix match, and the API's invalidation hierarchy means
+// some innocent-looking "normalizations" silently turn a 0.1x read into a 2x
+// write. Verified the hard way on 2026-08-22: replaying with
+// `thinking: {type:'disabled'}` instead of the request's own
+// `thinking: {type:'adaptive'}` produced create=5081 / read=0 — a full rewrite,
+// reported as a perfectly successful call. That failure is invisible unless you
+// check the usage numbers, so `refresh()` below checks them on every single
+// poke and disables the lineage rather than quietly burning 20x.
+//
+// Hence: we never rewrite the snapshot. We change `max_tokens` (not part of the
+// cache key) and drop `stream` (a transport concern), and nothing else. Any
+// request shape that can't tolerate `max_tokens: 0` is skipped outright rather
+// than "fixed up" — see `ineligibleReason()`.
+
+import { createHash } from 'node:crypto';
+
+/** Minimal shape we need back from a keepalive send. */
+export interface KeepaliveUsage {
+  // The SDK types these as `number | null`, and null is meaningfully different
+  // from 0 here: null means the field was absent (we learned nothing), 0 means
+  // the API told us nothing was read. Both are treated as "not a read" below.
+  cache_read_input_tokens?: number | null;
+  cache_creation_input_tokens?: number | null;
+}
+
+export type KeepaliveSend = (
+  wire: Record<string, unknown>,
+  headers: Record<string, string> | undefined,
+) => Promise<{ usage?: KeepaliveUsage }>;
+
+export type KeepaliveLane = 'stream' | 'complete';
+
+export type KeepaliveEvent =
+  | { type: 'refreshed'; key: string; lane: KeepaliveLane; readTokens: number; idleMs: number }
+  | { type: 'ineffective'; key: string; reason: string; readTokens: number; writeTokens: number }
+  | { type: 'skipped'; key: string; reason: string }
+  | { type: 'error'; key: string; error: string; consecutive: number }
+  | { type: 'disabled'; reason: string }
+  | { type: 'expired'; key: string; idleMs: number };
+
+export interface CacheKeepaliveConfig {
+  /** Master switch. Default true. */
+  enabled?: boolean;
+  /**
+   * Stop refreshing once the last REAL request is this old. Keepalive pokes do
+   * not extend this — otherwise an agent that never speaks again would be kept
+   * warm forever. Default 24h.
+   */
+  maxIdleMs?: number;
+  /**
+   * Refresh once the entry hasn't been touched for this long. Must be < the
+   * cache TTL, with margin: the TTL clock starts at the *start* of the request,
+   * and a long streaming turn can itself eat minutes. Default 45m against a 1h
+   * TTL leaves 15m of headroom.
+   */
+  refreshAfterMs?: number;
+  /** Timer cadence. Default 5m. */
+  checkIntervalMs?: number;
+  /**
+   * Which lanes to keep warm. Default ['stream'] — the primary/voice lane.
+   * The aux ('complete') lane is measured to do no prompt caching at all today
+   * (fable-cm: 382 aux calls, every one create=0/read=0), so warming it would
+   * poke a cache entry that does not exist.
+   */
+  lanes?: KeepaliveLane[];
+  /** LRU cap on tracked lineages, to bound memory. Each holds a full wire
+   *  request (~1.5MB for a 500k-token resident). Default 4. */
+  maxLineages?: number;
+  /** Consecutive send failures before the whole keepalive disables itself. */
+  maxConsecutiveErrors?: number;
+  /**
+   * How many times a lineage may come back as a WRITE instead of a read before
+   * we stop poking it. A lineage whose prefix churns every turn cannot be kept
+   * warm, and paying 2x to discover that repeatedly is the worst outcome.
+   */
+  maxIneffective?: number;
+  onEvent?: (event: KeepaliveEvent) => void;
+}
+
+interface Lineage {
+  wire: Record<string, unknown>;
+  headers: Record<string, string> | undefined;
+  lane: KeepaliveLane;
+  /** Last real (non-keepalive) request. Bounds the keepalive window. */
+  lastRealAt: number;
+  /** Last time the entry was touched by anything, real or keepalive. */
+  lastTouchAt: number;
+  ineffective: number;
+}
+
+const DEFAULTS = {
+  enabled: true,
+  maxIdleMs: 24 * 60 * 60 * 1000,
+  refreshAfterMs: 45 * 60 * 1000,
+  checkIntervalMs: 5 * 60 * 1000,
+  lanes: ['stream'] as KeepaliveLane[],
+  maxLineages: 4,
+  maxConsecutiveErrors: 3,
+  maxIneffective: 2,
+};
+
+/**
+ * Reasons a request shape cannot be safely replayed as `max_tokens: 0`.
+ *
+ * Each of these is either rejected outright by the API, or — worse — would
+ * require editing the request in a way that moves the cache-invalidation
+ * boundary. Skipping is always cheaper than guessing.
+ */
+export function ineligibleReason(wire: Record<string, unknown>): string | null {
+  const thinking = wire.thinking as { type?: string } | undefined;
+  // `max_tokens: 0` is rejected with thinking.type 'enabled', and we must not
+  // "fix" that by disabling thinking — toggling thinking invalidates the
+  // messages cache (measured: create=5081/read=0).
+  if (thinking?.type === 'enabled') return 'legacy-thinking-budget';
+
+  const toolChoice = wire.tool_choice as { type?: string } | undefined;
+  // Rejected with max_tokens: 0, and tool_choice changes invalidate the
+  // messages cache, so we cannot substitute 'auto'.
+  if (toolChoice?.type === 'tool' || toolChoice?.type === 'any') return 'forced-tool-choice';
+
+  const outputConfig = wire.output_config as { format?: unknown } | undefined;
+  if (outputConfig?.format) return 'structured-output';
+
+  // Only the 1h cache is worth a background timer. A 5m entry would need a poke
+  // every ~4 minutes; at 0.1x of a large prefix that costs more than it saves.
+  const markers = scanCacheMarkers(wire);
+  if (!markers.any) return 'no-cache-breakpoint';
+  if (!markers.oneHour) return 'no-1h-breakpoint';
+
+  return null;
+}
+
+/**
+ * Walk system + tools + messages for cache_control markers.
+ *
+ * This runs on every outbound request, and `messages` on a large resident is
+ * megabytes of blocks — so it short-circuits the moment it finds a 1h marker,
+ * which is the answer in the overwhelmingly common case.
+ */
+function scanCacheMarkers(wire: Record<string, unknown>): { any: boolean; oneHour: boolean } {
+  let any = false;
+  let oneHour = false;
+
+  const visit = (node: unknown): void => {
+    if (oneHour) return; // nothing left to learn
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        visit(item);
+        if (oneHour) return;
+      }
+      return;
+    }
+    if (!node || typeof node !== 'object') return;
+    const obj = node as Record<string, unknown>;
+    const cc = obj.cache_control as { ttl?: string } | undefined;
+    if (cc && typeof cc === 'object') {
+      any = true;
+      if ((cc.ttl ?? '5m') === '1h') {
+        oneHour = true;
+        return;
+      }
+    }
+    if (obj.content) visit(obj.content);
+  };
+
+  visit(wire.system);
+  visit(wire.tools);
+  visit(wire.messages);
+  return { any, oneHour };
+}
+
+/**
+ * Identity of a cache lineage: model + system + tools. This is exactly the root
+ * of the cached prefix, so two agents in one process, or an agent's primary vs
+ * aux lane, land in different buckets automatically.
+ */
+export function lineageKey(wire: Record<string, unknown>): string {
+  const h = createHash('sha256');
+  h.update(String(wire.model ?? ''));
+  h.update('');
+  h.update(JSON.stringify(wire.system ?? null));
+  h.update('');
+  h.update(JSON.stringify(wire.tools ?? null));
+  return h.digest('hex').slice(0, 16);
+}
+
+export class CacheKeepalive {
+  private lineages = new Map<string, Lineage>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private ticking = false;
+  private consecutiveErrors = 0;
+  private stopped = false;
+  private readonly cfg: Required<Omit<CacheKeepaliveConfig, 'onEvent'>> & {
+    onEvent?: (event: KeepaliveEvent) => void;
+  };
+
+  constructor(private readonly send: KeepaliveSend, config: CacheKeepaliveConfig = {}) {
+    this.cfg = { ...DEFAULTS, ...config };
+    if (!this.cfg.enabled) this.stopped = true;
+  }
+
+  /** Record a real outbound request. Cheap; called on every LLM call. */
+  record(
+    wire: Record<string, unknown>,
+    headers: Record<string, string> | undefined,
+    lane: KeepaliveLane,
+  ): void {
+    if (this.stopped) return;
+    if (!this.cfg.lanes.includes(lane)) return;
+
+    const reason = ineligibleReason(wire);
+    const key = lineageKey(wire);
+    if (reason) {
+      // Drop any stale snapshot: the shape changed and is no longer warmable.
+      if (this.lineages.delete(key)) this.emit({ type: 'skipped', key, reason });
+      return;
+    }
+
+    const now = Date.now();
+    const existing = this.lineages.get(key);
+    // Re-insert to refresh LRU position.
+    this.lineages.delete(key);
+    this.lineages.set(key, {
+      wire,
+      headers,
+      lane,
+      lastRealAt: now,
+      lastTouchAt: now,
+      ineffective: existing?.ineffective ?? 0,
+    });
+
+    while (this.lineages.size > this.cfg.maxLineages) {
+      const oldest = this.lineages.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.lineages.delete(oldest);
+    }
+
+    this.ensureTimer();
+  }
+
+  private ensureTimer(): void {
+    if (this.timer || this.stopped) return;
+    this.timer = setInterval(() => { void this.tick(); }, this.cfg.checkIntervalMs);
+    // Never hold the process open for a cache poke.
+    (this.timer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  private async tick(): Promise<void> {
+    if (this.ticking || this.stopped) return;
+    this.ticking = true;
+    try {
+      const now = Date.now();
+      for (const [key, lin] of [...this.lineages]) {
+        if (this.stopped) break;
+        // The keepalive window is measured from the last REAL request, so pokes
+        // can never extend their own mandate.
+        if (now - lin.lastRealAt >= this.cfg.maxIdleMs) {
+          this.lineages.delete(key);
+          this.emit({ type: 'expired', key, idleMs: now - lin.lastRealAt });
+          continue;
+        }
+        // Idle-gated, not blind: if real traffic already touched the entry
+        // inside the window, it refreshed the TTL for free and we do nothing.
+        // This is what keeps a busy agent's keepalive cost at ~zero.
+        if (now - lin.lastTouchAt < this.cfg.refreshAfterMs) continue;
+        await this.refresh(key, lin);
+      }
+    } finally {
+      this.ticking = false;
+    }
+  }
+
+  private async refresh(key: string, lin: Lineage): Promise<void> {
+    // Only max_tokens (not part of the cache key) and stream (transport) differ
+    // from the recorded request. Nothing else is touched — see file header.
+    const payload: Record<string, unknown> = { ...lin.wire, max_tokens: 0 };
+    delete payload.stream;
+
+    const idleMs = Date.now() - lin.lastTouchAt;
+    try {
+      const res = await this.send(payload, lin.headers);
+      this.consecutiveErrors = 0;
+
+      const read = res.usage?.cache_read_input_tokens ?? 0;
+      const wrote = res.usage?.cache_creation_input_tokens ?? 0;
+
+      // The self-check. A keepalive that WRITES has not kept anything alive —
+      // it paid 2x to create a fresh entry, which is the exact failure this
+      // whole module exists to avoid. Never assume the poke worked.
+      if (read <= 0 || wrote > 0) {
+        lin.ineffective += 1;
+        this.emit({
+          type: 'ineffective',
+          key,
+          reason: wrote > 0 ? 'wrote-instead-of-read' : 'no-cache-read',
+          readTokens: read,
+          writeTokens: wrote,
+        });
+        if (lin.ineffective >= this.cfg.maxIneffective) {
+          this.lineages.delete(key);
+        } else {
+          lin.lastTouchAt = Date.now();
+        }
+        return;
+      }
+
+      lin.ineffective = 0;
+      lin.lastTouchAt = Date.now();
+      this.emit({ type: 'refreshed', key, lane: lin.lane, readTokens: read, idleMs });
+    } catch (err) {
+      this.consecutiveErrors += 1;
+      const message = err instanceof Error ? err.message : String(err);
+      this.emit({ type: 'error', key, error: message, consecutive: this.consecutiveErrors });
+
+      // Back this lineage off immediately rather than retrying on the next tick.
+      lin.lastTouchAt = Date.now();
+
+      // Hard breaker. A background loop that keeps firing failing requests is
+      // how fable-cm produced 1033 `400 invalid_request_error` rows in 3h on
+      // 2026-08-21 — the exact error class that also trips the agent's
+      // poison-history breaker. A keepalive must never be that loop.
+      if (this.consecutiveErrors >= this.cfg.maxConsecutiveErrors) {
+        this.stop();
+        this.emit({
+          type: 'disabled',
+          reason: `${this.consecutiveErrors} consecutive keepalive failures; last: ${message}`,
+        });
+      }
+    }
+  }
+
+  private emit(event: KeepaliveEvent): void {
+    try {
+      this.cfg.onEvent?.(event);
+    } catch {
+      // Observability must never break the keepalive, nor the caller.
+    }
+  }
+
+  /** Snapshot for operators / tests. */
+  getStatus(): Array<{ key: string; lane: KeepaliveLane; idleMs: number; realIdleMs: number }> {
+    const now = Date.now();
+    return [...this.lineages].map(([key, l]) => ({
+      key,
+      lane: l.lane,
+      idleMs: now - l.lastTouchAt,
+      realIdleMs: now - l.lastRealAt,
+    }));
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.lineages.clear();
+  }
+}

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

@@ -0,0 +1,261 @@
+/**
+ * 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('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/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';