@agentcash/discovery 0.1.1 → 0.1.3

package/dist/index.js

@@ -12,7 +12,7 @@ var STRICT_ESCALATION_CODES = [
 ];
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "0.1.1".includes("-mmm");
+var isMmmEnabled = () => "0.1.3".includes("-mmm");
 
 // src/core/constants.ts
 var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];
@@ -1400,6 +1400,861 @@ async function runDiscovery({
   };
 }
 
+// src/validation/codes.ts
+var VALIDATION_CODES = {
+  COINBASE_SCHEMA_INVALID: "COINBASE_SCHEMA_INVALID",
+  X402_NOT_OBJECT: "X402_NOT_OBJECT",
+  X402_VERSION_MISSING: "X402_VERSION_MISSING",
+  X402_VERSION_UNSUPPORTED: "X402_VERSION_UNSUPPORTED",
+  X402_ACCEPTS_MISSING: "X402_ACCEPTS_MISSING",
+  X402_ACCEPTS_INVALID: "X402_ACCEPTS_INVALID",
+  X402_ACCEPTS_EMPTY: "X402_ACCEPTS_EMPTY",
+  X402_ACCEPT_ENTRY_INVALID: "X402_ACCEPT_ENTRY_INVALID",
+  NETWORK_CAIP2_INVALID: "NETWORK_CAIP2_INVALID",
+  NETWORK_EIP155_REFERENCE_INVALID: "NETWORK_EIP155_REFERENCE_INVALID",
+  NETWORK_SOLANA_ALIAS_INVALID: "NETWORK_SOLANA_ALIAS_INVALID",
+  NETWORK_SOLANA_ALIAS_COMPAT: "NETWORK_SOLANA_ALIAS_COMPAT",
+  NETWORK_REFERENCE_UNKNOWN: "NETWORK_REFERENCE_UNKNOWN",
+  SCHEMA_INPUT_MISSING: "SCHEMA_INPUT_MISSING",
+  SCHEMA_OUTPUT_MISSING: "SCHEMA_OUTPUT_MISSING",
+  METADATA_TITLE_MISSING: "METADATA_TITLE_MISSING",
+  METADATA_DESCRIPTION_MISSING: "METADATA_DESCRIPTION_MISSING",
+  METADATA_FAVICON_MISSING: "METADATA_FAVICON_MISSING",
+  METADATA_OG_IMAGE_MISSING: "METADATA_OG_IMAGE_MISSING"
+};
+
+// src/validation/metadata.ts
+function hasText(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function hasOgImage(metadata) {
+  const images = metadata.ogImages;
+  if (!Array.isArray(images) || images.length === 0) return false;
+  return images.some((entry) => {
+    if (typeof entry === "string") {
+      return entry.trim().length > 0;
+    }
+    if (!entry || typeof entry !== "object") return false;
+    return hasText(entry.url);
+  });
+}
+function evaluateMetadataCompleteness(metadata) {
+  const issues = [];
+  if (!hasText(metadata.title)) {
+    issues.push({
+      code: VALIDATION_CODES.METADATA_TITLE_MISSING,
+      severity: "warn",
+      message: "Metadata title is missing",
+      hint: "Provide a page title to improve discovery quality and UX.",
+      path: "metadata.title",
+      stage: "metadata"
+    });
+  }
+  if (!hasText(metadata.description)) {
+    issues.push({
+      code: VALIDATION_CODES.METADATA_DESCRIPTION_MISSING,
+      severity: "warn",
+      message: "Metadata description is missing",
+      hint: "Provide a concise description for integrators and search previews.",
+      path: "metadata.description",
+      stage: "metadata"
+    });
+  }
+  if (!hasText(metadata.favicon)) {
+    issues.push({
+      code: VALIDATION_CODES.METADATA_FAVICON_MISSING,
+      severity: "warn",
+      message: "Metadata favicon is missing",
+      hint: "Expose a favicon URL for stronger brand attribution.",
+      path: "metadata.favicon",
+      stage: "metadata"
+    });
+  }
+  if (!hasOgImage(metadata)) {
+    issues.push({
+      code: VALIDATION_CODES.METADATA_OG_IMAGE_MISSING,
+      severity: "warn",
+      message: "Metadata OG image is missing",
+      hint: "Provide an Open Graph image to improve sharing previews.",
+      path: "metadata.ogImages",
+      stage: "metadata"
+    });
+  }
+  return issues;
+}
+
+// src/validation/payment-required.ts
+import { parsePaymentRequired } from "@x402/core/schemas";
+var SOLANA_CANONICAL_BY_REF = {
+  "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "solana",
+  EtWTRABZaYq6iMfeYKouRu166VU2xqa1: "solana-devnet",
+  "4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z": "solana-testnet"
+};
+var SOLANA_ALIAS_BY_REF = {
+  mainnet: "solana",
+  devnet: "solana-devnet",
+  testnet: "solana-testnet"
+};
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function asPositiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function pushIssue(issues, issue) {
+  issues.push({
+    stage: issue.stage ?? "payment_required",
+    ...issue
+  });
+}
+function summarizeIssues(issues) {
+  const summary = {
+    errorCount: 0,
+    warnCount: 0,
+    infoCount: 0,
+    byCode: {}
+  };
+  for (const issue of issues) {
+    if (issue.severity === "error") summary.errorCount += 1;
+    else if (issue.severity === "warn") summary.warnCount += 1;
+    else summary.infoCount += 1;
+    summary.byCode[issue.code] = (summary.byCode[issue.code] ?? 0) + 1;
+  }
+  return summary;
+}
+function outputSchemaMissingSeverity(compatMode) {
+  return compatMode === "strict" ? "error" : "warn";
+}
+function zodPathToString(path) {
+  if (path.length === 0) return "$";
+  let out = "";
+  for (const segment of path) {
+    if (typeof segment === "number") out += `[${segment}]`;
+    else out += out.length === 0 ? segment : `.${segment}`;
+  }
+  return out;
+}
+function parseWithCoinbaseStructuralGate(payload, issues) {
+  const baseParsed = parsePaymentRequired(payload);
+  if (baseParsed.success) {
+    return baseParsed.data;
+  }
+  for (const issue of baseParsed.error.issues) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.COINBASE_SCHEMA_INVALID,
+      severity: "error",
+      message: `Coinbase schema validation failed: ${issue.message}`,
+      path: zodPathToString(issue.path),
+      actual: issue.code
+    });
+  }
+  return void 0;
+}
+function validateV2Network(networkRaw, index, issues) {
+  if (!/^[^:\s]+:[^:\s]+$/.test(networkRaw)) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.NETWORK_CAIP2_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} has invalid CAIP-2 network format`,
+      hint: "Expected '<namespace>:<reference>', e.g. 'eip155:8453' or 'solana:5eykt4...'.",
+      path: `accepts[${index}].network`,
+      expected: "<namespace>:<reference>",
+      actual: networkRaw
+    });
+    return void 0;
+  }
+  const [namespace, reference] = networkRaw.split(":");
+  if (namespace === "eip155") {
+    if (!/^\d+$/.test(reference)) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.NETWORK_EIP155_REFERENCE_INVALID,
+        severity: "error",
+        message: `Accept at index ${index} has invalid eip155 reference`,
+        hint: "Use a numeric chain id, e.g. 'eip155:8453'.",
+        path: `accepts[${index}].network`,
+        expected: "eip155:<numeric-chain-id>",
+        actual: networkRaw
+      });
+      return void 0;
+    }
+    return networkRaw;
+  }
+  if (namespace === "solana") {
+    const canonical = SOLANA_CANONICAL_BY_REF[reference];
+    if (canonical) return canonical;
+    const alias = SOLANA_ALIAS_BY_REF[reference];
+    if (alias) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.NETWORK_SOLANA_ALIAS_COMPAT,
+        severity: "warn",
+        message: `Accept at index ${index} uses compatibility Solana reference '${reference}'`,
+        hint: "Use canonical Solana CAIP references for deterministic behavior.",
+        path: `accepts[${index}].network`,
+        actual: networkRaw
+      });
+      return alias;
+    }
+    pushIssue(issues, {
+      code: VALIDATION_CODES.NETWORK_REFERENCE_UNKNOWN,
+      severity: "error",
+      message: `Accept at index ${index} uses unknown Solana reference '${reference}'`,
+      hint: "Use canonical references for mainnet/devnet/testnet.",
+      path: `accepts[${index}].network`,
+      actual: networkRaw
+    });
+    return void 0;
+  }
+  return networkRaw;
+}
+function validateV1Network(networkRaw, index, issues) {
+  if (networkRaw === "solana-mainnet-beta") {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.NETWORK_SOLANA_ALIAS_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} uses invalid Solana network alias`,
+      hint: "Use 'solana' (v1) or canonical Solana CAIP reference (v2).",
+      path: `accepts[${index}].network`,
+      expected: "solana",
+      actual: networkRaw
+    });
+    return void 0;
+  }
+  if (networkRaw.startsWith("solana-") && networkRaw !== "solana-devnet") {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.NETWORK_SOLANA_ALIAS_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} uses unsupported Solana network alias`,
+      hint: "Use 'solana' or 'solana-devnet' for v1 payloads.",
+      path: `accepts[${index}].network`,
+      actual: networkRaw
+    });
+    return void 0;
+  }
+  if (networkRaw.includes(":")) {
+    return validateV2Network(networkRaw, index, issues);
+  }
+  return networkRaw;
+}
+function validateAccept(acceptRaw, index, version, issues) {
+  if (!isRecord4(acceptRaw)) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} must be an object`,
+      path: `accepts[${index}]`
+    });
+    return null;
+  }
+  const scheme = asNonEmptyString(acceptRaw.scheme);
+  const networkRaw = asNonEmptyString(acceptRaw.network);
+  const payTo = asNonEmptyString(acceptRaw.payTo);
+  const asset = asNonEmptyString(acceptRaw.asset);
+  const maxTimeoutSeconds = asPositiveNumber(acceptRaw.maxTimeoutSeconds);
+  const amount = version === 2 ? asNonEmptyString(acceptRaw.amount) : asNonEmptyString(acceptRaw.maxAmountRequired);
+  if (!scheme) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing scheme`,
+      path: `accepts[${index}].scheme`
+    });
+  }
+  if (!networkRaw) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing network`,
+      path: `accepts[${index}].network`
+    });
+  }
+  if (!amount) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing ${version === 2 ? "amount" : "maxAmountRequired"}`,
+      path: `accepts[${index}].${version === 2 ? "amount" : "maxAmountRequired"}`
+    });
+  }
+  if (!payTo) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing payTo`,
+      path: `accepts[${index}].payTo`
+    });
+  }
+  if (!asset) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing asset`,
+      path: `accepts[${index}].asset`
+    });
+  }
+  if (!maxTimeoutSeconds) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing or has invalid maxTimeoutSeconds`,
+      path: `accepts[${index}].maxTimeoutSeconds`
+    });
+  }
+  let normalizedNetwork;
+  if (networkRaw) {
+    normalizedNetwork = version === 2 ? validateV2Network(networkRaw, index, issues) : validateV1Network(networkRaw, index, issues);
+  }
+  return {
+    index,
+    network: normalizedNetwork ?? networkRaw ?? "unknown",
+    networkRaw: networkRaw ?? "unknown",
+    scheme,
+    asset,
+    payTo,
+    amount,
+    maxTimeoutSeconds
+  };
+}
+function getSchemaPresence(payload, accepts, version) {
+  if (version === 1) {
+    const first = accepts[0];
+    if (!isRecord4(first)) {
+      return { hasInputSchema: false, hasOutputSchema: false };
+    }
+    const outputSchema = isRecord4(first.outputSchema) ? first.outputSchema : void 0;
+    return {
+      hasInputSchema: outputSchema?.input !== void 0 && outputSchema.input !== null,
+      hasOutputSchema: outputSchema?.output !== void 0 && outputSchema.output !== null
+    };
+  }
+  const extensions = isRecord4(payload.extensions) ? payload.extensions : void 0;
+  const bazaar = extensions && isRecord4(extensions.bazaar) ? extensions.bazaar : void 0;
+  const info = bazaar && isRecord4(bazaar.info) ? bazaar.info : void 0;
+  return {
+    hasInputSchema: info?.input !== void 0 && info.input !== null,
+    hasOutputSchema: info?.output !== void 0 && info.output !== null
+  };
+}
+function validatePaymentRequiredDetailed(payload, options = {}) {
+  const issues = [];
+  const compatMode = options.compatMode ?? DEFAULT_COMPAT_MODE;
+  const requireInputSchema = options.requireInputSchema ?? true;
+  const requireOutputSchema = options.requireOutputSchema ?? true;
+  if (!isRecord4(payload)) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_NOT_OBJECT,
+      severity: "error",
+      message: "Payment required payload must be a JSON object",
+      path: "$"
+    });
+    if (options.metadata) {
+      issues.push(...evaluateMetadataCompleteness(options.metadata));
+    }
+    return {
+      valid: false,
+      issues,
+      summary: summarizeIssues(issues)
+    };
+  }
+  const coinbaseParsed = parseWithCoinbaseStructuralGate(payload, issues);
+  const versionRaw = payload.x402Version;
+  let version;
+  if (versionRaw === 1 || versionRaw === 2) {
+    version = versionRaw;
+  } else if (versionRaw === void 0) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_VERSION_MISSING,
+      severity: "error",
+      message: "x402Version is required",
+      path: "x402Version"
+    });
+  } else {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_VERSION_UNSUPPORTED,
+      severity: "error",
+      message: `Unsupported x402Version '${String(versionRaw)}'`,
+      path: "x402Version",
+      expected: "1 | 2",
+      actual: String(versionRaw)
+    });
+  }
+  const acceptsRaw = payload.accepts;
+  let accepts = [];
+  if (acceptsRaw === void 0) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPTS_MISSING,
+      severity: "error",
+      message: "accepts is required",
+      path: "accepts"
+    });
+  } else if (!Array.isArray(acceptsRaw)) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPTS_INVALID,
+      severity: "error",
+      message: "accepts must be an array",
+      path: "accepts"
+    });
+  } else {
+    accepts = acceptsRaw;
+    if (accepts.length === 0) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.X402_ACCEPTS_EMPTY,
+        severity: "error",
+        message: "accepts must contain at least one payment requirement",
+        path: "accepts"
+      });
+    }
+  }
+  const normalizedAccepts = [];
+  if (version && Array.isArray(accepts)) {
+    accepts.forEach((accept, index) => {
+      const normalized = validateAccept(accept, index, version, issues);
+      if (normalized) normalizedAccepts.push(normalized);
+    });
+    const schemaPresence = getSchemaPresence(payload, accepts, version);
+    if (requireInputSchema && !schemaPresence.hasInputSchema) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.SCHEMA_INPUT_MISSING,
+        severity: "error",
+        message: "Input schema is missing",
+        hint: "Include input schema details so clients can invoke the endpoint correctly.",
+        path: version === 1 ? "accepts[0].outputSchema.input" : "extensions.bazaar.info.input"
+      });
+    }
+    if (requireOutputSchema && !schemaPresence.hasOutputSchema) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.SCHEMA_OUTPUT_MISSING,
+        severity: outputSchemaMissingSeverity(compatMode),
+        message: "Output schema is missing",
+        hint: "Include output schema details so clients can validate responses.",
+        path: version === 1 ? "accepts[0].outputSchema.output" : "extensions.bazaar.info.output"
+      });
+    }
+    if (options.metadata) {
+      issues.push(...evaluateMetadataCompleteness(options.metadata));
+    }
+    const summary2 = summarizeIssues(issues);
+    return {
+      valid: summary2.errorCount === 0,
+      version,
+      parsed: coinbaseParsed ?? payload,
+      normalized: {
+        version,
+        accepts: normalizedAccepts,
+        hasInputSchema: schemaPresence.hasInputSchema,
+        hasOutputSchema: schemaPresence.hasOutputSchema
+      },
+      issues,
+      summary: summary2
+    };
+  }
+  if (options.metadata) {
+    issues.push(...evaluateMetadataCompleteness(options.metadata));
+  }
+  const summary = summarizeIssues(issues);
+  return {
+    valid: summary.errorCount === 0,
+    version,
+    parsed: coinbaseParsed ?? payload,
+    issues,
+    summary
+  };
+}
+
+// src/adapters/mcp.ts
+var DEFAULT_GUIDANCE_AUTO_INCLUDE_MAX_TOKENS = 1e3;
+var OPENAPI_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+  "TRACE"
+];
+function isRecord5(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function toFiniteNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return void 0;
+}
+function formatPriceHintFromResource(resource) {
+  const pricing = resource.pricing;
+  if (pricing) {
+    if (pricing.pricingMode === "fixed" && pricing.price) {
+      return pricing.price.startsWith("$") ? pricing.price : `$${pricing.price}`;
+    }
+    if (pricing.pricingMode === "range" && pricing.minPrice && pricing.maxPrice) {
+      const min = pricing.minPrice.startsWith("$") ? pricing.minPrice : `$${pricing.minPrice}`;
+      const max = pricing.maxPrice.startsWith("$") ? pricing.maxPrice : `$${pricing.maxPrice}`;
+      return `${min}-${max}`;
+    }
+  }
+  if (!resource.priceHint) return void 0;
+  const hint = resource.priceHint.trim();
+  if (hint.length === 0) return void 0;
+  if (hint.startsWith("$")) return hint;
+  if (hint.includes("-")) {
+    const [min, max] = hint.split("-", 2).map((part) => part.trim());
+    if (min && max) return `$${min}-$${max}`;
+  }
+  return `$${hint}`;
+}
+function deriveMcpAuthMode(resource) {
+  if (!resource) return void 0;
+  const hint = resource.authHint;
+  if (hint === "paid" || hint === "siwx" || hint === "apiKey" || hint === "unprotected") {
+    return hint;
+  }
+  return void 0;
+}
+function inferFailureCause(warnings) {
+  const openapiWarnings = warnings.filter((w) => w.stage === "openapi");
+  const parseWarning = openapiWarnings.find(
+    (w) => w.code === "PARSE_FAILED" || w.code === "OPENAPI_TOP_LEVEL_INVALID" || w.code === "OPENAPI_OPERATION_INVALID" || w.code === "OPENAPI_PRICING_INVALID"
+  );
+  if (parseWarning) {
+    return { cause: "parse", message: parseWarning.message };
+  }
+  const fetchWarning = openapiWarnings.find((w) => w.code === "FETCH_FAILED");
+  if (fetchWarning) {
+    const msg = fetchWarning.message.toLowerCase();
+    if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("abort")) {
+      return { cause: "timeout", message: fetchWarning.message };
+    }
+    return { cause: "network", message: fetchWarning.message };
+  }
+  return { cause: "not_found" };
+}
+function getOpenApiInfo(document) {
+  if (!isRecord5(document) || !isRecord5(document.info)) return void 0;
+  if (typeof document.info.title !== "string") return void 0;
+  return {
+    title: document.info.title,
+    ...typeof document.info.version === "string" ? { version: document.info.version } : {},
+    ...typeof document.info.description === "string" ? { description: document.info.description } : {}
+  };
+}
+function getGuidanceUrl(result) {
+  const fromTrace = result.trace.find((entry) => entry.links?.llmsTxtUrl)?.links?.llmsTxtUrl;
+  if (fromTrace) return fromTrace;
+  const fromResource = result.resources.find((resource) => resource.links?.llmsTxtUrl)?.links?.llmsTxtUrl;
+  if (fromResource) return fromResource;
+  return void 0;
+}
+async function resolveGuidance(options) {
+  let guidanceText = typeof options.result.rawSources?.llmsTxt === "string" ? options.result.rawSources.llmsTxt : void 0;
+  if (!guidanceText) {
+    const guidanceUrl = getGuidanceUrl(options.result) ?? `${options.result.origin}/llms.txt`;
+    const fetcher = options.fetcher ?? fetch;
+    try {
+      const response = await fetcher(guidanceUrl, {
+        method: "GET",
+        headers: { Accept: "text/plain", ...options.headers },
+        signal: options.signal
+      });
+      if (response.ok) guidanceText = await response.text();
+    } catch {
+    }
+  }
+  if (!guidanceText) {
+    return { guidanceAvailable: false };
+  }
+  const guidanceTokens = estimateTokenCount(guidanceText);
+  const threshold = options.guidanceAutoIncludeMaxTokens ?? DEFAULT_GUIDANCE_AUTO_INCLUDE_MAX_TOKENS;
+  const shouldInclude = options.includeGuidance === true || options.includeGuidance == null && guidanceTokens <= threshold;
+  return {
+    guidanceAvailable: true,
+    guidanceTokens,
+    ...shouldInclude ? { guidance: guidanceText } : {}
+  };
+}
+function extractPathsDocument(document) {
+  if (!isRecord5(document)) return void 0;
+  if (!isRecord5(document.paths)) return void 0;
+  return document.paths;
+}
+function findMatchingOpenApiPath(paths, targetPath) {
+  const exact = paths[targetPath];
+  if (isRecord5(exact)) return { matchedPath: targetPath, pathItem: exact };
+  for (const [specPath, entry] of Object.entries(paths)) {
+    if (!isRecord5(entry)) continue;
+    const pattern = specPath.replace(/\{[^}]+\}/g, "[^/]+");
+    const regex = new RegExp(`^${pattern}$`);
+    if (regex.test(targetPath)) {
+      return { matchedPath: specPath, pathItem: entry };
+    }
+  }
+  return null;
+}
+function resolveRef(document, ref, seen) {
+  if (!ref.startsWith("#/")) return void 0;
+  if (seen.has(ref)) return { $circular: ref };
+  seen.add(ref);
+  const parts = ref.slice(2).split("/");
+  let current = document;
+  for (const part of parts) {
+    if (!isRecord5(current)) return void 0;
+    current = current[part];
+    if (current === void 0) return void 0;
+  }
+  if (isRecord5(current)) return resolveRefs(document, current, seen);
+  return current;
+}
+function resolveRefs(document, obj, seen, depth = 0) {
+  if (depth > 4) return obj;
+  const resolved = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "$ref" && typeof value === "string") {
+      const deref = resolveRef(document, value, seen);
+      if (isRecord5(deref)) {
+        Object.assign(resolved, deref);
+      } else {
+        resolved[key] = value;
+      }
+      continue;
+    }
+    if (isRecord5(value)) {
+      resolved[key] = resolveRefs(document, value, seen, depth + 1);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      resolved[key] = value.map(
+        (item) => isRecord5(item) ? resolveRefs(document, item, seen, depth + 1) : item
+      );
+      continue;
+    }
+    resolved[key] = value;
+  }
+  return resolved;
+}
+function extractRequestBodySchema(operationSchema) {
+  const requestBody = operationSchema.requestBody;
+  if (!isRecord5(requestBody)) return void 0;
+  const content = requestBody.content;
+  if (!isRecord5(content)) return void 0;
+  const jsonMediaType = content["application/json"];
+  if (isRecord5(jsonMediaType) && isRecord5(jsonMediaType.schema)) {
+    return jsonMediaType.schema;
+  }
+  for (const mediaType of Object.values(content)) {
+    if (isRecord5(mediaType) && isRecord5(mediaType.schema)) {
+      return mediaType.schema;
+    }
+  }
+  return void 0;
+}
+function extractParameters(operationSchema) {
+  const params = operationSchema.parameters;
+  if (!Array.isArray(params)) return [];
+  return params.filter((value) => isRecord5(value));
+}
+function extractInputSchema(operationSchema) {
+  const requestBody = extractRequestBodySchema(operationSchema);
+  const parameters = extractParameters(operationSchema);
+  if (!requestBody && parameters.length === 0) return void 0;
+  if (requestBody && parameters.length === 0) return requestBody;
+  return {
+    ...requestBody ? { requestBody } : {},
+    ...parameters.length > 0 ? { parameters } : {}
+  };
+}
+function parseOperationPrice(operation) {
+  const paymentInfo = operation["x-payment-info"];
+  if (!isRecord5(paymentInfo)) return void 0;
+  const fixed = toFiniteNumber(paymentInfo.price);
+  if (fixed != null) return `$${String(fixed)}`;
+  const min = toFiniteNumber(paymentInfo.minPrice);
+  const max = toFiniteNumber(paymentInfo.maxPrice);
+  if (min != null && max != null) return `$${String(min)}-$${String(max)}`;
+  return void 0;
+}
+function parseOperationProtocols(operation) {
+  const paymentInfo = operation["x-payment-info"];
+  if (!isRecord5(paymentInfo) || !Array.isArray(paymentInfo.protocols)) return void 0;
+  const protocols = paymentInfo.protocols.filter(
+    (protocol) => typeof protocol === "string" && protocol.length > 0
+  );
+  return protocols.length > 0 ? protocols : void 0;
+}
+function parseOperationAuthMode(operation) {
+  const authExtension = operation["x-agentcash-auth"];
+  if (isRecord5(authExtension)) {
+    const mode = authExtension.mode;
+    if (mode === "paid" || mode === "siwx" || mode === "apiKey" || mode === "unprotected") {
+      return mode;
+    }
+  }
+  if (isRecord5(operation["x-payment-info"])) return "paid";
+  return void 0;
+}
+function createResourceMap(result) {
+  const map = /* @__PURE__ */ new Map();
+  for (const resource of result.resources) {
+    map.set(resource.resourceKey, resource);
+  }
+  return map;
+}
+function toMcpEndpointSummary(resource) {
+  const method = parseMethod(resource.method);
+  if (!method) return void 0;
+  const price = formatPriceHintFromResource(resource);
+  const authMode = deriveMcpAuthMode(resource);
+  return {
+    path: resource.path,
+    method,
+    summary: resource.summary ?? `${method} ${resource.path}`,
+    ...price ? { price } : {},
+    ...resource.protocolHints?.length ? { protocols: [...resource.protocolHints] } : {},
+    ...authMode ? { authMode } : {}
+  };
+}
+async function discoverForMcp(options) {
+  const result = await runDiscovery({
+    detailed: true,
+    options: {
+      target: options.target,
+      compatMode: options.compatMode ?? "off",
+      rawView: "full",
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal
+    }
+  });
+  if (result.resources.length === 0) {
+    const failure = inferFailureCause(result.warnings);
+    return {
+      found: false,
+      origin: result.origin,
+      cause: failure.cause,
+      ...failure.message ? { message: failure.message } : {},
+      warnings: result.warnings
+    };
+  }
+  const source = result.selectedStage ?? "openapi";
+  const endpoints = result.resources.map(toMcpEndpointSummary).filter((endpoint) => endpoint != null).sort((a, b) => {
+    if (a.path !== b.path) return a.path.localeCompare(b.path);
+    return a.method.localeCompare(b.method);
+  });
+  const guidance = await resolveGuidance({
+    result,
+    includeGuidance: options.includeGuidance,
+    guidanceAutoIncludeMaxTokens: options.guidanceAutoIncludeMaxTokens,
+    fetcher: options.fetcher,
+    headers: options.headers,
+    signal: options.signal
+  });
+  return {
+    found: true,
+    origin: result.origin,
+    source,
+    ...getOpenApiInfo(result.rawSources?.openapi) ? { info: getOpenApiInfo(result.rawSources?.openapi) } : {},
+    ...guidance,
+    endpoints,
+    warnings: result.warnings
+  };
+}
+async function inspectEndpointForMcp(options) {
+  const endpoint = new URL(options.endpointUrl);
+  const origin = normalizeOrigin(endpoint.origin);
+  const path = normalizePath(endpoint.pathname || "/");
+  const result = await runDiscovery({
+    detailed: true,
+    options: {
+      target: options.target,
+      compatMode: options.compatMode ?? "off",
+      rawView: "full",
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal
+    }
+  });
+  const document = result.rawSources?.openapi;
+  const paths = extractPathsDocument(document);
+  const resourceMap = createResourceMap(result);
+  const advisories = {};
+  const specMethods = [];
+  if (paths) {
+    const matched = findMatchingOpenApiPath(paths, path);
+    if (matched) {
+      for (const candidate of OPENAPI_METHODS) {
+        const operation = matched.pathItem[candidate.toLowerCase()];
+        if (!isRecord5(operation) || !isRecord5(document)) continue;
+        specMethods.push(candidate);
+        const resolvedOperation = resolveRefs(document, operation, /* @__PURE__ */ new Set());
+        const resource = resourceMap.get(toResourceKey(origin, candidate, matched.matchedPath));
+        const formattedPrice = resource ? formatPriceHintFromResource(resource) : void 0;
+        const operationSummary = typeof resolvedOperation.summary === "string" ? resolvedOperation.summary : typeof resolvedOperation.description === "string" ? resolvedOperation.description : void 0;
+        const operationPrice = parseOperationPrice(resolvedOperation);
+        const operationProtocols = parseOperationProtocols(resolvedOperation);
+        const operationAuthMode = parseOperationAuthMode(resolvedOperation);
+        const inputSchema = extractInputSchema(resolvedOperation);
+        advisories[candidate] = {
+          method: candidate,
+          ...resource?.summary || operationSummary ? {
+            summary: resource?.summary ?? operationSummary
+          } : {},
+          ...formattedPrice || operationPrice ? {
+            estimatedPrice: formattedPrice ?? operationPrice
+          } : {},
+          ...resource?.protocolHints?.length || operationProtocols ? {
+            protocols: resource?.protocolHints ?? operationProtocols
+          } : {},
+          ...deriveMcpAuthMode(resource) || operationAuthMode ? {
+            authMode: deriveMcpAuthMode(resource) ?? operationAuthMode
+          } : {},
+          ...inputSchema ? { inputSchema } : {},
+          operationSchema: resolvedOperation
+        };
+      }
+    }
+  }
+  if (specMethods.length === 0) {
+    for (const method of OPENAPI_METHODS) {
+      const resource = resourceMap.get(toResourceKey(origin, method, path));
+      if (!resource) continue;
+      specMethods.push(method);
+      const formattedPrice = formatPriceHintFromResource(resource);
+      advisories[method] = {
+        method,
+        ...resource.summary ? { summary: resource.summary } : {},
+        ...formattedPrice ? { estimatedPrice: formattedPrice } : {},
+        ...resource.protocolHints?.length ? { protocols: [...resource.protocolHints] } : {},
+        ...deriveMcpAuthMode(resource) ? { authMode: deriveMcpAuthMode(resource) } : {}
+      };
+    }
+  }
+  if (specMethods.length === 0) {
+    const failure = inferFailureCause(result.warnings);
+    return {
+      found: false,
+      origin,
+      path,
+      cause: failure.cause,
+      ...failure.message ? { message: failure.message } : {},
+      warnings: result.warnings
+    };
+  }
+  return {
+    found: true,
+    origin,
+    path,
+    specMethods,
+    advisories,
+    warnings: result.warnings
+  };
+}
+
 // src/harness.ts
 var INTENT_TRIGGERS = ["x402", "mpp", "pay for", "micropayment", "agentic commerce"];
 var CLIENT_PROFILES = {
@@ -1652,12 +2507,17 @@ export {
   LEGACY_SUNSET_DATE,
   STRICT_ESCALATION_CODES,
   UPGRADE_WARNING_CODES,
+  VALIDATION_CODES,
   auditContextHarness,
   buildContextHarnessReport,
   computeUpgradeSignal,
   defaultHarnessProbeCandidates,
   discover,
   discoverDetailed,
+  discoverForMcp,
+  evaluateMetadataCompleteness,
   getHarnessClientProfile,
-  listHarnessClientProfiles
+  inspectEndpointForMcp,
+  listHarnessClientProfiles,
+  validatePaymentRequiredDetailed
 };