agentshield-live 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -0
- package/agent-kit.mjs +37 -14
- package/package.json +20 -4
- package/tools.json +3 -3
package/README.md
CHANGED
|
@@ -29,6 +29,27 @@ const out = await shield.call("agentshield_invoice", {
|
|
|
29
29
|
|
|
30
30
|
`choose` is free. `call` pays the live 402 price, and refuses if that price is above `maxUsdc`.
|
|
31
31
|
|
|
32
|
+
## Cost log
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
const shield = createAgentShield({
|
|
36
|
+
maxUsdc: 0.05,
|
|
37
|
+
onPay: (p) => console.log(`[agentshield] ${p.route} ${p.price_usdc} USDC ok=${p.ok} tx=${p.transaction}`),
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`onPay` runs after each settled payment with `tool`, `route`, `price_usdc`, `status`, `ok`, `failed`, `transaction`, `network` and `payer`. Silent when not set. An error inside it does not break the call.
|
|
42
|
+
|
|
43
|
+
## Dry run (CI, no key)
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
const shield = createAgentShield({ dryRun: true }); // or AGENTSHIELD_DRY_RUN=1
|
|
47
|
+
await shield.call("agentshield_invoice", { net: "100.00", gross: "119.00", country: "DE" });
|
|
48
|
+
// { dryRun: true, status: 402, charged: false, route: "/invoice", price_usdc: 0.03, would_pay: true, ... }
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
A dry run sends only the unpaid request. It returns the live price from the 402, or the free 404 for missing or unknown input. It never pays and never returns a check result.
|
|
52
|
+
|
|
32
53
|
OpenClaw: `openclaw skills install @bartelmost/agentshield-verify`
|
|
33
54
|
|
|
34
55
|
Rehearse the payment flow on Base Sepolia: https://agentshield.live/try.md
|
package/agent-kit.mjs
CHANGED
|
@@ -25,10 +25,22 @@ export const tools = [
|
|
|
25
25
|
parameters: q({ task: s("One sentence: what you are about to do or look up") }, ["task"]) },
|
|
26
26
|
];
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
28
|
+
// Options:
|
|
29
|
+
// maxUsdc hard per-call cap. A call above it is not made.
|
|
30
|
+
// onPay optional callback after each paid call: { tool, route, price_usdc, status, ok, failed, transaction, network, payer }.
|
|
31
|
+
// Silent when not set. Example: onPay: (p) => console.log(`[agentshield] ${p.route} ${p.price_usdc} USDC ${p.transaction}`)
|
|
32
|
+
// dryRun no payment and no key needed. Each call sends the unpaid request and returns the live price from the 402
|
|
33
|
+
// ({ dryRun: true, would_pay, price_usdc, ... }) or the free 404. It never returns a made-up check result.
|
|
34
|
+
// Also on with env AGENTSHIELD_DRY_RUN=1, for CI. A real check needs a real payment; rehearse on Base Sepolia at /try.md.
|
|
35
|
+
export function createAgentShield({ key = process.env.X402_PAYER_KEY, ref = process.env.X402_REF, maxUsdc = 0.1, onPay = null,
|
|
36
|
+
dryRun = process.env.AGENTSHIELD_DRY_RUN === "1" } = {}) {
|
|
37
|
+
let paidFetch = null;
|
|
38
|
+
if (!dryRun) {
|
|
39
|
+
if (!key) throw new Error("Set X402_PAYER_KEY, or pass dryRun: true. The key is yours; it never leaves your machine.");
|
|
40
|
+
const account = privateKeyToAccount(key.startsWith("0x") ? key : `0x${key}`);
|
|
41
|
+
paidFetch = wrapFetchWithPayment(globalThis.fetch, new x402Client().register("eip155:8453", new ExactEvmScheme(account)));
|
|
42
|
+
}
|
|
43
|
+
const decode = (h) => { try { return h ? JSON.parse(Buffer.from(h, "base64").toString()) : null; } catch { return null; } };
|
|
32
44
|
|
|
33
45
|
async function choose(task) {
|
|
34
46
|
const r = await fetch(`${BASE}/mcp`, { method: "POST", headers: { "content-type": "application/json" },
|
|
@@ -44,18 +56,29 @@ export function createAgentShield({ key = process.env.X402_PAYER_KEY, ref = proc
|
|
|
44
56
|
const clean = {};
|
|
45
57
|
for (const [k, v] of Object.entries(args)) if (v !== undefined && v !== "") clean[k] = String(v);
|
|
46
58
|
// The five bundles take a JSON body (POST), so IBANs and names never appear in a URL.
|
|
47
|
-
const init = { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(clean) };
|
|
48
|
-
const probe = await fetch(url, init);
|
|
49
|
-
if (probe.status === 402) {
|
|
50
|
-
const hdr = probe.headers.get("payment-required");
|
|
51
|
-
const price = hdr ? Number(JSON.parse(Buffer.from(hdr, "base64").toString()).accepts[0].amount) / 1e6 : null;
|
|
52
|
-
if (price !== null && price > maxUsdc) return { error: `price ${price} USDC exceeds maxUsdc ${maxUsdc}` };
|
|
53
|
-
}
|
|
54
59
|
const headers = { accept: "application/json", "content-type": "application/json" };
|
|
55
60
|
if (ref) headers["x-agent-ref"] = ref;
|
|
56
|
-
const
|
|
57
|
-
|
|
61
|
+
const body = JSON.stringify(clean);
|
|
62
|
+
const probe = await fetch(url, { method: "POST", headers, body });
|
|
63
|
+
// Not 402: a free 404 (unknown input, not charged, do not retry) or an error. Nothing was paid.
|
|
64
|
+
if (probe.status !== 402) return { status: probe.status, charged: false, ...(await probe.json().catch(() => ({}))) };
|
|
65
|
+
const req = decode(probe.headers.get("payment-required"));
|
|
66
|
+
const accept = req?.accepts?.[0];
|
|
67
|
+
const price = accept ? Number(accept.amount) / 1e6 : null;
|
|
68
|
+
if (dryRun) return { dryRun: true, status: 402, charged: false, route: tool.route, price_usdc: price, network: accept?.network ?? null,
|
|
69
|
+
would_pay: price !== null && price <= maxUsdc, note: "Dry run: price from the live 402. No payment, no check result." };
|
|
70
|
+
if (price === null || price > maxUsdc) return { error: `price ${price} USDC exceeds maxUsdc ${maxUsdc}`, charged: false };
|
|
71
|
+
const res = await paidFetch(url, { method: "POST", headers, body });
|
|
72
|
+
const out = { status: res.status, ...(await res.json().catch(() => ({}))) };
|
|
73
|
+
const settle = decode(res.headers.get("payment-response"));
|
|
74
|
+
if (onPay && settle) {
|
|
75
|
+
try {
|
|
76
|
+
await onPay({ tool: name, route: tool.route, price_usdc: price, status: res.status, ok: out.ok ?? null, failed: out.failed ?? [],
|
|
77
|
+
transaction: settle.transaction ?? null, network: settle.network ?? accept.network, payer: settle.payer ?? null });
|
|
78
|
+
} catch { /* a logging hook must not break the call */ }
|
|
79
|
+
}
|
|
80
|
+
return out;
|
|
58
81
|
}
|
|
59
82
|
|
|
60
|
-
return { tools, choose, call };
|
|
83
|
+
return { tools, choose, call, dryRun };
|
|
61
84
|
}
|
package/package.json
CHANGED
|
@@ -1,21 +1,37 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentshield-live",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Verify before you act. Tool definitions and a paying caller for agentshield.live checks (x402, USDC on Base).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./agent-kit.mjs",
|
|
7
7
|
"exports": {
|
|
8
8
|
".": "./agent-kit.mjs"
|
|
9
9
|
},
|
|
10
|
-
"files": [
|
|
10
|
+
"files": [
|
|
11
|
+
"agent-kit.mjs",
|
|
12
|
+
"tools.json",
|
|
13
|
+
"README.md",
|
|
14
|
+
"LICENSE"
|
|
15
|
+
],
|
|
11
16
|
"license": "MIT",
|
|
12
17
|
"homepage": "https://agentshield.live/integrate.md",
|
|
13
18
|
"repository": {
|
|
14
19
|
"type": "git",
|
|
15
20
|
"url": "git+https://github.com/bartelmost/agentshield-agent-kit.git"
|
|
16
21
|
},
|
|
17
|
-
"keywords": [
|
|
18
|
-
|
|
22
|
+
"keywords": [
|
|
23
|
+
"agentshield",
|
|
24
|
+
"x402",
|
|
25
|
+
"ai-agents",
|
|
26
|
+
"mcp",
|
|
27
|
+
"invoice",
|
|
28
|
+
"iban",
|
|
29
|
+
"usdc",
|
|
30
|
+
"base"
|
|
31
|
+
],
|
|
32
|
+
"engines": {
|
|
33
|
+
"node": ">=20"
|
|
34
|
+
},
|
|
19
35
|
"dependencies": {
|
|
20
36
|
"@x402/evm": "^2.28.0",
|
|
21
37
|
"@x402/fetch": "^2.28.0",
|
package/tools.json
CHANGED
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
{
|
|
45
45
|
"name": "agentshield_invoice",
|
|
46
|
-
"description": "
|
|
46
|
+
"description": "Call before you send or pay an invoice: net + VAT equals gross, VAT matches the stated or standard rate, plus IBAN and VAT-id format. Returns ok and failed fields. Not a receipt photo; that is /lines.",
|
|
47
47
|
"parameters": {
|
|
48
48
|
"type": "object",
|
|
49
49
|
"properties": {
|
|
@@ -134,7 +134,7 @@
|
|
|
134
134
|
},
|
|
135
135
|
{
|
|
136
136
|
"name": "agentshield_holidays",
|
|
137
|
-
"description": "
|
|
137
|
+
"description": "Call for the full statutory holiday calendar of a year and country or region, such as FR 2026 or DE-BY. A single date is /holiday. Adding business days is /deadline.",
|
|
138
138
|
"parameters": {
|
|
139
139
|
"type": "object",
|
|
140
140
|
"properties": {
|
|
@@ -161,7 +161,7 @@
|
|
|
161
161
|
},
|
|
162
162
|
{
|
|
163
163
|
"name": "agentshield_cryptopay",
|
|
164
|
-
"description": "
|
|
164
|
+
"description": "Call before sending USDC or USDT: checksum the recipient, reject the zero address and a token-contract recipient, confirm the native token contract. Not a balance or sanctions screen.",
|
|
165
165
|
"parameters": {
|
|
166
166
|
"type": "object",
|
|
167
167
|
"properties": {
|