agentfootprint 10.7.0 → 10.8.0

package/dist/esm/cache/cacheStrategyFor.js

@@ -34,7 +34,10 @@ import { NoOpCacheStrategy } from './strategies/NoOpCacheStrategy.js';
 /** One shared instance: the no-op strategy holds no state. */
 const NO_CACHING = new NoOpCacheStrategy();
 /**
- * The strategy that serves `provider`'s declared prompt caching.
+ * The strategy that serves `provider`'s declared prompt caching for `model`.
+ * Static declarations keep the one-argument form. For a model-aware adapter,
+ * pass its model (including its own supported shorthand); omitting it selects
+ * no caching rather than guessing a model.
  *
  * @throws TypeError when the declaration is malformed (an unknown `mode`, a
  *   `maxBreakpoints` that is not a positive integer, a non-boolean
@@ -42,16 +45,40 @@ const NO_CACHING = new NoOpCacheStrategy();
  *   quietly fell back to "no caching" would be the very failure this
  *   function exists to end.
  */
-export function cacheStrategyFor(provider) {
-    const declared = provider.promptCaching;
+export function cacheStrategyFor(provider, model) {
+    const declared = promptCachingFor(provider, model);
     if (declared === undefined)
         return NO_CACHING;
     const who = `the '${provider.name}' provider`;
-    assertDeclaration(declared, who);
     return declared.mode === 'breakpoints'
         ? new BreakpointCacheStrategy(declared, who)
         : new AutomaticCacheStrategy(declared, who);
 }
+/** Resolve the provider's one declaration for this model. An omitted model
+ * cannot establish a model-aware capability, so it fails closed. Static
+ * declarations retain the existing one-argument behavior.
+ *
+ * Use this reader instead of accessing `provider.promptCaching.mode`: the
+ * port also permits a model function. No resolver is duplicated in adapters.
+ *
+ * @example
+ * ```ts
+ * import { promptCachingFor } from 'agentfootprint/cache';
+ * const declaration = promptCachingFor(provider, model);
+ * if (declaration?.mode === 'breakpoints') console.log(declaration.maxBreakpoints);
+ * ```
+ */
+export function promptCachingFor(provider, model) {
+    const declaration = provider.promptCaching;
+    const declared = typeof declaration === 'function'
+        ? model === undefined
+            ? undefined
+            : declaration(model)
+        : declaration;
+    if (declared !== undefined)
+        assertDeclaration(declared, `the '${provider.name}' provider`);
+    return declared;
+}
 function assertDeclaration(declared, who) {
     const shape = declared;
     const refuse = (what) => {
@@ -69,5 +96,13 @@ function assertDeclaration(declared, who) {
     if (typeof shape.reportsUsage !== 'boolean') {
         refuse(`with reportsUsage ${JSON.stringify(shape.reportsUsage)} (true or false)`);
     }
+    if (shape.fields !== undefined &&
+        (!Array.isArray(shape.fields) ||
+            shape.fields.length === 0 ||
+            shape.fields.length > 3 ||
+            shape.fields.some((field) => !['system', 'tools', 'messages'].includes(field)) ||
+            new Set(shape.fields).size !== shape.fields.length)) {
+        refuse('with fields other than a nonempty unique subset of system, tools, messages');
+    }
 }
 //# sourceMappingURL=cacheStrategyFor.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"cacheStrategyFor.js","sourceRoot":"","sources":["../../../src/cache/cacheStrategyFor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE,8DAA8D;AAC9D,MAAM,UAAU,GAAG,IAAI,iBAAiB,EAAE,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,UAAU,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,uBAAuB,CAAC,QAAQ,EAAE,GAAG,CAAC;QAC5C,CAAC,CAAC,IAAI,sBAAsB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;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"}
+{"version":3,"file":"cacheStrategyFor.js","sourceRoot":"","sources":["../../../src/cache/cacheStrategyFor.ts"],"names":[],"mappings":"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"}

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

@@ -3,12 +3,12 @@
  *
  * 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 —
+ * `cacheStrategyFor(provider, model?)` returns the 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,
+ *   - `NoOpCacheStrategy` — nothing declared for the model (Mock, Ollama,
  *     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
@@ -21,7 +21,7 @@
  */
 export type { CachePolicy, CachePolicyContext, CacheMarker, CacheStrategy, CacheStrategyContext, CacheMetrics, CacheUsage, PromptCaching, } from './types.js';
 export { known, unknown, notApplicable, isKnown, valueOr, describeClaim, type Claim, } from '../lib/claim/claim.js';
-export { cacheStrategyFor } from './cacheStrategyFor.js';
+export { cacheStrategyFor, promptCachingFor } from './cacheStrategyFor.js';
 export { NoOpCacheStrategy } from './strategies/NoOpCacheStrategy.js';
 export { BreakpointCacheStrategy } from './strategies/BreakpointCacheStrategy.js';
 export { AutomaticCacheStrategy } from './strategies/AutomaticCacheStrategy.js';

package/dist/esm/cache/index.js

@@ -3,12 +3,12 @@
  *
  * 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 —
+ * `cacheStrategyFor(provider, model?)` returns the 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,
+ *   - `NoOpCacheStrategy` — nothing declared for the model (Mock, Ollama,
  *     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
@@ -24,7 +24,7 @@
 // `agentfootprint/maps` exports, so `known` from either door is one function.
 export { known, unknown, notApplicable, isKnown, valueOr, describeClaim, } from '../lib/claim/claim.js';
 // Strategy selection — by the provider's declared capability, never its name
-export { cacheStrategyFor } from './cacheStrategyFor.js';
+export { cacheStrategyFor, promptCachingFor } from './cacheStrategyFor.js';
 // Built-in strategy classes (for consumers who want explicit overrides via
 // `Agent.create({ cacheStrategy })`)
 export { NoOpCacheStrategy } from './strategies/NoOpCacheStrategy.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,oEAAoE;AACpE,2DAA2D;AAC3D,8EAA8E;AAC9E,OAAO,EACL,KAAK,EACL,OAAO,EACP,aAAa,EACb,OAAO,EACP,OAAO,EACP,aAAa,GAEd,MAAM,uBAAuB,CAAC;AAE/B,6EAA6E;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,2EAA2E;AAC3E,qCAAqC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAEhF,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,oEAAoE;AACpE,2DAA2D;AAC3D,8EAA8E;AAC9E,OAAO,EACL,KAAK,EACL,OAAO,EACP,aAAa,EACb,OAAO,EACP,OAAO,EACP,aAAa,GAEd,MAAM,uBAAuB,CAAC;AAE/B,6EAA6E;AAC7E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE3E,2EAA2E;AAC3E,qCAAqC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAEhF,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -24,6 +24,7 @@ export declare class BreakpointCacheStrategy implements CacheStrategy {
     private readonly maxBreakpoints;
     private readonly reportsUsage;
     private readonly who;
+    private readonly fields?;
     /**
      * @param declared  the provider's `promptCaching` declaration
      * @param who       names the adapter in the meter's evidence sentences,

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

@@ -23,6 +23,7 @@ export class BreakpointCacheStrategy {
     maxBreakpoints;
     reportsUsage;
     who;
+    fields;
     /**
      * @param declared  the provider's `promptCaching` declaration
      * @param who       names the adapter in the meter's evidence sentences,
@@ -32,6 +33,7 @@ export class BreakpointCacheStrategy {
         this.maxBreakpoints = declared.maxBreakpoints;
         this.reportsUsage = declared.reportsUsage;
         this.who = who;
+        this.fields = declared.fields;
     }
     async prepareRequest(req, candidates, ctx) {
         // The agent-side kill switch, honoured here too: the CacheGate should
@@ -40,9 +42,10 @@ export class BreakpointCacheStrategy {
         if (ctx.cachingDisabled || candidates.length === 0) {
             return { request: req, markersApplied: [] };
         }
-        const markersApplied = candidates.length <= this.maxBreakpoints
+        const supported = this.fields === undefined
             ? candidates
-            : candidates.slice(0, this.maxBreakpoints);
+            : candidates.filter((marker) => this.fields?.includes(marker.field));
+        const markersApplied = supported.length <= this.maxBreakpoints ? supported : supported.slice(0, this.maxBreakpoints);
         return { request: { ...req, cacheMarkers: markersApplied }, markersApplied };
     }
     extractMetrics(usage) {

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

@@ -1 +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"}
+{"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;IACZ,MAAM,CAAmC;IAE1D;;;;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;QACf,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAChC,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,SAAS,GACb,IAAI,CAAC,MAAM,KAAK,SAAS;YACvB,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACzE,MAAM,cAAc,GAClB,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAChG,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,6 +1,6 @@
 /**
  * NoOpCacheStrategy — for a provider that declares no prompt caching
- * (`LLMProvider.promptCaching` absent): Mock, Ollama, Bedrock Converse,
+ * (`LLMProvider.promptCaching` absent or undefined for this model): Mock, Ollama,
  * any adapter that has not said, or an intentional opt-out.
  *
  * Returns the request unchanged and reports *not applicable* — never a zero.

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

@@ -1,6 +1,6 @@
 /**
  * NoOpCacheStrategy — for a provider that declares no prompt caching
- * (`LLMProvider.promptCaching` absent): Mock, Ollama, Bedrock Converse,
+ * (`LLMProvider.promptCaching` absent or undefined for this model): Mock, Ollama,
  * any adapter that has not said, or an intentional opt-out.
  *
  * Returns the request unchanged and reports *not applicable* — never a zero.
@@ -14,7 +14,7 @@ export class NoOpCacheStrategy {
         return { request: req, markersApplied: [] };
     }
     extractMetrics(_usage) {
-        return notApplicable('the provider declares no prompt caching (LLMProvider.promptCaching is absent), so no ' +
+        return notApplicable('the provider declares no prompt caching for this model (LLMProvider.promptCaching is absent or resolves to undefined), so no ' +
             'cache traffic is driven or reported');
     }
 }

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;;;;;;;;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"}
+{"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,+HAA+H;YAC7H,qCAAqC,CACxC,CAAC;IACJ,CAAC;CACF"}

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

@@ -180,6 +180,9 @@ export type PromptCaching = {
     /** Breakpoints the wire honours on one request (Anthropic: 4). */
     readonly maxBreakpoints: number;
     readonly reportsUsage: boolean;
+    /** Optional wire-supported fields. Absent means all marker fields;
+     * models such as Bedrock Nova accept system/messages but not tools. */
+    readonly fields?: readonly CacheMarker['field'][];
 } | {
     readonly mode: 'automatic';
     readonly reportsUsage: boolean;

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

@@ -169,6 +169,8 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * consumer passes one explicitly.
      */
     private readonly cacheStrategy;
+    private readonly cacheStrategyIsOverride;
+    private readonly cacheUnsupported;
     private readonly registry;
     /**
      * The Injection list — Skills, Steering, Instructions, Facts (and
@@ -653,7 +655,7 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
         readonly strictness: 'assist' | 'guard' | 'rails';
         readonly continuity: 'turn' | 'conversation';
         readonly nodeIds: ReadonlySet<string>;
-    }, skillBrains?: import('./agent/skillBrains.js').FoldedSkillBrains, evidenceGate?: ResolvedEvidenceGate, limitsTravelWithTheAnswer?: boolean, recipes?: readonly AppliedRecipe[], skillGraphDeclared?: SkillGraphDeclaredMap, mapsPlan?: import('../maps/engagement/types.js').EngagementPlan, claimContract?: readonly import('../integrity/unsupported-claim/check.js').DeclaredClaim[], answerValidationConfig?: ResolvedAnswerValidation);
+    }, skillBrains?: import('./agent/skillBrains.js').FoldedSkillBrains, evidenceGate?: ResolvedEvidenceGate, limitsTravelWithTheAnswer?: boolean, recipes?: readonly AppliedRecipe[], skillGraphDeclared?: SkillGraphDeclaredMap, mapsPlan?: import('../maps/engagement/types.js').EngagementPlan, claimContract?: readonly import('../integrity/unsupported-claim/check.js').DeclaredClaim[], answerValidationConfig?: ResolvedAnswerValidation, systemPromptCacheExplicit?: boolean);
     static create(opts: AgentOptions): AgentBuilder;
     /**
      * Cache policy for the base system prompt. Read by the CacheDecision

package/dist/esm/core/Agent.js

@@ -19,6 +19,7 @@ import { extractSequence } from '../security/extractSequence.js';
 import { PolicyHaltError } from '../security/PolicyHaltError.js';
 import { updateSkillHistory as updateSkillHistoryStage } from '../cache/CacheGateDecider.js';
 import { cacheStrategyFor } from '../cache/cacheStrategyFor.js';
+import { cacheRequestedWithoutSupport } from './agent/cacheSupport.js';
 import { forcedToolChoiceFor, UnsupportedToolChoiceError, } from '../provider-contract/forcedToolChoice.js';
 import { nativeOutputSchemaFor, UnsupportedNativeOutputError, } from '../provider-contract/nativeOutputSchema.js';
 import { isRequestRefusal } from '../provider-contract/requestRefusal.js';
@@ -235,6 +236,8 @@ export class Agent extends RunnerBase {
      * consumer passes one explicitly.
      */
     cacheStrategy;
+    cacheStrategyIsOverride;
+    cacheUnsupported;
     registry;
     /**
      * The Injection list — Skills, Steering, Instructions, Facts (and
@@ -726,7 +729,7 @@ export class Agent extends RunnerBase {
      *  rebinding itself to each run id (`core/agent/receipt/receiptDigests.ts`). */
     receiptDigests = createReceiptDigests();
     answerValidationConfig;
-    constructor(opts, systemPromptValue, registry, voice, injections = [], memories = [], outputSchemaParser, toolProvider, systemPromptCachePolicy = 'always', cachingDisabled = false, cacheStrategy, outputFallbackCfg, reliabilityConfig, thinkingHandlerValue, thinkingBudgetValue, skillGraphNextSkill, skillGraphReachable, skillGraphScoreEntries, checkInOptions, runConfigFn, windowStrategy, toolMiddleware, messageMiddleware, outputEnforcement, skillGraphEdgeTargets, skillGraphExplainNextSkill, skillGraphIsTree, skillGraphSupersededEntries, skillGraphCascade, skillBrains, evidenceGate, limitsTravelWithTheAnswer, recipes, skillGraphDeclared, mapsPlan, claimContract, answerValidationConfig) {
+    constructor(opts, systemPromptValue, registry, voice, injections = [], memories = [], outputSchemaParser, toolProvider, systemPromptCachePolicy = 'always', cachingDisabled = false, cacheStrategy, outputFallbackCfg, reliabilityConfig, thinkingHandlerValue, thinkingBudgetValue, skillGraphNextSkill, skillGraphReachable, skillGraphScoreEntries, checkInOptions, runConfigFn, windowStrategy, toolMiddleware, messageMiddleware, outputEnforcement, skillGraphEdgeTargets, skillGraphExplainNextSkill, skillGraphIsTree, skillGraphSupersededEntries, skillGraphCascade, skillBrains, evidenceGate, limitsTravelWithTheAnswer, recipes, skillGraphDeclared, mapsPlan, claimContract, answerValidationConfig, systemPromptCacheExplicit = false) {
         super();
         // Which conversation this instance's self-explain evidence belongs to —
         // held in a module registry, not on the class, so it is not public API
@@ -756,7 +759,20 @@ export class Agent extends RunnerBase {
         // caller overrides it — never one looked up by `provider.name`, which a
         // renaming decorator (`withRetry`, an app's own wrapper) rewrites. A
         // provider that declares nothing gets the no-op strategy.
-        this.cacheStrategy = cacheStrategy ?? cacheStrategyFor(opts.provider);
+        this.cacheStrategy = cacheStrategy ?? cacheStrategyFor(opts.provider, opts.model);
+        this.cacheStrategyIsOverride = cacheStrategy !== undefined;
+        this.cacheUnsupported = cacheRequestedWithoutSupport({
+            strategy: this.cacheStrategy,
+            providerName: opts.provider.name,
+            systemPrompt: systemPromptValue,
+            systemPolicy: systemPromptCachePolicy,
+            systemExplicit: systemPromptCacheExplicit,
+            modelAwareUnavailable: cacheStrategy === undefined &&
+                typeof opts.provider.promptCaching === 'function' &&
+                this.cacheStrategy.name === 'none',
+            injections,
+            disabled: cachingDisabled,
+        });
         this.registry = registry;
         this.injections = injections;
         this.skillGraphNextSkill = skillGraphNextSkill;
@@ -3485,6 +3501,7 @@ export class Agent extends RunnerBase {
                 model: this.model,
                 hasRunConfig: this.runConfigFn !== undefined,
                 hasSkillBrains: this.skillBrains !== undefined,
+                ...(this.cacheUnsupported !== undefined && { cacheUnsupported: this.cacheUnsupported }),
                 reactMode: this.reactMode,
                 memories: this.memories,
                 ...(this.windowStrategy !== undefined && {
@@ -4707,6 +4724,7 @@ export class Agent extends RunnerBase {
             ...(costBudget !== undefined && { costBudget }),
             maxIterations,
             cacheStrategy,
+            ...(this.cacheStrategyIsOverride && { cacheStrategyIsOverride: true }),
             get toolSchemas() {
                 return toolSchemasResolved;
             },
@@ -4764,6 +4782,8 @@ export class Agent extends RunnerBase {
                     brains: this.skillBrains,
                     agentProvider: provider,
                     agentCacheStrategy: cacheStrategy,
+                    agentModel: model,
+                    ...(this.cacheStrategyIsOverride && { agentCacheStrategyIsOverride: true }),
                 }),
             }),
         });