@warlock.js/ai-tools 5.30.0 → 5.32.0

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

@@ -8,13 +8,13 @@
  * default policy allows only `"GET"`; mutating methods are opt-in via
  * {@link HttpRequestOptions.allowMethods}.
  */
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /**
  * Construction options for `ai.tools.http`. These bound what the model
  * is allowed to do — the model supplies the per-call URL / method /
  * body within these rails.
  */
-interface HttpRequestOptions {
+export interface HttpRequestOptions {
   /**
    * Override the tool name exposed to the LLM.
    *
@@ -68,7 +68,7 @@ interface HttpRequestOptions {
 /**
  * The validated input shape the model passes to `http_request`.
  */
-interface HttpRequestInput {
+export interface HttpRequestInput {
   /**
    * HTTP method. Must be one of {@link HttpRequestOptions.allowMethods}
    * (defaults to `"GET"` when omitted).
@@ -90,7 +90,7 @@ interface HttpRequestInput {
 /**
  * The `http_request` tool's output.
  */
-interface HttpRequestResult {
+export interface HttpRequestResult {
   /** HTTP status code of the response. */
   status: number;
   /** Response headers, lower-cased keys. */
@@ -104,5 +104,4 @@ interface HttpRequestResult {
   truncated: boolean;
 }
 //#endregion
-export { HttpMethod, HttpRequestInput, HttpRequestOptions, HttpRequestResult };
 //# sourceMappingURL=http.type.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"http.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/http.type.ts"],"mappings":";;AAUA;;;;AAAsB;AAOtB;;;KAPY,UAAA;;;;;;UAOK,kBAAA;EAqCf;;;;;EA/BA,IAAA;EAiDe;;;;EA5Cf,OAAA;EAiDS;;;;;;EA1CT,YAAA,GAAe,UAAA;EA4DA;;;;;EAtDf,UAAA;EA0DS;;;;AAOA;;;;;;EAtDT,mBAAA;;EAEA,OAAA,GAAU,MAAM;;;;;;EAMhB,SAAA;;;;;;EAMA,QAAA;AAAA;;;;UAMe,gBAAA;;;;;EAKf,MAAA,GAAS,UAAA;;;;;EAKT,GAAA;;EAEA,OAAA,GAAU,MAAM;;;;;EAKhB,IAAA;AAAA;;;;UAMe,iBAAA;;EAEf,MAAA;;EAEA,OAAA,EAAS,MAAM;;;;;EAKf,IAAA;;EAEA,SAAA;AAAA"}
+{"version":3,"file":"http.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/http.type.ts"],"mappings":";;;;;;;;;;YAUY;;;;;;iBAOK;;;;;;EAMf;;;;;EAKA;;;;;;;EAOA,eAAe;;;;;;EAMf;;;;;;;;;;;EAWA;;EAEA,UAAU;;;;;;EAMV;;;;;;EAMA;;;;;iBAMe;;;;;EAKf,SAAS;;;;;EAKT;;EAEA,UAAU;;;;;EAKV;;;;;iBAMe;;EAEf;;EAEA,SAAS;;;;;EAKT;;EAEA"}

package/esm/contracts/index.d.mts

@@ -1,4 +1,6 @@
 import { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, SearchProvider, WebSearchInput, WebSearchOptions, WebSearchResult, WebSearchResultItem } from "./web.type.mjs";
 import { HttpMethod, HttpRequestInput, HttpRequestOptions, HttpRequestResult } from "./http.type.mjs";
 import { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOp, DateTimeOptions, DateTimeResult } from "./utility.type.mjs";
-import { JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpClient, McpClientOptions, McpContentBlock, McpServeOptions, McpServeSource, McpServeTransport, McpServer, McpToolCallResult, McpToolDescriptor, McpTransport } from "./mcp.type.mjs";
+import { JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpClient, McpClientOptions, McpContentBlock, McpToolCallResult, McpToolDescriptor, McpTransport } from "./mcp.type.mjs";
+import { McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpServeHandle, McpHttpServeTransport, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeTransport, McpServer, McpToolSource } from "./mcp-serve.type.mjs";
+export type { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOp, DateTimeOptions, DateTimeResult, FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, HttpMethod, HttpRequestInput, HttpRequestOptions, HttpRequestResult, JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpClient, McpClientOptions, McpContentBlock, McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpServeHandle, McpHttpServeTransport, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeTransport, McpServer, McpToolCallResult, McpToolDescriptor, McpToolSource, McpTransport, SearchProvider, WebSearchInput, WebSearchOptions, WebSearchResult, WebSearchResultItem };

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

@@ -0,0 +1,285 @@
+import { McpContentBlock } from "./mcp.type.mjs";
+import { JsonSchemaTarget, ToolContract, ToolRequestContext } from "@warlock.js/ai";
+//#region ../../packages/ai-tools/src/contracts/mcp-serve.type.d.ts
+/**
+ * Type contracts for `ai.mcp.serve(source, options)` — exposing local
+ * tools (plus optional resources and prompts) AS a Model Context Protocol
+ * server over stdio or Streamable HTTP. Pure declarations only; the
+ * factories live in `../mcp/serve.ts` and `../mcp/serve-http.ts`.
+ */
+/**
+ * One set of tools: an object that can enumerate its `ToolContract`s (a
+ * built agent / supervisor / orchestrator / workspace), or a literal array.
+ */
+export type McpToolSource = {
+  tools(): ToolContract[];
+} | ToolContract[];
+/**
+ * Several named tool sets served by one server. Each key names a group;
+ * with `prefixToolNames` the group name is prepended to its tools' names
+ * so equal names from different groups stay distinct.
+ *
+ * @example
+ * { groups: { github: githubAgent, files: [readFile, writeFile] } }
+ */
+export type McpGroupedToolSource = {
+  /** Tool sets keyed by group name. */
+  groups: Record<string, McpToolSource>;
+};
+/**
+ * What `ai.mcp.serve` exposes as tools — one tool set, or several named
+ * groups. Every exposed tool name must be unique: a duplicate throws an
+ * {@link import("../errors").McpServeError} (`type: "collision"`) when
+ * `serve()` is called.
+ */
+export type McpServeSource = McpToolSource | McpGroupedToolSource;
+/**
+ * Normalised metadata of an inbound HTTP request, handed to a custom
+ * {@link McpHttpAuth.authorize} hook. Tools receive the same headers on
+ * `ctx.request` (see `ToolRequestContext` in `@warlock.js/ai`).
+ */
+export type McpHttpRequestInfo = ToolRequestContext & {
+  /** The HTTP method, upper-case (`"POST"`, `"GET"`, …). */
+  method: string;
+  /** The request path, without the query string. */
+  path: string;
+};
+/**
+ * Authentication for an HTTP-served MCP endpoint. At least one of
+ * `bearer` / `authorize` is required; when both are set, a request must
+ * pass both. A request that fails gets HTTP 401 before its body is read.
+ */
+export type McpHttpAuth = {
+  /**
+   * Accepted bearer token(s), matched against
+   * `Authorization: Bearer <token>`. Compared in constant time over
+   * SHA-256 digests, so neither the token's content nor its length leaks
+   * through response timing. Several tokens allow rotation without
+   * downtime. Empty strings are rejected when the server starts.
+   */
+  bearer?: string | readonly string[];
+  /**
+   * Custom check run for every request (after `bearer`, when both are
+   * set). Return `true` to allow. A hook that throws or rejects denies the
+   * request (fails closed).
+   */
+  authorize?: (request: McpHttpRequestInfo) => boolean | Promise<boolean>;
+};
+/**
+ * Serve over the MCP Streamable HTTP transport.
+ *
+ * Binds `127.0.0.1` by default. Binding any non-loopback address
+ * requires `auth`; `start()` throws otherwise.
+ */
+export type McpHttpServeTransport = {
+  /** Streamable HTTP transport. */
+  type: "http";
+  /**
+   * Interface to bind. Loopback (`127.0.0.1`, `::1`, `localhost`) needs
+   * no auth; anything else (`0.0.0.0`, a LAN address) requires `auth`.
+   *
+   * @default "127.0.0.1"
+   */
+  host?: string;
+  /**
+   * Port to bind. `0` picks a free ephemeral port; read the result from
+   * the `url` that `start()` resolves.
+   *
+   * @default 0
+   */
+  port?: number;
+  /**
+   * The single MCP endpoint path. Other paths answer 404.
+   *
+   * @default "/mcp"
+   */
+  path?: string;
+  /** Bearer token(s) and/or a custom authorize hook. Required off loopback. */
+  auth?: McpHttpAuth;
+  /**
+   * Extra browser origins allowed to call the endpoint, as full origins
+   * (`"https://app.example.com"`). Loopback origins (`http://localhost:*`,
+   * `http://127.0.0.1:*`, `http://[::1]:*`) are always allowed; any other
+   * `Origin` header is refused with 403, which blocks DNS-rebinding
+   * attacks from web pages. Requests without an `Origin` header (non-browser
+   * clients) are unaffected.
+   */
+  allowedOrigins?: readonly string[];
+  /**
+   * Extra `Host` header names accepted while bound to loopback (where only
+   * `localhost`, `127.0.0.1` and `[::1]` are accepted by default — the
+   * second DNS-rebinding guard). When bound off loopback, setting this
+   * restricts `Host` to exactly these names.
+   */
+  allowedHosts?: readonly string[];
+  /**
+   * Maximum accepted request body, in bytes. Larger bodies get 413.
+   *
+   * @default 1_048_576 (1 MiB)
+   */
+  maxBodyBytes?: number;
+  /**
+   * How long `close()` waits for in-flight requests to finish before it
+   * aborts their `ctx.signal` and destroys the remaining connections.
+   *
+   * @default 5_000
+   */
+  drainTimeoutMs?: number;
+};
+/**
+ * Where an `ai.mcp.serve` server listens. Discriminated by `type`.
+ *
+ * - `"stdio"` — serve JSON-RPC over this process's stdin/stdout.
+ * - `"http"` — serve MCP Streamable HTTP (see {@link McpHttpServeTransport}).
+ */
+export type McpServeTransport = {
+  type: "stdio";
+} | McpHttpServeTransport;
+/**
+ * Per-call context handed to resource readers and prompt builders (tools
+ * receive the same data on their `ToolContext`).
+ */
+export type McpServeCallContext = {
+  /** The inbound HTTP request; absent over stdio. */
+  request?: McpHttpRequestInfo;
+  /** Aborted when an HTTP server's `close()` gives up draining. */
+  signal?: AbortSignal;
+};
+/**
+ * A static MCP resource served by `resources/list` + `resources/read`.
+ */
+export type McpServeResource = {
+  /** Unique resource URI, e.g. `"docs://handbook"`. */
+  uri: string;
+  /** Resource name. */
+  name: string;
+  /** Optional display title. */
+  title?: string;
+  /** Optional description. */
+  description?: string;
+  /** Optional MIME type, echoed on the read result. */
+  mimeType?: string;
+  /**
+   * Produce the resource's contents. A string is sent as `text`; bytes
+   * are sent base64-encoded as `blob`.
+   */
+  read(context: McpServeCallContext): string | Uint8Array | Promise<string | Uint8Array>;
+};
+/** One declared argument of an {@link McpServePrompt}. */
+export type McpPromptArgument = {
+  /** Argument name. */
+  name: string;
+  /** Optional description shown to the user. */
+  description?: string;
+  /** When `true`, `prompts/get` without it answers an invalid-params error. */
+  required?: boolean;
+};
+/** One message of a prompt returned by `prompts/get`. */
+export type McpPromptMessage = {
+  /** Who speaks the message. */
+  role: "user" | "assistant";
+  /** The content block (`{ type: "text", text }` for plain text). */
+  content: McpContentBlock;
+};
+/**
+ * A prompt template served by `prompts/list` + `prompts/get`.
+ */
+export type McpServePrompt = {
+  /** Unique prompt name. */
+  name: string;
+  /** Optional display title. */
+  title?: string;
+  /** Optional description. */
+  description?: string;
+  /** Declared arguments. */
+  arguments?: McpPromptArgument[];
+  /**
+   * Build the prompt. A string becomes one `user` text message.
+   *
+   * @param args - The client's arguments (string values per the MCP spec).
+   */
+  get(args: Record<string, string>, context: McpServeCallContext): string | McpPromptMessage[] | Promise<string | McpPromptMessage[]>;
+};
+/**
+ * Options for `ai.mcp.serve(source, options)` (Direction B: local
+ * primitive → MCP server other clients can consume).
+ */
+export 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;
+  /**
+   * Opt in to native MCP result detection for objects containing `content`,
+   * `isError`, `structuredContent` or `_meta`. Other values still become text.
+   * Override per tool with `meta.mcpResults: "native" | "text"`.
+   * Explicit `mcpResult()` values always pass through after validation.
+   *
+   * @default "text"
+   */
+  results?: "text" | "native";
+  /**
+   * Prefix each tool of a grouped source (`{ groups: { … } }`) with its
+   * group name. `true` exposes `<group>_<tool>`; a function builds the
+   * exposed name itself. Only valid with a grouped source.
+   *
+   * @default false — names are exposed as-is and duplicates throw
+   */
+  prefixToolNames?: boolean | ((group: string, toolName: string) => string);
+  /** Static resources to serve. Omit to leave the `resources` capability off. */
+  resources?: McpServeResource[];
+  /** Prompt templates to serve. Omit to leave the `prompts` capability off. */
+  prompts?: McpServePrompt[];
+}
+/**
+ * What a started server resolves with. Over HTTP, `url` is the full
+ * endpoint (`http://127.0.0.1:53211/mcp`); over stdio it is absent.
+ */
+export interface McpServeHandle {
+  /** The endpoint URL (HTTP only). */
+  url?: string;
+  /**
+   * Stop serving. Over HTTP: stop accepting connections, let in-flight
+   * requests finish (up to `drainTimeoutMs`), then free the port.
+   * Idempotent.
+   */
+  close(): Promise<void>;
+}
+/** The handle of an HTTP-served MCP endpoint — `url` is always set. */
+export interface McpHttpServeHandle extends McpServeHandle {
+  /** The endpoint URL, e.g. `http://127.0.0.1:53211/mcp`. */
+  url: string;
+}
+/**
+ * A `ai.mcp.serve` server. Nothing listens until `start()`.
+ */
+export interface McpServer<THandle extends McpServeHandle = McpServeHandle> {
+  /**
+   * Begin serving. Over HTTP, resolves once the port is bound with
+   * `{ url, close }`. Calling it again while running resolves the same
+   * handle.
+   */
+  start(): Promise<THandle>;
+  /** Stop serving and release the transport (same as `handle.close()`). */
+  stop(): Promise<void>;
+}
+//#endregion
+//# sourceMappingURL=mcp-serve.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-serve.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/mcp-serve.type.ts"],"mappings":";;;;;;;;;;;;;YAcY;EAAkB,SAAS;IAAmB;;;;;;;;;YAU9C;;EAEV,QAAQ,eAAe;;;;;;;;YASb,iBAAiB,gBAAgB;;;;;;YAOjC,qBAAqB;;EAE/B;;EAEA;;;;;;;YAQU;;;;;;;;EAQV;;;;;;EAMA,aAAa,SAAS,iCAAiC;;;;;;;;YAS7C;;EAEV;;;;;;;EAOA;;;;;;;EAOA;;;;;;EAMA;;EAEA,OAAO;;;;;;;;;EASP;;;;;;;EAOA;;;;;;EAMA;;;;;;;EAOA;;;;;;;;YASU;EAAsB;IAAkB;;;;;YAMxC;;EAEV,UAAU;;EAEV,SAAS;;;;;YAMC;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;;;;EAKA,KAAK,SAAS,+BAA+B,aAAa,iBAAiB;;;YAIjE;;EAEV;;EAEA;;EAEA;;;YAIU;;EAEV;;EAEA,SAAS;;;;;YAMC;;EAEV;;EAEA;;EAEA;;EAEA,YAAY;;;;;;EAMZ,IACE,MAAM,wBACN,SAAS,+BACC,qBAAqB,iBAAiB;;;;;;iBAOnC;;EAEf;;;;;;EAMA;;;;;;EAMA,YAAY;;;;;;;;EAQZ,eAAe;;;;;;;;;EASf;;;;;;;;EAQA,8BAA8B,eAAe;;EAE7C,YAAY;;EAEZ,UAAU;;;;;;iBAOK;;EAEf;;;;;;EAMA,SAAS;;;iBAIM,2BAA2B;;EAE1C;;;;;iBAMe,UAAU,gBAAgB,iBAAiB;;;;;;EAM1D,SAAS,QAAQ;;EAEjB,QAAQ"}

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

@@ -1,5 +1,4 @@
-import { JsonSchemaTarget, ToolContract } from "@warlock.js/ai";
-
+import { ToolContract } from "@warlock.js/ai";
 //#region ../../packages/ai-tools/src/contracts/mcp.type.d.ts
 /**
  * Type contracts for the Model Context Protocol surface — the
@@ -19,9 +18,12 @@ import { JsonSchemaTarget, ToolContract } from "@warlock.js/ai";
  *   `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`. */
+export type McpTransport = {
+  /** stdio transport — a spawned child process. */
+  type: "stdio";
+  /** Executable to spawn (e.g. `"npx"`). */
+  command: string;
+  /** Arguments passed to `command`. */
   args?: string[];
   /**
    * Additional environment for the child. Explicit values override the
@@ -30,15 +32,18 @@ type McpTransport = {
    */
   env?: Record<string, string>;
 } | {
-  /** Streamable HTTP transport. */type: "http"; /** The server endpoint URL. */
-  url: string; /** Static headers sent with every request (e.g. auth). */
+  /** 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 {
+export interface McpClientOptions {
   /**
    * Prefix prepended to each remote tool name to avoid colliding with
    * local tools, e.g. `"github."`. The author owns uniqueness — there
@@ -53,11 +58,25 @@ interface McpClientOptions {
    * @default 30_000
    */
   timeoutMs?: number;
+  /**
+   * Bind the client's lifetime to a run. When it aborts, the client
+   * closes its transport (kills the stdio child / ends the HTTP session),
+   * in-flight requests reject, and later `tools()` / tool calls fail with
+   * an `McpTransportError` of type `"closed"`. Every `tools/call` also
+   * honors it, alongside the per-call `ctx.signal` the agent passes.
+   *
+   * @example
+   * const controller = new AbortController();
+   * const github = ai.mcp(server, { signal: controller.signal });
+   * await agent.execute(task, { signal: controller.signal, tools: await github.tools() });
+   * controller.abort(); // also shuts the MCP server down
+   */
+  signal?: AbortSignal;
 }
 /**
  * The client handle returned by `ai.mcp(server, options)`.
  */
-interface McpClient {
+export interface McpClient {
   /**
    * Lazily run the `initialize` handshake + `tools/list`, mapping each
    * remote tool to a {@link ToolContract}. Cached after the first call.
@@ -66,71 +85,14 @@ interface McpClient {
   /** 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";
+export type JsonRpcVersion = "2.0";
 /** A JSON-RPC id — a string or number (we never send notifications with `null`). */
-type JsonRpcId = string | number;
+export type JsonRpcId = string | number;
 /**
  * A JSON-RPC request: a method invocation that expects a response.
  */
-interface JsonRpcRequest<TParams = unknown> {
+export interface JsonRpcRequest<TParams = unknown> {
   jsonrpc: JsonRpcVersion;
   id: JsonRpcId;
   /** The RPC method name, e.g. `"tools/list"`. */
@@ -141,7 +103,7 @@ interface JsonRpcRequest<TParams = unknown> {
 /**
  * A JSON-RPC notification: a method invocation with no response.
  */
-interface JsonRpcNotification<TParams = unknown> {
+export interface JsonRpcNotification<TParams = unknown> {
   jsonrpc: JsonRpcVersion;
   /** The RPC method name. */
   method: string;
@@ -151,7 +113,7 @@ interface JsonRpcNotification<TParams = unknown> {
 /**
  * A JSON-RPC error object, carried in an error response.
  */
-interface JsonRpcError {
+export interface JsonRpcError {
   /** Numeric error code per the JSON-RPC spec. */
   code: number;
   /** Human-readable error message. */
@@ -162,7 +124,7 @@ interface JsonRpcError {
 /**
  * A JSON-RPC response — exactly one of `result` / `error` is present.
  */
-interface JsonRpcResponse<TResult = unknown> {
+export interface JsonRpcResponse<TResult = unknown> {
   jsonrpc: JsonRpcVersion;
   id: JsonRpcId;
   /** Present on success. */
@@ -173,19 +135,21 @@ interface JsonRpcResponse<TResult = unknown> {
 /**
  * Any inbound JSON-RPC message the transport may surface.
  */
-type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+export 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 {
+export 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>;
+  /** JSON Schema for structured results, when declared by the server. */
+  outputSchema?: Record<string, unknown>;
 }
 /**
  * One content block in an MCP `tools/call` result. MCP's wire field is
@@ -193,7 +157,7 @@ interface McpToolDescriptor {
  * `kind` for a content variant, the client maps it onto `type` so our
  * shapes only ever expose `type`.
  */
-interface McpContentBlock {
+export interface McpContentBlock {
   /** The content variant (`"text"`, `"image"`, `"resource"`, …). */
   type: string;
   /** Text payload, present for `type: "text"`. */
@@ -206,12 +170,15 @@ interface McpContentBlock {
  * tool-level failure the client rethrows so `tool()` wraps it as a
  * {@link import("@warlock.js/ai").ToolExecutionError}.
  */
-interface McpToolCallResult {
+export interface McpToolCallResult {
   /** Ordered content blocks produced by the tool. */
   content: McpContentBlock[];
   /** True when the call represents a tool-level error. */
   isError?: boolean;
+  /** Structured tool output (governed by the tool's outputSchema, if present). */
+  structuredContent?: Record<string, unknown>;
+  /** Protocol metadata forwarded without interpretation. */
+  _meta?: Record<string, unknown>;
 }
 //#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

@@ -1 +1 @@
-{"version":3,"file":"mcp.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/mcp.type.ts"],"mappings":";;;;;AAqBA;;;;;;;;;;;;;;AAqBsB;AAOtB;KA5BY,YAAA;mDAGN,IAAA,WA+BJ;EA7BI,OAAA,UA+BM;EA7BN,IAAA;EAmCK;AAAA;AAMX;;;EAnCM,GAAA,GAAM,MAAA;AAAA;EA0CD,iCAtCL,IAAA,UAsCY;EApCZ,GAAA,UAkCK;EAhCL,OAAA,GAAU,MAAM;AAAA;;;AAkCJ;AAQlB;UAnCiB,gBAAA;;;;;;EAMf,UAAA;EA+Bc;EA7Bd,MAAA,IAAU,QAAA;EAqCiB;;;;;EA/B3B,SAAA;AAAA;AAiCsB;AAMxB;;AANwB,UA3BP,SAAA;EAuDgB;;;;EAlD/B,KAAA,IAAS,OAAA,CAAQ,YAAA;EAkDjB;EAhDA,KAAA,IAAS,OAAA;AAAA;AAgDsB;AAMjC;;;;AANiC,KAxCrB,cAAA;EACN,KAAA,IAAS,YAAA;AAAA,IACX,YAAY;;;AAgDC;AAYjB;;;KApDY,iBAAA;EACN,IAAA;AAAA;EACA,IAAA;EAAc,IAAA;AAAA;AAqDC;AAKrB;;;AALqB,UA/CJ,eAAA;EAsDX;EApDJ,IAAA;EAwDgB;;;;;EAlDhB,OAAA;EA8CI;;;;;EAxCJ,SAAA,GAAY,iBAAA;EAkDG;;;;;;;EA1Cf,YAAA,GAAe,gBAAgB;AAAA;;;AA+Cf;UAzCD,SAAA;EA+CY;EA7C3B,KAAA,IAAS,OAAA;EA6CkB;EA3C3B,IAAA,IAAQ,OAAO;AAAA;;KAYL,cAAA;AAqCN;AAAA,KAlCM,SAAA;;;;UAKK,cAAA;EACf,OAAA,EAAS,cAAA;EACT,EAAA,EAAI,SAAA;EAuCgB;EArCpB,MAAA;EA+B+B;EA7B/B,MAAA,GAAS,OAAA;AAAA;;;;UAMM,mBAAA;EACf,OAAA,EAAS,cAAA;EA4BD;EA1BR,MAAA;EA0BoB;EAxBpB,MAAA,GAAS,OAAO;AAAA;;;;UAMD,YAAA;EA2BE;EAzBjB,IAAA;EAuBE;EArBF,OAAA;EAuBE;EArBF,IAAA;AAAA;AA4BF;;;AAAA,UAtBiB,eAAA;EACf,OAAA,EAAS,cAAA;EACT,EAAA,EAAI,SAAA;EA0BJ;EAxBA,MAAA,GAAS,OAAA;EAwBW;EAtBpB,KAAA,GAAQ,YAAA;AAAA;;;;KAME,cAAA,GACR,cAAA,GACA,mBAAA,GACA,eAAA;;;;AA4BY;AAQhB;UA7BiB,iBAAA;;EAEf,IAAA;EA6BA;EA3BA,WAAA;EA6BA;EA3BA,WAAA,GAAc,MAAM;AAAA;;;;;;;UASL,eAAA;;EAEf,IAAA;;EAEA,IAAA;;GAEC,KAAA;AAAA;;;;;;UAQc,iBAAA;;EAEf,OAAA,EAAS,eAAe;;EAExB,OAAA;AAAA"}
+{"version":3,"file":"mcp.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/mcp.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;YAqBY;;EAGN;;EAEA;;EAEA;;;;;;EAMA,MAAM;;;EAIN;;EAEA;;EAEA,UAAU;;;;;;iBAOC;;;;;;EAMf;;EAEA,UAAU;;;;;;EAMV;;;;;;;;;;;;;;EAcA,SAAS;;;;;iBAMM;;;;;EAKf,SAAS,QAAQ;;EAEjB,SAAS;;;YAYC;;YAGA;;;;iBAKK,eAAe;EAC9B,SAAS;EACT,IAAI;;EAEJ;;EAEA,SAAS;;;;;iBAMM,oBAAoB;EACnC,SAAS;;EAET;;EAEA,SAAS;;;;;iBAMM;;EAEf;;EAEA;;EAEA;;;;;iBAMe,gBAAgB;EAC/B,SAAS;EACT,IAAI;;EAEJ,SAAS;;EAET,QAAQ;;;;;YAME,iBAAiB,iBAAiB,sBAAsB;;;;;;iBAOnD;;EAEf;;EAEA;;EAEA,cAAc;;EAEd,eAAe;;;;;;;;iBASA;;EAEf;;EAEA;;GAEC;;;;;;;iBAQc;;EAEf,SAAS;;EAET;;EAEA,oBAAoB;;EAEpB,QAAQ"}

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

@@ -7,7 +7,7 @@
 /**
  * Construction options for `ai.tools.calculator`.
  */
-interface CalculatorOptions {
+export interface CalculatorOptions {
   /**
    * Override the tool name exposed to the LLM.
    *
@@ -18,14 +18,14 @@ interface CalculatorOptions {
 /**
  * The validated input shape the model passes to `calculator`.
  */
-interface CalculatorInput {
+export interface CalculatorInput {
   /** An arithmetic expression to evaluate, e.g. `"(3 + 4) * 2"`. */
   expression: string;
 }
 /**
  * The `calculator` tool's output.
  */
-interface CalculatorResult {
+export interface CalculatorResult {
   /** The numeric result of evaluating the expression. */
   result: number;
 }
@@ -37,11 +37,11 @@ interface CalculatorResult {
  * - `"diff"` — difference between two instants, in `unit`.
  * - `"format"` — render `iso` per `format`.
  */
-type DateTimeOp = "now" | "add" | "diff" | "format";
+export type DateTimeOp = "now" | "add" | "diff" | "format";
 /**
  * Construction options for `ai.tools.dateTime`.
  */
-interface DateTimeOptions {
+export interface DateTimeOptions {
   /**
    * Override the tool name exposed to the LLM.
    *
@@ -59,7 +59,7 @@ interface DateTimeOptions {
  * The validated input shape the model passes to `date_time`. Which
  * fields are required depends on `op` (validated at the seal layer).
  */
-interface DateTimeInput {
+export interface DateTimeInput {
   /** Which date-time operation to perform. */
   op: DateTimeOp;
   /** ISO-8601 instant the operation acts on (`add` / `diff` / `format`). */
@@ -84,7 +84,7 @@ interface DateTimeInput {
 /**
  * The `date_time` tool's output.
  */
-interface DateTimeResult {
+export interface DateTimeResult {
   /**
    * The result, rendered as a string — an ISO instant, a formatted
    * date, or a stringified numeric difference depending on `op`.
@@ -92,5 +92,4 @@ interface DateTimeResult {
   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

@@ -1 +1 @@
-{"version":3,"file":"utility.type.d.mts","names":[],"sources":["../../../../../../../../packages/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"}
+{"version":3,"file":"utility.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/utility.type.ts"],"mappings":";;;;;;;;;iBASiB;;;;;;EAMf;;;;;iBAMe;;EAEf;;;;;iBAMe;;EAEf;;;;;;;;;;YAWU;;;;iBAKK;;;;;;EAMf;;;;;;EAMA;;;;;;iBAOe;;EAEf,IAAI;;EAEJ;;;;;;EAMA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;iBAMe;;;;;EAKf"}