callx402 1.0.3 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -3
- package/bin/callx402.js +11 -7
- package/core/rail.js +1 -1
- package/core/subsystems.js +10 -2
- package/docs/problem-map.md +19 -8
- package/integrations/core.py +11 -2
- package/integrations/langchain/callx402_tools.py +5 -2
- package/mcp/index.js +46 -13
- package/package.json +1 -1
- package/server.json +2 -2
package/README.md
CHANGED
|
@@ -328,13 +328,79 @@ redemption is not currently enabled. Stripe credits use a separate redemption pa
|
|
|
328
328
|
|
|
329
329
|
Live fee schedule: `GET https://payload-rail.fly.dev/v1/callx402/actions`
|
|
330
330
|
(responds `"model":"paid on-demand per action; no subscription required"`).
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
331
|
+
There are two prices per action, and they are not interchangeable: the
|
|
332
|
+
**card price** is the Stripe schedule fee; the **USDC price** on the x402
|
|
333
|
+
path is exactly that fee divided by 20 (the free quote endpoint is the
|
|
334
|
+
source of truth for the USDC column). Both, side by side:
|
|
335
|
+
|
|
336
|
+
| Action | Card (Stripe) | USDC (x402 path) |
|
|
337
|
+
|---|---|---|
|
|
338
|
+
| `diagnose` | $2.00 | $0.10 |
|
|
339
|
+
| `explain` | $1.00 | $0.05 |
|
|
340
|
+
| `evidence` | $2.00 | $0.10 |
|
|
341
|
+
| `recover` | $10.00 | $0.50 |
|
|
342
|
+
| `resolve` | $5.00 | $0.25 |
|
|
343
|
+
| `preflight` | $3.00 | $0.15 |
|
|
344
|
+
| `settlement_interpretation` | $3.00 | $0.15 |
|
|
345
|
+
| `failure_classification` | $2.00 | $0.10 |
|
|
346
|
+
| `duplicate_payment_risk` | $5.00 | $0.25 |
|
|
347
|
+
|
|
348
|
+
Rail `evidence` and `explain` read back a prior paid invocation (the
|
|
349
|
+
request carries that invocation's `invocation_id`), so they cannot be used
|
|
350
|
+
cold; the free local forms read your local operation ledger instead.
|
|
351
|
+
|
|
352
|
+
**Not sold on the rail:** `safe_retry`, `rescue`, `monitor`, and `execute`
|
|
353
|
+
are local-only. They run in the self-hosted runtime (v2.0.0 tree), are
|
|
354
|
+
absent from the rail catalog above, and the rail refuses them with
|
|
355
|
+
`422 HOSTED_ACTION_UNAVAILABLE` — there is no Stripe or x402 purchase path
|
|
356
|
+
for them. For the "is this retry safe?" question, the free local `recover`
|
|
357
|
+
verdict is the available read-only answer.
|
|
358
|
+
|
|
359
|
+
Never blind-retry a payment to reach a paid action: get the quote first.
|
|
334
360
|
|
|
335
361
|
Problem to action map (which paid action answers which failure, with the free
|
|
336
362
|
CLI/MCP path for each): [`docs/problem-map.md`](docs/problem-map.md).
|
|
337
363
|
|
|
364
|
+
## Public RevRule evaluation (0.01 USDC)
|
|
365
|
+
|
|
366
|
+
The rail also exposes one public RevRule evaluation endpoint. It is a
|
|
367
|
+
RevRule demo, not a callx402 diagnostic action:
|
|
368
|
+
`POST https://payload-rail.fly.dev/v1/x402/public/evaluate` evaluates one
|
|
369
|
+
economic event against the fixed, transparent public demo graph (platform
|
|
370
|
+
5% of gross; creator 70% of the remainder; referrer 25% of the remainder
|
|
371
|
+
when a referrer is named in the event) for 0.01 USDC on Base.
|
|
372
|
+
|
|
373
|
+
The full, correct request body is:
|
|
374
|
+
|
|
375
|
+
```json
|
|
376
|
+
{
|
|
377
|
+
"event": {
|
|
378
|
+
"eventId": "my-event-001",
|
|
379
|
+
"type": "SALE_COMPLETED",
|
|
380
|
+
"rail": "stripe",
|
|
381
|
+
"amountMicros": 100000000,
|
|
382
|
+
"currency": "USD",
|
|
383
|
+
"occurredAt": "2026-10-13T00:00:00.000Z"
|
|
384
|
+
},
|
|
385
|
+
"txHash": "0x<your settled 0.01 USDC payment on Base>"
|
|
386
|
+
}
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
- `event.eventId` (any unique non-empty string) and `event.rail` are
|
|
390
|
+
**required**, even though the 402's advertised bazaar schema omits both.
|
|
391
|
+
Valid `rail` values: `stripe`, `ach`, `x402`, `manual`, `stablecoin`.
|
|
392
|
+
- `event.type` must be one of: `SALE_COMPLETED`, `API_PAYMENT`,
|
|
393
|
+
`LICENSE_PAID`, `SUBSCRIPTION_PAYMENT`, `REFERRAL_CONVERTED`,
|
|
394
|
+
`ROYALTY_RECEIVED`, `CAMPAIGN_MILESTONE`, `MARKETPLACE_TRANSACTION`,
|
|
395
|
+
`TOUCH`.
|
|
396
|
+
- The event is validated **before** payment: a malformed body gets
|
|
397
|
+
`400 INVALID_EVENT`, not a 402 (verified live: the body above, minus
|
|
398
|
+
`txHash`, returns the 402). The endpoint fills in the rest itself —
|
|
399
|
+
`graphId` is fixed to the public demo graph, and `currency` defaults to
|
|
400
|
+
`"USD"` and `occurredAt` to now when omitted.
|
|
401
|
+
- Omit `txHash` to receive the x402 v2 `402` challenge; pay 0.01 USDC,
|
|
402
|
+
then retry the same body with the hash. Each txHash is single-use.
|
|
403
|
+
|
|
338
404
|
## Integrations
|
|
339
405
|
|
|
340
406
|
Working entry points for agent frameworks, automation, MCP clients, and x402
|
package/bin/callx402.js
CHANGED
|
@@ -222,9 +222,11 @@ never executes, never repays. Requires PAYLOAD_VEYLINE_RECOVERY=1.
|
|
|
222
222
|
|
|
223
223
|
This is the read-only answer to "is a retry safe?" — a SAFE_RETRY verdict
|
|
224
224
|
here is advisory; performing the safe action stays with your own adapters.
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
225
|
+
There is NO paid rail form of 'safe_retry': the hosted rail refuses it as
|
|
226
|
+
local-only (it is absent from the rail catalog and cannot be bought via
|
|
227
|
+
Stripe or x402). This free recover verdict is the read-only answer
|
|
228
|
+
available without the self-hosted runtime tree (see docs/problem-map.md).
|
|
229
|
+
The MCP tool x402_recover covers the same free diagnostic.
|
|
228
230
|
|
|
229
231
|
Exit codes: 0 ok · 1 failure · 2 usage (missing identity/evidence) ·
|
|
230
232
|
3 disabled/unreachable · 4 budget refused ·
|
|
@@ -256,14 +258,16 @@ Usage:
|
|
|
256
258
|
callx402 "natural language intent" intent mode (plans, never executes blindly)
|
|
257
259
|
callx402 --help | --version
|
|
258
260
|
|
|
259
|
-
Commands (hosted by default — zero setup
|
|
261
|
+
Commands (rail actions hosted by default — zero setup; local-only
|
|
262
|
+
commands marked, they need the v2.0.0 runtime tree and are NOT sold on
|
|
263
|
+
the hosted rail):
|
|
260
264
|
diagnose run the x402 doctor over supplied evidence [--target <url|json>] [--evidence <json|@file>]
|
|
261
|
-
rescue incident triage (auth-gated; read-only without auth) --incident <id>
|
|
265
|
+
rescue incident triage, local only (auth-gated; read-only without auth) --incident <id>
|
|
262
266
|
route select a tool/route for a goal --goal <text>
|
|
263
267
|
resolve resolve settlement state from evidence --evidence <json|@file>
|
|
264
268
|
doctor alias of diagnose
|
|
265
|
-
execute run the intent pipeline
|
|
266
|
-
monitor sentinel snapshot [--once] or stream [--watch]
|
|
269
|
+
execute run the intent pipeline, local only --intent <text> [--max-budget N] [--dry-run] [--idempotency-key K]
|
|
270
|
+
monitor sentinel snapshot, local only [--once] or stream [--watch]
|
|
267
271
|
status per-subsystem reachable/enabled/version report
|
|
268
272
|
preflight run MCP preflight checks
|
|
269
273
|
inspect capability-graph lookup/stats [--query <text>]
|
package/core/rail.js
CHANGED
|
@@ -156,7 +156,7 @@ async function invokeRail(command, args, opts = {}) {
|
|
|
156
156
|
if (!interactive) {
|
|
157
157
|
return {
|
|
158
158
|
ok: false,
|
|
159
|
-
error: `Payment of $${price} required. Re-run with --
|
|
159
|
+
error: `Payment of $${price} required. Re-run with --approve to approve non-interactively, or run interactively.`,
|
|
160
160
|
quote: { action, price_usd: price, quote_id: quoteId, quote_inputs: quote.quote_inputs },
|
|
161
161
|
};
|
|
162
162
|
}
|
package/core/subsystems.js
CHANGED
|
@@ -52,6 +52,14 @@ const NOTES = {
|
|
|
52
52
|
recovery: 'File-backed idempotency store used for duplicate-idempotencyKey dedupe.',
|
|
53
53
|
};
|
|
54
54
|
|
|
55
|
+
/** First line only: Node require errors append a multi-line "Require stack:"
|
|
56
|
+
* dump that helps nobody in a status report or an MCP tool result. The short
|
|
57
|
+
* form still names the missing module and stays actionable. */
|
|
58
|
+
function briefError(err) {
|
|
59
|
+
const msg = err && err.message ? String(err.message) : String(err || 'unknown error');
|
|
60
|
+
return msg.split('\n')[0].trim();
|
|
61
|
+
}
|
|
62
|
+
|
|
55
63
|
function defaultV2Root() {
|
|
56
64
|
return path.resolve(__dirname, '../../x402-paid-api-starter-kit/v2.0.0');
|
|
57
65
|
}
|
|
@@ -98,7 +106,7 @@ function getSubsystem(name, { config = {}, deps = {} } = {}) {
|
|
|
98
106
|
try {
|
|
99
107
|
mod = requireFiles(v2Root, MODULE_FILES[name]);
|
|
100
108
|
} catch (err) {
|
|
101
|
-
return { name, reachable: false, module: null, enabled: false, flag: null, version: null, note: NOTES[name] || null, subsystemStatus: 'unreachable', error: `require failed: ${err
|
|
109
|
+
return { name, reachable: false, module: null, enabled: false, flag: null, version: null, note: NOTES[name] || null, subsystemStatus: 'unreachable', error: `require failed: ${briefError(err)}` };
|
|
102
110
|
}
|
|
103
111
|
|
|
104
112
|
let flag = null;
|
|
@@ -107,7 +115,7 @@ function getSubsystem(name, { config = {}, deps = {} } = {}) {
|
|
|
107
115
|
flag = typeof mod.FLAG === 'string' ? mod.FLAG : null;
|
|
108
116
|
enabled = typeof mod.enabled === 'function' ? mod.enabled() : false;
|
|
109
117
|
} catch (err) {
|
|
110
|
-
return { name, reachable: true, module: mod, enabled: false, flag, version: null, note: NOTES[name] || null, subsystemStatus: 'disabled', error: `enabled() check failed: ${err
|
|
118
|
+
return { name, reachable: true, module: mod, enabled: false, flag, version: null, note: NOTES[name] || null, subsystemStatus: 'disabled', error: `enabled() check failed: ${briefError(err)}` };
|
|
111
119
|
}
|
|
112
120
|
|
|
113
121
|
const version = mod.version || mod.RESCUE_VERSION || mod.EFFECT_PROOF_VERSION || null;
|
package/docs/problem-map.md
CHANGED
|
@@ -25,7 +25,13 @@ v2.0.0 runtime tree and `CALLX402_LOCAL=1`). The paid form runs on the
|
|
|
25
25
|
production rail: quote first, payment verified exactly once, then the
|
|
26
26
|
diagnostic executes server-side and the result is returned — zero local setup.
|
|
27
27
|
The "Free path" column names the free equivalent; "rail only" means the action
|
|
28
|
-
exists only as a paid rail action.
|
|
28
|
+
exists only as a paid rail action. "Local only" means the opposite: the action
|
|
29
|
+
exists ONLY locally (self-hosted runtime tree). The hosted rail refuses it
|
|
30
|
+
with `422 HOSTED_ACTION_UNAVAILABLE`, it is absent from the rail catalog
|
|
31
|
+
(`GET /v1/callx402/actions` lists nine actions), and there is no Stripe or
|
|
32
|
+
x402 purchase path for it. Four actions are local-only: `safe_retry`,
|
|
33
|
+
`rescue`, `monitor`, `execute`. Their fee cells below show the schedule
|
|
34
|
+
figure for reference only — it cannot be paid on the rail.
|
|
29
35
|
|
|
30
36
|
**Fees.** The table lists the Stripe-path fee per action. The x402 path
|
|
31
37
|
quoted by the free quote endpoint is exactly that fee divided by 20
|
|
@@ -40,16 +46,16 @@ deterministic, not an estimate.
|
|
|
40
46
|
| 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 |
|
|
41
47
|
| 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 |
|
|
42
48
|
| 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 |
|
|
43
|
-
| 4 | Retry uncertainty, narrowed — is THIS specific retry safe to sign? | `safe_retry` | $5.00
|
|
49
|
+
| 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 |
|
|
44
50
|
| 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 |
|
|
45
51
|
| 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 |
|
|
46
52
|
| 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 |
|
|
47
53
|
| 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 |
|
|
48
54
|
| 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 |
|
|
49
55
|
| 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 |
|
|
50
|
-
| 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 |
|
|
51
|
-
| 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 |
|
|
52
|
-
| 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 |
|
|
56
|
+
| 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 |
|
|
57
|
+
| 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 |
|
|
58
|
+
| 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 |
|
|
53
59
|
|
|
54
60
|
## Where each surface consumes this map
|
|
55
61
|
|
|
@@ -70,9 +76,14 @@ deterministic, not an estimate.
|
|
|
70
76
|
## Notes
|
|
71
77
|
|
|
72
78
|
- Action names are canonical in `snake_case`. The rail also accepts the
|
|
73
|
-
hyphenated aliases shown in the OpenAPI enum (`
|
|
74
|
-
`
|
|
75
|
-
`
|
|
79
|
+
hyphenated aliases shown in the OpenAPI enum (`duplicate-payment-risk`,
|
|
80
|
+
`settlement-interpretation`, `failure-classification`); both forms resolve
|
|
81
|
+
identically (verified live). `safe-retry` is not a rail action in either
|
|
82
|
+
spelling — it is local-only (see the two-tiers note above).
|
|
83
|
+
- Rail `evidence` / `explain` read back a PRIOR paid invocation: the request
|
|
84
|
+
must carry that invocation's `invocation_id`, and the rail returns
|
|
85
|
+
`400 MISSING_INPUT` without one, so they cannot be used cold. The free
|
|
86
|
+
local forms in the map read your local operation ledger instead.
|
|
76
87
|
- The x402-path quote is the valuation-layer quote, not the raw schedule;
|
|
77
88
|
the fixed schedule above is the Stripe-path floor.
|
|
78
89
|
- Local CLI / MCP-stdio diagnostics are free and read-only — no payment, no
|
package/integrations/core.py
CHANGED
|
@@ -5,7 +5,7 @@ Plain functions (no framework imports) so LangChain, CrewAI, AutoGen, or any
|
|
|
5
5
|
agent framework can wrap them directly. stdlib only.
|
|
6
6
|
|
|
7
7
|
The rail's public endpoints:
|
|
8
|
-
GET /v1/callx402/actions free — live
|
|
8
|
+
GET /v1/callx402/actions free — live fee schedule (9 hosted actions)
|
|
9
9
|
GET /v1/callx402/quote free — deterministic pre-execution quote
|
|
10
10
|
POST /v1/callx402/actions/{action} paid — unauthenticated -> x402 v2 402
|
|
11
11
|
(USDC on Base); credit_id / txHash /
|
|
@@ -30,6 +30,13 @@ RAIL = os.environ.get("CALLX402_RAIL", "https://payload-rail.fly.dev").rstrip("/
|
|
|
30
30
|
|
|
31
31
|
# Canonical action names (snake_case), verified live 2026-10-07.
|
|
32
32
|
# Hyphenated aliases are also accepted by the rail; these are canonical.
|
|
33
|
+
# AVAILABILITY (verified live 2026-10-13): only 9 of these 13 are hosted and
|
|
34
|
+
# purchasable on the rail — diagnose, explain, evidence, recover, resolve,
|
|
35
|
+
# preflight, settlement_interpretation, failure_classification,
|
|
36
|
+
# duplicate_payment_risk. The other four (safe_retry, rescue, monitor,
|
|
37
|
+
# execute) are LOCAL-ONLY: the rail refuses them with
|
|
38
|
+
# 422 HOSTED_ACTION_UNAVAILABLE, they are absent from the rail catalog, and
|
|
39
|
+
# they cannot be bought via Stripe or x402.
|
|
33
40
|
ACTIONS = (
|
|
34
41
|
"diagnose", "explain", "evidence", "recover", "resolve", "preflight",
|
|
35
42
|
"monitor", "execute", "rescue", "settlement_interpretation", "safe_retry",
|
|
@@ -303,7 +310,9 @@ FREE_LOCAL_ALTERNATIVE = (
|
|
|
303
310
|
"Local CLI / MCP-stdio diagnostics are free and read-only "
|
|
304
311
|
"(git clone https://github.com/Payloadhq/callx402; "
|
|
305
312
|
"node mcp/index.js as an MCP server). The paid rail actions above are "
|
|
306
|
-
"for hosted on-demand invocation with payment."
|
|
313
|
+
"for hosted on-demand invocation with payment. Note: safe_retry, "
|
|
314
|
+
"rescue, monitor, and execute are local-only and are NOT purchasable "
|
|
315
|
+
"on the hosted rail."
|
|
307
316
|
)
|
|
308
317
|
|
|
309
318
|
|
|
@@ -125,8 +125,11 @@ def callx402_explain(operation_id: str) -> str:
|
|
|
125
125
|
def callx402_safe_retry(retry_plan: str) -> str:
|
|
126
126
|
"""Go/no-go verdict on ONE specific retry plan before anything is signed.
|
|
127
127
|
Use when a retry is being considered and must be proven safe first.
|
|
128
|
-
|
|
129
|
-
|
|
128
|
+
AVAILABILITY: safe_retry is LOCAL-ONLY — the hosted rail refuses it
|
|
129
|
+
(422 HOSTED_ACTION_UNAVAILABLE) and it cannot be bought via Stripe or
|
|
130
|
+
x402, so this tool currently surfaces that refusal. For the
|
|
131
|
+
retry-safety question today, use callx402_recover's read-only verdict.
|
|
132
|
+
A retry that would double-pay is refused."""
|
|
130
133
|
return _render(invoke("safe_retry", {"retry_plan": retry_plan}, **_auth()))
|
|
131
134
|
|
|
132
135
|
|
package/mcp/index.js
CHANGED
|
@@ -18,13 +18,21 @@
|
|
|
18
18
|
* Only read-only / diagnostic actions are exposed. Actions with side effects
|
|
19
19
|
* (execute, rescue mutations) are intentionally NOT tools here.
|
|
20
20
|
*
|
|
21
|
+
* Honest surface: ONLY x402_status works on a bare install of this package.
|
|
22
|
+
* The other five tools dispatch into the v2.0.0 subsystem tree (the x402
|
|
23
|
+
* Paid API Starter Kit — a separate product that is NOT bundled here) and
|
|
24
|
+
* return `subsystem_unreachable` until CALLX402_V2_ROOT points at that tree
|
|
25
|
+
* and the matching feature flag is enabled. These tools never call the
|
|
26
|
+
* hosted rail; paid hosted equivalents live at
|
|
27
|
+
* https://payloadhq.github.io/agents.json.
|
|
28
|
+
*
|
|
21
29
|
* Usage (Claude Desktop / MCP client config):
|
|
22
30
|
* { "command": "node", "args": ["/path/to/callx402/mcp/index.js"] }
|
|
23
31
|
* Env: CALLX402_CONFIG, CALLX402_V2_ROOT, CALLX402_TIMEOUT_MS (default 30000).
|
|
24
32
|
*/
|
|
25
33
|
const readline = require('node:readline');
|
|
26
34
|
|
|
27
|
-
const VERSION = '1.0.
|
|
35
|
+
const VERSION = '1.0.4';
|
|
28
36
|
const PROTOCOL_VERSION = '2024-11-05';
|
|
29
37
|
const SERVER_NAME = 'callx402';
|
|
30
38
|
const TIMEOUT_MS = Number(process.env.CALLX402_TIMEOUT_MS || 30000);
|
|
@@ -34,7 +42,29 @@ const core = require(process.env.CALLX402_CORE_PATH ||
|
|
|
34
42
|
|
|
35
43
|
/* ------------------------------------------------------------------ */
|
|
36
44
|
/* Tool definitions: name, description, input schema, core action. */
|
|
45
|
+
/* */
|
|
46
|
+
/* Requirement trailers, stated in every description because the */
|
|
47
|
+
/* description is what an MCP client actually shows the user: */
|
|
48
|
+
/* TREE_REQUIRED — dispatches into the v2.0.0 subsystem tree, which */
|
|
49
|
+
/* is NOT part of this package. */
|
|
50
|
+
/* LEDGER_REQUIRED — reads the local Veyline operation ledger via */
|
|
51
|
+
/* modules that are likewise not bundled here. */
|
|
37
52
|
/* ------------------------------------------------------------------ */
|
|
53
|
+
const TREE_REQUIRED =
|
|
54
|
+
' Requires the v2.0.0 subsystem tree (x402 Paid API Starter Kit, a separate ' +
|
|
55
|
+
'product that is NOT included in this package): set CALLX402_V2_ROOT to the ' +
|
|
56
|
+
'tree and enable the subsystem flag, or this tool returns ' +
|
|
57
|
+
'subsystem_unreachable and does nothing. With the tree configured it is free ' +
|
|
58
|
+
'and read-only: no payment, no auth. A paid hosted equivalent runs on the ' +
|
|
59
|
+
'Payload rail — see https://payloadhq.github.io/agents.json.';
|
|
60
|
+
const ledgerRequired = (flag) =>
|
|
61
|
+
' Requires the local Veyline ledger modules (NOT included in this package; ' +
|
|
62
|
+
`enable with ${flag}=1 where the ledger lives) and reads ` +
|
|
63
|
+
'operations recorded on THIS machine — it cannot read back hosted rail ' +
|
|
64
|
+
'invocations. Until configured it returns subsystem_unreachable and does ' +
|
|
65
|
+
'nothing. When configured it is free and read-only: no payment, no auth.';
|
|
66
|
+
const LEDGER_REQUIRED = ledgerRequired('PAYLOAD_VEYLINE_LEDGER');
|
|
67
|
+
|
|
38
68
|
const TOOLS = [
|
|
39
69
|
{
|
|
40
70
|
name: 'x402_diagnose',
|
|
@@ -43,8 +73,8 @@ const TOOLS = [
|
|
|
43
73
|
'Run the x402 doctor over supplied evidence. Use when something went ' +
|
|
44
74
|
'wrong with an x402 payment or MCP/x402 interaction and you need a ' +
|
|
45
75
|
'diagnosis. Input: evidence as a JSON string or object describing the ' +
|
|
46
|
-
'failure (error strings, responses, tx hashes). Read-only.
|
|
47
|
-
|
|
76
|
+
'failure (error strings, responses, tx hashes). Read-only.' +
|
|
77
|
+
TREE_REQUIRED,
|
|
48
78
|
inputSchema: {
|
|
49
79
|
type: 'object',
|
|
50
80
|
properties: {
|
|
@@ -66,8 +96,8 @@ const TOOLS = [
|
|
|
66
96
|
description:
|
|
67
97
|
'Show recorded ledger evidence for an operation: event trail, latest ' +
|
|
68
98
|
'per-plane states (payment / execution / delivery), protocols involved. ' +
|
|
69
|
-
'Use FIRST in any incident — establishes ground truth before acting. Read-only.
|
|
70
|
-
|
|
99
|
+
'Use FIRST in any incident — establishes ground truth before acting. Read-only.' +
|
|
100
|
+
LEDGER_REQUIRED,
|
|
71
101
|
inputSchema: {
|
|
72
102
|
type: 'object',
|
|
73
103
|
properties: {
|
|
@@ -84,8 +114,8 @@ const TOOLS = [
|
|
|
84
114
|
'Explain an operation\'s state in plain language from recorded evidence. ' +
|
|
85
115
|
'Returns an assessment: NO_BASIS, INCOMPLETE (do not retry, do not repay), ' +
|
|
86
116
|
'KNOWN_SAFE, RECOVERY_CANDIDATE, or PARTIAL. Use to understand an incident ' +
|
|
87
|
-
'before deciding whether to retry, refund, or escalate. Read-only.
|
|
88
|
-
|
|
117
|
+
'before deciding whether to retry, refund, or escalate. Read-only.' +
|
|
118
|
+
LEDGER_REQUIRED,
|
|
89
119
|
inputSchema: {
|
|
90
120
|
type: 'object',
|
|
91
121
|
properties: {
|
|
@@ -102,8 +132,8 @@ const TOOLS = [
|
|
|
102
132
|
'Report the safe recovery decision for an operation whose result was lost ' +
|
|
103
133
|
'(paid but no result). READ-ONLY: nothing is charged, nothing is executed. ' +
|
|
104
134
|
'Returns RECOVERABLE/SAFE_RETRY -> KNOWN_SAFE, or HUMAN_REVIEW. Use for ' +
|
|
105
|
-
'the exact situation where blind retry would double-pay or double-execute.
|
|
106
|
-
'
|
|
135
|
+
'the exact situation where blind retry would double-pay or double-execute.' +
|
|
136
|
+
ledgerRequired('PAYLOAD_VEYLINE_RECOVERY'),
|
|
107
137
|
inputSchema: {
|
|
108
138
|
type: 'object',
|
|
109
139
|
properties: {
|
|
@@ -119,8 +149,8 @@ const TOOLS = [
|
|
|
119
149
|
action: 'resolve',
|
|
120
150
|
description:
|
|
121
151
|
'Resolve settlement state from evidence (e.g. settlement_pending: was the ' +
|
|
122
|
-
'broadcast transaction confirmed on chain?). Use instead of blind retry. Read-only.
|
|
123
|
-
|
|
152
|
+
'broadcast transaction confirmed on chain?). Use instead of blind retry. Read-only.' +
|
|
153
|
+
TREE_REQUIRED,
|
|
124
154
|
inputSchema: {
|
|
125
155
|
type: 'object',
|
|
126
156
|
properties: {
|
|
@@ -137,8 +167,11 @@ const TOOLS = [
|
|
|
137
167
|
action: 'status',
|
|
138
168
|
description:
|
|
139
169
|
'Check callx402 subsystem reachability (which diagnostic subsystems are ' +
|
|
140
|
-
'available). Use to verify the tool is operational before diagnosing.
|
|
141
|
-
'
|
|
170
|
+
'available). Use to verify the tool is operational before diagnosing. ' +
|
|
171
|
+
'Read-only. This is the one tool that works with zero setup in any ' +
|
|
172
|
+
'install — no key, no tree, no payment. On a bare npm install it ' +
|
|
173
|
+
'honestly reports 0/15 subsystems reachable: the other five tools need ' +
|
|
174
|
+
'the v2.0.0 subsystem tree (CALLX402_V2_ROOT) before they can answer.',
|
|
142
175
|
inputSchema: { type: 'object', properties: {} },
|
|
143
176
|
},
|
|
144
177
|
];
|
package/package.json
CHANGED
package/server.json
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
"transport": {
|
|
11
11
|
"type": "stdio"
|
|
12
12
|
},
|
|
13
|
-
"version": "1.0.
|
|
13
|
+
"version": "1.0.3"
|
|
14
14
|
}
|
|
15
15
|
],
|
|
16
16
|
"repository": {
|
|
@@ -18,6 +18,6 @@
|
|
|
18
18
|
"url": "https://github.com/Payloadhq/callx402"
|
|
19
19
|
},
|
|
20
20
|
"title": "callx402 MCP server",
|
|
21
|
-
"version": "1.0.
|
|
21
|
+
"version": "1.0.3",
|
|
22
22
|
"websiteUrl": "https://github.com/Payloadhq/callx402"
|
|
23
23
|
}
|