mcp-from-openapi 2.6.0 → 2.7.0

package/index.js

@@ -30,12 +30,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ArazzoError: () => ArazzoError,
   BLOCKED_HOSTNAMES: () => BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS: () => BUILTIN_FORMAT_RESOLVERS,
+  CODECALL_RESERVED_NAMESPACES: () => CODECALL_RESERVED_NAMESPACES,
   GenerationError: () => GenerationError,
   LoadError: () => LoadError,
   OpenAPIToolError: () => OpenAPIToolError,
   OpenAPIToolGenerator: () => OpenAPIToolGenerator,
+  OverlayError: () => OverlayError,
   ParameterResolver: () => ParameterResolver,
   ParseError: () => ParseError,
   RequestBuildError: () => RequestBuildError,
@@ -46,7 +49,9 @@ __export(index_exports, {
   SsrfError: () => SsrfError,
   ValidationError: () => ValidationError,
   Validator: () => Validator,
+  analyzeToolSet: () => analyzeToolSet,
   applyClientTarget: () => applyClientTarget,
+  applyOverlay: () => applyOverlay,
   assertUrlSafe: () => assertUrlSafe,
   buildHttpRequest: () => buildHttpRequest,
   collapseNestedUnions: () => collapseNestedUnions,
@@ -55,20 +60,28 @@ __export(index_exports, {
   decodeIpv4MappedIpv6: () => decodeIpv4MappedIpv6,
   defaultLookup: () => defaultLookup,
   demoteFormats: () => demoteFormats,
+  deriveSecurityElicitations: () => deriveSecurityElicitations,
+  dottedNaming: () => dottedNaming,
+  emitToolTypeScript: () => emitToolTypeScript,
   enforceClosedObjects: () => enforceClosedObjects,
   ensureArrayItems: () => ensureArrayItems,
+  estimateToolTokens: () => estimateToolTokens,
   extractExtensionOverrides: () => extractExtensionOverrides,
+  fromArazzo: () => fromArazzo,
   inferAnnotationsFromMethod: () => inferAnnotationsFromMethod,
   inlineLocalRefs: () => inlineLocalRefs,
   isBlockedAddress: () => isBlockedAddress,
   isBlockedHostname: () => isBlockedHostname,
   isReferenceObject: () => isReferenceObject,
+  lintDocument: () => lintDocument,
   normalizeSsrfOptions: () => normalizeSsrfOptions,
+  parseRuntimeExpression: () => parseRuntimeExpression,
   requireAllProperties: () => requireAllProperties,
   resolveExtensionEnabled: () => resolveExtensionEnabled,
   resolveSchemaFormats: () => resolveSchemaFormats,
   safeFetch: () => safeFetch,
   toJsonSchema: () => toJsonSchema,
+  toPascalIdentifier: () => toPascalIdentifier,
   toSdkTool: () => toSdkTool
 });
 module.exports = __toCommonJS(index_exports);
@@ -81,9 +94,24 @@ function isReferenceObject(obj) {
   return obj && typeof obj === "object" && "$ref" in obj;
 }
 function toJsonSchema(schema) {
+  return convertSchema(schema, /* @__PURE__ */ new Set());
+}
+function convertSchema(schema, stack) {
   if (isReferenceObject(schema)) {
     return { $ref: schema.$ref };
   }
+  if (stack.has(schema)) {
+    return {};
+  }
+  stack.add(schema);
+  try {
+    return convertSchemaInner(schema, stack);
+  } finally {
+    stack.delete(schema);
+  }
+}
+function convertSchemaInner(schema, stack) {
+  const recurse = (value) => convertSchema(value, stack);
   const { exclusiveMaximum, exclusiveMinimum, maximum, minimum, ...rest } = schema;
   const { nullable, example, ...cleanRest } = rest;
   const result = { ...cleanRest };
@@ -135,34 +163,34 @@ function toJsonSchema(schema) {
   if (result["properties"] && typeof result["properties"] === "object") {
     const props = {};
     for (const [key, value] of Object.entries(result["properties"])) {
-      props[key] = toJsonSchema(value);
+      props[key] = recurse(value);
     }
     result["properties"] = props;
   }
   if (result["items"]) {
     if (Array.isArray(result["items"])) {
-      result["items"] = result["items"].map(toJsonSchema);
+      result["items"] = result["items"].map(recurse);
     } else {
-      result["items"] = toJsonSchema(result["items"]);
+      result["items"] = recurse(result["items"]);
     }
   }
   if (result["additionalProperties"] && typeof result["additionalProperties"] === "object") {
-    result["additionalProperties"] = toJsonSchema(result["additionalProperties"]);
+    result["additionalProperties"] = recurse(result["additionalProperties"]);
   }
   for (const key of ["allOf", "anyOf", "oneOf"]) {
     if (result[key] && Array.isArray(result[key])) {
-      result[key] = result[key].map(toJsonSchema);
+      result[key] = result[key].map(recurse);
     }
   }
   if (result["not"]) {
-    result["not"] = toJsonSchema(result["not"]);
+    result["not"] = recurse(result["not"]);
   }
   for (const key of ["patternProperties", "$defs", "definitions", "dependentSchemas"]) {
     const value = result[key];
     if (value && typeof value === "object" && !Array.isArray(value)) {
       const mapped = {};
       for (const [name, sub] of Object.entries(value)) {
-        mapped[name] = toJsonSchema(sub);
+        mapped[name] = recurse(sub);
       }
       result[key] = mapped;
     }
@@ -179,11 +207,11 @@ function toJsonSchema(schema) {
   ]) {
     const value = result[key];
     if (value && typeof value === "object") {
-      result[key] = toJsonSchema(value);
+      result[key] = recurse(value);
     }
   }
   if (Array.isArray(result["prefixItems"])) {
-    result["prefixItems"] = result["prefixItems"].map(toJsonSchema);
+    result["prefixItems"] = result["prefixItems"].map(recurse);
   }
   if (wrapNullable) {
     const wrapper = {};
@@ -204,8 +232,11 @@ var ParameterResolver = class {
   namingStrategy;
   includeExamples;
   constructor(namingStrategy, options) {
-    this.namingStrategy = namingStrategy ?? {
-      conflictResolver: this.defaultConflictResolver
+    this.namingStrategy = {
+      ...namingStrategy,
+      // Bind a supplied resolver to its own strategy object so class-based
+      // strategies keep their `this` (we invoke it off a spread clone).
+      conflictResolver: namingStrategy?.conflictResolver ? namingStrategy.conflictResolver.bind(namingStrategy) : this.defaultConflictResolver
     };
     this.includeExamples = options?.includeExamples ?? false;
   }
@@ -387,6 +418,9 @@ var ParameterResolver = class {
       schema["deprecated"] = true;
     }
     schema["x-parameter-location"] = param.location;
+    if (param.location === "header") {
+      schema["x-mcp-header"] = param.name;
+    }
     if (param.style) {
       schema["x-parameter-style"] = param.style;
     }
@@ -481,6 +515,9 @@ var ParameterResolver = class {
       });
       const schemeInInput = includeInInput === true || Array.isArray(includeInInput) && includeInInput.includes(scheme);
       if (schemeInInput) {
+        if (paramLocation === "header") {
+          schema["x-mcp-header"] = headerKey;
+        }
         properties[inputKey] = schema;
         required.push(inputKey);
       }
@@ -1005,6 +1042,96 @@ var SchemaBuilder = class {
     }
     return copy;
   }
+  // Copy-on-walk over every structural keyword (same key groups as
+  // truncateDepth): `visit` transforms each node top-down and must return a
+  // new node when it changes anything.
+  static walkCopy(node, visit, seen = /* @__PURE__ */ new Map()) {
+    if (!node || typeof node !== "object") return node;
+    const existing = seen.get(node);
+    if (existing) return existing;
+    const copy = visit({ ...node });
+    seen.set(node, copy);
+    for (const key of this.TRUNCATE_MAP_KEYS) {
+      const value = copy[key];
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const mapped = {};
+        for (const [name, sub] of Object.entries(value)) {
+          mapped[name] = this.walkCopy(sub, visit, seen);
+        }
+        copy[key] = mapped;
+      }
+    }
+    for (const key of this.TRUNCATE_SCHEMA_KEYS) {
+      const value = copy[key];
+      if (Array.isArray(value)) {
+        copy[key] = value.map((item) => this.walkCopy(item, visit, seen));
+      } else if (value !== null && typeof value === "object") {
+        copy[key] = this.walkCopy(value, visit, seen);
+      }
+    }
+    for (const key of this.TRUNCATE_LIST_KEYS) {
+      const value = copy[key];
+      if (Array.isArray(value)) {
+        copy[key] = value.map((member) => this.walkCopy(member, visit, seen));
+      }
+    }
+    return copy;
+  }
+  /**
+   * Limit every object node to its first `max` properties (declaration
+   * order). Dropped properties are pruned from `required` and counted in a
+   * note appended to the node's description.
+   */
+  static limitProperties(schema, max) {
+    const bound = Number.isFinite(max) ? Math.max(1, Math.floor(max)) : Number.MAX_SAFE_INTEGER;
+    return this.walkCopy(schema, (node) => {
+      const properties = node.properties;
+      if (!properties || typeof properties !== "object") return node;
+      const entries = Object.entries(properties);
+      if (entries.length <= bound) return node;
+      const kept = entries.slice(0, bound);
+      const keptNames = new Set(kept.map(([name]) => name));
+      const dropped = entries.length - bound;
+      const note = `[${dropped} additional propert${dropped === 1 ? "y" : "ies"} omitted: exceeds maxProperties]`;
+      const next = { ...node, properties: Object.fromEntries(kept) };
+      if (Array.isArray(node.required)) {
+        const required = node.required.filter((name) => keptNames.has(String(name)));
+        if (required.length > 0) {
+          next.required = required;
+        } else {
+          delete next.required;
+        }
+      }
+      next.description = node.description ? `${node.description} ${note}` : note;
+      return next;
+    });
+  }
+  /**
+   * Cap every description in the schema tree to `maxLength` characters,
+   * truncating with an ellipsis.
+   */
+  static capDescriptions(schema, maxLength) {
+    const bound = Number.isFinite(maxLength) ? Math.max(1, Math.floor(maxLength)) : Number.MAX_SAFE_INTEGER;
+    return this.walkCopy(schema, (node) => {
+      if (typeof node.description === "string" && node.description.length > bound) {
+        return { ...node, description: `${node.description.slice(0, bound - 1)}\u2026` };
+      }
+      return node;
+    });
+  }
+  /**
+   * Remove every `examples` array from the schema tree (a token-budget
+   * trimming step — validation keywords are untouched).
+   */
+  static stripExamples(schema) {
+    return this.walkCopy(schema, (node) => {
+      if ("examples" in node) {
+        const { examples: _examples, ...rest } = node;
+        return rest;
+      }
+      return node;
+    });
+  }
   /**
    * Simplify schema by removing unnecessary fields
    */
@@ -1063,9 +1190,63 @@ function mergeOverrides(base, layer) {
     ...layer.description !== void 0 && { description: layer.description },
     ...(base.annotations || layer.annotations) && {
       annotations: { ...base.annotations, ...layer.annotations }
-    }
+    },
+    ...(base.meta || layer.meta) && { meta: { ...base.meta, ...layer.meta } },
+    ...layer.icons !== void 0 && { icons: layer.icons }
   };
 }
+function cleanseMeta(node, seen) {
+  if (!node || typeof node !== "object") {
+    return node;
+  }
+  if (seen.has(node)) {
+    return void 0;
+  }
+  seen.add(node);
+  try {
+    if (Array.isArray(node)) {
+      return node.map((item) => cleanseMeta(item, seen));
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+      out[key] = cleanseMeta(value, seen);
+    }
+    return out;
+  } finally {
+    seen.delete(node);
+  }
+}
+function sanitizeMeta(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return cleanseMeta(value, /* @__PURE__ */ new Set());
+  }
+  return void 0;
+}
+function isAllowedIconSrc(src) {
+  const lower = src.toLowerCase();
+  return lower.startsWith("https:") || lower.startsWith("data:");
+}
+function sanitizeIcons(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const icons = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const raw = entry;
+    if (typeof raw["src"] !== "string" || !isAllowedIconSrc(raw["src"])) continue;
+    const icon = { src: raw["src"] };
+    if (typeof raw["mimeType"] === "string") {
+      icon.mimeType = raw["mimeType"];
+    }
+    if (Array.isArray(raw["sizes"]) && raw["sizes"].every((s) => typeof s === "string")) {
+      icon.sizes = [...raw["sizes"]];
+    }
+    icons.push(icon);
+  }
+  return icons.length > 0 ? icons : void 0;
+}
 function readXMcp(node) {
   return node["x-mcp"];
 }
@@ -1114,16 +1295,24 @@ function extractExtensionOverrides(operation) {
       name: typeof ext["name"] === "string" ? ext["name"] : void 0,
       title: typeof ext["title"] === "string" ? ext["title"] : void 0,
       description: typeof ext["description"] === "string" ? ext["description"] : void 0,
-      annotations: pickAnnotations(ext["annotations"])
+      annotations: pickAnnotations(ext["annotations"]),
+      meta: sanitizeMeta(ext["meta"]),
+      icons: sanitizeIcons(ext["icons"])
     });
   }
   const frontmcp = op["x-frontmcp"];
-  if (frontmcp && typeof frontmcp === "object" && frontmcp.annotations) {
-    const annotations = pickAnnotations(frontmcp.annotations);
-    result = mergeOverrides(result, {
-      annotations,
-      title: typeof frontmcp.annotations.title === "string" ? frontmcp.annotations.title : void 0
-    });
+  if (frontmcp && typeof frontmcp === "object") {
+    const layer = {
+      meta: sanitizeMeta(frontmcp.meta),
+      icons: sanitizeIcons(frontmcp.icons)
+    };
+    if (frontmcp.annotations) {
+      layer.annotations = pickAnnotations(frontmcp.annotations);
+      if (typeof frontmcp.annotations.title === "string") {
+        layer.title = frontmcp.annotations.title;
+      }
+    }
+    result = mergeOverrides(result, layer);
   }
   return result;
 }
@@ -1445,6 +1634,564 @@ function applyClientTarget(schema, target) {
   return result;
 }
 
+// src/errors.ts
+var OpenAPIToolError = class extends Error {
+  context;
+  constructor(message, context) {
+    super(message);
+    this.name = this.constructor.name;
+    this.context = context;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var LoadError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var SsrfError = class extends LoadError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ParseError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ValidationError = class extends OpenAPIToolError {
+  errors;
+  constructor(message, context) {
+    super(message, context);
+    this.errors = context?.["errors"];
+  }
+};
+var GenerationError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var OverlayError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var RequestBuildError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ArazzoError = class extends OpenAPIToolError {
+  path;
+  constructor(message, context) {
+    super(message, context);
+    this.path = context?.["path"];
+  }
+};
+var SchemaError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+
+// src/overlay.ts
+function parsePath(path) {
+  if (typeof path !== "string" || !path.startsWith("$")) {
+    throw new OverlayError(`Overlay target must be a JSONPath starting with '$'; received '${String(path)}'`, {
+      target: path
+    });
+  }
+  const segments = [];
+  let rest = path.slice(1);
+  while (rest.length > 0) {
+    let recursive = false;
+    if (rest.startsWith("..")) {
+      recursive = true;
+      rest = rest.slice(2);
+      const bare = rest.match(/^([A-Za-z_][\w-]*)/);
+      if (bare) {
+        segments.push({ kind: "child", name: bare[1], recursive });
+        rest = rest.slice(bare[0].length);
+        continue;
+      }
+    } else if (rest.startsWith(".")) {
+      rest = rest.slice(1);
+      if (rest.startsWith("*")) {
+        segments.push({ kind: "wildcard", recursive });
+        rest = rest.slice(1);
+        continue;
+      }
+      const bare = rest.match(/^([A-Za-z_][\w-]*)/);
+      if (bare) {
+        segments.push({ kind: "child", name: bare[1], recursive });
+        rest = rest.slice(bare[0].length);
+        continue;
+      }
+      throw new OverlayError(`Invalid JSONPath segment after '.' in '${path}'`, { target: path });
+    }
+    if (!rest.startsWith("[")) {
+      throw new OverlayError(`Invalid JSONPath segment at '${rest}' in '${path}'`, { target: path });
+    }
+    const bracket = matchBracket(rest, path);
+    const inner = bracket.inner.trim();
+    rest = bracket.rest;
+    if (inner === "*") {
+      segments.push({ kind: "wildcard", recursive });
+    } else if (/^-?\d+$/.test(inner)) {
+      segments.push({ kind: "index", index: parseInt(inner, 10), recursive });
+    } else if (/^'.*'$/.test(inner) || /^".*"$/.test(inner)) {
+      segments.push({ kind: "child", name: inner.slice(1, -1), recursive });
+    } else if (inner.startsWith("?(") && inner.endsWith(")")) {
+      segments.push(parseFilter(inner.slice(2, -1).trim(), path, recursive));
+    } else {
+      throw new OverlayError(`Unsupported JSONPath selector '[${inner}]' in '${path}'`, { target: path });
+    }
+  }
+  return segments;
+}
+function matchBracket(input, fullPath) {
+  let quote = null;
+  let depth = 0;
+  for (let i = 1; i < input.length; i++) {
+    const char = input[i];
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === "[") {
+      depth++;
+    } else if (char === "]") {
+      if (depth === 0) {
+        return { inner: input.slice(1, i), rest: input.slice(i + 1) };
+      }
+      depth--;
+    }
+  }
+  throw new OverlayError(`Unterminated '[' selector in '${fullPath}'`, { target: fullPath });
+}
+function parseFilter(expr, path, recursive) {
+  const match = expr.match(/^@(?:\.([A-Za-z_][\w-]*)|\['([^']*)'\]|\["([^"]*)"\])\s*(?:(==|!=)\s*(.+))?$/);
+  if (!match) {
+    throw new OverlayError(`Unsupported filter expression '?(${expr})' in '${path}'`, { target: path });
+  }
+  const field = match[1] ?? match[2] ?? match[3];
+  const op = match[4];
+  if (!op) {
+    return { kind: "filter", field, op: "exists", recursive };
+  }
+  const raw = match[5].trim();
+  let literal;
+  if (/^'.*'$/.test(raw) || /^".*"$/.test(raw)) {
+    literal = raw.slice(1, -1);
+  } else if (/^-?\d+(\.\d+)?$/.test(raw)) {
+    literal = parseFloat(raw);
+  } else if (raw === "true" || raw === "false") {
+    literal = raw === "true";
+  } else {
+    throw new OverlayError(`Unsupported filter literal '${raw}' in '${path}'`, { target: path });
+  }
+  return { kind: "filter", field, op, literal, recursive };
+}
+function isContainer(value) {
+  return value !== null && typeof value === "object";
+}
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function descendants(match) {
+  const result = [];
+  const walk = (node) => {
+    if (!isContainer(node)) return;
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => {
+        result.push({ parent: node, key: index, value: item });
+        walk(item);
+      });
+    } else {
+      for (const [key, value] of Object.entries(node)) {
+        result.push({ parent: node, key, value });
+        walk(value);
+      }
+    }
+  };
+  walk(match.value);
+  return result;
+}
+function dedupeMatches(matches) {
+  const seen = /* @__PURE__ */ new Map();
+  const result = [];
+  for (const match of matches) {
+    let keys = seen.get(match.parent);
+    if (!keys) {
+      keys = /* @__PURE__ */ new Set();
+      seen.set(match.parent, keys);
+    }
+    if (keys.has(match.key)) continue;
+    keys.add(match.key);
+    result.push(match);
+  }
+  return result;
+}
+function applySegment(matches, segment) {
+  const scope = segment.recursive ? matches.flatMap((m) => [m, ...descendants(m)]) : matches;
+  const next = [];
+  for (const match of scope) {
+    const node = match.value;
+    switch (segment.kind) {
+      case "child": {
+        if (isContainer(node) && !Array.isArray(node) && !UNSAFE_KEYS.has(segment.name) && Object.prototype.hasOwnProperty.call(node, segment.name)) {
+          next.push({ parent: node, key: segment.name, value: node[segment.name] });
+        }
+        break;
+      }
+      case "wildcard": {
+        if (Array.isArray(node)) {
+          node.forEach((item, index) => next.push({ parent: node, key: index, value: item }));
+        } else if (isContainer(node)) {
+          for (const [key, value] of Object.entries(node)) {
+            next.push({ parent: node, key, value });
+          }
+        }
+        break;
+      }
+      case "index": {
+        if (Array.isArray(node)) {
+          const index = segment.index < 0 ? node.length + segment.index : segment.index;
+          if (index >= 0 && index < node.length) {
+            next.push({ parent: node, key: index, value: node[index] });
+          }
+        }
+        break;
+      }
+      case "filter": {
+        const members = Array.isArray(node) ? node.map((item, index) => ({ parent: node, key: index, value: item })) : isContainer(node) ? Object.entries(node).map(([key, value]) => ({ parent: node, key, value })) : [];
+        for (const member of members) {
+          if (!isContainer(member.value) || Array.isArray(member.value)) continue;
+          const fieldValue = member.value[segment.field];
+          const keep = segment.op === "exists" ? fieldValue !== void 0 : segment.op === "==" ? fieldValue === segment.literal : fieldValue !== segment.literal;
+          if (keep) next.push(member);
+        }
+        break;
+      }
+    }
+  }
+  return next;
+}
+function deepMerge(target, update) {
+  for (const [key, value] of Object.entries(update)) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    const existing = target[key];
+    if (isContainer(value) && !Array.isArray(value) && isContainer(existing) && !Array.isArray(existing)) {
+      deepMerge(existing, value);
+    } else {
+      target[key] = value;
+    }
+  }
+}
+function applyOverlay(document, overlay) {
+  if (!overlay || typeof overlay !== "object" || !Array.isArray(overlay.actions)) {
+    throw new OverlayError("Overlay document must have an actions array", {});
+  }
+  const result = JSON.parse(JSON.stringify(document));
+  for (const [index, action] of overlay.actions.entries()) {
+    if (!action || typeof action !== "object" || typeof action.target !== "string") {
+      throw new OverlayError(`Overlay action #${index} must have a string target`, { index });
+    }
+    if (action.update === void 0 && action.remove !== true) {
+      throw new OverlayError(`Overlay action #${index} needs 'update' or 'remove: true'`, {
+        index,
+        target: action.target
+      });
+    }
+    const segments = parsePath(action.target);
+    let matches = [{ parent: null, key: null, value: result }];
+    for (const segment of segments) {
+      matches = dedupeMatches(applySegment(matches, segment));
+    }
+    if (action.remove === true) {
+      const arrayRemovals = /* @__PURE__ */ new Map();
+      for (const match of matches) {
+        if (match.parent === null) {
+          throw new OverlayError("Overlay cannot remove the document root", { target: action.target });
+        }
+        if (Array.isArray(match.parent)) {
+          const indices = arrayRemovals.get(match.parent) ?? [];
+          indices.push(match.key);
+          arrayRemovals.set(match.parent, indices);
+        } else {
+          delete match.parent[match.key];
+        }
+      }
+      for (const [parent, indices] of arrayRemovals) {
+        for (const index2 of indices.sort((a, b) => b - a)) {
+          parent.splice(index2, 1);
+        }
+      }
+      continue;
+    }
+    for (const match of matches) {
+      const node = match.value;
+      if (Array.isArray(node)) {
+        node.push(action.update);
+      } else if (isContainer(node) && isContainer(action.update) && !Array.isArray(action.update)) {
+        deepMerge(node, action.update);
+      } else {
+        if (match.parent === null) {
+          throw new OverlayError("Overlay cannot replace the document root with a non-object", {
+            target: action.target
+          });
+        }
+        match.parent[match.key] = action.update;
+      }
+    }
+  }
+  return result;
+}
+
+// src/lint.ts
+var METHODS = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+var PAGINATION_PARAM = /^(page|limit|offset|cursor|per_page|pagesize|page_size|after|before)$/i;
+var DEEP_SCHEMA_THRESHOLD = 8;
+var WIDE_SCHEMA_THRESHOLD = 30;
+function measureSchema(node, seen = /* @__PURE__ */ new Map()) {
+  if (node === null || typeof node !== "object") {
+    return { depth: 0, widestObject: 0, hasArray: false };
+  }
+  if (seen.has(node)) {
+    return seen.get(node) ?? { depth: 0, widestObject: 0, hasArray: false };
+  }
+  seen.set(node, null);
+  const record = node;
+  let childDepth = 0;
+  let widestObject = 0;
+  let hasArray = record["type"] === "array" || Array.isArray(record["type"]) && record["type"].includes("array");
+  const visit = (child) => {
+    const shape2 = measureSchema(child, seen);
+    childDepth = Math.max(childDepth, shape2.depth);
+    widestObject = Math.max(widestObject, shape2.widestObject);
+    hasArray = hasArray || shape2.hasArray;
+  };
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") {
+    widestObject = Math.max(widestObject, Object.keys(properties).length);
+    for (const child of Object.values(properties)) visit(child);
+  }
+  for (const key of ["items", "additionalProperties", "not", "contentSchema"]) {
+    const value = record[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) visit(value);
+    if (Array.isArray(value)) value.forEach(visit);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    const value = record[key];
+    if (Array.isArray(value)) value.forEach(visit);
+  }
+  const shape = { depth: childDepth + 1, widestObject, hasArray };
+  seen.set(node, shape);
+  return shape;
+}
+function schemaHasExample(node, seen = /* @__PURE__ */ new Set()) {
+  if (node === null || typeof node !== "object" || seen.has(node)) return false;
+  seen.add(node);
+  const record = node;
+  if (record["example"] !== void 0 || record["examples"] !== void 0) return true;
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") {
+    if (Object.values(properties).some((child) => schemaHasExample(child, seen))) return true;
+  }
+  for (const key of ["items", "additionalProperties", "not", "contentSchema"]) {
+    const value = record[key];
+    if (value && typeof value === "object" && !Array.isArray(value) && schemaHasExample(value, seen)) return true;
+    if (Array.isArray(value) && value.some((item) => schemaHasExample(item, seen))) return true;
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    const value = record[key];
+    if (Array.isArray(value) && value.some((member) => schemaHasExample(member, seen))) return true;
+  }
+  return false;
+}
+function hasAnyExample(content) {
+  if (!content) return false;
+  return Object.values(content).some((media) => {
+    if (!media || typeof media !== "object") return false;
+    const record = media;
+    if (record["example"] !== void 0 || record["examples"] !== void 0) return true;
+    return schemaHasExample(record["schema"]);
+  });
+}
+function lintDocument(document) {
+  const findings = [];
+  const operationIds = /* @__PURE__ */ new Map();
+  const paths = document.paths ?? {};
+  for (const [pathStr, pathItem] of Object.entries(paths).sort(([a], [b]) => a < b ? -1 : 1)) {
+    if (!pathItem || "$ref" in pathItem) continue;
+    const pathLevelParameters = (pathItem["parameters"] ?? []).filter(
+      (param) => !isReferenceObject(param)
+    );
+    for (const method of METHODS) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      const label = `${method.toUpperCase()} ${pathStr}`;
+      if (!operation.operationId) {
+        findings.push({
+          severity: "warning",
+          code: "missing-operation-id",
+          message: "Operation has no operationId; the tool name will be generated from the method and path.",
+          path: label,
+          hint: "Add a short, action-oriented operationId (it becomes the tool name)."
+        });
+      } else {
+        const existing = operationIds.get(operation.operationId) ?? [];
+        existing.push(label);
+        operationIds.set(operation.operationId, existing);
+        if (operation.operationId.length > 64) {
+          findings.push({
+            severity: "info",
+            code: "long-operation-id",
+            message: `operationId '${operation.operationId.slice(0, 40)}\u2026' exceeds 64 characters and will be truncated with a hash suffix.`,
+            path: label,
+            hint: "Shorten the operationId below 64 characters to keep tool names readable."
+          });
+        }
+      }
+      const prose = `${operation.summary ?? ""} ${operation.description ?? ""}`.trim();
+      if (prose.length === 0) {
+        findings.push({
+          severity: "warning",
+          code: "missing-description",
+          message: "Operation has neither summary nor description; the model only sees the method and path.",
+          path: label,
+          hint: "Describe WHEN to use this operation and what it returns (or patch it in with an overlay)."
+        });
+      } else if (prose.length < 20) {
+        findings.push({
+          severity: "info",
+          code: "vague-description",
+          message: `Operation description is only ${prose.length} characters \u2014 likely too vague for reliable tool selection.`,
+          path: label,
+          hint: "Expand the description with the use case and key parameters."
+        });
+      }
+      const parameters = [
+        ...pathLevelParameters,
+        ...(operation.parameters ?? []).filter((param) => !isReferenceObject(param))
+      ];
+      const undescribed = parameters.filter((param) => !param.description).map((param) => param.name);
+      if (undescribed.length > 0) {
+        findings.push({
+          severity: "info",
+          code: "missing-parameter-description",
+          message: `Parameter(s) without description: ${undescribed.join(", ")}.`,
+          path: label,
+          hint: "Describe each parameter \u2014 models mis-fill undocumented arguments."
+        });
+      }
+      const responses = operation.responses ?? {};
+      const successCodes = Object.keys(responses).filter((code) => /^2(\d\d|XX)$/i.test(code));
+      if (successCodes.length === 0 && !responses["default"]) {
+        findings.push({
+          severity: "warning",
+          code: "missing-success-response",
+          message: "Operation declares no 2xx or default response; no output schema can be generated.",
+          path: label,
+          hint: "Add the success response with its schema."
+        });
+      }
+      let responseShape = { depth: 0, widestObject: 0, hasArray: false };
+      for (const code of [...successCodes, "default"]) {
+        const response = responses[code];
+        if (!response || typeof response !== "object" || isReferenceObject(response)) continue;
+        const content = response["content"];
+        if (!content) continue;
+        for (const media of Object.values(content)) {
+          const schema = media && typeof media === "object" ? media["schema"] : void 0;
+          const shape = measureSchema(schema);
+          responseShape = {
+            depth: Math.max(responseShape.depth, shape.depth),
+            widestObject: Math.max(responseShape.widestObject, shape.widestObject),
+            hasArray: responseShape.hasArray || shape.hasArray
+          };
+        }
+      }
+      if (method === "get" && responseShape.hasArray) {
+        const hasPagination = parameters.some((param) => param.in === "query" && PAGINATION_PARAM.test(param.name));
+        if (!hasPagination) {
+          findings.push({
+            severity: "warning",
+            code: "unpaginated-list",
+            message: "GET returns an array but declares no pagination parameter \u2014 responses can blow past client result limits (Claude Code caps tool results at 25K tokens).",
+            path: label,
+            hint: "Add limit/cursor/page parameters, or shape responses at the server."
+          });
+        }
+      }
+      const body = operation.requestBody;
+      const bodyContent = body && !isReferenceObject(body) ? body.content : void 0;
+      let requestShape = { depth: 0, widestObject: 0, hasArray: false };
+      for (const media of Object.values(bodyContent ?? {})) {
+        const schema = media && typeof media === "object" ? media["schema"] : void 0;
+        const shape = measureSchema(schema);
+        requestShape = {
+          depth: Math.max(requestShape.depth, shape.depth),
+          widestObject: Math.max(requestShape.widestObject, shape.widestObject),
+          hasArray: requestShape.hasArray || shape.hasArray
+        };
+      }
+      const maxDepth = Math.max(requestShape.depth, responseShape.depth);
+      if (maxDepth > DEEP_SCHEMA_THRESHOLD) {
+        findings.push({
+          severity: "warning",
+          code: "deep-schema",
+          message: `Schema nesting reaches depth ${maxDepth} (threshold ${DEEP_SCHEMA_THRESHOLD}) \u2014 deep schemas cost tokens and reduce accuracy.`,
+          path: label,
+          hint: "Flatten the schema, or bound generation with maxSchemaDepth."
+        });
+      }
+      const maxWidth = Math.max(requestShape.widestObject, responseShape.widestObject);
+      if (maxWidth > WIDE_SCHEMA_THRESHOLD) {
+        findings.push({
+          severity: "info",
+          code: "wide-schema",
+          message: `An object schema declares ${maxWidth} properties (threshold ${WIDE_SCHEMA_THRESHOLD}).`,
+          path: label,
+          hint: "Split the payload, or bound generation with maxProperties."
+        });
+      }
+      if (bodyContent && !hasAnyExample(bodyContent)) {
+        findings.push({
+          severity: "info",
+          code: "missing-request-example",
+          message: "Request body has no example \u2014 examples measurably improve complex-parameter accuracy.",
+          path: label,
+          hint: "Add a media-type example (and enable includeExamples), or patch one in with an overlay."
+        });
+      }
+    }
+  }
+  for (const [operationId, labels] of operationIds) {
+    if (labels.length > 1) {
+      findings.push({
+        severity: "error",
+        code: "duplicate-operation-id",
+        message: `operationId '${operationId}' is used by ${labels.length} operations: ${labels.join(", ")}.`,
+        path: labels[0],
+        hint: "Make operationIds unique \u2014 duplicates force hash-suffixed tool names."
+      });
+    }
+  }
+  const rank = { error: 0, warning: 1, info: 2 };
+  findings.sort(
+    (a, b) => rank[a.severity] - rank[b.severity] || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0) || (a.code < b.code ? -1 : 1)
+  );
+  return {
+    findings,
+    counts: {
+      error: findings.filter((f) => f.severity === "error").length,
+      warning: findings.filter((f) => f.severity === "warning").length,
+      info: findings.filter((f) => f.severity === "info").length
+    }
+  };
+}
+
 // src/validator.ts
 var Validator = class {
   /**
@@ -1495,7 +2242,8 @@ var Validator = class {
         code: "NO_PATHS"
       });
     } else {
-      this.validatePaths(document.paths, errors, warnings);
+      const componentParameters = document.components?.parameters ?? {};
+      this.validatePaths(document.paths, componentParameters, errors, warnings);
     }
     if (!document.servers || document.servers.length === 0) {
       warnings.push({
@@ -1526,7 +2274,18 @@ var Validator = class {
   /**
    * Validate paths
    */
-  validatePaths(paths, errors, warnings) {
+  /**
+   * Resolve a local `#/components/parameters/<name>` reference (JSON Pointer
+   * tokens decoded). Returns undefined for external or dangling references.
+   */
+  resolveParameterRef(param, componentParameters) {
+    if (!param || typeof param !== "object" || !("$ref" in param)) return param;
+    const match = /^#\/components\/parameters\/(.+)$/.exec(String(param.$ref));
+    if (!match) return void 0;
+    const name = match[1].replace(/~1/g, "/").replace(/~0/g, "~");
+    return componentParameters[name];
+  }
+  validatePaths(paths, componentParameters, errors, warnings) {
     for (const [path, pathItem] of Object.entries(paths)) {
       if (!pathItem) continue;
       if (!path.startsWith("/")) {
@@ -1538,11 +2297,15 @@ var Validator = class {
       }
       const methods = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
       let hasOperations = false;
+      const pathLevelParameters = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+      if (pathLevelParameters.length > 0) {
+        this.validateParameters(pathLevelParameters, `/paths/${path}/parameters`, errors, warnings);
+      }
       for (const method of methods) {
         const operation = pathItem[method];
         if (operation) {
           hasOperations = true;
-          this.validateOperation(operation, path, method, errors, warnings);
+          this.validateOperation(operation, path, method, errors, warnings, pathLevelParameters, componentParameters);
         }
       }
       if (!hasOperations && !pathItem.$ref) {
@@ -1557,7 +2320,7 @@ var Validator = class {
   /**
    * Validate an operation
    */
-  validateOperation(operation, path, method, errors, warnings) {
+  validateOperation(operation, path, method, errors, warnings, pathLevelParameters = [], componentParameters = {}) {
     const basePath = `/paths/${path}/${method}`;
     if (!operation.operationId) {
       warnings.push({
@@ -1574,14 +2337,18 @@ var Validator = class {
       });
     }
     if (operation.parameters) {
-      this.validateParameters(operation.parameters, path, method, errors, warnings);
+      this.validateParameters(operation.parameters, `${basePath}/parameters`, errors, warnings);
     }
-    const pathParams = path.match(/\{([^}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
+    const allParameters = [...pathLevelParameters, ...operation.parameters ?? []].map(
+      (p) => this.resolveParameterRef(p, componentParameters)
+    );
+    const hasUnresolvableRefs = allParameters.some((p) => p === void 0);
+    const pathParams = path.match(/\{([^{}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
     const definedPathParams = new Set(
-      operation.parameters?.filter((p) => p.in === "path").map((p) => p.name) ?? []
+      allParameters.filter((p) => p && p.in === "path").map((p) => p.name)
     );
     for (const param of pathParams) {
-      if (!definedPathParams.has(param)) {
+      if (!hasUnresolvableRefs && !definedPathParams.has(param)) {
         errors.push({
           message: `Path parameter '${param}' not defined in parameters: ${method.toUpperCase()} ${path}`,
           path: `${basePath}/parameters`,
@@ -1593,11 +2360,13 @@ var Validator = class {
   /**
    * Validate parameters
    */
-  validateParameters(parameters, path, method, errors, warnings) {
-    const basePath = `/paths/${path}/${method}/parameters`;
+  validateParameters(parameters, basePath, errors, warnings) {
     for (let i = 0; i < parameters.length; i++) {
       const param = parameters[i];
       const paramPath = `${basePath}/${i}`;
+      if (param && typeof param === "object" && "$ref" in param) {
+        continue;
+      }
       if (!param.name) {
         errors.push({
           message: "Parameter missing name",
@@ -1636,56 +2405,6 @@ var Validator = class {
   }
 };
 
-// src/errors.ts
-var OpenAPIToolError = class extends Error {
-  context;
-  constructor(message, context) {
-    super(message);
-    this.name = this.constructor.name;
-    this.context = context;
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-};
-var LoadError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var SsrfError = class extends LoadError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var ParseError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var ValidationError = class extends OpenAPIToolError {
-  errors;
-  constructor(message, context) {
-    super(message, context);
-    this.errors = context?.["errors"];
-  }
-};
-var GenerationError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var RequestBuildError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-var SchemaError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
-  }
-};
-
 // src/format-resolver.ts
 var BUILTIN_FORMAT_RESOLVERS = {
   // String formats
@@ -1795,6 +2514,376 @@ function resolveSchemaFormats(schema, resolvers) {
   return result;
 }
 
+// src/type-signature.ts
+var DEFAULT_MAX_DEPTH = 8;
+var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function toPascalIdentifier(toolName) {
+  const segments = toolName.split(/[^A-Za-z0-9]+/).filter((s) => s.length > 0);
+  const joined = segments.map((s) => s[0].toUpperCase() + s.slice(1)).join("");
+  if (joined === "") {
+    return "Tool";
+  }
+  return /^[0-9]/.test(joined) ? `T${joined}` : joined;
+}
+function lowerFirst(name) {
+  return name[0].toLowerCase() + name.slice(1);
+}
+function isSchemaRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNullSchema(value) {
+  return isSchemaRecord(value) && value["type"] === "null";
+}
+function paren(expr) {
+  return expr.includes(" | ") || expr.includes(" & ") ? `(${expr})` : expr;
+}
+function dedupe(parts) {
+  return [...new Set(parts)];
+}
+function quoteKey(name) {
+  return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+function literalOf(value) {
+  if (value === null) {
+    return "null";
+  }
+  const t = typeof value;
+  if (t === "number") {
+    return Number.isFinite(value) ? JSON.stringify(value) : "number";
+  }
+  if (t === "string" || t === "boolean") {
+    return JSON.stringify(value);
+  }
+  return "unknown";
+}
+var RESERVED_WORDS = /* @__PURE__ */ new Set([
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "instanceof",
+  "new",
+  "null",
+  "return",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "implements",
+  "interface",
+  "let",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "static",
+  "yield",
+  "await"
+]);
+function escapeJsdoc(text) {
+  return text.replace(/\*\//g, "*\\/");
+}
+function jsdocLines(prop) {
+  if (!isSchemaRecord(prop)) {
+    return [];
+  }
+  const lines = [];
+  const description = prop["description"];
+  if (typeof description === "string" && description !== "") {
+    lines.push(...escapeJsdoc(description).split("\n"));
+  }
+  const format = prop["format"];
+  if (typeof format === "string" && format !== "") {
+    lines.push(`@format ${escapeJsdoc(format)}`);
+  }
+  if ("default" in prop && !(typeof prop["default"] === "number" && !Number.isFinite(prop["default"]))) {
+    const rendered = JSON.stringify(prop["default"]);
+    if (rendered !== void 0) {
+      lines.push(`@default ${escapeJsdoc(rendered)}`);
+    }
+  }
+  if (prop["deprecated"] === true) {
+    lines.push("@deprecated");
+  }
+  return lines;
+}
+function renderJsdoc(lines, indent) {
+  if (lines.length === 1) {
+    return `${indent}/** ${lines[0]} */
+`;
+  }
+  return `${indent}/**
+${lines.map((l) => `${indent} * ${l}`).join("\n")}
+${indent} */
+`;
+}
+function hasObjectShape(r) {
+  return r["type"] === "object" || r["type"] === void 0 && (r["properties"] !== void 0 || r["additionalProperties"] !== void 0 || r["patternProperties"] !== void 0);
+}
+function typeExpr(schema, ctx, depth, indent) {
+  if (schema === true) {
+    return "unknown";
+  }
+  if (schema === false) {
+    return "never";
+  }
+  if (!isSchemaRecord(schema)) {
+    return "unknown";
+  }
+  if (ctx.stack.has(schema)) {
+    return "unknown";
+  }
+  if (depth >= ctx.maxDepth) {
+    return "unknown";
+  }
+  if (schema["$ref"] !== void 0) {
+    return "unknown";
+  }
+  ctx.stack.add(schema);
+  try {
+    return typeExprInner(schema, ctx, depth, indent);
+  } finally {
+    ctx.stack.delete(schema);
+  }
+}
+function typeExprInner(r, ctx, depth, indent) {
+  if ("const" in r) {
+    const rendered = literalOf(r["const"]);
+    if (rendered !== "unknown") {
+      return rendered;
+    }
+  }
+  const enumMembers = r["enum"];
+  if (Array.isArray(enumMembers)) {
+    if (enumMembers.length === 0) {
+      return "unknown";
+    }
+    return dedupe(enumMembers.map(literalOf)).join(" | ");
+  }
+  const anyOf = r["anyOf"];
+  if (Array.isArray(anyOf) && anyOf.length === 2) {
+    const nullIdx = anyOf.findIndex(isNullSchema);
+    if (nullIdx >= 0 && !isNullSchema(anyOf[1 - nullIdx])) {
+      return `${paren(typeExpr(anyOf[1 - nullIdx], ctx, depth + 1, indent))} | null`;
+    }
+  }
+  const allOf = r["allOf"];
+  if (Array.isArray(allOf)) {
+    const parts = allOf.map((m) => paren(typeExpr(m, ctx, depth + 1, indent)));
+    if (r["properties"] !== void 0) {
+      parts.push(paren(objectExpr(r, ctx, depth, indent)));
+    }
+    return parts.length === 0 ? "unknown" : dedupe(parts).join(" & ");
+  }
+  const union = Array.isArray(r["oneOf"]) ? r["oneOf"] : Array.isArray(anyOf) ? anyOf : void 0;
+  if (union) {
+    if (union.length === 0) {
+      return "unknown";
+    }
+    return dedupe(union.map((m) => typeExpr(m, ctx, depth + 1, indent))).join(" | ");
+  }
+  const type = r["type"];
+  if (Array.isArray(type)) {
+    const parts = type.filter((t) => typeof t === "string").map((t) => typeExpr({ ...r, type: t }, ctx, depth, indent));
+    return parts.length === 0 ? "unknown" : dedupe(parts).join(" | ");
+  }
+  switch (type) {
+    case "string":
+      return "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    case "array":
+      return arrayExpr(r, ctx, depth, indent);
+    default:
+      if (hasObjectShape(r)) {
+        return objectExpr(r, ctx, depth, indent);
+      }
+      return "unknown";
+  }
+}
+function arrayExpr(r, ctx, depth, indent) {
+  const items = r["items"];
+  const prefix = Array.isArray(r["prefixItems"]) ? r["prefixItems"] : Array.isArray(items) ? items : void 0;
+  if (prefix) {
+    const parts = prefix.map((m) => typeExpr(m, ctx, depth + 1, indent));
+    let rest = "";
+    if (Array.isArray(r["prefixItems"]) && items !== void 0 && !Array.isArray(items)) {
+      rest = `, ...${paren(typeExpr(items, ctx, depth + 1, indent))}[]`;
+    }
+    return `[${parts.join(", ")}${rest}]`;
+  }
+  if (items === void 0) {
+    return "unknown[]";
+  }
+  return `${paren(typeExpr(items, ctx, depth + 1, indent))}[]`;
+}
+function objectExpr(r, ctx, depth, indent) {
+  const properties = isSchemaRecord(r["properties"]) ? r["properties"] : {};
+  const entries = Object.entries(properties);
+  const required = new Set(Array.isArray(r["required"]) ? r["required"] : []);
+  const extraTypes = [];
+  const ap = r["additionalProperties"];
+  if (ap === true) {
+    extraTypes.push("unknown");
+  } else if (isSchemaRecord(ap)) {
+    extraTypes.push(typeExpr(ap, ctx, depth + 1, indent));
+  }
+  const patternProps = r["patternProperties"];
+  if (isSchemaRecord(patternProps)) {
+    for (const value of Object.values(patternProps)) {
+      extraTypes.push(typeExpr(value, ctx, depth + 1, indent));
+    }
+  }
+  const extra = extraTypes.length > 0 ? dedupe(extraTypes).join(" | ") : void 0;
+  if (entries.length === 0) {
+    if (extra !== void 0) {
+      return `Record<string, ${extra}>`;
+    }
+    return ap === false ? "Record<string, never>" : "Record<string, unknown>";
+  }
+  const suffix = extra !== void 0 ? ` & Record<string, ${extra}>` : "";
+  if (ctx.mode === "compact") {
+    const members = entries.map(
+      ([key, prop]) => `${quoteKey(key)}${required.has(key) ? "" : "?"}: ${typeExpr(prop, ctx, depth + 1, indent)}`
+    );
+    return `{ ${members.join("; ")} }${suffix}`;
+  }
+  const inner = indent + "  ";
+  let body = "{\n";
+  for (const [key, prop] of entries) {
+    const doc = jsdocLines(prop);
+    if (doc.length > 0) {
+      body += renderJsdoc(doc, inner);
+    }
+    body += `${inner}${quoteKey(key)}${required.has(key) ? "" : "?"}: ${typeExpr(prop, ctx, depth + 1, inner)};
+`;
+  }
+  body += `${indent}}`;
+  return `${body}${suffix}`;
+}
+function isPlainObjectBody(schema) {
+  if (!isSchemaRecord(schema) || schema["$ref"] !== void 0) {
+    return false;
+  }
+  if ("const" in schema && literalOf(schema["const"]) !== "unknown" || Array.isArray(schema["enum"])) {
+    return false;
+  }
+  if (Array.isArray(schema["allOf"]) || Array.isArray(schema["oneOf"]) || Array.isArray(schema["anyOf"])) {
+    return false;
+  }
+  if (Array.isArray(schema["type"]) || !hasObjectShape(schema)) {
+    return false;
+  }
+  const properties = isSchemaRecord(schema["properties"]) ? schema["properties"] : {};
+  if (Object.keys(properties).length === 0) {
+    return false;
+  }
+  const ap = schema["additionalProperties"];
+  if (ap === true || isSchemaRecord(ap) || isSchemaRecord(schema["patternProperties"])) {
+    return false;
+  }
+  return true;
+}
+function namedRoot(name, schema, ctx) {
+  const expr = typeExpr(schema, ctx, 0, "");
+  return isPlainObjectBody(schema) ? `interface ${name} ${expr}` : `type ${name} = ${expr};`;
+}
+function paramList(inputSchema, typeText) {
+  if (inputSchema === true) {
+    return `(input?: ${typeText})`;
+  }
+  if (!isSchemaRecord(inputSchema)) {
+    return "()";
+  }
+  const properties = isSchemaRecord(inputSchema["properties"]) ? inputSchema["properties"] : {};
+  const keys = Object.keys(properties);
+  if (keys.length === 0) {
+    const ap = inputSchema["additionalProperties"];
+    const hasExtra = ap === true || isSchemaRecord(ap) || isSchemaRecord(inputSchema["patternProperties"]);
+    const objectish = inputSchema["type"] === "object" || inputSchema["type"] === void 0;
+    const composed = Array.isArray(inputSchema["allOf"]) || Array.isArray(inputSchema["oneOf"]) || Array.isArray(inputSchema["anyOf"]) || Array.isArray(inputSchema["enum"]) || "const" in inputSchema;
+    return objectish && !hasExtra && !composed ? "()" : `(input: ${typeText})`;
+  }
+  const required = new Set(Array.isArray(inputSchema["required"]) ? inputSchema["required"] : []);
+  const allOptional = keys.every((k) => !required.has(k));
+  return allOptional ? `(input?: ${typeText})` : `(input: ${typeText})`;
+}
+function outputVariantsDeclaration(name, variants, ctx) {
+  const lines = variants.map((member) => {
+    let comment = "";
+    if (isSchemaRecord(member)) {
+      const status = member["x-status-code"];
+      if (typeof status === "number" || typeof status === "string") {
+        const contentType = member["x-content-type"];
+        const ct = typeof contentType === "string" ? ` (${escapeJsdoc(contentType)})` : "";
+        comment = `/** status ${escapeJsdoc(String(status))}${ct} */ `;
+      }
+    }
+    return `  | ${comment}${typeExpr(member, ctx, 1, "  ")}`;
+  });
+  return `type ${name} =
+${lines.join("\n")};`;
+}
+function emitToolTypeScript(toolName, description, inputSchema, outputSchema, options = {}) {
+  const maxDepth = typeof options.maxDepth === "number" && Number.isFinite(options.maxDepth) ? Math.max(1, Math.floor(options.maxDepth)) : DEFAULT_MAX_DEPTH;
+  const compact = { mode: "compact", maxDepth, stack: /* @__PURE__ */ new Set() };
+  const pretty = { mode: "pretty", maxDepth, stack: /* @__PURE__ */ new Set() };
+  const inputCompact = typeExpr(inputSchema, compact, 0, "");
+  const outputCompact = outputSchema === void 0 ? "unknown" : typeExpr(outputSchema, compact, 0, "");
+  const signature = `${paramList(inputSchema, inputCompact)} => Promise<${outputCompact}>`;
+  const base = toPascalIdentifier(toolName);
+  const inputName = `${base}Input`;
+  const outputName = `${base}Output`;
+  const blocks = [];
+  if (typeof description === "string" && description !== "") {
+    blocks.push(renderJsdoc(escapeJsdoc(description).split("\n"), "").trimEnd());
+  }
+  blocks.push(namedRoot(inputName, inputSchema, pretty));
+  const outputUnion = isSchemaRecord(outputSchema) && Array.isArray(outputSchema["oneOf"]) ? outputSchema["oneOf"] : void 0;
+  if (outputSchema === void 0) {
+    blocks.push(`type ${outputName} = unknown;`);
+  } else if (outputUnion && outputUnion.some((m) => isSchemaRecord(m) && m["x-status-code"] !== void 0)) {
+    blocks.push(outputVariantsDeclaration(outputName, outputUnion, pretty));
+  } else {
+    blocks.push(namedRoot(outputName, outputSchema, pretty));
+  }
+  let fnName = lowerFirst(base);
+  if (RESERVED_WORDS.has(fnName)) {
+    fnName = `${fnName}_`;
+  }
+  blocks.push(`declare function ${fnName}${paramList(inputSchema, inputName)}: Promise<${outputName}>;`);
+  return { signature, declaration: blocks.join("\n\n") };
+}
+
 // src/ssrf.ts
 var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
   "localhost",
@@ -2084,6 +3173,103 @@ function applySecureDefaults(options) {
     }
   };
 }
+function hasUnboundedArray(node, seen = /* @__PURE__ */ new Set()) {
+  if (node === null || typeof node !== "object" || seen.has(node)) return false;
+  seen.add(node);
+  const record = node;
+  const type = record["type"];
+  const isArray = type === "array" || Array.isArray(type) && type.includes("array");
+  if (isArray && record["maxItems"] === void 0) return true;
+  const children = [];
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") children.push(...Object.values(properties));
+  for (const key of ["items", "additionalProperties", "contentSchema"]) {
+    const value = record[key];
+    if (Array.isArray(value)) children.push(...value);
+    else if (value && typeof value === "object") children.push(value);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    if (Array.isArray(record[key])) children.push(...record[key]);
+  }
+  return children.some((child) => hasUnboundedArray(child, seen));
+}
+function detectResponseHints(outputSchema, mapper) {
+  const paginationParams = [
+    ...new Set(mapper.filter((m) => m.type === "query" && !m.security && PAGINATION_PARAM.test(m.key)).map((m) => m.key))
+  ];
+  const unboundedArray = outputSchema !== void 0 && hasUnboundedArray(outputSchema);
+  if (!unboundedArray && paginationParams.length === 0) return void 0;
+  return {
+    ...unboundedArray && { unboundedArray: true },
+    ...paginationParams.length > 0 && { paginationParams },
+    ...unboundedArray && paginationParams.length === 0 && { largeResponseRisk: true }
+  };
+}
+function composeDescription(operation, method, pathStr, strategy) {
+  const fallback = `${method.toUpperCase()} ${pathStr}`;
+  const summary = operation.summary?.trim();
+  const description = operation.description?.trim();
+  switch (strategy) {
+    case "descriptionOnly":
+      return description || summary || fallback;
+    case "combined":
+      if (summary && description && summary !== description) {
+        return `${summary}
+
+${description}`;
+      }
+      return summary || description || fallback;
+    case "full": {
+      const parts = [];
+      if (summary) parts.push(summary);
+      if (description && description !== summary) parts.push(description);
+      if (operation.operationId) parts.push(`Operation: ${operation.operationId}`);
+      parts.push(fallback);
+      return parts.join("\n\n");
+    }
+    default:
+      return summary || description || fallback;
+  }
+}
+function propertyNames(schema, cap = 8) {
+  const properties = schema["properties"];
+  if (!properties || typeof properties !== "object") return "";
+  const names = Object.keys(properties);
+  const listed = names.slice(0, cap).join(", ");
+  return names.length > cap ? `${listed}, \u2026` : listed;
+}
+function summarizeOutputSchema(schema) {
+  const record = schema;
+  const variants = record["oneOf"];
+  if (Array.isArray(variants) && variants.length > 0) {
+    const first = variants[0];
+    const firstSummary = first && typeof first === "object" ? summarizeOutputSchema(first) : void 0;
+    return firstSummary ? `${firstSummary} (${variants.length} response variants)` : void 0;
+  }
+  const type = record["type"];
+  if (type === "object" || type === void 0 && record["properties"]) {
+    const names = propertyNames(record);
+    return names ? `object with fields: ${names}` : "object";
+  }
+  if (type === "array") {
+    const items = record["items"];
+    if (items && typeof items === "object" && !Array.isArray(items)) {
+      const itemRecord = items;
+      if (itemRecord["type"] === "object" || itemRecord["properties"]) {
+        const names = propertyNames(itemRecord);
+        return names ? `array of objects with fields: ${names}` : "array of objects";
+      }
+      if (typeof itemRecord["type"] === "string") {
+        return `array of ${itemRecord["type"]}`;
+      }
+    }
+    return "array";
+  }
+  if (typeof type === "string" && type !== "null") {
+    return type;
+  }
+  return void 0;
+}
 function globToRegExp(glob) {
   let pattern = "^";
   for (let i = 0; i < glob.length; i++) {
@@ -2106,6 +3292,32 @@ function globToRegExp(glob) {
 function matchesAnyGlob(path, globs) {
   return globs.some((glob) => globToRegExp(glob).test(path));
 }
+function iconsFromInfoLogo(info) {
+  if (!info || typeof info !== "object") {
+    return void 0;
+  }
+  const logo = info["x-logo"];
+  let src;
+  if (typeof logo === "string") {
+    src = logo;
+  } else if (logo && typeof logo === "object" && !Array.isArray(logo)) {
+    const url = logo["url"];
+    if (typeof url === "string") {
+      src = url;
+    }
+  }
+  if (src !== void 0 && isAllowedIconSrc(src)) {
+    return [{ src }];
+  }
+  return void 0;
+}
+function trimUnderscores(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === "_") start++;
+  while (end > start && value[end - 1] === "_") end--;
+  return value.slice(start, end);
+}
 function fnv1aHex(input) {
   let hash = 2166136261;
   for (let i = 0; i < input.length; i++) {
@@ -2116,7 +3328,7 @@ function fnv1aHex(input) {
 }
 function normalizeToolName(raw, maxLength, fallbackSeed) {
   let hashSeed = raw;
-  let name = raw.replace(/[^A-Za-z0-9_.-]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  let name = trimUnderscores(raw.replace(/[^A-Za-z0-9_.-]/g, "_").replace(/_+/g, "_"));
   if (name.length === 0) {
     hashSeed = fallbackSeed;
     name = `tool_${fnv1aHex(fallbackSeed)}`;
@@ -2149,8 +3361,15 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       validate: options.validate ?? true,
       followRedirects: options.followRedirects ?? true,
       refResolution: options.refResolution ?? {},
-      secureDefaults: options.secureDefaults ?? false
+      secureDefaults: options.secureDefaults ?? false,
+      overlays: options.overlays
     };
+    if (this.options.overlays) {
+      const overlays = Array.isArray(this.options.overlays) ? this.options.overlays : [this.options.overlays];
+      for (const overlay of overlays) {
+        this.document = applyOverlay(this.document, overlay);
+      }
+    }
   }
   /**
    * Create generator from a URL
@@ -2180,7 +3399,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       }
       return new _OpenAPIToolGenerator(document, options);
     } catch (error) {
-      if (error instanceof LoadError) {
+      if (error instanceof LoadError || error instanceof OverlayError) {
         throw error;
       }
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -2213,6 +3432,9 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       }
       return new _OpenAPIToolGenerator(document, options);
     } catch (error) {
+      if (error instanceof OverlayError) {
+        throw error;
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new LoadError(`Failed to load OpenAPI spec from file: ${errorMessage}`, {
         filePath,
@@ -2228,6 +3450,9 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       const document = yaml.parse(yamlString);
       return new _OpenAPIToolGenerator(document, options);
     } catch (error) {
+      if (error instanceof OverlayError) {
+        throw error;
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new ParseError(`Failed to parse YAML: ${errorMessage}`, {
         originalError: error
@@ -2254,6 +3479,16 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     const validator = new Validator();
     return validator.validate(this.document);
   }
+  /**
+   * Lint the loaded document for agent-readiness (missing operationIds,
+   * vague descriptions, unpaginated lists, oversized schemas, ...). Runs
+   * after overlays and dereferencing so findings reflect what tools would
+   * actually be generated from.
+   */
+  async lint() {
+    await this.initialize(false);
+    return lintDocument(this.getDocument());
+  }
   // NOTE: internal/private-address blocking + IPv4-mapped-IPv6 decoding now live
   // in `ssrf.ts` (`isBlockedHostname` / `isBlockedAddress` / `decodeIpv4MappedIpv6`),
   // shared by the spec-URL fetch (`fromURL`) and the `$ref` resolver below, and
@@ -2391,7 +3626,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   /**
    * Initialize the generator (dereference if needed, then validate)
    */
-  async initialize() {
+  async initialize(runValidation = this.options.validate) {
     if (this.options.dereference && !this.dereferencedDocument) {
       const cloned = JSON.parse(JSON.stringify(this.document));
       if (!_OpenAPIToolGenerator.hasExternalRefs(cloned)) {
@@ -2409,7 +3644,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
         }
       }
     }
-    if (this.options.validate) {
+    if (runValidation) {
       const validator = new Validator();
       const documentToValidate = this.dereferencedDocument ?? this.document;
       const result = await validator.validate(documentToValidate);
@@ -2458,6 +3693,14 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
               attempts++;
             }
             tool = { ...tool, name: deduped };
+            if (tool.metadata.typescript) {
+              tool.metadata = {
+                ...tool.metadata,
+                typescript: emitToolTypeScript(deduped, tool.description, tool.inputSchema, tool.outputSchema, {
+                  maxDepth: Math.max(1, options.maxSchemaDepth ?? 10)
+                })
+              };
+            }
           }
           usedNames.add(tool.name);
           tools.push(tool);
@@ -2506,8 +3749,14 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     const responseBuilder = new ResponseBuilder(options);
     const outputSchema = responseBuilder.build(operation.responses);
     const overrides = extractExtensionOverrides(operation);
-    const name = this.generateToolName(pathStr, method, overrides.name ?? operation.operationId, options);
-    const description = overrides.description ?? (operation.summary || operation.description || `${method.toUpperCase()} ${pathStr}`);
+    const name = this.generateToolName(
+      pathStr,
+      method,
+      overrides.name ?? operation.operationId,
+      options,
+      operation
+    );
+    const description = overrides.description ?? composeDescription(operation, method, pathStr, options.descriptionStrategy ?? "summaryOnly");
     const title = overrides.title ?? operation.summary;
     const inferred = options.inferAnnotations !== false ? inferAnnotationsFromMethod(method.toLowerCase()) : void 0;
     const annotations = inferred || overrides.annotations ? { ...inferred, ...overrides.annotations } : void 0;
@@ -2524,17 +3773,95 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     if (resolvedOutputSchema) {
       resolvedOutputSchema = SchemaBuilder.truncateDepth(resolvedOutputSchema, maxSchemaDepth);
     }
+    const applyTrim = (schema, isInputRoot) => {
+      let trimmed = schema;
+      if (options.stripExamples) trimmed = SchemaBuilder.stripExamples(trimmed);
+      if (options.maxDescriptionLength !== void 0) {
+        trimmed = SchemaBuilder.capDescriptions(trimmed, options.maxDescriptionLength);
+      }
+      if (options.maxProperties !== void 0) {
+        if (isInputRoot) {
+          const properties = trimmed.properties;
+          if (properties && typeof properties === "object") {
+            const limited = {};
+            for (const [key, value] of Object.entries(properties)) {
+              limited[key] = SchemaBuilder.limitProperties(value, options.maxProperties);
+            }
+            trimmed = { ...trimmed, properties: limited };
+          }
+        } else {
+          trimmed = SchemaBuilder.limitProperties(trimmed, options.maxProperties);
+        }
+      }
+      return trimmed;
+    };
+    if (options.stripExamples || options.maxProperties !== void 0 || options.maxDescriptionLength !== void 0) {
+      resolvedInputSchema = applyTrim(resolvedInputSchema, true);
+      if (resolvedOutputSchema) {
+        resolvedOutputSchema = applyTrim(resolvedOutputSchema, false);
+      }
+    }
     if (options.target) {
       resolvedInputSchema = applyClientTarget(resolvedInputSchema, options.target);
       if (resolvedOutputSchema) {
         resolvedOutputSchema = applyClientTarget(resolvedOutputSchema, options.target);
       }
     }
+    const responseHints = detectResponseHints(resolvedOutputSchema, mapper);
+    if (responseHints) {
+      metadata.responseHints = responseHints;
+    }
+    let finalDescription = description;
+    if (options.appendResponseSummary && resolvedOutputSchema) {
+      const summary = summarizeOutputSchema(resolvedOutputSchema);
+      if (summary) {
+        finalDescription = `${finalDescription}
+
+Returns: ${summary}`;
+      }
+    }
+    if (options.emitTypeSignatures) {
+      metadata.typescript = emitToolTypeScript(name, finalDescription, resolvedInputSchema, resolvedOutputSchema, {
+        // Print at least as deep as the schemas were truncated, so the
+        // emitted types never collapse levels the schema still carries.
+        maxDepth: Math.max(1, options.maxSchemaDepth ?? 10)
+      });
+    }
+    let toolMeta;
+    if (overrides.meta) {
+      toolMeta = {};
+      for (const [key, value] of Object.entries(overrides.meta)) {
+        if (!key.startsWith("dev.agentfront.openapi/")) {
+          toolMeta[key] = value;
+        }
+      }
+    }
+    if (options.emitMeta) {
+      const info = document.info;
+      toolMeta = {
+        ...toolMeta,
+        "dev.agentfront.openapi/operation": {
+          path: pathStr,
+          method,
+          ...operation.operationId !== void 0 && { operationId: operation.operationId },
+          ...operation.tags && { tags: [...operation.tags] },
+          ...operation.deprecated !== void 0 && { deprecated: operation.deprecated },
+          ...typeof info?.["title"] === "string" && { specTitle: info["title"] },
+          ...typeof info?.["version"] === "string" && { specVersion: info["version"] }
+        }
+      };
+    }
+    if (toolMeta && Object.keys(toolMeta).length === 0) {
+      toolMeta = void 0;
+    }
+    const icons = overrides.icons ?? (options.inheritDocumentIcons ? iconsFromInfoLogo(document.info) : void 0);
     return {
       name,
       ...title !== void 0 && { title },
-      description,
+      description: finalDescription,
       ...annotations && { annotations },
+      ...toolMeta && { _meta: toolMeta },
+      ...icons && { icons },
       inputSchema: resolvedInputSchema,
       outputSchema: resolvedOutputSchema,
       mapper,
@@ -2602,14 +3929,16 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   /**
    * Generate a tool name
    */
-  generateToolName(path, method, operationId, options = {}) {
+  generateToolName(path, method, operationId, options = {}, operation) {
     let rawName;
     if (options.namingStrategy?.toolNameGenerator) {
-      rawName = options.namingStrategy.toolNameGenerator(path, method, operationId);
+      rawName = options.namingStrategy.toolNameGenerator(path, method, operationId, operation);
     } else if (operationId) {
       rawName = operationId;
     } else {
-      const sanitized = path.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+      const sanitized = trimUnderscores(
+        path.replace(/\{([^{}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_")
+      );
       rawName = `${method}_${sanitized}`;
     }
     return normalizeToolName(
@@ -2824,7 +4153,7 @@ var SecurityResolver = class {
   resolveDigestAuth(context) {
     const digest = context.digest;
     if (!digest) return void 0;
-    const quoted = (v) => String(v).replace(/[\r\n]/g, "").replace(/"/g, '\\"');
+    const quoted = (v) => String(v).replace(/[\r\n]/g, "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
     const token = (v) => String(v).replace(/[\r\n",]/g, "");
     const parts = [
       `username="${quoted(digest.username)}"`,
@@ -2941,6 +4270,1213 @@ function createSecurityContext(auth) {
   };
 }
 
+// src/naming-presets.ts
+var CODECALL_RESERVED_NAMESPACES = [
+  "console",
+  "Math",
+  "JSON",
+  "Object",
+  "Promise",
+  "Array",
+  "String",
+  "Number",
+  "Boolean",
+  "Date",
+  "RegExp",
+  "Error",
+  "Symbol",
+  "Map",
+  "Set",
+  "WeakMap",
+  "WeakSet",
+  "globalThis",
+  "global",
+  "window",
+  "self",
+  "undefined",
+  "null",
+  "true",
+  "false",
+  "NaN",
+  "Infinity",
+  "callTool",
+  "getTool",
+  "mcpLog",
+  "mcpNotify"
+];
+function sanitizeIdentifier(value) {
+  if (value === void 0) {
+    return "";
+  }
+  let out = value.replace(/[^A-Za-z0-9_]+/g, "_").replace(/_+/g, "_");
+  let start = 0;
+  let end = out.length;
+  while (start < end && out[start] === "_") start++;
+  while (end > start && out[end - 1] === "_") end--;
+  out = out.slice(start, end);
+  if (out === "") {
+    return "";
+  }
+  return /^[0-9]/.test(out) ? `_${out}` : out;
+}
+function firstPathSegment(path) {
+  for (const segment of path.split("/")) {
+    if (segment !== "" && !segment.startsWith("{")) {
+      return sanitizeIdentifier(segment);
+    }
+  }
+  return "";
+}
+function pathMethodHalf(method, path, ns) {
+  const segments = path.split("/").filter((s) => s !== "").map((s) => {
+    const templated = s.replace(/\{([^{}]+)\}/g, "by_$1");
+    return sanitizeIdentifier(templated);
+  }).filter((s) => s !== "");
+  if (segments.length > 0 && segments[0] === ns) {
+    segments.shift();
+  }
+  const joined = segments.join("_");
+  return joined === "" ? method : `${method}_${joined}`;
+}
+function dottedNaming(options = {}) {
+  const namespaceFrom = options.namespaceFrom ?? "tag";
+  const reserved = /* @__PURE__ */ new Set([...CODECALL_RESERVED_NAMESPACES, ...options.reservedNamespaces ?? []]);
+  return {
+    toolNameGenerator: (path, method, operationId, operation) => {
+      let ns = "";
+      if (namespaceFrom === "tag") {
+        ns = sanitizeIdentifier(operation?.tags?.[0]);
+      }
+      if (ns === "") {
+        ns = firstPathSegment(path);
+      }
+      if (ns === "") {
+        ns = "api";
+      }
+      if (ns.startsWith("_")) {
+        ns = `n${ns.slice(1)}`;
+      }
+      if (reserved.has(ns)) {
+        ns = `${ns}_`;
+      }
+      const methodHalf = sanitizeIdentifier(operationId) || pathMethodHalf(method, path, ns);
+      return `${ns}.${methodHalf}`;
+    }
+  };
+}
+
+// src/elicitation.ts
+function buildElicitation(source) {
+  const { scheme, type } = source;
+  if (type === "http") {
+    const httpScheme = (source.httpScheme ?? "bearer").toLowerCase();
+    if (httpScheme === "basic" || httpScheme === "digest") {
+      return {
+        scheme,
+        message: `Provide HTTP ${httpScheme} credentials for "${scheme}".`,
+        requestedSchema: {
+          type: "object",
+          properties: {
+            username: { type: "string", title: "Username" },
+            password: { type: "string", title: "Password", description: "Handled as a secret \u2014 never logged." }
+          },
+          required: ["username", "password"]
+        }
+      };
+    }
+    const format = source.bearerFormat ? ` (${source.bearerFormat})` : "";
+    return {
+      scheme,
+      message: `Provide the ${httpScheme} token for "${scheme}".`,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          token: { type: "string", title: "Token", description: `HTTP ${httpScheme} authentication token${format}.` }
+        },
+        required: ["token"]
+      }
+    };
+  }
+  if (type === "apiKey") {
+    const keyName = source.apiKeyName ?? scheme;
+    const location = source.apiKeyIn ?? "header";
+    return {
+      scheme,
+      message: `Provide the API key for "${scheme}".`,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          apiKey: { type: "string", title: "API key", description: `API key "${keyName}" sent via ${location}.` }
+        },
+        required: ["apiKey"]
+      }
+    };
+  }
+  if (type === "oauth2" || type === "openIdConnect") {
+    const scopes = source.scopes && source.scopes.length > 0 ? ` Scopes: ${source.scopes.join(", ")}.` : "";
+    return {
+      scheme,
+      message: `Provide an OAuth2 access token for "${scheme}".${scopes}`,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          accessToken: { type: "string", title: "Access token", description: `OAuth2 access token.${scopes}` }
+        },
+        required: ["accessToken"]
+      }
+    };
+  }
+  return void 0;
+}
+function deriveSecurityElicitations(tool) {
+  const sources = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of tool.mapper) {
+    const security = entry.security;
+    if (security && !seen.has(security.scheme)) {
+      seen.add(security.scheme);
+      sources.push(security);
+    }
+  }
+  if (sources.length === 0 && tool.metadata.security) {
+    for (const requirement of tool.metadata.security) {
+      if (!seen.has(requirement.scheme)) {
+        seen.add(requirement.scheme);
+        sources.push({
+          scheme: requirement.scheme,
+          type: requirement.type,
+          httpScheme: requirement.httpScheme,
+          bearerFormat: requirement.bearerFormat,
+          scopes: requirement.scopes,
+          apiKeyName: requirement.name,
+          apiKeyIn: requirement.in
+        });
+      }
+    }
+  }
+  const result = [];
+  for (const source of sources) {
+    const elicitation = buildElicitation(source);
+    if (elicitation) {
+      result.push(elicitation);
+    }
+  }
+  return result;
+}
+
+// src/arazzo-expressions.ts
+var EXACT_ROOTS = {
+  $url: "url",
+  $method: "method",
+  $statusCode: "statusCode"
+};
+var DOTTED_ROOTS = {
+  $inputs: "inputs",
+  $outputs: "outputs",
+  $steps: "steps",
+  $workflows: "workflows",
+  $sourceDescriptions: "sourceDescriptions",
+  $components: "components"
+};
+var KNOWN_ROOT = /^\$(?:(?:url|method|statusCode)$|(?:request|response|message)\.|(?:inputs|outputs|steps|workflows|sourceDescriptions|components)\.)/;
+function fail(message, docPath, expression) {
+  throw new ArazzoError(message, { path: docPath, expression });
+}
+var TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+function parseSourceRef(prefix, rest, raw, docPath) {
+  if (rest.startsWith("header.")) {
+    const name = rest.slice("header.".length);
+    if (name === "" || !TOKEN.test(name)) {
+      fail(`Invalid header name in runtime expression "${raw}"`, docPath, raw);
+    }
+    return { type: prefix, raw, path: [], source: "header", name };
+  }
+  if (rest.startsWith("query.") || rest.startsWith("path.")) {
+    const source = rest.startsWith("query.") ? "query" : "path";
+    const name = rest.slice(source.length + 1);
+    if (name === "") {
+      fail(`Empty ${source} parameter name in runtime expression "${raw}"`, docPath, raw);
+    }
+    return { type: prefix, raw, path: [], source, name };
+  }
+  if (rest === "body" || rest.startsWith("body#")) {
+    const node = { type: prefix, raw, path: [], source: "body" };
+    if (rest.startsWith("body#")) {
+      const pointer = rest.slice("body#".length);
+      if (pointer !== "" && !pointer.startsWith("/")) {
+        fail(`JSON Pointer in "${raw}" must be empty or start with "/"`, docPath, raw);
+      }
+      node.pointer = pointer;
+    }
+    return node;
+  }
+  fail(`Invalid $${prefix} reference "${raw}" \u2014 expected header.<name>, query.<name>, path.<name>, or body[#<pointer>]`, docPath, raw);
+}
+function parseRuntimeExpression(raw, docPath = "") {
+  const exact = EXACT_ROOTS[raw];
+  if (exact) {
+    return { type: exact, raw, path: [] };
+  }
+  for (const key of Object.keys(EXACT_ROOTS)) {
+    if (raw.startsWith(key) && raw !== key) {
+      fail(`Unexpected characters after "${key}" in runtime expression "${raw}"`, docPath, raw);
+    }
+  }
+  for (const prefix of ["request", "response", "message"]) {
+    if (raw.startsWith(`$${prefix}.`)) {
+      return parseSourceRef(prefix, raw.slice(prefix.length + 2), raw, docPath);
+    }
+  }
+  const dot = raw.indexOf(".");
+  const rootToken = dot === -1 ? raw : raw.slice(0, dot);
+  const root = DOTTED_ROOTS[rootToken];
+  if (root) {
+    const rest = dot === -1 ? "" : raw.slice(dot + 1);
+    if (rest === "") {
+      fail(`Runtime expression "${raw}" is missing a name after "${rootToken}."`, docPath, raw);
+    }
+    const path = rest.split(".");
+    if (path.some((segment) => segment === "" || /\s/.test(segment))) {
+      fail(`Runtime expression "${raw}" contains an empty or whitespace path segment`, docPath, raw);
+    }
+    return { type: root, raw, path };
+  }
+  fail(`Invalid runtime expression "${raw}"`, docPath, raw);
+}
+function parseExpressionValue(value, docPath = "") {
+  if (typeof value !== "string") {
+    return { kind: "literal", value };
+  }
+  if (value.startsWith("$")) {
+    if (KNOWN_ROOT.test(value)) {
+      return { kind: "expression", expression: parseRuntimeExpression(value, docPath) };
+    }
+    return { kind: "literal", value };
+  }
+  if (!value.includes("{$")) {
+    return { kind: "literal", value };
+  }
+  const parts = [];
+  let cursor = 0;
+  while (cursor < value.length) {
+    const open = value.indexOf("{$", cursor);
+    if (open === -1) {
+      parts.push(value.slice(cursor));
+      break;
+    }
+    if (open > cursor) {
+      parts.push(value.slice(cursor, open));
+    }
+    const close = value.indexOf("}", open);
+    if (close === -1) {
+      fail(`Unterminated "{$" template expression in "${value}"`, docPath, value);
+    }
+    parts.push(parseRuntimeExpression(value.slice(open + 1, close), docPath));
+    cursor = close + 1;
+  }
+  return { kind: "template", raw: value, parts };
+}
+function escapePointerSegment(segment) {
+  return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function collectPayloadExpressions(payload, docPath = "") {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (node, pointer) => {
+    if (typeof node === "string") {
+      const value = parseExpressionValue(node, docPath);
+      if (value.kind !== "literal") {
+        found.push({ pointer, value });
+      }
+      return;
+    }
+    if (!node || typeof node !== "object") {
+      return;
+    }
+    if (seen.has(node)) {
+      return;
+    }
+    seen.add(node);
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => visit(item, `${pointer}/${index}`));
+      return;
+    }
+    for (const [key, value] of Object.entries(node)) {
+      visit(value, `${pointer}/${escapePointerSegment(key)}`);
+    }
+  };
+  visit(payload, "");
+  return found;
+}
+
+// src/arazzo.ts
+var yaml2 = __toESM(require("yaml"));
+var ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+var OUTPUT_KEY_PATTERN = /^[a-zA-Z0-9.\-_]+$/;
+var VERSION_PATTERN = /^1\.0\.\d+$/;
+var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+var PARAMETER_LOCATIONS = ["path", "query", "header", "cookie"];
+var OUTPUT_DERIVATION_MAX_DEPTH = 8;
+function err(message, path, extra) {
+  throw new ArazzoError(message, { path, ...extra });
+}
+function toPlainJson(value) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ArazzoError(`Arazzo document must be JSON-serializable (acyclic, bounded depth): ${message}`, {
+      path: ""
+    });
+  }
+}
+function parseArazzoInput(input) {
+  if (typeof input === "string") {
+    let parsed;
+    try {
+      parsed = yaml2.parse(input);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ArazzoError(`Failed to parse Arazzo document: ${message}`, { path: "" });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      err("Arazzo document must be an object", "");
+    }
+    return toPlainJson(parsed);
+  }
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    err("Arazzo document must be an object", "");
+  }
+  return toPlainJson(input);
+}
+function validateCriteria(criteria, path) {
+  if (criteria === void 0) return;
+  if (!Array.isArray(criteria)) {
+    err("successCriteria/criteria must be an array", path);
+  }
+  criteria.forEach((criterion, index) => {
+    const cPath = `${path}/${index}`;
+    if (!criterion || typeof criterion !== "object") {
+      err("Criterion must be an object", cPath);
+    }
+    if (typeof criterion.condition !== "string" || criterion.condition === "") {
+      err('Criterion requires a non-empty string "condition"', cPath);
+    }
+    const type = criterion.type;
+    let effectiveType;
+    if (type !== void 0) {
+      if (typeof type === "string") {
+        if (!["simple", "regex", "jsonpath", "xpath"].includes(type)) {
+          err(`Unknown criterion type "${type}"`, cPath);
+        }
+        effectiveType = type;
+      } else if (type && typeof type === "object") {
+        if (type.type !== "jsonpath" && type.type !== "xpath" || typeof type.version !== "string") {
+          err('Criterion Expression Type Object requires "type" (jsonpath|xpath) and "version"', cPath);
+        }
+        effectiveType = type.type;
+      } else {
+        err('Criterion "type" must be a string or a Criterion Expression Type Object', cPath);
+      }
+    }
+    if (criterion.context !== void 0 && typeof criterion.context !== "string") {
+      err('Criterion "context" must be a runtime expression string', cPath);
+    }
+    if (effectiveType !== void 0 && effectiveType !== "simple" && criterion.context === void 0) {
+      err(`Criterion of type "${effectiveType}" requires a "context" expression`, cPath);
+    }
+  });
+}
+function validateActions(actions, kind, path) {
+  if (actions === void 0) return;
+  if (!Array.isArray(actions)) {
+    err("Actions must be an array", path);
+  }
+  actions.forEach((action, index) => {
+    const aPath = `${path}/${index}`;
+    if (!action || typeof action !== "object") {
+      err("Action must be an object", aPath);
+    }
+    if ("reference" in action) {
+      return;
+    }
+    validateActionObject(action, kind, aPath);
+  });
+}
+function validateActionObject(action, kind, aPath) {
+  const act = action;
+  if (typeof act.name !== "string" || act.name === "") {
+    err('Action requires a non-empty string "name"', aPath);
+  }
+  const allowed = kind === "success" ? ["end", "goto"] : ["end", "retry", "goto"];
+  if (!allowed.includes(act.type)) {
+    err(`Invalid ${kind}-action type "${String(act.type)}" (allowed: ${allowed.join(", ")})`, aPath);
+  }
+  const targets = [act.workflowId, act.stepId].filter((t) => t !== void 0).length;
+  if (act.type === "goto" && targets !== 1) {
+    err('A "goto" action requires exactly one of "workflowId" or "stepId"', aPath);
+  }
+  if (act.type === "end" && targets !== 0) {
+    err('An "end" action must not specify "workflowId" or "stepId"', aPath);
+  }
+  if (act.retryAfter !== void 0 && (typeof act.retryAfter !== "number" || act.retryAfter < 0)) {
+    err('"retryAfter" must be a non-negative number', aPath);
+  }
+  if (act.retryLimit !== void 0 && (typeof act.retryLimit !== "number" || !Number.isInteger(act.retryLimit) || act.retryLimit < 0)) {
+    err('"retryLimit" must be a non-negative integer', aPath);
+  }
+  validateCriteria(act.criteria, `${aPath}/criteria`);
+}
+function validateParameters(parameters, requireIn, path) {
+  if (parameters === void 0) return;
+  if (!Array.isArray(parameters)) {
+    err("Parameters must be an array", path);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  parameters.forEach((parameter, index) => {
+    const pPath = `${path}/${index}`;
+    if (!parameter || typeof parameter !== "object") {
+      err("Parameter must be an object", pPath);
+    }
+    if ("reference" in parameter) {
+      return;
+    }
+    validateParameterObject(parameter, requireIn, pPath);
+    const param = parameter;
+    const key = `${param.name} ${param.in ?? ""}`;
+    if (seen.has(key)) {
+      err(`Duplicate parameter "${param.name}"${param.in ? ` (in: ${param.in})` : ""}`, pPath);
+    }
+    seen.add(key);
+  });
+}
+function validateParameterObject(param, requireIn, pPath) {
+  if (typeof param.name !== "string" || param.name === "") {
+    err('Parameter requires a non-empty string "name"', pPath);
+  }
+  const paramName = param.name;
+  if (!("value" in param)) {
+    err(`Parameter "${paramName}" requires a "value"`, pPath);
+  }
+  if (param.in !== void 0 && !PARAMETER_LOCATIONS.includes(param.in)) {
+    err(`Invalid parameter location "${String(param.in)}"`, pPath);
+  }
+  if (requireIn === true && param.in === void 0) {
+    err(`Parameter "${param.name}" on an operation step requires "in"`, pPath);
+  }
+  if (requireIn === false && param.in !== void 0) {
+    err(`Parameter "${param.name}" on a workflowId step must not specify "in"`, pPath);
+  }
+}
+function validateOutputs(outputs, path) {
+  if (outputs === void 0) return;
+  if (!outputs || typeof outputs !== "object" || Array.isArray(outputs)) {
+    err('"outputs" must be an object of name \u2192 runtime expression', path);
+  }
+  for (const [key, value] of Object.entries(outputs)) {
+    if (!OUTPUT_KEY_PATTERN.test(key)) {
+      err(`Invalid output name "${key}"`, `${path}/${key}`);
+    }
+    if (typeof value !== "string") {
+      err(`Output "${key}" must be a runtime expression string`, `${path}/${key}`);
+    }
+  }
+}
+function validateDocument(doc) {
+  if (typeof doc.arazzo !== "string" || !VERSION_PATTERN.test(doc.arazzo)) {
+    err(`Unsupported arazzo version "${String(doc.arazzo)}" (expected 1.0.x)`, "/arazzo");
+  }
+  if (!doc.info || typeof doc.info !== "object" || typeof doc.info.title !== "string" || typeof doc.info.version !== "string") {
+    err('"info" requires string "title" and "version"', "/info");
+  }
+  if (!Array.isArray(doc.sourceDescriptions) || doc.sourceDescriptions.length === 0) {
+    err('"sourceDescriptions" must be a non-empty array', "/sourceDescriptions");
+  }
+  const sourceNames = /* @__PURE__ */ new Set();
+  doc.sourceDescriptions.forEach((source, index) => {
+    const sPath = `/sourceDescriptions/${index}`;
+    if (!source || typeof source !== "object" || typeof source.name !== "string" || !ID_PATTERN.test(source.name)) {
+      err('Source description requires a "name" matching [A-Za-z0-9_-]+', sPath);
+    }
+    if (typeof source.url !== "string" || source.url === "") {
+      err(`Source "${source.name}" requires a string "url"`, sPath);
+    }
+    if (source.type !== void 0 && source.type !== "openapi" && source.type !== "arazzo") {
+      err(`Source "${source.name}" has invalid type "${String(source.type)}"`, sPath);
+    }
+    if (sourceNames.has(source.name)) {
+      err(`Duplicate source description name "${source.name}"`, sPath);
+    }
+    sourceNames.add(source.name);
+  });
+  if (!Array.isArray(doc.workflows) || doc.workflows.length === 0) {
+    err('"workflows" must be a non-empty array', "/workflows");
+  }
+  const workflowIds = /* @__PURE__ */ new Set();
+  doc.workflows.forEach((workflow, wIndex) => {
+    const wPath = `/workflows/${wIndex}`;
+    if (!workflow || typeof workflow !== "object" || typeof workflow.workflowId !== "string" || !ID_PATTERN.test(workflow.workflowId)) {
+      err('Workflow requires a "workflowId" matching [A-Za-z0-9_-]+', wPath);
+    }
+    if (workflowIds.has(workflow.workflowId)) {
+      err(`Duplicate workflowId "${workflow.workflowId}"`, wPath);
+    }
+    workflowIds.add(workflow.workflowId);
+    if (!Array.isArray(workflow.steps) || workflow.steps.length === 0) {
+      err(`Workflow "${workflow.workflowId}" requires a non-empty "steps" array`, `${wPath}/steps`);
+    }
+    validateParameters(workflow.parameters, void 0, `${wPath}/parameters`);
+    validateActions(workflow.successActions, "success", `${wPath}/successActions`);
+    validateActions(workflow.failureActions, "failure", `${wPath}/failureActions`);
+    validateOutputs(workflow.outputs, `${wPath}/outputs`);
+    const stepIds = /* @__PURE__ */ new Set();
+    workflow.steps.forEach((step, sIndex) => {
+      const sPath = `${wPath}/steps/${sIndex}`;
+      if (!step || typeof step !== "object" || typeof step.stepId !== "string" || !ID_PATTERN.test(step.stepId)) {
+        err('Step requires a "stepId" matching [A-Za-z0-9_-]+', sPath);
+      }
+      if (stepIds.has(step.stepId)) {
+        err(`Duplicate stepId "${step.stepId}" in workflow "${workflow.workflowId}"`, sPath);
+      }
+      stepIds.add(step.stepId);
+      const kinds = [step.operationId, step.operationPath, step.workflowId].filter((k) => k !== void 0).length;
+      if (kinds !== 1) {
+        err(`Step "${step.stepId}" requires exactly one of "operationId", "operationPath", or "workflowId"`, sPath);
+      }
+      validateParameters(step.parameters, step.workflowId !== void 0 ? false : true, `${sPath}/parameters`);
+      validateCriteria(step.successCriteria, `${sPath}/successCriteria`);
+      validateActions(step.onSuccess, "success", `${sPath}/onSuccess`);
+      validateActions(step.onFailure, "failure", `${sPath}/onFailure`);
+      validateOutputs(step.outputs, `${sPath}/outputs`);
+    });
+  });
+}
+function ownComponent(group, name) {
+  if (!group || !Object.prototype.hasOwnProperty.call(group, name)) {
+    return void 0;
+  }
+  const value = group[name];
+  return value !== null && typeof value === "object" ? value : void 0;
+}
+function resolveReusable(entry, components, expectedGroup, path) {
+  if (!entry || typeof entry !== "object" || !("reference" in entry)) {
+    return entry;
+  }
+  const reusable = entry;
+  if (typeof reusable.reference !== "string") {
+    err('Reusable Object "reference" must be a string', path);
+  }
+  const ast = parseRuntimeExpression(reusable.reference, path);
+  if (ast.type !== "components" || ast.path.length < 2 || ast.path[0] !== expectedGroup) {
+    err(`Reference "${reusable.reference}" must point at $components.${expectedGroup}.<name>`, path);
+  }
+  const name = ast.path.slice(1).join(".");
+  const target = ownComponent(components?.[expectedGroup], name);
+  if (!target) {
+    err(`Unknown reference "$components.${expectedGroup}.${name}"`, path);
+  }
+  const resolved = JSON.parse(JSON.stringify(target));
+  if (expectedGroup === "parameters" && "value" in reusable) {
+    resolved.value = reusable.value;
+  }
+  return resolved;
+}
+function resolveInputRefs(node, components, path, seen) {
+  if (Array.isArray(node)) {
+    return node.map((item) => resolveInputRefs(item, components, path, seen));
+  }
+  if (!node || typeof node !== "object") {
+    return node;
+  }
+  const record = node;
+  const ref = record["$ref"];
+  if (typeof ref === "string") {
+    const prefix = "#/components/inputs/";
+    if (!ref.startsWith(prefix)) {
+      err(`Unsupported $ref "${ref}" in workflow inputs (only ${prefix}<name> is resolvable)`, path);
+    }
+    const name = ref.slice(prefix.length);
+    const target = ownComponent(components?.inputs, name);
+    if (!target) {
+      err(`Unknown workflow inputs reference "${ref}"`, path);
+    }
+    if (seen.has(name)) {
+      err(`Cyclic workflow inputs reference "${ref}"`, path);
+    }
+    seen.add(name);
+    const resolved = resolveInputRefs(target, components, path, seen);
+    seen.delete(name);
+    return resolved;
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(record)) {
+    out[key] = resolveInputRefs(value, components, path, seen);
+  }
+  return out;
+}
+async function prepareSources(doc, options) {
+  const declared = new Map(doc.sourceDescriptions.map((s) => [s.name, s]));
+  const generators = /* @__PURE__ */ new Map();
+  const sourceTypes = /* @__PURE__ */ new Map();
+  for (const [name, source] of Object.entries(options.sources ?? {})) {
+    if (!declared.has(name)) {
+      err(`options.sources contains "${name}", which is not a declared source description`, "/sourceDescriptions", {
+        declared: [...declared.keys()]
+      });
+    }
+    if (source instanceof OpenAPIToolGenerator) {
+      generators.set(name, source);
+    } else {
+      generators.set(name, await OpenAPIToolGenerator.fromJSON(source, options.loadOptions));
+    }
+  }
+  for (const [name, source] of declared) {
+    sourceTypes.set(name, source.type ?? "openapi");
+  }
+  const operationIndex = /* @__PURE__ */ new Map();
+  for (const [name, generator] of generators) {
+    const document = generator.getDocument();
+    for (const [pathStr, pathItem] of Object.entries(document.paths ?? {})) {
+      if (!pathItem || typeof pathItem !== "object") continue;
+      for (const method of HTTP_METHODS) {
+        const operation = pathItem[method];
+        if (!operation || typeof operation !== "object") continue;
+        const operationId = operation["operationId"];
+        if (typeof operationId !== "string") continue;
+        const hits = operationIndex.get(operationId) ?? [];
+        hits.push({ source: name, path: pathStr, method });
+        operationIndex.set(operationId, hits);
+      }
+    }
+  }
+  return { generators, operationIndex, sourceTypes };
+}
+function requireGenerator(ctx, source, path) {
+  if (ctx.sourceTypes.get(source) === "arazzo") {
+    err(`Source "${source}" has type "arazzo" \u2014 nested Arazzo sources are not supported`, path);
+  }
+  const generator = ctx.generators.get(source);
+  if (!generator) {
+    err(`No document supplied for source "${source}" (add it to options.sources)`, path, {
+      supplied: [...ctx.generators.keys()]
+    });
+  }
+  return generator;
+}
+function parseOperationPath(value, path) {
+  if (!value.startsWith("{")) {
+    err(`operationPath "${value}" must start with a "{$sourceDescriptions...}" expression`, path);
+  }
+  const close = value.indexOf("}");
+  if (close === -1) {
+    err(`operationPath "${value}" is missing "}"`, path);
+  }
+  const ast = parseRuntimeExpression(value.slice(1, close), path);
+  if (ast.type !== "sourceDescriptions" || ast.path.length !== 2 || ast.path[1] !== "url") {
+    err(`operationPath "${value}" must reference $sourceDescriptions.<name>.url`, path);
+  }
+  const source = ast.path[0];
+  const rest = value.slice(close + 1);
+  if (!rest.startsWith("#/")) {
+    err(`operationPath "${value}" requires a "#/paths/..." JSON Pointer after the source expression`, path);
+  }
+  const segments = rest.slice(2).split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+  if (segments.length !== 3 || segments[0] !== "paths") {
+    err(`operationPath pointer in "${value}" must have the shape #/paths/<path>/<method>`, path);
+  }
+  const method = segments[2].toLowerCase();
+  if (!HTTP_METHODS.includes(method)) {
+    err(`operationPath "${value}" ends in unknown HTTP method "${segments[2]}"`, path);
+  }
+  return { source, path: segments[1], method };
+}
+function resolveOperationRef(step, ctx, path) {
+  if (step.operationPath !== void 0) {
+    return parseOperationPath(step.operationPath, path);
+  }
+  const ref = step.operationId;
+  if (ref.startsWith("$")) {
+    const ast = parseRuntimeExpression(ref, path);
+    if (ast.type !== "sourceDescriptions" || ast.path.length < 2) {
+      err(`operationId expression "${ref}" must be $sourceDescriptions.<name>.<operationId>`, path);
+    }
+    const source = ast.path[0];
+    const operationId = ast.path.slice(1).join(".");
+    const hits2 = (ctx.operationIndex.get(operationId) ?? []).filter((h) => h.source === source);
+    if (hits2.length === 0) {
+      requireGenerator(ctx, source, path);
+      err(`operationId "${operationId}" not found in source "${source}"`, path);
+    }
+    if (hits2.length > 1) {
+      err(`operationId "${operationId}" is duplicated inside source "${source}"`, path, { hits: hits2 });
+    }
+    return { ...hits2[0], operationId };
+  }
+  const hits = ctx.operationIndex.get(ref) ?? [];
+  if (hits.length === 0) {
+    err(`operationId "${ref}" not found in any supplied source (${[...ctx.generators.keys()].join(", ") || "none"})`, path);
+  }
+  if (hits.length > 1) {
+    err(
+      `operationId "${ref}" is ambiguous across sources (${hits.map((h) => h.source).join(", ")}) \u2014 pin it with $sourceDescriptions.<name>.${ref}`,
+      path,
+      { hits }
+    );
+  }
+  return { ...hits[0], operationId: ref };
+}
+function checkCycles(edges, kind) {
+  const state = /* @__PURE__ */ new Map();
+  for (const start of edges.keys()) {
+    if (state.get(start) === "done") continue;
+    const stack = [{ node: start, next: 0 }];
+    state.set(start, "visiting");
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const targets = edges.get(frame.node) ?? [];
+      if (frame.next >= targets.length) {
+        state.set(frame.node, "done");
+        stack.pop();
+        continue;
+      }
+      const target = targets[frame.next++];
+      const targetState = state.get(target);
+      if (targetState === "visiting") {
+        const cycle = [...stack.map((f) => f.node), target];
+        err(`Cyclic ${kind}: ${cycle.slice(cycle.indexOf(target)).join(" -> ")}`, "/workflows");
+      }
+      if (targetState !== "done") {
+        state.set(target, "visiting");
+        stack.push({ node: target, next: 0 });
+      }
+    }
+  }
+}
+function toCriterionIR(criterion, path) {
+  const ir = {
+    condition: criterion.condition,
+    type: "simple"
+  };
+  if (criterion.context !== void 0) {
+    ir.context = parseRuntimeExpression(criterion.context, path);
+  }
+  if (typeof criterion.type === "string") {
+    ir.type = criterion.type;
+  } else if (criterion.type) {
+    ir.type = criterion.type.type;
+    ir.version = criterion.type.version;
+  }
+  return ir;
+}
+function toActionIR(action, kind, path) {
+  const failure = action;
+  return {
+    name: action.name,
+    kind,
+    type: action.type,
+    ...action.workflowId !== void 0 && { workflowId: action.workflowId },
+    ...action.stepId !== void 0 && { stepId: action.stepId },
+    ...failure.retryAfter !== void 0 && { retryAfter: failure.retryAfter },
+    ...failure.retryLimit !== void 0 && { retryLimit: failure.retryLimit },
+    ...action.criteria && { criteria: action.criteria.map((c, i) => toCriterionIR(c, `${path}/criteria/${i}`)) }
+  };
+}
+function resolveActions(actions, kind, components, path) {
+  const group = kind === "success" ? "successActions" : "failureActions";
+  return actions.map((action, index) => {
+    const aPath = `${path}/${index}`;
+    const concrete = resolveReusable(action, components, group, aPath);
+    validateActionObject(concrete, kind, aPath);
+    return toActionIR(concrete, kind, aPath);
+  });
+}
+function resolveParameters(parameters, components, requireIn, path) {
+  const seen = /* @__PURE__ */ new Set();
+  return parameters.map((parameter, index) => {
+    const pPath = `${path}/${index}`;
+    const concrete = resolveReusable(parameter, components, "parameters", pPath);
+    validateParameterObject(concrete, requireIn, pPath);
+    const key = `${concrete.name} ${concrete.in ?? ""}`;
+    if (seen.has(key)) {
+      err(`Duplicate parameter "${concrete.name}"${concrete.in ? ` (in: ${concrete.in})` : ""}`, pPath);
+    }
+    seen.add(key);
+    return {
+      name: concrete.name,
+      ...concrete.in !== void 0 && { in: concrete.in },
+      value: parseExpressionValue(concrete.value, pPath)
+    };
+  });
+}
+function parseOutputs(outputs, path) {
+  if (!outputs) return void 0;
+  const parsed = {};
+  for (const [name, expression] of Object.entries(outputs)) {
+    parsed[name] = parseRuntimeExpression(expression, `${path}/${name}`);
+  }
+  return parsed;
+}
+async function resolveStepOperation(ref, ctx, docPath) {
+  const key = `${ref.source} ${ref.method} ${ref.path}`;
+  let cached = ctx.operationCache.get(key);
+  if (!cached) {
+    const generator = requireGenerator(ctx.sources, ref.source, docPath);
+    cached = generator.generateTool(ref.path, ref.method, ctx.generateOptions).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ArazzoError(
+        `Failed to resolve ${ref.method.toUpperCase()} ${ref.path} from source "${ref.source}": ${message}`,
+        { path: docPath, source: ref.source }
+      );
+    });
+    ctx.operationCache.set(key, cached);
+  }
+  return cached;
+}
+async function buildStepIR(step, ctx, path) {
+  const components = ctx.doc.components;
+  const base = {
+    stepId: step.stepId,
+    ...step.description !== void 0 && { description: step.description },
+    ...step.parameters && {
+      parameters: resolveParameters(
+        step.parameters,
+        components,
+        step.workflowId !== void 0 ? false : true,
+        `${path}/parameters`
+      )
+    },
+    ...step.successCriteria && {
+      successCriteria: step.successCriteria.map((c, i) => toCriterionIR(c, `${path}/successCriteria/${i}`))
+    },
+    ...step.onSuccess && { onSuccess: resolveActions(step.onSuccess, "success", components, `${path}/onSuccess`) },
+    ...step.onFailure && { onFailure: resolveActions(step.onFailure, "failure", components, `${path}/onFailure`) },
+    ...step.outputs && { outputs: parseOutputs(step.outputs, `${path}/outputs`) }
+  };
+  if (step.workflowId !== void 0) {
+    if (step.requestBody !== void 0) {
+      err(`Step "${step.stepId}" invokes a workflow and must not declare a requestBody`, `${path}/requestBody`);
+    }
+    if (step.workflowId.startsWith("$")) {
+      err(`Step "${step.stepId}" invokes a workflow in another Arazzo document \u2014 nested Arazzo sources are not supported`, path);
+    }
+    if (!ctx.workflowIds.has(step.workflowId)) {
+      err(`Step "${step.stepId}" references unknown workflow "${step.workflowId}"`, path);
+    }
+    const ir2 = { kind: "workflow", workflowId: step.workflowId, ...base };
+    return ir2;
+  }
+  const ref = resolveOperationRef(step, ctx.sources, path);
+  const tool = await resolveStepOperation(ref, ctx, path);
+  const operation = {
+    inputSchema: tool.inputSchema,
+    outputSchema: tool.outputSchema,
+    mapper: tool.mapper,
+    ...tool.metadata.security && { security: tool.metadata.security },
+    ...tool.metadata.servers && { servers: tool.metadata.servers }
+  };
+  let requestBody;
+  if (step.requestBody !== void 0) {
+    if (!step.requestBody || typeof step.requestBody !== "object") {
+      err(`Step "${step.stepId}" requestBody must be an object`, `${path}/requestBody`);
+    }
+    requestBody = {
+      ...step.requestBody.contentType !== void 0 && { contentType: step.requestBody.contentType },
+      ...step.requestBody.payload !== void 0 && { payload: step.requestBody.payload }
+    };
+    const expressions = collectPayloadExpressions(step.requestBody.payload, `${path}/requestBody/payload`);
+    if (expressions.length > 0) {
+      requestBody.payloadExpressions = expressions;
+    }
+    if (step.requestBody.replacements !== void 0) {
+      if (!Array.isArray(step.requestBody.replacements)) {
+        err(`Step "${step.stepId}" requestBody.replacements must be an array`, `${path}/requestBody/replacements`);
+      }
+      requestBody.replacements = step.requestBody.replacements.map((replacement, index) => {
+        const rPath = `${path}/requestBody/replacements/${index}`;
+        if (!replacement || typeof replacement !== "object" || typeof replacement.target !== "string") {
+          err('Replacement requires a string "target"', rPath);
+        }
+        return { target: replacement.target, value: parseExpressionValue(replacement.value, rPath) };
+      });
+    }
+  }
+  const ir = {
+    kind: "operation",
+    source: ref.source,
+    path: ref.path,
+    method: ref.method,
+    ...ref.operationId !== void 0 && { operationId: ref.operationId },
+    operation,
+    ...requestBody && { requestBody },
+    ...base
+  };
+  return ir;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function walkPointer(schema, pointer) {
+  if (pointer === void 0 || pointer === "") {
+    return schema;
+  }
+  let node = schema;
+  for (const rawSegment of pointer.slice(1).split("/")) {
+    const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (!isRecord(node)) return void 0;
+    const properties = node["properties"];
+    if (isRecord(properties) && properties[segment] !== void 0) {
+      node = properties[segment];
+      continue;
+    }
+    if (/^\d+$/.test(segment) && node["items"] !== void 0 && !Array.isArray(node["items"])) {
+      node = node["items"];
+      continue;
+    }
+    return void 0;
+  }
+  return node;
+}
+function primaryResponseSchema(outputSchema) {
+  if (isRecord(outputSchema) && Array.isArray(outputSchema["oneOf"])) {
+    const variants = outputSchema["oneOf"];
+    if (variants.length > 0 && variants.every((v) => isRecord(v) && v["x-status-code"] !== void 0)) {
+      return variants[0];
+    }
+  }
+  return outputSchema;
+}
+function deriveOutputSchema(ast, steps, inputSchema, depth, stepContext) {
+  if (depth >= OUTPUT_DERIVATION_MAX_DEPTH) {
+    return {};
+  }
+  if (ast.type === "statusCode") {
+    return { type: "number" };
+  }
+  if (ast.type === "url" || ast.type === "method") {
+    return { type: "string" };
+  }
+  if (ast.type === "response") {
+    if (ast.source !== "body") {
+      return { type: "string" };
+    }
+    if (!stepContext) {
+      return {};
+    }
+    const body = primaryResponseSchema(stepContext.operation.outputSchema);
+    const target = walkPointer(body, ast.pointer);
+    return isRecord(target) ? target : {};
+  }
+  if (ast.type === "inputs") {
+    const properties = isRecord(inputSchema) ? inputSchema["properties"] : void 0;
+    const target = isRecord(properties) ? properties[ast.path.join(".")] : void 0;
+    return isRecord(target) ? target : {};
+  }
+  if (ast.type === "steps" && ast.path.length >= 3 && ast.path[1] === "outputs") {
+    const step = steps.get(ast.path[0]);
+    if (step?.kind === "operation") {
+      const stepOutput = step.outputs?.[ast.path.slice(2).join(".")];
+      if (stepOutput) {
+        return deriveOutputSchema(stepOutput, steps, inputSchema, depth + 1, step);
+      }
+    }
+    return {};
+  }
+  return {};
+}
+function deriveOutputsSchema(outputs, steps, inputSchema) {
+  if (!outputs) {
+    return void 0;
+  }
+  const stepMap = new Map(steps.map((s) => [s.stepId, s]));
+  const properties = {};
+  for (const [name, ast] of Object.entries(outputs)) {
+    const derived = deriveOutputSchema(ast, stepMap, inputSchema, 0);
+    const copied = JSON.parse(JSON.stringify(derived));
+    properties[name] = { ...copied, description: `Arazzo output: ${ast.raw}` };
+  }
+  return { type: "object", properties };
+}
+function applySchemaPipeline(schema, options, isInputRoot) {
+  const formatResolvers = {
+    ...options.resolveFormats ? BUILTIN_FORMAT_RESOLVERS : {},
+    ...options.formatResolvers
+  };
+  let resolved = Object.keys(formatResolvers).length > 0 ? resolveSchemaFormats(schema, formatResolvers) : schema;
+  resolved = SchemaBuilder.truncateDepth(resolved, Math.max(1, options.maxSchemaDepth ?? 10));
+  if (options.stripExamples) resolved = SchemaBuilder.stripExamples(resolved);
+  if (options.maxDescriptionLength !== void 0) {
+    resolved = SchemaBuilder.capDescriptions(resolved, options.maxDescriptionLength);
+  }
+  if (options.maxProperties !== void 0) {
+    if (isInputRoot) {
+      const properties = resolved.properties;
+      if (properties && typeof properties === "object") {
+        const limited = {};
+        for (const [key, value] of Object.entries(properties)) {
+          limited[key] = SchemaBuilder.limitProperties(value, options.maxProperties);
+        }
+        resolved = { ...resolved, properties: limited };
+      }
+    } else {
+      resolved = SchemaBuilder.limitProperties(resolved, options.maxProperties);
+    }
+  }
+  if (options.target) {
+    resolved = applyClientTarget(resolved, options.target);
+  }
+  return resolved;
+}
+function buildWorkflowTool(workflow, stepIRs, ctx, wPath) {
+  const options = ctx.generateOptions;
+  let inputSchema;
+  let rawInputSchema;
+  if (workflow.inputs !== void 0) {
+    const resolved = resolveInputRefs(workflow.inputs, ctx.doc.components, `${wPath}/inputs`, /* @__PURE__ */ new Set());
+    rawInputSchema = toJsonSchema(resolved);
+    inputSchema = applySchemaPipeline(rawInputSchema, options, true);
+  } else {
+    inputSchema = { type: "object", properties: {} };
+  }
+  const derivedOutput = deriveOutputsSchema(parseOutputs(workflow.outputs, `${wPath}/outputs`), stepIRs, rawInputSchema);
+  const outputSchema = derivedOutput ? applySchemaPipeline(derivedOutput, options, false) : void 0;
+  const name = normalizeToolName(workflow.workflowId, options.maxToolNameLength ?? 64, workflow.workflowId);
+  const description = workflow.summary && workflow.description ? `${workflow.summary}
+
+${workflow.description}` : workflow.summary ?? workflow.description ?? `Arazzo workflow: ${workflow.workflowId}`;
+  const operationSteps = stepIRs.filter((s) => s.kind === "operation");
+  const allReadOnly = operationSteps.length === stepIRs.length && operationSteps.every((s) => inferAnnotationsFromMethod(s.method).readOnlyHint === true);
+  const security = [];
+  const seenSecurity = /* @__PURE__ */ new Set();
+  for (const step of operationSteps) {
+    for (const requirement of step.operation.security ?? []) {
+      const key = JSON.stringify(requirement);
+      if (!seenSecurity.has(key)) {
+        seenSecurity.add(key);
+        security.push(requirement);
+      }
+    }
+  }
+  const ir = {
+    arazzoVersion: ctx.doc.arazzo,
+    workflowId: workflow.workflowId,
+    ...workflow.summary !== void 0 && { summary: workflow.summary },
+    ...workflow.description !== void 0 && { description: workflow.description },
+    ...rawInputSchema !== void 0 && { inputSchema: rawInputSchema },
+    ...workflow.dependsOn && { dependsOn: workflow.dependsOn },
+    ...workflow.parameters && {
+      parameters: resolveParameters(workflow.parameters, ctx.doc.components, void 0, `${wPath}/parameters`)
+    },
+    steps: stepIRs,
+    ...workflow.successActions && {
+      successActions: resolveActions(workflow.successActions, "success", ctx.doc.components, `${wPath}/successActions`)
+    },
+    ...workflow.failureActions && {
+      failureActions: resolveActions(workflow.failureActions, "failure", ctx.doc.components, `${wPath}/failureActions`)
+    },
+    ...workflow.outputs && { outputs: parseOutputs(workflow.outputs, `${wPath}/outputs`) }
+  };
+  const tool = {
+    name,
+    ...workflow.summary !== void 0 && { title: workflow.summary },
+    description,
+    ...allReadOnly && {
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    inputSchema,
+    outputSchema,
+    // A workflow tool has no single HTTP shape — each step's mapper lives at
+    // metadata.workflow.steps[*].operation.mapper
+    mapper: [],
+    metadata: {
+      path: `arazzo:${workflow.workflowId}`,
+      method: "post",
+      operationId: workflow.workflowId,
+      ...workflow.summary !== void 0 && { operationSummary: workflow.summary },
+      ...workflow.description !== void 0 && { operationDescription: workflow.description },
+      ...security.length > 0 && { security },
+      workflow: ir
+    }
+  };
+  if (options.emitTypeSignatures) {
+    tool.metadata.typescript = emitToolTypeScript(name, description, inputSchema, outputSchema, {
+      maxDepth: Math.max(1, options.maxSchemaDepth ?? 10)
+    });
+  }
+  return tool;
+}
+async function fromArazzo(document, options) {
+  const doc = parseArazzoInput(document);
+  validateDocument(doc);
+  const sources = await prepareSources(doc, options);
+  const workflowIds = new Set(doc.workflows.map((w) => w.workflowId));
+  const dependsEdges = /* @__PURE__ */ new Map();
+  const nestedEdges = /* @__PURE__ */ new Map();
+  const declaredSources = new Set(doc.sourceDescriptions.map((s) => s.name));
+  doc.workflows.forEach((workflow, index) => {
+    if (workflow.dependsOn !== void 0 && !Array.isArray(workflow.dependsOn)) {
+      err(`Workflow "${workflow.workflowId}" dependsOn must be an array of workflowIds`, `/workflows/${index}/dependsOn`);
+    }
+    const localTargets = [];
+    for (const target of workflow.dependsOn ?? []) {
+      if (typeof target !== "string") {
+        err(`Workflow "${workflow.workflowId}" dependsOn entries must be strings`, `/workflows/${index}/dependsOn`);
+      }
+      if (target.startsWith("$")) {
+        const ast = parseRuntimeExpression(target, `/workflows/${index}/dependsOn`);
+        if (ast.type !== "sourceDescriptions" || ast.path.length < 2 || !declaredSources.has(ast.path[0])) {
+          err(
+            `Workflow "${workflow.workflowId}" dependsOn "${target}" must reference a declared source ($sourceDescriptions.<name>.<workflowId>)`,
+            `/workflows/${index}/dependsOn`
+          );
+        }
+        continue;
+      }
+      if (!workflowIds.has(target)) {
+        err(`Workflow "${workflow.workflowId}" dependsOn unknown workflow "${target}"`, `/workflows/${index}/dependsOn`);
+      }
+      localTargets.push(target);
+    }
+    dependsEdges.set(workflow.workflowId, localTargets);
+    nestedEdges.set(
+      workflow.workflowId,
+      workflow.steps.filter((s) => s.workflowId !== void 0 && !s.workflowId.startsWith("$")).map((s) => s.workflowId)
+    );
+  });
+  checkCycles(dependsEdges, "dependsOn chain");
+  checkCycles(nestedEdges, "workflow invocation");
+  const ctx = {
+    doc,
+    sources,
+    generateOptions: options.generateOptions ?? {},
+    workflowIds,
+    operationCache: /* @__PURE__ */ new Map()
+  };
+  const tools = [];
+  const usedNames = /* @__PURE__ */ new Set();
+  for (let wIndex = 0; wIndex < doc.workflows.length; wIndex++) {
+    const workflow = doc.workflows[wIndex];
+    const wPath = `/workflows/${wIndex}`;
+    const stepIRs = [];
+    for (let sIndex = 0; sIndex < workflow.steps.length; sIndex++) {
+      stepIRs.push(await buildStepIR(workflow.steps[sIndex], ctx, `${wPath}/steps/${sIndex}`));
+    }
+    let tool = buildWorkflowTool(workflow, stepIRs, ctx, wPath);
+    if (usedNames.has(tool.name)) {
+      const maxLength = ctx.generateOptions.maxToolNameLength ?? 64;
+      let seed = workflow.workflowId;
+      let deduped = normalizeToolName(`${tool.name}_${fnv1aHex(seed)}`, maxLength, seed);
+      while (usedNames.has(deduped)) {
+        seed += "#";
+        deduped = normalizeToolName(`${tool.name}_${fnv1aHex(seed)}`, maxLength, seed);
+      }
+      tool = { ...tool, name: deduped };
+    }
+    usedNames.add(tool.name);
+    tools.push(tool);
+  }
+  return tools;
+}
+
 // src/request-builder.ts
 var RESERVED_DECODE = {
   "%3A": ":",
@@ -3177,7 +5713,7 @@ function buildHttpRequest(tool, input, options = {}) {
       case "body":
         hasBody = true;
         contentType = contentType ?? mapper.serialization?.contentType ?? "application/json";
-        if (mapper.serialization?.binary) binaryBody = true;
+        if (mapper.serialization?.binary && mapper.wholeBody) binaryBody = true;
         if (mapper.wholeBody) {
           rawBody = value;
         } else {
@@ -3274,25 +5810,67 @@ function buildHttpRequest(tool, input, options = {}) {
 // src/sdk.ts
 function toSdkTool(tool, wrapper) {
   const wrapSchema = wrapper?.fromJsonSchema ?? ((schema) => schema);
+  const outputSchema = tool.outputSchema !== void 0 && tool.outputSchema["type"] === "object" ? tool.outputSchema : void 0;
   return [
     tool.name,
     {
       ...tool.title !== void 0 && { title: tool.title },
       description: tool.description,
       inputSchema: wrapSchema(tool.inputSchema),
-      ...tool.outputSchema !== void 0 && { outputSchema: wrapSchema(tool.outputSchema) },
+      ...outputSchema !== void 0 && { outputSchema: wrapSchema(outputSchema) },
       ...tool.annotations !== void 0 && { annotations: tool.annotations }
     }
   ];
 }
+
+// src/token-report.ts
+function estimateToolTokens(tool) {
+  const advertised = {
+    name: tool.name,
+    ...tool.title !== void 0 && { title: tool.title },
+    description: tool.description,
+    ...tool.annotations !== void 0 && { annotations: tool.annotations },
+    inputSchema: tool.inputSchema,
+    ...tool.outputSchema !== void 0 && { outputSchema: tool.outputSchema }
+  };
+  return Math.ceil(JSON.stringify(advertised).length / 4);
+}
+function analyzeToolSet(tools, options = {}) {
+  const tokenBudget = options.tokenBudget ?? 1e4;
+  const maxRecommendedTools = options.maxRecommendedTools ?? 40;
+  const perToolWarning = options.perToolWarning ?? 2e3;
+  const perTool = tools.map((tool) => ({ name: tool.name, tokens: estimateToolTokens(tool) })).sort((a, b) => b.tokens - a.tokens || (a.name < b.name ? -1 : 1));
+  const estimatedTokens = perTool.reduce((sum, entry) => sum + entry.tokens, 0);
+  const warnings = [];
+  if (tools.length > maxRecommendedTools) {
+    warnings.push(
+      `${tools.length} tools exceeds the ~${maxRecommendedTools}-tool range where model selection accuracy degrades \u2014 curate with filters (tags, paths, readOnlyOnly) or split into focused servers.`
+    );
+  }
+  if (estimatedTokens > tokenBudget) {
+    warnings.push(
+      `Estimated ${estimatedTokens} tokens of tool definitions exceeds the ${tokenBudget}-token budget \u2014 trim schemas (maxSchemaDepth, maxProperties) or reduce the tool count.`
+    );
+  }
+  const heavy = perTool.filter((entry) => entry.tokens > perToolWarning);
+  if (heavy.length > 0) {
+    warnings.push(
+      `${heavy.length} tool(s) exceed ${perToolWarning} tokens each (${heavy.slice(0, 3).map((entry) => `${entry.name}: ~${entry.tokens}`).join(", ")}${heavy.length > 3 ? ", \u2026" : ""}) \u2014 consider schema trimming for these.`
+    );
+  }
+  return { toolCount: tools.length, estimatedTokens, perTool, warnings };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ArazzoError,
   BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS,
+  CODECALL_RESERVED_NAMESPACES,
   GenerationError,
   LoadError,
   OpenAPIToolError,
   OpenAPIToolGenerator,
+  OverlayError,
   ParameterResolver,
   ParseError,
   RequestBuildError,
@@ -3303,7 +5881,9 @@ function toSdkTool(tool, wrapper) {
   SsrfError,
   ValidationError,
   Validator,
+  analyzeToolSet,
   applyClientTarget,
+  applyOverlay,
   assertUrlSafe,
   buildHttpRequest,
   collapseNestedUnions,
@@ -3312,19 +5892,27 @@ function toSdkTool(tool, wrapper) {
   decodeIpv4MappedIpv6,
   defaultLookup,
   demoteFormats,
+  deriveSecurityElicitations,
+  dottedNaming,
+  emitToolTypeScript,
   enforceClosedObjects,
   ensureArrayItems,
+  estimateToolTokens,
   extractExtensionOverrides,
+  fromArazzo,
   inferAnnotationsFromMethod,
   inlineLocalRefs,
   isBlockedAddress,
   isBlockedHostname,
   isReferenceObject,
+  lintDocument,
   normalizeSsrfOptions,
+  parseRuntimeExpression,
   requireAllProperties,
   resolveExtensionEnabled,
   resolveSchemaFormats,
   safeFetch,
   toJsonSchema,
+  toPascalIdentifier,
   toSdkTool
 });