stitchkit 0.88.0 → 0.90.0

package/dist/tools/connections/index.js

@@ -0,0 +1,1047 @@
+import {
+  defineRuntimeTool
+} from "../../index-kc6h6hg0.js";
+import"../../index-r159gjwy.js";
+import"../../index-cby4ar3v.js";
+import {
+  isRecord
+} from "../../index-77fekveh.js";
+
+// src/tools/connections/errors.ts
+class ConnectionAuthorizationRequiredError extends Error {
+  connectionName;
+  instanceId;
+  constructor(connectionName, instanceId) {
+    super(`Connection "${connectionName}" requires authorization`);
+    this.name = "ConnectionAuthorizationRequiredError";
+    this.connectionName = connectionName;
+    this.instanceId = instanceId;
+  }
+}
+
+class ConnectionRequestError extends Error {
+  connectionName;
+  status;
+  body;
+  constructor(connectionName, status, body) {
+    super(`Connection "${connectionName}" request failed with status ${status}`);
+    this.name = "ConnectionRequestError";
+    this.connectionName = connectionName;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class ConnectionUrlError extends Error {
+  url;
+  constructor(message, url) {
+    super(message);
+    this.name = "ConnectionUrlError";
+    this.url = url;
+  }
+}
+
+class ConnectionBudgetExceededError extends Error {
+  limit;
+  actual;
+  constructor(limit, actual, unit = "tools") {
+    super(`Connection surface exposes ${actual} ${unit}, above the budget of ${limit}`);
+    this.name = "ConnectionBudgetExceededError";
+    this.limit = limit;
+    this.actual = actual;
+  }
+}
+
+class ConnectionTimeoutError extends Error {
+  connectionName;
+  timeoutMs;
+  constructor(connectionName, timeoutMs) {
+    super(`Connection "${connectionName}" timed out after ${timeoutMs} ms`);
+    this.name = "ConnectionTimeoutError";
+    this.connectionName = connectionName;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+class ConnectionResponseTooLargeError extends Error {
+  connectionName;
+  maxBytes;
+  constructor(connectionName, maxBytes) {
+    super(`Connection "${connectionName}" response exceeded the ${maxBytes} byte limit`);
+    this.name = "ConnectionResponseTooLargeError";
+    this.connectionName = connectionName;
+    this.maxBytes = maxBytes;
+  }
+}
+
+// src/tools/connections/ssrf.ts
+function assertConnectionUrl(rawUrl, connectionName) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new ConnectionUrlError(`Connection "${connectionName}" has an unparseable URL: ${rawUrl}`, rawUrl);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ConnectionUrlError(`Connection "${connectionName}" must use http(s), got "${url.protocol}"`, rawUrl);
+  }
+  return url;
+}
+function connectionAllowedHosts(connectionUrl, extra) {
+  const hosts = new Set([connectionUrl.host.toLowerCase()]);
+  for (const host of extra ?? [])
+    hosts.add(host.toLowerCase());
+  return hosts;
+}
+function assertAllowedHost(url, allowedHosts, connectionName) {
+  if (!allowedHosts.has(url.host.toLowerCase())) {
+    throw new ConnectionUrlError(`Connection "${connectionName}" refused request to host "${url.host}": not the connection host or an allowed host`, url.toString());
+  }
+}
+
+// src/tools/connections/define.ts
+function defineMcpClientConnection(config) {
+  if (!config.name.trim())
+    throw new Error("MCP connection requires a name");
+  assertConnectionUrl(config.transport.url, config.name);
+  return { ...config, kind: "mcp" };
+}
+function defineOpenApiConnection(config) {
+  if (!config.name.trim())
+    throw new Error("OpenAPI connection requires a name");
+  if (config.baseUrl)
+    assertConnectionUrl(config.baseUrl, config.name);
+  return { ...config, kind: "openapi" };
+}
+// src/tools/connections/instance.ts
+import { createHash } from "node:crypto";
+function connectionInstanceId(name, url, instanceKey) {
+  return createHash("sha256").update(`${name}\x00${url}\x00${instanceKey ?? ""}`).digest("hex").slice(0, 32);
+}
+
+// src/tools/connections/mcp.ts
+import { z as z2 } from "zod";
+
+// src/tools/connections/limits.ts
+var DEFAULT_CONNECTION_TIMEOUT_MS = 30000;
+var DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
+function connectionTimeoutMs(value) {
+  return value !== undefined && value > 0 ? value : DEFAULT_CONNECTION_TIMEOUT_MS;
+}
+function connectionMaxResponseBytes(value) {
+  return value !== undefined && value > 0 ? value : DEFAULT_MAX_RESPONSE_BYTES;
+}
+async function withConnectionDeadline(connectionName, timeoutMs, callerSignal, body) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(new ConnectionTimeoutError(connectionName, timeoutMs)), timeoutMs);
+  const onAbort = () => controller.abort(callerSignal?.reason);
+  if (callerSignal) {
+    if (callerSignal.aborted)
+      controller.abort(callerSignal.reason);
+    else
+      callerSignal.addEventListener("abort", onAbort, { once: true });
+  }
+  try {
+    return await body(controller.signal);
+  } finally {
+    clearTimeout(timer);
+    callerSignal?.removeEventListener("abort", onAbort);
+  }
+}
+async function readBoundedText(response, maxBytes, connectionName) {
+  const stream = response.body;
+  if (!stream)
+    return "";
+  const reader = stream.getReader();
+  const decoder = new TextDecoder;
+  let total = 0;
+  let text = "";
+  try {
+    for (;; ) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {
+          return;
+        });
+        throw new ConnectionResponseTooLargeError(connectionName, maxBytes);
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+    text += decoder.decode();
+    return text;
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function readBoundedJson(response, maxBytes, connectionName) {
+  const text = await readBoundedText(response, maxBytes, connectionName);
+  return JSON.parse(text);
+}
+
+// src/tools/connections/http.ts
+async function fetchConnection(target, init, allowedHosts, connectionName) {
+  const url = assertConnectionUrl(target.toString(), connectionName);
+  assertAllowedHost(url, allowedHosts, connectionName);
+  const response = await fetch(url, { ...init, redirect: "manual" });
+  if (response.status >= 300 && response.status < 400) {
+    await response.body?.cancel();
+    throw new ConnectionUrlError(`Connection "${connectionName}" refused a redirect`, url.toString());
+  }
+  return response;
+}
+
+// src/tools/connections/json-rpc.ts
+function unwrap(payload, id, connectionName) {
+  if (!isRecord(payload) || payload.id !== id)
+    throw new Error(`MCP response id mismatch from "${connectionName}"`);
+  if (isRecord(payload.error))
+    throw new Error(`MCP error from "${connectionName}": ${typeof payload.error.message === "string" ? payload.error.message : "unknown"}`);
+  return payload.result;
+}
+
+// src/tools/connections/sse-frames.ts
+async function* readSseFrames(response, maxBytes, connectionName, totalLimit = false) {
+  if (!response.body)
+    throw new Error("MCP stream ended with no body");
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  let bytes = 0;
+  try {
+    for (;; ) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      if (totalLimit) {
+        bytes += value.byteLength;
+        if (bytes > maxBytes)
+          throw new ConnectionResponseTooLargeError(connectionName, maxBytes);
+      }
+      for (let offset = 0;offset < value.byteLength; offset += 1024) {
+        buffer += decoder.decode(value.subarray(offset, offset + 1024), { stream: true });
+        let match = /\r?\n\r?\n/.exec(buffer);
+        while (match) {
+          const frame = buffer.slice(0, match.index);
+          if (new TextEncoder().encode(frame).byteLength > maxBytes)
+            throw new ConnectionResponseTooLargeError(connectionName, maxBytes);
+          buffer = buffer.slice(match.index + match[0].length);
+          let event = "message";
+          const data = [];
+          for (const line of frame.split(/\r?\n/)) {
+            if (line.startsWith("event:"))
+              event = line.slice(6).trim();
+            if (line.startsWith("data:"))
+              data.push(line.slice(5).replace(/^ /, ""));
+          }
+          yield { event, data: data.join(`
+`) };
+          match = /\r?\n\r?\n/.exec(buffer);
+        }
+        if (new TextEncoder().encode(buffer).byteLength > maxBytes)
+          throw new ConnectionResponseTooLargeError(connectionName, maxBytes);
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {
+      return;
+    });
+    reader.releaseLock();
+  }
+}
+
+// src/tools/connections/sse-session.ts
+class SseSession {
+  connectionName;
+  instanceId;
+  options;
+  controller = new AbortController;
+  pending = new Map;
+  endpoint = Promise.withResolvers();
+  failure;
+  constructor(connectionName, instanceId, options) {
+    this.connectionName = connectionName;
+    this.instanceId = instanceId;
+    this.options = options;
+    this.endpoint.promise.catch(() => {
+      return;
+    });
+    this.open();
+  }
+  async ready(signal) {
+    return withConnectionDeadline(this.connectionName, this.options.timeoutMs, signal, async (deadline) => {
+      const onAbort = () => this.close(deadline.reason);
+      deadline.addEventListener("abort", onAbort, { once: true });
+      try {
+        deadline.throwIfAborted();
+        return await this.endpoint.promise;
+      } finally {
+        deadline.removeEventListener("abort", onAbort);
+      }
+    });
+  }
+  close(reason = new Error("MCP SSE session closed")) {
+    this.failure = reason;
+    this.controller.abort(reason);
+    this.endpoint.reject(reason);
+    for (const pending of this.pending.values())
+      pending.reject(reason);
+    this.pending.clear();
+  }
+  async request(message, token, signal) {
+    return withConnectionDeadline(this.connectionName, this.options.timeoutMs, signal, async (deadline) => {
+      const abort = () => this.close(deadline.reason);
+      deadline.addEventListener("abort", abort, { once: true });
+      try {
+        deadline.throwIfAborted();
+        if (this.controller.signal.aborted)
+          throw this.failure;
+        const endpoint = await this.endpoint.promise;
+        const response = Promise.withResolvers();
+        response.promise.catch(() => {
+          return;
+        });
+        if (message.id !== undefined)
+          this.pending.set(message.id, response);
+        const post = await fetchConnection(endpoint, {
+          method: "POST",
+          headers: {
+            ...this.options.headers,
+            "content-type": "application/json",
+            ...token ? { authorization: `Bearer ${token}` } : {}
+          },
+          body: JSON.stringify(message),
+          signal: deadline
+        }, this.options.allowedHosts, this.connectionName);
+        this.assertStatus(post);
+        await post.body?.cancel();
+        return message.id === undefined ? undefined : await response.promise;
+      } finally {
+        if (message.id !== undefined)
+          this.pending.delete(message.id);
+        deadline.removeEventListener("abort", abort);
+      }
+    });
+  }
+  assertStatus(response) {
+    if (response.status === 401)
+      throw new ConnectionAuthorizationRequiredError(this.connectionName, this.instanceId);
+    if (!response.ok)
+      throw new ConnectionRequestError(this.connectionName, response.status, "");
+  }
+  async open() {
+    try {
+      const response = await fetchConnection(this.options.baseUrl, {
+        method: "GET",
+        headers: { ...this.options.headers, accept: "text/event-stream" },
+        signal: this.controller.signal
+      }, this.options.allowedHosts, this.connectionName);
+      this.assertStatus(response);
+      for await (const frame of readSseFrames(response, this.options.maxResponseBytes, this.connectionName)) {
+        if (frame.event === "endpoint") {
+          const url = assertConnectionUrl(new URL(frame.data, this.options.baseUrl).toString(), this.connectionName);
+          assertAllowedHost(url, this.options.allowedHosts, this.connectionName);
+          this.endpoint.resolve(url.toString());
+        } else if (frame.event === "message" && frame.data) {
+          const message = JSON.parse(frame.data);
+          if (!isRecord(message) || typeof message.id !== "number")
+            continue;
+          const pending = this.pending.get(message.id);
+          if (!pending)
+            continue;
+          try {
+            pending.resolve(unwrap(message, message.id, this.connectionName));
+          } catch (error) {
+            pending.reject(error);
+          }
+          this.pending.delete(message.id);
+        }
+      }
+      this.close(new Error("MCP SSE stream ended"));
+    } catch (error) {
+      this.close(error);
+    }
+  }
+}
+
+// src/tools/connections/mcp-client.ts
+var FALLBACK_STATUSES = new Set([400, 404, 405]);
+var PROTOCOL_VERSION = "2024-11-05";
+
+class McpHttpClient {
+  connectionName;
+  instanceId;
+  options;
+  mode = "streamable";
+  sessionId;
+  protocolVersion;
+  nextId = 1;
+  initialized = false;
+  sse;
+  constructor(connectionName, instanceId, options) {
+    this.connectionName = connectionName;
+    this.instanceId = instanceId;
+    this.options = options;
+  }
+  teardown() {
+    this.initialized = false;
+    this.sessionId = undefined;
+    this.sse?.close();
+    this.sse = undefined;
+    this.mode = "streamable";
+  }
+  async initialize(token, signal) {
+    if (this.initialized)
+      return;
+    const result = await this.request("initialize", {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "stitchkit", version: "0.0.0" }
+    }, token, signal);
+    if (isRecord(result) && typeof result.protocolVersion === "string") {
+      this.protocolVersion = result.protocolVersion;
+    }
+    this.initialized = true;
+    try {
+      await this.dispatch({ jsonrpc: "2.0", method: "notifications/initialized" }, token, signal);
+    } catch {}
+  }
+  request(method, params, token, signal) {
+    return this.dispatch({ jsonrpc: "2.0", id: this.nextId++, method, params }, token, signal);
+  }
+  async dispatch(message, token, signal) {
+    if (this.mode === "sse")
+      return this.sseRequest(message, token, signal);
+    try {
+      return await this.streamableRequest(message, token, signal);
+    } catch (error) {
+      if (error instanceof ConnectionRequestError && FALLBACK_STATUSES.has(error.status)) {
+        await this.openSse(token, signal);
+        this.mode = "sse";
+        return this.sseRequest(message, token, signal);
+      }
+      throw error;
+    }
+  }
+  streamableRequest(message, token, signal) {
+    const target = new URL(this.options.transport.url);
+    assertAllowedHost(target, this.options.allowedHosts, this.connectionName);
+    return withConnectionDeadline(this.connectionName, this.options.timeoutMs, signal, async (deadline) => {
+      const response = await fetchConnection(target, {
+        method: "POST",
+        headers: this.headers(token),
+        body: JSON.stringify(message),
+        signal: deadline
+      }, this.options.allowedHosts, this.connectionName);
+      if (response.status === 401) {
+        throw new ConnectionAuthorizationRequiredError(this.connectionName, this.instanceId);
+      }
+      if (!response.ok) {
+        throw new ConnectionRequestError(this.connectionName, response.status, await this.safeText(response));
+      }
+      const session = response.headers.get("mcp-session-id");
+      if (session)
+        this.sessionId = session;
+      if (message.id === undefined) {
+        await response.body?.cancel();
+        return;
+      }
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("text/event-stream")) {
+        for await (const frame of readSseFrames(response, this.options.maxResponseBytes, this.connectionName, true)) {
+          if (!frame.data)
+            continue;
+          const payload2 = JSON.parse(frame.data);
+          if (isRecord(payload2) && payload2.id === message.id)
+            return unwrap(payload2, message.id, this.connectionName);
+        }
+        throw new Error("MCP stream ended without a response");
+      }
+      const text = await readBoundedText(response, this.options.maxResponseBytes, this.connectionName);
+      let payload;
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        throw new Error(`MCP response from "${this.connectionName}" was not JSON`);
+      }
+      return unwrap(payload, message.id, this.connectionName);
+    });
+  }
+  headers(token) {
+    const headers = {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+      ...this.options.transport.headers
+    };
+    if (token)
+      headers.authorization = `Bearer ${token}`;
+    if (this.sessionId)
+      headers["mcp-session-id"] = this.sessionId;
+    if (this.protocolVersion)
+      headers["mcp-protocol-version"] = this.protocolVersion;
+    return headers;
+  }
+  async openSse(token, signal) {
+    this.sse?.close();
+    this.sse = new SseSession(this.connectionName, this.instanceId, {
+      baseUrl: this.options.transport.url,
+      allowedHosts: this.options.allowedHosts,
+      headers: this.headers(token),
+      timeoutMs: this.options.timeoutMs,
+      maxResponseBytes: this.options.maxResponseBytes
+    });
+    await this.sse.ready(signal);
+  }
+  async sseRequest(message, token, signal) {
+    if (!this.sse)
+      await this.openSse(token, signal);
+    const session = this.sse;
+    if (!session)
+      throw new Error("MCP SSE session failed to open");
+    return session.request(message, token, signal);
+  }
+  async safeText(response) {
+    try {
+      return (await readBoundedText(response, this.options.maxResponseBytes, this.connectionName)).slice(0, 512);
+    } catch {
+      return "";
+    }
+  }
+}
+
+// src/tools/connections/runtime.ts
+import { z } from "zod";
+async function withConnectionToken(params, body) {
+  const token = await params.provider?.(params.context);
+  try {
+    return await body(token);
+  } catch (error) {
+    if (error instanceof ConnectionAuthorizationRequiredError) {
+      params.client?.teardown();
+    }
+    throw error;
+  }
+}
+function zodObjectFromJsonSchema(schema) {
+  if (!schema || Object.keys(schema).length === 0)
+    return z.looseObject({});
+  const parsed = z.fromJSONSchema(schema);
+  if (parsed instanceof z.ZodObject)
+    return parsed;
+  return z.looseObject({});
+}
+function sanitizeToolName(value) {
+  return value.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "operation";
+}
+
+// src/tools/connections/schema-budget.ts
+var schemaBytes = new WeakMap;
+function recordForeignSchemaBytes(tool, size) {
+  schemaBytes.set(tool, size);
+}
+function foreignSchemaBytes(tool) {
+  return schemaBytes.get(tool) ?? 0;
+}
+function jsonSchemaBytes(schema) {
+  if (!schema || Object.keys(schema).length === 0)
+    return 0;
+  return new TextEncoder().encode(JSON.stringify(schema)).byteLength;
+}
+
+// src/tools/connections/mcp.ts
+async function mountMcpConnection(connection, instanceId) {
+  const url = assertConnectionUrl(connection.transport.url, connection.name);
+  const allowedHosts = connectionAllowedHosts(url, connection.allowHosts);
+  assertAllowedHost(url, allowedHosts, connection.name);
+  const createClient = () => new McpHttpClient(connection.name, instanceId, {
+    transport: connection.transport,
+    allowedHosts,
+    timeoutMs: connectionTimeoutMs(connection.timeoutMs),
+    maxResponseBytes: connectionMaxResponseBytes(connection.maxResponseBytes)
+  });
+  const discovery = createClient();
+  const listed = await withConnectionToken({ instanceId, provider: connection.token, client: discovery }, async (token) => {
+    await discovery.initialize(token);
+    return discovery.request("tools/list", {}, token);
+  }).finally(() => discovery.teardown());
+  const discovered = readDiscoveredTools(listed, connection.name);
+  const filtered = filterMcpTools(discovered, connection.tools);
+  return filtered.map((tool) => {
+    const name = tool.name;
+    const description = tool.description ?? `External MCP tool "${name}"`;
+    const input = zodObjectFromJsonSchema(tool.inputSchema);
+    const definition = defineRuntimeTool({
+      name,
+      description,
+      identity: { serviceName: connection.name, action: name, method: "POST" },
+      input,
+      output: z2.unknown(),
+      handler: (context) => {
+        const client = createClient();
+        return withConnectionToken({ instanceId, provider: connection.token, client, context }, async (token) => {
+          await client.initialize(token, context.signal);
+          const result = await client.request("tools/call", { name, arguments: context.input }, token, context.signal);
+          if (isRecord(result) && result.isError === true) {
+            throw new Error(`External MCP tool "${name}" returned an error`);
+          }
+          return result;
+        }).finally(() => client.teardown());
+      }
+    });
+    recordForeignSchemaBytes(definition, jsonSchemaBytes(tool.inputSchema));
+    return definition;
+  });
+}
+function readDiscoveredTools(listed, connectionName) {
+  if (!isRecord(listed) || !Array.isArray(listed.tools)) {
+    throw new Error(`MCP connection "${connectionName}" returned no tools list`);
+  }
+  const tools = [];
+  for (const raw of listed.tools) {
+    if (!isRecord(raw) || typeof raw.name !== "string")
+      continue;
+    tools.push({
+      name: raw.name,
+      ...typeof raw.description === "string" && { description: raw.description },
+      ...isRecord(raw.inputSchema) && { inputSchema: raw.inputSchema }
+    });
+  }
+  return tools;
+}
+function filterMcpTools(tools, filter) {
+  const allow = filter?.allow ? new Set(filter.allow) : undefined;
+  const block = new Set(filter?.block ?? []);
+  return tools.filter((tool) => (allow === undefined || allow.has(tool.name)) && !block.has(tool.name));
+}
+
+// src/tools/connections/openapi.ts
+import { z as z3 } from "zod";
+
+// src/tools/connections/openapi-document.ts
+function resolveOpenApiDocument(document) {
+  let nodes = 0;
+  const visit = (value, refs, depth) => {
+    if (++nodes > 1e5 || depth > 64)
+      throw new TypeError("OpenAPI document expansion exceeds its limit");
+    if (Array.isArray(value))
+      return value.map((item) => visit(item, refs, depth + 1));
+    if (!isRecord(value))
+      return value;
+    if (typeof value.$ref === "string") {
+      const ref = value.$ref;
+      if (!ref.startsWith("#/"))
+        throw new TypeError("OpenAPI external references are unsupported");
+      if (refs.includes(ref))
+        throw new TypeError("OpenAPI recursive references are unsupported");
+      let target = document;
+      for (const part of ref.slice(2).split("/").map((part2) => part2.replace(/~1/g, "/").replace(/~0/g, "~"))) {
+        if (!isRecord(target) || !Object.hasOwn(target, part))
+          throw new TypeError("OpenAPI reference does not resolve");
+        target = target[part];
+      }
+      if (!isRecord(target))
+        throw new TypeError("OpenAPI reference must resolve to an object");
+      const { $ref: _, ...siblings } = value;
+      return visit({ ...target, ...siblings }, [...refs, ref], depth + 1);
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, visit(item, refs, depth + 1)]));
+  };
+  const result = visit(document, [], 0);
+  if (!isRecord(result))
+    throw new TypeError("OpenAPI document must be an object");
+  return result;
+}
+function assertOpenApiOperation(document, operation, pathItem) {
+  for (const servers of [document.servers, pathItem.servers, operation.servers]) {
+    if (Array.isArray(servers) && servers.some((server) => isRecord(server) && typeof server.url === "string" && /[{}]/.test(server.url)))
+      throw new TypeError("OpenAPI server variables are unsupported");
+  }
+  const security = operation.security ?? document.security;
+  if (Array.isArray(security) && security.some((item) => isRecord(item) && Object.keys(item).length > 1))
+    throw new TypeError("OpenAPI combined security schemes require a custom tool");
+  const body = operation.requestBody;
+  if (isRecord(body) && (!isRecord(body.content) || !isRecord(body.content["application/json"])))
+    throw new TypeError("OpenAPI request bodies must declare application/json");
+  const names = new Map;
+  for (const source of [pathItem.parameters, operation.parameters]) {
+    if (!Array.isArray(source))
+      continue;
+    for (const parameter of source) {
+      if (!isRecord(parameter) || typeof parameter.name !== "string" || typeof parameter.in !== "string")
+        throw new TypeError("Invalid OpenAPI parameter");
+      const previous = names.get(parameter.name);
+      if (previous && previous !== parameter.in)
+        throw new TypeError("OpenAPI parameter names must be unique across locations");
+      names.set(parameter.name, parameter.in);
+      if (isRecord(parameter.schema) && (parameter.schema.type === "array" || parameter.schema.type === "object"))
+        throw new TypeError("OpenAPI structured parameter serialization is unsupported");
+      if (parameter.content)
+        throw new TypeError("OpenAPI parameter content serialization is unsupported");
+    }
+  }
+}
+
+// src/tools/connections/openapi.ts
+async function mountOpenApiConnection(connection, instanceId) {
+  const timeoutMs = connectionTimeoutMs(connection.timeoutMs);
+  const maxResponseBytes = connectionMaxResponseBytes(connection.maxResponseBytes);
+  const loaded = await loadOpenApiDocument(connection, timeoutMs, maxResponseBytes);
+  const document = resolveOpenApiDocument(loaded.document);
+  const baseUrl = resolveBaseUrl(connection, document, loaded.url);
+  const baseHost = assertConnectionUrl(baseUrl, connection.name);
+  const allowedHosts = connectionAllowedHosts(loaded.url && !connection.baseUrl ? new URL(loaded.url) : baseHost, loaded.url ? [...connection.allowHosts ?? [], new URL(loaded.url).host] : connection.allowHosts);
+  assertAllowedHost(new URL(baseUrl), allowedHosts, connection.name);
+  const operations = collectOperations(document);
+  const names = new Set;
+  return operations.map((entry) => {
+    assertOpenApiOperation(document, entry.operation, entry.pathItem);
+    const rawName = operationKey(entry);
+    const name = uniqueToolName(connection.name, rawName, names);
+    const description = typeof entry.operation.description === "string" ? entry.operation.description : `${entry.method} ${entry.path}`;
+    const schema = operationInputSchema(document, entry);
+    const input = zodObjectFromJsonSchema(schema);
+    const auth = resolveAuth(document, entry.operation);
+    const definition = defineRuntimeTool({
+      name,
+      description,
+      identity: {
+        serviceName: connection.name,
+        action: rawName,
+        method: entry.method
+      },
+      input,
+      output: z3.unknown(),
+      handler: (context) => withConnectionToken({ instanceId, provider: connection.token, context }, async (token) => {
+        const args = isRecord(context.input) ? context.input : {};
+        const url = buildOperationUrl(baseUrl, entry, args);
+        assertAllowedHost(url, allowedHosts, connection.name);
+        const headers = { accept: "application/json" };
+        for (const parameter of operationParameters(document, entry)) {
+          const value = args[parameter.name];
+          if (value === undefined)
+            continue;
+          if (parameter.in === "query")
+            url.searchParams.set(parameter.name, String(value));
+          else if (parameter.in === "header")
+            headers[parameter.name] = String(value);
+          else if (parameter.in === "cookie") {
+            const cookie = `${parameter.name}=${encodeURIComponent(String(value))}`;
+            headers.cookie = headers.cookie ? `${headers.cookie}; ${cookie}` : cookie;
+          }
+        }
+        const body = requestBody(entry.operation);
+        applyAuth(auth, token, url, headers);
+        return withConnectionDeadline(connection.name, timeoutMs, context.signal, async (signal) => {
+          const requestInit = { method: entry.method, headers, signal };
+          if (body && args.body !== undefined) {
+            headers["content-type"] = "application/json";
+            requestInit.body = JSON.stringify(args.body);
+          }
+          const response = await fetchConnection(url, requestInit, allowedHosts, connection.name);
+          if (response.status === 401) {
+            await response.body?.cancel();
+            throw new ConnectionAuthorizationRequiredError(connection.name, instanceId);
+          }
+          if (!response.ok) {
+            throw new ConnectionRequestError(connection.name, response.status, (await safeText(response, maxResponseBytes)).slice(0, 512));
+          }
+          return readResponse(response, maxResponseBytes, connection.name);
+        });
+      })
+    });
+    recordForeignSchemaBytes(definition, jsonSchemaBytes(schema));
+    return definition;
+  });
+}
+async function loadOpenApiDocument(connection, timeoutMs, maxResponseBytes) {
+  if (typeof connection.spec === "object" && connection.spec !== null) {
+    if (!isRecord(connection.spec)) {
+      throw new Error(`OpenAPI spec of "${connection.name}" is not an object`);
+    }
+    return { document: connection.spec };
+  }
+  const text = connection.spec.trim();
+  if (text.startsWith("{")) {
+    const parsed2 = JSON.parse(text);
+    if (!isRecord(parsed2))
+      throw new Error(`OpenAPI spec of "${connection.name}" is not an object`);
+    return { document: parsed2 };
+  }
+  const url = assertConnectionUrl(text, connection.name);
+  const parsed = await withConnectionDeadline(connection.name, timeoutMs, undefined, async (signal) => {
+    const response = await fetchConnection(url, { signal }, connectionAllowedHosts(url, connection.allowHosts), connection.name);
+    if (!response.ok) {
+      throw new ConnectionRequestError(connection.name, response.status, "");
+    }
+    return readBoundedJson(response, maxResponseBytes, connection.name);
+  });
+  if (!isRecord(parsed))
+    throw new Error(`OpenAPI spec at ${url} is not an object`);
+  return { document: parsed, url: url.toString() };
+}
+function resolveBaseUrl(connection, document, specUrl) {
+  if (connection.baseUrl)
+    return connection.baseUrl;
+  const servers = document.servers;
+  if (Array.isArray(servers)) {
+    for (const server of servers) {
+      if (isRecord(server) && typeof server.url === "string" && server.url)
+        return server.url;
+    }
+  }
+  if (specUrl)
+    return specUrl;
+  throw new Error(`OpenAPI connection "${connection.name}" declares no baseUrl or server`);
+}
+function collectOperations(document) {
+  const paths = asRecord(document.paths);
+  if (!paths)
+    return [];
+  const operations = [];
+  for (const [path, rawItem] of Object.entries(paths)) {
+    const pathItem = asRecord(rawItem);
+    if (!pathItem)
+      continue;
+    for (const [rawMethod, method] of Object.entries(HTTP_METHODS)) {
+      const operation = asRecord(pathItem[rawMethod]);
+      if (!operation)
+        continue;
+      operations.push({ method, path, operation, pathItem });
+    }
+  }
+  return operations;
+}
+var HTTP_METHODS = {
+  get: "GET",
+  head: "HEAD",
+  post: "POST",
+  put: "PUT",
+  patch: "PATCH",
+  delete: "DELETE"
+};
+function operationKey(entry) {
+  const id = entry.operation.operationId;
+  if (typeof id === "string" && id.trim())
+    return id;
+  return `${entry.method}_${entry.path}`;
+}
+function uniqueToolName(connectionName, rawName, used) {
+  const base = `${sanitizeToolName(connectionName)}__${sanitizeToolName(rawName)}`;
+  if (!used.has(base)) {
+    used.add(base);
+    return base;
+  }
+  let suffix = 2;
+  while (used.has(`${base}_${suffix}`))
+    suffix += 1;
+  const name = `${base}_${suffix}`;
+  used.add(name);
+  return name;
+}
+function operationParameters(document, entry) {
+  const merged = new Map;
+  for (const source of [entry.pathItem.parameters, entry.operation.parameters]) {
+    if (!Array.isArray(source))
+      continue;
+    for (const raw of source) {
+      const parameter = asRecord(raw);
+      if (!parameter || typeof parameter.name !== "string")
+        continue;
+      const location = parameter.in;
+      if (location !== "path" && location !== "query" && location !== "header" && location !== "cookie") {
+        continue;
+      }
+      const resolved = resolveRef(document, asRecord(parameter.schema));
+      merged.set(`${location}:${parameter.name}`, {
+        name: parameter.name,
+        in: location,
+        required: parameter.required === true || location === "path",
+        ...resolved && { schema: resolved }
+      });
+    }
+  }
+  return [...merged.values()];
+}
+function requestBody(operation) {
+  const body = asRecord(operation.requestBody);
+  if (!body)
+    return false;
+  const content = asRecord(body.content);
+  return Boolean(content && isRecord(content["application/json"]));
+}
+function operationInputSchema(document, entry) {
+  const properties = {};
+  const required = [];
+  for (const parameter of operationParameters(document, entry)) {
+    properties[parameter.name] = parameter.schema ?? { type: "string" };
+    if (parameter.required)
+      required.push(parameter.name);
+  }
+  const body = asRecord(entry.operation.requestBody);
+  const content = body ? asRecord(body.content) : undefined;
+  const json = content ? asRecord(content["application/json"]) : undefined;
+  if (body && json) {
+    properties.body = resolveRef(document, asRecord(json.schema)) ?? {};
+    if (body.required === true)
+      required.push("body");
+  }
+  return {
+    type: "object",
+    properties,
+    ...required.length > 0 && { required }
+  };
+}
+function resolveRef(document, node) {
+  if (!node)
+    return;
+  const ref = node.$ref;
+  if (typeof ref !== "string" || !ref.startsWith("#/"))
+    return node;
+  const segments = ref.slice(2).split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+  let current = document;
+  for (const segment of segments) {
+    if (!isRecord(current))
+      return;
+    current = current[segment];
+  }
+  return asRecord(current);
+}
+function resolveAuth(document, operation) {
+  const security = operation.security ?? document.security;
+  if (!Array.isArray(security))
+    return;
+  for (const requirement of security) {
+    const record = asRecord(requirement);
+    if (!record)
+      continue;
+    const schemeName = Object.keys(record)[0];
+    if (!schemeName)
+      return;
+    const scheme = asRecord(asRecord(asRecord(document.components)?.securitySchemes)?.[schemeName]);
+    if (!scheme)
+      continue;
+    const type = scheme.type;
+    if (type === "apiKey") {
+      const placement = scheme.in;
+      const headerName = scheme.name;
+      if (typeof headerName === "string" && (placement === "header" || placement === "query" || placement === "cookie")) {
+        return { placement, name: headerName, scheme: "apikey" };
+      }
+      continue;
+    }
+    if (type === "http") {
+      const httpScheme = typeof scheme.scheme === "string" ? scheme.scheme.toLowerCase() : "";
+      if (httpScheme === "basic")
+        return { placement: "header", name: "authorization", scheme: "basic" };
+      if (httpScheme === "bearer")
+        return { placement: "header", name: "authorization", scheme: "bearer" };
+      continue;
+    }
+    if (type === "oauth2" || type === "openIdConnect") {
+      return { placement: "header", name: "authorization", scheme: "bearer" };
+    }
+  }
+  if (security.length > 0)
+    throw new TypeError("OpenAPI security has no supported alternative");
+  return;
+}
+function applyAuth(auth, token, url, headers) {
+  if (!auth || token === undefined)
+    return;
+  const value = auth.scheme === "basic" ? `Basic ${btoa(token)}` : auth.scheme === "bearer" ? `Bearer ${token}` : token;
+  if (auth.placement === "query")
+    url.searchParams.set(auth.name, value);
+  else if (auth.placement === "cookie") {
+    headers.cookie = headers.cookie ? `${headers.cookie}; ${auth.name}=${value}` : `${auth.name}=${value}`;
+  } else
+    headers[auth.name] = value;
+}
+function operationServerUrl(entry) {
+  for (const source of [entry.operation.servers, entry.pathItem.servers]) {
+    if (!Array.isArray(source))
+      continue;
+    for (const server of source) {
+      if (isRecord(server) && typeof server.url === "string" && server.url)
+        return server.url;
+    }
+  }
+  return;
+}
+function buildOperationUrl(baseUrl, entry, args) {
+  let path = entry.path;
+  for (const parameter of operationParameters({}, entry)) {
+    if (parameter.in !== "path")
+      continue;
+    const value = args[parameter.name];
+    if (value === undefined)
+      continue;
+    path = path.replace(`{${parameter.name}}`, encodeURIComponent(String(value)));
+  }
+  const origin = operationServerUrl(entry) ?? baseUrl;
+  const resolved = `${origin.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+  return new URL(resolved);
+}
+async function readResponse(response, maxBytes, connectionName) {
+  if (response.status === 204)
+    return null;
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("json"))
+    return readBoundedJson(response, maxBytes, connectionName);
+  return readBoundedText(response, maxBytes, connectionName);
+}
+async function safeText(response, maxBytes) {
+  try {
+    return await readBoundedText(response, maxBytes, "response");
+  } catch {
+    return "";
+  }
+}
+function asRecord(value) {
+  return isRecord(value) ? value : undefined;
+}
+
+// src/tools/connections/mount.ts
+async function mountConnections(connections, options = {}) {
+  const tools = [];
+  for (const connection of connections) {
+    const instanceId = instanceIdOf(connection);
+    const mounted = connection.kind === "mcp" ? await mountMcpConnection(connection, instanceId) : await mountOpenApiConnection(connection, instanceId);
+    tools.push(...mounted);
+  }
+  const limit = options.budget?.maxTools;
+  if (limit !== undefined && tools.length > limit) {
+    throw new ConnectionBudgetExceededError(limit, tools.length);
+  }
+  const schemaLimit = options.budget?.maxSchemaBytes;
+  if (schemaLimit !== undefined) {
+    const schemaBytes2 = tools.reduce((total, tool) => total + foreignSchemaBytes(tool), 0);
+    if (schemaBytes2 > schemaLimit) {
+      throw new ConnectionBudgetExceededError(schemaLimit, schemaBytes2, "schema bytes");
+    }
+  }
+  return tools;
+}
+function instanceIdOf(connection) {
+  let url;
+  if (connection.kind === "mcp") {
+    url = connection.transport.url;
+  } else if (connection.baseUrl) {
+    url = connection.baseUrl;
+  } else if (typeof connection.spec === "string") {
+    url = connection.spec;
+  } else {
+    url = JSON.stringify(connection.spec);
+  }
+  return connectionInstanceId(connection.name, url, connection.instanceKey);
+}
+export {
+  mountConnections,
+  defineOpenApiConnection,
+  defineMcpClientConnection,
+  ConnectionUrlError,
+  ConnectionRequestError,
+  ConnectionBudgetExceededError,
+  ConnectionAuthorizationRequiredError
+};