octaflow 0.33.0 → 0.35.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 three tables (`createPgModelRunnerStore` + `modelRunnerDdl`; `modelRunnerColumns`, `modelRunnerRequestColumns`, `modelRunnerChunkColumns`) whose rows live only while a call is in flight, a streamed answer's parts chunk by chunk among them; nobody online fails the call at once, so the breaker trips and the probe answers in milliseconds; `octaflow-runner` is the runner as a process (Ollama or any OpenAI-compatible server) |
 | 🧱 | **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 nine 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`, `model_runner_chunk`). 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,7 +272,8 @@ 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
+`flowStepEventColumns`, `flowRateBucketColumns`, `flowStepLeaseColumns`, `modelProviderColumns`,
+`modelRunnerColumns`, `modelRunnerRequestColumns` and `modelRunnerChunkColumns` (`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,69 @@ 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 — the bin, or the loop in your own process
+//   npx octaflow-runner --url https://app.example/api/model-runner --token omr_… --ollama http://localhost:11434
+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' }),
+});
+```
+
+**`octaflow-runner`**, the bin, is the runner as a process: `--url` and `--token` (or
+`OCTAFLOW_RUNNER_URL` / `OCTAFLOW_RUNNER_TOKEN`), one backend — `--ollama <url>` for Ollama's
+native API, `--openai-compatible <url>` (with `--api-key`) for mlx_lm.server, vLLM or llama.cpp
+through the optional `@ai-sdk/openai-compatible` peer — and `--concurrency`. At start it says
+who the token belongs to, which models the app's provider rows declare for its tags (the door
+tells it) and which of them the local server has, with the `ollama pull` for a missing one;
+`--check` does that and exits. A door it cannot reach is retried with a backoff, forever.
+The skill `serve-a-model-from-a-runner` walks through the four pieces.
+
+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.
+`streamText` streams: the runner runs `doStream` and posts the parts in chunks as they come
+(every 100 ms, or 64 parts), a third table carries them, and the app emits each chunk as it
+lands; a chunk the door refuses tells the runner the caller gave up, and it cancels the
+stream. A runner on the older wire answers a stream whole, and the app emits that as parts
+too. 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/bin/octaflow-runner.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * octaflow-runner — serve a model to an app from a machine the app cannot reach.
+ *
+ * The runner connects *out* to the app's door (`@octabits-io/server/fetch/octaflow`'s
+ * `createModelRunnerHandler`) with the token an administrator minted for it, asks for the model
+ * calls that carry its tags and runs them on the server beside it — Ollama, or anything with
+ * OpenAI's chat API (mlx_lm.server, vLLM, llama.cpp) — and posts the answers back. No port is
+ * opened; the machine needs a way out and nothing else.
+ *
+ *   octaflow-runner --url https://app.example/api/model-runner --token omr_… --ollama http://localhost:11434
+ *   octaflow-runner --url … --token … --openai-compatible http://localhost:8081/v1 [--api-key …]
+ *
+ *   --url <url>                   the door; or OCTAFLOW_RUNNER_URL
+ *   --token <token>               the runner's token, shown once when it was registered; or OCTAFLOW_RUNNER_TOKEN
+ *   --ollama <url>                serve from Ollama's native API at this URL (num_ctx, thinking, keep_alive per model honoured)
+ *   --openai-compatible <url>     serve from an OpenAI-compatible server at this base URL (its `/v1`)
+ *   --api-key <key>               the key that server wants, if any; or OCTAFLOW_RUNNER_API_KEY
+ *   --concurrency <n>             requests in flight at once (default 1 — mlx_lm.server answers one at a time); the door caps it at what was registered
+ *   --check                       connect, say who the token belongs to and whether each model the app declares is installed, then exit
+ *   --quiet                       log failures only
+ *   --help
+ *
+ * At start the runner says who it is and which models the app's provider rows declare for its
+ * tags, and asks the local server which of them it has: a missing one is a warning with the
+ * command that installs it, not a refusal — the app may declare a model it will ask for later.
+ */
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const USAGE = `octaflow-runner — serve a model to an app from a machine the app cannot reach
+
+  octaflow-runner --url <door> --token <token> (--ollama <url> | --openai-compatible <url> [--api-key <key>]) [--concurrency <n>] [--check] [--quiet]
+
+  --url                 the app's door (OCTAFLOW_RUNNER_URL)
+  --token               the runner's token (OCTAFLOW_RUNNER_TOKEN)
+  --ollama              Ollama's native API, e.g. http://localhost:11434
+  --openai-compatible   an OpenAI-compatible base URL, e.g. http://localhost:8081/v1 (mlx_lm.server, vLLM, llama.cpp)
+  --api-key             that server's key, if it wants one (OCTAFLOW_RUNNER_API_KEY)
+  --concurrency         requests at once (default 1)
+  --check               connect and report, then exit
+  --quiet               log failures only
+`;
+
+/** The command line and the environment as one configuration, or the reason it is not one. */
+export function readArgs(argv, env = process.env) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: {
+        url: { type: 'string' },
+        token: { type: 'string' },
+        ollama: { type: 'string' },
+        'openai-compatible': { type: 'string' },
+        'api-key': { type: 'string' },
+        concurrency: { type: 'string' },
+        check: { type: 'boolean', default: false },
+        quiet: { type: 'boolean', default: false },
+        help: { type: 'boolean', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+  if (values.help) return { help: true };
+  const url = values.url ?? env.OCTAFLOW_RUNNER_URL;
+  const token = values.token ?? env.OCTAFLOW_RUNNER_TOKEN;
+  if (!url) return { error: 'the door is missing: --url or OCTAFLOW_RUNNER_URL' };
+  if (!token) return { error: 'the token is missing: --token or OCTAFLOW_RUNNER_TOKEN' };
+  if (values.ollama && values['openai-compatible']) return { error: 'one backend: --ollama or --openai-compatible, not both' };
+  if (!values.ollama && !values['openai-compatible']) return { error: 'a backend is missing: --ollama <url> or --openai-compatible <url>' };
+  const concurrency = values.concurrency === undefined ? 1 : Number(values.concurrency);
+  if (!Number.isInteger(concurrency) || concurrency < 1) return { error: `--concurrency wants a whole number of 1 or more, not '${values.concurrency}'` };
+  return {
+    url,
+    token,
+    backend: values.ollama ? { kind: 'ollama', url: values.ollama } : { kind: 'openai-compatible', url: values['openai-compatible'], apiKey: values['api-key'] ?? env.OCTAFLOW_RUNNER_API_KEY },
+    concurrency,
+    check: values.check,
+    quiet: values.quiet,
+  };
+}
+
+/** The model ids the local server has, or `null` when it could not be asked. */
+export async function installedModels(backend, fetchImpl = fetch) {
+  try {
+    if (backend.kind === 'ollama') {
+      const res = await fetchImpl(`${backend.url.replace(/\/+$/, '')}/api/tags`, { signal: AbortSignal.timeout(5000) });
+      if (!res.ok) return null;
+      const body = await res.json();
+      return (body.models ?? []).map((m) => m.name ?? m.model).filter(Boolean);
+    }
+    const res = await fetchImpl(`${backend.url.replace(/\/+$/, '')}/models`, {
+      headers: backend.apiKey ? { authorization: `Bearer ${backend.apiKey}` } : {},
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return (body.data ?? []).map((m) => m.id).filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+/** Ollama lists `name:tag`; an app may declare `name` alone and mean `name:latest`. */
+const sameModel = (declared, installed) => declared === installed || `${declared}:latest` === installed || declared === `${installed}:latest`;
+
+/** The lines the start-up report prints — what the token is, what the app declares, what is there. */
+export function startupReport(self, installed, backend) {
+  const lines = [`connected as ${self.id} (${self.label}) — tags ${self.tags.join(', ')}, up to ${self.concurrency} at once`];
+  if (self.models.length === 0) lines.push('the app declares no models for these tags yet — a provider row of kind `runner` with these tags names them');
+  for (const model of self.models) {
+    if (installed === null) lines.push(`  ${model} — the local server could not be asked whether it is installed`);
+    else if (installed.some((i) => sameModel(model, i))) lines.push(`  ${model} — installed`);
+    else lines.push(`  ${model} — NOT installed${backend.kind === 'ollama' ? ` (ollama pull ${model})` : ''}`);
+  }
+  return lines;
+}
+
+async function makeBackend(backend) {
+  if (backend.kind === 'ollama') {
+    const { createOllama } = await import('../dist/ai/providers/index.js');
+    return createOllama({ baseUrl: backend.url });
+  }
+  let mod;
+  try {
+    mod = await import('@ai-sdk/openai-compatible');
+  } catch {
+    throw new Error("an OpenAI-compatible backend needs the optional peer '@ai-sdk/openai-compatible' installed beside octaflow");
+  }
+  const sdk = mod.createOpenAICompatible({ name: 'runner', baseURL: backend.url, ...(backend.apiKey ? { apiKey: backend.apiKey } : {}), supportsStructuredOutputs: true });
+  return {
+    languageModel: (id) => sdk.languageModel(id),
+    embeddingModel: (id) => sdk.embeddingModel(id),
+  };
+}
+
+export async function main(argv, env = process.env, io = { out: console.log, err: console.error }) {
+  const args = readArgs(argv, env);
+  if (args.help) {
+    io.out(USAGE);
+    return 0;
+  }
+  if (args.error) {
+    io.err(`octaflow-runner: ${args.error}\n\n${USAGE}`);
+    return 2;
+  }
+  const { createHttpRunnerClient, runModelRunner } = await import('../dist/ai/runner/index.js');
+  const client = createHttpRunnerClient({ url: args.url, token: args.token });
+
+  let self;
+  try {
+    self = await client.self();
+  } catch (error) {
+    io.err(`octaflow-runner: cannot reach the door at ${args.url}: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  const installed = await installedModels(args.backend);
+  for (const line of startupReport(self, installed, args.backend)) io.out(line);
+  if (installed === null) io.err(`octaflow-runner: no model server answered at ${args.backend.url} — requests will fail until it is up`);
+  if (args.check) return installed === null ? 1 : 0;
+
+  const backend = await makeBackend(args.backend);
+  const stop = new AbortController();
+  const onSignal = () => {
+    io.out('stopping — what is in flight is aborted');
+    stop.abort();
+  };
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+
+  io.out(`waiting for work from ${args.url}`);
+  await runModelRunner({
+    client,
+    backend,
+    concurrency: Math.min(args.concurrency, self.concurrency),
+    signal: stop.signal,
+    log: (event) => {
+      switch (event.type) {
+        case 'claimed':
+          if (!args.quiet) io.out(`→ ${event.request.id.slice(0, 8)} ${event.request.kind} ${event.request.model}`);
+          break;
+        case 'delivered':
+          if (!args.quiet || !event.ok) io.out(`${event.ok ? '✓' : '✗'} ${event.requestId.slice(0, 8)} in ${event.elapsedMs} ms`);
+          break;
+        case 'lost':
+          io.err(`✗ ${event.requestId.slice(0, 8)} no longer ours — cancelled by the caller, or the lease ran out`);
+          break;
+        case 'door_unreachable':
+          io.err(`door unreachable (${event.error instanceof Error ? event.error.message : String(event.error)}) — retrying in ${Math.round(event.retryInMs / 1000)} s`);
+          break;
+      }
+    },
+  });
+  return 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (error) => {
+      console.error(`octaflow-runner: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    },
+  );
+}

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 };