octaflow 0.28.0 → 0.29.1

package/dist/ai/index.d.ts

@@ -1,7 +1,7 @@
 import { A as TypedStep, H as RetryPolicy, M as TypedWorkflow, f as Decider, j as TypedStepContext, vt as FlowErrorShape, yt as Result } from "../index-B8SvtiYn.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
 import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-BV-Vany9.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-BvXBqJDR.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 { z } from "zod";
 import { EmbeddingModelV4, LanguageModelV4, SharedV4ProviderMetadata } from "@ai-sdk/provider";
 //#region src/ai/instrumented-model.d.ts
@@ -73,8 +73,8 @@ export interface TokenUsage {
   cacheWriteTokens: number;
 }
 /**
- * Default pricing, USD per million tokens — Anthropic as of 2026-09, Mistral and
- * the OpenAI embeddings as of 2026-08. A best-effort estimate, not a billing
+ * Default pricing, USD per million tokens — Anthropic as of 2026-10, Mistral and
+ * the OpenAI embeddings as of 2026-08, the OpenAI language models as of 2026-10. A best-effort estimate, not a billing
  * record: a BYOK caller can name any model id, and an unknown id prices at the
  * priciest row (safe overcounting — see {@link createCostEstimator}). Retired ids
  * are kept rather than deleted: dropping one silently reprices every historical
@@ -507,7 +507,8 @@ export declare function createRefusalAwareModel(model: LanguageModelV4): Languag
 /**
  * Per-model API capability switches.
  *
- * Claude 4.6+ models (Opus 4.6/4.7/4.8/5, Sonnet 4.6/5, Fable/Mythos 5) use
+ * Claude 4.6+ models (Opus 4.6/4.7/4.8/5/5.5, Sonnet 4.6/5/5.5, Haiku 5.5,
+ * Fable/Mythos 5) use
  * adaptive thinking; on 4.7+ the legacy `thinking: { type: 'enabled',
  * budget_tokens }` shape and non-default sampling params (`temperature`,
  * `top_p`, `top_k`) are rejected with a 400. Older models (Haiku 4.5,
@@ -519,7 +520,7 @@ export declare function createRefusalAwareModel(model: LanguageModelV4): Languag
  * functions are that branch, written once. `providerId` is a plain string:
  * only `'anthropic'` has provider-specific shapes today.
  */
-/** True for Claude 4.6+ / 5-family models: adaptive thinking, no budgetTokens, no sampling params. */
+/** True for Claude 4.6+ / 5-family models (`claude-opus-5` covers `claude-opus-5-5`, and so on): adaptive thinking, no budgetTokens, no sampling params. */
 export declare function supportsAdaptiveThinking(modelId: string): boolean;
 export interface AnthropicThinkingSettings {
   temperature?: number;

package/dist/ai/index.js

@@ -1,6 +1,6 @@
 import { D as ok, E as err, T as noopLogger, _ as defineStep, m as buildWorkflow } from "../core-C9h3-KFr.js";
 import { a as readRefusalDetails, i as isAiRefusalError, n as REFUSAL_FINISH_REASON, r as createRefusalAwareModel, t as AiRefusalError } from "../refusal-BsL2HPDb.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-BRwjC6_3.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";
 //#region src/ai/instrumented-model.ts
@@ -125,8 +125,8 @@ function createInstrumentedEmbeddingModel(model, accumulator) {
 //#endregion
 //#region src/ai/cost.ts
 /**
-* Default pricing, USD per million tokens — Anthropic as of 2026-09, Mistral and
-* the OpenAI embeddings as of 2026-08. A best-effort estimate, not a billing
+* Default pricing, USD per million tokens — Anthropic as of 2026-10, Mistral and
+* the OpenAI embeddings as of 2026-08, the OpenAI language models as of 2026-10. A best-effort estimate, not a billing
 * record: a BYOK caller can name any model id, and an unknown id prices at the
 * priciest row (safe overcounting — see {@link createCostEstimator}). Retired ids
 * are kept rather than deleted: dropping one silently reprices every historical
@@ -170,6 +170,12 @@ const DEFAULT_MODEL_PRICING = {
 		cacheReadPerMillion: .25,
 		cacheWritePerMillion: 12.5
 	},
+	"claude-opus-5-5": {
+		inputPerMillion: 4,
+		outputPerMillion: 20,
+		cacheReadPerMillion: .2,
+		cacheWritePerMillion: 5
+	},
 	"claude-opus-5": {
 		inputPerMillion: 5,
 		outputPerMillion: 25,
@@ -182,6 +188,18 @@ const DEFAULT_MODEL_PRICING = {
 		cacheReadPerMillion: .2,
 		cacheWritePerMillion: 2.5
 	},
+	"claude-sonnet-5-5": {
+		inputPerMillion: 2,
+		outputPerMillion: 10,
+		cacheReadPerMillion: .2,
+		cacheWritePerMillion: 2.5
+	},
+	"claude-haiku-5-5": {
+		inputPerMillion: .1,
+		outputPerMillion: .5,
+		cacheReadPerMillion: .01,
+		cacheWritePerMillion: .125
+	},
 	"claude-opus-4-8": {
 		inputPerMillion: 5,
 		outputPerMillion: 25,
@@ -265,6 +283,30 @@ const DEFAULT_MODEL_PRICING = {
 		outputPerMillion: 0,
 		cacheReadPerMillion: 0,
 		cacheWritePerMillion: 0
+	},
+	"gpt-6-astra": {
+		inputPerMillion: 10,
+		outputPerMillion: 50,
+		cacheReadPerMillion: 1,
+		cacheWritePerMillion: 12.5
+	},
+	"gpt-6.1-sol": {
+		inputPerMillion: 2,
+		outputPerMillion: 10,
+		cacheReadPerMillion: .1,
+		cacheWritePerMillion: 2.5
+	},
+	"gpt-6-sol": {
+		inputPerMillion: 2,
+		outputPerMillion: 10,
+		cacheReadPerMillion: .2,
+		cacheWritePerMillion: 2.5
+	},
+	"gpt-6-luna": {
+		inputPerMillion: .1,
+		outputPerMillion: .5,
+		cacheReadPerMillion: .01,
+		cacheWritePerMillion: .125
 	}
 };
 /**
@@ -627,7 +669,8 @@ function createAiUsageAggregationService(deps) {
 /**
 * Per-model API capability switches.
 *
-* Claude 4.6+ models (Opus 4.6/4.7/4.8/5, Sonnet 4.6/5, Fable/Mythos 5) use
+* Claude 4.6+ models (Opus 4.6/4.7/4.8/5/5.5, Sonnet 4.6/5/5.5, Haiku 5.5,
+* Fable/Mythos 5) use
 * adaptive thinking; on 4.7+ the legacy `thinking: { type: 'enabled',
 * budget_tokens }` shape and non-default sampling params (`temperature`,
 * `top_p`, `top_k`) are rejected with a 400. Older models (Haiku 4.5,
@@ -647,9 +690,10 @@ const ADAPTIVE_THINKING_MODEL_PREFIXES = [
 	"claude-opus-4-7",
 	"claude-opus-4-6",
 	"claude-sonnet-5",
-	"claude-sonnet-4-6"
+	"claude-sonnet-4-6",
+	"claude-haiku-5"
 ];
-/** True for Claude 4.6+ / 5-family models: adaptive thinking, no budgetTokens, no sampling params. */
+/** True for Claude 4.6+ / 5-family models (`claude-opus-5` covers `claude-opus-5-5`, and so on): adaptive thinking, no budgetTokens, no sampling params. */
 function supportsAdaptiveThinking(modelId) {
 	return ADAPTIVE_THINKING_MODEL_PREFIXES.some((prefix) => modelId.startsWith(prefix));
 }

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

@@ -1,4 +1,4 @@
-import { b as OpenAiCompatibleProviderId, g as EmbeddingProviderId, i as AiEndpointResidency, o as AiProviderId } from "../../provider-registry-BvXBqJDR.js";
+import { b as OpenAiCompatibleProviderId, g as EmbeddingProviderId, i as AiEndpointResidency, o as AiProviderId } from "../../provider-registry-C_mOfdHH.js";
 import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
 //#region src/ai/providers/index.d.ts
 export type LanguageModelFactory = (modelId: string) => LanguageModelV4;

package/dist/ai/providers/index.js

@@ -1,5 +1,5 @@
 import { r as createRefusalAwareModel } from "../../refusal-BsL2HPDb.js";
-import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, t as AI_PROVIDERS } from "../../provider-registry-BRwjC6_3.js";
+import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, t as AI_PROVIDERS } from "../../provider-registry-B91lgOmu.js";
 import { wrapLanguageModel } from "ai";
 //#region src/ai/providers/index.ts
 const LLM_LOADERS = {
@@ -16,6 +16,13 @@ const LLM_LOADERS = {
 			apiKey,
 			baseURL
 		});
+	},
+	openai: async (apiKey, baseURL) => {
+		const { createOpenAI } = await import("@ai-sdk/openai");
+		return createOpenAI({
+			apiKey,
+			baseURL
+		});
 	}
 };
 const EMBEDDING_LOADERS = {

package/dist/ai/registry.d.ts

@@ -1,2 +1,2 @@
-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-BvXBqJDR.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";
 export { AI_PROVIDERS, AI_PROVIDER_IDS, AiEndpointRegion, AiEndpointResidency, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiResidencyError, AiResidencyResult, AiVendorResidency, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, OpenAiCompatibleProviderId, OpenAiCompatibleProviderMeta, embeddingDimensionsFor, isSubprocessorResidency, resolveEndpointResidency };

package/dist/ai/registry.js

@@ -1,2 +1 @@
-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-BRwjC6_3.js";
-export { AI_PROVIDERS, AI_PROVIDER_IDS, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, embeddingDimensionsFor, isSubprocessorResidency, resolveEndpointResidency };
+export { t as AI_PROVIDERS, n as AI_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, i as DEFAULT_EMBEDDING_PROVIDER, a as EMBEDDING_PROVIDERS, o as EMBEDDING_PROVIDER_IDS, s as OPENAI_COMPATIBLE_PROVIDER, c as OPENAI_COMPATIBLE_PROVIDER_ID, l as embeddingDimensionsFor, u as isSubprocessorResidency, d as resolveEndpointResidency } from "../provider-registry-B91lgOmu.js";

package/dist/{provider-registry-BRwjC6_3.js → provider-registry-B91lgOmu.js}

@@ -9,7 +9,11 @@
 * Adding a provider: an id here with its metadata, a factory in
 * `providers/`, and pricing rows in `cost.ts`.
 */
-const AI_PROVIDER_IDS = ["anthropic", "mistral"];
+const AI_PROVIDER_IDS = [
+	"anthropic",
+	"mistral",
+	"openai"
+];
 const EMBEDDING_PROVIDER_IDS = ["openai", "mistral"];
 /**
 * What an unset provider resolves to: the EU-established vendor, so a deployment
@@ -29,27 +33,31 @@ const AI_PROVIDERS = {
 			legalName: "Anthropic PBC",
 			country: "US"
 		},
-		defaultModel: "claude-sonnet-5",
-		classifierModel: "claude-haiku-4-5",
-		testModel: "claude-haiku-4-5",
+		defaultModel: "claude-sonnet-5-5",
+		classifierModel: "claude-haiku-5-5",
+		testModel: "claude-haiku-5-5",
 		keyPrefix: "sk-ant-",
 		consoleKeyUrl: "https://console.anthropic.com/settings/keys",
 		modelOptions: [
 			{
-				label: "Claude Opus 5",
-				value: "claude-opus-5"
+				label: "Claude Opus 5.5",
+				value: "claude-opus-5-5"
 			},
 			{
-				label: "Claude Opus 4.8",
-				value: "claude-opus-4-8"
+				label: "Claude Sonnet 5.5",
+				value: "claude-sonnet-5-5"
 			},
 			{
-				label: "Claude Sonnet 5",
-				value: "claude-sonnet-5"
+				label: "Claude Haiku 5.5",
+				value: "claude-haiku-5-5"
+			},
+			{
+				label: "Claude Opus 5",
+				value: "claude-opus-5"
 			},
 			{
-				label: "Claude Haiku 4.5",
-				value: "claude-haiku-4-5"
+				label: "Claude Sonnet 5",
+				value: "claude-sonnet-5"
 			}
 		]
 	},
@@ -80,6 +88,34 @@ const AI_PROVIDERS = {
 				value: "mistral-small-latest"
 			}
 		]
+	},
+	openai: {
+		id: "openai",
+		label: "OpenAI",
+		residency: {
+			region: "third-country",
+			legalName: "OpenAI, L.L.C.",
+			country: "US"
+		},
+		defaultModel: "gpt-6.1-sol",
+		classifierModel: "gpt-6-luna",
+		testModel: "gpt-6-luna",
+		keyPrefix: "sk-",
+		consoleKeyUrl: "https://platform.openai.com/api-keys",
+		modelOptions: [
+			{
+				label: "GPT-6 Astra",
+				value: "gpt-6-astra"
+			},
+			{
+				label: "GPT-6.1 Sol",
+				value: "gpt-6.1-sol"
+			},
+			{
+				label: "GPT-6 Luna",
+				value: "gpt-6-luna"
+			}
+		]
 	}
 };
 const EMBEDDING_PROVIDERS = {

package/dist/{provider-registry-BvXBqJDR.d.ts → provider-registry-C_mOfdHH.d.ts}

@@ -9,7 +9,7 @@
  * Adding a provider: an id here with its metadata, a factory in
  * `providers/`, and pricing rows in `cost.ts`.
  */
-declare const AI_PROVIDER_IDS: readonly ['anthropic', 'mistral'];
+declare const AI_PROVIDER_IDS: readonly ['anthropic', 'mistral', 'openai'];
 type AiProviderId = (typeof AI_PROVIDER_IDS)[number];
 declare const EMBEDDING_PROVIDER_IDS: readonly ['openai', 'mistral'];
 type EmbeddingProviderId = (typeof EMBEDDING_PROVIDER_IDS)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "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",
@@ -47,7 +47,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
@@ -116,23 +117,23 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^4.0.71",
-    "@ai-sdk/mistral": "^4.0.56",
-    "@ai-sdk/openai": "^4.0.83",
-    "@ai-sdk/openai-compatible": "^3.0.62",
-    "@ai-sdk/provider": "^4.0.21",
-    "@testcontainers/postgresql": "^12.2.0",
-    "@types/node": "^26.6.4",
+    "@ai-sdk/anthropic": "^4.0.79",
+    "@ai-sdk/mistral": "^4.0.63",
+    "@ai-sdk/openai": "^4.0.93",
+    "@ai-sdk/openai-compatible": "^3.0.68",
+    "@ai-sdk/provider": "^4.0.27",
+    "@testcontainers/postgresql": "^12.2.1",
+    "@types/node": "^26.6.5",
     "@types/pg": "^8.23.1",
-    "ai": "^7.0.127",
-    "drizzle-orm": "^0.45.3",
+    "ai": "^7.0.139",
+    "drizzle-orm": "^0.45.4",
     "pg": "^8.23.1",
-    "pg-boss": "^12.35.1",
-    "testcontainers": "^12.2.0",
-    "tsdown": "^0.23.0",
+    "pg-boss": "^12.37.1",
+    "testcontainers": "^12.2.1",
+    "tsdown": "^0.23.1",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3",
-    "zod": "^4.6.5"
+    "vitest": "^5.0.4",
+    "zod": "^4.6.7"
   },
   "scripts": {
     "build": "tsdown",

package/skills/add-a-decision/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: add-a-decision
+description: Add an octaflow decision step — a decider (a model, a rules function, your own) answers fixed questions with fixed options and a confidence; a confident answer is applied on its own as an `autopilot` ledger entry, an unsure one waits for a person in the decision card, and every applied decision can be reverted. Use to classify, route, tag, prioritise or score a record; when the model writes content a person must always see, use add-an-ai-proposal-workflow.
+---
+
+# Add a decision
+
+> 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/@octabits-io/<name>/README.md`.
+
+A decision asks questions whose answers you can list — *which team*, *how urgent* — and gets
+one option per question with a confidence. The step guarantees the shape: an answer outside the
+options fails the step without a retry and never reaches a dependent. Below a threshold a
+question goes to a person; above it the answer stands, and the ledger says that nobody looked.
+
+```
+decide ── review (only when a question is below the threshold) ── outcome ── apply
+```
+
+Shown end to end in `apps/starter/src/server/triage.ts` (Next.js, Drizzle, pg-boss) with its
+page in `apps/starter/src/components/triage-panel.tsx`. The engine's own example is
+`packages/octaflow/examples/17-decisions.ts`.
+
+**Which pattern?**
+
+| The model… | Pattern |
+|---|---|
+| chooses among options you can list, and a confident choice may stand | a decision (this skill) |
+| writes content — a text, field values, new rows — a person always reviews | `add-an-ai-proposal-workflow` (beside this skill) |
+
+An effect a person must always see first is a decision with `threshold: 1`. An effect that
+cannot be undone (a payment, a message to a third party) never runs on autopilot: keep the
+threshold at 1 and record the reversibility as `irreversible`.
+
+## Step 1 — the three steps
+
+```ts
+import { z } from 'zod';
+import { defineDecisionStep, defineDecisionReviewStep, defineDecisionOutcomeStep, functionDecider } from 'octaflow';
+import { createModelDecider } from 'octaflow/ai';
+
+const input = z.object({ dealId: z.string() });
+
+const route = defineDecisionStep({
+  type: 'deal-routing.decide',
+  workflowInputSchema: input,
+  questions: {                                   // inline, so the options stay literal types
+    team: ['sales', 'solutions', 'partners'],
+    urgency: ['low', 'normal', 'high'],
+  },
+  input: async (ctx) => readRoutingInput(ctx.context.host, ctx.workflowInput.dealId),
+  instructions: 'team: who should own this deal. urgency: how soon they should act.',
+  decider: createModelDecider<Host>(),           // ctx.context.model, behind your disclosure gate
+  threshold: 0.8,                                // or per question: { team: 0.8 } — urgency then never asks
+});
+const review = defineDecisionReviewStep({ type: 'deal-routing.review', decision: { route } });
+const outcome = defineDecisionOutcomeStep({ type: 'deal-routing.outcome', decision: { route }, review: { review } });
+```
+
+- **`input` is data, not a prompt** — the smallest data that answers the questions. Leave out
+  names and contact details; the decision input leaves the process.
+- **The decider.** `createModelDecider()` asks `ctx.context.model` (or the `model` you pass) with
+  structured output; wrap that model in the disclosure gate (`@octabits-io/disclosure/ai-sdk`).
+  Rules you can state outright are `functionDecider('rules', fn)`: confidence 1, `calibrated:
+  true`, never asks. Any object with `id`, `calibrated` and `decide()` is a `Decider`.
+- **The threshold is a policy, not a probability.** A language model's stated confidence is
+  `calibrated: false`, and the step records that on every output. Start high; lower it only when
+  reviewers rarely change the decider's answer.
+- **The review** suspends only when `output.review` is non-empty, and has no deadline by default.
+  `timeoutMs` with `onTimeout: 'accept'` keeps the decider's answers when it expires — that is
+  autopilot by another name, so prefer the default.
+- **The outcome** merges both with `resolveDecision`: a person's choice wins where they made one.
+  Its `decidedBy` says, per question, `'decider'` or `'person'`.
+
+## Step 2 — the apply step
+
+One more step after the outcome writes the settled choices. It is the host's code, because only
+the host knows what an answer means in its schema:
+
+```ts
+import { buildWorkflow, defineStep, nonRetryableError } from 'octaflow';
+
+const apply = defineStep<Input, { entryId: number | null }, Ctx, { route: typeof route; outcome: typeof outcome }>({
+  type: 'deal-routing.apply',
+  workflowInputSchema: input,
+  outputSchema: z.object({ entryId: z.number().nullable() }),
+  dependencies: { route, outcome },
+  handler: async (ctx) => {
+    const applied = await applyRouting(ctx.context.host, ctx.workflowId, ctx.deps.route, ctx.deps.outcome);
+    if (!applied.ok) throw nonRetryableError(applied.error.message);   // a refusal is not fixed by a retry
+    return applied.value;
+  },
+});
+export const routingWorkflow = buildWorkflow({ type: 'deal-routing', inputSchema: input, steps: { route, review, outcome, apply } });
+```
+
+Inside `applyRouting`, in **one transaction**:
+
+1. **Find the run's ledger entry first** — ``ledger.findByWorkflow(`flow:${workflowId}`)``, the
+   same id the disclosure log keeps as its correlation id — and write nothing if it is there.
+   Steps run at least once; the entry is the idempotency marker.
+2. **Keep what each write replaced** — `proposeFields({ target, current, proposed: outcome.choices })`
+   from `@octabits-io/proposal` — so a revert can put it back.
+3. **Record the mode that follows the person**: a reviewer, or any `decidedBy` of `'person'`, is
+   `mode: 'reviewed'` with `principal.onBehalfOf` the reviewer; nobody is `mode: 'autopilot'`
+   with `principal.authorizationId` naming the policy (`threshold:0.8`). Put the decider, its
+   `calibrated` claim, the threshold and each answer's choice and confidence in `decision`.
+4. Emit the change on the outbox (`add-an-event-type`).
+
+After the transaction commits, anchor the ledger's head (`anchor-the-ledger` in
+`@octabits-io/agent-ledger`) — never inside it.
+
+## Step 3 — the engine, start, decide, revert
+
+Register the workflow in the engine's registry exactly as in `add-an-ai-proposal-workflow`
+(Step 3: `createStepHandlerRegistry`, `createAiWorkflowHooks`, `createWorkflowEngine` over the
+`octaflow/postgres` store and the `octaflow/pg-boss` dispatcher). Then three routes:
+
+- **start** checks the record exists in the caller's scope, then
+  ``engine.start(routingWorkflow, { dealId }, { entityRef: `deal:${dealId}`, idempotencyKey })``
+  and answers `202`. The decider runs in the step worker, never in the request.
+- **decide** validates only `answers` from the body against the options (a Zod enum per
+  question), and calls `engine.resumeStep(workflowId, 'review', { answers, reviewer })` with the
+  reviewer from the session. Never take the reviewer from the request body. Refuse a run whose
+  `review` step is not `waiting` — `resumeStep` itself ignores it silently.
+- **revert** reads the entry with `findByWorkflow`, refuses one already reverted, inverts its
+  operations (`invertOperations`), refuses on drift (`detectDrift` — a person's later change
+  stays theirs), writes the inverse and `ledger.recordRevert({ reverts: entry.id, principal })` in
+  one transaction, then anchors.
+
+**Deleting the record.** Runs name it by `entityRef`, not a foreign key, and their steps hold
+what the decider saw. Before the delete, `engine.purgeWorkflows({ entityRef })` cancels and
+deletes them; it refuses with `workflow_step_running` while a step executes — answer `409`. The
+ledger entries stay.
+
+## Step 4 — the sweep and the reminder
+
+A step whose worker died stays `running`. Schedule `engine.recoverStuckWorkflows()` — every few
+minutes, per scope with a run in flight (a pg-boss schedule, or your cron). It retries the step
+while it has attempts (`onStuckStep: 'retry'`, the default) and fails it after, so the run
+reaches `failed` and the page can say so. Keep handlers safe to run twice.
+
+An unsure answer is never applied without a person, so a review may wait forever. The package
+sends no reminder; read the waiting runs and send one from the same sweep, through your mail or
+feed:
+
+```ts
+const runs = await engine.listWorkflows({ type: 'deal-routing', status: 'running' });
+const waiting = runs.ok ? runs.value.flatMap((run) => run.steps.filter((s) => s.key === 'review' && s.status === 'waiting').map((s) => ({ run, since: s.startedAt }))) : [];
+```
+
+## Step 5 — the card
+
+Hand the card the decide step's output with its questions — `{ ...output, questions:
+route.questions, threshold: 0.8 }` fits `DecisionReviewInput` as it is — and post what its
+confirm hands you to the decide route:
+
+- React: `DecisionReviewCard` from `@octabits-io/agent-ui/react/plain`, or `useDecisionReview`
+  from `@octabits-io/agent-ui/react` under your own design system;
+- Vue: `useDecisionReview` from `@octabits-io/agent-ui/vue`, or
+  `@octabits-io/agent-ui/nuxt-ui/DecisionReviewCard.vue` on Nuxt UI;
+- shadcn: `npx shadcn add` the `decision-review-card` registry item;
+- headless: `createDecisionReviewStore` from `@octabits-io/agent-ui`.
+
+The page shows who settled each value (autopilot with decider and confidence, or the person),
+how long a review has waited, and Revert. It re-reads on events; it never polls.
+
+## Prove it works
+
+In your app, a test on an in-memory engine — `createWorkflowEngine` over
+`createInMemoryWorkflowStore()` and a dispatcher that runs each step inline, as
+`packages/octaflow/src/core/decision.test.ts` builds it, with a `functionDecider` or a scripted
+model — that asserts:
+
+- a confident run applies itself: the columns are written and one `autopilot` entry records the
+  decider, `calibrated`, each choice and confidence;
+- an unsure run waits on `review` and changes nothing; the decide route records the session's
+  user even when the body names another reviewer; a second decide is refused;
+- revert restores, a second revert is refused, a revert after a manual change reports drift;
+- another scope sees no runs and no rows.
+
+```bash
+pnpm --filter octaflow test:unit
+```
+
+Green: `src/core/decision.test.ts` passes, including "waits for a person below the threshold, and
+their choice wins" and "fails the step, without retrying, when the decider answers outside the
+options".
+
+## Checklist
+
+- [ ] Questions inline with literal options; `input` is the smallest data that answers them
+- [ ] The decider's model goes through the disclosure gate; the threshold is a stated policy
+- [ ] The apply step finds the run's ledger entry before it writes, in one transaction
+- [ ] `mode` is `autopilot` only when nobody decided; `reviewed` names the reviewer
+- [ ] The ledger head is anchored after each apply and revert commits
+- [ ] The decide route takes the reviewer from the session and refuses a review not waiting
+- [ ] `recoverStuckWorkflows` runs on a schedule; records are purged with `purgeWorkflows` before delete
+- [ ] The card shows confidence, who decided, and Revert

package/skills/add-an-ai-proposal-workflow/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: add-an-ai-proposal-workflow
+description: Add an octaflow AI workflow whose last step emits a reviewable Proposal, plus the host's apply and revert with a drift guard and a ledger row — the "agents propose, humans decide" loop. Use when a model should suggest changes to records that already exist and a person must approve them before they are written.
+---
+
+# Add an AI workflow that ends in a proposal
+
+> 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/@octabits-io/<name>/README.md`.
+
+A run is a DAG of typed steps (`octaflow/ai`). Its final step turns what the model produced
+into a `Proposal` (`@octabits-io/proposal`): operations against rows the host already has,
+each saying what it replaces, with a drift guard. The host stores the proposal as the run's
+output, renders it for review, and applies the reviewer's decision through one mapping from
+operations to writes, recording a ledger row (`@octabits-io/agent-ledger`) that revert derives
+its inverse from. Nothing in the packages writes to your tables.
+
+Reference implementations:
+- Producer: `apps/demo-server/src/ai/workflows.ts` (the `contact-brief` DAG, the `propose` step)
+- Engine wiring: `apps/demo-server/src/ai/engine.ts`
+- Apply/revert on Drizzle: `apps/demo-server/src/ai/proposals.ts`; on Prisma: `apps/starter-next/src/lib/proposals.ts`
+- Routes: `apps/demo-server/src/routes/ai.ts`; tests: `apps/demo-server/src/ai/ai.test.ts`
+
+## When to use
+
+- The model's output is a change to existing records (fields, new child rows, deletions, an order) — not free text for a chat bubble.
+- The change must be reviewable, partially acceptable, editable before apply, refusable if the record moved meanwhile, and undoable afterwards.
+
+## Step 1: the DAG
+
+`defineAiStep` is octaflow's `defineStep` with the handler context fixed to
+`AiContext<THost>`: handlers get `ctx.context.model` (already instrumented — usage and cost
+are captured for you) and `ctx.context.host` (whatever your hooks' `resolveHost` returns).
+Independent steps run in parallel; the engine derives that from `dependencies`.
+
+```ts
+import { z } from 'zod';
+import { generateText } from 'ai';
+import { defineAiStep, buildAiWorkflow, type AiContext } from 'octaflow/ai';
+
+const SCHEMA_INPUT = z.object({ orderId: z.string() });
+type Input = z.infer<typeof SCHEMA_INPUT>;
+
+const fetch = defineAiStep<Input, { title: string; notes: string | null }, Host>({
+  type: 'order-brief.fetch',
+  workflowInputSchema: SCHEMA_INPUT,
+  outputSchema: z.object({ title: z.string(), notes: z.string().nullable() }),
+  handler: async (ctx) => ctx.context.host.orders.get(ctx.workflowInput.orderId),
+});
+
+// THost is explicit on dependent steps: inference cannot recover it from `dependencies`.
+const summarize = defineAiStep<Input, { summary: string }, Host, { fetch: typeof fetch }>({
+  type: 'order-brief.summarize',
+  workflowInputSchema: SCHEMA_INPUT,
+  outputSchema: z.object({ summary: z.string() }),
+  dependencies: { fetch },
+  retry: { maxAttempts: 3 },
+  handler: async (ctx) => {
+    const { text } = await generateText({ model: ctx.context.model, prompt: `Summarize: ${ctx.deps.fetch.title}` });
+    return { summary: text };
+  },
+});
+```
+
+## Step 2: the `propose` step — the proposal IS its output schema
+
+Re-read the row **now** so `current` is a fact about the run, not about the page load; carry
+`guard: driftDigest(current)`; say what the model left empty in `skipped`; name the agent in
+`provenance`.
+
+```ts
+import { buildProposal, driftDigest, entityAnchor, proposalSchema, proposeCreate, proposeFields, SKIP_REASONS } from '@octabits-io/proposal';
+import type { Proposal, SkippedItem } from '@octabits-io/proposal';
+
+// flow constrains step outputs to Record<string, unknown>; an interface has no index signature.
+type ProposalOutput = { [K in keyof Proposal]: Proposal[K] };
+export const AGENT = { kind: 'agent', id: 'ai:order-brief', label: 'Order brief' } as const;
+
+const propose = defineAiStep<Input, ProposalOutput, Host, { fetch: typeof fetch; summarize: typeof summarize }>({
+  type: 'order-brief.propose',
+  workflowInputSchema: SCHEMA_INPUT,
+  outputSchema: proposalSchema as unknown as z.ZodType<ProposalOutput>,
+  dependencies: { fetch, summarize },
+  handler: async (ctx) => {
+    const order = await ctx.context.host.orders.get(ctx.workflowInput.orderId);   // re-read at emit time
+    const target = entityAnchor('order', order.id, order.title);
+    const summary = ctx.deps.summarize.summary.trim();
+    const skipped: SkippedItem[] = [];
+    if (!summary) skipped.push({ target, path: ['notes'], reason: SKIP_REASONS.noOutput });
+    return buildProposal({
+      scope: `order:${order.id}`,
+      workflowId: ctx.workflowId,
+      workflowType: 'order-brief',
+      operations: [
+        ...proposeFields({
+          target,
+          current: { notes: order.notes },
+          proposed: { notes: summary || undefined },          // dropped if it reproduces `current` verbatim
+          guard: { notes: driftDigest(order.notes) },
+          display: { notes: { labelKey: 'ai.order.fields.notes', control: 'multiline', maxLength: 2000, order: 1 } },
+        }),
+        proposeCreate({ collection: 'tasks', ref: 'followup', value: 'Call back next week', display: { labelKey: 'ai.order.fields.task', control: 'multiline', order: 2 } }),
+      ],
+      skipped,
+      provenance: { model: 'your-model-id', keySource: 'platform', generatedAt: new Date().toISOString(), principal: AGENT },
+    });
+  },
+});
+
+export const orderBriefWorkflow = buildAiWorkflow<Input, Host>({ type: 'order-brief', inputSchema: SCHEMA_INPUT, steps: { fetch, summarize, propose } });
+```
+
+`display` is what a generic review surface renders: `labelKey` (the host translates),
+`control` (`text` | `multiline` | `richtext` | …), `maxLength`, `hint`, `order`.
+
+## Step 3: the engine
+
+`createAiWorkflowHooks` binds a model, a host and a key source per run; the refusal-aware
+wrapper, per-model capability switches, the cost estimator and a quota policy all live in
+`octaflow/ai` (`createRefusalAwareModel`, `createCostEstimator`, `DEFAULT_MODEL_PRICING`,
+`AiQuotaPolicy`); `octaflow/ai/providers` turns a key into a model, `octaflow/ai/registry`
+carries residency metadata. Register every workflow in one registry and build the engine:
+
+```ts
+import { createStepHandlerRegistry, createWorkflowEngine } from 'octaflow';
+import { createAiWorkflowHooks, createCostEstimator, DEFAULT_MODEL_PRICING } from 'octaflow/ai';
+
+const hooks = createAiWorkflowHooks<Host>({
+  modelResolver: { resolveModel: () => model, resolveHost: () => host, resolveKeySource: () => 'platform' },
+  usageRecorder, quotaPolicy, costEstimator: createCostEstimator({ pricing: DEFAULT_MODEL_PRICING }),
+});
+const registry = createStepHandlerRegistry<AiContext<Host>>();
+orderBriefWorkflow.register(registry);
+const engine = createWorkflowEngine<AiContext<Host>>({ store, dispatcher, registry, partitionKey, logger, hooks });
+```
+
+## Step 4: apply and revert — the host's half, once
+
+The same recipe on both stacks; only the write lines differ. Copy
+`apps/demo-server/src/ai/proposals.ts` (Drizzle) or `apps/starter-next/src/lib/proposals.ts`
+(Prisma) and replace the `applyOperation` switch.
+
+```ts
+import { detectDrift, invertOperations, proposalSchema, resolveDecision, reversibilityOf, validateProposal } from '@octabits-io/proposal';
+import type { ProposalDecision, ProposedOperation, ResolvedOperation } from '@octabits-io/proposal';
+// ledger: createDrizzleAgentLedgerStore (…/agent-ledger/drizzle) or createPostgresAgentLedgerStore ({ db: pool }, …/agent-ledger/postgres)
+
+async function apply(runId: number, decision: ProposalDecision, appliedBy: string | null) {
+  const proposal = proposalSchema.safeParse(run.output.propose);            // 1. the stored proposal
+  const standing = await ledger.findByWorkflow(runId);                       // 2. refuse while one stands
+  if (standing.value && standing.value.revertedAt === null) return err({ key: 'proposal_already_applied', … });
+  const issues = validateProposal(proposal.data);                            // 3. structural validity
+  const resolved = resolveDecision(proposal.data, decision);                 // 4. what the reviewer kept, with edits
+  const drifted = detectDrift(resolved, (op) => (isNotesUpdate(op) ? liveRow.notes : undefined)); // 5. 409, never overwrite
+  const created: Record<string, string> = {};
+  for (const op of resolved) { /* 6. ONE switch: op.target.type / op.collection / op.path → your write */ }
+  //   Drizzle: await db.update(orders).set({ notes: op.proposed }).where(eq(orders.id, id))
+  //   Prisma:  await prisma.order.update({ where: { id }, data: { notes: op.proposed } })
+  await ledger.record({ principal: { ...AGENT, onBehalfOf: appliedBy ?? undefined }, mode: 'reviewed', scope: proposal.data.scope,
+    workflowId: runId, decision, operations: resolved, created, reversibility: reversibilityOf(resolved), appliedAt: new Date().toISOString() });
+}
+
+async function revert(runId: number, revertedBy: string) {
+  const standing = await ledger.findByWorkflow(runId);                       // must stand: revertedAt === null
+  const plan = invertOperations(standing.value.operations as ResolvedOperation[], standing.value.created);
+  for (const op of plan.operations) { /* the same switch */ }
+  await ledger.markReverted(standing.value.id, { at: new Date().toISOString(), by: revertedBy });
+  return { missing: plan.missing, irreversible: plan.irreversible, compensable: plan.compensable };
+}
+```
+
+Whether a run is applied is never on the proposal: the host joins its ledger to the run
+(`findByWorkflows` for lists), and "standing" means `revertedAt IS NULL`. A production host
+wraps the writes and the ledger row in one transaction.
+
+## Step 5: routes
+
+Generic read/control routes (list, active, get, snapshot, cancel, resume) come from
+`@octabits-io/server`: `createFlowWorkflowHandler({ engine, extendWorkflow?, errorOverrides? })`
+in `./fetch/octaflow` is the six routes as one fetch handler, and `createFlowWorkflowCore` in
+`./octaflow` is the same logic without HTTP for a host that binds its own framework
+(`apps/demo-server/src/hono/flow.ts` binds it to Hono). Both project `appliedAt`/`revertedAt`
+from the ledger via `extendWorkflow`. Three routes stay app-side on any stack: the trigger (`POST …/workflows`
+with your input vocabulary), `POST …/workflows/:id/apply` (body: `proposalDecisionSchema`)
+and `POST …/workflows/:id/revert`. On Next these are route handlers
+(`apps/starter-next/src/app/api/runs/[id]/apply/route.ts`). Map keys to statuses:
+`proposal_drift` and `proposal_already_*` → 409, `proposal_invalid` → 400, `*_not_found` → 404.
+
+## Key rules
+
+- `current` is read in the `propose` step, never earlier — the model steps took time.
+- The proposal is the step's output schema; a step whose internals are a tool loop emits the same shape.
+- One `applyOperation` switch is the only place that knows which table an anchor names. Revert goes through it too.
+- Refuse a second apply while one stands; refuse on drift; refuse an empty decision. All three are 4xx, none is silent.
+- The ledger stores the resolved operations as written and the ids assigned to creates — revert never re-reads the entity to guess "before".
+
+## Proof
+
+```bash
+cd apps/demo-server && pnpm test     # `proposal review loop (apply / revert)`: partial decision with an edit,
+                                     # drift → 409, revert restores and clears appliedAt, second apply refused, empty decision rejected
+pnpm e2e                             # the loop in a browser against every host
+```
+
+Write the same five tests for your workflow (`apps/demo-server/src/ai/ai.test.ts` is the
+template, fully in-memory on octaflow's memory store). Green: all five pass and the e2e loop
+shows the edited value landing and the rejected operation not being created.
+
+## Checklist
+
+- [ ] Steps defined with `defineAiStep`, `THost` explicit on dependent steps, `retry` on model steps
+- [ ] `propose` re-reads the row, sets `guard: driftDigest(current)`, fills `skipped` and `provenance`, output schema is `proposalSchema`
+- [ ] Workflow registered in the engine's registry; hooks bind model, host, key source, usage recorder, cost estimator
+- [ ] Apply: parse → standing check → validate → resolve → drift → one write switch → ledger row
+- [ ] Revert: `invertOperations` over the ledger row → the same switch → `markReverted`
+- [ ] Routes: generic ones from `server/fetch/octaflow` (or `server/octaflow` bound to your framework), trigger/apply/revert app-side, keys mapped to 4xx
+- [ ] Five loop tests green; an e2e host drives it
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `packages/octaflow/src/ai/define-ai-step.ts` | `defineAiStep`, `buildAiWorkflow` |
+| `packages/octaflow/src/ai/hooks.ts`, `refusal.ts`, `capabilities.ts`, `cost.ts`, `quota.ts` | model resolution, refusal wrapper, capability switches, pricing, quota |
+| `packages/proposal/src/build.ts`, `apply.ts`, `schema.ts` | `buildProposal`/`proposeFields`/`proposeCreate`/`driftDigest`; `validateProposal`/`resolveDecision`/`detectDrift`/`invertOperations`/`reversibilityOf`; `proposalSchema`, `proposalDecisionSchema` |
+| `packages/agent-ledger/src/index.ts` | `AgentLedgerStore` — `record`, `findByWorkflow(s)`, `markReverted` |
+| `packages/server/src/octaflow.ts`, `src/fetch/octaflow.ts` | `createFlowWorkflowCore`; `createFlowWorkflowHandler` |