octaflow 0.17.3 → 0.19.0

package/dist/ai/index.d.ts

@@ -1,8 +1,9 @@
 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
 export interface AccumulatedUsage {
   inputTokens: number;
@@ -71,7 +72,15 @@ export interface TokenUsage {
   cacheReadTokens: number;
   cacheWriteTokens: number;
 }
-/** Default pricing (USD per million tokens), as of 2026-04. */
+/**
+ * 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`. */
@@ -393,4 +402,145 @@ export interface AiUsageAggregationService {
 }
 /** Build a store-agnostic AI usage-aggregation service. */
 export declare function createAiUsageAggregationService(deps: CreateAiUsageAggregationServiceDeps): AiUsageAggregationService;
-//#endregion
+//#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 { AI_PROVIDERS, AI_PROVIDER_IDS, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiVendorResidency, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, embeddingDimensionsFor };

package/dist/ai/index.js

@@ -1,4 +1,6 @@
 import { S as ok, b as noopLogger, f as defineStep, l as buildWorkflow, x as err } from "../core-DNWPwFaE.js";
+import { a as readRefusalDetails, i as isAiRefusalError, n as REFUSAL_FINISH_REASON, r as createRefusalAwareModel, t as AiRefusalError } from "../refusal-BsL2HPDb.js";
+import { a as EMBEDDING_PROVIDERS, i as DEFAULT_EMBEDDING_PROVIDER, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as embeddingDimensionsFor, t as AI_PROVIDERS } from "../provider-registry-DcRDsjtT.js";
 import { wrapEmbeddingModel, wrapLanguageModel } from "ai";
 //#region src/ai/instrumented-model.ts
 function createUsageAccumulator() {
@@ -121,7 +123,15 @@ function createInstrumentedEmbeddingModel(model, accumulator) {
 }
 //#endregion
 //#region src/ai/cost.ts
-/** Default pricing (USD per million tokens), as of 2026-04. */
+/**
+* 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.
+*/
 const DEFAULT_MODEL_PRICING = {
 	"text-embedding-3-small": {
 		inputPerMillion: .02,
@@ -135,6 +145,48 @@ const DEFAULT_MODEL_PRICING = {
 		cacheReadPerMillion: 0,
 		cacheWritePerMillion: 0
 	},
+	"claude-fable-5": {
+		inputPerMillion: 10,
+		outputPerMillion: 50,
+		cacheReadPerMillion: 1,
+		cacheWritePerMillion: 12.5
+	},
+	"claude-mythos-5": {
+		inputPerMillion: 10,
+		outputPerMillion: 50,
+		cacheReadPerMillion: 1,
+		cacheWritePerMillion: 12.5
+	},
+	"claude-fable-5-1": {
+		inputPerMillion: 10,
+		outputPerMillion: 50,
+		cacheReadPerMillion: .25,
+		cacheWritePerMillion: 12.5
+	},
+	"claude-mythos-5-1": {
+		inputPerMillion: 10,
+		outputPerMillion: 50,
+		cacheReadPerMillion: .25,
+		cacheWritePerMillion: 12.5
+	},
+	"claude-opus-5": {
+		inputPerMillion: 5,
+		outputPerMillion: 25,
+		cacheReadPerMillion: .5,
+		cacheWritePerMillion: 6.25
+	},
+	"claude-sonnet-5": {
+		inputPerMillion: 2,
+		outputPerMillion: 10,
+		cacheReadPerMillion: .2,
+		cacheWritePerMillion: 2.5
+	},
+	"claude-opus-4-8": {
+		inputPerMillion: 5,
+		outputPerMillion: 25,
+		cacheReadPerMillion: .5,
+		cacheWritePerMillion: 6.25
+	},
 	"claude-opus-4-7": {
 		inputPerMillion: 5,
 		outputPerMillion: 25,
@@ -142,10 +194,16 @@ const DEFAULT_MODEL_PRICING = {
 		cacheWritePerMillion: 6.25
 	},
 	"claude-opus-4-6": {
-		inputPerMillion: 15,
-		outputPerMillion: 75,
-		cacheReadPerMillion: 1.5,
-		cacheWritePerMillion: 18.75
+		inputPerMillion: 5,
+		outputPerMillion: 25,
+		cacheReadPerMillion: .5,
+		cacheWritePerMillion: 6.25
+	},
+	"claude-opus-4-5": {
+		inputPerMillion: 5,
+		outputPerMillion: 25,
+		cacheReadPerMillion: .5,
+		cacheWritePerMillion: 6.25
 	},
 	"claude-sonnet-4-6": {
 		inputPerMillion: 3,
@@ -153,17 +211,59 @@ const DEFAULT_MODEL_PRICING = {
 		cacheReadPerMillion: .3,
 		cacheWritePerMillion: 3.75
 	},
+	"claude-sonnet-4-5": {
+		inputPerMillion: 3,
+		outputPerMillion: 15,
+		cacheReadPerMillion: .3,
+		cacheWritePerMillion: 3.75
+	},
 	"claude-sonnet-4-5-20250929": {
 		inputPerMillion: 3,
 		outputPerMillion: 15,
 		cacheReadPerMillion: .3,
 		cacheWritePerMillion: 3.75
 	},
+	"claude-haiku-4-5": {
+		inputPerMillion: 1,
+		outputPerMillion: 5,
+		cacheReadPerMillion: .1,
+		cacheWritePerMillion: 1.25
+	},
 	"claude-haiku-4-5-20251001": {
-		inputPerMillion: .8,
-		outputPerMillion: 4,
-		cacheReadPerMillion: .08,
-		cacheWritePerMillion: 1
+		inputPerMillion: 1,
+		outputPerMillion: 5,
+		cacheReadPerMillion: .1,
+		cacheWritePerMillion: 1.25
+	},
+	"mistral-medium-latest": {
+		inputPerMillion: 1.5,
+		outputPerMillion: 7.5,
+		cacheReadPerMillion: .15,
+		cacheWritePerMillion: 1.5
+	},
+	"mistral-large-latest": {
+		inputPerMillion: .5,
+		outputPerMillion: 1.5,
+		cacheReadPerMillion: .05,
+		cacheWritePerMillion: .5
+	},
+	"mistral-small-latest": {
+		inputPerMillion: .15,
+		outputPerMillion: .6,
+		cacheReadPerMillion: .015,
+		cacheWritePerMillion: .15
+	},
+	"magistral-medium-latest": {
+		inputPerMillion: 2,
+		outputPerMillion: 5,
+		cacheReadPerMillion: .2,
+		cacheWritePerMillion: 2
+	},
+	"mistral-embed": {
+		inputPerMillion: .1,
+		outputPerMillion: 0,
+		cacheReadPerMillion: 0,
+		cacheWritePerMillion: 0
 	}
 };
 function priciest(pricing) {
@@ -463,4 +563,91 @@ function createAiUsageAggregationService(deps) {
 	};
 }
 //#endregion
-export { DEFAULT_AI_QUOTA, DEFAULT_MODEL_PRICING, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createUsageAccumulator, defineAiStep, estimateCostMicros };
+//#region src/ai/capabilities.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.
+*/
+const ADAPTIVE_THINKING_MODEL_PREFIXES = [
+	"claude-fable-5",
+	"claude-mythos-5",
+	"claude-opus-5",
+	"claude-opus-4-8",
+	"claude-opus-4-7",
+	"claude-opus-4-6",
+	"claude-sonnet-5",
+	"claude-sonnet-4-6"
+];
+/** True for Claude 4.6+ / 5-family models: adaptive thinking, no budgetTokens, no sampling params. */
+function supportsAdaptiveThinking(modelId) {
+	return ADAPTIVE_THINKING_MODEL_PREFIXES.some((prefix) => modelId.startsWith(prefix));
+}
+/**
+* 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.
+*/
+function anthropicThinkingSettings(modelId, opts) {
+	if (supportsAdaptiveThinking(modelId)) return { providerOptions: { anthropic: { thinking: {
+		type: "adaptive",
+		display: "summarized"
+	} } } };
+	return {
+		temperature: opts.temperature,
+		headers: { "anthropic-beta": "interleaved-thinking-2025-05-14" },
+		providerOptions: { anthropic: { thinking: {
+			type: "enabled",
+			budgetTokens: opts.budgetTokens
+		} } }
+	};
+}
+/**
+* Models supporting Anthropic's server-side tool search
+* (`tool_search_tool_regex_20251119`) with deferred tool loading — every
+* adaptive-thinking model plus the 4.5 generation.
+*/
+const TOOL_SEARCH_MODEL_PREFIXES = [
+	...ADAPTIVE_THINKING_MODEL_PREFIXES,
+	"claude-opus-4-5",
+	"claude-sonnet-4-5",
+	"claude-haiku-4-5"
+];
+/**
+* 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.
+*/
+function supportsToolSearch(providerId, modelId) {
+	return providerId === "anthropic" && TOOL_SEARCH_MODEL_PREFIXES.some((prefix) => modelId.startsWith(prefix));
+}
+/**
+* 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.
+*/
+function thinkingSettingsFor(providerId, modelId, opts) {
+	if (providerId === "anthropic") return anthropicThinkingSettings(modelId, opts);
+	return { temperature: opts.temperature };
+}
+//#endregion
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_PRICING, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, REFUSAL_FINISH_REASON, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createRefusalAwareModel, createUsageAccumulator, defineAiStep, embeddingDimensionsFor, estimateCostMicros, isAiRefusalError, readRefusalDetails, supportsAdaptiveThinking, supportsToolSearch, thinkingSettingsFor };

package/dist/ai/providers/index.d.ts

@@ -0,0 +1,69 @@
+import { f as EmbeddingProviderId, i as AiProviderId } from "../../provider-registry-bXGOmyeh.js";
+import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
+//#region src/ai/providers/index.d.ts
+export type LanguageModelFactory = (modelId: string) => LanguageModelV4;
+export type EmbeddingModelFactory = (modelId: string) => EmbeddingModelV4;
+/** A language-model factory for a provider, loading its SDK on first use. */
+export declare function createLanguageModelFactory(providerId: AiProviderId, apiKey: string, baseURL?: string): Promise<LanguageModelFactory>;
+/** An embedding-model factory for a provider, loading its SDK on first use. */
+export declare function createEmbeddingModelFactory(providerId: EmbeddingProviderId, apiKey: string, baseURL?: string): Promise<EmbeddingModelFactory>;
+export interface LanguageModelProvider {
+  /** Which vendor the key belongs to — gate provider-specific request shapes on this (see `thinkingSettingsFor`). */
+  providerId: AiProviderId;
+  /** Cheap model for classifier-style passes, from the registry. */
+  classifierModelId: string;
+  /**
+   * A model wrapped for refusal detection: a declined generation throws
+   * `AiRefusalError` from `doGenerate` instead of returning empty content.
+   * Make every one-shot call site go through this and the behaviour is universal.
+   */
+  languageModel(modelId?: string): LanguageModelV4;
+}
+export interface LanguageModelProviderConfig {
+  provider?: AiProviderId;
+  apiKey: string;
+  /** Overrides the registry's default model. */
+  defaultModel?: string;
+  /** Region-pinned endpoint, when the vendor serves one. Undefined = SDK default. */
+  baseUrl?: string;
+}
+/**
+ * The seam a BYOK deployment resolves per scope: key + provider → models.
+ *
+ * ```ts
+ * const models = await createLanguageModelProvider({ provider: 'mistral', apiKey });
+ * const result = await generateText({ model: models.languageModel(), prompt });
+ * ```
+ */
+export declare function createLanguageModelProvider(config: LanguageModelProviderConfig): Promise<LanguageModelProvider>;
+export interface EmbeddingModelProvider {
+  providerId: EmbeddingProviderId;
+  /** The resolved model id — what `embeddingDimensionsFor` should be asked about. */
+  modelId: string;
+  embeddingModel(): EmbeddingModelV4;
+}
+export interface EmbeddingModelProviderConfig {
+  provider?: EmbeddingProviderId;
+  apiKey: string;
+  /** Overrides the registry's default model. */
+  model?: string;
+  /** Region-pinned endpoint, when the vendor serves one. Undefined = SDK default. */
+  baseUrl?: string;
+}
+export declare function createEmbeddingModelProvider(config: EmbeddingModelProviderConfig): Promise<EmbeddingModelProvider>;
+export interface LazyEmbeddingModelMeta {
+  /** Logged as the model's `provider`. */
+  provider: string;
+  modelId: string;
+}
+/**
+ * An `EmbeddingModelV4` whose provider is resolved on first use — for
+ * synchronous wiring (a DI registration, a registry built at boot) that
+ * cannot await {@link createEmbeddingModelProvider}. The V4 contract allows
+ * `maxEmbeddingsPerCall` / `supportsParallelCalls` to be promises, so the
+ * laziness is expressible without a wrapper the caller has to unwrap: `embed()`
+ * awaits them itself. `load` runs at most once; a failure is retried on the
+ * next call rather than cached.
+ */
+export declare function createLazyEmbeddingModel(meta: LazyEmbeddingModelMeta, load: () => Promise<EmbeddingModelV4>): EmbeddingModelV4;
+//#endregion

package/dist/ai/providers/index.js

@@ -0,0 +1,107 @@
+import { r as createRefusalAwareModel } from "../../refusal-BsL2HPDb.js";
+import { a as EMBEDDING_PROVIDERS, t as AI_PROVIDERS } from "../../provider-registry-DcRDsjtT.js";
+//#region src/ai/providers/index.ts
+const LLM_LOADERS = {
+	anthropic: async (apiKey, baseURL) => {
+		const { createAnthropic } = await import("@ai-sdk/anthropic");
+		return createAnthropic({
+			apiKey,
+			baseURL
+		});
+	},
+	mistral: async (apiKey, baseURL) => {
+		const { createMistral } = await import("@ai-sdk/mistral");
+		return createMistral({
+			apiKey,
+			baseURL
+		});
+	}
+};
+const EMBEDDING_LOADERS = {
+	openai: async (apiKey, baseURL) => {
+		const { createOpenAI } = await import("@ai-sdk/openai");
+		const provider = createOpenAI({
+			apiKey,
+			baseURL
+		});
+		return (modelId) => provider.embedding(modelId);
+	},
+	mistral: async (apiKey, baseURL) => {
+		const { createMistral } = await import("@ai-sdk/mistral");
+		const provider = createMistral({
+			apiKey,
+			baseURL
+		});
+		return (modelId) => provider.embedding(modelId);
+	}
+};
+/** A language-model factory for a provider, loading its SDK on first use. */
+function createLanguageModelFactory(providerId, apiKey, baseURL) {
+	return LLM_LOADERS[providerId](apiKey, baseURL);
+}
+/** An embedding-model factory for a provider, loading its SDK on first use. */
+function createEmbeddingModelFactory(providerId, apiKey, baseURL) {
+	return EMBEDDING_LOADERS[providerId](apiKey, baseURL);
+}
+/**
+* The seam a BYOK deployment resolves per scope: key + provider → models.
+*
+* ```ts
+* const models = await createLanguageModelProvider({ provider: 'mistral', apiKey });
+* const result = await generateText({ model: models.languageModel(), prompt });
+* ```
+*/
+async function createLanguageModelProvider(config) {
+	const providerId = config.provider ?? "anthropic";
+	const meta = AI_PROVIDERS[providerId];
+	const factory = await createLanguageModelFactory(providerId, config.apiKey, config.baseUrl);
+	const defaultModel = config.defaultModel ?? meta.defaultModel;
+	return {
+		providerId,
+		classifierModelId: meta.classifierModel,
+		languageModel: (modelId) => createRefusalAwareModel(factory(modelId ?? defaultModel))
+	};
+}
+async function createEmbeddingModelProvider(config) {
+	const providerId = config.provider ?? "openai";
+	const factory = await createEmbeddingModelFactory(providerId, config.apiKey, config.baseUrl);
+	const modelId = config.model ?? EMBEDDING_PROVIDERS[providerId].defaultModel;
+	return {
+		providerId,
+		modelId,
+		embeddingModel: () => factory(modelId)
+	};
+}
+/**
+* An `EmbeddingModelV4` whose provider is resolved on first use — for
+* synchronous wiring (a DI registration, a registry built at boot) that
+* cannot await {@link createEmbeddingModelProvider}. The V4 contract allows
+* `maxEmbeddingsPerCall` / `supportsParallelCalls` to be promises, so the
+* laziness is expressible without a wrapper the caller has to unwrap: `embed()`
+* awaits them itself. `load` runs at most once; a failure is retried on the
+* next call rather than cached.
+*/
+function createLazyEmbeddingModel(meta, load) {
+	let pending;
+	const model = () => {
+		pending ??= load().catch((error) => {
+			pending = void 0;
+			throw error;
+		});
+		return pending;
+	};
+	return {
+		specificationVersion: "v4",
+		provider: meta.provider,
+		modelId: meta.modelId,
+		get maxEmbeddingsPerCall() {
+			return model().then((m) => m.maxEmbeddingsPerCall);
+		},
+		get supportsParallelCalls() {
+			return model().then((m) => m.supportsParallelCalls);
+		},
+		doEmbed: (options) => model().then((m) => m.doEmbed(options))
+	};
+}
+//#endregion
+export { createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel };

package/dist/ai/registry.d.ts

@@ -0,0 +1,2 @@
+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";
+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 };

package/dist/ai/registry.js

@@ -0,0 +1,2 @@
+import { a as EMBEDDING_PROVIDERS, i as DEFAULT_EMBEDDING_PROVIDER, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as embeddingDimensionsFor, t as AI_PROVIDERS } from "../provider-registry-DcRDsjtT.js";
+export { AI_PROVIDERS, AI_PROVIDER_IDS, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, embeddingDimensionsFor };

package/dist/provider-registry-DcRDsjtT.js

@@ -0,0 +1,121 @@
+//#region src/ai/provider-registry.ts
+/**
+* The provider registry — pure metadata about the vendors a BYOK deployment
+* can point at: ids, default and cheap models, where a key is created, and
+* **where the vendor processes what you send it**. Dependency-free, so a
+* browser bundle (a provider/model picker, a residency badge) can import it;
+* the SDK factories that need `@ai-sdk/*` live in `octaflow/ai/providers`.
+*
+* Adding a provider: an id here with its metadata, a factory in
+* `providers/`, and pricing rows in `cost.ts`.
+*/
+const AI_PROVIDER_IDS = ["anthropic", "mistral"];
+const EMBEDDING_PROVIDER_IDS = ["openai", "mistral"];
+/** What an unset provider resolves to. */
+const DEFAULT_AI_PROVIDER = "anthropic";
+const DEFAULT_EMBEDDING_PROVIDER = "openai";
+const AI_PROVIDERS = {
+	anthropic: {
+		id: "anthropic",
+		label: "Anthropic",
+		residency: {
+			region: "third-country",
+			legalName: "Anthropic PBC",
+			country: "US"
+		},
+		defaultModel: "claude-sonnet-5",
+		classifierModel: "claude-haiku-4-5",
+		testModel: "claude-haiku-4-5",
+		keyPrefix: "sk-ant-",
+		consoleKeyUrl: "https://console.anthropic.com/settings/keys",
+		modelOptions: [
+			{
+				label: "Claude Opus 5",
+				value: "claude-opus-5"
+			},
+			{
+				label: "Claude Opus 4.8",
+				value: "claude-opus-4-8"
+			},
+			{
+				label: "Claude Sonnet 5",
+				value: "claude-sonnet-5"
+			},
+			{
+				label: "Claude Haiku 4.5",
+				value: "claude-haiku-4-5"
+			}
+		]
+	},
+	mistral: {
+		id: "mistral",
+		label: "Mistral",
+		residency: {
+			region: "eu",
+			legalName: "Mistral AI SAS",
+			country: "FR"
+		},
+		defaultModel: "mistral-medium-latest",
+		classifierModel: "mistral-small-latest",
+		testModel: "mistral-small-latest",
+		keyPrefix: null,
+		consoleKeyUrl: "https://console.mistral.ai/api-keys",
+		modelOptions: [
+			{
+				label: "Mistral Medium 3.5",
+				value: "mistral-medium-latest"
+			},
+			{
+				label: "Mistral Large 3",
+				value: "mistral-large-latest"
+			},
+			{
+				label: "Mistral Small 4",
+				value: "mistral-small-latest"
+			}
+		]
+	}
+};
+const EMBEDDING_PROVIDERS = {
+	openai: {
+		id: "openai",
+		label: "OpenAI",
+		residency: {
+			region: "third-country",
+			legalName: "OpenAI, L.L.C.",
+			country: "US"
+		},
+		defaultModel: "text-embedding-3-small",
+		consoleKeyUrl: "https://platform.openai.com/api-keys",
+		dimensionsByModel: {
+			"text-embedding-3-small": 1536,
+			"text-embedding-3-large": 3072
+		}
+	},
+	mistral: {
+		id: "mistral",
+		label: "Mistral",
+		residency: {
+			region: "eu",
+			legalName: "Mistral AI SAS",
+			country: "FR"
+		},
+		defaultModel: "mistral-embed",
+		consoleKeyUrl: "https://console.mistral.ai/api-keys",
+		dimensionsByModel: { "mistral-embed": 1024 }
+	}
+};
+/**
+* Vector dimensions for an embedding model id. Unknown ids fall back to
+* `fallback` (default 1536, the common OpenAI-compatible dimension) so
+* free-form model ids keep a working column.
+*/
+function embeddingDimensionsFor(modelId, fallback = 1536) {
+	for (const meta of Object.values(EMBEDDING_PROVIDERS)) {
+		const dims = meta.dimensionsByModel[modelId];
+		if (dims !== void 0) return dims;
+	}
+	return fallback;
+}
+//#endregion
+export { EMBEDDING_PROVIDERS as a, DEFAULT_EMBEDDING_PROVIDER as i, AI_PROVIDER_IDS as n, EMBEDDING_PROVIDER_IDS as o, DEFAULT_AI_PROVIDER as r, embeddingDimensionsFor as s, AI_PROVIDERS as t };

package/dist/provider-registry-bXGOmyeh.d.ts

@@ -0,0 +1,81 @@
+//#region src/ai/provider-registry.d.ts
+/**
+ * The provider registry — pure metadata about the vendors a BYOK deployment
+ * can point at: ids, default and cheap models, where a key is created, and
+ * **where the vendor processes what you send it**. Dependency-free, so a
+ * browser bundle (a provider/model picker, a residency badge) can import it;
+ * the SDK factories that need `@ai-sdk/*` live in `octaflow/ai/providers`.
+ *
+ * Adding a provider: an id here with its metadata, a factory in
+ * `providers/`, and pricing rows in `cost.ts`.
+ */
+declare const AI_PROVIDER_IDS: readonly ['anthropic', 'mistral'];
+type AiProviderId = (typeof AI_PROVIDER_IDS)[number];
+declare const EMBEDDING_PROVIDER_IDS: readonly ['openai', 'mistral'];
+type EmbeddingProviderId = (typeof EMBEDDING_PROVIDER_IDS)[number];
+/** What an unset provider resolves to. */
+declare const DEFAULT_AI_PROVIDER: AiProviderId;
+declare const DEFAULT_EMBEDDING_PROVIDER: EmbeddingProviderId;
+/**
+ * Where a provider processes the payloads you send it.
+ *
+ * `'eu'` means the vendor is established in the EU/EEA and serves the API from
+ * there, so a call carries no third-country transfer under Art. 44 ff. GDPR.
+ * `'third-country'` means it does — your data-processing agreement then has
+ * to carry a transfer mechanism for that vendor.
+ *
+ * This is metadata about the *vendor endpoint called*, not a promise about a
+ * customer's own BYOK key: a customer who brings their own key contracts with
+ * the vendor directly.
+ */
+type AiProcessingRegion = 'eu' | 'third-country';
+interface AiVendorResidency {
+  region: AiProcessingRegion;
+  /** Legal entity, as it appears in a subprocessor annex. */
+  legalName: string;
+  /** Country of establishment, ISO 3166-1 alpha-2. */
+  country: string;
+}
+interface AiProviderModelOption {
+  label: string;
+  value: string;
+}
+interface AiProviderMeta {
+  id: AiProviderId;
+  label: string;
+  /** Where calls to this provider are processed — drives a residency badge and the subprocessor analysis. */
+  residency: AiVendorResidency;
+  /** Default chat/workflow model when nothing sets one. */
+  defaultModel: string;
+  /** Cheap model for classifier-style passes. */
+  classifierModel: string;
+  /** Cheap model for a "test connection" ping. */
+  testModel: string;
+  /** Well-known API key prefix for a soft format hint, or null when the provider has none. */
+  keyPrefix: string | null;
+  /** Where the operator creates an API key. */
+  consoleKeyUrl: string;
+  /** Curated model choices for a picker (free-form custom ids stay allowed). */
+  modelOptions: AiProviderModelOption[];
+}
+declare const AI_PROVIDERS: Record<AiProviderId, AiProviderMeta>;
+interface EmbeddingProviderMeta {
+  id: EmbeddingProviderId;
+  label: string;
+  /** See {@link AiProviderMeta.residency}. */
+  residency: AiVendorResidency;
+  defaultModel: string;
+  /** Where the operator creates an API key. */
+  consoleKeyUrl: string;
+  /** Vector dimensions per known model id — must match the `vector(N)` column in your schema. */
+  dimensionsByModel: Record<string, number>;
+}
+declare const EMBEDDING_PROVIDERS: Record<EmbeddingProviderId, EmbeddingProviderMeta>;
+/**
+ * Vector dimensions for an embedding model id. Unknown ids fall back to
+ * `fallback` (default 1536, the common OpenAI-compatible dimension) so
+ * free-form model ids keep a working column.
+ */
+declare function embeddingDimensionsFor(modelId: string, fallback?: number): number;
+//#endregion
+export { AiProviderMeta as a, DEFAULT_AI_PROVIDER as c, EMBEDDING_PROVIDER_IDS as d, EmbeddingProviderId as f, AiProviderId as i, DEFAULT_EMBEDDING_PROVIDER as l, embeddingDimensionsFor as m, AI_PROVIDER_IDS as n, AiProviderModelOption as o, EmbeddingProviderMeta as p, AiProcessingRegion as r, AiVendorResidency as s, AI_PROVIDERS as t, EMBEDDING_PROVIDERS as u };

package/dist/refusal-BsL2HPDb.js

@@ -0,0 +1,104 @@
+import { wrapLanguageModel } from "ai";
+//#region src/ai/refusal.ts
+/** The unified finish reason the AI SDK reports for a declined generation. */
+const REFUSAL_FINISH_REASON = "content-filter";
+/**
+* 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.
+*/
+var AiRefusalError = class extends Error {
+	name = "AiRefusalError";
+	details;
+	constructor(details) {
+		super(refusalMessage(details));
+		this.details = details;
+	}
+};
+function refusalMessage(details) {
+	const parts = [`${details.modelId} declined to answer`];
+	if (details.category) parts.push(`(${details.category})`);
+	if (details.explanation) parts.push(`— ${details.explanation}`);
+	return parts.join(" ");
+}
+/** How deep to follow `cause` before giving up. Guards against pathological chains. */
+const MAX_CAUSE_DEPTH = 8;
+/**
+* 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.
+*/
+function isAiRefusalError(error) {
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
+		if (typeof current !== "object" || current === null || seen.has(current)) return false;
+		if (current instanceof AiRefusalError) return true;
+		seen.add(current);
+		current = current.cause;
+	}
+	return false;
+}
+/**
+* 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.
+*/
+function readRefusalDetails(providerMetadata) {
+	for (const namespace of Object.values(providerMetadata ?? {})) {
+		const stopDetails = namespace?.stopDetails;
+		if (typeof stopDetails !== "object" || stopDetails === null || Array.isArray(stopDetails)) continue;
+		const read = (key) => {
+			const value = stopDetails[key];
+			return typeof value === "string" && value.length > 0 ? value : void 0;
+		};
+		return {
+			...read("category") ? { category: read("category") } : {},
+			...read("explanation") ? { explanation: read("explanation") } : {},
+			...read("recommendedModel") ? { recommendedModel: read("recommendedModel") } : {}
+		};
+	}
+	return {};
+}
+/**
+* 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.
+*/
+function createRefusalAwareModel(model) {
+	return wrapLanguageModel({
+		model,
+		middleware: {
+			specificationVersion: "v4",
+			wrapGenerate: async ({ doGenerate }) => {
+				const result = await doGenerate();
+				if (result.finishReason.unified === "content-filter") throw new AiRefusalError({
+					modelId: model.modelId,
+					...readRefusalDetails(result.providerMetadata),
+					...result.finishReason.raw ? { rawFinishReason: result.finishReason.raw } : {}
+				});
+				return result;
+			}
+		}
+	});
+}
+//#endregion
+export { readRefusalDetails as a, isAiRefusalError as i, REFUSAL_FINISH_REASON as n, createRefusalAwareModel as r, AiRefusalError as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.17.3",
+  "version": "0.19.0",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss, with an optional AI add-on (token/cost/quota). Layered single package.",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,16 @@
       "types": "./dist/dispatcher-pgboss/index.d.ts",
       "import": "./dist/dispatcher-pgboss/index.js",
       "default": "./dist/dispatcher-pgboss/index.js"
+    },
+    "./ai/providers": {
+      "types": "./dist/ai/providers/index.d.ts",
+      "import": "./dist/ai/providers/index.js",
+      "default": "./dist/ai/providers/index.js"
+    },
+    "./ai/registry": {
+      "types": "./dist/ai/registry.d.ts",
+      "import": "./dist/ai/registry.js",
+      "default": "./dist/ai/registry.js"
     }
   },
   "engines": {
@@ -58,6 +68,9 @@
     "zod"
   ],
   "peerDependencies": {
+    "@ai-sdk/anthropic": "^4.0.0",
+    "@ai-sdk/mistral": "^4.0.0",
+    "@ai-sdk/openai": "^4.0.0",
     "@ai-sdk/provider": "^4.0.0",
     "ai": "^7.0.0",
     "pg": "^8.0.0",
@@ -66,6 +79,15 @@
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/mistral": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    },
     "@ai-sdk/provider": {
       "optional": true
     },
@@ -80,6 +102,9 @@
     }
   },
   "devDependencies": {
+    "@ai-sdk/anthropic": "^4.0.49",
+    "@ai-sdk/mistral": "^4.0.39",
+    "@ai-sdk/openai": "^4.0.58",
     "@ai-sdk/provider": "^4.0.10",
     "@testcontainers/postgresql": "^12.1.0",
     "@types/node": "^26.4.1",