agentfootprint 9.136.0 → 9.138.0

package/dist/cache/CacheDecisionSubflow.js

@@ -16,6 +16,17 @@
  *      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
+ *   4. The moving breakpoint: when EVERYTHING the policies govern before
+ *      the conversation is cacheable — every tools entry, every system
+ *      entry, every delivered message — mark the conversation's LAST
+ *      message, so the next call (which repeats the conversation and
+ *      appends to it) reads the whole prefix back. See
+ *      `conversationTailMarker`.
+ *
+ * Nothing is marked when the tool schemas change on every call
+ * (`toolsVaryPerCall`, the findings offer): tools render first on a
+ * breakpoint wire, so every breakpoint would pay the write premium on bytes
+ * the next call does not send.
  *
  * Each marker is provider-agnostic. Provider strategy translates
  * to wire format in Phase 6+.
@@ -26,7 +37,7 @@
  * always-active rules) follow.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.decideCacheMarkers = exports.computeCacheMarkers = exports.injectionTargetSlots = exports.evaluateCachePolicy = void 0;
+exports.decideCacheMarkers = exports.cacheDecisionStage = exports.computeCacheMarkers = exports.injectionTargetSlots = exports.evaluateCachePolicy = void 0;
 const iterationBudget_js_1 = require("../lib/iterationBudget.js");
 /**
  * Evaluate a `CachePolicy` against the current context.
@@ -89,7 +100,7 @@ exports.injectionTargetSlots = injectionTargetSlots;
  */
 function computeCacheMarkers(state) {
     // Kill switch short-circuits immediately
-    if (state.cachingDisabled)
+    if (state.cachingDisabled || state.toolsVaryPerCall === true)
         return [];
     const ctx = {
         iteration: state.iteration,
@@ -150,12 +161,54 @@ function computeCacheMarkers(state) {
             });
         }
     }
-    const messagesMarker = messagesMarkerFor(state.history ?? [], cacheableById);
+    const history = state.history ?? [];
+    const messagesMarker = messagesMarkerFor(history, cacheableById);
     if (messagesMarker)
         markers.push(messagesMarker);
+    const prefixCacheable = perSlot.system.every((e) => e.cacheable) && perSlot.tools.every((e) => e.cacheable);
+    const tail = conversationTailMarker(history, cacheableById, prefixCacheable);
+    if (tail && tail.boundaryIndex !== messagesMarker?.boundaryIndex)
+        markers.push(tail);
     return markers;
 }
 exports.computeCacheMarkers = computeCacheMarkers;
+/**
+ * The moving breakpoint — the conversation's LAST message, marked.
+ *
+ * An agent loop sends the whole conversation on every call and only ever
+ * appends to it (the window stage is its one writer; a compaction is the
+ * rare exception and simply misses once). So everything up to this call's
+ * last message is the next call's prefix, byte for byte, and a breakpoint
+ * here lets the next call read it back instead of paying for it again. The
+ * index is a position in `history`, which is where `callLLM` puts the
+ * conversation — request-only lines (the staged-refs nudge, the time line,
+ * the evidence conclusion) are appended AFTER it and are never inside the
+ * cached prefix, so a line that is gone on the next call cannot break it.
+ *
+ * Placed only when the prefix before the conversation is cacheable this
+ * iteration — every system and tools entry (`prefixCacheable`) — and every
+ * message an injection delivered into the conversation is too: on a
+ * breakpoint wire this marker covers all of them, and marking past a piece
+ * its policy calls volatile would write a cache entry the next call cannot
+ * read. Fail-closed, like every other unknown in this file.
+ */
+function conversationTailMarker(history, cacheableById, prefixCacheable) {
+    if (!prefixCacheable || history.length === 0)
+        return undefined;
+    for (const m of history) {
+        const by = m.injectedBy;
+        if (by !== undefined && cacheableById.get(by.injectionId) !== true)
+            return undefined;
+    }
+    const boundary = history.length - 1;
+    return {
+        field: 'messages',
+        boundaryIndex: boundary,
+        ttl: 'short',
+        reason: `conversation tail through wire index ${boundary} — the moving breakpoint: the next ` +
+            'call repeats this prefix and appends after it',
+    };
+}
 /**
  * The `messages` marker, computed against the ACTUAL wire array (7.21).
  *
@@ -206,26 +259,31 @@ function messagesMarkerFor(history, cacheableById) {
     };
 }
 /**
- * The decision stage function. Thin scope-binding wrapper around
- * `computeCacheMarkers`. Exported so it can serve as the ROOT stage of
- * the `sf-cache` subflow (a chart cannot start with a nested subflow),
- * while `cacheDecisionSubflow` below still wraps the SAME function for
- * standalone use — no logic duplication.
+ * The decision stage, built for one chart. Thin scope-binding wrapper around
+ * `computeCacheMarkers`, so it can serve as the ROOT stage of the `sf-cache`
+ * subflow (a chart cannot start with a nested subflow) — no logic
+ * duplication.
  */
-function decideCacheMarkers(scope) {
-    scope.cacheMarkers = computeCacheMarkers({
-        activeInjections: scope.activeInjections,
-        iteration: scope.iteration,
-        maxIterations: scope.maxIterations,
-        userMessage: scope.userMessage,
-        ...(scope.lastToolName !== undefined && { lastToolName: scope.lastToolName }),
-        cumulativeInputTokens: scope.cumulativeInputTokens,
-        systemPromptCachePolicy: scope.systemPromptCachePolicy,
-        cachingDisabled: scope.cachingDisabled,
-        ...(scope.history !== undefined && { history: scope.history }),
-    });
+function cacheDecisionStage(options = {}) {
+    const toolsVaryPerCall = options.toolsVaryPerCall === true;
+    return (scope) => {
+        scope.cacheMarkers = computeCacheMarkers({
+            activeInjections: scope.activeInjections,
+            iteration: scope.iteration,
+            maxIterations: scope.maxIterations,
+            userMessage: scope.userMessage,
+            ...(scope.lastToolName !== undefined && { lastToolName: scope.lastToolName }),
+            cumulativeInputTokens: scope.cumulativeInputTokens,
+            systemPromptCachePolicy: scope.systemPromptCachePolicy,
+            cachingDisabled: scope.cachingDisabled,
+            ...(scope.history !== undefined && { history: scope.history }),
+            ...(toolsVaryPerCall && { toolsVaryPerCall: true }),
+        });
+    };
 }
-exports.decideCacheMarkers = decideCacheMarkers;
+exports.cacheDecisionStage = cacheDecisionStage;
+/** The decision stage for a chart whose tool schemas are stable per call. */
+exports.decideCacheMarkers = cacheDecisionStage();
 // NOTE: the cache decision is now the ROOT stage of the `sf-cache` subflow
 // (see core/agent/buildCacheSubflow.ts) via the exported `decideCacheMarkers`
 // above. The former standalone `cacheDecisionSubflow` FlowChart export was

package/dist/cache/CacheDecisionSubflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"CacheDecisionSubflow.js","sourceRoot":"","sources":["../../src/cache/CacheDecisionSubflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CacheDecisionSubflow.js","sourceRoot":"","sources":["../../src/cache/CacheDecisionSubflow.ts"],"names":[],"mappings":"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"}

package/dist/cache/cacheStrategyFor.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * cacheStrategyFor — the cache strategy for a provider, chosen from what the
+ * provider DECLARES (`LLMProvider.promptCaching`), never from its name.
+ *
+ * Pattern: Strategy, selected by capability. The provider adapter declares
+ *          how its wire caches (`'breakpoints'` | `'automatic'` | absent);
+ *          this function maps the declaration to the one strategy that
+ *          serves it.
+ * Role:    the ONE place an agent's cache strategy is chosen (`Agent`, and a
+ *          skill brain whose provider differs from the agent's).
+ *
+ * Why not by name: the name is a label, and labels get rewritten. The
+ * registry this replaces keyed strategies by `provider.name`, so every
+ * decorator that renamed its provider — `withRetry` (`anthropic+retry`),
+ * `withFallback` (`a|b`), an application's own routing wrapper
+ * (`my-app/anthropic`) — silently fell through to the no-op strategy: no
+ * cache markers, every call at full input price, and nothing in the run to
+ * say why. A wrapper that forwards the declaration (the library's three
+ * decorators do) caches exactly like the adapter it wraps.
+ *
+ * @example
+ * ```ts
+ * import { cacheStrategyFor } from 'agentfootprint/cache';
+ * import { withRetry } from 'agentfootprint/resilience';
+ * import { anthropic } from 'agentfootprint/providers';
+ *
+ * cacheStrategyFor(withRetry(anthropic())).name; // 'breakpoints'
+ * cacheStrategyFor({ name: 'x', complete }).name; // 'none' — nothing declared
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheStrategyFor = void 0;
+const AutomaticCacheStrategy_js_1 = require("./strategies/AutomaticCacheStrategy.js");
+const BreakpointCacheStrategy_js_1 = require("./strategies/BreakpointCacheStrategy.js");
+const NoOpCacheStrategy_js_1 = require("./strategies/NoOpCacheStrategy.js");
+/** One shared instance: the no-op strategy holds no state. */
+const NO_CACHING = new NoOpCacheStrategy_js_1.NoOpCacheStrategy();
+/**
+ * The strategy that serves `provider`'s declared prompt caching.
+ *
+ * @throws TypeError when the declaration is malformed (an unknown `mode`, a
+ *   `maxBreakpoints` that is not a positive integer, a non-boolean
+ *   `reportsUsage`) — refused at agent build, by provider name. A typo that
+ *   quietly fell back to "no caching" would be the very failure this
+ *   function exists to end.
+ */
+function cacheStrategyFor(provider) {
+    const declared = provider.promptCaching;
+    if (declared === undefined)
+        return NO_CACHING;
+    const who = `the '${provider.name}' provider`;
+    assertDeclaration(declared, who);
+    return declared.mode === 'breakpoints'
+        ? new BreakpointCacheStrategy_js_1.BreakpointCacheStrategy(declared, who)
+        : new AutomaticCacheStrategy_js_1.AutomaticCacheStrategy(declared, who);
+}
+exports.cacheStrategyFor = cacheStrategyFor;
+function assertDeclaration(declared, who) {
+    const shape = declared;
+    const refuse = (what) => {
+        throw new TypeError(`${who} declares promptCaching ${what}. Declare { mode: 'breakpoints', maxBreakpoints, ` +
+            "reportsUsage } or { mode: 'automatic', reportsUsage } — or leave promptCaching out " +
+            'if the provider does no caching the agent can drive.');
+    };
+    if (shape.mode !== 'breakpoints' && shape.mode !== 'automatic') {
+        refuse(`with mode ${JSON.stringify(shape.mode)}`);
+    }
+    if (shape.mode === 'breakpoints' &&
+        !(Number.isInteger(shape.maxBreakpoints) && shape.maxBreakpoints > 0)) {
+        refuse(`with maxBreakpoints ${JSON.stringify(shape.maxBreakpoints)} (a positive integer)`);
+    }
+    if (typeof shape.reportsUsage !== 'boolean') {
+        refuse(`with reportsUsage ${JSON.stringify(shape.reportsUsage)} (true or false)`);
+    }
+}
+//# sourceMappingURL=cacheStrategyFor.js.map

package/dist/cache/cacheStrategyFor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheStrategyFor.js","sourceRoot":"","sources":["../../src/cache/cacheStrategyFor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAIH,sFAAgF;AAChF,wFAAkF;AAClF,4EAAsE;AAEtE,8DAA8D;AAC9D,MAAM,UAAU,GAAG,IAAI,wCAAiB,EAAE,CAAC;AAE3C;;;;;;;;GAQG;AACH,SAAgB,gBAAgB,CAC9B,QAAqD;IAErD,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC;IACxC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC9C,MAAM,GAAG,GAAG,QAAQ,QAAQ,CAAC,IAAI,YAAY,CAAC;IAC9C,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACjC,OAAO,QAAQ,CAAC,IAAI,KAAK,aAAa;QACpC,CAAC,CAAC,IAAI,oDAAuB,CAAC,QAAQ,EAAE,GAAG,CAAC;QAC5C,CAAC,CAAC,IAAI,kDAAsB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;AAVD,4CAUC;AAED,SAAS,iBAAiB,CAAC,QAAuB,EAAE,GAAW;IAC7D,MAAM,KAAK,GAAG,QAAgF,CAAC;IAC/F,MAAM,MAAM,GAAG,CAAC,IAAY,EAAS,EAAE;QACrC,MAAM,IAAI,SAAS,CACjB,GAAG,GAAG,2BAA2B,IAAI,mDAAmD;YACtF,qFAAqF;YACrF,sDAAsD,CACzD,CAAC;IACJ,CAAC,CAAC;IACF,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC/D,MAAM,CAAC,aAAa,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,IACE,KAAK,CAAC,IAAI,KAAK,aAAa;QAC5B,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC,IAAK,KAAK,CAAC,cAAyB,GAAG,CAAC,CAAC,EACjF,CAAC;QACD,MAAM,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC,uBAAuB,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAC5C,MAAM,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY,CAAC,kBAAkB,CAAC,CAAC;IACpF,CAAC;AACH,CAAC"}

package/dist/cache/index.js

@@ -1,36 +1,27 @@
 "use strict";
 /**
- * agentfootprint/cache — public surface for the cache layer (v2.6+).
+ * agentfootprint/cache — public surface for the cache layer.
  *
- * 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') — the one
- *     end-to-end strategy: the adapter sends markers AND reads cache usage
- *   - OpenAICacheStrategy ('openai', 'browser-openai') — pass-through
- *     (OpenAI auto-caches); reports `not-applicable` metrics until the
- *     adapter lifts `prompt_tokens_details.cached_tokens` onto the port
- *   - BedrockCacheStrategy ('bedrock') — `enabled: false`; the Bedrock
- *     adapter implements neither half of the cache contract
- *
- * Future strategies:
- *   - GeminiCacheStrategy (async handle-based)
+ * The strategy an agent runs is chosen by CAPABILITY: the provider adapter
+ * declares how its wire caches (`LLMProvider.promptCaching`) and
+ * `cacheStrategyFor(provider)` returns the one strategy that serves it —
+ *   - `BreakpointCacheStrategy` — `mode: 'breakpoints'` (Anthropic's
+ *     `cache_control`; `anthropic()`, `browserAnthropic()`);
+ *   - `AutomaticCacheStrategy` — `mode: 'automatic'` (OpenAI and Azure
+ *     OpenAI cache on their own);
+ *   - `NoOpCacheStrategy` — nothing declared (Mock, Ollama, Bedrock Converse,
+ *     Gemini, any adapter that has not said).
+ * Nothing registers at module load and nothing is keyed by provider name, so
+ * a decorator that renames its provider keeps caching by forwarding the
+ * declaration.
  *
  * Public types (re-exported for consumers):
- *   - CachePolicy, CacheMarker, CacheStrategy, CacheCapabilities,
- *     CacheMetrics, CachePolicyContext, CacheStrategyContext
+ *   - PromptCaching (the provider's declaration), CachePolicy, CacheMarker,
+ *     CacheStrategy, CacheMetrics, CachePolicyContext, CacheStrategyContext,
+ *     CacheUsage
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cacheRecorder = exports.BedrockCacheStrategy = exports.OpenAICacheStrategy = exports.AnthropicCacheStrategy = exports.NoOpCacheStrategy = exports.listRegisteredStrategies = exports.registerCacheStrategy = exports.getDefaultCacheStrategy = exports.describeClaim = exports.valueOr = exports.isKnown = exports.notApplicable = exports.unknown = exports.known = void 0;
-// Side-effect imports — register strategies on module load.
-require("./strategies/AnthropicCacheStrategy.js");
-require("./strategies/OpenAICacheStrategy.js");
-require("./strategies/BedrockCacheStrategy.js");
+exports.cacheRecorder = exports.AutomaticCacheStrategy = exports.BreakpointCacheStrategy = exports.NoOpCacheStrategy = exports.cacheStrategyFor = exports.describeClaim = exports.valueOr = exports.isKnown = exports.notApplicable = exports.unknown = exports.known = void 0;
 // The honesty primitive the meter is typed in (9.59.0). Re-exported
 // reference-equal from `src/lib/claim/` — the SAME symbols
 // `agentfootprint/maps` exports, so `known` from either door is one function.
@@ -41,20 +32,17 @@ Object.defineProperty(exports, "notApplicable", { enumerable: true, get: functio
 Object.defineProperty(exports, "isKnown", { enumerable: true, get: function () { return claim_js_1.isKnown; } });
 Object.defineProperty(exports, "valueOr", { enumerable: true, get: function () { return claim_js_1.valueOr; } });
 Object.defineProperty(exports, "describeClaim", { enumerable: true, get: function () { return claim_js_1.describeClaim; } });
-// Strategy registry
-var strategyRegistry_js_1 = require("./strategyRegistry.js");
-Object.defineProperty(exports, "getDefaultCacheStrategy", { enumerable: true, get: function () { return strategyRegistry_js_1.getDefaultCacheStrategy; } });
-Object.defineProperty(exports, "registerCacheStrategy", { enumerable: true, get: function () { return strategyRegistry_js_1.registerCacheStrategy; } });
-Object.defineProperty(exports, "listRegisteredStrategies", { enumerable: true, get: function () { return strategyRegistry_js_1.listRegisteredStrategies; } });
-// Built-in strategy classes (for consumers who want explicit overrides)
+// Strategy selection — by the provider's declared capability, never its name
+var cacheStrategyFor_js_1 = require("./cacheStrategyFor.js");
+Object.defineProperty(exports, "cacheStrategyFor", { enumerable: true, get: function () { return cacheStrategyFor_js_1.cacheStrategyFor; } });
+// Built-in strategy classes (for consumers who want explicit overrides via
+// `Agent.create({ cacheStrategy })`)
 var NoOpCacheStrategy_js_1 = require("./strategies/NoOpCacheStrategy.js");
 Object.defineProperty(exports, "NoOpCacheStrategy", { enumerable: true, get: function () { return NoOpCacheStrategy_js_1.NoOpCacheStrategy; } });
-var AnthropicCacheStrategy_js_1 = require("./strategies/AnthropicCacheStrategy.js");
-Object.defineProperty(exports, "AnthropicCacheStrategy", { enumerable: true, get: function () { return AnthropicCacheStrategy_js_1.AnthropicCacheStrategy; } });
-var OpenAICacheStrategy_js_1 = require("./strategies/OpenAICacheStrategy.js");
-Object.defineProperty(exports, "OpenAICacheStrategy", { enumerable: true, get: function () { return OpenAICacheStrategy_js_1.OpenAICacheStrategy; } });
-var BedrockCacheStrategy_js_1 = require("./strategies/BedrockCacheStrategy.js");
-Object.defineProperty(exports, "BedrockCacheStrategy", { enumerable: true, get: function () { return BedrockCacheStrategy_js_1.BedrockCacheStrategy; } });
+var BreakpointCacheStrategy_js_1 = require("./strategies/BreakpointCacheStrategy.js");
+Object.defineProperty(exports, "BreakpointCacheStrategy", { enumerable: true, get: function () { return BreakpointCacheStrategy_js_1.BreakpointCacheStrategy; } });
+var AutomaticCacheStrategy_js_1 = require("./strategies/AutomaticCacheStrategy.js");
+Object.defineProperty(exports, "AutomaticCacheStrategy", { enumerable: true, get: function () { return AutomaticCacheStrategy_js_1.AutomaticCacheStrategy; } });
 // Recorder
 var cacheRecorder_js_1 = require("./cacheRecorder.js");
 Object.defineProperty(exports, "cacheRecorder", { enumerable: true, get: function () { return cacheRecorder_js_1.cacheRecorder; } });

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAEH,4DAA4D;AAC5D,kDAAgD;AAChD,+CAA6C;AAC7C,gDAA8C;AAc9C,oEAAoE;AACpE,2DAA2D;AAC3D,8EAA8E;AAC9E,kDAQ+B;AAP7B,iGAAA,KAAK,OAAA;AACL,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,mGAAA,OAAO,OAAA;AACP,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AAIf,oBAAoB;AACpB,6DAI+B;AAH7B,8HAAA,uBAAuB,OAAA;AACvB,4HAAA,qBAAqB,OAAA;AACrB,+HAAA,wBAAwB,OAAA;AAG1B,wEAAwE;AACxE,0EAAsE;AAA7D,yHAAA,iBAAiB,OAAA;AAC1B,oFAAgF;AAAvE,mIAAA,sBAAsB,OAAA;AAC/B,8EAA0E;AAAjE,6HAAA,mBAAmB,OAAA;AAC5B,gFAA4E;AAAnE,+HAAA,oBAAoB,OAAA;AAE7B,WAAW;AACX,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAeH,oEAAoE;AACpE,2DAA2D;AAC3D,8EAA8E;AAC9E,kDAQ+B;AAP7B,iGAAA,KAAK,OAAA;AACL,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,mGAAA,OAAO,OAAA;AACP,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AAIf,6EAA6E;AAC7E,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AAEzB,2EAA2E;AAC3E,qCAAqC;AACrC,0EAAsE;AAA7D,yHAAA,iBAAiB,OAAA;AAC1B,sFAAkF;AAAzE,qIAAA,uBAAuB,OAAA;AAChC,oFAAgF;AAAvE,mIAAA,sBAAsB,OAAA;AAE/B,WAAW;AACX,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}

package/dist/cache/strategies/AutomaticCacheStrategy.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * AutomaticCacheStrategy — for a provider that caches repeated prefixes on
+ * its own (`promptCaching.mode: 'automatic'`; OpenAI, Azure OpenAI).
+ *
+ * Chosen by CAPABILITY (`cacheStrategyFor`), never by provider name.
+ *
+ *   - **prepareRequest**: pass-through. The provider decides what to cache;
+ *     a marker would mean nothing on its wire. The `cache:` policies on
+ *     injections still matter — they travel with the agent and take effect
+ *     the moment it runs on a breakpoint provider — but here they have no
+ *     local effect, and `cache: 'never'` cannot stop the provider caching.
+ *   - **extractMetrics**: the port usage when the adapter declares it
+ *     reports cache tokens; `not applicable` when it declares it does not
+ *     (the OpenAI adapter does not lift `prompt_tokens_details.cached_tokens`
+ *     yet — named, rather than hidden behind a per-call `unknown` that would
+ *     suggest the measurement was attempted).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutomaticCacheStrategy = void 0;
+const claim_js_1 = require("../../lib/claim/claim.js");
+const portUsage_js_1 = require("../portUsage.js");
+class AutomaticCacheStrategy {
+    name = 'automatic';
+    reportsUsage;
+    who;
+    /**
+     * @param declared  the provider's `promptCaching` declaration
+     * @param who       names the adapter in the meter's evidence sentences
+     */
+    constructor(declared, who = 'the provider') {
+        this.reportsUsage = declared.reportsUsage;
+        this.who = who;
+    }
+    async prepareRequest(req, _candidates, _ctx) {
+        return { request: req, markersApplied: [] };
+    }
+    extractMetrics(usage) {
+        if (!this.reportsUsage) {
+            return (0, claim_js_1.notApplicable)(`${this.who} caches automatically but declares that it does not report cache ` +
+                'token counts (promptCaching.reportsUsage: false)');
+        }
+        return (0, portUsage_js_1.readPortCacheUsage)(usage, this.who);
+    }
+}
+exports.AutomaticCacheStrategy = AutomaticCacheStrategy;
+//# sourceMappingURL=AutomaticCacheStrategy.js.map

package/dist/cache/strategies/AutomaticCacheStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutomaticCacheStrategy.js","sourceRoot":"","sources":["../../../src/cache/strategies/AutomaticCacheStrategy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAUH,uDAAqE;AACrE,kDAAqD;AAGrD,MAAa,sBAAsB;IACxB,IAAI,GAAG,WAAW,CAAC;IACX,YAAY,CAAU;IACtB,GAAG,CAAS;IAE7B;;;OAGG;IACH,YAAY,QAAuD,EAAE,GAAG,GAAG,cAAc;QACvF,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;QAC1C,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,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,KAA6B;QAC1C,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO,IAAA,wBAAa,EAClB,GAAG,IAAI,CAAC,GAAG,mEAAmE;gBAC5E,kDAAkD,CACrD,CAAC;QACJ,CAAC;QACD,OAAO,IAAA,iCAAkB,EAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;CACF;AAlCD,wDAkCC"}

package/dist/cache/strategies/BreakpointCacheStrategy.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * BreakpointCacheStrategy — for a provider that caches a prefix only where
+ * the request marks it (`promptCaching.mode: 'breakpoints'`; Anthropic's
+ * `cache_control`).
+ *
+ * Chosen by CAPABILITY (`cacheStrategyFor`), never by provider name: built
+ * from the provider's own declaration, so `withRetry(anthropic())` or an
+ * application's routing wrapper caches exactly like the adapter it wraps.
+ *
+ * What it DOES:
+ *   - clamp the candidate markers to the declared `maxBreakpoints`, keeping
+ *     the first N in slot order (the most stable prefixes first);
+ *   - put them on `LLMRequest.cacheMarkers`, where the adapter reads them;
+ *   - read cache metrics off the PORT usage the adapter normalised —
+ *     `not applicable` when the declaration says the adapter reports none.
+ * What it does NOT: touch the wire. The adapter owns `cache_control`
+ * (`adapters/llm/anthropicCacheWire.ts`), and content is never edited.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BreakpointCacheStrategy = void 0;
+const claim_js_1 = require("../../lib/claim/claim.js");
+const portUsage_js_1 = require("../portUsage.js");
+class BreakpointCacheStrategy {
+    name = 'breakpoints';
+    maxBreakpoints;
+    reportsUsage;
+    who;
+    /**
+     * @param declared  the provider's `promptCaching` declaration
+     * @param who       names the adapter in the meter's evidence sentences,
+     *                  e.g. `"the 'anthropic' provider"`
+     */
+    constructor(declared, who = 'the provider') {
+        this.maxBreakpoints = declared.maxBreakpoints;
+        this.reportsUsage = declared.reportsUsage;
+        this.who = who;
+    }
+    async prepareRequest(req, candidates, ctx) {
+        // The agent-side kill switch, honoured here too: the CacheGate should
+        // already have emptied the candidates, but a buggy gate must not be able
+        // to put markers on a request whose run said caching is off.
+        if (ctx.cachingDisabled || candidates.length === 0) {
+            return { request: req, markersApplied: [] };
+        }
+        const markersApplied = candidates.length <= this.maxBreakpoints
+            ? candidates
+            : candidates.slice(0, this.maxBreakpoints);
+        return { request: { ...req, cacheMarkers: markersApplied }, markersApplied };
+    }
+    extractMetrics(usage) {
+        if (!this.reportsUsage) {
+            return (0, claim_js_1.notApplicable)(`${this.who} declares that it does not report cache token counts ` +
+                '(promptCaching.reportsUsage: false)');
+        }
+        return (0, portUsage_js_1.readPortCacheUsage)(usage, this.who);
+    }
+}
+exports.BreakpointCacheStrategy = BreakpointCacheStrategy;
+//# sourceMappingURL=BreakpointCacheStrategy.js.map

package/dist/cache/strategies/BreakpointCacheStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BreakpointCacheStrategy.js","sourceRoot":"","sources":["../../../src/cache/strategies/BreakpointCacheStrategy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAUH,uDAAqE;AACrE,kDAAqD;AAGrD,MAAa,uBAAuB;IACzB,IAAI,GAAG,aAAa,CAAC;IACb,cAAc,CAAS;IACvB,YAAY,CAAU;IACtB,GAAG,CAAS;IAE7B;;;;OAIG;IACH,YAAY,QAAyD,EAAE,GAAG,GAAG,cAAc;QACzF,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC,cAAc,CAAC;QAC9C,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;QAC1C,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,GAAe,EACf,UAAkC,EAClC,GAAyB;QAKzB,sEAAsE;QACtE,yEAAyE;QACzE,6DAA6D;QAC7D,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,MAAM,cAAc,GAClB,UAAU,CAAC,MAAM,IAAI,IAAI,CAAC,cAAc;YACtC,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/C,OAAO,EAAE,OAAO,EAAE,EAAE,GAAG,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE,EAAE,cAAc,EAAE,CAAC;IAC/E,CAAC;IAED,cAAc,CAAC,KAA6B;QAC1C,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO,IAAA,wBAAa,EAClB,GAAG,IAAI,CAAC,GAAG,uDAAuD;gBAChE,qCAAqC,CACxC,CAAC;QACJ,CAAC;QACD,OAAO,IAAA,iCAAkB,EAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;CACF;AA/CD,0DA+CC"}

package/dist/cache/strategies/NoOpCacheStrategy.js

@@ -1,40 +1,24 @@
 "use strict";
 /**
- * NoOpCacheStrategy — fallback strategy for providers without cache
- * support (Mock, unknown providers, intentional opt-out).
+ * NoOpCacheStrategy — for a provider that declares no prompt caching
+ * (`LLMProvider.promptCaching` absent): Mock, Ollama, Bedrock Converse,
+ * any adapter that has not said, or an 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.
+ * Returns the request unchanged and reports *not applicable* — never a zero.
+ * Chosen by `cacheStrategyFor` when the declaration is absent; one shared
+ * instance serves every such provider (it holds no state).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NoOpCacheStrategy = void 0;
 const claim_js_1 = require("../../lib/claim/claim.js");
-const NOOP_CAPABILITIES = Object.freeze({
-    enabled: false,
-    maxMarkers: 0,
-    ttls: [],
-    fields: [],
-    automatic: false,
-});
 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;
+    name = 'none';
     async prepareRequest(req, _candidates, _ctx) {
         return { request: req, markersApplied: [] };
     }
     extractMetrics(_usage) {
-        return (0, claim_js_1.notApplicable)('the NoOp strategy stands in for providers with no cache reporting at all');
+        return (0, claim_js_1.notApplicable)('the provider declares no prompt caching (LLMProvider.promptCaching is absent), so no ' +
+            'cache traffic is driven or reported');
     }
 }
 exports.NoOpCacheStrategy = NoOpCacheStrategy;

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

@@ -1 +1 @@
-{"version":3,"file":"NoOpCacheStrategy.js","sourceRoot":"","sources":["../../../src/cache/strategies/NoOpCacheStrategy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAUH,uDAAqE;AAGrE,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,MAAa,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,MAA8B;QAC3C,OAAO,IAAA,wBAAa,EAClB,0EAA0E,CAC3E,CAAC;IACJ,CAAC;CACF;AAzBD,8CAyBC"}
+{"version":3,"file":"NoOpCacheStrategy.js","sourceRoot":"","sources":["../../../src/cache/strategies/NoOpCacheStrategy.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AASH,uDAAqE;AAGrE,MAAa,iBAAiB;IACnB,IAAI,GAAG,MAAM,CAAC;IAEvB,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,MAA8B;QAC3C,OAAO,IAAA,wBAAa,EAClB,uFAAuF;YACrF,qCAAqC,CACxC,CAAC;IACJ,CAAC;CACF;AApBD,8CAoBC"}

package/dist/cache/types.js

@@ -12,10 +12,11 @@
  *      `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.
+ *   3. STRATEGY — one `CacheStrategy` per CAPABILITY, chosen from what the
+ *      provider DECLARES (`LLMProvider.promptCaching`), never from its name:
+ *      explicit breakpoints, automatic prefix caching, or none. Decides
+ *      which markers reach the request AND reads cache metrics off the
+ *      port usage. The adapter owns the wire format.
  *
  * The interfaces are read-only / immutable by convention. Strategies
  * MUST be stateless across runs; per-run state lives in the

package/dist/cache/types.js.map

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