@agentcash/discovery 0.0.0-pr-21-20260306191442

package/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Purpose
+
+This repo implements canonical discovery logic for the agentcash ecosystem.
+
+## Hard Constraints
+
+1. Keep canonical core and compatibility modules physically separate.
+2. Avoid legacy conditionals in `src/core/*`.
+3. Preserve stable warning codes.
+4. Keep `discover` token-light and deterministic.
+5. Keep compatibility removable via a single top-level mode.
+
+## Module Boundaries
+
+- `src/core/*`: canonical OpenAPI-first discovery.
+- `src/compat/legacy-x402scan/*`: `/.well-known/x402` + DNS `_x402` compatibility.
+
+## Result Contract
+
+Resource identity is always `origin + method + path`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Merit Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# @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
+
+```bash
+pnpm add @agentcash/discovery
+```
+
+## 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
+```
+
+L0-L5 context harness summary for a client:
+
+```bash
+npx @agentcash/discovery stabletravel.dev --harness --client claude-code
+```
+
+L0-L5 harness verbose with explicit budget:
+
+```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,
+  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:
+
+```text
+${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:
+
+```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/bin/discovery.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from '../dist/cli.js';
+
+const exitCode = await main(process.argv.slice(2));
+process.exit(exitCode);

package/dist/flags.cjs

@@ -0,0 +1,44 @@
+"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/flags.ts
+var flags_exports = {};
+__export(flags_exports, {
+  DEFAULT_COMPAT_MODE: () => DEFAULT_COMPAT_MODE,
+  LEGACY_SUNSET_DATE: () => LEGACY_SUNSET_DATE,
+  STRICT_ESCALATION_CODES: () => STRICT_ESCALATION_CODES
+});
+module.exports = __toCommonJS(flags_exports);
+var LEGACY_SUNSET_DATE = "2026-03-24";
+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"
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_COMPAT_MODE,
+  LEGACY_SUNSET_DATE,
+  STRICT_ESCALATION_CODES
+});

package/dist/flags.d.cts

@@ -0,0 +1,6 @@
+declare const LEGACY_SUNSET_DATE = "2026-03-24";
+type CompatibilityMode = 'on' | 'off' | 'strict';
+declare const DEFAULT_COMPAT_MODE: CompatibilityMode;
+declare const STRICT_ESCALATION_CODES: readonly ["LEGACY_WELL_KNOWN_USED", "LEGACY_DNS_USED", "LEGACY_DNS_PLAIN_URL", "LEGACY_MISSING_METHOD", "LEGACY_INSTRUCTIONS_USED", "LEGACY_OWNERSHIP_PROOFS_USED", "INTEROP_MPP_USED"];
+
+export { type CompatibilityMode, DEFAULT_COMPAT_MODE, LEGACY_SUNSET_DATE, STRICT_ESCALATION_CODES };

package/dist/flags.d.ts

@@ -0,0 +1,6 @@
+declare const LEGACY_SUNSET_DATE = "2026-03-24";
+type CompatibilityMode = 'on' | 'off' | 'strict';
+declare const DEFAULT_COMPAT_MODE: CompatibilityMode;
+declare const STRICT_ESCALATION_CODES: readonly ["LEGACY_WELL_KNOWN_USED", "LEGACY_DNS_USED", "LEGACY_DNS_PLAIN_URL", "LEGACY_MISSING_METHOD", "LEGACY_INSTRUCTIONS_USED", "LEGACY_OWNERSHIP_PROOFS_USED", "INTEROP_MPP_USED"];
+
+export { type CompatibilityMode, DEFAULT_COMPAT_MODE, LEGACY_SUNSET_DATE, STRICT_ESCALATION_CODES };

package/dist/flags.js

@@ -0,0 +1,17 @@
+// src/flags.ts
+var LEGACY_SUNSET_DATE = "2026-03-24";
+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"
+];
+export {
+  DEFAULT_COMPAT_MODE,
+  LEGACY_SUNSET_DATE,
+  STRICT_ESCALATION_CODES
+};