@warlock.js/ai-tools 5.19.0 → 5.20.0

package/llms.txt

@@ -6,6 +6,6 @@
 
 ## Skills
 
-- [connect-mcp-server](@warlock.js/ai-tools/connect-mcp-server/SKILL.md): Connect to an external MCP server (Direction A) in @warlock.js/ai-tools; use when you need to connect mcp server.
-- [expose-as-mcp-server](@warlock.js/ai-tools/expose-as-mcp-server/SKILL.md): Expose tools AS an MCP server (Direction B) in @warlock.js/ai-tools; use when you need to expose as mcp server.
-- [use-web-and-http-tools](@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md): Use the web + HTTP tool belt in @warlock.js/ai-tools; use when you need to use web and http tools.
+- [connect-mcp-server](@warlock.js/ai-tools/connect-mcp-server/SKILL.md): (no description)
+- [expose-as-mcp-server](@warlock.js/ai-tools/expose-as-mcp-server/SKILL.md): (no description)
+- [use-web-and-http-tools](@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md): (no description)

package/package.json

@@ -22,7 +22,7 @@
     "@modelcontextprotocol/sdk": "*",
     "@mozilla/readability": "*",
     "@tavily/core": "*",
-    "@warlock.js/ai": "5.19.0",
+    "@warlock.js/ai": "5.20.0",
     "ajv": "*",
     "jsdom": "*"
   },
@@ -46,7 +46,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.0.0"
   },
-  "version": "5.19.0",
+  "version": "5.20.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/connect-mcp-server/SKILL.md

@@ -1,98 +1,98 @@
----
-name: connect-mcp-server
-description: "Connect to an external MCP server (Direction A) in @warlock.js/ai-tools; use when you need to connect mcp server."
----
-
-# Connect to an external MCP server (Direction A)
-
-`ai.mcp(server, options?)` opens a connection to any Model Context Protocol server, lists its tools, and adapts each one into a native `ToolContract` — so a remote MCP tool is indistinguishable from a local one and drops straight into `ai.agent({ tools: [...] })`.
-
-```ts
-import "@warlock.js/ai-tools";
-import { ai } from "@warlock.js/ai";
-
-const github = ai.mcp(
-  { type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
-  { namePrefix: "github." },
-);
-
-const dev = ai.agent({
-  model,
-  systemPrompt: "Use the GitHub tools to triage issues.",
-  tools: [...(await github.tools())], // handshake + tools/list, run once and cached
-  maxTrips: 20,
-});
-
-await dev.execute("Find the oldest open 'bug' issue and propose a fix.");
-
-await github.close(); // on teardown — kills the child / ends the HTTP session
-```
-
-## The transport — `stdio` or `http`
-
-The `server` argument is discriminated by `type`:
-
-```ts
-// Spawn a child process and speak JSON-RPC over its stdin/stdout.
-// Uses node:child_process + node:readline — NO dependency.
-{ type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"], env: { GITHUB_TOKEN: "…" } }
-
-// Streamable HTTP against an endpoint.
-{ type: "http", url: "https://mcp.example.com/rpc", headers: { authorization: "Bearer …" } }
-```
-
-> **stdio env is not inherited.** When you pass `env`, only those keys reach the child — pass what the server needs (e.g. its API token) explicitly.
-
-## Client options
-
-```ts
-ai.mcp(server, {
-  namePrefix: "github.",                       // prepended to every remote tool name
-  filter: (name) => name.startsWith("issues_"),// only adapt tools whose name passes
-  timeoutMs: 30_000,                           // per tools/call deadline (default 30s)
-});
-```
-
-- **`namePrefix`** is the collision mitigation — there is **no runtime tool-name collision guard** (the agent resolves a tool by first name match), so the author owns uniqueness. Prefix remote tools to keep them distinct from local ones.
-- **`filter`** receives each tool's *unprefixed* name; return `false` to drop it.
-
-## What `tools()` does
-
-`client.tools()` is lazy and cached: the **first** call runs the `initialize` handshake, sends `notifications/initialized`, then `tools/list`, and maps each descriptor into a `ToolContract`. Repeat calls return the cached array without re-handshaking.
-
-For each remote tool:
-1. its JSON-Schema `inputSchema` is wrapped as a Standard Schema via `jsonSchemaToStandard` (Ajv-backed — `ajv` is an optional peer needed only for the client);
-2. `execute` issues `tools/call` honoring `ctx.signal` (cooperative abort) and the configured `timeoutMs`, then unwraps the result content (a single JSON text block is parsed back into an object);
-3. an MCP `isError` result is thrown so the surrounding `tool()` wraps it as a `ToolExecutionError` — the agent reads it as `{ error }` data and self-corrects.
-
-## `type`, never `kind`
-
-MCP's wire vocabulary uses `kind` in some content/capability descriptors. The client translates any inbound `kind` to `type` when normalizing content blocks, so a value a tool returns never carries MCP's `kind` — every discriminator the agent sees is `type`.
-
-## Errors
-
-Connection / handshake failures surface **at agent-construction time** because the example `await`s `github.tools()` — you see them then, not mid-run. A `tools/call` failure raised mid-run is wrapped by `tool()` and reaches the model as data. Branch on `McpTransportError.type`:
-
-```ts
-import { McpTransportError } from "@warlock.js/ai-tools";
-
-try {
-  await github.tools();
-} catch (error) {
-  if (error instanceof McpTransportError && error.type === "connect") {
-    // the child failed to spawn, the endpoint was unreachable, or the handshake failed
-  }
-}
-```
-
-`McpTransportError.type`: `"connect"` | `"protocol"` | `"timeout"` | `"closed"` (plus an optional `.method` naming the in-flight JSON-RPC method).
-
-## Optional peers
-
-The MCP client lazily imports `@modelcontextprotocol/sdk` (the protocol SDK) and `ajv` (runtime JSON-Schema validation) — both optional peers. A missing one surfaces a curated `npm install` string at first use, never a raw module-resolution crash at import time. The stdio transport itself needs no dependency.
-
-## See also
-
-- [`@warlock.js/ai-tools/expose-as-mcp-server/SKILL.md`](@warlock.js/ai-tools/expose-as-mcp-server/SKILL.md) — the reverse direction: publish a local primitive AS an MCP server.
-- [`@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md`](@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md) — the built-in web / HTTP / calculator / date-time belt.
-- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — running the agent that consumes the adapted tools.
+---
+name: connect-mcp-server
+description: 'Connect a @warlock.js/ai agent to an external Model Context Protocol (MCP) server and adapt its tools as native agent tools (Direction A) with `ai.mcp(server)`. Triggers: `ai.mcp(`, `ai.mcp.serve` (the other direction), `mcp(`, `McpClient`, `McpClientOptions`, `McpTransport`, `client.tools()`, `client.close()`, `namePrefix`, `filter`, `McpTransportError`, `{ type: "stdio" }`, `{ type: "http" }`, `tools/list`, `tools/call`, `jsonSchemaToStandard`, `@modelcontextprotocol/sdk`, `ajv`; ''consume an MCP server'', ''use an external MCP server''s tools in my agent'', ''connect to the GitHub/Slack/Filesystem MCP server'', ''adapt MCP tools as agent tools'', ''bridge my agent to the MCP ecosystem'', ''run an MCP server over stdio/http''; typical import `import "@warlock.js/ai-tools"; import { ai } from "@warlock.js/ai"`. Skip: exposing YOUR agent/tools AS an MCP server (the reverse direction) — `@warlock.js/ai-tools/expose-as-mcp-server/SKILL.md`; the built-in web/HTTP/calc/date tools — `@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md`.'
+---
+
+# Connect to an external MCP server (Direction A)
+
+`ai.mcp(server, options?)` opens a connection to any Model Context Protocol server, lists its tools, and adapts each one into a native `ToolContract` — so a remote MCP tool is indistinguishable from a local one and drops straight into `ai.agent({ tools: [...] })`.
+
+```ts
+import "@warlock.js/ai-tools";
+import { ai } from "@warlock.js/ai";
+
+const github = ai.mcp(
+  { type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+  { namePrefix: "github." },
+);
+
+const dev = ai.agent({
+  model,
+  systemPrompt: "Use the GitHub tools to triage issues.",
+  tools: [...(await github.tools())], // handshake + tools/list, run once and cached
+  maxTrips: 20,
+});
+
+await dev.execute("Find the oldest open 'bug' issue and propose a fix.");
+
+await github.close(); // on teardown — kills the child / ends the HTTP session
+```
+
+## The transport — `stdio` or `http`
+
+The `server` argument is discriminated by `type`:
+
+```ts
+// Spawn a child process and speak JSON-RPC over its stdin/stdout.
+// Uses node:child_process + node:readline — NO dependency.
+{ type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"], env: { GITHUB_TOKEN: "…" } }
+
+// Streamable HTTP against an endpoint.
+{ type: "http", url: "https://mcp.example.com/rpc", headers: { authorization: "Bearer …" } }
+```
+
+> **stdio env is not inherited.** When you pass `env`, only those keys reach the child — pass what the server needs (e.g. its API token) explicitly.
+
+## Client options
+
+```ts
+ai.mcp(server, {
+  namePrefix: "github.",                       // prepended to every remote tool name
+  filter: (name) => name.startsWith("issues_"),// only adapt tools whose name passes
+  timeoutMs: 30_000,                           // per tools/call deadline (default 30s)
+});
+```
+
+- **`namePrefix`** is the collision mitigation — there is **no runtime tool-name collision guard** (the agent resolves a tool by first name match), so the author owns uniqueness. Prefix remote tools to keep them distinct from local ones.
+- **`filter`** receives each tool's *unprefixed* name; return `false` to drop it.
+
+## What `tools()` does
+
+`client.tools()` is lazy and cached: the **first** call runs the `initialize` handshake, sends `notifications/initialized`, then `tools/list`, and maps each descriptor into a `ToolContract`. Repeat calls return the cached array without re-handshaking.
+
+For each remote tool:
+1. its JSON-Schema `inputSchema` is wrapped as a Standard Schema via `jsonSchemaToStandard` (Ajv-backed — `ajv` is an optional peer needed only for the client);
+2. `execute` issues `tools/call` honoring `ctx.signal` (cooperative abort) and the configured `timeoutMs`, then unwraps the result content (a single JSON text block is parsed back into an object);
+3. an MCP `isError` result is thrown so the surrounding `tool()` wraps it as a `ToolExecutionError` — the agent reads it as `{ error }` data and self-corrects.
+
+## `type`, never `kind`
+
+MCP's wire vocabulary uses `kind` in some content/capability descriptors. The client translates any inbound `kind` to `type` when normalizing content blocks, so a value a tool returns never carries MCP's `kind` — every discriminator the agent sees is `type`.
+
+## Errors
+
+Connection / handshake failures surface **at agent-construction time** because the example `await`s `github.tools()` — you see them then, not mid-run. A `tools/call` failure raised mid-run is wrapped by `tool()` and reaches the model as data. Branch on `McpTransportError.type`:
+
+```ts
+import { McpTransportError } from "@warlock.js/ai-tools";
+
+try {
+  await github.tools();
+} catch (error) {
+  if (error instanceof McpTransportError && error.type === "connect") {
+    // the child failed to spawn, the endpoint was unreachable, or the handshake failed
+  }
+}
+```
+
+`McpTransportError.type`: `"connect"` | `"protocol"` | `"timeout"` | `"closed"` (plus an optional `.method` naming the in-flight JSON-RPC method).
+
+## Optional peers
+
+The MCP client lazily imports `@modelcontextprotocol/sdk` (the protocol SDK) and `ajv` (runtime JSON-Schema validation) — both optional peers. A missing one surfaces a curated `npm install` string at first use, never a raw module-resolution crash at import time. The stdio transport itself needs no dependency.
+
+## See also
+
+- [`@warlock.js/ai-tools/expose-as-mcp-server/SKILL.md`](@warlock.js/ai-tools/expose-as-mcp-server/SKILL.md) — the reverse direction: publish a local primitive AS an MCP server.
+- [`@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md`](@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md) — the built-in web / HTTP / calculator / date-time belt.
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — running the agent that consumes the adapted tools.

package/skills/expose-as-mcp-server/SKILL.md

@@ -1,85 +1,85 @@
----
-name: expose-as-mcp-server
-description: "Expose tools AS an MCP server (Direction B) in @warlock.js/ai-tools; use when you need to expose as mcp server."
----
-
-# Expose tools AS an MCP server (Direction B)
-
-`ai.mcp.serve(source, options)` turns a local set of `ToolContract`s into a Model Context Protocol server — so Cursor, Claude Desktop, or any MCP client can call your warlock tools / agent over the wire.
-
-```ts
-import "@warlock.js/ai-tools";
-import { ai } from "@warlock.js/ai";
-
-const server = ai.mcp.serve(
-  [ai.tools.calculator(), ai.tools.dateTime()],
-  { name: "warlock-utils", transport: { type: "stdio" } },
-);
-
-await server.start();
-// ...later, on teardown:
-await server.stop();
-```
-
-## The `source` — array or anything with `tools()`
-
-```ts
-// A literal array of contracts:
-ai.mcp.serve([calc, dt], { name: "utils" });
-
-// Anything that can enumerate its ToolContracts — e.g. a workspace:
-ai.mcp.serve({ tools: () => ws.tools.all() }, { name: "acme-workspace" });
-```
-
-The tools are snapshotted at construction (`source.tools()` is called once), so a stable surface is advertised for the life of the server.
-
-## Serve options
-
-```ts
-ai.mcp.serve(source, {
-  name: "warlock-utils",          // advertised in the initialize response (required)
-  version: "1.0.0",               // default: the package version
-  transport: { type: "stdio" },   // default: stdio
-  schemaTarget: "draft-2020-12",  // JSON-Schema dialect for each tool's inputSchema
-});
-```
-
-- **`schemaTarget`** defaults to `"draft-2020-12"` — a neutral MCP draft, deliberately overriding `extractJsonSchema`'s own `"openai-strict"` default. Set it to match a consuming client's expectation.
-
-## How the protocol maps
-
-- **`initialize`** → advertises `{ name, version }` and `capabilities: { tools: {} }`.
-- **`tools/list`** → one descriptor per contract; each tool's `inputSchema` is produced by `extractJsonSchema(contract.input, { target: schemaTarget })`.
-- **`tools/call`** → routes to the named contract's `invoke()` and maps the **never-throwing** result: `data` becomes a `{ type: "text" }` content block (a string is sent verbatim, anything else is JSON-stringified), and `error` becomes an `isError: true` result. So a failing tool surfaces as a normal MCP tool error — the server never crashes on it. An unknown tool name answers with a JSON-RPC error.
-
-Everything the server emits uses `type`, never `kind`.
-
-## Transport — stdio is auto-pumped; HTTP is host-owned
-
-```ts
-{ type: "stdio" }            // default — reads JSON-RPC lines from process.stdin, writes to stdout
-{ type: "http", port: 8080 } // accepted in options, but start() does NOT bind a socket
-```
-
-`start()` over `stdio` wires a `node:readline` line reader on `process.stdin` and writes one-line JSON-RPC responses to `process.stdout` (notifications without an `id` are ignored). **Serving over HTTP is left to a server you own** — `start()` rejects an `http` transport. For that path, drive the pure protocol core yourself with `createServeHandler`:
-
-```ts
-import { createServeHandler } from "@warlock.js/ai-tools";
-
-const handler = createServeHandler([calc, dt], { name: "warlock-utils" });
-
-// In your own HTTP handler:
-const response = await handler.handle(jsonRpcRequest); // request → response, no I/O
-```
-
-`createServeHandler` is also the cleanest seam for unit tests: feed it a JSON-RPC request, assert the response — no real transport needed.
-
-## Errors
-
-`McpTransportError` covers serve-side failures (`type: "connect"` when `start()` is asked to bind an unsupported transport; `type: "protocol"` for a malformed `tools/call` or an unknown tool name). Tool-level failures are *not* errors here — they come back as `isError: true` results, exactly as MCP expects.
-
-## See also
-
-- [`@warlock.js/ai-tools/connect-mcp-server/SKILL.md`](@warlock.js/ai-tools/connect-mcp-server/SKILL.md) — the reverse direction: consume an external MCP server's tools.
-- [`@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md`](@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md) — the built-in tools you might expose.
-- [`@warlock.js/ai-workspace/use-a-workspace/SKILL.md`](@warlock.js/ai-workspace/use-a-workspace/SKILL.md) — a workspace whose `tools.all()` is a natural `serve` source.
+---
+name: expose-as-mcp-server
+description: 'Expose a @warlock.js/ai agent / supervisor / orchestrator (or a raw ToolContract[]) AS a Model Context Protocol (MCP) server other clients consume (Direction B) with `ai.mcp.serve(source, options)`. Triggers: `ai.mcp.serve(`, `serve(`, `createServeHandler`, `McpServer`, `McpServeOptions`, `McpServeSource`, `McpServeTransport`, `server.start()`, `server.stop()`, `schemaTarget`, `draft-2020-12`, `extractJsonSchema`, `tools/list`, `tools/call`, `{ type: "stdio" }`, `{ type: "http"; port }`; ''expose my agent as an MCP server'', ''publish my tools to Cursor/Claude Desktop'', ''make my warlock workspace an MCP server'', ''serve my ToolContract[] over MCP'', ''let other MCP clients call my agent''; typical import `import "@warlock.js/ai-tools"; import { ai } from "@warlock.js/ai"`. Skip: CONSUMING an external MCP server (the reverse direction) — `@warlock.js/ai-tools/connect-mcp-server/SKILL.md`; the built-in web/HTTP/calc/date tools — `@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md`.'
+---
+
+# Expose tools AS an MCP server (Direction B)
+
+`ai.mcp.serve(source, options)` turns a local set of `ToolContract`s into a Model Context Protocol server — so Cursor, Claude Desktop, or any MCP client can call your warlock tools / agent over the wire.
+
+```ts
+import "@warlock.js/ai-tools";
+import { ai } from "@warlock.js/ai";
+
+const server = ai.mcp.serve(
+  [ai.tools.calculator(), ai.tools.dateTime()],
+  { name: "warlock-utils", transport: { type: "stdio" } },
+);
+
+await server.start();
+// ...later, on teardown:
+await server.stop();
+```
+
+## The `source` — array or anything with `tools()`
+
+```ts
+// A literal array of contracts:
+ai.mcp.serve([calc, dt], { name: "utils" });
+
+// Anything that can enumerate its ToolContracts — e.g. a workspace:
+ai.mcp.serve({ tools: () => ws.tools.all() }, { name: "acme-workspace" });
+```
+
+The tools are snapshotted at construction (`source.tools()` is called once), so a stable surface is advertised for the life of the server.
+
+## Serve options
+
+```ts
+ai.mcp.serve(source, {
+  name: "warlock-utils",          // advertised in the initialize response (required)
+  version: "1.0.0",               // default: the package version
+  transport: { type: "stdio" },   // default: stdio
+  schemaTarget: "draft-2020-12",  // JSON-Schema dialect for each tool's inputSchema
+});
+```
+
+- **`schemaTarget`** defaults to `"draft-2020-12"` — a neutral MCP draft, deliberately overriding `extractJsonSchema`'s own `"openai-strict"` default. Set it to match a consuming client's expectation.
+
+## How the protocol maps
+
+- **`initialize`** → advertises `{ name, version }` and `capabilities: { tools: {} }`.
+- **`tools/list`** → one descriptor per contract; each tool's `inputSchema` is produced by `extractJsonSchema(contract.input, { target: schemaTarget })`.
+- **`tools/call`** → routes to the named contract's `invoke()` and maps the **never-throwing** result: `data` becomes a `{ type: "text" }` content block (a string is sent verbatim, anything else is JSON-stringified), and `error` becomes an `isError: true` result. So a failing tool surfaces as a normal MCP tool error — the server never crashes on it. An unknown tool name answers with a JSON-RPC error.
+
+Everything the server emits uses `type`, never `kind`.
+
+## Transport — stdio is auto-pumped; HTTP is host-owned
+
+```ts
+{ type: "stdio" }            // default — reads JSON-RPC lines from process.stdin, writes to stdout
+{ type: "http", port: 8080 } // accepted in options, but start() does NOT bind a socket
+```
+
+`start()` over `stdio` wires a `node:readline` line reader on `process.stdin` and writes one-line JSON-RPC responses to `process.stdout` (notifications without an `id` are ignored). **Serving over HTTP is left to a server you own** — `start()` rejects an `http` transport. For that path, drive the pure protocol core yourself with `createServeHandler`:
+
+```ts
+import { createServeHandler } from "@warlock.js/ai-tools";
+
+const handler = createServeHandler([calc, dt], { name: "warlock-utils" });
+
+// In your own HTTP handler:
+const response = await handler.handle(jsonRpcRequest); // request → response, no I/O
+```
+
+`createServeHandler` is also the cleanest seam for unit tests: feed it a JSON-RPC request, assert the response — no real transport needed.
+
+## Errors
+
+`McpTransportError` covers serve-side failures (`type: "connect"` when `start()` is asked to bind an unsupported transport; `type: "protocol"` for a malformed `tools/call` or an unknown tool name). Tool-level failures are *not* errors here — they come back as `isError: true` results, exactly as MCP expects.
+
+## See also
+
+- [`@warlock.js/ai-tools/connect-mcp-server/SKILL.md`](@warlock.js/ai-tools/connect-mcp-server/SKILL.md) — the reverse direction: consume an external MCP server's tools.
+- [`@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md`](@warlock.js/ai-tools/use-web-and-http-tools/SKILL.md) — the built-in tools you might expose.
+- [`@warlock.js/ai-workspace/use-a-workspace/SKILL.md`](@warlock.js/ai-workspace/use-a-workspace/SKILL.md) — a workspace whose `tools.all()` is a natural `serve` source.

package/skills/index.md

@@ -0,0 +1,18 @@
+---
+description: "Ready-made tools for @warlock.js/ai agents: web search, URL fetch, HTTP requests, calculator, date-time, and MCP client and server support. Exports `webSearchTool`, `fetchUrlTool`, `httpRequestTool`, `calculatorTool`, `dateTimeTool`, `mcp`, `serve`, `createServeHandler`, `McpTransportError`. Use for: let an agent search the web, fetch a page, call an HTTP API, do math, get the current date, connect to an MCP server, expose my tools as an MCP server. Not this package: defining your own tool or the agent itself → @warlock.js/ai; file and shell tools → @warlock.js/ai-workspace."
+---
+# @warlock.js/ai-tools
+
+A belt of prebuilt tools for `@warlock.js/ai` agents plus the Model Context Protocol bridge in both directions. Importing the package attaches `ai.tools.*` and `ai.mcp` onto the shared `ai` object; the factories are also exported directly.
+
+## The 80% path
+1. Give an agent web or API access with the factories (`use-web-and-http-tools.md`); pass the results in the agent's `tools` array.
+2. Consume tools from an external MCP server (`connect-mcp-server.md`); they arrive as normal agent tools.
+3. Publish your own tools to MCP clients such as editors (`expose-as-mcp-server.md`).
+
+## Conventions and pitfalls
+- Direction A (`connect-mcp-server.md`) consumes; Direction B (`expose-as-mcp-server.md`) serves. Do not mix them up.
+- `fetchUrlTool` and `httpRequestTool` are policy-gated: set host allowlists and byte caps rather than opening them fully.
+- `webSearchTool` needs a search provider choice and its API key (tavily, brave, or serpapi).
+- Every error class extends the `AIError` of `@warlock.js/ai`; catch by subclass.
+- Writing a custom tool with `ai.tool()` lives in `@warlock.js/ai` (`define-ai-tool.md`).