@warlock.js/ai-tools 4.5.0

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

@@ -0,0 +1,216 @@
+import { JsonSchemaTarget, ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/contracts/mcp.type.d.ts
+/**
+ * Type contracts for the Model Context Protocol surface — the
+ * `ai.mcp(server)` client and `ai.mcp.serve(source)` server. Pure
+ * declarations only; the factories live outside `contracts/`.
+ *
+ * **`type`, never `kind`.** MCP's own wire vocabulary uses `kind` in
+ * some content / capability descriptors. This package translates any
+ * inbound `kind` to `type` at the transport boundary and never emits
+ * `kind` from the types it owns — every discriminator below is `type`.
+ */
+/**
+ * How the MCP client reaches a server. Discriminated by `type`.
+ *
+ * - `"stdio"` — spawn `command` (+ `args`) as a child process and speak
+ *   JSON-RPC over its stdin/stdout (uses `node:child_process` +
+ *   `node:readline`; no dependency).
+ * - `"http"` — Streamable HTTP transport against `url`.
+ */
+type McpTransport = {
+  /** stdio transport — a spawned child process. */type: "stdio"; /** Executable to spawn (e.g. `"npx"`). */
+  command: string; /** Arguments passed to `command`. */
+  args?: string[];
+  /**
+   * Environment for the child. When omitted the process environment
+   * is NOT inherited — pass what the server needs explicitly.
+   */
+  env?: Record<string, string>;
+} | {
+  /** Streamable HTTP transport. */type: "http"; /** The server endpoint URL. */
+  url: string; /** Static headers sent with every request (e.g. auth). */
+  headers?: Record<string, string>;
+};
+/**
+ * Options for the `ai.mcp(server, options)` client (Direction A:
+ * external server → local agent tools).
+ */
+interface McpClientOptions {
+  /**
+   * Prefix prepended to each remote tool name to avoid colliding with
+   * local tools, e.g. `"github."`. The author owns uniqueness — there
+   * is no runtime collision guard.
+   */
+  namePrefix?: string;
+  /** Only adapt tools whose (unprefixed) name passes this filter. */
+  filter?: (toolName: string) => boolean;
+  /**
+   * Per-call timeout for `tools/call`, in milliseconds.
+   *
+   * @default 30_000
+   */
+  timeoutMs?: number;
+}
+/**
+ * The client handle returned by `ai.mcp(server, options)`.
+ */
+interface McpClient {
+  /**
+   * Lazily run the `initialize` handshake + `tools/list`, mapping each
+   * remote tool to a {@link ToolContract}. Cached after the first call.
+   */
+  tools(): Promise<ToolContract[]>;
+  /** Close the underlying transport (kills the child / ends the HTTP session). */
+  close(): Promise<void>;
+}
+/**
+ * A source of tools to expose via `ai.mcp.serve` — either an object that
+ * can enumerate its `ToolContract`s (a built agent / supervisor /
+ * orchestrator), or a literal array of contracts.
+ */
+type McpServeSource = {
+  tools(): ToolContract[];
+} | ToolContract[];
+/**
+ * Where an `ai.mcp.serve` server listens. Discriminated by `type`.
+ *
+ * - `"stdio"` — serve JSON-RPC over this process's stdin/stdout.
+ * - `"http"` — serve Streamable HTTP on `port`.
+ */
+type McpServeTransport = {
+  type: "stdio";
+} | {
+  type: "http";
+  port: number;
+};
+/**
+ * Options for `ai.mcp.serve(source, options)` (Direction B: local
+ * primitive → MCP server other clients can consume).
+ */
+interface McpServeOptions {
+  /** Server name advertised in the `initialize` response. */
+  name: string;
+  /**
+   * Server version advertised in `initialize`.
+   *
+   * @default the package version
+   */
+  version?: string;
+  /**
+   * Where to listen.
+   *
+   * @default { type: "stdio" }
+   */
+  transport?: McpServeTransport;
+  /**
+   * JSON-Schema dialect emitted for each tool's `inputSchema`. Defaults
+   * to a neutral MCP draft rather than `extractJsonSchema`'s own
+   * `"openai-strict"` default.
+   *
+   * @default "draft-2020-12"
+   */
+  schemaTarget?: JsonSchemaTarget;
+}
+/**
+ * A running `ai.mcp.serve` server.
+ */
+interface McpServer {
+  /** Begin accepting connections / reading the transport. */
+  start(): Promise<void>;
+  /** Stop serving and release the transport. */
+  stop(): Promise<void>;
+}
+/** The JSON-RPC version literal every message carries. */
+type JsonRpcVersion = "2.0";
+/** A JSON-RPC id — a string or number (we never send notifications with `null`). */
+type JsonRpcId = string | number;
+/**
+ * A JSON-RPC request: a method invocation that expects a response.
+ */
+interface JsonRpcRequest<TParams = unknown> {
+  jsonrpc: JsonRpcVersion;
+  id: JsonRpcId;
+  /** The RPC method name, e.g. `"tools/list"`. */
+  method: string;
+  /** Method parameters; shape is method-specific. */
+  params?: TParams;
+}
+/**
+ * A JSON-RPC notification: a method invocation with no response.
+ */
+interface JsonRpcNotification<TParams = unknown> {
+  jsonrpc: JsonRpcVersion;
+  /** The RPC method name. */
+  method: string;
+  /** Method parameters; shape is method-specific. */
+  params?: TParams;
+}
+/**
+ * A JSON-RPC error object, carried in an error response.
+ */
+interface JsonRpcError {
+  /** Numeric error code per the JSON-RPC spec. */
+  code: number;
+  /** Human-readable error message. */
+  message: string;
+  /** Optional structured error data. */
+  data?: unknown;
+}
+/**
+ * A JSON-RPC response — exactly one of `result` / `error` is present.
+ */
+interface JsonRpcResponse<TResult = unknown> {
+  jsonrpc: JsonRpcVersion;
+  id: JsonRpcId;
+  /** Present on success. */
+  result?: TResult;
+  /** Present on failure. */
+  error?: JsonRpcError;
+}
+/**
+ * Any inbound JSON-RPC message the transport may surface.
+ */
+type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+/**
+ * One tool descriptor as returned by an MCP server's `tools/list`. Its
+ * `inputSchema` is a JSON Schema object the client converts into a
+ * Standard Schema for the adapted {@link ToolContract}.
+ */
+interface McpToolDescriptor {
+  /** The remote tool's name (before any `namePrefix`). */
+  name: string;
+  /** Human-readable description forwarded to the LLM. */
+  description?: string;
+  /** JSON Schema for the tool's arguments. */
+  inputSchema?: Record<string, unknown>;
+}
+/**
+ * One content block in an MCP `tools/call` result. MCP's wire field is
+ * `type` here already (`"text"`, `"image"`, …); where a server uses
+ * `kind` for a content variant, the client maps it onto `type` so our
+ * shapes only ever expose `type`.
+ */
+interface McpContentBlock {
+  /** The content variant (`"text"`, `"image"`, `"resource"`, …). */
+  type: string;
+  /** Text payload, present for `type: "text"`. */
+  text?: string;
+  /** Any further variant-specific fields, left opaque. */
+  [extra: string]: unknown;
+}
+/**
+ * The `result` payload of an MCP `tools/call`. `isError: true` signals a
+ * tool-level failure the client rethrows so `tool()` wraps it as a
+ * {@link import("@warlock.js/ai").ToolExecutionError}.
+ */
+interface McpToolCallResult {
+  /** Ordered content blocks produced by the tool. */
+  content: McpContentBlock[];
+  /** True when the call represents a tool-level error. */
+  isError?: boolean;
+}
+//#endregion
+export { JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpClient, McpClientOptions, McpContentBlock, McpServeOptions, McpServeSource, McpServeTransport, McpServer, McpToolCallResult, McpToolDescriptor, McpTransport };
+//# sourceMappingURL=mcp.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/contracts/mcp.type.ts"],"mappings":";;;;;AAqBA;;;;;;;;;;;;;;AAoBsB;AAOtB;KA3BY,YAAA;mDAGN,IAAA,WA8BJ;EA5BI,OAAA,UA8BM;EA5BN,IAAA;EAkCK;AAAA;AAMX;;EAnCM,GAAA,GAAM,MAAA;AAAA;EAwCD,iCApCL,IAAA,UAsCY;EApCZ,GAAA,UAkCJ;EAhCI,OAAA,GAAU,MAAM;AAAA;;;;AAkCJ;UA3BD,gBAAA;EAmCS;;;;;EA7BxB,UAAA;EA+Bc;EA7Bd,MAAA,IAAU,QAAA;EAqCA;;;;;EA/BV,SAAA;AAAA;;AAiCsB;AAMxB;UAjCiB,SAAA;;;;;EAKf,KAAA,IAAS,OAAA,CAAQ,YAAA;EA0CL;EAxCZ,KAAA,IAAS,OAAA;AAAA;;AAgDsB;AAMjC;;;KA9CY,cAAA;EACN,KAAA,IAAS,YAAA;AAAA,IACX,YAAY;;;;AAgDC;AAYjB;;KApDY,iBAAA;EACN,IAAA;AAAA;EACA,IAAA;EAAc,IAAA;AAAA;;AAqDC;AAKrB;;UApDiB,eAAA;EAqDN;EAnDT,IAAA;EAwDS;;;;;EAlDT,OAAA;EA8CA;;;;;EAxCA,SAAA,GAAY,iBAAA;EA4CI;AAMlB;;;;;;EA1CE,YAAA,GAAe,gBAAgB;AAAA;;;;UAMhB,SAAA;EA+CA;EA7Cf,KAAA,IAAS,OAAA;;EAET,IAAA,IAAQ,OAAO;AAAA;;KAYL,cAAA;;KAGA,SAAA;AAwCZ;;;AAAA,UAnCiB,cAAA;EACf,OAAA,EAAS,cAAA;EACT,EAAA,EAAI,SAAA;EAuCI;EArCR,MAAA;EAqCoB;EAnCpB,MAAA,GAAS,OAAA;AAAA;;;;UAMM,mBAAA;EACf,OAAA,EAAS,cAAA;EA4BT;EA1BA,MAAA;EA0BoB;EAxBpB,MAAA,GAAS,OAAO;AAAA;;;;UAMD,YAAA;EA2Bb;EAzBF,IAAA;EAyBiB;EAvBjB,OAAA;EAsBE;EApBF,IAAA;AAAA;AAqBiB;AAOnB;;AAPmB,UAfF,eAAA;EACf,OAAA,EAAS,cAAA;EACT,EAAA,EAAI,SAAA;EAwBJ;EAtBA,MAAA,GAAS,OAAA;EAwBK;EAtBd,KAAA,GAAQ,YAAA;AAAA;AA+BV;;;AAAA,KAzBY,cAAA,GACR,cAAA,GACA,mBAAA,GACA,eAAA;;;;;AA4BY;UArBC,iBAAA;EA6BiB;EA3BhC,IAAA;EA6BwB;EA3BxB,WAAA;EA2BS;EAzBT,WAAA,GAAc,MAAM;AAAA;AA2Bb;;;;;;AAAA,UAlBQ,eAAA;;EAEf,IAAA;;EAEA,IAAA;;GAEC,KAAA;AAAA;;;;;;UAQc,iBAAA;;EAEf,OAAA,EAAS,eAAe;;EAExB,OAAA;AAAA"}

package/esm/contracts/utility.type.d.mts

@@ -0,0 +1,96 @@
+//#region ../@warlock.js/ai-tools/src/contracts/utility.type.d.ts
+/**
+ * Type contracts for the utility tools — `ai.tools.calculator` and
+ * `ai.tools.dateTime`. Pure declarations only; the factories live
+ * outside `contracts/`.
+ */
+/**
+ * Construction options for `ai.tools.calculator`.
+ */
+interface CalculatorOptions {
+  /**
+   * Override the tool name exposed to the LLM.
+   *
+   * @default "calculator"
+   */
+  name?: string;
+}
+/**
+ * The validated input shape the model passes to `calculator`.
+ */
+interface CalculatorInput {
+  /** An arithmetic expression to evaluate, e.g. `"(3 + 4) * 2"`. */
+  expression: string;
+}
+/**
+ * The `calculator` tool's output.
+ */
+interface CalculatorResult {
+  /** The numeric result of evaluating the expression. */
+  result: number;
+}
+/**
+ * The operations `ai.tools.dateTime` can perform.
+ *
+ * - `"now"` — current date-time, optionally in a given time zone.
+ * - `"add"` — add `amount` of `unit` to `iso`.
+ * - `"diff"` — difference between two instants, in `unit`.
+ * - `"format"` — render `iso` per `format`.
+ */
+type DateTimeOp = "now" | "add" | "diff" | "format";
+/**
+ * Construction options for `ai.tools.dateTime`.
+ */
+interface DateTimeOptions {
+  /**
+   * Override the tool name exposed to the LLM.
+   *
+   * @default "date_time"
+   */
+  name?: string;
+  /**
+   * Default IANA time zone applied when a call omits `timeZone`
+   * (e.g. `"UTC"`, `"Africa/Cairo"`). When unset, the host time zone
+   * is used.
+   */
+  defaultTimeZone?: string;
+}
+/**
+ * The validated input shape the model passes to `date_time`. Which
+ * fields are required depends on `op` (validated at the seal layer).
+ */
+interface DateTimeInput {
+  /** Which date-time operation to perform. */
+  op: DateTimeOp;
+  /** ISO-8601 instant the operation acts on (`add` / `diff` / `format`). */
+  iso?: string;
+  /**
+   * Start instant for `diff`, accepted as an alias for `iso` — models
+   * naturally pass `from` / `to` for a difference. When both are set, `iso`
+   * wins.
+   */
+  from?: string;
+  /** Second ISO-8601 instant for `diff`. */
+  to?: string;
+  /** Signed magnitude for `add`. */
+  amount?: number;
+  /** Unit for `add` / `diff`, e.g. `"days"`, `"hours"`, `"minutes"`. */
+  unit?: string;
+  /** IANA time zone override for this call. */
+  timeZone?: string;
+  /** Output format string for `format` (and the rendered `now`). */
+  format?: string;
+}
+/**
+ * The `date_time` tool's output.
+ */
+interface DateTimeResult {
+  /**
+   * The result, rendered as a string — an ISO instant, a formatted
+   * date, or a stringified numeric difference depending on `op`.
+   */
+  value: string;
+}
+//#endregion
+export { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOp, DateTimeOptions, DateTimeResult };
+//# sourceMappingURL=utility.type.d.mts.map

package/esm/contracts/utility.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utility.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/contracts/utility.type.ts"],"mappings":";;AASA;;;;AAMM;AAMN;;AANM,UANW,iBAAA;EAcL;AAAA;AAMZ;;;EAdE,IAAI;AAAA;AA2BN;;;AAAA,UArBiB,eAAA;EAqBK;EAnBpB,UAAU;AAAA;;;AAoCK;UA9BA,gBAAA;EAqCa;EAnC5B,MAAM;AAAA;;;;;;;;;KAWI,UAAA;;AA4CJ;AAMR;UA7CiB,eAAA;;;AAkDV;;;EA5CL,IAAA;;;;;;EAMA,eAAe;AAAA;;;;;UAOA,aAAA;;EAEf,EAAA,EAAI,UAAU;;EAEd,GAAA;;;;;;EAMA,IAAA;;EAEA,EAAA;;EAEA,MAAA;;EAEA,IAAA;;EAEA,QAAA;;EAEA,MAAA;AAAA;;;;UAMe,cAAA;;;;;EAKf,KAAK;AAAA"}

package/esm/contracts/web.type.d.mts

@@ -0,0 +1,136 @@
+//#region ../@warlock.js/ai-tools/src/contracts/web.type.d.ts
+/**
+ * Type contracts for the web tools — `ai.tools.webSearch` and
+ * `ai.tools.fetchUrl`. Pure declarations only; the factories live
+ * outside `contracts/`.
+ */
+/**
+ * Which optional search backend `ai.tools.webSearch` drives. The chosen
+ * provider's SDK / HTTP key is a lazily-imported optional peer, so an
+ * agent that never searches the web pulls in none of them.
+ *
+ * Uses `type` as the discriminator everywhere downstream — never `kind`.
+ */
+type SearchProvider = "tavily" | "brave" | "serpapi";
+/**
+ * Construction options for {@link SearchProvider}-backed web search.
+ */
+interface WebSearchOptions {
+  /** Which optional search backend to use. Its SDK/HTTP key is a lazy peer. */
+  provider: SearchProvider;
+  /**
+   * API key for the provider. Falls back to a provider-specific
+   * environment variable (e.g. `TAVILY_API_KEY`) when omitted.
+   */
+  apiKey?: string;
+  /**
+   * Default maximum results per call. The model may request fewer (or
+   * more, clamped into `[1, maxResults]`) via the tool input.
+   *
+   * @default 5
+   */
+  maxResults?: number;
+  /**
+   * Override the tool name exposed to the LLM.
+   *
+   * @default "web_search"
+   */
+  name?: string;
+}
+/**
+ * The validated input shape the model passes to the web-search tool.
+ */
+interface WebSearchInput {
+  /** The search query. */
+  query: string;
+  /** Per-call cap on results, clamped into `[1, options.maxResults]`. */
+  maxResults?: number;
+}
+/**
+ * A single web-search hit. `score` is provider-supplied relevance when
+ * the backend returns one (Tavily does; some others do not).
+ */
+interface WebSearchResultItem {
+  /** Page / document title. */
+  title: string;
+  /** Canonical URL of the result. */
+  url: string;
+  /** Short LLM-ready extract / snippet. */
+  snippet: string;
+  /** Provider relevance score, when available. */
+  score?: number;
+}
+/**
+ * The web-search tool's output — the ranked list of hits.
+ */
+interface WebSearchResult {
+  /** Ranked results, best-first. */
+  results: WebSearchResultItem[];
+}
+/**
+ * How `fetch_url` should render the fetched document into the `content`
+ * string handed back to the model.
+ *
+ * - `"text"` — readability-extracted main text (the default; needs the
+ *   `@mozilla/readability` + `jsdom` optional peers).
+ * - `"html"` — the raw response body, untouched.
+ * - `"markdown"` — readability extraction converted to Markdown.
+ */
+type FetchUrlExtract = "text" | "html" | "markdown";
+/**
+ * Construction options for `ai.tools.fetchUrl`.
+ */
+interface FetchUrlOptions {
+  /**
+   * Override the tool name exposed to the LLM.
+   *
+   * @default "fetch_url"
+   */
+  name?: string;
+  /**
+   * Hard cap on the number of response bytes read before truncation.
+   *
+   * @default 1_000_000
+   */
+  maxBytes?: number;
+  /**
+   * Per-request timeout in milliseconds.
+   *
+   * @default 15_000
+   */
+  timeoutMs?: number;
+  /**
+   * How to render the fetched document.
+   *
+   * @default "text"
+   */
+  extract?: FetchUrlExtract;
+  /**
+   * Host allowlist. When set, any request to a host not in this list is
+   * rejected before the network call (an SSRF guardrail).
+   */
+  allowHosts?: string[];
+}
+/**
+ * The validated input shape the model passes to `fetch_url`.
+ */
+interface FetchUrlInput {
+  /** The absolute URL to fetch. */
+  url: string;
+}
+/**
+ * The `fetch_url` tool's output.
+ */
+interface FetchUrlResult {
+  /** The URL that was fetched (after any redirects the platform followed). */
+  url: string;
+  /** HTTP status code of the final response. */
+  status: number;
+  /** The rendered content per the configured `extract` mode. */
+  content: string;
+  /** True when `content` was cut off at `maxBytes`. */
+  truncated: boolean;
+}
+//#endregion
+export { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, SearchProvider, WebSearchInput, WebSearchOptions, WebSearchResult, WebSearchResultItem };
+//# sourceMappingURL=web.type.d.mts.map

package/esm/contracts/web.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/contracts/web.type.ts"],"mappings":";;AAaA;;;;AAA0B;AAK1B;;;;;;AAL0B,KAAd,cAAA;;;;UAKK,gBAAA;EA0BA;EAxBf,QAAA,EAAU,cAAc;;;AA4Bd;AAOZ;EA9BE,MAAA;;;;;;;EAOA,UAAA;EA+BK;AAMP;;;;EA/BE,IAAA;AAAA;;;;UAMe,cAAA;EA4CA;EA1Cf,KAAA;;EAEA,UAAU;AAAA;;;;;UAOK,mBAAA;EA8DL;EA5DV,KAAA;EAkEe;EAhEf,GAAA;;EAEA,OAAA;EAgEG;EA9DH,KAAA;AAAA;;;;UAMe,eAAA;EAoEf;EAlEA,OAAA,EAAS,mBAAmB;AAAA;AAoEnB;;;;;;;;;AAAA,KAxDC,eAAA;;;;UAKK,eAAA;;;;;;EAMf,IAAA;;;;;;EAMA,QAAA;;;;;;EAMA,SAAA;;;;;;EAMA,OAAA,GAAU,eAAe;;;;;EAKzB,UAAA;AAAA;;;;UAMe,aAAA;;EAEf,GAAG;AAAA;;;;UAMY,cAAA;;EAEf,GAAA;;EAEA,MAAA;;EAEA,OAAA;;EAEA,SAAA;AAAA"}

package/esm/errors.d.mts

@@ -0,0 +1,225 @@
+import { AIError, AIErrorOptions } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/errors.d.ts
+/**
+ * Why the calculator rejected an expression.
+ *
+ * - `"syntax"` — the expression could not be tokenized or parsed
+ *   (an unknown character, a misplaced operator, unbalanced parens).
+ * - `"divide-by-zero"` — evaluation divided (or took a modulo) by zero.
+ * - `"overflow"` — the computed result was not a finite number.
+ */
+type CalculatorFailure = "syntax" | "divide-by-zero" | "overflow";
+/**
+ * Options for {@link CalculatorError} — the structured `type`
+ * discriminator so a caller can branch without parsing the message.
+ */
+type CalculatorErrorOptions = AIErrorOptions & {
+  /** Which class of calculator failure occurred. */type: CalculatorFailure;
+};
+/**
+ * The `calculator` tool could not evaluate an expression — it was not
+ * valid arithmetic, divided by zero, or overflowed to a non-finite
+ * value.
+ *
+ * **Surface.** Thrown inside the tool handler, where `tool()` wraps it
+ * into a `ToolExecutionError` whose message is preserved verbatim and
+ * reaches the model as `{ error }` data, so the agent self-corrects
+ * rather than crashing. Extends the framework {@link AIError} (category
+ * `"tool"` via code `TOOL_EXEC_FAILED`) so it flows through the same
+ * typed error contract as every other AI error; branch on `error.type`
+ * for the specific failure.
+ *
+ * @example
+ * if (error instanceof CalculatorError && error.type === "divide-by-zero") {
+ *   // the expression divided by zero — ask the model to revise it
+ * }
+ */
+declare class CalculatorError extends AIError {
+  /** Which class of calculator failure occurred. */
+  readonly type: CalculatorFailure;
+  constructor(message: string, options: CalculatorErrorOptions);
+}
+/**
+ * Why the date-time tool rejected a call.
+ *
+ * - `"invalid-input"` — a required field for the chosen `op` was
+ *   missing or malformed (an unparsable ISO instant, a bad `amount`).
+ * - `"invalid-unit"` — `unit` was not one of the supported units.
+ * - `"invalid-time-zone"` — the IANA time zone was not recognized.
+ * - `"unsupported-op"` — the `op` was not one this tool implements.
+ */
+type DateTimeFailure = "invalid-input" | "invalid-unit" | "invalid-time-zone" | "unsupported-op";
+/**
+ * Options for {@link DateTimeError} — the structured `type`
+ * discriminator so a caller can branch without parsing the message.
+ */
+type DateTimeErrorOptions = AIErrorOptions & {
+  /** Which class of date-time failure occurred. */type: DateTimeFailure;
+};
+/**
+ * The `date_time` tool could not complete a call — a required field was
+ * missing or malformed, the unit/time zone was unrecognized, or the
+ * operation is unsupported.
+ *
+ * **Surface.** Thrown inside the tool handler, where `tool()` wraps it
+ * into a `ToolExecutionError` whose message reaches the model as
+ * `{ error }` data so the agent self-corrects. Extends the framework
+ * {@link AIError} (category `"tool"` via code `TOOL_EXEC_FAILED`); branch
+ * on `error.type` for the specific failure.
+ *
+ * @example
+ * if (error instanceof DateTimeError && error.type === "invalid-unit") {
+ *   // the model passed an unknown unit — re-prompt with the allowed set
+ * }
+ */
+declare class DateTimeError extends AIError {
+  /** Which class of date-time failure occurred. */
+  readonly type: DateTimeFailure;
+  constructor(message: string, options: DateTimeErrorOptions);
+}
+/**
+ * Why an MCP transport operation failed.
+ *
+ * - `"connect"` — the transport could not be opened (child process
+ *   failed to spawn, HTTP endpoint unreachable) or the `initialize`
+ *   handshake failed.
+ * - `"protocol"` — a malformed / unexpected JSON-RPC message, a
+ *   response that matched no in-flight request, or a missing field.
+ * - `"timeout"` — a request exceeded its per-call deadline.
+ * - `"closed"` — the transport was used after it was closed, or the
+ *   peer closed it mid-call.
+ */
+type McpTransportFailure = "connect" | "protocol" | "timeout" | "closed";
+/**
+ * Options for {@link McpTransportError} — the structured `type`
+ * discriminator plus an optional JSON-RPC method name for branchable
+ * diagnostics without parsing the message.
+ */
+type McpTransportErrorOptions = AIErrorOptions & {
+  /** Which class of transport failure occurred. */type: McpTransportFailure; /** The JSON-RPC method in flight when the failure occurred, if any. */
+  method?: string;
+};
+/**
+ * The MCP client's transport layer failed — it could not connect, the
+ * peer spoke malformed JSON-RPC, a call timed out, or the transport was
+ * already closed.
+ *
+ * **Surface.** Connection / handshake failures surface at
+ * agent-construction time (the caller `await`s `client.tools()`). A
+ * `tools/call` failure raised mid-run is wrapped by `tool()` into a
+ * `ToolExecutionError` and reaches the model as `{ error }` data, so the
+ * agent self-corrects rather than crashing. Extends the framework
+ * {@link AIError} (category `"tool"`, code `TOOL_EXEC_FAILED`) so it
+ * flows through the same typed error contract as every other AI error;
+ * branch on `error.type` for the specific failure.
+ *
+ * @example
+ * if (error instanceof McpTransportError && error.type === "timeout") {
+ *   // the remote call exceeded its deadline — retry or escalate
+ * }
+ */
+declare class McpTransportError extends AIError {
+  /** Which class of transport failure occurred. */
+  readonly type: McpTransportFailure;
+  /** The JSON-RPC method in flight when the failure occurred, if any. */
+  readonly method?: string;
+  constructor(message: string, options: McpTransportErrorOptions);
+}
+/**
+ * Why a web tool (`ai.tools.webSearch` / `ai.tools.fetchUrl`) failed
+ * before or during a network call.
+ *
+ * - `"missing-peer"` — an optional peer dependency the chosen mode needs
+ *   (`@mozilla/readability` + `jsdom` for text/markdown extraction, a
+ *   search provider SDK) is not installed. The message carries a curated
+ *   `npm install` string for the developer.
+ * - `"missing-key"` — no API key was supplied via options or the
+ *   provider's environment variable.
+ * - `"denied-host"` — the requested URL's host is not in the configured
+ *   `allowHosts` allowlist (an SSRF guardrail), rejected before any fetch.
+ * - `"invalid-url"` — the supplied URL could not be parsed, or used a
+ *   non-`http(s)` scheme.
+ * - `"request-failed"` — the network call itself failed (DNS, connection
+ *   reset, timeout) or the provider returned a non-OK status.
+ */
+type WebToolFailure = "missing-peer" | "missing-key" | "denied-host" | "invalid-url" | "request-failed";
+/**
+ * Options for {@link WebToolError} — the structured `type` discriminator
+ * so a caller can branch without parsing the message.
+ */
+type WebToolErrorOptions = AIErrorOptions & {
+  /** Which class of web-tool failure occurred. */type: WebToolFailure;
+};
+/**
+ * A web tool failed — a missing optional peer, an absent API key, a host
+ * rejected by the `allowHosts` guardrail, an unparseable URL, or a failed
+ * network call.
+ *
+ * **Surface.** Thrown from inside a tool's `execute`, so the framework's
+ * `tool()` wrapper catches it and surfaces it in the returned `{ error }`
+ * field (`invoke()` never throws) — the agent reads the failure as data
+ * and self-corrects rather than crashing. Extends the framework
+ * {@link AIError} (category `"tool"` via code `TOOL_EXEC_FAILED`) so it
+ * flows through the same typed error contract as every other AI error;
+ * branch on `error.type` for the specific failure.
+ *
+ * @example
+ * const { error } = await fetchTool.invoke({ url: "http://evil.test" });
+ * if (error instanceof WebToolError && error.type === "denied-host") {
+ *   // the host was not in allowHosts — surfaced before any network call
+ * }
+ */
+declare class WebToolError extends AIError {
+  /** Which class of web-tool failure occurred. */
+  readonly type: WebToolFailure;
+  constructor(message: string, options: WebToolErrorOptions);
+}
+/**
+ * Why an `http_request` call was rejected by its own guardrails, before
+ * the network request was ever issued.
+ *
+ * - `"method-not-allowed"` — the model requested an HTTP method that is
+ *   not on the tool's `allowMethods` allowlist (defaults to `["GET"]`).
+ * - `"host-not-allowed"` — the resolved request host is not on the
+ *   tool's `allowHosts` allowlist (an SSRF guardrail).
+ * - `"invalid-url"` — the supplied URL (or its join with `baseUrl`)
+ *   could not be parsed into an absolute `http(s)` URL.
+ */
+type HttpPolicyFailure = "method-not-allowed" | "host-not-allowed" | "invalid-url";
+/**
+ * Options for {@link HttpPolicyError} — the structured `type`
+ * discriminator so a caller can branch without parsing the message.
+ */
+type HttpPolicyErrorOptions = AIErrorOptions & {
+  /** Which class of policy rejection occurred. */type: HttpPolicyFailure;
+};
+/**
+ * The `http_request` tool refused a call its construction-time policy
+ * does not permit — a disallowed method, a host outside the allowlist,
+ * or an unparseable URL. The rejection happens *before* any network
+ * request, so a guarded tool can never be coaxed into reaching an
+ * off-allowlist host (an SSRF guardrail).
+ *
+ * **Surface.** Thrown from inside the tool's `execute`, so the framework's
+ * `tool()` wrapper catches it and surfaces it in the returned `{ error }`
+ * field (`invoke()` never throws) — the agent reads the typed failure as
+ * data and self-corrects rather than crashing. Extends the framework
+ * {@link AIError} (category `"tool"` via code `TOOL_EXEC_FAILED`) so it
+ * flows through the same typed error contract as every other AI error;
+ * branch on `error.type` for the specific failure.
+ *
+ * @example
+ * const { error } = await httpTool.invoke({ url: "https://evil.test" });
+ * if (error instanceof HttpPolicyError && error.type === "host-not-allowed") {
+ *   // the model tried to reach a host outside the configured allowlist
+ * }
+ */
+declare class HttpPolicyError extends AIError {
+  /** Which class of policy rejection occurred. */
+  readonly type: HttpPolicyFailure;
+  constructor(message: string, options: HttpPolicyErrorOptions);
+}
+//#endregion
+export { CalculatorError, CalculatorErrorOptions, CalculatorFailure, DateTimeError, DateTimeErrorOptions, DateTimeFailure, HttpPolicyError, HttpPolicyErrorOptions, HttpPolicyFailure, McpTransportError, McpTransportErrorOptions, McpTransportFailure, WebToolError, WebToolErrorOptions, WebToolFailure };
+//# sourceMappingURL=errors.d.mts.map