@fgv/ts-extras 5.1.0-54 → 5.1.0-56

package/dist/ts-extras.d.ts

@@ -82,6 +82,8 @@ declare namespace AiAssist {
         AiServerToolType,
         AiServerToolConfig,
         AiToolConfig,
+        AiToolConflictPolicy,
+        IAiToolConflictReport,
         IAiWebSearchToolConfig,
         IAiClientToolConfig,
         IAiToolAnnotations,
@@ -155,7 +157,6 @@ declare namespace AiAssist {
         isAdaptiveThinkingModel,
         usesMaxCompletionTokensField,
         toDataUrl,
-        AiThinkingMode,
         IThinkingConfig,
         IThinkingProviderConfig,
         IAnthropicThinkingOptions,
@@ -215,6 +216,16 @@ declare namespace AiAssist {
         modelSpecKey,
         modelSpec,
         resolveEffectiveTools,
+        resolveToolConflicts,
+        defaultToolConflictPolicy,
+        IAiResolvedToolConflicts,
+        AiCacheReportingLevel,
+        IAiCompletionUsage,
+        supportsCacheUsageReporting,
+        supportsPromptCacheBreakpoints,
+        supportsPromptCacheRouting,
+        supportsStreamUsageOption,
+        IAiPromptCacheRoutingSupport,
         ANTHROPIC_STRUCTURED_OUTPUT_TOOL_NAME,
         AiStructuredOutputFormat,
         IAiStructuredOutputCapability,
@@ -236,7 +247,10 @@ declare namespace AiAssist {
         IGenerateJsonCompletionResult,
         JsonPromptHint,
         anthropicEffortToBudgetTokens,
-        IResolvedThinkingConfig
+        IResolvedThinkingConfig,
+        IAiCacheRequest,
+        validateAiCacheRequest,
+        validateCacheBreakpoints
     }
 }
 export { AiAssist }
@@ -253,6 +267,27 @@ declare const aiAssistProviderConfig: Converter<IAiAssistProviderConfig>;
  */
 declare const aiAssistSettings: Converter<IAiAssistSettings>;
 
+/**
+ * What a provider's wire shape is able to report about prompt-cache usage,
+ * given that a usage block was present on the response at all.
+ *
+ * @remarks
+ * `'reads'` — cache reads are reported; cache writes cannot be (either the API
+ * has no write concept, or the field structurally does not exist on this route).
+ * `'reads-and-writes'` — both reads and writes are reported.
+ *
+ * There is deliberately no `'none'` member: "no usage was reported at all" is
+ * already expressed by {@link AiAssist.IAiCompletionResponse.usage} itself
+ * being absent, and a third value here would be a second, reachable-only-via-
+ * bug way to say the same thing — check `usage === undefined`, not a `reports`
+ * value, to detect that case.
+ *
+ * See {@link AiAssist.IAiCompletionUsage.reports} for why this is required
+ * rather than optional.
+ * @public
+ */
+declare type AiCacheReportingLevel = 'reads' | 'reads-and-writes';
+
 /**
  * Converter for {@link AiAssist.IAiClientToolConfig}. Validates the wrapper shape: `type`,
  * `name`, `description`, the presence of a usable `parametersSchema`, and optional
@@ -417,12 +452,6 @@ declare const aiServerToolType: Converter<AiServerToolType>;
  */
 declare type AiStructuredOutputFormat = 'openai-json-schema' | 'openai-responses-format' | 'gemini-response-schema' | 'anthropic-tool-forced';
 
-/**
- * Thinking/reasoning mode support for a provider.
- * @public
- */
-declare type AiThinkingMode = 'optional' | 'required' | 'unsupported';
-
 /**
  * Converter for {@link AiAssist.IAiToolAnnotations} — the five optional host-advisory hints.
  * @public
@@ -436,6 +465,28 @@ declare const aiToolAnnotations: Converter<IAiToolAnnotations>;
  */
 declare type AiToolConfig = AiServerToolConfig | IAiClientToolConfig;
 
+/**
+ * What to do when a request would combine a server tool with client (function)
+ * tools on a provider that declares the two mutually exclusive (see
+ * `IAiProviderDescriptor.serverToolsExclusiveWithClientTools`).
+ *
+ * @remarks
+ * - `'drop-server-tools'` (the default) removes the offending server tools and
+ *   keeps every client tool. Client tools are what the host registered
+ *   explicitly for this turn; a built-in like grounding is a per-provider
+ *   nicety, and dropping it degrades the turn rather than losing it.
+ * - `'prefer-server-tools'` is the mirror image: keep the server tools and drop
+ *   every client tool. For hosts whose turn is *about* the grounded answer.
+ * - `'fail'` refuses the request up front with a message naming the conflict —
+ *   the behavior before this policy existed. For hosts that would rather
+ *   choose themselves than have either half silently disappear.
+ *
+ * Whichever is chosen, what actually happened is reported, never inferred: see
+ * {@link AiAssist.IAiToolConflictReport}.
+ * @public
+ */
+declare type AiToolConflictPolicy = 'drop-server-tools' | 'prefer-server-tools' | 'fail';
+
 /**
  * Converter for {@link IAiToolEnablement}.
  * @public
@@ -1273,6 +1324,19 @@ declare const DEFAULT_SECRET_ITERATIONS: number;
  */
 declare const DEFAULT_TIMEOUT_MS: number;
 
+/**
+ * The default {@link AiAssist.AiToolConflictPolicy} applied when a caller passes none.
+ *
+ * @remarks
+ * Keeping the client tools is the right default because they are what the host
+ * registered explicitly for *this* turn, while a built-in server tool is a
+ * per-provider nicety the same host would get on some providers and not others.
+ * Dropping the nicety degrades a turn; dropping the client tools changes what the
+ * turn can do.
+ * @public
+ */
+declare const defaultToolConflictPolicy: AiToolConflictPolicy;
+
 /**
  * Derives an asymmetric keypair *deterministically* from a fixed secret seed
  * using `globalThis.crypto.subtle`, shared by the Node and browser
@@ -1533,6 +1597,13 @@ declare const encryptionAlgorithm: Converter<EncryptionAlgorithm>;
  * a forced `tool_choice`. Only `tool_choice: 'auto'` (the default, i.e.
  * omitted) is compatible with extended thinking.
  *
+ * **Provider tool exclusions:** when the descriptor declares a server tool
+ * mutually exclusive with client tools (today only Gemini, for `web_search`),
+ * `toolConflictPolicy` decides — by default the server tool is dropped and the
+ * turn proceeds. The turn result's `toolConflicts` always says what happened, so
+ * a host can tell the person that e.g. web search was unavailable this turn.
+ * Pass `'fail'` to refuse the request up front instead.
+ *
  * @param params - Turn parameters
  * @returns `{ events, nextTurn }` — stream iterable + completion promise
  * @public
@@ -2485,6 +2556,41 @@ declare interface IAiAssistSettings {
     readonly proxyAllProviders?: boolean;
 }
 
+/**
+ * A request-level prompt-caching plan.
+ *
+ * @remarks
+ * Offsets rather than content blocks — see design.md §6.1 for why: `AiPrompt`/`IChatRequest`
+ * carry `system` as a plain string, offsets are usable without `@fgv/ts-prompt-assist` (a
+ * caller can say "the first 4,000 characters of my system prompt are stable" directly), and
+ * they are already the currency `IPromptSection.start`/`.chars` report.
+ * @public
+ */
+declare interface IAiCacheRequest {
+    /**
+     * Strictly ascending UTF-16 offsets into `AiPrompt.system` (equivalently
+     * `IProviderCompletionParams.system`), each marking the end of a cacheable prefix. Each must
+     * be an integer `> 0` and `< system.length`. Validated where the offsets are actually used
+     * (against the request's own `system.length`, and optionally against a cap) — never clamped;
+     * an invalid plan fails the request rather than silently caching less than declared. Sent where
+     * the provider has a breakpoint mechanism (Anthropic `cache_control`, OpenAI
+     * `prompt_cache_breakpoint`). Ignored by adapters that have no such concept (Gemini).
+     */
+    readonly systemBreakpoints?: ReadonlyArray<number>;
+    /**
+     * Opaque cache-routing key, sent where the provider has one and by that provider's transport:
+     * `prompt_cache_key` as a body field on OpenAI (both routes) and on xAI Responses, and an
+     * `x-grok-conv-id` header on xAI Chat Completions. See `supportsPromptCacheRouting`.
+     *
+     * @remarks
+     * On xAI this is not a nicety. Its prompt cache is per-server and evictable, so two requests
+     * sharing a prefix can still miss if they are routed to different servers; the key pins them
+     * together. Providers with no routing concept ignore it and receive a request byte-identical
+     * to one built without a `cache` at all.
+     */
+    readonly cacheKey?: string;
+}
+
 /**
  * A client-defined tool: configuration + execution callback pair.
  *
@@ -2552,7 +2658,7 @@ declare interface IAiClientToolConfig<TParams = unknown> {
     /**
      * Optional host-advisory behavior annotations (read-only / destructive /
      * idempotent / open-world hints + display title). Consumed by the host's
-     * tool loop; never serialized to the model. See {@link IAiToolAnnotations}.
+     * tool loop; never serialized to the model. See {@link AiAssist.IAiToolAnnotations}.
      */
     readonly annotations?: IAiToolAnnotations;
 }
@@ -2622,6 +2728,16 @@ declare interface IAiClientToolTurnResult {
     readonly truncated: boolean;
     /** The full concatenated text from all `text-delta` events in this turn. */
     readonly fullText: string;
+    /**
+     * What the provider tool-conflict resolution did to this turn's tools.
+     * Always present; empty arrays mean nothing conflicted.
+     *
+     * @remarks
+     * Read this to tell the person (or the model, on a later turn) that a
+     * capability they expected was unavailable — e.g. that web search was dropped
+     * because the pinned model cannot ground and call functions in one request.
+     */
+    readonly toolConflicts: IAiToolConflictReport;
 }
 
 /**
@@ -2651,6 +2767,61 @@ declare interface IAiCompletionResponse {
      * split.
      */
     readonly structuredOutput: StructuredOutputEnforcement;
+    /** Token usage, when the provider reports it. */
+    readonly usage?: IAiCompletionUsage;
+}
+
+/**
+ * Token accounting for a completion, normalized across providers.
+ *
+ * @remarks
+ * Every field but `reports` is best-effort: a provider's wire shape reports
+ * what it reports, and an absent field here means the corresponding wire
+ * field was itself absent — never a guessed zero. See `reports` for the one
+ * exception this rule has to be explicit about.
+ * @public
+ */
+declare interface IAiCompletionUsage {
+    /**
+     * What this response's wire shape *can* report about caching.
+     *
+     * @remarks
+     * **Required, not optional.** An optional field would make an absent
+     * `cacheWriteTokens` three-ways ambiguous — no write happened / this API
+     * cannot report writes / a build predating the field — and disambiguating
+     * exactly that is what this field exists for. Under `'reads-and-writes'`, an
+     * absent `cacheWriteTokens` genuinely means zero tokens were written this
+     * request — the actionable signal that a breakpoint did not take. Under
+     * `'reads'` it means the API cannot say, and inferring "zero writes" from it
+     * would be a fabricated fact. Same remedy as
+     * `IAiCompletionResponse.structuredOutput`.
+     */
+    readonly reports: AiCacheReportingLevel;
+    /** Input tokens **not** served from cache. Normalized — see `CAPABILITIES.md` for the per-provider table. */
+    readonly uncachedInputTokens?: number;
+    /** Input tokens served from cache. */
+    readonly cachedInputTokens?: number;
+    /**
+     * Input tokens written to cache.
+     *
+     * @remarks
+     * Two absence cases, disambiguated by `reports` — never by a `0` this field
+     * itself carries:
+     * - **`reports: 'reads-and-writes'` and this field absent** — the wire
+     *   genuinely reported zero tokens written. Treat absence as `0`, not as
+     *   unknown; this is the actionable "the breakpoint did not take" signal.
+     * - **`reports: 'reads'` and this field absent** — the API cannot report
+     *   writes on this route at all (structurally unfillable, e.g. OpenAI/xAI
+     *   Chat Completions). Never defaulted to `0` here — that would fabricate a
+     *   fact the wire never stated.
+     */
+    readonly cacheWriteTokens?: number;
+    /** Generated output tokens. */
+    readonly outputTokens?: number;
+    /** Total input = uncached + cached, when both are known. */
+    readonly totalInputTokens?: number;
+    /** The provider's own usage block, unnormalized, for anything this shape drops. */
+    readonly raw?: JsonObject;
 }
 
 /**
@@ -2964,6 +3135,23 @@ declare interface IAiModelInfo {
     readonly displayName?: string;
 }
 
+/**
+ * How a provider carries an {@link AiAssist.IAiCacheRequest.cacheKey} on the wire.
+ *
+ * @remarks
+ * Returned by {@link AiAssist.supportsPromptCacheRouting}. The Responses API takes the key as a
+ * `prompt_cache_key` body field on every provider that supports it, so only the Chat Completions
+ * transport varies and only that is described here.
+ * @public
+ */
+declare interface IAiPromptCacheRoutingSupport {
+    /**
+     * Header name to carry the key on Chat Completions, or `undefined` when the provider takes it
+     * as a `prompt_cache_key` body field there (OpenAI). xAI uses `x-grok-conv-id`.
+     */
+    readonly chatCompletionsHeader: string | undefined;
+}
+
 /**
  * Describes a single AI provider — single source of truth for all metadata.
  * @public
@@ -2998,6 +3186,29 @@ declare interface IAiProviderDescriptor {
     readonly aliases?: IModelAliasMap;
     /** Which server-side tools this provider supports (empty = none). */
     readonly supportedTools: ReadonlyArray<AiServerToolType>;
+    /**
+     * Server tools this provider's API refuses to accept in the *same request* as
+     * client (function) tools. Absent or empty means the provider imposes no such
+     * constraint and any supported server tool may be mixed with client tools.
+     *
+     * @remarks
+     * This is a narrower statement than {@link AiAssist.IAiProviderDescriptor.supportedTools}:
+     * a tool listed here is genuinely supported, just not *together* with function
+     * calling. Only Gemini declares anything today — its `generateContent` API
+     * HTTP-400s (`INVALID_ARGUMENT`) when built-in grounding (`web_search` →
+     * `google_search`) and `function_declarations` appear in one request.
+     *
+     * Declaring the rule here rather than enforcing it at the call site is the
+     * point: {@link AiAssist.resolveToolConflicts} applies it generically, so a host
+     * never writes `if (descriptor.apiFormat === 'gemini')` in its tool assembly,
+     * and the day a provider lifts its limit only this line changes.
+     *
+     * Optional because most providers have nothing to say. The library's own
+     * registry descriptors are the ones that reach the wire and are pinned by test;
+     * a hand-built descriptor that omits this simply gets the unconstrained
+     * behavior, which is the correct reading of "declares no constraint".
+     */
+    readonly serverToolsExclusiveWithClientTools?: ReadonlyArray<AiServerToolType>;
     /** Whether this provider's API enforces CORS restrictions that prevent direct browser calls. */
     readonly corsRestricted: boolean;
     /**
@@ -3017,13 +3228,6 @@ declare interface IAiProviderDescriptor {
      * `prompt.attachments` are rejected up front.
      */
     readonly acceptsImageInput: boolean;
-    /**
-     * Whether this provider supports thinking/reasoning mode.
-     * - 'optional': thinking can be enabled but is not required
-     * - 'required': thinking is always active (e.g. o-series models)
-     * - 'unsupported': thinking is not supported
-     */
-    readonly thinkingMode: AiThinkingMode;
     /**
      * Image-generation capabilities, scoped to model id prefixes. Empty or
      * undefined means the provider does not support image generation.
@@ -3117,6 +3321,20 @@ declare interface IAiProviderDescriptor {
     readonly adaptiveThinkingModelPrefixes?: ReadonlyArray<string>;
 }
 
+/**
+ * The outcome of {@link AiAssist.resolveToolConflicts}: the tools that survived,
+ * plus the report of what did not.
+ * @public
+ */
+declare interface IAiResolvedToolConflicts {
+    /** Server tools to send, after the policy was applied. */
+    readonly serverTools: ReadonlyArray<AiServerToolConfig>;
+    /** Client tools to send, after the policy was applied. */
+    readonly clientTools: ReadonlyArray<IAiClientTool>;
+    /** What the resolution did. Always populated; empty arrays mean nothing conflicted. */
+    readonly report: IAiToolConflictReport;
+}
+
 /**
  * Terminal success event for a streaming completion. Carries the aggregated
  * full text and truncation status for callers that want both the progressive
@@ -3138,6 +3356,8 @@ declare interface IAiStreamDone {
      * reports truncation without a reason).
      */
     readonly incompleteReason?: string;
+    /** Token usage, when the provider reports it on this stream. */
+    readonly usage?: IAiCompletionUsage;
 }
 
 /**
@@ -3303,6 +3523,27 @@ declare interface IAiToolAnnotations {
     readonly openWorldHint?: boolean;
 }
 
+/**
+ * What the conflict resolution did to a turn's tools.
+ *
+ * @remarks
+ * Required on {@link AiAssist.IAiClientToolTurnResult}, not optional, for the same reason
+ * `structuredOutput` is required on a completion response: an absent report is
+ * three-ways ambiguous — nothing conflicted / this build predates the feature /
+ * the resolution ran and said nothing — and disambiguating exactly that is what
+ * it is for. A turn where nothing conflicted reports the policy that was in
+ * force and two empty arrays.
+ * @public
+ */
+declare interface IAiToolConflictReport {
+    /** The policy that was in force for this turn (the default when none was passed). */
+    readonly policy: AiToolConflictPolicy;
+    /** Server tool types removed from the request. Empty when nothing was dropped. */
+    readonly droppedServerTools: ReadonlyArray<AiServerToolType>;
+    /** Names of client tools removed from the request. Empty when nothing was dropped. */
+    readonly droppedClientTools: ReadonlyArray<string>;
+}
+
 /**
  * Declares a tool as enabled/disabled in provider settings.
  * Tools are disabled by default — consuming apps must opt in explicitly.
@@ -4311,6 +4552,19 @@ declare interface IExecuteClientToolTurnParams extends IChatRequest {
      * `DEFAULT_ANTHROPIC_MAX_TOKENS`.
      */
     readonly maxTokens?: number;
+    /**
+     * What to do when this provider declares one of the requested server tools
+     * mutually exclusive with client tools (see
+     * {@link AiAssist.IAiProviderDescriptor.serverToolsExclusiveWithClientTools}). Defaults to
+     * `'drop-server-tools'` — the client tools this host registered for the turn are
+     * kept and the server tool is dropped.
+     *
+     * @remarks
+     * Whatever the policy, the turn result's `toolConflicts` says what actually
+     * happened, so a degraded turn is never a silent one. Pass `'fail'` for the
+     * pre-policy behavior: a `Result.fail` up front, before any wire call.
+     */
+    readonly toolConflictPolicy?: AiToolConflictPolicy;
 }
 
 /**
@@ -5361,6 +5615,11 @@ declare interface IProviderCompletionParams extends IChatRequest {
      * `IAiCompletionResponse.structuredOutput`.
      */
     readonly structuredOutput?: StructuredOutputRequest;
+    /**
+     * Prompt-caching plan for this request. Omitted, nothing cache-related is sent — the request
+     * body is byte-identical to a build predating this feature. See {@link AiAssist.IAiCacheRequest}.
+     */
+    readonly cache?: IAiCacheRequest;
 }
 
 /**
@@ -5530,6 +5789,38 @@ declare interface IRemoveSecretResult {
     readonly warning?: string;
 }
 
+/**
+ * One contiguous run of the rendered output, attributed to what produced it.
+ * @public
+ */
+declare interface IRenderedSegment {
+    /** `'literal'` for template text; `'substitution'` for an interpolated value. */
+    readonly kind: 'literal' | 'substitution';
+    /** Variable name, when `kind` is `'substitution'`. */
+    readonly name?: string;
+    /** Offset into `IRenderedTemplate.text`, in UTF-16 code units. */
+    readonly start: number;
+    /** Length in UTF-16 code units. May be `0` for a variable that rendered empty. */
+    readonly length: number;
+    /** `false` for a triple-stash / `{{&}}` interpolation, which bypasses escaping. */
+    readonly escaped: boolean;
+}
+
+/**
+ * A render plus the map of which part of the output came from where.
+ * @public
+ */
+declare interface IRenderedTemplate {
+    /** The rendered output — identical to what `MustacheTemplate.render` returns. */
+    readonly text: string;
+    /**
+     * Document-ordered, contiguous and gapless: every code unit of `text` belongs to exactly one
+     * segment, so concatenating them reproduces `text` exactly. That identity is verified before
+     * this is returned.
+     */
+    readonly segments: ReadonlyArray<IRenderedSegment>;
+}
+
 /**
  * Policy guard over the outbound request.
  *
@@ -5959,6 +6250,36 @@ declare interface ISchemaStructuredOutputRequest {
      */
     readonly schema: JsonSchema.ISchemaValidator<unknown>;
     readonly onUnsupported?: StructuredOutputFallback;
+    /**
+     * On a format that requires every property to be `required`, send an optional
+     * property as required when its node **already admits `null`**, instead of
+     * refusing the whole schema.
+     *
+     * @remarks
+     * `JsonSchema.optional(...)` emits its inner node verbatim — optionality lives
+     * only in the parent's `required` array — so for a property authored as
+     * `optional(string({ nullable: true }))` the wire node is already
+     * `['string', 'null']`, and adding the key to `required` narrows what the model
+     * may send from *absent-or-null-or-value* to *null-or-value*. **Every reply the
+     * narrowed schema permits, the original schema already accepted**, so the
+     * one-object-cannot-drift property is preserved rather than traded away.
+     *
+     * That is why this is not the caller asserting its validator tolerates `null`.
+     * An assertion could be false; this is read off the schema. A property authored
+     * as plain `optional(string())` rejects `null`, is therefore **not** hoistable,
+     * and the schema still refuses through `onUnsupported` exactly as before — with
+     * an error naming the properties that blocked it. Setting this flag can never
+     * produce a wire schema the supplied schema would reject.
+     *
+     * Opt-in because it is still a **semantic** change to the reply: the model must
+     * now emit `null` where it could previously omit the key. A caller that
+     * distinguishes those two — rather than treating them alike, as
+     * `optional(nullable)` says it does — should leave this off.
+     *
+     * Defaults to `false`. The enforcement report is unaffected: a schema that goes
+     * out reports `'schema'` whether or not any property was hoisted.
+     */
+    readonly adaptOptionalToNullable?: boolean;
 }
 
 /**
@@ -6042,11 +6363,27 @@ declare function isValidMultibaseSpkiPublicKey(value: unknown): value is Multiba
 declare interface IThinkingConfig {
     /**
      * Cross-provider effort level. Common-subset mapping:
+     * - 'none': Anthropic — no thinking param emitted | OpenAI effort:none | Gemini thinkingBudget:0 | xAI reasoning_effort:none
      * - 'low': Anthropic effort:low | OpenAI effort:low | Gemini thinkingBudget:1024 | xAI reasoning_effort:low
-     * - 'medium': effort:medium | effort:medium | thinkingBudget:4096 | reasoning_effort:medium
-     * - 'high': effort:high | effort:high | thinkingBudget:8192 | reasoning_effort:high
+     * - 'medium': Anthropic effort:medium | OpenAI effort:medium | Gemini thinkingBudget:4096 | xAI reasoning_effort:medium
+     * - 'high': Anthropic effort:high | OpenAI effort:high | Gemini thinkingBudget:8192 | xAI reasoning_effort:high
+     *
+     * @remarks
+     * `'none'` is the one cross-provider spelling for "thinking off". Anthropic has no
+     * off value in its own effort vocabulary — off there means omitting the `thinking`
+     * wire param entirely — so `'none'` maps to that omission rather than to a value.
+     * Whichever provider is in play, `'none'` also re-enables `temperature`: see
+     * `checkTemperatureConflict` in `thinkingOptionsResolver.ts`.
+     *
+     * The mapping is not model-aware (same posture as every other entry in this table —
+     * see `ModelSpecKey`'s remarks for why thinking availability isn't gated at the call
+     * path). For Gemini specifically, `thinkingBudget: 0` is documented as valid only on
+     * Flash and Flash-Lite and erroring on Pro (see `IGeminiThinkingConfig.thinkingBudget`);
+     * `'none'` on a Pro-family model inherits that same caveat, exactly as an explicit
+     * `providers: [{ provider: 'google', config: { thinkingBudget: 0 } }]` block already did
+     * before this field existed.
      */
-    readonly effort?: 'low' | 'medium' | 'high';
+    readonly effort?: 'none' | 'low' | 'medium' | 'high';
     /**
      * Optional per-provider precision blocks. Blocks for providers that don't
      * match the resolved model's provider are silently skipped.
@@ -7195,17 +7532,15 @@ declare const modelSpec: Converter<ModelSpec>;
  * `'advanced'` / `'frontier'`) and sets the tools / thinking request params
  * independently. Thinking composes with any tier without a tier-level capability
  * check — but that is a statement about the tier axis, not a claim that every
- * provider supports thinking: several descriptors declare
- * `thinkingMode: 'unsupported'` (e.g. `copy-paste`, `groq`, `mistral`, `ollama`,
- * `openai-compat`).
- *
- * Thinking availability is declared **per provider**, on the descriptor's
- * `thinkingMode`; the descriptor does not encode per-model thinking availability at
- * all, so a provider that declares support may still have individual models its own
- * API rejects thinking on. (`adaptiveThinkingModelPrefixes` is per-model but selects
- * a wire *shape*, not availability.) What the tier axis guarantees is therefore
- * narrow and exact: a tier selects a model within one provider and never changes the
- * provider, so it never changes `thinkingMode`.
+ * provider supports thinking, or that every model of a thinking-capable provider
+ * does: the descriptor itself declares no thinking-availability field at all.
+ * `AiModelCapability`'s `'thinking'` entry (per-model, RegExp-matched on model id
+ * in `DEFAULT_MODEL_CAPABILITY_CONFIG`) is a listing/filtering signal only — the
+ * call path does not gate a thinking request on it, so an unlisted model is not
+ * rejected, merely absent from a capability-filtered menu. (`adaptiveThinkingModelPrefixes`
+ * is per-model but selects a wire *shape*, not availability.) What the tier axis
+ * guarantees is therefore narrow and exact: a tier selects a model within one
+ * provider and never changes the provider.
  *
  * Do not add a `'tools'` or `'thinking'` key here, and do not hand-roll a
  * `resolveModel` + `resolveModelAlias` walk to emulate one — call
@@ -7287,6 +7622,8 @@ declare namespace Mustache {
         IContextValidationResult,
         IMissingVariableDetail,
         IMustacheTemplateOptions,
+        IRenderedSegment,
+        IRenderedTemplate,
         IVariableRef,
         MustacheEscapeStrategy,
         MustacheTokenType,
@@ -7375,6 +7712,61 @@ declare class MustacheTemplate {
      * @returns Success with the rendered string, or Failure if rendering fails
      */
     render(context: unknown): Result<string>;
+    /**
+     * Renders the template and reports which part of the output came from where.
+     *
+     * @remarks
+     * The rendered `text` is identical to `render`'s. What is added is
+     * `segments`: a document-ordered, contiguous, gapless attribution of every code unit to either
+     * template literal text or a named interpolation. It answers "what is in this output, in what
+     * order, and how much of it is each part" — a prompt's composition, a generated document's
+     * section sizes, a diff-free view of where a template's bulk actually goes.
+     *
+     * **Offsets are computed during the render, never recovered afterwards.** Recovering them by
+     * searching the output for each substituted value is the obvious shortcut and it is unsound: a
+     * value can occur more than once, can render empty, can be a substring of the surrounding
+     * literal text, and can be altered by escaping between input and output. That failure is silent
+     * and produces plausible offsets, which is the worst property a diagnostic can have.
+     *
+     * **Sections, inverted sections and partials are refused, not approximated.** Their rendered
+     * output is not a linear image of the token order — a section may repeat its body, or omit it —
+     * so a segment list walked from the template would mis-describe the result. Failing names the
+     * construct. Comments and set-delimiter tags emit nothing and are skipped; because each
+     * interpolation is rendered from its already-parsed token rather than from a re-parsed slice of
+     * the template, a set-delimiter tag has no effect on what this produces.
+     *
+     * **Every context value is evaluated exactly once, as `render()` evaluates it.** A lambda in the
+     * context is therefore invoked the same number of times either way, and a context whose lambda
+     * answers differently per call is rendered rather than rejected — the returned `segments` always
+     * describe the returned `text`, whatever that text was. (The concatenation identity is asserted
+     * across every shape in this package's test suite, not re-checked at runtime: re-checking means
+     * a second full render, which is precisely what would double those invocations.)
+     *
+     * @param context - The context object for template rendering.
+     * @returns Success with the rendered text and its segment map, or Failure if the
+     * template contains a construct this cannot describe
+     */
+    renderWithSegments(context: unknown): Result<IRenderedTemplate>;
+    /**
+     * Renders one interpolation token against a prepared lookup context.
+     *
+     * @remarks
+     * Delegates to the same `Writer` primitives `render()` reaches through `renderTokens`, so the
+     * value semantics — dotted paths, lambdas, `null` and `undefined` rendering empty, non-string
+     * coercion — are mustache.js's rather than a reimplementation of them.
+     *
+     * The token is passed as a freshly built `[type, name]` array rather than the parsed span. Both
+     * primitives read only the name, and `@types/mustache` declares the parameter as `string[]`
+     * while a parsed span carries its source offsets as numbers — so handing over the span would
+     * need a cast to work around the typings. Building the pair the primitives actually read needs
+     * none.
+     *
+     * @param type - `'name'` for an escaped interpolation, `'&'` for an unescaped one.
+     * @param name - The interpolation's name (may be a dotted path).
+     * @param lookup - The context to resolve the name against.
+     * @returns The rendered value; empty when the name resolves to `null` or `undefined`.
+     */
+    private _renderInterpolation;
     /**
      * Validates the context and renders the template if validation passes.
      * @param context - The context object to validate and render with
@@ -8053,6 +8445,34 @@ declare function resolveProviderModel(descriptor: IAiProviderDescriptor, modelOv
  */
 declare function resolveStructuredOutputCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiStructuredOutputCapability | undefined;
 
+/**
+ * Applies a provider's declared server-tool/client-tool exclusions to one request's
+ * tools.
+ *
+ * @remarks
+ * The generic half of a rule that used to be a provider-identity branch. The
+ * constraint is declared on the descriptor
+ * (`IAiProviderDescriptor.serverToolsExclusiveWithClientTools`); this reads it
+ * and applies `policy`, so no consumer needs to know *which* provider has the limit
+ * or *what* the limit is. A descriptor that declares nothing, or a request with no
+ * client tools, or one with no server tools, passes through untouched with an empty
+ * report — the exclusion is about the *combination*, and either half alone is legal.
+ *
+ * Sibling to {@link AiAssist.resolveEffectiveTools} rather than an extension of it:
+ * that function filters server tools against what the provider supports at all and
+ * is used by every completion path, most of which have no client tools to weigh.
+ *
+ * @param descriptor - The provider descriptor carrying the declared exclusions.
+ * @param serverTools - The server tools the caller wants to send, if any.
+ * @param clientTools - The client tools the caller wants to send.
+ * @param policy - What to do about a conflict. Defaults to
+ * {@link AiAssist.defaultToolConflictPolicy}.
+ * @returns `Success` with the surviving tools and a report, or `Failure` naming the
+ * conflict when `policy` is `'fail'`.
+ * @public
+ */
+declare function resolveToolConflicts(descriptor: IAiProviderDescriptor, serverTools: ReadonlyArray<AiServerToolConfig> | undefined, clientTools: ReadonlyArray<IAiClientTool>, policy?: AiToolConflictPolicy): Result<IAiResolvedToolConflicts>;
+
 /**
  * Statuses whose `Retry-After` header is honored.
  *
@@ -8396,6 +8816,29 @@ declare type StructuredOutputRequest = ISchemaStructuredOutputRequest | IJsonObj
  */
 declare const SUPPORTED_SCHEMES: ReadonlyArray<string>;
 
+/**
+ * Whether a provider has confirmed prompt-cache-relevant `usage` reporting on
+ * the shared Chat Completions / Responses completion paths (streaming and
+ * non-streaming alike).
+ *
+ * @remarks
+ * All four call sites (`callOpenAiCompletion`, `callOpenAiResponsesCompletion`,
+ * and their streaming counterparts) are shared by every `apiFormat: 'openai'`
+ * descriptor — xAI Grok, Groq, Mistral, Ollama, and self-hosted
+ * `openai-compat` all route through the same adapter as OpenAI. Only OpenAI
+ * and xAI Grok are confirmed to report cache-relevant `usage` fields; an
+ * ordinary `usage` block from one of the other descriptors (e.g. Groq's plain
+ * `prompt_tokens` / `completion_tokens`, with no cache sub-object at all)
+ * carries no cache information. Normalizing it anyway would stamp
+ * `reports: 'reads'` on a provider that has no prompt-caching concept —
+ * a false cache-reporting signal, not an absent one. So this gate is checked
+ * before every normalize call; when it's `false`, `usage` stays absent
+ * entirely rather than being guessed from whatever shape the wire happens to
+ * send.
+ * @public
+ */
+declare function supportsCacheUsageReporting(descriptor: IAiProviderDescriptor): boolean;
+
 /**
  * Whether a provider declares any embedding capability at all.
  *
@@ -8416,6 +8859,77 @@ declare function supportsEmbedding(descriptor: IAiProviderDescriptor): boolean;
  */
 declare function supportsImageGeneration(descriptor: IAiProviderDescriptor): boolean;
 
+/**
+ * Whether a provider has confirmed tolerance for the request-shape change
+ * {@link AiAssist.IAiCacheRequest.systemBreakpoints} produces on the shared Chat Completions /
+ * Responses paths: splitting `system` into content parts each carrying a
+ * `prompt_cache_breakpoint` field.
+ *
+ * This governs **breakpoints only**. The routing key is a separate capability with a different
+ * support set — see {@link AiAssist.supportsPromptCacheRouting}. An earlier version of this
+ * predicate gated both, which withheld the routing key from xAI, the one provider that most
+ * needs it.
+ *
+ * @remarks
+ * Same sharing problem as {@link AiAssist.supportsStreamUsageOption}, on the write side instead of the
+ * read side: `callOpenAiCompletion` and `callOpenAiResponsesCompletion` are shared by every
+ * `apiFormat: 'openai'` descriptor (xAI Grok, Groq, Mistral, Ollama, self-hosted
+ * `openai-compat`), but only OpenAI's own API is confirmed to accept a `system`/first-item
+ * `content` restructured into an array of parts each carrying an unrecognized
+ * `prompt_cache_breakpoint` field. A
+ * schema-strict server on one of the other descriptors could 400 on it — the identical
+ * failure mode `supportsStreamUsageOption` was written to avoid for `stream_options`. So `cache`
+ * is gated to `descriptor.id === 'openai'` at the dispatch site before it ever reaches these
+ * builders; every other descriptor gets the same request body it would have gotten had the
+ * caller passed no `cache` at all.
+ * @public
+ */
+declare function supportsPromptCacheBreakpoints(descriptor: IAiProviderDescriptor): boolean;
+
+/**
+ * Whether a provider accepts an opaque prompt-cache **routing** key, and by what transport.
+ *
+ * @remarks
+ * Distinct from {@link AiAssist.supportsPromptCacheBreakpoints}, and deliberately so. A breakpoint
+ * restructures the request body and needs the server to tolerate an unrecognized field inside
+ * `content`; a routing key is a single opaque string whose only job is to make repeated requests
+ * with a shared prefix land on the same cache-holding server.
+ *
+ * The two were originally gated together, which had a perverse effect: xAI does byte-for-byte
+ * prefix matching from the start of the `messages` array, and its cache is **per-server and
+ * evictable**, so without a routing key a caller can miss on an identical prefix simply by being
+ * routed elsewhere. Measured on `grok-4.3`: two requests sharing an 8,684-token system prefix but
+ * differing in their final user turn returned 2.2% cached, while a byte-identical pair returned
+ * 99.5%. Withholding the routing key from xAI withheld it from the provider whose caching depends
+ * on it most.
+ *
+ * The transport differs by route, which is why this returns a descriptor rather than a boolean:
+ *
+ * | provider | Chat Completions | Responses |
+ * |---|---|---|
+ * | `openai` | `prompt_cache_key` body field | `prompt_cache_key` body field |
+ * | `xai-grok` | `x-grok-conv-id` **header** | `prompt_cache_key` body field |
+ *
+ * Every other `apiFormat: 'openai'` descriptor (Groq, Mistral, Ollama, self-hosted
+ * `openai-compat`) returns `undefined` and gets the request it would have gotten had the caller
+ * passed no `cache` at all — the same unconfirmed-tolerance reasoning as
+ * {@link AiAssist.supportsStreamUsageOption}.
+ * @public
+ */
+declare function supportsPromptCacheRouting(descriptor: IAiProviderDescriptor): IAiPromptCacheRoutingSupport | undefined;
+
+/**
+ * Whether a provider's streaming Chat Completions request should carry
+ * `stream_options: { include_usage: true }`. A request-shape gate, not a
+ * capability guess: the shared adapter also carries providers (xAI, Groq,
+ * Mistral, Ollama, self-hosted `openai-compat`) not verified to tolerate an
+ * unrecognized field, so this is `true` only for `'openai'`; every other
+ * provider simply never gets a streaming `usage` block — a safe degradation,
+ * since `IAiStreamDone.usage` is optional everywhere.
+ * @public
+ */
+declare function supportsStreamUsageOption(descriptor: IAiProviderDescriptor): boolean;
+
 /**
  * Whether `descriptor` declares any structured-output capability at all.
  * @public
@@ -8493,6 +9007,39 @@ declare const uint8ArrayFromBase64: Converter<Uint8Array>;
  */
 declare function usesMaxCompletionTokensField(descriptor: IAiProviderDescriptor): boolean;
 
+/**
+ * Validates an {@link IAiCacheRequest}'s `systemBreakpoints` against the `system` string they
+ * index into. Thin wrapper over {@link validateCacheBreakpoints} for a caller that holds the
+ * actual string (every `ts-extras` adapter) rather than just its length.
+ * @public
+ */
+declare function validateAiCacheRequest(system: string, cache: IAiCacheRequest, maxBreakpointWrites?: number): Result<IAiCacheRequest>;
+
+/**
+ * Validates an {@link IAiCacheRequest}'s `systemBreakpoints` against the length of the `system`
+ * string they index into, and optionally against a per-model write cap.
+ *
+ * @remarks
+ * **Fails loudly, never clamps** (design.md §6.1): a non-ascending, out-of-range, or over-cap
+ * offset returns `fail()`. A silently-clamped breakpoint is precisely the silent, non-caching
+ * failure this stream exists to remove. `systemLength` and `maxBreakpointWrites` are themselves
+ * validated as non-negative integers — checked before `systemBreakpoints` even, so a malformed
+ * value (`NaN`, a negative number, a fraction) fails loudly rather than silently passing every
+ * offset check it should have rejected (`offset >= NaN` is always `false`) or, for the cap,
+ * passing unnoticed on an empty offset list. `maxBreakpointWrites` is left to the caller to supply —
+ * there is no model-keyed cap table in this package yet (design.md §7's `IAiCacheCapability` is
+ * out of this slice's scope), and design.md §5.2 establishes that a caller producing breakpoints
+ * from the three-level `PromptCacheStability` vocabulary never emits more than two, so an
+ * omitted cap is not a soundness gap for that caller — only a direct caller supplying more than a
+ * provider's cap would ever need one enforced here.
+ *
+ * Takes a length rather than {@link validateAiCacheRequest}'s `system` string because a caller
+ * building a plan from an `@fgv/ts-prompt-assist` `IPromptComposition` (`totalChars`) has the
+ * length without holding the resolved body text itself.
+ * @public
+ */
+declare function validateCacheBreakpoints(systemLength: number, cache: IAiCacheRequest, maxBreakpointWrites?: number): Result<IAiCacheRequest>;
+
 /**
  * Validates the resolved options against per-model registry constraints.
  *