octaflow 0.35.0 → 0.36.0

package/README.md

@@ -202,7 +202,6 @@ next to what your steps actually do.
 | 💤 | **Durable sleep** — hold a step in the queue for N ms (survives restarts) |
 | 🔀 | **Conditional branching** — `when` guards skip a step and its branch; `join: 'any'` converges |
 | 🎯 | **Decisions** — typed choices with a confidence from a swappable decider (a function, a model, your own); below a threshold a person settles it |
-| 🧭 | **Case loops** — `defineCaseLoop` (`octaflow/ai`): a manager agent chooses every next move of a case, each move its own workflow ending in the same tail (result → decide → next); policy refuses a choice with its reason inside the exit's schema, a move with a step that could fail is refused at definition time, and a manager that cannot decide closes the case for a person |
 | ⏳ | **Deadlines** — a budget on a suspended step (fail, or continue with a stand-in answer) and on a whole run |
 | ♻️ | **Retry a failed run** — `retryWorkflow` resumes from the failure point; completed steps keep their output |
 | 🧹 | **Delete the runs about a record** — `purgeWorkflows({ entityRef })` cancels and deletes them with their sub-workflow runs and steps, for an erasure or a deleted record; refuses only while a step is executing |
@@ -216,9 +215,7 @@ 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`), 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) |
+| 🤖 | **The model layer** — AI steps with token and cost capture, quotas, the model decider, agents that end by choosing an exit, case loops, managed providers and model runners: [`@octabits-io/models`](../models/README.md) (`./octaflow` is its binding to this engine; it was `octaflow/ai` until 0.36) |
 | 🧱 | **Pluggable everything** — `WorkflowStore`, `Dispatcher`, `StepGate`, `FlowObserver`, hooks |
 
 ---
@@ -242,8 +239,8 @@ pnpm add drizzle-orm
 # pg-boss dispatcher, workers, cron scheduler
 pnpm add pg-boss
 
-# the AI add-on
-pnpm add ai @ai-sdk/provider
+# the model layer on this engine: AI steps, agents, case loops (its ./octaflow subpath)
+pnpm add @octabits-io/models ai @ai-sdk/provider
 ```
 
 > Pure in-memory usage (great for tests and single-process apps) needs **nothing** beyond
@@ -251,10 +248,10 @@ pnpm add ai @ai-sdk/provider
 
 ### The Postgres tables
 
-`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
+`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`). The model providers' and runners' tables, here until
+0.36, are `@octabits-io/models/postgres`'s. 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.
 
@@ -272,8 +269,7 @@ 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`, `flowStepLeaseColumns`, `modelProviderColumns`,
-`modelRunnerColumns`, `modelRunnerRequestColumns` and `modelRunnerChunkColumns` (`drizzle-orm` an
+`flowStepEventColumns`, `flowRateBucketColumns` and `flowStepLeaseColumns` (`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:
@@ -318,71 +314,6 @@ 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.
-
----
-
 ---
 
 ## Documentation
@@ -405,7 +336,7 @@ Full docs — concepts, every feature, production wiring and the API reference
 | [Postgres & pg-boss](https://octaflow.octabits.io/running/postgres-and-pg-boss/) | production wiring, workers, DLQ, cron |
 | [Cancellation & recovery](https://octaflow.octabits.io/running/cancellation-and-recovery/) | cancelling a run, sweeping steps a crash left behind, retrying a failed run, and deleting the runs about a record |
 | [Observability](https://octaflow.octabits.io/running/observability/) · [Live progress](https://octaflow.octabits.io/running/live-progress/) | lifecycle events, spans, and streaming them to a browser |
-| [The AI add-on](https://octaflow.octabits.io/extending/ai/) | token/cost capture, quota, usage rollups |
+| [The AI add-on](https://octaflow.octabits.io/extending/ai/) | token/cost capture, quota, usage rollups — `@octabits-io/models/octaflow` |
 | [Extending](https://octaflow.octabits.io/extending/interfaces/) | custom stores, dispatchers and gates |
 | [API reference](https://octaflow.octabits.io/reference/api/) | every export, by entry point |
 
@@ -429,7 +360,6 @@ Runnable, focused examples live in [`examples/`](./examples) — see [`examples/
 | 10 | `10-saga-compensation.ts` | reverse-order rollback on failure |
 | 11 | `11-observability.ts` | observer events + tracer spans |
 | 12 | `12-postgres-pgboss-production.ts` | full pg store + gate + event sink + pg-boss + cron |
-| 13 | `13-ai-workflow.ts` | AI add-on (instrumented model + cost) |
 | 14 | `14-live-progress.ts` | `FlowObserver` → SSE fan-out (build your own dashboard) |
 | 15 | `15-conditional-branching.ts` | `when` guards + a `join: 'any'` convergence |
 | 16 | `16-deadlines-and-retry.ts` | wait deadlines, run deadlines, `retryWorkflow`, heartbeats |

package/dist/{core-COMWflJl.js → core-YqnPwR-v.js}

@@ -1,4 +1,112 @@
 import { z } from "zod";
+//#region src/core/gate.ts
+/**
+* The rule keys a request is held to, in the order they are checked: the
+* step's type, then each resource it declares, without repeats. The shipped
+* gates look up their `concurrency` and `rateLimit` rules by these keys, so a
+* rule keyed `'llm:local'` holds every step that names that resource, whatever
+* its type, and a rule keyed by a type still holds that type alone. A custom
+* gate that wants the same vocabulary calls this.
+*/
+function gateRuleKeys(req) {
+	const keys = [req.stepType];
+	for (const resource of req.resources ?? []) if (!keys.includes(resource)) keys.push(resource);
+	return keys;
+}
+/**
+* A per-process {@link StepGate}: concurrency caps (held slots) plus token-bucket
+* rate limits (throughput), each keyed by a step type or by a resource a step
+* declares ({@link gateRuleKeys}). Both are optional; a step none of whose keys
+* has a rule is always admitted, and a step with several keys must pass every
+* rule among them.
+*
+* Concurrency is reserved first, then the rate tokens — so a rate denial does not
+* waste a concurrency slot, and a denial by a later rule gives back what earlier
+* ones granted. Good for single-worker deployments; swap in a shared-store gate
+* for multi-worker concurrency control.
+*/
+function createInMemoryStepGate(config = {}) {
+	const now = config.now ?? (() => Date.now());
+	const concurrencyRetry = Math.max(1, config.concurrencyRetrySeconds ?? 1);
+	const running = /* @__PURE__ */ new Map();
+	const buckets = /* @__PURE__ */ new Map();
+	const capacityOf = (rule) => rule.burst ?? Math.max(1, Math.ceil(rule.perSecond));
+	function rateCheck(key) {
+		const rule = config.rateLimit?.[key];
+		if (!rule) return { ok: true };
+		const capacity = capacityOf(rule);
+		const tNow = now();
+		let b = buckets.get(key);
+		if (!b) {
+			b = {
+				tokens: capacity,
+				updatedMs: tNow
+			};
+			buckets.set(key, b);
+		}
+		const elapsedSec = Math.max(0, (tNow - b.updatedMs) / 1e3);
+		b.tokens = Math.min(capacity, b.tokens + elapsedSec * rule.perSecond);
+		b.updatedMs = tNow;
+		if (b.tokens >= 1) {
+			b.tokens -= 1;
+			return { ok: true };
+		}
+		const needed = 1 - b.tokens;
+		return {
+			ok: false,
+			retryAfterSeconds: Math.max(1, Math.ceil(needed / rule.perSecond))
+		};
+	}
+	/** Give back a token a denied request had already taken from an earlier bucket. */
+	function refund(key) {
+		const rule = config.rateLimit?.[key];
+		const b = buckets.get(key);
+		if (rule && b) b.tokens = Math.min(capacityOf(rule), b.tokens + 1);
+	}
+	return { async acquire(req) {
+		const keys = gateRuleKeys(req);
+		const held = [];
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			for (const key of held) running.set(key, Math.max(0, (running.get(key) ?? 1) - 1));
+		};
+		for (const key of keys) {
+			const cRule = config.concurrency?.[key];
+			if (!cRule) continue;
+			const current = running.get(key) ?? 0;
+			if (current >= cRule.maxConcurrent) {
+				release();
+				return {
+					admitted: false,
+					retryAfterSeconds: concurrencyRetry
+				};
+			}
+			running.set(key, current + 1);
+			held.push(key);
+		}
+		const taken = [];
+		for (const key of keys) {
+			if (!config.rateLimit?.[key]) continue;
+			const rate = rateCheck(key);
+			if (!rate.ok) {
+				for (const t of taken) refund(t);
+				release();
+				return {
+					admitted: false,
+					retryAfterSeconds: rate.retryAfterSeconds
+				};
+			}
+			taken.push(key);
+		}
+		return {
+			admitted: true,
+			release
+		};
+	} };
+}
+//#endregion
 //#region src/core/retry.ts
 /**
 * Realm-safe marker for an explicit retryability decision. `Symbol.for` so a
@@ -882,4 +990,4 @@ function toPublicWorkflow(workflow) {
 	};
 }
 //#endregion
-export { nonRetryableError as C, markRetryable as S, defineStep as _, WORKFLOW_STATUS_SCHEMA as a, explicitRetryability as b, toPublicWorkflow as c, defineDecisionStep as d, functionDecider as f, defineSleepStep as g, defineMapStep as h, STEP_DISPLAY_STATUS_SCHEMA as i, defineDecisionOutcomeStep as l, buildWorkflow as m, PUBLIC_WORKFLOW_STEP_SCHEMA as n, toDisplayStepStatus as o, resolveDecision as p, STEP_DISPLAY_STATUS as r, toPublicStep as s, PUBLIC_WORKFLOW_SCHEMA as t, defineDecisionReviewStep as u, defineSubWorkflowStep as v, retryableError as w, isRetryableError as x, defineWaitStep as y };
+export { nonRetryableError as C, gateRuleKeys as E, markRetryable as S, createInMemoryStepGate as T, defineStep as _, WORKFLOW_STATUS_SCHEMA as a, explicitRetryability as b, toPublicWorkflow as c, defineDecisionStep as d, functionDecider as f, defineSleepStep as g, defineMapStep as h, STEP_DISPLAY_STATUS_SCHEMA as i, defineDecisionOutcomeStep as l, buildWorkflow as m, PUBLIC_WORKFLOW_STEP_SCHEMA as n, toDisplayStepStatus as o, resolveDecision as p, STEP_DISPLAY_STATUS as r, toPublicStep as s, PUBLIC_WORKFLOW_SCHEMA as t, defineDecisionReviewStep as u, defineSubWorkflowStep as v, retryableError as w, isRetryableError as x, defineWaitStep as y };

package/dist/{dispatcher-BQErUGy_.d.ts → dispatcher-ltwBJjKc.d.ts}

@@ -1,4 +1,13 @@
 import { St as Result, lt as WorkflowId, nt as StepId, xt as FlowErrorShape } from "./index-DZUO24Rz.js";
+//#region src/core/logger.d.ts
+type LogAttributes = Record<string, unknown>;
+interface Logger {
+  info(message: string, attributes?: LogAttributes): void;
+  warn(message: string, attributes?: LogAttributes): void;
+  error(message: string, error?: Error, attributes?: LogAttributes): void;
+}
+declare const noopLogger: Logger;
+//#endregion
 //#region src/core/dispatcher.d.ts
 /**
  * What a step job is for. A queue carries two kinds of work for a step, and
@@ -61,4 +70,4 @@ interface Dispatcher {
   enqueueStepIn?(handle: unknown, payload: DispatchStepPayload, options?: EnqueueOptions): Promise<Result<void, FlowErrorShape>>;
 }
 //#endregion
-export { EnqueueOptions as i, DispatchStepPayload as n, Dispatcher as r, DispatchKind as t };
+export { LogAttributes as a, EnqueueOptions as i, DispatchStepPayload as n, Logger as o, Dispatcher as r, noopLogger as s, DispatchKind as t };

package/dist/drizzle/index.d.ts

@@ -170,107 +170,4 @@ export declare const flowStepLeaseColumns: {
   /** A lease past this instant is reaped on the next acquire. */
   expiresAt: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>;
 };
-/**
- * `model_provider` — one row per provider an administrator manages
- * (`createModelProviders` in `octaflow/ai`, over `createPgModelProviderStore`).
- * `id` is the primary key; nothing else is declared beyond the columns. A host
- * whose customers bring their own keys adds its scope column beside these and
- * makes the key composite.
- *
- * ```ts
- * import { pgTable } from 'drizzle-orm/pg-core';
- * import { modelProviderColumns } from 'octaflow/drizzle';
- *
- * export const modelProvider = pgTable('model_provider', modelProviderColumns);
- * ```
- */
-export declare const modelProviderColumns: {
-  id: import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"id", [string, ...string[]]>>>;
-  kind: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"kind", [string, ...string[]]>>;
-  label: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"label", [string, ...string[]]>>;
-  baseUrl: import("drizzle-orm/pg-core").PgTextBuilderInitial<"base_url", [string, ...string[]]>;
-  region: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"region", [string, ...string[]]>>;
-  apiKey: import("drizzle-orm/pg-core").PgTextBuilderInitial<"api_key", [string, ...string[]]>;
-  keyHint: import("drizzle-orm/pg-core").PgTextBuilderInitial<"key_hint", [string, ...string[]]>;
-  headers: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"headers">, Record<string, string>>>>;
-  tags: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"tags">, string[]>>>;
-  models: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"models">, unknown[]>>>;
-  defaultModel: import("drizzle-orm/pg-core").PgTextBuilderInitial<"default_model", [string, ...string[]]>;
-  enabled: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgBooleanBuilderInitial<"enabled">>>;
-  updatedAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>>;
-  updatedBy: import("drizzle-orm/pg-core").PgTextBuilderInitial<"updated_by", [string, ...string[]]>;
-};
-/**
- * `model_runner` — one row per runner an administrator registered
- * (`createModelRunnerHub` in `octaflow/ai/runner`, over
- * `createPgModelRunnerStore`). `id` is the primary key; the DDL adds a unique
- * index on `token_hash`, which the host mirrors. No scope column, as for the
- * providers.
- *
- * ```ts
- * import { pgTable, uniqueIndex } from 'drizzle-orm/pg-core';
- * import { modelRunnerColumns } from 'octaflow/drizzle';
- *
- * export const modelRunner = pgTable('model_runner', modelRunnerColumns, (t) => [uniqueIndex('model_runner_token_hash_idx').on(t.tokenHash)]);
- * ```
- */
-export declare const modelRunnerColumns: {
-  id: import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"id", [string, ...string[]]>>>;
-  label: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"label", [string, ...string[]]>>;
-  tags: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"tags">, string[]>>>;
-  concurrency: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"concurrency">>>;
-  tokenHash: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"token_hash", [string, ...string[]]>>;
-  lastSeenAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
-  createdAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>>;
-  createdBy: import("drizzle-orm/pg-core").PgTextBuilderInitial<"created_by", [string, ...string[]]>;
-};
-/**
- * `model_runner_request` — the mailbox: one row per model call in flight,
- * deleted as soon as the caller read the answer. The DDL's index is the
- * claim's, `(created_at) WHERE status = 'pending'`, which the host mirrors.
- *
- * ```ts
- * import { index, pgTable } from 'drizzle-orm/pg-core';
- * import { modelRunnerRequestColumns } from 'octaflow/drizzle';
- *
- * export const modelRunnerRequest = pgTable('model_runner_request', modelRunnerRequestColumns, (t) => [
- *   index('model_runner_request_pending_idx').on(t.createdAt).where(sql`${t.status} = 'pending'`),
- * ]);
- * ```
- */
-export declare const modelRunnerRequestColumns: {
-  id: import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"id", [string, ...string[]]>>>;
-  providerId: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"provider_id", [string, ...string[]]>>;
-  tags: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"tags">, string[]>>>;
-  model: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"model", [string, ...string[]]>>;
-  kind: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"kind", [string, ...string[]]>>;
-  payload: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"payload">>;
-  status: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"status", [string, ...string[]]>>>;
-  claimedBy: import("drizzle-orm/pg-core").PgTextBuilderInitial<"claimed_by", [string, ...string[]]>;
-  claimedAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
-  leaseUntil: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
-  attempts: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"attempts">>>;
-  result: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"result">;
-  error: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"error">;
-  createdAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>>;
-  finishedAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
-};
-/**
- * `model_runner_chunk` — the parts of a `stream` request as the runner posted
- * them, a batch per row, read and deleted with the request. The key is
- * composite, `(request_id, seq)`, and the host declares it.
- *
- * ```ts
- * import { pgTable, primaryKey } from 'drizzle-orm/pg-core';
- * import { modelRunnerChunkColumns } from 'octaflow/drizzle';
- *
- * export const modelRunnerChunk = pgTable('model_runner_chunk', modelRunnerChunkColumns, (t) => [primaryKey({ columns: [t.requestId, t.seq] })]);
- * ```
- */
-export declare const modelRunnerChunkColumns: {
-  requestId: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"request_id", [string, ...string[]]>>;
-  seq: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"seq">>;
-  parts: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"parts">>;
-  createdAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>>;
-};
 //#endregion

package/dist/drizzle/index.js

@@ -1,4 +1,4 @@
-import { bigint, bigserial, boolean, doublePrecision, integer, jsonb, text, timestamp } from "drizzle-orm/pg-core";
+import { bigint, bigserial, doublePrecision, integer, jsonb, text, timestamp } from "drizzle-orm/pg-core";
 //#region src/drizzle/index.ts
 /**
 * `octaflow/drizzle` — the engine's tables as Drizzle column sets.
@@ -195,108 +195,5 @@ const flowStepLeaseColumns = {
 	/** A lease past this instant is reaped on the next acquire. */
 	expiresAt: timestamptz("expires_at").notNull()
 };
-/**
-* `model_provider` — one row per provider an administrator manages
-* (`createModelProviders` in `octaflow/ai`, over `createPgModelProviderStore`).
-* `id` is the primary key; nothing else is declared beyond the columns. A host
-* whose customers bring their own keys adds its scope column beside these and
-* makes the key composite.
-*
-* ```ts
-* import { pgTable } from 'drizzle-orm/pg-core';
-* import { modelProviderColumns } from 'octaflow/drizzle';
-*
-* export const modelProvider = pgTable('model_provider', modelProviderColumns);
-* ```
-*/
-const modelProviderColumns = {
-	id: text("id").primaryKey(),
-	kind: text("kind").notNull(),
-	label: text("label").notNull(),
-	baseUrl: text("base_url"),
-	region: text("region").notNull(),
-	apiKey: text("api_key"),
-	keyHint: text("key_hint"),
-	headers: jsonb("headers").$type().notNull().default({}),
-	tags: jsonb("tags").$type().notNull().default([]),
-	models: jsonb("models").$type().notNull().default([]),
-	defaultModel: text("default_model"),
-	enabled: boolean("enabled").notNull().default(true),
-	updatedAt: timestamptz("updated_at").notNull().defaultNow(),
-	updatedBy: text("updated_by")
-};
-/**
-* `model_runner` — one row per runner an administrator registered
-* (`createModelRunnerHub` in `octaflow/ai/runner`, over
-* `createPgModelRunnerStore`). `id` is the primary key; the DDL adds a unique
-* index on `token_hash`, which the host mirrors. No scope column, as for the
-* providers.
-*
-* ```ts
-* import { pgTable, uniqueIndex } from 'drizzle-orm/pg-core';
-* import { modelRunnerColumns } from 'octaflow/drizzle';
-*
-* export const modelRunner = pgTable('model_runner', modelRunnerColumns, (t) => [uniqueIndex('model_runner_token_hash_idx').on(t.tokenHash)]);
-* ```
-*/
-const modelRunnerColumns = {
-	id: text("id").primaryKey(),
-	label: text("label").notNull(),
-	tags: jsonb("tags").$type().notNull().default([]),
-	concurrency: integer("concurrency").notNull().default(1),
-	tokenHash: text("token_hash").notNull(),
-	lastSeenAt: timestamptz("last_seen_at"),
-	createdAt: timestamptz("created_at").notNull().defaultNow(),
-	createdBy: text("created_by")
-};
-/**
-* `model_runner_request` — the mailbox: one row per model call in flight,
-* deleted as soon as the caller read the answer. The DDL's index is the
-* claim's, `(created_at) WHERE status = 'pending'`, which the host mirrors.
-*
-* ```ts
-* import { index, pgTable } from 'drizzle-orm/pg-core';
-* import { modelRunnerRequestColumns } from 'octaflow/drizzle';
-*
-* export const modelRunnerRequest = pgTable('model_runner_request', modelRunnerRequestColumns, (t) => [
-*   index('model_runner_request_pending_idx').on(t.createdAt).where(sql`${t.status} = 'pending'`),
-* ]);
-* ```
-*/
-const modelRunnerRequestColumns = {
-	id: text("id").primaryKey(),
-	providerId: text("provider_id").notNull(),
-	tags: jsonb("tags").$type().notNull().default([]),
-	model: text("model").notNull(),
-	kind: text("kind").notNull(),
-	payload: jsonb("payload").notNull(),
-	status: text("status").notNull().default("pending"),
-	claimedBy: text("claimed_by"),
-	claimedAt: timestamptz("claimed_at"),
-	leaseUntil: timestamptz("lease_until"),
-	attempts: integer("attempts").notNull().default(0),
-	result: jsonb("result"),
-	error: jsonb("error"),
-	createdAt: timestamptz("created_at").notNull().defaultNow(),
-	finishedAt: timestamptz("finished_at")
-};
-/**
-* `model_runner_chunk` — the parts of a `stream` request as the runner posted
-* them, a batch per row, read and deleted with the request. The key is
-* composite, `(request_id, seq)`, and the host declares it.
-*
-* ```ts
-* import { pgTable, primaryKey } from 'drizzle-orm/pg-core';
-* import { modelRunnerChunkColumns } from 'octaflow/drizzle';
-*
-* export const modelRunnerChunk = pgTable('model_runner_chunk', modelRunnerChunkColumns, (t) => [primaryKey({ columns: [t.requestId, t.seq] })]);
-* ```
-*/
-const modelRunnerChunkColumns = {
-	requestId: text("request_id").notNull(),
-	seq: integer("seq").notNull(),
-	parts: jsonb("parts").notNull(),
-	createdAt: timestamptz("created_at").notNull().defaultNow()
-};
 //#endregion
-export { flowRateBucketColumns, flowStepEventColumns, flowStepLeaseColumns, flowWorkflowColumns, flowWorkflowStepColumns, modelProviderColumns, modelRunnerChunkColumns, modelRunnerColumns, modelRunnerRequestColumns };
+export { flowRateBucketColumns, flowStepEventColumns, flowStepLeaseColumns, flowWorkflowColumns, flowWorkflowStepColumns };

package/dist/index.d.ts

@@ -1,8 +1,60 @@
 import { $ as StepHandler, A as StepOutput, B as defineWaitStep, C as defineDecisionOutcomeStep, Ct as err, D as resolveDecision, E as functionDecider, F as buildWorkflow, G as StepCompensateHandler, H as InvalidWorkflowDefinitionError, I as defineMapStep, J as StepDefinition, K as StepCompensationContext, L as defineSleepStep, M as TypedStepContext, N as TypedWorkflow, O as DefineStepConfig, P as WorkflowOutput, Q as StepFailurePolicy, R as defineStep, S as DecisionStep, St as Result, T as defineDecisionStep, U as RetryPolicy, V as FlowError, W as StartOptions, X as StepError, Y as StepDelay, Z as StepExecutionContext, _ as DecisionOutput, _t as PlannedSkip, a as STEP_DISPLAY_STATUS, at as StepStatus, b as DecisionResponse, bt as isTerminalStepStatus, c as WORKFLOW_STATUS_SCHEMA, ct as WorkflowDefinition, d as toPublicWorkflow, dt as WorkflowNotRetryableError, et as StepHandlerNotFoundError, f as Decider, ft as WorkflowRecord, g as DecisionOutcome, gt as JoinRule, h as DecisionChoices, ht as WorkflowWithSteps, i as PublicWorkflowStep, it as StepRegistration, j as TypedStep, k as StepDeps, l as toDisplayStepStatus, lt as WorkflowId, m as DecisionAnswers, mt as WorkflowStepRunningError, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as StepId, o as STEP_DISPLAY_STATUS_SCHEMA, ot as WaitTimeoutPolicy, p as DecisionAnswer, pt as WorkflowStatus, q as StepConditionHandler, r as PublicWorkflow, rt as StepRecord, s as StepDisplayStatus, st as WorkflowCreatedResult, t as PUBLIC_WORKFLOW_SCHEMA, tt as StepHandlerRegistry, u as toPublicStep, ut as WorkflowNotFoundError, v as DecisionQuestions, vt as ReadinessPlan, w as defineDecisionReviewStep, wt as ok, x as DecisionReview, xt as FlowErrorShape, y as DecisionRequest, yt as computeReadiness, z as defineSubWorkflowStep } from "./index-DZUO24Rz.js";
-import { n as Logger, r as noopLogger, t as LogAttributes } from "./logger-BCus3AOa.js";
+import { a as LogAttributes, i as EnqueueOptions, n as DispatchStepPayload, o as Logger, r as Dispatcher, s as noopLogger, t as DispatchKind } from "./dispatcher-ltwBJjKc.js";
 import { A as FinishWorkflowParams, C as gateRuleKeys, D as CreateWorkflowStep, E as CreateWorkflowParams, F as WorkflowTreeFilter, M as ReopenWorkflowParams, N as TransactionalScope, O as CreatedWorkflow, P as WorkflowStore, S as createInMemoryStepGate, T as CompleteStepParams, _ as InMemoryStepGateConfig, a as FlowSpan, b as StepGateDecision, c as RecordingObserver, d as createMeterObserver, f as createRecordingObserver, g as ConcurrencyRule, h as noopTracer, i as FlowObserver, j as ListWorkflowsFilters, k as FailStepParams, l as RecordingTracer, m as noopObserver, n as FlowEventType, o as FlowTracer, p as createRecordingTracer, r as FlowMeter, s as RecordedSpan, t as FlowEvent, u as combineObservers, v as RateRule, w as AddChildStep, x as StepGateRequest, y as StepGate } from "./observability-BLUEjdto.js";
-import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-BQErUGy_.js";
-import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-DHomzpiq.js";
+//#region src/core/hooks.d.ts
+export interface BeforeStartArgs {
+  definition: WorkflowDefinition;
+  input: Record<string, unknown>;
+  options?: StartOptions;
+}
+export interface BeforeStartResult {
+  /** Extra metadata persisted on the workflow row (merged over `options.metadata`). */
+  metadata?: Record<string, unknown>;
+}
+export interface BuildStepContextArgs {
+  workflowId: WorkflowId;
+  stepId: StepId;
+  stepKey: string;
+  partitionKey: string;
+  workflow: WorkflowRecord;
+  step: StepRecord;
+}
+export interface AfterStepArgs<TContext> {
+  workflowId: WorkflowId;
+  stepId: StepId;
+  partitionKey: string;
+  workflow: WorkflowRecord;
+  step: StepRecord;
+  output: Record<string, unknown>;
+  /** The same context object that was handed to the step handler. */
+  context: TContext;
+}
+export interface WorkflowCompletedArgs {
+  workflowId: WorkflowId;
+  partitionKey: string;
+  workflow: WorkflowRecord;
+}
+export interface WorkflowHooks<TContext = unknown> {
+  /**
+   * Runs before a workflow is created. Return an error to reject the start
+   * (e.g. quota exceeded) — the engine passes the error through untouched.
+   */
+  onBeforeStart?(args: BeforeStartArgs): Promise<Result<BeforeStartResult, FlowErrorShape>>;
+  /**
+   * Produces the per-step `context` handed to the handler (and later to
+   * `onAfterStep`). This is where the AI add-on resolves and instruments a model.
+   * If omitted, handlers receive `undefined` as their context.
+   */
+  buildStepContext?(args: BuildStepContextArgs): TContext | Promise<TContext>;
+  /**
+   * Runs after a step handler succeeds, before the step is marked completed.
+   * The AI add-on reads token usage off `context` here and persists cost.
+   */
+  onAfterStep?(args: AfterStepArgs<TContext>): Promise<void>;
+  /** Runs once when a workflow reaches `completed` (e.g. daily usage rollup). */
+  onWorkflowCompleted?(args: WorkflowCompletedArgs): Promise<void>;
+}
+//#endregion
 //#region src/core/registry.d.ts
 /**
  * Creates an in-memory step handler registry.
@@ -168,4 +220,4 @@ export declare function createInMemoryWorkflowStore(partitionKey?: string): Work
   };
 };
 //#endregion
-export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, Decider, DecisionAnswer, DecisionAnswers, DecisionChoices, DecisionOutcome, DecisionOutput, DecisionQuestions, DecisionRequest, DecisionResponse, DecisionReview, DecisionStep, DefineStepConfig, DispatchKind, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowMeter, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, JoinRule, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PlannedSkip, PublicWorkflow, PublicWorkflowStep, RateRule, ReadinessPlan, RecordedSpan, RecordingObserver, RecordingTracer, ReopenWorkflowParams, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDelay, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepFailurePolicy, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowNotRetryableError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStepRunningError, WorkflowStore, WorkflowTreeFilter, WorkflowWithSteps, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createMeterObserver, createRecordingObserver, createRecordingTracer, defineDecisionOutcomeStep, defineDecisionReviewStep, defineDecisionStep, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, functionDecider, gateRuleKeys, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, resolveDecision, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { AddChildStep, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, Decider, DecisionAnswer, DecisionAnswers, DecisionChoices, DecisionOutcome, DecisionOutput, DecisionQuestions, DecisionRequest, DecisionResponse, DecisionReview, DecisionStep, DefineStepConfig, DispatchKind, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowMeter, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, JoinRule, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PlannedSkip, PublicWorkflow, PublicWorkflowStep, RateRule, ReadinessPlan, RecordedSpan, RecordingObserver, RecordingTracer, ReopenWorkflowParams, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDelay, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepFailurePolicy, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCreatedResult, WorkflowDefinition, WorkflowId, WorkflowNotFoundError, WorkflowNotRetryableError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStepRunningError, WorkflowStore, WorkflowTreeFilter, WorkflowWithSteps, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createMeterObserver, createRecordingObserver, createRecordingTracer, defineDecisionOutcomeStep, defineDecisionReviewStep, defineDecisionStep, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, functionDecider, gateRuleKeys, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, resolveDecision, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

package/dist/index.js

@@ -1,6 +1,21 @@
-import { n as err, r as ok, t as noopLogger } from "./logger-epkdcXDA.js";
-import { n as gateRuleKeys, t as createInMemoryStepGate } from "./gate-BRq-t3K_.js";
-import { C as nonRetryableError, S as markRetryable, _ as defineStep, a as WORKFLOW_STATUS_SCHEMA, b as explicitRetryability, c as toPublicWorkflow, d as defineDecisionStep, f as functionDecider, g as defineSleepStep, h as defineMapStep, i as STEP_DISPLAY_STATUS_SCHEMA, l as defineDecisionOutcomeStep, m as buildWorkflow, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as toDisplayStepStatus, p as resolveDecision, r as STEP_DISPLAY_STATUS, s as toPublicStep, t as PUBLIC_WORKFLOW_SCHEMA, u as defineDecisionReviewStep, v as defineSubWorkflowStep, w as retryableError, x as isRetryableError, y as defineWaitStep } from "./core-COMWflJl.js";
+import { C as nonRetryableError, E as gateRuleKeys, S as markRetryable, T as createInMemoryStepGate, _ as defineStep, a as WORKFLOW_STATUS_SCHEMA, b as explicitRetryability, c as toPublicWorkflow, d as defineDecisionStep, f as functionDecider, g as defineSleepStep, h as defineMapStep, i as STEP_DISPLAY_STATUS_SCHEMA, l as defineDecisionOutcomeStep, m as buildWorkflow, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as toDisplayStepStatus, p as resolveDecision, r as STEP_DISPLAY_STATUS, s as toPublicStep, t as PUBLIC_WORKFLOW_SCHEMA, u as defineDecisionReviewStep, v as defineSubWorkflowStep, w as retryableError, x as isRetryableError, y as defineWaitStep } from "./core-YqnPwR-v.js";
+//#region src/core/result.ts
+const ok = (value) => ({
+	ok: true,
+	value
+});
+const err = (error) => ({
+	ok: false,
+	error
+});
+//#endregion
+//#region src/core/logger.ts
+const noopLogger = {
+	info() {},
+	warn() {},
+	error() {}
+};
+//#endregion
 //#region src/core/readiness.ts
 /** Statuses a step can no longer move out of on its own. */
 const TERMINAL_STATUSES = /* @__PURE__ */ new Set([

package/dist/pg-boss/index.d.ts

@@ -1,6 +1,5 @@
 import "../index-DZUO24Rz.js";
-import { n as Logger } from "../logger-BCus3AOa.js";
-import { r as Dispatcher } from "../dispatcher-BQErUGy_.js";
+import { o as Logger, r as Dispatcher } from "../dispatcher-ltwBJjKc.js";
 import { z } from "zod";
 import { PgBoss, Schedule } from "pg-boss";
 //#region src/pg-boss/payload.d.ts