@agentcash/discovery 0.1.0

package/dist/cli.cjs

@@ -0,0 +1,1825 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  main: () => main
+});
+module.exports = __toCommonJS(cli_exports);
+
+// src/flags.ts
+var DEFAULT_COMPAT_MODE = "on";
+var STRICT_ESCALATION_CODES = [
+  "LEGACY_WELL_KNOWN_USED",
+  "LEGACY_DNS_USED",
+  "LEGACY_DNS_PLAIN_URL",
+  "LEGACY_MISSING_METHOD",
+  "LEGACY_INSTRUCTIONS_USED",
+  "LEGACY_OWNERSHIP_PROOFS_USED",
+  "INTEROP_MPP_USED"
+];
+
+// src/cli/args.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+function parseCompatibilityMode(value) {
+  if (value === "on" || value === "off" || value === "strict") {
+    return value;
+  }
+  return null;
+}
+function parseTimeoutMs(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    return null;
+  }
+  return parsed;
+}
+function parseCliArgs(argv) {
+  let target;
+  let verbose = false;
+  let json = false;
+  let probe = false;
+  let timeoutMs = DEFAULT_TIMEOUT_MS;
+  let compatMode = DEFAULT_COMPAT_MODE;
+  let color = true;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      return { kind: "help" };
+    }
+    if (arg === "--verbose" || arg === "-v") {
+      verbose = true;
+      continue;
+    }
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (arg === "--probe") {
+      probe = true;
+      continue;
+    }
+    if (arg === "--no-color") {
+      color = false;
+      continue;
+    }
+    if (arg === "--compat") {
+      const value = argv[i + 1];
+      if (!value) {
+        return { kind: "error", message: "Missing value for --compat." };
+      }
+      const parsed = parseCompatibilityMode(value);
+      if (!parsed) {
+        return {
+          kind: "error",
+          message: `Invalid --compat value '${value}'. Expected: on | off | strict.`
+        };
+      }
+      compatMode = parsed;
+      i += 1;
+      continue;
+    }
+    if (arg === "--timeout-ms") {
+      const value = argv[i + 1];
+      if (!value) {
+        return { kind: "error", message: "Missing value for --timeout-ms." };
+      }
+      const parsed = parseTimeoutMs(value);
+      if (!parsed) {
+        return {
+          kind: "error",
+          message: `Invalid --timeout-ms value '${value}'. Expected a positive integer.`
+        };
+      }
+      timeoutMs = parsed;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return { kind: "error", message: `Unknown flag '${arg}'.` };
+    }
+    if (target) {
+      return {
+        kind: "error",
+        message: `Unexpected extra positional argument '${arg}'. Only one domain/URL is supported.`
+      };
+    }
+    target = arg;
+  }
+  if (!target) {
+    return { kind: "error", message: "Missing required <domain> argument." };
+  }
+  return {
+    kind: "ok",
+    options: {
+      target,
+      verbose,
+      json,
+      compatMode,
+      probe,
+      timeoutMs,
+      color
+    }
+  };
+}
+function renderHelp() {
+  return [
+    "Usage: npx @agentcash/discovery <domain-or-url> [options]",
+    "",
+    "Options:",
+    "  -v, --verbose          Show full compatibility matrix",
+    "  --json                 Emit JSON output",
+    "  --compat <mode>        Compatibility mode: on | off | strict (default: on)",
+    "  --probe                Re-run with probe candidates from discovered paths",
+    "  --timeout-ms <ms>      Per-request timeout in milliseconds (default: 5000)",
+    "  --no-color             Disable ANSI colors",
+    "  -h, --help             Show help"
+  ].join("\n");
+}
+
+// src/cli/render.ts
+function createPalette(enabled) {
+  const wrap = (code) => (value) => enabled ? `\x1B[${code}m${value}\x1B[0m` : value;
+  return {
+    dim: wrap(2),
+    bold: wrap(1),
+    red: wrap(31),
+    green: wrap(32),
+    yellow: wrap(33),
+    cyan: wrap(36)
+  };
+}
+function summarizeWarnings(warnings) {
+  const errors = warnings.filter((entry) => entry.severity === "error").length;
+  const warns = warnings.filter((entry) => entry.severity === "warn").length;
+  const infos = warnings.filter((entry) => entry.severity === "info").length;
+  const codeCounts = warnings.filter((entry) => entry.code !== "PROBE_STAGE_SKIPPED").reduce(
+    (acc, entry) => {
+      acc[entry.code] = (acc[entry.code] ?? 0) + 1;
+      return acc;
+    },
+    {}
+  );
+  const codes = Object.entries(codeCounts).sort((a, b) => b[1] - a[1]).slice(0, 8).map(([code]) => code);
+  return {
+    total: warnings.length,
+    errors,
+    warns,
+    infos,
+    codes
+  };
+}
+function formatPricing(resource) {
+  if (resource.authHint !== "paid") return "-";
+  if (resource.pricing) {
+    if (resource.pricing.pricingMode === "fixed") {
+      return `fixed:${resource.pricing.price ?? "?"}`;
+    }
+    if (resource.pricing.pricingMode === "range") {
+      return `range:${resource.pricing.minPrice ?? "?"}-${resource.pricing.maxPrice ?? "?"}`;
+    }
+    return "quote";
+  }
+  return resource.priceHint ?? "-";
+}
+function asYesNo(value) {
+  return value ? "yes" : "no";
+}
+function createTable(headers, rows) {
+  const widths = headers.map((header, idx) => {
+    const cellWidths = rows.map((row) => row[idx]?.length ?? 0);
+    return Math.max(header.length, ...cellWidths);
+  });
+  const line = (row) => row.map((cell, idx) => {
+    const value = cell ?? "";
+    return value.padEnd(widths[idx], " ");
+  }).join(" | ");
+  const separator = widths.map((width) => "-".repeat(width)).join("-|-");
+  return [line(headers), separator, ...rows.map((row) => line(row))].join("\n");
+}
+function stageRows(result) {
+  return result.trace.map((entry) => {
+    const uniqueWarningCodes = [...new Set(entry.warnings.map((warning2) => warning2.code))];
+    return [
+      entry.stage,
+      asYesNo(entry.valid),
+      String(entry.resourceCount),
+      `${entry.durationMs}ms`,
+      uniqueWarningCodes.length > 0 ? uniqueWarningCodes.join(",") : "-",
+      result.selectedStage === entry.stage ? "yes" : "-"
+    ];
+  });
+}
+function resourceRows(result) {
+  return [...result.resources].sort((a, b) => {
+    if (a.path !== b.path) return a.path.localeCompare(b.path);
+    if (a.method !== b.method) return a.method.localeCompare(b.method);
+    return a.origin.localeCompare(b.origin);
+  }).map((resource) => [
+    resource.method,
+    resource.path,
+    resource.authHint ?? "-",
+    formatPricing(resource),
+    resource.source,
+    asYesNo(resource.verified),
+    resource.authHint === "siwx" ? "siwx" : "-"
+  ]);
+}
+function renderHeader(run, options, palette, withVerboseSuffix) {
+  const ok = run.result.resources.length > 0;
+  const status = ok ? palette.green("PASS") : palette.red("FAIL");
+  const warningSummary = summarizeWarnings(run.result.warnings);
+  const mode = options.compatMode;
+  return [
+    `${palette.bold("agentcash discovery audit")}${withVerboseSuffix ? ` ${palette.cyan("(verbose)")}` : ""}`,
+    `target: ${options.target}`,
+    `origin: ${run.result.origin}`,
+    `status: ${status}`,
+    `resources: ${run.result.resources.length}`,
+    `selected_stage: ${run.result.selectedStage ?? "none"}`,
+    `compat_mode: ${mode}`,
+    `upgrade_suggested: ${run.result.upgradeSuggested ? palette.yellow("yes") : "no"}`,
+    `duration_ms: ${run.durationMs}`,
+    `warnings: total=${warningSummary.total} error=${warningSummary.errors} warn=${warningSummary.warns} info=${warningSummary.infos}`,
+    warningSummary.codes.length > 0 ? `warning_codes: ${warningSummary.codes.join(", ")}` : "warning_codes: -",
+    options.probe ? `probe_candidates: ${run.probeCandidateCount}` : "probe_candidates: disabled"
+  ].join("\n");
+}
+function renderSummary(run, options) {
+  const palette = createPalette(options.color);
+  return renderHeader(run, options, palette, false);
+}
+function renderVerbose(run, options) {
+  const palette = createPalette(options.color);
+  const parts = [renderHeader(run, options, palette, true), ""];
+  parts.push(palette.bold("stage_matrix"));
+  parts.push(
+    createTable(
+      ["stage", "valid", "resources", "duration", "warning_codes", "selected"],
+      stageRows(run.result)
+    )
+  );
+  parts.push("");
+  parts.push(palette.bold("resource_matrix"));
+  if (run.result.resources.length === 0) {
+    parts.push(palette.dim("(no discovered resources)"));
+  } else {
+    parts.push(
+      createTable(
+        ["method", "path", "auth", "pricing", "source", "verified", "notes"],
+        resourceRows(run.result)
+      )
+    );
+  }
+  if (run.result.upgradeReasons.length > 0) {
+    parts.push("");
+    parts.push(palette.bold("upgrade_reasons"));
+    for (const reason of run.result.upgradeReasons) {
+      parts.push(`- ${reason}`);
+    }
+  }
+  return parts.join("\n");
+}
+function renderJson(run, options) {
+  return JSON.stringify(
+    {
+      ok: run.result.resources.length > 0,
+      target: options.target,
+      origin: run.result.origin,
+      compatMode: run.result.compatMode,
+      selectedStage: run.result.selectedStage ?? null,
+      resources: run.result.resources,
+      trace: run.result.trace,
+      warnings: run.result.warnings,
+      upgradeSuggested: run.result.upgradeSuggested,
+      upgradeReasons: run.result.upgradeReasons,
+      meta: {
+        durationMs: run.durationMs,
+        probeEnabled: options.probe,
+        probeCandidateCount: run.probeCandidateCount,
+        timeoutMs: options.timeoutMs
+      }
+    },
+    null,
+    2
+  );
+}
+
+// src/core/constants.ts
+var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];
+var WELL_KNOWN_MPP_PATH = "/.well-known/mpp";
+var LLMS_TOKEN_WARNING_THRESHOLD = 2500;
+var HTTP_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+  "TRACE"
+]);
+var DEFAULT_PROBE_METHODS = ["GET", "POST"];
+var DEFAULT_MISSING_METHOD = "POST";
+
+// src/core/url.ts
+function normalizeOrigin(target) {
+  const trimmed = target.trim();
+  const withProtocol = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  const url = new URL(withProtocol);
+  url.pathname = "";
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function normalizePath(pathname) {
+  const parsed = pathname.trim();
+  if (parsed.length === 0 || parsed === "/") return "/";
+  const pathOnly = parsed.split("?")[0]?.split("#")[0] ?? "/";
+  const prefixed = pathOnly.startsWith("/") ? pathOnly : `/${pathOnly}`;
+  const normalized = prefixed.replace(/\/+/g, "/");
+  return normalized !== "/" ? normalized.replace(/\/$/, "") : "/";
+}
+function toResourceKey(origin, method, path) {
+  return `${origin} ${method} ${normalizePath(path)}`;
+}
+function parseMethod(value) {
+  if (!value) return void 0;
+  const upper = value.toUpperCase();
+  return HTTP_METHODS.has(upper) ? upper : void 0;
+}
+function toAbsoluteUrl(origin, value) {
+  try {
+    if (/^https?:\/\//i.test(value)) return new URL(value);
+    return new URL(normalizePath(value), `${origin}/`);
+  } catch {
+    return null;
+  }
+}
+
+// src/core/warnings.ts
+function warning(code, severity, message, options) {
+  return {
+    code,
+    severity,
+    message,
+    ...options?.hint ? { hint: options.hint } : {},
+    ...options?.stage ? { stage: options.stage } : {},
+    ...options?.resourceKey ? { resourceKey: options.resourceKey } : {}
+  };
+}
+function applyStrictEscalation(warnings, strict) {
+  if (!strict) return warnings;
+  return warnings.map((entry) => {
+    if (!STRICT_ESCALATION_CODES.includes(entry.code)) {
+      return entry;
+    }
+    if (entry.severity === "error") return entry;
+    return {
+      ...entry,
+      severity: "error",
+      message: `${entry.message} (strict mode escalated)`
+    };
+  });
+}
+function dedupeWarnings(warnings) {
+  const seen = /* @__PURE__ */ new Set();
+  const output = [];
+  for (const item of warnings) {
+    const key = `${item.code}|${item.severity}|${item.stage ?? ""}|${item.resourceKey ?? ""}|${item.message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    output.push(item);
+  }
+  return output;
+}
+
+// src/core/normalize.ts
+function createResource(input, confidence, trustTier) {
+  const normalizedOrigin = normalizeOrigin(input.origin);
+  const normalizedPath = normalizePath(input.path);
+  return {
+    resourceKey: toResourceKey(normalizedOrigin, input.method, normalizedPath),
+    origin: normalizedOrigin,
+    method: input.method,
+    path: normalizedPath,
+    source: input.source,
+    verified: false,
+    ...input.protocolHints?.length ? { protocolHints: [...new Set(input.protocolHints)] } : {},
+    ...input.priceHint ? { priceHint: input.priceHint } : {},
+    ...input.pricing ? { pricing: input.pricing } : {},
+    ...input.authHint ? { authHint: input.authHint } : {},
+    ...input.summary ? { summary: input.summary } : {},
+    confidence,
+    trustTier,
+    ...input.links ? { links: input.links } : {}
+  };
+}
+
+// src/compat/legacy-x402scan/wellKnown.ts
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseLegacyResourceEntry(entry) {
+  const trimmed = entry.trim();
+  if (!trimmed) return null;
+  const parts = trimmed.split(/\s+/);
+  if (parts.length >= 2) {
+    const maybeMethod = parseMethod(parts[0]);
+    if (maybeMethod) {
+      const target = parts.slice(1).join(" ");
+      return { method: maybeMethod, target };
+    }
+  }
+  if (trimmed.startsWith("/") || /^https?:\/\//i.test(trimmed)) {
+    return { target: trimmed };
+  }
+  return null;
+}
+function parseWellKnownPayload(payload, origin, sourceUrl) {
+  const warnings = [
+    warning(
+      "LEGACY_WELL_KNOWN_USED",
+      "warn",
+      "Using legacy /.well-known/x402 compatibility path. Migrate to OpenAPI-first.",
+      {
+        stage: "well-known/x402"
+      }
+    )
+  ];
+  if (!isRecord(payload)) {
+    warnings.push(
+      warning("PARSE_FAILED", "error", "Legacy well-known payload is not an object", {
+        stage: "well-known/x402"
+      })
+    );
+    return { resources: [], warnings, raw: payload };
+  }
+  const resourcesRaw = Array.isArray(payload.resources) ? payload.resources.filter((entry) => typeof entry === "string") : [];
+  if (resourcesRaw.length === 0) {
+    warnings.push(
+      warning("STAGE_EMPTY", "warn", "Legacy well-known has no valid resources array", {
+        stage: "well-known/x402"
+      })
+    );
+  }
+  const instructions = typeof payload.instructions === "string" ? payload.instructions : void 0;
+  const ownershipProofs = Array.isArray(payload.ownershipProofs) ? payload.ownershipProofs.filter((entry) => typeof entry === "string") : [];
+  if (instructions) {
+    warnings.push(
+      warning(
+        "LEGACY_INSTRUCTIONS_USED",
+        "warn",
+        "Using /.well-known/x402.instructions as compatibility guidance fallback. Prefer llms.txt.",
+        {
+          stage: "well-known/x402",
+          hint: "Move guidance to llms.txt and reference via x-agentcash-guidance.llmsTxtUrl."
+        }
+      )
+    );
+  }
+  if (ownershipProofs.length > 0) {
+    warnings.push(
+      warning(
+        "LEGACY_OWNERSHIP_PROOFS_USED",
+        "warn",
+        "Using /.well-known/x402.ownershipProofs compatibility field. Prefer OpenAPI provenance extension.",
+        {
+          stage: "well-known/x402",
+          hint: "Move ownership proofs to x-agentcash-provenance.ownershipProofs in OpenAPI."
+        }
+      )
+    );
+  }
+  const resources = [];
+  for (const rawEntry of resourcesRaw) {
+    const parsed = parseLegacyResourceEntry(rawEntry);
+    if (!parsed) {
+      warnings.push(
+        warning("PARSE_FAILED", "warn", `Invalid legacy resource entry: ${rawEntry}`, {
+          stage: "well-known/x402"
+        })
+      );
+      continue;
+    }
+    const absolute = toAbsoluteUrl(origin, parsed.target);
+    if (!absolute) {
+      warnings.push(
+        warning("PARSE_FAILED", "warn", `Invalid legacy resource URL: ${rawEntry}`, {
+          stage: "well-known/x402"
+        })
+      );
+      continue;
+    }
+    const method = parsed.method ?? DEFAULT_MISSING_METHOD;
+    if (!parsed.method) {
+      warnings.push(
+        warning(
+          "LEGACY_MISSING_METHOD",
+          "warn",
+          `Legacy resource '${rawEntry}' missing method. Defaulting to ${DEFAULT_MISSING_METHOD}.`,
+          {
+            stage: "well-known/x402"
+          }
+        )
+      );
+    }
+    const path = normalizePath(absolute.pathname);
+    resources.push(
+      createResource(
+        {
+          origin: absolute.origin,
+          method,
+          path,
+          source: "well-known/x402",
+          summary: `${method} ${path}`,
+          authHint: "paid",
+          protocolHints: ["x402"],
+          links: {
+            wellKnownUrl: sourceUrl,
+            discoveryUrl: sourceUrl
+          }
+        },
+        0.65,
+        ownershipProofs.length > 0 ? "ownership_verified" : "origin_hosted"
+      )
+    );
+  }
+  return {
+    resources,
+    warnings,
+    raw: payload
+  };
+}
+async function runWellKnownX402Stage(options) {
+  const stageUrl = options.url ?? `${options.origin}/.well-known/x402`;
+  try {
+    const response = await options.fetcher(stageUrl, {
+      method: "GET",
+      headers: { Accept: "application/json", ...options.headers },
+      signal: options.signal
+    });
+    if (!response.ok) {
+      if (response.status === 404) {
+        return {
+          stage: "well-known/x402",
+          valid: false,
+          resources: [],
+          warnings: [],
+          links: { wellKnownUrl: stageUrl }
+        };
+      }
+      return {
+        stage: "well-known/x402",
+        valid: false,
+        resources: [],
+        warnings: [
+          warning("FETCH_FAILED", "warn", `Legacy well-known fetch failed (${response.status})`, {
+            stage: "well-known/x402"
+          })
+        ],
+        links: { wellKnownUrl: stageUrl }
+      };
+    }
+    const payload = await response.json();
+    const parsed = parseWellKnownPayload(payload, options.origin, stageUrl);
+    return {
+      stage: "well-known/x402",
+      valid: parsed.resources.length > 0,
+      resources: parsed.resources,
+      warnings: parsed.warnings,
+      links: { wellKnownUrl: stageUrl },
+      ...options.includeRaw ? { raw: parsed.raw } : {}
+    };
+  } catch (error) {
+    return {
+      stage: "well-known/x402",
+      valid: false,
+      resources: [],
+      warnings: [
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `Legacy well-known fetch exception: ${error instanceof Error ? error.message : String(error)}`,
+          {
+            stage: "well-known/x402"
+          }
+        )
+      ],
+      links: { wellKnownUrl: stageUrl }
+    };
+  }
+}
+
+// src/compat/legacy-x402scan/dns.ts
+function parseDnsRecord(record) {
+  const trimmed = record.trim();
+  if (!trimmed) return null;
+  if (/^https?:\/\//i.test(trimmed)) {
+    return { url: trimmed, legacyPlainUrl: true };
+  }
+  const parts = trimmed.split(";").map((entry) => entry.trim()).filter(Boolean);
+  const keyValues = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    const separator = part.indexOf("=");
+    if (separator <= 0) continue;
+    const key = part.slice(0, separator).trim().toLowerCase();
+    const value = part.slice(separator + 1).trim();
+    if (key && value) keyValues.set(key, value);
+  }
+  if (keyValues.get("v") !== "x4021") return null;
+  const url = keyValues.get("url");
+  if (!url || !/^https?:\/\//i.test(url)) return null;
+  return { url, legacyPlainUrl: false };
+}
+async function runDnsStage(options) {
+  if (!options.txtResolver) {
+    return {
+      stage: "dns/_x402",
+      valid: false,
+      resources: [],
+      warnings: []
+    };
+  }
+  const origin = normalizeOrigin(options.origin);
+  const hostname = new URL(origin).hostname;
+  const fqdn = `_x402.${hostname}`;
+  let records;
+  try {
+    records = await options.txtResolver(fqdn);
+  } catch (error) {
+    return {
+      stage: "dns/_x402",
+      valid: false,
+      resources: [],
+      warnings: [
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `DNS TXT lookup failed for ${fqdn}: ${error instanceof Error ? error.message : String(error)}`,
+          { stage: "dns/_x402" }
+        )
+      ]
+    };
+  }
+  if (records.length === 0) {
+    return {
+      stage: "dns/_x402",
+      valid: false,
+      resources: [],
+      warnings: []
+    };
+  }
+  const warnings = [
+    warning(
+      "LEGACY_DNS_USED",
+      "warn",
+      "Using DNS _x402 compatibility path. Migrate to OpenAPI-first discovery.",
+      {
+        stage: "dns/_x402"
+      }
+    )
+  ];
+  const urls = [];
+  for (const record of records) {
+    const parsed = parseDnsRecord(record);
+    if (!parsed) {
+      warnings.push(
+        warning("PARSE_FAILED", "warn", `Invalid DNS _x402 TXT record: ${record}`, {
+          stage: "dns/_x402"
+        })
+      );
+      continue;
+    }
+    urls.push(parsed.url);
+    if (parsed.legacyPlainUrl) {
+      warnings.push(
+        warning("LEGACY_DNS_PLAIN_URL", "warn", `Legacy plain URL TXT format used: ${record}`, {
+          stage: "dns/_x402",
+          hint: "Use v=x4021;url=<https-url> format."
+        })
+      );
+    }
+  }
+  if (urls.length === 0) {
+    return {
+      stage: "dns/_x402",
+      valid: false,
+      resources: [],
+      warnings,
+      ...options.includeRaw ? { raw: { dnsRecords: records } } : {}
+    };
+  }
+  const mergedWarnings = [...warnings];
+  const mergedResources = [];
+  const rawDocuments = [];
+  for (const url of urls) {
+    const stageResult = await runWellKnownX402Stage({
+      origin,
+      url,
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal,
+      includeRaw: options.includeRaw
+    });
+    mergedResources.push(...stageResult.resources);
+    mergedWarnings.push(...stageResult.warnings);
+    if (options.includeRaw && stageResult.raw !== void 0) {
+      rawDocuments.push({ url, document: stageResult.raw });
+    }
+  }
+  const deduped = /* @__PURE__ */ new Map();
+  for (const resource of mergedResources) {
+    if (!deduped.has(resource.resourceKey)) {
+      deduped.set(resource.resourceKey, {
+        ...resource,
+        source: "dns/_x402",
+        links: {
+          ...resource.links,
+          discoveryUrl: resource.links?.discoveryUrl
+        }
+      });
+    }
+  }
+  return {
+    stage: "dns/_x402",
+    valid: deduped.size > 0,
+    resources: [...deduped.values()],
+    warnings: mergedWarnings,
+    ...options.includeRaw ? { raw: { dnsRecords: records, documents: rawDocuments } } : {}
+  };
+}
+
+// src/compat/interop-mpp/wellKnownMpp.ts
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function runInteropMppStage(options) {
+  const url = `${options.origin}${WELL_KNOWN_MPP_PATH}`;
+  try {
+    const response = await options.fetcher(url, {
+      method: "GET",
+      headers: { Accept: "application/json", ...options.headers },
+      signal: options.signal
+    });
+    if (!response.ok) {
+      return {
+        stage: "interop/mpp",
+        valid: false,
+        resources: [],
+        warnings: []
+      };
+    }
+    const payload = await response.json();
+    if (!isRecord2(payload)) {
+      return {
+        stage: "interop/mpp",
+        valid: false,
+        resources: [],
+        warnings: [
+          warning("PARSE_FAILED", "warn", "Interop /.well-known/mpp payload is not an object", {
+            stage: "interop/mpp"
+          })
+        ],
+        ...options.includeRaw ? { raw: payload } : {}
+      };
+    }
+    const warnings = [
+      warning(
+        "INTEROP_MPP_USED",
+        "info",
+        "Using /.well-known/mpp interop adapter. This is additive and non-canonical.",
+        {
+          stage: "interop/mpp",
+          hint: "Use for registry indexing only, not canonical runtime routing."
+        }
+      )
+    ];
+    const resources = [];
+    const fromStringResources = Array.isArray(payload.resources) ? payload.resources.filter((entry) => typeof entry === "string") : [];
+    for (const entry of fromStringResources) {
+      const parts = entry.trim().split(/\s+/);
+      let method = parseMethod(parts[0]);
+      let path = parts.join(" ");
+      if (method) {
+        path = parts.slice(1).join(" ");
+      } else {
+        method = "POST";
+      }
+      const normalizedPath = normalizePath(path);
+      resources.push(
+        createResource(
+          {
+            origin: options.origin,
+            method,
+            path: normalizedPath,
+            source: "interop/mpp",
+            summary: `${method} ${normalizedPath}`,
+            authHint: "paid",
+            protocolHints: ["mpp"],
+            links: { discoveryUrl: url }
+          },
+          0.45,
+          "unverified"
+        )
+      );
+    }
+    const fromServiceObjects = Array.isArray(payload.services) ? payload.services.filter((entry) => isRecord2(entry)) : [];
+    for (const service of fromServiceObjects) {
+      const path = typeof service.path === "string" ? service.path : void 0;
+      const method = parseMethod(typeof service.method === "string" ? service.method : void 0) ?? "POST";
+      if (!path) continue;
+      const normalizedPath = normalizePath(path);
+      resources.push(
+        createResource(
+          {
+            origin: options.origin,
+            method,
+            path: normalizedPath,
+            source: "interop/mpp",
+            summary: typeof service.summary === "string" ? service.summary : `${method} ${normalizedPath}`,
+            authHint: "paid",
+            protocolHints: ["mpp"],
+            links: { discoveryUrl: url }
+          },
+          0.45,
+          "unverified"
+        )
+      );
+    }
+    const deduped = /* @__PURE__ */ new Map();
+    for (const resource of resources) {
+      if (!deduped.has(resource.resourceKey)) deduped.set(resource.resourceKey, resource);
+    }
+    return {
+      stage: "interop/mpp",
+      valid: deduped.size > 0,
+      resources: [...deduped.values()],
+      warnings,
+      ...options.includeRaw ? { raw: payload } : {}
+    };
+  } catch (error) {
+    return {
+      stage: "interop/mpp",
+      valid: false,
+      resources: [],
+      warnings: [
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `Interop /.well-known/mpp fetch failed: ${error instanceof Error ? error.message : String(error)}`,
+          {
+            stage: "interop/mpp"
+          }
+        )
+      ]
+    };
+  }
+}
+
+// src/core/token.ts
+function estimateTokenCount(text) {
+  return Math.ceil(text.length / 4);
+}
+
+// src/core/openapi.ts
+function isRecord3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function parsePriceValue(value) {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return void 0;
+}
+function require402Response(operation) {
+  const responses = operation.responses;
+  if (!isRecord3(responses)) return false;
+  return Boolean(responses["402"]);
+}
+function parseProtocols(paymentInfo) {
+  const protocols = paymentInfo.protocols;
+  if (!Array.isArray(protocols)) return [];
+  return protocols.filter(
+    (entry) => typeof entry === "string" && entry.length > 0
+  );
+}
+function parseAuthMode(operation) {
+  const auth = operation["x-agentcash-auth"];
+  if (!isRecord3(auth)) return void 0;
+  const mode = auth.mode;
+  if (mode === "paid" || mode === "siwx" || mode === "apiKey" || mode === "unprotected") {
+    return mode;
+  }
+  return void 0;
+}
+async function runOpenApiStage(options) {
+  const warnings = [];
+  const resources = [];
+  let fetchedUrl;
+  let document;
+  for (const path of OPENAPI_PATH_CANDIDATES) {
+    const url = `${options.origin}${path}`;
+    try {
+      const response = await options.fetcher(url, {
+        method: "GET",
+        headers: { Accept: "application/json", ...options.headers },
+        signal: options.signal
+      });
+      if (!response.ok) {
+        if (response.status !== 404) {
+          warnings.push(
+            warning("FETCH_FAILED", "warn", `OpenAPI fetch failed (${response.status}) at ${url}`, {
+              stage: "openapi"
+            })
+          );
+        }
+        continue;
+      }
+      const payload = await response.json();
+      if (!isRecord3(payload)) {
+        warnings.push(
+          warning("PARSE_FAILED", "error", `OpenAPI payload at ${url} is not a JSON object`, {
+            stage: "openapi"
+          })
+        );
+        continue;
+      }
+      document = payload;
+      fetchedUrl = url;
+      break;
+    } catch (error) {
+      warnings.push(
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `OpenAPI fetch exception at ${url}: ${error instanceof Error ? error.message : String(error)}`,
+          { stage: "openapi" }
+        )
+      );
+    }
+  }
+  if (!document || !fetchedUrl) {
+    return {
+      stage: "openapi",
+      valid: false,
+      resources: [],
+      warnings
+    };
+  }
+  const hasTopLevel = typeof document.openapi === "string" && isRecord3(document.info) && typeof document.info.title === "string" && typeof document.info.version === "string" && isRecord3(document.paths);
+  if (!hasTopLevel) {
+    warnings.push(
+      warning("OPENAPI_TOP_LEVEL_INVALID", "error", "OpenAPI required fields are missing", {
+        stage: "openapi"
+      })
+    );
+    return {
+      stage: "openapi",
+      valid: false,
+      resources: [],
+      warnings,
+      links: { openapiUrl: fetchedUrl },
+      ...options.includeRaw ? { raw: document } : {}
+    };
+  }
+  const paths = document.paths;
+  const provenance = isRecord3(document["x-agentcash-provenance"]) ? document["x-agentcash-provenance"] : void 0;
+  const ownershipProofs = Array.isArray(provenance?.ownershipProofs) ? provenance.ownershipProofs.filter((entry) => typeof entry === "string") : [];
+  const guidance = isRecord3(document["x-agentcash-guidance"]) ? document["x-agentcash-guidance"] : void 0;
+  const llmsTxtUrl = asString(guidance?.llmsTxtUrl);
+  if (ownershipProofs.length > 0) {
+    warnings.push(
+      warning("OPENAPI_OWNERSHIP_PROOFS_PRESENT", "info", "OpenAPI ownership proofs detected", {
+        stage: "openapi"
+      })
+    );
+  }
+  for (const [rawPath, rawPathItem] of Object.entries(paths)) {
+    if (!isRecord3(rawPathItem)) {
+      warnings.push(
+        warning("OPENAPI_OPERATION_INVALID", "warn", `Path item ${rawPath} is not an object`, {
+          stage: "openapi"
+        })
+      );
+      continue;
+    }
+    for (const [rawMethod, rawOperation] of Object.entries(rawPathItem)) {
+      const method = parseMethod(rawMethod);
+      if (!method) continue;
+      if (!isRecord3(rawOperation)) {
+        warnings.push(
+          warning(
+            "OPENAPI_OPERATION_INVALID",
+            "warn",
+            `${rawMethod.toUpperCase()} ${rawPath} is not an object`,
+            {
+              stage: "openapi"
+            }
+          )
+        );
+        continue;
+      }
+      const operation = rawOperation;
+      const summary = asString(operation.summary) ?? asString(operation.description);
+      if (!summary) {
+        warnings.push(
+          warning(
+            "OPENAPI_SUMMARY_MISSING",
+            "warn",
+            `${method} ${rawPath} missing summary/description, using fallback summary`,
+            { stage: "openapi" }
+          )
+        );
+      }
+      const authMode = parseAuthMode(operation);
+      if (!authMode) {
+        warnings.push(
+          warning(
+            "OPENAPI_AUTH_MODE_MISSING",
+            "error",
+            `${method} ${rawPath} missing x-agentcash-auth.mode`,
+            {
+              stage: "openapi"
+            }
+          )
+        );
+        continue;
+      }
+      if ((authMode === "paid" || authMode === "siwx") && !require402Response(operation)) {
+        warnings.push(
+          warning(
+            "OPENAPI_402_MISSING",
+            "error",
+            `${method} ${rawPath} requires 402 response for authMode=${authMode}`,
+            { stage: "openapi" }
+          )
+        );
+        continue;
+      }
+      const paymentInfo = isRecord3(operation["x-payment-info"]) ? operation["x-payment-info"] : void 0;
+      const protocols = paymentInfo ? parseProtocols(paymentInfo) : [];
+      if (authMode === "paid" && protocols.length === 0) {
+        warnings.push(
+          warning(
+            "OPENAPI_PAID_PROTOCOLS_MISSING",
+            "error",
+            `${method} ${rawPath} must define x-payment-info.protocols when authMode=paid`,
+            { stage: "openapi" }
+          )
+        );
+        continue;
+      }
+      let pricing;
+      let priceHint;
+      if (paymentInfo && authMode === "paid") {
+        const pricingModeRaw = asString(paymentInfo.pricingMode);
+        const price = parsePriceValue(paymentInfo.price);
+        const minPrice = parsePriceValue(paymentInfo.minPrice);
+        const maxPrice = parsePriceValue(paymentInfo.maxPrice);
+        const inferredPricingMode = pricingModeRaw ?? (price ? "fixed" : minPrice && maxPrice ? "range" : "quote");
+        if (inferredPricingMode !== "fixed" && inferredPricingMode !== "range" && inferredPricingMode !== "quote") {
+          warnings.push(
+            warning(
+              "OPENAPI_PRICING_INVALID",
+              "error",
+              `${method} ${rawPath} has invalid pricingMode`,
+              {
+                stage: "openapi"
+              }
+            )
+          );
+          continue;
+        }
+        if (inferredPricingMode === "fixed" && !price) {
+          warnings.push(
+            warning(
+              "OPENAPI_PRICING_INVALID",
+              "error",
+              `${method} ${rawPath} fixed pricing requires price`,
+              {
+                stage: "openapi"
+              }
+            )
+          );
+          continue;
+        }
+        if (inferredPricingMode === "range") {
+          if (!minPrice || !maxPrice) {
+            warnings.push(
+              warning(
+                "OPENAPI_PRICING_INVALID",
+                "error",
+                `${method} ${rawPath} range pricing requires minPrice and maxPrice`,
+                { stage: "openapi" }
+              )
+            );
+            continue;
+          }
+          const min = Number(minPrice);
+          const max = Number(maxPrice);
+          if (!Number.isFinite(min) || !Number.isFinite(max) || min > max) {
+            warnings.push(
+              warning(
+                "OPENAPI_PRICING_INVALID",
+                "error",
+                `${method} ${rawPath} range pricing requires numeric minPrice <= maxPrice`,
+                { stage: "openapi" }
+              )
+            );
+            continue;
+          }
+        }
+        pricing = {
+          pricingMode: inferredPricingMode,
+          ...price ? { price } : {},
+          ...minPrice ? { minPrice } : {},
+          ...maxPrice ? { maxPrice } : {}
+        };
+        priceHint = inferredPricingMode === "fixed" ? price : inferredPricingMode === "range" ? `${minPrice}-${maxPrice}` : maxPrice;
+      }
+      const resource = createResource(
+        {
+          origin: options.origin,
+          method,
+          path: normalizePath(rawPath),
+          source: "openapi",
+          summary: summary ?? `${method} ${normalizePath(rawPath)}`,
+          authHint: authMode,
+          protocolHints: protocols,
+          ...priceHint ? { priceHint } : {},
+          ...pricing ? { pricing } : {},
+          links: {
+            openapiUrl: fetchedUrl,
+            ...llmsTxtUrl ? { llmsTxtUrl } : {}
+          }
+        },
+        0.95,
+        ownershipProofs.length > 0 ? "ownership_verified" : "origin_hosted"
+      );
+      resources.push(resource);
+    }
+  }
+  if (llmsTxtUrl) {
+    try {
+      const llmsResponse = await options.fetcher(llmsTxtUrl, {
+        method: "GET",
+        headers: { Accept: "text/plain", ...options.headers },
+        signal: options.signal
+      });
+      if (llmsResponse.ok) {
+        const llmsText = await llmsResponse.text();
+        const tokenCount = estimateTokenCount(llmsText);
+        if (tokenCount > LLMS_TOKEN_WARNING_THRESHOLD) {
+          warnings.push(
+            warning(
+              "LLMSTXT_TOO_LARGE",
+              "warn",
+              `llms.txt estimated ${tokenCount} tokens (threshold ${LLMS_TOKEN_WARNING_THRESHOLD})`,
+              {
+                stage: "openapi",
+                hint: "Keep llms.txt concise and domain-level only."
+              }
+            )
+          );
+        }
+        if (options.includeRaw) {
+          return {
+            stage: "openapi",
+            valid: resources.length > 0,
+            resources,
+            warnings,
+            links: { openapiUrl: fetchedUrl, llmsTxtUrl },
+            raw: {
+              openapi: document,
+              llmsTxt: llmsText
+            }
+          };
+        }
+      } else {
+        warnings.push(
+          warning(
+            "LLMSTXT_FETCH_FAILED",
+            "warn",
+            `llms.txt fetch failed (${llmsResponse.status})`,
+            {
+              stage: "openapi"
+            }
+          )
+        );
+      }
+    } catch (error) {
+      warnings.push(
+        warning(
+          "LLMSTXT_FETCH_FAILED",
+          "warn",
+          `llms.txt fetch failed: ${error instanceof Error ? error.message : String(error)}`,
+          { stage: "openapi" }
+        )
+      );
+    }
+  }
+  return {
+    stage: "openapi",
+    valid: resources.length > 0,
+    resources,
+    warnings,
+    links: {
+      openapiUrl: fetchedUrl,
+      ...llmsTxtUrl ? { llmsTxtUrl } : {}
+    },
+    ...options.includeRaw ? { raw: { openapi: document } } : {}
+  };
+}
+
+// src/core/probe.ts
+function detectAuthHintFrom402Payload(payload) {
+  if (payload && typeof payload === "object") {
+    const asRecord = payload;
+    const extensions = asRecord.extensions;
+    if (extensions && typeof extensions === "object") {
+      const extRecord = extensions;
+      if (extRecord["sign-in-with-x"]) return "siwx";
+    }
+  }
+  return "paid";
+}
+function detectProtocols(response) {
+  const protocols = /* @__PURE__ */ new Set();
+  const directHeader = response.headers.get("x-payment-protocol");
+  if (directHeader) {
+    for (const part of directHeader.split(",")) {
+      const protocol = part.trim().toLowerCase();
+      if (protocol) protocols.add(protocol);
+    }
+  }
+  const authHeader = response.headers.get("www-authenticate")?.toLowerCase() ?? "";
+  if (authHeader.includes("x402")) protocols.add("x402");
+  if (authHeader.includes("mpp")) protocols.add("mpp");
+  return [...protocols];
+}
+async function runProbeStage(options) {
+  const candidates = options.probeCandidates ?? [];
+  if (candidates.length === 0) {
+    return {
+      stage: "probe",
+      valid: false,
+      resources: [],
+      warnings: [
+        warning(
+          "PROBE_STAGE_SKIPPED",
+          "info",
+          "Probe stage skipped because no probe candidates were provided.",
+          { stage: "probe" }
+        )
+      ]
+    };
+  }
+  const resources = [];
+  const warnings = [];
+  for (const candidate of candidates) {
+    const path = normalizePath(candidate.path);
+    const methods = candidate.methods?.length ? candidate.methods : DEFAULT_PROBE_METHODS;
+    for (const method of methods) {
+      const url = `${options.origin}${path}`;
+      try {
+        const response = await options.fetcher(url, {
+          method,
+          headers: {
+            Accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+            ...options.headers
+          },
+          signal: options.signal
+        });
+        if (response.status !== 402 && (response.status < 200 || response.status >= 300)) {
+          continue;
+        }
+        let authHint = response.status === 402 ? "paid" : "unprotected";
+        if (response.status === 402) {
+          try {
+            const payload = await response.clone().json();
+            authHint = detectAuthHintFrom402Payload(payload);
+          } catch {
+          }
+        }
+        const protocolHints = detectProtocols(response);
+        resources.push(
+          createResource(
+            {
+              origin: options.origin,
+              method,
+              path,
+              source: "probe",
+              summary: `${method} ${path}`,
+              authHint,
+              ...protocolHints.length ? { protocolHints } : {}
+            },
+            0.6,
+            "runtime_verified"
+          )
+        );
+      } catch (error) {
+        warnings.push(
+          warning(
+            "FETCH_FAILED",
+            "info",
+            `Probe ${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
+            { stage: "probe" }
+          )
+        );
+      }
+    }
+  }
+  return {
+    stage: "probe",
+    valid: resources.length > 0,
+    resources,
+    warnings
+  };
+}
+
+// src/core/upgrade.ts
+var UPGRADE_WARNING_CODES = [
+  "LEGACY_WELL_KNOWN_USED",
+  "LEGACY_DNS_USED",
+  "LEGACY_DNS_PLAIN_URL",
+  "LEGACY_INSTRUCTIONS_USED",
+  "LEGACY_OWNERSHIP_PROOFS_USED",
+  "OPENAPI_AUTH_MODE_MISSING",
+  "OPENAPI_TOP_LEVEL_INVALID"
+];
+var UPGRADE_WARNING_CODE_SET = new Set(UPGRADE_WARNING_CODES);
+function computeUpgradeSignal(warnings) {
+  const reasons = warnings.map((entry) => entry.code).filter((code, index, list) => list.indexOf(code) === index).filter((code) => UPGRADE_WARNING_CODE_SET.has(code));
+  return {
+    upgradeSuggested: reasons.length > 0,
+    upgradeReasons: reasons
+  };
+}
+
+// src/core/discovery.ts
+function mergeResources(target, incoming, resourceWarnings) {
+  const warnings = [];
+  for (const resource of incoming) {
+    const existing = target.get(resource.resourceKey);
+    if (!existing) {
+      target.set(resource.resourceKey, resource);
+      continue;
+    }
+    const conflict = existing.authHint !== resource.authHint || existing.priceHint !== resource.priceHint || JSON.stringify(existing.protocolHints ?? []) !== JSON.stringify(resource.protocolHints ?? []);
+    if (conflict) {
+      const conflictWarning = warning(
+        "CROSS_SOURCE_CONFLICT",
+        "warn",
+        `Resource conflict for ${resource.resourceKey}; keeping higher-precedence source ${existing.source} over ${resource.source}.`,
+        {
+          resourceKey: resource.resourceKey
+        }
+      );
+      warnings.push(conflictWarning);
+      resourceWarnings[resource.resourceKey] = [
+        ...resourceWarnings[resource.resourceKey] ?? [],
+        conflictWarning
+      ];
+      continue;
+    }
+    target.set(resource.resourceKey, {
+      ...existing,
+      summary: existing.summary ?? resource.summary,
+      links: { ...resource.links, ...existing.links },
+      confidence: Math.max(existing.confidence ?? 0, resource.confidence ?? 0)
+    });
+  }
+  return warnings;
+}
+function toTrace(stageResult, startedAt) {
+  return {
+    stage: stageResult.stage,
+    attempted: true,
+    valid: stageResult.valid,
+    resourceCount: stageResult.resources.length,
+    durationMs: Date.now() - startedAt,
+    warnings: stageResult.warnings,
+    ...stageResult.links ? { links: stageResult.links } : {}
+  };
+}
+async function runOverrideStage(options) {
+  const warnings = [];
+  for (const overrideUrl of options.overrideUrls) {
+    const normalized = overrideUrl.trim();
+    if (!normalized) continue;
+    try {
+      const response = await options.fetcher(normalized, {
+        method: "GET",
+        headers: { Accept: "application/json, text/plain;q=0.9", ...options.headers },
+        signal: options.signal
+      });
+      if (!response.ok) {
+        warnings.push(
+          warning(
+            "FETCH_FAILED",
+            "warn",
+            `Override fetch failed (${response.status}) at ${normalized}`,
+            {
+              stage: "override"
+            }
+          )
+        );
+        continue;
+      }
+      const bodyText = await response.text();
+      let parsedJson;
+      try {
+        parsedJson = JSON.parse(bodyText);
+      } catch {
+        parsedJson = void 0;
+      }
+      if (parsedJson && typeof parsedJson === "object" && !Array.isArray(parsedJson) && "openapi" in parsedJson && "paths" in parsedJson) {
+        const openapiResult = await runOpenApiStage({
+          origin: options.origin,
+          fetcher: async (input, init) => {
+            const inputString = String(input);
+            if (inputString === `${options.origin}/openapi.json` || inputString === `${options.origin}/.well-known/openapi.json`) {
+              return new Response(bodyText, {
+                status: 200,
+                headers: { "content-type": "application/json" }
+              });
+            }
+            return options.fetcher(input, init);
+          },
+          headers: options.headers,
+          signal: options.signal,
+          includeRaw: options.includeRaw
+        });
+        return {
+          ...openapiResult,
+          stage: "override",
+          warnings: [
+            warning("OVERRIDE_USED", "info", `Using explicit override source ${normalized}`, {
+              stage: "override"
+            }),
+            ...openapiResult.warnings
+          ]
+        };
+      }
+      if (parsedJson && typeof parsedJson === "object" && !Array.isArray(parsedJson)) {
+        const parsedWellKnown = parseWellKnownPayload(parsedJson, options.origin, normalized);
+        if (parsedWellKnown.resources.length > 0) {
+          return {
+            stage: "override",
+            valid: true,
+            resources: parsedWellKnown.resources,
+            warnings: [
+              warning("OVERRIDE_USED", "info", `Using explicit override source ${normalized}`, {
+                stage: "override"
+              }),
+              ...parsedWellKnown.warnings
+            ],
+            links: { discoveryUrl: normalized },
+            ...options.includeRaw ? { raw: parsedWellKnown.raw } : {}
+          };
+        }
+      }
+    } catch (error) {
+      warnings.push(
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `Override fetch exception at ${normalized}: ${error instanceof Error ? error.message : String(error)}`,
+          { stage: "override" }
+        )
+      );
+      continue;
+    }
+    const fallbackWellKnownResult = await runWellKnownX402Stage({
+      origin: options.origin,
+      url: normalized,
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal,
+      includeRaw: options.includeRaw
+    });
+    if (fallbackWellKnownResult.valid) {
+      return {
+        ...fallbackWellKnownResult,
+        stage: "override",
+        warnings: [
+          warning("OVERRIDE_USED", "info", `Using explicit override source ${normalized}`, {
+            stage: "override"
+          }),
+          ...fallbackWellKnownResult.warnings
+        ]
+      };
+    }
+    warnings.push(...fallbackWellKnownResult.warnings);
+  }
+  return {
+    stage: "override",
+    valid: false,
+    resources: [],
+    warnings
+  };
+}
+async function runDiscovery({
+  detailed,
+  options
+}) {
+  const fetcher = options.fetcher ?? fetch;
+  const compatMode = options.compatMode ?? DEFAULT_COMPAT_MODE;
+  const strictCompat = compatMode === "strict";
+  const rawView = detailed ? options.rawView ?? "none" : "none";
+  const includeRaw = rawView === "full";
+  const includeInteropMpp = detailed && Boolean(options.includeInteropMpp);
+  const origin = normalizeOrigin(options.target);
+  const warnings = [];
+  const trace = [];
+  const resourceWarnings = {};
+  const rawSources = {};
+  const merged = /* @__PURE__ */ new Map();
+  if (compatMode !== "off") {
+    warnings.push(
+      warning(
+        "COMPAT_MODE_ENABLED",
+        compatMode === "strict" ? "warn" : "info",
+        `Compatibility mode is '${compatMode}'. Legacy adapters are active.`
+      )
+    );
+  }
+  const stages = [];
+  if (options.overrideUrls && options.overrideUrls.length > 0) {
+    stages.push(
+      () => runOverrideStage({
+        origin,
+        overrideUrls: options.overrideUrls ?? [],
+        fetcher,
+        headers: options.headers,
+        signal: options.signal,
+        includeRaw
+      })
+    );
+  }
+  stages.push(
+    () => runOpenApiStage({
+      origin,
+      fetcher,
+      headers: options.headers,
+      signal: options.signal,
+      includeRaw
+    })
+  );
+  if (compatMode !== "off") {
+    stages.push(
+      () => runWellKnownX402Stage({
+        origin,
+        fetcher,
+        headers: options.headers,
+        signal: options.signal,
+        includeRaw
+      })
+    );
+    stages.push(
+      () => runDnsStage({
+        origin,
+        fetcher,
+        txtResolver: options.txtResolver,
+        headers: options.headers,
+        signal: options.signal,
+        includeRaw
+      })
+    );
+    if (includeInteropMpp) {
+      stages.push(
+        () => runInteropMppStage({
+          origin,
+          fetcher,
+          headers: options.headers,
+          signal: options.signal,
+          includeRaw
+        })
+      );
+    }
+  }
+  stages.push(
+    () => runProbeStage({
+      origin,
+      fetcher,
+      headers: options.headers,
+      signal: options.signal,
+      probeCandidates: options.probeCandidates
+    })
+  );
+  let selectedStage;
+  for (const runStage of stages) {
+    const startedAt = Date.now();
+    const stageResult = await runStage();
+    stageResult.warnings = applyStrictEscalation(stageResult.warnings, strictCompat);
+    trace.push(toTrace(stageResult, startedAt));
+    warnings.push(...stageResult.warnings);
+    if (stageResult.resources.length > 0) {
+      for (const stageWarning of stageResult.warnings) {
+        if (stageWarning.resourceKey) {
+          resourceWarnings[stageWarning.resourceKey] = [
+            ...resourceWarnings[stageWarning.resourceKey] ?? [],
+            stageWarning
+          ];
+        }
+      }
+    }
+    if (!stageResult.valid) {
+      continue;
+    }
+    const mergeWarnings = mergeResources(merged, stageResult.resources, resourceWarnings);
+    warnings.push(...mergeWarnings);
+    if (includeRaw && stageResult.raw !== void 0) {
+      if (stageResult.stage === "openapi" || stageResult.stage === "override") {
+        const rawObject = stageResult.raw;
+        if (rawObject.openapi !== void 0) rawSources.openapi = rawObject.openapi;
+        if (typeof rawObject.llmsTxt === "string") rawSources.llmsTxt = rawObject.llmsTxt;
+      }
+      if (stageResult.stage === "well-known/x402" || stageResult.stage === "override") {
+        rawSources.wellKnownX402 = [...rawSources.wellKnownX402 ?? [], stageResult.raw];
+      }
+      if (stageResult.stage === "dns/_x402") {
+        const rawObject = stageResult.raw;
+        if (Array.isArray(rawObject.dnsRecords)) {
+          rawSources.dnsRecords = rawObject.dnsRecords;
+        }
+      }
+      if (stageResult.stage === "interop/mpp") {
+        rawSources.interopMpp = stageResult.raw;
+      }
+    }
+    if (!detailed) {
+      selectedStage = selectedStage ?? stageResult.stage;
+      break;
+    }
+  }
+  if (merged.size === 0) {
+    warnings.push(
+      warning(
+        "NO_DISCOVERY_SOURCES",
+        "error",
+        "No discovery stage returned first-valid-non-empty results."
+      )
+    );
+  }
+  const dedupedWarnings = dedupeWarnings(warnings);
+  const upgradeSignal = computeUpgradeSignal(dedupedWarnings);
+  const resources = [...merged.values()];
+  if (!detailed) {
+    return {
+      origin,
+      resources,
+      warnings: dedupedWarnings,
+      compatMode,
+      ...upgradeSignal,
+      ...selectedStage ? { selectedStage } : {}
+    };
+  }
+  return {
+    origin,
+    resources,
+    warnings: dedupedWarnings,
+    compatMode,
+    ...upgradeSignal,
+    selectedStage: trace.find((entry) => entry.valid)?.stage,
+    trace,
+    resourceWarnings,
+    ...includeRaw ? { rawSources } : {}
+  };
+}
+
+// src/index.ts
+async function discoverDetailed(options) {
+  return await runDiscovery({ detailed: true, options });
+}
+
+// src/cli/run.ts
+var CLI_USER_AGENT = "@agentcash/discovery-cli/0.1";
+function buildProbeCandidates(resources) {
+  const methodsByPath = /* @__PURE__ */ new Map();
+  for (const resource of resources) {
+    const existing = methodsByPath.get(resource.path) ?? /* @__PURE__ */ new Set();
+    existing.add(resource.method);
+    methodsByPath.set(resource.path, existing);
+  }
+  return [...methodsByPath.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([path, methods]) => ({ path, methods: [...methods].sort() }));
+}
+function createTimeoutFetcher(timeoutMs, fetchImpl) {
+  return async (input, init = {}) => {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    if (init.signal) {
+      if (init.signal.aborted) {
+        clearTimeout(timer);
+        throw new Error("Request aborted");
+      }
+      init.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    try {
+      return await fetchImpl(input, {
+        ...init,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+      init.signal?.removeEventListener("abort", onAbort);
+    }
+  };
+}
+async function runAudit(options, deps = {}) {
+  const discoverDetailedFn = deps.discoverDetailedFn ?? discoverDetailed;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const fetcher = createTimeoutFetcher(options.timeoutMs, fetchImpl);
+  const baseOptions = {
+    target: options.target,
+    compatMode: options.compatMode,
+    fetcher,
+    headers: {
+      "user-agent": CLI_USER_AGENT
+    },
+    rawView: "none"
+  };
+  const startedAt = Date.now();
+  let result = await discoverDetailedFn(baseOptions);
+  let probeCandidateCount = 0;
+  if (options.probe) {
+    const probeCandidates = buildProbeCandidates(result.resources);
+    probeCandidateCount = probeCandidates.length;
+    if (probeCandidates.length > 0) {
+      result = await discoverDetailedFn({
+        ...baseOptions,
+        probeCandidates
+      });
+    }
+  }
+  return {
+    result,
+    durationMs: Date.now() - startedAt,
+    probeCandidateCount
+  };
+}
+
+// src/cli.ts
+function defaultStdout(message) {
+  process.stdout.write(`${message}
+`);
+}
+function defaultStderr(message) {
+  process.stderr.write(`${message}
+`);
+}
+async function main(argv = process.argv.slice(2), deps = {}) {
+  const stdout = deps.stdout ?? defaultStdout;
+  const stderr = deps.stderr ?? defaultStderr;
+  const parsed = parseCliArgs(argv);
+  if (parsed.kind === "help") {
+    stdout(renderHelp());
+    return 0;
+  }
+  if (parsed.kind === "error") {
+    stderr(parsed.message);
+    stderr("");
+    stderr(renderHelp());
+    return 2;
+  }
+  try {
+    const run = await runAudit(parsed.options, deps);
+    if (parsed.options.json) {
+      stdout(renderJson(run, parsed.options));
+    } else if (parsed.options.verbose) {
+      stdout(renderVerbose(run, parsed.options));
+    } else {
+      stdout(renderSummary(run, parsed.options));
+    }
+    return run.result.resources.length > 0 ? 0 : 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr(`Discovery audit failed: ${message}`);
+    return 2;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main
+});