mcp-from-openapi 2.6.1 → 2.7.0

package/esm/index.mjs

@@ -6,9 +6,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 };
@@ -60,34 +75,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;
     }
@@ -104,11 +119,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 = {};
@@ -129,8 +144,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;
   }
@@ -312,6 +330,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;
     }
@@ -406,6 +427,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);
       }
@@ -1078,9 +1102,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"];
 }
@@ -1129,16 +1207,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;
 }
@@ -1509,6 +1595,13 @@ var RequestBuildError = class extends OpenAPIToolError {
     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);
@@ -2061,7 +2154,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({
@@ -2092,7 +2186,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("/")) {
@@ -2104,11 +2209,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) {
@@ -2123,7 +2232,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({
@@ -2140,14 +2249,18 @@ var Validator = class {
       });
     }
     if (operation.parameters) {
-      this.validateParameters(operation.parameters, path, method, errors, warnings);
+      this.validateParameters(operation.parameters, `${basePath}/parameters`, errors, warnings);
     }
+    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`,
@@ -2159,11 +2272,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",
@@ -2311,6 +2426,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",
@@ -2719,6 +3204,25 @@ 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;
@@ -3101,6 +3605,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);
@@ -3149,7 +3661,13 @@ 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 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;
@@ -3214,11 +3732,48 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
 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: finalDescription,
       ...annotations && { annotations },
+      ...toolMeta && { _meta: toolMeta },
+      ...icons && { icons },
       inputSchema: resolvedInputSchema,
       outputSchema: resolvedOutputSchema,
       mapper,
@@ -3286,10 +3841,10 @@ Returns: ${summary}`;
   /**
    * 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 {
@@ -3627,6 +4182,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
+import * as yaml2 from "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": ":",
@@ -3863,7 +5625,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 {
@@ -3960,13 +5722,14 @@ 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 }
     }
   ];
@@ -4010,8 +5773,10 @@ function analyzeToolSet(tools, options = {}) {
   return { toolCount: tools.length, estimatedTokens, perTool, warnings };
 }
 export {
+  ArazzoError,
   BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS,
+  CODECALL_RESERVED_NAMESPACES,
   GenerationError,
   LoadError,
   OpenAPIToolError,
@@ -4038,10 +5803,14 @@ export {
   decodeIpv4MappedIpv6,
   defaultLookup,
   demoteFormats,
+  deriveSecurityElicitations,
+  dottedNaming,
+  emitToolTypeScript,
   enforceClosedObjects,
   ensureArrayItems,
   estimateToolTokens,
   extractExtensionOverrides,
+  fromArazzo,
   inferAnnotationsFromMethod,
   inlineLocalRefs,
   isBlockedAddress,
@@ -4049,10 +5818,12 @@ export {
   isReferenceObject,
   lintDocument,
   normalizeSsrfOptions,
+  parseRuntimeExpression,
   requireAllProperties,
   resolveExtensionEnabled,
   resolveSchemaFormats,
   safeFetch,
   toJsonSchema,
+  toPascalIdentifier,
   toSdkTool
 };