@agentcash/discovery 1.6.4 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/AGENTS.md +2 -3
  2. package/README.md +123 -101
  3. package/dist/cli.cjs +1365 -850
  4. package/dist/cli.js +1366 -851
  5. package/dist/index.cjs +1402 -892
  6. package/dist/index.d.cts +17 -126
  7. package/dist/index.d.ts +17 -126
  8. package/dist/index.js +1390 -878
  9. package/dist/schemas.cjs +1250 -530
  10. package/dist/schemas.d.cts +1 -32
  11. package/dist/schemas.d.ts +1 -32
  12. package/dist/schemas.js +1249 -527
  13. package/docs/SPECIFICATION.md +270 -0
  14. package/docs/VALIDATION_DIAGNOSTICS_DESIGN_2026-03-03.md +117 -0
  15. package/package.json +24 -22
  16. package/dist/flags.cjs +0 -44
  17. package/dist/flags.d.cts +0 -6
  18. package/dist/flags.d.ts +0 -6
  19. package/dist/flags.js +0 -17
package/AGENTS.md CHANGED
@@ -6,16 +6,15 @@ This repo implements canonical discovery logic for the agentcash ecosystem.
6
6
 
7
7
  ## Hard Constraints
8
8
 
9
- 1. Keep canonical core and compatibility modules physically separate.
9
+ 1. OpenAPI is the only machine discovery source — no legacy parsing.
10
10
  2. Avoid legacy conditionals in `src/core/*`.
11
11
  3. Preserve stable warning codes.
12
12
  4. Keep `discover` token-light and deterministic.
13
- 5. Keep compatibility removable via a single top-level mode.
14
13
 
15
14
  ## Module Boundaries
16
15
 
17
16
  - `src/core/*`: canonical OpenAPI-first discovery.
18
- - `src/compat/legacy-x402scan/*`: `/.well-known/x402` + DNS `_x402` compatibility.
17
+ - `src/audit/legacy-well-known.ts`: shallow presence probe for `/.well-known/x402` and `/.well-known/mpp` that emits a single `LEGACY_WELL_KNOWN_FOUND` migration warning. No parsing.
19
18
 
20
19
  ## Result Contract
21
20
 
package/README.md CHANGED
@@ -1,36 +1,29 @@
1
1
  # @agentcash/discovery
2
2
 
3
- Canonical discovery runtime for the agentcash ecosystem.
3
+ Canonical TypeScript discovery runtime and v1 specification for agent-facing paid APIs.
4
4
 
5
- Use one library for MCP, CLI, router, and audit so discovery behavior is identical everywhere.
5
+ Agentcash Discovery gives agents a small, deterministic way to answer: "What can I call at this
6
+ origin, what auth or payment should I expect, and where do I fetch details only when I need them?"
6
7
 
7
- ## Why One Library
8
+ ## Status
8
9
 
9
- - Same parsing logic across surfaces: no CLI/server/client drift.
10
- - Shared Zod schema that the router can test against at compile-time.
11
- - Same warning codes and precedence rules: fewer integration surprises.
12
- - Same compatibility adapters in one place: legacy behavior is isolated and removable.
10
+ - Specification: [Agentcash Discovery v1](docs/SPECIFICATION.md)
11
+ - Runtime package: `@agentcash/discovery`
12
+ - Stability: public draft, production-oriented APIs
13
13
 
14
- ## L0-L5 Mental Model
14
+ ## Why This Exists
15
15
 
16
- - `L0` trigger layer: intents like `x402`, `pay for` should route to agentcash.
17
- - `L1` installed domain index: which domains are installed and when to fan out.
18
- - `L2` domain resources: token-light list (`discover <domain>`).
19
- - `L3` resource details: schema and deep metadata (`discover <domain> --verbose`).
20
- - `L4` domain guidance: unstructured guidance (`llms.txt`) when available.
21
- - `L5` cross-domain composition: intentionally out of scope for discovery v1.
16
+ Agentic commerce needs discovery that is boring in the best way: deterministic, typed, inspectable,
17
+ and cheap enough to place in an agent loop.
22
18
 
23
- Design rule: `L0` + `L1` are zero-hop critical. `L2+` should be fetched on demand.
19
+ This package centralizes discovery behavior for the agentcash ecosystem:
24
20
 
25
- In practice, each layer should guide the agent to discover the next:
26
-
27
- | Layer | Surface | What the agent gets |
28
- | ------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
29
- | **L0** | MCP tool description / `agentcash --help` | First impression of agentcash. Should encourage the agent to use it and explicitly explain `discoverOriginSchema` and `checkEndpointSchema`. |
30
- | **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. |
31
- | **L2** | `discoverOriginSchema` result | Detailed description of the origin and its supported endpoints. |
32
- | **L3** | `checkEndpointSchema` result | Specific guidance for a single endpoint: input/output schema, auth mode, and a detailed description of what the endpoint does. |
33
- | **L4** | `discoverOriginSchema` with `includeGuidance: true` | Composition guidance for 2+ resources at an origin. Sourced from the `guidance` field in OpenAPI. |
21
+ - OpenAPI-only resource discovery.
22
+ - Stable resource identity: `origin + method + path`.
23
+ - Advisory auth, pricing, protocol, schema, and guidance metadata.
24
+ - Runtime probes for live 402/payment truth.
25
+ - Stable audit and validation warning codes.
26
+ - Namespaced OpenAPI extensions that can compose with future standards such as Agent Auth.
34
27
 
35
28
  ## Install
36
29
 
@@ -38,112 +31,141 @@ In practice, each layer should guide the agent to discover the next:
38
31
  pnpm add @agentcash/discovery
39
32
  ```
40
33
 
41
- ## CLI
34
+ Node.js 20 or newer is required.
42
35
 
43
- Two commands: `discover` (list endpoints at an origin) and `check` (inspect a specific URL).
36
+ ## CLI
44
37
 
45
38
  ```bash
46
- # Discover all endpoints at an origin
47
- npx @agentcash/discovery stabletravel.dev
48
- npx @agentcash/discovery discover stabletravel.dev
39
+ # Discover token-light resource metadata for an origin
40
+ npx @agentcash/discovery stableenrich.dev
41
+ npx @agentcash/discovery discover stableenrich.dev
42
+
43
+ # Inspect one endpoint and fetch schemas/payment advisories
44
+ npx @agentcash/discovery check https://stableenrich.dev/api/search
49
45
 
50
- # Inspect a specific endpoint URL
51
- npx @agentcash/discovery check https://stabletravel.dev/search
46
+ # Machine-readable output
47
+ npx @agentcash/discovery discover stableenrich.dev --json
52
48
  ```
53
49
 
54
50
  Flags:
55
51
 
56
- | Flag | Description |
57
- | -------- | -------------------------------------------------- |
58
- | `--json` | Machine-readable JSON output |
59
- | `-v` | Verbose — includes guidance text and warning hints |
52
+ | Flag | Description |
53
+ | ----------------- | --------------------------------------- |
54
+ | `--json` | Machine-readable JSON output |
55
+ | `-v`, `--verbose` | Include guidance text and warning hints |
60
56
 
61
- JSON output shape (`discover`):
57
+ ## Programmatic Usage
62
58
 
63
- ```json
64
- {
65
- "ok": true,
66
- "selectedStage": "openapi",
67
- "resources": [{ "resourceKey": "GET /search", "method": "GET", "path": "/search" }],
68
- "warnings": [],
69
- "meta": { "origin": "https://stabletravel.dev", "specUrl": "..." }
70
- }
71
- ```
59
+ ```ts
60
+ import { discoverOriginSchema, checkEndpointSchema, GuidanceMode } from '@agentcash/discovery';
72
61
 
73
- JSON output shape (`check`):
62
+ const discovery = await discoverOriginSchema({
63
+ target: 'stableenrich.dev',
64
+ guidance: GuidanceMode.Auto,
65
+ });
74
66
 
75
- ```json
76
- {
77
- "url": "https://stabletravel.dev/search",
78
- "found": true,
79
- "origin": "https://stabletravel.dev",
80
- "path": "/search",
81
- "advisories": [{ "method": "GET", "authMode": "bearer", "estimatedPrice": "$0.01" }],
82
- "warnings": []
67
+ if (discovery.found) {
68
+ for (const endpoint of discovery.endpoints) {
69
+ console.log(endpoint.resourceKey, endpoint.authMode, endpoint.price);
70
+ }
83
71
  }
72
+
73
+ const endpoint = await checkEndpointSchema({
74
+ url: 'https://stableenrich.dev/api/search',
75
+ probe: true,
76
+ });
84
77
  ```
85
78
 
86
- ## Programmatic Usage
79
+ `discoverOriginSchema()` is the L2 route-list API. It stays token-light and stops after the first
80
+ valid non-empty source.
87
81
 
88
- ```ts
89
- import { discoverOriginSchema, checkEndpointSchema } from '@agentcash/discovery';
82
+ `checkEndpointSchema()` is the L3 endpoint-detail API. It returns per-method advisories, request
83
+ and response schemas when known, and live payment options when probing is enabled.
90
84
 
91
- // Discover all endpoints at an origin
92
- const result = await discoverOriginSchema({ target: 'stabletravel.dev' });
93
- // result.found === true → result.endpoints (L2Route[]), result.guidance?, result.guidanceTokens?
85
+ ## Discovery Model
94
86
 
95
- // Inspect a specific endpoint URL
96
- const check = await checkEndpointSchema({ url: 'https://stabletravel.dev/search' });
97
- // check.found === true → check.advisories (per-method: authMode, estimatedPrice, protocols, inputSchema)
87
+ Discovery order:
88
+
89
+ 1. Caller-supplied OpenAPI override URL.
90
+ 2. `GET /openapi.json`.
91
+
92
+ If no OpenAPI spec is found, discovery returns `{ found: false, cause: 'not_found' }`. Legacy
93
+ `/.well-known/x402`, `/.well-known/mpp`, and DNS `_x402` records are no longer parsed; call
94
+ `probeLegacyWellKnown()` to detect their presence and emit a single `LEGACY_WELL_KNOWN_FOUND`
95
+ migration warning.
96
+
97
+ Resource identity is always:
98
+
99
+ ```text
100
+ ${origin} ${method} ${path}
98
101
  ```
99
102
 
100
- ## Exported API
103
+ Example:
104
+
105
+ ```text
106
+ https://api.example.com POST /search
107
+ ```
101
108
 
102
- ### Core discovery
109
+ Discovery is advisory. Runtime payment/auth facts come from the live endpoint challenge.
103
110
 
104
- | Export | Description |
105
- | ------------------------ | --------------------------------------------------------- |
106
- | `discoverOriginSchema()` | Progressive discovery — returns endpoints + advisory data |
107
- | `checkEndpointSchema()` | Per-endpoint inspection — returns per-method advisories |
111
+ ## OpenAPI Profile
108
112
 
109
- ### Layer fetchers (low-level)
113
+ New providers should use OpenAPI `security` for auth and `x-payment-info` for payment:
110
114
 
111
- | Export | Layer | Description |
112
- | -------------------------- | ----- | ------------------------------------- |
113
- | `getOpenAPI(origin)` | — | Fetch OpenAPI spec from origin |
114
- | `getWellKnown(origin)` | — | Fetch `/.well-known/x402` document |
115
- | `getProbe(url, body?)` | — | Live endpoint probe |
116
- | `checkL2ForOpenAPI(spec)` | L2 | Extract route list from OpenAPI |
117
- | `checkL2ForWellknown(doc)` | L2 | Extract route list from well-known |
118
- | `getL3(origin, path)` | L3 | Get detailed metadata for an endpoint |
119
- | `checkL4ForOpenAPI(spec)` | L4 | Extract guidance from OpenAPI |
120
- | `checkL4ForWellknown(doc)` | L4 | Extract guidance from well-known |
115
+ ```json
116
+ {
117
+ "openapi": "3.1.0",
118
+ "info": { "title": "Example API", "version": "1.0.0" },
119
+ "paths": {
120
+ "/search": {
121
+ "post": {
122
+ "summary": "Search records",
123
+ "security": [],
124
+ "x-payment-info": {
125
+ "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
126
+ "protocols": [{ "x402": {} }]
127
+ },
128
+ "responses": {
129
+ "200": { "description": "OK" },
130
+ "402": { "description": "Payment Required" }
131
+ }
132
+ }
133
+ }
134
+ }
135
+ }
136
+ ```
121
137
 
122
- ### Validation
138
+ See [docs/SPECIFICATION.md](docs/SPECIFICATION.md) for the normative field rules.
123
139
 
124
- | Export | Description |
125
- | ----------------------------------- | -------------------------------------------- |
126
- | `validatePaymentRequiredDetailed()` | Full 402 payload validation with diagnostics |
127
- | `evaluateMetadataCompleteness()` | Metadata quality score |
128
- | `VALIDATION_CODES` | Stable issue code constants |
140
+ SIWX is modeled as OpenAPI security too. Mark the security scheme with
141
+ `x-agentcash-auth-kind: "siwx"` so discovery treats it as wallet identity auth rather than a
142
+ generic API key.
129
143
 
130
- ### Audit
144
+ ## Exported API
131
145
 
132
- | Export | Description |
133
- | --------------------------- | ------------------------------ |
134
- | `getWarningsForOpenAPI()` | Warnings for OpenAPI source |
135
- | `getWarningsForWellKnown()` | Warnings for well-known source |
136
- | `getWarningsForL2()` | Warnings for route list |
137
- | `getWarningsForL3()` | Warnings for endpoint metadata |
138
- | `getWarningsForL4()` | Warnings for guidance layer |
139
- | `AUDIT_CODES` | Stable audit code constants |
146
+ | Export | Description |
147
+ | ----------------------------------- | -------------------------------------------------------------------- |
148
+ | `discoverOriginSchema()` | Token-light origin discovery |
149
+ | `checkEndpointSchema()` | Per-endpoint schema/payment inspection |
150
+ | `getOpenAPI()` | Fetch and parse OpenAPI from canonical locations |
151
+ | `getProbe()` | Probe an endpoint for live auth/payment behavior |
152
+ | `validatePaymentRequiredDetailed()` | Canonical x402 payment-required validator |
153
+ | `getWarningsForOpenAPI()` | OpenAPI quality warnings |
154
+ | `probeLegacyWellKnown()` | Detect presence of legacy `/.well-known/x402` and `/.well-known/mpp` |
155
+ | `getWarningsForLegacyWellKnown()` | Emit `LEGACY_WELL_KNOWN_FOUND` migration warning |
156
+ | `getWarningsForL2()` | Route-list warnings |
157
+ | `getWarningsForL3()` | Endpoint-detail warnings |
158
+ | `AUDIT_CODES` | Stable audit warning code constants |
159
+
160
+ ## Development
140
161
 
141
- Ownership boundary:
162
+ ```bash
163
+ pnpm install
164
+ pnpm check
165
+ ```
142
166
 
143
- - `@agentcash/discovery` owns discovery/advisory contracts.
144
- - `@agentcash` should own all signing logic, but should be composable with the methods for probing built in this package.
167
+ `pnpm check` runs formatting, linting, dependency checks, typecheck, build, and tests.
145
168
 
146
- Philosophy boundary:
169
+ ## License
147
170
 
148
- - Machine-parsable discovery metadata belongs in OpenAPI.
149
- - Discovery is advisory. Runtime payment challenge/probe is authoritative.
171
+ MIT