@cognipeer/agent-sdk 0.20.0 → 0.22.1

package/dist/{model-rules--welxWDw.d.cts → model-rules-D6teB4rU.d.cts}

@@ -1,5 +1,6 @@
 type RuleFamily = "openai" | "anthropic" | "gemini" | "other";
-type ReasoningStyle = "effort" | "adaptive" | "budget" | "toggle" | "none";
+/** `level` = a discrete thinking level instead of a token budget (Gemini 3 `thinkingConfig.thinkingLevel`). */
+type ReasoningStyle = "effort" | "adaptive" | "budget" | "toggle" | "level" | "none";
 /** How "reasoning off" is spelled on the wire (`none` = the effort value itself). */
 type OffMechanism = "none" | "disabled" | "between_tools";
 type TemperatureRule = "any" | "default-only" | "unsupported" | "thinking-requires-1";
@@ -17,6 +18,21 @@ type ModelRule = {
         /** Efforts the OpenAI Responses endpoint accepts, when they differ from `efforts`. */
         responsesEfforts?: ReasoningEffort[];
         off: OffMechanism | null;
+        /**
+         * Budget style only: the smallest thinking budget the model accepts, used for
+         * effort `none` when `efforts` has no `none` (the model cannot turn thinking off,
+         * e.g. Gemini 2.5 Pro: 128).
+         */
+        minBudget?: number;
+        /**
+         * Adaptive style only: the model already thinks when a request carries no
+         * `thinking` field (Claude 5.x), but returns the thinking text empty because
+         * `display` defaults to "omitted". `includeThoughts: true` without any effort or
+         * budget then sends `thinking: { type: "adaptive", display: "summarized" }` alone
+         * (no `output_config`, no `max_tokens` raise). Unset: thinking is opt-in, and
+         * `includeThoughts` alone sends nothing.
+         */
+        defaultOn?: boolean;
     };
     sampling: {
         temperature: TemperatureRule;
@@ -39,6 +55,8 @@ type ModelRules = {
     effortLadder: ReasoningEffort[];
     /** Thinking-token budgets for budget-style engines (Anthropic 3.7/4.x, Bedrock). */
     budgets: Record<Exclude<ReasoningEffort, "none">, number>;
+    /** `max_tokens` floor per effort for adaptive thinking, where thinking and the answer share the cap. */
+    adaptiveMaxTokens: Record<Exclude<ReasoningEffort, "none">, number>;
     geminiBudgets: Record<Exclude<ReasoningEffort, "none">, number>;
     rules: ModelRule[];
 };
@@ -76,8 +94,10 @@ declare function clearLearnedModelRules(): void;
 /**
  * Finds the rule for a model: the first matching rule of the provider's family
  * (or families, for gateways such as Bedrock), else the family's permissive
- * default. Learned adjustments for (provider, model) are merged in; `patch`
- * lets a caller layer one more override on top (used by the retry loop).
+ * default. A Bedrock id that is not Claude has no Anthropic default to fall back
+ * on: it gets the generic `other` one. Learned adjustments for (provider, model)
+ * are merged in; `patch` lets a caller layer one more override on top (used by the
+ * retry loop).
  */
 declare function resolveModelRule(opts: {
     provider?: string;
@@ -111,7 +131,7 @@ declare function applyDropParams(body: Record<string, any>, rule: ModelRule): vo
 declare function effortBudget(effort: ReasoningEffort, table?: "anthropic" | "gemini"): number;
 
 declare const MAX_ADJUSTMENTS = 3;
-type ParsedModelErrorKind = "unsupported_parameter" | "unsupported_value" | "max_tokens_rename" | "default_only" | "chat_tools_effort" | "thinking_enabled_unsupported" | "thinking_adaptive_unsupported" | "thinking_off_between_tools" | "thinking_disabled_unsupported" | "temperature_thinking";
+type ParsedModelErrorKind = "unsupported_parameter" | "unsupported_value" | "max_tokens_rename" | "max_tokens_too_large" | "default_only" | "chat_tools_effort" | "thinking_enabled_unsupported" | "thinking_adaptive_unsupported" | "thinking_off_between_tools" | "thinking_disabled_unsupported" | "temperature_thinking";
 type ParsedModelError = {
     kind: ParsedModelErrorKind;
     param?: string;
@@ -119,6 +139,12 @@ type ParsedModelError = {
     supportedValues?: string[];
     /** `max_tokens` / `max_completion_tokens` for `max_tokens_rename`. */
     renameTo?: "max_tokens" | "max_completion_tokens";
+    /**
+     * `max_tokens_too_large` only: the most completion tokens the server says it
+     * accepts, when the message states it (a context-length message gives the
+     * window minus the prompt). Absent when the message states no usable number.
+     */
+    maxAllowed?: number;
     message: string;
 };
 type ModelRuleLearnedEvent = {
@@ -158,6 +184,19 @@ type MessageRole = "system" | "user" | "assistant" | "tool";
 type TextContent = {
     type: "text";
     text: string;
+    /**
+     * Explicit prompt-cache breakpoint on this text part (a 5-minute lifetime
+     * unless `ttl: "1h"`). Sent as `cache_control` by the Anthropic provider
+     * (Claude on Vertex included) and by the OpenAI-compatible provider
+     * (OpenRouter and LiteLLM forward it to Claude and similar models; Chat
+     * Completions only). Other providers ignore it: OpenAI and Azure never send
+     * the field. On an agent's messages it is set on the part itself (`cacheControl`,
+     * or Anthropic's `cache_control`); `fromNativeProvider` carries it through.
+     */
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    };
 };
 type ImageContent = {
     type: "image";
@@ -248,6 +287,11 @@ type UnifiedMessage = {
     name?: string;
     toolCalls?: ToolCall[];
     toolCallId?: string;
+    /**
+     * Tool-role messages only: the tool result is an error. A provider with a
+     * native error flag for tool results maps it; the others ignore it.
+     */
+    isError?: boolean;
     /** Native reasoning blocks to replay verbatim (Anthropic/Bedrock thinking). */
     reasoning?: ReasoningPayload;
 };
@@ -294,6 +338,13 @@ type ChatCompletionRequest = {
     /** OpenAI-family: how many top log probabilities per token. Passed through. */
     topLogprobs?: number;
     extra?: Record<string, any>;
+    /**
+     * What this call is for (`"summarization"`, `"reflection"`): the agent's own
+     * side calls tag themselves through the invoke options and the adapter copies
+     * the tag here. Providers ignore it and never put it on the wire; a host that
+     * reads the request (cost attribution, routing) can use it.
+     */
+    purpose?: string;
     /**
      * Unified native-reasoning request config. Each provider maps this to its
      * own shape:
@@ -344,6 +395,15 @@ type ReasoningRequestConfig = {
     /** Provider-specific passthrough merged on top of the mapped shape. */
     providerExtras?: Record<string, any>;
 };
+/**
+ * A provider's own usage counters, on the provider's NATIVE basis: Anthropic and
+ * Bedrock `inputTokens` leave out the cache read + write, Vertex `outputTokens`
+ * leaves out the reasoning; OpenAI-style providers are inclusive. `cachedInputTokens`
+ * / `cachedWriteTokens` / `reasoningTokens` are 0 when the provider does not report
+ * them (never an estimate). `fromNativeProvider` converts to the inclusive
+ * `MessageUsage` (see `BaseProvider.usageBasis`). A streaming provider may yield
+ * several usage chunks; each one is CUMULATIVE, so a consumer keeps the last.
+ */
 type TokenUsage = {
     inputTokens: number;
     outputTokens: number;
@@ -396,6 +456,14 @@ type ChatCompletionChunk = {
     rawFinishReason?: string;
     /** See ChatCompletionResponse.providerFields; per-chunk (fingerprint, tier, delta refusal/annotations, logprobs). */
     providerFields?: ProviderResponseFields;
+    /**
+     * The provider is starting the answer over (for example a host that retries a
+     * call cut off by its output limit inside one stream): `fromNativeProvider`
+     * drops the text, tool calls, reasoning and finish reason gathered so far. Text
+     * and reasoning deltas already yielded to the consumer cannot be taken back.
+     * Usage is not reset: usage chunks are cumulative, the last one wins.
+     */
+    reset?: boolean;
 };
 /** Why the text is being embedded; mapped to each provider's own task/input type. */
 type EmbeddingInputType = "search_document" | "search_query" | "classification" | "clustering" | "semantic_similarity" | "question_answering" | "fact_verification" | "code_retrieval_query" | (string & {});
@@ -548,6 +616,20 @@ type OpenAIProviderConfig = ProviderTransportConfig & {
      */
     responsesStreaming?: boolean;
 };
+/** Prompt caching options shared by the Anthropic, Bedrock, Vertex (Claude models) and OpenAI-compatible providers. */
+type PromptCachingConfig = {
+    /** Turns caching on. Off (or omitted) sends no cache markers. */
+    enabled: boolean;
+    /**
+     * `"auto"` (default): cache the static prefix (system + tools) AND the moving
+     * conversation tail (Anthropic: top-level automatic `cache_control`; Bedrock:
+     * a `cachePoint` after the last user message; OpenAI-compatible: the last text
+     * part of the last user or tool message). `"static"`: system (+ tools) only.
+     */
+    strategy?: "auto" | "static";
+    /** Cache lifetime: `"5m"` (default) or `"1h"`. Bedrock Nova is always 5 minutes. */
+    ttl?: "5m" | "1h";
+};
 type AnthropicProviderConfig = ProviderTransportConfig & {
     provider: "anthropic";
     apiKey: string;
@@ -557,13 +639,13 @@ type AnthropicProviderConfig = ProviderTransportConfig & {
     anthropicVersion?: string;
     retry?: ProviderRetryConfig;
     /**
-     * Prompt caching configuration. When enabled, places cache_control:
-     * ephemeral breakpoints on the system prompt and the final tool definition,
-     * which is the recommended Anthropic recipe for static system + tools.
+     * Prompt caching configuration. When enabled, places explicit cache_control
+     * breakpoints on the system prompt and the final tool definition (the static
+     * prefix) and, with the default `strategy: "auto"`, also sets the top-level
+     * automatic `cache_control` so the breakpoint follows the conversation tail.
+     * See {@link PromptCachingConfig}.
      */
-    prompt_caching?: {
-        enabled: boolean;
-    };
+    prompt_caching?: PromptCachingConfig;
     /**
      * Thinking request shape. `auto` (default) picks per model id: Claude 5.x
      * and newer use `thinking:{type:"adaptive"}` + `output_config.effort`, older
@@ -607,6 +689,31 @@ type OpenAICompatibleProviderConfig = ProviderTransportConfig & {
     baseURL: string;
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
+    /**
+     * Explicit prompt caching through servers that route to Claude and similar
+     * models (OpenRouter, LiteLLM): places `cache_control` markers on Chat
+     * Completions text parts. Off unless `enabled: true`.
+     *
+     *  - `strategy: "static"`: the end of the system prompt (leading system
+     *    messages; sent as a text part).
+     *  - `strategy: "auto"` (default): that, plus the last text part of the last
+     *    user or tool message.
+     *  - `ttl`: `"5m"` (default, the field is omitted) or `"1h"`.
+     *
+     * At most 4 markers go out in total, counting the `cacheControl` the caller
+     * set on its own text parts (those are always kept and sent, with or without
+     * this option). A plain string message becomes one text part only when a
+     * marker is added to it. Not sent to a server that rejects `cache_control`:
+     * leave this off for those. Ignored on the Responses API.
+     */
+    prompt_caching?: PromptCachingConfig;
+    /**
+     * Send the reasoning text of assistant messages back as `reasoning_content`
+     * (the DeepSeek spelling), for servers whose thinking mode requires it to be
+     * echoed in a tool loop. Default false. See the `reasoning_content` handling
+     * in the server's own documentation before enabling it.
+     */
+    replayReasoningContent?: boolean;
 };
 type BedrockProviderConfig = ProviderTransportConfig & {
     provider: "bedrock";
@@ -621,12 +728,12 @@ type BedrockProviderConfig = ProviderTransportConfig & {
     retry?: ProviderRetryConfig;
     /**
      * Insert Bedrock Converse `cachePoint` blocks at the end of the system
-     * prompt and tools list. Only supported by models that implement Converse
-     * prompt caching (most Anthropic Claude variants on Bedrock).
+     * prompt and tools list and, with the default `strategy: "auto"`, at the end
+     * of the last user message. Applies to Claude and Amazon Nova (Nova: no tools
+     * checkpoint, 5-minute only); models of families without explicit caching get
+     * no checkpoints. See {@link PromptCachingConfig}.
      */
-    prompt_caching?: {
-        enabled: boolean;
-    };
+    prompt_caching?: PromptCachingConfig;
 };
 type VertexProviderConfig = ProviderTransportConfig & {
     provider: "vertex";
@@ -638,6 +745,19 @@ type VertexProviderConfig = ProviderTransportConfig & {
     defaultHeaders?: Record<string, string>;
     /** Retry policy for 429/5xx (default 3 retries, exponential backoff). */
     retry?: ProviderRetryConfig;
+    /**
+     * Prompt caching for Claude models served by Vertex (ignored for Gemini): the
+     * same shape and meaning as on `AnthropicProviderConfig.prompt_caching`. Off
+     * unless `enabled: true`. See {@link PromptCachingConfig}.
+     */
+    prompt_caching?: PromptCachingConfig;
+    /**
+     * Thinking request shape for Claude models on Vertex (ignored for Gemini):
+     * `auto` (default, by model id), `adaptive` or `budget`, as on
+     * `AnthropicProviderConfig.thinkingMode`. Spelled out here because
+     * `utils/reasoning.ts`, which owns `ThinkingMode`, imports from this file.
+     */
+    thinkingMode?: "auto" | "adaptive" | "budget";
 };
 type JevProviderConfig = ProviderTransportConfig & {
     provider: "jev";
@@ -657,4 +777,4 @@ declare class ProviderError extends Error {
     constructor(message: string, provider: string, statusCode?: number | undefined, responseBody?: any | undefined);
 }
 
-export { type EmbeddingUsage as $, type AnthropicProviderConfig as A, type BedrockProviderConfig as B, type ChatCompletionRequest as C, type ModelRule as D, type EmbeddingRequest as E, type ModelRules as F, type ResolvedModelRule as G, type ReasoningEffort as H, type EffortMapping as I, type JevProviderConfig as J, type RuleFamily as K, type RuleSource as L, type ModelRuleLearnedEvent as M, type ReasoningStyle as N, type OpenAICompatibleProviderConfig as O, type ProviderType as P, type OffMechanism as Q, type RulePatch as R, type TemperatureRule as S, type ToolDefinition as T, type UnifiedMessage as U, type VertexProviderConfig as V, type MaxTokensParam as W, type SamplingField as X, type ParsedModelError as Y, type FinishReason as Z, type ProviderResponseFields as _, type EmbeddingResponse as a, type EmbeddingInputType as a0, type TextContent as a1, type ImageContent as a2, type FileContent as a3, type AudioContent as a4, type ToolCall as a5, type ProviderTransportConfig as a6, type ChatCompletionResponse as b, type ChatCompletionChunk as c, type OpenAIProviderConfig as d, type TokenUsage as e, type AzureProviderConfig as f, type ReasoningRequestConfig as g, type ProviderConfig as h, ProviderError as i, emptyUsage as j, MODEL_RULES as k, modelIdCandidates as l, mapReasoningEffort as m, allowsSampling as n, applyDropParams as o, effortBudget as p, mergeRulePatch as q, resolveModelRule as r, parseModelError as s, runWithModelAdjustments as t, asModelRequestError as u, MAX_ADJUSTMENTS as v, listLearnedModelRules as w, getLearnedModelRulePatch as x, rememberModelRulePatch as y, clearLearnedModelRules as z };
+export { type FinishReason as $, type AnthropicProviderConfig as A, type BedrockProviderConfig as B, type ChatCompletionRequest as C, rememberModelRulePatch as D, type EmbeddingRequest as E, clearLearnedModelRules as F, type ModelRule as G, type ModelRules as H, type ResolvedModelRule as I, type JevProviderConfig as J, type ReasoningEffort as K, type EffortMapping as L, type ModelRuleLearnedEvent as M, type RuleFamily as N, type OpenAICompatibleProviderConfig as O, type ProviderType as P, type RuleSource as Q, type RulePatch as R, type ReasoningStyle as S, type ToolDefinition as T, type UnifiedMessage as U, type VertexProviderConfig as V, type OffMechanism as W, type TemperatureRule as X, type MaxTokensParam as Y, type SamplingField as Z, type ParsedModelError as _, type EmbeddingResponse as a, type ProviderResponseFields as a0, type EmbeddingUsage as a1, type EmbeddingInputType as a2, type TextContent as a3, type ImageContent as a4, type FileContent as a5, type AudioContent as a6, type ToolCall as a7, type ProviderTransportConfig as a8, type ChatCompletionResponse as b, type ChatCompletionChunk as c, type OpenAIProviderConfig as d, type ReasoningBlock as e, type TokenUsage as f, type AzureProviderConfig as g, type PromptCachingConfig as h, type ReasoningRequestConfig as i, type ProviderConfig as j, ProviderError as k, emptyUsage as l, MODEL_RULES as m, mapReasoningEffort as n, modelIdCandidates as o, allowsSampling as p, applyDropParams as q, resolveModelRule as r, effortBudget as s, mergeRulePatch as t, parseModelError as u, runWithModelAdjustments as v, asModelRequestError as w, MAX_ADJUSTMENTS as x, listLearnedModelRules as y, getLearnedModelRulePatch as z };

package/dist/{model-rules--welxWDw.d.ts → model-rules-D6teB4rU.d.ts}

@@ -1,5 +1,6 @@
 type RuleFamily = "openai" | "anthropic" | "gemini" | "other";
-type ReasoningStyle = "effort" | "adaptive" | "budget" | "toggle" | "none";
+/** `level` = a discrete thinking level instead of a token budget (Gemini 3 `thinkingConfig.thinkingLevel`). */
+type ReasoningStyle = "effort" | "adaptive" | "budget" | "toggle" | "level" | "none";
 /** How "reasoning off" is spelled on the wire (`none` = the effort value itself). */
 type OffMechanism = "none" | "disabled" | "between_tools";
 type TemperatureRule = "any" | "default-only" | "unsupported" | "thinking-requires-1";
@@ -17,6 +18,21 @@ type ModelRule = {
         /** Efforts the OpenAI Responses endpoint accepts, when they differ from `efforts`. */
         responsesEfforts?: ReasoningEffort[];
         off: OffMechanism | null;
+        /**
+         * Budget style only: the smallest thinking budget the model accepts, used for
+         * effort `none` when `efforts` has no `none` (the model cannot turn thinking off,
+         * e.g. Gemini 2.5 Pro: 128).
+         */
+        minBudget?: number;
+        /**
+         * Adaptive style only: the model already thinks when a request carries no
+         * `thinking` field (Claude 5.x), but returns the thinking text empty because
+         * `display` defaults to "omitted". `includeThoughts: true` without any effort or
+         * budget then sends `thinking: { type: "adaptive", display: "summarized" }` alone
+         * (no `output_config`, no `max_tokens` raise). Unset: thinking is opt-in, and
+         * `includeThoughts` alone sends nothing.
+         */
+        defaultOn?: boolean;
     };
     sampling: {
         temperature: TemperatureRule;
@@ -39,6 +55,8 @@ type ModelRules = {
     effortLadder: ReasoningEffort[];
     /** Thinking-token budgets for budget-style engines (Anthropic 3.7/4.x, Bedrock). */
     budgets: Record<Exclude<ReasoningEffort, "none">, number>;
+    /** `max_tokens` floor per effort for adaptive thinking, where thinking and the answer share the cap. */
+    adaptiveMaxTokens: Record<Exclude<ReasoningEffort, "none">, number>;
     geminiBudgets: Record<Exclude<ReasoningEffort, "none">, number>;
     rules: ModelRule[];
 };
@@ -76,8 +94,10 @@ declare function clearLearnedModelRules(): void;
 /**
  * Finds the rule for a model: the first matching rule of the provider's family
  * (or families, for gateways such as Bedrock), else the family's permissive
- * default. Learned adjustments for (provider, model) are merged in; `patch`
- * lets a caller layer one more override on top (used by the retry loop).
+ * default. A Bedrock id that is not Claude has no Anthropic default to fall back
+ * on: it gets the generic `other` one. Learned adjustments for (provider, model)
+ * are merged in; `patch` lets a caller layer one more override on top (used by the
+ * retry loop).
  */
 declare function resolveModelRule(opts: {
     provider?: string;
@@ -111,7 +131,7 @@ declare function applyDropParams(body: Record<string, any>, rule: ModelRule): vo
 declare function effortBudget(effort: ReasoningEffort, table?: "anthropic" | "gemini"): number;
 
 declare const MAX_ADJUSTMENTS = 3;
-type ParsedModelErrorKind = "unsupported_parameter" | "unsupported_value" | "max_tokens_rename" | "default_only" | "chat_tools_effort" | "thinking_enabled_unsupported" | "thinking_adaptive_unsupported" | "thinking_off_between_tools" | "thinking_disabled_unsupported" | "temperature_thinking";
+type ParsedModelErrorKind = "unsupported_parameter" | "unsupported_value" | "max_tokens_rename" | "max_tokens_too_large" | "default_only" | "chat_tools_effort" | "thinking_enabled_unsupported" | "thinking_adaptive_unsupported" | "thinking_off_between_tools" | "thinking_disabled_unsupported" | "temperature_thinking";
 type ParsedModelError = {
     kind: ParsedModelErrorKind;
     param?: string;
@@ -119,6 +139,12 @@ type ParsedModelError = {
     supportedValues?: string[];
     /** `max_tokens` / `max_completion_tokens` for `max_tokens_rename`. */
     renameTo?: "max_tokens" | "max_completion_tokens";
+    /**
+     * `max_tokens_too_large` only: the most completion tokens the server says it
+     * accepts, when the message states it (a context-length message gives the
+     * window minus the prompt). Absent when the message states no usable number.
+     */
+    maxAllowed?: number;
     message: string;
 };
 type ModelRuleLearnedEvent = {
@@ -158,6 +184,19 @@ type MessageRole = "system" | "user" | "assistant" | "tool";
 type TextContent = {
     type: "text";
     text: string;
+    /**
+     * Explicit prompt-cache breakpoint on this text part (a 5-minute lifetime
+     * unless `ttl: "1h"`). Sent as `cache_control` by the Anthropic provider
+     * (Claude on Vertex included) and by the OpenAI-compatible provider
+     * (OpenRouter and LiteLLM forward it to Claude and similar models; Chat
+     * Completions only). Other providers ignore it: OpenAI and Azure never send
+     * the field. On an agent's messages it is set on the part itself (`cacheControl`,
+     * or Anthropic's `cache_control`); `fromNativeProvider` carries it through.
+     */
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    };
 };
 type ImageContent = {
     type: "image";
@@ -248,6 +287,11 @@ type UnifiedMessage = {
     name?: string;
     toolCalls?: ToolCall[];
     toolCallId?: string;
+    /**
+     * Tool-role messages only: the tool result is an error. A provider with a
+     * native error flag for tool results maps it; the others ignore it.
+     */
+    isError?: boolean;
     /** Native reasoning blocks to replay verbatim (Anthropic/Bedrock thinking). */
     reasoning?: ReasoningPayload;
 };
@@ -294,6 +338,13 @@ type ChatCompletionRequest = {
     /** OpenAI-family: how many top log probabilities per token. Passed through. */
     topLogprobs?: number;
     extra?: Record<string, any>;
+    /**
+     * What this call is for (`"summarization"`, `"reflection"`): the agent's own
+     * side calls tag themselves through the invoke options and the adapter copies
+     * the tag here. Providers ignore it and never put it on the wire; a host that
+     * reads the request (cost attribution, routing) can use it.
+     */
+    purpose?: string;
     /**
      * Unified native-reasoning request config. Each provider maps this to its
      * own shape:
@@ -344,6 +395,15 @@ type ReasoningRequestConfig = {
     /** Provider-specific passthrough merged on top of the mapped shape. */
     providerExtras?: Record<string, any>;
 };
+/**
+ * A provider's own usage counters, on the provider's NATIVE basis: Anthropic and
+ * Bedrock `inputTokens` leave out the cache read + write, Vertex `outputTokens`
+ * leaves out the reasoning; OpenAI-style providers are inclusive. `cachedInputTokens`
+ * / `cachedWriteTokens` / `reasoningTokens` are 0 when the provider does not report
+ * them (never an estimate). `fromNativeProvider` converts to the inclusive
+ * `MessageUsage` (see `BaseProvider.usageBasis`). A streaming provider may yield
+ * several usage chunks; each one is CUMULATIVE, so a consumer keeps the last.
+ */
 type TokenUsage = {
     inputTokens: number;
     outputTokens: number;
@@ -396,6 +456,14 @@ type ChatCompletionChunk = {
     rawFinishReason?: string;
     /** See ChatCompletionResponse.providerFields; per-chunk (fingerprint, tier, delta refusal/annotations, logprobs). */
     providerFields?: ProviderResponseFields;
+    /**
+     * The provider is starting the answer over (for example a host that retries a
+     * call cut off by its output limit inside one stream): `fromNativeProvider`
+     * drops the text, tool calls, reasoning and finish reason gathered so far. Text
+     * and reasoning deltas already yielded to the consumer cannot be taken back.
+     * Usage is not reset: usage chunks are cumulative, the last one wins.
+     */
+    reset?: boolean;
 };
 /** Why the text is being embedded; mapped to each provider's own task/input type. */
 type EmbeddingInputType = "search_document" | "search_query" | "classification" | "clustering" | "semantic_similarity" | "question_answering" | "fact_verification" | "code_retrieval_query" | (string & {});
@@ -548,6 +616,20 @@ type OpenAIProviderConfig = ProviderTransportConfig & {
      */
     responsesStreaming?: boolean;
 };
+/** Prompt caching options shared by the Anthropic, Bedrock, Vertex (Claude models) and OpenAI-compatible providers. */
+type PromptCachingConfig = {
+    /** Turns caching on. Off (or omitted) sends no cache markers. */
+    enabled: boolean;
+    /**
+     * `"auto"` (default): cache the static prefix (system + tools) AND the moving
+     * conversation tail (Anthropic: top-level automatic `cache_control`; Bedrock:
+     * a `cachePoint` after the last user message; OpenAI-compatible: the last text
+     * part of the last user or tool message). `"static"`: system (+ tools) only.
+     */
+    strategy?: "auto" | "static";
+    /** Cache lifetime: `"5m"` (default) or `"1h"`. Bedrock Nova is always 5 minutes. */
+    ttl?: "5m" | "1h";
+};
 type AnthropicProviderConfig = ProviderTransportConfig & {
     provider: "anthropic";
     apiKey: string;
@@ -557,13 +639,13 @@ type AnthropicProviderConfig = ProviderTransportConfig & {
     anthropicVersion?: string;
     retry?: ProviderRetryConfig;
     /**
-     * Prompt caching configuration. When enabled, places cache_control:
-     * ephemeral breakpoints on the system prompt and the final tool definition,
-     * which is the recommended Anthropic recipe for static system + tools.
+     * Prompt caching configuration. When enabled, places explicit cache_control
+     * breakpoints on the system prompt and the final tool definition (the static
+     * prefix) and, with the default `strategy: "auto"`, also sets the top-level
+     * automatic `cache_control` so the breakpoint follows the conversation tail.
+     * See {@link PromptCachingConfig}.
      */
-    prompt_caching?: {
-        enabled: boolean;
-    };
+    prompt_caching?: PromptCachingConfig;
     /**
      * Thinking request shape. `auto` (default) picks per model id: Claude 5.x
      * and newer use `thinking:{type:"adaptive"}` + `output_config.effort`, older
@@ -607,6 +689,31 @@ type OpenAICompatibleProviderConfig = ProviderTransportConfig & {
     baseURL: string;
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
+    /**
+     * Explicit prompt caching through servers that route to Claude and similar
+     * models (OpenRouter, LiteLLM): places `cache_control` markers on Chat
+     * Completions text parts. Off unless `enabled: true`.
+     *
+     *  - `strategy: "static"`: the end of the system prompt (leading system
+     *    messages; sent as a text part).
+     *  - `strategy: "auto"` (default): that, plus the last text part of the last
+     *    user or tool message.
+     *  - `ttl`: `"5m"` (default, the field is omitted) or `"1h"`.
+     *
+     * At most 4 markers go out in total, counting the `cacheControl` the caller
+     * set on its own text parts (those are always kept and sent, with or without
+     * this option). A plain string message becomes one text part only when a
+     * marker is added to it. Not sent to a server that rejects `cache_control`:
+     * leave this off for those. Ignored on the Responses API.
+     */
+    prompt_caching?: PromptCachingConfig;
+    /**
+     * Send the reasoning text of assistant messages back as `reasoning_content`
+     * (the DeepSeek spelling), for servers whose thinking mode requires it to be
+     * echoed in a tool loop. Default false. See the `reasoning_content` handling
+     * in the server's own documentation before enabling it.
+     */
+    replayReasoningContent?: boolean;
 };
 type BedrockProviderConfig = ProviderTransportConfig & {
     provider: "bedrock";
@@ -621,12 +728,12 @@ type BedrockProviderConfig = ProviderTransportConfig & {
     retry?: ProviderRetryConfig;
     /**
      * Insert Bedrock Converse `cachePoint` blocks at the end of the system
-     * prompt and tools list. Only supported by models that implement Converse
-     * prompt caching (most Anthropic Claude variants on Bedrock).
+     * prompt and tools list and, with the default `strategy: "auto"`, at the end
+     * of the last user message. Applies to Claude and Amazon Nova (Nova: no tools
+     * checkpoint, 5-minute only); models of families without explicit caching get
+     * no checkpoints. See {@link PromptCachingConfig}.
      */
-    prompt_caching?: {
-        enabled: boolean;
-    };
+    prompt_caching?: PromptCachingConfig;
 };
 type VertexProviderConfig = ProviderTransportConfig & {
     provider: "vertex";
@@ -638,6 +745,19 @@ type VertexProviderConfig = ProviderTransportConfig & {
     defaultHeaders?: Record<string, string>;
     /** Retry policy for 429/5xx (default 3 retries, exponential backoff). */
     retry?: ProviderRetryConfig;
+    /**
+     * Prompt caching for Claude models served by Vertex (ignored for Gemini): the
+     * same shape and meaning as on `AnthropicProviderConfig.prompt_caching`. Off
+     * unless `enabled: true`. See {@link PromptCachingConfig}.
+     */
+    prompt_caching?: PromptCachingConfig;
+    /**
+     * Thinking request shape for Claude models on Vertex (ignored for Gemini):
+     * `auto` (default, by model id), `adaptive` or `budget`, as on
+     * `AnthropicProviderConfig.thinkingMode`. Spelled out here because
+     * `utils/reasoning.ts`, which owns `ThinkingMode`, imports from this file.
+     */
+    thinkingMode?: "auto" | "adaptive" | "budget";
 };
 type JevProviderConfig = ProviderTransportConfig & {
     provider: "jev";
@@ -657,4 +777,4 @@ declare class ProviderError extends Error {
     constructor(message: string, provider: string, statusCode?: number | undefined, responseBody?: any | undefined);
 }
 
-export { type EmbeddingUsage as $, type AnthropicProviderConfig as A, type BedrockProviderConfig as B, type ChatCompletionRequest as C, type ModelRule as D, type EmbeddingRequest as E, type ModelRules as F, type ResolvedModelRule as G, type ReasoningEffort as H, type EffortMapping as I, type JevProviderConfig as J, type RuleFamily as K, type RuleSource as L, type ModelRuleLearnedEvent as M, type ReasoningStyle as N, type OpenAICompatibleProviderConfig as O, type ProviderType as P, type OffMechanism as Q, type RulePatch as R, type TemperatureRule as S, type ToolDefinition as T, type UnifiedMessage as U, type VertexProviderConfig as V, type MaxTokensParam as W, type SamplingField as X, type ParsedModelError as Y, type FinishReason as Z, type ProviderResponseFields as _, type EmbeddingResponse as a, type EmbeddingInputType as a0, type TextContent as a1, type ImageContent as a2, type FileContent as a3, type AudioContent as a4, type ToolCall as a5, type ProviderTransportConfig as a6, type ChatCompletionResponse as b, type ChatCompletionChunk as c, type OpenAIProviderConfig as d, type TokenUsage as e, type AzureProviderConfig as f, type ReasoningRequestConfig as g, type ProviderConfig as h, ProviderError as i, emptyUsage as j, MODEL_RULES as k, modelIdCandidates as l, mapReasoningEffort as m, allowsSampling as n, applyDropParams as o, effortBudget as p, mergeRulePatch as q, resolveModelRule as r, parseModelError as s, runWithModelAdjustments as t, asModelRequestError as u, MAX_ADJUSTMENTS as v, listLearnedModelRules as w, getLearnedModelRulePatch as x, rememberModelRulePatch as y, clearLearnedModelRules as z };
+export { type FinishReason as $, type AnthropicProviderConfig as A, type BedrockProviderConfig as B, type ChatCompletionRequest as C, rememberModelRulePatch as D, type EmbeddingRequest as E, clearLearnedModelRules as F, type ModelRule as G, type ModelRules as H, type ResolvedModelRule as I, type JevProviderConfig as J, type ReasoningEffort as K, type EffortMapping as L, type ModelRuleLearnedEvent as M, type RuleFamily as N, type OpenAICompatibleProviderConfig as O, type ProviderType as P, type RuleSource as Q, type RulePatch as R, type ReasoningStyle as S, type ToolDefinition as T, type UnifiedMessage as U, type VertexProviderConfig as V, type OffMechanism as W, type TemperatureRule as X, type MaxTokensParam as Y, type SamplingField as Z, type ParsedModelError as _, type EmbeddingResponse as a, type ProviderResponseFields as a0, type EmbeddingUsage as a1, type EmbeddingInputType as a2, type TextContent as a3, type ImageContent as a4, type FileContent as a5, type AudioContent as a6, type ToolCall as a7, type ProviderTransportConfig as a8, type ChatCompletionResponse as b, type ChatCompletionChunk as c, type OpenAIProviderConfig as d, type ReasoningBlock as e, type TokenUsage as f, type AzureProviderConfig as g, type PromptCachingConfig as h, type ReasoningRequestConfig as i, type ProviderConfig as j, ProviderError as k, emptyUsage as l, MODEL_RULES as m, mapReasoningEffort as n, modelIdCandidates as o, allowsSampling as p, applyDropParams as q, resolveModelRule as r, effortBudget as s, mergeRulePatch as t, parseModelError as u, runWithModelAdjustments as v, asModelRequestError as w, MAX_ADJUSTMENTS as x, listLearnedModelRules as y, getLearnedModelRulePatch as z };