@warlock.js/ai-tools 4.5.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog — @warlock.js/ai-tools
+
+All notable changes to `@warlock.js/ai-tools` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
+
+## 4.5.0 - 2026-07-01
+
+Initial release — a batteries-included tool belt + a Model Context Protocol client and server for `@warlock.js/ai`, built entirely on the framework's vendor-neutral `ai.tool()` seam.
+
+### Added
+
+- **Five ready-made agent tools, attached to the shared `ai` object under `ai.tools.*`** via a `declare module "@warlock.js/ai"` augmentation, so a bare `import "@warlock.js/ai-tools"` makes them available and statically typed. Each returns a `ToolContract` that drops straight into `ai.agent({ tools: [...] })`:
+  - **`ai.tools.webSearch(options)`** (`web_search`) — web search via a chosen provider (`tavily` / `brave` / `serpapi`) over the global `fetch`; the API key falls back to `TAVILY_API_KEY` / `BRAVE_API_KEY` / `SERPAPI_API_KEY`; `maxResults` is clamped per call.
+  - **`ai.tools.fetchUrl(options?)`** (`fetch_url`) — fetch a URL and return its content as readability-extracted `text` (default), raw `html`, or `markdown`, with a host allowlist (SSRF guardrail), a byte cap (`truncated` flag), and a request timeout.
+  - **`ai.tools.http(options?)`** (`http_request`) — a guarded HTTP/REST client: method + host allowlists enforced before the network call, optional `baseUrl` join, static-header merge, byte cap, and timeout; JSON-parses a JSON response body.
+  - **`ai.tools.calculator(options?)`** (`calculator`) — a SAFE arithmetic evaluator (`+ - * / % ^`, unary signs, parentheses, decimal/scientific literals) implemented with a shunting-yard pass — it never calls `eval`/`Function`.
+  - **`ai.tools.dateTime(options?)`** (`date_time`) — clock/calendar operations: `now` / `add` / `diff` / `format` over ISO-8601 instants, with millisecond-based units and IANA time-zone rendering. `diff` accepts `from` as an alias for the start instant (`iso` wins when both are set).
+- **MCP client — `ai.mcp(server, options?)` (Direction A).** Connects to an external MCP server over a stdio (`node:child_process` + `node:readline`, no dependency) or Streamable HTTP transport, runs the `initialize` handshake + `tools/list`, and adapts each remote tool into a native `ToolContract` (its JSON Schema wrapped as a Standard Schema, `tools/call` as `execute`). Supports `namePrefix`, `filter`, and a per-call `timeoutMs`; an `isError` result surfaces as `{ error }` data.
+- **MCP server — `ai.mcp.serve(source, options)` (Direction B).** Exposes a built agent / supervisor / orchestrator (or a raw `ToolContract[]`) AS an MCP server: `tools/list` emits each tool's `inputSchema` via `extractJsonSchema` at the configured `schemaTarget` (default `draft-2020-12`), and `tools/call` routes to `contract.invoke()`, mapping `data` to a text content block and `error` to an `isError: true` result. The stdio transport is auto-pumped over `process.stdin` / `process.stdout`; the pure protocol core is also exported as `createServeHandler` for a host's own HTTP wiring.
+- **Typed error classes** — `WebToolError`, `HttpPolicyError`, `CalculatorError`, `DateTimeError`, and `McpTransportError`, each extending the `@warlock.js/ai` `AIError` base with a `type` discriminator. Every tool follows the errors-as-data contract: failures are thrown inside `execute`, wrapped by `tool()`, and reach the model as `{ error }` so the agent self-corrects instead of crashing the run.
+- **Optional peers, lazily imported.** Heavy dependencies — a search provider (`@tavily/core`), the readability scraper (`@mozilla/readability` + `jsdom`), the MCP SDK (`@modelcontextprotocol/sdk`), and the JSON-Schema validator (`ajv`) — are optional peers, `import()`ed only when the relevant path runs, surfacing a curated `npm install` string when absent rather than crashing at import time. The only required runtime peer is `@warlock.js/ai`; everything else is Node built-ins + the global `fetch` (Node 18+).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @warlock.js/ai-tools
+
+> Ready-made agent tools (web search, fetch, HTTP, calculator, date-time) + an MCP client/server for `@warlock.js/ai`.
+
+A batteries-included **tool belt** for [`@warlock.js/ai`](https://github.com/warlockjs) agents plus a
+Model Context Protocol (MCP) client and server — built entirely on the framework's vendor-neutral
+`ai.tool()` seam, so every tool returns a `ToolContract` that drops straight into
+`ai.agent({ tools: [...] })`. Importing the package registers the tools on the shared `ai` object,
+so they are reached as `ai.tools.*` and `ai.mcp` per the `ai.`-namespace convention.
+
+## What's in the belt
+
+All five tools attach onto the shared `ai` object at import time under the `ai.tools.*` namespace
+(via a `declare module "@warlock.js/ai"` augmentation), so a bare `import "@warlock.js/ai-tools"`
+makes them available and statically typed.
+
+| Tool | LLM-visible name | What it does |
+|---|---|---|
+| `ai.tools.webSearch(options)` | `web_search` | Web search via a chosen provider (`tavily` / `brave` / `serpapi`) — ranked title/URL/snippet hits. |
+| `ai.tools.fetchUrl(options?)` | `fetch_url` | Fetch a URL → readability `text` (default), raw `html`, or `markdown`; host allowlist + byte cap. |
+| `ai.tools.http(options?)` | `http_request` | A guarded HTTP/REST client — method + host allowlists, `baseUrl` join, byte/timeout caps. |
+| `ai.tools.calculator(options?)` | `calculator` | A SAFE arithmetic evaluator (shunting-yard; never `eval`/`Function`). |
+| `ai.tools.dateTime(options?)` | `date_time` | `now` / `add` / `diff` / `format` over ISO-8601 instants, IANA time zones. |
+
+## MCP — both directions
+
+- **`ai.mcp(server, options?)`** — connect to an external MCP server and adapt each of its tools into
+  a native `ToolContract` (Direction A: server → agent tools).
+- **`ai.mcp.serve(source, options)`** — expose a warlock agent / supervisor / orchestrator (or a raw
+  `ToolContract[]`) **as** an MCP server other clients consume (Direction B: primitive → server).
+
+> There is **no SQL tool.** An LLM-driven SQL surface is sensitive and must be audited per app, so it
+> is deliberately not part of this belt.
+
+## Install
+
+```bash
+npm install @warlock.js/ai-tools
+```
+
+`@warlock.js/ai` is the only required runtime peer. Everything heavy — a search provider, the
+readability scraper, the MCP SDK, and a JSON-Schema validator — is an **optional peer**, lazily
+`import()`ed only when the relevant path runs; a missing one surfaces a curated `npm install` string
+rather than crashing at import time. Beyond `@warlock.js/ai` the package uses only Node built-ins and
+the global `fetch` (Node 18+). Import the package once for its side effect so the surface is
+registered:
+
+```ts
+import "@warlock.js/ai-tools";
+```
+
+## Usage
+
+### 1. An agent with web search + HTTP
+
+Hand an agent the web tools and let it research, then hit an API — both bounded by a host allowlist.
+A failing tool call comes back as `{ error }` *data*, so the agent self-corrects instead of crashing.
+
+```ts
+import "@warlock.js/ai-tools"; // registers ai.tools.* + ai.mcp on import
+import { ai } from "@warlock.js/ai";
+
+const agent = ai.agent({
+  model: ai.openai.model({ name: "gpt-4o" }),
+  systemPrompt: "Research with web_search, then call the API with http_request.",
+  tools: [
+    ai.tools.webSearch({ provider: "tavily" }), // TAVILY_API_KEY from env, or pass { apiKey }
+    ai.tools.http({
+      baseUrl: "https://api.github.com",
+      allowHosts: ["api.github.com"],
+      allowMethods: ["GET"],
+      headers: { "user-agent": "warlock-agent" },
+    }),
+  ],
+  maxTrips: 12,
+});
+
+await agent.execute("Find the latest @warlock.js release and summarize its notes.");
+```
+
+### 2. Consume an external MCP server
+
+`ai.mcp(server)` connects to any MCP server, lists its tools, and adapts each into a `ToolContract`.
+`await client.tools()` runs the handshake once and is cached; spread the result into `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." }, // avoid colliding with local tool names
+);
+
+const dev = ai.agent({
+  model: ai.openai.model({ name: "gpt-4o" }),
+  systemPrompt: "Use the GitHub tools to triage issues.",
+  tools: [...(await github.tools())],
+  maxTrips: 20,
+});
+
+await dev.execute("List the open issues labeled 'bug' and propose a fix for the oldest.");
+
+// On teardown:
+await github.close();
+```
+
+### 3. Expose an agent's tools AS an MCP server
+
+`ai.mcp.serve(source, options)` turns a local `ToolContract[]` (or anything with a `tools()` method)
+into an MCP server. The default `stdio` transport is auto-pumped over `process.stdin`/`process.stdout`,
+so Cursor / Claude Desktop / any MCP client can call these tools.
+
+```ts
+import "@warlock.js/ai-tools";
+
+const server = ai.mcp.serve(
+  [ai.tools.calculator(), ai.tools.dateTime()],
+  { name: "warlock-utils", transport: { type: "stdio" } },
+);
+
+await server.start();
+// ...later:
+await server.stop();
+```
+
+## Errors flow as data, not throws
+
+Every tool follows the framework's errors-as-data contract: a guardrail rejection or a failed call is
+thrown inside the tool handler, caught by `tool()`, and surfaced in the returned `{ error }` field —
+`invoke()` never throws. Each error class extends the `@warlock.js/ai` `AIError` base and carries a
+`type` discriminator you can branch on:
+
+```ts
+import { HttpPolicyError } from "@warlock.js/ai-tools";
+
+const http = ai.tools.http({ allowHosts: ["api.github.com"] });
+const { error } = await http.invoke({ url: "https://evil.test" });
+
+if (error instanceof HttpPolicyError && error.type === "host-not-allowed") {
+  // rejected before any network call — an SSRF guardrail
+}
+```
+
+- `WebToolError.type`: `"missing-peer"` | `"missing-key"` | `"denied-host"` | `"invalid-url"` | `"request-failed"`
+- `HttpPolicyError.type`: `"method-not-allowed"` | `"host-not-allowed"` | `"invalid-url"`
+- `CalculatorError.type`: `"syntax"` | `"divide-by-zero"` | `"overflow"`
+- `DateTimeError.type`: `"invalid-input"` | `"invalid-unit"` | `"invalid-time-zone"` | `"unsupported-op"`
+- `McpTransportError.type`: `"connect"` | `"protocol"` | `"timeout"` | `"closed"`
+
+## Skills
+
+Progressive-disclosure, per-task docs live under [`skills/`](./skills/README.md):
+
+- [`use-web-and-http-tools/`](./skills/use-web-and-http-tools/SKILL.md) — wire `web_search`, `fetch_url`,
+  `http_request`, `calculator`, and `date_time` into an agent under their guardrails.
+- [`connect-mcp-server/`](./skills/connect-mcp-server/SKILL.md) — adapt an external MCP server's tools
+  with `ai.mcp(server)` (Direction A).
+- [`expose-as-mcp-server/`](./skills/expose-as-mcp-server/SKILL.md) — publish a local primitive AS an
+  MCP server with `ai.mcp.serve(source)` (Direction B).
+
+## License
+
+MIT © Hassan Zohdy