agentfootprint 9.58.0 → 9.59.1

package/CLAUDE.md

@@ -43,7 +43,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | letting the UI draw an artifact without the model naming a component | `registerArtifactComponent` (in the `agentfootprint-lens` package) | — | — |
 | finding which tools the model keeps writing by hand | `agentfootprint.tools.code_run` + `codeShape` | `src/core/codeRunnerTool.ts` | 9.46.0 |
 | a skill wrongly activated by a keyword staying loaded for the whole turn — suspending/parking a map's prompt + tools when its contribution goes unused, WITHOUT touching its cursor, and re-engaging it on evidence | `.maps()` + `advanceEngagement` + `agentfootprint.map.engaged/parked` + skip reason `'parked'` | `src/maps/` | 9.58.0 |
-| a value that must say how it knows itself — an unknown count that can never render as zero | `Claim<T>` (`known`/`unknown`/`notApplicable`) | `src/maps/claim/claim.ts` | 9.58.0 |
+| a value that must say how it knows itself — an unknown count that can never render as zero | `Claim<T>` (`known`/`unknown`/`notApplicable`) | `src/lib/claim/claim.ts` | 9.58.0 |
 | a tool answering "I looked and found nothing", routably | `absent` | `src/core/agent/coverage/absent.ts` | 9.43.0 |
 | stating what a clean answer does NOT rule out | `coverage` | `src/core/agent/coverage/ledger.ts` | 9.43.0 |
 | proving a session store really honours the port | `runSessionLifecycleConformance` | `src/hosting/conformance/` | 9.37.0 |

package/dist/cache/cacheRecorder.js

@@ -1,35 +1,72 @@
 "use strict";
 /**
- * cacheRecorder() — observability for the v2.6 cache layer.
+ * cacheRecorder() — the cache layer's meter.
  *
  * 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).
+ *   - `FlowRecorder.onDecision` — CacheGate routing decisions
+ *     (apply-markers / no-markers + the rule that fired + evidence from
+ *     `decide()`).
+ *   - `agentfootprint.stream.llm_end` — reads that event's `usage` (the PORT
+ *     shape: `{ input, output, cacheRead?, cacheWrite? }`) and asks the
+ *     agent's `CacheStrategy.extractMetrics` what is known about it.
  *
- * 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
+ * Produces: a per-turn report via `recorder.report()` — token tallies, hit
+ * rate and dollar estimates, each carried as a `Claim` so an UNMEASURED turn
+ * can never render as a zero one.
  *
- * 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).
+ * ── Why every number here is a Claim (9.59.0) ─────────────────────────
+ * The shipped 9.58.0 meter reported `hitRate: 0` for a 20-call turn that hit
+ * cache on every call. Two faults, and the second is why the first went
+ * unnoticed for so long: (1) the strategies parsed RAW WIRE field names off a
+ * value that carries the PORT shape, so every field read `undefined`; (2) the
+ * report typed its aggregates as bare `number`, so "nobody measured" and
+ * "measured, and it was zero" rendered identically. Fixing (1) alone would
+ * have left a meter that still cannot say "unmeasured" — hence `Claim<T>`,
+ * plus `measuredIterations` / `unmeasuredIterations` so a rate computed from
+ * 3 of 20 calls states its own denominator.
+ *
+ * Read the number through `isKnown(report.hitRate)` (or `describeClaim` for a
+ * one-line render). There is deliberately no door that hands you a bare
+ * number without your having branched.
+ *
+ * ── And an unknown carries ITS OWN reason (9.59.1) ────────────────────
+ * 9.59.0 enforced that law per call and then broke it in `report()`, which
+ * hardcoded "the provider reported no cache fields" for the whole turn no
+ * matter what the rows said. With no strategy passed and a provider that DID
+ * report cache fields, the row said "nothing read the usage" and the summary
+ * blamed the provider — pointing the reader away from their actual mistake.
+ * The summary now carries the rows' own reasons, and says so plainly when the
+ * rows disagree rather than picking one.
+ *
+ * ── What this recorder does NOT do ────────────────────────────────────
+ * It emits no events. (Earlier prose here promised per-iteration
+ * `agentfootprint.cache.applied` / `agentfootprint.cache.metrics` events;
+ * neither name has ever existed in the event registry and no `typedEmit` has
+ * ever been in this file. The prose was the bug.)
+ *
+ * It does not write `scope.recentHitRate` back into agent state either, so
+ * CacheGate's hit-rate-floor rule never fires on its own — the loop is
+ * severed at both ends (the key is seeded `undefined` and written by
+ * nothing). Recorders do not write to chart scope, so closing that loop needs
+ * an agent-side accessor convention; it is separable work from measuring the
+ * number, which is what this file now does.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cacheRecorder = void 0;
 const trace_1 = require("footprintjs/trace");
 const conventions_js_1 = require("../conventions.js");
+const claim_js_1 = require("../lib/claim/claim.js");
+/**
+ * How many distinct reasons a disagreeing summary spells out before it
+ * switches to counting the rest. A summary sentence must stay readable.
+ */
+const MAX_LISTED_REASONS = 3;
+/** The metrics of a row already filtered by `isKnown`. Narrowing helper only. */
+function valueOfMetrics(entry) {
+    return (0, claim_js_1.isKnown)(entry.metrics)
+        ? entry.metrics.value
+        : { cacheReadTokens: 0, cacheWriteTokens: 0, freshInputTokens: 0 };
+}
 function cacheRecorder(options = {}) {
     const perIter = [];
     let lastDecision;
@@ -64,8 +101,11 @@ function cacheRecorder(options = {}) {
             if (event.type !== 'agentfootprint.stream.llm_end')
                 return;
             iterationCounter++;
+            // The PORT shape, which is the only shape this event has ever carried.
             const usage = event.payload.usage;
-            const metrics = options.strategy?.extractMetrics(usage);
+            const metrics = options.strategy === undefined
+                ? (0, claim_js_1.unknown)('no CacheStrategy was given to cacheRecorder(), so nothing read the usage')
+                : options.strategy.extractMetrics(usage);
             const branch = lastDecision?.branch ?? 'apply-markers';
             // Compute dollar math:
             //   spent = freshInput * inputPrice
@@ -73,21 +113,34 @@ function cacheRecorder(options = {}) {
             //         + cacheWrite * cacheWritePrice
             //   no-cache cost = (freshInput + cacheRead + cacheWrite) * inputPrice
             //   saved        = no-cache cost - spent
-            let dollarsSpent = 0;
-            let savedVsNoCache = 0;
-            if (metrics) {
-                dollarsSpent =
-                    dollars(metrics.freshInputTokens, 'input') +
-                        dollars(metrics.cacheReadTokens, 'cacheRead') +
-                        dollars(metrics.cacheWriteTokens, 'cacheWrite');
-                const noCacheCost = dollars(metrics.freshInputTokens + metrics.cacheReadTokens + metrics.cacheWriteTokens, 'input');
-                savedVsNoCache = noCacheCost - dollarsSpent;
+            let dollarsSpent;
+            let savedVsNoCache;
+            if ((0, claim_js_1.isKnown)(metrics)) {
+                const m = metrics.value;
+                const spent = dollars(m.freshInputTokens, 'input') +
+                    dollars(m.cacheReadTokens, 'cacheRead') +
+                    dollars(m.cacheWriteTokens, 'cacheWrite');
+                const noCacheCost = dollars(m.freshInputTokens + m.cacheReadTokens + m.cacheWriteTokens, 'input');
+                const ev = options.pricing === undefined
+                    ? 'measured tokens, but no PricingTable was given — every price is 0'
+                    : 'measured tokens priced with the given PricingTable';
+                dollarsSpent = (0, claim_js_1.known)(spent, ev);
+                savedVsNoCache = (0, claim_js_1.known)(noCacheCost - spent, ev);
+            }
+            else {
+                // No tokens measured ⇒ no dollars. Carrying the metrics claim's own
+                // reason forward is what keeps a $0 estimate from reading as "free".
+                const why = metrics.kind === 'unknown'
+                    ? metrics.reason
+                    : `no cache tokens are measurable here — ${metrics.evidence}`;
+                dollarsSpent = (0, claim_js_1.unknown)(why);
+                savedVsNoCache = (0, claim_js_1.unknown)(why);
             }
             const entry = {
                 iteration: iterationCounter,
                 branch,
                 ...(lastDecision?.rule !== undefined && { rule: lastDecision.rule }),
-                ...(metrics !== undefined && { metrics }),
+                metrics,
                 dollarsSpent,
                 dollarsSavedVsNoCache: savedVsNoCache,
             };
@@ -97,23 +150,78 @@ function cacheRecorder(options = {}) {
         report() {
             const apply = perIter.filter((p) => p.branch === 'apply-markers').length;
             const skip = perIter.filter((p) => p.branch === 'no-markers').length;
-            const cacheRead = perIter.reduce((s, p) => s + (p.metrics?.cacheReadTokens ?? 0), 0);
-            const cacheWrite = perIter.reduce((s, p) => s + (p.metrics?.cacheWriteTokens ?? 0), 0);
-            const fresh = perIter.reduce((s, p) => s + (p.metrics?.freshInputTokens ?? 0), 0);
-            const totalRequest = cacheRead + cacheWrite + fresh;
-            const hitRate = totalRequest > 0 ? cacheRead / totalRequest : 0;
-            const dollarsSpent = perIter.reduce((s, p) => s + p.dollarsSpent, 0);
-            const dollarsSaved = perIter.reduce((s, p) => s + p.dollarsSavedVsNoCache, 0);
+            const measured = perIter.filter((p) => (0, claim_js_1.isKnown)(p.metrics));
+            const n = measured.length;
+            const total = perIter.length;
+            // ONE reason, stated once, reused by every claim below — so a reader
+            // who prints any single field learns why the whole report is empty.
+            //
+            // ── The summary CARRIES the rows' reasons; it never invents one (9.59.1)
+            // 9.59.0 hardcoded 'the provider reported no cache fields' here. That
+            // sentence is a fabrication whenever the rows said something else — most
+            // painfully when no CacheStrategy was passed and the provider DID report
+            // cacheRead/cacheWrite: the rows said "nothing read the usage", and the
+            // summary blamed the provider for the caller's own omission. An unknown
+            // must carry ITS OWN reason. That is the law this file exists to
+            // enforce, and this is it applied to the summary too.
+            const unmeasured = perIter.filter((p) => !(0, claim_js_1.isKnown)(p.metrics));
+            const reasons = [];
+            for (const row of unmeasured) {
+                const m = row.metrics;
+                // `unmeasured` already excluded 'known'; this narrows the type.
+                if ((0, claim_js_1.isKnown)(m))
+                    continue;
+                const stated = m.kind === 'not-applicable' ? `this provider cannot report it (${m.evidence})` : m.reason;
+                if (!reasons.includes(stated))
+                    reasons.push(stated);
+            }
+            // Rows can disagree — a turn may mix an adapter that cannot report with
+            // calls that carried no usage at all. Picking one silently would state a
+            // cause for calls that stated a different one, so the summary says there
+            // was more than one and lists them. Bounded by construction: at most
+            // MAX_LISTED_REASONS are spelled out and the remainder is COUNTED, so a
+            // strategy whose reason varies per call cannot grow this into a wall.
+            const listed = reasons.slice(0, MAX_LISTED_REASONS);
+            const remaining = reasons.length - listed.length;
+            const [onlyReason] = reasons;
+            const carried = reasons.length === 1 && onlyReason !== undefined
+                ? onlyReason
+                : `the calls did not agree on why — ${reasons.length} different reasons were ` +
+                    `given: ${listed.map((r, i) => `(${i + 1}) ${r}`).join('; ')}` +
+                    (remaining > 0 ? `; and ${remaining} more not listed here` : '');
+            const why = total === 0
+                ? 'no LLM call was observed, so there is nothing to measure'
+                : reasons.length === 0
+                    ? // Unreachable where `why` is USED (it is read only when nothing
+                        // was measured, and an unmeasured row always states a reason).
+                        `all ${total} observed call(s) reported cache usage`
+                    : `none of the ${total} observed call(s) reported cache usage — ${carried}`;
+            const evidence = `summed over the ${n} of ${total} call(s) whose usage was measured`;
+            const claimOf = (value) => n === 0 ? (0, claim_js_1.unknown)(why) : (0, claim_js_1.known)(value, evidence);
+            const cacheRead = measured.reduce((s2, p) => s2 + valueOfMetrics(p).cacheReadTokens, 0);
+            const cacheWrite = measured.reduce((s2, p) => s2 + valueOfMetrics(p).cacheWriteTokens, 0);
+            const fresh = measured.reduce((s2, p) => s2 + valueOfMetrics(p).freshInputTokens, 0);
+            const requestTotal = cacheRead + cacheWrite + fresh;
+            const dollarsSpent = measured.reduce((s2, p) => s2 + ((0, claim_js_1.isKnown)(p.dollarsSpent) ? p.dollarsSpent.value : 0), 0);
+            const dollarsSaved = measured.reduce((s2, p) => s2 + ((0, claim_js_1.isKnown)(p.dollarsSavedVsNoCache) ? p.dollarsSavedVsNoCache.value : 0), 0);
             return Object.freeze({
-                totalIterations: perIter.length,
+                totalIterations: total,
                 applyMarkersIterations: apply,
                 noMarkersIterations: skip,
-                cacheReadTokensTotal: cacheRead,
-                cacheWriteTokensTotal: cacheWrite,
-                freshInputTokensTotal: fresh,
-                hitRate,
-                estimatedDollarsSpent: dollarsSpent,
-                estimatedDollarsSavedVsNoCache: dollarsSaved,
+                measuredIterations: n,
+                unmeasuredIterations: total - n,
+                cacheReadTokensTotal: claimOf(cacheRead),
+                cacheWriteTokensTotal: claimOf(cacheWrite),
+                freshInputTokensTotal: claimOf(fresh),
+                // A measured turn with zero prompt tokens is not a thing; guard it
+                // anyway rather than divide by zero and hand back NaN as a rate.
+                hitRate: n === 0
+                    ? (0, claim_js_1.unknown)(why)
+                    : requestTotal === 0
+                        ? (0, claim_js_1.unknown)(`the ${n} measured call(s) reported 0 prompt tokens in total, so a hit rate has no denominator`)
+                        : (0, claim_js_1.known)(cacheRead / requestTotal, evidence),
+                estimatedDollarsSpent: claimOf(dollarsSpent),
+                estimatedDollarsSavedVsNoCache: claimOf(dollarsSaved),
                 perIter: Object.freeze([...perIter]),
             });
         },

package/dist/cache/cacheRecorder.js.map

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

package/dist/cache/index.js

@@ -10,23 +10,37 @@
  * Strategies registered as of v2.6:
  *   - NoOp (wildcard '*' fallback) — always available, registered by
  *     the registry module itself
- *   - AnthropicCacheStrategy ('anthropic', 'browser-anthropic')
+ *   - 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 (Phase 8+):
- *   - OpenAICacheStrategy
- *   - BedrockCacheStrategy
- *   - GeminiCacheStrategy (v2.7+, async handle-based)
+ * Future strategies:
+ *   - GeminiCacheStrategy (async handle-based)
  *
  * Public types (re-exported for consumers):
  *   - CachePolicy, CacheMarker, CacheStrategy, CacheCapabilities,
  *     CacheMetrics, CachePolicyContext, CacheStrategyContext
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cacheRecorder = exports.BedrockCacheStrategy = exports.OpenAICacheStrategy = exports.AnthropicCacheStrategy = exports.NoOpCacheStrategy = exports.listRegisteredStrategies = exports.registerCacheStrategy = exports.getDefaultCacheStrategy = void 0;
+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");
+// 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.
+var claim_js_1 = require("../lib/claim/claim.js");
+Object.defineProperty(exports, "known", { enumerable: true, get: function () { return claim_js_1.known; } });
+Object.defineProperty(exports, "unknown", { enumerable: true, get: function () { return claim_js_1.unknown; } });
+Object.defineProperty(exports, "notApplicable", { enumerable: true, get: function () { return claim_js_1.notApplicable; } });
+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; } });

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAEH,4DAA4D;AAC5D,kDAAgD;AAChD,+CAA6C;AAC7C,gDAA8C;AAa9C,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;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/cache/portUsage.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * The one reader of PORT-shaped usage for the cache meter.
+ *
+ * Pattern: pure function, one job. Given the `usage` the framework put on
+ *          `agentfootprint.stream.llm_end`, answer what is actually known
+ *          about cache traffic on that call.
+ * Role:    the honest half of the 9.59.0 meter fix. Before it, three
+ *          strategies each parsed RAW WIRE field names (`cache_read_input_tokens`,
+ *          `prompt_tokens_details.cached_tokens`) off a value that has never
+ *          carried them — the framework normalises the wire at the ADAPTER
+ *          ring (`readCacheUsage`) and only ever hands a strategy the port
+ *          shape. Every field read `undefined`, `?? 0` turned that into a
+ *          zero, the guard tripped, and a 20-call turn that hit cache on
+ *          every call reported hitRate 0.
+ *
+ * The distinction this function exists to preserve: an adapter sets
+ * `cacheRead` / `cacheWrite` ONLY when the provider reported a number, so
+ *   • both absent      → nobody measured  → `unknown`
+ *   • either present   → measured         → `known` (a present 0 is a real 0)
+ * That is exactly the line `Claim<T>` was written to hold.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPortCacheUsage = void 0;
+const claim_js_1 = require("../lib/claim/claim.js");
+/**
+ * Read cache metrics off port usage.
+ *
+ * @param usage  the `usage` field of `agentfootprint.stream.llm_end`
+ * @param who    the adapter named in the evidence sentence, e.g. `'the Anthropic adapter'`
+ */
+function readPortCacheUsage(usage, who) {
+    if (usage === undefined || usage === null || typeof usage !== 'object') {
+        return (0, claim_js_1.unknown)('the llm_end event carried no usage payload, so nothing about cache traffic was measured', 'agentfootprint.stream.llm_end');
+    }
+    const { cacheRead, cacheWrite, input } = usage;
+    if (cacheRead === undefined && cacheWrite === undefined) {
+        return (0, claim_js_1.unknown)(`${who} reported no cache fields on this call — that is "nobody measured", not "no cache traffic"`, 'agentfootprint.stream.llm_end usage (port shape)');
+    }
+    return (0, claim_js_1.known)({
+        cacheReadTokens: cacheRead ?? 0,
+        cacheWriteTokens: cacheWrite ?? 0,
+        freshInputTokens: typeof input === 'number' ? input : 0,
+    }, `${who} reported cache token counts on the port usage`);
+}
+exports.readPortCacheUsage = readPortCacheUsage;
+//# sourceMappingURL=portUsage.js.map

package/dist/cache/portUsage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portUsage.js","sourceRoot":"","sources":["../../src/cache/portUsage.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,oDAAmE;AAGnE;;;;;GAKG;AACH,SAAgB,kBAAkB,CAChC,KAA6B,EAC7B,GAAW;IAEX,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvE,OAAO,IAAA,kBAAO,EACZ,yFAAyF,EACzF,+BAA+B,CAChC,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAC/C,IAAI,SAAS,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QACxD,OAAO,IAAA,kBAAO,EACZ,GAAG,GAAG,4FAA4F,EAClG,kDAAkD,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,IAAA,gBAAK,EACV;QACE,eAAe,EAAE,SAAS,IAAI,CAAC;QAC/B,gBAAgB,EAAE,UAAU,IAAI,CAAC;QACjC,gBAAgB,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACxD,EACD,GAAG,GAAG,gDAAgD,CACvD,CAAC;AACJ,CAAC;AAzBD,gDAyBC"}

package/dist/cache/strategies/AnthropicCacheStrategy.js

@@ -16,7 +16,9 @@
  *
  * What this strategy DOES vs DOESN'T do:
  *   - DOES: clamp markers, attach to LLMRequest.cacheMarkers,
- *     extract metrics from response.usage
+ *     read cache metrics off the PORT usage the framework hands it
+ *     (`{ input, output, cacheRead?, cacheWrite? }`) — never off the raw
+ *     Anthropic wire, which the adapter has already normalised
  *   - DOES NOT: rewrite the wire body. The provider
  *     (BrowserAnthropicProvider) reads `cacheMarkers` and applies
  *     `cache_control` blocks during body construction. Separation of
@@ -28,6 +30,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnthropicCacheStrategy = void 0;
+const portUsage_js_1 = require("../portUsage.js");
 const strategyRegistry_js_1 = require("../strategyRegistry.js");
 /** Anthropic enforces 4 cache breakpoints per request. */
 const ANTHROPIC_MAX_MARKERS = 4;
@@ -65,22 +68,7 @@ class AnthropicCacheStrategy {
         return { request, markersApplied };
     }
     extractMetrics(usage) {
-        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;
-        const fresh = u.input_tokens ?? 0;
-        // If neither cache field present, response didn't involve caching.
-        // Returning undefined signals "no cache info" so cacheRecorder
-        // doesn't compute a misleading 0% hit rate.
-        if (cacheRead === 0 && cacheWrite === 0)
-            return undefined;
-        return {
-            cacheReadTokens: cacheRead,
-            cacheWriteTokens: cacheWrite,
-            freshInputTokens: fresh,
-        };
+        return (0, portUsage_js_1.readPortCacheUsage)(usage, 'the Anthropic adapter');
     }
 }
 exports.AnthropicCacheStrategy = AnthropicCacheStrategy;

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

@@ -1 +1 @@
-{"version":3,"file":"AnthropicCacheStrategy.js","sourceRoot":"","sources":["../../../src/cache/strategies/AnthropicCacheStrategy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAUH,gEAA+D;AAE/D,0DAA0D;AAC1D,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC9D,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,qBAAqB;IACjC,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,MAAa,sBAAsB;IACxB,YAAY,GAAG,WAAW,CAAC;IAC3B,YAAY,GAAG,sBAAsB,CAAC;IAE/C,KAAK,CAAC,cAAc,CAClB,GAAe,EACf,UAAkC,EAClC,GAAyB;QAKzB,8DAA8D;QAC9D,kEAAkE;QAClE,gEAAgE;QAChE,kEAAkE;QAClE,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;YACxB,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,2DAA2D;QAC3D,4DAA4D;QAC5D,kEAAkE;QAClE,MAAM,cAAc,GAClB,UAAU,CAAC,MAAM,IAAI,qBAAqB;YACxC,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAe;YAC1B,GAAG,GAAG;YACN,YAAY,EAAE,cAAc;SAC7B,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACrC,CAAC;IAED,cAAc,CAAC,KAAc;QAC3B,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,MAAM,KAAK,GAAG,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;QAClC,mEAAmE;QACnE,+DAA+D;QAC/D,4CAA4C;QAC5C,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,KAAK;SACxB,CAAC;IACJ,CAAC;CACF;AA3DD,wDA2DC;AAED,qEAAqE;AACrE,sEAAsE;AACtE,CAAC;IACC,MAAM,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAC9C,IAAA,2CAAqB,EAAC,QAAQ,CAAC,CAAC;IAChC,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,eAAe,GAAkB;QACrC,YAAY,EAAE,mBAAmB;QACjC,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,IAAA,2CAAqB,EAAC,eAAe,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"AnthropicCacheStrategy.js","sourceRoot":"","sources":["../../../src/cache/strategies/AnthropicCacheStrategy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAWH,kDAAqD;AAErD,gEAA+D;AAE/D,0DAA0D;AAC1D,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC9D,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,qBAAqB;IACjC,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,MAAa,sBAAsB;IACxB,YAAY,GAAG,WAAW,CAAC;IAC3B,YAAY,GAAG,sBAAsB,CAAC;IAE/C,KAAK,CAAC,cAAc,CAClB,GAAe,EACf,UAAkC,EAClC,GAAyB;QAKzB,8DAA8D;QAC9D,kEAAkE;QAClE,gEAAgE;QAChE,kEAAkE;QAClE,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;YACxB,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,2DAA2D;QAC3D,4DAA4D;QAC5D,kEAAkE;QAClE,MAAM,cAAc,GAClB,UAAU,CAAC,MAAM,IAAI,qBAAqB;YACxC,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAe;YAC1B,GAAG,GAAG;YACN,YAAY,EAAE,cAAc;SAC7B,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACrC,CAAC;IAED,cAAc,CAAC,KAA6B;QAC1C,OAAO,IAAA,iCAAkB,EAAC,KAAK,EAAE,uBAAuB,CAAC,CAAC;IAC5D,CAAC;CACF;AA1CD,wDA0CC;AAED,qEAAqE;AACrE,sEAAsE;AACtE,CAAC;IACC,MAAM,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAC9C,IAAA,2CAAqB,EAAC,QAAQ,CAAC,CAAC;IAChC,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,eAAe,GAAkB;QACrC,YAAY,EAAE,mBAAmB;QACjC,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,IAAA,2CAAqB,EAAC,eAAe,CAAC,CAAC;AACzC,CAAC"}

package/dist/cache/strategies/BedrockCacheStrategy.js

@@ -1,79 +1,95 @@
 "use strict";
 /**
- * BedrockCacheStrategy — model-aware strategy for AWS Bedrock.
+ * BedrockCacheStrategy — REGISTERED, AND HONEST ABOUT DOING NOTHING (9.59.0).
  *
- * 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.
+ * What Bedrock supports and what THIS ADAPTER does are two different facts,
+ * and until 9.59.0 the strategy stated the first while the runtime lived
+ * under the second:
  *
- * 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`).
+ *   - AWS's Converse API does support prompt caching for Claude models
+ *     (`cachePoint: { type: 'default' }` entries inserted into the `system` /
+ *     `tools` / `messages` arrays) and does report
+ *     `cacheReadInputTokens` / `cacheWriteInputTokens` in its usage block.
+ *   - `BedrockProvider` implements NEITHER half. It never reads
+ *     `req.cacheMarkers` (compare `AnthropicProvider`, which calls
+ *     `applyCacheMarkers`) and it builds `usage` as `{ input, output }` at
+ *     both its streaming and non-streaming sites. The string "cache" does
+ *     not appear in that file.
  *
- * Auto-registers under provider name `'bedrock'`.
+ * So this strategy used to clamp markers onto a request field the adapter
+ * then discarded, and report `markersApplied` for markers that never reached
+ * a wire — a meter attached to a provider that cannot feed it. It now:
+ *
+ *   - declares `enabled: false` (nothing here works end to end);
+ *   - passes the request through with `markersApplied: []`, and says why
+ *     once, in dev mode;
+ *   - answers `extractMetrics` with `not-applicable` and the reason.
+ *
+ * It stays REGISTERED rather than being deleted so that a Bedrock consumer
+ * asking the registry what it got is told the truth by name, instead of
+ * silently falling through to the wildcard NoOp and being left to guess.
  *
- * 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.
+ * Note on Converse: the send half is genuinely a DIFFERENT wire from
+ * Anthropic's `cache_control` block, so implementing it wants its own
+ * `bedrockCacheWire.ts` beside `anthropicCacheWire.ts` — not a reuse. That
+ * is the follow-up this file is waiting for; when it lands, flip `enabled`
+ * and give `extractMetrics` the `readPortCacheUsage` body the Anthropic
+ * strategy has.
+ *
+ * Auto-registers under provider name `'bedrock'`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BedrockCacheStrategy = void 0;
+const claim_js_1 = require("../../lib/claim/claim.js");
 const strategyRegistry_js_1 = require("../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 footprintjs_1 = require("footprintjs");
 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'],
+    // `false`, and it is a statement about the ADAPTER, not about Bedrock.
+    // Bedrock-Claude supports prompt caching; `BedrockProvider` implements
+    // neither half of the contract (never sends markers, never reads cache
+    // usage), so nothing this strategy could do would reach a wire. Saying
+    // `true` here is what let a dead meter look alive.
+    enabled: false,
+    maxMarkers: 0,
+    ttls: [],
+    fields: [],
     automatic: false,
 });
+/** One warning per process, not one per call — the fact does not change. */
+let warnedAboutAdapterGap = false;
 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: [] };
+    async prepareRequest(req, candidates, _ctx) {
+        // Pass-through, ALWAYS. Writing `req.cacheMarkers` here would be writing
+        // to a field `BedrockProvider` never reads, and returning a non-empty
+        // `markersApplied` would put markers that never reached a wire onto the
+        // recorder's record.
+        if (candidates.length > 0 && !warnedAboutAdapterGap && (0, footprintjs_1.isDevMode)()) {
+            warnedAboutAdapterGap = true;
+            // eslint-disable-next-line no-console
+            console.warn(`[agentfootprint] cache: ${candidates.length} cache marker(s) were declared for ` +
+                `model "${req.model}", but the Bedrock adapter does not implement prompt caching — ` +
+                `it never sends cachePoint entries and never reads cacheReadInputTokens off the ` +
+                `Converse response. No markers were applied and no hit rate can be measured. ` +
+                `Your cache: directives stay portable and light up on the Anthropic providers.`);
         }
-        const markersApplied = candidates.length <= BEDROCK_MAX_MARKERS
-            ? candidates
-            : candidates.slice(0, BEDROCK_MAX_MARKERS);
-        return {
-            request: { ...req, cacheMarkers: markersApplied },
-            markersApplied,
-        };
+        return { request: req, 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,
-        };
+    /**
+     * Always `not-applicable` — and that is a statement about THIS adapter,
+     * not about Bedrock. AWS's Converse API does report
+     * `cacheReadInputTokens` / `cacheWriteInputTokens`, but
+     * `BedrockProvider` never reads them: its `usage` is built as
+     * `{ input, output }` at both the streaming and non-streaming sites. So
+     * `cacheRead`/`cacheWrite` are ALWAYS absent on this port, and an
+     * `unknown` per call would read as a measurement that merely failed.
+     * `not-applicable` says the true thing: nothing here can be measured
+     * until the adapter grows the read half.
+     */
+    extractMetrics(_usage) {
+        return (0, claim_js_1.notApplicable)('the Bedrock adapter does not read cache usage off the Converse response, so no ' +
+            'cache tokens ever reach the port');
     }
 }
 exports.BedrockCacheStrategy = BedrockCacheStrategy;