octaflow 0.30.0 → 0.32.0

package/README.md

@@ -215,7 +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, 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`) |
 | 🧱 | **Pluggable everything** — `WorkflowStore`, `Dispatcher`, `StepGate`, `FlowObserver`, hooks |
 
 ---
@@ -254,6 +254,12 @@ pnpm add ai @ai-sdk/provider
 a `schema`, and is meant to be pasted into your own migration system; `applySchema(pool, ddl)`
 is the dev and test shortcut.
 
+The stores, the gate and the event sink reach the database only through the `SqlExecutor` seam
+(`query` plus a same-connection `transaction`). Three executors ship with it: `poolExecutor(pool)`
+for `pg`, `postgresJsExecutor(sql)` for a postgres.js host (`transaction` is `sql.begin`), and
+`pgliteExecutor(pglite)` for PGlite in tests. Wrap any of them to set row-level-security GUCs
+first.
+
 #### The Drizzle columns
 
 The rule for every table-owning capability on the platform: `./postgres` ships the store over

package/dist/ai/index.d.ts

@@ -1,9 +1,10 @@
-import { A as TypedStep, H as RetryPolicy, M as TypedWorkflow, bt as Result, f as Decider, j as TypedStepContext, yt as FlowErrorShape } from "../index-Du05Lnwr.js";
+import { M as TypedStepContext, N as TypedWorkflow, O as DefineStepConfig, St as Result, U as RetryPolicy, f as Decider, gt as JoinRule, j as TypedStep, xt as FlowErrorShape } from "../index-D0XhoTkE.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-mWaAKHqn.js";
+import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-C46TPBEg.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-l2Jmpuhr.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-_rio4ykx.js";
 import { z } from "zod";
+import { ToolSet } from "ai";
 import { EmbeddingModelV4, LanguageModelV4, LanguageModelV4Usage, SharedV4ProviderMetadata } from "@ai-sdk/provider";
 //#region src/ai/instrumented-model.d.ts
 export interface AccumulatedUsage {
@@ -12,6 +13,8 @@ export interface AccumulatedUsage {
   cacheReadTokens: number;
   cacheWriteTokens: number;
   modelId: string;
+  /** The provider the model belongs to (`model.provider`), when the call reported it. */
+  provider?: string;
 }
 export interface UsageAccumulator {
   /** Record usage from a single LLM call (additive — supports multiple calls per step). */
@@ -123,35 +126,18 @@ export interface AiContext<THost = unknown> {
 //#region src/ai/define-ai-step.d.ts
 /** An AI workflow step — a flow-core `TypedStep` whose context is an `AiContext`. */
 export type AiTypedStep<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}> = TypedStep<TInput, TOutput, TDeps, AiContext<THost>>;
-interface DefineAiStepConfig<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>>> {
-  type: string;
-  workflowInputSchema: z.ZodType<TInput>;
-  outputSchema: z.ZodType<TOutput>;
-  dependencies?: TDeps;
-  handler: (ctx: TypedStepContext<TInput, TDeps, AiContext<THost>>) => Promise<TOutput>;
-  /** Optional retry policy (max attempts, backoff) — e.g. for provider 429s. */
-  retry?: RetryPolicy;
-  /** Optional per-step wall-clock timeout in ms. */
-  timeoutMs?: number;
-  /** Optional durable start delay in ms — held in the queue once the step is ready. */
-  delayMs?: number;
-  /**
-   * What a terminal failure does — see `defineStep`'s `onFailure`. `{ output }`
-   * completes the step with a stand-in and the DAG carries on; the model's
-   * refusal or outage then costs one section of the result, not the run.
-   */
-  onFailure?: 'fail' | {
-    output: TOutput;
-  };
-  /** Resources the step draws on (the model, a vendor), for the admission gate — see `defineStep`. */
-  resources?: readonly string[];
-}
+/**
+ * `defineStep`'s config with the handler context fixed to `AiContext<THost>` —
+ * every option a step has (`when`, `join`, heartbeats, `onFailure`, …), so an
+ * AI step branches and converges like any other.
+ */
+export type DefineAiStepConfig<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>>, TJoin extends JoinRule = 'all'> = DefineStepConfig<TInput, TOutput, TDeps, AiContext<THost>, TJoin>;
 /**
  * Define a type-safe AI workflow step. Identical to flow-core's `defineStep`
  * except the handler context is fixed to `AiContext<THost>`, so handlers get a
  * ready-to-use `ctx.context.model` (instrumented) and `ctx.context.host`.
  */
-export declare function defineAiStep<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: DefineAiStepConfig<TInput, TOutput, THost, TDeps>): AiTypedStep<TInput, TOutput, THost, TDeps>;
+export declare function defineAiStep<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}, TJoin extends JoinRule = 'all'>(config: DefineAiStepConfig<TInput, TOutput, THost, TDeps, TJoin>): AiTypedStep<TInput, TOutput, THost, TDeps>;
 /** Build a typed AI workflow from `defineAiStep` definitions. */
 export declare function buildAiWorkflow<TInput extends Record<string, unknown>, THost = unknown, TSteps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: {
   type: string;
@@ -184,6 +170,114 @@ export interface ModelDeciderOptions {
  */
 export declare function createModelDecider<THost = unknown>(options?: ModelDeciderOptions): Decider<AiContext<THost>>;
 //#endregion
+//#region src/ai/agent.d.ts
+/** What one agent run did — persisted with the answer, never parsed. */
+export interface AgentTrace {
+  /** Model calls the loop made. */
+  rounds: number;
+  /** Tool names in the order they were called, the exit last. */
+  toolCalls: string[];
+  /** Input + output tokens across all rounds. */
+  tokens: number;
+}
+/** One way out of an agent: the model ends the run by calling it, and its arguments are the value. */
+export interface AgentExit<T = unknown> {
+  description: string;
+  schema: z.ZodType<T>;
+}
+export type AgentExits = Record<string, AgentExit<any>>;
+/** The exit an agent took, typed by its name. */
+export type AgentExitTaken<TExits extends AgentExits> = { [K in keyof TExits & string]: {
+  exit: K;
+  value: TExits[K] extends AgentExit<infer T> ? T : never;
+}; }[keyof TExits & string];
+interface AgentLimits {
+  /** The model — in a step, `ctx.context.model`, so usage lands on the step. */
+  model: LanguageModelV4;
+  system: string;
+  prompt: string;
+  /** The tools the agent works with. Their names must not collide with an exit's. */
+  tools?: ToolSet;
+  /** Most model calls before the run gives up. Default 8. */
+  maxRounds?: number;
+  /** Most input + output tokens before the run gives up. Default: no cap. */
+  maxTokens?: number;
+  /**
+   * Most output tokens per model call, passed to the AI SDK. Default: the
+   * provider's — which on a local server can be small enough to cut a
+   * thinking model off before it calls anything.
+   */
+  maxOutputTokens?: number;
+  /** Called after every round; `false` stops the run — pass the step's `heartbeat`. */
+  heartbeat?: () => Promise<boolean>;
+  abortSignal?: AbortSignal;
+  /** Passed to the AI SDK. Default 0 — the step's retry policy owns retries. */
+  maxRetries?: number;
+}
+export interface RunAgentToExitOptions<TExits extends AgentExits> extends AgentLimits {
+  exits: TExits;
+}
+export interface RunAgentOptions<TOutput> extends AgentLimits {
+  /** The answer's shape — the arguments of the one exit, `answer`. */
+  output: z.ZodType<TOutput>;
+}
+export interface AgentRun<TOutput> {
+  output: TOutput;
+  trace: AgentTrace;
+}
+/**
+ * Run one agent until it takes one of `exits`, or fails. Stopping on a limit
+ * before an exit is not retryable — the same budget would stop the same way —
+ * so the step fails, or takes its `onFailure` stand-in.
+ */
+export declare function runAgentToExit<TExits extends AgentExits>(options: RunAgentToExitOptions<TExits>): Promise<AgentExitTaken<TExits> & {
+  trace: AgentTrace;
+}>;
+/** Run one agent to a typed answer: `runAgentToExit` with the single exit `answer`. */
+export declare function runAgent<TOutput>(options: RunAgentOptions<TOutput>): Promise<AgentRun<TOutput>>;
+/** The trace as a schema — for a step output that carries one. */
+export declare const AGENT_TRACE_SCHEMA: z.ZodObject<{
+  rounds: z.ZodNumber;
+  toolCalls: z.ZodArray<z.ZodString>;
+  tokens: z.ZodNumber;
+}, z.core.$strip>;
+interface DefineAgentStepConfig<TInput extends Record<string, unknown>, TAnswer extends Record<string, unknown>, THost, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>>> {
+  type: string;
+  workflowInputSchema: z.ZodType<TInput>;
+  /** The answer's shape — the step outputs `{ answer, trace }`. */
+  answerSchema: z.ZodType<TAnswer>;
+  dependencies?: TDeps;
+  system: string;
+  /** The task, built from the workflow input and the dependencies' outputs. */
+  prompt: (ctx: TypedStepContext<TInput, TDeps, AiContext<THost>>) => string;
+  tools?: (ctx: TypedStepContext<TInput, TDeps, AiContext<THost>>) => ToolSet;
+  maxRounds?: number;
+  maxTokens?: number;
+  maxOutputTokens?: number;
+  retry?: RetryPolicy;
+  timeoutMs?: number;
+  /** See `defineStep`'s `heartbeatTimeoutMs` — every round beats. */
+  heartbeatTimeoutMs?: number;
+  /** See `defineStep`'s `onFailure`. */
+  onFailure?: 'fail' | {
+    output: {
+      answer: TAnswer;
+      trace: AgentTrace;
+    };
+  };
+  resources?: readonly string[];
+  when?: (ctx: TypedStepContext<TInput, TDeps, AiContext<THost>>) => boolean | Promise<boolean>;
+}
+/**
+ * A step that runs one agent on the step's instrumented model. Its output is
+ * `{ answer, trace }`: dependents read `ctx.deps.<key>.answer`, and the trace
+ * stays on the run for whoever reads it back.
+ */
+export declare function defineAgentStep<TInput extends Record<string, unknown>, TAnswer extends Record<string, unknown>, THost = unknown, TDeps extends Record<string, TypedStep<any, any, any, AiContext<THost>>> = {}>(config: DefineAgentStepConfig<TInput, TAnswer, THost, TDeps>): TypedStep<TInput, {
+  answer: TAnswer;
+  trace: AgentTrace;
+}, TDeps, AiContext<THost>>;
+//#endregion
 //#region src/ai/hooks.d.ts
 export interface AiModelResolver<THost = unknown> {
   /** Resolve the base (uninstrumented) model for a step. */
@@ -222,6 +316,32 @@ export interface AiUsageRecorder {
     date: string;
   }): Promise<void>;
 }
+/**
+ * What one step's model usage looks like to a metering sink: the booking
+ * `@octabits-io/metering`'s `record` takes, by shape — tokens as the vendor
+ * reported them, the provider as the service, and the attribution octaflow
+ * knows (the run, the workflow type as the feature, the step). A sink that
+ * runs inside `withUsage` adds the paying account from the ambient context.
+ */
+export interface AiModelUsageEvent {
+  kind: 'model';
+  /** The provider (`model.provider`), or `'model'` when the call did not report one. */
+  service: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  context: {
+    runId: string;
+    feature: string;
+    correlationId?: string;
+  };
+}
+/** Where a step's model usage is booked — `@octabits-io/metering`'s `Metering` satisfies it. Optional: without one nothing is booked. */
+export interface AiUsageSink {
+  record(event: AiModelUsageEvent): unknown;
+}
 export interface AiQuotaPolicy {
   /** Return an error (e.g. `ai_quota_exceeded`) to reject a workflow start. */
   checkQuota(): Promise<Result<void, FlowErrorShape>>;
@@ -231,6 +351,12 @@ export interface CreateAiWorkflowHooksDeps<THost = unknown> {
   usageRecorder: AiUsageRecorder;
   /** Optional quota guard. BYOK exemption etc. is the policy's concern. */
   quotaPolicy?: AiQuotaPolicy;
+  /**
+   * Optional metering sink: every step's model usage is booked here as well,
+   * unpriced, attributed to the run and the workflow type — so a model call
+   * and the paid API calls around it land in one table with one context.
+   */
+  usage?: AiUsageSink;
   /** Defaults to `createCostEstimator()` (the built-in pricing table). */
   costEstimator?: CostEstimator;
   /** Clock injection for tests. */

package/dist/ai/index.js

@@ -1,9 +1,9 @@
 import { n as err, r as ok, t as noopLogger } from "../logger-epkdcXDA.js";
-import { _ as defineStep, m as buildWorkflow } from "../core-DBqxBk3R.js";
+import { C as nonRetryableError, _ as defineStep, m as buildWorkflow } from "../core-DBqxBk3R.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 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 { z } from "zod";
-import { Output, generateText, wrapEmbeddingModel, wrapLanguageModel } from "ai";
+import { Output, generateText, stepCountIs, tool, wrapEmbeddingModel, wrapLanguageModel } from "ai";
 //#region src/ai/instrumented-model.ts
 function createUsageAccumulator() {
 	const total = {
@@ -21,6 +21,7 @@ function createUsageAccumulator() {
 			total.cacheReadTokens += usage.cacheReadTokens;
 			total.cacheWriteTokens += usage.cacheWriteTokens;
 			if (usage.modelId) total.modelId = usage.modelId;
+			if (usage.provider) total.provider = usage.provider;
 			hasAny = true;
 		},
 		get() {
@@ -48,7 +49,8 @@ function createInstrumentedModel(model, accumulator) {
 					outputTokens: usage.outputTokens?.total ?? 0,
 					cacheReadTokens: usage.inputTokens?.cacheRead ?? 0,
 					cacheWriteTokens: usage.inputTokens?.cacheWrite ?? 0,
-					modelId: model.modelId
+					modelId: model.modelId,
+					provider: model.provider
 				});
 				return result;
 			},
@@ -63,7 +65,8 @@ function createInstrumentedModel(model, accumulator) {
 							outputTokens: u.outputTokens?.total ?? 0,
 							cacheReadTokens: u.inputTokens?.cacheRead ?? 0,
 							cacheWriteTokens: u.inputTokens?.cacheWrite ?? 0,
-							modelId: model.modelId
+							modelId: model.modelId,
+							provider: model.provider
 						});
 					}
 				} }));
@@ -409,6 +412,141 @@ function createModelDecider(options = {}) {
 	};
 }
 //#endregion
+//#region src/ai/agent.ts
+const DEFAULT_MAX_ROUNDS = 8;
+function tokensOf(steps) {
+	return steps.reduce((sum, s) => sum + (s.usage.inputTokens ?? 0) + (s.usage.outputTokens ?? 0), 0);
+}
+/** The first exit called with valid arguments in a round — an invalid one is answered with its error and the loop goes on. */
+function exitIn(step, exits) {
+	return step?.toolCalls.find((c) => !c.invalid && Object.hasOwn(exits, c.toolName));
+}
+/**
+* Run one agent until it takes one of `exits`, or fails. Stopping on a limit
+* before an exit is not retryable — the same budget would stop the same way —
+* so the step fails, or takes its `onFailure` stand-in.
+*/
+async function runAgentToExit(options) {
+	const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
+	const { maxTokens, exits } = options;
+	for (const name of Object.keys(exits)) if (options.tools && Object.hasOwn(options.tools, name)) throw new Error(`agent tool "${name}" collides with an exit`);
+	const exitTools = Object.fromEntries(Object.entries(exits).map(([name, e]) => [name, tool({
+		description: e.description,
+		inputSchema: e.schema,
+		execute: async () => ({ accepted: true })
+	})]));
+	const stopWhen = [({ steps }) => exitIn(steps.at(-1), exits) !== void 0];
+	if (maxTokens !== void 0) stopWhen.push(({ steps }) => tokensOf(steps) >= maxTokens);
+	const abort = new AbortController();
+	const signal = options.abortSignal ? AbortSignal.any([options.abortSignal, abort.signal]) : abort.signal;
+	const exitList = Object.keys(exits).join(", ");
+	const reminder = (finish) => finish === "length" ? `Your reply was cut off at the output limit. Think less, act now: call a tool, or finish by calling one of: ${exitList}.` : `Continue with your tools. To finish, call one of: ${exitList}.`;
+	const steps = [];
+	const messages = [{
+		role: "user",
+		content: options.prompt
+	}];
+	let taken;
+	while (steps.length < maxRounds) {
+		const result = await generateText({
+			model: options.model,
+			system: options.system,
+			messages,
+			tools: {
+				...options.tools,
+				...exitTools
+			},
+			stopWhen: [stepCountIs(maxRounds - steps.length), ...stopWhen],
+			maxOutputTokens: options.maxOutputTokens,
+			maxRetries: options.maxRetries ?? 0,
+			abortSignal: signal,
+			onStepFinish: options.heartbeat ? async () => {
+				if (!await options.heartbeat()) abort.abort();
+			} : void 0
+		});
+		steps.push(...result.steps);
+		taken = exitIn(steps.at(-1), exits);
+		const budgetLeft = maxTokens === void 0 || tokensOf(steps) < maxTokens;
+		if (taken || result.finishReason === "tool-calls" || !budgetLeft) break;
+		messages.push(...result.responseMessages, {
+			role: "user",
+			content: reminder(result.finishReason)
+		});
+	}
+	const trace = {
+		rounds: steps.length,
+		toolCalls: steps.flatMap((s) => s.toolCalls.map((c) => c.toolName)),
+		tokens: tokensOf(steps)
+	};
+	if (!taken) throw nonRetryableError(`agent stopped without taking an exit after ${trace.rounds} rounds and ${trace.tokens} tokens (limits: ${maxRounds} rounds${maxTokens !== void 0 ? `, ${maxTokens} tokens` : ""})`);
+	return {
+		exit: taken.toolName,
+		value: taken.input,
+		trace
+	};
+}
+/** Run one agent to a typed answer: `runAgentToExit` with the single exit `answer`. */
+async function runAgent(options) {
+	const { output, ...rest } = options;
+	const run = await runAgentToExit({
+		...rest,
+		exits: { answer: {
+			description: "Give your final answer. Call this once you are done.",
+			schema: output
+		} }
+	});
+	return {
+		output: run.value,
+		trace: run.trace
+	};
+}
+/** The trace as a schema — for a step output that carries one. */
+const AGENT_TRACE_SCHEMA = z.object({
+	rounds: z.number(),
+	toolCalls: z.array(z.string()),
+	tokens: z.number()
+});
+/**
+* A step that runs one agent on the step's instrumented model. Its output is
+* `{ answer, trace }`: dependents read `ctx.deps.<key>.answer`, and the trace
+* stays on the run for whoever reads it back.
+*/
+function defineAgentStep(config) {
+	return defineStep({
+		type: config.type,
+		workflowInputSchema: config.workflowInputSchema,
+		outputSchema: z.object({
+			answer: config.answerSchema,
+			trace: AGENT_TRACE_SCHEMA
+		}),
+		dependencies: config.dependencies,
+		retry: config.retry,
+		timeoutMs: config.timeoutMs,
+		heartbeatTimeoutMs: config.heartbeatTimeoutMs,
+		onFailure: config.onFailure,
+		resources: config.resources,
+		when: config.when,
+		handler: async (ctx) => {
+			const { output, trace } = await runAgent({
+				model: ctx.context.model,
+				system: config.system,
+				prompt: config.prompt(ctx),
+				tools: config.tools?.(ctx),
+				output: config.answerSchema,
+				maxRounds: config.maxRounds,
+				maxTokens: config.maxTokens,
+				maxOutputTokens: config.maxOutputTokens,
+				heartbeat: ctx.heartbeat,
+				abortSignal: ctx.signal
+			});
+			return {
+				answer: output,
+				trace
+			};
+		}
+	});
+}
+//#endregion
 //#region src/ai/hooks.ts
 /**
 * Wire the AI behaviors (model instrumentation, token/cost capture, quota,
@@ -440,7 +578,7 @@ function createAiWorkflowHooks(deps) {
 				usage
 			};
 		},
-		async onAfterStep({ workflowId, stepId, context }) {
+		async onAfterStep({ workflowId, stepId, workflow, step, context }) {
 			const acc = context.usage;
 			if (!acc.hasUsage()) return;
 			const usage = acc.get();
@@ -456,6 +594,19 @@ function createAiWorkflowHooks(deps) {
 				usage,
 				costMicros
 			});
+			deps.usage?.record({
+				kind: "model",
+				service: usage.provider ?? "model",
+				model: usage.modelId,
+				inputTokens: usage.inputTokens,
+				outputTokens: usage.outputTokens,
+				cacheReadTokens: usage.cacheReadTokens,
+				cacheWriteTokens: usage.cacheWriteTokens,
+				context: {
+					runId: String(workflowId),
+					feature: workflow?.type ?? step?.key ?? "workflow"
+				}
+			});
 		},
 		async onWorkflowCompleted({ workflowId, workflow }) {
 			if (!deps.usageRecorder.recordWorkflowDaily) return;
@@ -1134,4 +1285,4 @@ function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
-export { 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, defineAiStep, embeddingDimensionsFor, estimateCostMicros, excerptOf, explainProviderError, isAiRefusalError, isFatalProviderError, isModelJsonError, isProviderError, isSubprocessorResidency, maskKeys, mergeModelJsonObjects, modelJsonRepairText, parseModelJson, readRefusalDetails, recoverModelJson, resolveEndpointResidency, supportsAdaptiveThinking, supportsToolSearch, testOllamaModel, testProvider, thinkingSettingsFor, withCircuitBreaker, withJsonRepair };
+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, 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 };

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

@@ -1,5 +1,5 @@
 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-l2Jmpuhr.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-_rio4ykx.js";
 import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
 //#region src/ai/providers/index.d.ts
 export type LanguageModelFactory = (modelId: string) => LanguageModelV4;

package/dist/{dispatcher-ClQMXA9E.d.ts → dispatcher-B3ruILCN.d.ts}

@@ -1,4 +1,4 @@
-import { bt as Result, et as StepId, st as WorkflowId, yt as FlowErrorShape } from "./index-Du05Lnwr.js";
+import { St as Result, lt as WorkflowId, nt as StepId, xt as FlowErrorShape } from "./index-D0XhoTkE.js";
 //#region src/core/dispatcher.d.ts
 /**
  * What a step job is for. A queue carries two kinds of work for a step, and

package/dist/{hooks-mWaAKHqn.d.ts → hooks-C46TPBEg.d.ts}

@@ -1,4 +1,4 @@
-import { U as StartOptions, bt as Result, et as StepId, ot as WorkflowDefinition, st as WorkflowId, tt as StepRecord, ut as WorkflowRecord, yt as FlowErrorShape } from "./index-Du05Lnwr.js";
+import { St as Result, W as StartOptions, ct as WorkflowDefinition, ft as WorkflowRecord, lt as WorkflowId, nt as StepId, rt as StepRecord, xt as FlowErrorShape } from "./index-D0XhoTkE.js";
 //#region src/core/hooks.d.ts
 interface BeforeStartArgs {
   definition: WorkflowDefinition;

package/dist/{index-Du05Lnwr.d.ts → index-D0XhoTkE.d.ts}

@@ -61,6 +61,8 @@ declare function computeReadiness(steps: StepRecord[], joinOf: (stepType: string
 type WorkflowId = number;
 type StepId = number;
 type WorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/** A durable start delay in ms — fixed, or computed from the run's input when the step becomes ready. */
+type StepDelay = number | ((workflowInput: Record<string, unknown>) => number);
 type StepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'waiting' | 'mapping' | 'compensating' | 'compensated';
 /**
  * Declarative workflow definition: a DAG of steps with dependencies.
@@ -278,9 +280,11 @@ interface StepRegistration<TContext = unknown> {
   /**
    * Durable start delay in ms: once the step becomes ready (all deps complete), its
    * first dispatch is held for this long via the queue. A no-op handler with a delay
-   * is a durable "sleep" step. Does not affect retry backoff.
+   * is a durable "sleep" step. Does not affect retry backoff. A function computes
+   * it from the run's input when the step becomes ready — a wait whose length the
+   * run decided (an agent's "check again in 3 days").
    */
-  delayMs?: number;
+  delayMs?: StepDelay;
   /**
    * When true, a ready step **suspends** (status `waiting`) instead of being dispatched,
    * until `engine.resumeStep(workflowId, stepKey, payload)` delivers an external event.
@@ -326,7 +330,7 @@ interface StepHandlerRegistry<TContext = unknown> {
     resources?: readonly string[];
     heartbeatTimeoutMs?: number;
     heartbeat?: 'auto' | 'manual';
-    delayMs?: number;
+    delayMs?: StepDelay;
     waitForEvent?: boolean;
     map?: boolean;
     childType?: string;
@@ -451,8 +455,8 @@ interface TypedStep<TInput extends Record<string, unknown> = Record<string, unkn
   readonly heartbeatTimeoutMs?: number;
   /** Who beats: the engine on a timer (`'auto'`, default) or only `ctx.heartbeat()`. */
   readonly heartbeat?: 'auto' | 'manual';
-  /** Optional durable start delay in ms (held in the queue once the step is ready). */
-  readonly delayMs?: number;
+  /** Optional durable start delay in ms (held in the queue once the step is ready), fixed or from the run's input. */
+  readonly delayMs?: StepDelay;
   /** When true, the step suspends (waiting) until `engine.resumeStep` delivers an event. */
   readonly waitForEvent?: boolean;
   /** Untyped guard built from the typed `when` config — `false` skips the step. */
@@ -610,8 +614,11 @@ interface DefineStepConfig<TInput extends Record<string, unknown>, TOutput exten
    * silence also means a *hung* handler.
    */
   heartbeat?: 'auto' | 'manual';
-  /** Optional durable start delay in ms — held in the queue once the step is ready. */
-  delayMs?: number;
+  /**
+   * Optional durable start delay in ms — held in the queue once the step is
+   * ready. A function computes it from the run's input at that moment.
+   */
+  delayMs?: number | ((workflowInput: TInput) => number);
   /** When true, the step suspends (waiting) until `engine.resumeStep` delivers an event. */
   waitForEvent?: boolean;
   /**
@@ -769,8 +776,8 @@ declare function defineSubWorkflowStep<TOutput extends Record<string, unknown> =
  */
 declare function defineSleepStep<TContext = unknown, TDeps extends Record<string, TypedStep<any, any, any, TContext>> = {}>(config: {
   type: string;
-  /** How long to sleep once the step becomes ready, in ms. */
-  sleepMs: number;
+  /** How long to sleep once the step becomes ready, in ms — fixed, or computed from the run's input then. */
+  sleepMs: StepDelay;
   dependencies?: TDeps;
 }): TypedStep<Record<string, never>, Record<string, never>, TDeps, TContext>;
 /** Minimal engine surface `buildWorkflow().start()` needs — avoids a circular import. */
@@ -1098,4 +1105,4 @@ declare function toPublicStep(step: StepRecord): PublicWorkflowStep;
  */
 declare function toPublicWorkflow(workflow: WorkflowWithSteps): PublicWorkflow;
 //#endregion
-export { StepHandlerRegistry as $, TypedStep as A, FlowError as B, defineDecisionOutcomeStep as C, resolveDecision as D, functionDecider as E, defineMapStep as F, StepCompensationContext as G, RetryPolicy as H, defineSleepStep as I, StepError as J, StepConditionHandler as K, defineStep as L, TypedWorkflow as M, WorkflowOutput as N, StepDeps as O, buildWorkflow as P, StepHandlerNotFoundError as Q, defineSubWorkflowStep as R, DecisionStep as S, ok as St, defineDecisionStep as T, StartOptions as U, InvalidWorkflowDefinitionError as V, StepCompensateHandler as W, StepFailurePolicy as X, StepExecutionContext as Y, StepHandler as Z, DecisionOutput as _, computeReadiness as _t, STEP_DISPLAY_STATUS as a, WorkflowCreatedResult as at, DecisionResponse as b, Result as bt, WORKFLOW_STATUS_SCHEMA as c, WorkflowNotFoundError as ct, toPublicWorkflow as d, WorkflowStatus as dt, StepId as et, Decider as f, WorkflowStepRunningError as ft, DecisionOutcome as g, ReadinessPlan as gt, DecisionChoices as h, PlannedSkip as ht, PublicWorkflowStep as i, WaitTimeoutPolicy as it, TypedStepContext as j, StepOutput as k, toDisplayStepStatus as l, WorkflowNotRetryableError as lt, DecisionAnswers as m, JoinRule as mt, PUBLIC_WORKFLOW_STEP_SCHEMA as n, StepRegistration as nt, STEP_DISPLAY_STATUS_SCHEMA as o, WorkflowDefinition as ot, DecisionAnswer as p, WorkflowWithSteps as pt, StepDefinition as q, PublicWorkflow as r, StepStatus as rt, StepDisplayStatus as s, WorkflowId as st, PUBLIC_WORKFLOW_SCHEMA as t, StepRecord as tt, toPublicStep as u, WorkflowRecord as ut, DecisionQuestions as v, isTerminalStepStatus as vt, defineDecisionReviewStep as w, DecisionReview as x, err as xt, DecisionRequest as y, FlowErrorShape as yt, defineWaitStep as z };
+export { StepHandler as $, StepOutput as A, defineWaitStep as B, defineDecisionOutcomeStep as C, err as Ct, resolveDecision as D, functionDecider as E, buildWorkflow as F, StepCompensateHandler as G, InvalidWorkflowDefinitionError as H, defineMapStep as I, StepDefinition as J, StepCompensationContext as K, defineSleepStep as L, TypedStepContext as M, TypedWorkflow as N, DefineStepConfig as O, WorkflowOutput as P, StepFailurePolicy as Q, defineStep as R, DecisionStep as S, Result as St, defineDecisionStep as T, RetryPolicy as U, FlowError as V, StartOptions as W, StepError as X, StepDelay as Y, StepExecutionContext as Z, DecisionOutput as _, PlannedSkip as _t, STEP_DISPLAY_STATUS as a, StepStatus as at, DecisionResponse as b, isTerminalStepStatus as bt, WORKFLOW_STATUS_SCHEMA as c, WorkflowDefinition as ct, toPublicWorkflow as d, WorkflowNotRetryableError as dt, StepHandlerNotFoundError as et, Decider as f, WorkflowRecord as ft, DecisionOutcome as g, JoinRule as gt, DecisionChoices as h, WorkflowWithSteps as ht, PublicWorkflowStep as i, StepRegistration as it, TypedStep as j, StepDeps as k, toDisplayStepStatus as l, WorkflowId as lt, DecisionAnswers as m, WorkflowStepRunningError as mt, PUBLIC_WORKFLOW_STEP_SCHEMA as n, StepId as nt, STEP_DISPLAY_STATUS_SCHEMA as o, WaitTimeoutPolicy as ot, DecisionAnswer as p, WorkflowStatus as pt, StepConditionHandler as q, PublicWorkflow as r, StepRecord as rt, StepDisplayStatus as s, WorkflowCreatedResult as st, PUBLIC_WORKFLOW_SCHEMA as t, StepHandlerRegistry as tt, toPublicStep as u, WorkflowNotFoundError as ut, DecisionQuestions as v, ReadinessPlan as vt, defineDecisionReviewStep as w, ok as wt, DecisionReview as x, FlowErrorShape as xt, DecisionRequest as y, computeReadiness as yt, defineSubWorkflowStep as z };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { $ as StepHandlerRegistry, A as TypedStep, B as FlowError, C as defineDecisionOutcomeStep, D as resolveDecision, E as functionDecider, F as defineMapStep, G as StepCompensationContext, H as RetryPolicy, I as defineSleepStep, J as StepError, K as StepConditionHandler, L as defineStep, M as TypedWorkflow, N as WorkflowOutput, O as StepDeps, P as buildWorkflow, Q as StepHandlerNotFoundError, R as defineSubWorkflowStep, S as DecisionStep, St as ok, T as defineDecisionStep, U as StartOptions, V as InvalidWorkflowDefinitionError, W as StepCompensateHandler, X as StepFailurePolicy, Y as StepExecutionContext, Z as StepHandler, _ as DecisionOutput, _t as computeReadiness, a as STEP_DISPLAY_STATUS, at as WorkflowCreatedResult, b as DecisionResponse, bt as Result, c as WORKFLOW_STATUS_SCHEMA, ct as WorkflowNotFoundError, d as toPublicWorkflow, dt as WorkflowStatus, et as StepId, f as Decider, ft as WorkflowStepRunningError, g as DecisionOutcome, gt as ReadinessPlan, h as DecisionChoices, ht as PlannedSkip, i as PublicWorkflowStep, it as WaitTimeoutPolicy, j as TypedStepContext, k as StepOutput, l as toDisplayStepStatus, lt as WorkflowNotRetryableError, m as DecisionAnswers, mt as JoinRule, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as StepRegistration, o as STEP_DISPLAY_STATUS_SCHEMA, ot as WorkflowDefinition, p as DecisionAnswer, pt as WorkflowWithSteps, q as StepDefinition, r as PublicWorkflow, rt as StepStatus, s as StepDisplayStatus, st as WorkflowId, t as PUBLIC_WORKFLOW_SCHEMA, tt as StepRecord, u as toPublicStep, ut as WorkflowRecord, v as DecisionQuestions, vt as isTerminalStepStatus, w as defineDecisionReviewStep, x as DecisionReview, xt as err, y as DecisionRequest, yt as FlowErrorShape, z as defineWaitStep } from "./index-Du05Lnwr.js";
+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-D0XhoTkE.js";
 import { n as Logger, r as noopLogger, t as LogAttributes } from "./logger-BCus3AOa.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-CkC4FRCp.js";
-import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-ClQMXA9E.js";
-import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-mWaAKHqn.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-0MLzBjuV.js";
+import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-B3ruILCN.js";
+import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-C46TPBEg.js";
 //#region src/core/registry.d.ts
 /**
  * Creates an in-memory step handler registry.
@@ -168,4 +168,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, 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, 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, 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 };

package/dist/index.js

@@ -436,10 +436,18 @@ function createWorkflowEngine(deps) {
 			}
 		};
 	}
-	/** Durable start delay for a ready step, from its registered `delayMs`. */
-	function readyStepDelay(stepType) {
-		const delayMs = registry.getRegistration(stepType)?.delayMs;
-		if (!delayMs || delayMs <= 0) return void 0;
+	/**
+	* Durable start delay for a ready step, from its registered `delayMs`. A
+	* function reads the run's input — the one extra read, and only for such steps.
+	*/
+	async function readyStepDelay(stepType, workflowId, st = store) {
+		const delay = registry.getRegistration(stepType)?.delayMs;
+		let delayMs = typeof delay === "number" ? delay : void 0;
+		if (typeof delay === "function") {
+			const workflow = await st.getWorkflow(workflowId);
+			delayMs = workflow ? delay(workflow.input ?? {}) : void 0;
+		}
+		if (!delayMs || !Number.isFinite(delayMs) || delayMs <= 0) return void 0;
 		return { startAfterSeconds: Math.ceil(delayMs / 1e3) };
 	}
 	/** Whether a step type suspends on readiness instead of dispatching. */
@@ -531,7 +539,7 @@ function createWorkflowEngine(deps) {
 			stepKey,
 			stepType
 		};
-		const delay = readyStepDelay(stepType);
+		const delay = await readyStepDelay(stepType, workflowId, st);
 		const result = scope ? await dispatcher.enqueueStepIn(scope.handle, payload, delay) : await dispatcher.enqueueStep(payload, delay);
 		if (!result.ok) {
 			logger.error("Failed to enqueue step", new Error(result.error.message), {
@@ -1289,7 +1297,7 @@ function createWorkflowEngine(deps) {
 				stepId: child.id,
 				stepKey: child.key,
 				stepType: child.type
-			}, readyStepDelay(child.type));
+			}, await readyStepDelay(child.type, workflowId));
 			if (!result.ok) logger.error("Failed to enqueue map child", new Error(result.error.message), {
 				workflowId,
 				stepKey: child.key

package/dist/{observability-CkC4FRCp.d.ts → observability-0MLzBjuV.d.ts}

@@ -1,4 +1,4 @@
-import { dt as WorkflowStatus, et as StepId, pt as WorkflowWithSteps, st as WorkflowId, tt as StepRecord, ut as WorkflowRecord } from "./index-Du05Lnwr.js";
+import { ft as WorkflowRecord, ht as WorkflowWithSteps, lt as WorkflowId, nt as StepId, pt as WorkflowStatus, rt as StepRecord } from "./index-D0XhoTkE.js";
 //#region src/core/store.d.ts
 interface CreateWorkflowStep {
   key: string;

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

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

package/dist/postgres/index.d.ts

@@ -1,5 +1,5 @@
-import { st as WorkflowId } from "../index-Du05Lnwr.js";
-import { P as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-CkC4FRCp.js";
+import { lt as WorkflowId } from "../index-D0XhoTkE.js";
+import { P as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-0MLzBjuV.js";
 import { Pool } from "pg";
 //#region src/postgres/ddl.d.ts
 /**
@@ -42,6 +42,53 @@ export interface SqlExecutor {
  * batteries-included executor used by the `createPg*` adapters.
  */
 export declare function poolExecutor(pool: Pool): SqlExecutor;
+/**
+ * The slice of a postgres.js `sql` instance {@link postgresJsExecutor} uses —
+ * structural, so the driver is never imported. `sql.unsafe` resolves to the row
+ * list with the affected-row `count` on it; `sql.begin` runs its callback on one
+ * reserved connection inside `BEGIN`/`COMMIT` and hands it a `sql` of the same shape.
+ */
+export interface PostgresJsSqlLike {
+  unsafe(query: string, params?: unknown[]): PromiseLike<unknown[] & {
+    count?: number | null;
+  }>;
+  begin<T>(fn: (tx: PostgresJsSqlLike) => Promise<T>): PromiseLike<T>;
+}
+/**
+ * Build a {@link SqlExecutor} over a postgres.js `sql` instance: top-level
+ * queries run on its pool (autocommit); `transaction` runs `fn` inside
+ * `sql.begin`, so every query of `fn` shares one connection and a throw rolls
+ * back. For a host whose app already speaks postgres.js (Drizzle's
+ * `drizzle-orm/postgres-js`) and that would otherwise open a `pg` pool just for
+ * the workflow store.
+ *
+ * ```ts
+ * import postgres from 'postgres';
+ * const sql = postgres(process.env.DATABASE_URL);
+ * const store = createWorkflowStore({ exec: postgresJsExecutor(sql), partitionKey });
+ * ```
+ *
+ * Wrap the result to set row-level-security GUCs first, exactly as with
+ * {@link poolExecutor}.
+ */
+export declare function postgresJsExecutor(sql: PostgresJsSqlLike): SqlExecutor;
+/** The slice of a PGlite instance {@link pgliteExecutor} uses — structural, so PGlite is never imported. */
+export interface PgliteLike {
+  query<R>(query: string, params?: unknown[]): Promise<{
+    rows: R[];
+    affectedRows?: number;
+  }>;
+}
+/** A PGlite instance: {@link PgliteLike} plus its `transaction`. */
+export interface PgliteDatabaseLike extends PgliteLike {
+  transaction<T>(fn: (tx: PgliteLike) => Promise<T>): Promise<T>;
+}
+/**
+ * Build a {@link SqlExecutor} over a PGlite instance — the embedded Postgres a
+ * host runs its tests (or a single-process deployment) on. `transaction` uses
+ * PGlite's own, which serialises with every other query on the instance.
+ */
+export declare function pgliteExecutor(db: PgliteDatabaseLike): SqlExecutor;
 /**
  * Normalize a `Pool | SqlExecutor` argument to a {@link SqlExecutor}. Lets the
  * read helpers accept either the batteries-included pool or a host's RLS-scoped

package/dist/postgres/index.js

@@ -126,6 +126,58 @@ function poolExecutor(pool) {
 	};
 }
 /**
+* Build a {@link SqlExecutor} over a postgres.js `sql` instance: top-level
+* queries run on its pool (autocommit); `transaction` runs `fn` inside
+* `sql.begin`, so every query of `fn` shares one connection and a throw rolls
+* back. For a host whose app already speaks postgres.js (Drizzle's
+* `drizzle-orm/postgres-js`) and that would otherwise open a `pg` pool just for
+* the workflow store.
+*
+* ```ts
+* import postgres from 'postgres';
+* const sql = postgres(process.env.DATABASE_URL);
+* const store = createWorkflowStore({ exec: postgresJsExecutor(sql), partitionKey });
+* ```
+*
+* Wrap the result to set row-level-security GUCs first, exactly as with
+* {@link poolExecutor}.
+*/
+function postgresJsExecutor(sql) {
+	const over = (conn, inTransaction) => ({
+		async query(text, params) {
+			const rows = await conn.unsafe(text, params ?? []);
+			return {
+				rows: Array.from(rows),
+				rowCount: rows.count ?? rows.length
+			};
+		},
+		transaction(fn) {
+			return inTransaction ? fn(over(conn, true)) : Promise.resolve(conn.begin((tx) => fn(over(tx, true))));
+		}
+	});
+	return over(sql, false);
+}
+/**
+* Build a {@link SqlExecutor} over a PGlite instance — the embedded Postgres a
+* host runs its tests (or a single-process deployment) on. `transaction` uses
+* PGlite's own, which serialises with every other query on the instance.
+*/
+function pgliteExecutor(db) {
+	const over = (conn, tx) => ({
+		async query(text, params) {
+			const res = await conn.query(text, params ?? []);
+			return {
+				rows: res.rows,
+				rowCount: res.affectedRows ?? res.rows.length
+			};
+		},
+		transaction(fn) {
+			return tx ? fn(over(conn, true)) : db.transaction((t) => fn(over(t, true)));
+		}
+	});
+	return over(db, false);
+}
+/**
 * Normalize a `Pool | SqlExecutor` argument to a {@link SqlExecutor}. Lets the
 * read helpers accept either the batteries-included pool or a host's RLS-scoped
 * executor without a breaking signature change. `SqlExecutor` is discriminated by
@@ -794,4 +846,4 @@ async function readFlowEvents(db, params) {
 	}));
 }
 //#endregion
-export { FLOW_EVENT_DDL, FLOW_GATE_DDL, FLOW_STORE_DDL, applySchema, createEventSink, createPgEventSink, createPgStepGate, createPgWorkflowStore, createSchemaDdl, createStepGate, createWorkflowStore, flowEventDdl, flowGateDdl, flowStoreDdl, poolExecutor, readFlowEvents, toExecutor };
+export { FLOW_EVENT_DDL, FLOW_GATE_DDL, FLOW_STORE_DDL, applySchema, createEventSink, createPgEventSink, createPgStepGate, createPgWorkflowStore, createSchemaDdl, createStepGate, createWorkflowStore, flowEventDdl, flowGateDdl, flowStoreDdl, pgliteExecutor, poolExecutor, postgresJsExecutor, readFlowEvents, toExecutor };

package/dist/{provider-probe-l2Jmpuhr.d.ts → provider-probe-_rio4ykx.d.ts}

@@ -1,4 +1,4 @@
-import { bt as Result } from "./index-Du05Lnwr.js";
+import { St as Result } from "./index-D0XhoTkE.js";
 import { o as AiProviderId } from "./provider-registry-C_mOfdHH.js";
 import { LanguageModelV4 } from "@ai-sdk/provider";
 //#region src/ai/provider-errors.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss, with an optional AI add-on (token/cost/quota). Layered single package.",
   "license": "MIT",
   "type": "module",
@@ -122,6 +122,7 @@
     "@ai-sdk/openai": "^4.0.95",
     "@ai-sdk/openai-compatible": "^3.0.70",
     "@ai-sdk/provider": "^4.0.28",
+    "@electric-sql/pglite": "0.5.10",
     "@testcontainers/postgresql": "^12.2.1",
     "@types/node": "^26.6.5",
     "@types/pg": "^8.23.1",