agentfootprint 9.136.0 → 9.138.0

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

@@ -0,0 +1,43 @@
+/**
+ * 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).
+ */
+import { notApplicable } from '../../lib/claim/claim.js';
+import { readPortCacheUsage } from '../portUsage.js';
+export 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 notApplicable(`${this.who} caches automatically but declares that it does not report cache ` +
+                'token counts (promptCaching.reportsUsage: false)');
+        }
+        return readPortCacheUsage(usage, this.who);
+    }
+}
+//# sourceMappingURL=AutomaticCacheStrategy.js.map

package/dist/esm/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,OAAO,EAAE,aAAa,EAAc,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGrD,MAAM,OAAO,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,aAAa,CAClB,GAAG,IAAI,CAAC,GAAG,mEAAmE;gBAC5E,kDAAkD,CACrD,CAAC;QACJ,CAAC;QACD,OAAO,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;CACF"}

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+import type { CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext, CacheUsage, PromptCaching } from '../types.js';
+import { type Claim } from '../../lib/claim/claim.js';
+import type { LLMRequest } from '../../adapters/types.js';
+export declare class BreakpointCacheStrategy implements CacheStrategy {
+    readonly name = "breakpoints";
+    private readonly maxBreakpoints;
+    private readonly reportsUsage;
+    private readonly 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: Extract<PromptCaching, {
+        mode: 'breakpoints';
+    }>, who?: string);
+    prepareRequest(req: LLMRequest, candidates: readonly CacheMarker[], ctx: CacheStrategyContext): Promise<{
+        readonly request: LLMRequest;
+        readonly markersApplied: readonly CacheMarker[];
+    }>;
+    extractMetrics(usage: CacheUsage | undefined): Claim<CacheMetrics>;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+import { notApplicable } from '../../lib/claim/claim.js';
+import { readPortCacheUsage } from '../portUsage.js';
+export 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 notApplicable(`${this.who} declares that it does not report cache token counts ` +
+                '(promptCaching.reportsUsage: false)');
+        }
+        return readPortCacheUsage(usage, this.who);
+    }
+}
+//# sourceMappingURL=BreakpointCacheStrategy.js.map

package/dist/esm/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,OAAO,EAAE,aAAa,EAAc,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGrD,MAAM,OAAO,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,aAAa,CAClB,GAAG,IAAI,CAAC,GAAG,uDAAuD;gBAChE,qCAAqC,CACxC,CAAC;QACJ,CAAC;QACD,OAAO,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;CACF"}

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

@@ -1,27 +1,17 @@
 /**
- * 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).
  */
-import type { CacheCapabilities, CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext, CacheUsage } from '../types.js';
+import type { CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext, CacheUsage } from '../types.js';
 import { type Claim } from '../../lib/claim/claim.js';
 import type { LLMRequest } from '../../adapters/types.js';
 export declare class NoOpCacheStrategy implements CacheStrategy {
-    /**
-     * Wildcard provider name. The strategy registry treats this as the
-     * fallback for any provider that doesn't have a specific strategy
-     * registered.
-     */
-    readonly providerName = "*";
-    readonly capabilities: CacheCapabilities;
+    readonly name = "none";
     prepareRequest(req: LLMRequest, _candidates: readonly CacheMarker[], _ctx: CacheStrategyContext): Promise<{
         readonly request: LLMRequest;
         readonly markersApplied: readonly CacheMarker[];

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

@@ -1,37 +1,21 @@
 /**
- * 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).
  */
 import { notApplicable } from '../../lib/claim/claim.js';
-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;
+    name = 'none';
     async prepareRequest(req, _candidates, _ctx) {
         return { request: req, markersApplied: [] };
     }
     extractMetrics(_usage) {
-        return notApplicable('the NoOp strategy stands in for providers with no cache reporting at all');
+        return notApplicable('the provider declares no prompt caching (LLMProvider.promptCaching is absent), so no ' +
+            'cache traffic is driven or reported');
     }
 }
 //# sourceMappingURL=NoOpCacheStrategy.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"NoOpCacheStrategy.js","sourceRoot":"","sources":["../../../../src/cache/strategies/NoOpCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,OAAO,EAAE,aAAa,EAAc,MAAM,0BAA0B,CAAC;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,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,MAA8B;QAC3C,OAAO,aAAa,CAClB,0EAA0E,CAC3E,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"NoOpCacheStrategy.js","sourceRoot":"","sources":["../../../../src/cache/strategies/NoOpCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,EAAE,aAAa,EAAc,MAAM,0BAA0B,CAAC;AAGrE,MAAM,OAAO,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,aAAa,CAClB,uFAAuF;YACrF,qCAAqC,CACxC,CAAC;IACJ,CAAC;CACF"}

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

@@ -11,10 +11,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
@@ -110,14 +111,16 @@ export interface CachePolicyContext {
  *
  * The CacheDecision subflow walks `activeInjections` and emits one
  * marker per slot whose entries from index 0..boundaryIndex form a
- * stable, contiguous, cacheable prefix.
+ * stable, contiguous, cacheable prefix — and one more on the conversation
+ * tail when everything before it is cacheable (the moving breakpoint).
  *
- * `field` is the request field this marker targets. Each provider
- * strategy translates it differently:
- * - `'system'` → Anthropic puts `cache_control` on a system block
- * - `'tools'` → Anthropic puts `cache_control` on a tools array entry
- * - `'messages'` → Anthropic puts `cache_control` on the LAST content
- *   block of the LAST message (Anthropic-specific positional rule)
+ * `field` is the request field this marker targets. An adapter that declares
+ * `promptCaching.mode: 'breakpoints'` encodes it on its wire; the Anthropic
+ * one does:
+ * - `'system'` → `cache_control` on a system block
+ * - `'tools'` → `cache_control` on a tools array entry
+ * - `'messages'` → `cache_control` on the LAST content block of the
+ *   message the index names (Anthropic's positional rule)
  */
 export interface CacheMarker {
     readonly field: 'system' | 'tools' | 'messages';
@@ -126,12 +129,11 @@ export interface CacheMarker {
      * cached prefix. Everything from index 0..boundaryIndex (inclusive)
      * is cacheable.
      *
-     * **Provider note for `field: 'messages'`**: Anthropic's `cache_control`
-     * on `messages` is positional — it only takes effect on the LAST
-     * content block of the LAST message in the cacheable prefix. The
-     * AnthropicCacheStrategy translates `boundaryIndex` to the right
-     * positional placement; consumers and CacheDecision subflow don't
-     * see this complexity.
+     * **Provider note for `field: 'messages'`**: the index is a position in
+     * `LLMRequest.messages`. Anthropic's `cache_control` on `messages` is
+     * positional — it takes effect on the LAST content block of a message —
+     * and the adapter translates the index into its own (coalesced) message
+     * array; consumers and the CacheDecision subflow don't see this.
      */
     readonly boundaryIndex: number;
     /**
@@ -147,31 +149,68 @@ export interface CacheMarker {
     readonly reason: string;
 }
 /**
- * Per-provider cache implementation. One strategy per provider name;
- * registered in a default map keyed by `LLMProvider.name`.
+ * How an adapter's wire caches a repeated prompt prefix — DECLARED by the
+ * adapter, read by the agent to choose its cache strategy
+ * (`agentfootprint/cache` · `cacheStrategyFor`).
  *
- * Strategies MUST be stateless across runs. Any per-run state (handle
- * cache, hit-rate tracking) lives inside the strategy instance.
+ * - `'breakpoints'` — the provider caches a prefix only where the request
+ *   marks it (Anthropic's `cache_control`). The adapter reads
+ *   `LLMRequest.cacheMarkers` and writes them on its wire, at most
+ *   `maxBreakpoints` per request.
+ * - `'automatic'` — the provider caches repeated prefixes on its own (OpenAI).
+ *   Markers are inert; nothing the request says changes what is cached.
+ *
+ * `reportsUsage` says whether the adapter lifts the provider's cache token
+ * counts onto `LLMResponse.usage.cacheRead` / `cacheWrite`. The cache meter
+ * reads it: `false` makes every call's cache claim *not applicable*, never a
+ * zero.
+ *
+ * @example
+ * ```ts
+ * // A wrapper forwards what it wraps, like every other capability:
+ * const wrapped: LLMProvider = {
+ *   name: `my-app/${inner.name}`,
+ *   ...(inner.promptCaching !== undefined && { promptCaching: inner.promptCaching }),
+ *   complete: (req, hooks) => inner.complete(req, hooks),
+ * };
+ * ```
+ */
+export type PromptCaching = {
+    readonly mode: 'breakpoints';
+    /** Breakpoints the wire honours on one request (Anthropic: 4). */
+    readonly maxBreakpoints: number;
+    readonly reportsUsage: boolean;
+} | {
+    readonly mode: 'automatic';
+    readonly reportsUsage: boolean;
+};
+/**
+ * The cache strategy an agent runs between request assembly and the provider.
+ *
+ * Chosen by CAPABILITY: `cacheStrategyFor(provider)` reads the provider's
+ * declared `promptCaching` and returns `BreakpointCacheStrategy`,
+ * `AutomaticCacheStrategy` or `NoOpCacheStrategy`. Pass your own as
+ * `Agent.create({ cacheStrategy })` to override it.
+ *
+ * Strategies MUST be stateless across runs; per-run state arrives in the
+ * {@link CacheStrategyContext}.
  */
 export interface CacheStrategy {
-    /** Provider name match. e.g. `'anthropic'`, `'openai'`, `'bedrock'`. */
-    readonly providerName: string;
     /**
-     * Static description of what this strategy can do. Read by the
-     * CacheDecision subflow to know whether to bother emitting markers,
-     * and how many to emit before clamping to provider limits.
+     * What the run's receipt records as the strategy that stood between
+     * assembly and the port (`Receipt.cache.strategy`). The built-ins name the
+     * capability they serve: `'breakpoints'`, `'automatic'`, `'none'`.
      */
-    readonly capabilities: CacheCapabilities;
+    readonly name: string;
     /**
-     * Translate agnostic markers to provider-specific wire format.
+     * Decide which agnostic markers reach the request.
      *
-     * Async to support handle-based caching (Gemini does
-     * `createCachedContent` and references handles; not in v2.6 but
-     * the interface is async-ready for v2.7+).
+     * Async to support handle-based caching (Gemini's `createCachedContent`
+     * references handles) without another interface change.
      *
-     * Returns the modified request AND the markers actually applied
-     * (after capability-clamping). `markersApplied` flows into the
-     * cacheRecorder for diagnostic surfacing.
+     * Returns the request (with `cacheMarkers` set for the adapter to encode)
+     * AND the markers actually applied, after clamping. `markersApplied` flows
+     * into the receipt and the cacheRecorder.
      */
     prepareRequest(req: LLMRequest, candidates: readonly CacheMarker[], ctx: CacheStrategyContext): Promise<{
         readonly request: LLMRequest;
@@ -191,49 +230,12 @@ export interface CacheStrategy {
      * - `unknown(reason, …)`  — nothing measured this call (no usage payload,
      *                           or the provider reported no cache fields). The
      *                           report renders this as *unmeasured*, never 0.
-     * - `notApplicable(…)`    — this provider/adapter cannot report cache
-     *                           usage at all (NoOp; Bedrock until its adapter
-     *                           grows the read half).
+     * - `notApplicable(…)`    — this provider cannot report cache usage at
+     *                           all (it declares no `promptCaching`, or
+     *                           declares `reportsUsage: false`).
      */
     extractMetrics(usage: CacheUsage | undefined): Claim<CacheMetrics>;
 }
-/**
- * Static description of a strategy's capabilities. The CacheDecision
- * subflow reads this BEFORE calling `prepareRequest` so it can clamp
- * candidates to a count the strategy can actually use.
- */
-export interface CacheCapabilities {
-    /**
-     * `true` if this strategy actually does anything. `false` for NoOp,
-     * Mock, or providers we haven't built yet. CacheDecision subflow
-     * skips entirely when `enabled` is `false`.
-     */
-    readonly enabled: boolean;
-    /**
-     * Maximum number of cache markers per request. Anthropic enforces 4
-     * cache breakpoints per request; OpenAI is automatic (∞); Gemini
-     * is per-handle (∞ effectively). Strategies clamp internally.
-     */
-    readonly maxMarkers: number;
-    /**
-     * TTL values this strategy can map to. Anthropic supports both;
-     * OpenAI is fixed (~5min); some providers may only support one.
-     */
-    readonly ttls: ReadonlyArray<'short' | 'long'>;
-    /**
-     * Which request fields this strategy can mark. Most providers support
-     * all three (system / tools / messages); some are field-restricted.
-     */
-    readonly fields: ReadonlyArray<'system' | 'tools' | 'messages'>;
-    /**
-     * `true` if the provider auto-caches without explicit markers (OpenAI).
-     * In that case `prepareRequest` is a pass-through; only
-     * `extractMetrics` does meaningful work. Surfaced for documentation
-     * (so consumers know `cache: 'never'` may not actually disable caching
-     * on auto-caching providers).
-     */
-    readonly automatic: boolean;
-}
 /**
  * Per-run state passed into `prepareRequest`. Strategies use this to
  * make per-iteration decisions (rate of cache invalidation, current
@@ -243,10 +245,9 @@ export interface CacheStrategyContext {
     readonly iteration: number;
     readonly iterationsRemaining: number;
     /**
-     * Hit rate across previous iterations of this run (0..1). Strategies
-     * use this for self-disable behaviors (e.g., AnthropicCacheStrategy
-     * auto-skips markers when hit rate < 30% to avoid the cache-write
-     * penalty without recoup).
+     * Hit rate across previous iterations of this run (0..1), when something
+     * supplied one. Nothing in the library writes it today, so it arrives
+     * `undefined`; the CacheGate's hit-rate rule reads the same value.
      */
     readonly recentHitRate: number | undefined;
     /**

package/dist/esm/cache/types.js

@@ -11,10 +11,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/esm/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"}

package/dist/esm/core/Agent.d.ts

@@ -27,6 +27,7 @@ import { type CheckInBuilderOptions } from './checkin.js';
 import type { MemoryDefinition } from '../memory/define.types.js';
 import type { MemoryIdentity } from '../memory/identity/types.js';
 import type { SelfExplainBinding } from '../lib/trace-toolpack/selfExplain.js';
+import { type ChildOutcome } from './terminalVerdict.js';
 import type { ResolvedEvidenceGate } from './agent/evidence/types.js';
 import type { Injection, InjectionContext } from '../lib/injection-engine/types.js';
 import type { CursorMove, EntryScoring, TurnRoutingPlan } from '../lib/injection-engine/skillGraph.js';
@@ -137,11 +138,9 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      */
     private readonly 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.
+     * The CacheStrategy this agent runs. Chosen at build time from the
+     * provider's declared `promptCaching` (`cacheStrategyFor`) unless the
+     * consumer passes one explicitly.
      */
     private readonly cacheStrategy;
     private readonly registry;
@@ -493,6 +492,10 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      *  kept here rather than read back from the recording. Undefined after a run
      *  that failed or paused. */
     private lastRunAnswer?;
+    /** Whether any run on this instance got past input admission — so a
+     *  refused FIRST turn is reported as 'never-run', never as "continue from
+     *  your earlier accepted checkpoint" when there is none. */
+    private hadAdmittedRun;
     /** The id the CONSUMER chose, or undefined when they took the default.
      *  `this.id` cannot answer that question — it is `'agent'` either way — and
      *  the stored-conversation fingerprint refuses only on ids somebody picked
@@ -550,8 +553,8 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      */
     private readonly reliabilityConfig?;
     /**
-     * Resolved ThinkingHandler (v2.14+). Auto-wired by `provider.name`
-     * via `findThinkingHandler` UNLESS the builder explicitly set one
+     * Resolved ThinkingHandler (v2.14+). The provider's DECLARED one
+     * (`thinkingHandlerFor`) UNLESS the builder explicitly set one
      * (or `null` to opt out). When undefined, the NormalizeThinking
      * sub-subflow is NOT mounted at chart build time — zero overhead
      * for non-thinking agents.
@@ -1046,7 +1049,10 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * hand it back next turn, and the agent continues where it left off — across
      * a restart, a deploy, or a different machine.
      *
-     * Returns `undefined` before any run has completed.
+     * Returns `undefined` before any run has completed or when the latest run
+     * was refused by input middleware. A refused input is not an admitted
+     * conversation. Keep an earlier accepted checkpoint to continue explicitly;
+     * `followUp()` after input denial raises `NoConversationError`.
      *
      * **Read from the run's own recording, not from a second copy.** The history
      * comes from `getLastSnapshot().sharedState.history` — the state the run
@@ -1076,11 +1082,16 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * const conversation = agent.checkpoint();          // persist anywhere
      * // …a restart later, on a fresh Agent:
      * await agent.run({ message: 'Make it three.', continueFrom: conversation });
-     * // `continueFrom` runs the 'input' middleware chain on the new turn; a user
-     * // entry appended to `history` by hand and passed to `resumeOnError` skips it.
+     * // `continueFrom` admits the new turn through the 'input' middleware chain.
+     * // `resumeOnError` rechecks originalInput but replays stored history as-is;
+     * // it does not rewrite entries manually appended to that history.
      * ```
      */
     checkpoint(): AgentRunCheckpoint | undefined;
+    /** Called as each run/resume ends: remember a run that got past input admission. */
+    private noteAdmittedRun;
+    /** Whether input middleware refused the last run's message — the one reading both doors ask. */
+    private lastInputRefused;
     /** Both checkpoint doors keep the repair budget separately from conversation text. */
     private evidenceRecoveryOf;
     /**
@@ -1664,6 +1675,21 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * ```
      */
     assessment(declarations?: AssessmentDeclarations): Promise<AnswerAssessment | undefined>;
+    /**
+     * @internal What a mount of this agent's chart handed back
+     * (`core/terminalVerdict.ts` · `ReadsItsOwnOutcome`, read by every
+     * composition): the ANSWER, or the terminal verdict the chart ended on. A
+     * string, or the validated answer's `{ finalContent, answerValidationCommitted }`,
+     * is the answer; a verdict is read ONLY from the chart's state — handed over
+     * when the chart returned no result — with the one translation this agent's
+     * own run boundary (`finalizeResult`) uses. The `'tell-model'` consent record
+     * travels off tracked state, so it is raised by the run boundary only.
+     */
+    outcomeOf(sfOutput: unknown): ChildOutcome;
+    /** The records a run ends on in place of an answer, in the order the boundary raises them. */
+    private refusalVerdictOf;
+    /** Answer validation's verdict on a run that reached the end (7.24): blocked, or never committed. */
+    private validationVerdictOf;
     private finalizeResult;
     private buildChart;
 }