@warlock.js/ai-tools 4.5.0

package/esm/mcp/transport.mjs

@@ -0,0 +1,381 @@
+import { McpTransportError } from "../errors.mjs";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+//#region ../@warlock.js/ai-tools/src/mcp/transport.ts
+/** Default per-request wait before a transport call is abandoned. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+/** The JSON-RPC version literal every outbound message carries. */
+const JSONRPC_VERSION = "2.0";
+/**
+* Wire a per-call timeout and an optional caller `AbortSignal` onto a
+* pending request, returning a `cleanup()` that tears both down. The
+* `onSettle` callback removes the pending entry from whatever registry the
+* transport keeps so a late response can't double-settle.
+*/
+function armCall(reject, method, options, onSettle) {
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+	const timer = setTimeout(() => {
+		onSettle();
+		reject(new McpTransportError(`MCP request "${method}" timed out after ${timeoutMs}ms.`, {
+			type: "timeout",
+			method
+		}));
+	}, timeoutMs);
+	const onAbort = () => {
+		cleanup();
+		reject(new McpTransportError(`MCP request "${method}" was aborted.`, {
+			type: "closed",
+			method
+		}));
+	};
+	const signal = options?.signal;
+	if (signal) if (signal.aborted) queueMicrotask(onAbort);
+	else signal.addEventListener("abort", onAbort, { once: true });
+	function cleanup() {
+		clearTimeout(timer);
+		if (signal) signal.removeEventListener("abort", onAbort);
+	}
+	return cleanup;
+}
+/**
+* The stdio transport — spawns a child process and speaks JSON-RPC over
+* its stdin/stdout, one JSON object per line (newline-delimited framing).
+* Uses only Node built-ins (`node:child_process` + `node:readline`); no
+* dependency.
+*
+* Constructed via {@link createStdioTransport}; the class itself is
+* internal.
+*/
+var StdioTransport = class {
+	constructor(transport) {
+		this.pending = /* @__PURE__ */ new Map();
+		this.nextId = 1;
+		this.closed = false;
+		let child;
+		try {
+			child = spawn(transport.command, transport.args ?? [], {
+				env: transport.env,
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new McpTransportError(`MCP stdio transport could not spawn "${transport.command}": ${message}`, {
+				type: "connect",
+				cause
+			});
+		}
+		this.child = child;
+		this.reader = createInterface({ input: child.stdout });
+		this.reader.on("line", (line) => this.onLine(line));
+		child.on("exit", (code) => this.failAll("connect", `child exited with code ${code ?? "null"}`));
+		child.on("error", (error) => this.failAll("connect", error.message));
+	}
+	/**
+	* Parse one stdout line and route it to its pending request. Non-JSON
+	* lines (a server logging to stdout) and messages with no matching `id`
+	* (notifications, stray responses) are ignored — robustness over strictness.
+	*/
+	onLine(line) {
+		const trimmed = line.trim();
+		if (!trimmed) return;
+		let message;
+		try {
+			message = JSON.parse(trimmed);
+		} catch {
+			return;
+		}
+		if (message.id === void 0 || message.id === null) return;
+		const call = this.pending.get(message.id);
+		if (!call) return;
+		this.pending.delete(message.id);
+		call.cleanup();
+		call.resolve(message);
+	}
+	/**
+	* Reject every pending call (and mark the transport unusable) when the
+	* child dies or errors — so a hung server can never leave a caller
+	* waiting forever.
+	*/
+	failAll(type, reason) {
+		this.closed = true;
+		for (const [id, call] of this.pending) {
+			this.pending.delete(id);
+			call.cleanup();
+			call.reject(new McpTransportError(`MCP stdio transport failed: ${reason}.`, { type }));
+		}
+	}
+	request(request, options) {
+		if (this.closed) return Promise.reject(new McpTransportError("MCP stdio transport is closed.", {
+			type: "closed",
+			method: request.method
+		}));
+		const id = request.id;
+		return new Promise((resolve, reject) => {
+			const cleanup = armCall(reject, request.method, options, () => this.pending.delete(id));
+			this.pending.set(id, {
+				resolve: (response) => resolve(response),
+				reject,
+				cleanup
+			});
+			try {
+				this.child.stdin.write(`${JSON.stringify(request)}\n`);
+			} catch (cause) {
+				this.pending.delete(id);
+				cleanup();
+				const message = cause instanceof Error ? cause.message : String(cause);
+				reject(new McpTransportError(`MCP stdio transport failed to write request "${request.method}": ${message}`, {
+					type: "closed",
+					method: request.method,
+					cause
+				}));
+			}
+		});
+	}
+	async notify(method, params) {
+		if (this.closed) throw new McpTransportError("MCP stdio transport is closed.", {
+			type: "closed",
+			method
+		});
+		const notification = {
+			jsonrpc: JSONRPC_VERSION,
+			method,
+			params
+		};
+		this.child.stdin.write(`${JSON.stringify(notification)}\n`);
+	}
+	/** Allocate the next outbound request id. */
+	allocateId() {
+		return this.nextId++;
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.reader.close();
+		this.failAll("closed", "transport closed by caller");
+		this.child.kill();
+	}
+};
+/**
+* The Streamable HTTP transport — POSTs each JSON-RPC request to the
+* server endpoint over the global `fetch` (Node 18+) and reads the single
+* JSON response. No SSE-legacy, no WebSocket. Static `headers` (e.g. auth)
+* are sent with every request.
+*
+* Constructed via {@link createHttpTransport}; the class itself is internal.
+*/
+var HttpTransport = class {
+	constructor(transport) {
+		this.nextId = 1;
+		this.url = transport.url;
+		this.headers = {
+			"content-type": "application/json",
+			accept: "application/json, text/event-stream",
+			...transport.headers
+		};
+	}
+	async request(request, options) {
+		const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		const onAbort = () => controller.abort();
+		const signal = options?.signal;
+		if (signal) if (signal.aborted) controller.abort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+		let response;
+		try {
+			response = await fetch(this.url, {
+				method: "POST",
+				headers: this.headers,
+				body: JSON.stringify(request),
+				signal: controller.signal
+			});
+		} catch (cause) {
+			const aborted = controller.signal.aborted;
+			const message = cause instanceof Error ? cause.message : String(cause);
+			throw new McpTransportError(aborted ? `MCP request "${request.method}" timed out or was aborted after ${timeoutMs}ms.` : `MCP http transport request "${request.method}" failed: ${message}`, {
+				type: aborted ? "timeout" : "connect",
+				method: request.method,
+				cause
+			});
+		} finally {
+			clearTimeout(timer);
+			if (signal) signal.removeEventListener("abort", onAbort);
+		}
+		if (!response.ok) throw new McpTransportError(`MCP http transport request "${request.method}" returned HTTP ${response.status}.`, {
+			type: "connect",
+			method: request.method,
+			context: { status: response.status }
+		});
+		return this.parseBody(response, request.method);
+	}
+	/**
+	* Parse the HTTP response body into a JSON-RPC response. Streamable HTTP
+	* may answer with either `application/json` (a single response object)
+	* or `text/event-stream` (SSE frames); we read the body as text and
+	* extract the first JSON object, supporting the common `data: {...}`
+	* SSE line shape without a streaming parser.
+	*/
+	async parseBody(response, method) {
+		const raw = await response.text();
+		const jsonText = (response.headers.get("content-type")?.toLowerCase() ?? "").includes("text/event-stream") ? extractSseData(raw) : raw;
+		if (!jsonText) throw new McpTransportError(`MCP http transport got an empty response for "${method}".`, {
+			type: "protocol",
+			method
+		});
+		try {
+			return JSON.parse(jsonText);
+		} catch (cause) {
+			throw new McpTransportError(`MCP http transport got a non-JSON response for "${method}".`, {
+				type: "protocol",
+				method,
+				cause
+			});
+		}
+	}
+	async notify(method, params) {
+		const notification = {
+			jsonrpc: JSONRPC_VERSION,
+			method,
+			params
+		};
+		try {
+			await fetch(this.url, {
+				method: "POST",
+				headers: this.headers,
+				body: JSON.stringify(notification)
+			});
+		} catch (cause) {
+			throw new McpTransportError(`MCP http transport notification "${method}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+				type: "connect",
+				method,
+				cause
+			});
+		}
+	}
+	/** Allocate the next outbound request id. */
+	allocateId() {
+		return this.nextId++;
+	}
+	async close() {}
+};
+/**
+* Pull the first `data:` JSON payload out of an SSE response body. MCP's
+* Streamable HTTP transport answers a single request with one SSE frame
+* carrying the JSON-RPC response; we take the first non-empty `data:`
+* line. Returns an empty string when none is found.
+*/
+function extractSseData(body) {
+	for (const line of body.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed.startsWith("data:")) {
+			const payload = trimmed.slice(5).trim();
+			if (payload && payload !== "[DONE]") return payload;
+		}
+	}
+	return "";
+}
+/**
+* Build the concrete {@link McpTransportClient} for an {@link McpTransport}
+* config — a {@link StdioTransport} for `type: "stdio"`, an
+* {@link HttpTransport} for `type: "http"`. The returned client also
+* carries an `allocateId()` for the JSON-RPC client to mint request ids.
+*
+* @param transport - The transport config (discriminated by `type`).
+* @returns A transport client paired with its id allocator.
+*/
+function createTransport(transport) {
+	if (transport.type === "stdio") return new StdioTransport(transport);
+	return new HttpTransport(transport);
+}
+/**
+* A minimal JSON-RPC 2.0 request/response client over any
+* {@link McpTransportClient}. Mints monotonic ids, frames the
+* `{ jsonrpc, id, method, params }` envelope, and unwraps the response —
+* translating a JSON-RPC `error` member into a typed
+* {@link McpTransportError} so callers branch on `error.type` rather than
+* parsing the wire.
+*
+* Constructed via {@link createJsonRpcClient}; the class itself is internal.
+*/
+var JsonRpcClient = class {
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/**
+	* Issue a JSON-RPC `method` call and resolve with its `result`,
+	* throwing a typed {@link McpTransportError} on a JSON-RPC error member
+	* or a malformed response (neither `result` nor `error`).
+	*/
+	async call(method, params, options) {
+		const request = {
+			jsonrpc: JSONRPC_VERSION,
+			id: this.transport.allocateId(),
+			method,
+			params
+		};
+		const response = await this.transport.request(request, options);
+		if (response.error) throw new McpTransportError(`MCP "${method}" failed: ${response.error.message} (code ${response.error.code}).`, {
+			type: "protocol",
+			method,
+			context: { code: response.error.code },
+			cause: response.error.data
+		});
+		if (response.result === void 0) throw new McpTransportError(`MCP "${method}" returned a response with neither result nor error.`, {
+			type: "protocol",
+			method
+		});
+		return response.result;
+	}
+	/** Send a one-way JSON-RPC notification (no response awaited). */
+	notify(method, params) {
+		return this.transport.notify(method, params);
+	}
+	/** Close the underlying transport. */
+	close() {
+		return this.transport.close();
+	}
+};
+/**
+* Build a {@link JsonRpcClientHandle} over a transport. Accepts either a
+* pre-built {@link McpTransportClient} (the test seam — inject a scripted
+* fake) or an {@link McpTransport} config, in which case the concrete
+* transport is constructed via {@link createTransport}.
+*
+* When a bare {@link McpTransportClient} (without an `allocateId`) is
+* injected, the client supplies its own monotonic id source.
+*
+* @param source - A transport client or an `McpTransport` config.
+* @returns A JSON-RPC client handle.
+*/
+function createJsonRpcClient(source) {
+	return new JsonRpcClient(isTransportConfig(source) ? createTransport(source) : withIdAllocator(source));
+}
+/**
+* Distinguish an {@link McpTransport} config (a plain object with a `type`
+* discriminator and no `request` method) from a built
+* {@link McpTransportClient} (which exposes `request`).
+*/
+function isTransportConfig(source) {
+	return typeof source.request !== "function";
+}
+/**
+* Wrap an injected {@link McpTransportClient} that lacks its own
+* `allocateId` with a monotonic id source, so the JSON-RPC client can mint
+* request ids uniformly regardless of whether the transport was built here
+* or supplied by a test.
+*/
+function withIdAllocator(client) {
+	const candidate = client;
+	if (typeof candidate.allocateId === "function") return candidate;
+	let nextId = 1;
+	return Object.assign(client, { allocateId: () => nextId++ });
+}
+
+//#endregion
+export { createJsonRpcClient, createTransport };
+//# sourceMappingURL=transport.mjs.map

package/esm/mcp/transport.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/mcp/transport.ts"],"sourcesContent":["import { spawn, type ChildProcessWithoutNullStreams } from \"node:child_process\";\nimport { createInterface, type Interface } from \"node:readline\";\nimport type {\n  JsonRpcId,\n  JsonRpcRequest,\n  JsonRpcResponse,\n  McpTransport,\n} from \"../contracts\";\nimport { McpTransportError } from \"../errors\";\nimport type { McpTransportClient } from \"./transport.type\";\n\n/** Default per-request wait before a transport call is abandoned. */\nconst DEFAULT_REQUEST_TIMEOUT_MS = 30_000;\n\n/** The JSON-RPC version literal every outbound message carries. */\nconst JSONRPC_VERSION = \"2.0\";\n\n/**\n * A pending in-flight request awaiting its correlated response, keyed by\n * the JSON-RPC `id`. The stdio transport multiplexes many requests over\n * one line-framed pipe, so each resolve/reject is parked here until the\n * line whose `id` matches arrives.\n */\ninterface PendingCall {\n  resolve(response: JsonRpcResponse): void;\n  reject(error: McpTransportError): void;\n  /** Clears the per-call timeout + abort wiring when the call settles. */\n  cleanup(): void;\n}\n\n/**\n * Wire a per-call timeout and an optional caller `AbortSignal` onto a\n * pending request, returning a `cleanup()` that tears both down. The\n * `onSettle` callback removes the pending entry from whatever registry the\n * transport keeps so a late response can't double-settle.\n */\nfunction armCall(\n  reject: (error: McpTransportError) => void,\n  method: string,\n  options: { signal?: AbortSignal; timeoutMs?: number } | undefined,\n  onSettle: () => void,\n): () => void {\n  const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;\n\n  const timer = setTimeout(() => {\n    onSettle();\n    reject(\n      new McpTransportError(\n        `MCP request \"${method}\" timed out after ${timeoutMs}ms.`,\n        { type: \"timeout\", method },\n      ),\n    );\n  }, timeoutMs);\n\n  const onAbort = () => {\n    cleanup();\n    reject(\n      new McpTransportError(`MCP request \"${method}\" was aborted.`, {\n        type: \"closed\",\n        method,\n      }),\n    );\n  };\n\n  const signal = options?.signal;\n\n  if (signal) {\n    if (signal.aborted) {\n      // Defer so the caller has the rejection wired before it fires.\n      queueMicrotask(onAbort);\n    } else {\n      signal.addEventListener(\"abort\", onAbort, { once: true });\n    }\n  }\n\n  function cleanup(): void {\n    clearTimeout(timer);\n\n    if (signal) {\n      signal.removeEventListener(\"abort\", onAbort);\n    }\n  }\n\n  return cleanup;\n}\n\n/**\n * The stdio transport — spawns a child process and speaks JSON-RPC over\n * its stdin/stdout, one JSON object per line (newline-delimited framing).\n * Uses only Node built-ins (`node:child_process` + `node:readline`); no\n * dependency.\n *\n * Constructed via {@link createStdioTransport}; the class itself is\n * internal.\n */\nclass StdioTransport implements McpTransportClient {\n  /** The spawned server process. */\n  private readonly child: ChildProcessWithoutNullStreams;\n\n  /** Line reader over the child's stdout — one JSON-RPC message per line. */\n  private readonly reader: Interface;\n\n  /** In-flight requests awaiting a correlated response, keyed by id. */\n  private readonly pending = new Map<JsonRpcId, PendingCall>();\n\n  /** Monotonic id source for outbound requests. */\n  private nextId = 1;\n\n  /** Flipped once {@link close} runs (or the child exits) so reuse rejects. */\n  private closed = false;\n\n  public constructor(transport: Extract<McpTransport, { type: \"stdio\" }>) {\n    let child: ChildProcessWithoutNullStreams;\n\n    try {\n      child = spawn(transport.command, transport.args ?? [], {\n        // process.env is NOT inherited unless the caller opts in — pass\n        // what the server needs explicitly, mirroring the workspace shell\n        // policy. `undefined` lets Node default to an empty-ish env.\n        env: transport.env,\n        stdio: [\"pipe\", \"pipe\", \"pipe\"],\n      }) as ChildProcessWithoutNullStreams;\n    } catch (cause) {\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        `MCP stdio transport could not spawn \"${transport.command}\": ${message}`,\n        { type: \"connect\", cause },\n      );\n    }\n\n    this.child = child;\n    this.reader = createInterface({ input: child.stdout });\n\n    this.reader.on(\"line\", (line) => this.onLine(line));\n\n    // A child that dies takes every in-flight (and future) call with it.\n    child.on(\"exit\", (code) => this.failAll(\"connect\", `child exited with code ${code ?? \"null\"}`));\n    child.on(\"error\", (error) => this.failAll(\"connect\", error.message));\n  }\n\n  /**\n   * Parse one stdout line and route it to its pending request. Non-JSON\n   * lines (a server logging to stdout) and messages with no matching `id`\n   * (notifications, stray responses) are ignored — robustness over strictness.\n   */\n  private onLine(line: string): void {\n    const trimmed = line.trim();\n\n    if (!trimmed) {\n      return;\n    }\n\n    let message: JsonRpcResponse;\n\n    try {\n      message = JSON.parse(trimmed) as JsonRpcResponse;\n    } catch {\n      // Not a JSON-RPC line (server diagnostics on stdout) — ignore.\n      return;\n    }\n\n    if (message.id === undefined || message.id === null) {\n      // A notification or a malformed response — nothing to correlate.\n      return;\n    }\n\n    const call = this.pending.get(message.id);\n\n    if (!call) {\n      return;\n    }\n\n    this.pending.delete(message.id);\n    call.cleanup();\n    call.resolve(message);\n  }\n\n  /**\n   * Reject every pending call (and mark the transport unusable) when the\n   * child dies or errors — so a hung server can never leave a caller\n   * waiting forever.\n   */\n  private failAll(type: \"connect\" | \"closed\", reason: string): void {\n    this.closed = true;\n\n    for (const [id, call] of this.pending) {\n      this.pending.delete(id);\n      call.cleanup();\n      call.reject(\n        new McpTransportError(`MCP stdio transport failed: ${reason}.`, { type }),\n      );\n    }\n  }\n\n  public request<TResult = unknown>(\n    request: JsonRpcRequest,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<JsonRpcResponse<TResult>> {\n    if (this.closed) {\n      return Promise.reject(\n        new McpTransportError(\"MCP stdio transport is closed.\", {\n          type: \"closed\",\n          method: request.method,\n        }),\n      );\n    }\n\n    const id = request.id;\n\n    return new Promise<JsonRpcResponse<TResult>>((resolve, reject) => {\n      const cleanup = armCall(reject, request.method, options, () =>\n        this.pending.delete(id),\n      );\n\n      this.pending.set(id, {\n        resolve: (response) => resolve(response as JsonRpcResponse<TResult>),\n        reject,\n        cleanup,\n      });\n\n      try {\n        this.child.stdin.write(`${JSON.stringify(request)}\\n`);\n      } catch (cause) {\n        this.pending.delete(id);\n        cleanup();\n\n        const message = cause instanceof Error ? cause.message : String(cause);\n\n        reject(\n          new McpTransportError(\n            `MCP stdio transport failed to write request \"${request.method}\": ${message}`,\n            { type: \"closed\", method: request.method, cause },\n          ),\n        );\n      }\n    });\n  }\n\n  public async notify(method: string, params?: unknown): Promise<void> {\n    if (this.closed) {\n      throw new McpTransportError(\"MCP stdio transport is closed.\", {\n        type: \"closed\",\n        method,\n      });\n    }\n\n    const notification = { jsonrpc: JSONRPC_VERSION, method, params };\n    this.child.stdin.write(`${JSON.stringify(notification)}\\n`);\n  }\n\n  /** Allocate the next outbound request id. */\n  public allocateId(): number {\n    return this.nextId++;\n  }\n\n  public async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n\n    this.closed = true;\n    this.reader.close();\n    this.failAll(\"closed\", \"transport closed by caller\");\n    this.child.kill();\n  }\n}\n\n/**\n * The Streamable HTTP transport — POSTs each JSON-RPC request to the\n * server endpoint over the global `fetch` (Node 18+) and reads the single\n * JSON response. No SSE-legacy, no WebSocket. Static `headers` (e.g. auth)\n * are sent with every request.\n *\n * Constructed via {@link createHttpTransport}; the class itself is internal.\n */\nclass HttpTransport implements McpTransportClient {\n  /** The server endpoint POST target. */\n  private readonly url: string;\n\n  /** Static headers merged into every request (auth, etc.). */\n  private readonly headers: Record<string, string>;\n\n  /** Monotonic id source for outbound requests. */\n  private nextId = 1;\n\n  public constructor(transport: Extract<McpTransport, { type: \"http\" }>) {\n    this.url = transport.url;\n    this.headers = {\n      \"content-type\": \"application/json\",\n      accept: \"application/json, text/event-stream\",\n      ...transport.headers,\n    };\n  }\n\n  public async request<TResult = unknown>(\n    request: JsonRpcRequest,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<JsonRpcResponse<TResult>> {\n    const timeoutMs = options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    const onAbort = () => controller.abort();\n    const signal = options?.signal;\n\n    if (signal) {\n      if (signal.aborted) {\n        controller.abort();\n      } else {\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n      }\n    }\n\n    let response: Response;\n\n    try {\n      response = await fetch(this.url, {\n        method: \"POST\",\n        headers: this.headers,\n        body: JSON.stringify(request),\n        signal: controller.signal,\n      });\n    } catch (cause) {\n      const aborted = controller.signal.aborted;\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        aborted\n          ? `MCP request \"${request.method}\" timed out or was aborted after ${timeoutMs}ms.`\n          : `MCP http transport request \"${request.method}\" failed: ${message}`,\n        { type: aborted ? \"timeout\" : \"connect\", method: request.method, cause },\n      );\n    } finally {\n      clearTimeout(timer);\n\n      if (signal) {\n        signal.removeEventListener(\"abort\", onAbort);\n      }\n    }\n\n    if (!response.ok) {\n      throw new McpTransportError(\n        `MCP http transport request \"${request.method}\" returned HTTP ${response.status}.`,\n        { type: \"connect\", method: request.method, context: { status: response.status } },\n      );\n    }\n\n    return this.parseBody<TResult>(response, request.method);\n  }\n\n  /**\n   * Parse the HTTP response body into a JSON-RPC response. Streamable HTTP\n   * may answer with either `application/json` (a single response object)\n   * or `text/event-stream` (SSE frames); we read the body as text and\n   * extract the first JSON object, supporting the common `data: {...}`\n   * SSE line shape without a streaming parser.\n   */\n  private async parseBody<TResult>(\n    response: Response,\n    method: string,\n  ): Promise<JsonRpcResponse<TResult>> {\n    const raw = await response.text();\n    const contentType = response.headers.get(\"content-type\")?.toLowerCase() ?? \"\";\n\n    const jsonText = contentType.includes(\"text/event-stream\")\n      ? extractSseData(raw)\n      : raw;\n\n    if (!jsonText) {\n      throw new McpTransportError(\n        `MCP http transport got an empty response for \"${method}\".`,\n        { type: \"protocol\", method },\n      );\n    }\n\n    try {\n      return JSON.parse(jsonText) as JsonRpcResponse<TResult>;\n    } catch (cause) {\n      throw new McpTransportError(\n        `MCP http transport got a non-JSON response for \"${method}\".`,\n        { type: \"protocol\", method, cause },\n      );\n    }\n  }\n\n  public async notify(method: string, params?: unknown): Promise<void> {\n    const notification = { jsonrpc: JSONRPC_VERSION, method, params };\n\n    // A notification expects no response; fire-and-forget but surface a\n    // connect failure so a dead endpoint is not silently ignored.\n    try {\n      await fetch(this.url, {\n        method: \"POST\",\n        headers: this.headers,\n        body: JSON.stringify(notification),\n      });\n    } catch (cause) {\n      const message = cause instanceof Error ? cause.message : String(cause);\n\n      throw new McpTransportError(\n        `MCP http transport notification \"${method}\" failed: ${message}`,\n        { type: \"connect\", method, cause },\n      );\n    }\n  }\n\n  /** Allocate the next outbound request id. */\n  public allocateId(): number {\n    return this.nextId++;\n  }\n\n  public async close(): Promise<void> {\n    // Streamable HTTP is stateless per request — nothing persistent to\n    // release.\n  }\n}\n\n/**\n * Pull the first `data:` JSON payload out of an SSE response body. MCP's\n * Streamable HTTP transport answers a single request with one SSE frame\n * carrying the JSON-RPC response; we take the first non-empty `data:`\n * line. Returns an empty string when none is found.\n */\nfunction extractSseData(body: string): string {\n  for (const line of body.split(/\\r?\\n/)) {\n    const trimmed = line.trim();\n\n    if (trimmed.startsWith(\"data:\")) {\n      const payload = trimmed.slice(\"data:\".length).trim();\n\n      if (payload && payload !== \"[DONE]\") {\n        return payload;\n      }\n    }\n  }\n\n  return \"\";\n}\n\n/**\n * Build the concrete {@link McpTransportClient} for an {@link McpTransport}\n * config — a {@link StdioTransport} for `type: \"stdio\"`, an\n * {@link HttpTransport} for `type: \"http\"`. The returned client also\n * carries an `allocateId()` for the JSON-RPC client to mint request ids.\n *\n * @param transport - The transport config (discriminated by `type`).\n * @returns A transport client paired with its id allocator.\n */\nexport function createTransport(\n  transport: McpTransport,\n): McpTransportClient & { allocateId(): number } {\n  if (transport.type === \"stdio\") {\n    return new StdioTransport(transport);\n  }\n\n  return new HttpTransport(transport);\n}\n\n/**\n * A minimal JSON-RPC 2.0 request/response client over any\n * {@link McpTransportClient}. Mints monotonic ids, frames the\n * `{ jsonrpc, id, method, params }` envelope, and unwraps the response —\n * translating a JSON-RPC `error` member into a typed\n * {@link McpTransportError} so callers branch on `error.type` rather than\n * parsing the wire.\n *\n * Constructed via {@link createJsonRpcClient}; the class itself is internal.\n */\nclass JsonRpcClient {\n  /** The underlying framing transport. */\n  private readonly transport: McpTransportClient & { allocateId(): number };\n\n  public constructor(transport: McpTransportClient & { allocateId(): number }) {\n    this.transport = transport;\n  }\n\n  /**\n   * Issue a JSON-RPC `method` call and resolve with its `result`,\n   * throwing a typed {@link McpTransportError} on a JSON-RPC error member\n   * or a malformed response (neither `result` nor `error`).\n   */\n  public async call<TResult = unknown>(\n    method: string,\n    params?: unknown,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<TResult> {\n    const request: JsonRpcRequest = {\n      jsonrpc: JSONRPC_VERSION,\n      id: this.transport.allocateId(),\n      method,\n      params,\n    };\n\n    const response = await this.transport.request<TResult>(request, options);\n\n    if (response.error) {\n      throw new McpTransportError(\n        `MCP \"${method}\" failed: ${response.error.message} (code ${response.error.code}).`,\n        { type: \"protocol\", method, context: { code: response.error.code }, cause: response.error.data },\n      );\n    }\n\n    if (response.result === undefined) {\n      throw new McpTransportError(\n        `MCP \"${method}\" returned a response with neither result nor error.`,\n        { type: \"protocol\", method },\n      );\n    }\n\n    return response.result;\n  }\n\n  /** Send a one-way JSON-RPC notification (no response awaited). */\n  public notify(method: string, params?: unknown): Promise<void> {\n    return this.transport.notify(method, params);\n  }\n\n  /** Close the underlying transport. */\n  public close(): Promise<void> {\n    return this.transport.close();\n  }\n}\n\n/**\n * A JSON-RPC client over an MCP transport. Either pass an already-built\n * transport client (tests inject a fake) or an {@link McpTransport} config\n * to spawn/connect a real one.\n */\nexport interface JsonRpcClientHandle {\n  /** Issue a request and resolve with its `result` (throws on error). */\n  call<TResult = unknown>(\n    method: string,\n    params?: unknown,\n    options?: { signal?: AbortSignal; timeoutMs?: number },\n  ): Promise<TResult>;\n  /** Send a one-way notification. */\n  notify(method: string, params?: unknown): Promise<void>;\n  /** Close the underlying transport. */\n  close(): Promise<void>;\n}\n\n/**\n * Build a {@link JsonRpcClientHandle} over a transport. Accepts either a\n * pre-built {@link McpTransportClient} (the test seam — inject a scripted\n * fake) or an {@link McpTransport} config, in which case the concrete\n * transport is constructed via {@link createTransport}.\n *\n * When a bare {@link McpTransportClient} (without an `allocateId`) is\n * injected, the client supplies its own monotonic id source.\n *\n * @param source - A transport client or an `McpTransport` config.\n * @returns A JSON-RPC client handle.\n */\nexport function createJsonRpcClient(\n  source: McpTransport | McpTransportClient,\n): JsonRpcClientHandle {\n  const transport: McpTransportClient & { allocateId(): number } = isTransportConfig(source)\n    ? createTransport(source)\n    : withIdAllocator(source);\n\n  return new JsonRpcClient(transport);\n}\n\n/**\n * Distinguish an {@link McpTransport} config (a plain object with a `type`\n * discriminator and no `request` method) from a built\n * {@link McpTransportClient} (which exposes `request`).\n */\nfunction isTransportConfig(\n  source: McpTransport | McpTransportClient,\n): source is McpTransport {\n  return typeof (source as McpTransportClient).request !== \"function\";\n}\n\n/**\n * Wrap an injected {@link McpTransportClient} that lacks its own\n * `allocateId` with a monotonic id source, so the JSON-RPC client can mint\n * request ids uniformly regardless of whether the transport was built here\n * or supplied by a test.\n */\nfunction withIdAllocator(\n  client: McpTransportClient,\n): McpTransportClient & { allocateId(): number } {\n  const candidate = client as McpTransportClient & { allocateId?(): number };\n\n  if (typeof candidate.allocateId === \"function\") {\n    return candidate as McpTransportClient & { allocateId(): number };\n  }\n\n  let nextId = 1;\n\n  return Object.assign(client, { allocateId: () => nextId++ });\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,51 @@
+import { JsonRpcRequest, JsonRpcResponse } from "../contracts/mcp.type.mjs";
+//#region ../@warlock.js/ai-tools/src/mcp/transport.type.d.ts
+/**
+ * Internal contract every concrete MCP transport (stdio / Streamable HTTP)
+ * satisfies. Pure declaration — the factories that build transports live
+ * in `transport.ts`.
+ *
+ * A transport is a thin, framing-only layer: it ships one JSON-RPC request
+ * out and resolves with the matching response, and it can ship a one-way
+ * notification (no response expected). It owns nothing protocol-specific —
+ * the `initialize` handshake, `tools/list`, and `tools/call` semantics all
+ * live above it in {@link import("./client").mcp}.
+ *
+ * **`type`, never `kind`.** This package's discriminators are all `type`;
+ * any inbound MCP `kind` is translated at the client boundary.
+ */
+interface McpTransportClient {
+  /**
+   * Send a JSON-RPC request and resolve with its matching response.
+   *
+   * The transport correlates the response by `id`; on a stdio transport
+   * that means matching the line whose `id` equals the request's, on HTTP
+   * it is the single response to the POST. Honors `signal` to abort an
+   * in-flight call (rejecting the returned promise) and `timeoutMs` to
+   * bound the wait.
+   *
+   * @param request - A fully-formed JSON-RPC request (caller assigns `id`).
+   * @param options - Optional per-call abort signal and timeout.
+   */
+  request<TResult = unknown>(request: JsonRpcRequest, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  }): Promise<JsonRpcResponse<TResult>>;
+  /**
+   * Send a JSON-RPC notification — a method call with no `id` that
+   * expects no response (e.g. the post-handshake `notifications/initialized`).
+   *
+   * @param method - The notification method name.
+   * @param params - Optional method parameters.
+   */
+  notify(method: string, params?: unknown): Promise<void>;
+  /**
+   * Close the transport, releasing its resources — kill the spawned child
+   * (stdio) or drop the session (http). Idempotent: closing twice is a
+   * no-op.
+   */
+  close(): Promise<void>;
+}
+//#endregion
+export { McpTransportClient };
+//# sourceMappingURL=transport.type.d.mts.map

package/esm/mcp/transport.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/mcp/transport.type.ts"],"mappings":";;;;;AAgBA;;;;;;;;;;;UAAiB,kBAAA;EAaf;;;;;;;;;;;;EAAA,OAAA,oBACE,OAAA,EAAS,cAAA,EACT,OAAA;IAAY,MAAA,GAAS,WAAA;IAAa,SAAA;EAAA,IACjC,OAAA,CAAQ,eAAA,CAAgB,OAAA;EAgBlB;;AAAO;;;;;EAPhB,MAAA,CAAO,MAAA,UAAgB,MAAA,aAAmB,OAAA;;;;;;EAO1C,KAAA,IAAS,OAAA;AAAA"}

package/esm/node_modules/@standard-schema/spec/dist/index.d.mts

@@ -0,0 +1,80 @@
+//#region ../@warlock.js/node_modules/@standard-schema/spec/dist/index.d.ts
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+/** The Standard JSON Schema interface. */
+//#endregion
+export { StandardSchemaV1 };
+//# sourceMappingURL=index.d.mts.map

package/esm/node_modules/@standard-schema/spec/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":["Input","Output","StandardTypedV1","Props","version","vendor","types","Types","input","output","InferInput","Schema","NonNullable","InferOutput","StandardSchemaV1","validate","value","Options","options","Result","Promise","SuccessResult","FailureResult","issues","libraryOptions","Record","ReadonlyArray","Issue","message","path","PropertyKey","PathSegment","key","StandardJSONSchemaV1","jsonSchema","Converter","Target","target"],"sources":["../../../../../../../../../../@warlock.js/node_modules/@standard-schema/spec/dist/index.d.ts"],"x_google_ignoreList":[0],"mappings":";;UACU,eAAA,2BAA0C,KAAA;EAA3B;EAAA,SAEZ,WAAA,EAAa,eAAA,CAAgB,KAAA,CAAM,KAAA,EAAO,MAAA;AAAA;AAAA,kBAErC,eAAA;EAFqC;EAAA,UAIzCG,KAAAA,2BAAgC,KAAA;IAJC;IAAA,SAM9BC,OAAAA;IARSJ;IAAAA,SAUTK,MAAAA;IAVmCL;IAAAA,SAYnCM,KAAAA,GAAQ,KAAA,CAAM,KAAA,EAAO,MAAA;EAAA;EAVIH;EAAAA,UAa5BI,KAAAA,2BAAgC,KAAA;IAbSN;IAAAA,SAetCO,KAAAA,EAAO,KAAA;IAfqC;IAAA,SAiB5CC,MAAAA,EAAQ,MAAA;EAAA;EAfQ;EAAA,KAkBxBC,UAAAA,gBAA0B,eAAA,IAAmB,WAAA,CAAY,MAAA;EAVnC;EAAA,KAYtBG,WAAAA,gBAA2B,eAAA,IAAmB,WAAA,CAAY,MAAA;AAAA;;UAGzD,gBAAA,2BAA2C,KAAA;EAR5B;EAAA,SAUZ,WAAA,EAAa,gBAAA,CAAiB,KAAA,CAAM,KAAA,EAAO,MAAA;AAAA;AAAA,kBAEtC,gBAAA;EAPkB;EAAA,UAStBV,KAAAA,2BAAgC,KAAA,UAAe,eAAA,CAAgB,KAAA,CAAM,KAAA,EAAO,MAAA;IATnC;IAAA,SAWtCY,QAAAA,GAAWC,KAAAA,WAAgBE,OAAAA,GAAU,gBAAA,CAAiB,OAAA,iBAAwB,MAAA,CAAO,MAAA,IAAU,OAAA,CAAQ,MAAA,CAAO,MAAA;EAAA;EA7BjHf;EAAAA,KAgCLgB,MAAAA,WAAiB,aAAA,CAAc,MAAA,IAAU,aAAA;EAhCblB;EAAAA,UAkCvBoB,aAAAA;IAhCGjB;IAAAA,SAkCAY,KAAAA,EAAO,MAAA;IA9BPV;IAAAA,SAgCAiB,MAAAA;EAAAA;EAAAA,UAEHN,OAAAA;IA/BAV;IAAAA,SAiCGiB,cAAAA,GAAiB,MAAA;EAAA;EAjCYxB;EAAAA,UAoChCsB,aAAAA;IAlCUtB;IAAAA,SAoCPuB,MAAAA,EAAQ,aAAA,CAAc,KAAA;EAAA;EA/B9Bb;EAAAA,UAkCKiB,KAAAA;IAlCqBzB;IAAAA,SAoClB0B,OAAAA;IApCiDjB;IAAAA,SAsCjDkB,IAAAA,GAAO,aAAA,CAAc,WAAA,GAAc,WAAA;EAAA;EApChB3B;EAAAA,UAuCtB6B,WAAAA;IAvCqDpB;IAAAA,SAyClDqB,GAAAA,EAAK,WAAA;EAAA;EAtCZ;EAAA,UAyCIzB,KAAAA,2BAAgC,KAAA,UAAe,eAAA,CAAgB,KAAA,CAAM,KAAA,EAAO,MAAA;EAzCrC;EAAA,KA4C5CG,UAAAA,gBAA0B,eAAA,IAAmB,eAAA,CAAgB,UAAA,CAAW,MAAA;EA1CzB;EAAA,KA4C/CG,WAAAA,gBAA2B,eAAA,IAAmB,eAAA,CAAgB,WAAA,CAAY,MAAA;AAAA"}

package/esm/register.d.mts

@@ -0,0 +1,55 @@
+import { FetchUrlInput, FetchUrlOptions, FetchUrlResult, WebSearchInput, WebSearchOptions, WebSearchResult } from "./contracts/web.type.mjs";
+import { HttpRequestInput, HttpRequestOptions, HttpRequestResult } from "./contracts/http.type.mjs";
+import { CalculatorInput, CalculatorOptions, CalculatorResult, DateTimeInput, DateTimeOptions, DateTimeResult } from "./contracts/utility.type.mjs";
+import { McpFactory } from "./mcp/index.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/register.d.ts
+/**
+ * The `ai.tools.*` namespace — the five ready-made agent tools this
+ * package vends. Each member is a factory returning a {@link ToolContract}
+ * that drops straight into `ai.agent({ tools: [...] })`. Declared inline on
+ * the `Ai` interface below (one block, one shape) rather than accreted
+ * across the tool sub-barrels, mirroring the `ai.workspace` augmentation in
+ * `@warlock.js/ai-workspace`.
+ */
+interface AiToolsNamespace {
+  /** Search the web via a chosen provider; returns ranked LLM-ready hits. */
+  webSearch(options: WebSearchOptions): ToolContract<WebSearchInput, WebSearchResult>;
+  /** Fetch a URL (host-allowlisted, byte-capped) and return its content. */
+  fetchUrl(options?: FetchUrlOptions): ToolContract<FetchUrlInput, FetchUrlResult>;
+  /** A guarded HTTP/REST client — method + host allowlists, byte/timeout caps. */
+  http(options?: HttpRequestOptions): ToolContract<HttpRequestInput, HttpRequestResult>;
+  /** A SAFE arithmetic-expression evaluator (no `eval`/`Function`). */
+  calculator(options?: CalculatorOptions): ToolContract<CalculatorInput, CalculatorResult>;
+  /** Clock/calendar ops — now / add / diff / format over ISO instants. */
+  dateTime(options?: DateTimeOptions): ToolContract<DateTimeInput, DateTimeResult>;
+}
+/**
+ * Attach the `tools` namespace and the `mcp` factory to the `ai` namespace
+ * via module augmentation, per the `ai.`-namespace convention.
+ * `@warlock.js/ai` now exposes a named `Ai` interface for exactly this, so
+ * after a bare `import "@warlock.js/ai-tools"`, `ai.tools.webSearch(...)`,
+ * `ai.tools.http(...)`, `ai.mcp(server)`, and `ai.mcp.serve(source)` are all
+ * globally typed — no view/cast needed.
+ */
+declare module "@warlock.js/ai" {
+  interface Ai {
+    /**
+     * Ready-made agent tools from `@warlock.js/ai-tools` — web search,
+     * fetch/scrape, HTTP/REST, calculator, and date-time. Each returns a
+     * `ToolContract` that slots into `ai.agent({ tools: [...] })`.
+     */
+    tools: AiToolsNamespace;
+    /**
+     * The Model Context Protocol surface — `ai.mcp(server)` connects to an
+     * external MCP server and adapts its tools as agent tools (Direction A),
+     * while `ai.mcp.serve(source, options)` exposes a local primitive AS an
+     * MCP server other clients can consume (Direction B).
+     */
+    mcp: McpFactory;
+  }
+} //# sourceMappingURL=register.d.ts.map
+//#endregion
+export { AiToolsNamespace };
+//# sourceMappingURL=register.d.mts.map

package/esm/register.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai-tools/src/register.ts"],"mappings":";;;;;;;;;;;;AAiCA;;;UAAiB,gBAAA;EAEoC;EAAnD,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,YAAA,CAAa,cAAA,EAAgB,eAAA;EAA7B;EAEtC,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,YAAA,CAAa,aAAA,EAAe,cAAA;EAAf;EAElD,IAAA,CAAK,OAAA,GAAU,kBAAA,GAAqB,YAAA,CAAa,gBAAA,EAAkB,iBAAA;EAF9B;EAIrC,UAAA,CAAW,OAAA,GAAU,iBAAA,GAAoB,YAAA,CAAa,eAAA,EAAiB,gBAAA;EAFtB;EAIjD,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,YAAA,CAAa,aAAA,EAAe,cAAA;AAAA;;;;;;;;;;YAYvD,EAAA;IApBV;;;;;IA0BE,KAAA,EAAO,gBAAA;IAxBT;;;;;;IA+BE,GAAA,EAAK,UAAU;EAAA;AAAA"}

package/esm/register.mjs

@@ -0,0 +1,21 @@
+import { httpRequestTool } from "./http/http-request.mjs";
+import { mcp } from "./mcp/index.mjs";
+import { calculatorTool } from "./utility/calculator.mjs";
+import { dateTimeTool } from "./utility/date-time.mjs";
+import { fetchUrlTool } from "./web/fetch-url.mjs";
+import { webSearchTool } from "./web/web-search.mjs";
+import { ai } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/register.ts
+ai.tools = {
+	webSearch: webSearchTool,
+	fetchUrl: fetchUrlTool,
+	http: httpRequestTool,
+	calculator: calculatorTool,
+	dateTime: (options) => dateTimeTool(options)
+};
+ai.mcp = mcp;
+
+//#endregion
+export {  };
+//# sourceMappingURL=register.mjs.map