agentfootprint 2.5.1 → 2.6.0

package/dist/esm/cache/strategies/BedrockCacheStrategy.js

@@ -0,0 +1,77 @@
+/**
+ * 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 { registerCacheStrategy } from '../strategyRegistry.js';
+/** Match Bedrock-Claude model ids: `anthropic.claude-...` */
+const BEDROCK_CLAUDE_RE = /^anthropic\.claude/i;
+/** Anthropic's 4-marker limit applies to Bedrock-Claude too. */
+const BEDROCK_MAX_MARKERS = 4;
+const BEDROCK_CAPABILITIES = Object.freeze({
+    // We say `enabled: true` at the capability level because Bedrock-
+    // Claude DOES support caching. Bedrock-Llama/Mistral land in the
+    // model-aware code path inside prepareRequest (no markers applied).
+    enabled: true,
+    maxMarkers: BEDROCK_MAX_MARKERS,
+    ttls: ['short', 'long'],
+    fields: ['system', 'tools', 'messages'],
+    automatic: false,
+});
+export class BedrockCacheStrategy {
+    providerName = 'bedrock';
+    capabilities = BEDROCK_CAPABILITIES;
+    async prepareRequest(req, candidates, ctx) {
+        if (ctx.cachingDisabled || candidates.length === 0) {
+            return { request: req, markersApplied: [] };
+        }
+        // Model-aware: only Claude on Bedrock supports cache_control.
+        // Other model families silently drop the markers.
+        if (!BEDROCK_CLAUDE_RE.test(req.model)) {
+            return { request: req, markersApplied: [] };
+        }
+        const markersApplied = candidates.length <= BEDROCK_MAX_MARKERS
+            ? candidates
+            : candidates.slice(0, BEDROCK_MAX_MARKERS);
+        return {
+            request: { ...req, cacheMarkers: markersApplied },
+            markersApplied,
+        };
+    }
+    extractMetrics(usage) {
+        // Bedrock returns the SAME usage shape as Anthropic for Claude
+        // models — same cache_creation_input_tokens / cache_read_input_tokens
+        // fields. Reuse identical extraction.
+        if (!usage || typeof usage !== 'object')
+            return undefined;
+        const u = usage;
+        const cacheRead = u.cache_read_input_tokens ?? 0;
+        const cacheWrite = u.cache_creation_input_tokens ?? 0;
+        if (cacheRead === 0 && cacheWrite === 0)
+            return undefined;
+        return {
+            cacheReadTokens: cacheRead,
+            cacheWriteTokens: cacheWrite,
+            freshInputTokens: u.input_tokens ?? 0,
+        };
+    }
+}
+registerCacheStrategy(new BedrockCacheStrategy());
+//# sourceMappingURL=BedrockCacheStrategy.js.map

package/dist/esm/cache/strategies/BedrockCacheStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BedrockCacheStrategy.js","sourceRoot":"","sources":["../../../../src/cache/strategies/BedrockCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,6DAA6D;AAC7D,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEhD,gEAAgE;AAChE,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B,MAAM,oBAAoB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC5D,kEAAkE;IAClE,iEAAiE;IACjE,oEAAoE;IACpE,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,mBAAmB;IAC/B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAkC;IACxD,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAiD;IACvF,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,OAAO,oBAAoB;IACtB,YAAY,GAAG,SAAS,CAAC;IACzB,YAAY,GAAG,oBAAoB,CAAC;IAE7C,KAAK,CAAC,cAAc,CAClB,GAAe,EACf,UAAkC,EAClC,GAAyB;QAKzB,IAAI,GAAG,CAAC,eAAe,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QACD,8DAA8D;QAC9D,kDAAkD;QAClD,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QACD,MAAM,cAAc,GAClB,UAAU,CAAC,MAAM,IAAI,mBAAmB;YACtC,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;QAC/C,OAAO;YACL,OAAO,EAAE,EAAE,GAAG,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE;YACjD,cAAc;SACf,CAAC;IACJ,CAAC;IAED,cAAc,CAAC,KAAc;QAC3B,+DAA+D;QAC/D,sEAAsE;QACtE,sCAAsC;QACtC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC1D,MAAM,CAAC,GAAG,KAIT,CAAC;QACF,MAAM,SAAS,GAAG,CAAC,CAAC,uBAAuB,IAAI,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,CAAC,CAAC,2BAA2B,IAAI,CAAC,CAAC;QACtD,IAAI,SAAS,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC1D,OAAO;YACL,eAAe,EAAE,SAAS;YAC1B,gBAAgB,EAAE,UAAU;YAC5B,gBAAgB,EAAE,CAAC,CAAC,YAAY,IAAI,CAAC;SACtC,CAAC;IACJ,CAAC;CACF;AAED,qBAAqB,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC"}

package/dist/esm/cache/strategies/NoOpCacheStrategy.js

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+const NOOP_CAPABILITIES = Object.freeze({
+    enabled: false,
+    maxMarkers: 0,
+    ttls: [],
+    fields: [],
+    automatic: false,
+});
+export class NoOpCacheStrategy {
+    /**
+     * Wildcard provider name. The strategy registry treats this as the
+     * fallback for any provider that doesn't have a specific strategy
+     * registered.
+     */
+    providerName = '*';
+    capabilities = NOOP_CAPABILITIES;
+    async prepareRequest(req, _candidates, _ctx) {
+        return { request: req, markersApplied: [] };
+    }
+    extractMetrics(_usage) {
+        return undefined;
+    }
+}
+//# sourceMappingURL=NoOpCacheStrategy.js.map

package/dist/esm/cache/strategies/NoOpCacheStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoOpCacheStrategy.js","sourceRoot":"","sources":["../../../../src/cache/strategies/NoOpCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,MAAM,iBAAiB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACzD,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,CAAC;IACb,IAAI,EAAE,EAAmC;IACzC,MAAM,EAAE,EAAkD;IAC1D,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,OAAO,iBAAiB;IAC5B;;;;OAIG;IACM,YAAY,GAAG,GAAG,CAAC;IACnB,YAAY,GAAG,iBAAiB,CAAC;IAE1C,KAAK,CAAC,cAAc,CAClB,GAAe,EACf,WAAmC,EACnC,IAA0B;QAK1B,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;IAC9C,CAAC;IAED,cAAc,CAAC,MAAe;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/esm/cache/strategies/OpenAICacheStrategy.js

@@ -0,0 +1,71 @@
+/**
+ * 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 { registerCacheStrategy } from '../strategyRegistry.js';
+const OPENAI_CAPABILITIES = Object.freeze({
+    // `enabled: true` because metrics ARE extracted (cacheRecorder shows
+    // hit rates). The `automatic: true` flag tells consumers the markers
+    // are inert here — OpenAI decides what to cache, not us.
+    enabled: true,
+    maxMarkers: 0,
+    ttls: ['short'],
+    fields: [],
+    automatic: true,
+});
+export class OpenAICacheStrategy {
+    providerName = 'openai';
+    capabilities = OPENAI_CAPABILITIES;
+    async prepareRequest(req, _candidates, _ctx) {
+        // Pass-through. OpenAI auto-caches; no opt-in needed.
+        return { request: req, markersApplied: [] };
+    }
+    extractMetrics(usage) {
+        if (!usage || typeof usage !== 'object')
+            return undefined;
+        const u = usage;
+        const cached = u.prompt_tokens_details?.cached_tokens ?? 0;
+        if (cached === 0)
+            return undefined;
+        const totalPrompt = u.prompt_tokens ?? cached;
+        return {
+            cacheReadTokens: cached,
+            cacheWriteTokens: 0, // OpenAI doesn't charge a write premium
+            freshInputTokens: Math.max(0, totalPrompt - cached),
+        };
+    }
+}
+// Auto-register for both server-side and browser variants.
+{
+    const strategy = new OpenAICacheStrategy();
+    registerCacheStrategy(strategy);
+    const browserStrategy = {
+        providerName: 'browser-openai',
+        capabilities: strategy.capabilities,
+        prepareRequest: strategy.prepareRequest.bind(strategy),
+        extractMetrics: strategy.extractMetrics.bind(strategy),
+    };
+    registerCacheStrategy(browserStrategy);
+}
+//# sourceMappingURL=OpenAICacheStrategy.js.map

package/dist/esm/cache/strategies/OpenAICacheStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAICacheStrategy.js","sourceRoot":"","sources":["../../../../src/cache/strategies/OpenAICacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC3D,qEAAqE;IACrE,qEAAqE;IACrE,yDAAyD;IACzD,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,CAAC;IACb,IAAI,EAAE,CAAC,OAAO,CAAkC;IAChD,MAAM,EAAE,EAAkD;IAC1D,SAAS,EAAE,IAAI;CAChB,CAAC,CAAC;AAEH,MAAM,OAAO,mBAAmB;IACrB,YAAY,GAAG,QAAQ,CAAC;IACxB,YAAY,GAAG,mBAAmB,CAAC;IAE5C,KAAK,CAAC,cAAc,CAClB,GAAe,EACf,WAAmC,EACnC,IAA0B;QAK1B,sDAAsD;QACtD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;IAC9C,CAAC;IAED,cAAc,CAAC,KAAc;QAC3B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC1D,MAAM,CAAC,GAAG,KAGT,CAAC;QACF,MAAM,MAAM,GAAG,CAAC,CAAC,qBAAqB,EAAE,aAAa,IAAI,CAAC,CAAC;QAC3D,IAAI,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACnC,MAAM,WAAW,GAAG,CAAC,CAAC,aAAa,IAAI,MAAM,CAAC;QAC9C,OAAO;YACL,eAAe,EAAE,MAAM;YACvB,gBAAgB,EAAE,CAAC,EAAE,wCAAwC;YAC7D,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;SACpD,CAAC;IACJ,CAAC;CACF;AAED,2DAA2D;AAC3D,CAAC;IACC,MAAM,QAAQ,GAAG,IAAI,mBAAmB,EAAE,CAAC;IAC3C,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,eAAe,GAAkB;QACrC,YAAY,EAAE,gBAAgB;QAC9B,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;QACtD,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;KACvD,CAAC;IACF,qBAAqB,CAAC,eAAe,CAAC,CAAC;AACzC,CAAC"}

package/dist/esm/cache/strategyRegistry.js

@@ -0,0 +1,73 @@
+/**
+ * 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 { NoOpCacheStrategy } from './strategies/NoOpCacheStrategy.js';
+/**
+ * Registry singleton. Populated by individual strategy modules
+ * importing this and calling `registerCacheStrategy` at module load
+ * time, OR by the consumer at agent build time.
+ *
+ * Contains the wildcard `'*'` → NoOp entry by default; never empty.
+ */
+const REGISTRY = new Map([['*', new NoOpCacheStrategy()]]);
+/**
+ * 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 function getDefaultCacheStrategy(providerName) {
+    const exact = REGISTRY.get(providerName);
+    if (exact !== undefined)
+        return exact;
+    const lower = providerName.toLowerCase();
+    if (lower !== providerName) {
+        const lowercased = REGISTRY.get(lower);
+        if (lowercased !== undefined)
+            return lowercased;
+    }
+    // Fallback wildcard always present
+    return REGISTRY.get('*');
+}
+/**
+ * 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 function registerCacheStrategy(strategy) {
+    REGISTRY.set(strategy.providerName, strategy);
+}
+/**
+ * Read-only view of registered strategy names. Useful for diagnostics
+ * (e.g., logging "we have strategies for: anthropic, openai, *").
+ */
+export function listRegisteredStrategies() {
+    return [...REGISTRY.keys()];
+}
+/**
+ * Internal helper for tests: reset the registry to the default
+ * (wildcard → NoOp only). Not exported from the public barrel.
+ */
+export function _resetRegistryForTests() {
+    REGISTRY.clear();
+    REGISTRY.set('*', new NoOpCacheStrategy());
+}
+//# sourceMappingURL=strategyRegistry.js.map

package/dist/esm/cache/strategyRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategyRegistry.js","sourceRoot":"","sources":["../../../src/cache/strategyRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAwB,CAAC,CAAC,GAAG,EAAE,IAAI,iBAAiB,EAAE,CAAC,CAAC,CAAC,CAAC;AAElF;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,YAAoB;IAC1D,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;IACzC,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,UAAU,CAAC;IAClD,CAAC;IACD,mCAAmC;IACnC,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAuB;IAC3D,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACjB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,iBAAiB,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/esm/cache/types.js

@@ -0,0 +1,24 @@
+/**
+ * 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`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cache/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/esm/conventions.js

@@ -28,6 +28,9 @@ export const SUBFLOW_IDS = {
     MERGE: 'sf-merge',
     /** Final-answer composition inside Agent. */
     FINAL: 'sf-final',
+    /** Cache decision subflow (v2.6). Walks activeInjections, emits
+     *  agnostic CacheMarker[]. Provider-independent. */
+    CACHE_DECISION: 'sf-cache-decision',
 };
 /** Stage IDs — plain function stages that builders mount. */
 export const STAGE_IDS = {
@@ -37,6 +40,21 @@ export const STAGE_IDS = {
     FORMAT_MERGE: 'format-merge',
     MERGE_LLM: 'merge-llm',
     EXTRACT_MERGE: 'extract-merge',
+    /** Updates the rolling skill-history window before CacheGate
+     *  evaluates skill-churn (v2.6). */
+    UPDATE_SKILL_HISTORY: 'update-skill-history',
+    /** CacheGate decider stage — routes to apply-markers / no-markers
+     *  based on kill switch / hit rate / skill churn (v2.6). */
+    CACHE_GATE: 'cache-gate',
+    /** CacheGate branch (routing key) when markers SHOULD be applied
+     *  this iteration. Pass-through stage; markers stay in scope. (v2.6) */
+    APPLY_MARKERS: 'apply-markers',
+    /** CacheGate branch (routing key) when markers should be SKIPPED
+     *  this iteration. Stage clears scope.cacheMarkers. (v2.6) */
+    SKIP_CACHING: 'no-markers',
+    /** BuildLLMRequest stage — calls strategy.prepareRequest to apply
+     *  markers to the wire request (v2.6). */
+    BUILD_LLM_REQUEST: 'build-llm-request',
 };
 // ─── Type guards ─────────────────────────────────────────────────────
 /** True when a subflow id corresponds to one of the 3 context slots. */

package/dist/esm/conventions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB;0EACsE;IACtE,gBAAgB,EAAE,qBAAqB;IACvC,+DAA+D;IAC/D,aAAa,EAAE,kBAAkB;IACjC,6BAA6B;IAC7B,QAAQ,EAAE,aAAa;IACvB,0BAA0B;IAC1B,KAAK,EAAE,UAAU;IACjB,2CAA2C;IAC3C,KAAK,EAAE,UAAU;IACjB,uDAAuD;IACvD,UAAU,EAAE,eAAe;IAC3B,kCAAkC;IAClC,KAAK,EAAE,UAAU;IACjB,6CAA6C;IAC7C,KAAK,EAAE,UAAU;CACT,CAAC;AAIX,6DAA6D;AAC7D,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,YAAY,EAAE,cAAc;IAC5B,SAAS,EAAE,WAAW;IACtB,aAAa,EAAE,eAAe;CACtB,CAAC;AAIX,wEAAwE;AAExE,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAC3B,EAAU;IAEV,OAAO,CACL,EAAE,KAAK,WAAW,CAAC,aAAa,IAAI,EAAE,KAAK,WAAW,CAAC,QAAQ,IAAI,EAAE,KAAK,WAAW,CAAC,KAAK,CAC5F,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,iEAAiE;IACjE,mEAAmE;IACnE,kEAAkE;IAClE,6CAA6C;IAC7C,MAAM,WAAW,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,WAAW,CAAC,aAAa;YAC5B,OAAO,eAAe,CAAC;QACzB,KAAK,WAAW,CAAC,QAAQ;YACvB,OAAO,UAAU,CAAC;QACpB,KAAK,WAAW,CAAC,KAAK;YACpB,OAAO,OAAO,CAAC;QACjB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,OAAQ,MAAM,CAAC,MAAM,CAAC,WAAW,CAAc,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,OAAQ,MAAM,CAAC,MAAM,CAAC,SAAS,CAAc,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa,EAAE,wBAAwB;IACvC,QAAQ,EAAE,oBAAoB;IAC9B,KAAK,EAAE,iBAAiB;CAChB,CAAC;AAIX,6CAA6C;AAC7C,MAAM,UAAU,mBAAmB,CAAC,IAA4C;IAC9E,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,eAAe;YAClB,OAAO,cAAc,CAAC,aAAa,CAAC;QACtC,KAAK,UAAU;YACb,OAAO,cAAc,CAAC,QAAQ,CAAC;QACjC,KAAK,OAAO;YACV,OAAO,cAAc,CAAC,KAAK,CAAC;IAChC,CAAC;AACH,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAQ,MAAM,CAAC,MAAM,CAAC,cAAc,CAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/conventions.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/Agent.js

@@ -21,6 +21,9 @@ import { FlowChartExecutor, flowChart, } from 'footprintjs';
 // with it (default behavior re-introduces duplicate tool names that
 // LLM providers reject).
 import { ArrayMergeMode } from 'footprintjs/advanced';
+import { cacheDecisionSubflow } from '../cache/CacheDecisionSubflow.js';
+import { cacheGateDecide, updateSkillHistory as updateSkillHistoryStage, } from '../cache/CacheGateDecider.js';
+import { getDefaultCacheStrategy } from '../cache/strategyRegistry.js';
 import { isPauseRequest } from './pause.js';
 import { emitCostTick } from './cost.js';
 import { STAGE_IDS, SUBFLOW_IDS } from '../conventions.js';
@@ -55,6 +58,27 @@ export class Agent extends RunnerBase {
     maxTokens;
     maxIterations;
     systemPromptValue;
+    /**
+     * Cache policy for the base system prompt (set via
+     * `.system(text, { cache })`). Default `'always'` — base prompt is
+     * stable per-turn, ideal cache anchor. CacheDecision subflow reads
+     * this when computing the SystemPrompt slot's cache markers.
+     */
+    systemPromptCachePolicy;
+    /**
+     * Global cache kill switch from `Agent.create({ caching: 'off' })`.
+     * Threaded into agent scope at seed-time as `scope.cachingDisabled`;
+     * read by the CacheGate decider every iteration (highest-priority rule).
+     */
+    cachingDisabledValue;
+    /**
+     * Provider-specific CacheStrategy. Auto-resolved from
+     * `getDefaultCacheStrategy(provider.name)` at agent build time
+     * unless the consumer explicitly passes one via builder option.
+     * Phase 7+ implementations (Anthropic, OpenAI, Bedrock) register
+     * themselves in the strategyRegistry on import.
+     */
+    cacheStrategy;
     registry;
     /**
      * The Injection list — Skills, Steering, Instructions, Facts (and
@@ -119,7 +143,7 @@ export class Agent extends RunnerBase {
      * dispatch correctly when their visible-set changes mid-turn.
      */
     externalToolProvider;
-    constructor(opts, systemPromptValue, registry, voice, injections = [], memories = [], outputSchemaParser, toolProvider) {
+    constructor(opts, systemPromptValue, registry, voice, injections = [], memories = [], outputSchemaParser, toolProvider, systemPromptCachePolicy = 'always', cachingDisabled = false, cacheStrategy) {
         super();
         this.provider = opts.provider;
         this.name = opts.name ?? 'Agent';
@@ -129,6 +153,11 @@ export class Agent extends RunnerBase {
         this.maxTokens = opts.maxTokens;
         this.maxIterations = clampIterations(opts.maxIterations ?? 10);
         this.systemPromptValue = systemPromptValue;
+        this.systemPromptCachePolicy = systemPromptCachePolicy;
+        this.cachingDisabledValue = cachingDisabled;
+        // Auto-resolve strategy from provider.name unless caller overrides.
+        // NoOp is the wildcard fallback so unknown providers stay safe.
+        this.cacheStrategy = cacheStrategy ?? getDefaultCacheStrategy(opts.provider.name);
         this.registry = registry;
         this.injections = injections;
         this.memories = memories;
@@ -158,6 +187,15 @@ export class Agent extends RunnerBase {
     toFlowChart() {
         return this.buildChart();
     }
+    /**
+     * Cache policy for the base system prompt. Read by the CacheDecision
+     * subflow (v2.6 Phase 4) to know how to treat the SystemPrompt slot's
+     * cache markers. Exposed as a method (not direct field access) so
+     * the Agent's encapsulation boundary stays clean.
+     */
+    getSystemPromptCachePolicy() {
+        return this.systemPromptCachePolicy;
+    }
     /**
      * The footprintjs `RuntimeSnapshot` from the most recent `run()` /
      * `resume()`. Feeds Lens's Trace tab (ExplainableShell `runtimeSnapshot`
@@ -310,6 +348,15 @@ export class Agent extends RunnerBase {
         const pricingTable = this.pricingTable;
         const costBudget = this.costBudget;
         const permissionChecker = this.permissionChecker;
+        // Cache layer (v2.6) — capture for the seed + chart-build closures.
+        // `systemPromptCachePolicy` is fed into the CacheDecision subflow's
+        // inputMapper. `cacheStrategy` is consulted by BuildLLMRequest at
+        // run-time (Phase 7+ for the actual prepareRequest call). For
+        // Phase 6b the chart mounts the stages but BuildLLMRequest is a
+        // pass-through; Phase 7 lights up the strategy call.
+        const systemPromptCachePolicy = this.systemPromptCachePolicy;
+        const cachingDisabled = this.cachingDisabledValue;
+        const cacheStrategy = this.cacheStrategy;
         const seed = (scope) => {
             const args = scope.$getArgs();
             scope.userMessage = args.message;
@@ -347,6 +394,17 @@ export class Agent extends RunnerBase {
             scope.activeInjections = [];
             scope.activatedInjectionIds = [];
             scope.dynamicToolSchemas = toolSchemas;
+            // Cache layer state (v2.6) — initialized to inert defaults.
+            // CacheDecision subflow populates `cacheMarkers` per iteration;
+            // UpdateSkillHistory + CacheGate consume `cachingDisabled`,
+            // `recentHitRate`, `skillHistory`. Empty defaults mean the
+            // CacheGate falls through to 'apply-markers' on iter 1 (no
+            // history yet → no churn detected; recentHitRate undefined →
+            // hit-rate floor doesn't fire).
+            scope.cacheMarkers = [];
+            scope.cachingDisabled = cachingDisabled;
+            scope.recentHitRate = undefined;
+            scope.skillHistory = [];
             typedEmit(scope, 'agentfootprint.agent.turn_start', {
                 turnIndex: 0,
                 userPrompt: args.message,
@@ -501,7 +559,7 @@ export class Agent extends RunnerBase {
             // Falls back to the static schemas at startup before the tools
             // slot has run for the first time.
             const activeToolSchemas = scope.dynamicToolSchemas ?? toolSchemas;
-            const llmRequest = {
+            const baseRequest = {
                 ...(systemPrompt.length > 0 && { systemPrompt }),
                 messages,
                 ...(activeToolSchemas.length > 0 && { tools: activeToolSchemas }),
@@ -509,6 +567,18 @@ export class Agent extends RunnerBase {
                 ...(temperature !== undefined && { temperature }),
                 ...(maxTokens !== undefined && { maxTokens }),
             };
+            // v2.6+ — call cache strategy to attach provider-specific cache
+            // hints. CacheGate has already routed (apply-markers / no-markers)
+            // and populated scope.cacheMarkers accordingly. Strategy.prepareRequest
+            // is a pass-through for empty markers.
+            const cacheMarkers = scope.cacheMarkers ?? [];
+            const cachePrepared = await cacheStrategy.prepareRequest(baseRequest, cacheMarkers, {
+                iteration,
+                iterationsRemaining: Math.max(0, maxIterations - iteration),
+                recentHitRate: scope.recentHitRate,
+                cachingDisabled: scope.cachingDisabled ?? false,
+            });
+            const llmRequest = cachePrepared.request;
             // Streaming-first: when the provider implements `stream()` we
             // consume chunk-by-chunk so consumers (Lens commentary, chat
             // UIs) see tokens as they arrive instead of waiting for the
@@ -960,6 +1030,44 @@ export class Agent extends RunnerBase {
             // concatenate.
             arrayMerge: ArrayMergeMode.Replace,
         })
+            // ── Cache layer (v2.6) ─────────────────────────────────────
+            // CacheDecision subflow walks `activeInjections` + evaluates
+            // each `cache:` directive, emits provider-agnostic
+            // `CacheMarker[]` to scope. Pure transform; no IO.
+            //
+            // CRITICAL: arrayMerge: ArrayMergeMode.Replace — same lesson
+            // as the v2.5.1 InjectionEngine fix. The default footprintjs
+            // behavior CONCATENATES arrays from child to parent;
+            // `cacheMarkers` MUST replace each iteration, not accumulate.
+            .addSubFlowChartNext(SUBFLOW_IDS.CACHE_DECISION, cacheDecisionSubflow, 'CacheDecision', {
+            inputMapper: (parent) => ({
+                activeInjections: parent.activeInjections ?? [],
+                iteration: parent.iteration ?? 1,
+                maxIterations: parent.maxIterations ?? maxIterations,
+                userMessage: parent.userMessage ?? '',
+                ...(parent.lastToolResult !== undefined && {
+                    lastToolName: parent.lastToolResult?.toolName,
+                }),
+                cumulativeInputTokens: parent.totalInputTokens ?? 0,
+                systemPromptCachePolicy,
+                cachingDisabled: parent.cachingDisabled ?? false,
+            }),
+            outputMapper: (sf) => ({ cacheMarkers: sf.cacheMarkers }),
+            arrayMerge: ArrayMergeMode.Replace,
+        })
+            .addFunction('UpdateSkillHistory', updateSkillHistoryStage, STAGE_IDS.UPDATE_SKILL_HISTORY, 'Update skill-history rolling window for CacheGate churn detection')
+            .addDeciderFunction('CacheGate', cacheGateDecide, STAGE_IDS.CACHE_GATE, 'Gate cache-marker application: kill switch / hit-rate / skill-churn')
+            .addFunctionBranch(STAGE_IDS.APPLY_MARKERS, 'ApplyMarkers', 
+        // Pass-through stage — markers stay in scope as-is.
+        // BuildLLMRequest (Phase 7+) reads them on the next stage.
+        () => undefined, 'Proceed with cache markers from CacheDecision')
+            .addFunctionBranch(STAGE_IDS.SKIP_CACHING, 'SkipCaching', 
+        // Clear markers so BuildLLMRequest sees an empty list and
+        // makes the request unmodified.
+        (scope) => {
+            scope.cacheMarkers = [];
+        }, 'Skip caching this iteration')
+            .end()
             .addFunction('IterationStart', iterationStart, 'iteration-start', 'Iteration begin marker')
             .addFunction('CallLLM', callLLM, STAGE_IDS.CALL_LLM, 'LLM invocation')
             .addDeciderFunction('Route', routeDecider, SUBFLOW_IDS.ROUTE, 'ReAct routing')
@@ -1006,6 +1114,26 @@ export class Agent extends RunnerBase {
 export class AgentBuilder {
     opts;
     systemPromptValue = '';
+    /**
+     * Cache policy for the base system prompt. Set via the optional
+     * 2nd argument to `.system(text, { cache })`. Default `'always'` —
+     * the base prompt is stable per-turn and an ideal cache anchor.
+     */
+    systemPromptCachePolicy = 'always';
+    /**
+     * Global cache kill switch. Set via `Agent.create({ caching: 'off' })`
+     * (handled in `AgentOptions` propagation). Defaults to `false`
+     * (caching enabled). When `true`, the CacheGate decider routes to
+     * `'no-markers'` every iteration regardless of other rules.
+     */
+    cachingDisabledValue = false;
+    /**
+     * Optional explicit CacheStrategy override. Default: undefined,
+     * which means the agent auto-resolves from
+     * `getDefaultCacheStrategy(provider.name)` at construction. Power
+     * users override here for custom backends or test mocks.
+     */
+    cacheStrategyOverride;
     registry = [];
     injectionList = [];
     memoryList = [];
@@ -1042,9 +1170,34 @@ export class AgentBuilder {
     thinkingOverrides = {};
     constructor(opts) {
         this.opts = opts;
+        // Cache layer: opts.caching === 'off' propagates to scope's
+        // `cachingDisabled` kill switch read by CacheGate. opts.cacheStrategy
+        // overrides the registry-resolved default.
+        if (opts.caching === 'off')
+            this.cachingDisabledValue = true;
+        if (opts.cacheStrategy !== undefined)
+            this.cacheStrategyOverride = opts.cacheStrategy;
     }
-    system(prompt) {
+    /**
+     * Set the base system prompt.
+     *
+     * @param prompt - The system prompt text. Stable per-turn.
+     * @param options - Optional config. `cache` controls how the
+     *   CacheDecision subflow treats this prompt block:
+     *   - `'always'` (default) — cache the base prompt as a stable
+     *     prefix anchor. Highest cache-hit rate; recommended for
+     *     production agents whose system prompt rarely changes.
+     *   - `'never'` — skip caching. Use if the prompt contains volatile
+     *     content (timestamps, per-request user IDs).
+     *   - `'while-active'` — semantically equivalent to `'always'` for
+     *     the base prompt (it's always active by definition).
+     *   - `{ until }` — conditional invalidation (e.g., flush after iter 5).
+     */
+    system(prompt, options) {
         this.systemPromptValue = prompt;
+        if (options?.cache !== undefined) {
+            this.systemPromptCachePolicy = options.cache;
+        }
         return this;
     }
     tool(tool) {
@@ -1358,7 +1511,7 @@ export class AgentBuilder {
         const opts = this.maxIterationsOverride !== undefined
             ? { ...this.opts, maxIterations: this.maxIterationsOverride }
             : this.opts;
-        const agent = new Agent(opts, this.systemPromptValue, this.registry, voice, this.injectionList, this.memoryList, this.outputSchemaParser, this.toolProviderRef);
+        const agent = new Agent(opts, this.systemPromptValue, this.registry, voice, this.injectionList, this.memoryList, this.outputSchemaParser, this.toolProviderRef, this.systemPromptCachePolicy, this.cachingDisabledValue, this.cacheStrategyOverride);
         // Attach builder-collected recorders so they receive events from
         // the very first run. Mirrors what consumers would do post-build
         // via `agent.attach(rec)`; the builder method is purely sugar.