@warlock.js/ai 4.2.11 → 4.4.0

package/skills/run-planner/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: run-planner
+description: 'Goal-driven planning with ai.planner({...}) — an LLM GENERATES an ordered execution plan over your registered capabilities (agents / workflows / supervisors / tools), then the planner EXECUTES that plan step-by-step, threading each step output into the next, and returns the unified {data, report, usage, error} envelope with report.type "planner". A plan step may delegate via ai.spawnSubAgent({...}) — a GENERAL one-shot-agent helper (a fresh agent + optional per-task budget), covered fully in `@warlock.js/ai/run-ai-agent/SKILL.md`; it is not planner-specific and the planner engine does not require it. Triggers: `ai.planner`, `planner.execute`, `spawnSubAgent`, `PlannerConfig`, `PlannerCapability`, `PlannerResult`, `PlannerReport`, `PlannerPlan`, `PlannerStep`, `maxSteps`, `report.plan`, `report.executedSteps`; ''let the model plan the steps'', ''dynamic plan from a goal'', ''decompose a goal into capability calls'', ''spawn a sub-agent for a subtask''; typical import `import { ai } from "@warlock.js/ai"`. Skip: a FIXED known pipeline — `@warlock.js/ai/run-ai-workflow/SKILL.md`; routing one input to a specialist each turn — `@warlock.js/ai/run-supervisor/SKILL.md`; a single model + tools call — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langgraph`, `crewai`.'
+---
+
+# `ai.planner()` — LLM-generated, then executed, plans
+
+A planner turns a free-form **goal** into an ordered **plan** the LLM writes itself (referencing only the capabilities you registered), then runs that plan one step at a time through each capability's own `execute()`. Use it when you do NOT know the steps up front — the model decides the sequence.
+
+## When to reach for it
+
+- **`agent`** — one model + tools, single task. No multi-step decomposition.
+- **`workflow`** — a FIXED pipeline you author by hand (`steps: [...]`). The steps are known at design time.
+- **`supervisor`** — routes one input to the right specialist each turn; loops on a quality verdict.
+- **`planner`** — the steps are NOT known in advance. The LLM generates the ordered plan from the goal, then the planner executes it. Bounded v1: strictly sequential, no DAG scheduling, no mid-plan re-planning.
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const research = ai.planner({
+  name: "research-assistant",
+  model: ai.openai.model({ name: "gpt-4o" }), // the plan-GENERATION brain
+  capabilities: [
+    { name: "search", description: "Search the web for sources", executable: searchAgent },
+    { name: "summarize", description: "Summarize text into bullet points", executable: summarizer },
+    { name: "write", description: "Draft a final report", executable: writerAgent },
+  ],
+  maxSteps: 6, // hard cap; steps beyond it are recorded as "skipped"
+});
+
+const { data, report, usage, error } = await research.execute("Compare React vs Vue in 2026");
+
+console.log(report.plan?.summary);          // the LLM's one-line strategy
+for (const step of report.executedSteps) {  // forensic, in execution order
+  console.log(step.step.capability, step.status);
+}
+```
+
+- `model` builds an internal planning agent with a generated plan-prompt baked on. **Mutually exclusive** with `planner`.
+- `planner` lets you bring your own fully-configured planning agent (custom prompt, middleware). The planner injects the plan schema as that agent's per-call `output`.
+- A `capability` is `{ name, description, executable }`. The `name` is what the LLM references per step; the `description` is what it reads to pick. `executable` is any `ExecutableContract` (agent / workflow / supervisor / tool).
+
+## Execution model (bounded v1)
+
+1. **Generate** — the planning agent is asked for a `{ steps, summary? }` plan via a generated schema whose `capability` field is an `enum` of your capability names.
+2. **Execute** — steps run **strictly in array order**. Each completed step's output is threaded into the next step's input as "Context from earlier steps". `dependsOn` on a step is advisory metadata only — recorded, not scheduled on.
+3. **Finalize** — when `output` is set (factory or per-call), the LAST completed step's structured output is validated into `result.data`. A capability that should feed typed output to the planner's `output` should declare its own `output` schema (the planner reads `data`, falling back to an agent's raw `text`).
+
+`report.type === "planner"`; `report.children[]` carries every dispatched capability report (plus the planning trip), with usage rolled up. Lazy capability loading is **deferred** — every capability is fully constructed up front.
+
+## Failure + cancellation
+
+`execute()` never throws — failures surface on `result.error`:
+
+- **`PlannerPlanInvalidError`** (`PLANNER_PLAN_INVALID`, category `schema`) — empty plan or a step naming an unknown capability; also a final-output validation failure.
+- **`PlannerCancelledError`** (`PLANNER_CANCELLED`, category `cancelled`) — the `AbortSignal` fired. `report.status === "cancelled"`, `report.cancelledAt` set; remaining steps are `skipped`.
+- A child capability's own error (agent / tool / provider) flows through unchanged on the failing step's snapshot and as `result.error`. The planner stops at the first failed step and marks the rest `skipped`.
+- **`PlannerFailedError`** is the base for the `PLANNER_*` family.
+
+## Delegating a step with `ai.spawnSubAgent()`
+
+A plan step can hand a bounded subtask to a fresh single-use agent with a hard spend cap via `ai.spawnSubAgent({...})`. It is **not** a planner feature — it's a general one-shot-agent helper (a fresh `ai.agent()` + an optional per-task `budget`, run once) that works identically inside a tool, a workflow step, a supervisor intent, or hand-rolled orchestration. The planner engine never calls it; it's simply a primitive a capability *you* write can reach for. Full coverage: [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md).
+
+## Testing
+
+Use `MockSDK` for the planning model — script the plan as a JSON string matching `{ steps, summary? }`. Capabilities can be `mockAgent({ name, responses })`. See `src/planner/planner.spec.ts`.

package/skills/run-supervisor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-supervisor
-description: 'Multi-intent routing with ai.supervisor({...}) — classifier (iter-0 dispatch), router agent OR route callback, intents as agents / workflows / callbacks, fan-out, evaluate quality loop, ack receptionist. Triggers: `ai.supervisor`, `supervisor.execute`, `supervisor.resume`, `intents`, `router`, `route`, `classifier`, `evaluate`, `ack`, `artifactsSchema`, `END`, `ctx.intents.X.execute`; ''route one input across specialists'', ''multi-intent dispatch'', ''fan-out then evaluate'', ''classifier then router''; typical import `import { ai } from "@warlock.js/ai"`. Skip: fixed pipelines — `@warlock.js/ai/run-ai-workflow/SKILL.md`; single agent — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langgraph`, `crewai`.'
+description: 'Multi-intent routing with ai.supervisor({...}) — classifier (iter-0 dispatch), router agent OR route callback, intents as agents / workflows / callbacks, fan-out, evaluate quality loop, ack receptionist, supervisor-level middleware. Triggers: `ai.supervisor`, `ai.router`, `ai.fanOut`, `supervisor.execute`, `supervisor.resume`, `intents`, `router`, `route`, `classifier`, `evaluate`, `ack`, `artifactsSchema`, `middleware`, `END`, `ctx.intents.X.execute`; ''route one input across specialists'', ''multi-intent dispatch'', ''fan-out then evaluate'', ''classifier then router'', ''supervisor middleware'', ''self-consistency / voting''; typical import `import { ai } from "@warlock.js/ai"`. Skip: durable multi-turn sessions — `@warlock.js/ai/run-orchestrator/SKILL.md`; fixed pipelines — `@warlock.js/ai/run-ai-workflow/SKILL.md`; single agent — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langgraph`, `crewai`.'
 ---
 
 # `ai.supervisor()` — multi-intent routing
@@ -12,7 +12,7 @@ A supervisor takes one input, picks which intent(s) handle it, runs them, option
 - **`agent`** — one model + tools, single task. Doesn't fit when the right specialist depends on the input.
 - **`workflow`** — fixed step order. Doesn't fit when routing decisions need an LLM or vary per request.
 - **`supervisor`** — when the right specialist is decided per-call and you may iterate to a goal.
-- **`orchestrator` (v2)** — when the *session* matters: long-running conversations.
+- **`orchestrator`** — when the *session* matters: long-running conversations with durable cross-turn state, history windowing/compaction, and mid-turn resume. See [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md).
 
 ## Three dispatch surfaces
 
@@ -73,6 +73,41 @@ The router agent's output MUST include `next: string | string[] | typeof END`; `
 
 `evaluate` pairs with both `router` AND `route` — state-driven termination is useful in either dispatch mode.
 
+#### `ai.router()` — skip the boilerplate
+
+`ai.router({ model, intents })` builds the routing agent for you: it generates the `{ next, reasoning }` output schema (with the intent names + `END` baked in as a JSON-Schema `enum`) and auto-writes the routing system prompt listing every intent + description. Pass the **same** `intents` object you pass to `ai.supervisor()`.
+
+```ts
+const intents = { billing, shipping, returns, escalate };
+
+const supportBot = ai.supervisor({
+  router: ai.router({
+    model,
+    intents,
+    systemPrompt: "You coordinate a customer-support team.", // optional framing on top
+  }),
+  intents,
+});
+```
+
+The result is a plain `AgentContract` — usable standalone or as `router`. Hand-writing the agent (above) still works; `ai.router()` is the shortcut.
+
+#### `ai.fanOut()` — voting / self-consistency
+
+`ai.fanOut(unit, n)` spreads one agent/workflow into `n` distinctly-keyed intent entries (`writer1..writerN`) so the supervisor can dispatch them in parallel and a downstream intent can pick the best/majority answer. Spread it into `intents`:
+
+```ts
+ai.supervisor({
+  intents: {
+    ...ai.fanOut(writer, 3),                                   // writer1, writer2, writer3
+    vote: { run: pickMajority, description: "Choose the majority answer." },
+  },
+  route: (ctx) => (ctx.iteration === 0 ? ["writer1", "writer2", "writer3"] : "vote"),
+});
+```
+
+Each key references the same underlying unit; the description defaults to the unit's. Override the key base with `{ keyPrefix }` and the per-entry text with `{ description }`.
+
 ## The `intents` map — five accepted shapes
 
 ```ts
@@ -246,6 +281,16 @@ await supportBot.execute(message, {
 
 `history` precedence: per-call → factory `config.history`. Slice with `historyWindow.{router,agents,ack}` (default ack = 0, router/agents = unbounded) or per-entry `history(ctx)` override.
 
+## Supervisor-level middleware
+
+`middleware: AgentMiddleware[]` fires each middleware's optional `supervisor` hook map (`before` / `after` / `onError`) ONCE around the whole `execute()` / `stream()` / `resume()` run:
+
+```ts
+ai.supervisor({ name: "support", router, intents, middleware: [auditTrail] });
+```
+
+Same onion semantics as the agent pipeline: `before` top-down (return a `SupervisorResult` to short-circuit, throw to abort), `after` / `onError` bottom-up. A middleware without a `supervisor` hook map is skipped — the SAME builtin objects (budget, guardrail, …) can be registered on agents AND here, each declaring whichever level applies. Each needs a unique `name`. See [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md).
+
 ## Iteration model
 
 1. Router/route picks `next` (or `END`).

package/skills/use-ai-memory/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: use-ai-memory
+description: 'Agent memory with ai.memory({...}) — a provider-neutral store with FOUR tiers: WORKING (in-run scratch, recalled by recency), SEMANTIC (durable facts by cosine similarity over a @warlock.js/cache vector driver via .similar()), EPISODIC (durable events, similarity blended with recency), and PROCEDURAL (durable how-tos, similarity blended with reinforcement). remember() / recall() / clear(); wire it into ai.orchestrator({ memory }). Triggers: `ai.memory`, `memory.remember`, `memory.recall`, `memory.clear`, `MemoryContract`, `MemoryConfig`, `MemoryItem`, `RecalledMemory`, `MemoryTier`, `SemanticMemoryConfig`, `EpisodicMemoryConfig`, `ProceduralMemoryConfig`, `working`, `semantic`, `episodic`, `procedural`, `defaultTier`, `threshold`, `recencyWeight`, `halfLifeMs`, `reinforcementWeight`, `injectKey`; ''give the agent memory'', ''remember user preferences'', ''semantic recall'', ''per-session working memory'', ''episodic / event memory'', ''procedural / how-to memory'', ''recency-weighted recall'', ''reinforce a procedure''; typical import `import { ai } from "@warlock.js/ai"`. Skip: orchestrator wiring of the memory — `@warlock.js/ai/run-orchestrator/SKILL.md`; the vector cache driver itself — `@warlock.js/cache/cache-basics/SKILL.md`; embeddings primitive — `@warlock.js/ai/embed-text/SKILL.md`; competing libs `mem0`, `langchain` memory.'
+---
+
+# `ai.memory()` — agent memory store
+
+A single provider-neutral store that holds and retrieves what an agent / orchestrator should remember across turns. Four tiers ship in 4.3.0:
+
+- **working** — in-run scratch threaded across turns of one session. Volatile, unscored, recalled in insertion order (recency). On by default.
+- **semantic** — durable *facts* stored as embeddings in a `@warlock.js/cache` driver, retrieved by cosine similarity via the driver's native `.similar()` — the same delegation the `semanticCache` middleware uses. Activates only when you pass `semantic` config.
+- **episodic** — durable *events*: a timestamped log retrieved by similarity **blended with recency** (recent episodes rank higher). Embedder-backed like semantic; tune with `recencyWeight` + `halfLifeMs`.
+- **procedural** — durable *how-tos*: learned procedures retrieved by similarity **blended with reinforcement** — re-remembering a procedure increments its use count so well-worn procedures rank higher. Tune with `reinforcementWeight`.
+
+> **Still deferred** — decay / forgetting (TTL falloff, eviction). The four tiers above are the full 4.3.0 surface; the `MemoryTier` union widened from `"working" | "semantic"` to add `"episodic" | "procedural"` (a non-breaking change).
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { MemoryCacheDriver } from "@warlock.js/cache";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+const store = new MemoryCacheDriver();
+store.setOptions({});
+
+const mem = ai.memory({
+  semantic: {
+    embedder: openai.embedder({ name: "text-embedding-3-small" }),
+    store,                                  // vector-capable CacheDriver
+    namespace: "ai.memory",                 // key prefix; default "ai.memory"
+  },
+  defaultTier: "semantic",                  // tier a remember() item lands in without its own `tier`
+  k: 5,                                     // default recall count
+  threshold: 0.7,                           // default semantic similarity floor [0,1]
+});
+
+await mem.remember({ text: "User prefers concise answers." });
+const hits = await mem.recall("how should I respond?", { k: 3 });
+```
+
+## Configuration rules (loud at construction)
+
+- **At least one tier must be enabled** — `working` defaults to `true`; `semantic` / `episodic` / `procedural` each activate only when you pass their config. Enabling neither throws (`a memory with no tiers can't store or recall`).
+- **A vector tier with no store throws now** — pass the tier's `store`, or set `ai.config({ defaultStore })` at boot. Applies to `semantic`, `episodic`, and `procedural`. Resolution happens once at construction, not silently on first use (the same loud-now contract `semanticCache` follows).
+- **`defaultTier` must reference an enabled tier** — defaults to `"working"`.
+- Set `working: false` for a durable-only memory (then set `defaultTier` to an enabled vector tier).
+
+## Episodic & procedural tiers
+
+Both are durable, embedder-backed tiers wired like `semantic` (`{ embedder, store? }`), but they re-rank by *time* and *use*:
+
+```ts
+const mem = ai.memory({
+  episodic:   { embedder, store, recencyWeight: 0.3, halfLifeMs: 7 * 24 * 60 * 60 * 1000 },
+  procedural: { embedder, store, reinforcementWeight: 0.3 },
+  defaultTier: "episodic",
+});
+
+await mem.remember({ text: "Refunded order 5821 after a cracked-item complaint.", tier: "episodic" });
+await mem.remember({ id: "esc", text: "Escalate refunds over $500 to a human.", tier: "procedural" });
+await mem.remember({ id: "esc", text: "Escalate refunds over $500 to a human.", tier: "procedural" }); // reinforce → uses 1→2
+```
+
+- **episodic** — stamps each entry with the remember time and decays its recency on an exponential half-life; at equal similarity a recent episode wins. `recencyWeight: 0` → pure similarity. The similarity `threshold` still gates relevance (recency never surfaces an irrelevant-but-recent episode). `now` is injectable for deterministic tests.
+- **procedural** — keeps a per-procedure use count; re-remembering (same `id`, or same text → same derived id) **reinforces** it with diminishing returns. Recall is side-effect-free.
+- Each vector tier defaults to its own namespace (`ai.memory.semantic` / `.episodic` / `.procedural`) so they don't collide on a shared driver; override with `namespace`.
+
+## The three methods
+
+### `remember(items)`
+
+```ts
+await mem.remember({ text: "User is on the Enterprise plan.", tier: "semantic", metadata: { source: "crm" } });
+await mem.remember([{ text: "a" }, { text: "b", tier: "working" }]);   // batch
+```
+
+A `MemoryItem` is `{ text, tier?, id?, metadata? }`. `text` is the only required field — it's what gets embedded (semantic) and surfaced back on recall. `tier` defaults to the factory `defaultTier`. Semantic items are embedded + indexed; working items append to the in-run buffer. **Re-remembering an item whose id (explicit or text-derived) already exists overwrites in place rather than duplicating.** `metadata` is an opaque bag round-tripped verbatim onto the recalled memory.
+
+### `recall(query, options?)`
+
+```ts
+const hits = await mem.recall("which plan is the user on?", {
+  k: 5,              // cap result count (defaults to factory k)
+  threshold: 0.75,   // raise the semantic floor for this call
+  tier: "semantic",  // restrict to one tier; omit to query every enabled tier
+});
+
+for (const hit of hits) {
+  hit.id; hit.text; hit.tier; hit.score; hit.metadata;
+}
+```
+
+Returns `RecalledMemory[]` scored and ordered by descending relevance. By default queries every enabled tier and merges. `score` is in `[0,1]` for **every** tier — cosine similarity (semantic), a recency proxy (working, most-recent = 1), similarity×recency (episodic), or similarity×reinforcement (procedural) — so a mixed recall set sorts on one field without special-casing the tier. Returns `[]` when nothing clears the threshold — never throws on "no hits".
+
+**Memory never mutates the prompt.** `recall()` hands you scored entries; surfacing the recalled text (system prefix, a synthesized "what you remember" block, …) is YOUR call so the injection point stays explicit.
+
+### `clear(tier?)`
+
+```ts
+await mem.clear();            // every tier
+await mem.clear("working");   // just working — e.g. at session end, keeping durable recall
+```
+
+## Wiring into an orchestrator
+
+Pass the store as `ai.orchestrator({ memory })` to recall before each turn's dispatch and remember the settled outcome after. Recalled memories land in `ctx.context[injectKey]` (default `"memories"`). See [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) for the per-turn `memory` field, `recall.k: 0` (write-only), `remember: false` (read-only), and `rememberTier`.
+
+## Picking a vector driver
+
+The semantic tier delegates similarity entirely to the `CacheDriver`:
+- **Dev / tests** — `new MemoryCacheDriver()` (zero config, O(N) scan; fine up to a few thousand entries).
+- **Production** — a driver with a real ANN index: `pg` with pgvector, `redis` with RediSearch.
+
+Drivers without similarity support throw `CacheUnsupportedError` from `set({ vector })` / `similar()`. See [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md).
+
+## See also
+
+- [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) — the `memory` field on a session
+- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — the embedder the semantic tier needs
+- [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) — `semanticCache`, the sibling `.similar()` consumer
+- [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md) — vector driver catalog

package/skills/write-system-prompt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-system-prompt
-description: 'Compose system prompts via ai.systemPrompt() / ai.persona() / ai.instruction() — immutable builders with {{placeholder}} substitution. Triggers: `ai.systemPrompt`, `ai.persona`, `ai.instruction`, `SystemPromptBlockContract`, `PersonaContract`, `InstructionContract`, `placeholders`, `{{placeholder|default}}`; ''write a system prompt'', ''compose persona + instructions'', ''per-call prompt override'', ''mustache placeholder''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent factory wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain` `PromptTemplate`, raw f-strings.'
+description: 'Compose system prompts via ai.systemPrompt() / ai.persona() / ai.instruction() — immutable builders with {{placeholder}} substitution, plus ai.systemPrompt.fromFile(path) to seed from a file read once at construction. Triggers: `ai.systemPrompt`, `ai.systemPrompt.fromFile`, `ai.persona`, `ai.instruction`, `SystemPromptBlockContract`, `PersonaContract`, `InstructionContract`, `placeholders`, `{{placeholder|default}}`, `InvalidRequestError`; ''write a system prompt'', ''compose persona + instructions'', ''prompt from a file'', ''per-call prompt override'', ''mustache placeholder''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent factory wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain` `PromptTemplate`, raw f-strings.'
 ---
 
 # System prompts — immutable builders
@@ -15,6 +15,7 @@ import { ai } from "@warlock.js/ai";
 ai.systemPrompt();                  // empty — chain .persona(), .instruction() onto it
 ai.systemPrompt("literal text");    // one-shot string form
 ai.systemPrompt([block1, block2]);  // array form — blocks render in declaration order
+ai.systemPrompt.fromFile(path);     // seed from a file read once at construction
 
 ai.persona(text);                   // PersonaContract block
 ai.instruction(text);               // InstructionContract block
@@ -51,6 +52,18 @@ ai.systemPrompt([
 ]);
 ```
 
+### From a file — `ai.systemPrompt.fromFile(path)`
+
+Read a prompt template from disk ONCE, synchronously, at construction. The file's UTF-8 contents seed one instruction block — so `{{placeholders}}` inside the file resolve at `resolve()` time and the result forks with further `.persona()` / `.instruction()` calls:
+
+```ts
+const prompt = ai.systemPrompt.fromFile("./prompts/support-agent.md");
+const localized = prompt.instruction("Respond in {{language|English}}.");
+localized.resolve({ language: "Arabic" });
+```
+
+One-shot by design (never re-read on `resolve()`). Throws `InvalidRequestError` when the file can't be read — a path typo fails loudly at construction instead of silently producing an empty prompt. `ai.systemPrompt.fromFile(path)` === `SystemPrompt.fromFile(path)`.
+
 ## Block ordering
 
 `SystemPrompt` stores `blocks: readonly SystemPromptBlockContract[]` — not separate persona + instructions fields. Rendering honors insertion order.