@fgv/ts-extras 5.1.0-55 → 5.1.0-57

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
@@ -593,8 +644,11 @@ declare const ANTHROPIC_STRUCTURED_OUTPUT_TOOL_NAME: string;
  *
  * Policy: low = 2048, medium = 8192, high = 24000, max = 32000. The lower three
  * align with the Anthropic-published minimum-meaningful budget, a mid-range
- * default, and a "deep thinking" allotment respectively. `max` targets Opus 4.6's
- * deepest budget and stays within typical model limits.
+ * default, and a "deep thinking" allotment respectively. `max` is the deepest
+ * allotment and stays within typical model limits.
+ *
+ * Only reached for models outside the Claude 5 family — the adaptive-thinking path
+ * sends no budget at all.
  *
  * @public
  */
@@ -758,6 +812,11 @@ declare function callProviderCompletion(params: IProviderCompletionParams): Prom
  * `Result.fail` before fetch is invoked. Callers should route through
  * {@link AiAssist.callProxiedCompletionStream} or surface the failure to the user.
  *
+ * This guard is applied **here only**. `executeClientToolTurn` is also a
+ * streaming entry point and does not pre-flight the flag, so a browser
+ * client-tool turn against a `streamingCorsRestricted` provider fails at the
+ * fetch with a CORS error rather than with this legible refusal.
+ *
  * Connection-time failures (auth, network, non-2xx) surface as the outer
  * `Result.fail`. Once iteration begins, errors mid-stream surface as a
  * terminal error event ({@link AiAssist.IAiStreamError}) followed by the iterable
@@ -814,6 +873,19 @@ declare function callProviderListModels(params: IProviderListModelsParams): Prom
  * CORS, and API key forwarding. The request body serializes the unified
  * {@link AiAssist.IChatRequest} shape (`system?` + `messages`). Enforces the same
  * non-empty / trailing-user-turn and image-input invariants as the direct path.
+ *
+ * @remarks
+ * Two parameters are handled before the body is composed, rather than forwarded.
+ * `tier` is resolved here and sent as a concrete `modelOverride`, because both
+ * halves of the resolution live on the descriptor the caller already holds — so a
+ * proxy needs no `tier` vocabulary, where a `tier` body field it did not understand
+ * would be ignored and silently serve a frontier request from the base model.
+ * `endpoint` is **refused**: it names where the prompt must go, the proxy is what
+ * makes that call, and the field has never been sent to one — so honoring it is
+ * unverifiable and ignoring it would reach the provider's default upstream instead
+ * of the host the caller pinned. Use `callProviderCompletion`, or point the
+ * proxy itself at the intended upstream.
+ *
  * @param proxyUrl - Base URL of the proxy server
  * @param params - Same parameters as {@link callProviderCompletion}
  * @public
@@ -831,9 +903,23 @@ declare function callProxiedCompletion(proxyUrl: string, params: IProviderComple
  * - Response: `Content-Type: text/event-stream`; body is the unified
  *   {@link AiAssist.IAiStreamEvent} JSON-serialized one event per SSE `data:` line
  *   (no `event:` line needed since the type discriminator is in the JSON).
+ *   **Only `text-delta`, `tool-event`, `done` and `error` are carried** — an event
+ *   of any other type, including the three `client-tool-*` variants, is discarded
+ *   without error. Client-tool turns are not proxiable; `executeClientToolTurn`
+ *   has no proxied entry point.
  * - Error response (when the proxy can't even start): JSON `{error: string}`
  *   with a non-2xx status, surfaced as `proxy: ${error}`.
  *
+ * Two request parameters are handled before the body is composed, identically to
+ * `callProxiedCompletion`: `tier` is resolved here and sent as a concrete
+ * `modelOverride`, so a proxy needs no `tier` vocabulary; `endpoint` is refused,
+ * because a proxy cannot confirm it honored it and reaching the provider's default
+ * upstream instead would send the request somewhere the caller excluded. `cache`,
+ * by contrast, is forwarded as a plain `body.cache` field exactly as
+ * `callProxiedCompletion` forwards it — a proxy that ignores it degrades to the
+ * request it would have sent anyway, never a misdirected one, so there is no
+ * `endpoint`-style reason to refuse it.
+ *
  * The proxy server is responsible for opening the upstream SSE connection,
  * translating provider-native events to the unified vocabulary, and
  * forwarding events as they arrive (no buffering). The library does not
@@ -850,6 +936,15 @@ declare function callProxiedCompletionStream(proxyUrl: string, params: IProvider
  * handles descriptor lookup, model/capability resolution, and provider dispatch.
  * Error body `{ error: string }` is surfaced as `proxy: ${error}`.
  *
+ * @remarks
+ * `endpoint` is **refused** on this path rather than forwarded or dropped, on the
+ * same terms as `callProxiedCompletion`. It matters more here than
+ * anywhere else: pointing `endpoint` at `http://localhost:11434/v1` is the
+ * documented way to reach a local Ollama, so dropping it does not degrade the
+ * answer — it sends the text to OpenAI's public API instead of the machine the
+ * caller named. Use `callProviderEmbedding`, or point the proxy
+ * itself at the intended upstream.
+ *
  * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`).
  * @param params - Same parameters as {@link AiAssist.callProviderEmbedding}.
  * @returns The embedding result, or a failure.
@@ -865,6 +960,15 @@ declare function callProxiedEmbedding(proxyUrl: string, params: IProviderEmbeddi
  * lookup, model resolution, provider dispatch, and response normalization
  * (including repackaging `referenceImages` for the upstream wire format).
  * Error body `{error: string}` is surfaced as `proxy: ${error}`.
+ *
+ * @remarks
+ * `endpoint` is **refused** on this path rather than forwarded or dropped, on the
+ * same terms as `callProxiedCompletion`: a proxy cannot confirm it honored
+ * it, the field has never been sent to one, and reaching the provider's default
+ * upstream instead would send the prompt somewhere the caller excluded. Use
+ * `callProviderImageGeneration`, or point the proxy itself at the intended
+ * upstream.
+ *
  * @param proxyUrl - Base URL of the proxy server
  * @param params - Same parameters as {@link callProviderImageGeneration}
  * @public
@@ -876,6 +980,18 @@ declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderI
  * `POST ${proxyUrl}/api/ai/list-models`. Capability config is not forwarded;
  * `capabilities` is serialized as a string array. Error body `{error: string}`
  * is surfaced as `proxy: ${error}`.
+ *
+ * @remarks
+ * `capabilityConfig` and `endpoint` are both unusable here, but they are not the
+ * same case and are not treated the same way. `capabilityConfig` overrides how a
+ * model id is classified, and the proxy returns models already classified — so a
+ * caller-supplied override could only ever have arrived too late. Ignoring it
+ * yields the default classification: a degraded answer, disclosed above, and
+ * that is where it stays. `endpoint` names *which server answers at all*, so
+ * ignoring it would list the provider's public catalog in place of the host the
+ * caller pinned; it is **refused**, on the same terms as
+ * `callProxiedCompletion`.
+ *
  * @public
  */
 declare function callProxiedListModels(proxyUrl: string, params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
@@ -1273,6 +1389,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 +1662,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 +2621,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 +2723,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 +2793,61 @@ 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;
+    /**
+     * Token usage for this turn's provider call, when the provider reports it.
+     *
+     * @remarks
+     * The same `IAiCompletionUsage` the plain completion paths carry — normalized
+     * cache reads/writes, output and total input tokens, and a `reports` level
+     * saying which of those the provider is able to tell you. Sourced from the
+     * terminal `done` event of the underlying stream, so it is exactly what a
+     * caller watching `events` would see.
+     *
+     * Reading it here spares you *inspecting* the event stream, not *driving* it:
+     * `nextTurn` only resolves once `events` has been iterated to completion, the
+     * same as every other field on this interface.
+     *
+     * **One call, one usage.** `executeClientToolTurn` makes a single provider
+     * call per invocation; the multi-round loop is driven by the caller
+     * re-invoking with `continuationMessages`. So each result's `usage` already
+     * *is* one round's usage, and a host accumulating a per-turn total sums the
+     * results of its own loop. There is deliberately no `perRound` array here —
+     * it could only ever have one entry.
+     *
+     * **Optional on purpose, unlike `toolConflicts`.** The library always knows
+     * what it did to your tools, so a silent `toolConflicts` would be a defect
+     * and it is required. It cannot always know what a turn cost, so a required
+     * `usage` could only be satisfied by inventing one — the exact failure
+     * {@link AiAssist.IAiCompletionUsage.reports} exists to prevent.
+     *
+     * Absent means **no normalized usage is being exposed**, which covers two
+     * cases, the same as on {@link AiAssist.IAiCompletionResponse.usage} and
+     * {@link AiAssist.IAiStreamDone.usage}:
+     *
+     * - the provider reported nothing; or
+     * - the provider reported something the library declines to normalize,
+     *   because this descriptor is outside
+     *   {@link AiAssist.supportsCacheUsageReporting}. Groq, Mistral, Ollama and
+     *   self-hosted `openai-compat` share the OpenAI-format adapter but have
+     *   unverified usage shapes, so a raw `usage` block from one of them is
+     *   dropped rather than stamped with a cache-reporting level it may not
+     *   have earned.
+     *
+     * Either way it is never a fabricated zero. If you need to tell the two
+     * apart, the descriptor answers it: the second case is a property of the
+     * provider you picked, not of the turn.
+     */
+    readonly usage?: IAiCompletionUsage;
 }
 
 /**
@@ -2651,6 +2877,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 +3245,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 +3296,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 +3338,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 +3431,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 +3466,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 +3633,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.
@@ -3323,11 +3674,23 @@ declare interface IAiToolEnablement {
  */
 declare interface IAiWebSearchToolConfig {
     readonly type: 'web_search';
-    /** Optional: restrict search to these domains. */
+    /**
+     * Optional: restrict search to these domains.
+     * Reaches Anthropic and the OpenAI/xAI Responses API; ignored on Gemini,
+     * whose `google_search` tool takes no configuration at all.
+     */
     readonly allowedDomains?: ReadonlyArray<string>;
-    /** Optional: exclude these domains from search. */
+    /**
+     * Optional: exclude these domains from search.
+     * Same reach as {@link AiAssist.IAiWebSearchToolConfig.allowedDomains}:
+     * Anthropic and OpenAI/xAI, ignored on Gemini.
+     */
     readonly blockedDomains?: ReadonlyArray<string>;
-    /** Optional: max number of searches per request. */
+    /**
+     * Optional: max number of searches per request.
+     * **Anthropic only** — emitted as `max_uses` by the Anthropic formatter and
+     * read nowhere else, so it is silently ignored on OpenAI/xAI and Gemini.
+     */
     readonly maxUses?: number;
     /**
      * Optional: enable image understanding during web search.
@@ -3343,11 +3706,25 @@ declare interface IAiWebSearchToolConfig {
  */
 declare interface IAnthropicThinkingConfig {
     /**
-     * Anthropic effort level. The emit-site converts to `thinking.budget_tokens`
-     * (the integer budget the Anthropic API requires). Mapping policy: low = 2048,
-     * medium = 8192, high = 24000, max = 32000.
-     * - 'low' | 'medium' | 'high': all thinking-capable models
-     * - 'max': Opus 4.6 only
+     * Anthropic effort level, emitted as one of **two** wire shapes chosen by
+     * {@link AiAssist.isAdaptiveThinkingModel}:
+     *
+     * - **Claude 5 family** (`claude-sonnet-5`, `claude-opus-5`, `claude-fable-5`
+     *   — which includes the `base` and `advanced` tiers, so this is the default
+     *   path): an adaptive `thinking` block plus an `output_config` block
+     *   carrying `effort`. The effort string goes on the wire verbatim and
+     *   **no token budget is sent**.
+     * - **Older thinking-capable models**: an enabled `thinking` block carrying
+     *   `budget_tokens`, converted by `anthropicEffortToBudgetTokens` — low =
+     *   2048, medium = 8192, high = 24000, max = 32000.
+     *
+     * So the budget mapping is not a description of what a default Anthropic
+     * call sends; size a budget from it only when you have pinned a pre-Claude-5
+     * model.
+     *
+     * `'max'` is accepted on every thinking-capable model here — the library
+     * applies no model restriction of its own, and whether a given model accepts
+     * it is the provider's to enforce.
      */
     readonly effort?: 'low' | 'medium' | 'high' | 'max';
 }
@@ -4311,6 +4688,30 @@ 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;
+    /**
+     * 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}.
+     *
+     * @remarks
+     * `executeClientToolTurn` represents a single round of a multi-round tool loop; a caller
+     * driving several rounds passes this on **each** call, and it is validated against — and
+     * applied to — that round's own `system` each time, never cached across rounds. Gated per
+     * provider exactly as `IProviderCompletionParams.cache` is on the non-streaming path.
+     */
+    readonly cache?: IAiCacheRequest;
 }
 
 /**
@@ -4320,14 +4721,37 @@ declare interface IExecuteClientToolTurnParams extends IChatRequest {
 declare interface IExecuteClientToolTurnResult {
     /**
      * The unified-event iterable. Callers iterate this to drive the streaming UI.
-     * The iterable forwards `text-delta`, `tool-event`, `client-tool-call-start`,
-     * `client-tool-call-done`, and `client-tool-result` events through.
+     *
+     * @remarks
+     * Forwards every event the underlying adapter emits: `text-delta`,
+     * `tool-event`, `done` and `error` come through from the provider stream, and
+     * `client-tool-call-start`, `client-tool-call-done` and `client-tool-result`
+     * are the tool-dispatch events this layer adds.
+     *
+     * The `done` event is the terminal one and carries
+     * {@link AiAssist.IAiStreamDone.usage} when the provider reports it — this
+     * iterable is not a text-only view. A caller that only wants the token counts
+     * can read them off {@link AiAssist.IAiClientToolTurnResult.usage} instead of
+     * matching on events — but it must still iterate this to completion, because
+     * that is what drives `nextTurn` to resolve at all.
+     *
+     * (An earlier version of this comment listed only the five non-terminal
+     * events. It was describing the tool-dispatch subset, but it read as the
+     * complete set, and at least one consumer reasonably concluded from it that
+     * usage never crossed the package boundary on this path. It always did.)
      */
     readonly events: AsyncIterable<IAiStreamEvent>;
     /**
      * Resolves when the stream terminates. On success, carries the
      * {@link AiAssist.IAiClientToolTurnResult} with the optional continuation for the
      * next round. On failure, carries the error message.
+     *
+     * @remarks
+     * **You must drive `events` for this to resolve.** It is settled from inside
+     * the generator backing `events`, and an async generator does not start until
+     * something iterates it — so `await nextTurn` on its own waits forever, and
+     * the response body is never drained. Iterate `events` to completion (ignore
+     * the events if you do not want them) and then await this.
      */
     readonly nextTurn: Promise<Result<IAiClientToolTurnResult>>;
 }
@@ -4420,8 +4844,9 @@ declare interface IGeminiThinkingConfig {
     /**
      * Whether to include thought summaries in the response.
      * @remarks
-     * INERT in phase B. Adapters never send `includeThoughts: true`.
-     * Wired up by the followup stream `ai-assist-thinking-events`.
+     * Reserved for forward compatibility and **currently ignored by every
+     * adapter** — nothing reads this field, so setting it has no effect on the
+     * request. Surfacing thinking output as stream events is not yet built.
      */
     readonly includeThoughts?: boolean;
 }
@@ -5361,12 +5786,23 @@ 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;
 }
 
 /**
- * Parameters for a streaming completion request. Structurally identical to
- * the non-streaming `IProviderCompletionParams`; kept as its own interface
- * so callers can be explicit about which path they're invoking.
+ * Parameters for a streaming completion request. The non-streaming
+ * `IProviderCompletionParams` shape **minus `structuredOutput`**; kept as its
+ * own interface so callers can be explicit about which path they're invoking.
+ *
+ * @remarks
+ * The omission is deliberate, not an oversight. Native structured output is a
+ * non-streaming feature on every provider the package supports, so the field
+ * would have nowhere to go here. A caller that needs it must use
+ * `callProviderCompletion`.
  *
  * @remarks
  * Carries the unified {@link AiAssist.IChatRequest} shape (`system?` + ordered
@@ -5422,6 +5858,13 @@ declare interface IProviderCompletionStreamParams extends IChatRequest {
      * Messages API requires the field, so it falls back to `DEFAULT_ANTHROPIC_MAX_TOKENS`.
      */
     readonly maxTokens?: number;
+    /**
+     * 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}.
+     * Validated against this request's own `system` at the point it is applied, and gated per
+     * provider exactly as `IProviderCompletionParams.cache` is on the non-streaming path.
+     */
+    readonly cache?: IAiCacheRequest;
 }
 
 /**
@@ -5530,6 +5973,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.
  *
@@ -5628,7 +6103,12 @@ declare interface IResolvedImageOptions {
  * @public
  */
 declare interface IResolvedThinkingConfig {
-    /** Anthropic: effort level; emit-site converts to `thinking.budget_tokens` via `anthropicEffortToBudgetTokens`. */
+    /**
+     * Anthropic: effort level. The emit-site picks one of two wire shapes — on the
+     * Claude 5 family it sends the effort string verbatim in `output_config` with no
+     * budget; on older models it converts via `anthropicEffortToBudgetTokens`. See
+     * {@link AiAssist.IAnthropicThinkingConfig.effort}.
+     */
     readonly anthropicEffort?: IAnthropicThinkingConfig['effort'];
     /** OpenAI Chat: reasoning_effort value; OpenAI Responses: reasoning.effort */
     readonly openAiEffort?: IOpenAiThinkingConfig['effort'];
@@ -6072,11 +6552,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.
@@ -7225,17 +7721,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
@@ -7317,6 +7811,8 @@ declare namespace Mustache {
         IContextValidationResult,
         IMissingVariableDetail,
         IMustacheTemplateOptions,
+        IRenderedSegment,
+        IRenderedTemplate,
         IVariableRef,
         MustacheEscapeStrategy,
         MustacheTokenType,
@@ -7405,6 +7901,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
@@ -8083,6 +8634,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.
  *
@@ -8426,6 +9005,39 @@ 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
+ * The completion paths it gates — `callOpenAiCompletion`,
+ * `callOpenAiResponsesCompletion`, the Responses streaming adapter, and
+ * `executeClientToolTurn`'s direct Responses call — 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 it governs; when it's `false`, `usage` stays
+ * absent entirely rather than being guessed from whatever shape the wire
+ * happens to send.
+ *
+ * **Streaming Chat Completions is gated by a different predicate.** That path
+ * consults {@link AiAssist.supportsStreamUsageOption} instead, because the
+ * request has to opt in via `stream_options: { include_usage: true }` before
+ * there is any usage to normalize — and that opt-in is `'openai'`-only, since
+ * the other descriptors' tolerance for the unrecognized field is unverified.
+ * The practical consequence is that xAI Grok, which *is* confirmed here, still
+ * gets no `usage` on streaming Chat Completions. If you are tracing a missing
+ * xAI streaming figure, that predicate is the one to read, not this one.
+ * @public
+ */
+declare function supportsCacheUsageReporting(descriptor: IAiProviderDescriptor): boolean;
+
 /**
  * Whether a provider declares any embedding capability at all.
  *
@@ -8446,6 +9058,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
@@ -8523,6 +9206,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.
  *