octaflow 0.17.2 → 0.18.0

package/README.md

@@ -1,6 +1,6 @@
 # octaflow
 
-[![CI](https://github.com/octabits-io/octaflow/actions/workflows/ci.yml/badge.svg)](https://github.com/octabits-io/octaflow/actions/workflows/ci.yml)
+[![CI](https://github.com/octabits-io/octabits/actions/workflows/ci.yml/badge.svg)](https://github.com/octabits-io/octabits/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/octaflow.svg)](https://www.npmjs.com/package/octaflow)
 [![docs](https://img.shields.io/badge/docs-octaflow.octabits.io-16794a.svg)](https://octaflow.octabits.io/)
 [![license](https://img.shields.io/npm/l/octaflow.svg)](./LICENSE)
@@ -299,6 +299,8 @@ enforces, and the correctness requirements a custom `WorkflowStore` has to meet.
 
 ## Status
 
-Pre-1.0 — developed in [octabits-io/octaflow](https://github.com/octabits-io/octaflow) (extracted from the
-[octabits platform monorepo](https://github.com/octabits-io/platform), where its earlier history lives).
-The API is stable but may still see breaking changes in 0.x minors.
+Pre-1.0 — developed in the [octabits platform monorepo](https://github.com/octabits-io/octabits)
+under [`packages/octaflow`](https://github.com/octabits-io/octabits/tree/main/packages/octaflow)
+(a standalone repository from 2026-07-14 to 2026-09-06; that history is merged in).
+Independently versioned and published as the unscoped `octaflow`. The API is stable but may
+still see breaking changes in 0.x minors.

package/dist/ai/index.d.ts

@@ -1,17 +1,18 @@
 import { E as RetryPolicy, g as TypedWorkflow, h as TypedStepContext, m as TypedStep, nt as Result, tt as FlowErrorShape } from "../index-BURAYZui.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
 import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-BdxIcc92.js";
+import { a as AiProviderMeta, c as DEFAULT_AI_PROVIDER, d as EMBEDDING_PROVIDER_IDS, f as EmbeddingProviderId, i as AiProviderId, l as DEFAULT_EMBEDDING_PROVIDER, m as embeddingDimensionsFor, n as AI_PROVIDER_IDS, o as AiProviderModelOption, p as EmbeddingProviderMeta, r as AiProcessingRegion, s as AiVendorResidency, t as AI_PROVIDERS, u as EMBEDDING_PROVIDERS } from "../provider-registry-bXGOmyeh.js";
 import { z } from "zod";
-import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
+import { EmbeddingModelV4, LanguageModelV4, SharedV4ProviderMetadata } from "@ai-sdk/provider";
 //#region src/ai/instrumented-model.d.ts
-interface AccumulatedUsage {
+export interface AccumulatedUsage {
   inputTokens: number;
   outputTokens: number;
   cacheReadTokens: number;
   cacheWriteTokens: number;
   modelId: string;
 }
-interface UsageAccumulator {
+export interface UsageAccumulator {
   /** Record usage from a single LLM call (additive — supports multiple calls per step). */
   record(usage: AccumulatedUsage): void;
   /** Total accumulated usage across all calls. */
@@ -19,20 +20,20 @@ interface UsageAccumulator {
   /** Whether any usage was recorded. */
   hasUsage(): boolean;
 }
-declare function createUsageAccumulator(): UsageAccumulator;
+export declare function createUsageAccumulator(): UsageAccumulator;
 /**
  * Wrap a language model with usage-tracking middleware. The accumulator collects
  * token usage from every doGenerate/doStream call routed through the wrapped model.
  */
-declare function createInstrumentedModel(model: LanguageModelV4, accumulator: UsageAccumulator): LanguageModelV4;
+export declare function createInstrumentedModel(model: LanguageModelV4, accumulator: UsageAccumulator): LanguageModelV4;
 //#endregion
 //#region src/ai/instrumented-embedding-model.d.ts
-interface EmbeddingAccumulatedUsage {
+export interface EmbeddingAccumulatedUsage {
   inputTokens: number;
   callCount: number;
   modelId: string;
 }
-interface EmbeddingUsageAccumulator {
+export interface EmbeddingUsageAccumulator {
   /** Record usage from a single doEmbed call (additive — supports multiple calls per batch). */
   record(tokens: number, modelId: string): void;
   /** Total accumulated usage across all calls. */
@@ -42,14 +43,14 @@ interface EmbeddingUsageAccumulator {
   /** Clear all accumulated state — used when a long-lived accumulator is reused across flushes. */
   reset(): void;
 }
-declare function createEmbeddingUsageAccumulator(): EmbeddingUsageAccumulator;
+export declare function createEmbeddingUsageAccumulator(): EmbeddingUsageAccumulator;
 /**
  * Wrap an embedding model with usage-tracking middleware. The accumulator collects
  * token usage from every doEmbed call routed through the wrapped model — both
  * `embed()` (single value) and `embedMany()` (batched values) invoke doEmbed one or
  * more times, and each invocation is recorded.
  */
-declare function createInstrumentedEmbeddingModel(model: EmbeddingModelV4, accumulator: EmbeddingUsageAccumulator): EmbeddingModelV4;
+export declare function createInstrumentedEmbeddingModel(model: EmbeddingModelV4, accumulator: EmbeddingUsageAccumulator): EmbeddingModelV4;
 //#endregion
 //#region src/ai/cost.d.ts
 /**
@@ -59,31 +60,39 @@ declare function createInstrumentedEmbeddingModel(model: EmbeddingModelV4, accum
  * The pricing table is injectable: pass your own to `createCostEstimator` for a
  * different provider/model set. A default Anthropic/OpenAI-embedding table ships.
  */
-interface ModelPricing {
+export interface ModelPricing {
   inputPerMillion: number;
   outputPerMillion: number;
   cacheReadPerMillion: number;
   cacheWritePerMillion: number;
 }
-interface TokenUsage {
+export interface TokenUsage {
   inputTokens: number;
   outputTokens: number;
   cacheReadTokens: number;
   cacheWriteTokens: number;
 }
-/** Default pricing (USD per million tokens), as of 2026-04. */
-declare const DEFAULT_MODEL_PRICING: Record<string, ModelPricing>;
-interface CostEstimatorOptions {
+/**
+ * Default pricing, USD per million tokens — Anthropic as of 2026-09, Mistral and
+ * the OpenAI embeddings as of 2026-08. A best-effort estimate, not a billing
+ * record: a BYOK caller can name any model id, and an unknown id prices at the
+ * priciest row (safe overcounting — see {@link createCostEstimator}). Retired ids
+ * are kept rather than deleted: dropping one silently reprices every historical
+ * usage row at the fallback rate. Only the Mistral `-latest` aliases are listed;
+ * pinned ids (`mistral-medium-2508`) fall to the fallback.
+ */
+export declare const DEFAULT_MODEL_PRICING: Record<string, ModelPricing>;
+export interface CostEstimatorOptions {
   /** Pricing table keyed by model id. Defaults to `DEFAULT_MODEL_PRICING`. */
   pricing?: Record<string, ModelPricing>;
   /** Pricing used for unknown model ids. Defaults to the priciest entry in the table (safe overcounting). */
   fallback?: ModelPricing;
 }
-type CostEstimator = (usage: TokenUsage, modelId: string) => number;
+export type CostEstimator = (usage: TokenUsage, modelId: string) => number;
 /** Build a cost estimator returning microdollars. */
-declare function createCostEstimator(options?: CostEstimatorOptions): CostEstimator;
+export declare function createCostEstimator(options?: CostEstimatorOptions): CostEstimator;
 /** Convenience estimator using the default pricing table. */
-declare const estimateCostMicros: CostEstimator;
+export declare const estimateCostMicros: CostEstimator;
 //#endregion
 //#region src/ai/context.d.ts
 /**
@@ -91,7 +100,7 @@ declare const estimateCostMicros: CostEstimator;
  * `buildStepContext` hook in `createAiWorkflowHooks` and consumed by AI step
  * handlers (which read `ctx.context.model` / `ctx.context.host`).
  */
-interface AiContext<THost = unknown> {
+export interface AiContext<THost = unknown> {
   /** Instrumented language model — token usage is captured automatically. */
   model: LanguageModelV4;
   /** Host-provided per-step context (DI scope, domain services, …). */
@@ -105,7 +114,7 @@ interface AiContext<THost = unknown> {
 //#endregion
 //#region src/ai/define-ai-step.d.ts
 /** An AI workflow step — a flow-core `TypedStep` whose context is an `AiContext`. */
-type AiTypedStep<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}> = TypedStep<TInput, TOutput, TDeps, AiContext<THost>>;
+export type AiTypedStep<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}> = TypedStep<TInput, TOutput, TDeps, AiContext<THost>>;
 interface DefineAiStepConfig<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>>> {
   type: string;
   workflowInputSchema: z.ZodType<TInput>;
@@ -124,16 +133,16 @@ interface DefineAiStepConfig<TInput extends Record<string, unknown>, TOutput ext
  * except the handler context is fixed to `AiContext<THost>`, so handlers get a
  * ready-to-use `ctx.context.model` (instrumented) and `ctx.context.host`.
  */
-declare function defineAiStep<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: DefineAiStepConfig<TInput, TOutput, THost, TDeps>): AiTypedStep<TInput, TOutput, THost, TDeps>;
+export declare function defineAiStep<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: DefineAiStepConfig<TInput, TOutput, THost, TDeps>): AiTypedStep<TInput, TOutput, THost, TDeps>;
 /** Build a typed AI workflow from `defineAiStep` definitions. */
-declare function buildAiWorkflow<TInput extends Record<string, unknown>, THost = unknown, TSteps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: {
+export declare function buildAiWorkflow<TInput extends Record<string, unknown>, THost = unknown, TSteps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: {
   type: string;
   inputSchema: z.ZodType<TInput>;
   steps: TSteps;
 }): TypedWorkflow<TInput, AiContext<THost>>;
 //#endregion
 //#region src/ai/hooks.d.ts
-interface AiModelResolver<THost = unknown> {
+export interface AiModelResolver<THost = unknown> {
   /** Resolve the base (uninstrumented) model for a step. */
   resolveModel(args: BuildStepContextArgs): Promise<LanguageModelV4> | LanguageModelV4;
   /** Optional host context (DI scope, services) exposed to handlers as `ctx.context.host`. */
@@ -145,7 +154,7 @@ interface AiModelResolver<THost = unknown> {
    */
   resolveKeySource?(): Promise<string> | string;
 }
-interface AiUsageRecorder {
+export interface AiUsageRecorder {
   /** Persist per-step token usage + cost (e.g. onto the step row). */
   recordStepUsage(args: {
     workflowId: number;
@@ -170,11 +179,11 @@ interface AiUsageRecorder {
     date: string;
   }): Promise<void>;
 }
-interface AiQuotaPolicy {
+export interface AiQuotaPolicy {
   /** Return an error (e.g. `ai_quota_exceeded`) to reject a workflow start. */
   checkQuota(): Promise<Result<void, FlowErrorShape>>;
 }
-interface CreateAiWorkflowHooksDeps<THost = unknown> {
+export interface CreateAiWorkflowHooksDeps<THost = unknown> {
   modelResolver: AiModelResolver<THost>;
   usageRecorder: AiUsageRecorder;
   /** Optional quota guard. BYOK exemption etc. is the policy's concern. */
@@ -189,7 +198,7 @@ interface CreateAiWorkflowHooksDeps<THost = unknown> {
  * usage rollups) into a set of flow-core lifecycle hooks. Pass the result as the
  * engine's `hooks`. flow-core stays AI-free; everything AI lives here.
  */
-declare function createAiWorkflowHooks<THost = unknown>(deps: CreateAiWorkflowHooksDeps<THost>): WorkflowHooks<AiContext<THost>>;
+export declare function createAiWorkflowHooks<THost = unknown>(deps: CreateAiWorkflowHooksDeps<THost>): WorkflowHooks<AiContext<THost>>;
 //#endregion
 //#region src/ai/quota.d.ts
 /**
@@ -198,7 +207,7 @@ declare function createAiWorkflowHooks<THost = unknown>(deps: CreateAiWorkflowHo
  * return `null` for the whole config to exempt a scope entirely (e.g. a
  * bring-your-own-key caller that shouldn't be metered against platform quota).
  */
-interface AiQuotaConfig {
+export interface AiQuotaConfig {
   /** Max simultaneously-running workflows. `null` = unlimited. */
   maxConcurrentWorkflows: number | null;
   /** Max workflows started per calendar day (UTC). `null` = unlimited. */
@@ -211,14 +220,14 @@ interface AiQuotaConfig {
  * flow does **not** apply these automatically — resolution policy lives in the
  * injected {@link AiQuotaConfigResolver}.
  */
-declare const DEFAULT_AI_QUOTA: AiQuotaConfig;
+export declare const DEFAULT_AI_QUOTA: AiQuotaConfig;
 /**
  * Resolves the quota limits for a scope. Returning `null` exempts the scope
  * from all quota enforcement (the check short-circuits to success).
  */
-type AiQuotaConfigResolver = (partitionKey: string) => AiQuotaConfig | null | Promise<AiQuotaConfig | null>;
+export type AiQuotaConfigResolver = (partitionKey: string) => AiQuotaConfig | null | Promise<AiQuotaConfig | null>;
 /** A `[startDate, endDate]` inclusive query over the daily-usage rollup (dates are `YYYY-MM-DD`). */
-interface AiUsageCountQuery {
+export interface AiUsageCountQuery {
   partitionKey: string;
   /** Inclusive lower bound, `YYYY-MM-DD`. */
   startDate: string;
@@ -232,16 +241,16 @@ interface AiUsageCountQuery {
  * (e.g. excluding synthetic embedding rows from the count) lives in the
  * consumer's SQL, keeping this layer policy-agnostic.
  */
-interface AiQuotaStore {
+export interface AiQuotaStore {
   /** Number of workflows currently `running` for the scope. */
   countRunningWorkflows(partitionKey: string): Promise<number>;
   /** Sum of `workflowCount` in the daily rollup over the inclusive date range. */
   sumWorkflowCount(query: AiUsageCountQuery): Promise<number>;
 }
 /** Reason a start was rejected — which window tripped. */
-type AiQuotaExceededReason = 'concurrent_limit' | 'daily_limit' | 'monthly_limit';
+export type AiQuotaExceededReason = 'concurrent_limit' | 'daily_limit' | 'monthly_limit';
 /** Expected error value when a start is rejected by quota. Extends flow's structural error. */
-interface AiQuotaExceededError {
+export interface AiQuotaExceededError {
   key: 'ai_quota_exceeded';
   reason: AiQuotaExceededReason;
   message: string;
@@ -250,7 +259,7 @@ interface AiQuotaExceededError {
   /** The observed count at rejection (includes in-flight runs for the day/month windows). */
   current: number;
 }
-interface CreateAiQuotaServiceDeps {
+export interface CreateAiQuotaServiceDeps {
   /** Count reads over the in-flight workflow table + daily rollup. */
   store: AiQuotaStore;
   /** Per-scope limit resolver. Return `null` to exempt the scope. */
@@ -258,7 +267,7 @@ interface CreateAiQuotaServiceDeps {
   /** Clock injection for window computation (tests). Defaults to `() => new Date()`. */
   now?: () => Date;
 }
-interface AiQuotaService {
+export interface AiQuotaService {
   /**
    * Check all quota windows for the scope. Resolves `ok` when the start is
    * allowed, or an {@link AiQuotaExceededError} naming the window that tripped.
@@ -271,11 +280,11 @@ interface AiQuotaService {
  * Build a store-agnostic AI quota service. Enforcement order is concurrent →
  * day → month; the first tripped window short-circuits with its error.
  */
-declare function createAiQuotaService(deps: CreateAiQuotaServiceDeps): AiQuotaService;
+export declare function createAiQuotaService(deps: CreateAiQuotaServiceDeps): AiQuotaService;
 //#endregion
 //#region src/ai/usage-aggregation.d.ts
 /** An additive write into the daily-usage rollup for one run (workflow completion or embedding batch). */
-interface DailyUsageDelta {
+export interface DailyUsageDelta {
   partitionKey: string;
   /** Calendar day of the run, `YYYY-MM-DD`. */
   date: string;
@@ -290,13 +299,13 @@ interface DailyUsageDelta {
   estimatedCostMicros: number;
 }
 /** Inclusive `[startDate, endDate]` range query for the aggregate reads (`YYYY-MM-DD`). */
-interface AiUsageRangeQuery {
+export interface AiUsageRangeQuery {
   partitionKey: string;
   startDate: string;
   endDate: string;
 }
 /** One row of the per-day aggregate (GROUP BY date). */
-interface UsageSummaryRow {
+export interface UsageSummaryRow {
   date: string;
   workflowCount: number;
   inputTokens: number;
@@ -306,7 +315,7 @@ interface UsageSummaryRow {
   estimatedCostMicros: number;
 }
 /** One row of the per-type aggregate (GROUP BY workflowType, keySource). */
-interface UsageByTypeRow {
+export interface UsageByTypeRow {
   workflowType: string;
   keySource: string;
   workflowCount: number;
@@ -320,7 +329,7 @@ interface UsageByTypeRow {
  * and aggregation engines. The `addDailyUsage` UPSERT and the two aggregate
  * reads are the consumer's SQL; flow owns everything above the seam.
  */
-interface AiUsageStore extends AiQuotaStore {
+export interface AiUsageStore extends AiQuotaStore {
   /** UPSERT-add a run's usage into the daily rollup (unique on partition+date+type+keySource). */
   addDailyUsage(delta: DailyUsageDelta): Promise<void>;
   /** Per-day totals over the range, ascending by date. */
@@ -329,7 +338,7 @@ interface AiUsageStore extends AiQuotaStore {
   aggregateByWorkflowType(query: AiUsageRangeQuery): Promise<UsageByTypeRow[]>;
 }
 /** A completed LLM workflow's usage to roll up. */
-interface WorkflowUsageInput {
+export interface WorkflowUsageInput {
   partitionKey: string;
   /** Calendar day of completion, `YYYY-MM-DD`. */
   date: string;
@@ -343,7 +352,7 @@ interface WorkflowUsageInput {
  * tokens (no output, no cache); `workflowCount` increments once per flushed
  * batch, not per inner embed call.
  */
-interface EmbeddingUsageInput {
+export interface EmbeddingUsageInput {
   partitionKey: string;
   /** Calendar day of the flush, `YYYY-MM-DD`. */
   date: string;
@@ -354,7 +363,7 @@ interface EmbeddingUsageInput {
   estimatedCostMicros: number;
 }
 /** Current-window usage snapshot for a scope. */
-interface CurrentQuotaUsage {
+export interface CurrentQuotaUsage {
   today: {
     workflowCount: number;
   };
@@ -366,18 +375,18 @@ interface CurrentQuotaUsage {
   };
 }
 /** Expected error value from aggregation reads/writes. Extends flow's structural error. */
-interface AiUsageError {
+export interface AiUsageError {
   key: 'ai_usage_error';
   message: string;
 }
-interface CreateAiUsageAggregationServiceDeps {
+export interface CreateAiUsageAggregationServiceDeps {
   store: AiUsageStore;
   /** Clock injection for the current-window computation (tests). Defaults to `() => new Date()`. */
   now?: () => Date;
   /** Optional logger for write failures. Defaults to a no-op. */
   logger?: Logger;
 }
-interface AiUsageAggregationService {
+export interface AiUsageAggregationService {
   /** Roll a completed LLM workflow's totals into the daily aggregate (UPSERT +1). */
   recordWorkflowCompletion(data: WorkflowUsageInput): Promise<Result<void, AiUsageError>>;
   /** Roll a flushed embedding batch into the daily aggregate (output/cache tokens = 0). */
@@ -392,6 +401,146 @@ interface AiUsageAggregationService {
   }): Promise<Result<CurrentQuotaUsage, AiUsageError>>;
 }
 /** Build a store-agnostic AI usage-aggregation service. */
-declare function createAiUsageAggregationService(deps: CreateAiUsageAggregationServiceDeps): AiUsageAggregationService;
+export declare function createAiUsageAggregationService(deps: CreateAiUsageAggregationServiceDeps): AiUsageAggregationService;
+//#endregion
+//#region src/ai/refusal.d.ts
+/** The unified finish reason the AI SDK reports for a declined generation. */
+export declare const REFUSAL_FINISH_REASON = "content-filter";
+/**
+ * What the provider said about a refusal. Every field is optional except the
+ * model: providers other than Anthropic report the refusal without the
+ * `stop_details` breakdown, and Anthropic itself only sends `category` and
+ * `explanation` for some categories.
+ */
+export interface AiRefusalDetails {
+  /** The model that declined. */
+  modelId: string;
+  /** Provider's refusal category — Anthropic's `stop_details.category`. */
+  category?: string;
+  /** Provider's prose reason, when it sends one. */
+  explanation?: string;
+  /** The model the provider suggests retrying on (`stop_details.recommended_model`). */
+  recommendedModel?: string;
+  /** The provider's own stop reason (`refusal` on Anthropic), before unification. */
+  rawFinishReason?: string;
+}
+/**
+ * A generation the model declined to produce.
+ *
+ * Distinct from a transport failure on purpose: it is deterministic, so
+ * retrying the same prompt on the same model produces the same refusal. Callers
+ * that classify retryability must treat it as terminal — `defineAiStep` does
+ * this for every AI workflow step.
+ */
+export declare class AiRefusalError extends Error {
+  readonly name = "AiRefusalError";
+  readonly details: AiRefusalDetails;
+  constructor(details: AiRefusalDetails);
+}
+/**
+ * True when `error` is an {@link AiRefusalError}, or wraps one as its `cause`.
+ *
+ * Walks the chain because the SDK layer between the middleware and the caller
+ * may re-wrap: `generateObject`, for instance, reports parse failures as
+ * `NoObjectGeneratedError` with the original as `cause`. Depth-capped and
+ * cycle-safe.
+ */
+export declare function isAiRefusalError(error: unknown): error is AiRefusalError;
+/**
+ * Pull the provider's refusal breakdown out of `providerMetadata`.
+ *
+ * Scans every provider namespace for a `stopDetails` record rather than reading
+ * `providerMetadata.anthropic` directly — the shape is Anthropic's today, and
+ * the surrounding module is deliberately provider-agnostic. A provider that
+ * reports a refusal with no breakdown simply yields no fields.
+ */
+export declare function readRefusalDetails(providerMetadata: SharedV4ProviderMetadata | undefined): Omit<AiRefusalDetails, 'modelId'>;
+/**
+ * Wrap a model so a declined generation throws {@link AiRefusalError} instead
+ * of returning empty content.
+ *
+ * **`doGenerate` only, on purpose.** One-shot calls — every AI workflow step,
+ * every ad-hoc generation service, both classifiers — have no way to present a
+ * refusal to anyone: their contract is "return the value or fail", so a refusal
+ * that does not throw becomes an empty field or an unparseable object several
+ * frames away from its cause. The streaming path is the opposite case: the help
+ * chat is a conversation, where a decline is a legitimate turn the operator
+ * should *read*, and it already has a refusal surface (the `refusal` data part)
+ * for exactly that. `ChatAgentService` branches on the finish reason in
+ * `onFinish` instead, so the stream stays a stream.
+ */
+export declare function createRefusalAwareModel(model: LanguageModelV4): LanguageModelV4;
+//#endregion
+//#region src/ai/capabilities.d.ts
+/**
+ * Per-model API capability switches.
+ *
+ * Claude 4.6+ models (Opus 4.6/4.7/4.8/5, Sonnet 4.6/5, Fable/Mythos 5) use
+ * adaptive thinking; on 4.7+ the legacy `thinking: { type: 'enabled',
+ * budget_tokens }` shape and non-default sampling params (`temperature`,
+ * `top_p`, `top_k`) are rejected with a 400. Older models (Haiku 4.5,
+ * Sonnet 4.5, …) still require `enabled` + budgetTokens for extended
+ * thinking and accept `temperature`.
+ *
+ * A BYOK deployment lets a caller name any model id, so call sites must
+ * branch on the resolved id rather than assume one API shape — these
+ * functions are that branch, written once. `providerId` is a plain string:
+ * only `'anthropic'` has provider-specific shapes today.
+ */
+/** True for Claude 4.6+ / 5-family models: adaptive thinking, no budgetTokens, no sampling params. */
+export declare function supportsAdaptiveThinking(modelId: string): boolean;
+export interface AnthropicThinkingSettings {
+  temperature?: number;
+  headers?: Record<string, string>;
+  providerOptions: {
+    anthropic: {
+      thinking: {
+        type: 'adaptive';
+        display: 'summarized';
+      } | {
+        type: 'enabled';
+        budgetTokens: number;
+      };
+    };
+  };
+}
+/**
+ * Spreadable `streamText`/`generateText` settings for a thinking-enabled
+ * agent loop, shaped for the target model's API generation.
+ *
+ * - Adaptive models: `thinking: { type: 'adaptive' }` with summarized display
+ *   (the default `omitted` streams empty reasoning parts to the client).
+ *   Interleaved thinking is implicit — no beta header, no temperature.
+ * - Legacy models: extended thinking with a token budget, the interleaved
+ *   thinking beta header, and the caller's temperature.
+ */
+export declare function anthropicThinkingSettings(modelId: string, opts: {
+  temperature: number;
+  budgetTokens: number;
+}): AnthropicThinkingSettings;
+/**
+ * True when the provider+model pair supports Anthropic's tool search tool.
+ * Anthropic-only — like the thinking/beta-header shapes, `deferLoading`
+ * provider options and the search tool must never be emitted for another
+ * vendor. Unknown or pre-4.5 Anthropic model ids return false so callers
+ * fall back to shipping the full tool registry undeferred.
+ */
+export declare function supportsToolSearch(providerId: string, modelId: string): boolean;
+export interface ThinkingSettings {
+  temperature?: number;
+  headers?: Record<string, string>;
+  providerOptions?: AnthropicThinkingSettings['providerOptions'];
+}
+/**
+ * Provider-neutral wrapper around {@link anthropicThinkingSettings}. Other
+ * providers have no thinking/beta-header surface — they just get the caller's
+ * temperature. Never emit `providerOptions.anthropic` (or the beta header) for
+ * another vendor's model, even though it would be ignored on the wire — it
+ * pollutes request logs and breaks request-shape tests.
+ */
+export declare function thinkingSettingsFor(providerId: string, modelId: string, opts: {
+  temperature: number;
+  budgetTokens: number;
+}): ThinkingSettings;
 //#endregion
-export { AccumulatedUsage, AiContext, AiModelResolver, AiQuotaConfig, AiQuotaConfigResolver, AiQuotaExceededError, AiQuotaExceededReason, AiQuotaPolicy, AiQuotaService, AiQuotaStore, AiTypedStep, AiUsageAggregationService, AiUsageCountQuery, AiUsageError, AiUsageRangeQuery, AiUsageRecorder, AiUsageStore, CostEstimator, CostEstimatorOptions, CreateAiQuotaServiceDeps, CreateAiUsageAggregationServiceDeps, CreateAiWorkflowHooksDeps, CurrentQuotaUsage, DEFAULT_AI_QUOTA, DEFAULT_MODEL_PRICING, DailyUsageDelta, EmbeddingAccumulatedUsage, EmbeddingUsageAccumulator, EmbeddingUsageInput, ModelPricing, TokenUsage, UsageAccumulator, UsageByTypeRow, UsageSummaryRow, WorkflowUsageInput, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createUsageAccumulator, defineAiStep, estimateCostMicros };
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiVendorResidency, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, embeddingDimensionsFor };