@warlock.js/ai 4.1.1

package/llms.txt

@@ -0,0 +1,20 @@
+# Warlock AI
+
+> Package: `@warlock.js/ai`
+
+> Core @warlock.js AI framework — contracts, agent, workflow, supervisor
+
+## Skills
+
+- [ai-basics](@warlock.js/ai/ai-basics/SKILL.md): Start with @warlock.js/ai — provider-agnostic core for agents / tools / workflows / supervisors. 4-primitive ladder (agent → workflow → supervisor → orchestrator v2). Every primitive returns {data, error, usage, report}. Triggers: `ai.agent`, `ai.tool`, `ai.workflow`, `ai.supervisor`, `ai.systemPrompt`, `ExecuteResult`, `BaseReport`, `AIError`; 'which AI primitive do I use', 'what is warlock ai', 'pick an AI skill'; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent details — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain`, `llamaindex`, `ai` (Vercel SDK); raw `openai` / `@anthropic-ai/sdk`.
+- [attach-ai-middleware](@warlock.js/ai/attach-ai-middleware/SKILL.md): Wire agent middleware — ai.middleware.budget (token / USD caps), ai.middleware.guardrail (pre / post content checks), ai.middleware.semanticCache (exact + vector cache), plus authoring custom hooks (execute / trip / tool). Triggers: `ai.middleware.budget`, `ai.middleware.guardrail`, `ai.middleware.semanticCache`, `ai.middleware.compose`, `ai.middleware.forTool`, `AgentMiddleware`, `BudgetExceededError`, `GuardrailViolationError`; 'cap token cost', 'block pii in prompts', 'semantic cache before LLM', 'write custom hook'; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent lifecycle — `@warlock.js/ai/run-ai-agent/SKILL.md`; cache drivers — `@warlock.js/ai/persist-ai-data/SKILL.md`; competing libs `langchain` callbacks.
+- [define-ai-tool](@warlock.js/ai/define-ai-tool/SKILL.md): Define tools with ai.tool({...}) — typed validated async functions the model can call. Covers name / description / action / mode (feedback / silent) / input / execute, `ctx.artifacts` side-channel, `ToolExecutionError`. Triggers: `ai.tool`, `ToolContract`, `ToolContext`, `ToolCall`, `ToolExecutionError`, `artifactsSchema`, `mode: "silent"`, `workflow.asTool`; 'define a tool', 'wire tool into agent', 'tool input validation', 'side-channel artifacts'; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent loop — `@warlock.js/ai/run-ai-agent/SKILL.md`; supervisor artifacts — `@warlock.js/ai/run-supervisor/SKILL.md`; competing libs `langchain` tools, raw `openai` function-calling.
+- [embed-text](@warlock.js/ai/embed-text/SKILL.md): Text-to-vector via sdk.embedder({...}) — embed(string) for single, embedMany(string[]) for batch. Peer primitive on the SDK adapter, not wired into agents. Compose into RAG tools, workflow run steps, or ai.middleware.semanticCache. Triggers: `sdk.embedder`, `EmbedderContract`, `embedder.embed`, `embedder.embedMany`, `EmbeddingResult`, `EmbeddingBatchResult`, `dimensions`; 'embed text', 'build RAG tool', 'populate vector store', 'embedding batch'; typical import `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: cache similarity — `@warlock.js/cache/use-cache-similarity/SKILL.md`; pgvector queries — `@warlock.js/cascade/search-by-vector/SKILL.md`; competing libs `langchain` embeddings, raw `openai.embeddings.create`.
+- [handle-ai-errors](@warlock.js/ai/handle-ai-errors/SKILL.md): Typed AIError hierarchy with stable code strings + coarse category for retry-policy dispatch. execute() never throws — errors surface via result.error. Triggers: `AIError`, `ProviderRateLimitError`, `ProviderAuthError`, `ContextLengthExceededError`, `ContentFilterError`, `SchemaValidationError`, `ToolExecutionError`, `WorkflowDriftError`, `BudgetExceededError`, `GuardrailViolationError`, `error.code`, `error.category`; 'handle ai error', 'retry on rate limit', 'branch on error code', 'build fallback ladder'; typical import `import { AIError } from "@warlock.js/ai"`. Skip: log surfacing — `@warlock.js/ai/log-ai-calls/SKILL.md`; native `try / catch` on raw `openai`.
+- [log-ai-calls](@warlock.js/ai/log-ai-calls/SKILL.md): Framework logging delegated to @warlock.js/logger — every primitive emits via the log singleton, configure channels / levels / redaction once at boot. Four-arg call convention (module, action, message, context). Triggers: `log.configure`, `log.setMinLevel`, `log.setChannels`, `ConsoleLog`, `FileLog`, `LogChannel`, `redact.paths`, `ai.agent.<name>` / `ai.workflow.<name>` / `ai.supervisor.<name>` modules; 'configure ai logging', 'mask prompts in logs', 'silence logs in tests', 'capture log entries'; typical import `import { log } from "@warlock.js/logger"`. Skip: error hierarchy — `@warlock.js/ai/handle-ai-errors/SKILL.md`; competing libs `pino`, `winston`, `console.log`.
+- [persist-ai-data](@warlock.js/ai/persist-ai-data/SKILL.md): 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`.
+- [pick-ai-provider](@warlock.js/ai/pick-ai-provider/SKILL.md): 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`.
+- [run-ai-agent](@warlock.js/ai/run-ai-agent/SKILL.md): 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`.
+- [run-ai-workflow](@warlock.js/ai/run-ai-workflow/SKILL.md): 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`.
+- [run-supervisor](@warlock.js/ai/run-supervisor/SKILL.md): 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`.
+- [write-system-prompt](@warlock.js/ai/write-system-prompt/SKILL.md): 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.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@warlock.js/ai",
+  "description": "Core @warlock.js AI framework — contracts, agent, workflow, supervisor",
+  "keywords": [
+    "warlock",
+    "ai"
+  ],
+  "author": "Hasan Zohdy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/warlockjs/ai"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@warlock.js/cache": "*",
+    "@warlock.js/logger": "*"
+  },
+  "version": "4.1.1",
+  "main": "./cjs/index.cjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./esm/index.d.mts",
+        "default": "./cjs/index.cjs"
+      }
+    }
+  }
+}

package/skills/README.md

@@ -0,0 +1,53 @@
+# `@warlock.js/ai` — skills index
+
+Per-task skills. All cross-references use the form `@warlock.js/<pkg>/<skill>/SKILL.md`.
+
+## Skills
+
+### [`ai-basics/`](./ai-basics/SKILL.md)
+
+Start with @warlock.js/ai — provider-agnostic core for agents / tools / workflows / supervisors. 4-primitive ladder (agent → workflow → supervisor → orchestrator v2). Every primitive returns {data, error, usage, report}. Persistence + logging delegated. Load when importing @warlock.js/ai, picking a primitive, or choosing which AI skill to load.
+
+### [`attach-ai-middleware/`](./attach-ai-middleware/SKILL.md)
+
+Wire agent middleware — ai.middleware.budget (token / USD caps), ai.middleware.guardrail (pre / post content checks), ai.middleware.semanticCache (exact + vector cache via @warlock.js/cache), plus authoring custom hooks (execute / trip / tool). Load when capping cost / tokens, gating input or output, hitting semantic cache before the LLM, or writing custom hooks.
+
+### [`define-ai-tool/`](./define-ai-tool/SKILL.md)
+
+Define tools with ai.tool({...}) — typed validated async functions the model can call. Covers name / description / action / mode (feedback / silent) / input / execute, ctx.artifacts side-channel, ToolExecutionError. Load when wiring tools into an agent, authoring ai.tool, inspecting result.report.toolCalls, or debugging a ToolExecutionError.
+
+### [`embed-text/`](./embed-text/SKILL.md)
+
+Text-to-vector via sdk.embedder({...}) — embed(string) for single, embedMany(string[]) for batch. Peer primitive on the SDK adapter, not wired into agents. Compose into RAG tools, workflow run steps, or ai.middleware.semanticCache. Load when calling sdk.embedder, building RAG tools, or populating a vector store.
+
+### [`handle-ai-errors/`](./handle-ai-errors/SKILL.md)
+
+Typed AIError hierarchy with stable code strings + coarse category for retry-policy dispatch. execute() never throws — errors surface via result.error. Load when inspecting result.error, branching on error.code / error.category, designing retry / fallback logic, or wrapping framework errors in HTTP errors.
+
+### [`log-ai-calls/`](./log-ai-calls/SKILL.md)
+
+Framework logging delegated to @warlock.js/logger — every primitive emits via the log singleton, configure channels / levels / redaction once at boot. Four-arg call convention (module, action, message, context). Load when configuring AI logging, masking prompts / API keys / PII, picking which events surface, or filtering by module / action.
+
+### [`persist-ai-data/`](./persist-ai-data/SKILL.md)
+
+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. Load when configuring snapshotStore, calling resume(runId), or handling WorkflowDriftError / SupervisorDriftError.
+
+### [`pick-ai-provider/`](./pick-ai-provider/SKILL.md)
+
+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. Load when picking a provider, deciding between OpenAI direct vs OpenRouter, or understanding which adapter supports a feature (vision / structured / embeddings).
+
+### [`run-ai-agent/`](./run-ai-agent/SKILL.md)
+
+Build agents with ai.agent({...}) — the single-LLM-turn primitive. Covers execute / stream, attachments, structured output, placeholders, events, AgentResult envelope, streamingToolGuard. Load when calling ai.agent(...), reading AgentResult, wiring options.output / attachments / repair, or streaming.
+
+### [`run-ai-workflow/`](./run-ai-workflow/SKILL.md)
+
+Build durable resumable pipelines with ai.workflow({...}) + ai.step({...}) — lifecycle (skip / before / run|agent|parallel / output / after / nextStep), routing on success / failure, retry with backoff, parallel groups, cancel via AbortSignal, snapshot resume. Load when authoring ai.workflow, defining steps, handling WorkflowDriftError, or resuming a run.
+
+### [`run-supervisor/`](./run-supervisor/SKILL.md)
+
+Multi-intent routing with ai.supervisor({...}) — classifier (iter-0 dispatch), router agent OR route callback (iter 1+), intents as agents / workflows / callbacks, fan-out, evaluate quality loop, ack receptionist, ctx.intents.X.execute composition. Load when routing one user input across a fixed roster of specialists.
+
+### [`write-system-prompt/`](./write-system-prompt/SKILL.md)
+
+Compose system prompts via ai.systemPrompt() / ai.persona() / ai.instruction() — immutable builders with {{placeholder}} substitution. Load when building or chaining system prompts, mixing persona + instruction blocks, using {{placeholder}}, or doing per-call override via agent.execute(input, {systemPrompt}).

package/skills/ai-basics/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ai-basics
+description: 'Start with @warlock.js/ai — provider-agnostic core for agents / tools / workflows / supervisors. 4-primitive ladder (agent → workflow → supervisor → orchestrator v2). Every primitive returns {data, error, usage, report}. Triggers: `ai.agent`, `ai.tool`, `ai.workflow`, `ai.supervisor`, `ai.systemPrompt`, `ExecuteResult`, `BaseReport`, `AIError`; ''which AI primitive do I use'', ''what is warlock ai'', ''pick an AI skill''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent details — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain`, `llamaindex`, `ai` (Vercel SDK); raw `openai` / `@anthropic-ai/sdk`.'
+---
+
+# AI foundations
+
+Provider-agnostic core for building AI primitives in TypeScript. Adapters live in sibling packages — all five first-party adapters ship today: `@warlock.js/ai-openai`, `-anthropic`, `-bedrock`, `-google`, `-ollama`.
+
+> This skill is the AI **map** — read it first, then load the specific skill for the task.
+
+## The 4-primitive ladder
+
+```
+ai.agent()        →  single task, stateless                    [shipped]
+ai.workflow()     →  static predefined steps, resumable        [shipped]
+ai.supervisor()   →  multi-agent dynamic routing, resumable    [shipped]
+ai.orchestrator() →  stateful — owns session/history/ctx       (v2)
+```
+
+Each primitive is an escape hatch to the next level of complexity. Users start low, graduate upward only when needed. Every primitive returns the same result envelope — canonical destructure `{ data, error, usage, report }` (the shared `BaseResult` guarantees `usage` + optional `error`; each primitive adds `data` + `report`). Workflows and supervisors expose `.asTool()` so an agent can call them inside its tool loop; compose freely.
+
+## Foundations
+
+1. **Public API is functional factories.** Use `ai.agent({...})`, `ai.tool({...})`, `ai.workflow({...})`, `ai.step({...})`, `ai.supervisor({...})`, `ai.systemPrompt()`, `ai.persona()`, `ai.instruction()`. Never `new Agent()`.
+2. **Adapter entry points are classes.** `new OpenAISDK({ apiKey })` from [`@warlock.js/ai-openai/setup-openai/SKILL.md`](@warlock.js/ai-openai/setup-openai/SKILL.md).
+3. **Schemas everywhere are `StandardSchemaV1<T>`.** Recommended: [`@warlock.js/seal`](@warlock.js/seal/seal-basics/SKILL.md) — `v.object({...})`. Zod, Valibot, hand-rolled all interop.
+4. **`execute()` never throws.** Errors funnel into `result.error` as a typed `AIError` subclass. Same for `stream.result`, `workflow.execute()` / `resume()`, `supervisor.execute()` / `resume()`. See [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
+5. **Each `execute()` call is isolated.** Fresh internal execution instance per call.
+6. **Every error is an `AIError`.** Plain `Error` never leaks. Branch on `error.code` (stable string), `error.category` (coarse), or `instanceof`.
+7. **Result shape is uniform.** `{ data, error, usage, report }` across every primitive. `report` is a recursive `BaseReport` tree.
+8. **Persistence is delegated** to `@warlock.js/cache`. See [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md).
+9. **Logging is delegated** to `@warlock.js/logger`. See [`@warlock.js/ai/log-ai-calls/SKILL.md`](@warlock.js/ai/log-ai-calls/SKILL.md).
+10. **`name` on agents is optional.** Anonymous agents get a deterministic `anon_<provider>_<model>` fingerprint.
+11. **Every report carries lineage** — `rootRunId` + `parentRunId` + `reportSchemaVersion: 1`.
+12. **`version` is dev-curated, `sessionId` is caller-supplied** — both propagate through nested reports.
+13. **Cost is computed at emit time as a per-channel breakdown.** Set `pricing` on the model adapter; `Usage.cost` carries `{ input, output, cachedInput?, cachedOutput? }` per trip, rolled up bottom-up.
+14. **Every `AIError` carries a coarse `category`** for retry-policy dispatch (`rate-limit`, `auth`, `content-filter`, `schema`, etc.).
+
+## 30-second example
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+const myAgent = ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) });
+
+const { data, text, report, usage, error } = await myAgent.execute("Hello");
+
+if (error) /* typed AIError */ ;
+console.log(text, usage.total, report.duration);
+```
+
+## Pick a skill
+
+| If the task is about… | Load |
+| --- | --- |
+| `ai.agent({...})` — single-LLM-turn primitive, structured output, streaming, attachments | [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) |
+| `ai.tool({...})` — typed validated functions the model can call | [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) |
+| `ai.systemPrompt()` / `ai.persona()` / `ai.instruction()` — composable prompts with placeholders | [`@warlock.js/ai/write-system-prompt/SKILL.md`](@warlock.js/ai/write-system-prompt/SKILL.md) |
+| `ai.workflow({...})` — durable resumable pipelines with steps, routing, retry | [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) |
+| `ai.supervisor({...})` — multi-intent routing, fan-out, evaluate loops | [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) |
+| `sdk.embedder({...})` — text-to-vector for RAG tools, vector ingest | [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) |
+| Agent middleware — `budget` / `guardrail` / `semanticCache` + custom hooks | [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) |
+| Snapshot resume + semantic cache via `@warlock.js/cache` | [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) |
+| Configuring framework logging | [`@warlock.js/ai/log-ai-calls/SKILL.md`](@warlock.js/ai/log-ai-calls/SKILL.md) |
+| `AIError` hierarchy, `error.code` / `error.category`, retry patterns | [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) |
+| Choosing a provider adapter (OpenAI / OpenRouter / Anthropic / Bedrock / Ollama) | [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) |
+
+## Package layout
+
+```
+@warlock.js/ai               — agent, tool, workflow, supervisor, system-prompt, errors, middleware
+@warlock.js/ai-openai        — OpenAI SDK adapter (model + embedder); also OpenRouter / Azure via baseURL
+@warlock.js/ai-anthropic     — Anthropic / Claude adapter (Messages API)
+@warlock.js/ai-bedrock       — AWS Bedrock adapter (Converse API + Titan embeddings)
+@warlock.js/ai-google        — Google / Gemini adapter (@google/genai + batch embeddings)
+@warlock.js/ai-ollama        — Ollama adapter for local models
+```
+
+Runtime deps: `@warlock.js/cache` (persistence), `@warlock.js/logger` (logging), `@warlock.js/seal` (recommended schema lib).
+
+## When NOT to use this skill
+
+- Code importing `openai` / `@anthropic-ai/sdk` directly without going through `@warlock.js/ai` — those are raw provider SDKs.
+- Generic JS/TS questions unrelated to agent / tool / workflow / supervisor wiring.
+
+## Design references
+
+- `domains/ai/design/decisions.md` — locked architectural decisions with rationale
+- `domains/ai/design/workflow.md` — workflow spec
+- `domains/ai/design/supervisor.md` — supervisor spec
+- `domains/ai/design/execution-result.md` — unified `ExecuteResult` + recursive `BaseReport` tree
+- `domains/ai/conventions/errors.md` — framework-vs-consumer-app error split

package/skills/attach-ai-middleware/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: attach-ai-middleware
+description: 'Wire agent middleware — ai.middleware.budget (token / USD caps), ai.middleware.guardrail (pre / post content checks), ai.middleware.semanticCache (exact + vector cache), plus authoring custom hooks (execute / trip / tool). Triggers: `ai.middleware.budget`, `ai.middleware.guardrail`, `ai.middleware.semanticCache`, `ai.middleware.compose`, `ai.middleware.forTool`, `AgentMiddleware`, `BudgetExceededError`, `GuardrailViolationError`; ''cap token cost'', ''block pii in prompts'', ''semantic cache before LLM'', ''write custom hook''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent lifecycle — `@warlock.js/ai/run-ai-agent/SKILL.md`; cache drivers — `@warlock.js/ai/persist-ai-data/SKILL.md`; competing libs `langchain` callbacks.'
+---
+
+# Middleware — agent-level pipeline
+
+Cross-cutting concerns wrapped around an agent run at three granularities: `execute`, `trip`, `tool`. One middleware = one object. Ships with `budget`, `guardrail`, and `semanticCache` built-ins.
+
+## Install order at a glance
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+import { cache } from "@warlock.js/cache";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+ai.config({ defaultStore: cache.driver("redis", { client: redisClient }) });
+
+const myAgent = ai.agent({
+  model: openai.model({ name: "gpt-4o" }),
+  middleware: [
+    ai.middleware.semanticCache({
+      embedder: openai.embedder({ name: "text-embedding-3-small" }),
+      threshold: 0.95,
+    }),
+    ai.middleware.budget({ maxTokens: 50_000 }),
+    ai.middleware.guardrail({
+      inputCheck: async (text) =>
+        text.match(/\bSSN\b/) ? { ok: false, reason: "pii" } : { ok: true },
+    }),
+  ],
+});
+```
+
+**Canonical order: `[cache, budget, guardrail, observability]`** — see "Ordering invariants" below.
+
+## `ai.middleware.budget(options)`
+
+Cumulative token / USD cap across all trips of one execution.
+
+```ts
+ai.middleware.budget({
+  maxTokens: 50_000,
+  maxCostUSD: 0.5,
+  pricing: { "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 } },
+  onExceeded: "abort", // or "warn"
+});
+```
+
+Breach → `BudgetExceededError` on `result.error`. Inspect `error.unit` (`"tokens" | "usd"`), `error.limit`, `error.actual`. Warn mode logs and continues — useful for measuring before enforcing.
+
+USD only fires when both `maxCostUSD` AND a matching `pricing[modelName]` entry exist.
+
+## `ai.middleware.guardrail(options)`
+
+Pre / post content checks.
+
+```ts
+ai.middleware.guardrail({
+  inputCheck: async (text, ctx) =>
+    text.includes("forbidden") ? { ok: false, reason: "policy-1" } : { ok: true },
+  outputCheck: async (text) =>
+    text.length > 10_000 ? { ok: false, reason: "too-long" } : { ok: true },
+  name: "pii-guardrail",
+});
+```
+
+Rejection → `GuardrailViolationError` with `phase: "input" | "output"` and the configured `reason`. Output checks fire BEFORE tool dispatch — a rejected response means the tools it requested are never invoked.
+
+Checks run on every trip (including tool follow-ups and repair attempts). Gate only the first trip via `ctx.tripIndex === 0`.
+
+## `ai.middleware.semanticCache(options)`
+
+Two-tier cache — exact-match key first, vector similarity second. Delegates to any vector-capable `CacheDriver`.
+
+```ts
+ai.middleware.semanticCache({
+  embedder: openai.embedder({ name: "text-embedding-3-small" }),
+  // store optional — falls back to ai.config({ defaultStore })
+  store: cache.driver("pg", {
+    client: pgPool,
+    vector: { dimensions: 1536, index: "hnsw" },
+  }),
+  threshold: 0.95,
+  ttlMs: 60 * 60 * 1000,
+  namespace: "support-faq",
+});
+```
+
+**Driver requirements.** Must support `similar()` — `pg` (with `vector` config), `redis` (with RediSearch), or memory drivers for dev. Without similarity → `CacheUnsupportedError` at first vector op.
+
+**How it works.**
+- **Exact-match** — FNV hash over the message list. `store.get(hash)` returns an instant hit.
+- **Vector-match** — embeds the prompt, calls `store.similar(vector, { topK: 1, threshold })`. Driver uses its native ANN index.
+- **Hits** return a synthetic `ModelResponse` with `usage: { input: 0, output: 0, total: 0 }`.
+- **Writes** happen at `trip.after` on miss.
+- **Trip-zero only** — only first-trip responses are cached. Tool-using loops never serve cached tool-call responses (would infinite-loop).
+- **Never use memory drivers in production** — linear scan per query.
+
+## Writing your own middleware
+
+One object. Any subset of three hook maps.
+
+```ts
+import type { AgentMiddleware } from "@warlock.js/ai";
+
+const latencyLogger: AgentMiddleware = {
+  name: "latency-logger",
+  execute: {
+    before(ctx) {
+      ctx.state.set("latency.start", performance.now());
+    },
+    after(ctx, result) {
+      const start = ctx.state.get("latency.start") as number;
+      console.log(`agent ${ctx.agent.name} finished in ${performance.now() - start}ms`);
+    },
+  },
+  trip: {
+    before(ctx) {
+      ctx.state.set(`latency.trip.${ctx.tripIndex}.start`, performance.now());
+    },
+    after(ctx) {
+      const start = ctx.state.get(`latency.trip.${ctx.tripIndex}.start`) as number;
+      console.log(`  trip ${ctx.tripIndex}: ${performance.now() - start}ms`);
+    },
+  },
+};
+```
+
+### Rules
+
+- **Never close over mutable state.** Use `ctx.state` — fresh per `execute()` call.
+- **Abort with a typed `AIError` subclass.** Never `throw new Error(...)`.
+- **Short-circuit by returning from `before`.** Return the level's result type — the pipeline skips the real work and outer `after` hooks still run on your synthetic value.
+- **`onError` is opt-in recovery.** Return a value to recover; return `void` to let the error propagate.
+- **`log: false`** suppresses framework debug emission for that middleware (the middleware itself still runs).
+
+## Ordering invariants — read before shipping
+
+1. **Cache MUST be outermost when guardrails are present.** Guardrail `trip.after` throws to reject bad output — but `after` hooks run bottom-up. If guardrail is outside the cache, rejection fires AFTER the cache has written the bad response. Canonical order `[cache, budget, guardrail]` keeps rejected outputs out of the cache.
+2. **Budget before guardrails.** Guardrails may call classifiers with their own token costs.
+3. **Observability last.** It should see the final decision every other middleware made.
+
+## Helpers
+
+### `ai.middleware.compose(...sources)`
+
+Flatten multiple sources into one ordered array. No sorting, no dedup.
+
+```ts
+ai.agent({
+  model,
+  middleware: ai.middleware.compose(standardStack, toolRules, auditMiddleware),
+});
+```
+
+### `ai.middleware.forTool(name | names, middleware)`
+
+Scope `tool.*` hooks to specific tool names. `execute` and `trip` hooks pass through.
+
+```ts
+const scoped = ai.middleware.forTool(["paid_api", "expensive_db"], toolRateLimit({ maxCalls: 5 }));
+```
+
+## Caveats
+
+- **`tool.onError` is almost-never-useful.** `ToolContract.invoke()` never throws — errors are captured into `result.error`. `tool.onError` only fires when another middleware's `tool.before`/`tool.after` itself throws. For "the tool itself failed," branch on `result.error` in a `tool.after`.
+- **Middleware does NOT observe unregistered tool calls.** When the model asks for a tool the agent wasn't configured with, the pipeline is bypassed and a failed `ToolCall` is recorded directly.
+- **`name` must be unique** across an agent's middleware array.
+- **Middleware state does NOT cross `agent.execute()` boundaries.** One execute → one fresh `ctx.state`.
+
+## Workflow + middleware — what works today (v1)
+
+- Inside a workflow step with `agent: myAgent` — the agent's own middleware fires normally.
+- `workflow.asTool()` called from an agent — the calling agent's `tool`-level middleware wraps the workflow.
+- Step-level / workflow-level / supervisor-level middleware does NOT exist yet.
+
+## See also
+
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — agent lifecycle the middleware wraps
+- [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) — `defaultStore` for semantic cache
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `BudgetExceededError` / `GuardrailViolationError`

package/skills/define-ai-tool/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: define-ai-tool
+description: 'Define tools with ai.tool({...}) — typed validated async functions the model can call. Covers name / description / action / mode (feedback / silent) / input / execute, `ctx.artifacts` side-channel, `ToolExecutionError`. Triggers: `ai.tool`, `ToolContract`, `ToolContext`, `ToolCall`, `ToolExecutionError`, `artifactsSchema`, `mode: "silent"`, `workflow.asTool`; ''define a tool'', ''wire tool into agent'', ''tool input validation'', ''side-channel artifacts''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent loop — `@warlock.js/ai/run-ai-agent/SKILL.md`; supervisor artifacts — `@warlock.js/ai/run-supervisor/SKILL.md`; competing libs `langchain` tools, raw `openai` function-calling.'
+---
+
+# `ai.tool()` — typed tool factory
+
+Tools are async functions the model can call by name during a trip loop. Define one with `ai.tool()`, pass it in `agent({ tools: [...] })`, and the agent handles dispatch, input validation, and error surfacing automatically.
+
+## Factory shape
+
+```ts
+ai.tool({
+  name: string,                                 // stable identifier
+  description: string,                          // sent to the model
+  version?: string,                             // mirrored onto tool reports
+  action?: string | ((input: TInput) => string), // UI label for streaming UX
+  mode?: "feedback" | "silent",                 // result feedback control
+  input: StandardSchemaV1<TInput>,              // validated before execute
+  execute: (input: TInput, ctx?: ToolContext) => Promise<unknown>,
+});
+```
+
+Returns a `ToolContract<TInput, TOutput>`. One tool can be attached to many agents.
+
+## `description` vs `action`
+
+Two roles, two fields:
+
+- **`description`** — what the LLM reads when deciding whether to call this tool.
+- **`action`** — present-progressive UI string surfaced to humans on `agent.tool.calling` / `agent.tool.called` events.
+
+```ts
+ai.tool({
+  name: "search_catalog",
+  description: "Search the product catalog. Returns matching products with SKU, name, price.",
+  action: ({ query }) => `Searching the catalog for "${query}"`,
+  input: v.object({ query: v.string() }),
+  execute: async ({ query }) => searchProducts(query),
+});
+```
+
+Two forms supported: static string or function. Function form runs after input validation; throws are swallowed (UI strings aren't worth aborting LLM dispatch over).
+
+## Schema via Standard Schema V1
+
+Input is typed as `StandardSchemaV1<T>`. Recommended: `@warlock.js/seal`. Zod / Valibot / hand-rolled all interop.
+
+```ts
+import { v } from "@warlock.js/seal";
+
+const searchTool = ai.tool({
+  name: "search",
+  description: "Search the docs index",
+  input: v.object({
+    query: v.string(),
+    limit: v.number().optional(),
+  }),
+  execute: async ({ query, limit }) => fetchDocs(query, limit ?? 10),
+});
+```
+
+## Input validation is automatic
+
+The agent calls `input["~standard"].validate(rawArgs)` before invoking `execute`. Validation failures **do not throw** — the failure is recorded on the trip's `ToolCall.error` and fed back to the model on the next trip as a tool error message. The model gets a chance to correct and retry within the bounded `maxTrips` loop.
+
+## What gets returned to the model
+
+Whatever your `execute` resolves with is `JSON.stringify`'d and sent back as the next trip's `tool` message. Strings pass through unchanged. Throw (or return a rejected promise) to signal failure — the agent records the error on `ToolCall.error` and tells the model.
+
+## `mode` — feedback vs silent
+
+Default `"feedback"`.
+
+- **`mode: "feedback"`** (default) — standard round-trip. Result feeds back into next trip; the model reads it and replies. Use for tools whose output the model needs to narrate: `search_catalog`, `search_knowledge_base`, `ask_questions`.
+- **`mode: "silent"`** — fire-and-forget. Result NOT fed back to the model. When EVERY tool call in a single generation is silent, the agent loop terminates after dispatch. Use for pure side-effect tools: `update_state`, `set_locale`, telemetry pings.
+
+```ts
+ai.tool({
+  name: "update_state",
+  description: "Persist customer slot-fill across turns.",
+  mode: "silent",
+  input: v.object({ preferences: v.array(v.string()).optional() }),
+  execute: async (patch, ctx) => {
+    ctx.artifacts.stateUpdate = patch;
+    return { ok: true };  // model never sees this
+  },
+});
+```
+
+**All-silent rule.** The loop terminates only when EVERY tool call this trip is silent. Silent + feedback in the same generation → loop continues (the feedback tool still round-trips, the silent one piggybacks).
+
+**Constraints for silent tools.** MUST be cheap + fast (HTTP request still open until dispatch resolves), should be idempotent (no surface to communicate failure to the model), side-effect-only.
+
+## Tool context — `ctx.artifacts` side-channel
+
+`execute` accepts an optional **second argument** — a `ToolContext` with a mutable `artifacts` bag and the dispatch's `signal`. Use it to capture system-only data (renderable blocks, citations, files, telemetry, soft signals) that the LLM should NOT see.
+
+```ts
+ai.tool({
+  name: "search_catalog",
+  input: v.object({ query: v.string() }),
+  execute: async (input, ctx) => {
+    const items = await searchItems(input.query);
+
+    // Side-channel — never reaches the LLM.
+    ctx.artifacts.blocks ??= [];
+    ctx.artifacts.blocks.push({ type: "items", itemIds: items.map(i => i.id) });
+
+    // LLM-visible — what the agent reasons over.
+    return { total: items.length };
+  },
+});
+```
+
+Under a supervisor: bag starts empty per iteration, accumulates writes from all tool calls, merges into state at iteration end (auto-spread by default; `finalizeArtifacts` for concat / dedupe). See [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md).
+
+Standalone (no supervisor): framework supplies `{ artifacts: {} }`. Mutations are harmless no-ops.
+
+## Type contract for artifacts
+
+The supervisor declares an `artifactsSchema`; tools registered to it inherit typed `ctx.artifacts.*`. Standalone tools fall back to `Record<string, unknown>`.
+
+```ts
+ai.supervisor({
+  artifactsSchema: v.object({
+    blocks: v.array(blockSchema).optional(),
+    citations: v.array(citationSchema).optional(),
+  }),
+  // tools see ctx.artifacts typed as { blocks?, citations? }
+});
+```
+
+## Error categorization
+
+`invoke()` never throws — failures surface on the returned `error` field, and the agent records them on the dispatch's `ToolCall.error`. The error class depends on what failed:
+
+- **Input schema rejected the model's args** → `SchemaValidationError` (`code: "SCHEMA_VALIDATION_FAILED"`), `issues` preserved. NOT wrapped in `ToolExecutionError`.
+- **Schema's own `validate()` threw** → `SchemaValidationError` wrapping the cause.
+- **Your `execute()` threw** → `ToolExecutionError` (`code: "TOOL_EXEC_FAILED"`, category `tool`) with `toolName`, and the thrown value on `error.cause`.
+
+`ToolExecutionError` carries `toolName` always; `tripIndex` is stamped by the agent that dispatched it. The validation failure is fed back to the model on the next trip so it can correct within the `maxTrips` loop.
+
+See [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
+
+## Inspecting tool calls
+
+```ts
+const result = await myAgent.execute("Pick a city and tell me the weather.");
+
+const toolCalls = result.report.children.filter((c) => c.type === "tool");
+
+for (const call of toolCalls) {
+  console.log(call.tripIndex, call.name, call.input, call.output, call.duration);
+}
+```
+
+Tool dispatches are child `BaseReport` nodes on `report.children` (not a separate `report.toolCalls` field) — filter by `c.type === "tool"`. Each `ToolCall` is a `BaseReport & { type: "tool", tripIndex, input, output?, error? }`, so it carries `name` / `startedAt` / `endedAt` / `duration` from the report base.
+
+## Events
+
+- `agent.tool.calling` — `{ tool, input, tripIndex }`
+- `agent.tool.called` — `ToolCall & { tool }` (full record)
+- `agent.tool.failed` — `{ tool, input, error, tripIndex }`
+
+Subscribe at factory / instance / per-call.
+
+## Pattern — workflow as a tool
+
+```ts
+const wrapped = myWorkflow.asTool({
+  description: "Run the catalog ingestion workflow",
+  inputSchema: v.object({ url: v.string() }),
+});
+
+const agent = ai.agent({ model, tools: [wrapped] });
+```
+
+Workflow errors surface as `ToolExecutionError` with `cause` pointing at the original `WorkflowError` subclass.
+
+## See also
+
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — how tools plug into the trip loop
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — error hierarchy
+- [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — artifacts under a supervisor
+- [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — `workflow.asTool()` composition