octaflow 0.32.0 → 0.33.0

package/README.md

@@ -202,6 +202,7 @@ 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 |

package/dist/ai/index.d.ts

@@ -1,8 +1,8 @@
-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 { 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-DZUO24Rz.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-C46TPBEg.js";
+import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-DHomzpiq.js";
 import { C as isSubprocessorResidency, S as embeddingDimensionsFor, _ as EmbeddingProviderMeta, a as AiProcessingRegion, b as OpenAiCompatibleProviderId, c as AiProviderModelOption, d as AiVendorResidency, f as DEFAULT_AI_PROVIDER, g as EmbeddingProviderId, h as EMBEDDING_PROVIDER_IDS, i as AiEndpointResidency, l as AiResidencyError, m as EMBEDDING_PROVIDERS, n as AI_PROVIDER_IDS, o as AiProviderId, p as DEFAULT_EMBEDDING_PROVIDER, r as AiEndpointRegion, s as AiProviderMeta, t as AI_PROVIDERS, u as AiResidencyResult, v as OPENAI_COMPATIBLE_PROVIDER, w as resolveEndpointResidency, x as OpenAiCompatibleProviderMeta, y as OPENAI_COMPATIBLE_PROVIDER_ID } from "../provider-registry-C_mOfdHH.js";
-import { A as maskKeys, C as ProviderErrorExplanation, D as explainProviderError, E as ProviderErrorPreset, O as isFatalProviderError, S as ProviderError, T as ProviderErrorPhrase, _ as ExplainProviderErrorOptions, a as OllamaProbeReport, b as PROVIDER_ERROR_REDACTED, c as ProviderProbeOptions, d as testProvider, f as CircuitBreaker, g as DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, h as withCircuitBreaker, i as OllamaProbeOptions, k as isProviderError, l as ProviderProbeReport, m as createCircuitBreaker, n as DEFAULT_PROVIDER_PROBE_PROMPT, o as ProbeableProvider, p as CircuitBreakerOptions, r as DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, s as ProviderProbeFailure, t as DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, u as testOllamaModel, v as FATAL_PROVIDER_ERROR_KEYS, w as ProviderErrorKey, x as PROVIDER_ERROR_STATUS, y as PROVIDER_ERROR_PHRASES } from "../provider-probe-_rio4ykx.js";
+import { A as maskKeys, C as ProviderErrorExplanation, D as explainProviderError, E as ProviderErrorPreset, O as isFatalProviderError, S as ProviderError, T as ProviderErrorPhrase, _ as ExplainProviderErrorOptions, a as OllamaProbeReport, b as PROVIDER_ERROR_REDACTED, c as ProviderProbeOptions, d as testProvider, f as CircuitBreaker, g as DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, h as withCircuitBreaker, i as OllamaProbeOptions, k as isProviderError, l as ProviderProbeReport, m as createCircuitBreaker, n as DEFAULT_PROVIDER_PROBE_PROMPT, o as ProbeableProvider, p as CircuitBreakerOptions, r as DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, s as ProviderProbeFailure, t as DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, u as testOllamaModel, v as FATAL_PROVIDER_ERROR_KEYS, w as ProviderErrorKey, x as PROVIDER_ERROR_STATUS, y as PROVIDER_ERROR_PHRASES } from "../provider-probe-BDg4c1Rk.js";
 import { z } from "zod";
 import { ToolSet } from "ai";
 import { EmbeddingModelV4, LanguageModelV4, LanguageModelV4Usage, SharedV4ProviderMetadata } from "@ai-sdk/provider";
@@ -866,4 +866,152 @@ export declare function withJsonRepair(model: LanguageModelV4, options?: JsonRep
  */
 export declare function addUsage(a: LanguageModelV4Usage, b: LanguageModelV4Usage): LanguageModelV4Usage;
 //#endregion
+//#region src/ai/case-loop.d.ts
+/** What a move leaves for the manager: a summary, and an outcome when the move itself ends the case. */
+export type CaseMoveResult<TOutcome extends string, TResult extends Record<string, unknown>> = TResult & {
+  summary: string;
+  closes?: TOutcome;
+};
+/** One finished move, as the next moves see it. */
+export interface CaseMoveRecord<TMove extends string, TOutcome extends string, TResult extends Record<string, unknown>> {
+  no: number;
+  move: TMove;
+  /** The manager's reason for it — its exit's `why`, when the exit has one. */
+  why: string;
+  result: CaseMoveResult<TOutcome, TResult>;
+}
+/** A move's input: the case's own fields, plus where the case stands. */
+export type CaseMoveInput<TMove extends string, TOutcome extends string, TCase extends Record<string, unknown>, TResult extends Record<string, unknown>> = TCase & {
+  caseId: string;
+  move: TMove;
+  /** 1 for the first move. */
+  moveNo: number;
+  /** The manager's arguments for this move — its exit's value. */
+  brief: Record<string, any>;
+  moves: CaseMoveRecord<TMove, TOutcome, TResult>[];
+  startedAt: string;
+};
+/** The manager's choice, as `decide` outputs it. `stuck` when it could not choose within its limits. */
+export type CaseDecision<TExit extends string = string> = {
+  exit: TExit | 'stuck';
+  value: Record<string, any>;
+  /** Choices the policy refused on the way, each with its reason, de-duplicated. */
+  refusals: Array<{
+    choice: string;
+    reason: string;
+  }>;
+  trace: AgentTrace;
+};
+/** What `next` did: the case's outcome, or `continued` with the run it started. */
+export type CaseNext<TOutcome extends string = string> = {
+  outcome: TOutcome | 'continued';
+  detail: string;
+  nextWorkflowId?: number;
+};
+type Ctx<THost> = AiContext<THost>;
+type AnyStep<THost> = TypedStep<any, any, any, Ctx<THost>>;
+export interface CaseLoopConfig<TMove extends string, TOutcome extends string, TCase extends Record<string, unknown>, TResult extends Record<string, unknown>, TDecisions extends AgentExits, TFacts, THost> {
+  /** Prefix of every workflow and step type: move `write` runs as `<name>:write`, its tail as `<name>:write:decide`. */
+  name: string;
+  moves: readonly [TMove, ...TMove[]];
+  /** The case's own fields, carried by every move. */
+  case: z.ZodType<TCase>;
+  /** The move result's own fields, beside `summary` and `closes`. */
+  result: z.ZodType<TResult>;
+  /** What a result step that failed stands in with — `summary` says it failed. */
+  failedResult: TResult;
+  outcomes: readonly [TOutcome, ...TOutcome[]];
+  /** The outcome of a case whose manager could not decide — a person takes it over. */
+  stuck: NoInfer<TOutcome>;
+  /** The exits the manager may take. An exit named after a move starts it; any other must be in `closers`. */
+  decisions: TDecisions;
+  /** The exits that close the case, each turning its value into the outcome. */
+  closers?: { [K in keyof TDecisions & string]?: (value: any) => {
+    outcome: NoInfer<TOutcome>;
+    detail: string;
+  }; };
+  /** The facts the policy is checked against, read once per decision — the move's own result included. */
+  facts: (ctx: TypedStepContext<CaseMoveInput<TMove, TOutcome, TCase, TResult>, any, Ctx<THost>>, result: CaseMoveResult<TOutcome, TResult>) => Promise<TFacts> | TFacts;
+  /** The policy on one choice: a reason refuses it. */
+  refuse?: (choice: keyof TDecisions & string, value: any, facts: TFacts, input: CaseMoveInput<TMove, TOutcome, TCase, TResult>) => string | null;
+  /** The most moves a case takes; from the last one on, only `atLimit` is allowed. */
+  maxMoves: number;
+  atLimit: ReadonlyArray<keyof TDecisions & string>;
+  manager: {
+    system: string;
+    /** The case file the manager decides on. */
+    prompt: (ctx: TypedStepContext<CaseMoveInput<TMove, TOutcome, TCase, TResult>, any, Ctx<THost>>, result: CaseMoveResult<TOutcome, TResult>, facts: TFacts) => string;
+    /** Read-only tools: the manager looks things up and chooses — the moves do the work. */
+    tools?: (ctx: TypedStepContext<CaseMoveInput<TMove, TOutcome, TCase, TResult>, any, Ctx<THost>>) => ToolSet;
+    maxRounds?: number;
+    maxTokens?: number;
+    maxOutputTokens?: number;
+    resources?: readonly string[];
+    retry?: RetryPolicy;
+    heartbeatTimeoutMs?: number;
+    /** The `detail` of a case closed as `stuck`. */
+    stuckDetail?: string;
+  };
+  startMove: (host: THost, input: CaseMoveInput<TMove, TOutcome, TCase, TResult>) => Promise<number>;
+  closeCase: (host: THost, closed: {
+    caseId: string;
+    outcome: TOutcome;
+    detail: string;
+  }) => Promise<void>;
+}
+export interface CaseMoveConfig<TMove extends string, TOutcome extends string, TCase extends Record<string, unknown>, TResult extends Record<string, unknown>, THost> {
+  /** The move's own steps, by key. `result`, `decide` and `next` are the tail's. */
+  steps: Record<string, AnyStep<THost>>;
+  /** The steps `result` reads — it runs once any of them completed and the others stopped. */
+  ends: Record<string, AnyStep<THost>>;
+  /** What the move achieved. `deps` holds the outputs of the `ends` that completed. */
+  summarize: (ctx: Omit<TypedStepContext<CaseMoveInput<TMove, TOutcome, TCase, TResult>, {}, Ctx<THost>>, 'deps'> & {
+    deps: Record<string, any>;
+  }) => Promise<CaseMoveResult<TOutcome, TResult>> | CaseMoveResult<TOutcome, TResult>;
+}
+export interface CaseLoop<TMove extends string, TOutcome extends string, TCase extends Record<string, unknown>, TResult extends Record<string, unknown>, TDecisions extends AgentExits, TFacts, THost> {
+  readonly name: string;
+  readonly inputSchema: z.ZodType<CaseMoveInput<TMove, TOutcome, TCase, TResult>>;
+  readonly resultSchema: z.ZodType<CaseMoveResult<TOutcome, TResult>>;
+  readonly decisionSchema: z.ZodType<CaseDecision<keyof TDecisions & string>>;
+  /** One move as its own workflow: its steps, then the tail. Throws on a step that can end in failure. */
+  move(name: TMove, config: CaseMoveConfig<TMove, TOutcome, TCase, TResult, THost>): TypedWorkflow<CaseMoveInput<TMove, TOutcome, TCase, TResult>, Ctx<THost>>;
+  /** The policy on one choice, with the move ceiling — what `decide` holds the manager to, for a page that shows it. */
+  refusal(choice: keyof TDecisions & string, value: unknown, facts: TFacts, input: CaseMoveInput<TMove, TOutcome, TCase, TResult>): string | null;
+  /** The input of a case's first move. */
+  first(fields: TCase & {
+    caseId: string;
+    move: TMove;
+    brief?: Record<string, any>;
+    startedAt?: string;
+  }): CaseMoveInput<TMove, TOutcome, TCase, TResult>;
+}
+/**
+ * Define a case loop: a manager agent that chooses every next move, each move
+ * its own workflow ending in the same tail — see the module comment.
+ *
+ * ```ts
+ * const loop = defineCaseLoop({
+ *   name: 'move',
+ *   moves: ['open', 'investigate', 'write', 'wait'],
+ *   case: z.object({ invoice: z.string() }),
+ *   result: z.object({ mailSent: z.boolean() }),
+ *   failedResult: { mailSent: false },
+ *   outcomes: ['paid', 'unresolved'],
+ *   stuck: 'unresolved',
+ *   decisions: { investigate: …, write: …, wait: …, close: … },
+ *   closers: { close: (v) => ({ outcome: 'paid', detail: v.summary }) },
+ *   facts: async (ctx) => readBooks(ctx.workflowInput.caseId),
+ *   refuse: (choice, value, facts) => (choice === 'close' && facts.balance > 0 ? 'The balance is open.' : null),
+ *   maxMoves: 12,
+ *   atLimit: ['close'],
+ *   manager: { system: '…', prompt: (ctx, result) => caseFile(ctx.workflowInput, result) },
+ *   startMove: (host, input) => host.startMove(input),
+ *   closeCase: (host, c) => host.cases.close(c.caseId, c.outcome, c.detail),
+ * });
+ * const write = loop.move('write', { steps: { compose, approval, send }, ends: { approval, send }, summarize });
+ * ```
+ */
+export declare function defineCaseLoop<const TMove extends string, const TOutcome extends string, TCase extends Record<string, unknown>, TResult extends Record<string, unknown>, TDecisions extends AgentExits, TFacts, THost = any>(config: CaseLoopConfig<TMove, TOutcome, TCase, TResult, TDecisions, TFacts, THost>): CaseLoop<TMove, TOutcome, TCase, TResult, TDecisions, TFacts, THost>;
+//#endregion
 export { AI_PROVIDERS, AI_PROVIDER_IDS, AiEndpointRegion, AiEndpointResidency, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiResidencyError, AiResidencyResult, AiVendorResidency, CircuitBreaker, CircuitBreakerOptions, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, ExplainProviderErrorOptions, FATAL_PROVIDER_ERROR_KEYS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, OllamaProbeOptions, OllamaProbeReport, OpenAiCompatibleProviderId, OpenAiCompatibleProviderMeta, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProbeableProvider, ProviderError, ProviderErrorExplanation, ProviderErrorKey, ProviderErrorPhrase, ProviderErrorPreset, ProviderProbeFailure, ProviderProbeOptions, ProviderProbeReport, createCircuitBreaker, embeddingDimensionsFor, explainProviderError, isFatalProviderError, isProviderError, isSubprocessorResidency, maskKeys, resolveEndpointResidency, testOllamaModel, testProvider, withCircuitBreaker };

package/dist/ai/index.js

@@ -1,5 +1,5 @@
 import { n as err, r as ok, t as noopLogger } from "../logger-epkdcXDA.js";
-import { C as nonRetryableError, _ as defineStep, m as buildWorkflow } from "../core-DBqxBk3R.js";
+import { C as nonRetryableError, _ as defineStep, m as buildWorkflow } from "../core-COMWflJl.js";
 import { S as readRefusalDetails, _ as maskKeys, a as testProvider, b as createRefusalAwareModel, c as DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, d as PROVIDER_ERROR_REDACTED, f as PROVIDER_ERROR_STATUS, g as isProviderError, h as isFatalProviderError, i as testOllamaModel, l as FATAL_PROVIDER_ERROR_KEYS, m as explainProviderError, n as DEFAULT_PROVIDER_PROBE_PROMPT, o as createCircuitBreaker, p as ProviderError, r as DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, s as withCircuitBreaker, t as DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, u as PROVIDER_ERROR_PHRASES, v as AiRefusalError, x as isAiRefusalError, y as REFUSAL_FINISH_REASON } from "../provider-probe-CGN2MpaZ.js";
 import { a as 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";
@@ -1285,4 +1285,278 @@ function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
-export { AGENT_TRACE_SCHEMA, AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_JSON_EXCERPT_LENGTH, DEFAULT_MODEL_PRICING, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, FATAL_PROVIDER_ERROR_KEYS, MODEL_JSON_PROVIDER_METADATA_KEY, MODEL_JSON_REPAIRED_ATTRIBUTE, ModelJsonError, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProviderError, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, addUsage, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCircuitBreaker, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createModelDecider, createRefusalAwareModel, createUsageAccumulator, defineAgentStep, defineAiStep, embeddingDimensionsFor, estimateCostMicros, excerptOf, explainProviderError, isAiRefusalError, isFatalProviderError, isModelJsonError, isProviderError, isSubprocessorResidency, maskKeys, mergeModelJsonObjects, modelJsonRepairText, parseModelJson, readRefusalDetails, recoverModelJson, resolveEndpointResidency, runAgent, runAgentToExit, supportsAdaptiveThinking, supportsToolSearch, testOllamaModel, testProvider, thinkingSettingsFor, withCircuitBreaker, withJsonRepair };
+//#region src/ai/case-loop.ts
+const NO_TRACE = {
+	rounds: 0,
+	toolCalls: [],
+	tokens: 0
+};
+const TAIL = [
+	"result",
+	"decide",
+	"next"
+];
+/** Why a step can end in failure, or null when it cannot. */
+function failureOf(step) {
+	if (step.waitForEvent) {
+		if (step.timeoutMs === void 0) return "a wait step without timeoutMs can hold the case forever";
+		if (typeof step.onTimeout !== "object") return "a wait step needs onTimeout: { output } — an expiry would fail the move";
+		return null;
+	}
+	if (typeof step.onFailure !== "object") return "a step needs onFailure: { output } — its failure would skip the tail and leave the case open";
+	return null;
+}
+/**
+* Define a case loop: a manager agent that chooses every next move, each move
+* its own workflow ending in the same tail — see the module comment.
+*
+* ```ts
+* const loop = defineCaseLoop({
+*   name: 'move',
+*   moves: ['open', 'investigate', 'write', 'wait'],
+*   case: z.object({ invoice: z.string() }),
+*   result: z.object({ mailSent: z.boolean() }),
+*   failedResult: { mailSent: false },
+*   outcomes: ['paid', 'unresolved'],
+*   stuck: 'unresolved',
+*   decisions: { investigate: …, write: …, wait: …, close: … },
+*   closers: { close: (v) => ({ outcome: 'paid', detail: v.summary }) },
+*   facts: async (ctx) => readBooks(ctx.workflowInput.caseId),
+*   refuse: (choice, value, facts) => (choice === 'close' && facts.balance > 0 ? 'The balance is open.' : null),
+*   maxMoves: 12,
+*   atLimit: ['close'],
+*   manager: { system: '…', prompt: (ctx, result) => caseFile(ctx.workflowInput, result) },
+*   startMove: (host, input) => host.startMove(input),
+*   closeCase: (host, c) => host.cases.close(c.caseId, c.outcome, c.detail),
+* });
+* const write = loop.move('write', { steps: { compose, approval, send }, ends: { approval, send }, summarize });
+* ```
+*/
+function defineCaseLoop(config) {
+	const { name, moves, outcomes, decisions } = config;
+	const closers = config.closers ?? {};
+	if (!outcomes.includes(config.stuck)) throw new Error(`[${name}] stuck outcome '${config.stuck}' is not one of the outcomes`);
+	for (const exit of Object.keys(decisions)) {
+		const isMove = moves.includes(exit);
+		if (isMove && closers[exit]) throw new Error(`[${name}] exit '${exit}' is a move and a closer`);
+		if (!isMove && !closers[exit]) throw new Error(`[${name}] exit '${exit}' is neither a move nor a closer`);
+	}
+	if (Object.hasOwn(decisions, "stuck")) throw new Error(`[${name}] 'stuck' is reserved`);
+	for (const exit of config.atLimit) if (!Object.hasOwn(decisions, exit)) throw new Error(`[${name}] atLimit names '${exit}', not an exit`);
+	if (!(config.maxMoves >= 1)) throw new Error(`[${name}] maxMoves must be at least 1`);
+	const resultSchema = z.intersection(config.result, z.object({
+		summary: z.string(),
+		closes: z.enum(outcomes).optional()
+	}));
+	const recordSchema = z.object({
+		no: z.number().int().min(1),
+		move: z.enum(moves),
+		why: z.string(),
+		result: resultSchema
+	});
+	const inputSchema = z.intersection(config.case, z.object({
+		caseId: z.string(),
+		move: z.enum(moves),
+		moveNo: z.number().int().min(1),
+		brief: z.record(z.string(), z.any()),
+		moves: z.array(recordSchema),
+		startedAt: z.string()
+	}));
+	const exitNames = Object.keys(decisions);
+	const decisionSchema = z.object({
+		exit: z.enum([...exitNames, "stuck"]),
+		value: z.record(z.string(), z.any()),
+		refusals: z.array(z.object({
+			choice: z.string(),
+			reason: z.string()
+		})),
+		trace: AGENT_TRACE_SCHEMA
+	});
+	const nextSchema = z.object({
+		outcome: z.enum([...outcomes, "continued"]),
+		detail: z.string(),
+		nextWorkflowId: z.number().optional()
+	});
+	const refusal = (choice, value, facts, input) => {
+		if (input.moveNo >= config.maxMoves && !config.atLimit.includes(choice)) return `${config.maxMoves} moves are spent — choose one of: ${config.atLimit.join(", ")}.`;
+		return config.refuse?.(choice, value, facts, input) ?? null;
+	};
+	const stuckDetail = config.manager.stuckDetail ?? "The manager could not decide — a person takes over.";
+	function tail(move, ends, summarize) {
+		const result = defineAiStep({
+			type: `${name}:${move}:result`,
+			workflowInputSchema: inputSchema,
+			outputSchema: resultSchema,
+			dependencies: ends,
+			join: "any",
+			onFailure: { output: {
+				...config.failedResult,
+				summary: `The ${move} move's result could not be read.`
+			} },
+			handler: async (ctx) => summarize(ctx)
+		});
+		const m = config.manager;
+		const decide = defineAiStep({
+			type: `${name}:${move}:decide`,
+			workflowInputSchema: inputSchema,
+			outputSchema: decisionSchema,
+			dependencies: { result },
+			when: (ctx) => !ctx.deps.result.closes,
+			resources: m.resources,
+			retry: m.retry,
+			heartbeatTimeoutMs: m.heartbeatTimeoutMs,
+			onFailure: { output: {
+				exit: "stuck",
+				value: { why: stuckDetail },
+				refusals: [],
+				trace: NO_TRACE
+			} },
+			handler: async (ctx) => {
+				const input = ctx.workflowInput;
+				const facts = await config.facts(ctx, ctx.deps.result);
+				const refusals = [];
+				const exits = Object.fromEntries(Object.entries(decisions).map(([exit, d]) => [exit, {
+					description: d.description,
+					schema: d.schema.superRefine((value, issue) => {
+						const reason = refusal(exit, value, facts, input);
+						if (!reason) return;
+						if (!refusals.some((r) => r.choice === exit && r.reason === reason)) refusals.push({
+							choice: exit,
+							reason
+						});
+						issue.addIssue({
+							code: "custom",
+							message: `Refused by policy: ${reason}`
+						});
+					})
+				}]));
+				const run = await runAgentToExit({
+					model: ctx.context.model,
+					system: m.system,
+					prompt: m.prompt(ctx, ctx.deps.result, facts),
+					tools: m.tools?.(ctx),
+					exits,
+					maxRounds: m.maxRounds ?? 10,
+					maxTokens: m.maxTokens,
+					maxOutputTokens: m.maxOutputTokens,
+					heartbeat: ctx.heartbeat,
+					abortSignal: ctx.signal
+				});
+				return {
+					exit: run.exit,
+					value: run.value ?? {},
+					refusals,
+					trace: run.trace
+				};
+			}
+		});
+		return {
+			result,
+			decide,
+			next: defineAiStep({
+				type: `${name}:${move}:next`,
+				workflowInputSchema: inputSchema,
+				outputSchema: nextSchema,
+				dependencies: {
+					result,
+					decide
+				},
+				join: "any",
+				retry: {
+					maxAttempts: 10,
+					backoff: "exponential",
+					initialDelayMs: 1e3,
+					maxDelayMs: 6e4
+				},
+				handler: async (ctx) => {
+					const i = ctx.workflowInput;
+					const r = ctx.deps.result;
+					const d = ctx.deps.decide;
+					const host = ctx.context.host;
+					const close = async (outcome, detail) => {
+						await config.closeCase(host, {
+							caseId: i.caseId,
+							outcome,
+							detail
+						});
+						return {
+							outcome,
+							detail
+						};
+					};
+					if (r.closes) return close(r.closes, r.summary);
+					if (!d || d.exit === "stuck") return close(config.stuck, String(d?.value.why ?? stuckDetail));
+					const closer = closers[d.exit];
+					if (closer) {
+						const c = closer(d.value);
+						return close(c.outcome, c.detail);
+					}
+					const record = {
+						no: i.moveNo,
+						move: i.move,
+						why: String(i.brief.why ?? ""),
+						result: r
+					};
+					const caseFields = Object.fromEntries(Object.entries(i).filter(([k]) => ![
+						"move",
+						"moveNo",
+						"brief",
+						"moves",
+						"startedAt"
+					].includes(k)));
+					const nextWorkflowId = await config.startMove(host, {
+						...caseFields,
+						move: d.exit,
+						moveNo: i.moveNo + 1,
+						brief: d.value,
+						moves: [...i.moves, record],
+						startedAt: (/* @__PURE__ */ new Date()).toISOString()
+					});
+					return {
+						outcome: "continued",
+						detail: `${d.exit}: ${String(d.value.why ?? "")}`,
+						nextWorkflowId
+					};
+				}
+			})
+		};
+	}
+	return {
+		name,
+		inputSchema,
+		resultSchema,
+		decisionSchema,
+		refusal,
+		first(fields) {
+			const { brief, startedAt, ...rest } = fields;
+			return {
+				...rest,
+				moveNo: 1,
+				brief: brief ?? {},
+				moves: [],
+				startedAt: startedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+			};
+		},
+		move(move, { steps, ends, summarize }) {
+			if (!moves.includes(move)) throw new Error(`[${name}] '${move}' is not a move`);
+			for (const key of TAIL) if (Object.hasOwn(steps, key)) throw new Error(`[${name}:${move}] step key '${key}' is the tail's`);
+			for (const [key, step] of Object.entries(steps)) {
+				const why = failureOf(step);
+				if (why) throw new Error(`[${name}:${move}] step '${key}' (${step.type}): ${why}`);
+			}
+			const owned = new Set(Object.values(steps));
+			for (const [key, step] of Object.entries(ends)) if (!owned.has(step)) throw new Error(`[${name}:${move}] ends.${key} is not one of the move's steps`);
+			if (Object.keys(ends).length === 0) throw new Error(`[${name}:${move}] ends names no step`);
+			return buildAiWorkflow({
+				type: `${name}:${move}`,
+				inputSchema,
+				steps: {
+					...steps,
+					...tail(move, ends, summarize)
+				}
+			});
+		}
+	};
+}
+//#endregion
+export { AGENT_TRACE_SCHEMA, AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_JSON_EXCERPT_LENGTH, DEFAULT_MODEL_PRICING, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, FATAL_PROVIDER_ERROR_KEYS, MODEL_JSON_PROVIDER_METADATA_KEY, MODEL_JSON_REPAIRED_ATTRIBUTE, ModelJsonError, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProviderError, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, addUsage, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCircuitBreaker, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createModelDecider, createRefusalAwareModel, createUsageAccumulator, defineAgentStep, defineAiStep, defineCaseLoop, embeddingDimensionsFor, estimateCostMicros, excerptOf, explainProviderError, isAiRefusalError, isFatalProviderError, isModelJsonError, isProviderError, isSubprocessorResidency, maskKeys, mergeModelJsonObjects, modelJsonRepairText, parseModelJson, readRefusalDetails, recoverModelJson, resolveEndpointResidency, runAgent, runAgentToExit, supportsAdaptiveThinking, supportsToolSearch, testOllamaModel, testProvider, thinkingSettingsFor, withCircuitBreaker, withJsonRepair };

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-_rio4ykx.js";
+import { A as maskKeys, C as ProviderErrorExplanation, D as explainProviderError, E as ProviderErrorPreset, O as isFatalProviderError, S as ProviderError, T as ProviderErrorPhrase, _ as ExplainProviderErrorOptions, a as OllamaProbeReport, c as ProviderProbeOptions, d as testProvider, f as CircuitBreaker, h as withCircuitBreaker, i as OllamaProbeOptions, k as isProviderError, l as ProviderProbeReport, m as createCircuitBreaker, o as ProbeableProvider, p as CircuitBreakerOptions, s as ProviderProbeFailure, u as testOllamaModel, v as FATAL_PROVIDER_ERROR_KEYS, w as ProviderErrorKey, x as PROVIDER_ERROR_STATUS, y as PROVIDER_ERROR_PHRASES } from "../../provider-probe-BDg4c1Rk.js";
 import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
 //#region src/ai/providers/index.d.ts
 export type LanguageModelFactory = (modelId: string) => LanguageModelV4;

package/dist/{core-DBqxBk3R.js → core-COMWflJl.js}

@@ -459,6 +459,7 @@ function defineSleepStep(config) {
 		outputSchema: emptyObjectSchema,
 		dependencies: config.dependencies,
 		delayMs: config.sleepMs,
+		onFailure: config.onFailure,
 		handler: async () => ({})
 	});
 }
@@ -635,6 +636,7 @@ function defineDecisionStep(config) {
 			isRetryable: config.isRetryable,
 			timeoutMs: config.timeoutMs,
 			resources: config.resources,
+			onFailure: config.onFailure,
 			handler: async (ctx) => {
 				const response = await decider.decide({
 					questions,

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

@@ -1,4 +1,4 @@
-import { St as Result, lt as WorkflowId, nt as StepId, xt as FlowErrorShape } from "./index-D0XhoTkE.js";
+import { St as Result, lt as WorkflowId, nt as StepId, xt as FlowErrorShape } from "./index-DZUO24Rz.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-C46TPBEg.d.ts → hooks-DHomzpiq.d.ts}

@@ -1,4 +1,4 @@
-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";
+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-DZUO24Rz.js";
 //#region src/core/hooks.d.ts
 interface BeforeStartArgs {
   definition: WorkflowDefinition;

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

@@ -779,6 +779,13 @@ declare function defineSleepStep<TContext = unknown, TDeps extends Record<string
   /** How long to sleep once the step becomes ready, in ms — fixed, or computed from the run's input then. */
   sleepMs: StepDelay;
   dependencies?: TDeps;
+  /**
+   * What a terminal failure does — the sleep's job exhausted, its worker
+   * presumed dead. `{ output: {} }` wakes the run anyway. Default `'fail'`.
+   */
+  onFailure?: 'fail' | {
+    output: Record<string, never>;
+  };
 }): TypedStep<Record<string, never>, Record<string, never>, TDeps, TContext>;
 /** Minimal engine surface `buildWorkflow().start()` needs — avoids a circular import. */
 interface StartableEngine {
@@ -908,6 +915,10 @@ interface DefineDecisionStepConfig<Q extends DecisionQuestions, TInput extends R
   timeoutMs?: number;
   /** Resources the decider draws on (a model, say), for the admission gate — see `defineStep`. */
   resources?: readonly string[];
+  /** What a terminal failure does — see `defineStep`'s `onFailure`. Default `'fail'`. */
+  onFailure?: 'fail' | {
+    output: DecisionOutput<Q>;
+  };
 }
 /**
  * Define a **decision** step: the decider answers each question with one of

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-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 { $ 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 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";
+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/registry.d.ts
 /**
  * Creates an in-memory step handler registry.

package/dist/index.js

@@ -1,6 +1,6 @@
 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-DBqxBk3R.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";
 //#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/{observability-0MLzBjuV.d.ts → observability-BLUEjdto.d.ts}

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

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

@@ -1,6 +1,6 @@
-import "../index-D0XhoTkE.js";
+import "../index-DZUO24Rz.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { r as Dispatcher } from "../dispatcher-B3ruILCN.js";
+import { r as Dispatcher } from "../dispatcher-BQErUGy_.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 { 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 { lt as WorkflowId } from "../index-DZUO24Rz.js";
+import { P as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-BLUEjdto.js";
 import { Pool } from "pg";
 //#region src/postgres/ddl.d.ts
 /**

package/dist/postgres/index.js

@@ -1,5 +1,5 @@
 import { n as gateRuleKeys } from "../gate-BRq-t3K_.js";
-import "../core-DBqxBk3R.js";
+import "../core-COMWflJl.js";
 //#region src/postgres/ddl.ts
 /**
 * Schema for the Postgres WorkflowStore adapter. Two tables mirror flow-core's

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

@@ -1,4 +1,4 @@
-import { St as Result } from "./index-D0XhoTkE.js";
+import { St as Result } from "./index-DZUO24Rz.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.32.0",
+  "version": "0.33.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",

package/skills/add-a-case-loop/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: add-a-case-loop
+description: Add an octaflow case loop — a manager agent chooses every next move of a case (investigate, draft, wait, ask a person, escalate, close), each move its own workflow with its own shape, all ending in the same tail; the policy refuses a choice with its reason inside the exit's schema so the agent chooses again, every outward step waits for a person, and no failure leaves a case open. Use when the sequence of work is not known in advance; when it is, write one workflow, and when the model only picks among options, use add-a-decision.
+---
+
+# Add a case loop
+
+> Paths under `apps/` and `packages/` are in the platform repository,
+> <https://github.com/octabits-io/octabits>. In your own app, read a package's README at
+> `node_modules/octaflow/README.md`.
+
+A case loop is for work whose order nobody can write down: chasing an overdue invoice, checking
+a claim until it holds or falls. A **manager** agent reads the case file and takes one exit per
+decision; each exit named after a **move** starts that move's workflow, each other exit closes
+the case.
+
+```
+┌──────── move N (its own steps) ────────┐
+… body … ─► result ─► decide (manager) ─► next ─► move N+1 | case closed
+```
+
+Shown end to end in `apps/demo-task-loop/src/moves.ts` (Postgres, pg-boss, a customer agent
+that answers by resuming the move that waits for it), with whole cases on scripted models in
+`apps/demo-task-loop/src/moves.test.ts`. The loop's own tests are
+`packages/octaflow/src/ai/case-loop.test.ts`.
+
+**Which pattern?**
+
+| The model… | Pattern |
+|---|---|
+| chooses what happens next, and the next thing is a whole piece of work | a case loop (this skill) |
+| chooses among options you can list for one record | `add-a-decision` (beside this skill) |
+| writes content a person always reviews | `add-an-ai-proposal-workflow` (beside this skill) |
+
+## 1. Define the loop
+
+```ts
+import { defineCaseLoop } from 'octaflow/ai';
+
+export const caseLoop = defineCaseLoop({
+  name: 'move',                                   // workflow types move:<move>, tail steps move:<move>:result|decide|next
+  moves: ['open', 'investigate', 'write', 'wait', 'escalate'],
+  case: z.object({ invoiceId: z.string() }),      // the case's own fields, carried by every move
+  result: z.object({ mailSent: z.boolean() }),    // a move's result beside `summary` and `closes`
+  failedResult: { mailSent: false },
+  outcomes: ['paid', 'collection', 'unresolved'],
+  stuck: 'unresolved',                            // a manager that cannot decide hands the case to a person
+  decisions: {
+    investigate: { description: '…', schema: z.object({ question: z.string(), why: z.string() }) },
+    write: { description: '…', schema: z.object({ purpose: z.string(), why: z.string() }) },
+    wait: { description: '…', schema: z.object({ days: z.number().int().min(1).max(14), why: z.string() }) },
+    escalate: { description: '…', schema: z.object({ reason: z.string(), why: z.string() }) },
+    close: { description: 'Close: paid.', schema: z.object({ summary: z.string(), why: z.string() }) },
+  },
+  closers: { close: (v) => ({ outcome: 'paid', detail: v.summary }) },
+  facts: async (ctx, result) => readFacts(ctx.workflowInput, result),   // once per decision, this move's result included
+  refuse: (choice, value, facts) =>
+    choice === 'close' && facts.balance > 0 ? `The open balance is ${facts.balance}.` : null,
+  maxMoves: 12,
+  atLimit: ['escalate', 'close'],
+  manager: {
+    system: 'You decide the next move, one at a time, by calling exactly one decision tool. …',
+    prompt: (ctx, result, facts) => caseFile(ctx.workflowInput, result, facts),
+    tools: (ctx) => readOnlyTools(ctx),            // the manager looks things up; moves do the work
+    resources: ['llm'],
+    retry: { maxAttempts: 3 },
+  },
+  startMove: (host: Host, input) => host.startMove(input),
+  closeCase: (host: Host, c) => host.cases.close(c.caseId, c.outcome, c.detail),
+});
+```
+
+- Give every exit a `why`: the next move's input keeps it as the record's reason.
+- The policy belongs in `refuse`, never in the prompt alone. A refused choice is an invalid
+  tool call answered with "Refused by policy: <reason>"; the manager chooses again, and
+  `decide`'s output lists the refusals for the page.
+- `caseLoop.refusal(choice, value, facts, input)` is the same check, ceiling included — use it
+  on the page that shows what the manager may choose next.
+
+## 2. Write each move
+
+```ts
+const write = caseLoop.move('write', {
+  steps: { compose, riskCritic, factCritic, approval, send, reply },
+  ends: { compose, approval, send, reply },       // what `result` reads; it runs once one completed and the rest stopped
+  summarize: (ctx) => mailSummary(ctx.deps),
+});
+```
+
+`move()` throws at definition time on a step that can end in failure, because a failed step
+skips the tail and nothing would close the case:
+
+- every step declares `onFailure: { output }` — a stand-in the move's summary can say out loud
+  ("the draft failed", "sending failed"), with `when` guards so nothing downstream acts on it;
+- every wait step has `timeoutMs` and `onTimeout: { output }` (`{ decision: 'expired' }`);
+- a sleep step takes `onFailure: { output: {} }`.
+
+Anything that leaves the house — a mail, a booking, a filing — is a wait step for a person
+followed by a step that does exactly what the person saw, with no model in between. Critics see
+the purpose and the draft, never the writer's trace.
+
+## 3. Wire the host
+
+`startMove` starts `workflows[input.move]` with `{ idempotencyKey: \`${caseId}:${moveNo}\` }`, so
+a re-run `next` starts the move once. Register every move's workflow; start a case with
+`caseLoop.first({ caseId, ...caseFields, move: 'open' })`. Another workflow (a customer, a child
+check) answers a move by `engine.resumeStep(moveWorkflowId, 'reply', payload)`; a `false` result
+means the move stopped waiting — keep the answer where the next `wait` move finds it.
+
+## Prove it works
+
+A test on the in-memory engine with one scripted model whose lines are routed by the system
+prompt — `apps/demo-task-loop/src/moves.test.ts` is the template — that asserts:
+
+- a whole case: the moves in order, the outcome the host recorded;
+- a refused choice is in `decide`'s `refusals` with its reason, and the next choice is taken;
+- at `maxMoves` only the `atLimit` exits pass;
+- a manager with no lines left closes the case as `stuck`;
+- a drafting step that fails reaches no person and the manager decides again.
+
+```bash
+pnpm --filter octaflow test:unit
+```
+
+Green: `src/ai/case-loop.test.ts` passes, including "refuses a step that can end in failure"
+and "closes the case as stuck when the manager cannot decide".
+
+## Checklist
+
+- [ ] Every exit has a `why`; every non-move exit has a closer
+- [ ] The policy is in `refuse` and reads facts from the store, not from the model's words
+- [ ] The manager's tools only read
+- [ ] Every outward step waits for a person and sends exactly what they released
+- [ ] `startMove` passes the `caseId:moveNo` idempotency key
+- [ ] The manager's model goes through the disclosure gate
+- [ ] A test plays whole cases on scripted models