@warlock.js/ai-tools 4.5.0

package/esm/mcp/client.mjs

@@ -0,0 +1,199 @@
+import { McpTransportError } from "../errors.mjs";
+import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
+import { createJsonRpcClient } from "./transport.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/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`. */
+const PROTOCOL_VERSION = "2025-06-18";
+/**
+* The internal {@link McpClient} implementation. Owns one JSON-RPC client
+* over a transport, runs the `initialize` handshake on first use, lists
+* the server's tools, and adapts each into a {@link ToolContract} whose
+* `execute` issues `tools/call`. The adapted contracts are cached after
+* the first `tools()` so repeat calls don't re-handshake.
+*
+* Constructed via {@link mcp}; the class itself is internal.
+*/
+var McpClientImpl = class {
+	constructor(source, options = {}) {
+		this.initialized = false;
+		this.rpc = createJsonRpcClient(source);
+		this.options = options;
+	}
+	/**
+	* Run the MCP `initialize` handshake exactly once, then send the
+	* `notifications/initialized` notification the protocol requires before
+	* any other request. Wraps a handshake failure as a typed
+	* {@link McpTransportError} of type `"connect"`.
+	*/
+	async handshake() {
+		if (this.initialized) return;
+		try {
+			await this.rpc.call("initialize", {
+				protocolVersion: PROTOCOL_VERSION,
+				capabilities: {},
+				clientInfo: {
+					name: "@warlock.js/ai-tools",
+					version: "4.4.0"
+				}
+			});
+			await this.rpc.notify("notifications/initialized");
+		} catch (cause) {
+			if (cause instanceof McpTransportError) throw cause;
+			throw new McpTransportError(`MCP initialize handshake failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+				type: "connect",
+				method: "initialize",
+				cause
+			});
+		}
+		this.initialized = true;
+	}
+	tools() {
+		if (this.cached) return Promise.resolve(this.cached);
+		if (this.pending) return this.pending;
+		this.pending = this.listAndAdapt().then((tools) => {
+			this.cached = tools;
+			return tools;
+		}).finally(() => {
+			this.pending = void 0;
+		});
+		return this.pending;
+	}
+	/**
+	* Handshake, `tools/list`, and adapt each descriptor into a
+	* {@link ToolContract}, applying the `filter` and `namePrefix` options.
+	*/
+	async listAndAdapt() {
+		await this.handshake();
+		const descriptors = (await this.rpc.call("tools/list")).tools ?? [];
+		const filter = this.options.filter;
+		return (filter ? descriptors.filter((d) => filter(d.name)) : descriptors).map((descriptor) => this.adapt(descriptor));
+	}
+	/**
+	* Adapt one remote tool descriptor into a {@link ToolContract}: build
+	* the input schema from its JSON Schema via {@link jsonSchemaToStandard},
+	* prefix the name, and route `execute` through a `tools/call` that
+	* honors `ctx.signal`, unwraps the content blocks, and throws on an
+	* `isError` result so `tool()` wraps it.
+	*/
+	adapt(descriptor) {
+		const prefixedName = `${this.options.namePrefix ?? ""}${descriptor.name}`;
+		const remoteName = descriptor.name;
+		const timeoutMs = this.options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+		const input = jsonSchemaToStandard(descriptor.inputSchema);
+		return tool({
+			name: prefixedName,
+			description: descriptor.description ?? `Invoke the remote MCP tool "${remoteName}".`,
+			input,
+			execute: async (args, ctx) => {
+				const result = await this.rpc.call("tools/call", {
+					name: remoteName,
+					arguments: args ?? {}
+				}, {
+					signal: ctx?.signal,
+					timeoutMs
+				});
+				if (result.isError) throw new McpTransportError(`MCP tool "${remoteName}" returned an error: ${unwrapContent(result.content)}`, {
+					type: "protocol",
+					method: "tools/call"
+				});
+				return unwrapResult(result.content);
+			}
+		});
+	}
+	close() {
+		return this.rpc.close();
+	}
+};
+/**
+* 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
+* rather than a string. Non-text blocks are preserved as `type`-tagged
+* objects (MCP's wire `type` is kept; any inbound `kind` is normalized to
+* `type`).
+*/
+function unwrapResult(content) {
+	const blocks = content ?? [];
+	if (blocks.length === 1 && blocks[0].type === "text") return tryParseJson(blocks[0].text ?? "");
+	return blocks.map((block) => normalizeBlock(block));
+}
+/**
+* Render content blocks to a short human string for error messages — the
+* concatenated text of every text block.
+*/
+function unwrapContent(content) {
+	return (content ?? []).filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join(" ").trim();
+}
+/**
+* Normalize one content block onto our `type`-only shape: translate an
+* inbound `kind` discriminator to `type` (and strip `kind`) so the value a
+* tool returns never carries MCP's `kind` vocabulary.
+*/
+function normalizeBlock(block) {
+	const { kind, ...rest } = block;
+	const type = block.type ?? kind ?? "unknown";
+	return {
+		...rest,
+		type
+	};
+}
+/**
+* Parse a string as JSON, returning the parsed value on success or the
+* original string when it is not JSON — so a plain-text tool result stays
+* a string while a JSON tool result becomes an object.
+*/
+function tryParseJson(text) {
+	const trimmed = text.trim();
+	if (!trimmed) return text;
+	const first = trimmed[0];
+	if (first !== "{" && first !== "[") return text;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return text;
+	}
+}
+/**
+* Connect to an external MCP server and adapt its tools as agent tools
+* (Direction A: server → local agent tools).
+*
+* Opens the transport lazily and exposes {@link McpClient.tools}, which on
+* first call runs the `initialize` handshake, lists the server's tools via
+* `tools/list`, and maps each into a {@link ToolContract}:
+* - **input schema** — the remote tool's JSON Schema is wrapped as a
+*   Standard Schema via {@link jsonSchemaToStandard} (Ajv-backed, an
+*   optional peer);
+* - **execute** — issues `tools/call` honoring `ctx.signal` and the
+*   configured `timeoutMs`, unwraps the result content, and throws on an
+*   `isError` result so the `tool()` wrapper surfaces it as `{ error }`;
+* - **name** — prefixed with `options.namePrefix` to avoid local
+*   collisions; only tools passing `options.filter` are adapted.
+*
+* The adapted contracts are cached after the first `tools()` call, so the
+* handshake + list happen exactly once. The returned contracts drop
+* straight into `ai.agent({ tools: [...] })`.
+*
+* @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.
+* @returns An {@link McpClient} handle.
+*
+* @example
+* const github = mcp(
+*   { type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+*   { namePrefix: "github." },
+* );
+* const dev = ai.agent({ model, tools: [...(await github.tools())] });
+*/
+function mcp(server, options) {
+	return new McpClientImpl(server, options);
+}
+
+//#endregion
+export { mcp };
+//# sourceMappingURL=client.mjs.map

package/esm/mcp/client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.mjs","names":[],"sources":["../../../../../../../@warlock.js/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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"}

package/esm/mcp/index.d.mts

@@ -0,0 +1,43 @@
+import { McpClient, McpClientOptions, McpServeOptions, McpServeSource, McpServer, McpTransport } from "../contracts/mcp.type.mjs";
+import { createServeHandler, serve } from "./serve.mjs";
+import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
+import { McpTransportClient } from "./transport.type.mjs";
+import { JsonRpcClientHandle, createJsonRpcClient, createTransport } from "./transport.mjs";
+
+//#region ../@warlock.js/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
+ * primitive AS an MCP server (Direction B). Modeled as a function with an
+ * attached `serve` property, mirroring how `ai.mcp(server).tools()` and
+ * `ai.mcp.serve(source, options).start()` read in the design.
+ */
+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.
+   */
+  (server: McpTransport, options?: McpClientOptions): McpClient;
+  /**
+   * Expose a built agent / supervisor / orchestrator (or a literal
+   * `ToolContract[]`) AS an MCP server.
+   *
+   * @param source - The tools to expose.
+   * @param options - Server name, version, transport, and schema dialect.
+   */
+  serve(source: McpServeSource, options: McpServeOptions): McpServer;
+}
+/**
+ * The `ai.mcp` factory value: the client factory with `.serve` attached.
+ * `Object.assign` keeps `mcp` callable (Direction A) while widening it with
+ * the `serve` member (Direction B) — one object, both directions. The
+ * `declare module "@warlock.js/ai"` augmentation and the runtime
+ * registration (`ai.mcp = mcp`) live in `../register`, so this barrel is a
+ * pure value/type module the registrar consumes.
+ */
+declare const mcp: McpFactory;
+//#endregion
+export { McpFactory, mcp };
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../@warlock.js/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"}

package/esm/mcp/index.mjs

@@ -0,0 +1,19 @@
+import { jsonSchemaToStandard } from "./json-schema-to-standard.mjs";
+import { createJsonRpcClient, createTransport } from "./transport.mjs";
+import { mcp as mcp$1 } from "./client.mjs";
+import { createServeHandler, serve } from "./serve.mjs";
+
+//#region ../@warlock.js/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
+* the `serve` member (Direction B) — one object, both directions. The
+* `declare module "@warlock.js/ai"` augmentation and the runtime
+* registration (`ai.mcp = mcp`) live in `../register`, so this barrel is a
+* pure value/type module the registrar consumes.
+*/
+const mcp = Object.assign((server, options) => mcp$1(server, options), { serve });
+
+//#endregion
+export { mcp };
+//# sourceMappingURL=index.mjs.map

package/esm/mcp/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["mcpClient"],"sources":["../../../../../../../@warlock.js/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"}

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

@@ -0,0 +1,34 @@
+import { StandardSchemaV1 } from "../node_modules/@standard-schema/spec/dist/index.mjs";
+
+//#region ../@warlock.js/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()`
+ * (`{ "~standard": { version: 1, vendor, validate } }`) so it drops into
+ * `tool({ input })` exactly like a native seal schema.
+ *
+ * Validation behavior:
+ * - **Valid input** → `{ value }` (the input is passed through unchanged;
+ *   Ajv validates, it does not transform).
+ * - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +
+ *   message per failure, so `tool()` produces a `SchemaValidationError`.
+ * - **Missing `ajv` peer** → a single issue carrying the curated install
+ *   string, surfaced the same way (a developer-facing message in logs).
+ * - **No / empty schema** → an accept-all passthrough (an MCP tool may
+ *   advertise no `inputSchema`).
+ *
+ * @param schema - The JSON Schema (an MCP tool's `inputSchema`), or
+ *   `undefined` for a no-argument tool.
+ * @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.
+ *
+ * @example
+ * const input = jsonSchemaToStandard<{ q: string }>({
+ *   type: "object",
+ *   properties: { q: { type: "string" } },
+ *   required: ["q"],
+ * });
+ */
+declare function jsonSchemaToStandard<TInput = unknown>(schema: Record<string, unknown> | undefined): StandardSchemaV1<TInput>;
+//#endregion
+export { jsonSchemaToStandard };
+//# sourceMappingURL=json-schema-to-standard.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-to-standard.d.mts","names":[],"sources":["../../../../../../../@warlock.js/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

@@ -0,0 +1,147 @@
+//#region ../@warlock.js/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
+* {@link StandardSchemaV1} whose `~standard.validate` runs a lazily-imported
+* Ajv validator — so an MCP server's `inputSchema` (JSON Schema) becomes a
+* `ToolConfig.input` the `tool()` factory can validate against.
+*
+* Ajv is an OPTIONAL peer, lazy-imported on first validate following the
+* langfuse/readability pattern: a missing peer surfaces a curated install
+* string (via the returned issues), never a raw module-resolution stack.
+*/
+/** The structural vendor template, mirroring `passthroughSchema()`. */
+const VENDOR = "warlock-ai";
+let AjvSdk;
+let ajvInstance;
+let isAjvAvailable;
+let loadingPromise;
+const AJV_INSTALL_INSTRUCTIONS = `
+The MCP client's JSON-Schema validation requires the ajv package.
+Install it with:
+
+  npm install ajv
+
+Or with your preferred package manager:
+
+  pnpm add ajv
+  yarn add ajv
+`.trim();
+/**
+* Settle the lazy import of `ajv` once, concurrency-safe. A bare `catch`
+* flips the availability flag to `false`; the curated install string then
+* surfaces at validate time as a Standard Schema issue, never a raw
+* module-resolution error. The constructed `Ajv` instance is cached and
+* reused for every schema compile.
+*/
+async function loadAjv() {
+	if (isAjvAvailable !== void 0) return;
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			AjvSdk = await import("ajv");
+			ajvInstance = new (AjvSdk.default ?? AjvSdk)({
+				allErrors: true,
+				strict: false
+			});
+			isAjvAvailable = true;
+		} catch {
+			isAjvAvailable = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* Compile a JSON Schema with the shared Ajv instance, caching the compiled
+* validator on a closure so repeated validations don't recompile. A schema
+* Ajv itself rejects at compile time (an invalid meta-schema) degrades to
+* an accept-all validator so a malformed remote schema can't wedge the
+* tool — the server, not us, owns its schema's correctness.
+*/
+function makeCompiler(schema) {
+	let compiled;
+	let attempted = false;
+	return () => {
+		if (attempted) return compiled;
+		attempted = true;
+		if (!ajvInstance) return;
+		try {
+			compiled = ajvInstance.compile(schema);
+		} catch {
+			compiled = void 0;
+		}
+		return compiled;
+	};
+}
+/**
+* Wrap a raw JSON Schema as a {@link StandardSchemaV1} whose
+* `~standard.validate` runs Ajv. The shape mirrors `passthroughSchema()`
+* (`{ "~standard": { version: 1, vendor, validate } }`) so it drops into
+* `tool({ input })` exactly like a native seal schema.
+*
+* Validation behavior:
+* - **Valid input** → `{ value }` (the input is passed through unchanged;
+*   Ajv validates, it does not transform).
+* - **Invalid input** → `{ issues }` carrying Ajv's `instancePath` +
+*   message per failure, so `tool()` produces a `SchemaValidationError`.
+* - **Missing `ajv` peer** → a single issue carrying the curated install
+*   string, surfaced the same way (a developer-facing message in logs).
+* - **No / empty schema** → an accept-all passthrough (an MCP tool may
+*   advertise no `inputSchema`).
+*
+* @param schema - The JSON Schema (an MCP tool's `inputSchema`), or
+*   `undefined` for a no-argument tool.
+* @returns A `StandardSchemaV1<TInput>` ready for `tool({ input })`.
+*
+* @example
+* const input = jsonSchemaToStandard<{ q: string }>({
+*   type: "object",
+*   properties: { q: { type: "string" } },
+*   required: ["q"],
+* });
+*/
+function jsonSchemaToStandard(schema) {
+	if (!schema || Object.keys(schema).length === 0) return { "~standard": {
+		version: 1,
+		vendor: VENDOR,
+		validate: (value) => ({ value })
+	} };
+	const compile = makeCompiler(schema);
+	return { "~standard": {
+		version: 1,
+		vendor: VENDOR,
+		async validate(value) {
+			await loadAjv();
+			if (!isAjvAvailable) return { issues: [{ message: AJV_INSTALL_INSTRUCTIONS }] };
+			const validator = compile();
+			if (!validator) return { value };
+			if (validator(value)) return { value };
+			const issues = (validator.errors ?? []).map((error) => ({
+				message: formatAjvError(error),
+				path: pathFromInstancePath(error.instancePath)
+			}));
+			return { issues: issues.length > 0 ? issues : [{ message: "input failed JSON Schema validation" }] };
+		}
+	} };
+}
+/**
+* Render one Ajv error into a human-readable issue message. Prefixes the
+* failing instance path (when present) so the model can see WHICH field
+* was wrong, e.g. `/query: must be string`.
+*/
+function formatAjvError(error) {
+	return `${error.instancePath ? `${error.instancePath}: ` : ""}${error.message ?? `failed "${error.keyword ?? "validation"}"`}`;
+}
+/**
+* Convert an Ajv `instancePath` (a JSON-Pointer like `/items/0/name`) into
+* the Standard Schema `path` segment array (`["items", "0", "name"]`).
+* Empty paths (a root-level failure) become an empty array.
+*/
+function pathFromInstancePath(instancePath) {
+	if (!instancePath) return [];
+	return instancePath.split("/").filter((segment) => segment.length > 0).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+//#endregion
+export { jsonSchemaToStandard };
+//# sourceMappingURL=json-schema-to-standard.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-to-standard.mjs","names":[],"sources":["../../../../../../../@warlock.js/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/serve.d.mts

@@ -0,0 +1,46 @@
+import { JsonRpcRequest, JsonRpcResponse, McpServeOptions, McpServeSource, McpServer } from "../contracts/mcp.type.mjs";
+//#region ../@warlock.js/ai-tools/src/mcp/serve.d.ts
+/**
+ * Build the pure protocol handler for a serve source. Exposed (alongside
+ * {@link serve}) so callers and tests can drive the MCP protocol without an
+ * actual transport — feed it a JSON-RPC request, get the response.
+ *
+ * @param source - The tools to expose (an object with `tools()` or a literal array).
+ * @param options - Serve options (name / version / schema target).
+ * @returns An object whose `handle(request)` maps a request to a response.
+ */
+declare function createServeHandler(source: McpServeSource, options: McpServeOptions): {
+  handle(request: JsonRpcRequest): Promise<JsonRpcResponse>;
+};
+/**
+ * Expose a built agent / supervisor / orchestrator (or a raw
+ * `ToolContract[]`) AS an MCP server (Direction B: local primitive → MCP
+ * server other clients consume).
+ *
+ * Enumerates `source.tools()` (or the literal array) once at construction.
+ * `tools/list` answers with each tool's `inputSchema` extracted via
+ * `extractJsonSchema` at the configured `schemaTarget` (default
+ * `draft-2020-12`). `tools/call` routes to the named contract's
+ * `invoke()` and maps the never-throwing result — `data` becomes a text
+ * content block, `error` becomes an `isError: true` result — so a failing
+ * tool surfaces as a normal MCP tool error rather than crashing the server.
+ *
+ * The default transport is `stdio`, pumped over `process.stdin` /
+ * `process.stdout`. Serving over HTTP is left to a host-owned server;
+ * `start()` rejects an `http` transport (the protocol core is available
+ * via {@link createServeHandler} for a caller's own HTTP wiring).
+ *
+ * @param source - The tools to expose.
+ * @param options - Server name, version, transport, and schema dialect.
+ * @returns An {@link McpServer} with `start()` / `stop()`.
+ *
+ * @example
+ * serve(
+ *   { tools: () => ws.allTools() },
+ *   { name: "warlock-workspace", transport: { type: "stdio" } },
+ * ).start();
+ */
+declare function serve(source: McpServeSource, options: McpServeOptions): McpServer;
+//#endregion
+export { createServeHandler, serve };
+//# sourceMappingURL=serve.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/mcp/serve.ts"],"mappings":";;;;;AAiOA;;;;;;iBAAgB,kBAAA,CACd,MAAA,EAAQ,cAAA,EACR,OAAA,EAAS,eAAA;EACN,MAAA,CAAO,OAAA,EAAS,cAAA,GAAiB,OAAA,CAAQ,eAAA;AAAA;;;;;;;;;;;;AAAe;AAqH7D;;;;;;;;;;;;;;AAAkF;;iBAAlE,KAAA,CAAM,MAAA,EAAQ,cAAA,EAAgB,OAAA,EAAS,eAAA,GAAkB,SAAA"}