@agentcash/discovery

Canonical discovery runtime for the agentcash ecosystem.

Use one library for CLI, server, and client so discovery behavior is identical everywhere.

Why One Library

• Same parsing logic across surfaces: no CLI/server/client drift.
• 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

• L0 trigger layer: intents like x402, pay for should route to agentcash.
• L1 installed domain index: which domains are installed and when to fan out.
• L2 domain resources: token-light list (discover <domain>).
• L3 resource details: schema and deep metadata (discover <domain> --verbose).
• L4 domain guidance: unstructured guidance (llms.txt) when available.
• L5 cross-domain composition: intentionally out of scope for discovery v1.

Design rule: L0 + L1 are zero-hop critical. L2+ should be fetched on demand.

Install

pnpm add @agentcash/discovery

CLI Usage

Quick audit:

npx @agentcash/discovery stabletravel.dev

Verbose matrices:

npx @agentcash/discovery stabletravel.dev -v

Machine-readable output:

npx @agentcash/discovery stabletravel.dev --json

L0-L5 context harness summary for a client:

npx @agentcash/discovery stabletravel.dev --harness --client claude-code

L0-L5 harness verbose with explicit budget:

npx @agentcash/discovery stabletravel.dev --harness -v --client skill-cli --context-window-tokens 200000

Useful flags:

• --compat on|off|strict
• --probe
• --timeout-ms <ms>
• --no-truncate
• --no-color

Programmatic Usage

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

Discovery Waterfall

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)

Behavior:

• discover(...) stops at first valid non-empty stage.
• discoverDetailed(...) runs full waterfall and merges deterministically.

Validation behavior:

• 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.

Compatibility Modes

• on (default): legacy adapters enabled.
• off: canonical-only behavior.
• strict: legacy adapters enabled, selected warnings escalated.

Contract Guarantees

Resource identity:

${origin} ${method} ${path}

Required normalized fields:

• resourceKey
• origin
• method
• path
• source
• verified (default false)

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:

SCAN_DATABASE_URL='postgresql://...' pnpm audit:registry

Quick sample:

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