@warlock.js/ai-tools 4.5.0

package/cjs/index.cjs

@@ -0,0 +1,2519 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _warlock_js_ai = require("@warlock.js/ai");
+let node_child_process = require("node:child_process");
+let node_readline = require("node:readline");
+
+//#region ../@warlock.js/ai-tools/src/errors.ts
+/**
+* The `calculator` tool could not evaluate an expression — it was not
+* valid arithmetic, divided by zero, or overflowed to a non-finite
+* value.
+*
+* **Surface.** Thrown inside the tool handler, where `tool()` wraps it
+* into a `ToolExecutionError` whose message is preserved verbatim and
+* reaches the model as `{ error }` data, so the agent self-corrects
+* rather than crashing. Extends the framework {@link AIError} (category
+* `"tool"` via code `TOOL_EXEC_FAILED`) so it flows through the same
+* typed error contract as every other AI error; branch on `error.type`
+* for the specific failure.
+*
+* @example
+* if (error instanceof CalculatorError && error.type === "divide-by-zero") {
+*   // the expression divided by zero — ask the model to revise it
+* }
+*/
+var CalculatorError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "CalculatorError";
+		this.type = options.type;
+	}
+};
+/**
+* The `date_time` tool could not complete a call — a required field was
+* missing or malformed, the unit/time zone was unrecognized, or the
+* operation is unsupported.
+*
+* **Surface.** Thrown inside the tool handler, where `tool()` wraps it
+* into a `ToolExecutionError` whose message reaches the model as
+* `{ error }` data so the agent self-corrects. Extends the framework
+* {@link AIError} (category `"tool"` via code `TOOL_EXEC_FAILED`); branch
+* on `error.type` for the specific failure.
+*
+* @example
+* if (error instanceof DateTimeError && error.type === "invalid-unit") {
+*   // the model passed an unknown unit — re-prompt with the allowed set
+* }
+*/
+var DateTimeError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "DateTimeError";
+		this.type = options.type;
+	}
+};
+/**
+* The MCP client's transport layer failed — it could not connect, the
+* peer spoke malformed JSON-RPC, a call timed out, or the transport was
+* already closed.
+*
+* **Surface.** Connection / handshake failures surface at
+* agent-construction time (the caller `await`s `client.tools()`). A
+* `tools/call` failure raised mid-run is wrapped by `tool()` into a
+* `ToolExecutionError` and reaches the model as `{ error }` data, so the
+* agent self-corrects rather than crashing. Extends the framework
+* {@link AIError} (category `"tool"`, code `TOOL_EXEC_FAILED`) so it
+* flows through the same typed error contract as every other AI error;
+* branch on `error.type` for the specific failure.
+*
+* @example
+* if (error instanceof McpTransportError && error.type === "timeout") {
+*   // the remote call exceeded its deadline — retry or escalate
+* }
+*/
+var McpTransportError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "McpTransportError";
+		this.type = options.type;
+		this.method = options.method;
+	}
+};
+/**
+* A web tool failed — a missing optional peer, an absent API key, a host
+* rejected by the `allowHosts` guardrail, an unparseable URL, or a failed
+* network call.
+*
+* **Surface.** Thrown from inside a tool's `execute`, so the framework's
+* `tool()` wrapper catches it and surfaces it in the returned `{ error }`
+* field (`invoke()` never throws) — the agent reads the failure as data
+* and self-corrects rather than crashing. Extends the framework
+* {@link AIError} (category `"tool"` via code `TOOL_EXEC_FAILED`) so it
+* flows through the same typed error contract as every other AI error;
+* branch on `error.type` for the specific failure.
+*
+* @example
+* const { error } = await fetchTool.invoke({ url: "http://evil.test" });
+* if (error instanceof WebToolError && error.type === "denied-host") {
+*   // the host was not in allowHosts — surfaced before any network call
+* }
+*/
+var WebToolError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "WebToolError";
+		this.type = options.type;
+	}
+};
+/**
+* The `http_request` tool refused a call its construction-time policy
+* does not permit — a disallowed method, a host outside the allowlist,
+* or an unparseable URL. The rejection happens *before* any network
+* request, so a guarded tool can never be coaxed into reaching an
+* off-allowlist host (an SSRF guardrail).
+*
+* **Surface.** Thrown from inside the tool's `execute`, so the framework's
+* `tool()` wrapper catches it and surfaces it in the returned `{ error }`
+* field (`invoke()` never throws) — the agent reads the typed failure as
+* data and self-corrects rather than crashing. Extends the framework
+* {@link AIError} (category `"tool"` via code `TOOL_EXEC_FAILED`) so it
+* flows through the same typed error contract as every other AI error;
+* branch on `error.type` for the specific failure.
+*
+* @example
+* const { error } = await httpTool.invoke({ url: "https://evil.test" });
+* if (error instanceof HttpPolicyError && error.type === "host-not-allowed") {
+*   // the model tried to reach a host outside the configured allowlist
+* }
+*/
+var HttpPolicyError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "HttpPolicyError";
+		this.type = options.type;
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/schema.ts
+/**
+* Tiny, dependency-free [Standard Schema](https://standardschema.dev)
+* builders for the tools' input validation. The package pins only
+* `@warlock.js/ai` as a required runtime peer and keeps every heavy
+* dependency optional, so rather than pull in a schema library we
+* hand-roll the few shapes the tools need — exactly the pattern
+* `@warlock.js/ai`'s own `tool()` tests use. Each builder returns a
+* `StandardSchemaV1`, which is what `tool({ input })` validates against
+* before calling `execute`.
+*
+* These intentionally cover only the primitive cases the bundled tools
+* require (`string`, an optional string drawn from a fixed set, an
+* optional string-to-string record, and an opaque passthrough value),
+* plus an `object` of fields. They are not a general-purpose validator.
+*/
+/** The vendor tag stamped on every issue these builders produce. */
+const VENDOR$3 = "ai-tools";
+/** Required string field — rejects anything that is not a string. */
+function stringField$2() {
+	return (value, key) => {
+		if (typeof value === "string") return { value };
+		return { issues: [{
+			message: `"${key}" must be a string`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional string field constrained to a fixed set of allowed values.
+* Accepts `undefined` (the property absent or explicitly undefined) or
+* one of `allowed`; rejects any other string and every non-string type.
+* Used for `method` so an out-of-vocabulary verb is a clean validation
+* error rather than reaching the handler.
+*
+* @param allowed - The exhaustive set of permitted string literals.
+*/
+function optionalStringEnumField(allowed) {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "string" && allowed.includes(value)) return { value };
+		return { issues: [{
+			message: `"${key}" must be one of: ${allowed.join(", ")}`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional string-to-string record field — accepts `undefined` or a flat
+* object whose every value is a string, and rejects arrays, non-objects,
+* and any record with a non-string value. Used for per-call `headers`.
+*/
+function optionalStringRecordField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return { issues: [{
+			message: `"${key}" must be an object of string values when provided`,
+			path: [key]
+		}] };
+		const source = value;
+		const result = {};
+		for (const recordKey of Object.keys(source)) {
+			const entry = source[recordKey];
+			if (typeof entry !== "string") return { issues: [{
+				message: `"${key}.${recordKey}" must be a string`,
+				path: [key, recordKey]
+			}] };
+			result[recordKey] = entry;
+		}
+		return { value: result };
+	};
+}
+/**
+* Opaque passthrough field — accepts any value (including `undefined`)
+* verbatim, performing no validation. Used for a request `body` whose
+* shape the tool deliberately does not constrain: an object is later
+* JSON-serialized, a string is sent as-is.
+*/
+function passthroughField() {
+	return (value) => ({ value });
+}
+/**
+* Build a {@link StandardSchemaV1} for a flat object whose every property
+* is validated by a {@link FieldValidator}. The input must be a non-null
+* object; each declared field is validated and the (possibly coerced)
+* values are collected into the typed result. All field issues are merged
+* so the caller sees every problem at once.
+*
+* `T` is constrained to `object` rather than `Record<string, unknown>` so
+* the tool IO `interface`s (which carry no implicit string index
+* signature) satisfy it directly — only the declared keys in `shape` are
+* ever read, so a string index signature is never required.
+*
+* @example
+* const schema = objectSchema<{ url: string; method?: HttpMethod }>({
+*   url: stringField(),
+*   method: optionalStringEnumField(["GET", "POST"]),
+* });
+*/
+function objectSchema$2(shape) {
+	return { "~standard": {
+		version: 1,
+		vendor: VENDOR$3,
+		validate(input) {
+			if (typeof input !== "object" || input === null || Array.isArray(input)) return { issues: [{ message: "input must be an object" }] };
+			const source = input;
+			const issues = [];
+			const result = {};
+			for (const key of Object.keys(shape)) {
+				const field = shape[key];
+				const present = key in source;
+				const outcome = field(source[key], key);
+				if ("issues" in outcome) {
+					issues.push(...outcome.issues);
+					continue;
+				}
+				if (outcome.value !== void 0 || present) result[key] = outcome.value;
+			}
+			if (issues.length > 0) return { issues };
+			return { value: result };
+		}
+	} };
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/http/http-request.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$4 = "http_request";
+/** Default per-request wall-clock timeout, in milliseconds. */
+const DEFAULT_TIMEOUT_MS$1 = 15e3;
+/** Default hard cap on response-body bytes before truncation. */
+const DEFAULT_MAX_BYTES$1 = 1e6;
+/** The full set of HTTP methods, in the order they appear in {@link HttpMethod}. */
+const ALL_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+];
+/** Methods that conventionally carry no request body — `body` is dropped for these. */
+const BODYLESS_METHODS = new Set(["GET"]);
+/**
+* Standard Schema for {@link HttpRequestInput}. `url` is required;
+* `method` is constrained to the canonical HTTP verb set (further
+* narrowed to the tool's `allowMethods` at runtime); `headers` is an
+* optional string-to-string record; `body` is an opaque passthrough the
+* handler serializes based on its runtime type.
+*/
+const httpRequestInputSchema = objectSchema$2({
+	method: optionalStringEnumField(ALL_METHODS),
+	url: stringField$2(),
+	headers: optionalStringRecordField(),
+	body: passthroughField()
+});
+/**
+* Resolve the request target. With a `baseUrl` configured the model
+* supplies a path joined against it; otherwise the model's `url` must be
+* an absolute `http(s)` URL. Throws a typed {@link HttpPolicyError} of
+* type `"invalid-url"` when the result cannot be parsed or is not an
+* `http`/`https` URL — surfaced as `{ error }` data, never a crash.
+*/
+function resolveUrl(rawUrl, baseUrl) {
+	let resolved;
+	try {
+		resolved = baseUrl !== void 0 ? new URL(rawUrl, baseUrl) : new URL(rawUrl);
+	} catch {
+		throw new HttpPolicyError(`http_request could not resolve a valid URL from "${rawUrl}"` + (baseUrl !== void 0 ? ` against base "${baseUrl}".` : "."), { type: "invalid-url" });
+	}
+	if (resolved.protocol !== "http:" && resolved.protocol !== "https:") throw new HttpPolicyError(`http_request only permits http(s) URLs; got "${resolved.protocol}".`, { type: "invalid-url" });
+	return resolved;
+}
+/**
+* Read a `Response` body, capping at `maxBytes`. Returns the decoded text
+* and whether it was cut off. Streams chunk-by-chunk so an oversized body
+* is abandoned at the cap rather than fully buffered; falls back to
+* `response.text()` (then a post-hoc byte slice) when the body is not a
+* readable stream (e.g. a stubbed `Response` in tests).
+*/
+async function readCappedBody(response, maxBytes) {
+	const body = response.body;
+	if (!body) return {
+		text: "",
+		truncated: false
+	};
+	const decoder = new TextDecoder();
+	const reader = body.getReader();
+	let received = 0;
+	let truncated = false;
+	let text = "";
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			const remaining = maxBytes - received;
+			if (value.byteLength > remaining) {
+				text += decoder.decode(value.subarray(0, remaining), { stream: true });
+				received = maxBytes;
+				truncated = true;
+				break;
+			}
+			text += decoder.decode(value, { stream: true });
+			received += value.byteLength;
+		}
+	} finally {
+		await reader.cancel().catch(() => void 0);
+		reader.releaseLock();
+	}
+	text += decoder.decode();
+	return {
+		text,
+		truncated
+	};
+}
+/**
+* Decide whether a response's `content-type` indicates JSON. Matches
+* `application/json` and the `+json` structured-suffix convention
+* (e.g. `application/vnd.api+json`), case-insensitively.
+*/
+function isJsonContentType(contentType) {
+	if (!contentType) return false;
+	const value = contentType.toLowerCase();
+	return value.includes("application/json") || value.includes("+json");
+}
+/**
+* Build the agent-facing `http_request` tool — a guarded HTTP/REST client
+* over the global `fetch`. The `options` bound what the model may do; the
+* model supplies the per-call URL / method / headers / body within those
+* rails.
+*
+* **Guardrails (all enforced before the network call).**
+* - **Method allowlist** — `allowMethods` (default `["GET"]`). A method
+*   outside the list is rejected with a typed
+*   {@link HttpPolicyError} (`type: "method-not-allowed"`).
+* - **Host allowlist** — when `allowHosts` is set, any other host is
+*   rejected (`type: "host-not-allowed"`), an SSRF guardrail.
+* - **`baseUrl` join** — when configured, the model passes a path that
+*   is resolved against `baseUrl`; otherwise it must pass an absolute
+*   `http(s)` URL. An unresolvable URL is rejected
+*   (`type: "invalid-url"`).
+*
+* **Request shaping.** Static `options.headers` are merged under the
+* per-call `headers` (the per-call value wins). An object `body` is
+* JSON-serialized with a `content-type: application/json` default; a
+* string `body` is sent verbatim; `body` is dropped for bodyless methods
+* (`GET`). The call is bounded by `timeoutMs` (default `15_000`) via an
+* `AbortController`, also wired to `ctx.signal` for cooperative
+* cancellation.
+*
+* **Response shaping.** Headers are returned with lower-cased keys. The
+* body is read up to `maxBytes` (default `1_000_000`) and JSON-parsed
+* when the response `content-type` is JSON, otherwise returned as text;
+* `truncated` is `true` when the body was cut off at the cap (a truncated
+* JSON body is returned as the raw partial string, since it can no longer
+* be parsed).
+*
+* **Errors flow as data.** Every guardrail rejection and network failure
+* is thrown inside `execute`; the framework's `tool()` wrapper catches it
+* and surfaces it in the returned `{ error }` field, so the agent reads
+* the failure and self-corrects rather than crashing.
+*
+* @param options - Construction-time policy bounding the tool.
+* @returns A {@link ToolContract} the agent can call as `http_request`.
+*
+* @example
+* const stripe = httpRequestTool({
+*   baseUrl: "https://api.stripe.com",
+*   allowHosts: ["api.stripe.com"],
+*   allowMethods: ["GET", "POST"],
+*   headers: { authorization: `Bearer ${process.env.STRIPE_KEY}` },
+* });
+* const { data } = await stripe.invoke({ method: "GET", url: "/v1/charges" });
+*/
+function httpRequestTool(options = {}) {
+	const allowMethods = options.allowMethods ?? ["GET"];
+	const allowedMethodSet = new Set(allowMethods);
+	const allowHostSet = options.allowHosts ? new Set(options.allowHosts) : void 0;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS$1;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES$1;
+	const staticHeaders = options.headers;
+	return (0, _warlock_js_ai.tool)({
+		name: options.name ?? DEFAULT_NAME$4,
+		description: "Issue an HTTP request and return the status, response headers, and parsed body. Allowed methods and hosts are restricted by the tool's configuration; a request outside those rails is rejected before any network call. Pass an object body to send JSON, or a string to send it verbatim. The response body is JSON-parsed when the content-type is JSON, otherwise returned as text, and is capped — `truncated` is true when the body was cut off.",
+		action: (input) => `Requesting ${input.method ?? "GET"} ${input.url}`,
+		input: httpRequestInputSchema,
+		async execute(input, ctx) {
+			const method = input.method ?? "GET";
+			if (!allowedMethodSet.has(method)) throw new HttpPolicyError(`http_request method "${method}" is not allowed. Permitted methods: ${[...allowedMethodSet].join(", ")}.`, { type: "method-not-allowed" });
+			const url = resolveUrl(input.url, options.baseUrl);
+			if (allowHostSet && !allowHostSet.has(url.hostname)) throw new HttpPolicyError(`http_request host "${url.hostname}" is not in the allowlist. Permitted hosts: ${[...allowHostSet].join(", ")}.`, { type: "host-not-allowed" });
+			const headers = {
+				...staticHeaders,
+				...input.headers
+			};
+			let body;
+			if (!BODYLESS_METHODS.has(method) && input.body !== void 0) if (typeof input.body === "string") body = input.body;
+			else {
+				body = JSON.stringify(input.body);
+				if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-type")) headers["content-type"] = "application/json";
+			}
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), timeoutMs);
+			const onAbort = () => controller.abort();
+			if (ctx?.signal) if (ctx.signal.aborted) controller.abort();
+			else ctx.signal.addEventListener("abort", onAbort, { once: true });
+			let response;
+			try {
+				response = await fetch(url, {
+					method,
+					headers,
+					body,
+					signal: controller.signal
+				});
+			} finally {
+				clearTimeout(timer);
+				ctx?.signal?.removeEventListener("abort", onAbort);
+			}
+			const responseHeaders = {};
+			response.headers.forEach((value, key) => {
+				responseHeaders[key.toLowerCase()] = value;
+			});
+			const { text, truncated } = await readCappedBody(response, maxBytes);
+			let parsedBody = text;
+			if (!truncated && isJsonContentType(responseHeaders["content-type"]) && text.length > 0) try {
+				parsedBody = JSON.parse(text);
+			} catch {
+				parsedBody = text;
+			}
+			return {
+				status: response.status,
+				headers: responseHeaders,
+				body: parsedBody,
+				truncated
+			};
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/mcp/json-schema-to-standard.ts
+/**
+* The inverse of `@warlock.js/ai`'s `extractJsonSchema` (which goes
+* Standard Schema → JSON Schema). Here we wrap a raw JSON Schema as a
+* {@link StandardSchemaV1} whose `~standard.validate` runs a lazily-imported
+* Ajv validator — so an MCP server's `inputSchema` (JSON Schema) becomes a
+* `ToolConfig.input` the `tool()` factory can validate against.
+*
+* Ajv is an OPTIONAL peer, lazy-imported on first validate following the
+* langfuse/readability pattern: a missing peer surfaces a curated install
+* string (via the returned issues), never a raw module-resolution stack.
+*/
+/** The structural vendor template, mirroring `passthroughSchema()`. */
+const VENDOR$2 = "warlock-ai";
+let AjvSdk;
+let ajvInstance;
+let isAjvAvailable;
+let loadingPromise$1;
+const AJV_INSTALL_INSTRUCTIONS = `
+The MCP client's JSON-Schema validation requires the ajv package.
+Install it with:
+
+  npm install ajv
+
+Or with your preferred package manager:
+
+  pnpm add ajv
+  yarn add ajv
+`.trim();
+/**
+* Settle the lazy import of `ajv` once, concurrency-safe. A bare `catch`
+* flips the availability flag to `false`; the curated install string then
+* surfaces at validate time as a Standard Schema issue, never a raw
+* module-resolution error. The constructed `Ajv` instance is cached and
+* reused for every schema compile.
+*/
+async function loadAjv() {
+	if (isAjvAvailable !== void 0) return;
+	if (loadingPromise$1) return loadingPromise$1;
+	loadingPromise$1 = (async () => {
+		try {
+			AjvSdk = await import("ajv");
+			ajvInstance = new (AjvSdk.default ?? AjvSdk)({
+				allErrors: true,
+				strict: false
+			});
+			isAjvAvailable = true;
+		} catch {
+			isAjvAvailable = false;
+		}
+	})();
+	return loadingPromise$1;
+}
+/**
+* Compile a JSON Schema with the shared Ajv instance, caching the compiled
+* validator on a closure so repeated validations don't recompile. A schema
+* Ajv itself rejects at compile time (an invalid meta-schema) degrades to
+* an accept-all validator so a malformed remote schema can't wedge the
+* tool — the server, not us, owns its schema's correctness.
+*/
+function makeCompiler(schema) {
+	let compiled;
+	let attempted = false;
+	return () => {
+		if (attempted) return compiled;
+		attempted = true;
+		if (!ajvInstance) return;
+		try {
+			compiled = ajvInstance.compile(schema);
+		} catch {
+			compiled = void 0;
+		}
+		return compiled;
+	};
+}
+/**
+* Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose
+* `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`
+* (`{ "~standard": { version: 1, vendor, validate } }`) so it drops into
+* `tool({ input })` exactly like a native seal schema.
+*
+* Validation behavior:
+* - **Valid input** → `{ value }` (the input is passed through unchanged;
+*   Ajv validates, it does not transform).
+* - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +
+*   message per failure, so `tool()` produces a `SchemaValidationError`.
+* - **Missing `ajv` peer** → a single issue carrying the curated install
+*   string, surfaced the same way (a developer-facing message in logs).
+* - **No / empty schema** → an accept-all passthrough (an MCP tool may
+*   advertise no `inputSchema`).
+*
+* @param schema - The JSON Schema (an MCP tool's `inputSchema`), or
+*   `undefined` for a no-argument tool.
+* @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.
+*
+* @example
+* const input = jsonSchemaToStandard<{ q: string }>({
+*   type: "object",
+*   properties: { q: { type: "string" } },
+*   required: ["q"],
+* });
+*/
+function jsonSchemaToStandard(schema) {
+	if (!schema || Object.keys(schema).length === 0) return { "~standard": {
+		version: 1,
+		vendor: VENDOR$2,
+		validate: (value) => ({ value })
+	} };
+	const compile = makeCompiler(schema);
+	return { "~standard": {
+		version: 1,
+		vendor: VENDOR$2,
+		async validate(value) {
+			await loadAjv();
+			if (!isAjvAvailable) return { issues: [{ message: AJV_INSTALL_INSTRUCTIONS }] };
+			const validator = compile();
+			if (!validator) return { value };
+			if (validator(value)) return { value };
+			const issues = (validator.errors ?? []).map((error) => ({
+				message: formatAjvError(error),
+				path: pathFromInstancePath(error.instancePath)
+			}));
+			return { issues: issues.length > 0 ? issues : [{ message: "input failed JSON Schema validation" }] };
+		}
+	} };
+}
+/**
+* Render one Ajv error into a human-readable issue message. Prefixes the
+* failing instance path (when present) so the model can see WHICH field
+* was wrong, e.g. `/query: must be string`.
+*/
+function formatAjvError(error) {
+	return `${error.instancePath ? `${error.instancePath}: ` : ""}${error.message ?? `failed "${error.keyword ?? "validation"}"`}`;
+}
+/**
+* Convert an Ajv `instancePath` (a JSON-Pointer like `/items/0/name`) into
+* the Standard Schema `path` segment array (`["items", "0", "name"]`).
+* Empty paths (a root-level failure) become an empty array.
+*/
+function pathFromInstancePath(instancePath) {
+	if (!instancePath) return [];
+	return instancePath.split("/").filter((segment) => segment.length > 0).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/mcp/transport.ts
+/** Default per-request wait before a transport call is abandoned. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+/** The JSON-RPC version literal every outbound message carries. */
+const JSONRPC_VERSION$1 = "2.0";
+/**
+* Wire a per-call timeout and an optional caller `AbortSignal` onto a
+* pending request, returning a `cleanup()` that tears both down. The
+* `onSettle` callback removes the pending entry from whatever registry the
+* transport keeps so a late response can't double-settle.
+*/
+function armCall(reject, method, options, onSettle) {
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+	const timer = setTimeout(() => {
+		onSettle();
+		reject(new McpTransportError(`MCP request "${method}" timed out after ${timeoutMs}ms.`, {
+			type: "timeout",
+			method
+		}));
+	}, timeoutMs);
+	const onAbort = () => {
+		cleanup();
+		reject(new McpTransportError(`MCP request "${method}" was aborted.`, {
+			type: "closed",
+			method
+		}));
+	};
+	const signal = options?.signal;
+	if (signal) if (signal.aborted) queueMicrotask(onAbort);
+	else signal.addEventListener("abort", onAbort, { once: true });
+	function cleanup() {
+		clearTimeout(timer);
+		if (signal) signal.removeEventListener("abort", onAbort);
+	}
+	return cleanup;
+}
+/**
+* The stdio transport — spawns a child process and speaks JSON-RPC over
+* its stdin/stdout, one JSON object per line (newline-delimited framing).
+* Uses only Node built-ins (`node:child_process` + `node:readline`); no
+* dependency.
+*
+* Constructed via {@link createStdioTransport}; the class itself is
+* internal.
+*/
+var StdioTransport = class {
+	constructor(transport) {
+		this.pending = /* @__PURE__ */ new Map();
+		this.nextId = 1;
+		this.closed = false;
+		let child;
+		try {
+			child = (0, node_child_process.spawn)(transport.command, transport.args ?? [], {
+				env: transport.env,
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new McpTransportError(`MCP stdio transport could not spawn "${transport.command}": ${message}`, {
+				type: "connect",
+				cause
+			});
+		}
+		this.child = child;
+		this.reader = (0, node_readline.createInterface)({ input: child.stdout });
+		this.reader.on("line", (line) => this.onLine(line));
+		child.on("exit", (code) => this.failAll("connect", `child exited with code ${code ?? "null"}`));
+		child.on("error", (error) => this.failAll("connect", error.message));
+	}
+	/**
+	* Parse one stdout line and route it to its pending request. Non-JSON
+	* lines (a server logging to stdout) and messages with no matching `id`
+	* (notifications, stray responses) are ignored — robustness over strictness.
+	*/
+	onLine(line) {
+		const trimmed = line.trim();
+		if (!trimmed) return;
+		let message;
+		try {
+			message = JSON.parse(trimmed);
+		} catch {
+			return;
+		}
+		if (message.id === void 0 || message.id === null) return;
+		const call = this.pending.get(message.id);
+		if (!call) return;
+		this.pending.delete(message.id);
+		call.cleanup();
+		call.resolve(message);
+	}
+	/**
+	* Reject every pending call (and mark the transport unusable) when the
+	* child dies or errors — so a hung server can never leave a caller
+	* waiting forever.
+	*/
+	failAll(type, reason) {
+		this.closed = true;
+		for (const [id, call] of this.pending) {
+			this.pending.delete(id);
+			call.cleanup();
+			call.reject(new McpTransportError(`MCP stdio transport failed: ${reason}.`, { type }));
+		}
+	}
+	request(request, options) {
+		if (this.closed) return Promise.reject(new McpTransportError("MCP stdio transport is closed.", {
+			type: "closed",
+			method: request.method
+		}));
+		const id = request.id;
+		return new Promise((resolve, reject) => {
+			const cleanup = armCall(reject, request.method, options, () => this.pending.delete(id));
+			this.pending.set(id, {
+				resolve: (response) => resolve(response),
+				reject,
+				cleanup
+			});
+			try {
+				this.child.stdin.write(`${JSON.stringify(request)}\n`);
+			} catch (cause) {
+				this.pending.delete(id);
+				cleanup();
+				const message = cause instanceof Error ? cause.message : String(cause);
+				reject(new McpTransportError(`MCP stdio transport failed to write request "${request.method}": ${message}`, {
+					type: "closed",
+					method: request.method,
+					cause
+				}));
+			}
+		});
+	}
+	async notify(method, params) {
+		if (this.closed) throw new McpTransportError("MCP stdio transport is closed.", {
+			type: "closed",
+			method
+		});
+		const notification = {
+			jsonrpc: JSONRPC_VERSION$1,
+			method,
+			params
+		};
+		this.child.stdin.write(`${JSON.stringify(notification)}\n`);
+	}
+	/** Allocate the next outbound request id. */
+	allocateId() {
+		return this.nextId++;
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.reader.close();
+		this.failAll("closed", "transport closed by caller");
+		this.child.kill();
+	}
+};
+/**
+* The Streamable HTTP transport — POSTs each JSON-RPC request to the
+* server endpoint over the global `fetch` (Node 18+) and reads the single
+* JSON response. No SSE-legacy, no WebSocket. Static `headers` (e.g. auth)
+* are sent with every request.
+*
+* Constructed via {@link createHttpTransport}; the class itself is internal.
+*/
+var HttpTransport = class {
+	constructor(transport) {
+		this.nextId = 1;
+		this.url = transport.url;
+		this.headers = {
+			"content-type": "application/json",
+			accept: "application/json, text/event-stream",
+			...transport.headers
+		};
+	}
+	async request(request, options) {
+		const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		const onAbort = () => controller.abort();
+		const signal = options?.signal;
+		if (signal) if (signal.aborted) controller.abort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+		let response;
+		try {
+			response = await fetch(this.url, {
+				method: "POST",
+				headers: this.headers,
+				body: JSON.stringify(request),
+				signal: controller.signal
+			});
+		} catch (cause) {
+			const aborted = controller.signal.aborted;
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new McpTransportError(aborted ? `MCP request "${request.method}" timed out or was aborted after ${timeoutMs}ms.` : `MCP http transport request "${request.method}" failed: ${message}`, {
+				type: aborted ? "timeout" : "connect",
+				method: request.method,
+				cause
+			});
+		} finally {
+			clearTimeout(timer);
+			if (signal) signal.removeEventListener("abort", onAbort);
+		}
+		if (!response.ok) throw new McpTransportError(`MCP http transport request "${request.method}" returned HTTP ${response.status}.`, {
+			type: "connect",
+			method: request.method,
+			context: { status: response.status }
+		});
+		return this.parseBody(response, request.method);
+	}
+	/**
+	* Parse the HTTP response body into a JSON-RPC response. Streamable HTTP
+	* may answer with either `application/json` (a single response object)
+	* or `text/event-stream` (SSE frames); we read the body as text and
+	* extract the first JSON object, supporting the common `data: {...}`
+	* SSE line shape without a streaming parser.
+	*/
+	async parseBody(response, method) {
+		const raw = await response.text();
+		const jsonText = (response.headers.get("content-type")?.toLowerCase() ?? "").includes("text/event-stream") ? extractSseData(raw) : raw;
+		if (!jsonText) throw new McpTransportError(`MCP http transport got an empty response for "${method}".`, {
+			type: "protocol",
+			method
+		});
+		try {
+			return JSON.parse(jsonText);
+		} catch (cause) {
+			throw new McpTransportError(`MCP http transport got a non-JSON response for "${method}".`, {
+				type: "protocol",
+				method,
+				cause
+			});
+		}
+	}
+	async notify(method, params) {
+		const notification = {
+			jsonrpc: JSONRPC_VERSION$1,
+			method,
+			params
+		};
+		try {
+			await fetch(this.url, {
+				method: "POST",
+				headers: this.headers,
+				body: JSON.stringify(notification)
+			});
+		} catch (cause) {
+			throw new McpTransportError(`MCP http transport notification "${method}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+				type: "connect",
+				method,
+				cause
+			});
+		}
+	}
+	/** Allocate the next outbound request id. */
+	allocateId() {
+		return this.nextId++;
+	}
+	async close() {}
+};
+/**
+* Pull the first `data:` JSON payload out of an SSE response body. MCP's
+* Streamable HTTP transport answers a single request with one SSE frame
+* carrying the JSON-RPC response; we take the first non-empty `data:`
+* line. Returns an empty string when none is found.
+*/
+function extractSseData(body) {
+	for (const line of body.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed.startsWith("data:")) {
+			const payload = trimmed.slice(5).trim();
+			if (payload && payload !== "[DONE]") return payload;
+		}
+	}
+	return "";
+}
+/**
+* Build the concrete {@link McpTransportClient} for an {@link McpTransport}
+* config — a {@link StdioTransport} for `type: "stdio"`, an
+* {@link HttpTransport} for `type: "http"`. The returned client also
+* carries an `allocateId()` for the JSON-RPC client to mint request ids.
+*
+* @param transport - The transport config (discriminated by `type`).
+* @returns A transport client paired with its id allocator.
+*/
+function createTransport(transport) {
+	if (transport.type === "stdio") return new StdioTransport(transport);
+	return new HttpTransport(transport);
+}
+/**
+* A minimal JSON-RPC 2.0 request/response client over any
+* {@link McpTransportClient}. Mints monotonic ids, frames the
+* `{ jsonrpc, id, method, params }` envelope, and unwraps the response —
+* translating a JSON-RPC `error` member into a typed
+* {@link McpTransportError} so callers branch on `error.type` rather than
+* parsing the wire.
+*
+* Constructed via {@link createJsonRpcClient}; the class itself is internal.
+*/
+var JsonRpcClient = class {
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/**
+	* Issue a JSON-RPC `method` call and resolve with its `result`,
+	* throwing a typed {@link McpTransportError} on a JSON-RPC error member
+	* or a malformed response (neither `result` nor `error`).
+	*/
+	async call(method, params, options) {
+		const request = {
+			jsonrpc: JSONRPC_VERSION$1,
+			id: this.transport.allocateId(),
+			method,
+			params
+		};
+		const response = await this.transport.request(request, options);
+		if (response.error) throw new McpTransportError(`MCP "${method}" failed: ${response.error.message} (code ${response.error.code}).`, {
+			type: "protocol",
+			method,
+			context: { code: response.error.code },
+			cause: response.error.data
+		});
+		if (response.result === void 0) throw new McpTransportError(`MCP "${method}" returned a response with neither result nor error.`, {
+			type: "protocol",
+			method
+		});
+		return response.result;
+	}
+	/** Send a one-way JSON-RPC notification (no response awaited). */
+	notify(method, params) {
+		return this.transport.notify(method, params);
+	}
+	/** Close the underlying transport. */
+	close() {
+		return this.transport.close();
+	}
+};
+/**
+* Build a {@link JsonRpcClientHandle} over a transport. Accepts either a
+* pre-built {@link McpTransportClient} (the test seam — inject a scripted
+* fake) or an {@link McpTransport} config, in which case the concrete
+* transport is constructed via {@link createTransport}.
+*
+* When a bare {@link McpTransportClient} (without an `allocateId`) is
+* injected, the client supplies its own monotonic id source.
+*
+* @param source - A transport client or an `McpTransport` config.
+* @returns A JSON-RPC client handle.
+*/
+function createJsonRpcClient(source) {
+	return new JsonRpcClient(isTransportConfig(source) ? createTransport(source) : withIdAllocator(source));
+}
+/**
+* Distinguish an {@link McpTransport} config (a plain object with a `type`
+* discriminator and no `request` method) from a built
+* {@link McpTransportClient} (which exposes `request`).
+*/
+function isTransportConfig(source) {
+	return typeof source.request !== "function";
+}
+/**
+* Wrap an injected {@link McpTransportClient} that lacks its own
+* `allocateId` with a monotonic id source, so the JSON-RPC client can mint
+* request ids uniformly regardless of whether the transport was built here
+* or supplied by a test.
+*/
+function withIdAllocator(client) {
+	const candidate = client;
+	if (typeof candidate.allocateId === "function") return candidate;
+	let nextId = 1;
+	return Object.assign(client, { allocateId: () => nextId++ });
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/mcp/client.ts
+/** Default per-call timeout for `tools/call`. */
+const DEFAULT_CALL_TIMEOUT_MS = 3e4;
+/** The MCP protocol version this client advertises in `initialize`. */
+const PROTOCOL_VERSION$1 = "2025-06-18";
+/**
+* The internal {@link McpClient} implementation. Owns one JSON-RPC client
+* over a transport, runs the `initialize` handshake on first use, lists
+* the server's tools, and adapts each into a {@link ToolContract} whose
+* `execute` issues `tools/call`. The adapted contracts are cached after
+* the first `tools()` so repeat calls don't re-handshake.
+*
+* Constructed via {@link mcp}; the class itself is internal.
+*/
+var McpClientImpl = class {
+	constructor(source, options = {}) {
+		this.initialized = false;
+		this.rpc = createJsonRpcClient(source);
+		this.options = options;
+	}
+	/**
+	* Run the MCP `initialize` handshake exactly once, then send the
+	* `notifications/initialized` notification the protocol requires before
+	* any other request. Wraps a handshake failure as a typed
+	* {@link McpTransportError} of type `"connect"`.
+	*/
+	async handshake() {
+		if (this.initialized) return;
+		try {
+			await this.rpc.call("initialize", {
+				protocolVersion: PROTOCOL_VERSION$1,
+				capabilities: {},
+				clientInfo: {
+					name: "@warlock.js/ai-tools",
+					version: "4.4.0"
+				}
+			});
+			await this.rpc.notify("notifications/initialized");
+		} catch (cause) {
+			if (cause instanceof McpTransportError) throw cause;
+			throw new McpTransportError(`MCP initialize handshake failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+				type: "connect",
+				method: "initialize",
+				cause
+			});
+		}
+		this.initialized = true;
+	}
+	tools() {
+		if (this.cached) return Promise.resolve(this.cached);
+		if (this.pending) return this.pending;
+		this.pending = this.listAndAdapt().then((tools) => {
+			this.cached = tools;
+			return tools;
+		}).finally(() => {
+			this.pending = void 0;
+		});
+		return this.pending;
+	}
+	/**
+	* Handshake, `tools/list`, and adapt each descriptor into a
+	* {@link ToolContract}, applying the `filter` and `namePrefix` options.
+	*/
+	async listAndAdapt() {
+		await this.handshake();
+		const descriptors = (await this.rpc.call("tools/list")).tools ?? [];
+		const filter = this.options.filter;
+		return (filter ? descriptors.filter((d) => filter(d.name)) : descriptors).map((descriptor) => this.adapt(descriptor));
+	}
+	/**
+	* Adapt one remote tool descriptor into a {@link ToolContract}: build
+	* the input schema from its JSON Schema via {@link jsonSchemaToStandard},
+	* prefix the name, and route `execute` through a `tools/call` that
+	* honors `ctx.signal`, unwraps the content blocks, and throws on an
+	* `isError` result so `tool()` wraps it.
+	*/
+	adapt(descriptor) {
+		const prefixedName = `${this.options.namePrefix ?? ""}${descriptor.name}`;
+		const remoteName = descriptor.name;
+		const timeoutMs = this.options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+		const input = jsonSchemaToStandard(descriptor.inputSchema);
+		return (0, _warlock_js_ai.tool)({
+			name: prefixedName,
+			description: descriptor.description ?? `Invoke the remote MCP tool "${remoteName}".`,
+			input,
+			execute: async (args, ctx) => {
+				const result = await this.rpc.call("tools/call", {
+					name: remoteName,
+					arguments: args ?? {}
+				}, {
+					signal: ctx?.signal,
+					timeoutMs
+				});
+				if (result.isError) throw new McpTransportError(`MCP tool "${remoteName}" returned an error: ${unwrapContent(result.content)}`, {
+					type: "protocol",
+					method: "tools/call"
+				});
+				return unwrapResult(result.content);
+			}
+		});
+	}
+	close() {
+		return this.rpc.close();
+	}
+};
+/**
+* Flatten an MCP `tools/call` result's content blocks into the value a
+* tool returns. Text blocks are concatenated; a single block whose text is
+* valid JSON is parsed so structured tool output flows back as an object
+* rather than a string. Non-text blocks are preserved as `type`-tagged
+* objects (MCP's wire `type` is kept; any inbound `kind` is normalized to
+* `type`).
+*/
+function unwrapResult(content) {
+	const blocks = content ?? [];
+	if (blocks.length === 1 && blocks[0].type === "text") return tryParseJson(blocks[0].text ?? "");
+	return blocks.map((block) => normalizeBlock(block));
+}
+/**
+* Render content blocks to a short human string for error messages — the
+* concatenated text of every text block.
+*/
+function unwrapContent(content) {
+	return (content ?? []).filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join(" ").trim();
+}
+/**
+* Normalize one content block onto our `type`-only shape: translate an
+* inbound `kind` discriminator to `type` (and strip `kind`) so the value a
+* tool returns never carries MCP's `kind` vocabulary.
+*/
+function normalizeBlock(block) {
+	const { kind, ...rest } = block;
+	const type = block.type ?? kind ?? "unknown";
+	return {
+		...rest,
+		type
+	};
+}
+/**
+* Parse a string as JSON, returning the parsed value on success or the
+* original string when it is not JSON — so a plain-text tool result stays
+* a string while a JSON tool result becomes an object.
+*/
+function tryParseJson(text) {
+	const trimmed = text.trim();
+	if (!trimmed) return text;
+	const first = trimmed[0];
+	if (first !== "{" && first !== "[") return text;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return text;
+	}
+}
+/**
+* Connect to an external MCP server and adapt its tools as agent tools
+* (Direction A: server → local agent tools).
+*
+* Opens the transport lazily and exposes {@link McpClient.tools}, which on
+* first call runs the `initialize` handshake, lists the server's tools via
+* `tools/list`, and maps each into a {@link ToolContract}:
+* - **input schema** — the remote tool's JSON Schema is wrapped as a
+*   Standard Schema via {@link jsonSchemaToStandard} (Ajv-backed, an
+*   optional peer);
+* - **execute** — issues `tools/call` honoring `ctx.signal` and the
+*   configured `timeoutMs`, unwraps the result content, and throws on an
+*   `isError` result so the `tool()` wrapper surfaces it as `{ error }`;
+* - **name** — prefixed with `options.namePrefix` to avoid local
+*   collisions; only tools passing `options.filter` are adapted.
+*
+* The adapted contracts are cached after the first `tools()` call, so the
+* handshake + list happen exactly once. The returned contracts drop
+* straight into `ai.agent({ tools: [...] })`.
+*
+* @param server - The transport config (`{ type: "stdio" }` /
+*   `{ type: "http" }`). A pre-built transport client may be injected for
+*   testing.
+* @param options - Prefix / filter / per-call timeout.
+* @returns An {@link McpClient} handle.
+*
+* @example
+* const github = mcp(
+*   { type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+*   { namePrefix: "github." },
+* );
+* const dev = ai.agent({ model, tools: [...(await github.tools())] });
+*/
+function mcp$1(server, options) {
+	return new McpClientImpl(server, options);
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/mcp/serve.ts
+/** JSON-RPC version literal every outbound message carries. */
+const JSONRPC_VERSION = "2.0";
+/** Default JSON-Schema dialect emitted for each tool's `inputSchema`. */
+const DEFAULT_SCHEMA_TARGET = "draft-2020-12";
+/** Default advertised server version when the caller omits one. */
+const DEFAULT_VERSION = "4.4.0";
+/** The MCP protocol version this server advertises in `initialize`. */
+const PROTOCOL_VERSION = "2025-06-18";
+/** JSON-RPC standard error codes we emit. */
+const JSON_RPC_METHOD_NOT_FOUND = -32601;
+const JSON_RPC_INVALID_PARAMS = -32602;
+/**
+* Resolve the {@link McpServeSource} (either an object exposing `tools()`
+* or a literal `ToolContract[]`) into a flat contract array.
+*/
+function resolveTools(source) {
+	if (Array.isArray(source)) return source;
+	return source.tools();
+}
+/**
+* The pure protocol core of `serve` — maps one JSON-RPC request to its
+* response, with no I/O. Both the stdio and http serve-transports pump
+* their inbound requests through this, and specs can drive it directly.
+*
+* Handles exactly the MCP slice this package serves: `initialize`,
+* `tools/list`, and `tools/call`. Any other method answers with a
+* JSON-RPC `method not found` error.
+*
+* Constructed via {@link createServeHandler}.
+*/
+var McpServeHandler = class {
+	constructor(source, options) {
+		this.tools = resolveTools(source);
+		this.byName = new Map(this.tools.map((contract) => [contract.name, contract]));
+		this.options = options;
+	}
+	/**
+	* Dispatch one inbound JSON-RPC request to its handler and produce the
+	* response. A handler that throws is mapped to a JSON-RPC error response
+	* — the serve loop never crashes on a bad request.
+	*/
+	async handle(request) {
+		try {
+			switch (request.method) {
+				case "initialize": return this.ok(request.id, this.initializeResult());
+				case "tools/list": return this.ok(request.id, { tools: this.listTools() });
+				case "tools/call": return this.ok(request.id, await this.callTool(request.params));
+				default: return this.error(request.id, JSON_RPC_METHOD_NOT_FOUND, `Method "${request.method}" is not supported by this MCP server.`);
+			}
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			return this.error(request.id, JSON_RPC_INVALID_PARAMS, message);
+		}
+	}
+	/** Build the `initialize` result advertising name / version / capabilities. */
+	initializeResult() {
+		return {
+			protocolVersion: PROTOCOL_VERSION,
+			capabilities: { tools: {} },
+			serverInfo: {
+				name: this.options.name,
+				version: this.options.version ?? DEFAULT_VERSION
+			}
+		};
+	}
+	/**
+	* Build the `tools/list` payload: one {@link McpToolDescriptor} per
+	* contract, its `inputSchema` extracted via `extractJsonSchema` at the
+	* configured dialect (default `draft-2020-12` — overriding
+	* `extractJsonSchema`'s own `openai-strict` default to a neutral MCP draft).
+	*/
+	listTools() {
+		const target = this.options.schemaTarget ?? DEFAULT_SCHEMA_TARGET;
+		return this.tools.map((contract) => {
+			const inputSchema = (0, _warlock_js_ai.extractJsonSchema)(contract.input, { target }) ?? {
+				type: "object",
+				properties: {}
+			};
+			return {
+				name: contract.name,
+				description: contract.description,
+				inputSchema
+			};
+		});
+	}
+	/**
+	* Route a `tools/call` to the named contract's `invoke()` and map the
+	* never-throwing {@link import("@warlock.js/ai").ToolInvokeResult}: `data`
+	* → a text content block, `error` → an `isError: true` result. An unknown
+	* tool name throws (mapped to a JSON-RPC error by {@link handle}).
+	*/
+	async callTool(params) {
+		const { name, args } = readCallParams(params);
+		const contract = this.byName.get(name);
+		if (!contract) throw new McpTransportError(`Unknown tool "${name}".`, {
+			type: "protocol",
+			method: "tools/call"
+		});
+		const result = await contract.invoke(args);
+		if (result.error) return {
+			content: [{
+				type: "text",
+				text: result.error.message
+			}],
+			isError: true
+		};
+		return {
+			content: [{
+				type: "text",
+				text: serializeData(result.data)
+			}],
+			isError: false
+		};
+	}
+	/** Build a JSON-RPC success response. */
+	ok(id, result) {
+		return {
+			jsonrpc: JSONRPC_VERSION,
+			id,
+			result
+		};
+	}
+	/** Build a JSON-RPC error response. */
+	error(id, code, message) {
+		return {
+			jsonrpc: JSONRPC_VERSION,
+			id,
+			error: {
+				code,
+				message
+			}
+		};
+	}
+};
+/**
+* Read and validate the `tools/call` params into `{ name, args }`. Throws
+* a typed {@link McpTransportError} when `name` is missing — mapped to a
+* JSON-RPC `invalid params` error by the handler.
+*/
+function readCallParams(params) {
+	if (typeof params !== "object" || params === null) throw new McpTransportError("tools/call params must be an object.", {
+		type: "protocol",
+		method: "tools/call"
+	});
+	const record = params;
+	if (typeof record.name !== "string") throw new McpTransportError("tools/call requires a string `name`.", {
+		type: "protocol",
+		method: "tools/call"
+	});
+	return {
+		name: record.name,
+		args: record.arguments ?? {}
+	};
+}
+/**
+* Serialize a tool's `data` for an MCP text content block — a string is
+* passed verbatim, everything else is JSON-stringified so structured
+* output crosses the wire as text the consuming client can re-parse.
+*/
+function serializeData(data) {
+	if (typeof data === "string") return data;
+	if (data === void 0) return "";
+	return JSON.stringify(data);
+}
+/**
+* Build the pure protocol handler for a serve source. Exposed (alongside
+* {@link serve}) so callers and tests can drive the MCP protocol without an
+* actual transport — feed it a JSON-RPC request, get the response.
+*
+* @param source - The tools to expose (an object with `tools()` or a literal array).
+* @param options - Serve options (name / version / schema target).
+* @returns An object whose `handle(request)` maps a request to a response.
+*/
+function createServeHandler(source, options) {
+	return new McpServeHandler(source, options);
+}
+/**
+* The internal {@link McpServer} — owns a {@link McpServeHandler} and a
+* transport pump. For `stdio` it reads newline-delimited JSON-RPC requests
+* from `process.stdin` and writes responses to `process.stdout`; the
+* `http` transport is accepted but listening is deferred to the host
+* (a serve-over-HTTP needs a server the caller owns).
+*
+* Constructed via {@link serve}; the class itself is internal.
+*/
+var McpServerImpl = class {
+	constructor(source, options) {
+		this.running = false;
+		this.handler = new McpServeHandler(source, options);
+		this.options = options;
+	}
+	async start() {
+		if (this.running) return;
+		if ((this.options.transport ?? { type: "stdio" }).type !== "stdio") throw new McpTransportError("serve() over http requires a host-provided server; only stdio is auto-pumped.", { type: "connect" });
+		this.running = true;
+		this.reader = (0, node_readline.createInterface)({ input: process.stdin });
+		this.reader.on("line", (line) => {
+			this.onLine(line);
+		});
+	}
+	/**
+	* Parse one stdin line as a JSON-RPC request, dispatch it through the
+	* handler, and write the response as a single line to stdout. Non-JSON
+	* lines and notifications (no `id`) are ignored.
+	*/
+	async onLine(line) {
+		const trimmed = line.trim();
+		if (!trimmed) return;
+		let request;
+		try {
+			request = JSON.parse(trimmed);
+		} catch {
+			return;
+		}
+		if (request.id === void 0 || request.id === null) return;
+		const response = await this.handler.handle(request);
+		process.stdout.write(`${JSON.stringify(response)}\n`);
+	}
+	async stop() {
+		this.running = false;
+		this.reader?.close();
+		this.reader = void 0;
+	}
+};
+/**
+* Expose a built agent / supervisor / orchestrator (or a raw
+* `ToolContract[]`) AS an MCP server (Direction B: local primitive → MCP
+* server other clients consume).
+*
+* Enumerates `source.tools()` (or the literal array) once at construction.
+* `tools/list` answers with each tool's `inputSchema` extracted via
+* `extractJsonSchema` at the configured `schemaTarget` (default
+* `draft-2020-12`). `tools/call` routes to the named contract's
+* `invoke()` and maps the never-throwing result — `data` becomes a text
+* content block, `error` becomes an `isError: true` result — so a failing
+* tool surfaces as a normal MCP tool error rather than crashing the server.
+*
+* The default transport is `stdio`, pumped over `process.stdin` /
+* `process.stdout`. Serving over HTTP is left to a host-owned server;
+* `start()` rejects an `http` transport (the protocol core is available
+* via {@link createServeHandler} for a caller's own HTTP wiring).
+*
+* @param source - The tools to expose.
+* @param options - Server name, version, transport, and schema dialect.
+* @returns An {@link McpServer} with `start()` / `stop()`.
+*
+* @example
+* serve(
+*   { tools: () => ws.allTools() },
+*   { name: "warlock-workspace", transport: { type: "stdio" } },
+* ).start();
+*/
+function serve(source, options) {
+	return new McpServerImpl(source, options);
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/mcp/index.ts
+/**
+* The `ai.mcp` factory value: the client factory with `.serve` attached.
+* `Object.assign` keeps `mcp` callable (Direction A) while widening it with
+* the `serve` member (Direction B) — one object, both directions. The
+* `declare module "@warlock.js/ai"` augmentation and the runtime
+* registration (`ai.mcp = mcp`) live in `../register`, so this barrel is a
+* pure value/type module the registrar consumes.
+*/
+const mcp = Object.assign((server, options) => mcp$1(server, options), { serve });
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/utility/schema.ts
+/**
+* Tiny, dependency-free [Standard Schema](https://standardschema.dev)
+* builders for the utility tools' input validation. This package pins
+* only `@warlock.js/ai` as a runtime peer, so rather than pull in a
+* schema library we hand-roll the few field shapes the calculator and
+* date-time tools need — the same approach `@warlock.js/ai`'s own
+* `tool()` tests use. Each builder returns a {@link StandardSchemaV1},
+* which is what `tool({ input })` validates against before calling
+* `execute`.
+*
+* These intentionally cover only the primitive cases the UTILITY tools
+* require (`string`, `optional string`, `optional number`, and a
+* `literal union` enum). They are not a general-purpose validator.
+*/
+/** The vendor tag stamped on every issue these builders produce. */
+const VENDOR$1 = "ai-tools";
+/** Required string field — rejects anything that is not a string. */
+function stringField$1() {
+	return (value, key) => {
+		if (typeof value === "string") return { value };
+		return { issues: [{
+			message: `"${key}" must be a string`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional string field — accepts `undefined` (the property absent or
+* explicitly undefined) or a string, and rejects every other type.
+*/
+function optionalStringField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "string") return { value };
+		return { issues: [{
+			message: `"${key}" must be a string when provided`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional finite-number field — accepts `undefined` or a finite number,
+* rejecting `NaN`/`Infinity` and non-number types.
+*/
+function optionalNumberField$1() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "number" && Number.isFinite(value)) return { value };
+		return { issues: [{
+			message: `"${key}" must be a finite number when provided`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Required literal-union field — accepts only one of `allowed`, rejecting
+* everything else. Used for discriminators like the date-time `op`.
+*
+* @param allowed - The closed set of permitted string literals.
+*/
+function literalField(allowed) {
+	return (value, key) => {
+		if (typeof value === "string" && allowed.includes(value)) return { value };
+		return { issues: [{
+			message: `"${key}" must be one of: ${allowed.join(", ")}`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Build a {@link StandardSchemaV1} for a flat object whose every property
+* is validated by a {@link FieldValidator}. The input must be a non-null
+* object; each declared field is validated and the (possibly coerced)
+* values are collected into the typed result. All field issues are merged
+* so the caller sees every problem at once.
+*
+* `T` is constrained to `object` rather than `Record<string, unknown>` so
+* the tool IO `interface`s (which carry no implicit string index
+* signature) satisfy it directly — only the declared keys in `shape` are
+* ever read, so a string index signature is never required.
+*
+* @example
+* const schema = objectSchema<{ expression: string }>({
+*   expression: stringField(),
+* });
+*/
+function objectSchema$1(shape) {
+	return { "~standard": {
+		version: 1,
+		vendor: VENDOR$1,
+		validate(input) {
+			if (typeof input !== "object" || input === null || Array.isArray(input)) return { issues: [{ message: "input must be an object" }] };
+			const source = input;
+			const issues = [];
+			const result = {};
+			for (const key of Object.keys(shape)) {
+				const field = shape[key];
+				const outcome = field(source[key], key);
+				if ("issues" in outcome) {
+					issues.push(...outcome.issues);
+					continue;
+				}
+				if (outcome.value !== void 0) result[key] = outcome.value;
+			}
+			if (issues.length > 0) return { issues };
+			return { value: result };
+		}
+	} };
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/utility/calculator.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$3 = "calculator";
+/** Input schema for the `calculator` tool: a single `expression` string. */
+const inputSchema$3 = objectSchema$1({ expression: stringField$1() });
+/** The closed set of supported binary operators. */
+const OPERATORS = {
+	"+": {
+		precedence: 1,
+		associativity: "left",
+		apply: (a, b) => a + b
+	},
+	"-": {
+		precedence: 1,
+		associativity: "left",
+		apply: (a, b) => a - b
+	},
+	"*": {
+		precedence: 2,
+		associativity: "left",
+		apply: (a, b) => a * b
+	},
+	"/": {
+		precedence: 2,
+		associativity: "left",
+		apply: (a, b) => {
+			if (b === 0) throw new CalculatorError("Division by zero.", { type: "divide-by-zero" });
+			return a / b;
+		}
+	},
+	"%": {
+		precedence: 2,
+		associativity: "left",
+		apply: (a, b) => {
+			if (b === 0) throw new CalculatorError("Modulo by zero.", { type: "divide-by-zero" });
+			return a % b;
+		}
+	},
+	"^": {
+		precedence: 3,
+		associativity: "right",
+		apply: (a, b) => a ** b
+	}
+};
+/**
+* Tokenize an arithmetic expression into {@link Token}s. Recognizes
+* decimal and scientific-notation numbers (`3`, `4.5`, `1e3`, `2.5E-2`),
+* the operators in {@link OPERATORS}, and parentheses; whitespace is
+* skipped. Any other character is a syntax error — there is no path to
+* an identifier, function call, or property access, so nothing
+* code-like can be smuggled in.
+*
+* @throws CalculatorError `type: "syntax"` on an unrecognized character
+*   or a malformed number.
+*/
+function tokenize(expression) {
+	const tokens = [];
+	let index = 0;
+	while (index < expression.length) {
+		const char = expression[index];
+		if (char === " " || char === "	" || char === "\n" || char === "\r") {
+			index += 1;
+			continue;
+		}
+		if (char === "(" || char === ")") {
+			tokens.push({
+				type: "paren",
+				value: char
+			});
+			index += 1;
+			continue;
+		}
+		if (char in OPERATORS) {
+			tokens.push({
+				type: "operator",
+				value: char
+			});
+			index += 1;
+			continue;
+		}
+		if (isDigit(char) || char === ".") {
+			const { value, nextIndex } = readNumber(expression, index);
+			tokens.push({
+				type: "number",
+				value
+			});
+			index = nextIndex;
+			continue;
+		}
+		throw new CalculatorError(`Unexpected character "${char}" at position ${index}. Only numbers, parentheses, and the operators + - * / % ^ are allowed.`, { type: "syntax" });
+	}
+	return tokens;
+}
+/** True for an ASCII digit `0`–`9`. */
+function isDigit(char) {
+	return char >= "0" && char <= "9";
+}
+/**
+* Read a single number literal starting at `start`. Consumes an optional
+* integer part, optional fraction, and optional exponent
+* (`e`/`E` with an optional sign). Returns the parsed value and the index
+* just past the literal.
+*
+* @throws CalculatorError `type: "syntax"` if the consumed run is not a
+*   valid finite number (e.g. a lone `.` or `1e` with no exponent).
+*/
+function readNumber(expression, start) {
+	let index = start;
+	while (index < expression.length && isDigit(expression[index])) index += 1;
+	if (expression[index] === ".") {
+		index += 1;
+		while (index < expression.length && isDigit(expression[index])) index += 1;
+	}
+	if (expression[index] === "e" || expression[index] === "E") {
+		index += 1;
+		if (expression[index] === "+" || expression[index] === "-") index += 1;
+		while (index < expression.length && isDigit(expression[index])) index += 1;
+	}
+	const literal = expression.slice(start, index);
+	const value = Number(literal);
+	if (!Number.isFinite(value)) throw new CalculatorError(`Invalid number literal "${literal}".`, { type: "syntax" });
+	return {
+		value,
+		nextIndex: index
+	};
+}
+/**
+* Evaluate a token stream with a single left-to-right pass that resolves
+* unary signs, then a shunting-yard conversion that interleaves operator
+* application — so the result is produced without ever building an AST or
+* calling `eval`/`Function`.
+*
+* Unary `+`/`-` are detected positionally: a `+`/`-` is unary when it
+* starts the expression or directly follows another operator or an
+* opening paren. A unary `-` folds into the following number literal
+* (and a unary `+` is a no-op), which keeps the operator stack purely
+* binary.
+*
+* @throws CalculatorError on malformed structure (`type: "syntax"`),
+*   division/modulo by zero (`type: "divide-by-zero"`), or a non-finite
+*   result (`type: "overflow"`).
+*/
+function evaluate(tokens) {
+	const values = [];
+	const operators = [];
+	/** Pop the top operator and apply it to the top two values. */
+	const applyTop = () => {
+		const operator = operators.pop();
+		if (operator === void 0) throw new CalculatorError("Malformed expression.", { type: "syntax" });
+		const right = values.pop();
+		const left = values.pop();
+		if (left === void 0 || right === void 0) throw new CalculatorError(`Operator "${operator}" is missing an operand.`, { type: "syntax" });
+		values.push(OPERATORS[operator].apply(left, right));
+	};
+	let expectOperand = true;
+	let pendingSign = 1;
+	for (let i = 0; i < tokens.length; i += 1) {
+		const token = tokens[i];
+		if (token.type === "number") {
+			if (!expectOperand) throw new CalculatorError("Unexpected number — a number cannot directly follow another value.", { type: "syntax" });
+			values.push(pendingSign * token.value);
+			pendingSign = 1;
+			expectOperand = false;
+			continue;
+		}
+		if (token.type === "paren") {
+			if (token.value === "(") {
+				if (!expectOperand) throw new CalculatorError("Unexpected \"(\" — it cannot directly follow a value.", { type: "syntax" });
+				if (pendingSign === -1) {
+					values.push(-1);
+					operators.push("*");
+					pendingSign = 1;
+				}
+				operators.push("(");
+				expectOperand = true;
+				continue;
+			}
+			if (expectOperand) throw new CalculatorError("Unexpected \")\" — an operand was expected.", { type: "syntax" });
+			let foundOpen = false;
+			while (operators.length > 0) {
+				if (operators[operators.length - 1] === "(") {
+					operators.pop();
+					foundOpen = true;
+					break;
+				}
+				applyTop();
+			}
+			if (!foundOpen) throw new CalculatorError("Unbalanced parentheses.", { type: "syntax" });
+			expectOperand = false;
+			continue;
+		}
+		if (expectOperand) {
+			if (token.value === "-") {
+				pendingSign = -pendingSign;
+				continue;
+			}
+			if (token.value === "+") continue;
+			throw new CalculatorError(`Operator "${token.value}" has no left-hand operand.`, { type: "syntax" });
+		}
+		const incoming = OPERATORS[token.value];
+		while (operators.length > 0) {
+			const top = operators[operators.length - 1];
+			if (top === "(") break;
+			const topSpec = OPERATORS[top];
+			const higher = topSpec.precedence > incoming.precedence;
+			const equalLeft = topSpec.precedence === incoming.precedence && incoming.associativity === "left";
+			if (higher || equalLeft) {
+				applyTop();
+				continue;
+			}
+			break;
+		}
+		operators.push(token.value);
+		expectOperand = true;
+	}
+	if (expectOperand) throw new CalculatorError("Expression ends with an operator or is empty.", { type: "syntax" });
+	while (operators.length > 0) {
+		if (operators[operators.length - 1] === "(") throw new CalculatorError("Unbalanced parentheses.", { type: "syntax" });
+		applyTop();
+	}
+	const result = values.pop();
+	if (result === void 0 || values.length > 0) throw new CalculatorError("Malformed expression.", { type: "syntax" });
+	if (!Number.isFinite(result)) throw new CalculatorError("Result is not a finite number.", { type: "overflow" });
+	return result;
+}
+/**
+* Build the `calculator` tool — a SAFE arithmetic evaluator the agent can
+* call to compute a numeric expression. It supports `+ - * / % ^`, unary
+* signs, parentheses, and decimal/scientific-notation literals, with the
+* usual precedence (`^` highest and right-associative, then `* / %`, then
+* `+ -`).
+*
+* **Safety.** The expression is tokenized and evaluated with a
+* shunting-yard pass — it NEVER calls `eval` or `new Function`. The
+* lexer only recognizes numbers, parentheses, and the fixed operator set,
+* so there is no path to an identifier, function call, or property
+* access; any other character is a syntax error returned as data.
+*
+* **Errors flow as data.** A malformed expression, division/modulo by
+* zero, or a non-finite result throws a {@link CalculatorError} inside
+* the handler; `tool()` catches it and surfaces it in the returned
+* `{ error }` field (the LLM-visible message is preserved), so the agent
+* reads the failure and self-corrects instead of crashing.
+*
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+* @returns A `ToolContract<{ expression }, { result }>` ready to drop into `tools: []`.
+*
+* @example
+* const calc = calculatorTool();
+* const { data } = await calc.invoke({ expression: "(3 + 4) * 2" });
+* console.log(data?.result); // 14
+*/
+function calculatorTool(options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$3,
+		description: "Evaluate an arithmetic expression and return the numeric result. Supports + - * / % ^, parentheses, unary +/-, and decimal or scientific-notation numbers. Does not support variables or functions — pass a literal expression like \"(3 + 4) * 2\".",
+		input: inputSchema$3,
+		async execute(input) {
+			const tokens = tokenize(input.expression);
+			if (tokens.length === 0) throw new CalculatorError("Expression is empty.", { type: "syntax" });
+			return { result: evaluate(tokens) };
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/utility/date-time.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$2 = "date_time";
+/** Input schema for the `date_time` tool. */
+const inputSchema$2 = objectSchema$1({
+	op: literalField([
+		"now",
+		"add",
+		"diff",
+		"format"
+	]),
+	iso: optionalStringField(),
+	from: optionalStringField(),
+	to: optionalStringField(),
+	amount: optionalNumberField$1(),
+	unit: optionalStringField(),
+	timeZone: optionalStringField(),
+	format: optionalStringField()
+});
+/**
+* The time units `add` and `diff` understand, each as its length in
+* milliseconds. Calendar-unaware on purpose: a "month" / "year" has no
+* fixed millisecond length, so they are deliberately excluded — adding
+* `30 days` is unambiguous in a way adding `1 month` is not.
+*/
+const UNIT_MS = {
+	milliseconds: 1,
+	seconds: 1e3,
+	minutes: 6e4,
+	hours: 36e5,
+	days: 864e5,
+	weeks: 6048e5
+};
+/** Singular aliases mapped to their canonical plural unit key. */
+const UNIT_ALIASES = {
+	millisecond: "milliseconds",
+	ms: "milliseconds",
+	second: "seconds",
+	sec: "seconds",
+	s: "seconds",
+	minute: "minutes",
+	min: "minutes",
+	m: "minutes",
+	hour: "hours",
+	hr: "hours",
+	h: "hours",
+	day: "days",
+	d: "days",
+	week: "weeks",
+	w: "weeks"
+};
+/** Resolve a (possibly aliased / singular) unit token to its ms length. */
+function unitToMs(unit) {
+	const ms = UNIT_MS[UNIT_ALIASES[unit] ?? unit];
+	if (ms === void 0) throw new DateTimeError(`Unknown unit "${unit}". Supported units: ${Object.keys(UNIT_MS).join(", ")}.`, { type: "invalid-unit" });
+	return ms;
+}
+/**
+* Parse an ISO-8601 instant into a {@link Date}, or throw a typed
+* {@link DateTimeError} when the string is missing or unparseable.
+*
+* @param iso - The ISO string from the model (may be undefined).
+* @param field - The input field name, for the error message.
+*/
+function parseIso(iso, field) {
+	if (iso === void 0) throw new DateTimeError(`"${field}" is required for this operation.`, { type: "invalid-input" });
+	const date = new Date(iso);
+	if (Number.isNaN(date.getTime())) throw new DateTimeError(`"${field}" is not a valid ISO-8601 instant: "${iso}".`, { type: "invalid-input" });
+	return date;
+}
+/**
+* Render a {@link Date} in a target time zone using `Intl`. The
+* `"iso"` format (the default) returns the instant's UTC ISO string;
+* any other `format` value is treated as an `Intl.DateTimeFormat`
+* locale-style rendering in the given `timeZone`.
+*
+* @throws DateTimeError `type: "invalid-time-zone"` when `timeZone` is
+*   not a recognized IANA zone.
+*/
+function render$1(date, format, timeZone) {
+	if (format === void 0 || format === "iso") {
+		if (timeZone !== void 0) assertTimeZone(timeZone);
+		return date.toISOString();
+	}
+	try {
+		return new Intl.DateTimeFormat("en-US", {
+			timeZone,
+			dateStyle: format === "date" ? "medium" : void 0,
+			timeStyle: format === "time" ? "medium" : void 0,
+			...format === "datetime" ? {
+				dateStyle: "medium",
+				timeStyle: "medium"
+			} : {}
+		}).format(date);
+	} catch (error) {
+		throw new DateTimeError(`Could not render with format "${format}"${timeZone ? ` in time zone "${timeZone}"` : ""}.`, {
+			type: "invalid-time-zone",
+			cause: error
+		});
+	}
+}
+/**
+* Validate an IANA time zone by attempting to construct a formatter for
+* it; an unrecognized zone makes `Intl` throw a `RangeError`.
+*
+* @throws DateTimeError `type: "invalid-time-zone"` for an unknown zone.
+*/
+function assertTimeZone(timeZone) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone });
+	} catch (error) {
+		throw new DateTimeError(`Unknown time zone "${timeZone}".`, {
+			type: "invalid-time-zone",
+			cause: error
+		});
+	}
+}
+/**
+* Build the `date_time` tool — a small clock/calendar utility the agent
+* can call to read the current instant, shift an instant, measure the
+* gap between two instants, or render one. The `op` discriminator selects
+* the operation:
+*
+* - **`now`** — the current instant, rendered per `format` / `timeZone`
+*   (defaults to a UTC ISO string). Reads the injectable {@link Clock}.
+* - **`add`** — `iso` shifted by `amount` of `unit` (e.g.
+*   `+3 days`); a negative `amount` shifts backward.
+* - **`diff`** — the signed difference `to − iso`, expressed in `unit`.
+* - **`format`** — `iso` rendered per `format` / `timeZone`.
+*
+* Units are millisecond-based (`milliseconds`…`weeks`, plus common
+* aliases); calendar-relative `month`/`year` are intentionally
+* unsupported because they have no fixed length.
+*
+* **Deterministic in tests.** The clock backing `now` is injectable via
+* `deps.clock`; production defaults to `Date.now`.
+*
+* **Errors flow as data.** A missing/invalid field, an unknown unit, or
+* an unrecognized time zone throws a {@link DateTimeError} inside the
+* handler; `tool()` surfaces it in `{ error }` so the agent self-corrects.
+*
+* @param options - Optional overrides; `name` renames the tool,
+*   `defaultTimeZone` applies when a call omits `timeZone`.
+* @param deps - Injectable dependencies (the {@link Clock}); defaults to real time.
+* @returns A `ToolContract<DateTimeInput, { value }>` ready for `tools: []`.
+*
+* @example
+* const clock = () => Date.parse("2026-06-22T00:00:00Z");
+* const dt = dateTimeTool({}, { clock });
+* const { data } = await dt.invoke({ op: "now" });
+* console.log(data?.value); // "2026-06-22T00:00:00.000Z"
+*/
+function dateTimeTool(options, deps) {
+	const clock = deps?.clock ?? Date.now;
+	const defaultTimeZone = options?.defaultTimeZone;
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$2,
+		description: "Work with dates and times. Set op to: \"now\" (current instant), \"add\" (shift iso by amount of unit), \"diff\" (signed to − from in unit; pass the start instant as iso or from), or \"format\" (render iso). Units are milliseconds, seconds, minutes, hours, days, or weeks (month/year are not supported). Pass instants as ISO-8601 strings; set format to \"iso\" (default), \"date\", \"time\", or \"datetime\", and timeZone as an IANA zone like \"Africa/Cairo\".",
+		input: inputSchema$2,
+		async execute(input) {
+			const timeZone = input.timeZone ?? defaultTimeZone;
+			switch (input.op) {
+				case "now": return { value: render$1(new Date(clock()), input.format, timeZone) };
+				case "format": return { value: render$1(parseIso(input.iso, "iso"), input.format, timeZone) };
+				case "add": {
+					const date = parseIso(input.iso, "iso");
+					if (input.amount === void 0) throw new DateTimeError("\"amount\" is required for the \"add\" operation.", { type: "invalid-input" });
+					if (input.unit === void 0) throw new DateTimeError("\"unit\" is required for the \"add\" operation.", { type: "invalid-input" });
+					return { value: render$1(new Date(date.getTime() + input.amount * unitToMs(input.unit)), input.format, timeZone) };
+				}
+				case "diff": {
+					const from = parseIso(input.iso ?? input.from, "iso (or from)");
+					const to = parseIso(input.to, "to");
+					if (input.unit === void 0) throw new DateTimeError("\"unit\" is required for the \"diff\" operation.", { type: "invalid-input" });
+					const diff = (to.getTime() - from.getTime()) / unitToMs(input.unit);
+					return { value: String(diff) };
+				}
+				default: {
+					const unreachable = input.op;
+					throw new DateTimeError(`Unsupported operation "${String(unreachable)}".`, { type: "unsupported-op" });
+				}
+			}
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/web/schema.ts
+/**
+* Tiny, dependency-free [Standard Schema](https://standardschema.dev)
+* builders for the web tools' input validation. The package pins only
+* `@warlock.js/ai` as a runtime peer, so rather than pull in a schema
+* library we hand-roll the few shapes the web tools need — exactly the
+* pattern `@warlock.js/ai`'s own `tool()` tests use and the sibling
+* `@warlock.js/ai-workspace` package follows. Each builder returns a
+* `StandardSchemaV1`, which is what `tool({ input })` validates against
+* before calling `execute`.
+*
+* These intentionally cover only the primitive cases the WEB tools
+* require (`string`, `optional number`, and an `object` of fields). They
+* are not a general-purpose validator.
+*/
+/** The vendor tag stamped on every issue these builders produce. */
+const VENDOR = "ai-tools";
+/** Required string field — rejects anything that is not a string. */
+function stringField() {
+	return (value, key) => {
+		if (typeof value === "string") return { value };
+		return { issues: [{
+			message: `"${key}" must be a string`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional finite-number field — accepts `undefined` or a finite number,
+* rejecting `NaN`/`Infinity` and non-number types.
+*/
+function optionalNumberField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "number" && Number.isFinite(value)) return { value };
+		return { issues: [{
+			message: `"${key}" must be a finite number when provided`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Build a {@link StandardSchemaV1} for a flat object whose every property
+* is validated by a {@link FieldValidator}. The input must be a non-null
+* object; each declared field is validated and the (possibly coerced)
+* values are collected into the typed result. All field issues are merged
+* so the caller sees every problem at once.
+*
+* `T` is constrained to `object` rather than `Record<string, unknown>` so
+* the tool IO `interface`s (which carry no implicit string index
+* signature) satisfy it directly — only the declared keys in `shape` are
+* ever read, so a string index signature is never required.
+*
+* @example
+* const schema = objectSchema<{ query: string; maxResults?: number }>({
+*   query: stringField(),
+*   maxResults: optionalNumberField(),
+* });
+*/
+function objectSchema(shape) {
+	return { "~standard": {
+		version: 1,
+		vendor: VENDOR,
+		validate(input) {
+			if (typeof input !== "object" || input === null || Array.isArray(input)) return { issues: [{ message: "input must be an object" }] };
+			const source = input;
+			const issues = [];
+			const result = {};
+			for (const key of Object.keys(shape)) {
+				const field = shape[key];
+				const outcome = field(source[key], key);
+				if ("issues" in outcome) {
+					issues.push(...outcome.issues);
+					continue;
+				}
+				if (outcome.value !== void 0) result[key] = outcome.value;
+			}
+			if (issues.length > 0) return { issues };
+			return { value: result };
+		}
+	} };
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/web/fetch-url.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$1 = "fetch_url";
+/** Default hard cap on response bytes read before truncation. */
+const DEFAULT_MAX_BYTES = 1e6;
+/** Default per-request timeout in milliseconds. */
+const DEFAULT_TIMEOUT_MS = 15e3;
+/** Default rendering mode for the fetched document. */
+const DEFAULT_EXTRACT = "text";
+/** Input schema: `{ url }`. */
+const inputSchema$1 = objectSchema({ url: stringField() });
+const READABILITY_MODULE_ID = "@mozilla/readability";
+const JSDOM_MODULE_ID = "jsdom";
+let ReadabilitySdk;
+let JsdomSdk;
+let isReadabilityAvailable;
+let loadingPromise;
+const READABILITY_INSTALL_INSTRUCTIONS = `
+The fetch_url text/markdown extractor requires the @mozilla/readability and jsdom packages.
+Install them with:
+
+  npm install @mozilla/readability jsdom
+
+Or with your preferred package manager:
+
+  pnpm add @mozilla/readability jsdom
+  yarn add @mozilla/readability jsdom
+`.trim();
+/**
+* Settle the lazy import of `@mozilla/readability` + `jsdom` once,
+* concurrency-safe. Only needed for the `"text"` / `"markdown"` extract
+* modes — `"html"` returns the raw body and never loads them. A bare
+* `catch` flips the flag to `false`; the curated install string surfaces
+* at use time via {@link WebToolError}, never a raw module-resolution
+* stack trace.
+*/
+function loadReadability() {
+	if (isReadabilityAvailable !== void 0) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			ReadabilitySdk = await import(READABILITY_MODULE_ID);
+			JsdomSdk = await import(JSDOM_MODULE_ID);
+			isReadabilityAvailable = true;
+		} catch {
+			isReadabilityAvailable = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* Parse the input URL, rejecting anything unparseable or not over
+* `http`/`https` with a typed {@link WebToolError}.
+*/
+function parseUrl(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw new WebToolError(`fetch_url received an unparseable URL: "${raw}".`, { type: "invalid-url" });
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new WebToolError(`fetch_url only supports http(s) URLs; got "${url.protocol}".`, { type: "invalid-url" });
+	return url;
+}
+/**
+* Enforce the host allowlist (an SSRF guardrail) before any network call.
+* When `allowHosts` is set, a request to a host not in it is rejected;
+* matching is exact on the URL hostname (case-insensitive).
+*/
+function assertHostAllowed(url, allowHosts) {
+	if (!allowHosts || allowHosts.length === 0) return;
+	const host = url.hostname.toLowerCase();
+	if (!allowHosts.some((entry) => entry.toLowerCase() === host)) throw new WebToolError(`fetch_url blocked host "${url.hostname}" — it is not in the allowHosts allowlist.`, {
+		type: "denied-host",
+		context: { host: url.hostname }
+	});
+}
+/**
+* Read the response body up to `maxBytes`, stopping early once the cap is
+* reached. Returns the decoded text and whether it was truncated. When
+* the body has no stream (a stubbed `Response`), falls back to `.text()`
+* and truncates the decoded string at `maxBytes`.
+*/
+async function readBody(response, maxBytes) {
+	const stream = response.body;
+	if (!stream) {
+		const text = await response.text();
+		if (text.length > maxBytes) return {
+			body: text.slice(0, maxBytes),
+			truncated: true
+		};
+		return {
+			body: text,
+			truncated: false
+		};
+	}
+	const reader = stream.getReader();
+	const chunks = [];
+	let received = 0;
+	let truncated = false;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (value) {
+			received += value.byteLength;
+			chunks.push(value);
+			if (received >= maxBytes) {
+				truncated = true;
+				await reader.cancel();
+				break;
+			}
+		}
+	}
+	const merged = new Uint8Array(received);
+	let offset = 0;
+	for (const chunk of chunks) {
+		merged.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	const sliced = truncated ? merged.subarray(0, maxBytes) : merged;
+	return {
+		body: new TextDecoder().decode(sliced),
+		truncated
+	};
+}
+/**
+* Render the fetched HTML into the configured `extract` mode. `"html"`
+* returns the raw body untouched; `"text"` and `"markdown"` run
+* `@mozilla/readability` over a `jsdom` document, throwing a curated
+* {@link WebToolError} when those optional peers are absent. `"markdown"`
+* applies a light heading/paragraph conversion over the extracted text.
+*/
+async function render(html, url, extract) {
+	if (extract === "html") return html;
+	await loadReadability();
+	if (!isReadabilityAvailable) throw new WebToolError(READABILITY_INSTALL_INSTRUCTIONS, { type: "missing-peer" });
+	const dom = new JsdomSdk.JSDOM(html, { url });
+	const article = new ReadabilitySdk.Readability(dom.window.document).parse();
+	if (extract === "markdown") return article?.content ? htmlToMarkdown(article.content) : article?.textContent ?? "";
+	return article?.textContent ?? "";
+}
+/**
+* Minimal HTML→Markdown reduction for readability's extracted article
+* HTML — headings become `#` prefixes, paragraphs/line-breaks become
+* blank-line separated blocks, and remaining tags are stripped. This is a
+* pragmatic conversion, not a full CommonMark serializer.
+*/
+function htmlToMarkdown(html) {
+	return html.replace(/<h([1-6])[^>]*>(.*?)<\/h\1>/gis, (_match, level, text) => {
+		return `\n\n${"#".repeat(Number(level))} ${stripTags(text).trim()}\n\n`;
+	}).replace(/<\/(p|div|section|article|li)>/gi, "\n\n").replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** Strip any remaining HTML tags from a fragment. */
+function stripTags(html) {
+	return html.replace(/<[^>]+>/g, "");
+}
+/**
+* Build the agent-facing `fetch_url` tool — fetch a URL over the global
+* `fetch` (Node 18+) and hand the model back rendered `content`.
+*
+* Guardrails, applied in order before/around the network call:
+* - **`allowHosts`** — when set, a request to any host not in the list is
+*   rejected before the fetch (an SSRF guardrail).
+* - **`timeoutMs`** — the request is aborted via `AbortSignal.timeout`
+*   (default {@link DEFAULT_TIMEOUT_MS}).
+* - **`maxBytes`** — the response body is read up to this cap and the
+*   result flags `truncated` when it was cut off (default
+*   {@link DEFAULT_MAX_BYTES}).
+* - **`extract`** — `"html"` returns the raw body; `"text"` (default) and
+*   `"markdown"` run `@mozilla/readability` over `jsdom`, lazily imported
+*   so they stay OPTIONAL peers — a missing peer throws the curated
+*   install string.
+*
+* **Errors flow as data.** Every guardrail rejection and network failure
+* throws a typed {@link WebToolError}; the `tool()` wrapper catches it and
+* surfaces it in the returned `{ error }` field — `invoke()` never throws
+* — so the agent reads the failure and self-corrects.
+*
+* @param options - Tool-name override, byte cap, timeout, extract mode,
+*   and host allowlist.
+* @returns A `ToolContract<{ url }, FetchUrlResult>`.
+*
+* @example
+* const fetchUrl = fetchUrlTool({ extract: "text", allowHosts: ["docs.stripe.com"] });
+* const { data } = await fetchUrl.invoke({ url: "https://docs.stripe.com/api" });
+* console.log(data?.content, data?.truncated);
+*/
+function fetchUrlTool(options) {
+	const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const extract = options?.extract ?? DEFAULT_EXTRACT;
+	const allowHosts = options?.allowHosts;
+	if (extract !== "html") loadReadability();
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$1,
+		description: "Fetch a web page or document by URL and return its main content as text (readability-extracted), raw HTML, or Markdown. Use to read a specific page you already have the URL for.",
+		input: inputSchema$1,
+		async execute(input) {
+			const url = parseUrl(input.url);
+			assertHostAllowed(url, allowHosts);
+			let response;
+			try {
+				response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+			} catch (cause) {
+				throw new WebToolError(`fetch_url request failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+					type: "request-failed",
+					cause
+				});
+			}
+			const { body, truncated } = await readBody(response, maxBytes);
+			const content = await render(body, response.url || url.toString(), extract);
+			return {
+				url: response.url || url.toString(),
+				status: response.status,
+				content,
+				truncated
+			};
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/web/web-search.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "web_search";
+/** Default per-call result cap when the constructor does not set one. */
+const DEFAULT_MAX_RESULTS = 5;
+/**
+* Per-provider configuration — the environment variable consulted when no
+* `apiKey` is passed, plus the human-readable provider label used in
+* error messages.
+*/
+const PROVIDER_ENV = {
+	tavily: "TAVILY_API_KEY",
+	brave: "BRAVE_API_KEY",
+	serpapi: "SERPAPI_API_KEY"
+};
+/** Input schema: `{ query, maxResults? }`. */
+const inputSchema = objectSchema({
+	query: stringField(),
+	maxResults: optionalNumberField()
+});
+/**
+* Resolve the API key from explicit options or the provider's environment
+* variable, throwing a typed {@link WebToolError} when neither is present.
+*/
+function resolveApiKey(provider, apiKey) {
+	const key = apiKey ?? process.env[PROVIDER_ENV[provider]];
+	if (!key) throw new WebToolError(`web_search requires an API key for the "${provider}" provider. Pass { apiKey } or set the ${PROVIDER_ENV[provider]} environment variable.`, { type: "missing-key" });
+	return key;
+}
+/**
+* Clamp the model-requested result count into `[1, max]`. An omitted /
+* non-positive request falls back to the configured default.
+*/
+function clampResults(requested, max) {
+	if (requested === void 0 || requested < 1) return Math.min(DEFAULT_MAX_RESULTS, max);
+	return Math.min(Math.max(1, Math.floor(requested)), max);
+}
+/**
+* Issue the provider HTTP call and return its parsed JSON, mapping a
+* non-OK status or a network failure to a typed {@link WebToolError}.
+*/
+async function fetchJson(url, init, provider) {
+	let response;
+	try {
+		response = await fetch(url, init);
+	} catch (cause) {
+		throw new WebToolError(`web_search request to the "${provider}" provider failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+			type: "request-failed",
+			cause
+		});
+	}
+	if (!response.ok) throw new WebToolError(`web_search "${provider}" provider returned HTTP ${response.status}.`, {
+		type: "request-failed",
+		context: { status: response.status }
+	});
+	return response.json();
+}
+/** Drive Tavily's `/search` HTTP API and normalize its hits. */
+async function searchTavily(query, maxResults, apiKey) {
+	return ((await fetchJson("https://api.tavily.com/search", {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			api_key: apiKey,
+			query,
+			max_results: maxResults
+		})
+	}, "tavily")).results ?? []).slice(0, maxResults).map((hit) => ({
+		title: hit.title ?? "",
+		url: hit.url ?? "",
+		snippet: hit.content ?? "",
+		score: hit.score
+	}));
+}
+/** Drive Brave's web-search HTTP API and normalize its hits. */
+async function searchBrave(query, maxResults, apiKey) {
+	const url = new URL("https://api.search.brave.com/res/v1/web/search");
+	url.searchParams.set("q", query);
+	url.searchParams.set("count", String(maxResults));
+	return ((await fetchJson(url.toString(), {
+		method: "GET",
+		headers: {
+			accept: "application/json",
+			"x-subscription-token": apiKey
+		}
+	}, "brave")).web?.results ?? []).slice(0, maxResults).map((hit) => ({
+		title: hit.title ?? "",
+		url: hit.url ?? "",
+		snippet: hit.description ?? ""
+	}));
+}
+/** Drive SerpAPI's `search.json` HTTP API and normalize its hits. */
+async function searchSerpApi(query, maxResults, apiKey) {
+	const url = new URL("https://serpapi.com/search.json");
+	url.searchParams.set("q", query);
+	url.searchParams.set("num", String(maxResults));
+	url.searchParams.set("api_key", apiKey);
+	return ((await fetchJson(url.toString(), { method: "GET" }, "serpapi")).organic_results ?? []).slice(0, maxResults).map((hit) => ({
+		title: hit.title ?? "",
+		url: hit.link ?? "",
+		snippet: hit.snippet ?? ""
+	}));
+}
+/**
+* Build the agent-facing `web_search` tool over a {@link SearchProvider}.
+*
+* The provider's HTTP API is called directly through the global `fetch`
+* (Node 18+) — Tavily via `POST /search` (LLM-ready snippets + relevance
+* scores), Brave and SerpAPI via their `GET` endpoints. The API key is
+* taken from `options.apiKey`, falling back to the provider's environment
+* variable (`TAVILY_API_KEY` / `BRAVE_API_KEY` / `SERPAPI_API_KEY`). No
+* provider SDK is required for the HTTP path; `@tavily/core` remains an
+* optional peer for callers who prefer it, but this factory never forces
+* it to be installed.
+*
+* The model passes `{ query, maxResults? }`; `maxResults` is clamped into
+* `[1, options.maxResults]` (default {@link DEFAULT_MAX_RESULTS}).
+*
+* **Errors flow as data.** A missing key, a non-OK provider status, or a
+* network failure throws a typed {@link WebToolError}; the `tool()`
+* wrapper catches it and surfaces it in the returned `{ error }` field —
+* `invoke()` never throws — so the agent can read the failure and
+* self-correct.
+*
+* @param options - Provider selection, API key, result cap, and an
+*   optional tool-name override.
+* @returns A `ToolContract<{ query; maxResults? }, WebSearchResult>`.
+*
+* @example
+* const search = webSearchTool({ provider: "tavily" });
+* const { data } = await search.invoke({ query: "warlock.js ai tools" });
+* for (const hit of data?.results ?? []) console.log(hit.title, hit.url);
+*/
+function webSearchTool(options) {
+	const provider = options.provider;
+	const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;
+	return (0, _warlock_js_ai.tool)({
+		name: options.name ?? DEFAULT_NAME,
+		description: "Search the web for current information and return a ranked list of results (title, URL, and a short snippet). Use for facts that may have changed since training, or anything you are unsure about.",
+		input: inputSchema,
+		async execute(input) {
+			const apiKey = resolveApiKey(provider, options.apiKey);
+			const limit = clampResults(input.maxResults, maxResults);
+			let results;
+			switch (provider) {
+				case "tavily":
+					results = await searchTavily(input.query, limit, apiKey);
+					break;
+				case "brave":
+					results = await searchBrave(input.query, limit, apiKey);
+					break;
+				case "serpapi":
+					results = await searchSerpApi(input.query, limit, apiKey);
+					break;
+			}
+			return { results };
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-tools/src/register.ts
+_warlock_js_ai.ai.tools = {
+	webSearch: webSearchTool,
+	fetchUrl: fetchUrlTool,
+	http: httpRequestTool,
+	calculator: calculatorTool,
+	dateTime: (options) => dateTimeTool(options)
+};
+_warlock_js_ai.ai.mcp = mcp;
+
+//#endregion
+exports.CalculatorError = CalculatorError;
+exports.DateTimeError = DateTimeError;
+exports.HttpPolicyError = HttpPolicyError;
+exports.McpTransportError = McpTransportError;
+exports.WebToolError = WebToolError;
+exports.calculatorTool = calculatorTool;
+exports.createJsonRpcClient = createJsonRpcClient;
+exports.createServeHandler = createServeHandler;
+exports.createTransport = createTransport;
+exports.dateTimeTool = dateTimeTool;
+exports.fetchUrlTool = fetchUrlTool;
+exports.httpRequestTool = httpRequestTool;
+exports.jsonSchemaToStandard = jsonSchemaToStandard;
+exports.mcp = mcp;
+exports.serve = serve;
+exports.webSearchTool = webSearchTool;
+//# sourceMappingURL=index.cjs.map