@agentcash/discovery 1.0.1 → 1.1.0

package/README.md

@@ -2,14 +2,14 @@
 
 Canonical discovery runtime for the agentcash ecosystem.
 
-Use one library for CLI, server, and client so discovery behavior is identical everywhere.
+Use one library for MCP, CLI, router, and audit so discovery behavior is identical everywhere.
 
 ## Why One Library
 
 - Same parsing logic across surfaces: no CLI/server/client drift.
+- Shared Zod schema that the router can test against at compile-time.
 - Same warning codes and precedence rules: fewer integration surprises.
 - Same compatibility adapters in one place: legacy behavior is isolated and removable.
-- Same L0-L5 harness model: easier context-budget auditing and rollout decisions.
 
 ## L0-L5 Mental Model
 
@@ -22,196 +22,128 @@ Use one library for CLI, server, and client so discovery behavior is identical e
 
 Design rule: `L0` + `L1` are zero-hop critical. `L2+` should be fetched on demand.
 
+In practice, each layer should guide the agent to discover the next:
+
+| Layer  | Surface                                             | What the agent gets                                                                                                                          |
+| ------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **L0** | MCP tool description / `agentcash --help`           | First impression of agentcash. Should encourage the agent to use it and explicitly explain `discoverOriginSchema` and `checkEndpointSchema`. |
+| **L1** | Same location as L0                                 | List of domains available to the agent. Each entry should be descriptive enough for the agent to understand what it does at a high level.    |
+| **L2** | `discoverOriginSchema` result                       | Detailed description of the origin and its supported endpoints.                                                                              |
+| **L3** | `checkEndpointSchema` result                        | Specific guidance for a single endpoint: input/output schema, auth mode, and a detailed description of what the endpoint does.               |
+| **L4** | `discoverOriginSchema` with `includeGuidance: true` | Composition guidance for 2+ resources at an origin. Sourced from the `guidance` field in OpenAPI.                                            |
+
 ## Install
 
 ```bash
 pnpm add @agentcash/discovery
 ```
 
-## CLI Usage
+## CLI
 
-Quick audit:
+Two commands: `discover` (list endpoints at an origin) and `check` (inspect a specific URL).
 
 ```bash
+# Discover all endpoints at an origin
 npx @agentcash/discovery stabletravel.dev
-```
+npx @agentcash/discovery discover stabletravel.dev
 
-Verbose matrices:
-
-```bash
-npx @agentcash/discovery stabletravel.dev -v
+# Inspect a specific endpoint URL
+npx @agentcash/discovery check https://stabletravel.dev/search
 ```
 
-Machine-readable output:
+Flags:
 
-```bash
-npx @agentcash/discovery stabletravel.dev --json
-```
+| Flag     | Description                                        |
+| -------- | -------------------------------------------------- |
+| `--json` | Machine-readable JSON output                       |
+| `-v`     | Verbose — includes guidance text and warning hints |
 
-L0-L5 context harness summary for a client:
+JSON output shape (`discover`):
 
-```bash
-npx @agentcash/discovery stabletravel.dev --harness --client claude-code
+```json
+{
+  "ok": true,
+  "selectedStage": "openapi",
+  "resources": [{ "resourceKey": "GET /search", "method": "GET", "path": "/search" }],
+  "warnings": [],
+  "meta": { "origin": "https://stabletravel.dev", "specUrl": "..." }
+}
 ```
 
-L0-L5 harness verbose with explicit budget:
-
-```bash
-npx @agentcash/discovery stabletravel.dev --harness -v --client skill-cli --context-window-tokens 200000
+JSON output shape (`check`):
+
+```json
+{
+  "url": "https://stabletravel.dev/search",
+  "found": true,
+  "origin": "https://stabletravel.dev",
+  "path": "/search",
+  "advisories": [{ "method": "GET", "authMode": "bearer", "estimatedPrice": "$0.01" }],
+  "warnings": []
+}
 ```
 
-Useful flags:
-
-- `--compat on|off|strict`
-- `--probe`
-- `--timeout-ms <ms>`
-- `--no-truncate`
-- `--no-color`
-
 ## Programmatic Usage
 
 ```ts
-import {
-  auditContextHarness,
-  discover,
-  discoverDetailed,
-  validatePaymentRequiredDetailed,
-  type HarnessClientId,
-} from '@agentcash/discovery';
-
-const progressive = await discover({
-  target: 'stabletravel.dev',
-  compatMode: 'on',
-});
-
-const detailed = await discoverDetailed({
-  target: 'stabletravel.dev',
-  compatMode: 'strict',
-  rawView: 'full',
-});
-
-const client: HarnessClientId = 'claude-code';
-const harness = await auditContextHarness({
-  target: 'stabletravel.dev',
-  client,
-  contextWindowTokens: 200000,
-  compatMode: 'on',
-});
-
-const validation = validatePaymentRequiredDetailed(payload, {
-  compatMode: 'strict',
-  metadata: {
-    title: 'Example API',
-    description: 'Sample description',
-    favicon: 'https://example.com/favicon.ico',
-    ogImages: [{ url: 'https://example.com/og.png' }],
-  },
-});
-```
-
-## MCP Adapter Contract
-
-This section is the canonical contract for MCP-facing discovery adapters:
-
-- `discoverForMcp(options)` for L2 resources + L4 guidance policy projection.
-- `inspectEndpointForMcp(options)` for L3 OpenAPI advisory projection.
-
-`discoverForMcp` guarantees:
-
-- `guidanceAvailable` is always present.
-- `guidanceTokens` is present when guidance exists.
-- `guidance` is included when `includeGuidance=true`, excluded when
-  `includeGuidance=false`, and auto-included under the token threshold when not
-  specified.
-
-`inspectEndpointForMcp` guarantees:
-
-- Spec-derived HTTP methods for the selected endpoint path.
-- Per-method advisory data: summary, estimated price, protocols, auth mode, and
-  input schema.
-
-Ownership boundary:
-
-- `@agentcash/discovery` owns discovery/advisory contracts.
-- Runtime probe truth (live 402 parsing/payment option extraction/divergence)
-  belongs to the `agentcash` MCP package.
-
-Reference integration boundary:
-
-- `https://github.com/Merit-Systems/agentcash/blob/main/packages/external/mcp/docs/discovery-boundary.md`
+import { discoverOriginSchema, checkEndpointSchema } from '@agentcash/discovery';
 
-## Discovery Waterfall
+// Discover all endpoints at an origin
+const result = await discoverOriginSchema({ target: 'stabletravel.dev' });
+// result.found === true → result.endpoints (L2Route[]), result.guidance?, result.guidanceTokens?
 
-Default order:
-
-1. Explicit override URLs (if provided)
-2. OpenAPI (`/openapi.json`, then `/.well-known/openapi.json`)
-3. `/.well-known/x402` (compat)
-4. DNS TXT `_x402` pointers (compat)
-5. Probe fallback (only when probe candidates are provided)
+// Inspect a specific endpoint URL
+const check = await checkEndpointSchema({ url: 'https://stabletravel.dev/search' });
+// check.found === true → check.advisories (per-method: authMode, estimatedPrice, protocols, inputSchema)
+```
 
-Behavior:
+## Exported API
 
-- `discover(...)` stops at first valid non-empty stage.
-- `discoverDetailed(...)` runs full waterfall and merges deterministically.
+### Core discovery
 
-Validation behavior:
+| Export                   | Description                                               |
+| ------------------------ | --------------------------------------------------------- |
+| `discoverOriginSchema()` | Progressive discovery — returns endpoints + advisory data |
+| `checkEndpointSchema()`  | Per-endpoint inspection — returns per-method advisories   |
 
-- `validatePaymentRequiredDetailed(...)` uses Coinbase `@x402/core` schemas as the structural base gate.
-- Product policy diagnostics (network/schema/metadata) are layered on top with stable issue codes.
+### Layer fetchers (low-level)
 
-## Compatibility Modes
+| Export                     | Layer | Description                           |
+| -------------------------- | ----- | ------------------------------------- |
+| `getOpenAPI(origin)`       | —     | Fetch OpenAPI spec from origin        |
+| `getWellKnown(origin)`     | —     | Fetch `/.well-known/x402` document    |
+| `getProbe(url, body?)`     | —     | Live endpoint probe                   |
+| `checkL2ForOpenAPI(spec)`  | L2    | Extract route list from OpenAPI       |
+| `checkL2ForWellknown(doc)` | L2    | Extract route list from well-known    |
+| `getL3(origin, path)`      | L3    | Get detailed metadata for an endpoint |
+| `checkL4ForOpenAPI(spec)`  | L4    | Extract guidance from OpenAPI         |
+| `checkL4ForWellknown(doc)` | L4    | Extract guidance from well-known      |
 
-- `on` (default): legacy adapters enabled.
-- `off`: canonical-only behavior.
-- `strict`: legacy adapters enabled, selected warnings escalated.
+### Validation
 
-## Contract Guarantees
+| Export                              | Description                                  |
+| ----------------------------------- | -------------------------------------------- |
+| `validatePaymentRequiredDetailed()` | Full 402 payload validation with diagnostics |
+| `evaluateMetadataCompleteness()`    | Metadata quality score                       |
+| `VALIDATION_CODES`                  | Stable issue code constants                  |
 
-Resource identity:
+### Audit
 
-```text
-${origin} ${method} ${path}
-```
+| Export                      | Description                    |
+| --------------------------- | ------------------------------ |
+| `getWarningsForOpenAPI()`   | Warnings for OpenAPI source    |
+| `getWarningsForWellKnown()` | Warnings for well-known source |
+| `getWarningsForL2()`        | Warnings for route list        |
+| `getWarningsForL3()`        | Warnings for endpoint metadata |
+| `getWarningsForL4()`        | Warnings for guidance layer    |
+| `AUDIT_CODES`               | Stable audit code constants    |
 
-Required normalized fields:
+Ownership boundary:
 
-- `resourceKey`
-- `origin`
-- `method`
-- `path`
-- `source`
-- `verified` (default `false`)
+- `@agentcash/discovery` owns discovery/advisory contracts.
+- `@agentcash` should own all signing logic, but should be composable with the methods for probing built in this package.
 
 Philosophy boundary:
 
 - Machine-parsable discovery metadata belongs in OpenAPI.
-- `llms.txt` is optional, unstructured guidance.
 - Discovery is advisory. Runtime payment challenge/probe is authoritative.
-
-## Internal Registry Audit Harness
-
-For x402scan registry benchmarking:
-
-```bash
-SCAN_DATABASE_URL='postgresql://...' pnpm audit:registry
-```
-
-Quick sample:
-
-```bash
-SCAN_DATABASE_URL='postgresql://...' pnpm audit:registry:quick
-```
-
-Output:
-
-- `audit/registry-audit-<timestamp>.json`
-- `audit/registry-audit-latest.json`
-
-## Deeper Docs
-
-Architecture and planning artifacts live in `.claude/`.
-
-Validation design doc:
-
-- `docs/VALIDATION_DIAGNOSTICS_DESIGN_2026-03-03.md`

package/dist/cli.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/cli.ts
@@ -76,6 +86,7 @@ var OpenApiDocSchema = import_zod.z.object({
     description: import_zod.z.string().optional(),
     guidance: import_zod.z.string().optional()
   }),
+  security: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.array(import_zod.z.string()))).optional(),
   servers: import_zod.z.array(import_zod.z.object({ url: import_zod.z.string() })).optional(),
   tags: import_zod.z.array(import_zod.z.object({ name: import_zod.z.string() })).optional(),
   components: import_zod.z.object({ securitySchemes: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional() }).optional(),
@@ -105,20 +116,31 @@ var WellKnownParsedSchema = import_zod.z.object({
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function hasSecurity(operation, scheme) {
-  return operation.security?.some((s) => scheme in s) ?? false;
-}
-function has402Response(operation) {
-  return Boolean(operation.responses?.["402"]);
+function resolveSecurityFlags(requirements, securitySchemes) {
+  let hasApiKey = false;
+  let hasSiwx = false;
+  for (const requirement of requirements) {
+    for (const schemeName of Object.keys(requirement)) {
+      if (schemeName === "siwx") {
+        hasSiwx = true;
+        continue;
+      }
+      if (schemeName === "apiKey") {
+        hasApiKey = true;
+        continue;
+      }
+      const def = securitySchemes[schemeName];
+      if (isRecord(def) && def["type"] === "apiKey") hasApiKey = true;
+    }
+  }
+  return { hasApiKey, hasSiwx };
 }
-function inferAuthMode(operation) {
+function inferAuthMode(operation, globalSecurity, securitySchemes) {
   const hasXPaymentInfo = Boolean(operation["x-payment-info"]);
-  const hasPayment = hasXPaymentInfo || has402Response(operation);
-  const hasApiKey = hasSecurity(operation, "apiKey");
-  const hasSiwx = hasSecurity(operation, "siwx");
-  if (hasPayment && hasApiKey) return "apiKey+paid";
+  const effectiveSecurity = operation.security !== void 0 && operation.security.length > 0 ? operation.security : globalSecurity ?? [];
+  const { hasApiKey, hasSiwx } = resolveSecurityFlags(effectiveSecurity, securitySchemes ?? {});
+  if (hasXPaymentInfo && hasApiKey) return "apiKey+paid";
   if (hasXPaymentInfo) return "paid";
-  if (hasPayment) return hasSiwx ? "siwx" : "paid";
   if (hasApiKey) return "apiKey";
   if (hasSiwx) return "siwx";
   return void 0;
@@ -138,10 +160,12 @@ var HTTP_METHODS = /* @__PURE__ */ new Set([
 var DEFAULT_MISSING_METHOD = "POST";
 
 // src/core/lib/url.ts
-function normalizeOrigin(target) {
+function ensureProtocol(target) {
   const trimmed = target.trim();
-  const withProtocol = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
-  const url = new URL(withProtocol);
+  return /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+}
+function normalizeOrigin(target) {
+  const url = new URL(ensureProtocol(target));
   url.pathname = "";
   url.search = "";
   url.hash = "";
@@ -180,7 +204,7 @@ function fetchSafe(url, init) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "1.0.1".includes("-mmm");
+var isMmmEnabled = () => "1.1.0".includes("-mmm");
 
 // src/core/source/openapi/index.ts
 var OpenApiParsedSchema = OpenApiDocSchema.transform((doc) => {
@@ -189,15 +213,13 @@ var OpenApiParsedSchema = OpenApiDocSchema.transform((doc) => {
     for (const httpMethod of [...HTTP_METHODS]) {
       const operation = pathItem[httpMethod.toLowerCase()];
       if (!operation) continue;
-      const authMode = inferAuthMode(operation) ?? void 0;
+      const authMode = inferAuthMode(operation, doc.security, doc.components?.securitySchemes) ?? void 0;
       if (!authMode) continue;
       const p = operation["x-payment-info"];
       const protocols = (p?.protocols ?? []).filter(
         (proto) => proto !== "mpp" || isMmmEnabled()
       );
-      if ((authMode === "paid" || authMode === "siwx") && !has402Response(operation)) continue;
-      if (authMode === "paid" && protocols.length === 0) continue;
-      const pricing = authMode === "paid" && p ? {
+      const pricing = (authMode === "paid" || authMode === "apiKey+paid") && p ? {
         pricingMode: p.pricingMode,
         ...p.price ? { price: p.price } : {},
         ...p.minPrice ? { minPrice: p.minPrice } : {},
@@ -348,6 +370,7 @@ var AUDIT_CODES = {
   L2_NO_ROUTES: "L2_NO_ROUTES",
   L2_ROUTE_COUNT_HIGH: "L2_ROUTE_COUNT_HIGH",
   L2_AUTH_MODE_MISSING: "L2_AUTH_MODE_MISSING",
+  L2_NO_PAID_ROUTES: "L2_NO_PAID_ROUTES",
   L2_PRICE_MISSING_ON_PAID: "L2_PRICE_MISSING_ON_PAID",
   L2_PROTOCOLS_MISSING_ON_PAID: "L2_PROTOCOLS_MISSING_ON_PAID",
   // ─── L3 endpoint advisory checks ─────────────────────────────────────────────
@@ -409,6 +432,15 @@ function getWarningsForL2(l2) {
     });
     return warnings;
   }
+  const hasPaidRoute = l2.routes.some((r) => r.authMode === "paid" || r.authMode === "apiKey+paid");
+  if (!hasPaidRoute) {
+    warnings.push({
+      code: AUDIT_CODES.L2_NO_PAID_ROUTES,
+      severity: "info",
+      message: "No endpoints are marked as paid or apiKey+paid.",
+      hint: "Add x-payment-info to operations that require payment so agents know which endpoints are monetized."
+    });
+  }
   if (l2.routes.length > ROUTE_COUNT_HIGH) {
     warnings.push({
       code: AUDIT_CODES.L2_ROUTE_COUNT_HIGH,
@@ -495,8 +527,8 @@ function getWarningsForL4(l4) {
       {
         code: AUDIT_CODES.L4_GUIDANCE_MISSING,
         severity: "info",
-        message: "No guidance text found (llms.txt or OpenAPI info.guidance).",
-        hint: "Add an info.guidance field to your OpenAPI spec or expose /llms.txt for agent-readable instructions."
+        message: "No guidance text found (OpenAPI info.guidance).",
+        hint: "Add an info.guidance field to your OpenAPI spec for agent-readable instructions."
       }
     ];
   }
@@ -805,54 +837,31 @@ function extractPaymentOptions4(wwwAuthenticate) {
   return options;
 }
 
-// src/core/layers/l3.ts
-function findMatchingOpenApiPath(paths, targetPath) {
-  const exact = paths[targetPath];
-  if (isRecord(exact)) return { matchedPath: targetPath, pathItem: exact };
-  for (const [specPath, entry] of Object.entries(paths)) {
-    if (!isRecord(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 (!isRecord(current)) return void 0;
-    current = current[part];
-    if (current === void 0) return void 0;
-  }
-  if (isRecord(current)) return resolveRefs(document, current, seen);
-  return current;
+// src/core/lib/resolve-ref.ts
+var import_dereference_json_schema = __toESM(require("dereference-json-schema"), 1);
+var { resolveRefSync } = import_dereference_json_schema.default;
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function resolveRefs(document, obj, seen, depth = 0) {
-  if (depth > 4) return obj;
+function deepResolveRefs(document, obj) {
   const resolved = {};
   for (const [key, value] of Object.entries(obj)) {
     if (key === "$ref" && typeof value === "string") {
-      const deref = resolveRef(document, value, seen);
-      if (isRecord(deref)) {
-        Object.assign(resolved, deref);
+      const deref = resolveRefSync(document, value);
+      if (isRecord2(deref)) {
+        Object.assign(resolved, deepResolveRefs(document, deref));
       } else {
         resolved[key] = value;
       }
       continue;
     }
-    if (isRecord(value)) {
-      resolved[key] = resolveRefs(document, value, seen, depth + 1);
+    if (isRecord2(value)) {
+      resolved[key] = deepResolveRefs(document, value);
       continue;
     }
     if (Array.isArray(value)) {
       resolved[key] = value.map(
-        (item) => isRecord(item) ? resolveRefs(document, item, seen, depth + 1) : item
+        (item) => isRecord2(item) ? deepResolveRefs(document, item) : item
       );
       continue;
     }
@@ -860,6 +869,24 @@ function resolveRefs(document, obj, seen, depth = 0) {
   }
   return resolved;
 }
+function resolveRefs(obj, document) {
+  return deepResolveRefs(document, obj);
+}
+
+// src/core/layers/l3.ts
+function findMatchingOpenApiPath(paths, targetPath) {
+  const exact = paths[targetPath];
+  if (isRecord(exact)) return { matchedPath: targetPath, pathItem: exact };
+  for (const [specPath, entry] of Object.entries(paths)) {
+    if (!isRecord(entry)) continue;
+    const pattern = specPath.replace(/\{[^}]+\}/g, "[^/]+");
+    const regex = new RegExp(`^${pattern}$`);
+    if (regex.test(targetPath)) {
+      return { matchedPath: specPath, pathItem: entry };
+    }
+  }
+  return null;
+}
 function extractRequestBodySchema(operationSchema) {
   const requestBody = operationSchema.requestBody;
   if (!isRecord(requestBody)) return void 0;
@@ -939,7 +966,7 @@ function getL3ForOpenAPI(openApi, path, method) {
   if (!matched) return null;
   const operation = matched.pathItem[method.toLowerCase()];
   if (!isRecord(operation)) return null;
-  const resolvedOperation = resolveRefs(document, operation, /* @__PURE__ */ new Set());
+  const resolvedOperation = resolveRefs(operation, document);
   const summary = typeof resolvedOperation.summary === "string" ? resolvedOperation.summary : typeof resolvedOperation.description === "string" ? resolvedOperation.description : void 0;
   return {
     source: "openapi",
@@ -985,12 +1012,12 @@ function getAdvisoriesForProbe(probe, path) {
   });
 }
 async function checkEndpointSchema(options) {
-  const endpoint = new URL(options.url);
+  const endpoint = new URL(ensureProtocol(options.url));
   const origin = normalizeOrigin(endpoint.origin);
   const path = normalizePath(endpoint.pathname || "/");
   if (options.sampleInputBody !== void 0) {
     const probeResult2 = await getProbe(
-      options.url,
+      endpoint.href,
       options.headers,
       options.signal,
       options.sampleInputBody
@@ -1015,7 +1042,7 @@ async function checkEndpointSchema(options) {
     if (advisories2.length > 0) return { found: true, origin, path, advisories: advisories2 };
     return { found: false, origin, path, cause: "not_found" };
   }
-  const probeResult = await getProbe(options.url, options.headers, options.signal);
+  const probeResult = await getProbe(endpoint.href, options.headers, options.signal);
   if (probeResult.isErr()) {
     return {
       found: false,