@warlock.js/ai 4.2.11 → 4.4.0

package/skills/manage-ai-stores/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: manage-ai-stores
+description: 'Durable orchestrator stores — ai.checkpoint.{memory,pg,redis}() for cross-turn SESSION STATE and ai.snapshot.{memory,pg,redis}() for in-flight SUPERVISOR/WORKFLOW run state. Two distinct contracts (CheckpointStore vs SnapshotStore), dev-owned pg/redis clients (no peer dep), never-auto-migrated schema(), global defaults via ai.config({defaultCheckpointStore, defaultSnapshotStore}). Triggers: `ai.checkpoint`, `ai.snapshot`, `checkpointStore`, `snapshotStore`, `CheckpointStore`, `SnapshotStore`, `CheckpointRecord`, `checkpoint.pg`, `checkpoint.redis`, `snapshot.pg`, `snapshot.redis`, `store.schema()`, `keepSnapshots`, `defaultCheckpointStore`, `defaultSnapshotStore`, `PgClientLike`, `RedisClientLike`; ''persist orchestrator sessions'', ''wire a pg checkpoint store'', ''run the store DDL'', ''checkpoint vs snapshot''; typical import `import { ai } from "@warlock.js/ai"`. Skip: orchestrator lifecycle — `@warlock.js/ai/run-orchestrator/SKILL.md`; cache-backed snapshot resume / semanticCache store — `@warlock.js/ai/persist-ai-data/SKILL.md`; competing libs `temporal`, `inngest`.'
+---
+
+# Orchestrator stores — checkpoint vs snapshot
+
+`ai.orchestrator()` persists through **two distinct stores** with two distinct contracts. Confusing them is the #1 wiring mistake.
+
+| Store | Contract | Persists | Keyed by | Factories |
+|---|---|---|---|---|
+| **checkpoint** | `CheckpointStore` | cross-turn SESSION STATE (one append-only row per settled turn) | `(orchestrator_name, session_id, turn_index)` | `ai.checkpoint.{memory,pg,redis}()` |
+| **snapshot** | `SnapshotStore` | in-flight internal SUPERVISOR run state (for `iterate: true` mid-turn resume) | `runId` | `ai.snapshot.{memory,pg,redis}()` |
+
+- A **checkpoint** is what lets `execute()` rehydrate a session across calls — state, `turn_index`, drift `signature`, `version`, `last_route`, compaction progress, lock metadata.
+- A **snapshot** is what lets a crashed mid-turn `iterate: true` turn resume — it round-trips the existing `SupervisorSnapshot` envelope (the same shape the supervisor's own `snapshotStore` uses).
+
+`iterate: false` orchestrators need only a `checkpointStore`. `iterate: true` needs **both**.
+
+## Wiring
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const orch = ai.orchestrator({
+  name: "support",
+  intents,
+  route,
+  iterate: true,
+  checkpointStore: ai.checkpoint.pg({ client: pgPool }),
+  snapshotStore: ai.snapshot.pg({ client: pgPool }),  // a single pg.Pool backs both
+});
+```
+
+### Global defaults
+
+```ts
+ai.config({
+  defaultCheckpointStore: ai.checkpoint.memory(),
+  defaultSnapshotStore: ai.snapshot.memory(),
+});
+```
+
+Resolution: explicit `checkpointStore` / `snapshotStore` on the config wins, else the matching `ai.config({ default… })`, else undefined. `iterate: true` with no snapshot store resolvable throws `OrchestratorConfigError` at construction.
+
+## The three drivers
+
+| Driver | Client | Durable | Cross-process | Fits |
+|---|---|---|---|---|
+| `memory()` | none | ❌ | ❌ | dev / tests / single-process; no resume across restarts |
+| `pg({ client, table?, ttl? })` | dev-supplied `pg.Pool`/`Client` | ✅ | ✅ | production with Postgres |
+| `redis({ client, prefix?, ttl? })` | dev-supplied `redis` client | ✅ | ✅ | production with Redis |
+
+`@warlock.js/ai` takes **NO peer dependency** on `pg` or `redis` — you install the client, build it, and pass it in via `{ client }` (anything matching `PgClientLike` / `RedisClientLike`). The store never opens or closes the connection. A single `pg.Pool` can back the cache, the checkpoint store, and the snapshot store at once.
+
+```ts
+import { Pool } from "pg";
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+ai.checkpoint.pg({ client: pool, table: "warlock_orchestrator_sessions", ttl: 86_400 });
+ai.snapshot.pg({ client: pool, table: "warlock_supervisor_snapshots" });
+
+// redis
+ai.checkpoint.redis({ client: redisClient, prefix: "warlock:orchestrator", ttl: 86_400 });
+ai.snapshot.redis({ client: redisClient, prefix: "warlock:snapshot" });
+```
+
+Table / prefix names must be safe SQL identifiers (`[A-Za-z_][A-Za-z0-9_]*`) — interpolated into DDL/DML, so anything outside that subset is rejected. Defaults: pg checkpoint table `warlock_orchestrator_sessions`, pg snapshot table `warlock_supervisor_snapshots`, redis prefix `warlock:orchestrator`.
+
+## Schema is NEVER auto-migrated
+
+The framework never creates or alters tables. Each pg store exposes `schema()` returning the reference DDL — run it through YOUR migration tool once before use:
+
+```ts
+const store = ai.checkpoint.pg({ client: pool });
+await pool.query(store.schema());   // once, via your migration tooling
+```
+
+The memory and redis drivers return an empty `schema()` string (no backing table), so callers can treat `schema()` uniformly.
+
+## `CheckpointRecord` — the persisted row
+
+```ts
+type CheckpointRecord = {
+  orchestrator_name: string;          // PK segment 1
+  session_id: string;                 // PK segment 2
+  turn_index: number;                 // PK segment 3 — highest is live
+  state: unknown;                     // post-merge session accumulator (TState)
+  last_route: string | string[] | null;
+  signature: string;                  // drift fingerprint at write time
+  version: string | null;             // config.version tag — metadata only
+  summarized_through: number | null;  // exclusive turn index compaction reached
+  lock_acquired_at: string | null;    // compaction lock metadata
+  lock_expires_at: string | null;
+  saved_at: string;                   // ISO write timestamp
+};
+```
+
+Append-only from v1 — `save()` never overwrites a prior `turn_index`. `load(name, sessionId)` returns the latest row (highest `turn_index`), or `undefined` for a session the store has never seen.
+
+## Store contract methods
+
+Both stores: `load(...)`, `save(...)`, `delete(...)`, optional `list(...)`, `schema()`.
+
+- **`list(orchestratorName, prefix?)`** (checkpoint) / **`list(prefix?)`** (snapshot) — enumerate session/run ids for the production boot-drain loop. Optional: stores that can't enumerate omit it.
+- The orchestrator's **`keepSnapshots`** retention policy lives on the orchestrator config, NOT the store — the orchestrator calls the pg store's `prune()` after a successful `save` when `keepSnapshots` is a finite number; `"all"` skips pruning.
+
+## Boot-drain pattern
+
+On startup, resume any session whose last turn was interrupted mid-flight:
+
+```ts
+const sessions = await checkpointStore.list?.(orch.name) ?? [];
+for (const sessionId of sessions) {
+  await orch.resume(sessionId);   // null when nothing in flight — harmless
+}
+```
+
+## Distinct from `@warlock.js/cache` snapshot resume
+
+A bare `ai.supervisor()` / `ai.workflow()` uses a `snapshotStore` for `resume(runId)`. That `SnapshotStore` was promoted from the historical `@warlock.js/cache` `CacheDriver` path. ⚠ The CacheDriver overload is deprecated for one minor — new code wires `ai.snapshot.*` stores. See [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) for the supervisor/workflow side and the cache-backed semantic cache.
+
+## See also
+
+- [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) — the consumer of these stores
+- [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) — supervisor/workflow snapshot resume + the SnapshotStore migration
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `OrchestratorDriftError` / `OrchestratorConfigError`

package/skills/persist-ai-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: persist-ai-data
-description: 'Persistence delegated to @warlock.js/cache — workflow + supervisor snapshot resume via snapshotStore, semantic cache via vector-capable CacheDriver, global default via ai.config({defaultStore}). Covers drift detection + three recovery paths. Triggers: `ai.config`, `defaultStore`, `snapshotStore`, `wf.resume`, `supervisor.resume`, `WorkflowSnapshot`, `SupervisorSnapshot`, `WorkflowDriftError`, `SupervisorDriftError`, `force: true`; ''resume a workflow run'', ''configure snapshot store'', ''handle signature drift'', ''wire pg vector cache''; typical import `import { ai } from "@warlock.js/ai"`. Skip: cache driver catalog — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `temporal`, `inngest`.'
+description: 'Persistence delegated to @warlock.js/cache — workflow + supervisor snapshot resume via snapshotStore (4.3.0: now a SnapshotStore from ai.snapshot.*, ⚠ moved off raw CacheDriver), semantic cache + memory via vector-capable CacheDriver, global defaults via ai.config({defaultStore}) + ai.config({defaultSnapshotStore}). Covers drift detection + three recovery paths. Triggers: `ai.config`, `defaultStore`, `defaultSnapshotStore`, `snapshotStore`, `ai.snapshot`, `wf.resume`, `supervisor.resume`, `WorkflowSnapshot`, `SupervisorSnapshot`, `WorkflowDriftError`, `SupervisorDriftError`, `force: true`; ''resume a workflow run'', ''configure snapshot store'', ''handle signature drift'', ''wire pg vector cache''; typical import `import { ai } from "@warlock.js/ai"`. Skip: orchestrator checkpoint/snapshot store factories — `@warlock.js/ai/manage-ai-stores/SKILL.md`; cache driver catalog — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `temporal`, `inngest`.'
 ---
 
 # Persistence — `@warlock.js/cache` everywhere
@@ -23,15 +23,19 @@ description: 'Persistence delegated to @warlock.js/cache — workflow + supervis
 └──────────────┘         └────────────────────┘         └──────────────────┘
 ```
 
-## Resolution order
+## Resolution order — two separate defaults
 
 ```
-options.store ?? ai.config({ defaultStore }) ?? undefined
+// semantic cache + memory (CacheDriver):
+options.store         ?? ai.config({ defaultStore })         ?? undefined
+
+// supervisor / workflow / orchestrator snapshots (SnapshotStore):
+options.snapshotStore ?? ai.config({ defaultSnapshotStore }) ?? undefined
 ```
 
-When neither is set:
+`defaultStore` (a `CacheDriver`) and `defaultSnapshotStore` (a `SnapshotStore`) are independent — set whichever the consumer needs. When the relevant one is unset:
 - **Snapshot consumers** silently skip writes and throw on `resume()`.
-- **Semantic cache** throws at construction.
+- **Semantic cache / memory** throws at construction.
 
 ## `ai.config({ defaultStore })` — set once at boot
 
@@ -60,26 +64,32 @@ Brute-force memory drivers carry an `O(N)` similarity scan — fine up to a few
 
 ## Snapshot resume — workflow + supervisor
 
-### Wiring
+> ⚠ **BREAKING (4.3.0): supervisor + workflow snapshot persistence moved `CacheDriver` → `SnapshotStore`.** A `snapshotStore` is now a `SnapshotStore` built with `ai.snapshot.{memory,pg,redis}()`, not a raw `cache.driver(...)`. The framework still ships a deprecated `CacheDriver` overload for ONE minor so existing wiring keeps working, but new code uses the dedicated store factories. The `defaultSnapshotStore` resolution is via `ai.config({ defaultSnapshotStore })` (a `SnapshotStore`), separate from `defaultStore` (a `CacheDriver`, still used for `semanticCache` + memory). See [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md).
+
+### Wiring (new)
 
 ```ts
-ai.config({ defaultStore: cache.driver("redis", { client }) });
+import { ai } from "@warlock.js/ai";
+
+ai.config({ defaultSnapshotStore: ai.snapshot.redis({ client }) });
 
 const wf = ai.workflow({
   name: "ticket-processor",
   steps: [...],
-  // snapshotStore optional — falls back to defaultStore
+  // snapshotStore optional — falls back to ai.config({ defaultSnapshotStore })
 });
 
 const sup = ai.supervisor({
   name: "support-team",
   router: routerAgent,
   intents: { triage, billing, resolver },
-  // explicit override when this primitive needs a different driver
-  snapshotStore: cache.driver("pg", { client: pgPool, table: "support_runs" }),
+  // explicit override when this primitive needs a different store
+  snapshotStore: ai.snapshot.pg({ client: pgPool, table: "support_runs" }),
 });
 ```
 
+The `SnapshotStore` is generic over its snapshot shape — it defaults to `SupervisorSnapshot`, and the workflow engine parameterizes it with `WorkflowSnapshot`; the only structural requirement is a `runId` string. `ai.snapshot.memory()` for dev/tests, `ai.snapshot.{pg,redis}()` for production (dev-owned client, never-auto-migrated `schema()`).
+
 ### Snapshot shapes
 
 ```ts
@@ -200,6 +210,7 @@ The driver must support `similar()`. Without similarity → `CacheUnsupportedErr
 
 ## See also
 
+- [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md) — `ai.snapshot.*` + `ai.checkpoint.*` store factories, schema(), drivers
 - [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — `snapshotStore` + `resume()`
 - [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — same on supervisor
 - [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) — `semanticCache` middleware

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

@@ -1,6 +1,6 @@
 ---
 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`.'
+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 — plus cost truth: ModelPricing (per-1M tokens), Usage cost breakdown, the cachedTokens / cacheWriteTokens / reasoningTokens channels, and capability flags. Triggers: `OpenAISDK`, `SDKAdapterContract`, `ModelContract`, `ModelPricing`, `ModelCapabilities`, `sdk.model`, `sdk.embedder`, `capabilities.vision`, `capabilities.structuredOutput`, `capabilities.reasoning`, `capabilities.promptCaching`, `pricing`, `Usage.cost`, `cachedTokens`, `cacheWriteTokens`, `reasoningTokens`, `reasoning.effort`, `cacheControl`, `baseURL`, `provider: "openrouter"`; ''pick a provider'', ''openai vs openrouter'', ''does this model support vision/reasoning'', ''configure pricing'', ''how much did reasoning cost'', ''prompt cache tokens''; 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
@@ -44,16 +44,20 @@ Adapters are classes — `new OpenAISDK({ apiKey })`, `new AnthropicSDK({ apiKey
 - `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`):
+The `ModelContract.capabilities` field declares what the model supports — all flags optional (absent = treat as `false`):
 
 ```ts
 type ModelCapabilities = {
   structuredOutput?: boolean;   // native response_format: json_schema support?
   vision?: boolean;             // can accept image attachments?
+  reasoning?: boolean;          // forwards ModelCallOptions.reasoning (effort / thinking budget)?
+  promptCaching?: boolean;      // honors cacheControl breakpoints + reports cache token channels?
+  audio?: boolean;              // can accept audio ContentPart input?
+  pdf?: boolean;                // can accept PDF / document ContentPart input?
 };
 ```
 
-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.
+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; reasoning / cacheControl options are silently skipped when the adapter doesn't declare support, rather than sent as unsupported params.
 
 ## OpenAI adapter — usage
 
@@ -100,23 +104,53 @@ const customModel = openai.model({
 });
 ```
 
-## Pricing — per-channel cost breakdown
+## Cost truth — pricing + token channels
 
-Configure `pricing` on the model (or via the SDK registry) and every report carries `Usage.cost`:
+`ModelPricing` is **USD per 1,000,000 tokens** (the industry-standard unit), declared at two optional sites — `SDK.pricing` (registry keyed by model name) and `model({ pricing })` (per-model override, wins). Resolution: per-model > SDK registry > undefined (no cost computed).
 
 ```ts
-const openai = new OpenAISDK({
-  apiKey,
-  pricing: { "gpt-4o-mini": { input: 0.15, output: 0.6, cachedInput: 0.075 } },
-});
+type ModelPricing = {
+  input: number;            // required — USD / 1M input tokens
+  output: number;           // required — USD / 1M output tokens
+  cachedInput?: number;     // prompt-cache READ rate; falls back to `input`
+  cachedOutput?: number;    // cache-WRITE rate (Anthropic premium); falls back to `output`
+  reasoning?: number;       // reasoning/thinking-token rate; falls back to `output`
+};
+```
 
+Configure it and every report carries `Usage.cost` — a per-channel breakdown captured at emit time as a historical fact (stored reports stay accurate after the upstream table changes):
+
+```ts
 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
+usage.cost;          // { input, output, cachedInput?, cachedOutput? }  — USD per channel
+// single scalar total: sum the populated fields, treating undefined as 0.
+```
+
+`usage.cost` is `undefined` when no pricing is available — honest absence over false zero. Aggregators merge only defined fields, so one unpriced child never erases a priced sibling's cost.
+
+### Token channels (`Usage`) — what each adapter reports
+
+Beyond `input` / `output` / `total`, `Usage` carries optional sub-channels (undefined when the provider doesn't meter them):
+
+| Channel | Meaning | Provider source |
+|---|---|---|
+| `cachedTokens` | subset of `input` served from prompt cache (READ hit) | OpenAI `prompt_tokens_details.cached_tokens`, Anthropic `cache_read_input_tokens` |
+| `cacheWriteTokens` | input tokens WRITTEN to the cache this call | Anthropic `cache_creation_input_tokens` (OpenAI does not write-bill) |
+| `reasoningTokens` | subset of `output` for internal reasoning/thinking | OpenAI `completion_tokens_details.reasoning_tokens`, Anthropic extended-thinking |
+
+### Driving cache + reasoning per call
+
+`ModelCallOptions` exposes vendor-neutral controls the agent forwards only when `capabilities` allows:
+
+```ts
+await model.complete(messages, {
+  reasoning: { effort: "high", maxTokens: 8_000 },  // effort → OpenAI reasoning_effort; maxTokens → Anthropic thinking budget
+  cacheControl: { breakpoints: 1 },                 // WRITE breakpoint → Anthropic cache_control markers
+});
 ```
 
-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.
+Read-side cache accounting (`Usage.cachedTokens`) works WITHOUT `cacheControl` — it only controls WRITE placement. Adapters whose `capabilities.reasoning` / `.promptCaching` is absent ignore these rather than forwarding unsupported params.
 
 ## Embeddings
 

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

@@ -1,6 +1,6 @@
 ---
 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`.'
+description: 'Build agents with ai.agent({...}) — the single-LLM-turn primitive. Covers execute / stream, attachments, structured output, placeholders, events, agent.eval scoring, and auto-adapting raw executables in tools:[]. Triggers: `ai.agent`, `agent.execute`, `agent.stream`, `agent.eval`, `AgentResult`, `AgentReport`, `AgentToolEntry`, `streamingToolGuard`, `attachments`, `repair`, `maxTrips`, `sessionId`, `spawnSubAgent`, `SpawnSubAgentSpec`; ''run an agent'', ''stream an agent response'', ''structured output schema'', ''pass image to agent'', ''evaluate an agent'', ''put a supervisor in tools'', ''cancel an agent run'', ''spawn a one-shot sub-agent with a per-task budget''; 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`; eval matchers / batch / fallback detail — `@warlock.js/ai/ai-dx-helpers/SKILL.md`; competing libs `langchain`, `ai` (Vercel), raw `openai`.'
 ---
 
 # `ai.agent()` — single-turn primitive
@@ -19,7 +19,7 @@ ai.agent({
   name?: string,                              // optional — anonymous gets a fingerprint
   model: openai.model({ name: "gpt-4o-mini" }),
   systemPrompt?: string | SystemPromptContract,
-  tools?: ToolContract<any, any>[],
+  tools?: AgentToolEntry<any, any>[],          // ToolContract OR a raw executable (auto-adapted)
   placeholders?: Record<string, unknown>,
   maxTrips?: number,                           // default 10
   modelOptions?: ModelCallOptions,
@@ -255,6 +255,55 @@ await myAgent.execute("go", {
 
 Every event payload carries `runId` and `rootRunId`. Same identity fields ride on stream events.
 
+## `tools: []` — auto-adapt executables
+
+Each `tools` entry is either a built `ToolContract` (from `ai.tool(...)` or an explicit `.asTool(...)`) OR a **raw executable primitive** (`AgentContract` / `WorkflowInstance` / `SupervisorContract` / orchestrator) — auto-adapted into a `ToolContract` at factory time. The manifest is derived from the executable's `name` + `description` + (optional) `inputSchema`; dispatch flows through its `execute()`.
+
+```ts
+const concierge = ai.agent({
+  model,
+  tools: [billingWorkflow, supportSupervisor, lookupTool],  // no .asTool() needed
+});
+```
+
+`.asTool()` still works and takes precedence when you need a custom name / schema per use. A supervisor/orchestrator needs `inputSchema` on its config to drop straight into `tools: []`. See [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md).
+
+## `agent.eval(options)` — score the agent against a suite
+
+```ts
+const report = await myAgent.eval({
+  cases: [
+    { name: "capital", input: "Capital of Egypt?", expected: "Cairo" },
+    { name: "tone", input: "Comfort an upset user." },          // judge-scored
+  ],
+  scorers: [ai.eval.contains()],                                 // default for cases w/o their own
+  judge: { agent: judgeAgent, rubric: "Score 1.0 only if empathetic." },  // LLM-as-judge fallback
+  passThreshold: 0.5,                                            // default
+});
+
+expect(report.passed).toBe(true);   // true only when EVERY case passed
+```
+
+Each case runs through `execute(input)`; scorer precedence is per-case `scorers` → suite `scorers` → synthesized `judge` (throws at author time if a case resolves none). Built-in scorers on `ai.eval.*`: `exact()`, `contains()`, `predicate(fn)`, `judge(config)`. Full coverage — plus the Vitest matchers (`registerAiMatchers` / `toRouteTo` / `toConverge` / `toPassStep` / `toOutputShape`) — in [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md).
+
+## `ai.spawnSubAgent()` — one-shot delegation with a budget
+
+`ai.spawnSubAgent(spec)` is a thin wrapper over this same `ai.agent()`: it builds a fresh agent from the spec, optionally attaches a `budget` middleware, runs the `task` once, and returns the `AgentResult`. Not a sandbox or a separate runtime — a spawn is an ordinary new agent (empty conversation, its own tools/prompt). It is a **general** primitive: usable inside a tool, a workflow or planner step, a supervisor intent, or hand-rolled orchestration — it is NOT planner-specific (the planner engine never calls it).
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const result = await ai.spawnSubAgent({
+  name: "extract-entities",
+  model,
+  task: "Pull every company name from this article: ...",
+  budget: { maxCostUSD: 0.05 },   // per-task spend cap — aborts when crossed
+  output: companiesSchema,
+});
+```
+
+The one field a bare agent config doesn't surface ergonomically is `budget` (`BudgetOptions` — `maxTokens` / `maxCostUSD`), equivalent to `ai.agent({ middleware: [ai.middleware.budget(...)] })` but promoted to a first-class spec field so a delegated subtask can't overrun its cap (distinct from `maxTrips`, which caps round-trips, not spend). The surface is **narrower** than `agent.execute()`: one-shot, with no `history`, `placeholders`, per-call events, or `repair`. The spawned `report` slots under the caller's `report.children[]`, so cost and traces roll up uniformly. Reach for it when you want a named single-use delegation with a hard spend cap; otherwise just build an `ai.agent()` and call it.
+
 ## 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)

package/skills/run-orchestrator/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: run-orchestrator
+description: 'Durable stateful sessions with ai.orchestrator({...}) — the capstone of the 4-primitive ladder. Wraps a supervisor with cross-turn session state (checkpointStore), per-turn windowing, drift detection, post-turn compaction, mid-turn resume (iterate: true + snapshotStore), per-turn memory, typed commands, asTool, and a 3-tier event model. Triggers: `ai.orchestrator`, `orchestrator.execute`, `orchestrator.resume`, `orchestrator.command`, `orchestrator.stream`, `OrchestratorConfig`, `OrchestratorResult`, `OrchestratorReport`, `OrchestratorContract`, `CheckpointStore`, `OrchestratorDriftError`, `sessionId`, `iterate`, `historyWindow`, `summarize`, `keepSnapshots`, `awaiting-input`, `turns[]`, `TurnSnapshot`, `CompactionResult`, `initialAgent`, `checkpointStore`; ''multi-turn conversation that persists'', ''durable session across calls'', ''resume an interrupted turn'', ''compact session history'', ''per-session memory''; typical import `import { ai } from "@warlock.js/ai"`. Skip: a single routing turn with no session — `@warlock.js/ai/run-supervisor/SKILL.md`; a fixed pipeline — `@warlock.js/ai/run-ai-workflow/SKILL.md`; the store factories themselves — `@warlock.js/ai/manage-ai-stores/SKILL.md`; competing libs `langgraph`, `crewai`.'
+---
+
+# `ai.orchestrator()` — durable stateful sessions
+
+The capstone of the 4-primitive ladder. An orchestrator is a **session-state manager wrapped around a supervisor**: each `execute` / `stream` call is ONE turn against a named `sessionId`, with the session's accumulated state, drift signature, and compaction progress persisted in a `CheckpointStore` between calls. The "what runs" fields (`intents`, `route` / `router`, `evaluate`, `state`, `output`, `initialAgent`, `maxIterations`) are the supervisor's surface spread directly — the orchestrator builds the supervisor lazily per turn and delegates to it. You never see the supervisor object.
+
+## When to reach for it
+
+- **`supervisor`** — routes one input to a specialist each turn; stateless between runs unless you wire `snapshotStore`. No cross-turn session memory.
+- **`orchestrator`** — when the **session** matters: a long-running conversation where each turn must rehydrate the prior turn's state, history must be windowed/compacted, and an interrupted turn must resume after a crash.
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { END } from "@warlock.js/ai";
+
+type SessionState = { category?: string; order?: { id: string }; reply?: string };
+
+const supportBot = ai.orchestrator<SessionState>({
+  name: "refund-support",
+  intents: { classify, lookup, process, compose },
+  route: (ctx) => (ctx.iteration === 0 ? "classify" : END),
+  iterate: true,                                  // delegate each turn to a real supervisor
+  historyWindow: { router: 5, agents: 20 },
+  summarize: { afterTurns: 20, keep: 6 },         // auto-compaction policy
+  keepSnapshots: 100,                             // turns retained per session
+  checkpointStore: ai.checkpoint.pg({ client: pg }),
+  snapshotStore: ai.snapshot.pg({ client: pg }),  // required when iterate: true
+});
+
+const result = await supportBot.execute(message, { sessionId: "sess_42", history });
+
+if (result.report.status === "awaiting-input") {
+  // session continues — wait for the next user turn
+}
+```
+
+`route` XOR `router` is required (mutually exclusive). `initialAgent`, when set, must be a key in `intents` and dispatches on turn 0, skipping the first route/router call. All config-shape errors throw `OrchestratorConfigError` at construction (author-time), not on the first turn.
+
+## The session is owned by `sessionId` — passed per call
+
+There is no stateful session object and no implicit "current session" — every method names the session it acts on via `options.sessionId`. `history` is **required** on every `execute` call: the framework never persists raw messages (it owns session *state*, not the message log — that is the dev's store). `state` is a partial seed/patch shallow-merged into the loaded session state; `context` is the request-scoped bag, frozen at intake.
+
+```ts
+await supportBot.execute(input, {
+  sessionId: "sess_42",       // required — names the session
+  history: priorMessages,     // required — the dev re-supplies prior turns each call
+  state: { tier: "gold" },    // partial patch shallow-merged into loaded state
+  context: { userId, db },    // request-scoped, never persisted
+  signal: AbortSignal.timeout(60_000),
+  on: { "orchestrator.turn.awaiting-input": (e) => log(e) },  // tier-3 per-call handlers
+  force: false,               // bypass drift check for this call
+});
+```
+
+## The turn lifecycle (what each turn does)
+
+1. **load** — read the latest checkpoint for `(name, sessionId)`; seed empty on first call (`orchestrator.session.loaded`).
+2. **drift check** — compare the loaded checkpoint's `signature` to the current definition (`orchestrator.drift.checked`). Mismatch throws `OrchestratorDriftError` unless `force: true`.
+3. **lock wait** — wait on the compaction lock if held (`orchestrator.lock.waiting`).
+4. **window** — slice history per `historyWindow.{router,agents}` (`orchestrator.history.windowed`).
+5. **dispatch** — `route`/`router` (or `initialAgent` on turn 0) picks the intent(s); the supervisor runs the turn (`orchestrator.turn.routed`, `orchestrator.turn.streaming`).
+6. **persist** — append a checkpoint row for the settled turn, then prune to `keepSnapshots` (`orchestrator.checkpoint.persisted`).
+7. **compaction** — fire the post-turn compaction trigger if configured (`orchestrator.compaction.suggested` / `.applied`).
+
+A clean turn ends with `orchestrator.turn.awaiting-input` (the session stays open for the next user turn); `orchestrator.turn.failed` and `orchestrator.turn.cancelled` end error / cancelled turns. (`orchestrator.turn.completed` is defined on the event map, but the v1 lifecycle maps a clean completion to `awaiting-input`, so it isn't emitted on the normal path — subscribe to `awaiting-input` for "turn done".)
+
+## `OrchestratorResult` — read the report
+
+```ts
+const result = await supportBot.execute(message, { sessionId, history });
+
+result.sessionId;                 // echoes the session this turn acted on
+result.turnIndex;                 // zero-indexed turn number
+result.data;                      // validated against `output`, if set
+result.error;                     // typed AIError — execute() never throws on runtime failure
+result.report.type;               // "orchestrator"
+result.report.status;             // ReportStatus | "awaiting-input"
+result.report.turns;              // TurnSnapshot[] — current turn + prior, bounded by keepSnapshots
+result.compaction;                // CompactionResult when a turn compacted (and no onCompact ran)
+```
+
+`report.children[]` carries ONLY the current turn's dispatched primitive reports. Full session history lives on `report.turns[]` — a `children[]` walker will NOT reach prior turns (intentional). Child `supervisor.*` / `agent.*` events bubble up unmodified under their own identity.
+
+**`awaiting-input` is the only non-terminal status across the unified result tree.** Code branching on `status === "completed"` MUST explicitly handle `"awaiting-input"` as a session-continues path, not a failure.
+
+## `iterate` — single dispatch vs. internal supervisor
+
+- **`iterate: false`** (default) — one dispatch per turn. No `snapshotStore` needed.
+- **`iterate: true`** — each turn delegates to a real internal supervisor that loops to `maxIterations` (default 10). **Requires** a `snapshotStore` (explicit or `ai.config({ defaultSnapshotStore })`) so a crashed mid-turn iteration can resume. Construction throws if you set `iterate: true` without one.
+
+## `resume()` — drain an interrupted turn
+
+```ts
+const result = await supportBot.resume("sess_42", { context: { db }, force: false });
+```
+
+Resume continues an interrupted `iterate: true` turn from its persisted supervisor snapshot. Returns `null` when there is nothing in flight for the session (a no-op for `iterate: false` orchestrators). It re-supplies request-scoped `context` (NOT persisted) and rehydrates state from the checkpoint — there is no `history` field, since it continues an in-flight turn rather than opening a fresh one. Runs the same drift check as `execute()`; throws `OrchestratorDriftError` on mismatch unless `{ force: true }`. Use the boot-drain pattern: enumerate sessions via `checkpointStore.list(name)` and `resume()` each on startup.
+
+## Compaction — `summarize`
+
+Bounds session history growth. Two forms:
+
+```ts
+// Object policy — count-based auto-fire after `afterTurns`, keep the most recent `keep`.
+summarize: {
+  afterTurns: 20,
+  keep: 6,
+  summarizer: cheapModel,                  // defaults to the orchestrator's own model
+  onCompact: async (compaction, ctx) => {  // apply to the dev's message store
+    await messages.applyCompaction(ctx.sessionId, compaction);
+  },
+  lock: { maxWait: 5_000 },
+}
+
+// Callback form — full control; NEVER auto-fires, driven only by command("compact").
+summarize: (history) => ({ summary, replacesFromIndex, replacesToIndex }),
+```
+
+A `CompactionResult` is `{ summary: Message, replacesFromIndex, replacesToIndex }` — the replacement summary plus the inclusive index range it replaces in the dev's history array. When `onCompact` is supplied the orchestrator applies it for you and does NOT surface `result.compaction`; otherwise it surfaces `result.compaction` for you to apply manually.
+
+## `command()` — typed built-ins
+
+```ts
+const compaction = await supportBot.command("compact", { sessionId, history });
+// → { summary, replacesFromIndex, replacesToIndex }
+```
+
+v1 ships exactly one built-in command, `compact` (manual compaction outside the auto-trigger; reuses the same compaction code path). User commands attach via module augmentation of `OrchestratorCommands` — declaring extra keys in your own `.d.ts` widens the typed `command<K>` surface without a framework release.
+
+## Per-turn memory — `memory`
+
+Wire an `ai.memory()` store so each turn recalls relevant memories before routing and remembers the settled outcome after:
+
+```ts
+ai.orchestrator({
+  name: "support",
+  intents,
+  route,
+  memory: mem,                                  // bare MemoryContract — recall + remember w/ defaults
+  // or finer control:
+  memory: {
+    store: mem,
+    recall: { k: 5, threshold: 0.7, tier: "semantic" },  // k: 0 = write-only memory
+    remember: true,                             // false = read-only (recall, never write)
+    rememberTier: "semantic",
+    injectKey: "memories",                      // ctx.context[injectKey] holds RecalledMemory[]
+  },
+});
+```
+
+Recalled memories land in the per-turn `context` bag under `injectKey` (default `"memories"`) — every route / router / evaluate / dispatch callback reads them at `ctx.context.memories`. Memory never mutates the prompt itself; surfacing it stays explicit. Cancelled / failed turns never remember (they revert), regardless of `remember`. See [`@warlock.js/ai/use-ai-memory/SKILL.md`](@warlock.js/ai/use-ai-memory/SKILL.md).
+
+## `asTool()` — orchestrator as a tool
+
+```ts
+const supportTool = supportBot.asTool({
+  name: "handle_refund",
+  description: "Handle a refund conversation end-to-end.",
+  inputSchema: v.object({ message: v.string() }),
+  sessionScope: "fresh",   // default — each call gets a brand-new sessionId
+});
+
+const concierge = ai.agent({ model, tools: [supportTool] });
+```
+
+The tool boundary is **opaque**: the parent's `signal` / `context` / events do NOT auto-forward — anything the wrapped orchestrator needs must ride on the `inputSchema` payload. `sessionScope`:
+- **`"fresh"`** (default) — each invocation gets a generated `sessionId` and empty history; no continuity across calls.
+- **`"shared"`** — the parent threads `sessionId` (and optionally `history`) through the validated payload; the orchestrator participates in that session. A missing/blank `sessionId` throws.
+
+## Drift detection
+
+The orchestrator signature fingerprints: name + intents map + route/router presence + evaluate presence + initialAgent + maxIterations + iterate flag + historyWindow shape. It does NOT aggregate the internal supervisor's signature — internal-supervisor drift surfaces only on `iterate: true` resume via the supervisor's own drift check. On mismatch, `OrchestratorDriftError` (`code: "ORCHESTRATOR_DRIFT"`, `category: "drift"`) is thrown synchronously — nothing dispatches. Recover by discarding the session, migrating the persisted checkpoint, or passing `{ force: true }`.
+
+## 3-tier events
+
+Handlers fire definition → instance → per-call, in that order, on every emission:
+
+```ts
+const orch = ai.orchestrator({ ..., on: { "orchestrator.turn.failed": tier1 } });   // tier 1 — definition
+const off = orch.on("orchestrator.turn.completed", tier2);                          // tier 2 — instance
+await orch.execute(input, { sessionId, history, on: { "orchestrator.drift.checked": tier3 } }); // tier 3 — per-call
+```
+
+## Stores
+
+`checkpointStore` (cross-turn session state) and `snapshotStore` (internal-supervisor run state for `iterate: true`) are distinct contracts with distinct factories. See [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md).
+
+## See also
+
+- [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — the engine each turn delegates to
+- [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md) — `ai.checkpoint.*` / `ai.snapshot.*`
+- [`@warlock.js/ai/use-ai-memory/SKILL.md`](@warlock.js/ai/use-ai-memory/SKILL.md) — the `memory` field
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `OrchestratorDriftError` / `OrchestratorConfigError`