@warlock.js/ai-tools 5.31.0 → 5.33.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

@@ -2,4 +2,5 @@ import { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, Search
 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, 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";
+import { McpBeforeCall, McpCallRefusal, McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpServeHandle, McpHttpServeTransport, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, 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, McpBeforeCall, McpCallRefusal, McpClient, McpClientOptions, McpContentBlock, McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpServeHandle, McpHttpServeTransport, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolCallResult, McpToolDescriptor, McpToolSource, McpTransport, SearchProvider, WebSearchInput, WebSearchOptions, WebSearchResult, WebSearchResultItem };

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

@@ -1,6 +1,5 @@
-import { McpContentBlock } from "./mcp.type.mjs";
+import { JsonRpcId, McpContentBlock, McpToolCallResult } 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
@@ -12,7 +11,7 @@ import { JsonSchemaTarget, ToolContract, ToolRequestContext } from "@warlock.js/
  * One set of tools: an object that can enumerate its `ToolContract`s (a
  * built agent / supervisor / orchestrator / workspace), or a literal array.
  */
-type McpToolSource = {
+export type McpToolSource = {
   tools(): ToolContract[];
 } | ToolContract[];
 /**
@@ -23,8 +22,9 @@ type McpToolSource = {
  * @example
  * { groups: { github: githubAgent, files: [readFile, writeFile] } }
  */
-type McpGroupedToolSource = {
-  /** Tool sets keyed by group name. */groups: Record<string, McpToolSource>;
+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
@@ -32,22 +32,24 @@ type McpGroupedToolSource = {
  * {@link import("../errors").McpServeError} (`type: "collision"`) when
  * `serve()` is called.
  */
-type McpServeSource = McpToolSource | McpGroupedToolSource;
+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`).
  */
-type McpHttpRequestInfo = ToolRequestContext & {
-  /** The HTTP method, upper-case (`"POST"`, `"GET"`, …). */method: string; /** The request path, without the query string. */
+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.
+ * `bearer` / `authorize` / `authenticate` is required; all configured checks
+ * must pass, in that order. A request that fails gets HTTP 401 before its body is read.
  */
-type McpHttpAuth = {
+export type McpHttpAuth = {
   /**
    * Accepted bearer token(s), matched against
    * `Authorization: Bearer <token>`. Compared in constant time over
@@ -62,6 +64,12 @@ type McpHttpAuth = {
    * request (fails closed).
    */
   authorize?: (request: McpHttpRequestInfo) => boolean | Promise<boolean>;
+  /**
+   * Resolve the caller after Host/Origin, bearer and authorize checks.
+   * Undefined or a thrown/rejected error denies with 401 and a Bearer challenge.
+   * Any other value becomes context.principal (including null or false).
+   */
+  authenticate?: (request: McpHttpRequestInfo) => unknown | Promise<unknown>;
 };
 /**
  * Serve over the MCP Streamable HTTP transport.
@@ -69,8 +77,9 @@ type McpHttpAuth = {
  * Binds `127.0.0.1` by default. Binding any non-loopback address
  * requires `auth`; `start()` throws otherwise.
  */
-type McpHttpServeTransport = {
-  /** Streamable HTTP transport. */type: "http";
+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`.
@@ -90,7 +99,8 @@ type McpHttpServeTransport = {
    *
    * @default "/mcp"
    */
-  path?: string; /** Bearer token(s) and/or a custom authorize hook. Required off loopback. */
+  path?: string;
+  /** Bearer, authorize and/or authenticate checks. Required off loopback. */
   auth?: McpHttpAuth;
   /**
    * Extra browser origins allowed to call the endpoint, as full origins
@@ -128,25 +138,52 @@ type McpHttpServeTransport = {
  * - `"stdio"` — serve JSON-RPC over this process's stdin/stdout.
  * - `"http"` — serve MCP Streamable HTTP (see {@link McpHttpServeTransport}).
  */
-type McpServeTransport = {
+export type McpServeTransport = McpStdioServeTransport | McpHttpServeTransport;
+/** Local caller identity for the stdio connection. */
+export type McpStdioServeTransport = {
   type: "stdio";
-} | McpHttpServeTransport;
+  /** Static trusted identity; never read from tool arguments. */
+  principal?: unknown;
+  /** Per-request identity provider; takes precedence over principal when set. */
+  principalProvider?: (context: McpServeCallContext) => unknown | Promise<unknown>;
+};
 /**
  * Per-call context handed to resource readers and prompt builders (tools
  * receive the same data on their `ToolContext`).
  */
-type McpServeCallContext = {
-  /** The inbound HTTP request; absent over stdio. */request?: McpHttpRequestInfo; /** Aborted when an HTTP server's `close()` gives up draining. */
+export type McpServeCallContext = {
+  /** The inbound HTTP request; absent over stdio. */
+  request?: McpHttpRequestInfo;
+  /** JSON-RPC request id; populated by the serving boundary. */
+  requestId?: JsonRpcId;
+  /** Caller identity from HTTP authenticate or the stdio transport options. */
+  principal?: unknown;
+  /** Aborted on cancellation, client disconnect or server shutdown. */
   signal?: AbortSignal;
 };
+/** Context supplied to beforeCall after successful tool input validation. */
+export type McpServeToolContext = McpServeCallContext & {
+  requestId: JsonRpcId;
+};
+/** Native MCP error result returned by a beforeCall policy hook. */
+export type McpCallRefusal = McpToolCallResult & {
+  isError: true;
+};
+/** Validate policy before execute; a refusal bypasses result serialization. */
+export type McpBeforeCall = (context: McpServeToolContext, tool: ToolContract, input: unknown) => void | McpCallRefusal | Promise<void | McpCallRefusal>;
 /**
  * A static MCP resource served by `resources/list` + `resources/read`.
  */
-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. */
+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
@@ -155,23 +192,32 @@ type McpServeResource = {
   read(context: McpServeCallContext): string | Uint8Array | Promise<string | Uint8Array>;
 };
 /** One declared argument of an {@link McpServePrompt}. */
-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. */
+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`. */
-type McpPromptMessage = {
-  /** Who speaks the message. */role: "user" | "assistant"; /** The content block (`{ type: "text", text }` for plain text). */
+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`.
  */
-type McpServePrompt = {
-  /** Unique prompt name. */name: string; /** Optional display title. */
-  title?: string; /** Optional description. */
-  description?: string; /** Declared arguments. */
+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.
@@ -184,7 +230,7 @@ type McpServePrompt = {
  * Options for `ai.mcp.serve(source, options)` (Direction B: local
  * primitive → MCP server other clients can consume).
  */
-interface McpServeOptions {
+export interface McpServeOptions {
   /** Server name advertised in the `initialize` response. */
   name: string;
   /**
@@ -207,6 +253,21 @@ interface McpServeOptions {
    * @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";
+  /**
+   * Runs after schema validation and before invocation. Input is the validated
+   * value and should be treated as read-only. Return an isError:true native
+   * result to refuse; throw to answer with a JSON-RPC invalid-params error.
+   */
+  beforeCall?: McpBeforeCall;
   /**
    * Prefix each tool of a grouped source (`{ groups: { … } }`) with its
    * group name. `true` exposes `<group>_<tool>`; a function builds the
@@ -224,7 +285,7 @@ interface McpServeOptions {
  * 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.
  */
-interface McpServeHandle {
+export interface McpServeHandle {
   /** The endpoint URL (HTTP only). */
   url?: string;
   /**
@@ -235,14 +296,14 @@ interface McpServeHandle {
   close(): Promise<void>;
 }
 /** The handle of an HTTP-served MCP endpoint — `url` is always set. */
-interface McpHttpServeHandle extends McpServeHandle {
+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()`.
  */
-interface McpServer<THandle extends McpServeHandle = McpServeHandle> {
+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
@@ -253,5 +314,4 @@ interface McpServer<THandle extends McpServeHandle = McpServeHandle> {
   stop(): Promise<void>;
 }
 //#endregion
-export { McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpServeHandle, McpHttpServeTransport, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeTransport, McpServer, McpToolSource };
 //# sourceMappingURL=mcp-serve.type.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"mcp-serve.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/mcp-serve.type.ts"],"mappings":";;;;;;AAcA;;;;;;;;KAAY,aAAA;EAAkB,KAAA,IAAS,YAAA;AAAA,IAAmB,YAAY;;;;;;;AAYhC;AAStC;KAXY,oBAAA;uCAEV,MAAA,EAAQ,MAAM,SAAS,aAAA;AAAA;AAgBzB;;;;;;AAAA,KAPY,cAAA,GAAiB,aAAA,GAAgB,oBAAoB;;AAW3D;AAQN;;;KAZY,kBAAA,GAAqB,kBAAkB;EAoBjD,0DAlBA,MAAA,UAwBsB;EAtBtB,IAAA;AAAA;;AAsB8D;AAShE;;;KAvBY,WAAA;EAyBV;;;;;;;EAjBA,MAAA;EA6DA;;;AAOc;AAShB;EAvEE,SAAA,IAAa,OAAA,EAAS,kBAAA,eAAiC,OAAO;AAAA;;AAuES;AAMzE;;;;KApEY,qBAAA;EAsEA,iCApEV,IAAA;EAsES;;AAAW;AAMtB;;;EArEE,IAAA;EAoF6C;;;;;;EA7E7C,IAAA;EAoEA;;;;;EA9DA,IAAA,WAuE6C;EArE7C,IAAA,GAAO,WAAW;EAqEyD;;AAAU;AAIvF;;;;;EAhEE,cAAA;EAsEA;;AAAQ;AAIV;;;EAnEE,YAAA;EAqEA;;;;AAEwB;EAjExB,YAAA;EAuEwB;;;;;;EAhExB,cAAA;AAAA;;;;;;;KASU,iBAAA;EAAsB,IAAA;AAAA,IAAkB,qBAAqB;;;;;KAM7D,mBAAA;EAkEwC,mDAhElD,OAAA,GAAU,kBAAA,EAgEwD;EA9DlE,MAAA,GAAS,WAAW;AAAA;;;;KAMV,gBAAA;EAiGA,qDA/FV,GAAA,UA+FwB;EA7FxB,IAAA,UAmEA;EAjEA,KAAA,WAuEY;EArEZ,WAAA,WA6Ee;EA3Ef,QAAA;EAmF8B;;;;EA9E9B,IAAA,CAAK,OAAA,EAAS,mBAAA,YAA+B,UAAA,GAAa,OAAA,UAAiB,UAAA;AAAA;;KAIjE,iBAAA;EAqFK,qBAnFf,IAAA;EAEA,WAAA,WAmFA;EAjFA,QAAA;AAAA;;KAIU,gBAAA;EAuFK,8BArFf,IAAA;EAEA,OAAA,EAAS,eAAe;AAAA;AA2F1B;;;AAAA,KArFY,cAAA;EAqFgD,0BAnF1D,IAAA,UAyFS;EAvFT,KAAA,WAyFe;EAvFf,WAAA,WA+EyB;EA7EzB,SAAA,GAAY,iBAAA;EA6E8C;;;;;EAvE1D,GAAA,CACE,IAAA,EAAM,MAAA,kBACN,OAAA,EAAS,mBAAA,YACC,gBAAA,KAAqB,OAAA,UAAiB,gBAAA;AAAA;AA4EnC;;;;AAAA,UArEA,eAAA;;EAEf,IAAA;;;;;;EAMA,OAAA;;;;;;EAMA,SAAA,GAAY,iBAAA;;;;;;;;EAQZ,YAAA,GAAe,gBAAA;;;;;;;;EAQf,eAAA,eAA8B,KAAA,UAAe,QAAA;;EAE7C,SAAA,GAAY,gBAAA;;EAEZ,OAAA,GAAU,cAAA;AAAA;;;;;UAOK,cAAA;;EAEf,GAAA;;;;;;EAMA,KAAA,IAAS,OAAO;AAAA;;UAID,kBAAA,SAA2B,cAAc;;EAExD,GAAG;AAAA;;;;UAMY,SAAA,iBAA0B,cAAA,GAAiB,cAAA;;;;;;EAM1D,KAAA,IAAS,OAAA,CAAQ,OAAA;;EAEjB,IAAA,IAAQ,OAAA;AAAA"}
+{"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;;;;;;EAMvD,gBAAgB,SAAS,iCAAiC;;;;;;;;YAShD;;EAEV;;;;;;;EAOA;;;;;;;EAOA;;;;;;EAMA;;EAEA,OAAO;;;;;;;;;EASP;;;;;;;EAOA;;;;;;EAMA;;;;;;;EAOA;;;;;;;;YASU,oBAAoB,yBAAyB;;YAG7C;EACV;;EAEA;;EAEA,qBAAqB,SAAS,kCAAkC;;;;;;YAOtD;;EAEV,UAAU;;EAEV,YAAY;;EAEZ;;EAEA,SAAS;;;YAIC,sBAAsB;EAAwB,WAAW;;;YAGzD,iBAAiB;EAAsB;;;YAGvC,iBACV,SAAS,qBACT,MAAM,cACN,0BACU,iBAAiB,eAAe;;;;YAKhC;;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;;;;;;EAMA,aAAa;;;;;;;;EAQb,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 { 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 { 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
@@ -71,7 +76,7 @@ interface McpClientOptions {
 /**
  * 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.
@@ -81,13 +86,13 @@ interface McpClient {
   close(): 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"`. */
@@ -98,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;
@@ -108,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. */
@@ -119,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. */
@@ -130,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
@@ -150,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"`. */
@@ -163,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, 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;EAiDJ;;;AAAoB;AAMtB;EAjDM,GAAA,GAAM,MAAA;AAAA;EAsDO,iCAlDb,IAAA,UAoDK;EAlDL,GAAA,UAkDY;EAhDZ,OAAA,GAAU,MAAM;AAAA;;;;;UAOL,gBAAA;EAqDL;;;;AAAc;EA/CxB,UAAA;EAkDmB;EAhDnB,MAAA,IAAU,QAAA;EAgDS;AAAA;AAKrB;;;EA/CE,SAAA;EAiDI;;;;;;;;;;;;;EAnCJ,MAAA,GAAS,WAAW;AAAA;;;;UAML,SAAA;EAwCf;;;;EAnCA,KAAA,IAAS,OAAA,CAAQ,YAAA;EAuCD;EArChB,KAAA,IAAS,OAAA;AAAA;;KAYC,cAAA;;KAGA,SAAA;;;;UAKK,cAAA;EACf,OAAA,EAAS,cAAA;EACT,EAAA,EAAI,SAAA;EAiC0B;EA/B9B,MAAA;EAiCI;EA/BJ,MAAA,GAAS,OAAA;AAAA;;;;UAMM,mBAAA;EACf,OAAA,EAAS,cAAA;EAwBT;EAtBA,MAAA;EAwBA;EAtBA,MAAA,GAAS,OAAO;AAAA;;;AAwBI;UAlBL,YAAA;EAwBS;EAtBxB,IAAA;EAsB2B;EApB3B,OAAA;EAoBkE;EAlBlE,IAAA;AAAA;;;;UAMe,eAAA;EACf,OAAA,EAAS,cAAA;EACT,EAAA,EAAI,SAAA;EAiB4B;EAfhC,MAAA,GAAS,OAAA;EAqBW;EAnBpB,KAAA,GAAQ,YAAA;AAAA;;;;KAME,cAAA,GAAiB,cAAA,GAAiB,mBAAA,GAAsB,eAAA;AAsBpE;;;;;AAAA,UAfiB,iBAAA;EAqBd;EAnBD,IAAA;EAmBc;EAjBd,WAAA;EAyBgC;EAvBhC,WAAA,GAAc,MAAM;AAAA;;;;;AA2Bb;;UAlBQ,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"}

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

@@ -11,11 +11,11 @@
  *
  * Uses `type` as the discriminator everywhere downstream — never `kind`.
  */
-type SearchProvider = "tavily" | "brave" | "serpapi";
+export type SearchProvider = "tavily" | "brave" | "serpapi";
 /**
  * Construction options for {@link SearchProvider}-backed web search.
  */
-interface WebSearchOptions {
+export interface WebSearchOptions {
   /** Which optional search backend to use. Its SDK/HTTP key is a lazy peer. */
   provider: SearchProvider;
   /**
@@ -40,7 +40,7 @@ interface WebSearchOptions {
 /**
  * The validated input shape the model passes to the web-search tool.
  */
-interface WebSearchInput {
+export interface WebSearchInput {
   /** The search query. */
   query: string;
   /** Per-call cap on results, clamped into `[1, options.maxResults]`. */
@@ -50,7 +50,7 @@ interface WebSearchInput {
  * A single web-search hit. `score` is provider-supplied relevance when
  * the backend returns one (Tavily does; some others do not).
  */
-interface WebSearchResultItem {
+export interface WebSearchResultItem {
   /** Page / document title. */
   title: string;
   /** Canonical URL of the result. */
@@ -63,7 +63,7 @@ interface WebSearchResultItem {
 /**
  * The web-search tool's output — the ranked list of hits.
  */
-interface WebSearchResult {
+export interface WebSearchResult {
   /** Ranked results, best-first. */
   results: WebSearchResultItem[];
 }
@@ -76,11 +76,11 @@ interface WebSearchResult {
  * - `"html"` — the raw response body, untouched.
  * - `"markdown"` — readability extraction converted to Markdown.
  */
-type FetchUrlExtract = "text" | "html" | "markdown";
+export type FetchUrlExtract = "text" | "html" | "markdown";
 /**
  * Construction options for `ai.tools.fetchUrl`.
  */
-interface FetchUrlOptions {
+export interface FetchUrlOptions {
   /**
    * Override the tool name exposed to the LLM.
    *
@@ -126,14 +126,14 @@ interface FetchUrlOptions {
 /**
  * The validated input shape the model passes to `fetch_url`.
  */
-interface FetchUrlInput {
+export interface FetchUrlInput {
   /** The absolute URL to fetch. */
   url: string;
 }
 /**
  * The `fetch_url` tool's output.
  */
-interface FetchUrlResult {
+export interface FetchUrlResult {
   /** The URL that was fetched (after any redirects the platform followed). */
   url: string;
   /** HTTP status code of the final response. */
@@ -144,5 +144,4 @@ interface FetchUrlResult {
   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

@@ -1 +1 @@
-{"version":3,"file":"web.type.d.mts","names":[],"sources":["../../../../../../../../packages/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;EA0Ef;EAxEA,KAAA;EAwEmB;EAtEnB,GAAA;EA4E4B;EA1E5B,OAAA;EA4EG;EA1EH,KAAA;AAAA;;;;UAMe,eAAA;EA8Ef;EA5EA,OAAA,EAAS,mBAAmB;AAAA;;AAgFnB;;;;;;;;KApEC,eAAA;;;;UAKK,eAAA;;;;;;EAMf,IAAA;;;;;;EAMA,QAAA;;;;;;EAMA,SAAA;;;;;;EAMA,OAAA,GAAU,eAAe;;;;;;EAMzB,UAAA;;;;;;;;;;;EAWA,mBAAA;AAAA;;;;UAMe,aAAA;;EAEf,GAAG;AAAA;;;;UAMY,cAAA;;EAEf,GAAA;;EAEA,MAAA;;EAEA,OAAA;;EAEA,SAAA;AAAA"}
+{"version":3,"file":"web.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/contracts/web.type.ts"],"mappings":";;;;;;;;;;;;;YAaY;;;;iBAKK;;EAEf,UAAU;;;;;EAKV;;;;;;;EAOA;;;;;;EAMA;;;;;iBAMe;;EAEf;;EAEA;;;;;;iBAOe;;EAEf;;EAEA;;EAEA;;EAEA;;;;;iBAMe;;EAEf,SAAS;;;;;;;;;;;YAYC;;;;iBAKK;;;;;;EAMf;;;;;;EAMA;;;;;;EAMA;;;;;;EAMA,UAAU;;;;;;EAMV;;;;;;;;;;;EAWA;;;;;iBAMe;;EAEf;;;;;iBAMe;;EAEf;;EAEA;;EAEA;;EAEA"}