agentfootprint 2.5.0 → 2.6.0

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

@@ -0,0 +1,89 @@
+/**
+ * CacheDecision subflow — provider-agnostic translation from
+ * `activeInjections + DSL directives` → `CacheMarker[]`.
+ *
+ * This is the core "policy → markers" Lego layer. It runs every
+ * iteration (after slot subflows produce their output, before the
+ * CacheGate decider). Pure transform: no IO, no LLM calls, no
+ * provider knowledge.
+ *
+ * Algorithm:
+ *   1. Build a `CachePolicyContext` from agent state
+ *   2. For each injection in `activeInjections`, evaluate its
+ *      `metadata.cache` directive against the context → cacheable boolean
+ *   3. For each slot (system / tools / messages):
+ *      a. Walk the slot's contributions in order
+ *      b. Find the LAST index that's contiguous-from-start cacheable
+ *      c. Emit one CacheMarker at that boundary if any cacheable
+ *
+ * Each marker is provider-agnostic. Provider strategy translates
+ * to wire format in Phase 6+.
+ *
+ * Special case — base system prompt: the agent's
+ * `agent.getSystemPromptCachePolicy()` value is folded in at index 0
+ * of the system slot. Always-on injections (Steering / Fact /
+ * always-active rules) follow.
+ */
+import { type FlowChart } from 'footprintjs';
+import type { CacheMarker, CachePolicy, CachePolicyContext } from './types.js';
+import type { Injection } from '../lib/injection-engine/types.js';
+/**
+ * Subflow scope state. Set via inputMapper from the agent's parent
+ * scope; produces `cacheMarkers` consumed by the BuildLLMRequest stage.
+ */
+export interface CacheDecisionState {
+    readonly activeInjections: readonly Injection[];
+    readonly iteration: number;
+    readonly maxIterations: number;
+    readonly userMessage: string;
+    readonly lastToolName?: string;
+    /**
+     * Cumulative input tokens spent across all LLM calls in THIS
+     * `agent.run()` invocation only. Resets at the start of each turn
+     * (each `agent.run()` call). Predicates can use this for budget-
+     * aware cache invalidation (e.g., "flush cache after 50K tokens").
+     */
+    readonly cumulativeInputTokens: number;
+    /**
+     * Base system prompt's cache policy (from
+     * `agent.getSystemPromptCachePolicy()`). Folded in at index 0 of
+     * the system slot's cache evaluation, ahead of any always-on
+     * injections.
+     */
+    readonly systemPromptCachePolicy: CachePolicy;
+    /** Global kill switch. When `true`, subflow emits zero markers. */
+    readonly cachingDisabled: boolean;
+    cacheMarkers: readonly CacheMarker[];
+}
+/**
+ * Evaluate a `CachePolicy` against the current context.
+ * Returns `true` if the policy says THIS iteration's content is cacheable.
+ */
+export declare function evaluateCachePolicy(policy: CachePolicy, ctx: CachePolicyContext): boolean;
+/**
+ * Identify which slots an injection contributes to. An injection can
+ * target multiple slots simultaneously (Skills target both system +
+ * tools); we visit each contributing slot independently.
+ */
+export declare function injectionTargetSlots(injection: Injection): ReadonlyArray<'system' | 'tools' | 'messages'>;
+/**
+ * Pure transform: state → markers. Exported so tests can exercise
+ * the algorithm directly without the FlowChartExecutor ceremony of
+ * mounting the subflow as a child of a parent chart.
+ *
+ * The subflow body (`decide` below) is a thin wrapper that pulls
+ * state from scope and delegates here.
+ */
+export declare function computeCacheMarkers(state: Omit<CacheDecisionState, 'cacheMarkers'>): readonly CacheMarker[];
+/**
+ * The cache-decision subflow. Mounted into the agent's main chart
+ * after the slot subflows (System / Messages / Tools) and before
+ * the CacheGate decider stage.
+ *
+ * Mounted via `addSubFlowChartNext(SUBFLOW_IDS.CACHE_DECISION, ...)`
+ * with `arrayMerge: ArrayMergeMode.Replace` on the outputMapper —
+ * `cacheMarkers` MUST replace, not concatenate, across iterations
+ * (same lesson as the v2.5.1 InjectionEngine fix).
+ */
+export declare const cacheDecisionSubflow: FlowChart;
+//# sourceMappingURL=CacheDecisionSubflow.d.ts.map

package/dist/types/cache/CacheDecisionSubflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheDecisionSubflow.d.ts","sourceRoot":"","sources":["../../../src/cache/CacheDecisionSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAa,KAAK,SAAS,EAAmB,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,SAAS,EAAE,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAC9C,mEAAmE;IACnE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAElC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAuBzF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,GACnB,aAAa,CAAC,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC,CAYhD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,cAAc,CAAC,GAC9C,SAAS,WAAW,EAAE,CA2DxB;AAmBD;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAM1B,CAAC"}

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

@@ -0,0 +1,114 @@
+/**
+ * CacheGate — runtime decider that gates cache-marker application.
+ *
+ * Runs every iteration AFTER the CacheDecision subflow produces
+ * `scope.cacheMarkers` and BEFORE the BuildLLMRequest stage applies
+ * them. Three rules can fall through to "no-markers" (skip caching);
+ * default branch is "apply-markers" (proceed with caching).
+ *
+ * Why a decider stage and not a function: footprintjs's `decide()`
+ * captures evidence on `FlowRecorder.onDecision` natively. The
+ * `cacheRecorder()` (Phase 9) reads
+ * `event.evidence.rules.find(r => r.matched).inputs[]` to surface
+ * WHY caching was applied or skipped each iter. Same channel
+ * footprintjs uses for every other decision; same renderer in Lens.
+ *
+ * Three rules (evaluated top-down; first match wins):
+ *   1. Kill switch — `Agent.create({ caching: 'off' })` was set
+ *   2. Hit-rate floor — recent hit rate < 30%; cache writes outpacing
+ *      reads, auto-disable to avoid the cache-write penalty
+ *   3. Skill churn — active skills changing too rapidly for caching
+ *      to amortize (Anthropic LLM expert's concern from Phase 4 review)
+ *
+ * Default branch (no rule matches): `'apply-markers'`.
+ */
+import { type DecisionResult, type TypedScope } from 'footprintjs';
+/**
+ * Subset of agent scope state the CacheGate decider reads.
+ * Phase 6 wires these keys into the agent's main chart.
+ */
+export interface CacheGateState {
+    /**
+     * Global kill switch. When `true`, decider skips caching
+     * unconditionally. Set via `Agent.create({ caching: 'off' })`.
+     */
+    readonly cachingDisabled: boolean;
+    /**
+     * Running cache hit rate from the last N iterations (0..1).
+     * `undefined` when no cache events have fired yet (e.g., iter 1 of
+     * the first turn — no history). The cacheRecorder (Phase 9)
+     * computes this from `CacheMetrics` events.
+     */
+    readonly recentHitRate: number | undefined;
+    /**
+     * Rolling window of active-skill IDs across recent iterations,
+     * one per iteration (latest LAST). Maintained by the
+     * UpdateSkillHistory function stage (Phase 6 mount).
+     *
+     * `undefined` entry = no skill active that iteration.
+     */
+    readonly skillHistory: readonly (string | undefined)[];
+}
+/**
+ * Hit-rate floor below which we auto-disable caching. The 30% number
+ * is calibrated for Anthropic's pricing: cache write costs +25%
+ * premium, cache read costs 90% off. Break-even at ~25% hit rate.
+ * 30% gives a buffer; below that we're losing money on writes that
+ * never recoup.
+ *
+ * Reasoning: if hit rate is X, cost-per-token vs no caching is
+ *   (1 - X) * 1.0 + X * 0.1                                    // baseline
+ *   minus
+ *   write_iters * 1.25 + read_iters * 0.1                       // with caching
+ * Solving for break-even gives X ≈ 0.25 for typical agent shapes.
+ */
+export declare const HIT_RATE_FLOOR = 0.3;
+/**
+ * Window size for skill-churn detection. Last 5 iterations of
+ * active skill IDs are inspected.
+ */
+export declare const SKILL_CHURN_WINDOW = 5;
+/**
+ * Threshold above which skill churn is considered detected: this many
+ * UNIQUE skills in the rolling window. With window=5 and threshold=3,
+ * the pattern A → B → A → C still triggers (3 unique skills in 4 iters).
+ */
+export declare const SKILL_CHURN_THRESHOLD = 3;
+/**
+ * Pure helper: detect skill churn given a rolling history.
+ * Exported for direct testing without decider/scope ceremony.
+ */
+export declare function detectSkillChurn(history: readonly (string | undefined)[], windowSize?: number, threshold?: number): boolean;
+/**
+ * Branch routing keys for the CacheGate decider. Two outcomes:
+ * apply markers (proceed with cache) or skip (no markers this iter).
+ */
+export type CacheGateBranch = 'apply-markers' | 'no-markers';
+/**
+ * The decider function. Mounted via `addDeciderFunction` in the
+ * agent's main chart in Phase 6.
+ *
+ * Returns a `DecisionResult` (footprintjs's `decide()` helper output)
+ * which the engine unwraps via `.branch` for routing AND publishes
+ * `evidence.rules[matched].inputs[]` to FlowRecorder.onDecision.
+ * cacheRecorder (Phase 9) subscribes to that channel for the audit trail.
+ *
+ * For non-routing consumers (testing the decision in isolation), read
+ * the `.branch` field of the returned DecisionResult.
+ */
+export declare function cacheGateDecide(scope: TypedScope<CacheGateState>): DecisionResult;
+/**
+ * Update the skill-history rolling window. Called as a function
+ * stage BEFORE the CacheGate decider. Reads the current iteration's
+ * active skill (head of `activatedInjectionIds`) and appends to the
+ * `skillHistory` array.
+ *
+ * Window length is bounded at `SKILL_CHURN_WINDOW * 2` so the array
+ * doesn't grow unboundedly across long agent runs. Old entries
+ * fall off the front naturally.
+ */
+export declare function updateSkillHistory(scope: TypedScope<{
+    activatedInjectionIds?: readonly string[];
+    skillHistory: readonly (string | undefined)[];
+}>): void;
+//# sourceMappingURL=CacheGateDecider.d.ts.map

package/dist/types/cache/CacheGateDecider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheGateDecider.d.ts","sourceRoot":"","sources":["../../../src/cache/CacheGateDecider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAU,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CACxD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EACxC,UAAU,GAAE,MAA2B,EACvC,SAAS,GAAE,MAA8B,GACxC,OAAO,CAQT;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,YAAY,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,cAAc,CAAC,GAAG,cAAc,CAsBjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,CAAC;IAChB,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CAC/C,CAAC,GACD,IAAI,CAQN"}

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

@@ -0,0 +1,38 @@
+/**
+ * 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 {};
+//# sourceMappingURL=applyCachePolicy.d.ts.map

package/dist/types/cache/applyCachePolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyCachePolicy.d.ts","sourceRoot":"","sources":["../../../src/cache/applyCachePolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,QAAA,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAMzD,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,OAAO,eAAe,GAAG,MAAM,EAC7C,aAAa,EAAE,WAAW,GAAG,SAAS,GACrC,WAAW,CAKb;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAE5D"}

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

@@ -0,0 +1,86 @@
+/**
+ * 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 {};
+//# sourceMappingURL=cacheRecorder.d.ts.map

package/dist/types/cache/cacheRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheRecorder.d.ts","sourceRoot":"","sources":["../../../src/cache/cacheRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,UAAU,YAAY;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,CAAC;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,8BAA8B,EAAE,MAAM,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D;;;;OAIG;IACH,MAAM,IAAI,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CA8FrF"}

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

@@ -0,0 +1,34 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,wCAAwC,CAAC;AAChD,OAAO,qCAAqC,CAAC;AAC7C,OAAO,sCAAsC,CAAC;AAG9C,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAG5E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,39 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=AnthropicCacheStrategy.d.ts.map

package/dist/types/cache/strategies/AnthropicCacheStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnthropicCacheStrategy.d.ts","sourceRoot":"","sources":["../../../../src/cache/strategies/AnthropicCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,oBAAoB,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAc1D,qBAAa,sBAAuB,YAAW,aAAa;IAC1D,QAAQ,CAAC,YAAY,eAAe;IACpC,QAAQ,CAAC,YAAY,oBAA0B;IAEzC,cAAc,CAClB,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,SAAS,WAAW,EAAE,EAClC,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC;QACT,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;QAC7B,QAAQ,CAAC,cAAc,EAAE,SAAS,WAAW,EAAE,CAAC;KACjD,CAAC;IA4BF,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS;CAoBzD"}

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

@@ -0,0 +1,34 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=BedrockCacheStrategy.d.ts.map

package/dist/types/cache/strategies/BedrockCacheStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BedrockCacheStrategy.d.ts","sourceRoot":"","sources":["../../../../src/cache/strategies/BedrockCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,oBAAoB,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAoB1D,qBAAa,oBAAqB,YAAW,aAAa;IACxD,QAAQ,CAAC,YAAY,aAAa;IAClC,QAAQ,CAAC,YAAY,oBAAwB;IAEvC,cAAc,CAClB,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,SAAS,WAAW,EAAE,EAClC,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC;QACT,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;QAC7B,QAAQ,CAAC,cAAc,EAAE,SAAS,WAAW,EAAE,CAAC;KACjD,CAAC;IAmBF,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS;CAmBzD"}

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

@@ -0,0 +1,30 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=NoOpCacheStrategy.d.ts.map

package/dist/types/cache/strategies/NoOpCacheStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoOpCacheStrategy.d.ts","sourceRoot":"","sources":["../../../../src/cache/strategies/NoOpCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,oBAAoB,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAU1D,qBAAa,iBAAkB,YAAW,aAAa;IACrD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,OAAO;IAC5B,QAAQ,CAAC,YAAY,oBAAqB;IAEpC,cAAc,CAClB,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,SAAS,WAAW,EAAE,EACnC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC;QACT,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;QAC7B,QAAQ,CAAC,cAAc,EAAE,SAAS,WAAW,EAAE,CAAC;KACjD,CAAC;IAIF,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS;CAG1D"}

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

@@ -0,0 +1,37 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=OpenAICacheStrategy.d.ts.map

package/dist/types/cache/strategies/OpenAICacheStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAICacheStrategy.d.ts","sourceRoot":"","sources":["../../../../src/cache/strategies/OpenAICacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,oBAAoB,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAc1D,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,YAAY,YAAY;IACjC,QAAQ,CAAC,YAAY,oBAAuB;IAEtC,cAAc,CAClB,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,SAAS,WAAW,EAAE,EACnC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC;QACT,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;QAC7B,QAAQ,CAAC,cAAc,EAAE,SAAS,WAAW,EAAE,CAAC;KACjD,CAAC;IAKF,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS;CAezD"}

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

@@ -0,0 +1,46 @@
+/**
+ * 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;
+//# sourceMappingURL=strategyRegistry.d.ts.map

package/dist/types/cache/strategyRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategyRegistry.d.ts","sourceRoot":"","sources":["../../../src/cache/strategyRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAYhD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAU3E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAEnE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,SAAS,MAAM,EAAE,CAE5D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C"}