@warlock.js/ai 4.4.0 → 4.6.0

package/skills/rag-loaders-and-stores/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: rag-loaders-and-stores
+description: 'Turn any source into a RagDocument and index it in a production vector store — the document loaders ai.rag.loadText / loadHtml / loadWeb (SSRF-safe via guardedFetch) / loadPdf (lazy pdf-parse peer), plus the swappable stores ai.rag.pgVectorStore({client}) (pgvector + ensureSchema DDL + hnsw/ivfflat index) and ai.rag.cacheVectorStore(driver), both satisfying VectorStoreContract (upsert / query / removeNamespace). Loaders return the exact RagDocument[] that kb.index() consumes — no adapter. Triggers: `ai.rag.loadText`, `ai.rag.loadHtml`, `ai.rag.loadWeb`, `ai.rag.loadPdf`, `loadText`, `loadHtml`, `loadWeb`, `loadPdf`, `ai.rag.pgVectorStore`, `ai.rag.cacheVectorStore`, `pgVectorStore`, `cacheVectorStore`, `VectorStore`, `PgVectorStoreOptions`, `PgVectorStoreInstance`, `ensureSchema`, `schema()`, `RagLoaderResult`, `LoadWebOptions`, `LoadPdfOptions`, `perPage`, `OutboundPolicy`, `guardedFetch`, `hnsw`, `ivfflat`, `pgvector`, `dimensions`, `PgClientLike`, `PDF_PARSE_INSTALL_INSTRUCTIONS`; ''load a website into a knowledge base'', ''index a PDF for RAG'', ''strip HTML to text for embedding'', ''pgvector store for RAG'', ''SSRF-safe document fetch'', ''one document per PDF page'', ''swap the vector store''; typical import `import { ai } from "@warlock.js/ai"`. Skip: the chunk → embed → retrieve → rerank → cite pipeline that consumes these — `@warlock.js/ai/run-ai-rag/SKILL.md`; the raw embedder primitive — `@warlock.js/ai/embed-text/SKILL.md`; cache similarity internals — `@warlock.js/cache/use-cache-similarity/SKILL.md`; competing libs `langchain` loaders, `llamaindex` readers.'
+---
+
+# RAG loaders + vector stores — source → `RagDocument` → durable store
+
+Two feature groups that bracket `ai.rag()`: **loaders** turn a source (string, raw HTML, a URL, or PDF bytes) into the exact `RagDocument[]` shape `kb.index()` consumes, and **stores** are the swappable backends that hold the embeddings. Both live on the `ai.rag.*` namespace — present the moment `@warlock.js/ai` is imported, no side-effect import, no module augmentation.
+
+## Contract — what each side produces / satisfies
+
+Every loader returns `RagLoaderResult` — a plain `RagDocument[]` — so a load feeds `index()` with no adapter and callers never branch on arity (one page ⇒ 1 doc, a per-page PDF ⇒ N docs):
+
+```ts
+type RagLoaderResult = RagDocument[];
+type RagDocument = { id: string; text: string; metadata?: Record<string, unknown>; tags?: string[] };
+```
+
+Every store satisfies the three-method `VectorStore` contract (a thin narrowing of the cache `similar()` surface — NOT a new engine):
+
+```ts
+interface VectorStore {
+  upsert(key: string, value: unknown, vector: number[], tags?: string[]): Promise<void>;
+  query<T>(vector: number[], options: { topK: number; threshold?: number; tags?: string[] }): Promise<{ key: string; value: T; score: number }[]>;
+  removeNamespace(namespace: string): Promise<void>;
+}
+```
+
+## Loaders
+
+| Loader | Input | Deps | Emits |
+|---|---|---|---|
+| `ai.rag.loadText(input, opts?)` | `string` \| `{ id, text }` \| array of either | none | one doc per non-empty item |
+| `ai.rag.loadHtml(html, opts?)` | raw HTML string | none (regex strip) | one doc, `metadata.title` from `<title>` |
+| `ai.rag.loadWeb(url, opts?)` | absolute URL | none (uses core `guardedFetch`) | one doc, SSRF-safe fetch |
+| `ai.rag.loadPdf(bytes, opts?)` | `Buffer` \| `ArrayBuffer` \| `Uint8Array` | lazy `pdf-parse` peer | one doc, or one per page with `perPage: true` |
+
+Shared options (`RagLoaderOptions`): `id` (source id — falls back to the URL for web, `"document"` otherwise), `metadata` (merged **over** the loader-derived keys, so an explicit `metadata.title` always wins), and `tags` (applied to every chunk for `retrieve({ tags })` filtering). Loader-derived keys: `source`, `loader` (`"text" | "html" | "web" | "pdf"`), plus `title` / `page` / `pageCount` / `contentType` where determinable. Empty / whitespace-only / all-markup inputs emit **no** document — never a no-op record for `index()` to skip.
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+// Bare string, or many records → many distinctly-identified docs:
+await kb.index(ai.rag.loadText([
+  { id: "faq-billing", text: "…", metadata: { section: "billing" } },
+  { id: "faq-shipping", text: "…" },
+]));
+
+// Raw HTML → readable text (scripts/styles dropped, entities decoded):
+await kb.index(ai.rag.loadHtml(rawHtml, { id: "landing", tags: ["marketing"] }));
+```
+
+### `loadWeb` is SSRF-safe — never a raw `fetch`
+
+Every request goes through core's `guardedFetch` under an `OutboundPolicy`. The strict defaults (https-only, private-IP-deny on, 10s timeout, 5 MiB cap) apply even when you pass no `policy`, so an untuned call is already hardened. Tighten it per call:
+
+```ts
+await kb.index(await ai.rag.loadWeb("https://docs.example.com/guide", {
+  policy: { hostAllowlist: ["docs.example.com"], maxBytes: 2_000_000, timeoutMs: 5_000 },
+  tags: ["docs"],
+}));
+```
+
+HTML responses run through the same tag-strip pass as `loadHtml`; non-HTML text (`text/plain`, markdown) is used verbatim. `metadata.source` is the resolved URL, `metadata.contentType` the server-reported type. A non-OK response, a policy block, a timeout, or an over-cap body throws `OutboundPolicyError`.
+
+### `loadPdf` — lazy optional peer, page-precise citations
+
+`pdf-parse` is an **optional** peer, dynamic-imported on the FIRST `loadPdf` call — importing `@warlock.js/ai` never forces it. When it is absent, the curated `PDF_PARSE_INSTALL_INSTRUCTIONS` string is thrown as a plain `Error` (a missing infra peer, not a content problem), never a raw module-resolution stack trace.
+
+```ts
+import { readFile } from "node:fs/promises";
+
+// Whole PDF → one doc carrying metadata.pageCount:
+await kb.index(await ai.rag.loadPdf(await readFile("manual.pdf"), { id: "manual" }));
+
+// One doc per page → citations stay page-precise (id suffixed `#p<n>`, metadata.page set):
+await kb.index(await ai.rag.loadPdf(bytes, { id: "manual", perPage: true }));
+```
+
+An image-only / scanned page has no text layer and is dropped, so a fully-scanned PDF yields zero docs (nothing to embed).
+
+## Stores
+
+### `ai.rag.cacheVectorStore(driver)` — adapt any `@warlock.js/cache` driver
+
+The cache driver **is** the vector store — `upsert → set({ vector, tags })`, `query → similar()`, `removeNamespace → removeNamespace()`. A driver without similarity support throws `CacheUnsupportedError` unchanged (pointing you at the `pg` / `redis` cache drivers).
+
+```ts
+import { MemoryCacheDriver } from "@warlock.js/cache";
+
+const store = ai.rag.cacheVectorStore(new MemoryCacheDriver()); // dev / tests
+```
+
+### `ai.rag.pgVectorStore(options)` — production pgvector
+
+One durable row per chunk keyed by the pipeline's dotted key, the chunk payload in a `JSONB` `value` column, the embedding in a pgvector `vector` column. Pass a live pool (`{ client }` — `@warlock.js/ai` imports **nothing**) or a `{ connectionString }` and let the store lazily `import("pg")` (the optional peer; curated install string on first use if absent). Exactly one of the two is required.
+
+```ts
+type PgVectorStoreOptions = {
+  client?: PgClientLike;               // a pg.Pool / pg.Client — only `query` is ever called
+  connectionString?: string;           // else the store builds its own Pool lazily
+  table?: string;                      // default "warlock_ai_rag_vectors"; must be a safe identifier
+  dimensions?: number;                 // vector(N) width in the DDL, default 1536
+  index?: "hnsw" | "ivfflat" | "none"; // ANN strategy, default "hnsw"
+  ivfflatLists?: number;               // ivfflat only, default 100
+};
+```
+
+`schema()` (alias `ensureSchema()`) returns the reference migration DDL — `CREATE EXTENSION vector`, the table, a GIN index on `tags`, and the chosen ANN index (`USING hnsw (embedding vector_cosine_ops)`). It **only returns the string**; the framework never auto-migrates — you run it once through your own tool. Index and query MUST use the same embedding model: the `vector(N)` width is fixed at table-creation time from `dimensions`.
+
+```ts
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536, index: "hnsw" });
+
+// Once, via your migration tooling — never auto-run:
+await pool.query(store.ensureSchema());
+```
+
+`query()` runs the cosine floor (`threshold`) and `tags` overlap filter **in SQL** (a below-floor row never crosses the wire), orders by `embedding <=> $vec`, caps at `topK`, and maps the pgvector distance back to a `[0,1]` cosine-similarity `score` — the same scale the cache store emits. `removeNamespace()` is a prefix DELETE that escapes `_` / `%` so dropping `ai.rag.docs` never also catches `ai.rag.docs2`.
+
+## Pattern — a knowledge base from a website, backed by pgvector
+
+```ts
+import { Pool } from "pg";
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536 });
+await pool.query(store.ensureSchema()); // once at boot / migration
+
+const kb = ai.rag({
+  name: "docs",
+  embedder: openai.embedder({ name: "text-embedding-3-small" }), // 1536 dims — matches the DDL
+  store,
+});
+
+// Crawl a few pages (SSRF-safe) + a spec PDF into the same namespace:
+for (const url of ["https://docs.example.com/intro", "https://docs.example.com/config"]) {
+  await kb.index(await ai.rag.loadWeb(url, { policy: { hostAllowlist: ["docs.example.com"] }, tags: ["docs"] }));
+}
+await kb.index(await ai.rag.loadPdf(await readFile("spec.pdf"), { id: "spec", perPage: true, tags: ["spec"] }));
+
+// Now retrieve — every hit's citation traces back to its source URL / page:
+const { chunks } = await kb.retrieve("how do I configure caching?", { topK: 4, tags: ["docs"] });
+```
+
+The `embedder`'s `dimensions` MUST equal the store's `dimensions` — a mismatch is a runtime insert failure at the pgvector column, not a type error.
+
+## Cost + testing
+
+- **Loaders are cheap.** `loadText` / `loadHtml` are zero-dependency string passes; `loadWeb` costs one guarded HTTP round-trip; `loadPdf` costs the `pdf-parse` parse. **None embed** — embedding cost lands entirely in `kb.index()` (batched, 96 texts per `embedMany` call). The token spend is per chunk, so `perPage` PDFs and finer chunking mean more, smaller vectors.
+- **`pgVectorStore` construction is synchronous and does no I/O** — the `pg` import + pool build are deferred to first `query`/`upsert`. Table-name validation (`/^[A-Za-z_][A-Za-z0-9_]*$/`) throws at construction, so a `table: "bad; DROP TABLE x"` fails fast.
+- **Unit-test loaders with fixtures** (a stubbed `policy.fetch` for `loadWeb`, `vi.mock("pdf-parse")` for `loadPdf` — the literal specifier is mockable). Test stores against a `FakePgClient` implementing `{ query }`, or `cacheVectorStore(new MemoryCacheDriver())` for a real end-to-end index/retrieve with no external service.
+
+## See also
+
+- [[run-ai-rag]] — the chunk → embed → retrieve → rerank → cite pipeline that **consumes** these loaders and stores (`ai.rag({ embedder, store })`, `index()` / `retrieve()`).
+- [[embed-text]] — the `sdk.embedder` primitive whose `dimensions` must match the store's `vector(N)` width.
+- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — the cache driver `cacheVectorStore` adapts.

package/skills/record-replay-llm/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: record-replay-llm
+description: 'Deterministic, offline LLM tests with ai.vcr(model,{path,mode}) — a record/replay decorator over ANY ModelContract that intercepts only complete()/stream(), delegates name/provider/capabilities/pricing to the inner model, and hashes each request against a JSON cassette on disk. Covers the three modes (record / replay / auto), the cassette format, save(), VcrCassetteMissError, streaming round-trip, hashOptions, and composing below fallbackModel. Triggers: `ai.vcr`, `vcr`, `VcrModel`, `VcrOptions`, `VcrMode`, `Cassette`, `CassetteEntry`, `VcrCassetteMissError`, `hashRequest`, `DEFAULT_HASH_OPTIONS`, `mode`, `path`, `hashOptions`, `save`, `cassette`, record, replay, cassette; ''record LLM responses for tests'', ''replay model calls offline in CI'', ''deterministic agent test without hitting the provider'', ''cassette for model calls''; typical import `import { ai } from "@warlock.js/ai"`. Skip: eval scoring + regression gating — `@warlock.js/ai/eval-datasets-and-ci/SKILL.md`; the Vitest matchers + mockRouter — `@warlock.js/ai/ai-dx-helpers/SKILL.md`; choosing a provider adapter — `@warlock.js/ai/pick-ai-provider/SKILL.md`; competing libs `nock`, `polly.js`.'
+---
+
+# `ai.vcr()` — record / replay any model
+
+`ai.vcr(model, { path, mode })` wraps any `ModelContract` in a record/replay decorator backed by a JSON cassette on disk. It intercepts only `complete()` / `stream()` — the single seam every agent trip funnels through — and delegates `name`, `provider`, `capabilities`, and `pricing` to the inner model untouched, so cost accounting and capability detection are unchanged. Depends only on `ModelContract`, so it works with **any** adapter.
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+const live = openai.model({ name: "gpt-4o-mini" });
+
+const model = ai.vcr(live, {
+  path: "./cassettes/support.json",  // cassette file (JSON); read on construct, written on save()
+  mode: "auto",                      // "record" | "replay" | "auto" (default)
+});
+
+const agent = ai.agent({ model, systemPrompt: "..." });
+const result = await agent.execute("hi");
+
+await model.save(); // first run records; later runs replay deterministically
+```
+
+The returned `VcrModel` is a `ModelContract` plus `save(): Promise<void>` and a readonly `cassette` (exposed for assertions).
+
+## Modes — `VcrMode`
+
+- **`record`** — always calls the inner model and appends a cassette entry. Never replays (the in-memory cassette starts empty, so a record run never accidentally replays a stale entry). Use to (re)capture a fresh cassette.
+- **`replay`** — never calls the inner model. A cassette hit returns the stored response / re-yields its chunks / re-throws its error; a **miss throws `VcrCassetteMissError`** — never a silent live call. Use in CI for deterministic, offline tests.
+- **`auto`** (default) — replay on a hit, record on a miss. The friendliest mode for local dev: records once, replays thereafter.
+
+## Request hashing — `hashOptions`
+
+On each call VCR computes a stable hash over `{ messages, picked options }` and looks for a matching `CassetteEntry`. The hashed option fields default to:
+
+```ts
+["temperature", "maxTokens", "responseSchema", "tools", "reasoning"]
+```
+
+(`DEFAULT_HASH_OPTIONS`). `signal` and unknown provider keys are **always excluded**, so an otherwise-identical logical call still matches. `tools` are hashed by name + description + input-schema shape, not object identity. Override `hashOptions` to widen / narrow what counts as "the same request". `hashRequest(messages, options, hashOptions)` is exported for direct use.
+
+## Cassette format
+
+A `Cassette` is `{ version: 1, model, provider, entries: CassetteEntry[] }`. Each `CassetteEntry` is `{ requestHash, request: { messages, options? }, ... }` where **exactly one** of `response` / `chunks` / `error` is populated — mirroring the three outcomes of a model call (non-streaming reply, streamed chunk list, or a thrown provider error). The full `request` is stored verbatim for human readability and so the cassette can be re-hashed if the hashing format ever changes.
+
+## Streaming round-trip
+
+```ts
+for await (const chunk of model.stream(messages)) {
+  // record mode: buffers each chunk into entry.chunks[] while re-emitting
+  // replay mode: re-yields the stored chunks in order (delta / tool-call / done sequence)
+}
+await model.save();
+```
+
+Recorded chunks reproduce the exact `delta` / `tool-call` / `done` sequence on replay; a recorded error is re-thrown.
+
+## `VcrCassetteMissError`
+
+```ts
+import { VcrCassetteMissError } from "@warlock.js/ai";
+
+try {
+  await vcrModel.complete(messages);
+} catch (error) {
+  if (error instanceof VcrCassetteMissError) {
+    console.error("Re-record the cassette:", error.path, error.requestHash);
+  }
+}
+```
+
+Thrown only in `replay` mode on a miss (code `"VCR_CASSETTE_MISS"`). It carries the looked-up `requestHash` and the cassette `path` so a failing CI run names exactly which call was not recorded. Extends `AIError` directly (not `ProviderError`) — a miss is a harness/config failure, not a provider failure. **The whole point:** `replay` never falls back to a live call, which would silently re-introduce non-determinism into a test that asked for the opposite. Re-record by running once in `record` / `auto`.
+
+## `save()` — flush new entries
+
+`save()` writes newly recorded entries to `path`. It is a **no-op when nothing was recorded** (pure replay, or a record/auto run that only hit cached entries), so calling it unconditionally is safe.
+
+## Composition
+
+VCR composes **below** `ai.fallbackModel` and works with any adapter. Wrap the live model in `vcr(...)`, then pass it anywhere a `ModelContract` is accepted (agent, planner, reranker, judge).
+
+## See also
+
+- [`@warlock.js/ai/eval-datasets-and-ci/SKILL.md`](@warlock.js/ai/eval-datasets-and-ci/SKILL.md) — pair a cassette with a dataset for fully offline eval CI
+- [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md) — `ai.mockRouter` + Vitest matchers for the rest of the test surface
+- [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) — the adapters whose models VCR wraps

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, 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`.'
+description: 'Build agents with ai.agent({...}) — the single-LLM-turn primitive. Covers execute / stream, attachments, structured output, placeholders, events, agent.eval scoring, the judge-safe preset for resilient LLM-as-judge / verdict classifiers (ai.agent.judge / judge: true — lenient JSON parse + repair + never-throw, for Nova-class models), and auto-adapting raw executables in tools:[]. Triggers: `ai.agent`, `ai.agent.judge`, `agent.execute`, `agent.stream`, `agent.eval`, `AgentResult`, `AgentReport`, `AgentToolEntry`, `JudgeConfig`, `JudgeAgentConfig`, `judge`, `repairAttempts`, `streamingToolGuard`, `attachments`, `repair`, `maxTrips`, `sessionId`, `spawnSubAgent`, `SpawnSubAgentSpec`; ''run an agent'', ''stream an agent response'', ''structured output schema'', ''pass image to agent'', ''evaluate an agent'', ''LLM-as-judge that survives malformed JSON'', ''grade with a Nova model without crashing'', ''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
@@ -183,6 +183,31 @@ await myAgent.execute(input, {
 
 Disabled by default. Each repair attempt counts against `maxTrips`.
 
+## `judge` preset — resilient LLM-as-judge / verdict classifiers
+
+For graders and verdict classifiers running on models that emit **corrupted** structured output — notably the Amazon Nova family, which wraps verdicts in fenced ` ```json ` blocks, prepends prose, or trails commentary — set `judge: true` (or a `JudgeConfig`). It turns on three behaviors at once:
+
+```ts
+const grader = ai.agent.judge({
+  model: nova.model({ name: "amazon.nova-pro-v1:0" }),
+  systemPrompt: "Grade the answer. Respond with JSON only.",
+  output: verdictSchema,
+});
+
+const result = await grader.execute(prompt);
+if (result.error) {
+  // graceful default — the judge couldn't produce a clean verdict
+}
+```
+
+1. **Repair** — a couple of re-ask attempts by default (`repairAttempts`, defaults to `2`; bounded by `maxTrips`) when the verdict fails to parse / validate. The caller's per-call `options.repair` still wins.
+2. **Lenient verdict parsing** — extracts the first balanced JSON object / array (tolerating fenced blocks + surrounding prose) instead of the strict parser.
+3. **Never throws on a parse miss** — even an unparseable verdict yields a well-formed result (`result.error` populated, `result.data` undefined), so a flaky judge degrades instead of crashing the flow.
+
+`ai.agent.judge(config, judge?)` is sugar for `ai.agent({ ...config, judge })`; the bare `ai.agent({ judge: true })` option does the same. `judge: {}` ≡ `judge: true` (every field falls back to its resilient default); `judge: { repairAttempts: 0 }` keeps the lenient parser + never-throw guarantee but disables repair.
+
+**Trade-off — resilience over strictness.** The lenient parse can recover JSON the strict parser would (correctly) reject — leave `judge` **off** for normal structured output, where a hard parse failure is a useful signal. Off by default; omitting it parses strictly and never auto-enables repair, byte-for-byte as before. (This is the same Nova-safe judge the unified prompt `validate()` uses — see [`@warlock.js/ai/manage-prompts/SKILL.md`](@warlock.js/ai/manage-prompts/SKILL.md).)
+
 ## Pattern — image attachments
 
 ```ts

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

@@ -0,0 +1,139 @@
+---
+name: run-ai-rag
+description: 'Retrieval-augmented generation with ai.rag({...}) — a chunk → embed → vector-store → retrieve → rerank → cite pipeline that reuses ai.embedder + a @warlock.js/cache CacheDriver. Covers index() / retrieve() / clear() / asTool(), chunking strategies (recursive | markdown | sentence | fixed), Citation / RetrievedChunk provenance, and the opt-in rerankers ai.rag.keywordReranker / ai.rag.llmReranker. Triggers: `ai.rag`, `rag.index`, `rag.retrieve`, `rag.clear`, `rag.asTool`, `RagConfig`, `RagDocument`, `RetrieveOptions`, `RetrieveResult`, `RetrievedChunk`, `Citation`, `ChunkOptions`, `ChunkType`, `ai.rag.keywordReranker`, `ai.rag.llmReranker`, `cacheVectorStore`, `VectorStore`, `topK`, `threshold`, `candidates`; ''build a knowledge base'', ''retrieve relevant chunks for a query'', ''cite the source of an answer'', ''chunk markdown for embedding'', ''rerank retrieval results'', ''expose retrieval as a tool''; typical import `import { ai } from "@warlock.js/ai"`. Skip: raw single-string embedding — `@warlock.js/ai/embed-text/SKILL.md`; exact + vector LLM-response cache — `@warlock.js/ai/attach-ai-middleware/SKILL.md` (ai.middleware.semanticCache); tool wiring — `@warlock.js/ai/define-ai-tool/SKILL.md`; competing libs `langchain`, `llamaindex`.'
+---
+
+# `ai.rag()` — chunk → embed → retrieve → rerank → cite
+
+A self-contained retrieval pipeline. It reuses the embedder you already have (`provider.embedder(...)`), a `@warlock.js/cache` vector-capable `CacheDriver` as the store, and the composite-as-tool engine for `asTool()`. Zero new dependencies. `ai.rag` is a native core verb — present the moment `@warlock.js/ai` is imported (no module augmentation, no side-effect import).
+
+## Factory 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 kb = ai.rag({
+  name: "docs",                                            // default "rag"
+  embedder: openai.embedder({ name: "text-embedding-3-small" }), // REQUIRED
+  store: new MemoryCacheDriver(),                          // or ai.config({ defaultStore })
+  namespace: "ai.rag.docs",                                // default `ai.rag.<name>`
+  chunk: { type: "markdown", size: 800, overlap: 120 },    // index() defaults
+  reranker: ai.rag.keywordReranker(),                      // OFF by default (cosine-only)
+  retrieve: { topK: 4, threshold: 0.5 },                   // default retrieval knobs
+});
+```
+
+Resolution is **loud at construction** (mirrors `ai.memory`):
+
+- `embedder` is **required** — a provider with no embedder must be caught here, not at first `index()`.
+- `store` falls back to `ai.config({ defaultStore })`; if neither resolves, the factory throws.
+
+## Surface — `Rag`
+
+```ts
+interface Rag {
+  readonly name: string;
+  index(docs: RagDocument[], chunk?: ChunkOptions): Promise<{ chunks: number }>;
+  retrieve(query: string, options?: RetrieveOptions): Promise<RetrieveResult>;
+  clear(): Promise<void>;
+  asTool(options?: RagAsToolOptions): ToolContract<{ query: string }, RetrieveResult>;
+}
+```
+
+## `index()` — chunk, embed (batched), store
+
+```ts
+await kb.index([
+  { id: "guide", text: longMarkdown, metadata: { url: "/guide" }, tags: ["frontend"] },
+  { id: "faq", text: faqText },
+]);
+```
+
+A `RagDocument` is `{ id, text, metadata?, tags? }` — **you** load + parse documents to text (loaders are out of scope for v1). Each doc is split into chunks, embedded in sub-batches of 96 texts per `embedMany()` call (so one giant doc never blows the provider's per-request cap), and upserted. Returns the chunk count written. Empty / whitespace-only documents yield zero chunks — nothing is embedded. The per-call `chunk` arg overrides `config.chunk` for that index.
+
+## Chunking — `ChunkOptions`
+
+All sizing is in **characters** (tokenizer-free; the embedder owns token counting). `chunk(text, options)` is also exported standalone.
+
+```ts
+type ChunkType = "recursive" | "sentence" | "fixed" | "markdown";
+
+{
+  type?: ChunkType,          // default "recursive"
+  size?: number,             // target chars per chunk, default 1000
+  overlap?: number,          // chars carried between adjacent chunks, default 200
+  separators?: string[],     // recursive only; default ["\n\n", "\n", ". ", " ", ""]
+}
+```
+
+- **`recursive`** (default) — separator-aware greedy packing, largest unit first.
+- **`markdown`** — heading/section-aware, then recursive within each section.
+- **`sentence`** — packs whole sentences up to `size`.
+- **`fixed`** — back-to-back character windows.
+
+Every chunk records its exact `[start, end)` span in the original text, so a `Citation.span` is precise.
+
+## `retrieve()` — embed query, fetch, rerank, slice, cite
+
+```ts
+const { query, chunks } = await kb.retrieve("how do I configure caching?", {
+  topK: 4,          // returned AFTER reranking. default 5
+  threshold: 0.5,   // cosine floor at the store stage. default 0.5
+  candidates: 16,   // pool fetched before rerank. default topK * 4 (clamped >= topK)
+  tags: ["frontend"], // restrict to chunks whose source had one of these tags
+});
+
+for (const hit of chunks) {
+  console.log(hit.score, hit.text);
+  console.log(hit.citation.sourceId, hit.citation.chunkIndex, hit.citation.span);
+}
+```
+
+`retrieve()` is **return-only** — it never auto-injects into a prompt. The caller formats the cited chunks (or uses `asTool()` for the agent loop). A `RetrievedChunk` carries `{ text, score, citation }`; the `Citation` is `{ sourceId, chunkIndex, span, score, metadata? }`. The reranker is **OFF by default** (cosine ranking only) unless `config.reranker` is set.
+
+## Rerankers — opt-in, on `ai.rag.*`
+
+Both are exposed as namespaced helpers on the factory (`ai.rag.keywordReranker`, `ai.rag.llmReranker`).
+
+```ts
+// Zero-dependency lexical reranker (BM25-lite keyword overlap).
+ai.rag.keywordReranker({ weight: 0.5 }); // weight in [0,1]; 1 = pure keyword, 0 = keep cosine
+
+// Model-backed reranker — one or more model calls per retrieval.
+ai.rag.llmReranker({ model: openai.model({ name: "gpt-4o-mini" }), batchSize: 10 });
+```
+
+- **`keywordReranker`** — blends lexical query-term overlap with the original cosine score by `weight`; ties keep the incoming cosine order. Costs nothing beyond string splits. Reach for it when embedding-only ranking buries a keyword-rich chunk.
+- **`llmReranker`** — asks an LLM to grade each over-fetched candidate `0..1` and sorts by that. Candidates the model fails to score keep their cosine score, so a garbled reply degrades gracefully. Opt in only when precision beats latency/cost. Both implement the `RagReranker` contract, so you can write your own.
+
+## `asTool()` — drop retrieval into an agent's `tools: []`
+
+```ts
+const agent = ai.agent({
+  model: openai.model({ name: "gpt-4o" }),
+  tools: [kb.asTool({ name: "search_docs", retrieve: { topK: 6 } })],
+});
+```
+
+Input is `{ query: string }`; output is the `RetrieveResult`. Default tool name is `retrieve_<rag.name>`; `description` and a per-tool `retrieve` override are optional. Built via the same composite-as-tool engine every other primitive uses.
+
+## `clear()`
+
+```ts
+await kb.clear(); // drops every entry written under this rag's namespace
+```
+
+## Advanced
+
+- `cacheVectorStore(driver)` + the `VectorStore` contract are exported for swapping in a custom store.
+- A stored chunk's namespaced key is `${namespace}.${sourceId}.${chunkIndex}`.
+
+## See also
+
+- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — the `sdk.embedder` primitive this consumes
+- [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) — what `asTool()` produces
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — wiring the retrieval tool into an agent

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

@@ -0,0 +1,107 @@
+---
+name: run-ai-team
+description: 'Manager-led multi-agent teams with ai.team({...}) — transparent sugar over ai.supervisor that maps a manager → route/router, members → intents, and a gate → evaluate, returning a REAL SupervisorContract (no new loop, no new contract). Covers the built-in gate strings "quality" (review-then-fix) and "verify" (test-then-fix), a custom gate function, role mapping (roles / gateKey), and the verbatim supervisor pass-throughs (goal / output / state / maxIterations / snapshotStore / on / observe). Triggers: `ai.team`, `TeamConfig`, `TeamGate`, `TeamGateFn`, `TeamMemberValue`, `manager`, `members`, `gate`, `roles`, `gateKey`, `buildQualityGate`, `buildVerifyGate`, `SupervisorContract`, `ReportType`; ''build a team of agents'', ''manager that delegates to members'', ''review then fix loop'', ''test then fix loop'', ''quality gate for a multi-agent run'', ''report type team''; typical import `import { ai } from "@warlock.js/ai"`. Skip: routing one input to a fixed roster directly — `@warlock.js/ai/run-supervisor/SKILL.md` (team is sugar over it); durable cross-turn sessions — `@warlock.js/ai/run-orchestrator/SKILL.md`; LLM-generated plans — `@warlock.js/ai/run-planner/SKILL.md`; competing libs `crewai`, `autogen`.'
+---
+
+# `ai.team()` — manager + members + a quality gate
+
+`ai.team(config)` is **thin, transparent sugar over `ai.supervisor`**. It builds a `SupervisorConfig` from the team-shaped config, calls `supervisor(...)`, and returns the **unchanged** `SupervisorContract<TOutput>` — the exact object `ai.supervisor` returns. So `ctx.intents.<member>.execute()`, `.asTool()`, `.resume()`, snapshots, and events all stay intact. `team()` owns no loop of its own.
+
+The mapping:
+
+| team field | becomes supervisor field |
+| --- | --- |
+| `manager` | `route` (deterministic `{ route }`) XOR `router` (an agent / `RouterEntry`) |
+| `members` | `intents` |
+| `gate` | `evaluate` |
+
+Everything else passes through 1:1 — the sole exception is the report/result `type`, which is stamped `"team"` (see [Pass-throughs](#pass-throughs-verbatim-supervisor-semantics)).
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { v } from "@warlock.js/seal";
+
+const codeTeam = ai.team({
+  name: "code-team",
+  goal: "Ship a tested module that passes review.",
+  manager: techLeadRouter,                 // an agent / RouterEntry → router; or { route } → deterministic
+  members: { builder, reviewer, fixer },   // role-name → agent | workflow
+  gate: "quality",                         // "quality" | "verify" | (ctx) => EvaluateResult
+  output: v.object({ code: v.string() }),
+  maxIterations: 6,                        // default 10 (supervisor's)
+});
+
+const { data, report } = await codeTeam.execute("Build a debounce<T> utility.");
+```
+
+A `member` is an `AgentContract` or a `WorkflowInstance` (the `TeamMemberValue` union — the autocomplete-friendly common case; callback / full-entry intent shapes still work when forwarded). The keys are both the role names the manager routes to AND the keys `ctx.intents.<role>` exposes (the supervisor escape hatch is preserved).
+
+## The manager — `route` XOR `router`
+
+```ts
+// LLM-driven manager: an agent (or RouterEntry) → becomes SupervisorConfig.router
+manager: techLeadRouter
+
+// Deterministic manager: { route } → becomes SupervisorConfig.route
+manager: { route: (ctx) => (ctx.iteration === 0 ? "builder" : "reviewer") }
+```
+
+Exactly one form is forwarded — mutually exclusive, mirroring the supervisor's own `router` XOR `route` rule. A malformed manager surfaces the existing `SupervisorFailedError` downstream.
+
+## Gates — `"quality"` | `"verify"` | a function
+
+A `gate` string selects a pre-built `evaluate` strategy; both desugar to a concrete `evaluate` callback that leans entirely on the already-shipped `EvaluateResult` semantics (`satisfied` terminates, `reassignTo` re-dispatches the fixer, `feedback` threads forward) — **no new termination or loop code**.
+
+### `gate: "quality"` — review-then-fix
+
+After each iteration's members settle and merge into supervisor `state`, the gate reads `state.approved` (the `gateKey`, default `"approved"`). If truthy → `{ satisfied: true }`; otherwise → `{ reassignTo: "fixer", feedback: String(state.notes ?? "") }`. The reviewer's feedback (`state.notes`) threads into the next iteration.
+
+### `gate: "verify"` — test-then-fix
+
+Identical shape but keyed on the tester's pass/fail slice `state.passed` (default `gateKey`) rather than a subjective score. On failure it re-dispatches the fixer; there is no feedback channel for a pass/fail signal, so none is threaded.
+
+> The named member whose `output` schema writes the gate slice must produce a boolean into `gateKey`.
+
+### A custom gate (full escape hatch)
+
+```ts
+gate: (ctx) => {
+  if (ctx.state.score >= 0.9) return { satisfied: true };
+  return { reassignTo: "fixer", feedback: ctx.state.review };
+}
+```
+
+Supplying a `TeamGateFn` instead of a string opts out of the sugar entirely while keeping the rest of `team()`'s wiring — it forwards straight to `SupervisorConfig.evaluate` with zero wrapping.
+
+## Role mapping — `roles` + `gateKey`
+
+The string gates default to canonical role names. Override when your `members` keys differ:
+
+```ts
+ai.team({
+  name: "qa-team",
+  manager,
+  members: { author, critic, patcher },
+  gate: "quality",
+  roles: { reviewer: "critic", fixer: "patcher" }, // map gate roles → your member keys
+  gateKey: "ok",                                    // state slice the gate reads
+});
+```
+
+**Construction-time validation:** when the gate is a string, the resolved `fixer` (and, for `"quality"`, the `reviewer`) role is checked against `members`. A missing role throws an authoring-style `SupervisorFailedError` (`context: { authoring: true }`) immediately — rather than silently starving until `maxIterations`.
+
+## Pass-throughs (verbatim supervisor semantics)
+
+`goal`, `output`, `state`, `maxIterations`, `snapshotStore`, `on`, `observe`, and `version` are forwarded unchanged. Because the returned object IS a supervisor, observability rides the same generic `Observer` seam every other flow uses (see `observe-ai-flows`), and snapshot resume works exactly as on a bare supervisor.
+
+The one behavioural difference from a bare supervisor: a team stamps **`type: "team"`** on both its report (a first-class `ReportType`, was `"supervisor"`) and its result, so Panoptic and any `Observer` can distinguish, group, filter, and label team runs as their own type rather than folding them into plain supervisor runs. Everything else passes through 1:1.
+
+A member callback that calls `agent.execute()` **directly** still nests `member → agent → tool` under the member span with usage rolled up — the same ambient-`RunFrame` auto-nesting as a bare supervisor. See [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md).
+
+## See also
+
+- [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — the primitive team desugars into (intents, route/router, evaluate, ctx.intents)
+- [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) — wrap a team in durable cross-turn session state
+- [`@warlock.js/ai/observe-ai-flows/SKILL.md`](@warlock.js/ai/observe-ai-flows/SKILL.md) — the `observe` seam a team inherits

package/skills/run-orchestrator/SKILL.md

@@ -86,6 +86,8 @@ result.compaction;                // CompactionResult when a turn compacted (and
 
 `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.
 
+A turn callback that calls `agent.execute()` **directly** (not via `ctx.run` / `ctx.intents`) still nests `callback → agent → tool` inside the turn's report tree, with usage rolled up and the session's `sessionId` stamped onto the captured subtree — an ambient `RunFrame` handles the self-attach. See [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md).
+
 **`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