octaflow 0.33.0 → 0.34.0

package/README.md

@@ -216,7 +216,9 @@ next to what your steps actually do.
 | 🚑 | **Crash recovery** — a step whose worker died is re-queued while its attempt budget lasts |
 | 💓 | **Heartbeats** — a long step proves it is alive, so a dead one is caught in seconds, not minutes |
 | 🔭 | **Observability** — lifecycle events (run history), per-step spans, and `createMeterObserver` turning the events into OpenTelemetry-style metrics — all pluggable, all structural |
-| 🤖 | **AI add-on** — instrumented models, token/cost capture, quota, daily rollups, a `usage` sink that books each step into `@octabits-io/metering` (the paid APIs around the model in the same table, priced at read time), refusal-aware models, lenient JSON from local models (`withJsonRepair`), a vendor's refusal explained by key and hint (`explainProviderError`), a per-run circuit breaker, a connection test (`testProvider`) |
+| 🤖 | **AI add-on** — instrumented models, token/cost capture, quota, daily rollups, a `usage` sink that books each step into `@octabits-io/metering` (the paid APIs around the model in the same table, priced at read time), refusal-aware models, lenient JSON from local models (`withJsonRepair`), a vendor's refusal explained by key and hint (`explainProviderError`), a per-run circuit breaker, a connection test (`testProvider`), Ollama's native API as language and embedding models (`createOllama` in `octaflow/ai/providers`: `num_ctx`, thinking and `keep_alive` per model or per call, no dependency) |
+| 🗂️ | **Model providers an administrator manages** — `createModelProviders` (`octaflow/ai`): providers as rows, each with its kind, server, region, a key that crosses a cipher seam, and its models with declared capabilities (temperature, JSON mode, vision, video, tools, embedding); `createPgModelProviderStore` + `modelProviderDdl` (`octaflow/postgres`), `modelProviderColumns` (`octaflow/drizzle`); `createModelResolver` (`octaflow/ai/providers`) builds the AI SDK model from a row, shapes each call to what the model declares, hands the host its `destination` for the disclosure guard, and rebuilds after a write |
+| 🏃 | **Model runners** — a model the app cannot reach, served by a process that connects *out*: a provider row of kind `runner` carries tags instead of a URL, a runner registered with a token (`octaflow/ai/runner`: `createModelRunnerHub`, shown once, kept as a hash) subscribes with its tags, claims the calls by long-poll through `@octabits-io/server/fetch/octaflow`'s `createModelRunnerHandler` and posts the answers back; the mailbox is two tables (`createPgModelRunnerStore` + `modelRunnerDdl`, `modelRunnerColumns` + `modelRunnerRequestColumns`) whose rows live only while a call is in flight; nobody online fails the call at once, so the breaker trips and the probe answers in milliseconds |
 | 🧱 | **Pluggable everything** — `WorkflowStore`, `Dispatcher`, `StepGate`, `FlowObserver`, hooks |
 
 ---
@@ -249,9 +251,10 @@ pnpm add ai @ai-sdk/provider
 
 ### The Postgres tables
 
-`octaflow/postgres` owns five tables and ships their DDL: `flowStoreDdl()` (`flow_workflow`,
-`flow_workflow_step`), `flowEventDdl()` (`flow_step_event`) and `flowGateDdl()`
-(`flow_rate_bucket`, `flow_step_lease`). Each is idempotent `CREATE TABLE IF NOT EXISTS`, takes
+`octaflow/postgres` owns eight tables and ships their DDL: `flowStoreDdl()` (`flow_workflow`,
+`flow_workflow_step`), `flowEventDdl()` (`flow_step_event`), `flowGateDdl()`
+(`flow_rate_bucket`, `flow_step_lease`), `modelProviderDdl()` (`model_provider`) and
+`modelRunnerDdl()` (`model_runner`, `model_runner_request`). Each is idempotent `CREATE TABLE IF NOT EXISTS`, takes
 a `schema`, and is meant to be pasted into your own migration system; `applySchema(pool, ddl)`
 is the dev and test shortcut.
 
@@ -269,8 +272,9 @@ column set, so a host on Drizzle declares it in its own schema and drizzle-kit o
 migration. Where the store's queries are one SQL statement by nature — every one of octaflow's
 is — `./drizzle` ships the columns only, and the store stays the SQL one. So
 `octaflow/drizzle` exports `flowWorkflowColumns`, `flowWorkflowStepColumns`,
-`flowStepEventColumns`, `flowRateBucketColumns` and `flowStepLeaseColumns` (`drizzle-orm` an
-optional peer) and nothing that runs a query. The foreign keys, the composite keys, the unique
+`flowStepEventColumns`, `flowRateBucketColumns`, `flowStepLeaseColumns`, `modelProviderColumns`,
+`modelRunnerColumns` and `modelRunnerRequestColumns` (`drizzle-orm` an optional peer) and
+nothing that runs a query. The foreign keys, the composite keys, the unique
 constraint and the indexes are yours to declare on the `pgTable`; each column set's doc lists
 the ones its DDL creates, and two of them the store relies on:
 
@@ -314,6 +318,56 @@ The store stays plain SQL, bound to the `schema` you hand `createPgWorkflowStore
 declare the tables under the same schema and names. A test in the package holds every column
 set and its DDL equal, column for column: a column added to one side alone fails the build.
 
+### Model runners — a model that connects out
+
+A model the app cannot reach: a laptop with the model loaded for a demo, a GPU box behind
+someone's firewall, a machine that is only on when it is needed. The runner never opens a
+port. It connects *out* to the app with a token, subscribes with its tags, claims the model
+calls that carry those tags and posts the answers back — the shape of a self-hosted CI
+runner. The mailbox is Postgres, because the call runs in the worker and the door the runner
+knocks on runs in the API; a request row lives only while the call is in flight.
+
+```ts
+// the app — once, beside the providers
+import { createModelRunnerHub } from 'octaflow/ai/runner';
+import { createPgModelRunnerStore } from 'octaflow/postgres';
+
+const runners = createModelRunnerHub({ store: createPgModelRunnerStore({ executor }) });
+const resolver = createModelResolver({ providers, runners, wrap });
+
+// an administrator: the provider row carries tags, the runner gets its token once
+await providers.save({ id: 'mac', kind: 'runner', label: 'The Mac', region: 'self-hosted', tags: ['qwen'], models: [{ id: 'qwen3:32b', settings: { numCtx: 16_384 } }] });
+const { token } = (await runners.registerRunner({ id: 'dani-mac', label: "Dani's Mac", tags: ['qwen', 'mac'] })).value;
+
+// the API: the door, behind the host's rate limit
+import { createModelRunnerHandler } from '@octabits-io/server/fetch/octaflow';
+export const POST = compose(withErrorMapping())(createModelRunnerHandler({ prefix: '/api/model-runner', hub: runners }));
+
+// the runner, on the machine with the model
+import { createHttpRunnerClient, runModelRunner } from 'octaflow/ai/runner';
+import { createOllama } from 'octaflow/ai/providers';
+await runModelRunner({
+  client: createHttpRunnerClient({ url: 'https://app.example/api/model-runner', token }),
+  backend: createOllama({ baseUrl: 'http://localhost:11434' }),
+});
+```
+
+A runner may claim a request when it has **every tag** of the request — the provider row's
+tags — as a CI job's labels must all be on the runner. A call with nobody online for its
+tags fails at once with `provider_unreachable`, so `withCircuitBreaker` trips and
+`testProvider` reports it in milliseconds instead of a timeout; whether another provider is
+tried is the host's resolver's choice, through the same disclosure gate. A claim lasts 30 s
+without a heartbeat; an expired claim is requeued once and failed the second time. The
+region is the administrator's declaration about where runners with these tags are, as for
+every provider, and the disclosure gate reads it the same way.
+
+The wire is the AI SDK's own call and answer as JSON — binary file data as base64, a URL
+restored on the other side — so the runner's backend is any `LanguageModelV4`: `createOllama`
+from this package, or `@ai-sdk/openai-compatible` for mlx_lm.server, vLLM and llama.cpp. The
+first version answers whole: `streamText` over a runner model works, emitted as one text
+block when the answer is there. Files reach the runner as bytes, since the runner model
+declares no URL support and the SDK downloads on the app's side. Embeddings go the same way.
+
 ---
 
 ---

package/dist/ai/index.d.ts

@@ -3,6 +3,7 @@ import { n as Logger } from "../logger-BCus3AOa.js";
 import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-DHomzpiq.js";
 import { C as isSubprocessorResidency, S as embeddingDimensionsFor, _ as EmbeddingProviderMeta, a as AiProcessingRegion, b as OpenAiCompatibleProviderId, c as AiProviderModelOption, d as AiVendorResidency, f as DEFAULT_AI_PROVIDER, g as EmbeddingProviderId, h as EMBEDDING_PROVIDER_IDS, i as AiEndpointResidency, l as AiResidencyError, m as EMBEDDING_PROVIDERS, n as AI_PROVIDER_IDS, o as AiProviderId, p as DEFAULT_EMBEDDING_PROVIDER, r as AiEndpointRegion, s as AiProviderMeta, t as AI_PROVIDERS, u as AiResidencyResult, v as OPENAI_COMPATIBLE_PROVIDER, w as resolveEndpointResidency, x as OpenAiCompatibleProviderMeta, y as OPENAI_COMPATIBLE_PROVIDER_ID } from "../provider-registry-C_mOfdHH.js";
 import { A as maskKeys, C as ProviderErrorExplanation, D as explainProviderError, E as ProviderErrorPreset, O as isFatalProviderError, S as ProviderError, T as ProviderErrorPhrase, _ as ExplainProviderErrorOptions, a as OllamaProbeReport, b as PROVIDER_ERROR_REDACTED, c as ProviderProbeOptions, d as testProvider, f as CircuitBreaker, g as DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, h as withCircuitBreaker, i as OllamaProbeOptions, k as isProviderError, l as ProviderProbeReport, m as createCircuitBreaker, n as DEFAULT_PROVIDER_PROBE_PROMPT, o as ProbeableProvider, p as CircuitBreakerOptions, r as DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, s as ProviderProbeFailure, t as DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, u as testOllamaModel, v as FATAL_PROVIDER_ERROR_KEYS, w as ProviderErrorKey, x as PROVIDER_ERROR_STATUS, y as PROVIDER_ERROR_PHRASES } from "../provider-probe-BDg4c1Rk.js";
+import { C as modelProviderInputSchema, S as modelEntrySchema, _ as StoredModelProvider, a as ModelCapabilities, b as maskModelProvider, c as ModelProvider, d as ModelProviderError, f as ModelProviderInput, g as ModelProviders, h as ModelProviderStore, i as MODEL_PROVIDER_REGIONS, l as ModelProviderChange, m as ModelProviderRegion, n as MODEL_JSON_MODES, o as ModelEntry, p as ModelProviderKind, r as MODEL_PROVIDER_KINDS, s as ModelJsonMode, t as CreateModelProvidersOptions, u as ModelProviderCipher, v as createInMemoryModelProviderStore, x as modelCapabilitiesSchema, y as createModelProviders } from "../model-providers-DQU57vAf.js";
 import { z } from "zod";
 import { ToolSet } from "ai";
 import { EmbeddingModelV4, LanguageModelV4, LanguageModelV4Usage, SharedV4ProviderMetadata } from "@ai-sdk/provider";
@@ -1014,4 +1015,4 @@ export interface CaseLoop<TMove extends string, TOutcome extends string, TCase e
  */
 export declare function defineCaseLoop<const TMove extends string, const TOutcome extends string, TCase extends Record<string, unknown>, TResult extends Record<string, unknown>, TDecisions extends AgentExits, TFacts, THost = any>(config: CaseLoopConfig<TMove, TOutcome, TCase, TResult, TDecisions, TFacts, THost>): CaseLoop<TMove, TOutcome, TCase, TResult, TDecisions, TFacts, THost>;
 //#endregion
-export { AI_PROVIDERS, AI_PROVIDER_IDS, AiEndpointRegion, AiEndpointResidency, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiResidencyError, AiResidencyResult, AiVendorResidency, CircuitBreaker, CircuitBreakerOptions, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, ExplainProviderErrorOptions, FATAL_PROVIDER_ERROR_KEYS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, OllamaProbeOptions, OllamaProbeReport, OpenAiCompatibleProviderId, OpenAiCompatibleProviderMeta, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProbeableProvider, ProviderError, ProviderErrorExplanation, ProviderErrorKey, ProviderErrorPhrase, ProviderErrorPreset, ProviderProbeFailure, ProviderProbeOptions, ProviderProbeReport, createCircuitBreaker, embeddingDimensionsFor, explainProviderError, isFatalProviderError, isProviderError, isSubprocessorResidency, maskKeys, resolveEndpointResidency, testOllamaModel, testProvider, withCircuitBreaker };
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiEndpointRegion, AiEndpointResidency, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiResidencyError, AiResidencyResult, AiVendorResidency, CircuitBreaker, CircuitBreakerOptions, CreateModelProvidersOptions, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, ExplainProviderErrorOptions, FATAL_PROVIDER_ERROR_KEYS, MODEL_JSON_MODES, MODEL_PROVIDER_KINDS, MODEL_PROVIDER_REGIONS, ModelCapabilities, ModelEntry, ModelJsonMode, ModelProvider, ModelProviderChange, ModelProviderCipher, ModelProviderError, ModelProviderInput, ModelProviderKind, ModelProviderRegion, ModelProviderStore, ModelProviders, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, OllamaProbeOptions, OllamaProbeReport, OpenAiCompatibleProviderId, OpenAiCompatibleProviderMeta, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProbeableProvider, ProviderError, ProviderErrorExplanation, ProviderErrorKey, ProviderErrorPhrase, ProviderErrorPreset, ProviderProbeFailure, ProviderProbeOptions, ProviderProbeReport, StoredModelProvider, createCircuitBreaker, createInMemoryModelProviderStore, createModelProviders, embeddingDimensionsFor, explainProviderError, isFatalProviderError, isProviderError, isSubprocessorResidency, maskKeys, maskModelProvider, modelCapabilitiesSchema, modelEntrySchema, modelProviderInputSchema, resolveEndpointResidency, testOllamaModel, testProvider, withCircuitBreaker };

package/dist/ai/index.js

@@ -1,7 +1,8 @@
 import { n as err, r as ok, t as noopLogger } from "../logger-epkdcXDA.js";
 import { C as nonRetryableError, _ as defineStep, m as buildWorkflow } from "../core-COMWflJl.js";
-import { S as readRefusalDetails, _ as maskKeys, a as testProvider, b as createRefusalAwareModel, c as DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, d as PROVIDER_ERROR_REDACTED, f as PROVIDER_ERROR_STATUS, g as isProviderError, h as isFatalProviderError, i as testOllamaModel, l as FATAL_PROVIDER_ERROR_KEYS, m as explainProviderError, n as DEFAULT_PROVIDER_PROBE_PROMPT, o as createCircuitBreaker, p as ProviderError, r as DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, s as withCircuitBreaker, t as DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, u as PROVIDER_ERROR_PHRASES, v as AiRefusalError, x as isAiRefusalError, y as REFUSAL_FINISH_REASON } from "../provider-probe-CGN2MpaZ.js";
+import { a as testProvider, c as AiRefusalError, d as isAiRefusalError, f as readRefusalDetails, i as testOllamaModel, l as REFUSAL_FINISH_REASON, n as DEFAULT_PROVIDER_PROBE_PROMPT, o as createCircuitBreaker, r as DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, s as withCircuitBreaker, t as DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, u as createRefusalAwareModel } from "../provider-probe-CwZWwFlo.js";
 import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, i as DEFAULT_EMBEDDING_PROVIDER, l as embeddingDimensionsFor, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as OPENAI_COMPATIBLE_PROVIDER, t as AI_PROVIDERS, u as isSubprocessorResidency } from "../provider-registry-B91lgOmu.js";
+import { a as PROVIDER_ERROR_STATUS, c as isFatalProviderError, i as PROVIDER_ERROR_REDACTED, l as isProviderError, n as FATAL_PROVIDER_ERROR_KEYS, o as ProviderError, r as PROVIDER_ERROR_PHRASES, s as explainProviderError, t as DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, u as maskKeys } from "../provider-errors-DZWjl8di.js";
 import { z } from "zod";
 import { Output, generateText, stepCountIs, tool, wrapEmbeddingModel, wrapLanguageModel } from "ai";
 //#region src/ai/instrumented-model.ts
@@ -1559,4 +1560,269 @@ function defineCaseLoop(config) {
 	};
 }
 //#endregion
-export { AGENT_TRACE_SCHEMA, AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_JSON_EXCERPT_LENGTH, DEFAULT_MODEL_PRICING, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, FATAL_PROVIDER_ERROR_KEYS, MODEL_JSON_PROVIDER_METADATA_KEY, MODEL_JSON_REPAIRED_ATTRIBUTE, ModelJsonError, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProviderError, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, addUsage, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCircuitBreaker, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createModelDecider, createRefusalAwareModel, createUsageAccumulator, defineAgentStep, defineAiStep, defineCaseLoop, embeddingDimensionsFor, estimateCostMicros, excerptOf, explainProviderError, isAiRefusalError, isFatalProviderError, isModelJsonError, isProviderError, isSubprocessorResidency, maskKeys, mergeModelJsonObjects, modelJsonRepairText, parseModelJson, readRefusalDetails, recoverModelJson, resolveEndpointResidency, runAgent, runAgentToExit, supportsAdaptiveThinking, supportsToolSearch, testOllamaModel, testProvider, thinkingSettingsFor, withCircuitBreaker, withJsonRepair };
+//#region src/ai/model-providers.ts
+/** A runner tag — the same rule `model-runner.ts` holds a runner's own tags to. */
+const MODEL_RUNNER_TAG = /^[a-z0-9][a-z0-9._-]{0,62}$/;
+/**
+* The API a provider speaks. `openai-compatible` is any server with OpenAI's
+* chat API (vLLM, LiteLLM, OpenRouter, a gateway). `runner` is no API at all:
+* the models are served by a runner that connects out to the app and claims
+* the calls that carry the row's `tags` (`octaflow/ai/runner`).
+*/
+const MODEL_PROVIDER_KINDS = [
+	"anthropic",
+	"openai",
+	"mistral",
+	"google",
+	"ollama",
+	"openai-compatible",
+	"runner"
+];
+/** Where the data goes: the disclosure destination's region. */
+const MODEL_PROVIDER_REGIONS = [
+	"self-hosted",
+	"eu",
+	"third-country"
+];
+/**
+* How a model is asked for JSON: `schema` — native structured output against
+* a JSON schema; `object` — a JSON mode that guarantees an object but no
+* shape; `prompt` — no JSON mode, the instruction is in the prompt and the
+* answer is parsed.
+*/
+const MODEL_JSON_MODES = [
+	"schema",
+	"object",
+	"prompt"
+];
+const modelCapabilitiesSchema = z.object({
+	/** Takes a sampling temperature. Reasoning models often refuse one. */
+	temperature: z.boolean().default(true),
+	json: z.enum(MODEL_JSON_MODES).default("object"),
+	/** Takes images. */
+	vision: z.boolean().default(false),
+	/** Takes a whole video (a file or, for Gemini, a YouTube URL). */
+	video: z.boolean().default(false),
+	/** Calls tools — what an agent needs. */
+	tools: z.boolean().default(true),
+	/** Embeds text instead of answering. */
+	embedding: z.boolean().default(false)
+});
+const modelEntrySchema = z.object({
+	/** The vendor's model id, e.g. `claude-sonnet-5-5`, `gemini-3.5-flash`, `qwen3:32b`. */
+	id: z.string().min(1),
+	label: z.string().optional(),
+	capabilities: modelCapabilitiesSchema.default(modelCapabilitiesSchema.parse({})),
+	/** The most output tokens a call asks for, when the caller names none. */
+	maxOutputTokens: z.number().int().positive().optional(),
+	/**
+	* Settings the kind understands, passed as given — for `ollama`:
+	* `{ numCtx, think, keepAlive, options }` (see `createOllama`).
+	*/
+	settings: z.record(z.string(), z.unknown()).optional()
+});
+/** What an administrator saves. `apiKey` absent keeps the stored key, `null` removes it. */
+const modelProviderInputSchema = z.object({
+	id: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/, "lowercase letters, digits, - and _; at most 63"),
+	kind: z.enum(MODEL_PROVIDER_KINDS),
+	label: z.string().min(1),
+	/** The server; for a vendor, a region-pinned endpoint or nothing for the SDK's default. */
+	baseUrl: z.string().url().nullish(),
+	region: z.enum(MODEL_PROVIDER_REGIONS),
+	apiKey: z.string().min(1).nullish(),
+	/** Sent with every request — attribution, a gateway's routing. Stored in plain text: never a secret. */
+	headers: z.record(z.string(), z.string()).default({}),
+	/** For `runner`: the tags a runner must have to serve this provider's calls. Empty for every other kind. */
+	tags: z.array(z.string().regex(MODEL_RUNNER_TAG, "lowercase letters, digits, . _ -; at most 63")).max(32).default([]),
+	models: z.array(modelEntrySchema).default([]),
+	defaultModel: z.string().min(1).nullish(),
+	enabled: z.boolean().default(true)
+}).superRefine((p, issue) => {
+	const ids = p.models.map((m) => m.id);
+	const repeated = ids.find((id, i) => ids.indexOf(id) !== i);
+	if (repeated) issue.addIssue({
+		code: "custom",
+		path: ["models"],
+		message: `model '${repeated}' is listed twice`
+	});
+	if (p.defaultModel && !ids.includes(p.defaultModel)) issue.addIssue({
+		code: "custom",
+		path: ["defaultModel"],
+		message: `'${p.defaultModel}' is not one of the models`
+	});
+	if ((p.kind === "ollama" || p.kind === "openai-compatible") && !p.baseUrl) issue.addIssue({
+		code: "custom",
+		path: ["baseUrl"],
+		message: `a ${p.kind} provider needs its server's URL`
+	});
+	if (p.kind === "runner" && p.tags.length === 0) issue.addIssue({
+		code: "custom",
+		path: ["tags"],
+		message: "a runner provider needs at least one tag"
+	});
+	if (p.kind !== "runner" && p.tags.length > 0) issue.addIssue({
+		code: "custom",
+		path: ["tags"],
+		message: `tags are for a runner provider, not a ${p.kind} one`
+	});
+});
+const hintOf = (key) => key.length > 8 ? key.slice(-4) : null;
+function maskModelProvider(row) {
+	const { apiKey, ...rest } = row;
+	return {
+		...rest,
+		hasKey: apiKey !== null
+	};
+}
+/**
+* The providers an administrator manages: validated writes, the key through
+* the cipher, a masked read for the page and a before/after pair for the audit
+* log.
+*
+* ```ts
+* const providers = createModelProviders({ store: createPgModelProviderStore({ executor }), cipher });
+* const saved = await providers.save({ id: 'mistral', kind: 'mistral', label: 'Mistral', region: 'eu', apiKey, models: [{ id: 'mistral-large-latest' }] }, { actor: staffId });
+* ```
+*/
+function createModelProviders(options) {
+	const { store, cipher } = options;
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	let version = 0;
+	const listeners = /* @__PURE__ */ new Set();
+	const changed = (id) => {
+		version++;
+		for (const l of listeners) try {
+			l(id);
+		} catch {}
+	};
+	return {
+		async list(opts) {
+			return (await store.list()).filter((r) => !opts?.enabledOnly || r.enabled).map(maskModelProvider);
+		},
+		async get(id) {
+			const row = await store.get(id);
+			return row && maskModelProvider(row);
+		},
+		async save(input, by) {
+			const parsed = modelProviderInputSchema.safeParse(input);
+			if (!parsed.success) {
+				const issues = parsed.error.issues.map((i) => ({
+					path: i.path.join("."),
+					message: i.message
+				}));
+				return {
+					ok: false,
+					error: {
+						key: "invalid",
+						message: issues.map((i) => `${i.path || "(provider)"}: ${i.message}`).join("; "),
+						issues
+					}
+				};
+			}
+			const p = parsed.data;
+			const before = await store.get(p.id);
+			let apiKey = before?.apiKey ?? null;
+			let keyHint = before?.keyHint ?? null;
+			if (p.apiKey === null) apiKey = keyHint = null;
+			else if (p.apiKey !== void 0) {
+				if (!cipher) return {
+					ok: false,
+					error: {
+						key: "no_cipher",
+						message: "a key can only be saved with a cipher"
+					}
+				};
+				apiKey = await cipher.encrypt(p.apiKey);
+				keyHint = hintOf(p.apiKey);
+			}
+			const row = {
+				id: p.id,
+				kind: p.kind,
+				label: p.label,
+				baseUrl: p.baseUrl ?? null,
+				region: p.region,
+				apiKey,
+				keyHint,
+				headers: p.headers,
+				tags: p.tags,
+				models: p.models,
+				defaultModel: p.defaultModel ?? p.models[0]?.id ?? null,
+				enabled: p.enabled,
+				updatedAt: now(),
+				updatedBy: by?.actor ?? null
+			};
+			await store.put(row);
+			changed(p.id);
+			return {
+				ok: true,
+				value: {
+					id: p.id,
+					before: before && maskModelProvider(before),
+					after: maskModelProvider(row),
+					actor: by?.actor ?? null,
+					reason: by?.reason ?? null
+				}
+			};
+		},
+		async remove(id, by) {
+			const before = await store.get(id);
+			if (!before || !await store.remove(id)) return {
+				ok: false,
+				error: {
+					key: "not_found",
+					message: `no provider '${id}'`
+				}
+			};
+			changed(id);
+			return {
+				ok: true,
+				value: {
+					id,
+					before: maskModelProvider(before),
+					after: null,
+					actor: by?.actor ?? null,
+					reason: by?.reason ?? null
+				}
+			};
+		},
+		async reveal(id) {
+			const row = await store.get(id);
+			if (!row) return null;
+			if (row.apiKey !== null && !cipher) throw new Error(`provider '${id}' has a key, and no cipher was given to read it`);
+			const apiKey = row.apiKey === null ? null : await cipher.decrypt(row.apiKey);
+			return {
+				...maskModelProvider(row),
+				apiKey
+			};
+		},
+		version: () => version,
+		onChange(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		touch() {
+			changed("*");
+		}
+	};
+}
+/** The reference store, in memory — for tests and a host with nothing to persist. */
+function createInMemoryModelProviderStore(rows = []) {
+	const byId = new Map(rows.map((r) => [r.id, structuredClone(r)]));
+	return {
+		async list() {
+			return [...byId.values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).map((r) => structuredClone(r));
+		},
+		async get(id) {
+			const r = byId.get(id);
+			return r ? structuredClone(r) : null;
+		},
+		async put(row) {
+			byId.set(row.id, structuredClone(row));
+		},
+		async remove(id) {
+			return byId.delete(id);
+		}
+	};
+}
+//#endregion
+export { AGENT_TRACE_SCHEMA, AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_JSON_EXCERPT_LENGTH, DEFAULT_MODEL_PRICING, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, FATAL_PROVIDER_ERROR_KEYS, MODEL_JSON_MODES, MODEL_JSON_PROVIDER_METADATA_KEY, MODEL_JSON_REPAIRED_ATTRIBUTE, MODEL_PROVIDER_KINDS, MODEL_PROVIDER_REGIONS, ModelJsonError, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProviderError, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, addUsage, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCircuitBreaker, createCostEstimator, createEmbeddingUsageAccumulator, createInMemoryModelProviderStore, createInstrumentedEmbeddingModel, createInstrumentedModel, createModelDecider, createModelProviders, createRefusalAwareModel, createUsageAccumulator, defineAgentStep, defineAiStep, defineCaseLoop, embeddingDimensionsFor, estimateCostMicros, excerptOf, explainProviderError, isAiRefusalError, isFatalProviderError, isModelJsonError, isProviderError, isSubprocessorResidency, maskKeys, maskModelProvider, mergeModelJsonObjects, modelCapabilitiesSchema, modelEntrySchema, modelJsonRepairText, modelProviderInputSchema, parseModelJson, readRefusalDetails, recoverModelJson, resolveEndpointResidency, runAgent, runAgentToExit, supportsAdaptiveThinking, supportsToolSearch, testOllamaModel, testProvider, thinkingSettingsFor, withCircuitBreaker, withJsonRepair };

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

@@ -1,6 +1,122 @@
 import { b as OpenAiCompatibleProviderId, g as EmbeddingProviderId, i as AiEndpointResidency, o as AiProviderId } from "../../provider-registry-C_mOfdHH.js";
 import { A as maskKeys, C as ProviderErrorExplanation, D as explainProviderError, E as ProviderErrorPreset, O as isFatalProviderError, S as ProviderError, T as ProviderErrorPhrase, _ as ExplainProviderErrorOptions, a as OllamaProbeReport, c as ProviderProbeOptions, d as testProvider, f as CircuitBreaker, h as withCircuitBreaker, i as OllamaProbeOptions, k as isProviderError, l as ProviderProbeReport, m as createCircuitBreaker, o as ProbeableProvider, p as CircuitBreakerOptions, s as ProviderProbeFailure, u as testOllamaModel, v as FATAL_PROVIDER_ERROR_KEYS, w as ProviderErrorKey, x as PROVIDER_ERROR_STATUS, y as PROVIDER_ERROR_PHRASES } from "../../provider-probe-BDg4c1Rk.js";
-import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
+import { a as ModelCapabilities, c as ModelProvider, g as ModelProviders, m as ModelProviderRegion, o as ModelEntry } from "../../model-providers-DQU57vAf.js";
+import { u as ModelRunnerHub } from "../../hub-SXfvoqH3.js";
+import { EmbeddingModelV4, LanguageModelV4, LanguageModelV4CallOptions } from "@ai-sdk/provider";
+//#region src/ai/providers/ollama.d.ts
+/** `false` switches thinking off; a level asks a model that has levels for that much. */
+type OllamaThink = boolean | 'low' | 'medium' | 'high';
+interface OllamaModelSettings {
+  /** The context window in tokens (`num_ctx`). Default: the server's. */
+  numCtx?: number;
+  /** Thinking on, off, or a level. Default: the model's. */
+  think?: OllamaThink;
+  /** How long the model stays loaded after the call: `'15m'`, seconds, or `-1` for ever. Default: the server's. */
+  keepAlive?: string | number;
+  /** Further entries of Ollama's `options` (`repeat_penalty`, `min_p`, …), sent as given. */
+  options?: Record<string, unknown>;
+}
+interface OllamaProviderOptions extends OllamaModelSettings {
+  /** The server, e.g. `http://localhost:11434`. A trailing `/v1` or `/api` is dropped. */
+  baseUrl: string;
+  /** Sent with every request — a proxy's key, say. */
+  headers?: Record<string, string>;
+  /** A fetch of your own: a timeout, a guarded outbound fetch, metering. Default: the global one. */
+  fetch?: typeof fetch;
+}
+interface OllamaProvider {
+  languageModel(modelId: string, settings?: OllamaModelSettings): LanguageModelV4;
+  embeddingModel(modelId: string, settings?: Pick<OllamaModelSettings, 'keepAlive' | 'options'> & {
+    truncate?: boolean;
+  }): EmbeddingModelV4;
+}
+export declare function createOllama(provider: OllamaProviderOptions): OllamaProvider;
+//#endregion
+//#region src/ai/providers/resolve.d.ts
+interface ResolvedModel<M> {
+  model: M;
+  provider: ModelProvider;
+  entry: ModelEntry;
+  /** The disclosure destination this model is: the provider's id and region. */
+  destination: {
+    id: string;
+    region: ModelProviderRegion;
+  };
+}
+type ModelResolveError = {
+  key: 'no_provider';
+  message: string;
+} | {
+  key: 'unknown_provider';
+  message: string;
+} | {
+  key: 'disabled';
+  message: string;
+} | {
+  key: 'unknown_model';
+  message: string;
+} | {
+  key: 'not_capable';
+  message: string;
+  missing: Array<keyof ModelCapabilities>;
+} | {
+  key: 'no_key';
+  message: string;
+} |
+/** A `runner` provider, and the resolver was made without `runners`. */
+{
+  key: 'no_runner_hub';
+  message: string;
+};
+type Resolved<M> = {
+  ok: true;
+  value: ResolvedModel<M>;
+} | {
+  ok: false;
+  error: ModelResolveError;
+};
+interface ModelRef {
+  /** The provider's id; the resolver's `defaultProvider` when absent. */
+  provider?: string;
+  /** The model's id; the provider's default model when absent. */
+  model?: string;
+  /** What the model must be able to do — a vision step asks for `{ vision: true }`. */
+  require?: Partial<Record<keyof ModelCapabilities, true>>;
+}
+interface ModelResolver {
+  languageModel(ref?: ModelRef): Promise<Resolved<LanguageModelV4>>;
+  embeddingModel(ref?: Omit<ModelRef, 'require'>): Promise<Resolved<EmbeddingModelV4>>;
+  /** Drop every cached model — after a write another replica made, when `providers.touch()` is not wired. */
+  invalidate(): void;
+}
+interface CreateModelResolverOptions {
+  providers: ModelProviders;
+  /** The provider a ref without one resolves to — a setting, an env var. */
+  defaultProvider?: () => string | undefined | Promise<string | undefined>;
+  /** The fetch every vendor SDK uses: a timeout, a guarded outbound fetch, metering. */
+  fetch?: typeof fetch;
+  /** The hub a `runner` provider's models go through (`createModelRunnerHub`, `octaflow/ai/runner`). */
+  runners?: ModelRunnerHub;
+  /** What every language model goes through on its way out — the disclosure guard, a breaker. */
+  wrap?: (model: LanguageModelV4, resolved: Omit<ResolvedModel<LanguageModelV4>, 'model'>) => LanguageModelV4;
+  /** The same for embedding models. */
+  wrapEmbedding?: (model: EmbeddingModelV4, resolved: Omit<ResolvedModel<EmbeddingModelV4>, 'model'>) => EmbeddingModelV4;
+}
+/** Shape a call to what the model declares — see the module comment. */
+export declare function shapeCall(params: LanguageModelV4CallOptions, entry: ModelEntry): LanguageModelV4CallOptions;
+/**
+ * ```ts
+ * const models = createModelResolver({
+ *   providers,
+ *   defaultProvider: () => settings.get('MODEL_PROVIDER'),
+ *   wrap: (model, r) => guardLanguageModel(model, { destination: r.destination, classOf: () => 'public', log }),
+ * });
+ * const vision = await models.languageModel({ provider: 'gemini', require: { video: true } });
+ * if (vision.ok) await generateText({ model: vision.value.model, messages });
+ * ```
+ */
+export declare function createModelResolver(options: CreateModelResolverOptions): ModelResolver;
+//#endregion
 //#region src/ai/providers/index.d.ts
 export type LanguageModelFactory = (modelId: string) => LanguageModelV4;
 export type EmbeddingModelFactory = (modelId: string) => EmbeddingModelV4;
@@ -207,4 +323,4 @@ export interface OpenAiCompatibleGatewayProvider {
  */
 export declare function createOpenAiCompatibleGatewayProvider(config: OpenAiCompatibleGatewayConfig): Promise<OpenAiCompatibleGatewayProvider>;
 //#endregion
-export { type CircuitBreaker, type CircuitBreakerOptions, type ExplainProviderErrorOptions, FATAL_PROVIDER_ERROR_KEYS, type OllamaProbeOptions, type OllamaProbeReport, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_STATUS, type ProbeableProvider, ProviderError, type ProviderErrorExplanation, type ProviderErrorKey, type ProviderErrorPhrase, type ProviderErrorPreset, type ProviderProbeFailure, type ProviderProbeOptions, type ProviderProbeReport, createCircuitBreaker, explainProviderError, isFatalProviderError, isProviderError, maskKeys, testOllamaModel, testProvider, withCircuitBreaker };
+export { type CircuitBreaker, type CircuitBreakerOptions, type CreateModelResolverOptions, type ExplainProviderErrorOptions, FATAL_PROVIDER_ERROR_KEYS, type ModelRef, type ModelResolveError, type ModelResolver, type OllamaModelSettings, type OllamaProbeOptions, type OllamaProbeReport, type OllamaProvider, type OllamaProviderOptions, type OllamaThink, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_STATUS, type ProbeableProvider, ProviderError, type ProviderErrorExplanation, type ProviderErrorKey, type ProviderErrorPhrase, type ProviderErrorPreset, type ProviderProbeFailure, type ProviderProbeOptions, type ProviderProbeReport, type ResolvedModel, createCircuitBreaker, explainProviderError, isFatalProviderError, isProviderError, maskKeys, testOllamaModel, testProvider, withCircuitBreaker };