@agentcash/discovery 1.0.0 → 1.0.2

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

@@ -76,6 +76,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 +106,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 +150,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 +194,7 @@ function fetchSafe(url, init) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "1.0.0".includes("-mmm");
+var isMmmEnabled = () => "1.0.2".includes("-mmm");
 
 // src/core/source/openapi/index.ts
 var OpenApiParsedSchema = OpenApiDocSchema.transform((doc) => {
@@ -189,15 +203,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 } : {},
@@ -643,10 +655,12 @@ function extractSchemas3(payload) {
   return {};
 }
 function parseInputSchema(payload) {
-  return extractSchemas3(payload).inputSchema;
+  const schema = extractSchemas3(payload).inputSchema;
+  return schema;
 }
 function parseOutputSchema(payload) {
-  return extractSchemas3(payload).outputSchema;
+  const schema = extractSchemas3(payload).outputSchema;
+  return schema;
 }
 
 // src/core/protocols/x402/v1/parse-payment-required.ts
@@ -874,6 +888,20 @@ function extractRequestBodySchema(operationSchema) {
   }
   return void 0;
 }
+function extractOutputSchema(operationSchema) {
+  const responses = operationSchema.responses;
+  if (!isRecord(responses)) return void 0;
+  const candidate = responses["200"] ?? responses["201"] ?? Object.entries(responses).find(([k]) => k.startsWith("2"))?.[1];
+  if (!isRecord(candidate)) return void 0;
+  const content = candidate.content;
+  if (!isRecord(content)) return void 0;
+  const json = content["application/json"];
+  if (isRecord(json) && isRecord(json.schema)) return json.schema;
+  for (const mediaType of Object.values(content)) {
+    if (isRecord(mediaType) && isRecord(mediaType.schema)) return mediaType.schema;
+  }
+  return void 0;
+}
 function extractParameters(operationSchema) {
   const params = operationSchema.parameters;
   if (!Array.isArray(params)) return [];
@@ -932,7 +960,7 @@ function getL3ForOpenAPI(openApi, path, method) {
     estimatedPrice: parseOperationPrice(resolvedOperation),
     protocols: parseOperationProtocols(resolvedOperation),
     inputSchema: extractInputSchema(resolvedOperation),
-    outputSchema: resolvedOperation
+    outputSchema: extractOutputSchema(resolvedOperation)
   };
 }
 function getL3ForProbe(probe, path, method) {
@@ -969,12 +997,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
@@ -999,7 +1027,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,

package/dist/cli.js

@@ -50,6 +50,7 @@ var OpenApiDocSchema = z.object({
     description: z.string().optional(),
     guidance: z.string().optional()
   }),
+  security: z.array(z.record(z.string(), z.array(z.string()))).optional(),
   servers: z.array(z.object({ url: z.string() })).optional(),
   tags: z.array(z.object({ name: z.string() })).optional(),
   components: z.object({ securitySchemes: z.record(z.string(), z.unknown()).optional() }).optional(),
@@ -79,20 +80,31 @@ var WellKnownParsedSchema = 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;
@@ -112,10 +124,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 = "";
@@ -154,7 +168,7 @@ function fetchSafe(url, init) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "1.0.0".includes("-mmm");
+var isMmmEnabled = () => "1.0.2".includes("-mmm");
 
 // src/core/source/openapi/index.ts
 var OpenApiParsedSchema = OpenApiDocSchema.transform((doc) => {
@@ -163,15 +177,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 } : {},
@@ -617,10 +629,12 @@ function extractSchemas3(payload) {
   return {};
 }
 function parseInputSchema(payload) {
-  return extractSchemas3(payload).inputSchema;
+  const schema = extractSchemas3(payload).inputSchema;
+  return schema;
 }
 function parseOutputSchema(payload) {
-  return extractSchemas3(payload).outputSchema;
+  const schema = extractSchemas3(payload).outputSchema;
+  return schema;
 }
 
 // src/core/protocols/x402/v1/parse-payment-required.ts
@@ -848,6 +862,20 @@ function extractRequestBodySchema(operationSchema) {
   }
   return void 0;
 }
+function extractOutputSchema(operationSchema) {
+  const responses = operationSchema.responses;
+  if (!isRecord(responses)) return void 0;
+  const candidate = responses["200"] ?? responses["201"] ?? Object.entries(responses).find(([k]) => k.startsWith("2"))?.[1];
+  if (!isRecord(candidate)) return void 0;
+  const content = candidate.content;
+  if (!isRecord(content)) return void 0;
+  const json = content["application/json"];
+  if (isRecord(json) && isRecord(json.schema)) return json.schema;
+  for (const mediaType of Object.values(content)) {
+    if (isRecord(mediaType) && isRecord(mediaType.schema)) return mediaType.schema;
+  }
+  return void 0;
+}
 function extractParameters(operationSchema) {
   const params = operationSchema.parameters;
   if (!Array.isArray(params)) return [];
@@ -906,7 +934,7 @@ function getL3ForOpenAPI(openApi, path, method) {
     estimatedPrice: parseOperationPrice(resolvedOperation),
     protocols: parseOperationProtocols(resolvedOperation),
     inputSchema: extractInputSchema(resolvedOperation),
-    outputSchema: resolvedOperation
+    outputSchema: extractOutputSchema(resolvedOperation)
   };
 }
 function getL3ForProbe(probe, path, method) {
@@ -943,12 +971,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
@@ -973,7 +1001,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,

package/dist/index.cjs

@@ -97,6 +97,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(),
@@ -126,20 +127,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;
@@ -159,10 +171,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 = "";
@@ -201,7 +215,7 @@ function fetchSafe(url, init) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "1.0.0".includes("-mmm");
+var isMmmEnabled = () => "1.0.2".includes("-mmm");
 
 // src/core/source/openapi/index.ts
 var OpenApiParsedSchema = OpenApiDocSchema.transform((doc) => {
@@ -210,15 +224,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 } : {},
@@ -816,10 +828,12 @@ function extractSchemas3(payload) {
   return {};
 }
 function parseInputSchema(payload) {
-  return extractSchemas3(payload).inputSchema;
+  const schema = extractSchemas3(payload).inputSchema;
+  return schema;
 }
 function parseOutputSchema(payload) {
-  return extractSchemas3(payload).outputSchema;
+  const schema = extractSchemas3(payload).outputSchema;
+  return schema;
 }
 
 // src/core/protocols/x402/v1/parse-payment-required.ts
@@ -1047,6 +1061,20 @@ function extractRequestBodySchema(operationSchema) {
   }
   return void 0;
 }
+function extractOutputSchema(operationSchema) {
+  const responses = operationSchema.responses;
+  if (!isRecord(responses)) return void 0;
+  const candidate = responses["200"] ?? responses["201"] ?? Object.entries(responses).find(([k]) => k.startsWith("2"))?.[1];
+  if (!isRecord(candidate)) return void 0;
+  const content = candidate.content;
+  if (!isRecord(content)) return void 0;
+  const json = content["application/json"];
+  if (isRecord(json) && isRecord(json.schema)) return json.schema;
+  for (const mediaType of Object.values(content)) {
+    if (isRecord(mediaType) && isRecord(mediaType.schema)) return mediaType.schema;
+  }
+  return void 0;
+}
 function extractParameters(operationSchema) {
   const params = operationSchema.parameters;
   if (!Array.isArray(params)) return [];
@@ -1105,7 +1133,7 @@ function getL3ForOpenAPI(openApi, path, method) {
     estimatedPrice: parseOperationPrice(resolvedOperation),
     protocols: parseOperationProtocols(resolvedOperation),
     inputSchema: extractInputSchema(resolvedOperation),
-    outputSchema: resolvedOperation
+    outputSchema: extractOutputSchema(resolvedOperation)
   };
 }
 function getL3ForProbe(probe, path, method) {
@@ -1146,12 +1174,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
@@ -1176,7 +1204,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,

package/dist/index.js

@@ -50,6 +50,7 @@ var OpenApiDocSchema = z.object({
     description: z.string().optional(),
     guidance: z.string().optional()
   }),
+  security: z.array(z.record(z.string(), z.array(z.string()))).optional(),
   servers: z.array(z.object({ url: z.string() })).optional(),
   tags: z.array(z.object({ name: z.string() })).optional(),
   components: z.object({ securitySchemes: z.record(z.string(), z.unknown()).optional() }).optional(),
@@ -79,20 +80,31 @@ var WellKnownParsedSchema = 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;
@@ -112,10 +124,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 = "";
@@ -154,7 +168,7 @@ function fetchSafe(url, init) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "1.0.0".includes("-mmm");
+var isMmmEnabled = () => "1.0.2".includes("-mmm");
 
 // src/core/source/openapi/index.ts
 var OpenApiParsedSchema = OpenApiDocSchema.transform((doc) => {
@@ -163,15 +177,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 } : {},
@@ -769,10 +781,12 @@ function extractSchemas3(payload) {
   return {};
 }
 function parseInputSchema(payload) {
-  return extractSchemas3(payload).inputSchema;
+  const schema = extractSchemas3(payload).inputSchema;
+  return schema;
 }
 function parseOutputSchema(payload) {
-  return extractSchemas3(payload).outputSchema;
+  const schema = extractSchemas3(payload).outputSchema;
+  return schema;
 }
 
 // src/core/protocols/x402/v1/parse-payment-required.ts
@@ -1000,6 +1014,20 @@ function extractRequestBodySchema(operationSchema) {
   }
   return void 0;
 }
+function extractOutputSchema(operationSchema) {
+  const responses = operationSchema.responses;
+  if (!isRecord(responses)) return void 0;
+  const candidate = responses["200"] ?? responses["201"] ?? Object.entries(responses).find(([k]) => k.startsWith("2"))?.[1];
+  if (!isRecord(candidate)) return void 0;
+  const content = candidate.content;
+  if (!isRecord(content)) return void 0;
+  const json = content["application/json"];
+  if (isRecord(json) && isRecord(json.schema)) return json.schema;
+  for (const mediaType of Object.values(content)) {
+    if (isRecord(mediaType) && isRecord(mediaType.schema)) return mediaType.schema;
+  }
+  return void 0;
+}
 function extractParameters(operationSchema) {
   const params = operationSchema.parameters;
   if (!Array.isArray(params)) return [];
@@ -1058,7 +1086,7 @@ function getL3ForOpenAPI(openApi, path, method) {
     estimatedPrice: parseOperationPrice(resolvedOperation),
     protocols: parseOperationProtocols(resolvedOperation),
     inputSchema: extractInputSchema(resolvedOperation),
-    outputSchema: resolvedOperation
+    outputSchema: extractOutputSchema(resolvedOperation)
   };
 }
 function getL3ForProbe(probe, path, method) {
@@ -1099,12 +1127,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
@@ -1129,7 +1157,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,

package/dist/schemas.cjs

@@ -76,6 +76,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(),

package/dist/schemas.d.cts

@@ -300,6 +300,7 @@ declare const OpenApiDocSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         guidance: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+    security: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
     servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
     }, z.core.$strip>>>;

package/dist/schemas.d.ts

@@ -300,6 +300,7 @@ declare const OpenApiDocSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         guidance: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+    security: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
     servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
     }, z.core.$strip>>>;

package/dist/schemas.js

@@ -47,6 +47,7 @@ var OpenApiDocSchema = z.object({
     description: z.string().optional(),
     guidance: z.string().optional()
   }),
+  security: z.array(z.record(z.string(), z.array(z.string()))).optional(),
   servers: z.array(z.object({ url: z.string() })).optional(),
   tags: z.array(z.object({ name: z.string() })).optional(),
   components: z.object({ securitySchemes: z.record(z.string(), z.unknown()).optional() }).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/discovery",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Canonical OpenAPI-first discovery runtime for the agentcash ecosystem",
   "type": "module",
   "main": "./dist/index.cjs",