@agentcash/discovery 0.1.0 → 0.1.2

package/AGENTS.md

@@ -16,7 +16,6 @@ This repo implements canonical discovery logic for the agentcash ecosystem.
 
 - `src/core/*`: canonical OpenAPI-first discovery.
 - `src/compat/legacy-x402scan/*`: `/.well-known/x402` + DNS `_x402` compatibility.
-- `src/compat/interop-mpp/*`: optional registry interop adapter.
 
 ## Result Contract
 

package/README.md

@@ -1,26 +1,26 @@
 # @agentcash/discovery
 
-Canonical discovery library for the agentcash ecosystem.
+Canonical discovery runtime for the agentcash ecosystem.
 
-## What It Solves
+Use one library for CLI, server, and client so discovery behavior is identical everywhere.
 
-- One deterministic discovery contract across `agentcash`, `agentcash-router`, `the-stables`, and scanners.
-- OpenAPI-first discovery with explicit compatibility fallbacks.
-- Progressive runtime output (`discover`) and full debug/indexer output (`discoverDetailed`).
+## Why One Library
 
-## Discovery Order
+- 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.
 
-Default order is:
+## L0-L5 Mental Model
 
-1. explicit override URLs (if provided)
-2. OpenAPI (`/openapi.json`, then `/.well-known/openapi.json`)
-3. `/.well-known/x402` (compat path)
-4. DNS TXT `_x402` pointers (compat path)
-5. live probe fallback (only when probe candidates are provided)
-
-`discover` stops on the first valid non-empty stage.
+- `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.
 
-`discoverDetailed` runs the full waterfall and merges deterministically.
+Design rule: `L0` + `L1` are zero-hop critical. `L2+` should be fetched on demand.
 
 ## Install
 
@@ -28,88 +28,170 @@ Default order is:
 pnpm add @agentcash/discovery
 ```
 
-CLI audit:
+## CLI Usage
+
+Quick audit:
 
 ```bash
 npx @agentcash/discovery stabletravel.dev
+```
+
+Verbose matrices:
+
+```bash
 npx @agentcash/discovery stabletravel.dev -v
+```
+
+Machine-readable output:
+
+```bash
 npx @agentcash/discovery stabletravel.dev --json
 ```
 
-## Usage
+L0-L5 context harness summary for a client:
 
-```ts
-import { discover, discoverDetailed } from '@agentcash/discovery';
+```bash
+npx @agentcash/discovery stabletravel.dev --harness --client claude-code
+```
+
+L0-L5 harness verbose with explicit budget:
 
-const result = await discover({
-  target: 'https://api.example.com',
+```bash
+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
+
+```ts
+import {
+  auditContextHarness,
+  discover,
+  discoverDetailed,
+  type HarnessClientId,
+} from '@agentcash/discovery';
+
+const progressive = await discover({
+  target: 'stabletravel.dev',
   compatMode: 'on',
 });
 
 const detailed = await discoverDetailed({
-  target: 'api.example.com',
+  target: 'stabletravel.dev',
   compatMode: 'strict',
   rawView: 'full',
-  includeInteropMpp: true,
-  txtResolver: async (fqdn) => {
-    // Provide DNS TXT lookup in your runtime.
-    return [];
-  },
+});
+
+const client: HarnessClientId = 'claude-code';
+const harness = await auditContextHarness({
+  target: 'stabletravel.dev',
+  client,
+  contextWindowTokens: 200000,
+  compatMode: 'on',
 });
 ```
 
-## Key API
+## MCP Adapter Contract
 
-- `discover(options)`: token-light, progressive, first-valid-non-empty.
-- `discoverDetailed(options)`: full trace/details, merge across stages, optional raw artifacts.
-- Both results include:
-- `upgradeSuggested` (`boolean`)
-- `upgradeReasons` (`string[]` warning-code reasons such as legacy-path usage)
+This section is the canonical contract for MCP-facing discovery adapters:
 
-## Compatibility Controls
+- `discoverForMcp(options)` for L2 resources + L4 guidance policy projection.
+- `inspectEndpointForMcp(options)` for L3 OpenAPI advisory projection.
 
-- `compatMode: 'on'` (default): enable legacy adapters.
-- `compatMode: 'off'`: disable all legacy adapters.
-- `compatMode: 'strict'`: enable legacy adapters and escalate legacy warnings to errors.
+`discoverForMcp` guarantees:
 
-## Internal Registry Audit Harness
+- `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.
 
-Use this to benchmark compatibility against the x402scan registry dataset.
+`inspectEndpointForMcp` guarantees:
 
-```bash
-SCAN_DATABASE_URL='postgresql://...' pnpm audit:registry
-```
+- Spec-derived HTTP methods for the selected endpoint path.
+- Per-method advisory data: summary, estimated price, protocols, auth mode, and
+  input schema.
 
-Quick sample mode:
+Ownership boundary:
 
-```bash
-SCAN_DATABASE_URL='postgresql://...' pnpm audit:registry:quick
-```
+- `@agentcash/discovery` owns discovery/advisory contracts.
+- Runtime probe truth (live 402 parsing/payment option extraction/divergence)
+  belongs to the `agentcash` MCP package.
 
-Outputs are written to:
+Reference integration boundary:
 
-- `audit/registry-audit-<timestamp>.json`
-- `audit/registry-audit-latest.json`
+- `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)
 
-## Canonical Contract
+Behavior:
 
-Each normalized resource key is:
+- `discover(...)` stops at first valid non-empty stage.
+- `discoverDetailed(...)` runs full waterfall and merges deterministically.
+
+## Compatibility Modes
+
+- `on` (default): legacy adapters enabled.
+- `off`: canonical-only behavior.
+- `strict`: legacy adapters enabled, selected warnings escalated.
+
+## Contract Guarantees
+
+Resource identity:
 
 ```text
 ${origin} ${method} ${path}
 ```
 
-Required per-resource fields:
+Required normalized fields:
 
 - `resourceKey`
 - `origin`
 - `method`
 - `path`
 - `source`
-- `verified` (defaults to `false`)
+- `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:
+
+```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`
 
-## Philosophy Boundary
+## Deeper Docs
 
-- Machine-parsable discovery metadata lives in OpenAPI.
-- `llms.txt` is unstructured, optional domain guidance.
-- Discovery is advisory. Runtime challenge/probe is authoritative.
+Architecture and planning artifacts live in `.claude/`.