@warlock.js/ai-tools 5.31.0 → 5.32.0

package/esm/mcp/transport.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/transport.ts"],"mappings":";;;;;;;AAgeA;;;;;;iBAAgB,eAAA,CACd,SAAA,EAAW,YAAA,GACV,kBAAkB;EAAK,UAAA;AAAA;AAAU;AAmFpC;;;;AAnFoC,UAmFnB,mBAAA;EAMZ;EAJH,IAAA,oBACE,MAAA,UACA,MAAA,YACA,OAAA;IAAY,MAAA,GAAS,WAAA;IAAa,SAAA;EAAA,IACjC,OAAA,CAAQ,OAAA;EAJX;EAMA,MAAA,CAAO,MAAA,UAAgB,MAAA,aAAmB,OAAA;EALxC;EAOF,KAAA,IAAS,OAAA;AAAA;;;;;;;;;;;;;iBAeK,mBAAA,CACd,MAAA,EAAQ,YAAA,GAAe,kBAAA,GACtB,mBAAA"}
+{"version":3,"file":"transport.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/transport.ts"],"mappings":";;;;;;;;;;;;;wBAgegB,gBACd,WAAW,eACV;EAAuB;;;;;;;iBAmFT;;EAEf,KAAK,mBACH,gBACA,kBACA;IAAY,SAAS;IAAa;MACjC,QAAQ;;EAEX,OAAO,gBAAgB,mBAAmB;;EAE1C,SAAS;;;;;;;;;;;;;;wBAeK,oBACd,QAAQ,eAAe,qBACtB"}

package/esm/mcp/transport.mjs

@@ -65,8 +65,10 @@ function armCall(reject, method, options, onSettle) {
 		}));
 	};
 	const signal = options?.signal;
-	if (signal) if (signal.aborted) queueMicrotask(onAbort);
-	else signal.addEventListener("abort", onAbort, { once: true });
+	if (signal) {
+		if (signal.aborted) queueMicrotask(onAbort);
+		else signal.addEventListener("abort", onAbort, { once: true });
+	}
 	function cleanup() {
 		clearTimeout(timer);
 		if (signal) signal.removeEventListener("abort", onAbort);
@@ -219,8 +221,10 @@ var HttpTransport = class {
 		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 });
+		if (signal) {
+			if (signal.aborted) controller.abort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
 		let response;
 		try {
 			response = await fetch(this.url, {
@@ -285,7 +289,8 @@ var HttpTransport = class {
 				body: JSON.stringify(notification)
 			});
 		} catch (cause) {
-			throw new McpTransportError(`MCP http transport notification "${method}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new McpTransportError(`MCP http transport notification "${method}" failed: ${message}`, {
 				type: "connect",
 				method,
 				cause
@@ -388,7 +393,8 @@ var JsonRpcClient = class {
 * @returns A JSON-RPC client handle.
 */
 function createJsonRpcClient(source) {
-	return new JsonRpcClient(isTransportConfig(source) ? createTransport(source) : withIdAllocator(source));
+	const transport = isTransportConfig(source) ? createTransport(source) : withIdAllocator(source);
+	return new JsonRpcClient(transport);
 }
 /**
 * Distinguish an {@link McpTransport} config (a plain object with a `type`

package/esm/mcp/transport.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"transport.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/transport.ts"],"sourcesContent":["import { spawn, type ChildProcessWithoutNullStreams } from \"node:child_process\";\nimport { createInterface, type Interface } from \"node:readline\";\nimport type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, McpTransport } from \"../contracts\";\nimport { McpTransportError } from \"../errors\";\nimport type { McpTransportClient } from \"./transport.type\";\n\n/** Default per-request wait before a transport call is abandoned. */\nconst DEFAULT_REQUEST_TIMEOUT_MS = 30_000;\n\n/** The JSON-RPC version literal every outbound message carries. */\nconst JSONRPC_VERSION = \"2.0\";\n\n/**\n * The only host environment entries a stdio MCP server inherits. This keeps\n * executable lookup and platform runtime behaviour intact without exposing\n * application secrets or arbitrary parent-process configuration to children.\n */\nconst STDIO_ENV_ALLOWLIST = [\n  \"PATH\",\n  \"Path\",\n  \"HOME\",\n  \"USERPROFILE\",\n  \"HOMEDRIVE\",\n  \"HOMEPATH\",\n  \"SystemRoot\",\n  \"SYSTEMROOT\",\n  \"WINDIR\",\n  \"ComSpec\",\n  \"COMSPEC\",\n  \"PATHEXT\",\n] as const;\n\n/**\n * Build the environment passed to a child MCP stdio server. Never forward\n * `process.env` wholesale: only the cross-platform execution essentials are\n * copied, and application-supplied server variables take precedence.\n */\nfunction createStdioEnvironment(\n  serverEnvironment?: Record<string, string>,\n): Record<string, string> {\n  const environment: Record<string, string> = {};\n\n  for (const key of STDIO_ENV_ALLOWLIST) {\n    const value = process.env[key];\n\n    if (value !== undefined) {\n      environment[key] = value;\n    }\n  }\n\n  return { ...environment, ...serverEnvironment };\n}\n\n/**\n * A pending in-flight request awaiting its correlated response, keyed by\n * the JSON-RPC `id`. The stdio transport multiplexes many requests over\n * one line-framed pipe, so each resolve/reject is parked here until the\n * line whose `id` matches arrives.\n */\ninterface PendingCall {\n  resolve(response: JsonRpcResponse): void;\n  reject(error: McpTransportError): void;\n  /** Clears the per-call timeout + abort wiring when the call settles. */\n  cleanup(): void;\n}\n\n/**\n * Wire a per-call timeout and an optional caller `AbortSignal` onto a\n * pending request, returning a `cleanup()` that tears both down. The\n * `onSettle` callback removes the pending entry from whatever registry the\n * transport keeps so a late response can't double-settle.\n */\nfunction armCall(\n  reject: (error: McpTransportError) => void,\n  method: string,\n  options: { signal?: AbortSignal; timeoutMs?: number } | undefined,\n  onSettle: () => void,\n): () => void {\n  const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;\n\n  const timer = setTimeout(() => {\n    onSettle();\n    reject(\n      new McpTransportError(`MCP request \"${method}\" timed out after ${timeoutMs}ms.`, {\n        type: \"timeout\",\n        method,\n      }),\n    );\n  }, timeoutMs);\n\n  const onAbort = () => {\n    cleanup();\n    reject(\n      new McpTransportError(`MCP request \"${method}\" was aborted.`, {\n        type: \"closed\",\n        method,\n      }),\n    );\n  };\n\n  const signal = options?.signal;\n\n  if (signal) {\n    if (signal.aborted) {\n      // Defer so the caller has the rejection wired before it fires.\n      queueMicrotask(onAbort);\n    } else {\n      signal.addEventListener(\"abort\", onAbort, { once: true });\n    }\n  }\n\n  function cleanup(): void {\n    clearTimeout(timer);\n\n    if (signal) {\n      signal.removeEventListener(\"abort\", onAbort);\n    }\n  }\n\n  return cleanup;\n}\n\n/**\n * The stdio transport — spawns a child process and speaks JSON-RPC over\n * its stdin/stdout, one JSON object per line (newline-delimited framing).\n * Uses only Node built-ins (`node:child_process` + `node:readline`); no\n * dependency.\n *\n * Constructed via {@link createStdioTransport}; the class itself is\n * internal.\n */\nclass StdioTransport implements McpTransportClient {\n  /** The spawned server process. */\n  private readonly child: ChildProcessWithoutNullStreams;\n\n  /** Line reader over the child's stdout — one JSON-RPC message per line. */\n  private readonly reader: Interface;\n\n  /** In-flight requests awaiting a correlated response, keyed by id. */\n  private readonly pending = new Map<JsonRpcId, PendingCall>();\n\n  /** Monotonic id source for outbound requests. */\n  private nextId = 1;\n\n  /** Flipped once {@link close} runs (or the child exits) so reuse rejects. */\n  private closed = false;\n\n  public constructor(transport: Extract<McpTransport, { type: \"stdio\" }>) {\n    let child: ChildProcessWithoutNullStreams;\n\n    try {\n      child = spawn(transport.command, transport.args ?? [], {\n        // process.env is NOT inherited wholesale: only the\n        // STDIO_ENV_ALLOWLIST keys are copied, then the caller's explicit\n        // `transport.env` entries are layered on top.\n        env: createStdioEnvironment(transport.env),\n        stdio: [\"pipe\", \"pipe\", \"pipe\"],\n      }) as ChildProcessWithoutNullStreams;\n    } catch (cause) {\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        `MCP stdio transport could not spawn \"${transport.command}\": ${message}`,\n        { type: \"connect\", cause },\n      );\n    }\n\n    this.child = child;\n    this.reader = createInterface({ input: child.stdout });\n\n    this.reader.on(\"line\", (line) => this.onLine(line));\n\n    // A child that dies takes every in-flight (and future) call with it.\n    child.on(\"exit\", (code) => this.failAll(\"connect\", `child exited with code ${code ?? \"null\"}`));\n    child.on(\"error\", (error) => this.failAll(\"connect\", error.message));\n  }\n\n  /**\n   * Parse one stdout line and route it to its pending request. Non-JSON\n   * lines (a server logging to stdout) and messages with no matching `id`\n   * (notifications, stray responses) are ignored — robustness over strictness.\n   */\n  private onLine(line: string): void {\n    const trimmed = line.trim();\n\n    if (!trimmed) {\n      return;\n    }\n\n    let message: JsonRpcResponse;\n\n    try {\n      message = JSON.parse(trimmed) as JsonRpcResponse;\n    } catch {\n      // Not a JSON-RPC line (server diagnostics on stdout) — ignore.\n      return;\n    }\n\n    if (message.id === undefined || message.id === null) {\n      // A notification or a malformed response — nothing to correlate.\n      return;\n    }\n\n    const call = this.pending.get(message.id);\n\n    if (!call) {\n      return;\n    }\n\n    this.pending.delete(message.id);\n    call.cleanup();\n    call.resolve(message);\n  }\n\n  /**\n   * Reject every pending call (and mark the transport unusable) when the\n   * child dies or errors — so a hung server can never leave a caller\n   * waiting forever.\n   */\n  private failAll(type: \"connect\" | \"closed\", reason: string): void {\n    this.closed = true;\n\n    for (const [id, call] of this.pending) {\n      this.pending.delete(id);\n      call.cleanup();\n      call.reject(new McpTransportError(`MCP stdio transport failed: ${reason}.`, { type }));\n    }\n  }\n\n  public request<TResult = unknown>(\n    request: JsonRpcRequest,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<JsonRpcResponse<TResult>> {\n    if (this.closed) {\n      return Promise.reject(\n        new McpTransportError(\"MCP stdio transport is closed.\", {\n          type: \"closed\",\n          method: request.method,\n        }),\n      );\n    }\n\n    const id = request.id;\n\n    return new Promise<JsonRpcResponse<TResult>>((resolve, reject) => {\n      const cleanup = armCall(reject, request.method, options, () => this.pending.delete(id));\n\n      this.pending.set(id, {\n        resolve: (response) => resolve(response as JsonRpcResponse<TResult>),\n        reject,\n        cleanup,\n      });\n\n      try {\n        this.child.stdin.write(`${JSON.stringify(request)}\\n`);\n      } catch (cause) {\n        this.pending.delete(id);\n        cleanup();\n\n        const message = cause instanceof Error ? cause.message : String(cause);\n\n        reject(\n          new McpTransportError(\n            `MCP stdio transport failed to write request \"${request.method}\": ${message}`,\n            { type: \"closed\", method: request.method, cause },\n          ),\n        );\n      }\n    });\n  }\n\n  public async notify(method: string, params?: unknown): Promise<void> {\n    if (this.closed) {\n      throw new McpTransportError(\"MCP stdio transport is closed.\", {\n        type: \"closed\",\n        method,\n      });\n    }\n\n    const notification = { jsonrpc: JSONRPC_VERSION, method, params };\n    this.child.stdin.write(`${JSON.stringify(notification)}\\n`);\n  }\n\n  /** Allocate the next outbound request id. */\n  public allocateId(): number {\n    return this.nextId++;\n  }\n\n  public async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n\n    this.closed = true;\n    this.reader.close();\n    this.failAll(\"closed\", \"transport closed by caller\");\n    this.child.kill();\n  }\n}\n\n/**\n * The Streamable HTTP transport — POSTs each JSON-RPC request to the\n * server endpoint over the global `fetch` (Node 18+) and reads the single\n * JSON response. No SSE-legacy, no WebSocket. Static `headers` (e.g. auth)\n * are sent with every request.\n *\n * Constructed via {@link createHttpTransport}; the class itself is internal.\n */\nclass HttpTransport implements McpTransportClient {\n  /** The server endpoint POST target. */\n  private readonly url: string;\n\n  /** Static headers merged into every request (auth, etc.). */\n  private readonly headers: Record<string, string>;\n\n  /** Monotonic id source for outbound requests. */\n  private nextId = 1;\n\n  public constructor(transport: Extract<McpTransport, { type: \"http\" }>) {\n    this.url = transport.url;\n    this.headers = {\n      \"content-type\": \"application/json\",\n      accept: \"application/json, text/event-stream\",\n      ...transport.headers,\n    };\n  }\n\n  public async request<TResult = unknown>(\n    request: JsonRpcRequest,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<JsonRpcResponse<TResult>> {\n    const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    const onAbort = () => controller.abort();\n    const signal = options?.signal;\n\n    if (signal) {\n      if (signal.aborted) {\n        controller.abort();\n      } else {\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n      }\n    }\n\n    let response: Response;\n\n    try {\n      response = await fetch(this.url, {\n        method: \"POST\",\n        headers: this.headers,\n        body: JSON.stringify(request),\n        signal: controller.signal,\n      });\n    } catch (cause) {\n      const aborted = controller.signal.aborted;\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        aborted\n          ? `MCP request \"${request.method}\" timed out or was aborted after ${timeoutMs}ms.`\n          : `MCP http transport request \"${request.method}\" failed: ${message}`,\n        { type: aborted ? \"timeout\" : \"connect\", method: request.method, cause },\n      );\n    } finally {\n      clearTimeout(timer);\n\n      if (signal) {\n        signal.removeEventListener(\"abort\", onAbort);\n      }\n    }\n\n    if (!response.ok) {\n      throw new McpTransportError(\n        `MCP http transport request \"${request.method}\" returned HTTP ${response.status}.`,\n        { type: \"connect\", method: request.method, context: { status: response.status } },\n      );\n    }\n\n    return this.parseBody<TResult>(response, request.method);\n  }\n\n  /**\n   * Parse the HTTP response body into a JSON-RPC response. Streamable HTTP\n   * may answer with either `application/json` (a single response object)\n   * or `text/event-stream` (SSE frames); we read the body as text and\n   * extract the first JSON object, supporting the common `data: {...}`\n   * SSE line shape without a streaming parser.\n   */\n  private async parseBody<TResult>(\n    response: Response,\n    method: string,\n  ): Promise<JsonRpcResponse<TResult>> {\n    const raw = await response.text();\n    const contentType = response.headers.get(\"content-type\")?.toLowerCase() ?? \"\";\n\n    const jsonText = contentType.includes(\"text/event-stream\") ? extractSseData(raw) : raw;\n\n    if (!jsonText) {\n      throw new McpTransportError(`MCP http transport got an empty response for \"${method}\".`, {\n        type: \"protocol\",\n        method,\n      });\n    }\n\n    try {\n      return JSON.parse(jsonText) as JsonRpcResponse<TResult>;\n    } catch (cause) {\n      throw new McpTransportError(`MCP http transport got a non-JSON response for \"${method}\".`, {\n        type: \"protocol\",\n        method,\n        cause,\n      });\n    }\n  }\n\n  public async notify(method: string, params?: unknown): Promise<void> {\n    const notification = { jsonrpc: JSONRPC_VERSION, method, params };\n\n    // A notification expects no response; fire-and-forget but surface a\n    // connect failure so a dead endpoint is not silently ignored.\n    try {\n      await fetch(this.url, {\n        method: \"POST\",\n        headers: this.headers,\n        body: JSON.stringify(notification),\n      });\n    } catch (cause) {\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        `MCP http transport notification \"${method}\" failed: ${message}`,\n        { type: \"connect\", method, cause },\n      );\n    }\n  }\n\n  /** Allocate the next outbound request id. */\n  public allocateId(): number {\n    return this.nextId++;\n  }\n\n  public async close(): Promise<void> {\n    // Streamable HTTP is stateless per request — nothing persistent to\n    // release.\n  }\n}\n\n/**\n * Pull the first `data:` JSON payload out of an SSE response body. MCP's\n * Streamable HTTP transport answers a single request with one SSE frame\n * carrying the JSON-RPC response; we take the first non-empty `data:`\n * line. Returns an empty string when none is found.\n */\nfunction extractSseData(body: string): string {\n  for (const line of body.split(/\\r?\\n/)) {\n    const trimmed = line.trim();\n\n    if (trimmed.startsWith(\"data:\")) {\n      const payload = trimmed.slice(\"data:\".length).trim();\n\n      if (payload && payload !== \"[DONE]\") {\n        return payload;\n      }\n    }\n  }\n\n  return \"\";\n}\n\n/**\n * Build the concrete {@link McpTransportClient} for an {@link McpTransport}\n * config — a {@link StdioTransport} for `type: \"stdio\"`, an\n * {@link HttpTransport} for `type: \"http\"`. The returned client also\n * carries an `allocateId()` for the JSON-RPC client to mint request ids.\n *\n * @param transport - The transport config (discriminated by `type`).\n * @returns A transport client paired with its id allocator.\n */\nexport function createTransport(\n  transport: McpTransport,\n): McpTransportClient & { allocateId(): number } {\n  if (transport.type === \"stdio\") {\n    return new StdioTransport(transport);\n  }\n\n  return new HttpTransport(transport);\n}\n\n/**\n * A minimal JSON-RPC 2.0 request/response client over any\n * {@link McpTransportClient}. Mints monotonic ids, frames the\n * `{ jsonrpc, id, method, params }` envelope, and unwraps the response —\n * translating a JSON-RPC `error` member into a typed\n * {@link McpTransportError} so callers branch on `error.type` rather than\n * parsing the wire.\n *\n * Constructed via {@link createJsonRpcClient}; the class itself is internal.\n */\nclass JsonRpcClient {\n  /** The underlying framing transport. */\n  private readonly transport: McpTransportClient & { allocateId(): number };\n\n  public constructor(transport: McpTransportClient & { allocateId(): number }) {\n    this.transport = transport;\n  }\n\n  /**\n   * Issue a JSON-RPC `method` call and resolve with its `result`,\n   * throwing a typed {@link McpTransportError} on a JSON-RPC error member\n   * or a malformed response (neither `result` nor `error`).\n   */\n  public async call<TResult = unknown>(\n    method: string,\n    params?: unknown,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<TResult> {\n    const request: JsonRpcRequest = {\n      jsonrpc: JSONRPC_VERSION,\n      id: this.transport.allocateId(),\n      method,\n      params,\n    };\n\n    const response = await this.transport.request<TResult>(request, options);\n\n    if (response.error) {\n      throw new McpTransportError(\n        `MCP \"${method}\" failed: ${response.error.message} (code ${response.error.code}).`,\n        {\n          type: \"protocol\",\n          method,\n          context: { code: response.error.code },\n          cause: response.error.data,\n        },\n      );\n    }\n\n    if (response.result === undefined) {\n      throw new McpTransportError(\n        `MCP \"${method}\" returned a response with neither result nor error.`,\n        { type: \"protocol\", method },\n      );\n    }\n\n    return response.result;\n  }\n\n  /** Send a one-way JSON-RPC notification (no response awaited). */\n  public notify(method: string, params?: unknown): Promise<void> {\n    return this.transport.notify(method, params);\n  }\n\n  /** Close the underlying transport. */\n  public close(): Promise<void> {\n    return this.transport.close();\n  }\n}\n\n/**\n * A JSON-RPC client over an MCP transport. Either pass an already-built\n * transport client (tests inject a fake) or an {@link McpTransport} config\n * to spawn/connect a real one.\n */\nexport interface JsonRpcClientHandle {\n  /** Issue a request and resolve with its `result` (throws on error). */\n  call<TResult = unknown>(\n    method: string,\n    params?: unknown,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<TResult>;\n  /** Send a one-way notification. */\n  notify(method: string, params?: unknown): Promise<void>;\n  /** Close the underlying transport. */\n  close(): Promise<void>;\n}\n\n/**\n * Build a {@link JsonRpcClientHandle} over a transport. Accepts either a\n * pre-built {@link McpTransportClient} (the test seam — inject a scripted\n * fake) or an {@link McpTransport} config, in which case the concrete\n * transport is constructed via {@link createTransport}.\n *\n * When a bare {@link McpTransportClient} (without an `allocateId`) is\n * injected, the client supplies its own monotonic id source.\n *\n * @param source - A transport client or an `McpTransport` config.\n * @returns A JSON-RPC client handle.\n */\nexport function createJsonRpcClient(\n  source: McpTransport | McpTransportClient,\n): JsonRpcClientHandle {\n  const transport: McpTransportClient & { allocateId(): number } = isTransportConfig(source)\n    ? createTransport(source)\n    : withIdAllocator(source);\n\n  return new JsonRpcClient(transport);\n}\n\n/**\n * Distinguish an {@link McpTransport} config (a plain object with a `type`\n * discriminator and no `request` method) from a built\n * {@link McpTransportClient} (which exposes `request`).\n */\nfunction isTransportConfig(source: McpTransport | McpTransportClient): source is McpTransport {\n  return typeof (source as McpTransportClient).request !== \"function\";\n}\n\n/**\n * Wrap an injected {@link McpTransportClient} that lacks its own\n * `allocateId` with a monotonic id source, so the JSON-RPC client can mint\n * request ids uniformly regardless of whether the transport was built here\n * or supplied by a test.\n */\nfunction withIdAllocator(\n  client: McpTransportClient,\n): McpTransportClient & { allocateId(): number } {\n  const candidate = client as McpTransportClient & { allocateId?(): number };\n\n  if (typeof candidate.allocateId === \"function\") {\n    return candidate as McpTransportClient & { allocateId(): number };\n  }\n\n  let nextId = 1;\n\n  return Object.assign(client, { allocateId: () => nextId++ });\n}\n"],"mappings":"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"}
+{"version":3,"file":"transport.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/transport.ts"],"sourcesContent":["import { spawn, type ChildProcessWithoutNullStreams } from \"node:child_process\";\nimport { createInterface, type Interface } from \"node:readline\";\nimport type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, McpTransport } from \"../contracts\";\nimport { McpTransportError } from \"../errors\";\nimport type { McpTransportClient } from \"./transport.type\";\n\n/** Default per-request wait before a transport call is abandoned. */\nconst DEFAULT_REQUEST_TIMEOUT_MS = 30_000;\n\n/** The JSON-RPC version literal every outbound message carries. */\nconst JSONRPC_VERSION = \"2.0\";\n\n/**\n * The only host environment entries a stdio MCP server inherits. This keeps\n * executable lookup and platform runtime behaviour intact without exposing\n * application secrets or arbitrary parent-process configuration to children.\n */\nconst STDIO_ENV_ALLOWLIST = [\n  \"PATH\",\n  \"Path\",\n  \"HOME\",\n  \"USERPROFILE\",\n  \"HOMEDRIVE\",\n  \"HOMEPATH\",\n  \"SystemRoot\",\n  \"SYSTEMROOT\",\n  \"WINDIR\",\n  \"ComSpec\",\n  \"COMSPEC\",\n  \"PATHEXT\",\n] as const;\n\n/**\n * Build the environment passed to a child MCP stdio server. Never forward\n * `process.env` wholesale: only the cross-platform execution essentials are\n * copied, and application-supplied server variables take precedence.\n */\nfunction createStdioEnvironment(\n  serverEnvironment?: Record<string, string>,\n): Record<string, string> {\n  const environment: Record<string, string> = {};\n\n  for (const key of STDIO_ENV_ALLOWLIST) {\n    const value = process.env[key];\n\n    if (value !== undefined) {\n      environment[key] = value;\n    }\n  }\n\n  return { ...environment, ...serverEnvironment };\n}\n\n/**\n * A pending in-flight request awaiting its correlated response, keyed by\n * the JSON-RPC `id`. The stdio transport multiplexes many requests over\n * one line-framed pipe, so each resolve/reject is parked here until the\n * line whose `id` matches arrives.\n */\ninterface PendingCall {\n  resolve(response: JsonRpcResponse): void;\n  reject(error: McpTransportError): void;\n  /** Clears the per-call timeout + abort wiring when the call settles. */\n  cleanup(): void;\n}\n\n/**\n * Wire a per-call timeout and an optional caller `AbortSignal` onto a\n * pending request, returning a `cleanup()` that tears both down. The\n * `onSettle` callback removes the pending entry from whatever registry the\n * transport keeps so a late response can't double-settle.\n */\nfunction armCall(\n  reject: (error: McpTransportError) => void,\n  method: string,\n  options: { signal?: AbortSignal; timeoutMs?: number } | undefined,\n  onSettle: () => void,\n): () => void {\n  const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;\n\n  const timer = setTimeout(() => {\n    onSettle();\n    reject(\n      new McpTransportError(`MCP request \"${method}\" timed out after ${timeoutMs}ms.`, {\n        type: \"timeout\",\n        method,\n      }),\n    );\n  }, timeoutMs);\n\n  const onAbort = () => {\n    cleanup();\n    reject(\n      new McpTransportError(`MCP request \"${method}\" was aborted.`, {\n        type: \"closed\",\n        method,\n      }),\n    );\n  };\n\n  const signal = options?.signal;\n\n  if (signal) {\n    if (signal.aborted) {\n      // Defer so the caller has the rejection wired before it fires.\n      queueMicrotask(onAbort);\n    } else {\n      signal.addEventListener(\"abort\", onAbort, { once: true });\n    }\n  }\n\n  function cleanup(): void {\n    clearTimeout(timer);\n\n    if (signal) {\n      signal.removeEventListener(\"abort\", onAbort);\n    }\n  }\n\n  return cleanup;\n}\n\n/**\n * The stdio transport — spawns a child process and speaks JSON-RPC over\n * its stdin/stdout, one JSON object per line (newline-delimited framing).\n * Uses only Node built-ins (`node:child_process` + `node:readline`); no\n * dependency.\n *\n * Constructed via {@link createStdioTransport}; the class itself is\n * internal.\n */\nclass StdioTransport implements McpTransportClient {\n  /** The spawned server process. */\n  private readonly child: ChildProcessWithoutNullStreams;\n\n  /** Line reader over the child's stdout — one JSON-RPC message per line. */\n  private readonly reader: Interface;\n\n  /** In-flight requests awaiting a correlated response, keyed by id. */\n  private readonly pending = new Map<JsonRpcId, PendingCall>();\n\n  /** Monotonic id source for outbound requests. */\n  private nextId = 1;\n\n  /** Flipped once {@link close} runs (or the child exits) so reuse rejects. */\n  private closed = false;\n\n  public constructor(transport: Extract<McpTransport, { type: \"stdio\" }>) {\n    let child: ChildProcessWithoutNullStreams;\n\n    try {\n      child = spawn(transport.command, transport.args ?? [], {\n        // process.env is NOT inherited wholesale: only the\n        // STDIO_ENV_ALLOWLIST keys are copied, then the caller's explicit\n        // `transport.env` entries are layered on top.\n        env: createStdioEnvironment(transport.env),\n        stdio: [\"pipe\", \"pipe\", \"pipe\"],\n      }) as ChildProcessWithoutNullStreams;\n    } catch (cause) {\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        `MCP stdio transport could not spawn \"${transport.command}\": ${message}`,\n        { type: \"connect\", cause },\n      );\n    }\n\n    this.child = child;\n    this.reader = createInterface({ input: child.stdout });\n\n    this.reader.on(\"line\", (line) => this.onLine(line));\n\n    // A child that dies takes every in-flight (and future) call with it.\n    child.on(\"exit\", (code) => this.failAll(\"connect\", `child exited with code ${code ?? \"null\"}`));\n    child.on(\"error\", (error) => this.failAll(\"connect\", error.message));\n  }\n\n  /**\n   * Parse one stdout line and route it to its pending request. Non-JSON\n   * lines (a server logging to stdout) and messages with no matching `id`\n   * (notifications, stray responses) are ignored — robustness over strictness.\n   */\n  private onLine(line: string): void {\n    const trimmed = line.trim();\n\n    if (!trimmed) {\n      return;\n    }\n\n    let message: JsonRpcResponse;\n\n    try {\n      message = JSON.parse(trimmed) as JsonRpcResponse;\n    } catch {\n      // Not a JSON-RPC line (server diagnostics on stdout) — ignore.\n      return;\n    }\n\n    if (message.id === undefined || message.id === null) {\n      // A notification or a malformed response — nothing to correlate.\n      return;\n    }\n\n    const call = this.pending.get(message.id);\n\n    if (!call) {\n      return;\n    }\n\n    this.pending.delete(message.id);\n    call.cleanup();\n    call.resolve(message);\n  }\n\n  /**\n   * Reject every pending call (and mark the transport unusable) when the\n   * child dies or errors — so a hung server can never leave a caller\n   * waiting forever.\n   */\n  private failAll(type: \"connect\" | \"closed\", reason: string): void {\n    this.closed = true;\n\n    for (const [id, call] of this.pending) {\n      this.pending.delete(id);\n      call.cleanup();\n      call.reject(new McpTransportError(`MCP stdio transport failed: ${reason}.`, { type }));\n    }\n  }\n\n  public request<TResult = unknown>(\n    request: JsonRpcRequest,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<JsonRpcResponse<TResult>> {\n    if (this.closed) {\n      return Promise.reject(\n        new McpTransportError(\"MCP stdio transport is closed.\", {\n          type: \"closed\",\n          method: request.method,\n        }),\n      );\n    }\n\n    const id = request.id;\n\n    return new Promise<JsonRpcResponse<TResult>>((resolve, reject) => {\n      const cleanup = armCall(reject, request.method, options, () => this.pending.delete(id));\n\n      this.pending.set(id, {\n        resolve: (response) => resolve(response as JsonRpcResponse<TResult>),\n        reject,\n        cleanup,\n      });\n\n      try {\n        this.child.stdin.write(`${JSON.stringify(request)}\\n`);\n      } catch (cause) {\n        this.pending.delete(id);\n        cleanup();\n\n        const message = cause instanceof Error ? cause.message : String(cause);\n\n        reject(\n          new McpTransportError(\n            `MCP stdio transport failed to write request \"${request.method}\": ${message}`,\n            { type: \"closed\", method: request.method, cause },\n          ),\n        );\n      }\n    });\n  }\n\n  public async notify(method: string, params?: unknown): Promise<void> {\n    if (this.closed) {\n      throw new McpTransportError(\"MCP stdio transport is closed.\", {\n        type: \"closed\",\n        method,\n      });\n    }\n\n    const notification = { jsonrpc: JSONRPC_VERSION, method, params };\n    this.child.stdin.write(`${JSON.stringify(notification)}\\n`);\n  }\n\n  /** Allocate the next outbound request id. */\n  public allocateId(): number {\n    return this.nextId++;\n  }\n\n  public async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n\n    this.closed = true;\n    this.reader.close();\n    this.failAll(\"closed\", \"transport closed by caller\");\n    this.child.kill();\n  }\n}\n\n/**\n * The Streamable HTTP transport — POSTs each JSON-RPC request to the\n * server endpoint over the global `fetch` (Node 18+) and reads the single\n * JSON response. No SSE-legacy, no WebSocket. Static `headers` (e.g. auth)\n * are sent with every request.\n *\n * Constructed via {@link createHttpTransport}; the class itself is internal.\n */\nclass HttpTransport implements McpTransportClient {\n  /** The server endpoint POST target. */\n  private readonly url: string;\n\n  /** Static headers merged into every request (auth, etc.). */\n  private readonly headers: Record<string, string>;\n\n  /** Monotonic id source for outbound requests. */\n  private nextId = 1;\n\n  public constructor(transport: Extract<McpTransport, { type: \"http\" }>) {\n    this.url = transport.url;\n    this.headers = {\n      \"content-type\": \"application/json\",\n      accept: \"application/json, text/event-stream\",\n      ...transport.headers,\n    };\n  }\n\n  public async request<TResult = unknown>(\n    request: JsonRpcRequest,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<JsonRpcResponse<TResult>> {\n    const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    const onAbort = () => controller.abort();\n    const signal = options?.signal;\n\n    if (signal) {\n      if (signal.aborted) {\n        controller.abort();\n      } else {\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n      }\n    }\n\n    let response: Response;\n\n    try {\n      response = await fetch(this.url, {\n        method: \"POST\",\n        headers: this.headers,\n        body: JSON.stringify(request),\n        signal: controller.signal,\n      });\n    } catch (cause) {\n      const aborted = controller.signal.aborted;\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        aborted\n          ? `MCP request \"${request.method}\" timed out or was aborted after ${timeoutMs}ms.`\n          : `MCP http transport request \"${request.method}\" failed: ${message}`,\n        { type: aborted ? \"timeout\" : \"connect\", method: request.method, cause },\n      );\n    } finally {\n      clearTimeout(timer);\n\n      if (signal) {\n        signal.removeEventListener(\"abort\", onAbort);\n      }\n    }\n\n    if (!response.ok) {\n      throw new McpTransportError(\n        `MCP http transport request \"${request.method}\" returned HTTP ${response.status}.`,\n        { type: \"connect\", method: request.method, context: { status: response.status } },\n      );\n    }\n\n    return this.parseBody<TResult>(response, request.method);\n  }\n\n  /**\n   * Parse the HTTP response body into a JSON-RPC response. Streamable HTTP\n   * may answer with either `application/json` (a single response object)\n   * or `text/event-stream` (SSE frames); we read the body as text and\n   * extract the first JSON object, supporting the common `data: {...}`\n   * SSE line shape without a streaming parser.\n   */\n  private async parseBody<TResult>(\n    response: Response,\n    method: string,\n  ): Promise<JsonRpcResponse<TResult>> {\n    const raw = await response.text();\n    const contentType = response.headers.get(\"content-type\")?.toLowerCase() ?? \"\";\n\n    const jsonText = contentType.includes(\"text/event-stream\") ? extractSseData(raw) : raw;\n\n    if (!jsonText) {\n      throw new McpTransportError(`MCP http transport got an empty response for \"${method}\".`, {\n        type: \"protocol\",\n        method,\n      });\n    }\n\n    try {\n      return JSON.parse(jsonText) as JsonRpcResponse<TResult>;\n    } catch (cause) {\n      throw new McpTransportError(`MCP http transport got a non-JSON response for \"${method}\".`, {\n        type: \"protocol\",\n        method,\n        cause,\n      });\n    }\n  }\n\n  public async notify(method: string, params?: unknown): Promise<void> {\n    const notification = { jsonrpc: JSONRPC_VERSION, method, params };\n\n    // A notification expects no response; fire-and-forget but surface a\n    // connect failure so a dead endpoint is not silently ignored.\n    try {\n      await fetch(this.url, {\n        method: \"POST\",\n        headers: this.headers,\n        body: JSON.stringify(notification),\n      });\n    } catch (cause) {\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        `MCP http transport notification \"${method}\" failed: ${message}`,\n        { type: \"connect\", method, cause },\n      );\n    }\n  }\n\n  /** Allocate the next outbound request id. */\n  public allocateId(): number {\n    return this.nextId++;\n  }\n\n  public async close(): Promise<void> {\n    // Streamable HTTP is stateless per request — nothing persistent to\n    // release.\n  }\n}\n\n/**\n * Pull the first `data:` JSON payload out of an SSE response body. MCP's\n * Streamable HTTP transport answers a single request with one SSE frame\n * carrying the JSON-RPC response; we take the first non-empty `data:`\n * line. Returns an empty string when none is found.\n */\nfunction extractSseData(body: string): string {\n  for (const line of body.split(/\\r?\\n/)) {\n    const trimmed = line.trim();\n\n    if (trimmed.startsWith(\"data:\")) {\n      const payload = trimmed.slice(\"data:\".length).trim();\n\n      if (payload && payload !== \"[DONE]\") {\n        return payload;\n      }\n    }\n  }\n\n  return \"\";\n}\n\n/**\n * Build the concrete {@link McpTransportClient} for an {@link McpTransport}\n * config — a {@link StdioTransport} for `type: \"stdio\"`, an\n * {@link HttpTransport} for `type: \"http\"`. The returned client also\n * carries an `allocateId()` for the JSON-RPC client to mint request ids.\n *\n * @param transport - The transport config (discriminated by `type`).\n * @returns A transport client paired with its id allocator.\n */\nexport function createTransport(\n  transport: McpTransport,\n): McpTransportClient & { allocateId(): number } {\n  if (transport.type === \"stdio\") {\n    return new StdioTransport(transport);\n  }\n\n  return new HttpTransport(transport);\n}\n\n/**\n * A minimal JSON-RPC 2.0 request/response client over any\n * {@link McpTransportClient}. Mints monotonic ids, frames the\n * `{ jsonrpc, id, method, params }` envelope, and unwraps the response —\n * translating a JSON-RPC `error` member into a typed\n * {@link McpTransportError} so callers branch on `error.type` rather than\n * parsing the wire.\n *\n * Constructed via {@link createJsonRpcClient}; the class itself is internal.\n */\nclass JsonRpcClient {\n  /** The underlying framing transport. */\n  private readonly transport: McpTransportClient & { allocateId(): number };\n\n  public constructor(transport: McpTransportClient & { allocateId(): number }) {\n    this.transport = transport;\n  }\n\n  /**\n   * Issue a JSON-RPC `method` call and resolve with its `result`,\n   * throwing a typed {@link McpTransportError} on a JSON-RPC error member\n   * or a malformed response (neither `result` nor `error`).\n   */\n  public async call<TResult = unknown>(\n    method: string,\n    params?: unknown,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<TResult> {\n    const request: JsonRpcRequest = {\n      jsonrpc: JSONRPC_VERSION,\n      id: this.transport.allocateId(),\n      method,\n      params,\n    };\n\n    const response = await this.transport.request<TResult>(request, options);\n\n    if (response.error) {\n      throw new McpTransportError(\n        `MCP \"${method}\" failed: ${response.error.message} (code ${response.error.code}).`,\n        {\n          type: \"protocol\",\n          method,\n          context: { code: response.error.code },\n          cause: response.error.data,\n        },\n      );\n    }\n\n    if (response.result === undefined) {\n      throw new McpTransportError(\n        `MCP \"${method}\" returned a response with neither result nor error.`,\n        { type: \"protocol\", method },\n      );\n    }\n\n    return response.result;\n  }\n\n  /** Send a one-way JSON-RPC notification (no response awaited). */\n  public notify(method: string, params?: unknown): Promise<void> {\n    return this.transport.notify(method, params);\n  }\n\n  /** Close the underlying transport. */\n  public close(): Promise<void> {\n    return this.transport.close();\n  }\n}\n\n/**\n * A JSON-RPC client over an MCP transport. Either pass an already-built\n * transport client (tests inject a fake) or an {@link McpTransport} config\n * to spawn/connect a real one.\n */\nexport interface JsonRpcClientHandle {\n  /** Issue a request and resolve with its `result` (throws on error). */\n  call<TResult = unknown>(\n    method: string,\n    params?: unknown,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<TResult>;\n  /** Send a one-way notification. */\n  notify(method: string, params?: unknown): Promise<void>;\n  /** Close the underlying transport. */\n  close(): Promise<void>;\n}\n\n/**\n * Build a {@link JsonRpcClientHandle} over a transport. Accepts either a\n * pre-built {@link McpTransportClient} (the test seam — inject a scripted\n * fake) or an {@link McpTransport} config, in which case the concrete\n * transport is constructed via {@link createTransport}.\n *\n * When a bare {@link McpTransportClient} (without an `allocateId`) is\n * injected, the client supplies its own monotonic id source.\n *\n * @param source - A transport client or an `McpTransport` config.\n * @returns A JSON-RPC client handle.\n */\nexport function createJsonRpcClient(\n  source: McpTransport | McpTransportClient,\n): JsonRpcClientHandle {\n  const transport: McpTransportClient & { allocateId(): number } = isTransportConfig(source)\n    ? createTransport(source)\n    : withIdAllocator(source);\n\n  return new JsonRpcClient(transport);\n}\n\n/**\n * Distinguish an {@link McpTransport} config (a plain object with a `type`\n * discriminator and no `request` method) from a built\n * {@link McpTransportClient} (which exposes `request`).\n */\nfunction isTransportConfig(source: McpTransport | McpTransportClient): source is McpTransport {\n  return typeof (source as McpTransportClient).request !== \"function\";\n}\n\n/**\n * Wrap an injected {@link McpTransportClient} that lacks its own\n * `allocateId` with a monotonic id source, so the JSON-RPC client can mint\n * request ids uniformly regardless of whether the transport was built here\n * or supplied by a test.\n */\nfunction withIdAllocator(\n  client: McpTransportClient,\n): McpTransportClient & { allocateId(): number } {\n  const candidate = client as McpTransportClient & { allocateId?(): number };\n\n  if (typeof candidate.allocateId === \"function\") {\n    return candidate as McpTransportClient & { allocateId(): number };\n  }\n\n  let nextId = 1;\n\n  return Object.assign(client, { allocateId: () => nextId++ });\n}\n"],"mappings":"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"}

package/esm/mcp/transport.type.d.mts

@@ -1,4 +1,5 @@
 import { JsonRpcRequest, JsonRpcResponse } from "../contracts/mcp.type.mjs";
+import "../contracts/index.mjs";
 //#region ../../packages/ai-tools/src/mcp/transport.type.d.ts
 /**
  * Internal contract every concrete MCP transport (stdio / Streamable HTTP)
@@ -14,7 +15,7 @@ import { JsonRpcRequest, JsonRpcResponse } from "../contracts/mcp.type.mjs";
  * **`type`, never `kind`.** This package's discriminators are all `type`;
  * any inbound MCP `kind` is translated at the client boundary.
  */
-interface McpTransportClient {
+export interface McpTransportClient {
   /**
    * Send a JSON-RPC request and resolve with its matching response.
    *
@@ -47,5 +48,4 @@ interface McpTransportClient {
   close(): Promise<void>;
 }
 //#endregion
-export { McpTransportClient };
 //# sourceMappingURL=transport.type.d.mts.map

package/esm/mcp/transport.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/transport.type.ts"],"mappings":";;;;;AAgBA;;;;;;;;;;;UAAiB,kBAAA;EAaf;;;;;;;;;;;;EAAA,OAAA,oBACE,OAAA,EAAS,cAAA,EACT,OAAA;IAAY,MAAA,GAAS,WAAA;IAAa,SAAA;EAAA,IACjC,OAAA,CAAQ,eAAA,CAAgB,OAAA;EAgBlB;;AAAO;;;;;EAPhB,MAAA,CAAO,MAAA,UAAgB,MAAA,aAAmB,OAAA;;;;;;EAO1C,KAAA,IAAS,OAAA;AAAA"}
+{"version":3,"file":"transport.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/transport.type.ts"],"mappings":";;;;;;;;;;;;;;;;;iBAgBiB;;;;;;;;;;;;;EAaf,QAAQ,mBACN,SAAS,gBACT;IAAY,SAAS;IAAa;MACjC,QAAQ,gBAAgB;;;;;;;;EAS3B,OAAO,gBAAgB,mBAAmB;;;;;;EAO1C,SAAS"}

package/esm/register.d.mts

@@ -1,9 +1,9 @@
 import { FetchUrlInput, FetchUrlOptions, FetchUrlResult, WebSearchInput, WebSearchOptions, WebSearchResult } from "./contracts/web.type.mjs";
 import { HttpRequestInput, HttpRequestOptions, HttpRequestResult } from "./contracts/http.type.mjs";
 import { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOptions, DateTimeResult } from "./contracts/utility.type.mjs";
+import "./contracts/index.mjs";
 import { McpFactory } from "./mcp/index.mjs";
 import { ToolContract, measureTools } from "@warlock.js/ai";
-
 //#region ../../packages/ai-tools/src/register.d.ts
 /**
  * The `ai.tools.*` namespace — the five ready-made agent tools this
@@ -13,7 +13,7 @@ import { ToolContract, measureTools } from "@warlock.js/ai";
  * across the tool sub-barrels, mirroring the `ai.workspace` augmentation in
  * `@warlock.js/ai-workspace`.
  */
-interface AiToolsNamespace {
+export interface AiToolsNamespace {
   /** Search the web via a chosen provider; returns ranked LLM-ready hits. */
   webSearch(options: WebSearchOptions): ToolContract<WebSearchInput, WebSearchResult>;
   /** Fetch a URL (host-allowlisted, byte-capped) and return its content. */
@@ -60,7 +60,6 @@ declare module "@warlock.js/ai" {
      */
     mcp: McpFactory;
   }
-} //# sourceMappingURL=register.d.ts.map
+}
 //#endregion
-export { AiToolsNamespace };
 //# sourceMappingURL=register.d.mts.map

package/esm/register.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"register.d.mts","names":[],"sources":["../../../../../../../packages/ai-tools/src/register.ts"],"mappings":";;;;;;;;;;;;AAiCA;;;UAAiB,gBAAA;EAEoC;EAAnD,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,YAAA,CAAa,cAAA,EAAgB,eAAA;EAA7B;EAEtC,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,YAAA,CAAa,aAAA,EAAe,cAAA;EAAf;EAElD,IAAA,CAAK,OAAA,GAAU,kBAAA,GAAqB,YAAA,CAAa,gBAAA,EAAkB,iBAAA;EAF9B;EAIrC,UAAA,CAAW,OAAA,GAAU,iBAAA,GAAoB,YAAA,CAAa,eAAA,EAAiB,gBAAA;EAFtB;EAIjD,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,YAAA,CAAa,aAAA,EAAe,cAAA;EAJ7B;;;;;;;;;;EAepC,OAAA,SAAgB,YAAA;AAAA;;;;;;;;;;YAYN,EAAA;IA7BwC;;;;;IAmChD,KAAA,EAAO,gBAAA;IAjCwC;;;;;;IAwC/C,GAAA,EAAK,UAAU;EAAA;AAAA"}
+{"version":3,"file":"register.d.mts","names":[],"sources":["../../../../../../../packages/ai-tools/src/register.ts"],"mappings":";;;;;;;;;;;;;;;iBAiCiB;;EAEf,UAAU,SAAS,mBAAmB,aAAa,gBAAgB;;EAEnE,SAAS,UAAU,kBAAkB,aAAa,eAAe;;EAEjE,KAAK,UAAU,qBAAqB,aAAa,kBAAkB;;EAEnE,WAAW,UAAU,oBAAoB,aAAa,iBAAiB;;EAEvE,SAAS,UAAU,kBAAkB,aAAa,eAAe;;;;;;;;;;;EAWjE,gBAAgB;;;;;;;;;;;YAYN;;;;;;IAMR,OAAO;;;;;;;IAOP,KAAK"}

package/esm/utility/calculator.d.mts

@@ -1,6 +1,5 @@
 import { CalculatorInput, CalculatorOptions, CalculatorResult } from "../contracts/utility.type.mjs";
 import { ToolContract } from "@warlock.js/ai";
-
 //#region ../../packages/ai-tools/src/utility/calculator.d.ts
 /**
  * Build the `calculator` tool — a SAFE arithmetic evaluator the agent can
@@ -29,7 +28,6 @@ import { ToolContract } from "@warlock.js/ai";
  * const { data } = await calc.invoke({ expression: "(3 + 4) * 2" });
  * console.log(data?.result); // 14
  */
-declare function calculatorTool(options?: CalculatorOptions): ToolContract<CalculatorInput, CalculatorResult>;
+export declare function calculatorTool(options?: CalculatorOptions): ToolContract<CalculatorInput, CalculatorResult>;
 //#endregion
-export { calculatorTool };
 //# sourceMappingURL=calculator.d.mts.map

package/esm/utility/calculator.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"calculator.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/utility/calculator.ts"],"mappings":";;;;;;AAoYA;;;;;;;;;;;;;;;AAEiD;;;;;;;;;;iBAFjC,cAAA,CACd,OAAA,GAAU,iBAAA,GACT,YAAA,CAAa,eAAA,EAAiB,gBAAA"}
+{"version":3,"file":"calculator.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/utility/calculator.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoYgB,eACd,UAAU,oBACT,aAAa,iBAAiB"}

package/esm/utility/date-time.d.mts

@@ -1,15 +1,14 @@
 import { DateTimeInput, DateTimeOptions, DateTimeResult } from "../contracts/utility.type.mjs";
 import { ToolContract } from "@warlock.js/ai";
-
 //#region ../../packages/ai-tools/src/utility/date-time.d.ts
 /**
  * A clock seam so tests are deterministic. Defaults to the real
  * {@link Date}; a test injects a fixed instant. Returns milliseconds
  * since the Unix epoch — the same contract as `Date.now()`.
  */
-type Clock = () => number;
+export type Clock = () => number;
 /** Construction dependencies for {@link dateTimeTool}, all optional. */
-interface DateTimeToolDeps {
+export interface DateTimeToolDeps {
   /**
    * The clock used by the `now` op. Defaults to `Date.now`. Injected in
    * tests for deterministic output.
@@ -51,7 +50,6 @@ interface DateTimeToolDeps {
  * const { data } = await dt.invoke({ op: "now" });
  * console.log(data?.value); // "2026-06-22T00:00:00.000Z"
  */
-declare function dateTimeTool(options?: DateTimeOptions, deps?: DateTimeToolDeps): ToolContract<DateTimeInput, DateTimeResult>;
+export declare function dateTimeTool(options?: DateTimeOptions, deps?: DateTimeToolDeps): ToolContract<DateTimeInput, DateTimeResult>;
 //#endregion
-export { Clock, DateTimeToolDeps, dateTimeTool };
 //# sourceMappingURL=date-time.d.mts.map

package/esm/utility/date-time.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"date-time.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/utility/date-time.ts"],"mappings":";;;;;;AAqBA;;;KAAY,KAAA;AAAK;AAAA,UAGA,gBAAA;EAAgB;;;AAKlB;EAAb,KAAA,GAAQ,KAAK;AAAA;;;;;;;;;;;;;;;;;AAmL8B;;;;;;;;;;;;;;;;;;;iBAH7B,YAAA,CACd,OAAA,GAAU,eAAA,EACV,IAAA,GAAO,gBAAA,GACN,YAAA,CAAa,aAAA,EAAe,cAAA"}
+{"version":3,"file":"date-time.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/utility/date-time.ts"],"mappings":";;;;;;;;YAqBY;;iBAGK;;;;;EAKf,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAgLM,aACd,UAAU,iBACV,OAAO,mBACN,aAAa,eAAe"}

package/esm/utility/date-time.mjs

@@ -55,7 +55,8 @@ const UNIT_ALIASES = {
 };
 /** Resolve a (possibly aliased / singular) unit token to its ms length. */
 function unitToMs(unit) {
-	const ms = UNIT_MS[UNIT_ALIASES[unit] ?? unit];
+	const canonical = UNIT_ALIASES[unit] ?? unit;
+	const ms = UNIT_MS[canonical];
 	if (ms === void 0) throw new DateTimeError(`Unknown unit "${unit}". Supported units: ${Object.keys(UNIT_MS).join(", ")}.`, { type: "invalid-unit" });
 	return ms;
 }

package/esm/utility/date-time.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"date-time.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/utility/date-time.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { DateTimeError } from \"../errors\";\nimport { literalField, objectSchema, optionalNumberField, optionalStringField } from \"./schema\";\nimport type {\n  DateTimeInput,\n  DateTimeOp,\n  DateTimeOptions,\n  DateTimeResult,\n} from \"../contracts/utility.type\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"date_time\";\n\n/** The closed set of operations the tool implements. */\nconst OPS: readonly DateTimeOp[] = [\"now\", \"add\", \"diff\", \"format\"];\n\n/**\n * A clock seam so tests are deterministic. Defaults to the real\n * {@link Date}; a test injects a fixed instant. Returns milliseconds\n * since the Unix epoch — the same contract as `Date.now()`.\n */\nexport type Clock = () => number;\n\n/** Construction dependencies for {@link dateTimeTool}, all optional. */\nexport interface DateTimeToolDeps {\n  /**\n   * The clock used by the `now` op. Defaults to `Date.now`. Injected in\n   * tests for deterministic output.\n   */\n  clock?: Clock;\n}\n\n/** Input schema for the `date_time` tool. */\nconst inputSchema = objectSchema<DateTimeInput>({\n  op: literalField<DateTimeOp>(OPS),\n  iso: optionalStringField(),\n  from: optionalStringField(),\n  to: optionalStringField(),\n  amount: optionalNumberField(),\n  unit: optionalStringField(),\n  timeZone: optionalStringField(),\n  format: optionalStringField(),\n});\n\n/**\n * The time units `add` and `diff` understand, each as its length in\n * milliseconds. Calendar-unaware on purpose: a \"month\" / \"year\" has no\n * fixed millisecond length, so they are deliberately excluded — adding\n * `30 days` is unambiguous in a way adding `1 month` is not.\n */\nconst UNIT_MS: Record<string, number> = {\n  milliseconds: 1,\n  seconds: 1_000,\n  minutes: 60_000,\n  hours: 3_600_000,\n  days: 86_400_000,\n  weeks: 604_800_000,\n};\n\n/** Singular aliases mapped to their canonical plural unit key. */\nconst UNIT_ALIASES: Record<string, string> = {\n  millisecond: \"milliseconds\",\n  ms: \"milliseconds\",\n  second: \"seconds\",\n  sec: \"seconds\",\n  s: \"seconds\",\n  minute: \"minutes\",\n  min: \"minutes\",\n  m: \"minutes\",\n  hour: \"hours\",\n  hr: \"hours\",\n  h: \"hours\",\n  day: \"days\",\n  d: \"days\",\n  week: \"weeks\",\n  w: \"weeks\",\n};\n\n/** Resolve a (possibly aliased / singular) unit token to its ms length. */\nfunction unitToMs(unit: string): number {\n  const canonical = UNIT_ALIASES[unit] ?? unit;\n  const ms = UNIT_MS[canonical];\n\n  if (ms === undefined) {\n    throw new DateTimeError(\n      `Unknown unit \"${unit}\". Supported units: ${Object.keys(UNIT_MS).join(\", \")}.`,\n      { type: \"invalid-unit\" },\n    );\n  }\n\n  return ms;\n}\n\n/**\n * Parse an ISO-8601 instant into a {@link Date}, or throw a typed\n * {@link DateTimeError} when the string is missing or unparseable.\n *\n * @param iso - The ISO string from the model (may be undefined).\n * @param field - The input field name, for the error message.\n */\nfunction parseIso(iso: string | undefined, field: string): Date {\n  if (iso === undefined) {\n    throw new DateTimeError(`\"${field}\" is required for this operation.`, {\n      type: \"invalid-input\",\n    });\n  }\n\n  const date = new Date(iso);\n\n  if (Number.isNaN(date.getTime())) {\n    throw new DateTimeError(`\"${field}\" is not a valid ISO-8601 instant: \"${iso}\".`, {\n      type: \"invalid-input\",\n    });\n  }\n\n  return date;\n}\n\n/**\n * Render a {@link Date} in a target time zone using `Intl`. The\n * `\"iso\"` format (the default) returns the instant's UTC ISO string;\n * any other `format` value is treated as an `Intl.DateTimeFormat`\n * locale-style rendering in the given `timeZone`.\n *\n * @throws DateTimeError `type: \"invalid-time-zone\"` when `timeZone` is\n *   not a recognized IANA zone.\n */\nfunction render(date: Date, format: string | undefined, timeZone: string | undefined): string {\n  if (format === undefined || format === \"iso\") {\n    // `timeZone` is irrelevant to a UTC ISO string, but validate it when\n    // supplied so a bad zone is reported rather than silently ignored.\n    if (timeZone !== undefined) {\n      assertTimeZone(timeZone);\n    }\n\n    return date.toISOString();\n  }\n\n  try {\n    return new Intl.DateTimeFormat(\"en-US\", {\n      timeZone,\n      dateStyle: format === \"date\" ? \"medium\" : undefined,\n      timeStyle: format === \"time\" ? \"medium\" : undefined,\n      ...(format === \"datetime\" ? { dateStyle: \"medium\", timeStyle: \"medium\" } : {}),\n    }).format(date);\n  } catch (error) {\n    throw new DateTimeError(\n      `Could not render with format \"${format}\"${timeZone ? ` in time zone \"${timeZone}\"` : \"\"}.`,\n      { type: \"invalid-time-zone\", cause: error },\n    );\n  }\n}\n\n/**\n * Validate an IANA time zone by attempting to construct a formatter for\n * it; an unrecognized zone makes `Intl` throw a `RangeError`.\n *\n * @throws DateTimeError `type: \"invalid-time-zone\"` for an unknown zone.\n */\nfunction assertTimeZone(timeZone: string): void {\n  try {\n    new Intl.DateTimeFormat(\"en-US\", { timeZone });\n  } catch (error) {\n    throw new DateTimeError(`Unknown time zone \"${timeZone}\".`, {\n      type: \"invalid-time-zone\",\n      cause: error,\n    });\n  }\n}\n\n/**\n * Build the `date_time` tool — a small clock/calendar utility the agent\n * can call to read the current instant, shift an instant, measure the\n * gap between two instants, or render one. The `op` discriminator selects\n * the operation:\n *\n * - **`now`** — the current instant, rendered per `format` / `timeZone`\n *   (defaults to a UTC ISO string). Reads the injectable {@link Clock}.\n * - **`add`** — `iso` shifted by `amount` of `unit` (e.g.\n *   `+3 days`); a negative `amount` shifts backward.\n * - **`diff`** — the signed difference `to − iso`, expressed in `unit`.\n * - **`format`** — `iso` rendered per `format` / `timeZone`.\n *\n * Units are millisecond-based (`milliseconds`…`weeks`, plus common\n * aliases); calendar-relative `month`/`year` are intentionally\n * unsupported because they have no fixed length.\n *\n * **Deterministic in tests.** The clock backing `now` is injectable via\n * `deps.clock`; production defaults to `Date.now`.\n *\n * **Errors flow as data.** A missing/invalid field, an unknown unit, or\n * an unrecognized time zone throws a {@link DateTimeError} inside the\n * handler; `tool()` surfaces it in `{ error }` so the agent self-corrects.\n *\n * @param options - Optional overrides; `name` renames the tool,\n *   `defaultTimeZone` applies when a call omits `timeZone`.\n * @param deps - Injectable dependencies (the {@link Clock}); defaults to real time.\n * @returns A `ToolContract<DateTimeInput, { value }>` ready for `tools: []`.\n *\n * @example\n * const clock = () => Date.parse(\"2026-06-22T00:00:00Z\");\n * const dt = dateTimeTool({}, { clock });\n * const { data } = await dt.invoke({ op: \"now\" });\n * console.log(data?.value); // \"2026-06-22T00:00:00.000Z\"\n */\nexport function dateTimeTool(\n  options?: DateTimeOptions,\n  deps?: DateTimeToolDeps,\n): ToolContract<DateTimeInput, DateTimeResult> {\n  const clock: Clock = deps?.clock ?? Date.now;\n  const defaultTimeZone = options?.defaultTimeZone;\n\n  return tool<DateTimeInput, DateTimeResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      'Work with dates and times. Set op to: \"now\" (current instant), ' +\n      '\"add\" (shift iso by amount of unit), \"diff\" (signed to − from in unit; ' +\n      \"pass the start instant as iso or from), \" +\n      'or \"format\" (render iso). Units are milliseconds, seconds, minutes, ' +\n      \"hours, days, or weeks (month/year are not supported). Pass instants as \" +\n      'ISO-8601 strings; set format to \"iso\" (default), \"date\", \"time\", or ' +\n      '\"datetime\", and timeZone as an IANA zone like \"Africa/Cairo\".',\n    input: inputSchema,\n    async execute(input) {\n      const timeZone = input.timeZone ?? defaultTimeZone;\n\n      switch (input.op) {\n        case \"now\": {\n          const date = new Date(clock());\n\n          return { value: render(date, input.format, timeZone) };\n        }\n\n        case \"format\": {\n          const date = parseIso(input.iso, \"iso\");\n\n          return { value: render(date, input.format, timeZone) };\n        }\n\n        case \"add\": {\n          const date = parseIso(input.iso, \"iso\");\n\n          if (input.amount === undefined) {\n            throw new DateTimeError('\"amount\" is required for the \"add\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          if (input.unit === undefined) {\n            throw new DateTimeError('\"unit\" is required for the \"add\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          const shifted = new Date(date.getTime() + input.amount * unitToMs(input.unit));\n\n          return { value: render(shifted, input.format, timeZone) };\n        }\n\n        case \"diff\": {\n          // Accept `from` as an alias for `iso` — models naturally pass\n          // `from` / `to` for a difference. `iso` wins when both are set.\n          const from = parseIso(input.iso ?? input.from, \"iso (or from)\");\n          const to = parseIso(input.to, \"to\");\n\n          if (input.unit === undefined) {\n            throw new DateTimeError('\"unit\" is required for the \"diff\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          const diff = (to.getTime() - from.getTime()) / unitToMs(input.unit);\n\n          return { value: String(diff) };\n        }\n\n        default: {\n          // Exhaustiveness guard — the schema's literal union should make\n          // this unreachable, but a future op added to the union without a\n          // case here surfaces as typed data rather than silent fallthrough.\n          const unreachable: never = input.op;\n\n          throw new DateTimeError(`Unsupported operation \"${String(unreachable)}\".`, {\n            type: \"unsupported-op\",\n          });\n        }\n      }\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"date-time.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/utility/date-time.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { DateTimeError } from \"../errors\";\nimport { literalField, objectSchema, optionalNumberField, optionalStringField } from \"./schema\";\nimport type {\n  DateTimeInput,\n  DateTimeOp,\n  DateTimeOptions,\n  DateTimeResult,\n} from \"../contracts/utility.type\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"date_time\";\n\n/** The closed set of operations the tool implements. */\nconst OPS: readonly DateTimeOp[] = [\"now\", \"add\", \"diff\", \"format\"];\n\n/**\n * A clock seam so tests are deterministic. Defaults to the real\n * {@link Date}; a test injects a fixed instant. Returns milliseconds\n * since the Unix epoch — the same contract as `Date.now()`.\n */\nexport type Clock = () => number;\n\n/** Construction dependencies for {@link dateTimeTool}, all optional. */\nexport interface DateTimeToolDeps {\n  /**\n   * The clock used by the `now` op. Defaults to `Date.now`. Injected in\n   * tests for deterministic output.\n   */\n  clock?: Clock;\n}\n\n/** Input schema for the `date_time` tool. */\nconst inputSchema = objectSchema<DateTimeInput>({\n  op: literalField<DateTimeOp>(OPS),\n  iso: optionalStringField(),\n  from: optionalStringField(),\n  to: optionalStringField(),\n  amount: optionalNumberField(),\n  unit: optionalStringField(),\n  timeZone: optionalStringField(),\n  format: optionalStringField(),\n});\n\n/**\n * The time units `add` and `diff` understand, each as its length in\n * milliseconds. Calendar-unaware on purpose: a \"month\" / \"year\" has no\n * fixed millisecond length, so they are deliberately excluded — adding\n * `30 days` is unambiguous in a way adding `1 month` is not.\n */\nconst UNIT_MS: Record<string, number> = {\n  milliseconds: 1,\n  seconds: 1_000,\n  minutes: 60_000,\n  hours: 3_600_000,\n  days: 86_400_000,\n  weeks: 604_800_000,\n};\n\n/** Singular aliases mapped to their canonical plural unit key. */\nconst UNIT_ALIASES: Record<string, string> = {\n  millisecond: \"milliseconds\",\n  ms: \"milliseconds\",\n  second: \"seconds\",\n  sec: \"seconds\",\n  s: \"seconds\",\n  minute: \"minutes\",\n  min: \"minutes\",\n  m: \"minutes\",\n  hour: \"hours\",\n  hr: \"hours\",\n  h: \"hours\",\n  day: \"days\",\n  d: \"days\",\n  week: \"weeks\",\n  w: \"weeks\",\n};\n\n/** Resolve a (possibly aliased / singular) unit token to its ms length. */\nfunction unitToMs(unit: string): number {\n  const canonical = UNIT_ALIASES[unit] ?? unit;\n  const ms = UNIT_MS[canonical];\n\n  if (ms === undefined) {\n    throw new DateTimeError(\n      `Unknown unit \"${unit}\". Supported units: ${Object.keys(UNIT_MS).join(\", \")}.`,\n      { type: \"invalid-unit\" },\n    );\n  }\n\n  return ms;\n}\n\n/**\n * Parse an ISO-8601 instant into a {@link Date}, or throw a typed\n * {@link DateTimeError} when the string is missing or unparseable.\n *\n * @param iso - The ISO string from the model (may be undefined).\n * @param field - The input field name, for the error message.\n */\nfunction parseIso(iso: string | undefined, field: string): Date {\n  if (iso === undefined) {\n    throw new DateTimeError(`\"${field}\" is required for this operation.`, {\n      type: \"invalid-input\",\n    });\n  }\n\n  const date = new Date(iso);\n\n  if (Number.isNaN(date.getTime())) {\n    throw new DateTimeError(`\"${field}\" is not a valid ISO-8601 instant: \"${iso}\".`, {\n      type: \"invalid-input\",\n    });\n  }\n\n  return date;\n}\n\n/**\n * Render a {@link Date} in a target time zone using `Intl`. The\n * `\"iso\"` format (the default) returns the instant's UTC ISO string;\n * any other `format` value is treated as an `Intl.DateTimeFormat`\n * locale-style rendering in the given `timeZone`.\n *\n * @throws DateTimeError `type: \"invalid-time-zone\"` when `timeZone` is\n *   not a recognized IANA zone.\n */\nfunction render(date: Date, format: string | undefined, timeZone: string | undefined): string {\n  if (format === undefined || format === \"iso\") {\n    // `timeZone` is irrelevant to a UTC ISO string, but validate it when\n    // supplied so a bad zone is reported rather than silently ignored.\n    if (timeZone !== undefined) {\n      assertTimeZone(timeZone);\n    }\n\n    return date.toISOString();\n  }\n\n  try {\n    return new Intl.DateTimeFormat(\"en-US\", {\n      timeZone,\n      dateStyle: format === \"date\" ? \"medium\" : undefined,\n      timeStyle: format === \"time\" ? \"medium\" : undefined,\n      ...(format === \"datetime\" ? { dateStyle: \"medium\", timeStyle: \"medium\" } : {}),\n    }).format(date);\n  } catch (error) {\n    throw new DateTimeError(\n      `Could not render with format \"${format}\"${timeZone ? ` in time zone \"${timeZone}\"` : \"\"}.`,\n      { type: \"invalid-time-zone\", cause: error },\n    );\n  }\n}\n\n/**\n * Validate an IANA time zone by attempting to construct a formatter for\n * it; an unrecognized zone makes `Intl` throw a `RangeError`.\n *\n * @throws DateTimeError `type: \"invalid-time-zone\"` for an unknown zone.\n */\nfunction assertTimeZone(timeZone: string): void {\n  try {\n    new Intl.DateTimeFormat(\"en-US\", { timeZone });\n  } catch (error) {\n    throw new DateTimeError(`Unknown time zone \"${timeZone}\".`, {\n      type: \"invalid-time-zone\",\n      cause: error,\n    });\n  }\n}\n\n/**\n * Build the `date_time` tool — a small clock/calendar utility the agent\n * can call to read the current instant, shift an instant, measure the\n * gap between two instants, or render one. The `op` discriminator selects\n * the operation:\n *\n * - **`now`** — the current instant, rendered per `format` / `timeZone`\n *   (defaults to a UTC ISO string). Reads the injectable {@link Clock}.\n * - **`add`** — `iso` shifted by `amount` of `unit` (e.g.\n *   `+3 days`); a negative `amount` shifts backward.\n * - **`diff`** — the signed difference `to − iso`, expressed in `unit`.\n * - **`format`** — `iso` rendered per `format` / `timeZone`.\n *\n * Units are millisecond-based (`milliseconds`…`weeks`, plus common\n * aliases); calendar-relative `month`/`year` are intentionally\n * unsupported because they have no fixed length.\n *\n * **Deterministic in tests.** The clock backing `now` is injectable via\n * `deps.clock`; production defaults to `Date.now`.\n *\n * **Errors flow as data.** A missing/invalid field, an unknown unit, or\n * an unrecognized time zone throws a {@link DateTimeError} inside the\n * handler; `tool()` surfaces it in `{ error }` so the agent self-corrects.\n *\n * @param options - Optional overrides; `name` renames the tool,\n *   `defaultTimeZone` applies when a call omits `timeZone`.\n * @param deps - Injectable dependencies (the {@link Clock}); defaults to real time.\n * @returns A `ToolContract<DateTimeInput, { value }>` ready for `tools: []`.\n *\n * @example\n * const clock = () => Date.parse(\"2026-06-22T00:00:00Z\");\n * const dt = dateTimeTool({}, { clock });\n * const { data } = await dt.invoke({ op: \"now\" });\n * console.log(data?.value); // \"2026-06-22T00:00:00.000Z\"\n */\nexport function dateTimeTool(\n  options?: DateTimeOptions,\n  deps?: DateTimeToolDeps,\n): ToolContract<DateTimeInput, DateTimeResult> {\n  const clock: Clock = deps?.clock ?? Date.now;\n  const defaultTimeZone = options?.defaultTimeZone;\n\n  return tool<DateTimeInput, DateTimeResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      'Work with dates and times. Set op to: \"now\" (current instant), ' +\n      '\"add\" (shift iso by amount of unit), \"diff\" (signed to − from in unit; ' +\n      \"pass the start instant as iso or from), \" +\n      'or \"format\" (render iso). Units are milliseconds, seconds, minutes, ' +\n      \"hours, days, or weeks (month/year are not supported). Pass instants as \" +\n      'ISO-8601 strings; set format to \"iso\" (default), \"date\", \"time\", or ' +\n      '\"datetime\", and timeZone as an IANA zone like \"Africa/Cairo\".',\n    input: inputSchema,\n    async execute(input) {\n      const timeZone = input.timeZone ?? defaultTimeZone;\n\n      switch (input.op) {\n        case \"now\": {\n          const date = new Date(clock());\n\n          return { value: render(date, input.format, timeZone) };\n        }\n\n        case \"format\": {\n          const date = parseIso(input.iso, \"iso\");\n\n          return { value: render(date, input.format, timeZone) };\n        }\n\n        case \"add\": {\n          const date = parseIso(input.iso, \"iso\");\n\n          if (input.amount === undefined) {\n            throw new DateTimeError('\"amount\" is required for the \"add\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          if (input.unit === undefined) {\n            throw new DateTimeError('\"unit\" is required for the \"add\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          const shifted = new Date(date.getTime() + input.amount * unitToMs(input.unit));\n\n          return { value: render(shifted, input.format, timeZone) };\n        }\n\n        case \"diff\": {\n          // Accept `from` as an alias for `iso` — models naturally pass\n          // `from` / `to` for a difference. `iso` wins when both are set.\n          const from = parseIso(input.iso ?? input.from, \"iso (or from)\");\n          const to = parseIso(input.to, \"to\");\n\n          if (input.unit === undefined) {\n            throw new DateTimeError('\"unit\" is required for the \"diff\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          const diff = (to.getTime() - from.getTime()) / unitToMs(input.unit);\n\n          return { value: String(diff) };\n        }\n\n        default: {\n          // Exhaustiveness guard — the schema's literal union should make\n          // this unreachable, but a future op added to the union without a\n          // case here surfaces as typed data rather than silent fallthrough.\n          const unreachable: never = input.op;\n\n          throw new DateTimeError(`Unsupported operation \"${String(unreachable)}\".`, {\n            type: \"unsupported-op\",\n          });\n        }\n      }\n    },\n  });\n}\n"],"mappings":"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"}

package/esm/utility/index.d.mts

@@ -1,2 +1,3 @@
 import { calculatorTool } from "./calculator.mjs";
-import { Clock, DateTimeToolDeps, dateTimeTool } from "./date-time.mjs";
+import { Clock, DateTimeToolDeps, dateTimeTool } from "./date-time.mjs";
+export { calculatorTool, dateTimeTool };

package/esm/utility/index.mjs

@@ -1,4 +1,4 @@
 import { calculatorTool } from "./calculator.mjs";
 import { dateTimeTool } from "./date-time.mjs";
 
-export {  };
+export { calculatorTool, dateTimeTool };

package/esm/web/fetch-url.d.mts

@@ -1,6 +1,6 @@
 import { FetchUrlInput, FetchUrlOptions, FetchUrlResult } from "../contracts/web.type.mjs";
+import "../contracts/index.mjs";
 import { ToolContract } from "@warlock.js/ai";
-
 //#region ../../packages/ai-tools/src/web/fetch-url.d.ts
 /**
  * Build the agent-facing `fetch_url` tool — fetch a URL over the global
@@ -41,7 +41,6 @@ import { ToolContract } from "@warlock.js/ai";
  * const { data } = await fetchUrl.invoke({ url: "https://docs.stripe.com/api" });
  * console.log(data?.content, data?.truncated);
  */
-declare function fetchUrlTool(options?: FetchUrlOptions): ToolContract<FetchUrlInput, FetchUrlResult>;
+export declare function fetchUrlTool(options?: FetchUrlOptions): ToolContract<FetchUrlInput, FetchUrlResult>;
 //#endregion
-export { fetchUrlTool };
 //# sourceMappingURL=fetch-url.d.mts.map

package/esm/web/fetch-url.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-url.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/web/fetch-url.ts"],"mappings":";;;;;;;AA2SA;;;;;;;;;;;;;;;AAE6C;;;;;;;;;;;;;;;;;;;;;iBAF7B,YAAA,CACd,OAAA,GAAU,eAAA,GACT,YAAA,CAAa,aAAA,EAAe,cAAA"}
+{"version":3,"file":"fetch-url.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/web/fetch-url.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2SgB,aACd,UAAU,kBACT,aAAa,eAAe"}

package/esm/web/fetch-url.mjs

@@ -224,7 +224,8 @@ function fetchUrlTool(options) {
 					type: "denied-host",
 					cause
 				});
-				throw new WebToolError(`fetch_url request failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+				const message = cause instanceof Error ? cause.message : String(cause);
+				throw new WebToolError(`fetch_url request failed: ${message}`, {
 					type: "request-failed",
 					cause
 				});

package/esm/web/fetch-url.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-url.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/web/fetch-url.ts"],"sourcesContent":["import { guardedFetch, OutboundPolicyError, tool, type ToolContract } from \"@warlock.js/ai\";\nimport type { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult } from \"../contracts\";\nimport { WebToolError } from \"../errors\";\nimport { objectSchema, stringField } from \"./schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"fetch_url\";\n\n/** Default hard cap on response bytes read before truncation. */\nconst DEFAULT_MAX_BYTES = 1_000_000;\n\n/** Default per-request timeout in milliseconds. */\nconst DEFAULT_TIMEOUT_MS = 15_000;\n\n/** Default rendering mode for the fetched document. */\nconst DEFAULT_EXTRACT: FetchUrlExtract = \"text\";\n\n/** Input schema: `{ url }`. */\nconst inputSchema = objectSchema<FetchUrlInput>({\n  url: stringField(),\n});\n\n// ============================================================\n// Lazily-loaded @mozilla/readability + jsdom (OPTIONAL peers)\n// ============================================================\n\n/**\n * Minimal structural shapes of the optional `@mozilla/readability` + `jsdom`\n * peers — only the members this file actually uses. Declared locally so the\n * package type-checks even when the peers are NOT installed (they are lazy\n * optional peers, loaded below via a `string` specifier so `tsc` never tries\n * to statically resolve them).\n */\ninterface ReadabilityArticleLike {\n  readonly content?: string | null;\n  readonly textContent?: string | null;\n}\ninterface ReadabilityInstanceLike {\n  parse(): ReadabilityArticleLike | null;\n}\ninterface ReadabilityModuleLike {\n  Readability: new (document: unknown) => ReadabilityInstanceLike;\n}\ninterface JsdomInstanceLike {\n  readonly window: { readonly document: unknown };\n}\ninterface JsdomModuleLike {\n  JSDOM: new (html: string, options?: { url?: string }) => JsdomInstanceLike;\n}\n\n// String specifiers typed `string` (not a literal) so `tsc` does not attempt\n// to resolve these optional peers at build time.\nconst READABILITY_MODULE_ID: string = \"@mozilla/readability\";\nconst JSDOM_MODULE_ID: string = \"jsdom\";\n\nlet ReadabilitySdk: ReadabilityModuleLike;\nlet JsdomSdk: JsdomModuleLike;\nlet isReadabilityAvailable: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\nconst READABILITY_INSTALL_INSTRUCTIONS = `\nThe fetch_url text/markdown extractor requires the @mozilla/readability and jsdom packages.\nInstall them with:\n\n  npm install @mozilla/readability jsdom\n\nOr with your preferred package manager:\n\n  pnpm add @mozilla/readability jsdom\n  yarn add @mozilla/readability jsdom\n`.trim();\n\n/**\n * Settle the lazy import of `@mozilla/readability` + `jsdom` once,\n * concurrency-safe. Only needed for the `\"text\"` / `\"markdown\"` extract\n * modes — `\"html\"` returns the raw body and never loads them. A bare\n * `catch` flips the flag to `false`; the curated install string surfaces\n * at use time via {@link WebToolError}, never a raw module-resolution\n * stack trace.\n */\nfunction loadReadability(): Promise<void> {\n  if (isReadabilityAvailable !== undefined) {\n    return Promise.resolve();\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      ReadabilitySdk = (await import(READABILITY_MODULE_ID)) as ReadabilityModuleLike;\n      JsdomSdk = (await import(JSDOM_MODULE_ID)) as JsdomModuleLike;\n      isReadabilityAvailable = true;\n    } catch {\n      isReadabilityAvailable = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Parse the input URL, rejecting anything unparseable or not over\n * `http`/`https` with a typed {@link WebToolError}.\n */\nfunction parseUrl(raw: string): URL {\n  let url: URL;\n\n  try {\n    url = new URL(raw);\n  } catch {\n    throw new WebToolError(`fetch_url received an unparseable URL: \"${raw}\".`, {\n      type: \"invalid-url\",\n    });\n  }\n\n  if (url.protocol !== \"http:\" && url.protocol !== \"https:\") {\n    throw new WebToolError(`fetch_url only supports http(s) URLs; got \"${url.protocol}\".`, {\n      type: \"invalid-url\",\n    });\n  }\n\n  return url;\n}\n\n/**\n * Enforce the host allowlist (an SSRF guardrail) before any network call.\n * When `allowHosts` is set, a request to a host not in it is rejected;\n * matching is exact on the URL hostname (case-insensitive).\n */\nfunction assertHostAllowed(url: URL, allowHosts?: string[]): void {\n  if (!allowHosts || allowHosts.length === 0) {\n    return;\n  }\n\n  const host = url.hostname.toLowerCase();\n  const allowed = allowHosts.some((entry) => entry.toLowerCase() === host);\n\n  if (!allowed) {\n    throw new WebToolError(\n      `fetch_url blocked host \"${url.hostname}\" — it is not in the allowHosts allowlist.`,\n      { type: \"denied-host\", context: { host: url.hostname } },\n    );\n  }\n}\n\n/**\n * Read the response body up to `maxBytes`, stopping early once the cap is\n * reached. Returns the decoded text and whether it was truncated. When\n * the body has no stream (a stubbed `Response`), falls back to `.text()`\n * and truncates the decoded string at `maxBytes`.\n */\nasync function readBody(\n  response: Response,\n  maxBytes: number,\n): Promise<{ body: string; truncated: boolean }> {\n  const stream = response.body;\n\n  if (!stream) {\n    const text = await response.text();\n\n    if (text.length > maxBytes) {\n      return { body: text.slice(0, maxBytes), truncated: true };\n    }\n\n    return { body: text, truncated: false };\n  }\n\n  const reader = stream.getReader();\n  const chunks: Uint8Array[] = [];\n  let received = 0;\n  let truncated = false;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n\n    if (done) {\n      break;\n    }\n\n    if (value) {\n      received += value.byteLength;\n      chunks.push(value);\n\n      if (received >= maxBytes) {\n        truncated = true;\n        await reader.cancel();\n        break;\n      }\n    }\n  }\n\n  const merged = new Uint8Array(received);\n  let offset = 0;\n\n  for (const chunk of chunks) {\n    merged.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n\n  const sliced = truncated ? merged.subarray(0, maxBytes) : merged;\n  const body = new TextDecoder().decode(sliced);\n\n  return { body, truncated };\n}\n\n/**\n * Render the fetched HTML into the configured `extract` mode. `\"html\"`\n * returns the raw body untouched; `\"text\"` and `\"markdown\"` run\n * `@mozilla/readability` over a `jsdom` document, throwing a curated\n * {@link WebToolError} when those optional peers are absent. `\"markdown\"`\n * applies a light heading/paragraph conversion over the extracted text.\n */\nasync function render(html: string, url: string, extract: FetchUrlExtract): Promise<string> {\n  if (extract === \"html\") {\n    return html;\n  }\n\n  await loadReadability();\n\n  if (!isReadabilityAvailable) {\n    throw new WebToolError(READABILITY_INSTALL_INSTRUCTIONS, { type: \"missing-peer\" });\n  }\n\n  const dom = new JsdomSdk.JSDOM(html, { url });\n  const article = new ReadabilitySdk.Readability(dom.window.document).parse();\n\n  if (extract === \"markdown\") {\n    return article?.content ? htmlToMarkdown(article.content) : (article?.textContent ?? \"\");\n  }\n\n  return article?.textContent ?? \"\";\n}\n\n/**\n * Minimal HTML→Markdown reduction for readability's extracted article\n * HTML — headings become `#` prefixes, paragraphs/line-breaks become\n * blank-line separated blocks, and remaining tags are stripped. This is a\n * pragmatic conversion, not a full CommonMark serializer.\n */\nfunction htmlToMarkdown(html: string): string {\n  return html\n    .replace(/<h([1-6])[^>]*>(.*?)<\\/h\\1>/gis, (_match, level: string, text: string) => {\n      const hashes = \"#\".repeat(Number(level));\n\n      return `\\n\\n${hashes} ${stripTags(text).trim()}\\n\\n`;\n    })\n    .replace(/<\\/(p|div|section|article|li)>/gi, \"\\n\\n\")\n    .replace(/<br\\s*\\/?>/gi, \"\\n\")\n    .replace(/<[^>]+>/g, \"\")\n    .replace(/\\n{3,}/g, \"\\n\\n\")\n    .trim();\n}\n\n/** Strip any remaining HTML tags from a fragment. */\nfunction stripTags(html: string): string {\n  return html.replace(/<[^>]+>/g, \"\");\n}\n\n/**\n * Build the agent-facing `fetch_url` tool — fetch a URL over the global\n * `fetch` (Node 18+) and hand the model back rendered `content`.\n *\n * Guardrails, applied in order before/around the network call:\n * - **Private-network deny (default).** Every request — and every\n *   redirect hop — goes through the framework's `guardedFetch` outbound\n *   policy, which refuses private / loopback / link-local /\n *   cloud-metadata addresses (and hostnames resolving to them) unless\n *   `allowPrivateNetwork: true` is set. This applies even when\n *   `allowHosts` is not configured, so a bare `ai.tools.fetchUrl()` is\n *   not an SSRF primitive.\n * - **`allowHosts`** — when set, a request to any host not in the list is\n *   rejected before the fetch, and redirect targets are held to the same\n *   allowlist.\n * - **`timeoutMs`** — the request is aborted via `AbortSignal.timeout`\n *   (default {@link DEFAULT_TIMEOUT_MS}).\n * - **`maxBytes`** — the response body is read up to this cap and the\n *   result flags `truncated` when it was cut off (default\n *   {@link DEFAULT_MAX_BYTES}).\n * - **`extract`** — `\"html\"` returns the raw body; `\"text\"` (default) and\n *   `\"markdown\"` run `@mozilla/readability` over `jsdom`, lazily imported\n *   so they stay OPTIONAL peers — a missing peer throws the curated\n *   install string.\n *\n * **Errors flow as data.** Every guardrail rejection and network failure\n * throws a typed {@link WebToolError}; the `tool()` wrapper catches it and\n * surfaces it in the returned `{ error }` field — `invoke()` never throws\n * — so the agent reads the failure and self-corrects.\n *\n * @param options - Tool-name override, byte cap, timeout, extract mode,\n *   and host allowlist.\n * @returns A `ToolContract<{ url }, FetchUrlResult>`.\n *\n * @example\n * const fetchUrl = fetchUrlTool({ extract: \"text\", allowHosts: [\"docs.stripe.com\"] });\n * const { data } = await fetchUrl.invoke({ url: \"https://docs.stripe.com/api\" });\n * console.log(data?.content, data?.truncated);\n */\nexport function fetchUrlTool(\n  options?: FetchUrlOptions,\n): ToolContract<FetchUrlInput, FetchUrlResult> {\n  const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;\n  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const extract = options?.extract ?? DEFAULT_EXTRACT;\n  const allowHosts = options?.allowHosts;\n  const allowPrivateNetwork = options?.allowPrivateNetwork ?? false;\n\n  // Warm the readability peers non-blockingly when the configured mode\n  // needs them, so the curated install string is ready (and logged at\n  // first use) without delaying construction.\n  if (extract !== \"html\") {\n    void loadReadability();\n  }\n\n  return tool<FetchUrlInput, FetchUrlResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Fetch a web page or document by URL and return its main content as \" +\n      \"text (readability-extracted), raw HTML, or Markdown. Use to read a \" +\n      \"specific page you already have the URL for.\",\n    input: inputSchema,\n    async execute(input) {\n      const url = parseUrl(input.url);\n      assertHostAllowed(url, allowHosts);\n\n      let response: Response;\n\n      try {\n        // The shared hardened outbound path: private-IP deny by default,\n        // per-hop redirect re-validation, timeout — never a raw fetch.\n        response = await guardedFetch(url.toString(), {\n          allowedSchemes: [\"http\", \"https\"],\n          hostAllowlist: allowHosts,\n          denyPrivateIPsAfterDNS: !allowPrivateNetwork,\n          timeoutMs,\n        });\n      } catch (cause) {\n        if (cause instanceof OutboundPolicyError) {\n          throw new WebToolError(`fetch_url blocked: ${cause.message}`, {\n            type: \"denied-host\",\n            cause,\n          });\n        }\n\n        const message = cause instanceof Error ? cause.message : String(cause);\n\n        throw new WebToolError(`fetch_url request failed: ${message}`, {\n          type: \"request-failed\",\n          cause,\n        });\n      }\n\n      const { body, truncated } = await readBody(response, maxBytes);\n      const content = await render(body, response.url || url.toString(), extract);\n\n      return {\n        url: response.url || url.toString(),\n        status: response.status,\n        content,\n        truncated,\n      };\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"fetch-url.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/web/fetch-url.ts"],"sourcesContent":["import { guardedFetch, OutboundPolicyError, tool, type ToolContract } from \"@warlock.js/ai\";\nimport type { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult } from \"../contracts\";\nimport { WebToolError } from \"../errors\";\nimport { objectSchema, stringField } from \"./schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"fetch_url\";\n\n/** Default hard cap on response bytes read before truncation. */\nconst DEFAULT_MAX_BYTES = 1_000_000;\n\n/** Default per-request timeout in milliseconds. */\nconst DEFAULT_TIMEOUT_MS = 15_000;\n\n/** Default rendering mode for the fetched document. */\nconst DEFAULT_EXTRACT: FetchUrlExtract = \"text\";\n\n/** Input schema: `{ url }`. */\nconst inputSchema = objectSchema<FetchUrlInput>({\n  url: stringField(),\n});\n\n// ============================================================\n// Lazily-loaded @mozilla/readability + jsdom (OPTIONAL peers)\n// ============================================================\n\n/**\n * Minimal structural shapes of the optional `@mozilla/readability` + `jsdom`\n * peers — only the members this file actually uses. Declared locally so the\n * package type-checks even when the peers are NOT installed (they are lazy\n * optional peers, loaded below via a `string` specifier so `tsc` never tries\n * to statically resolve them).\n */\ninterface ReadabilityArticleLike {\n  readonly content?: string | null;\n  readonly textContent?: string | null;\n}\ninterface ReadabilityInstanceLike {\n  parse(): ReadabilityArticleLike | null;\n}\ninterface ReadabilityModuleLike {\n  Readability: new (document: unknown) => ReadabilityInstanceLike;\n}\ninterface JsdomInstanceLike {\n  readonly window: { readonly document: unknown };\n}\ninterface JsdomModuleLike {\n  JSDOM: new (html: string, options?: { url?: string }) => JsdomInstanceLike;\n}\n\n// String specifiers typed `string` (not a literal) so `tsc` does not attempt\n// to resolve these optional peers at build time.\nconst READABILITY_MODULE_ID: string = \"@mozilla/readability\";\nconst JSDOM_MODULE_ID: string = \"jsdom\";\n\nlet ReadabilitySdk: ReadabilityModuleLike;\nlet JsdomSdk: JsdomModuleLike;\nlet isReadabilityAvailable: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\nconst READABILITY_INSTALL_INSTRUCTIONS = `\nThe fetch_url text/markdown extractor requires the @mozilla/readability and jsdom packages.\nInstall them with:\n\n  npm install @mozilla/readability jsdom\n\nOr with your preferred package manager:\n\n  pnpm add @mozilla/readability jsdom\n  yarn add @mozilla/readability jsdom\n`.trim();\n\n/**\n * Settle the lazy import of `@mozilla/readability` + `jsdom` once,\n * concurrency-safe. Only needed for the `\"text\"` / `\"markdown\"` extract\n * modes — `\"html\"` returns the raw body and never loads them. A bare\n * `catch` flips the flag to `false`; the curated install string surfaces\n * at use time via {@link WebToolError}, never a raw module-resolution\n * stack trace.\n */\nfunction loadReadability(): Promise<void> {\n  if (isReadabilityAvailable !== undefined) {\n    return Promise.resolve();\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      ReadabilitySdk = (await import(READABILITY_MODULE_ID)) as ReadabilityModuleLike;\n      JsdomSdk = (await import(JSDOM_MODULE_ID)) as JsdomModuleLike;\n      isReadabilityAvailable = true;\n    } catch {\n      isReadabilityAvailable = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Parse the input URL, rejecting anything unparseable or not over\n * `http`/`https` with a typed {@link WebToolError}.\n */\nfunction parseUrl(raw: string): URL {\n  let url: URL;\n\n  try {\n    url = new URL(raw);\n  } catch {\n    throw new WebToolError(`fetch_url received an unparseable URL: \"${raw}\".`, {\n      type: \"invalid-url\",\n    });\n  }\n\n  if (url.protocol !== \"http:\" && url.protocol !== \"https:\") {\n    throw new WebToolError(`fetch_url only supports http(s) URLs; got \"${url.protocol}\".`, {\n      type: \"invalid-url\",\n    });\n  }\n\n  return url;\n}\n\n/**\n * Enforce the host allowlist (an SSRF guardrail) before any network call.\n * When `allowHosts` is set, a request to a host not in it is rejected;\n * matching is exact on the URL hostname (case-insensitive).\n */\nfunction assertHostAllowed(url: URL, allowHosts?: string[]): void {\n  if (!allowHosts || allowHosts.length === 0) {\n    return;\n  }\n\n  const host = url.hostname.toLowerCase();\n  const allowed = allowHosts.some((entry) => entry.toLowerCase() === host);\n\n  if (!allowed) {\n    throw new WebToolError(\n      `fetch_url blocked host \"${url.hostname}\" — it is not in the allowHosts allowlist.`,\n      { type: \"denied-host\", context: { host: url.hostname } },\n    );\n  }\n}\n\n/**\n * Read the response body up to `maxBytes`, stopping early once the cap is\n * reached. Returns the decoded text and whether it was truncated. When\n * the body has no stream (a stubbed `Response`), falls back to `.text()`\n * and truncates the decoded string at `maxBytes`.\n */\nasync function readBody(\n  response: Response,\n  maxBytes: number,\n): Promise<{ body: string; truncated: boolean }> {\n  const stream = response.body;\n\n  if (!stream) {\n    const text = await response.text();\n\n    if (text.length > maxBytes) {\n      return { body: text.slice(0, maxBytes), truncated: true };\n    }\n\n    return { body: text, truncated: false };\n  }\n\n  const reader = stream.getReader();\n  const chunks: Uint8Array[] = [];\n  let received = 0;\n  let truncated = false;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n\n    if (done) {\n      break;\n    }\n\n    if (value) {\n      received += value.byteLength;\n      chunks.push(value);\n\n      if (received >= maxBytes) {\n        truncated = true;\n        await reader.cancel();\n        break;\n      }\n    }\n  }\n\n  const merged = new Uint8Array(received);\n  let offset = 0;\n\n  for (const chunk of chunks) {\n    merged.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n\n  const sliced = truncated ? merged.subarray(0, maxBytes) : merged;\n  const body = new TextDecoder().decode(sliced);\n\n  return { body, truncated };\n}\n\n/**\n * Render the fetched HTML into the configured `extract` mode. `\"html\"`\n * returns the raw body untouched; `\"text\"` and `\"markdown\"` run\n * `@mozilla/readability` over a `jsdom` document, throwing a curated\n * {@link WebToolError} when those optional peers are absent. `\"markdown\"`\n * applies a light heading/paragraph conversion over the extracted text.\n */\nasync function render(html: string, url: string, extract: FetchUrlExtract): Promise<string> {\n  if (extract === \"html\") {\n    return html;\n  }\n\n  await loadReadability();\n\n  if (!isReadabilityAvailable) {\n    throw new WebToolError(READABILITY_INSTALL_INSTRUCTIONS, { type: \"missing-peer\" });\n  }\n\n  const dom = new JsdomSdk.JSDOM(html, { url });\n  const article = new ReadabilitySdk.Readability(dom.window.document).parse();\n\n  if (extract === \"markdown\") {\n    return article?.content ? htmlToMarkdown(article.content) : (article?.textContent ?? \"\");\n  }\n\n  return article?.textContent ?? \"\";\n}\n\n/**\n * Minimal HTML→Markdown reduction for readability's extracted article\n * HTML — headings become `#` prefixes, paragraphs/line-breaks become\n * blank-line separated blocks, and remaining tags are stripped. This is a\n * pragmatic conversion, not a full CommonMark serializer.\n */\nfunction htmlToMarkdown(html: string): string {\n  return html\n    .replace(/<h([1-6])[^>]*>(.*?)<\\/h\\1>/gis, (_match, level: string, text: string) => {\n      const hashes = \"#\".repeat(Number(level));\n\n      return `\\n\\n${hashes} ${stripTags(text).trim()}\\n\\n`;\n    })\n    .replace(/<\\/(p|div|section|article|li)>/gi, \"\\n\\n\")\n    .replace(/<br\\s*\\/?>/gi, \"\\n\")\n    .replace(/<[^>]+>/g, \"\")\n    .replace(/\\n{3,}/g, \"\\n\\n\")\n    .trim();\n}\n\n/** Strip any remaining HTML tags from a fragment. */\nfunction stripTags(html: string): string {\n  return html.replace(/<[^>]+>/g, \"\");\n}\n\n/**\n * Build the agent-facing `fetch_url` tool — fetch a URL over the global\n * `fetch` (Node 18+) and hand the model back rendered `content`.\n *\n * Guardrails, applied in order before/around the network call:\n * - **Private-network deny (default).** Every request — and every\n *   redirect hop — goes through the framework's `guardedFetch` outbound\n *   policy, which refuses private / loopback / link-local /\n *   cloud-metadata addresses (and hostnames resolving to them) unless\n *   `allowPrivateNetwork: true` is set. This applies even when\n *   `allowHosts` is not configured, so a bare `ai.tools.fetchUrl()` is\n *   not an SSRF primitive.\n * - **`allowHosts`** — when set, a request to any host not in the list is\n *   rejected before the fetch, and redirect targets are held to the same\n *   allowlist.\n * - **`timeoutMs`** — the request is aborted via `AbortSignal.timeout`\n *   (default {@link DEFAULT_TIMEOUT_MS}).\n * - **`maxBytes`** — the response body is read up to this cap and the\n *   result flags `truncated` when it was cut off (default\n *   {@link DEFAULT_MAX_BYTES}).\n * - **`extract`** — `\"html\"` returns the raw body; `\"text\"` (default) and\n *   `\"markdown\"` run `@mozilla/readability` over `jsdom`, lazily imported\n *   so they stay OPTIONAL peers — a missing peer throws the curated\n *   install string.\n *\n * **Errors flow as data.** Every guardrail rejection and network failure\n * throws a typed {@link WebToolError}; the `tool()` wrapper catches it and\n * surfaces it in the returned `{ error }` field — `invoke()` never throws\n * — so the agent reads the failure and self-corrects.\n *\n * @param options - Tool-name override, byte cap, timeout, extract mode,\n *   and host allowlist.\n * @returns A `ToolContract<{ url }, FetchUrlResult>`.\n *\n * @example\n * const fetchUrl = fetchUrlTool({ extract: \"text\", allowHosts: [\"docs.stripe.com\"] });\n * const { data } = await fetchUrl.invoke({ url: \"https://docs.stripe.com/api\" });\n * console.log(data?.content, data?.truncated);\n */\nexport function fetchUrlTool(\n  options?: FetchUrlOptions,\n): ToolContract<FetchUrlInput, FetchUrlResult> {\n  const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;\n  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const extract = options?.extract ?? DEFAULT_EXTRACT;\n  const allowHosts = options?.allowHosts;\n  const allowPrivateNetwork = options?.allowPrivateNetwork ?? false;\n\n  // Warm the readability peers non-blockingly when the configured mode\n  // needs them, so the curated install string is ready (and logged at\n  // first use) without delaying construction.\n  if (extract !== \"html\") {\n    void loadReadability();\n  }\n\n  return tool<FetchUrlInput, FetchUrlResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Fetch a web page or document by URL and return its main content as \" +\n      \"text (readability-extracted), raw HTML, or Markdown. Use to read a \" +\n      \"specific page you already have the URL for.\",\n    input: inputSchema,\n    async execute(input) {\n      const url = parseUrl(input.url);\n      assertHostAllowed(url, allowHosts);\n\n      let response: Response;\n\n      try {\n        // The shared hardened outbound path: private-IP deny by default,\n        // per-hop redirect re-validation, timeout — never a raw fetch.\n        response = await guardedFetch(url.toString(), {\n          allowedSchemes: [\"http\", \"https\"],\n          hostAllowlist: allowHosts,\n          denyPrivateIPsAfterDNS: !allowPrivateNetwork,\n          timeoutMs,\n        });\n      } catch (cause) {\n        if (cause instanceof OutboundPolicyError) {\n          throw new WebToolError(`fetch_url blocked: ${cause.message}`, {\n            type: \"denied-host\",\n            cause,\n          });\n        }\n\n        const message = cause instanceof Error ? cause.message : String(cause);\n\n        throw new WebToolError(`fetch_url request failed: ${message}`, {\n          type: \"request-failed\",\n          cause,\n        });\n      }\n\n      const { body, truncated } = await readBody(response, maxBytes);\n      const content = await render(body, response.url || url.toString(), extract);\n\n      return {\n        url: response.url || url.toString(),\n        status: response.status,\n        content,\n        truncated,\n      };\n    },\n  });\n}\n"],"mappings":"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"}

package/esm/web/index.d.mts

@@ -1,2 +1,3 @@
 import { webSearchTool } from "./web-search.mjs";
-import { fetchUrlTool } from "./fetch-url.mjs";
+import { fetchUrlTool } from "./fetch-url.mjs";
+export { fetchUrlTool, webSearchTool };

package/esm/web/index.mjs

@@ -1,4 +1,4 @@
 import { fetchUrlTool } from "./fetch-url.mjs";
 import { webSearchTool } from "./web-search.mjs";
 
-export {  };
+export { fetchUrlTool, webSearchTool };

package/esm/web/web-search.d.mts

@@ -1,6 +1,6 @@
 import { WebSearchInput, WebSearchOptions, WebSearchResult } from "../contracts/web.type.mjs";
+import "../contracts/index.mjs";
 import { ToolContract } from "@warlock.js/ai";
-
 //#region ../../packages/ai-tools/src/web/web-search.d.ts
 /**
  * Build the agent-facing `web_search` tool over a {@link SearchProvider}.
@@ -32,7 +32,6 @@ import { ToolContract } from "@warlock.js/ai";
  * const { data } = await search.invoke({ query: "warlock.js ai tools" });
  * for (const hit of data?.results ?? []) console.log(hit.title, hit.url);
  */
-declare function webSearchTool(options: WebSearchOptions): ToolContract<WebSearchInput, WebSearchResult>;
+export declare function webSearchTool(options: WebSearchOptions): ToolContract<WebSearchInput, WebSearchResult>;
 //#endregion
-export { webSearchTool };
 //# sourceMappingURL=web-search.d.mts.map

package/esm/web/web-search.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"web-search.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/web/web-search.ts"],"mappings":";;;;;;;AAsNA;;;;;;;;;;;;;;;AAE+C;;;;;;;;;;;;iBAF/B,aAAA,CACd,OAAA,EAAS,gBAAA,GACR,YAAA,CAAa,cAAA,EAAgB,eAAA"}
+{"version":3,"file":"web-search.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/web/web-search.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAsNgB,cACd,SAAS,mBACR,aAAa,gBAAgB"}

package/esm/web/web-search.mjs

@@ -48,7 +48,8 @@ async function fetchJson(url, init, provider) {
 	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)}`, {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		throw new WebToolError(`web_search request to the "${provider}" provider failed: ${message}`, {
 			type: "request-failed",
 			cause
 		});
@@ -153,9 +154,7 @@ function webSearchTool(options) {
 				case "brave":
 					results = await searchBrave(input.query, limit, apiKey);
 					break;
-				case "serpapi":
-					results = await searchSerpApi(input.query, limit, apiKey);
-					break;
+				case "serpapi": results = await searchSerpApi(input.query, limit, apiKey);
 			}
 			return { results };
 		}