agentfootprint 6.44.0 → 6.45.0

package/dist/esm/cache/applyCachePolicy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * applyCachePolicy — internal helper for injection factories.
+ *
+ * Each factory (`defineSkill`, `defineSteering`, `defineFact`,
+ * `defineInstruction`, `defineMemory`) calls this to merge the
+ * consumer-supplied `cache` option with the flavor-specific default.
+ * The merged policy lands in `Injection.metadata.cache` for the
+ * CacheDecision subflow (Phase 4) to read back.
+ *
+ * Why it lives in src/cache/ (not co-located with each factory):
+ *   - Single source of truth for per-flavor defaults
+ *   - Tests for the defaults live in one place (test/cache/)
+ *   - Adding a new factory means adding one entry to the map below;
+ *     not duplicating the default-resolution logic five times
+ */
+import type { CachePolicy } from './types.js';
+/**
+ * Per-flavor default `cache` values when consumer doesn't specify.
+ * These match the documentation in `CachePolicy`'s JSDoc — keep
+ * synchronized.
+ */
+declare const FLAVOR_DEFAULTS: Readonly<Record<string, CachePolicy>>;
+/**
+ * Resolve the effective `cache` policy for an injection.
+ *
+ * @param flavor - The injection flavor (drives the default if `consumerValue` undefined)
+ * @param consumerValue - What the consumer wrote in `cache:` (or undefined)
+ * @returns The effective CachePolicy. Always defined.
+ */
+export declare function resolveCachePolicy(flavor: keyof typeof FLAVOR_DEFAULTS | string, consumerValue: CachePolicy | undefined): CachePolicy;
+/**
+ * Read-only access to the per-flavor default table. Exported for
+ * tests asserting the documented defaults are wired correctly. Not
+ * intended for runtime use — callers should use `resolveCachePolicy`.
+ */
+export declare function getFlavorDefault(flavor: string): CachePolicy;
+export {};

package/dist/esm/cache/cacheRecorder.d.ts

@@ -0,0 +1,85 @@
+/**
+ * cacheRecorder() — observability for the v2.6 cache layer.
+ *
+ * Subscribes to:
+ *   - `FlowRecorder.onDecision` — captures CacheGate routing decisions
+ *     (apply-markers / no-markers + the rule that fired + evidence
+ *     from `decide()`). Read directly from `event.evidence.rules[matched]`
+ *     since footprintjs already auto-captures predicate `inputs[]`.
+ *   - `agentfootprint.stream.llm_end` events — read provider's `usage`
+ *     and call the agent's CacheStrategy.extractMetrics() to normalize
+ *     into CacheMetrics (cacheReadTokens / cacheWriteTokens / fresh).
+ *
+ * Produces:
+ *   - per-iteration `agentfootprint.cache.applied` events (markers
+ *     applied this iter or empty if skipped) — for Lens trace
+ *   - per-iteration `agentfootprint.cache.metrics` events (hit/write
+ *     token counts + estimated dollars via PricingTable) — for
+ *     dashboards
+ *   - a turn-end summary printable via `recorder.report()` —
+ *     numeric tally plus dollars saved
+ *
+ * v2.6 LIMITATION: doesn't yet write `scope.recentHitRate` back into
+ * agent state. CacheGate's hit-rate-floor rule won't fire automatically;
+ * consumers can manually wire feedback via `Agent.create(...).attach(rec)`.
+ * Full feedback loop deferred to v2.7 (needs an agent-side accessor
+ * convention since recorders don't normally write to scope).
+ */
+import type { CombinedRecorder } from 'footprintjs';
+import type { CacheMetrics, CacheStrategy } from './types.js';
+import type { PricingTable } from '../adapters/types.js';
+interface PerIterEntry {
+    readonly iteration: number;
+    readonly branch: 'apply-markers' | 'no-markers';
+    readonly rule?: string;
+    readonly metrics?: CacheMetrics;
+    readonly dollarsSpent: number;
+    readonly dollarsSavedVsNoCache: number;
+}
+interface CacheReportSummary {
+    readonly totalIterations: number;
+    readonly applyMarkersIterations: number;
+    readonly noMarkersIterations: number;
+    readonly cacheReadTokensTotal: number;
+    readonly cacheWriteTokensTotal: number;
+    readonly freshInputTokensTotal: number;
+    readonly hitRate: number;
+    readonly estimatedDollarsSpent: number;
+    readonly estimatedDollarsSavedVsNoCache: number;
+    readonly perIter: readonly PerIterEntry[];
+}
+export interface CacheRecorderOptions {
+    /**
+     * The agent's CacheStrategy. Required for `extractMetrics` —
+     * normalizes provider-specific `usage` shapes into CacheMetrics.
+     * If not provided, recorder logs the raw usage and skips dollar math.
+     */
+    readonly strategy?: CacheStrategy;
+    /**
+     * PricingTable for dollar estimates. Falls back to token-count-only
+     * reporting when omitted. Looks up `'input'` / `'cacheRead'` /
+     * `'cacheWrite'` token kinds (PricingTable already supports these
+     * as of v2.5).
+     */
+    readonly pricing?: PricingTable;
+    /**
+     * Model id for pricing lookup. Defaults to a placeholder; set to
+     * the actual model the agent is using for accurate dollar math.
+     */
+    readonly model?: string;
+}
+export interface CacheRecorderHandle extends CombinedRecorder {
+    /**
+     * Build a per-turn report. Call after `agent.run()` completes.
+     * Returns a frozen snapshot — recorder keeps accumulating but the
+     * report you held is stable.
+     */
+    report(): CacheReportSummary;
+    /**
+     * Reset accumulated state. Call between turns if you want
+     * per-turn rather than per-session reporting.
+     */
+    reset(): void;
+}
+export declare function cacheRecorder(options?: CacheRecorderOptions): CacheRecorderHandle;
+export {};

package/dist/esm/cache/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * agentfootprint/cache — public surface for the cache layer (v2.6+).
+ *
+ * Importing this module side-effect-registers every built-in cache
+ * strategy in the registry. The agentfootprint main barrel imports
+ * from here so consumers get the registered strategies without
+ * needing to know they exist.
+ *
+ * Strategies registered as of v2.6:
+ *   - NoOp (wildcard '*' fallback) — always available, registered by
+ *     the registry module itself
+ *   - AnthropicCacheStrategy ('anthropic', 'browser-anthropic')
+ *
+ * Future strategies (Phase 8+):
+ *   - OpenAICacheStrategy
+ *   - BedrockCacheStrategy
+ *   - GeminiCacheStrategy (v2.7+, async handle-based)
+ *
+ * Public types (re-exported for consumers):
+ *   - CachePolicy, CacheMarker, CacheStrategy, CacheCapabilities,
+ *     CacheMetrics, CachePolicyContext, CacheStrategyContext
+ */
+import './strategies/AnthropicCacheStrategy.js';
+import './strategies/OpenAICacheStrategy.js';
+import './strategies/BedrockCacheStrategy.js';
+export type { CachePolicy, CachePolicyContext, CacheMarker, CacheStrategy, CacheStrategyContext, CacheCapabilities, CacheMetrics, } from './types.js';
+export { getDefaultCacheStrategy, registerCacheStrategy, listRegisteredStrategies, } from './strategyRegistry.js';
+export { NoOpCacheStrategy } from './strategies/NoOpCacheStrategy.js';
+export { AnthropicCacheStrategy } from './strategies/AnthropicCacheStrategy.js';
+export { OpenAICacheStrategy } from './strategies/OpenAICacheStrategy.js';
+export { BedrockCacheStrategy } from './strategies/BedrockCacheStrategy.js';
+export { cacheRecorder } from './cacheRecorder.js';
+export type { CacheRecorderOptions, CacheRecorderHandle } from './cacheRecorder.js';

package/dist/esm/cache/strategies/AnthropicCacheStrategy.d.ts

@@ -0,0 +1,38 @@
+/**
+ * AnthropicCacheStrategy — translates agnostic CacheMarker[] to
+ * Anthropic API's `cache_control: { type: 'ephemeral' }` markers.
+ *
+ * Anthropic-specific behaviors honored:
+ *   - **4-marker limit**: Anthropic allows ≤4 cache breakpoints per
+ *     request. Strategy clamps oversize candidate sets, keeping the
+ *     first 4 in slot order.
+ *   - **TTL mapping**: 'short' → default 5min ephemeral; 'long' →
+ *     `ttl: '1h'` (1-hour beta).
+ *   - **Provider-side hashing**: this strategy doesn't hash — Anthropic
+ *     keys cache by exact byte prefix server-side. We don't need
+ *     content hashes for the v2.6 surface; reserved for v2.7+ if a
+ *     pre-flight cache-warm-check API ships.
+ *
+ * What this strategy DOES vs DOESN'T do:
+ *   - DOES: clamp markers, attach to LLMRequest.cacheMarkers,
+ *     extract metrics from response.usage
+ *   - DOES NOT: rewrite the wire body. The provider
+ *     (BrowserAnthropicProvider) reads `cacheMarkers` and applies
+ *     `cache_control` blocks during body construction. Separation of
+ *     concerns: strategy decides WHAT to cache; provider knows HOW
+ *     to encode on its specific wire.
+ *
+ * Auto-registers in the strategy registry on module import for
+ * provider names: 'anthropic', 'browser-anthropic'.
+ */
+import type { CacheCapabilities, CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext } from '../types.js';
+import type { LLMRequest } from '../../adapters/types.js';
+export declare class AnthropicCacheStrategy implements CacheStrategy {
+    readonly providerName = "anthropic";
+    readonly capabilities: CacheCapabilities;
+    prepareRequest(req: LLMRequest, candidates: readonly CacheMarker[], ctx: CacheStrategyContext): Promise<{
+        readonly request: LLMRequest;
+        readonly markersApplied: readonly CacheMarker[];
+    }>;
+    extractMetrics(usage: unknown): CacheMetrics | undefined;
+}

package/dist/esm/cache/strategies/BedrockCacheStrategy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * BedrockCacheStrategy — model-aware strategy for AWS Bedrock.
+ *
+ * Bedrock hosts multiple model families. Cache support varies:
+ *   - Claude on Bedrock → identical mechanics to direct Anthropic
+ *     (`cache_control: { type: 'ephemeral' }` markers, 4-marker
+ *     limit). Strategy delegates to Anthropic-shaped behavior.
+ *   - Llama / Mistral / Cohere on Bedrock → no cache support today
+ *     (as of 2026-04-30). Strategy passes through, returns no metrics.
+ *
+ * Auto-detection: inspects `req.model` to decide. Claude model IDs
+ * start with `'anthropic.claude'` on Bedrock (e.g.,
+ * `anthropic.claude-3-5-sonnet-20240620-v1:0`).
+ *
+ * Auto-registers under provider name `'bedrock'`.
+ *
+ * Per the Phase 1 review (Reviewer 6 — Provider SDK expert): for
+ * non-Claude Bedrock models the strategy reports `enabled: false` in
+ * its capabilities so the CacheDecision subflow can short-circuit
+ * marker emission (potential v2.7 optimization). Today markers still
+ * emit and we drop them silently in prepareRequest.
+ */
+import type { CacheCapabilities, CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext } from '../types.js';
+import type { LLMRequest } from '../../adapters/types.js';
+export declare class BedrockCacheStrategy implements CacheStrategy {
+    readonly providerName = "bedrock";
+    readonly capabilities: CacheCapabilities;
+    prepareRequest(req: LLMRequest, candidates: readonly CacheMarker[], ctx: CacheStrategyContext): Promise<{
+        readonly request: LLMRequest;
+        readonly markersApplied: readonly CacheMarker[];
+    }>;
+    extractMetrics(usage: unknown): CacheMetrics | undefined;
+}

package/dist/esm/cache/strategies/NoOpCacheStrategy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * NoOpCacheStrategy — fallback strategy for providers without cache
+ * support (Mock, unknown providers, intentional opt-out).
+ *
+ * Returns the request unchanged; reports no metrics. The
+ * `capabilities.enabled` flag is `false` so the CacheDecision subflow
+ * could choose to skip emitting markers entirely (potential v2.7
+ * optimization), though current Phase 4+5 always emit markers and
+ * let the strategy decide what to do with them.
+ *
+ * Always-available default. Registered against the special wildcard
+ * `'*'` so any unrecognized provider name falls back to NoOp.
+ */
+import type { CacheCapabilities, CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext } from '../types.js';
+import type { LLMRequest } from '../../adapters/types.js';
+export declare class NoOpCacheStrategy implements CacheStrategy {
+    /**
+     * Wildcard provider name. The strategy registry treats this as the
+     * fallback for any provider that doesn't have a specific strategy
+     * registered.
+     */
+    readonly providerName = "*";
+    readonly capabilities: CacheCapabilities;
+    prepareRequest(req: LLMRequest, _candidates: readonly CacheMarker[], _ctx: CacheStrategyContext): Promise<{
+        readonly request: LLMRequest;
+        readonly markersApplied: readonly CacheMarker[];
+    }>;
+    extractMetrics(_usage: unknown): CacheMetrics | undefined;
+}

package/dist/esm/cache/strategies/OpenAICacheStrategy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenAICacheStrategy — metrics-only strategy for OpenAI providers.
+ *
+ * OpenAI auto-caches request prefixes ≥1024 tokens at 50% off.
+ * No client-side opt-in markers needed (and no way to influence
+ * cache behavior from the client). The strategy:
+ *
+ *   - **prepareRequest**: pass-through. We can't tell OpenAI what
+ *     to cache; they decide automatically. Markers are silently
+ *     dropped (the 80% case for OpenAI consumers is "I declared
+ *     cache: 'always' for my injections" — that's still meaningful
+ *     because (a) it's portable across providers, (b) for OpenAI
+ *     the auto-cache may still hit on stable prefixes regardless).
+ *   - **extractMetrics**: reads `prompt_tokens_details.cached_tokens`
+ *     from OpenAI's usage response so cacheRecorder can surface
+ *     hit rates / dollar savings.
+ *
+ * Auto-registers on module import for: 'openai', 'browser-openai'.
+ *
+ * Documentation note for consumers (Phase 12 docs): the `cache:`
+ * directive on injection definitions is portable but has NO LOCAL
+ * EFFECT on OpenAI runs — the provider auto-caches based on prefix
+ * length. The directive still ships correctly with the agent and
+ * lights up automatically when you swap to Anthropic / Bedrock.
+ */
+import type { CacheCapabilities, CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext } from '../types.js';
+import type { LLMRequest } from '../../adapters/types.js';
+export declare class OpenAICacheStrategy implements CacheStrategy {
+    readonly providerName = "openai";
+    readonly capabilities: CacheCapabilities;
+    prepareRequest(req: LLMRequest, _candidates: readonly CacheMarker[], _ctx: CacheStrategyContext): Promise<{
+        readonly request: LLMRequest;
+        readonly markersApplied: readonly CacheMarker[];
+    }>;
+    extractMetrics(usage: unknown): CacheMetrics | undefined;
+}

package/dist/esm/cache/strategyRegistry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Strategy registry — maps provider name → CacheStrategy.
+ *
+ * Auto-resolution at agent build time: agentfootprint inspects
+ * `provider.name` and looks up the registered strategy for that
+ * name. Falls back to `NoOpCacheStrategy` (registered under wildcard
+ * `'*'`) when the provider isn't recognized.
+ *
+ * Phases shipping registered strategies:
+ *   - v2.6 Phase 6 (this phase): NoOp
+ *   - v2.6 Phase 7: AnthropicCacheStrategy ('anthropic',
+ *     'browser-anthropic')
+ *   - v2.6 Phase 8: OpenAICacheStrategy ('openai', 'browser-openai'),
+ *     BedrockCacheStrategy ('bedrock')
+ *   - v2.7+ : GeminiCacheStrategy (handle-based, async, deferred)
+ *
+ * Consumers can register their own strategy via
+ * `registerCacheStrategy(strategy)`. Useful for in-house LLM proxies
+ * or test mocks.
+ */
+import type { CacheStrategy } from './types.js';
+/**
+ * Look up a CacheStrategy by provider name. Falls back to the
+ * wildcard NoOp strategy if no match.
+ *
+ * Lookup is case-insensitive on the provider name.
+ */
+export declare function getDefaultCacheStrategy(providerName: string): CacheStrategy;
+/**
+ * Register (or replace) a strategy for a provider name. Called by
+ * strategy modules (v2.6 Phase 7+) at module load OR by consumers
+ * needing a custom backend. Replacing an existing strategy is allowed
+ * — the most-recent registration wins.
+ */
+export declare function registerCacheStrategy(strategy: CacheStrategy): void;
+/**
+ * Read-only view of registered strategy names. Useful for diagnostics
+ * (e.g., logging "we have strategies for: anthropic, openai, *").
+ */
+export declare function listRegisteredStrategies(): readonly string[];
+/**
+ * Internal helper for tests: reset the registry to the default
+ * (wildcard → NoOp only). Not exported from the public barrel.
+ */
+export declare function _resetRegistryForTests(): void;

package/dist/esm/cache/types.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Cache layer — public types.
+ *
+ * Three layers, each with one responsibility:
+ *
+ *   1. CONSUMER DSL — `CachePolicy` field on every injection factory.
+ *      Declarative, like GraphQL schema input. Says WHAT should be
+ *      cacheable. Examples: `cache: 'always'`, `cache: 'while-active'`.
+ *
+ *   2. AGNOSTIC MARKERS — `CacheMarker[]` produced by the
+ *      `CacheDecision` subflow at runtime. Provider-independent
+ *      identification of "cacheable prefix in field X up to index Y".
+ *
+ *   3. PROVIDER STRATEGY — one `CacheStrategy` implementation per
+ *      provider (Anthropic / OpenAI / Bedrock / NoOp). Translates
+ *      agnostic markers to provider-specific wire format AND extracts
+ *      cache metrics from the provider's response.
+ *
+ * The interfaces are read-only / immutable by convention. Strategies
+ * MUST be stateless across runs; per-run state lives in the
+ * `CacheStrategyContext` passed into `prepareRequest`.
+ */
+import type { LLMRequest } from '../adapters/types.js';
+/**
+ * `cache:` field shape on every injection factory.
+ *
+ * Defaults per factory (chosen so `cache:` is rarely written explicitly):
+ * - `defineSteering` → `'always'`
+ * - `defineFact` → `'always'`
+ * - `defineSkill` → `'while-active'`
+ * - `defineInstruction` → `'never'`
+ * - `defineMemory` → `'while-active'`
+ *
+ * Variants:
+ * - `'always'` — cache whenever this injection is in `activeInjections`.
+ *   Sugar for `{ until: () => false }`. The most aggressive form.
+ * - `'never'` — never cache. Use for volatile content (rule predicates,
+ *   on-tool-return injections, content with timestamps or per-request IDs).
+ *   Sugar for `{ until: () => true }` — i.e., always-invalidated.
+ * - `'while-active'` — cache while this injection appears in
+ *   `activeInjections[]` for the current iteration. The cache invalidates
+ *   the moment the injection becomes inactive (predicate returns `false`,
+ *   skill deactivates, fact gets removed). Skill default; intuitive
+ *   meaning regardless of factory.
+ * - `{ until: ctx => ... }` — conditional invalidation; cached UNTIL
+ *   the predicate returns `true`. The predicate runs every iteration;
+ *   if it flips to `true`, the cache prefix is rebuilt.
+ *
+ * **Composition**: the four sentinel forms cover most cases. For
+ * complex composition (e.g., "cache always EXCEPT after iter 5"), use
+ * the `{ until: ... }` form directly:
+ *
+ * ```ts
+ * // Stable for the first 5 iters, then flush:
+ * cache: { until: ctx => ctx.iteration > 5 }
+ *
+ * // Cache while iter > 1 (skip caching on the very first call):
+ * cache: { until: ctx => ctx.iteration <= 1 }
+ *
+ * // Invalidate when cumulative spend exceeds budget:
+ * cache: { until: ctx => ctx.cumulativeInputTokens > 50_000 }
+ * ```
+ *
+ * The predicate is the DSL's escape hatch — Turing-complete by design.
+ * 80% of consumers stick with the three sentinel strings; power users
+ * compose freely via `{ until }`.
+ */
+export type CachePolicy = 'always' | 'never' | 'while-active' | {
+    readonly until: (ctx: CachePolicyContext) => boolean;
+};
+/**
+ * Context passed to a `CachePolicy.until` predicate. Read-only
+ * snapshot; predicates must be pure.
+ *
+ * Mirrors `InjectionContext` but trimmed to the fields a cache
+ * predicate would meaningfully inspect.
+ */
+export interface CachePolicyContext {
+    /** Current ReAct iteration (1-based). */
+    readonly iteration: number;
+    /** Number of iterations remaining (= maxIterations - iteration). */
+    readonly iterationsRemaining: number;
+    /** The current user message that started this turn. */
+    readonly userMessage: string;
+    /** Last tool that returned, if any. */
+    readonly lastToolName?: string;
+    /** Cumulative input tokens so far this run. */
+    readonly cumulativeInputTokens: number;
+}
+/**
+ * Provider-independent identification of a cacheable prefix.
+ *
+ * The CacheDecision subflow walks `activeInjections` and emits one
+ * marker per slot whose entries from index 0..boundaryIndex form a
+ * stable, contiguous, cacheable prefix.
+ *
+ * `field` is the request field this marker targets. Each provider
+ * strategy translates it differently:
+ * - `'system'` → Anthropic puts `cache_control` on a system block
+ * - `'tools'` → Anthropic puts `cache_control` on a tools array entry
+ * - `'messages'` → Anthropic puts `cache_control` on the LAST content
+ *   block of the LAST message (Anthropic-specific positional rule)
+ */
+export interface CacheMarker {
+    readonly field: 'system' | 'tools' | 'messages';
+    /**
+     * 0-based index of the LAST element in `field` to include in the
+     * cached prefix. Everything from index 0..boundaryIndex (inclusive)
+     * is cacheable.
+     *
+     * **Provider note for `field: 'messages'`**: Anthropic's `cache_control`
+     * on `messages` is positional — it only takes effect on the LAST
+     * content block of the LAST message in the cacheable prefix. The
+     * AnthropicCacheStrategy translates `boundaryIndex` to the right
+     * positional placement; consumers and CacheDecision subflow don't
+     * see this complexity.
+     */
+    readonly boundaryIndex: number;
+    /**
+     * Suggested TTL for this marker. Strategies map to provider-specific
+     * values (Anthropic: `'short'` → 5min ephemeral, `'long'` → 1h beta).
+     */
+    readonly ttl: 'short' | 'long';
+    /**
+     * Diagnostic string surfaced in cacheRecorder events. Helps consumers
+     * understand WHY this marker fired. Examples: `'always-on injections'`,
+     * `'skill body (port-error-triage)'`.
+     */
+    readonly reason: string;
+}
+/**
+ * Per-provider cache implementation. One strategy per provider name;
+ * registered in a default map keyed by `LLMProvider.name`.
+ *
+ * Strategies MUST be stateless across runs. Any per-run state (handle
+ * cache, hit-rate tracking) lives inside the strategy instance.
+ */
+export interface CacheStrategy {
+    /** Provider name match. e.g. `'anthropic'`, `'openai'`, `'bedrock'`. */
+    readonly providerName: string;
+    /**
+     * Static description of what this strategy can do. Read by the
+     * CacheDecision subflow to know whether to bother emitting markers,
+     * and how many to emit before clamping to provider limits.
+     */
+    readonly capabilities: CacheCapabilities;
+    /**
+     * Translate agnostic markers to provider-specific wire format.
+     *
+     * Async to support handle-based caching (Gemini does
+     * `createCachedContent` and references handles; not in v2.6 but
+     * the interface is async-ready for v2.7+).
+     *
+     * Returns the modified request AND the markers actually applied
+     * (after capability-clamping). `markersApplied` flows into the
+     * cacheRecorder for diagnostic surfacing.
+     */
+    prepareRequest(req: LLMRequest, candidates: readonly CacheMarker[], ctx: CacheStrategyContext): Promise<{
+        readonly request: LLMRequest;
+        readonly markersApplied: readonly CacheMarker[];
+    }>;
+    /**
+     * Extract cache hit/miss metrics from the provider's `usage` field.
+     * Each provider names its cache fields differently:
+     * - Anthropic: `cache_creation_input_tokens` + `cache_read_input_tokens`
+     * - OpenAI: `prompt_tokens_details.cached_tokens`
+     *
+     * Returns `undefined` for providers without cache reporting (Mock, NoOp).
+     */
+    extractMetrics(usage: unknown): CacheMetrics | undefined;
+}
+/**
+ * Static description of a strategy's capabilities. The CacheDecision
+ * subflow reads this BEFORE calling `prepareRequest` so it can clamp
+ * candidates to a count the strategy can actually use.
+ */
+export interface CacheCapabilities {
+    /**
+     * `true` if this strategy actually does anything. `false` for NoOp,
+     * Mock, or providers we haven't built yet. CacheDecision subflow
+     * skips entirely when `enabled` is `false`.
+     */
+    readonly enabled: boolean;
+    /**
+     * Maximum number of cache markers per request. Anthropic enforces 4
+     * cache breakpoints per request; OpenAI is automatic (∞); Gemini
+     * is per-handle (∞ effectively). Strategies clamp internally.
+     */
+    readonly maxMarkers: number;
+    /**
+     * TTL values this strategy can map to. Anthropic supports both;
+     * OpenAI is fixed (~5min); some providers may only support one.
+     */
+    readonly ttls: ReadonlyArray<'short' | 'long'>;
+    /**
+     * Which request fields this strategy can mark. Most providers support
+     * all three (system / tools / messages); some are field-restricted.
+     */
+    readonly fields: ReadonlyArray<'system' | 'tools' | 'messages'>;
+    /**
+     * `true` if the provider auto-caches without explicit markers (OpenAI).
+     * In that case `prepareRequest` is a pass-through; only
+     * `extractMetrics` does meaningful work. Surfaced for documentation
+     * (so consumers know `cache: 'never'` may not actually disable caching
+     * on auto-caching providers).
+     */
+    readonly automatic: boolean;
+}
+/**
+ * Per-run state passed into `prepareRequest`. Strategies use this to
+ * make per-iteration decisions (rate of cache invalidation, current
+ * iteration index, etc.) without leaking state into module scope.
+ */
+export interface CacheStrategyContext {
+    readonly iteration: number;
+    readonly iterationsRemaining: number;
+    /**
+     * Hit rate across previous iterations of this run (0..1). Strategies
+     * use this for self-disable behaviors (e.g., AnthropicCacheStrategy
+     * auto-skips markers when hit rate < 30% to avoid the cache-write
+     * penalty without recoup).
+     */
+    readonly recentHitRate: number | undefined;
+    /**
+     * `true` when `Agent.create({ caching: 'off' })` is set OR a
+     * higher-level kill switch fires. Strategy MUST honor this and
+     * return the request unchanged.
+     */
+    readonly cachingDisabled: boolean;
+}
+/**
+ * Normalized cache metrics extracted from a provider's `usage`
+ * response. cacheRecorder consumes these for hit-rate tracking,
+ * cost estimation (via PricingTable), and diagnostic events.
+ */
+export interface CacheMetrics {
+    /** Tokens served from cache (10% / 50% / 25% off depending on provider). */
+    readonly cacheReadTokens: number;
+    /** Tokens written to cache this call (premium varies by provider). */
+    readonly cacheWriteTokens: number;
+    /** New input tokens not from cache — full price. */
+    readonly freshInputTokens: number;
+}