@warlock.js/ai 4.1.1

package/skills/pick-ai-provider/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: pick-ai-provider
+description: 'Choose an AI provider adapter — @warlock.js/ai-openai (shipped, also handles OpenRouter / Azure via baseURL), @warlock.js/ai-anthropic, @warlock.js/ai-bedrock, @warlock.js/ai-google, @warlock.js/ai-ollama. Triggers: `OpenAISDK`, `SDKAdapterContract`, `ModelContract`, `sdk.model`, `sdk.embedder`, `capabilities.vision`, `capabilities.structuredOutput`, `pricing`, `baseURL`, `provider: "openrouter"`; ''pick a provider'', ''openai vs openrouter'', ''does this model support vision'', ''configure pricing''; typical import `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: agent factory — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs raw `openai`, `@anthropic-ai/sdk`, `@aws-sdk/client-bedrock-runtime`.'
+---
+
+# Pick an AI provider adapter
+
+`@warlock.js/ai` is provider-agnostic. Concrete adapters live in sibling packages and follow the same `SDKAdapterContract`. Pick by which provider(s) your app talks to and which capabilities the model needs.
+
+## Available adapters
+
+| Package | Status | Notes |
+| --- | --- | --- |
+| `@warlock.js/ai-openai` | ✅ Shipped | OpenAI + any OpenAI-compatible gateway (OpenRouter, Together.ai, etc.) |
+| `@warlock.js/ai-anthropic` | ✅ Shipped | Native Claude API (Opus / Sonnet / Haiku) |
+| `@warlock.js/ai-bedrock` | ✅ Shipped | AWS Bedrock — Converse API + Titan embeddings |
+| `@warlock.js/ai-google` | ✅ Shipped | Gemini direct via `@google/genai`, native batch embeddings |
+| `@warlock.js/ai-ollama` | ✅ Shipped | Local models via the official `ollama` client |
+
+All five first-party adapters share the same `SDKAdapterContract`, so switching providers is a one-line change at the model construction site. `ai-openrouter` is intentionally deferred — use `ai-openai` with a `baseURL` pointed at OpenRouter.
+
+## Decision tree
+
+- **Default first choice:** `@warlock.js/ai-openai` direct to OpenAI. Best support, predictable behavior, native structured-output, native vision on `gpt-4o*`, embeddings, streaming.
+- **Need many models / cost arbitrage:** `@warlock.js/ai-openai` against OpenRouter. Same code, different `baseURL` + `provider: "openrouter"` on the SDK.
+- **Need native Claude features:** `@warlock.js/ai-anthropic` — Opus / Sonnet / Haiku via the native Messages API.
+- **Need local / self-hosted models:** `@warlock.js/ai-ollama`, or a local OpenAI-compatible gateway via `ai-openai`.
+- **Need AWS Bedrock pricing / compliance:** `@warlock.js/ai-bedrock` — Converse API + Titan embeddings.
+- **Need Gemini:** `@warlock.js/ai-google` — Gemini direct via `@google/genai`.
+
+## The adapter contract
+
+```ts
+interface SDKAdapterContract {
+  model(config): ModelContract;            // chat completions / tool calls / structured output
+  count(text, model?): Promise<number>;    // token counting
+  embedder?(config): EmbedderContract;     // optional — not every provider supports embeddings
+}
+```
+
+Adapters are classes — `new OpenAISDK({ apiKey })`, `new AnthropicSDK({ apiKey })`. They expose:
+
+- `model({ name, ...options })` — returns a `ModelContract`. The provider label lives on the returned `ModelContract.provider` (`"openai"`, `"openrouter"`, …), not on the SDK.
+- `count(text, model?)` — provider-appropriate token count.
+- `embedder({ name })` — text-to-vector. Optional; check `typeof sdk.embedder === "function"` before calling.
+
+The `ModelContract.capabilities` field declares what the model supports — two flags today, both optional (absent = treat as `false`):
+
+```ts
+type ModelCapabilities = {
+  structuredOutput?: boolean;   // native response_format: json_schema support?
+  vision?: boolean;             // can accept image attachments?
+};
+```
+
+The framework reads `capabilities` to fail loud upfront — e.g. passing `attachments: [...]` to a non-vision model throws at the boundary instead of failing mid-trip.
+
+## OpenAI adapter — usage
+
+```ts
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+// Direct OpenAI
+const openai = new OpenAISDK({
+  apiKey: process.env.OPENAI_API_KEY!,
+  pricing: {
+    "gpt-4o-mini": { input: 0.15, output: 0.6, cachedInput: 0.075 },
+    "gpt-4o":      { input: 5.0,  output: 15.0 },
+  },
+});
+
+const agent = ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) });
+```
+
+### Via OpenRouter (cost arbitrage, many providers)
+
+```ts
+const openrouter = new OpenAISDK({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  baseURL: "https://openrouter.ai/api/v1",
+  provider: "openrouter",   // labels reports correctly
+});
+
+const agent = ai.agent({ model: openrouter.model({ name: "anthropic/claude-3.5-sonnet" }) });
+```
+
+Same `OpenAISDK` class, different `baseURL`. Reports label the provider via the `provider` field for downstream metrics.
+
+### Per-model overrides
+
+```ts
+const openai = new OpenAISDK({ apiKey });
+
+// Override capabilities for a custom or fine-tuned model
+const customModel = openai.model({
+  name: "my-org/custom-gpt-4-finetuned",
+  vision: true,                    // override capabilities.vision
+  structuredOutput: true,
+  pricing: { input: 1.0, output: 3.0 },   // per-model pricing (wins over SDK registry)
+});
+```
+
+## Pricing — per-channel cost breakdown
+
+Configure `pricing` on the model (or via the SDK registry) and every report carries `Usage.cost`:
+
+```ts
+const openai = new OpenAISDK({
+  apiKey,
+  pricing: { "gpt-4o-mini": { input: 0.15, output: 0.6, cachedInput: 0.075 } },
+});
+
+const { usage } = await ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) }).execute("hi");
+
+usage.cost;
+// { input: 0.0000045, output: 0.000192, cachedInput: 0.000009 }  — USD breakdown
+```
+
+Shape mirrors `ModelPricing` — `{ input, output, cachedInput?, cachedOutput? }`. Per-model `pricing` wins over the SDK-level registry. `undefined` when no pricing configured — honest absence over false zero.
+
+## Embeddings
+
+OpenAI ships the first embedder:
+
+```ts
+const embedder = openai.embedder({ name: "text-embedding-3-small" });
+const { vector } = await embedder.embed("Hello, world.");
+```
+
+See [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md).
+
+## Multi-provider apps
+
+Pattern: one SDK instance per provider, mix at the call site:
+
+```ts
+const openai     = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+const openrouter = new OpenAISDK({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  baseURL: "https://openrouter.ai/api/v1",
+  provider: "openrouter",
+});
+
+const fastAgent  = ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) });
+const claudeAgent = ai.agent({ model: openrouter.model({ name: "anthropic/claude-3.5-sonnet" }) });
+```
+
+Reports label per-agent provider correctly. Pricing applies per SDK instance.
+
+## When the adapter changes
+
+If you switch providers mid-project (e.g. OpenAI → Anthropic):
+
+1. The agent factory call signature stays the same — `ai.agent({ model: <newSdk>.model({...}) })`.
+2. Capabilities matter — if the new model doesn't support `structuredOutput` natively, fall back to the soft "respond in JSON only" instruction (framework handles it).
+3. Errors stay typed — `ProviderAuthError`, `ContextLengthExceededError`, etc. are adapter-agnostic.
+4. Pricing matrix needs updating per the new provider's rates.
+
+## See also
+
+- [`@warlock.js/ai-openai/setup-openai/SKILL.md`](@warlock.js/ai-openai/setup-openai/SKILL.md) — full OpenAI adapter docs
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — model passed into `ai.agent({...})`
+- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — embedder primitive on the SDK
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — adapter error categorization

package/skills/run-ai-agent/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: run-ai-agent
+description: 'Build agents with ai.agent({...}) — the single-LLM-turn primitive. Covers execute / stream, attachments, structured output, placeholders, events. Triggers: `ai.agent`, `agent.execute`, `agent.stream`, `AgentResult`, `AgentReport`, `streamingToolGuard`, `attachments`, `repair`, `maxTrips`, `sessionId`; ''run an agent'', ''stream an agent response'', ''structured output schema'', ''pass image to agent'', ''cancel an agent run''; typical import `import { ai } from "@warlock.js/ai"`. Skip: tool definition — `@warlock.js/ai/define-ai-tool/SKILL.md`; workflows — `@warlock.js/ai/run-ai-workflow/SKILL.md`; competing libs `langchain`, `ai` (Vercel), raw `openai`.'
+---
+
+# `ai.agent()` — single-turn primitive
+
+The lowest rung of the 4-primitive ladder. One LLM call, optional tool loop, optional structured output. Stateless across calls.
+
+## Factory shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+ai.agent({
+  name?: string,                              // optional — anonymous gets a fingerprint
+  model: openai.model({ name: "gpt-4o-mini" }),
+  systemPrompt?: string | SystemPromptContract,
+  tools?: ToolContract<any, any>[],
+  placeholders?: Record<string, unknown>,
+  maxTrips?: number,                           // default 10
+  modelOptions?: ModelCallOptions,
+  output?: StandardSchemaV1<T>,                // default structured-output schema
+  middleware?: AgentMiddleware[],
+  streamingToolGuard?: StreamingToolGuardConfig, // opt-in tool-call recovery from text leaks
+  on?: AgentEventHandlers,
+  version?: string,                            // mirrored onto reports for trip archives
+});
+```
+
+The factory returns an `AgentContract<TOutput>`. Every execution spawns a fresh internal `Execution` — the factory holds no per-call state.
+
+## Anonymous agents
+
+`name` is optional. Anonymous agents receive a deterministic fingerprint:
+
+```
+anon_<provider>_<model>[_<tool1>+<tool2>+...]
+```
+
+Same config across process restarts → same synthetic name. Keeps workflow signature drift detection honest when you compose anonymous agents into a workflow.
+
+## Execute surface
+
+```ts
+agent.execute(input: string, options?: AgentExecuteOptions): Promise<AgentResult<T>>;
+agent.stream(input: string, options?: AgentExecuteOptions): StreamContract<AgentResult<T>>;
+```
+
+`AgentExecuteOptions` — every field optional:
+
+```ts
+{
+  history?: Message[];
+  attachments?: Attachment[];                    // images today; PDFs later
+  placeholders?: Record<string, unknown>;
+  output?: StandardSchemaV1<T>;                  // typed structured output → result.data
+  responseSchema?: Record<string, unknown>;      // hand-crafted JSON Schema escape hatch
+  systemPrompt?: SystemPromptContract;           // per-call override
+  repair?: { maxAttempts?: number };             // opt-in re-ask on validation failure
+  signal?: AbortSignal;                          // cancellation
+  sessionId?: string;                            // stitch many runs into one session
+  streamingToolGuard?: StreamingToolGuardConfig;
+  on?: AgentEventHandlers;
+}
+```
+
+## `streamingToolGuard` — recover tool calls leaked as text
+
+Cheap and fast models occasionally emit a registered tool's structured input as **literal text in the content stream** instead of as a real `tool_call`. Without intervention, customers watch raw JSON build character-by-character.
+
+```ts
+ai.agent({
+  model: someFastModel,
+  tools: [suggestFollowupsTool, searchCatalogTool],
+  streamingToolGuard: {},  // empty object = on with defaults
+});
+```
+
+Recovery conditions: the buffered JSON must (a) parse cleanly, (b) carry a `name` or `tool` key resolving to a registered tool, AND (c) carry an `arguments` or `input` key whose value validates against that tool's input schema. Anything else flushes back as text — the guard never invents calls.
+
+**Off by default.** Set this explicitly on agents whose registered tools have been observed to leak.
+
+## `sessionId` — stitch many runs into one user session
+
+```ts
+const sessionId = "sess_user_42_2026-05-12";
+await agent.execute("what's my order?", { sessionId });
+await agent.execute("cancel it", { sessionId });   // 30 seconds later, same session
+```
+
+The framework stamps it onto every report node this run produces. Cost dashboards can group by `sessionId` without joining the report tree.
+
+## Result shape — `AgentResult<T>`
+
+```ts
+type AgentResult<T> = {
+  type: "agent";
+  data?: T;             // structured output when `output` schema was supplied
+  text?: string;        // raw final LLM text
+  report: AgentReport;  // trips, toolCalls, status, timing
+  usage: Usage;         // aggregated token usage + cost breakdown
+  error?: AIError;
+};
+
+type AgentReport = {
+  runId: string;
+  rootRunId: string;
+  name: string;
+  status: "completed" | "failed" | "cancelled";
+  startedAt: string;
+  endedAt: string;
+  duration: number;
+  model: { name: string; provider: string };
+  trips: LLMTrip[];
+  children: ToolCall[];   // tool dispatches — filter by `c.type === "tool"`
+};
+```
+
+Tool calls are NOT a separate `report.toolCalls` field — every tool dispatch is a child `BaseReport` node (`type: "tool"`) on `report.children`. Filter the tree to isolate them:
+
+```ts
+const toolCalls = report.children.filter((c) => c.type === "tool");
+const nestedAgents = report.children.filter((c) => c.type === "agent");
+```
+
+Canonical destructuring:
+
+```ts
+const { data, text, report, usage, error } = await agent.execute(input);
+
+if (error) {
+  logger.warn(error.code, { duration: report.duration, trips: report.trips.length });
+  return;
+}
+```
+
+## Pattern — structured output
+
+```ts
+import { v, type Infer } from "@warlock.js/seal";
+
+const summarySchema = v.object({
+  summary: v.string(),
+  keyPoints: v.array(v.string()).min(1),
+});
+
+const result = await myAgent.execute(input, { output: summarySchema });
+
+if (result.data) {
+  // typed as Infer<typeof summarySchema>
+}
+```
+
+Adapters with `capabilities.structuredOutput: true` forward the schema natively. Adapters without it get a soft "respond in JSON only" instruction. Client-side validation always runs.
+
+## Pattern — output baked into the agent
+
+```ts
+const titleAgent = ai.agent({
+  model: openai.model({ name: "gpt-4o-mini" }),
+  output: titleSchema, // typed end-to-end via AgentContract<Infer<typeof titleSchema>>
+  systemPrompt: "...",
+});
+
+const result = await titleAgent.execute(currentMessage, { history });
+//    ^? AgentResult<{ title?: string }>
+```
+
+Call-site `options.output` fully **replaces** `config.output` for that run — no merging.
+
+## Pattern — repair on validation failure
+
+```ts
+await myAgent.execute(input, {
+  output: schema,
+  repair: { maxAttempts: 1 }, // re-ask once on parse/validation failure
+});
+```
+
+Disabled by default. Each repair attempt counts against `maxTrips`.
+
+## Pattern — image attachments
+
+```ts
+await myAgent.execute("What's in this?", {
+  attachments: ["./photo.png", "https://cdn.example.com/cat.jpg"],
+});
+```
+
+Shorthand strings infer the image kind from extension. Tagged form for explicit control:
+
+```ts
+attachments: [
+  { type: "image", source: "./photo" },
+  { type: "image", source: { base64: "...", mediaType: "image/png" } },
+];
+```
+
+Model must declare `capabilities.vision`. OpenAI adapter auto-infers from name; override with `openai.model({ name, vision: true })`.
+
+## Pattern — streaming
+
+```ts
+const stream = myAgent.stream(input);
+
+for await (const event of stream) {
+  if (event.type === "agent.trip.streaming") {
+    process.stdout.write(event.delta);
+  }
+}
+
+const result = await stream.result;
+```
+
+Or use `.on({ "agent.trip.streaming": ..., "agent.completed": ..., "agent.error": ... })` alongside iteration.
+
+## Pattern — cancellation
+
+```ts
+const ctrl = new AbortController();
+const resultPromise = myAgent.execute(input, { signal: ctrl.signal });
+
+setTimeout(() => ctrl.abort("too slow"), 30_000);
+
+const { error, report } = await resultPromise;
+if (report.status === "cancelled") {
+  // error is an AgentCancelledError (code "AGENT_CANCELLED",
+  // category "cancelled") carrying `cancelledAt` + `reason`
+}
+```
+
+Between-trip abort is guaranteed. Mid-trip best-effort.
+
+## Events — dot-notation + 3-tier subscription
+
+- `agent.starting`, `agent.trip.started`, `agent.trip.streaming`, `agent.trip.completed`
+- `agent.tool.calling`, `agent.tool.called`, `agent.tool.failed`
+- `agent.completed`, `agent.error`
+
+Three subscription tiers — fire in order **factory → instance → per-call**:
+
+```ts
+ai.agent({ model, on: { "agent.starting": () => metrics.inc("agent.runs") } });
+
+const unsubscribe = myAgent.on("agent.error", ({ error }) => logger.error(error));
+
+await myAgent.execute("go", {
+  on: { "agent.trip.completed": ({ trip }) => console.log(trip.duration) },
+});
+```
+
+Every event payload carries `runId` and `rootRunId`. Same identity fields ride on stream events.
+
+## When NOT to use this primitive
+
+- Multi-step pipeline with a fixed shape → [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md)
+- Multi-agent routing with iteration → [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md)
+
+## See also
+
+- [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) — tool wiring + schema validation
+- [`@warlock.js/ai/write-system-prompt/SKILL.md`](@warlock.js/ai/write-system-prompt/SKILL.md) — persona / instruction builders
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `AIError` hierarchy

package/skills/run-ai-workflow/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: run-ai-workflow
+description: 'Build durable resumable pipelines with ai.workflow({...}) + ai.step({...}) — lifecycle (skip / before / run|agent|parallel / output / after / nextStep), retry, parallel groups, snapshot resume. Triggers: `ai.workflow`, `ai.step`, `wf.execute`, `wf.resume`, `WorkflowContext`, `WorkflowResult`, `StepSnapshot`, `nextStep`, `onFailure`, `WorkflowDriftError`; ''build a workflow'', ''define a step'', ''resume after crash'', ''parallel steps'', ''retry with backoff''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent — `@warlock.js/ai/run-ai-agent/SKILL.md`; supervisor — `@warlock.js/ai/run-supervisor/SKILL.md`; competing libs `temporal`, `inngest`, `bullmq`.'
+---
+
+# `ai.workflow()` — static, deterministic pipelines
+
+Second rung of the 4-primitive ladder. A named, ordered set of steps with a stable signature. Each step is exactly one of: an agent call (`agent`), a `run` function, or a parallel group (`parallel`). Compose another workflow in by wrapping it with `workflow.asTool()` and calling it from a `run` step. Durable (resumable via any `CacheDriver` from `@warlock.js/cache`), observable, cancellable.
+
+## When NOT to use a workflow
+
+- Unknown shape at author time → wait for `ai.planner()` (v3)
+- Quality-loop until goal met → [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md)
+- Multi-turn conversation with persistent session → orchestrator (v2)
+- Iterate a runtime list of items → `ai.batch()` utility wrapping a workflow
+
+## Minimal shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { MemoryCacheDriver } from "@warlock.js/cache";
+import { v } from "@warlock.js/seal";
+
+ai.config({ defaultStore: new MemoryCacheDriver() });
+
+type CatalogInput = { url: string };
+type CatalogOutput = { id: string };
+type CatalogState = { html?: string; catalogId?: string };
+
+const wf = ai.workflow<CatalogInput, CatalogOutput, CatalogState>({
+  name: "catalog-item",
+  output: {
+    extract: (ctx) => ({ id: ctx.state.catalogId ?? "" }),
+    schema: v.object({ id: v.string() }),
+  },
+  steps: [
+    ai.step<CatalogInput, CatalogState>({
+      name: "fetch",
+      run: async (ctx) => {
+        ctx.state.html = await fetch(ctx.input.url).then(r => r.text());
+      },
+    }),
+    ai.step<CatalogInput, CatalogState>({
+      name: "extract",
+      agent: extractorAgent,
+      input: (ctx) => ({ prompt: `Extract from: ${ctx.state.html}` }),
+      output: {
+        extract: (ctx) => ctx.agentResult?.data,
+        schema: itemSchema,
+      },
+      retry: { attempts: 3, backoff: "exponential" },
+    }),
+  ],
+});
+```
+
+## Generics
+
+```ts
+ai.workflow<TInput, TOutput, TState, TContext>(...)
+ai.step<TInput, TState, TContext>(...)
+```
+
+Order: Input/Output describe the public contract, State before Context because step bodies touch state more often. Defaults (`unknown`, `Record<string, unknown>`) let partial typing work.
+
+## Execute — two interchangeable shapes
+
+```ts
+// canonical — mirrors agent.execute
+const result = await wf.execute(
+  { url: "https://..." },
+  { runId: "catalog-123", signal: AbortSignal.timeout(60_000) },
+);
+
+// single-object — ergonomic alt
+const result = await wf.execute({
+  input: { url: "https://..." },
+  runId: "catalog-123",
+});
+```
+
+`WorkflowRunOptions` carries `runId`, `signal`, `on`, `context`, `sessionId`. `WorkflowDefinition.version` mirrors onto every produced report.
+
+## `execute()` never throws
+
+All failures funnel into `result.error`:
+
+- `StepFailedError` / `STEP_FAILED`
+- `RoutingError` / `WORKFLOW_INVALID_GOTO`
+- `WorkflowDriftError` / `WORKFLOW_DRIFT`
+- `WorkflowCancelledError` / `WORKFLOW_CANCELLED`
+- `MaxStepsExceededError` / `WORKFLOW_MAX_STEPS`
+
+See [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
+
+## Result shape
+
+```ts
+const { data, report, usage, error } = await wf.execute(input);
+```
+
+```ts
+type WorkflowResult<TOutput> = {
+  type: "workflow";
+  data?: TOutput;            // from workflow.output.extract
+  report: WorkflowReport;    // runId, signature, status, timings, per-step snapshots
+  usage: Usage;              // aggregated across all agent calls
+  error?: AIError;
+};
+```
+
+`report.steps[name]` holds a frozen `StepSnapshot` with `output`, `status`, `attempts`, `attemptHistory`, timings, nested children for parallel groups.
+
+## Step lifecycle
+
+```
+skip? → before? → (run | agent | parallel) → output.extract (+ schema) → after? → nextStep?
+```
+
+Exactly one of `run` / `agent` / `parallel` per step (enforced at `ai.step()` author time).
+
+| Phase | Purpose |
+| --- | --- |
+| `skip` | Return `true` to skip the step. Output becomes `undefined`. `nextStep` still fires. |
+| `before` | Pre-work — fetch, set state, validate. |
+| `run` | Core non-agent work. |
+| `agent` | Agent to execute. Takes `input(ctx)` as prompt builder. |
+| `input` | Required when `agent` is set. |
+| `output` | `{ extract, schema? }` — extracts the step's output. |
+| `after` | Post-work — save, notify. |
+| `nextStep` | Step-level routing on `completed` / `skipped`. |
+| `onFailure` | Step-level recovery routing after retries exhaust. |
+| `onCancel` | Cleanup if cancelled in-flight. |
+
+Errors in `before`/`run`/`agent`/`after`/`output` are retryable. Errors in `nextStep` and `onFailure` terminate the workflow with `RoutingError`.
+
+## Context (`ctx`)
+
+```ts
+type WorkflowContext<TInput, TState, TContext> = {
+  readonly input: TInput;                         // frozen — durable cause
+  readonly context: TContext;                     // frozen — per-execution
+  readonly steps: Record<string, StepSnapshot>;   // frozen snapshots of COMPLETED steps
+  state: TState;                                  // mutable current shared state
+  readonly agentResult?: AgentResult<unknown>;    // set when current step has an agent
+  readonly runId: string;
+  readonly signal?: AbortSignal;
+  readonly startedAt: Date;
+};
+```
+
+`input`, `context`, `steps` are deep-frozen. `state` is mutable during a step and frozen into `steps[name].state` on completion.
+
+### `input` vs `context`
+
+- `input` answers *what* to process — persisted in the snapshot, replayed verbatim on `resume()`.
+- `context` answers *who's running it* — tenancy, user, locale, traceId. **Never persisted.** Callers pass fresh on every `execute()` and `resume()`.
+
+**Resume rule.** No fingerprinting on context. Persistence-scoping fields (e.g. `organizationId`) MUST match across resume — silent data corruption otherwise.
+
+## State vs `steps[x].output` — performance
+
+- **Small control data** (flags, counters) → `ctx.state`. Cheap.
+- **Large artifacts** (HTML blobs, embedding vectors) → producer's `output.extract`, read via `ctx.steps[prev].output`. `ctx.state` clones on every retry attempt; `ctx.steps` clones once on step commit.
+
+## Parallel children
+
+```ts
+ai.step({
+  name: "generate",
+  parallel: [
+    ai.step({ name: "draft", agent: writerAgent, input, output }),
+    ai.step({ name: "suggest-articles", agent: kbAgent, input, output }),
+  ],
+});
+```
+
+- Children share `ctx.state` — last-write-wins.
+- Addressable by flat (`ctx.steps.draft`) AND nested (`ctx.steps.generate.steps.draft`) path.
+- Any child fails → all siblings still complete (atomic settlement); parent's `error` becomes the first child's error.
+- Checkpoint atomically after all children settle.
+
+## Routing — `nextStep` (success) + `onFailure` (failure)
+
+```ts
+ai.step({
+  name: "qa",
+  agent: qaReviewerAgent,
+  input,
+  output,
+  nextStep: (ctx) => {
+    if (!ctx.agentResult?.data.approved) {
+      ctx.state.qaFeedback = ctx.agentResult?.data.feedback;
+      return { goto: "draft" };       // success-path route
+    }
+  },
+  onFailure: (ctx, error) => {
+    if (error.code === "PROVIDER_RATE_LIMIT") {
+      return { goto: "fallbackQa" };
+    }
+    // void → halt with the original StepFailedError
+  },
+});
+```
+
+Returns: `{ goto: "stepName" }`, `{ end: true }`, or `void` (fall through / halt).
+
+**Guards:** `maxSteps` (default 100) hard-fails with `MaxStepsExceededError`. `loopWarnAfter` (default 5) emits `workflow.loop.warning`.
+
+## Retry
+
+```ts
+retry: {
+  attempts: 3,                    // default 1 = no retry
+  backoff: "exponential",         // "none" | "linear" | "exponential" | (attempt) => ms
+  retryOn: (error, attempt) => true,
+  onRetry: (attempt, error) => {},
+}
+```
+
+Exponential defaults: 500 ms → 1 s → 2 s → 4 s → 8 s, capped at 30 s. `AbortError` short-circuits retry.
+
+## Cancellation
+
+```ts
+const ctrl = new AbortController();
+const result = wf.execute({ input, signal: ctrl.signal });
+ctrl.abort("user cancelled");
+```
+
+Between-step cancellation is guaranteed. Mid-step is best-effort. `status: "cancelled"` on return with partial `report.steps`; checkpoint written before returning (resume works).
+
+## Persistence & resume
+
+See [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md).
+
+```ts
+await wf.execute({ input, runId: "ticket-123" });  // fresh run
+await wf.resume("ticket-123");                      // after crash
+```
+
+## Events — three-tier subscription
+
+`workflow.starting`, `workflow.step.{starting|streaming|completed|skipped|retrying|failed}`, `workflow.loop.warning`, `workflow.cancelled`, `workflow.completed`, `workflow.error`.
+
+Subscription order: **definition → instance → per-call** (all matching handlers fire).
+
+Every payload carries `runId` and `rootRunId`.
+
+## Design reference
+
+`domains/ai/design/workflow.md` — locked spec, §1–§16 covers every rule with five PoC examples.
+
+## See also
+
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — agents inside steps
+- [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) — snapshot resume + drift
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `WorkflowError` subclasses