@warlock.js/ai-tools 5.32.0 → 5.34.0

package/esm/contracts/index.d.mts

@@ -2,5 +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";
-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 };
+import { McpBeforeCall, McpCallRefusal, McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolSource, McpValidateCallParams } 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, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolCallResult, McpToolDescriptor, McpToolSource, McpTransport, McpValidateCallParams, SearchProvider, WebSearchInput, WebSearchOptions, WebSearchResult, WebSearchResultItem };

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

@@ -1,4 +1,4 @@
-import { McpContentBlock } from "./mcp.type.mjs";
+import { JsonRpcId, McpContentBlock, McpToolCallResult, McpToolDescriptor } from "./mcp.type.mjs";
 import { JsonSchemaTarget, ToolContract, ToolRequestContext } from "@warlock.js/ai";
 //#region ../../packages/ai-tools/src/contracts/mcp-serve.type.d.ts
 /**
@@ -46,8 +46,8 @@ export type McpHttpRequestInfo = ToolRequestContext & {
 };
 /**
  * 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.
  */
 export type McpHttpAuth = {
   /**
@@ -64,6 +64,40 @@ export 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>;
+};
+/** Authenticated context for an extra HTTP route; there is no JSON-RPC id. */
+export type McpHttpRouteContext = McpServeCallContext & {
+  request: McpHttpRequestInfo;
+  /** Parsed request URL; use searchParams to read query parameters. */
+  url: URL;
+  /** UTF-8 request body, subject to the transport's maxBodyBytes limit. */
+  body: string;
+  signal: AbortSignal;
+};
+/** JSON response from an extra HTTP route. Omit body for an empty response. */
+export type McpHttpRouteResponse = {
+  /** @default 200 */
+  status?: number;
+  headers?: Record<string, string>;
+  body?: unknown;
+};
+/** An exact method/path route beneath the MCP endpoint, sharing its auth. */
+export type McpHttpRoute = {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+  /**
+   * Suffix such as /tool-policy, appended to the MCP path without its trailing
+   * slash. Nonempty segments use letters, digits, _, -, . or ~; . and .. are
+   * forbidden. No query, fragment, escapes, wildcard or trailing slash.
+   * The MCP endpoint itself is reserved for every method. Duplicates fail start().
+   */
+  path: string;
+  handler(context: McpHttpRouteContext): McpHttpRouteResponse | Promise<McpHttpRouteResponse>;
 };
 /**
  * Serve over the MCP Streamable HTTP transport.
@@ -89,13 +123,15 @@ export type McpHttpServeTransport = {
    */
   port?: number;
   /**
-   * The single MCP endpoint path. Other paths answer 404.
+   * The MCP endpoint path. Other paths answer 404 unless registered in routes.
    *
    * @default "/mcp"
    */
   path?: string;
-  /** Bearer token(s) and/or a custom authorize hook. Required off loopback. */
+  /** Bearer, authorize and/or authenticate checks. Required off loopback. */
   auth?: McpHttpAuth;
+  /** Extra HTTP routes with the same Host/Origin and authentication checks. */
+  routes?: readonly McpHttpRoute[];
   /**
    * Extra browser origins allowed to call the endpoint, as full origins
    * (`"https://app.example.com"`). Loopback origins (`http://localhost:*`,
@@ -132,9 +168,15 @@ export type McpHttpServeTransport = {
  * - `"stdio"` — serve JSON-RPC over this process's stdin/stdout.
  * - `"http"` — serve MCP Streamable HTTP (see {@link McpHttpServeTransport}).
  */
-export 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`).
@@ -142,9 +184,30 @@ export type McpServeTransport = {
 export type McpServeCallContext = {
   /** The inbound HTTP request; absent over stdio. */
   request?: McpHttpRequestInfo;
-  /** Aborted when an HTTP server's `close()` gives up draining. */
+  /** 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>;
+/** Filter fresh wire descriptors for discovery only; hidden tools stay callable. */
+export type McpListFilter = (context: McpServeToolContext, tools: readonly McpToolDescriptor[]) => readonly McpToolDescriptor[] | Promise<readonly McpToolDescriptor[]>;
+/**
+ * Inspect the complete tools/call params before lookup, schema validation or
+ * beforeCall. Treat params as read-only; throw McpError for an app-defined error.
+ */
+export type McpValidateCallParams = (context: McpServeToolContext, params: Readonly<Record<string, unknown>>) => void | Promise<void>;
 /**
  * A static MCP resource served by `resources/list` + `resources/read`.
  */
@@ -236,6 +299,20 @@ export interface McpServeOptions {
    * @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. McpError preserves its code/message/data; other throws
+   * answer with a JSON-RPC invalid-params error.
+   */
+  beforeCall?: McpBeforeCall;
+  /** Per-request discovery filter; never changes tools/call lookup or policy. */
+  listFilter?: McpListFilter;
+  /**
+   * Optional envelope policy. Receives all params, including unknown fields,
+   * task and _meta. By default extra fields are ignored (no task capability).
+   */
+  validateCallParams?: McpValidateCallParams;
   /**
    * Prefix each tool of a grouped source (`{ groups: { … } }`) with its
    * group name. `true` exposes `<group>_<tool>`; a function builds the

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":";;;;;;;;;;;;;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"}
+{"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;;;YAIhD,sBAAsB;EAChC,SAAS;;EAET,KAAK;;EAEL;EACA,QAAQ;;;YAIE;;EAEV;EACA,UAAU;EACV;;;YAIU;EACV;;;;;;;EAOA;EACA,QAAQ,SAAS,sBAAsB,uBAAuB,QAAQ;;;;;;;;YAS5D;;EAEV;;;;;;;EAOA;;;;;;;EAOA;;;;;;EAMA;;EAEA,OAAO;;EAEP,kBAAkB;;;;;;;;;EASlB;;;;;;;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;;YAGhC,iBACV,SAAS,qBACT,gBAAgB,iCACJ,sBAAsB,iBAAiB;;;;;YAMzC,yBACV,SAAS,qBACT,QAAQ,SAAS,oCACP;;;;YAKA;;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;;;;;;;EAOA,aAAa;;EAEb,aAAa;;;;;EAKb,qBAAqB;;;;;;;;EAQrB,8BAA8B,eAAe;;EAE7C,YAAY;;EAEZ,UAAU;;;;;;iBAOK;;EAEf;;;;;;EAMA,SAAS;;;iBAIM,2BAA2B;;EAE1C;;;;;iBAMe,UAAU,gBAAgB,iBAAiB;;;;;;EAM1D,SAAS,QAAQ;;EAEjB,QAAQ"}

package/esm/index.d.mts

@@ -2,10 +2,11 @@ import { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, Search
 import { HttpMethod, HttpRequestInput, HttpRequestOptions, HttpRequestResult } from "./contracts/http.type.mjs";
 import { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOp, DateTimeOptions, DateTimeResult } from "./contracts/utility.type.mjs";
 import { JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcVersion, McpClient, McpClientOptions, McpContentBlock, McpToolCallResult, McpToolDescriptor, McpTransport } from "./contracts/mcp.type.mjs";
-import { McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpServeHandle, McpHttpServeTransport, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeTransport, McpServer, McpToolSource } from "./contracts/mcp-serve.type.mjs";
+import { McpBeforeCall, McpCallRefusal, McpGroupedToolSource, McpHttpAuth, McpHttpRequestInfo, McpHttpRoute, McpHttpRouteContext, McpHttpRouteResponse, McpHttpServeHandle, McpHttpServeTransport, McpListFilter, McpPromptArgument, McpPromptMessage, McpServeCallContext, McpServeHandle, McpServeOptions, McpServePrompt, McpServeResource, McpServeSource, McpServeToolContext, McpServeTransport, McpServer, McpStdioServeTransport, McpToolSource, McpValidateCallParams } from "./contracts/mcp-serve.type.mjs";
 import "./contracts/index.mjs";
 import { McpServeRequestHandler, createServeHandler, serve } from "./mcp/serve.mjs";
 import { SUPPORTED_PROTOCOL_VERSIONS } from "./mcp/protocol.mjs";
+import { McpError } from "./mcp/error.mjs";
 import { McpNativeResult, mcpResult } from "./mcp/result.mjs";
 import { jsonSchemaToStandard } from "./mcp/json-schema-to-standard.mjs";
 import { McpTransportClient } from "./mcp/transport.type.mjs";
@@ -20,6 +21,6 @@ import { calculatorTool } from "./utility/calculator.mjs";
 import { dateTimeTool } from "./utility/date-time.mjs";
 import "./utility/index.mjs";
 import { CalculatorError, CalculatorErrorOptions, CalculatorFailure, DateTimeError, DateTimeErrorOptions, DateTimeFailure, HttpPolicyError, HttpPolicyErrorOptions, HttpPolicyFailure, McpServeError, McpServeErrorOptions, McpServeFailure, McpTransportError, McpTransportErrorOptions, McpTransportFailure, WebToolError, WebToolErrorOptions, WebToolFailure } from "./errors.mjs";
-export { type AiToolsNamespace, CalculatorError, type CalculatorErrorOptions, type CalculatorFailure, type CalculatorInput, type CalculatorOptions, type CalculatorResult, DateTimeError, type DateTimeErrorOptions, type DateTimeFailure, type DateTimeInput, type DateTimeOp, type DateTimeOptions, type DateTimeResult, type FetchUrlExtract, type FetchUrlInput, type FetchUrlOptions, type FetchUrlResult, type HttpMethod, HttpPolicyError, type HttpPolicyErrorOptions, type HttpPolicyFailure, type HttpRequestInput, type HttpRequestOptions, type HttpRequestResult, type JsonRpcClientHandle, type JsonRpcError, type JsonRpcId, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type JsonRpcVersion, type McpClient, type McpClientOptions, type McpContentBlock, type McpFactory, type McpGroupedToolSource, type McpHttpAuth, type McpHttpRequestInfo, type McpHttpServeHandle, type McpHttpServeTransport, type McpNativeResult, type McpPromptArgument, type McpPromptMessage, type McpServeCallContext, McpServeError, type McpServeErrorOptions, type McpServeFailure, type McpServeHandle, type McpServeOptions, type McpServePrompt, type McpServeRequestHandler, type McpServeResource, type McpServeSource, type McpServeTransport, type McpServer, type McpToolCallResult, type McpToolDescriptor, type McpToolSource, type McpTransport, type McpTransportClient, McpTransportError, type McpTransportErrorOptions, type McpTransportFailure, SUPPORTED_PROTOCOL_VERSIONS, type SearchProvider, type WebSearchInput, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, WebToolError, type WebToolErrorOptions, type WebToolFailure, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, mcpResult, serve, webSearchTool };
+export { type AiToolsNamespace, CalculatorError, type CalculatorErrorOptions, type CalculatorFailure, type CalculatorInput, type CalculatorOptions, type CalculatorResult, DateTimeError, type DateTimeErrorOptions, type DateTimeFailure, type DateTimeInput, type DateTimeOp, type DateTimeOptions, type DateTimeResult, type FetchUrlExtract, type FetchUrlInput, type FetchUrlOptions, type FetchUrlResult, type HttpMethod, HttpPolicyError, type HttpPolicyErrorOptions, type HttpPolicyFailure, type HttpRequestInput, type HttpRequestOptions, type HttpRequestResult, type JsonRpcClientHandle, type JsonRpcError, type JsonRpcId, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type JsonRpcVersion, type McpBeforeCall, type McpCallRefusal, type McpClient, type McpClientOptions, type McpContentBlock, McpError, type McpFactory, type McpGroupedToolSource, type McpHttpAuth, type McpHttpRequestInfo, type McpHttpRoute, type McpHttpRouteContext, type McpHttpRouteResponse, type McpHttpServeHandle, type McpHttpServeTransport, type McpListFilter, type McpNativeResult, type McpPromptArgument, type McpPromptMessage, type McpServeCallContext, McpServeError, type McpServeErrorOptions, type McpServeFailure, type McpServeHandle, type McpServeOptions, type McpServePrompt, type McpServeRequestHandler, type McpServeResource, type McpServeSource, type McpServeToolContext, type McpServeTransport, type McpServer, type McpStdioServeTransport, type McpToolCallResult, type McpToolDescriptor, type McpToolSource, type McpTransport, type McpTransportClient, McpTransportError, type McpTransportErrorOptions, type McpTransportFailure, type McpValidateCallParams, SUPPORTED_PROTOCOL_VERSIONS, type SearchProvider, type WebSearchInput, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, WebToolError, type WebToolErrorOptions, type WebToolFailure, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, mcpResult, serve, webSearchTool };
 import "./mcp/index.mjs";
 import "./register.mjs";

package/esm/index.mjs

@@ -2,6 +2,7 @@ import { CalculatorError, DateTimeError, HttpPolicyError, McpServeError, McpTran
 import { httpRequestTool } from "./http/http-request.mjs";
 import { jsonSchemaToStandard } from "./mcp/json-schema-to-standard.mjs";
 import { createJsonRpcClient, createTransport } from "./mcp/transport.mjs";
+import { McpError } from "./mcp/error.mjs";
 import { SUPPORTED_PROTOCOL_VERSIONS } from "./mcp/protocol.mjs";
 import { mcpResult } from "./mcp/result.mjs";
 import { createServeHandler, serve } from "./mcp/serve.mjs";
@@ -14,4 +15,4 @@ import "./register.mjs";
 import "./web/index.mjs";
 import "./utility/index.mjs";
 
-export { CalculatorError, DateTimeError, HttpPolicyError, McpServeError, McpTransportError, SUPPORTED_PROTOCOL_VERSIONS, WebToolError, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, mcpResult, serve, webSearchTool };
+export { CalculatorError, DateTimeError, HttpPolicyError, McpError, McpServeError, McpTransportError, SUPPORTED_PROTOCOL_VERSIONS, WebToolError, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, mcpResult, serve, webSearchTool };

package/esm/mcp/error.d.mts

@@ -0,0 +1,9 @@
+//#region ../../packages/ai-tools/src/mcp/error.d.ts
+/** An application-defined JSON-RPC error thrown by MCP serving policy hooks. */
+export declare class McpError extends Error {
+  readonly code: number;
+  readonly data: unknown;
+  constructor(code: number, message: string, data?: unknown);
+}
+//#endregion
+//# sourceMappingURL=error.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/error.ts"],"mappings":";;qBACa,iBAAiB;WACZ;WAEA;EAEhB,YAAmB,cAAc,iBAAiB"}

package/esm/mcp/error.mjs

@@ -0,0 +1,24 @@
+//#region ../../packages/ai-tools/src/mcp/error.ts
+/** An application-defined JSON-RPC error thrown by MCP serving policy hooks. */
+var McpError = class extends Error {
+	constructor(code, message, data) {
+		super(message);
+		this.name = "McpError";
+		this.code = code;
+		this.data = data;
+	}
+};
+/**
+* Recognize our error and the SDK's McpError without a runtime SDK dependency.
+* SDK source (checked 2026-10-19):
+* https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/src/types.ts
+* Only explicitly named errors with an integer code opt in; ordinary throws
+* retain the existing mapping. Preserve the error's message verbatim.
+*/
+function isMcpError(cause) {
+	return cause instanceof Error && cause.name === "McpError" && "code" in cause && typeof cause.code === "number" && Number.isInteger(cause.code);
+}
+
+//#endregion
+export { McpError, isMcpError };
+//# sourceMappingURL=error.mjs.map

package/esm/mcp/error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/error.ts"],"sourcesContent":["/** An application-defined JSON-RPC error thrown by MCP serving policy hooks. */\nexport class McpError extends Error {\n  public readonly code: number;\n\n  public readonly data: unknown;\n\n  public constructor(code: number, message: string, data?: unknown) {\n    super(message);\n    this.name = \"McpError\";\n    this.code = code;\n    this.data = data;\n  }\n}\n\n/**\n * Recognize our error and the SDK's McpError without a runtime SDK dependency.\n * SDK source (checked 2026-10-19):\n * https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/src/types.ts\n * Only explicitly named errors with an integer code opt in; ordinary throws\n * retain the existing mapping. Preserve the error's message verbatim.\n */\nexport function isMcpError(cause: unknown): cause is Error & { code: number; data?: unknown } {\n  return (\n    cause instanceof Error &&\n    cause.name === \"McpError\" &&\n    \"code\" in cause &&\n    typeof cause.code === \"number\" &&\n    Number.isInteger(cause.code)\n  );\n}\n"],"mappings":";;AACA,IAAa,WAAb,cAA8B,MAAM;CAKlC,AAAO,YAAY,MAAc,SAAiB,MAAgB;EAChE,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,OAAO;CACd;AACF;;;;;;;;AASA,SAAgB,WAAW,OAAmE;CAC5F,OACE,iBAAiB,SACjB,MAAM,SAAS,cACf,UAAU,SACV,OAAO,MAAM,SAAS,YACtB,OAAO,UAAU,MAAM,IAAI;AAE/B"}

package/esm/mcp/index.d.mts

@@ -3,6 +3,7 @@ import { McpHttpServeHandle, McpHttpServeTransport, McpServeOptions, McpServeSou
 import "../contracts/index.mjs";
 import { McpServeRequestHandler, createServeHandler, serve } from "./serve.mjs";
 import { SUPPORTED_PROTOCOL_VERSIONS } from "./protocol.mjs";
+import { McpError } from "./error.mjs";
 import { McpNativeResult, mcpResult } from "./result.mjs";
 import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
 import { McpTransportClient } from "./transport.type.mjs";
@@ -47,5 +48,5 @@ export interface McpFactory {
  */
 export declare const mcp: McpFactory;
 //#endregion
-export { type McpNativeResult, type McpServeRequestHandler, type McpTransportClient, SUPPORTED_PROTOCOL_VERSIONS, createServeHandler, mcpResult, serve };
+export { McpError, type McpNativeResult, type McpServeRequestHandler, type McpTransportClient, SUPPORTED_PROTOCOL_VERSIONS, createServeHandler, mcpResult, serve };
 //# sourceMappingURL=index.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/index.ts"],"mappings":";;;;;;;;;;;;;;;;;iBA8BiB;;;;;;;;GAQd,QAAQ,cAAc,UAAU,mBAAmB;;;;;;;;;EASpD,MACE,QAAQ,gBACR,SAAS;IAAoB,WAAW;MACvC,UAAU;EACb,MAAM,QAAQ,gBAAgB,SAAS,kBAAkB;;;;;;;;;;qBAW9C,KAAK"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;iBA+BiB;;;;;;;;GAQd,QAAQ,cAAc,UAAU,mBAAmB;;;;;;;;;EASpD,MACE,QAAQ,gBACR,SAAS;IAAoB,WAAW;MACvC,UAAU;EACb,MAAM,QAAQ,gBAAgB,SAAS,kBAAkB;;;;;;;;;;qBAW9C,KAAK"}

package/esm/mcp/index.mjs

@@ -1,6 +1,7 @@
 import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
 import { createJsonRpcClient, createTransport } from "./transport.mjs";
 import { mcp as mcp$1 } from "./client.mjs";
+import { McpError } from "./error.mjs";
 import { SUPPORTED_PROTOCOL_VERSIONS } from "./protocol.mjs";
 import { mcpResult } from "./result.mjs";
 import { createServeHandler, serve } from "./serve.mjs";
@@ -17,5 +18,5 @@ import { createServeHandler, serve } from "./serve.mjs";
 const mcp = Object.assign((server, options) => mcp$1(server, options), { serve });
 
 //#endregion
-export { SUPPORTED_PROTOCOL_VERSIONS, createServeHandler, mcp, mcpResult, serve };
+export { McpError, SUPPORTED_PROTOCOL_VERSIONS, createServeHandler, mcp, mcpResult, serve };
 //# sourceMappingURL=index.mjs.map

package/esm/mcp/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["mcpClient"],"sources":["../../../../../../../../packages/ai-tools/src/mcp/index.ts"],"sourcesContent":["import type {\n  McpClient,\n  McpClientOptions,\n  McpHttpServeHandle,\n  McpHttpServeTransport,\n  McpServeOptions,\n  McpServeSource,\n  McpServer,\n  McpTransport,\n} from \"../contracts\";\nimport { mcp as mcpClient } from \"./client\";\nimport { serve } from \"./serve\";\n\nexport { serve, createServeHandler } from \"./serve\";\nexport type { McpServeRequestHandler } from \"./serve\";\nexport { SUPPORTED_PROTOCOL_VERSIONS } from \"./protocol\";\nexport { mcpResult } from \"./result\";\nexport type { McpNativeResult } from \"./result\";\nexport { jsonSchemaToStandard } from \"./json-schema-to-standard\";\nexport { createJsonRpcClient, createTransport } from \"./transport\";\nexport type { JsonRpcClientHandle } from \"./transport\";\nexport type { McpTransportClient } from \"./transport.type\";\n\n/**\n * The callable `ai.mcp` surface — a factory that connects to an external\n * MCP server (Direction A) and also carries `.serve` to expose a local\n * primitive AS an MCP server (Direction B). Modeled as a function with an\n * attached `serve` property, mirroring how `ai.mcp(server).tools()` and\n * `ai.mcp.serve(source, options).start()` read in the design.\n */\nexport interface McpFactory {\n  /**\n   * Connect to an external MCP server and adapt its tools as agent tools.\n   *\n   * @param server - The transport config (`{ type: \"stdio\" }` / `{ type: \"http\" }`).\n   * @param options - Prefix / filter / per-call timeout, and a `signal`\n   *   that closes the client (and fails its calls) when it aborts.\n   */\n  (server: McpTransport, options?: McpClientOptions): McpClient;\n  /**\n   * Expose a built agent / supervisor / orchestrator (or a literal\n   * `ToolContract[]`, or named `{ groups }`) AS an MCP server. Over\n   * `{ type: \"http\" }`, `start()` resolves `{ url, close }`.\n   *\n   * @param source - The tools to expose.\n   * @param options - Server name, version, transport, schema dialect, resources, prompts.\n   */\n  serve(\n    source: McpServeSource,\n    options: McpServeOptions & { transport: McpHttpServeTransport },\n  ): McpServer<McpHttpServeHandle>;\n  serve(source: McpServeSource, options: McpServeOptions): McpServer;\n}\n\n/**\n * The `ai.mcp` factory value: the client factory with `.serve` attached.\n * `Object.assign` keeps `mcp` callable (Direction A) while widening it with\n * the `serve` member (Direction B) — one object, both directions. The\n * `declare module \"@warlock.js/ai\"` augmentation and the runtime\n * registration (`ai.mcp = mcp`) live in `../register`, so this barrel is a\n * pure value/type module the registrar consumes.\n */\nexport const mcp: McpFactory = Object.assign(\n  (server: McpTransport, options?: McpClientOptions): McpClient => mcpClient(server, options),\n  { serve },\n);\n"],"mappings":";;;;;;;;;;;;;;;;AA8DA,MAAa,MAAkB,OAAO,QACnC,QAAsB,YAA0CA,MAAU,QAAQ,OAAO,GAC1F,EAAE,MAAM,CACV"}
+{"version":3,"file":"index.mjs","names":["mcpClient"],"sources":["../../../../../../../../packages/ai-tools/src/mcp/index.ts"],"sourcesContent":["import type {\n  McpClient,\n  McpClientOptions,\n  McpHttpServeHandle,\n  McpHttpServeTransport,\n  McpServeOptions,\n  McpServeSource,\n  McpServer,\n  McpTransport,\n} from \"../contracts\";\nimport { mcp as mcpClient } from \"./client\";\nimport { serve } from \"./serve\";\n\nexport { serve, createServeHandler } from \"./serve\";\nexport type { McpServeRequestHandler } from \"./serve\";\nexport { SUPPORTED_PROTOCOL_VERSIONS } from \"./protocol\";\nexport { McpError } from \"./error\";\nexport { mcpResult } from \"./result\";\nexport type { McpNativeResult } from \"./result\";\nexport { jsonSchemaToStandard } from \"./json-schema-to-standard\";\nexport { createJsonRpcClient, createTransport } from \"./transport\";\nexport type { JsonRpcClientHandle } from \"./transport\";\nexport type { McpTransportClient } from \"./transport.type\";\n\n/**\n * The callable `ai.mcp` surface — a factory that connects to an external\n * MCP server (Direction A) and also carries `.serve` to expose a local\n * primitive AS an MCP server (Direction B). Modeled as a function with an\n * attached `serve` property, mirroring how `ai.mcp(server).tools()` and\n * `ai.mcp.serve(source, options).start()` read in the design.\n */\nexport interface McpFactory {\n  /**\n   * Connect to an external MCP server and adapt its tools as agent tools.\n   *\n   * @param server - The transport config (`{ type: \"stdio\" }` / `{ type: \"http\" }`).\n   * @param options - Prefix / filter / per-call timeout, and a `signal`\n   *   that closes the client (and fails its calls) when it aborts.\n   */\n  (server: McpTransport, options?: McpClientOptions): McpClient;\n  /**\n   * Expose a built agent / supervisor / orchestrator (or a literal\n   * `ToolContract[]`, or named `{ groups }`) AS an MCP server. Over\n   * `{ type: \"http\" }`, `start()` resolves `{ url, close }`.\n   *\n   * @param source - The tools to expose.\n   * @param options - Server name, version, transport, schema dialect, resources, prompts.\n   */\n  serve(\n    source: McpServeSource,\n    options: McpServeOptions & { transport: McpHttpServeTransport },\n  ): McpServer<McpHttpServeHandle>;\n  serve(source: McpServeSource, options: McpServeOptions): McpServer;\n}\n\n/**\n * The `ai.mcp` factory value: the client factory with `.serve` attached.\n * `Object.assign` keeps `mcp` callable (Direction A) while widening it with\n * the `serve` member (Direction B) — one object, both directions. The\n * `declare module \"@warlock.js/ai\"` augmentation and the runtime\n * registration (`ai.mcp = mcp`) live in `../register`, so this barrel is a\n * pure value/type module the registrar consumes.\n */\nexport const mcp: McpFactory = Object.assign(\n  (server: McpTransport, options?: McpClientOptions): McpClient => mcpClient(server, options),\n  { serve },\n);\n"],"mappings":";;;;;;;;;;;;;;;;;AA+DA,MAAa,MAAkB,OAAO,QACnC,QAAsB,YAA0CA,MAAU,QAAQ,OAAO,GAC1F,EAAE,MAAM,CACV"}

package/esm/mcp/serve-http.mjs

@@ -1,5 +1,6 @@
 import { McpServeError } from "../errors.mjs";
 import { SUPPORTED_PROTOCOL_VERSIONS } from "./protocol.mjs";
+import { McpServeRequests } from "./serve-requests.mjs";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { isIPv4, isIPv6 } from "node:net";
@@ -12,7 +13,7 @@ import { isIPv4, isIPv6 } from "node:net";
 * specification (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports,
 * checked 2026-10-17) on `node:http`, with no SDK dependency:
 *
-* - one endpoint path; each POST carries exactly one JSON-RPC message
+* - one MCP endpoint path (plus optional authenticated app routes); each MCP POST carries exactly one JSON-RPC message
 *   (batches were removed from the protocol in 2025-06-18 and get 400);
 * - a request is answered with `Content-Type: application/json` (the spec
 *   lets a server pick JSON or SSE per request); a notification or a
@@ -70,6 +71,35 @@ function hostnameOf(hostHeader) {
 function digest(value) {
 	return createHash("sha256").update(value, "utf8").digest();
 }
+/** Resolve exact descendant routes; no route may replace the MCP endpoint. */
+function resolveRoutes(path, routes) {
+	const resolved = /* @__PURE__ */ new Map();
+	const methods = /* @__PURE__ */ new Set([
+		"GET",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE",
+		"HEAD",
+		"OPTIONS"
+	]);
+	if (routes.length > 0) {
+		let canonical = false;
+		try {
+			canonical = !path.startsWith("//") && new URL(path, "http://localhost").pathname === path;
+		} catch {}
+		if (!canonical) throw new McpServeError("MCP http routes require a canonical endpoint pathname.", { type: "config" });
+	}
+	for (const route of routes) {
+		if (!methods.has(route.method) || !/^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/.test(route.path) || route.path.split("/").some((segment) => segment === "." || segment === "..") || typeof route.handler !== "function") throw new McpServeError("Invalid MCP http route method, path or handler.", { type: "config" });
+		const fullPath = `${path.replace(/\/+$/, "")}${route.path}`;
+		const byMethod = resolved.get(fullPath) ?? /* @__PURE__ */ new Map();
+		if (fullPath === path || byMethod.has(route.method)) throw new McpServeError(`MCP http route "${route.method} ${fullPath}" conflicts.`, { type: "collision" });
+		byMethod.set(route.method, { ...route });
+		resolved.set(fullPath, byMethod);
+	}
+	return resolved;
+}
 /** Normalise a configured origin to `scheme://host[:port]`, or throw a config error. */
 function normalizeOrigin(origin) {
 	try {
@@ -101,9 +131,9 @@ function resolveSettings(transport) {
 	const tokens = auth?.bearer === void 0 ? [] : typeof auth.bearer === "string" ? [auth.bearer] : [...auth.bearer];
 	if (tokens.some((token) => token.length === 0)) throw new McpServeError("MCP http auth.bearer tokens must be non-empty strings.", { type: "config" });
 	if (auth && auth.bearer !== void 0 && tokens.length === 0) throw new McpServeError("MCP http auth.bearer needs at least one token.", { type: "config" });
-	if (auth && tokens.length === 0 && !auth.authorize) throw new McpServeError("MCP http auth needs `bearer` and/or `authorize`.", { type: "config" });
-	const authRequired = tokens.length > 0 || auth?.authorize !== void 0;
-	if (!loopback && !authRequired) throw new McpServeError(`Refusing to serve MCP over http on non-loopback host "${host}" without auth. Set transport.auth ({ bearer } or { authorize }), or bind 127.0.0.1.`, {
+	if (auth && tokens.length === 0 && !auth.authorize && !auth.authenticate) throw new McpServeError("MCP http auth needs `bearer`, `authorize` and/or `authenticate`.", { type: "config" });
+	const authRequired = tokens.length > 0 || auth?.authorize !== void 0 || auth?.authenticate !== void 0;
+	if (!loopback && !authRequired) throw new McpServeError(`Refusing to serve MCP over http on non-loopback host "${host}" without auth. Set transport.auth ({ bearer }, { authorize } or { authenticate }), or bind 127.0.0.1.`, {
 		type: "config",
 		context: { host }
 	});
@@ -116,9 +146,11 @@ function resolveSettings(transport) {
 		drainTimeoutMs,
 		tokenDigests: tokens.map(digest),
 		authorize: auth?.authorize,
+		authenticate: auth?.authenticate,
 		authRequired,
 		allowedOrigins: new Set((transport.allowedOrigins ?? []).map(normalizeOrigin)),
-		allowedHosts: new Set((transport.allowedHosts ?? []).map((name) => hostnameOf(name)))
+		allowedHosts: new Set((transport.allowedHosts ?? []).map((name) => hostnameOf(name))),
+		routes: resolveRoutes(path, transport.routes ?? [])
 	};
 }
 /** Flatten Node's header bag into lower-cased `name → value` strings. */
@@ -174,6 +206,7 @@ function sendEmpty(response, status, headers = {}) {
 async function startHttpServer(transport, dispatch) {
 	const settings = resolveSettings(transport);
 	const shutdown = new AbortController();
+	const requests = new McpServeRequests();
 	const inFlight = /* @__PURE__ */ new Set();
 	let closing;
 	const server = createServer((request, response) => {
@@ -181,7 +214,7 @@ async function startHttpServer(transport, dispatch) {
 			sendRefusal(response, 503, JSON_RPC_SERVER_ERROR, "Server is shutting down.", { connection: "close" });
 			return;
 		}
-		const work = handleRequest(request, response, settings, dispatch, shutdown.signal).catch(() => {
+		const work = handleRequest(request, response, settings, dispatch, shutdown.signal, requests).catch(() => {
 			sendRefusal(response, 500, JSON_RPC_SERVER_ERROR, "Internal server error.");
 		});
 		inFlight.add(work);
@@ -240,13 +273,15 @@ async function startHttpServer(transport, dispatch) {
 	};
 }
 /**
-* Validate and answer one HTTP request: path → Host / Origin → auth →
-* method → headers → body → JSON-RPC dispatch.
+* Validate and answer one HTTP request: Host / Origin → path → auth →
+* method → route handler or MCP headers/body/JSON-RPC dispatch.
 */
-async function handleRequest(request, response, settings, dispatch, signal) {
+async function handleRequest(request, response, settings, dispatch, signal, requests) {
 	const headers = flattenHeaders(request.headers);
 	const method = (request.method ?? "GET").toUpperCase();
-	const path = new URL(request.url ?? "/", "http://localhost").pathname;
+	const url = new URL(request.url ?? "/", "http://localhost");
+	const path = url.pathname;
+	const routes = settings.routes.get(path);
 	if (!hostAllowed(headers.host, settings)) {
 		sendRefusal(response, 403, JSON_RPC_SERVER_ERROR, "Forbidden: Host header not allowed.");
 		return;
@@ -255,7 +290,7 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 		sendRefusal(response, 403, JSON_RPC_SERVER_ERROR, "Forbidden: Origin not allowed.");
 		return;
 	}
-	if (path !== settings.path) {
+	if (path !== settings.path && !routes) {
 		sendRefusal(response, 404, JSON_RPC_SERVER_ERROR, "Not found.");
 		return;
 	}
@@ -265,11 +300,21 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 		headers
 	};
 	if (request.socket.remoteAddress !== void 0) info.remoteAddress = request.socket.remoteAddress;
-	if (!await authorized(info, settings)) {
-		const challenge = settings.tokenDigests.length > 0 ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {};
+	const authentication = await authorized(info, settings);
+	if (!authentication.allowed) {
+		const challenge = settings.tokenDigests.length > 0 || settings.authenticate ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {};
 		sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", challenge);
 		return;
 	}
+	if (routes) {
+		const route = routes.get(method);
+		if (!route) {
+			sendEmpty(response, 405, { allow: [...routes.keys()].sort().join(", ") });
+			return;
+		}
+		await handleRoute(request, response, route, info, url, authentication.principal, signal, settings);
+		return;
+	}
 	if (method !== "POST") {
 		sendEmpty(response, 405, { allow: "POST" });
 		return;
@@ -311,6 +356,7 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 	const id = record.id;
 	if (typeof record.method === "string") {
 		if (typeof id !== "string" && typeof id !== "number") {
+			requests.cancel(record, cancellationScope(info));
 			sendEmpty(response, 202);
 			return;
 		}
@@ -320,10 +366,20 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 			method: record.method
 		};
 		if (record.params !== void 0) rpcRequest.params = record.params;
-		sendJson(response, 200, await dispatch(rpcRequest, {
-			request: info,
-			signal
-		}));
+		const disconnected = new AbortController();
+		const onClose = () => disconnected.abort();
+		response.once("close", onClose);
+		try {
+			const rpcResponse = await requests.run(rpcRequest, {
+				request: info,
+				principal: authentication.principal,
+				signal: AbortSignal.any([signal, disconnected.signal])
+			}, (context) => dispatch(rpcRequest, context), cancellationScope(info));
+			if (rpcResponse === void 0) sendEmpty(response, 202);
+			else sendJson(response, 200, rpcResponse);
+		} finally {
+			response.off("close", onClose);
+		}
 		return;
 	}
 	if ((typeof id === "string" || typeof id === "number") && ("result" in record || "error" in record)) {
@@ -332,6 +388,32 @@ async function handleRequest(request, response, settings, dispatch, signal) {
 	}
 	sendRefusal(response, 400, JSON_RPC_INVALID_REQUEST, "Invalid request: not a JSON-RPC message.");
 }
+/** Run a side route after the shared guards, tracking disconnect and shutdown. */
+async function handleRoute(request, response, route, info, url, principal, shutdown, settings) {
+	const disconnected = new AbortController();
+	const onClose = () => disconnected.abort();
+	response.once("close", onClose);
+	try {
+		const body = await readBody(request, settings.maxBodyBytes);
+		if (body.type === "too-large") {
+			sendRefusal(response, 413, JSON_RPC_SERVER_ERROR, `Request body exceeds ${settings.maxBodyBytes} bytes.`, { connection: "close" });
+			return;
+		}
+		const signal = AbortSignal.any([shutdown, disconnected.signal]);
+		signal.throwIfAborted();
+		const result = await route.handler({
+			request: info,
+			url,
+			principal,
+			body: body.text,
+			signal
+		});
+		if (result.body === void 0 || info.method === "HEAD") sendEmpty(response, result.status ?? 200, result.headers);
+		else sendJson(response, result.status ?? 200, result.body, result.headers);
+	} finally {
+		response.off("close", onClose);
+	}
+}
 /**
 * Host-header check. While bound to loopback only loopback names (plus
 * `allowedHosts`) are accepted, so a DNS-rebound name pointing at
@@ -362,27 +444,50 @@ function originAllowed(origin, settings) {
 	if (settings.allowedOrigins.has(parsed.origin)) return true;
 	return (parsed.protocol === "http:" || parsed.protocol === "https:") && isLoopbackHost(parsed.hostname);
 }
-/**
-* Run the configured auth. Bearer tokens are compared in constant time
-* over SHA-256 digests (equal-length buffers for `timingSafeEqual`), and
-* every configured token is compared so the match position does not leak.
-* An `authorize` hook that throws denies the request.
-*/
 async function authorized(info, settings) {
-	if (!settings.authRequired) return true;
+	if (!settings.authRequired) return { allowed: true };
 	if (settings.tokenDigests.length > 0) {
 		const match = /^Bearer[ \t]+(.+)$/i.exec(info.headers.authorization ?? "");
 		const presented = digest(match?.[1]?.trim() ?? "");
 		let matched = false;
 		for (const expected of settings.tokenDigests) matched = timingSafeEqual(presented, expected) || matched;
-		if (!match || !matched) return false;
+		if (!match || !matched) return { allowed: false };
 	}
-	if (settings.authorize) try {
-		return await settings.authorize(info) === true;
+	try {
+		if (settings.authorize && await settings.authorize(info) !== true) return { allowed: false };
+		if (settings.authenticate) {
+			const principal = await settings.authenticate(info);
+			return principal === void 0 ? { allowed: false } : {
+				allowed: true,
+				principal
+			};
+		}
+		return { allowed: true };
 	} catch {
-		return false;
+		return { allowed: false };
 	}
-	return true;
+}
+/**
+* Stateless HTTP has no connection/session id. Repeat the caller's credential
+* and application headers on notifications; per-message transport headers do
+* not identify a caller. Hash the material rather than retaining secrets as keys.
+*/
+function cancellationScope(info) {
+	const transportHeaders = /* @__PURE__ */ new Set([
+		"host",
+		"origin",
+		"accept",
+		"accept-encoding",
+		"accept-language",
+		"connection",
+		"content-type",
+		"content-length",
+		"transfer-encoding",
+		"mcp-protocol-version",
+		"user-agent"
+	]);
+	const credentials = Object.entries(info.headers).filter(([name]) => !transportHeaders.has(name)).sort(([left], [right]) => left.localeCompare(right));
+	return digest(JSON.stringify([info.remoteAddress, credentials])).toString("hex");
 }
 /** True for `application/json` (any parameters, e.g. `; charset=utf-8`). */
 function isJsonContentType(contentType) {