callx402 1.0.3 → 1.0.5

package/.github/release-intent/callx402-v1.0.5.txt

@@ -0,0 +1,2 @@
+Release callx402@1.0.5 after the clean-install consumer suite and legacy-subsystem regression suite pass. No production money movement.
+Retried after correcting the npm v11 pack metadata assertion to verify the generated tarball on disk.

package/.github/workflows/consumer-compatibility.yml

@@ -0,0 +1,20 @@
+name: consumer-compatibility
+on:
+  push:
+    branches:
+      - 'test/clean-npm-mcp-consumer-20261016'
+  pull_request:
+    branches:
+      - main
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: npm test && node --test test/external-mcp-package.test.js

package/.github/workflows/npm-publish.yml

@@ -4,6 +4,10 @@ on:
   release:
     types: [published]
   workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - '.github/release-intent/callx402-v1.0.5.txt'
 
 permissions:
   id-token: write
@@ -14,7 +18,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
@@ -23,7 +26,32 @@ jobs:
       - run: npm ci --no-audit --no-fund
       - run: npm test
       - run: npm pack --dry-run
-
-
-      - name: Publish to npm via Trusted Publishing (OIDC, no token)
+      - name: Confirm release version
+        run: |
+          node -e "if (require('./package.json').version !== '1.0.5') process.exit(1)"
+      - name: Check whether version is already published
+        id: published
+        run: |
+          if npm view callx402@1.0.5 version >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Publish to npm via existing Trusted Publishing (OIDC)
+        if: steps.published.outputs.exists != 'true'
         run: npm publish --provenance --access public
+
+  github-release:
+    if: github.event_name == 'push'
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Publish tagged source release after npm publication
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if ! gh release view v1.0.5 --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release create v1.0.5 --repo "$GITHUB_REPOSITORY" --target "$GITHUB_SHA" --title "callx402 v1.0.5" --notes "Free read-only MCP diagnostics work from a clean npm installation. Existing configured local/remote subsystems remain available. Financial execution remains disabled through MCP. Release verified by full test suite and npm-pack consumer tests."
+          fi

package/README.md

@@ -77,10 +77,7 @@ Ask the client to list its MCP tools: the six `x402_*` tools should appear.
 Per-client notes and the raw stdio test handshake:
 [`integrations/mcp-clients/`](integrations/mcp-clients/).
 
-Note: `x402_status` works with zero setup. The other five tools dispatch
-into the v2.0.0 subsystem tree, so they report `subsystem_unreachable`
-until `CALLX402_V2_ROOT` points at the tree (see "Full subsystem commands"
-above) and the matching flag is enabled.
+Note: all six free MCP tools respond on a clean npm install using conservative local, read-only assessment of supplied evidence. Without an authoritative source they **do not** verify settlement, access a private ledger, or execute recovery. Existing configured local/remote subsystem integrations remain available.
 
 ## The relationship
 
@@ -328,13 +325,79 @@ redemption is not currently enabled. Stripe credits use a separate redemption pa
 
 Live fee schedule: `GET https://payload-rail.fly.dev/v1/callx402/actions`
 (responds `"model":"paid on-demand per action; no subscription required"`).
-The x402-path price is the Stripe-path fee divided by 20 — for example
-`resolve` is $5.00 via Stripe, $0.25 via the x402 path. Never blind-retry a
-payment to reach a paid action: get the quote first.
+There are two prices per action, and they are not interchangeable: the
+**card price** is the Stripe schedule fee; the **USDC price** on the x402
+path is exactly that fee divided by 20 (the free quote endpoint is the
+source of truth for the USDC column). Both, side by side:
+
+| Action | Card (Stripe) | USDC (x402 path) |
+|---|---|---|
+| `diagnose` | $2.00 | $0.10 |
+| `explain` | $1.00 | $0.05 |
+| `evidence` | $2.00 | $0.10 |
+| `recover` | $10.00 | $0.50 |
+| `resolve` | $5.00 | $0.25 |
+| `preflight` | $3.00 | $0.15 |
+| `settlement_interpretation` | $3.00 | $0.15 |
+| `failure_classification` | $2.00 | $0.10 |
+| `duplicate_payment_risk` | $5.00 | $0.25 |
+
+Rail `evidence` and `explain` read back a prior paid invocation (the
+request carries that invocation's `invocation_id`), so they cannot be used
+cold; the free local forms read your local operation ledger instead.
+
+**Not sold on the rail:** `safe_retry`, `rescue`, `monitor`, and `execute`
+are local-only. They run in the self-hosted runtime (v2.0.0 tree), are
+absent from the rail catalog above, and the rail refuses them with
+`422 HOSTED_ACTION_UNAVAILABLE` — there is no Stripe or x402 purchase path
+for them. For the "is this retry safe?" question, the free local `recover`
+verdict is the available read-only answer.
+
+Never blind-retry a payment to reach a paid action: get the quote first.
 
 Problem to action map (which paid action answers which failure, with the free
 CLI/MCP path for each): [`docs/problem-map.md`](docs/problem-map.md).
 
+## Public RevRule evaluation (0.01 USDC)
+
+The rail also exposes one public RevRule evaluation endpoint. It is a
+RevRule demo, not a callx402 diagnostic action:
+`POST https://payload-rail.fly.dev/v1/x402/public/evaluate` evaluates one
+economic event against the fixed, transparent public demo graph (platform
+5% of gross; creator 70% of the remainder; referrer 25% of the remainder
+when a referrer is named in the event) for 0.01 USDC on Base.
+
+The full, correct request body is:
+
+```json
+{
+  "event": {
+    "eventId": "my-event-001",
+    "type": "SALE_COMPLETED",
+    "rail": "stripe",
+    "amountMicros": 100000000,
+    "currency": "USD",
+    "occurredAt": "2026-10-13T00:00:00.000Z"
+  },
+  "txHash": "0x<your settled 0.01 USDC payment on Base>"
+}
+```
+
+- `event.eventId` (any unique non-empty string) and `event.rail` are
+  **required**, even though the 402's advertised bazaar schema omits both.
+  Valid `rail` values: `stripe`, `ach`, `x402`, `manual`, `stablecoin`.
+- `event.type` must be one of: `SALE_COMPLETED`, `API_PAYMENT`,
+  `LICENSE_PAID`, `SUBSCRIPTION_PAYMENT`, `REFERRAL_CONVERTED`,
+  `ROYALTY_RECEIVED`, `CAMPAIGN_MILESTONE`, `MARKETPLACE_TRANSACTION`,
+  `TOUCH`.
+- The event is validated **before** payment: a malformed body gets
+  `400 INVALID_EVENT`, not a 402 (verified live: the body above, minus
+  `txHash`, returns the 402). The endpoint fills in the rest itself —
+  `graphId` is fixed to the public demo graph, and `currency` defaults to
+  `"USD"` and `occurredAt` to now when omitted.
+- Omit `txHash` to receive the x402 v2 `402` challenge; pay 0.01 USDC,
+  then retry the same body with the hash. Each txHash is single-use.
+
 ## Integrations
 
 Working entry points for agent frameworks, automation, MCP clients, and x402

package/bin/callx402.js

@@ -222,9 +222,11 @@ never executes, never repays. Requires PAYLOAD_VEYLINE_RECOVERY=1.
 
 This is the read-only answer to "is a retry safe?" — a SAFE_RETRY verdict
 here is advisory; performing the safe action stays with your own adapters.
-For the paid one-off verdict on a specific retry plan, use the 'safe_retry'
-rail action (quote first, then pay; see docs/problem-map.md). The MCP tool
-x402_recover covers the same free diagnostic.
+There is NO paid rail form of 'safe_retry': the hosted rail refuses it as
+local-only (it is absent from the rail catalog and cannot be bought via
+Stripe or x402). This free recover verdict is the read-only answer
+available without the self-hosted runtime tree (see docs/problem-map.md).
+The MCP tool x402_recover covers the same free diagnostic.
 
 Exit codes: 0 ok · 1 failure · 2 usage (missing identity/evidence) ·
 3 disabled/unreachable · 4 budget refused ·
@@ -256,14 +258,16 @@ Usage:
   callx402 "natural language intent"        intent mode (plans, never executes blindly)
   callx402 --help | --version
 
-Commands (hosted by default — zero setup):
+Commands (rail actions hosted by default — zero setup; local-only
+commands marked, they need the v2.0.0 runtime tree and are NOT sold on
+the hosted rail):
   diagnose    run the x402 doctor over supplied evidence        [--target <url|json>] [--evidence <json|@file>]
-  rescue      incident triage (auth-gated; read-only without auth) --incident <id>
+  rescue      incident triage, local only (auth-gated; read-only without auth) --incident <id>
   route       select a tool/route for a goal                   --goal <text>
   resolve     resolve settlement state from evidence           --evidence <json|@file>
   doctor      alias of diagnose
-  execute     run the intent pipeline                          --intent <text> [--max-budget N] [--dry-run] [--idempotency-key K]
-  monitor     sentinel snapshot [--once] or stream [--watch]
+  execute     run the intent pipeline, local only              --intent <text> [--max-budget N] [--dry-run] [--idempotency-key K]
+  monitor     sentinel snapshot, local only [--once] or stream [--watch]
   status      per-subsystem reachable/enabled/version report
   preflight   run MCP preflight checks
   inspect     capability-graph lookup/stats                    [--query <text>]

package/core/rail.js

@@ -156,7 +156,7 @@ async function invokeRail(command, args, opts = {}) {
     if (!interactive) {
       return {
         ok: false,
-        error: `Payment of $${price} required. Re-run with --yes to approve non-interactively, or run interactively.`,
+        error: `Payment of $${price} required. Re-run with --approve to approve non-interactively, or run interactively.`,
         quote: { action, price_usd: price, quote_id: quoteId, quote_inputs: quote.quote_inputs },
       };
     }

package/core/subsystems.js

@@ -52,6 +52,14 @@ const NOTES = {
   recovery: 'File-backed idempotency store used for duplicate-idempotencyKey dedupe.',
 };
 
+/** First line only: Node require errors append a multi-line "Require stack:"
+ * dump that helps nobody in a status report or an MCP tool result. The short
+ * form still names the missing module and stays actionable. */
+function briefError(err) {
+  const msg = err && err.message ? String(err.message) : String(err || 'unknown error');
+  return msg.split('\n')[0].trim();
+}
+
 function defaultV2Root() {
   return path.resolve(__dirname, '../../x402-paid-api-starter-kit/v2.0.0');
 }
@@ -98,7 +106,7 @@ function getSubsystem(name, { config = {}, deps = {} } = {}) {
   try {
     mod = requireFiles(v2Root, MODULE_FILES[name]);
   } catch (err) {
-    return { name, reachable: false, module: null, enabled: false, flag: null, version: null, note: NOTES[name] || null, subsystemStatus: 'unreachable', error: `require failed: ${err.message}` };
+    return { name, reachable: false, module: null, enabled: false, flag: null, version: null, note: NOTES[name] || null, subsystemStatus: 'unreachable', error: `require failed: ${briefError(err)}` };
   }
 
   let flag = null;
@@ -107,7 +115,7 @@ function getSubsystem(name, { config = {}, deps = {} } = {}) {
     flag = typeof mod.FLAG === 'string' ? mod.FLAG : null;
     enabled = typeof mod.enabled === 'function' ? mod.enabled() : false;
   } catch (err) {
-    return { name, reachable: true, module: mod, enabled: false, flag, version: null, note: NOTES[name] || null, subsystemStatus: 'disabled', error: `enabled() check failed: ${err.message}` };
+    return { name, reachable: true, module: mod, enabled: false, flag, version: null, note: NOTES[name] || null, subsystemStatus: 'disabled', error: `enabled() check failed: ${briefError(err)}` };
   }
 
   const version = mod.version || mod.RESCUE_VERSION || mod.EFFECT_PROOF_VERSION || null;

package/docs/problem-map.md

@@ -25,7 +25,13 @@ v2.0.0 runtime tree and `CALLX402_LOCAL=1`). The paid form runs on the
 production rail: quote first, payment verified exactly once, then the
 diagnostic executes server-side and the result is returned — zero local setup.
 The "Free path" column names the free equivalent; "rail only" means the action
-exists only as a paid rail action.
+exists only as a paid rail action. "Local only" means the opposite: the action
+exists ONLY locally (self-hosted runtime tree). The hosted rail refuses it
+with `422 HOSTED_ACTION_UNAVAILABLE`, it is absent from the rail catalog
+(`GET /v1/callx402/actions` lists nine actions), and there is no Stripe or
+x402 purchase path for it. Four actions are local-only: `safe_retry`,
+`rescue`, `monitor`, `execute`. Their fee cells below show the schedule
+figure for reference only — it cannot be paid on the rail.
 
 **Fees.** The table lists the Stripe-path fee per action. The x402 path
 quoted by the free quote endpoint is exactly that fee divided by 20
@@ -40,16 +46,16 @@ deterministic, not an estimate.
 | 1 | Settlement uncertainty — can't tell from current info whether the payment settled | `resolve` | $5.00 | `callx402 resolve --evidence ...` / `x402_resolve` | Unknown stays unknown; never auto-retry, never repay |
 | 2 | Lost result after payment — paid, but the result never arrived | `recover` | $10.00 | `callx402 recover <op> --identity ...` / `x402_recover` | Read-only: nothing charged, nothing executed; returns the safe recovery decision or the proven prior result, never a blind re-execution |
 | 3 | Retry uncertainty — something failed; need what/why before deciding if retry is safe | `diagnose` | $2.00 | `callx402 diagnose --evidence ...` / `x402_diagnose` | Unknown failure class returns UNKNOWN, never a guess |
-| 4 | Retry uncertainty, narrowed — is THIS specific retry safe to sign? | `safe_retry` | $5.00 | rail only (start free with `recover`: a SAFE_RETRY verdict there is the read-only answer) | A retry that would double-pay is refused |
+| 4 | Retry uncertainty, narrowed — is THIS specific retry safe to sign? | `safe_retry` | $5.00 (local only — not purchasable on the rail) | local only (self-hosted runtime; no CLI command in this package and no rail purchase path — start free with `recover`: a SAFE_RETRY verdict there is the read-only answer) | A retry that would double-pay is refused |
 | 5 | Duplicate-payment risk — a retry might sign a second authorization for the same intent | `duplicate_payment_risk` | $5.00 | rail only (start free: `resolve` the settlement, then `recover` for the retry verdict) | Ambiguous authorization state blocks the retry |
 | 6 | Need proof — ground truth before acting on any incident | `evidence` | $2.00 | `callx402 evidence <op>` / `x402_evidence` | First step in any incident; returns what is recorded, nothing invented |
 | 7 | Need explanation — plain-language state assessment before retry/refund/escalate | `explain` | $1.00 | `callx402 explain <op>` / `x402_explain` | INCOMPLETE means do not retry, do not repay |
 | 8 | Pre-commit check — intent, payment readiness, risk before an economic operation commits | `preflight` | $3.00 | `callx402 preflight` (local checks) | Blocked stays blocked until the reasons clear |
 | 9 | Failure triage — classify the failure so the right playbook runs | `failure_classification` | $2.00 | rail only (start free with `diagnose`) | Unclassifiable failures escalate to human review |
 | 10 | Settlement-record interpretation — read a raw settlement record, state what it means | `settlement_interpretation` | $3.00 | rail only (start free with `resolve --evidence ...`) | Ambiguous records are reported ambiguous |
-| 11 | Rescue a failed transaction — triage and recover the incident end to end | `rescue` | $15.00 | `callx402 rescue --incident <id>` (triage and quote only, never executes) | Never fabricates success; unreachable subsystems fail closed |
-| 12 | Watch an operation/workload for state changes, failures, anomalies | `monitor` | $5.00 | `callx402 monitor --once` (local sentinel snapshot) | An unwatched gap is reported as a gap, not as healthy |
-| 13 | Run an economic operation through the protected path (exactly-once) | `execute` | $10.00 | `callx402 execute --intent ... --dry-run` (plans only) | Over-budget intents refused with zero side effects |
+| 11 | Rescue a failed transaction — triage and recover the incident end to end | `rescue` | $15.00 (local only — not purchasable on the rail) | `callx402 rescue --incident <id>` (triage and quote only, never executes) | Never fabricates success; unreachable subsystems fail closed |
+| 12 | Watch an operation/workload for state changes, failures, anomalies | `monitor` | $5.00 (local only — not purchasable on the rail) | `callx402 monitor --once` (local sentinel snapshot) | An unwatched gap is reported as a gap, not as healthy |
+| 13 | Run an economic operation through the protected path (exactly-once) | `execute` | $10.00 (local only — not purchasable on the rail) | `callx402 execute --intent ... --dry-run` (plans only) | Over-budget intents refused with zero side effects |
 
 ## Where each surface consumes this map
 
@@ -70,9 +76,14 @@ deterministic, not an estimate.
 ## Notes
 
 - Action names are canonical in `snake_case`. The rail also accepts the
-  hyphenated aliases shown in the OpenAPI enum (`safe-retry`,
-  `duplicate-payment-risk`, `settlement-interpretation`,
-  `failure-classification`); both forms resolve identically (verified live).
+  hyphenated aliases shown in the OpenAPI enum (`duplicate-payment-risk`,
+  `settlement-interpretation`, `failure-classification`); both forms resolve
+  identically (verified live). `safe-retry` is not a rail action in either
+  spelling — it is local-only (see the two-tiers note above).
+- Rail `evidence` / `explain` read back a PRIOR paid invocation: the request
+  must carry that invocation's `invocation_id`, and the rail returns
+  `400 MISSING_INPUT` without one, so they cannot be used cold. The free
+  local forms in the map read your local operation ledger instead.
 - The x402-path quote is the valuation-layer quote, not the raw schedule;
   the fixed schedule above is the Stripe-path floor.
 - Local CLI / MCP-stdio diagnostics are free and read-only — no payment, no

package/integrations/core.py

@@ -5,7 +5,7 @@ Plain functions (no framework imports) so LangChain, CrewAI, AutoGen, or any
 agent framework can wrap them directly. stdlib only.
 
 The rail's public endpoints:
-  GET  /v1/callx402/actions            free — live 13-action fee schedule
+  GET  /v1/callx402/actions            free — live fee schedule (9 hosted actions)
   GET  /v1/callx402/quote              free — deterministic pre-execution quote
   POST /v1/callx402/actions/{action}   paid — unauthenticated -> x402 v2 402
                                        (USDC on Base); credit_id / txHash /
@@ -30,6 +30,13 @@ RAIL = os.environ.get("CALLX402_RAIL", "https://payload-rail.fly.dev").rstrip("/
 
 # Canonical action names (snake_case), verified live 2026-10-07.
 # Hyphenated aliases are also accepted by the rail; these are canonical.
+# AVAILABILITY (verified live 2026-10-13): only 9 of these 13 are hosted and
+# purchasable on the rail — diagnose, explain, evidence, recover, resolve,
+# preflight, settlement_interpretation, failure_classification,
+# duplicate_payment_risk. The other four (safe_retry, rescue, monitor,
+# execute) are LOCAL-ONLY: the rail refuses them with
+# 422 HOSTED_ACTION_UNAVAILABLE, they are absent from the rail catalog, and
+# they cannot be bought via Stripe or x402.
 ACTIONS = (
     "diagnose", "explain", "evidence", "recover", "resolve", "preflight",
     "monitor", "execute", "rescue", "settlement_interpretation", "safe_retry",
@@ -303,7 +310,9 @@ FREE_LOCAL_ALTERNATIVE = (
     "Local CLI / MCP-stdio diagnostics are free and read-only "
     "(git clone https://github.com/Payloadhq/callx402; "
     "node mcp/index.js as an MCP server). The paid rail actions above are "
-    "for hosted on-demand invocation with payment."
+    "for hosted on-demand invocation with payment. Note: safe_retry, "
+    "rescue, monitor, and execute are local-only and are NOT purchasable "
+    "on the hosted rail."
 )
 
 

package/integrations/langchain/callx402_tools.py

@@ -125,8 +125,11 @@ def callx402_explain(operation_id: str) -> str:
 def callx402_safe_retry(retry_plan: str) -> str:
     """Go/no-go verdict on ONE specific retry plan before anything is signed.
     Use when a retry is being considered and must be proven safe first.
-    Paid on-demand ($5.00 via Stripe). A retry that would double-pay is
-    refused."""
+    AVAILABILITY: safe_retry is LOCAL-ONLY — the hosted rail refuses it
+    (422 HOSTED_ACTION_UNAVAILABLE) and it cannot be bought via Stripe or
+    x402, so this tool currently surfaces that refusal. For the
+    retry-safety question today, use callx402_recover's read-only verdict.
+    A retry that would double-pay is refused."""
     return _render(invoke("safe_retry", {"retry_plan": retry_plan}, **_auth()))
 
 

package/mcp/README.md

@@ -17,13 +17,9 @@ over stdio. Zero dependencies (node stdlib only).
 | `x402_status` | Subsystem reachability |
 
 Only diagnostic, read-only actions are exposed. Nothing here charges, executes,
-retries, or repays. If a subsystem is unreachable, the tool fails closed
-instead of inventing an answer.
+retries, or repays. If a verified local or remote subsystem is configured, the tools retain the existing full-subsystem dispatch. On a clean npm install, packaged free tools provide conservative, read-only analysis of *caller-supplied* evidence. They cannot independently verify settlement or access a private ledger.
 
-Setup note: `x402_status` works with zero setup. The other five tools
-dispatch into the v2.0.0 subsystem tree, so they report
-`subsystem_unreachable` until `CALLX402_V2_ROOT` points at the tree and the
-matching flag is enabled (see the main README, "Full subsystem commands").
+Setup note: **all six MCP tools work on a clean npm install**. Missing private ledger evidence is reported as NO_BASIS; recovery is never auto-executed; settlement without chain verification remains UNKNOWN. Existing optional local v2.0.0 integrations continue to work when configured and enabled.
 
 Tool names are namespaced `x402_*` — never `call_x402` (live collision on the
 fiatdock marketplace).

package/mcp/free-core.js

@@ -0,0 +1,45 @@
+'use strict';
+// Local, read-only, dependency-free MCP diagnosis.
+function run(name, args = {}) {
+  if(name === 'x402_status') return {status:'READY', mode:'FREE_MCP', tools:6};
+  let evidence = args.evidence || {};
+  if(typeof evidence === 'string') evidence = JSON.parse(evidence);
+  if(!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) {
+    throw new Error('Evidence must be a JSON object');
+  }
+  const status = Number(evidence.httpStatus || evidence.status || evidence.response?.status || 0);
+  let challenge = evidence.challenge || evidence.paymentRequired || evidence.responseBody || {};
+  if(typeof challenge === 'string') {
+    try { challenge = JSON.parse(challenge); } catch { challenge = {}; }
+  }
+  const accept = (Array.isArray(challenge.accepts) && challenge.accepts[0]) ||
+    challenge.paymentRequirements || challenge;
+  const network = accept.network || evidence.network || null;
+  const legacy = ['base','base-sepolia','solana','solana-devnet','ethereum','arbitrum','optimism','polygon'];
+  const known = typeof network === 'string' && (
+    /^(eip155:\d+|solana:[A-Za-z0-9]+)$/.test(network) || legacy.includes(network));
+  const terms = !!(network && accept.asset && (accept.amount != null || accept.maxAmountRequired != null));
+  const version = challenge.x402Version || evidence.x402Version || null;
+  if(name === 'x402_diagnose') return {
+    classification: status === 402 ? (terms ? (known ? 'RECOGNIZED_CHALLENGE' : 'UNKNOWN_NETWORK')
+        : 'INCOMPLETE_CHALLENGE') :
+      status >= 500 ? 'SERVER_ERROR' :
+      status === 401 || status === 403 ? 'AUTH_DENIED' : 'INSUFFICIENT_EVIDENCE',
+    network, x402Version: version, termsPresent: terms,
+    legacySlugInV2: !!(version === 2 && known && network && !network.includes(':')),
+    evidenceSource: 'USER_SUPPLIED', verifiedSettlement:false,
+    note:'Recognition does not verify payability or on-chain settlement.'
+  };
+  if(name === 'x402_evidence') return {
+    operationId: args.operationId || null, evidence,
+    basis: Object.keys(evidence).length ? 'USER_SUPPLIED' : 'NO_BASIS'
+  };
+  if(name === 'x402_explain') return {
+    operationId: args.operationId || null, summary:'Local supplied evidence only',
+    basis: Object.keys(evidence).length ? 'USER_SUPPLIED' : 'NO_BASIS'
+  };
+  if(name === 'x402_recover') return {decision:'HUMAN_REVIEW', canRetry:false, executed:false};
+  if(name === 'x402_resolve') return {settlement:'UNKNOWN', canRetry:false};
+  throw new Error('Unknown MCP tool');
+}
+module.exports = {run};

package/mcp/index.js

@@ -18,23 +18,62 @@
  * Only read-only / diagnostic actions are exposed. Actions with side effects
  * (execute, rescue mutations) are intentionally NOT tools here.
  *
+ * All six tools load without sibling packages. Existing enabled local/remote\n * subsystems are used when configured; otherwise free evidence and settlement
+ * assessments remain conservative: caller evidence is not authenticated,
+ * and local tools cannot certify a real payment or automatically retry.
+ *
  * Usage (Claude Desktop / MCP client config):
  *   { "command": "node", "args": ["/path/to/callx402/mcp/index.js"] }
  * Env: CALLX402_CONFIG, CALLX402_V2_ROOT, CALLX402_TIMEOUT_MS (default 30000).
  */
 const readline = require('node:readline');
 
-const VERSION = '1.0.2';
+const VERSION = '1.0.5';
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_NAME = 'callx402';
 const TIMEOUT_MS = Number(process.env.CALLX402_TIMEOUT_MS || 30000);
 
-const core = require(process.env.CALLX402_CORE_PATH ||
-  require('node:path').join(__dirname, '..', 'core'));
+// The free MCP artifact must be functional when installed alone. The CLI's
+// optional v2 subsystem tree is not a dependency of these read-only tools.
+const freeCore = require('./free-core.js');
+const core = require('../core/index.js');
+const { loadConfig } = require('../core/config.js');
+const { getSubsystem } = require('../core/subsystems.js');
+const { loadVeyline } = require('../core/veyline.js');
+
+/**
+ * Prefer a customer's already configured *real* local/remote subsystem.
+ * Otherwise use the packaged, read-only offline diagnostic instead of
+ * returning subsystem_unreachable on a fresh npm install.
+ *
+ * No payment, signer, or execute action is reachable through this MCP server.
+ */
+function hasConfiguredBackend(action) {
+  const cfg = loadConfig();
+  if (cfg.mode === 'remote' && cfg.remoteUrl) return true;
+  const subsystem = ({ diagnose: 'doctor', resolve: 'settlement' })[action];
+  if (subsystem) {
+    const handle = getSubsystem(subsystem, { config: cfg });
+    return handle.reachable && handle.enabled;
+  }
+  if (['evidence', 'explain', 'recover'].includes(action)) {
+    const flag = action === 'recover' ? 'PAYLOAD_VEYLINE_RECOVERY' : 'PAYLOAD_VEYLINE_LEDGER';
+    if (process.env[flag] !== '1') return false;
+    const loaded = loadVeyline(cfg, {});
+    return !!loaded.modules;
+  }
+  return false;
+}
 
 /* ------------------------------------------------------------------ */
-/* Tool definitions: name, description, input schema, core action.     */
+/* Tool definitions: packaged read-only diagnostics only.             */
+/*                                                                     */
+/* Caller-supplied evidence is unverified. No private ledger or funds.  */
 /* ------------------------------------------------------------------ */
+const TREE_REQUIRED = ' Local read-only inference from caller-supplied evidence, included in npm. Does not independently verify payments or access private infrastructure.';
+const ledgerRequired = () => ' Returns only caller-supplied evidence; no remote/private ledger is included and no on-chain data is verified.';
+const LEDGER_REQUIRED = ledgerRequired();
+
 const TOOLS = [
   {
     name: 'x402_diagnose',
@@ -43,14 +82,14 @@ const TOOLS = [
       'Run the x402 doctor over supplied evidence. Use when something went ' +
       'wrong with an x402 payment or MCP/x402 interaction and you need a ' +
       'diagnosis. Input: evidence as a JSON string or object describing the ' +
-      'failure (error strings, responses, tx hashes). Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'failure (error strings, responses, tx hashes). Read-only.' +
+      TREE_REQUIRED,
     inputSchema: {
       type: 'object',
       properties: {
         evidence: {
           type: 'string',
-          description: 'JSON string (or @file path) describing the failure evidence.',
+          description: 'JSON string describing non-sensitive failure evidence; local file references are unsupported.',
         },
         target: {
           type: 'string',
@@ -64,15 +103,14 @@ const TOOLS = [
     name: 'x402_evidence',
     action: 'evidence',
     description:
-      'Show recorded ledger evidence for an operation: event trail, latest ' +
-      'per-plane states (payment / execution / delivery), protocols involved. ' +
-      'Use FIRST in any incident — establishes ground truth before acting. Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'Show caller-supplied operation evidence only; no private or hosted ledger is included. ' +
+      'Missing evidence returns NO_BASIS, never an invented ledger record. Read-only.' +
+      LEDGER_REQUIRED,
     inputSchema: {
       type: 'object',
       properties: {
         operationId: { type: 'string', description: 'The operation ID to look up.' },
-        dir: { type: 'string', description: 'Optional ledger directory.' },
+        evidence: { type: 'string', description: 'Optional sanitized JSON evidence; otherwise NO_BASIS.' },
       },
       required: ['operationId'],
     },
@@ -81,16 +119,14 @@ const TOOLS = [
     name: 'x402_explain',
     action: 'explain',
     description:
-      'Explain an operation\'s state in plain language from recorded evidence. ' +
-      'Returns an assessment: NO_BASIS, INCOMPLETE (do not retry, do not repay), ' +
-      'KNOWN_SAFE, RECOVERY_CANDIDATE, or PARTIAL. Use to understand an incident ' +
-      'before deciding whether to retry, refund, or escalate. Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'Provide a conservative interpretation of caller-supplied evidence only; ' +
+      'no independent payment or settlement verification is performed. Read-only.' +
+      LEDGER_REQUIRED,
     inputSchema: {
       type: 'object',
       properties: {
         operationId: { type: 'string', description: 'The operation ID to explain.' },
-        dir: { type: 'string', description: 'Optional ledger directory.' },
+        evidence: { type: 'string', description: 'Optional sanitized JSON evidence; otherwise NO_BASIS.' },
       },
       required: ['operationId'],
     },
@@ -101,9 +137,9 @@ const TOOLS = [
     description:
       'Report the safe recovery decision for an operation whose result was lost ' +
       '(paid but no result). READ-ONLY: nothing is charged, nothing is executed. ' +
-      'Returns RECOVERABLE/SAFE_RETRY -> KNOWN_SAFE, or HUMAN_REVIEW. Use for ' +
-      'the exact situation where blind retry would double-pay or double-execute. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.',
+      'Without an authoritative settlement source, return HUMAN_REVIEW and never retry. ' +
+      'This free diagnostic cannot execute recovery.' +
+      ledgerRequired(),
     inputSchema: {
       type: 'object',
       properties: {
@@ -118,9 +154,9 @@ const TOOLS = [
     name: 'x402_resolve',
     action: 'resolve',
     description:
-      'Resolve settlement state from evidence (e.g. settlement_pending: was the ' +
-      'broadcast transaction confirmed on chain?). Use instead of blind retry. Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'Classify caller-provided settlement evidence conservatively. Returns UNKNOWN ' +
+      'without authoritative chain verification; no retry is performed. Read-only.' +
+      TREE_REQUIRED,
     inputSchema: {
       type: 'object',
       properties: {
@@ -137,8 +173,9 @@ const TOOLS = [
     action: 'status',
     description:
       'Check callx402 subsystem reachability (which diagnostic subsystems are ' +
-      'available). Use to verify the tool is operational before diagnosing. Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'available). Use to verify the tool is operational before diagnosing. ' +
+      'Read-only. Works with zero setup on a bare npm install. ' +
+      'reports the availability of the packaged free tools independently of optional subsystems.',
     inputSchema: { type: 'object', properties: {} },
   },
 ];
@@ -167,12 +204,19 @@ async function handleToolsCall(id, params) {
   }
   const args = (params && params.arguments) || {};
   try {
-    const { result: r, exitCode } = await core.runAction(tool.action, args, { timeoutMs: TIMEOUT_MS });
-    const ok = exitCode === 0;
-    result(id, {
-      content: [{ type: 'text', text: JSON.stringify(r, null, 2) }],
-      isError: !ok,
-    });
+    if (hasConfiguredBackend(tool.action)) {
+      const { result: r, exitCode } = await core.runAction(tool.action, args, { timeoutMs: TIMEOUT_MS });
+      result(id, {
+        content: [{ type: 'text', text: JSON.stringify(r, null, 2) }],
+        isError: exitCode !== 0,
+      });
+    } else {
+      const r = freeCore.run(tool.name, args);
+      result(id, {
+        content: [{ type: 'text', text: JSON.stringify(r, null, 2) }],
+        isError: false,
+      });
+    }
   } catch (e) {
     result(id, {
       content: [{ type: 'text', text: JSON.stringify({ error: e && e.message ? e.message : String(e) }) }],

package/package.json

@@ -27,6 +27,6 @@
     "smoke": "node bin/callx402.js status --json",
     "test": "node --test test/*.test.js"
   },
-  "version": "1.0.3",
+  "version": "1.0.5",
   "mcpName": "io.github.payload-tools/callx402"
 }

package/server.json

@@ -10,7 +10,7 @@
       "transport": {
         "type": "stdio"
       },
-      "version": "1.0.2"
+      "version": "1.0.5"
     }
   ],
   "repository": {
@@ -18,6 +18,6 @@
     "url": "https://github.com/Payloadhq/callx402"
   },
   "title": "callx402 MCP server",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "websiteUrl": "https://github.com/Payloadhq/callx402"
-}
+}

package/test/external-mcp-package.test.js

@@ -0,0 +1,84 @@
+'use strict';
+// Consumer smoke test for the actual npm artifact. Uses npm pack locally,
+// installs nothing, sends no financial transactions or production requests.
+const {test}=require('node:test');
+const assert=require('node:assert/strict');
+const fs=require('node:fs');
+const os=require('node:os');
+const path=require('node:path');
+const cp=require('node:child_process');
+const readline=require('node:readline');
+
+test('npm-packed callx402 exposes usable free MCP diagnosis to a clean consumer',async()=>{
+ const root=path.resolve(__dirname,'..');
+ const temp=fs.mkdtempSync(path.join(os.tmpdir(),'callx402-npm-consumer-'));
+ let proc;
+ try{
+   const pack=cp.spawnSync('npm',['pack','--ignore-scripts','--json','--pack-destination',temp],{
+     cwd:root,encoding:'utf8',timeout:30000});
+   assert.equal(pack.status,0,pack.stderr);
+   // Newer npm versions differ in --json metadata; inspect the actual artifact
+   // instead of relying on a particular stdout schema.
+   const filename=fs.readdirSync(temp).find(name=>name.endsWith('.tgz'));
+   assert.ok(filename,'npm pack must produce a tarball in '+temp+
+     ' (stdout: '+pack.stdout.slice(0,500)+')');
+   const bundle=path.join(temp,filename);
+   assert.ok(fs.existsSync(bundle),'packed npm tarball present');
+   const extracted=cp.spawnSync('tar',['-xzf',bundle,'-C',temp],{encoding:'utf8'});
+   assert.equal(extracted.status,0,extracted.stderr);
+   const entry=path.join(temp,'package','mcp','index.js');
+   assert.ok(fs.existsSync(entry),'MCP executable included in distributed npm archive');
+   proc=cp.spawn(process.execPath,[entry],{
+     cwd:temp,
+     env:{
+       ...process.env,
+       CALLX402_V2_ROOT:path.join(temp,'absent-v2'),
+       CALLX402_CONFIG:path.join(temp,'empty-config.json'),
+       CALLX402_MODE:'local',
+       CALLX402_CORE_PATH:path.join(temp,'package','core')
+     },
+     stdio:['pipe','pipe','pipe']
+   });
+   let stderr='';proc.stderr.on('data',d=>stderr+=d);
+   let id=0;const wait=new Map();
+   readline.createInterface({input:proc.stdout}).on('line',line=>{
+     try{const r=JSON.parse(line),fn=wait.get(r.id);if(fn){wait.delete(r.id);fn(r);}}catch{}
+   });
+   const rpc=(method,params)=>new Promise((resolve,reject)=>{
+     const n=++id,t=setTimeout(()=>{wait.delete(n);reject(new Error('MCP timeout '+stderr.slice(0,300)));},5000);
+     wait.set(n,result=>{clearTimeout(t);resolve(result);});
+     proc.stdin.write(JSON.stringify({jsonrpc:'2.0',id:n,method,params})+'\n');
+   });
+   assert.ok((await rpc('initialize',{protocolVersion:'2024-11-05',capabilities:{},
+     clientInfo:{name:'fresh-npm-consumer',version:'1.0'}})).result);
+   const tools=(await rpc('tools/list',{})).result?.tools||[];
+   for(const name of ['x402_diagnose','x402_evidence','x402_explain','x402_recover','x402_resolve','x402_status'])
+     assert.ok(tools.some(t=>t.name===name),'missing advertised tool '+name);
+   const diagnostic=await rpc('tools/call',{
+     name:'x402_diagnose',
+     arguments:{evidence:JSON.stringify({httpStatus:402,
+       failure:'client could not parse challenge',network:'base'})}
+   });
+   assert.ok(diagnostic.result,'MCP tool response exists');
+   const output=JSON.stringify(diagnostic.result);
+   assert.ok(!/subsystem_unreachable|Cannot find module|missing v2\.0\.0|could not be loaded/i.test(output),
+     'fresh npm package must not demand an unpublished sibling module: '+output.slice(0,600));
+   assert.equal(diagnostic.result.isError,false,
+     'free diagnostic must work from a clean published-style npm artifact: '+output.slice(0,600));
+   for (const [name,args] of [
+     ['x402_status',{}],
+     ['x402_evidence',{operationId:'operation-fixture'}],
+     ['x402_explain',{operationId:'operation-fixture'}],
+     ['x402_recover',{operationId:'operation-fixture'}],
+     ['x402_resolve',{evidence:JSON.stringify({txHash:'0x'+'a'.repeat(64),network:'base'})}]
+   ]) {
+     const response=await rpc('tools/call',{name,arguments:args});
+     assert.equal(response.result?.isError,false,
+       name+' must respond safely on clean npm install: '+JSON.stringify(response));
+     const data=JSON.parse(response.result.content[0].text);
+     if(name==='x402_recover') assert.equal(data.canRetry,false,'no unauthenticated automatic recovery');
+     if(name==='x402_resolve') assert.equal(data.settlement,'UNKNOWN','no synthetic proof of settlement');
+     if(name==='x402_evidence') assert.equal(data.basis,'NO_BASIS','no invented private ledger entries');
+   }
+ }finally{if(proc)proc.kill('SIGTERM');fs.rmSync(temp,{recursive:true,force:true});}
+});

package/test/mcp-full-subsystem-compat.test.js

@@ -0,0 +1,42 @@
+'use strict';
+const {test}=require('node:test');
+const assert=require('node:assert/strict');
+const fs=require('node:fs');
+const os=require('node:os');
+const path=require('node:path');
+const {spawn}=require('node:child_process');
+const readline=require('node:readline');
+
+test('configured full doctor remains preferred to free fallback after npm packaging fix',async()=>{
+ const temp=fs.mkdtempSync(path.join(os.tmpdir(),'callx402-legacy-compat-'));
+ const d=path.join(temp,'lib','mcp');fs.mkdirSync(d,{recursive:true});
+ fs.writeFileSync(path.join(d,'doctor.js'),
+   "module.exports={FLAG:'FAKE_DOCTOR',enabled:()=>true,runMcpDoctor:()=>({whatFailed:'CONFIGURED_DOCTOR_USED',stages:[]})};\n");
+ const proc=spawn(process.execPath,[path.join(__dirname,'..','mcp','index.js')],{
+   cwd:temp,env:{
+     ...process.env,CALLX402_V2_ROOT:temp,CALLX402_MODE:'local',
+     CALLX402_CONFIG:path.join(temp,'not-present.json'),
+     CALLX402_TIMEOUT_MS:'5000'
+   },stdio:['pipe','pipe','pipe']
+ });
+ let id=0,err='';const pending=new Map();
+ proc.stderr.on('data',b=>err+=b);
+ readline.createInterface({input:proc.stdout}).on('line',line=>{
+   try{const r=JSON.parse(line),fn=pending.get(r.id);if(fn){pending.delete(r.id);fn(r);}}catch{}
+ });
+ function rpc(method,params){
+   return new Promise((resolve,reject)=>{
+     const n=++id,t=setTimeout(()=>{pending.delete(n);reject(Error('timeout '+err.slice(0,200)));},4000);
+     pending.set(n,v=>{clearTimeout(t);resolve(v);});
+     proc.stdin.write(JSON.stringify({jsonrpc:'2.0',id:n,method,params})+'\n');
+   });
+ }
+ try {
+   const r=await rpc('tools/call',{name:'x402_diagnose',
+     arguments:{evidence:JSON.stringify({httpStatus:402})}});
+   assert.equal(r.result?.isError,false,JSON.stringify(r));
+   const payload=JSON.parse(r.result.content[0].text);
+   assert.equal(payload.data.report.whatFailed,'CONFIGURED_DOCTOR_USED',
+     'configured full-subsystem dispatch must not silently be replaced by free approximation');
+ }finally{proc.kill('SIGTERM');fs.rmSync(temp,{recursive:true,force:true});}
+});