@warlock.js/ai-tools 5.29.0 → 5.31.0

package/esm/http/http-request.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"http-request.mjs","names":[],"sources":["../../../../../../../ai-tools/src/http/http-request.ts"],"sourcesContent":["import {\n  guardedFetch,\n  OutboundPolicyError,\n  tool,\n  type ToolContract,\n} from \"@warlock.js/ai\";\nimport type {\n  HttpMethod,\n  HttpRequestInput,\n  HttpRequestOptions,\n  HttpRequestResult,\n} from \"../contracts\";\nimport { HttpPolicyError } from \"../errors\";\nimport {\n  objectSchema,\n  optionalStringEnumField,\n  optionalStringRecordField,\n  passthroughField,\n  stringField,\n} from \"../schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"http_request\";\n\n/** Default per-request wall-clock timeout, in milliseconds. */\nconst DEFAULT_TIMEOUT_MS = 15_000;\n\n/** Default hard cap on response-body bytes before truncation. */\nconst DEFAULT_MAX_BYTES = 1_000_000;\n\n/** The full set of HTTP methods, in the order they appear in {@link HttpMethod}. */\nconst ALL_METHODS: readonly HttpMethod[] = [\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"];\n\n/** Methods that conventionally carry no request body — `body` is dropped for these. */\nconst BODYLESS_METHODS: ReadonlySet<HttpMethod> = new Set<HttpMethod>([\"GET\"]);\n\n/**\n * Standard Schema for {@link HttpRequestInput}. `url` is required;\n * `method` is constrained to the canonical HTTP verb set (further\n * narrowed to the tool's `allowMethods` at runtime); `headers` is an\n * optional string-to-string record; `body` is an opaque passthrough the\n * handler serializes based on its runtime type.\n */\nconst httpRequestInputSchema = objectSchema<HttpRequestInput>({\n  method: optionalStringEnumField<HttpMethod>(ALL_METHODS),\n  url: stringField(),\n  headers: optionalStringRecordField(),\n  body: passthroughField(),\n});\n\n/**\n * Resolve the request target. With a `baseUrl` configured the model\n * supplies a path joined against it; otherwise the model's `url` must be\n * an absolute `http(s)` URL. Throws a typed {@link HttpPolicyError} of\n * type `\"invalid-url\"` when the result cannot be parsed or is not an\n * `http`/`https` URL — surfaced as `{ error }` data, never a crash.\n */\nfunction resolveUrl(rawUrl: string, baseUrl: string | undefined): URL {\n  let resolved: URL;\n\n  try {\n    // `new URL(input, base)` joins relative paths against `base` and\n    // ignores `base` when `input` is already absolute, which is exactly\n    // the \"path vs full URL\" behavior the design specifies.\n    resolved = baseUrl !== undefined ? new URL(rawUrl, baseUrl) : new URL(rawUrl);\n  } catch {\n    throw new HttpPolicyError(\n      `http_request could not resolve a valid URL from \"${rawUrl}\"` +\n        (baseUrl !== undefined ? ` against base \"${baseUrl}\".` : \".\"),\n      { type: \"invalid-url\" },\n    );\n  }\n\n  if (resolved.protocol !== \"http:\" && resolved.protocol !== \"https:\") {\n    throw new HttpPolicyError(\n      `http_request only permits http(s) URLs; got \"${resolved.protocol}\".`,\n      { type: \"invalid-url\" },\n    );\n  }\n\n  return resolved;\n}\n\n/**\n * Read a `Response` body, capping at `maxBytes`. Returns the decoded text\n * and whether it was cut off. Streams chunk-by-chunk so an oversized body\n * is abandoned at the cap rather than fully buffered; falls back to\n * `response.text()` (then a post-hoc byte slice) when the body is not a\n * readable stream (e.g. a stubbed `Response` in tests).\n */\nasync function readCappedBody(\n  response: Response,\n  maxBytes: number,\n): Promise<{ text: string; truncated: boolean }> {\n  const body = response.body;\n\n  if (!body) {\n    return { text: \"\", truncated: false };\n  }\n\n  const decoder = new TextDecoder();\n  const reader = body.getReader();\n  let received = 0;\n  let truncated = false;\n  let text = \"\";\n\n  try {\n    for (;;) {\n      const { done, value } = await reader.read();\n\n      if (done) {\n        break;\n      }\n\n      if (!value) {\n        continue;\n      }\n\n      const remaining = maxBytes - received;\n\n      if (value.byteLength > remaining) {\n        text += decoder.decode(value.subarray(0, remaining), { stream: true });\n        received = maxBytes;\n        truncated = true;\n        break;\n      }\n\n      text += decoder.decode(value, { stream: true });\n      received += value.byteLength;\n    }\n  } finally {\n    // Release the lock and abandon any unread remainder.\n    await reader.cancel().catch(() => undefined);\n    reader.releaseLock();\n  }\n\n  text += decoder.decode();\n\n  return { text, truncated };\n}\n\n/**\n * Decide whether a response's `content-type` indicates JSON. Matches\n * `application/json` and the `+json` structured-suffix convention\n * (e.g. `application/vnd.api+json`), case-insensitively.\n */\nfunction isJsonContentType(contentType: string | undefined): boolean {\n  if (!contentType) {\n    return false;\n  }\n\n  const value = contentType.toLowerCase();\n\n  return value.includes(\"application/json\") || value.includes(\"+json\");\n}\n\n/**\n * Build the agent-facing `http_request` tool — a guarded HTTP/REST client\n * over the global `fetch`. The `options` bound what the model may do; the\n * model supplies the per-call URL / method / headers / body within those\n * rails.\n *\n * **Guardrails (all enforced before the network call).**\n * - **Method allowlist** — `allowMethods` (default `[\"GET\"]`). A method\n *   outside the list is rejected with a typed\n *   {@link HttpPolicyError} (`type: \"method-not-allowed\"`).\n * - **Private-network deny (default).** The request — and every redirect\n *   hop — goes through the framework's `guardedFetch` outbound policy,\n *   which refuses private / loopback / link-local / cloud-metadata\n *   addresses (and hostnames resolving to them) unless\n *   `allowPrivateNetwork: true` is set. This applies even when\n *   `allowHosts` is not configured, so a bare `ai.tools.http()` is not\n *   an SSRF primitive (`type: \"host-not-allowed\"`).\n * - **Host allowlist** — when `allowHosts` is set, any other host is\n *   rejected (`type: \"host-not-allowed\"`), an SSRF guardrail; redirect\n *   targets are held to the same allowlist.\n * - **`baseUrl` join** — when configured, the model passes a path that\n *   is resolved against `baseUrl`; otherwise it must pass an absolute\n *   `http(s)` URL. An unresolvable URL is rejected\n *   (`type: \"invalid-url\"`).\n *\n * **Request shaping.** Static `options.headers` are merged under the\n * per-call `headers` (the per-call value wins). An object `body` is\n * JSON-serialized with a `content-type: application/json` default; a\n * string `body` is sent verbatim; `body` is dropped for bodyless methods\n * (`GET`). The call is bounded by `timeoutMs` (default `15_000`) via an\n * `AbortController`, also wired to `ctx.signal` for cooperative\n * cancellation.\n *\n * **Response shaping.** Headers are returned with lower-cased keys. The\n * body is read up to `maxBytes` (default `1_000_000`) and JSON-parsed\n * when the response `content-type` is JSON, otherwise returned as text;\n * `truncated` is `true` when the body was cut off at the cap (a truncated\n * JSON body is returned as the raw partial string, since it can no longer\n * be parsed).\n *\n * **Errors flow as data.** Every guardrail rejection and network failure\n * is thrown inside `execute`; the framework's `tool()` wrapper catches it\n * and surfaces it in the returned `{ error }` field, so the agent reads\n * the failure and self-corrects rather than crashing.\n *\n * @param options - Construction-time policy bounding the tool.\n * @returns A {@link ToolContract} the agent can call as `http_request`.\n *\n * @example\n * const stripe = httpRequestTool({\n *   baseUrl: \"https://api.stripe.com\",\n *   allowHosts: [\"api.stripe.com\"],\n *   allowMethods: [\"GET\", \"POST\"],\n *   headers: { authorization: `Bearer ${process.env.STRIPE_KEY}` },\n * });\n * const { data } = await stripe.invoke({ method: \"GET\", url: \"/v1/charges\" });\n */\nexport function httpRequestTool(\n  options: HttpRequestOptions = {},\n): ToolContract<HttpRequestInput, HttpRequestResult> {\n  const allowMethods = options.allowMethods ?? [\"GET\"];\n  const allowedMethodSet = new Set<HttpMethod>(allowMethods);\n  const allowHostSet = options.allowHosts ? new Set(options.allowHosts) : undefined;\n  const allowPrivateNetwork = options.allowPrivateNetwork ?? false;\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n  const staticHeaders = options.headers;\n\n  return tool<HttpRequestInput, HttpRequestResult>({\n    name: options.name ?? DEFAULT_NAME,\n    description:\n      \"Issue an HTTP request and return the status, response headers, and \" +\n      \"parsed body. Allowed methods and hosts are restricted by the tool's \" +\n      \"configuration; a request outside those rails is rejected before any \" +\n      \"network call. Pass an object body to send JSON, or a string to send \" +\n      \"it verbatim. The response body is JSON-parsed when the content-type \" +\n      \"is JSON, otherwise returned as text, and is capped — `truncated` is \" +\n      \"true when the body was cut off.\",\n    action: (input) => `Requesting ${input.method ?? \"GET\"} ${input.url}`,\n    input: httpRequestInputSchema,\n    async execute(input, ctx) {\n      const method: HttpMethod = input.method ?? \"GET\";\n\n      // 1. Method allowlist — rejected before anything else.\n      if (!allowedMethodSet.has(method)) {\n        throw new HttpPolicyError(\n          `http_request method \"${method}\" is not allowed. ` +\n            `Permitted methods: ${[...allowedMethodSet].join(\", \")}.`,\n          { type: \"method-not-allowed\" },\n        );\n      }\n\n      // 2. URL resolution (baseUrl join when configured).\n      const url = resolveUrl(input.url, options.baseUrl);\n\n      // 3. Host allowlist — SSRF guardrail, before the fetch.\n      if (allowHostSet && !allowHostSet.has(url.hostname)) {\n        throw new HttpPolicyError(\n          `http_request host \"${url.hostname}\" is not in the allowlist. ` +\n            `Permitted hosts: ${[...allowHostSet].join(\", \")}.`,\n          { type: \"host-not-allowed\" },\n        );\n      }\n\n      // 4. Merge headers — static option headers under the per-call ones,\n      //    so a per-call header overrides a static default of the same name.\n      const headers: Record<string, string> = { ...staticHeaders, ...input.headers };\n\n      // 5. Shape the body. Dropped for bodyless methods; objects become\n      //    JSON (with a default content-type); strings are sent verbatim.\n      let body: string | undefined;\n\n      if (!BODYLESS_METHODS.has(method) && input.body !== undefined) {\n        if (typeof input.body === \"string\") {\n          body = input.body;\n        } else {\n          body = JSON.stringify(input.body);\n\n          const hasContentType = Object.keys(headers).some(\n            (key) => key.toLowerCase() === \"content-type\",\n          );\n\n          if (!hasContentType) {\n            headers[\"content-type\"] = \"application/json\";\n          }\n        }\n      }\n\n      // 6. Issue the request through the shared hardened outbound path:\n      //    private-IP deny by default, per-hop redirect re-validation,\n      //    timeout, and the caller's signal — never a raw fetch.\n      let response: Response;\n\n      try {\n        response = await guardedFetch(\n          url.toString(),\n          {\n            allowedSchemes: [\"http\", \"https\"],\n            hostAllowlist: options.allowHosts,\n            denyPrivateIPsAfterDNS: !allowPrivateNetwork,\n            timeoutMs,\n            signal: ctx?.signal,\n          },\n          { method, headers, body },\n        );\n      } catch (cause) {\n        if (cause instanceof OutboundPolicyError) {\n          throw new HttpPolicyError(`http_request blocked: ${cause.message}`, {\n            type: \"host-not-allowed\",\n            cause,\n          });\n        }\n\n        throw cause;\n      }\n\n      // 7. Collect response headers with lower-cased keys.\n      const responseHeaders: Record<string, string> = {};\n      response.headers.forEach((value, key) => {\n        responseHeaders[key.toLowerCase()] = value;\n      });\n\n      // 8. Read the body up to the cap, then parse-or-pass.\n      const { text, truncated } = await readCappedBody(response, maxBytes);\n\n      let parsedBody: unknown = text;\n\n      // A truncated body can no longer be valid JSON, so only attempt a\n      // parse on a complete JSON response; otherwise hand back the raw text.\n      if (!truncated && isJsonContentType(responseHeaders[\"content-type\"]) && text.length > 0) {\n        try {\n          parsedBody = JSON.parse(text);\n        } catch {\n          // Content-type claimed JSON but the body was not — fall back to\n          // the raw text rather than failing the whole call.\n          parsedBody = text;\n        }\n      }\n\n      return {\n        status: response.status,\n        headers: responseHeaders,\n        body: parsedBody,\n        truncated,\n      };\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"http-request.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/http/http-request.ts"],"sourcesContent":["import { guardedFetch, OutboundPolicyError, tool, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  HttpMethod,\n  HttpRequestInput,\n  HttpRequestOptions,\n  HttpRequestResult,\n} from \"../contracts\";\nimport { HttpPolicyError } from \"../errors\";\nimport {\n  objectSchema,\n  optionalStringEnumField,\n  optionalStringRecordField,\n  passthroughField,\n  stringField,\n} from \"../schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"http_request\";\n\n/** Default per-request wall-clock timeout, in milliseconds. */\nconst DEFAULT_TIMEOUT_MS = 15_000;\n\n/** Default hard cap on response-body bytes before truncation. */\nconst DEFAULT_MAX_BYTES = 1_000_000;\n\n/** The full set of HTTP methods, in the order they appear in {@link HttpMethod}. */\nconst ALL_METHODS: readonly HttpMethod[] = [\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"];\n\n/** Methods that conventionally carry no request body — `body` is dropped for these. */\nconst BODYLESS_METHODS: ReadonlySet<HttpMethod> = new Set<HttpMethod>([\"GET\"]);\n\n/**\n * Standard Schema for {@link HttpRequestInput}. `url` is required;\n * `method` is constrained to the canonical HTTP verb set (further\n * narrowed to the tool's `allowMethods` at runtime); `headers` is an\n * optional string-to-string record; `body` is an opaque passthrough the\n * handler serializes based on its runtime type.\n */\nconst httpRequestInputSchema = objectSchema<HttpRequestInput>({\n  method: optionalStringEnumField<HttpMethod>(ALL_METHODS),\n  url: stringField(),\n  headers: optionalStringRecordField(),\n  body: passthroughField(),\n});\n\n/**\n * Resolve the request target. With a `baseUrl` configured the model\n * supplies a path joined against it; otherwise the model's `url` must be\n * an absolute `http(s)` URL. Throws a typed {@link HttpPolicyError} of\n * type `\"invalid-url\"` when the result cannot be parsed or is not an\n * `http`/`https` URL — surfaced as `{ error }` data, never a crash.\n */\nfunction resolveUrl(rawUrl: string, baseUrl: string | undefined): URL {\n  let resolved: URL;\n\n  try {\n    // `new URL(input, base)` joins relative paths against `base` and\n    // ignores `base` when `input` is already absolute, which is exactly\n    // the \"path vs full URL\" behavior the design specifies.\n    resolved = baseUrl !== undefined ? new URL(rawUrl, baseUrl) : new URL(rawUrl);\n  } catch {\n    throw new HttpPolicyError(\n      `http_request could not resolve a valid URL from \"${rawUrl}\"` +\n        (baseUrl !== undefined ? ` against base \"${baseUrl}\".` : \".\"),\n      { type: \"invalid-url\" },\n    );\n  }\n\n  if (resolved.protocol !== \"http:\" && resolved.protocol !== \"https:\") {\n    throw new HttpPolicyError(\n      `http_request only permits http(s) URLs; got \"${resolved.protocol}\".`,\n      { type: \"invalid-url\" },\n    );\n  }\n\n  return resolved;\n}\n\n/**\n * Read a `Response` body, capping at `maxBytes`. Returns the decoded text\n * and whether it was cut off. Streams chunk-by-chunk so an oversized body\n * is abandoned at the cap rather than fully buffered; falls back to\n * `response.text()` (then a post-hoc byte slice) when the body is not a\n * readable stream (e.g. a stubbed `Response` in tests).\n */\nasync function readCappedBody(\n  response: Response,\n  maxBytes: number,\n): Promise<{ text: string; truncated: boolean }> {\n  const body = response.body;\n\n  if (!body) {\n    return { text: \"\", truncated: false };\n  }\n\n  const decoder = new TextDecoder();\n  const reader = body.getReader();\n  let received = 0;\n  let truncated = false;\n  let text = \"\";\n\n  try {\n    for (;;) {\n      const { done, value } = await reader.read();\n\n      if (done) {\n        break;\n      }\n\n      if (!value) {\n        continue;\n      }\n\n      const remaining = maxBytes - received;\n\n      if (value.byteLength > remaining) {\n        text += decoder.decode(value.subarray(0, remaining), { stream: true });\n        received = maxBytes;\n        truncated = true;\n        break;\n      }\n\n      text += decoder.decode(value, { stream: true });\n      received += value.byteLength;\n    }\n  } finally {\n    // Release the lock and abandon any unread remainder.\n    await reader.cancel().catch(() => undefined);\n    reader.releaseLock();\n  }\n\n  text += decoder.decode();\n\n  return { text, truncated };\n}\n\n/**\n * Decide whether a response's `content-type` indicates JSON. Matches\n * `application/json` and the `+json` structured-suffix convention\n * (e.g. `application/vnd.api+json`), case-insensitively.\n */\nfunction isJsonContentType(contentType: string | undefined): boolean {\n  if (!contentType) {\n    return false;\n  }\n\n  const value = contentType.toLowerCase();\n\n  return value.includes(\"application/json\") || value.includes(\"+json\");\n}\n\n/**\n * Build the agent-facing `http_request` tool — a guarded HTTP/REST client\n * over the global `fetch`. The `options` bound what the model may do; the\n * model supplies the per-call URL / method / headers / body within those\n * rails.\n *\n * **Guardrails (all enforced before the network call).**\n * - **Method allowlist** — `allowMethods` (default `[\"GET\"]`). A method\n *   outside the list is rejected with a typed\n *   {@link HttpPolicyError} (`type: \"method-not-allowed\"`).\n * - **Private-network deny (default).** The request — and every redirect\n *   hop — goes through the framework's `guardedFetch` outbound policy,\n *   which refuses private / loopback / link-local / cloud-metadata\n *   addresses (and hostnames resolving to them) unless\n *   `allowPrivateNetwork: true` is set. This applies even when\n *   `allowHosts` is not configured, so a bare `ai.tools.http()` is not\n *   an SSRF primitive (`type: \"host-not-allowed\"`).\n * - **Host allowlist** — when `allowHosts` is set, any other host is\n *   rejected (`type: \"host-not-allowed\"`), an SSRF guardrail; redirect\n *   targets are held to the same allowlist.\n * - **`baseUrl` join** — when configured, the model passes a path that\n *   is resolved against `baseUrl`; otherwise it must pass an absolute\n *   `http(s)` URL. An unresolvable URL is rejected\n *   (`type: \"invalid-url\"`).\n *\n * **Request shaping.** Static `options.headers` are merged under the\n * per-call `headers` (the per-call value wins). An object `body` is\n * JSON-serialized with a `content-type: application/json` default; a\n * string `body` is sent verbatim; `body` is dropped for bodyless methods\n * (`GET`). The call is bounded by `timeoutMs` (default `15_000`) via an\n * `AbortController`, also wired to `ctx.signal` for cooperative\n * cancellation.\n *\n * **Response shaping.** Headers are returned with lower-cased keys. The\n * body is read up to `maxBytes` (default `1_000_000`) and JSON-parsed\n * when the response `content-type` is JSON, otherwise returned as text;\n * `truncated` is `true` when the body was cut off at the cap (a truncated\n * JSON body is returned as the raw partial string, since it can no longer\n * be parsed).\n *\n * **Errors flow as data.** Every guardrail rejection and network failure\n * is thrown inside `execute`; the framework's `tool()` wrapper catches it\n * and surfaces it in the returned `{ error }` field, so the agent reads\n * the failure and self-corrects rather than crashing.\n *\n * @param options - Construction-time policy bounding the tool.\n * @returns A {@link ToolContract} the agent can call as `http_request`.\n *\n * @example\n * const stripe = httpRequestTool({\n *   baseUrl: \"https://api.stripe.com\",\n *   allowHosts: [\"api.stripe.com\"],\n *   allowMethods: [\"GET\", \"POST\"],\n *   headers: { authorization: `Bearer ${process.env.STRIPE_KEY}` },\n * });\n * const { data } = await stripe.invoke({ method: \"GET\", url: \"/v1/charges\" });\n */\nexport function httpRequestTool(\n  options: HttpRequestOptions = {},\n): ToolContract<HttpRequestInput, HttpRequestResult> {\n  const allowMethods = options.allowMethods ?? [\"GET\"];\n  const allowedMethodSet = new Set<HttpMethod>(allowMethods);\n  const allowHostSet = options.allowHosts ? new Set(options.allowHosts) : undefined;\n  const allowPrivateNetwork = options.allowPrivateNetwork ?? false;\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n  const staticHeaders = options.headers;\n\n  return tool<HttpRequestInput, HttpRequestResult>({\n    name: options.name ?? DEFAULT_NAME,\n    description:\n      \"Issue an HTTP request and return the status, response headers, and \" +\n      \"parsed body. Allowed methods and hosts are restricted by the tool's \" +\n      \"configuration; a request outside those rails is rejected before any \" +\n      \"network call. Pass an object body to send JSON, or a string to send \" +\n      \"it verbatim. The response body is JSON-parsed when the content-type \" +\n      \"is JSON, otherwise returned as text, and is capped — `truncated` is \" +\n      \"true when the body was cut off.\",\n    action: (input) => `Requesting ${input.method ?? \"GET\"} ${input.url}`,\n    input: httpRequestInputSchema,\n    async execute(input, ctx) {\n      const method: HttpMethod = input.method ?? \"GET\";\n\n      // 1. Method allowlist — rejected before anything else.\n      if (!allowedMethodSet.has(method)) {\n        throw new HttpPolicyError(\n          `http_request method \"${method}\" is not allowed. ` +\n            `Permitted methods: ${[...allowedMethodSet].join(\", \")}.`,\n          { type: \"method-not-allowed\" },\n        );\n      }\n\n      // 2. URL resolution (baseUrl join when configured).\n      const url = resolveUrl(input.url, options.baseUrl);\n\n      // 3. Host allowlist — SSRF guardrail, before the fetch.\n      if (allowHostSet && !allowHostSet.has(url.hostname)) {\n        throw new HttpPolicyError(\n          `http_request host \"${url.hostname}\" is not in the allowlist. ` +\n            `Permitted hosts: ${[...allowHostSet].join(\", \")}.`,\n          { type: \"host-not-allowed\" },\n        );\n      }\n\n      // 4. Merge headers — static option headers under the per-call ones,\n      //    so a per-call header overrides a static default of the same name.\n      const headers: Record<string, string> = { ...staticHeaders, ...input.headers };\n\n      // 5. Shape the body. Dropped for bodyless methods; objects become\n      //    JSON (with a default content-type); strings are sent verbatim.\n      let body: string | undefined;\n\n      if (!BODYLESS_METHODS.has(method) && input.body !== undefined) {\n        if (typeof input.body === \"string\") {\n          body = input.body;\n        } else {\n          body = JSON.stringify(input.body);\n\n          const hasContentType = Object.keys(headers).some(\n            (key) => key.toLowerCase() === \"content-type\",\n          );\n\n          if (!hasContentType) {\n            headers[\"content-type\"] = \"application/json\";\n          }\n        }\n      }\n\n      // 6. Issue the request through the shared hardened outbound path:\n      //    private-IP deny by default, per-hop redirect re-validation,\n      //    timeout, and the caller's signal — never a raw fetch.\n      let response: Response;\n\n      try {\n        response = await guardedFetch(\n          url.toString(),\n          {\n            allowedSchemes: [\"http\", \"https\"],\n            hostAllowlist: options.allowHosts,\n            denyPrivateIPsAfterDNS: !allowPrivateNetwork,\n            timeoutMs,\n            signal: ctx?.signal,\n          },\n          { method, headers, body },\n        );\n      } catch (cause) {\n        if (cause instanceof OutboundPolicyError) {\n          throw new HttpPolicyError(`http_request blocked: ${cause.message}`, {\n            type: \"host-not-allowed\",\n            cause,\n          });\n        }\n\n        throw cause;\n      }\n\n      // 7. Collect response headers with lower-cased keys.\n      const responseHeaders: Record<string, string> = {};\n      response.headers.forEach((value, key) => {\n        responseHeaders[key.toLowerCase()] = value;\n      });\n\n      // 8. Read the body up to the cap, then parse-or-pass.\n      const { text, truncated } = await readCappedBody(response, maxBytes);\n\n      let parsedBody: unknown = text;\n\n      // A truncated body can no longer be valid JSON, so only attempt a\n      // parse on a complete JSON response; otherwise hand back the raw text.\n      if (!truncated && isJsonContentType(responseHeaders[\"content-type\"]) && text.length > 0) {\n        try {\n          parsedBody = JSON.parse(text);\n        } catch {\n          // Content-type claimed JSON but the body was not — fall back to\n          // the raw text rather than failing the whole call.\n          parsedBody = text;\n        }\n      }\n\n      return {\n        status: response.status,\n        headers: responseHeaders,\n        body: parsedBody,\n        truncated,\n      };\n    },\n  });\n}\n"],"mappings":";;;;;;AAiBA,MAAM,eAAe;;AAGrB,MAAM,qBAAqB;;AAG3B,MAAM,oBAAoB;;AAG1B,MAAM,cAAqC;CAAC;CAAO;CAAQ;CAAO;CAAS;AAAQ;;AAGnF,MAAM,mBAA4C,IAAI,IAAgB,CAAC,KAAK,CAAC;;;;;;;;AAS7E,MAAM,yBAAyB,aAA+B;CAC5D,QAAQ,wBAAoC,WAAW;CACvD,KAAK,YAAY;CACjB,SAAS,0BAA0B;CACnC,MAAM,iBAAiB;AACzB,CAAC;;;;;;;;AASD,SAAS,WAAW,QAAgB,SAAkC;CACpE,IAAI;CAEJ,IAAI;EAIF,WAAW,YAAY,SAAY,IAAI,IAAI,QAAQ,OAAO,IAAI,IAAI,IAAI,MAAM;CAC9E,QAAQ;EACN,MAAM,IAAI,gBACR,oDAAoD,OAAO,MACxD,YAAY,SAAY,kBAAkB,QAAQ,MAAM,MAC3D,EAAE,MAAM,cAAc,CACxB;CACF;CAEA,IAAI,SAAS,aAAa,WAAW,SAAS,aAAa,UACzD,MAAM,IAAI,gBACR,gDAAgD,SAAS,SAAS,KAClE,EAAE,MAAM,cAAc,CACxB;CAGF,OAAO;AACT;;;;;;;;AASA,eAAe,eACb,UACA,UAC+C;CAC/C,MAAM,OAAO,SAAS;CAEtB,IAAI,CAAC,MACH,OAAO;EAAE,MAAM;EAAI,WAAW;CAAM;CAGtC,MAAM,UAAU,IAAI,YAAY;CAChC,MAAM,SAAS,KAAK,UAAU;CAC9B,IAAI,WAAW;CACf,IAAI,YAAY;CAChB,IAAI,OAAO;CAEX,IAAI;EACF,SAAS;GACP,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;GAE1C,IAAI,MACF;GAGF,IAAI,CAAC,OACH;GAGF,MAAM,YAAY,WAAW;GAE7B,IAAI,MAAM,aAAa,WAAW;IAChC,QAAQ,QAAQ,OAAO,MAAM,SAAS,GAAG,SAAS,GAAG,EAAE,QAAQ,KAAK,CAAC;IACrE,WAAW;IACX,YAAY;IACZ;GACF;GAEA,QAAQ,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC;GAC9C,YAAY,MAAM;EACpB;CACF,UAAU;EAER,MAAM,OAAO,OAAO,CAAC,CAAC,YAAY,MAAS;EAC3C,OAAO,YAAY;CACrB;CAEA,QAAQ,QAAQ,OAAO;CAEvB,OAAO;EAAE;EAAM;CAAU;AAC3B;;;;;;AAOA,SAAS,kBAAkB,aAA0C;CACnE,IAAI,CAAC,aACH,OAAO;CAGT,MAAM,QAAQ,YAAY,YAAY;CAEtC,OAAO,MAAM,SAAS,kBAAkB,KAAK,MAAM,SAAS,OAAO;AACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,SAAgB,gBACd,UAA8B,CAAC,GACoB;CACnD,MAAM,eAAe,QAAQ,gBAAgB,CAAC,KAAK;CACnD,MAAM,mBAAmB,IAAI,IAAgB,YAAY;CACzD,MAAM,eAAe,QAAQ,aAAa,IAAI,IAAI,QAAQ,UAAU,IAAI;CACxE,MAAM,sBAAsB,QAAQ,uBAAuB;CAC3D,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,gBAAgB,QAAQ;CAE9B,OAAO,KAA0C;EAC/C,MAAM,QAAQ,QAAQ;EACtB,aACE;EAOF,SAAS,UAAU,cAAc,MAAM,UAAU,MAAM,GAAG,MAAM;EAChE,OAAO;EACP,MAAM,QAAQ,OAAO,KAAK;GACxB,MAAM,SAAqB,MAAM,UAAU;GAG3C,IAAI,CAAC,iBAAiB,IAAI,MAAM,GAC9B,MAAM,IAAI,gBACR,wBAAwB,OAAO,uCACP,CAAC,GAAG,gBAAgB,CAAC,CAAC,KAAK,IAAI,EAAE,IACzD,EAAE,MAAM,qBAAqB,CAC/B;GAIF,MAAM,MAAM,WAAW,MAAM,KAAK,QAAQ,OAAO;GAGjD,IAAI,gBAAgB,CAAC,aAAa,IAAI,IAAI,QAAQ,GAChD,MAAM,IAAI,gBACR,sBAAsB,IAAI,SAAS,8CACb,CAAC,GAAG,YAAY,CAAC,CAAC,KAAK,IAAI,EAAE,IACnD,EAAE,MAAM,mBAAmB,CAC7B;GAKF,MAAM,UAAkC;IAAE,GAAG;IAAe,GAAG,MAAM;GAAQ;GAI7E,IAAI;GAEJ,IAAI,CAAC,iBAAiB,IAAI,MAAM,KAAK,MAAM,SAAS,QAClD,IAAI,OAAO,MAAM,SAAS,UACxB,OAAO,MAAM;QACR;IACL,OAAO,KAAK,UAAU,MAAM,IAAI;IAMhC,IAAI,CAJmB,OAAO,KAAK,OAAO,CAAC,CAAC,MACzC,QAAQ,IAAI,YAAY,MAAM,cAGf,GAChB,QAAQ,kBAAkB;GAE9B;GAMF,IAAI;GAEJ,IAAI;IACF,WAAW,MAAM,aACf,IAAI,SAAS,GACb;KACE,gBAAgB,CAAC,QAAQ,OAAO;KAChC,eAAe,QAAQ;KACvB,wBAAwB,CAAC;KACzB;KACA,QAAQ,KAAK;IACf,GACA;KAAE;KAAQ;KAAS;IAAK,CAC1B;GACF,SAAS,OAAO;IACd,IAAI,iBAAiB,qBACnB,MAAM,IAAI,gBAAgB,yBAAyB,MAAM,WAAW;KAClE,MAAM;KACN;IACF,CAAC;IAGH,MAAM;GACR;GAGA,MAAM,kBAA0C,CAAC;GACjD,SAAS,QAAQ,SAAS,OAAO,QAAQ;IACvC,gBAAgB,IAAI,YAAY,KAAK;GACvC,CAAC;GAGD,MAAM,EAAE,MAAM,cAAc,MAAM,eAAe,UAAU,QAAQ;GAEnE,IAAI,aAAsB;GAI1B,IAAI,CAAC,aAAa,kBAAkB,gBAAgB,eAAe,KAAK,KAAK,SAAS,GACpF,IAAI;IACF,aAAa,KAAK,MAAM,IAAI;GAC9B,QAAQ;IAGN,aAAa;GACf;GAGF,OAAO;IACL,QAAQ,SAAS;IACjB,SAAS;IACT,MAAM;IACN;GACF;EACF;CACF,CAAC;AACH"}

package/esm/index.d.mts

@@ -1,8 +1,10 @@
 import { FetchUrlExtract, FetchUrlInput, FetchUrlOptions, FetchUrlResult, SearchProvider, WebSearchInput, WebSearchOptions, WebSearchResult, WebSearchResultItem } from "./contracts/web.type.mjs";
 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, McpServeOptions, McpServeSource, McpServeTransport, McpServer, McpToolCallResult, McpToolDescriptor, McpTransport } from "./contracts/mcp.type.mjs";
-import { createServeHandler, serve } from "./mcp/serve.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 { McpServeRequestHandler, createServeHandler, serve } from "./mcp/serve.mjs";
+import { SUPPORTED_PROTOCOL_VERSIONS } from "./mcp/protocol.mjs";
 import { jsonSchemaToStandard } from "./mcp/json-schema-to-standard.mjs";
 import { McpTransportClient } from "./mcp/transport.type.mjs";
 import { JsonRpcClientHandle, createJsonRpcClient, createTransport } from "./mcp/transport.mjs";
@@ -13,7 +15,7 @@ import { fetchUrlTool } from "./web/fetch-url.mjs";
 import { httpRequestTool } from "./http/http-request.mjs";
 import { calculatorTool } from "./utility/calculator.mjs";
 import { dateTimeTool } from "./utility/date-time.mjs";
-import { CalculatorError, CalculatorErrorOptions, CalculatorFailure, DateTimeError, DateTimeErrorOptions, DateTimeFailure, HttpPolicyError, HttpPolicyErrorOptions, HttpPolicyFailure, 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 McpServeOptions, type McpServeSource, type McpServeTransport, type McpServer, type McpToolCallResult, type McpToolDescriptor, type McpTransport, type McpTransportClient, McpTransportError, type McpTransportErrorOptions, type McpTransportFailure, type SearchProvider, type WebSearchInput, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, WebToolError, type WebToolErrorOptions, type WebToolFailure, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, serve, webSearchTool };
+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 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, serve, webSearchTool };
 import "./mcp/index.mjs";
 import "./register.mjs";

package/esm/index.mjs

@@ -1,7 +1,8 @@
-import { CalculatorError, DateTimeError, HttpPolicyError, McpTransportError, WebToolError } from "./errors.mjs";
+import { CalculatorError, DateTimeError, HttpPolicyError, McpServeError, McpTransportError, WebToolError } from "./errors.mjs";
 import { httpRequestTool } from "./http/http-request.mjs";
 import { jsonSchemaToStandard } from "./mcp/json-schema-to-standard.mjs";
 import { createJsonRpcClient, createTransport } from "./mcp/transport.mjs";
+import { SUPPORTED_PROTOCOL_VERSIONS } from "./mcp/protocol.mjs";
 import { createServeHandler, serve } from "./mcp/serve.mjs";
 import { mcp } from "./mcp/index.mjs";
 import { calculatorTool } from "./utility/calculator.mjs";
@@ -12,4 +13,4 @@ import "./register.mjs";
 import "./web/index.mjs";
 import "./utility/index.mjs";
 
-export { CalculatorError, DateTimeError, HttpPolicyError, McpTransportError, WebToolError, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, serve, webSearchTool };
+export { CalculatorError, DateTimeError, HttpPolicyError, McpServeError, McpTransportError, SUPPORTED_PROTOCOL_VERSIONS, WebToolError, calculatorTool, createJsonRpcClient, createServeHandler, createTransport, dateTimeTool, fetchUrlTool, httpRequestTool, jsonSchemaToStandard, mcp, serve, webSearchTool };

package/esm/mcp/client.mjs

@@ -3,7 +3,7 @@ import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
 import { createJsonRpcClient } from "./transport.mjs";
 import { tool } from "@warlock.js/ai";
 
-//#region ../ai-tools/src/mcp/client.ts
+//#region ../../packages/ai-tools/src/mcp/client.ts
 /** Default per-call timeout for `tools/call`. */
 const DEFAULT_CALL_TIMEOUT_MS = 3e4;
 /** The MCP protocol version this client advertises in `initialize`. */
@@ -20,8 +20,24 @@ const PROTOCOL_VERSION = "2025-06-18";
 var McpClientImpl = class {
 	constructor(source, options = {}) {
 		this.initialized = false;
+		this.onAbort = () => {
+			this.close().catch(() => void 0);
+		};
 		this.rpc = createJsonRpcClient(source);
 		this.options = options;
+		const signal = options.signal;
+		if (signal?.aborted) this.onAbort();
+		else signal?.addEventListener("abort", this.onAbort, { once: true });
+	}
+	/**
+	* Reject with a typed `"closed"` error once the client was closed or its
+	* `signal` aborted, so no request is sent on a dead transport.
+	*/
+	assertOpen(method) {
+		if (this.closing || this.options.signal?.aborted) throw new McpTransportError(`MCP client is closed; "${method}" was not sent.`, {
+			type: "closed",
+			method
+		});
 	}
 	/**
 	* Run the MCP `initialize` handshake exactly once, then send the
@@ -31,6 +47,7 @@ var McpClientImpl = class {
 	*/
 	async handshake() {
 		if (this.initialized) return;
+		this.assertOpen("initialize");
 		try {
 			await this.rpc.call("initialize", {
 				protocolVersion: PROTOCOL_VERSION,
@@ -39,7 +56,7 @@ var McpClientImpl = class {
 					name: "@warlock.js/ai-tools",
 					version: "4.4.0"
 				}
-			});
+			}, { signal: this.options.signal });
 			await this.rpc.notify("notifications/initialized");
 		} catch (cause) {
 			if (cause instanceof McpTransportError) throw cause;
@@ -68,7 +85,8 @@ var McpClientImpl = class {
 	*/
 	async listAndAdapt() {
 		await this.handshake();
-		const descriptors = (await this.rpc.call("tools/list")).tools ?? [];
+		this.assertOpen("tools/list");
+		const descriptors = (await this.rpc.call("tools/list", void 0, { signal: this.options.signal })).tools ?? [];
 		const filter = this.options.filter;
 		return (filter ? descriptors.filter((d) => filter(d.name)) : descriptors).map((descriptor) => this.adapt(descriptor));
 	}
@@ -89,11 +107,12 @@ var McpClientImpl = class {
 			description: descriptor.description ?? `Invoke the remote MCP tool "${remoteName}".`,
 			input,
 			execute: async (args, ctx) => {
+				this.assertOpen("tools/call");
 				const result = await this.rpc.call("tools/call", {
 					name: remoteName,
 					arguments: args ?? {}
 				}, {
-					signal: ctx?.signal,
+					signal: combineSignals(ctx?.signal, this.options.signal),
 					timeoutMs
 				});
 				if (result.isError) throw new McpTransportError(`MCP tool "${remoteName}" returned an error: ${unwrapContent(result.content)}`, {
@@ -105,10 +124,20 @@ var McpClientImpl = class {
 		});
 	}
 	close() {
-		return this.rpc.close();
+		this.options.signal?.removeEventListener("abort", this.onAbort);
+		this.closing ??= this.rpc.close();
+		return this.closing;
 	}
 };
 /**
+* The signal a `tools/call` honors: the per-call `ctx.signal`, the
+* client-level `options.signal`, both (whichever aborts first), or none.
+*/
+function combineSignals(callSignal, clientSignal) {
+	if (!callSignal || !clientSignal) return callSignal ?? clientSignal;
+	return AbortSignal.any([callSignal, clientSignal]);
+}
+/**
 * Flatten an MCP `tools/call` result's content blocks into the value a
 * tool returns. Text blocks are concatenated; a single block whose text is
 * valid JSON is parsed so structured tool output flows back as an object
@@ -180,7 +209,8 @@ function tryParseJson(text) {
 * @param server - The transport config (`{ type: "stdio" }` /
 *   `{ type: "http" }`). A pre-built transport client may be injected for
 *   testing.
-* @param options - Prefix / filter / per-call timeout.
+* @param options - Prefix / filter / per-call timeout, and a `signal` that
+*   closes the client when it aborts.
 * @returns An {@link McpClient} handle.
 *
 * @example

package/esm/mcp/client.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"client.mjs","names":[],"sources":["../../../../../../../ai-tools/src/mcp/client.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  McpClient,\n  McpClientOptions,\n  McpContentBlock,\n  McpToolCallResult,\n  McpToolDescriptor,\n  McpTransport,\n} from \"../contracts\";\nimport { McpTransportError } from \"../errors\";\nimport { jsonSchemaToStandard } from \"./json-schema-to-standard\";\nimport { createJsonRpcClient, type JsonRpcClientHandle } from \"./transport\";\nimport type { McpTransportClient } from \"./transport.type\";\n\n/** Default per-call timeout for `tools/call`. */\nconst DEFAULT_CALL_TIMEOUT_MS = 30_000;\n\n/** The MCP protocol version this client advertises in `initialize`. */\nconst PROTOCOL_VERSION = \"2025-06-18\";\n\n/** The `tools/list` response slice we read. */\ninterface ToolsListResult {\n  tools?: McpToolDescriptor[];\n}\n\n/**\n * The internal {@link McpClient} implementation. Owns one JSON-RPC client\n * over a transport, runs the `initialize` handshake on first use, lists\n * the server's tools, and adapts each into a {@link ToolContract} whose\n * `execute` issues `tools/call`. The adapted contracts are cached after\n * the first `tools()` so repeat calls don't re-handshake.\n *\n * Constructed via {@link mcp}; the class itself is internal.\n */\nclass McpClientImpl implements McpClient {\n  /** The JSON-RPC client over the transport. */\n  private readonly rpc: JsonRpcClientHandle;\n\n  /** Construction-time options (prefix / filter / timeout). */\n  private readonly options: McpClientOptions;\n\n  /** Resolved + cached adapted tools, set after the first `tools()`. */\n  private cached: ToolContract[] | undefined;\n\n  /** In-flight `tools()` so concurrent callers share one handshake. */\n  private pending: Promise<ToolContract[]> | undefined;\n\n  /** Flipped once the handshake completes so we only do it once. */\n  private initialized = false;\n\n  public constructor(\n    source: McpTransport | McpTransportClient,\n    options: McpClientOptions = {},\n  ) {\n    this.rpc = createJsonRpcClient(source);\n    this.options = options;\n  }\n\n  /**\n   * Run the MCP `initialize` handshake exactly once, then send the\n   * `notifications/initialized` notification the protocol requires before\n   * any other request. Wraps a handshake failure as a typed\n   * {@link McpTransportError} of type `\"connect\"`.\n   */\n  private async handshake(): Promise<void> {\n    if (this.initialized) {\n      return;\n    }\n\n    try {\n      await this.rpc.call(\"initialize\", {\n        protocolVersion: PROTOCOL_VERSION,\n        capabilities: {},\n        clientInfo: { name: \"@warlock.js/ai-tools\", version: \"4.4.0\" },\n      });\n\n      await this.rpc.notify(\"notifications/initialized\");\n    } catch (cause) {\n      if (cause instanceof McpTransportError) {\n        throw cause;\n      }\n\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(`MCP initialize handshake failed: ${message}`, {\n        type: \"connect\",\n        method: \"initialize\",\n        cause,\n      });\n    }\n\n    this.initialized = true;\n  }\n\n  public tools(): Promise<ToolContract[]> {\n    if (this.cached) {\n      return Promise.resolve(this.cached);\n    }\n\n    if (this.pending) {\n      return this.pending;\n    }\n\n    this.pending = this.listAndAdapt()\n      .then((tools) => {\n        this.cached = tools;\n\n        return tools;\n      })\n      .finally(() => {\n        this.pending = undefined;\n      });\n\n    return this.pending;\n  }\n\n  /**\n   * Handshake, `tools/list`, and adapt each descriptor into a\n   * {@link ToolContract}, applying the `filter` and `namePrefix` options.\n   */\n  private async listAndAdapt(): Promise<ToolContract[]> {\n    await this.handshake();\n\n    const result = await this.rpc.call<ToolsListResult>(\"tools/list\");\n    const descriptors = result.tools ?? [];\n\n    const filter = this.options.filter;\n    const selected = filter ? descriptors.filter((d) => filter(d.name)) : descriptors;\n\n    return selected.map((descriptor) => this.adapt(descriptor));\n  }\n\n  /**\n   * Adapt one remote tool descriptor into a {@link ToolContract}: build\n   * the input schema from its JSON Schema via {@link jsonSchemaToStandard},\n   * prefix the name, and route `execute` through a `tools/call` that\n   * honors `ctx.signal`, unwraps the content blocks, and throws on an\n   * `isError` result so `tool()` wraps it.\n   */\n  private adapt(descriptor: McpToolDescriptor): ToolContract {\n    const prefixedName = `${this.options.namePrefix ?? \"\"}${descriptor.name}`;\n    const remoteName = descriptor.name;\n    const timeoutMs = this.options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;\n    const input = jsonSchemaToStandard(descriptor.inputSchema);\n\n    return tool<unknown, unknown>({\n      name: prefixedName,\n      description:\n        descriptor.description ?? `Invoke the remote MCP tool \"${remoteName}\".`,\n      input,\n      execute: async (args, ctx) => {\n        const result = await this.rpc.call<McpToolCallResult>(\n          \"tools/call\",\n          { name: remoteName, arguments: args ?? {} },\n          { signal: ctx?.signal, timeoutMs },\n        );\n\n        // An `isError` result is a tool-level failure — throw it so the\n        // surrounding `tool()` wraps it as a `ToolExecutionError` and the\n        // agent reads it as `{ error }` data and self-corrects.\n        if (result.isError) {\n          throw new McpTransportError(\n            `MCP tool \"${remoteName}\" returned an error: ${unwrapContent(result.content)}`,\n            { type: \"protocol\", method: \"tools/call\" },\n          );\n        }\n\n        return unwrapResult(result.content);\n      },\n    });\n  }\n\n  public close(): Promise<void> {\n    return this.rpc.close();\n  }\n}\n\n/**\n * Flatten an MCP `tools/call` result's content blocks into the value a\n * tool returns. Text blocks are concatenated; a single block whose text is\n * valid JSON is parsed so structured tool output flows back as an object\n * rather than a string. Non-text blocks are preserved as `type`-tagged\n * objects (MCP's wire `type` is kept; any inbound `kind` is normalized to\n * `type`).\n */\nfunction unwrapResult(content: McpContentBlock[] | undefined): unknown {\n  const blocks = content ?? [];\n\n  // The overwhelmingly common case: a single text block. Parse JSON when\n  // it is one, so structured results come back typed; otherwise the string.\n  if (blocks.length === 1 && blocks[0].type === \"text\") {\n    const text = blocks[0].text ?? \"\";\n\n    return tryParseJson(text);\n  }\n\n  // Multiple / mixed blocks: return a normalized array, each tagged by\n  // `type` (never `kind`).\n  return blocks.map((block) => normalizeBlock(block));\n}\n\n/**\n * Render content blocks to a short human string for error messages — the\n * concatenated text of every text block.\n */\nfunction unwrapContent(content: McpContentBlock[] | undefined): string {\n  return (content ?? [])\n    .filter((block) => block.type === \"text\" && typeof block.text === \"string\")\n    .map((block) => block.text)\n    .join(\" \")\n    .trim();\n}\n\n/**\n * Normalize one content block onto our `type`-only shape: translate an\n * inbound `kind` discriminator to `type` (and strip `kind`) so the value a\n * tool returns never carries MCP's `kind` vocabulary.\n */\nfunction normalizeBlock(block: McpContentBlock): Record<string, unknown> {\n  const { kind, ...rest } = block as McpContentBlock & { kind?: string };\n  const type = block.type ?? kind ?? \"unknown\";\n\n  return { ...rest, type };\n}\n\n/**\n * Parse a string as JSON, returning the parsed value on success or the\n * original string when it is not JSON — so a plain-text tool result stays\n * a string while a JSON tool result becomes an object.\n */\nfunction tryParseJson(text: string): unknown {\n  const trimmed = text.trim();\n\n  if (!trimmed) {\n    return text;\n  }\n\n  const first = trimmed[0];\n\n  // Only attempt a parse for plausibly-structured payloads, so a bare\n  // sentence isn't mangled by a lenient parse.\n  if (first !== \"{\" && first !== \"[\") {\n    return text;\n  }\n\n  try {\n    return JSON.parse(trimmed);\n  } catch {\n    return text;\n  }\n}\n\n/**\n * Connect to an external MCP server and adapt its tools as agent tools\n * (Direction A: server → local agent tools).\n *\n * Opens the transport lazily and exposes {@link McpClient.tools}, which on\n * first call runs the `initialize` handshake, lists the server's tools via\n * `tools/list`, and maps each into a {@link ToolContract}:\n * - **input schema** — the remote tool's JSON Schema is wrapped as a\n *   Standard Schema via {@link jsonSchemaToStandard} (Ajv-backed, an\n *   optional peer);\n * - **execute** — issues `tools/call` honoring `ctx.signal` and the\n *   configured `timeoutMs`, unwraps the result content, and throws on an\n *   `isError` result so the `tool()` wrapper surfaces it as `{ error }`;\n * - **name** — prefixed with `options.namePrefix` to avoid local\n *   collisions; only tools passing `options.filter` are adapted.\n *\n * The adapted contracts are cached after the first `tools()` call, so the\n * handshake + list happen exactly once. The returned contracts drop\n * straight into `ai.agent({ tools: [...] })`.\n *\n * @param server - The transport config (`{ type: \"stdio\" }` /\n *   `{ type: \"http\" }`). A pre-built transport client may be injected for\n *   testing.\n * @param options - Prefix / filter / per-call timeout.\n * @returns An {@link McpClient} handle.\n *\n * @example\n * const github = mcp(\n *   { type: \"stdio\", command: \"npx\", args: [\"-y\", \"@modelcontextprotocol/server-github\"] },\n *   { namePrefix: \"github.\" },\n * );\n * const dev = ai.agent({ model, tools: [...(await github.tools())] });\n */\nexport function mcp(\n  server: McpTransport | McpTransportClient,\n  options?: McpClientOptions,\n): McpClient {\n  return new McpClientImpl(server, options);\n}\n"],"mappings":"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"}
+{"version":3,"file":"client.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/client.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  McpClient,\n  McpClientOptions,\n  McpContentBlock,\n  McpToolCallResult,\n  McpToolDescriptor,\n  McpTransport,\n} from \"../contracts\";\nimport { McpTransportError } from \"../errors\";\nimport { jsonSchemaToStandard } from \"./json-schema-to-standard\";\nimport { createJsonRpcClient, type JsonRpcClientHandle } from \"./transport\";\nimport type { McpTransportClient } from \"./transport.type\";\n\n/** Default per-call timeout for `tools/call`. */\nconst DEFAULT_CALL_TIMEOUT_MS = 30_000;\n\n/** The MCP protocol version this client advertises in `initialize`. */\nconst PROTOCOL_VERSION = \"2025-06-18\";\n\n/** The `tools/list` response slice we read. */\ninterface ToolsListResult {\n  tools?: McpToolDescriptor[];\n}\n\n/**\n * The internal {@link McpClient} implementation. Owns one JSON-RPC client\n * over a transport, runs the `initialize` handshake on first use, lists\n * the server's tools, and adapts each into a {@link ToolContract} whose\n * `execute` issues `tools/call`. The adapted contracts are cached after\n * the first `tools()` so repeat calls don't re-handshake.\n *\n * Constructed via {@link mcp}; the class itself is internal.\n */\nclass McpClientImpl implements McpClient {\n  /** The JSON-RPC client over the transport. */\n  private readonly rpc: JsonRpcClientHandle;\n\n  /** Construction-time options (prefix / filter / timeout). */\n  private readonly options: McpClientOptions;\n\n  /** Resolved + cached adapted tools, set after the first `tools()`. */\n  private cached: ToolContract[] | undefined;\n\n  /** In-flight `tools()` so concurrent callers share one handshake. */\n  private pending: Promise<ToolContract[]> | undefined;\n\n  /** Flipped once the handshake completes so we only do it once. */\n  private initialized = false;\n\n  /** The in-flight / settled `close()`, so closing is idempotent. */\n  private closing: Promise<void> | undefined;\n\n  /** Closes the client when `options.signal` aborts. */\n  private readonly onAbort = (): void => {\n    void this.close().catch(() => undefined);\n  };\n\n  public constructor(source: McpTransport | McpTransportClient, options: McpClientOptions = {}) {\n    this.rpc = createJsonRpcClient(source);\n    this.options = options;\n\n    const signal = options.signal;\n\n    if (signal?.aborted) {\n      this.onAbort();\n    } else {\n      signal?.addEventListener(\"abort\", this.onAbort, { once: true });\n    }\n  }\n\n  /**\n   * Reject with a typed `\"closed\"` error once the client was closed or its\n   * `signal` aborted, so no request is sent on a dead transport.\n   */\n  private assertOpen(method: string): void {\n    if (this.closing || this.options.signal?.aborted) {\n      throw new McpTransportError(`MCP client is closed; \"${method}\" was not sent.`, {\n        type: \"closed\",\n        method,\n      });\n    }\n  }\n\n  /**\n   * Run the MCP `initialize` handshake exactly once, then send the\n   * `notifications/initialized` notification the protocol requires before\n   * any other request. Wraps a handshake failure as a typed\n   * {@link McpTransportError} of type `\"connect\"`.\n   */\n  private async handshake(): Promise<void> {\n    if (this.initialized) {\n      return;\n    }\n\n    this.assertOpen(\"initialize\");\n\n    try {\n      await this.rpc.call(\n        \"initialize\",\n        {\n          protocolVersion: PROTOCOL_VERSION,\n          capabilities: {},\n          clientInfo: { name: \"@warlock.js/ai-tools\", version: \"4.4.0\" },\n        },\n        { signal: this.options.signal },\n      );\n\n      await this.rpc.notify(\"notifications/initialized\");\n    } catch (cause) {\n      if (cause instanceof McpTransportError) {\n        throw cause;\n      }\n\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(`MCP initialize handshake failed: ${message}`, {\n        type: \"connect\",\n        method: \"initialize\",\n        cause,\n      });\n    }\n\n    this.initialized = true;\n  }\n\n  public tools(): Promise<ToolContract[]> {\n    if (this.cached) {\n      return Promise.resolve(this.cached);\n    }\n\n    if (this.pending) {\n      return this.pending;\n    }\n\n    this.pending = this.listAndAdapt()\n      .then((tools) => {\n        this.cached = tools;\n\n        return tools;\n      })\n      .finally(() => {\n        this.pending = undefined;\n      });\n\n    return this.pending;\n  }\n\n  /**\n   * Handshake, `tools/list`, and adapt each descriptor into a\n   * {@link ToolContract}, applying the `filter` and `namePrefix` options.\n   */\n  private async listAndAdapt(): Promise<ToolContract[]> {\n    await this.handshake();\n\n    this.assertOpen(\"tools/list\");\n\n    const result = await this.rpc.call<ToolsListResult>(\"tools/list\", undefined, {\n      signal: this.options.signal,\n    });\n    const descriptors = result.tools ?? [];\n\n    const filter = this.options.filter;\n    const selected = filter ? descriptors.filter((d) => filter(d.name)) : descriptors;\n\n    return selected.map((descriptor) => this.adapt(descriptor));\n  }\n\n  /**\n   * Adapt one remote tool descriptor into a {@link ToolContract}: build\n   * the input schema from its JSON Schema via {@link jsonSchemaToStandard},\n   * prefix the name, and route `execute` through a `tools/call` that\n   * honors `ctx.signal`, unwraps the content blocks, and throws on an\n   * `isError` result so `tool()` wraps it.\n   */\n  private adapt(descriptor: McpToolDescriptor): ToolContract {\n    const prefixedName = `${this.options.namePrefix ?? \"\"}${descriptor.name}`;\n    const remoteName = descriptor.name;\n    const timeoutMs = this.options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;\n    const input = jsonSchemaToStandard(descriptor.inputSchema);\n\n    return tool<unknown, unknown>({\n      name: prefixedName,\n      description: descriptor.description ?? `Invoke the remote MCP tool \"${remoteName}\".`,\n      input,\n      execute: async (args, ctx) => {\n        this.assertOpen(\"tools/call\");\n\n        const result = await this.rpc.call<McpToolCallResult>(\n          \"tools/call\",\n          { name: remoteName, arguments: args ?? {} },\n          { signal: combineSignals(ctx?.signal, this.options.signal), timeoutMs },\n        );\n\n        // An `isError` result is a tool-level failure — throw it so the\n        // surrounding `tool()` wraps it as a `ToolExecutionError` and the\n        // agent reads it as `{ error }` data and self-corrects.\n        if (result.isError) {\n          throw new McpTransportError(\n            `MCP tool \"${remoteName}\" returned an error: ${unwrapContent(result.content)}`,\n            { type: \"protocol\", method: \"tools/call\" },\n          );\n        }\n\n        return unwrapResult(result.content);\n      },\n    });\n  }\n\n  public close(): Promise<void> {\n    this.options.signal?.removeEventListener(\"abort\", this.onAbort);\n    this.closing ??= this.rpc.close();\n\n    return this.closing;\n  }\n}\n\n/**\n * The signal a `tools/call` honors: the per-call `ctx.signal`, the\n * client-level `options.signal`, both (whichever aborts first), or none.\n */\nfunction combineSignals(\n  callSignal: AbortSignal | undefined,\n  clientSignal: AbortSignal | undefined,\n): AbortSignal | undefined {\n  if (!callSignal || !clientSignal) {\n    return callSignal ?? clientSignal;\n  }\n\n  return AbortSignal.any([callSignal, clientSignal]);\n}\n\n/**\n * Flatten an MCP `tools/call` result's content blocks into the value a\n * tool returns. Text blocks are concatenated; a single block whose text is\n * valid JSON is parsed so structured tool output flows back as an object\n * rather than a string. Non-text blocks are preserved as `type`-tagged\n * objects (MCP's wire `type` is kept; any inbound `kind` is normalized to\n * `type`).\n */\nfunction unwrapResult(content: McpContentBlock[] | undefined): unknown {\n  const blocks = content ?? [];\n\n  // The overwhelmingly common case: a single text block. Parse JSON when\n  // it is one, so structured results come back typed; otherwise the string.\n  if (blocks.length === 1 && blocks[0].type === \"text\") {\n    const text = blocks[0].text ?? \"\";\n\n    return tryParseJson(text);\n  }\n\n  // Multiple / mixed blocks: return a normalized array, each tagged by\n  // `type` (never `kind`).\n  return blocks.map((block) => normalizeBlock(block));\n}\n\n/**\n * Render content blocks to a short human string for error messages — the\n * concatenated text of every text block.\n */\nfunction unwrapContent(content: McpContentBlock[] | undefined): string {\n  return (content ?? [])\n    .filter((block) => block.type === \"text\" && typeof block.text === \"string\")\n    .map((block) => block.text)\n    .join(\" \")\n    .trim();\n}\n\n/**\n * Normalize one content block onto our `type`-only shape: translate an\n * inbound `kind` discriminator to `type` (and strip `kind`) so the value a\n * tool returns never carries MCP's `kind` vocabulary.\n */\nfunction normalizeBlock(block: McpContentBlock): Record<string, unknown> {\n  const { kind, ...rest } = block as McpContentBlock & { kind?: string };\n  const type = block.type ?? kind ?? \"unknown\";\n\n  return { ...rest, type };\n}\n\n/**\n * Parse a string as JSON, returning the parsed value on success or the\n * original string when it is not JSON — so a plain-text tool result stays\n * a string while a JSON tool result becomes an object.\n */\nfunction tryParseJson(text: string): unknown {\n  const trimmed = text.trim();\n\n  if (!trimmed) {\n    return text;\n  }\n\n  const first = trimmed[0];\n\n  // Only attempt a parse for plausibly-structured payloads, so a bare\n  // sentence isn't mangled by a lenient parse.\n  if (first !== \"{\" && first !== \"[\") {\n    return text;\n  }\n\n  try {\n    return JSON.parse(trimmed);\n  } catch {\n    return text;\n  }\n}\n\n/**\n * Connect to an external MCP server and adapt its tools as agent tools\n * (Direction A: server → local agent tools).\n *\n * Opens the transport lazily and exposes {@link McpClient.tools}, which on\n * first call runs the `initialize` handshake, lists the server's tools via\n * `tools/list`, and maps each into a {@link ToolContract}:\n * - **input schema** — the remote tool's JSON Schema is wrapped as a\n *   Standard Schema via {@link jsonSchemaToStandard} (Ajv-backed, an\n *   optional peer);\n * - **execute** — issues `tools/call` honoring `ctx.signal` and the\n *   configured `timeoutMs`, unwraps the result content, and throws on an\n *   `isError` result so the `tool()` wrapper surfaces it as `{ error }`;\n * - **name** — prefixed with `options.namePrefix` to avoid local\n *   collisions; only tools passing `options.filter` are adapted.\n *\n * The adapted contracts are cached after the first `tools()` call, so the\n * handshake + list happen exactly once. The returned contracts drop\n * straight into `ai.agent({ tools: [...] })`.\n *\n * @param server - The transport config (`{ type: \"stdio\" }` /\n *   `{ type: \"http\" }`). A pre-built transport client may be injected for\n *   testing.\n * @param options - Prefix / filter / per-call timeout, and a `signal` that\n *   closes the client when it aborts.\n * @returns An {@link McpClient} handle.\n *\n * @example\n * const github = mcp(\n *   { type: \"stdio\", command: \"npx\", args: [\"-y\", \"@modelcontextprotocol/server-github\"] },\n *   { namePrefix: \"github.\" },\n * );\n * const dev = ai.agent({ model, tools: [...(await github.tools())] });\n */\nexport function mcp(\n  server: McpTransport | McpTransportClient,\n  options?: McpClientOptions,\n): McpClient {\n  return new McpClientImpl(server, options);\n}\n"],"mappings":"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"}

package/esm/mcp/index.d.mts

@@ -1,10 +1,12 @@
-import { McpClient, McpClientOptions, McpServeOptions, McpServeSource, McpServer, McpTransport } from "../contracts/mcp.type.mjs";
-import { createServeHandler, serve } from "./serve.mjs";
+import { McpClient, McpClientOptions, McpTransport } from "../contracts/mcp.type.mjs";
+import { McpHttpServeHandle, McpHttpServeTransport, McpServeOptions, McpServeSource, McpServer } from "../contracts/mcp-serve.type.mjs";
+import { McpServeRequestHandler, createServeHandler, serve } from "./serve.mjs";
+import { SUPPORTED_PROTOCOL_VERSIONS } from "./protocol.mjs";
 import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
 import { McpTransportClient } from "./transport.type.mjs";
 import { JsonRpcClientHandle, createJsonRpcClient, createTransport } from "./transport.mjs";
 
-//#region ../ai-tools/src/mcp/index.d.ts
+//#region ../../packages/ai-tools/src/mcp/index.d.ts
 /**
  * The callable `ai.mcp` surface — a factory that connects to an external
  * MCP server (Direction A) and also carries `.serve` to expose a local
@@ -17,16 +19,21 @@ interface McpFactory {
    * Connect to an external MCP server and adapt its tools as agent tools.
    *
    * @param server - The transport config (`{ type: "stdio" }` / `{ type: "http" }`).
-   * @param options - Prefix / filter / per-call timeout.
+   * @param options - Prefix / filter / per-call timeout, and a `signal`
+   *   that closes the client (and fails its calls) when it aborts.
    */
   (server: McpTransport, options?: McpClientOptions): McpClient;
   /**
    * Expose a built agent / supervisor / orchestrator (or a literal
-   * `ToolContract[]`) AS an MCP server.
+   * `ToolContract[]`, or named `{ groups }`) AS an MCP server. Over
+   * `{ type: "http" }`, `start()` resolves `{ url, close }`.
    *
    * @param source - The tools to expose.
-   * @param options - Server name, version, transport, and schema dialect.
+   * @param options - Server name, version, transport, schema dialect, resources, prompts.
    */
+  serve(source: McpServeSource, options: McpServeOptions & {
+    transport: McpHttpServeTransport;
+  }): McpServer<McpHttpServeHandle>;
   serve(source: McpServeSource, options: McpServeOptions): McpServer;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../ai-tools/src/mcp/index.ts"],"mappings":";;;;;;;;;AAwBA;;;;;UAAiB,UAAA;EAeD;;;;;;EAAA,CARb,MAAA,EAAQ,YAAA,EAAc,OAAA,GAAU,gBAAA,GAAmB,SAAA;EAAnB;;;;;;;EAQjC,KAAA,CAAM,MAAA,EAAQ,cAAA,EAAgB,OAAA,EAAS,eAAA,GAAkB,SAAA;AAAA;;AAAS;AAWpE;;;;AAGC;;cAHY,GAAA,EAAK,UAGjB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/index.ts"],"mappings":";;;;;;;;;;;AA4BA;;;;;UAAiB,UAAA;EAkBL;;;;;;;EAAA,CAVT,MAAA,EAAQ,YAAA,EAAc,OAAA,GAAU,gBAAA,GAAmB,SAAA;EAac;;;;;;;;EAJlE,KAAA,CACE,MAAA,EAAQ,cAAA,EACR,OAAA,EAAS,eAAA;IAAoB,SAAA,EAAW,qBAAA;EAAA,IACvC,SAAA,CAAU,kBAAA;EACb,KAAA,CAAM,MAAA,EAAQ,cAAA,EAAgB,OAAA,EAAS,eAAA,GAAkB,SAAA;AAAA;;;;;;;;;cAW9C,GAAA,EAAK,UAGjB"}

package/esm/mcp/index.mjs

@@ -1,9 +1,10 @@
 import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
 import { createJsonRpcClient, createTransport } from "./transport.mjs";
 import { mcp as mcp$1 } from "./client.mjs";
+import { SUPPORTED_PROTOCOL_VERSIONS } from "./protocol.mjs";
 import { createServeHandler, serve } from "./serve.mjs";
 
-//#region ../ai-tools/src/mcp/index.ts
+//#region ../../packages/ai-tools/src/mcp/index.ts
 /**
 * The `ai.mcp` factory value: the client factory with `.serve` attached.
 * `Object.assign` keeps `mcp` callable (Direction A) while widening it with

package/esm/mcp/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["mcpClient"],"sources":["../../../../../../../ai-tools/src/mcp/index.ts"],"sourcesContent":["import type {\n  McpClient,\n  McpClientOptions,\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 { 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.\n   */\n  (server: McpTransport, options?: McpClientOptions): McpClient;\n  /**\n   * Expose a built agent / supervisor / orchestrator (or a literal\n   * `ToolContract[]`) AS an MCP server.\n   *\n   * @param source - The tools to expose.\n   * @param options - Server name, version, transport, and schema dialect.\n   */\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":";;;;;;;;;;;;;;AAkDA,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 { 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":";;;;;;;;;;;;;;;AA4DA,MAAa,MAAkB,OAAO,QACnC,QAAsB,YAA0CA,MAAU,QAAQ,OAAO,GAC1F,EAAE,MAAM,CACV"}

package/esm/mcp/json-schema-to-standard.d.mts

@@ -1,6 +1,6 @@
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
-//#region ../ai-tools/src/mcp/json-schema-to-standard.d.ts
+//#region ../../packages/ai-tools/src/mcp/json-schema-to-standard.d.ts
 /**
  * Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose
  * `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`

package/esm/mcp/json-schema-to-standard.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"json-schema-to-standard.d.mts","names":[],"sources":["../../../../../../../ai-tools/src/mcp/json-schema-to-standard.ts"],"mappings":";;;;;AA+JA;;;;;;;;;;;;;;AAE0B;;;;;;;;;;;iBAFV,oBAAA,mBACd,MAAA,EAAQ,MAAA,gCACP,gBAAA,CAAiB,MAAA"}
+{"version":3,"file":"json-schema-to-standard.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/json-schema-to-standard.ts"],"mappings":";;;;;AA+JA;;;;;;;;;;;;;;AAE0B;;;;;;;;;;;iBAFV,oBAAA,mBACd,MAAA,EAAQ,MAAA,gCACP,gBAAA,CAAiB,MAAA"}

package/esm/mcp/json-schema-to-standard.mjs

@@ -1,4 +1,4 @@
-//#region ../ai-tools/src/mcp/json-schema-to-standard.ts
+//#region ../../packages/ai-tools/src/mcp/json-schema-to-standard.ts
 /**
 * The inverse of `@warlock.js/ai`'s `extractJsonSchema` (which goes
 * Standard Schema → JSON Schema). Here we wrap a raw JSON Schema as a

package/esm/mcp/json-schema-to-standard.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"json-schema-to-standard.mjs","names":[],"sources":["../../../../../../../ai-tools/src/mcp/json-schema-to-standard.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * The inverse of `@warlock.js/ai`'s `extractJsonSchema` (which goes\n * Standard Schema → JSON Schema). Here we wrap a raw JSON Schema as a\n * {@link StandardSchemaV1} whose `~standard.validate` runs a lazily-imported\n * Ajv validator — so an MCP server's `inputSchema` (JSON Schema) becomes a\n * `ToolConfig.input` the `tool()` factory can validate against.\n *\n * Ajv is an OPTIONAL peer, lazy-imported on first validate following the\n * langfuse/readability pattern: a missing peer surfaces a curated install\n * string (via the returned issues), never a raw module-resolution stack.\n */\n\n/** The structural vendor template, mirroring `passthroughSchema()`. */\nconst VENDOR = \"warlock-ai\";\n\n// ============================================================\n// Lazily-loaded ajv (OPTIONAL peer)\n// ============================================================\n\n/**\n * Minimal structural view of an Ajv-compiled validator. Ajv is an optional\n * peer that may not be installed, so we model only the surface we touch\n * rather than depending on ajv's own published types. A validator is a\n * callable that returns a boolean and exposes the `errors` it collected.\n */\ninterface AjvValidateFunctionLike {\n  (data: unknown): boolean;\n  errors?: AjvErrorObject[] | null;\n}\n\n/** Minimal structural view of an `Ajv` instance — only `compile`. */\ninterface AjvInstanceLike {\n  compile(schema: Record<string, unknown>): AjvValidateFunctionLike;\n}\n\n/** The `Ajv` constructor, as exposed by both the CJS and ESM builds. */\ntype AjvConstructorLike = new (options?: Record<string, unknown>) => AjvInstanceLike;\n\n/**\n * Minimal structural view of the dynamically imported `ajv` module. Ajv\n * ships its constructor as a `default` export under ESM interop; the older\n * CJS shape exposes the constructor as the module namespace itself, so\n * `default` is optional here and the loader falls back to the namespace.\n */\ninterface AjvModuleLike {\n  default?: AjvConstructorLike;\n}\n\nlet AjvSdk: AjvModuleLike | undefined;\nlet ajvInstance: AjvInstanceLike | undefined;\nlet isAjvAvailable: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\nconst AJV_INSTALL_INSTRUCTIONS = `\nThe MCP client's JSON-Schema validation requires the ajv package.\nInstall it with:\n\n  npm install ajv\n\nOr with your preferred package manager:\n\n  pnpm add ajv\n  yarn add ajv\n`.trim();\n\n/**\n * Settle the lazy import of `ajv` once, concurrency-safe. A bare `catch`\n * flips the availability flag to `false`; the curated install string then\n * surfaces at validate time as a Standard Schema issue, never a raw\n * module-resolution error. The constructed `Ajv` instance is cached and\n * reused for every schema compile.\n */\nasync function loadAjv(): Promise<void> {\n  if (isAjvAvailable !== undefined) {\n    return;\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      AjvSdk = (await import(\"ajv\")) as AjvModuleLike;\n      // Ajv ships as a default export under both CJS and ESM interop; the\n      // older CJS shape exposes the constructor as the namespace itself.\n      const AjvCtor: AjvConstructorLike =\n        AjvSdk.default ?? (AjvSdk as unknown as AjvConstructorLike);\n      ajvInstance = new AjvCtor({ allErrors: true, strict: false });\n      isAjvAvailable = true;\n    } catch {\n      isAjvAvailable = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Compile a JSON Schema with the shared Ajv instance, caching the compiled\n * validator on a closure so repeated validations don't recompile. A schema\n * Ajv itself rejects at compile time (an invalid meta-schema) degrades to\n * an accept-all validator so a malformed remote schema can't wedge the\n * tool — the server, not us, owns its schema's correctness.\n */\nfunction makeCompiler(schema: Record<string, unknown>): () => AjvValidateFunctionLike | undefined {\n  let compiled: AjvValidateFunctionLike | undefined;\n  let attempted = false;\n\n  return () => {\n    if (attempted) {\n      return compiled;\n    }\n\n    attempted = true;\n\n    if (!ajvInstance) {\n      return undefined;\n    }\n\n    try {\n      compiled = ajvInstance.compile(schema);\n    } catch {\n      compiled = undefined;\n    }\n\n    return compiled;\n  };\n}\n\n/**\n * Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose\n * `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`\n * (`{ \"~standard\": { version: 1, vendor, validate } }`) so it drops into\n * `tool({ input })` exactly like a native seal schema.\n *\n * Validation behavior:\n * - **Valid input** → `{ value }` (the input is passed through unchanged;\n *   Ajv validates, it does not transform).\n * - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +\n *   message per failure, so `tool()` produces a `SchemaValidationError`.\n * - **Missing `ajv` peer** → a single issue carrying the curated install\n *   string, surfaced the same way (a developer-facing message in logs).\n * - **No / empty schema** → an accept-all passthrough (an MCP tool may\n *   advertise no `inputSchema`).\n *\n * @param schema - The JSON Schema (an MCP tool's `inputSchema`), or\n *   `undefined` for a no-argument tool.\n * @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.\n *\n * @example\n * const input = jsonSchemaToStandard<{ q: string }>({\n *   type: \"object\",\n *   properties: { q: { type: \"string\" } },\n *   required: [\"q\"],\n * });\n */\nexport function jsonSchemaToStandard<TInput = unknown>(\n  schema: Record<string, unknown> | undefined,\n): StandardSchemaV1<TInput> {\n  // A tool with no schema (or an empty object schema) validates everything\n  // — return an accept-all passthrough and never touch Ajv.\n  if (!schema || Object.keys(schema).length === 0) {\n    return {\n      \"~standard\": {\n        version: 1,\n        vendor: VENDOR,\n        validate: (value: unknown) => ({ value: value as TInput }),\n      },\n    };\n  }\n\n  const compile = makeCompiler(schema);\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: VENDOR,\n      async validate(value: unknown): Promise<StandardSchemaV1.Result<TInput>> {\n        await loadAjv();\n\n        if (!isAjvAvailable) {\n          return {\n            issues: [{ message: AJV_INSTALL_INSTRUCTIONS }],\n          };\n        }\n\n        const validator = compile();\n\n        // A schema Ajv could not compile degrades to accept-all rather\n        // than failing every call — the remote server owns its schema.\n        if (!validator) {\n          return { value: value as TInput };\n        }\n\n        const ok = validator(value);\n\n        if (ok) {\n          return { value: value as TInput };\n        }\n\n        const issues: StandardSchemaV1.Issue[] = (validator.errors ?? []).map((error) => ({\n          message: formatAjvError(error),\n          path: pathFromInstancePath(error.instancePath),\n        }));\n\n        return {\n          issues: issues.length > 0 ? issues : [{ message: \"input failed JSON Schema validation\" }],\n        };\n      },\n    },\n  };\n}\n\n/** A single Ajv error object — narrowed to the fields we read. */\ninterface AjvErrorObject {\n  instancePath?: string;\n  message?: string;\n  keyword?: string;\n}\n\n/**\n * Render one Ajv error into a human-readable issue message. Prefixes the\n * failing instance path (when present) so the model can see WHICH field\n * was wrong, e.g. `/query: must be string`.\n */\nfunction formatAjvError(error: AjvErrorObject): string {\n  const where = error.instancePath ? `${error.instancePath}: ` : \"\";\n  const message = error.message ?? `failed \"${error.keyword ?? \"validation\"}\"`;\n\n  return `${where}${message}`;\n}\n\n/**\n * Convert an Ajv `instancePath` (a JSON-Pointer like `/items/0/name`) into\n * the Standard Schema `path` segment array (`[\"items\", \"0\", \"name\"]`).\n * Empty paths (a root-level failure) become an empty array.\n */\nfunction pathFromInstancePath(instancePath: string | undefined): string[] {\n  if (!instancePath) {\n    return [];\n  }\n\n  return instancePath\n    .split(\"/\")\n    .filter((segment) => segment.length > 0)\n    .map((segment) => segment.replace(/~1/g, \"/\").replace(/~0/g, \"~\"));\n}\n\n/**\n * Reset the cached lazy-import state. Test-only seam so a spec can mock\n * `ajv` as present/absent across cases without module-cache bleed.\n *\n * @internal\n */\nexport function resetAjvCacheForTests(): void {\n  AjvSdk = undefined;\n  ajvInstance = undefined;\n  isAjvAvailable = undefined;\n  loadingPromise = undefined;\n}\n"],"mappings":";;;;;;;;;;;;;AAeA,MAAM,SAAS;AAmCf,IAAI;AACJ,IAAI;AACJ,IAAI;AACJ,IAAI;AAEJ,MAAM,2BAA2B;;;;;;;;;;EAU/B,KAAK;;;;;;;;AASP,eAAe,UAAyB;CACtC,IAAI,mBAAmB,QACrB;CAGF,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GACF,SAAU,MAAM,OAAO;GAKvB,cAAc,KADZ,OAAO,WAAY,QACK;IAAE,WAAW;IAAM,QAAQ;GAAM,CAAC;GAC5D,iBAAiB;EACnB,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;;;AASA,SAAS,aAAa,QAA4E;CAChG,IAAI;CACJ,IAAI,YAAY;CAEhB,aAAa;EACX,IAAI,WACF,OAAO;EAGT,YAAY;EAEZ,IAAI,CAAC,aACH;EAGF,IAAI;GACF,WAAW,YAAY,QAAQ,MAAM;EACvC,QAAQ;GACN,WAAW;EACb;EAEA,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,qBACd,QAC0B;CAG1B,IAAI,CAAC,UAAU,OAAO,KAAK,MAAM,CAAC,CAAC,WAAW,GAC5C,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,WAAoB,EAAS,MAAgB;CAC1D,EACF;CAGF,MAAM,UAAU,aAAa,MAAM;CAEnC,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,MAAM,SAAS,OAA0D;GACvE,MAAM,QAAQ;GAEd,IAAI,CAAC,gBACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAChD;GAGF,MAAM,YAAY,QAAQ;GAI1B,IAAI,CAAC,WACH,OAAO,EAAS,MAAgB;GAKlC,IAFW,UAAU,KAEhB,GACH,OAAO,EAAS,MAAgB;GAGlC,MAAM,UAAoC,UAAU,UAAU,CAAC,EAAC,CAAE,KAAK,WAAW;IAChF,SAAS,eAAe,KAAK;IAC7B,MAAM,qBAAqB,MAAM,YAAY;GAC/C,EAAE;GAEF,OAAO,EACL,QAAQ,OAAO,SAAS,IAAI,SAAS,CAAC,EAAE,SAAS,sCAAsC,CAAC,EAC1F;EACF;CACF,EACF;AACF;;;;;;AAcA,SAAS,eAAe,OAA+B;CAIrD,OAAO,GAHO,MAAM,eAAe,GAAG,MAAM,aAAa,MAAM,KAC/C,MAAM,WAAW,WAAW,MAAM,WAAW,aAAa;AAG5E;;;;;;AAOA,SAAS,qBAAqB,cAA4C;CACxE,IAAI,CAAC,cACH,OAAO,CAAC;CAGV,OAAO,aACJ,MAAM,GAAG,CAAC,CACV,QAAQ,YAAY,QAAQ,SAAS,CAAC,CAAC,CACvC,KAAK,YAAY,QAAQ,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC;AACrE"}
+{"version":3,"file":"json-schema-to-standard.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/json-schema-to-standard.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * The inverse of `@warlock.js/ai`'s `extractJsonSchema` (which goes\n * Standard Schema → JSON Schema). Here we wrap a raw JSON Schema as a\n * {@link StandardSchemaV1} whose `~standard.validate` runs a lazily-imported\n * Ajv validator — so an MCP server's `inputSchema` (JSON Schema) becomes a\n * `ToolConfig.input` the `tool()` factory can validate against.\n *\n * Ajv is an OPTIONAL peer, lazy-imported on first validate following the\n * langfuse/readability pattern: a missing peer surfaces a curated install\n * string (via the returned issues), never a raw module-resolution stack.\n */\n\n/** The structural vendor template, mirroring `passthroughSchema()`. */\nconst VENDOR = \"warlock-ai\";\n\n// ============================================================\n// Lazily-loaded ajv (OPTIONAL peer)\n// ============================================================\n\n/**\n * Minimal structural view of an Ajv-compiled validator. Ajv is an optional\n * peer that may not be installed, so we model only the surface we touch\n * rather than depending on ajv's own published types. A validator is a\n * callable that returns a boolean and exposes the `errors` it collected.\n */\ninterface AjvValidateFunctionLike {\n  (data: unknown): boolean;\n  errors?: AjvErrorObject[] | null;\n}\n\n/** Minimal structural view of an `Ajv` instance — only `compile`. */\ninterface AjvInstanceLike {\n  compile(schema: Record<string, unknown>): AjvValidateFunctionLike;\n}\n\n/** The `Ajv` constructor, as exposed by both the CJS and ESM builds. */\ntype AjvConstructorLike = new (options?: Record<string, unknown>) => AjvInstanceLike;\n\n/**\n * Minimal structural view of the dynamically imported `ajv` module. Ajv\n * ships its constructor as a `default` export under ESM interop; the older\n * CJS shape exposes the constructor as the module namespace itself, so\n * `default` is optional here and the loader falls back to the namespace.\n */\ninterface AjvModuleLike {\n  default?: AjvConstructorLike;\n}\n\nlet AjvSdk: AjvModuleLike | undefined;\nlet ajvInstance: AjvInstanceLike | undefined;\nlet isAjvAvailable: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\nconst AJV_INSTALL_INSTRUCTIONS = `\nThe MCP client's JSON-Schema validation requires the ajv package.\nInstall it with:\n\n  npm install ajv\n\nOr with your preferred package manager:\n\n  pnpm add ajv\n  yarn add ajv\n`.trim();\n\n/**\n * Settle the lazy import of `ajv` once, concurrency-safe. A bare `catch`\n * flips the availability flag to `false`; the curated install string then\n * surfaces at validate time as a Standard Schema issue, never a raw\n * module-resolution error. The constructed `Ajv` instance is cached and\n * reused for every schema compile.\n */\nasync function loadAjv(): Promise<void> {\n  if (isAjvAvailable !== undefined) {\n    return;\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      AjvSdk = (await import(\"ajv\")) as AjvModuleLike;\n      // Ajv ships as a default export under both CJS and ESM interop; the\n      // older CJS shape exposes the constructor as the namespace itself.\n      const AjvCtor: AjvConstructorLike =\n        AjvSdk.default ?? (AjvSdk as unknown as AjvConstructorLike);\n      ajvInstance = new AjvCtor({ allErrors: true, strict: false });\n      isAjvAvailable = true;\n    } catch {\n      isAjvAvailable = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Compile a JSON Schema with the shared Ajv instance, caching the compiled\n * validator on a closure so repeated validations don't recompile. A schema\n * Ajv itself rejects at compile time (an invalid meta-schema) degrades to\n * an accept-all validator so a malformed remote schema can't wedge the\n * tool — the server, not us, owns its schema's correctness.\n */\nfunction makeCompiler(schema: Record<string, unknown>): () => AjvValidateFunctionLike | undefined {\n  let compiled: AjvValidateFunctionLike | undefined;\n  let attempted = false;\n\n  return () => {\n    if (attempted) {\n      return compiled;\n    }\n\n    attempted = true;\n\n    if (!ajvInstance) {\n      return undefined;\n    }\n\n    try {\n      compiled = ajvInstance.compile(schema);\n    } catch {\n      compiled = undefined;\n    }\n\n    return compiled;\n  };\n}\n\n/**\n * Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose\n * `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`\n * (`{ \"~standard\": { version: 1, vendor, validate } }`) so it drops into\n * `tool({ input })` exactly like a native seal schema.\n *\n * Validation behavior:\n * - **Valid input** → `{ value }` (the input is passed through unchanged;\n *   Ajv validates, it does not transform).\n * - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +\n *   message per failure, so `tool()` produces a `SchemaValidationError`.\n * - **Missing `ajv` peer** → a single issue carrying the curated install\n *   string, surfaced the same way (a developer-facing message in logs).\n * - **No / empty schema** → an accept-all passthrough (an MCP tool may\n *   advertise no `inputSchema`).\n *\n * @param schema - The JSON Schema (an MCP tool's `inputSchema`), or\n *   `undefined` for a no-argument tool.\n * @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.\n *\n * @example\n * const input = jsonSchemaToStandard<{ q: string }>({\n *   type: \"object\",\n *   properties: { q: { type: \"string\" } },\n *   required: [\"q\"],\n * });\n */\nexport function jsonSchemaToStandard<TInput = unknown>(\n  schema: Record<string, unknown> | undefined,\n): StandardSchemaV1<TInput> {\n  // A tool with no schema (or an empty object schema) validates everything\n  // — return an accept-all passthrough and never touch Ajv.\n  if (!schema || Object.keys(schema).length === 0) {\n    return {\n      \"~standard\": {\n        version: 1,\n        vendor: VENDOR,\n        validate: (value: unknown) => ({ value: value as TInput }),\n      },\n    };\n  }\n\n  const compile = makeCompiler(schema);\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: VENDOR,\n      async validate(value: unknown): Promise<StandardSchemaV1.Result<TInput>> {\n        await loadAjv();\n\n        if (!isAjvAvailable) {\n          return {\n            issues: [{ message: AJV_INSTALL_INSTRUCTIONS }],\n          };\n        }\n\n        const validator = compile();\n\n        // A schema Ajv could not compile degrades to accept-all rather\n        // than failing every call — the remote server owns its schema.\n        if (!validator) {\n          return { value: value as TInput };\n        }\n\n        const ok = validator(value);\n\n        if (ok) {\n          return { value: value as TInput };\n        }\n\n        const issues: StandardSchemaV1.Issue[] = (validator.errors ?? []).map((error) => ({\n          message: formatAjvError(error),\n          path: pathFromInstancePath(error.instancePath),\n        }));\n\n        return {\n          issues: issues.length > 0 ? issues : [{ message: \"input failed JSON Schema validation\" }],\n        };\n      },\n    },\n  };\n}\n\n/** A single Ajv error object — narrowed to the fields we read. */\ninterface AjvErrorObject {\n  instancePath?: string;\n  message?: string;\n  keyword?: string;\n}\n\n/**\n * Render one Ajv error into a human-readable issue message. Prefixes the\n * failing instance path (when present) so the model can see WHICH field\n * was wrong, e.g. `/query: must be string`.\n */\nfunction formatAjvError(error: AjvErrorObject): string {\n  const where = error.instancePath ? `${error.instancePath}: ` : \"\";\n  const message = error.message ?? `failed \"${error.keyword ?? \"validation\"}\"`;\n\n  return `${where}${message}`;\n}\n\n/**\n * Convert an Ajv `instancePath` (a JSON-Pointer like `/items/0/name`) into\n * the Standard Schema `path` segment array (`[\"items\", \"0\", \"name\"]`).\n * Empty paths (a root-level failure) become an empty array.\n */\nfunction pathFromInstancePath(instancePath: string | undefined): string[] {\n  if (!instancePath) {\n    return [];\n  }\n\n  return instancePath\n    .split(\"/\")\n    .filter((segment) => segment.length > 0)\n    .map((segment) => segment.replace(/~1/g, \"/\").replace(/~0/g, \"~\"));\n}\n\n/**\n * Reset the cached lazy-import state. Test-only seam so a spec can mock\n * `ajv` as present/absent across cases without module-cache bleed.\n *\n * @internal\n */\nexport function resetAjvCacheForTests(): void {\n  AjvSdk = undefined;\n  ajvInstance = undefined;\n  isAjvAvailable = undefined;\n  loadingPromise = undefined;\n}\n"],"mappings":";;;;;;;;;;;;;AAeA,MAAM,SAAS;AAmCf,IAAI;AACJ,IAAI;AACJ,IAAI;AACJ,IAAI;AAEJ,MAAM,2BAA2B;;;;;;;;;;EAU/B,KAAK;;;;;;;;AASP,eAAe,UAAyB;CACtC,IAAI,mBAAmB,QACrB;CAGF,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GACF,SAAU,MAAM,OAAO;GAKvB,cAAc,KADZ,OAAO,WAAY,QACK;IAAE,WAAW;IAAM,QAAQ;GAAM,CAAC;GAC5D,iBAAiB;EACnB,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;;;AASA,SAAS,aAAa,QAA4E;CAChG,IAAI;CACJ,IAAI,YAAY;CAEhB,aAAa;EACX,IAAI,WACF,OAAO;EAGT,YAAY;EAEZ,IAAI,CAAC,aACH;EAGF,IAAI;GACF,WAAW,YAAY,QAAQ,MAAM;EACvC,QAAQ;GACN,WAAW;EACb;EAEA,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,qBACd,QAC0B;CAG1B,IAAI,CAAC,UAAU,OAAO,KAAK,MAAM,CAAC,CAAC,WAAW,GAC5C,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,WAAoB,EAAS,MAAgB;CAC1D,EACF;CAGF,MAAM,UAAU,aAAa,MAAM;CAEnC,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,MAAM,SAAS,OAA0D;GACvE,MAAM,QAAQ;GAEd,IAAI,CAAC,gBACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAChD;GAGF,MAAM,YAAY,QAAQ;GAI1B,IAAI,CAAC,WACH,OAAO,EAAS,MAAgB;GAKlC,IAFW,UAAU,KAEhB,GACH,OAAO,EAAS,MAAgB;GAGlC,MAAM,UAAoC,UAAU,UAAU,CAAC,EAAC,CAAE,KAAK,WAAW;IAChF,SAAS,eAAe,KAAK;IAC7B,MAAM,qBAAqB,MAAM,YAAY;GAC/C,EAAE;GAEF,OAAO,EACL,QAAQ,OAAO,SAAS,IAAI,SAAS,CAAC,EAAE,SAAS,sCAAsC,CAAC,EAC1F;EACF;CACF,EACF;AACF;;;;;;AAcA,SAAS,eAAe,OAA+B;CAIrD,OAAO,GAHO,MAAM,eAAe,GAAG,MAAM,aAAa,MAAM,KAC/C,MAAM,WAAW,WAAW,MAAM,WAAW,aAAa;AAG5E;;;;;;AAOA,SAAS,qBAAqB,cAA4C;CACxE,IAAI,CAAC,cACH,OAAO,CAAC;CAGV,OAAO,aACJ,MAAM,GAAG,CAAC,CACV,QAAQ,YAAY,QAAQ,SAAS,CAAC,CAAC,CACvC,KAAK,YAAY,QAAQ,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC;AACrE"}

package/esm/mcp/protocol.d.mts

@@ -0,0 +1,16 @@
+//#region ../../packages/ai-tools/src/mcp/protocol.d.ts
+/**
+ * MCP protocol versions the `ai.mcp.serve` server speaks, newest first.
+ * `initialize` echoes the client's requested version when it is listed
+ * here and otherwise answers with the newest one (lifecycle, version
+ * negotiation). The HTTP transport rejects any other value in the
+ * `MCP-Protocol-Version` header with 400.
+ *
+ * Source: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+ * and https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+ * (checked 2026-10-17).
+ */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+//#endregion
+export { SUPPORTED_PROTOCOL_VERSIONS };
+//# sourceMappingURL=protocol.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.mts","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/protocol.ts"],"mappings":";;AAWA;;;;AAIC;;;;;;cAJY,2BAAA"}

package/esm/mcp/protocol.mjs

@@ -0,0 +1,23 @@
+//#region ../../packages/ai-tools/src/mcp/protocol.ts
+/**
+* MCP protocol versions the `ai.mcp.serve` server speaks, newest first.
+* `initialize` echoes the client's requested version when it is listed
+* here and otherwise answers with the newest one (lifecycle, version
+* negotiation). The HTTP transport rejects any other value in the
+* `MCP-Protocol-Version` header with 400.
+*
+* Source: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+* and https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+* (checked 2026-10-17).
+*/
+const SUPPORTED_PROTOCOL_VERSIONS = [
+	"2025-11-25",
+	"2025-06-18",
+	"2025-03-26"
+];
+/** The newest MCP protocol version the server speaks. */
+const LATEST_PROTOCOL_VERSION = "2025-11-25";
+
+//#endregion
+export { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS };
+//# sourceMappingURL=protocol.mjs.map

package/esm/mcp/protocol.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/mcp/protocol.ts"],"sourcesContent":["/**\n * MCP protocol versions the `ai.mcp.serve` server speaks, newest first.\n * `initialize` echoes the client's requested version when it is listed\n * here and otherwise answers with the newest one (lifecycle, version\n * negotiation). The HTTP transport rejects any other value in the\n * `MCP-Protocol-Version` header with 400.\n *\n * Source: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle\n * and https://modelcontextprotocol.io/specification/2025-11-25/basic/transports\n * (checked 2026-10-17).\n */\nexport const SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [\n  \"2025-11-25\",\n  \"2025-06-18\",\n  \"2025-03-26\",\n];\n\n/** The newest MCP protocol version the server speaks. */\nexport const LATEST_PROTOCOL_VERSION = \"2025-11-25\";\n"],"mappings":";;;;;;;;;;;;AAWA,MAAa,8BAAiD;CAC5D;CACA;CACA;AACF;;AAGA,MAAa,0BAA0B"}