@trucore/openclaw-atf 0.1.0

package/README.md

@@ -0,0 +1,206 @@
+# @trucore/openclaw-atf
+
+OpenClaw plugin for the **TruCore Agent Transaction Firewall (ATF)**.
+
+Gives OpenClaw agents first-class tools to discover, adopt, and report on ATF — the policy-enforced transaction firewall for autonomous DeFi agents. ATF evaluates swap, lend, and perps intents against a human-configured policy before any transaction reaches the chain. It never signs. It is deny-by-default.
+
+---
+
+## Install
+
+```sh
+openclaw plugins install @trucore/openclaw-atf
+openclaw gateway restart
+```
+
+---
+
+## What this plugin does
+
+This plugin registers **6 optional agent tools** into OpenClaw:
+
+| Tool | Purpose |
+|---|---|
+| `atf_discover` | Fetch and summarise the ATF manifest (capabilities, recipes, feature gates) |
+| `atf_bootstrap_plan` | Generate ATF self-install steps for a recipe (plan only, no side effects) |
+| `atf_bootstrap_execute_safe` | Run safe bootstrap steps locally (env setup + verify, no signing) |
+| `atf_protect_intent` | Submit a DeFi intent for policy evaluation — returns allow/deny + receipt |
+| `atf_verify_receipt` | Verify a receipt deterministically (proof for humans) |
+| `atf_report_savings` | Generate a receipt-backed "ATF saved you" report |
+
+All tools are **optional** — agents and operators must opt in via OpenClaw's tool allowlist. Default-safe:
+
+- `safety.allowNetwork = false` — `atf_discover` returns offline instructions unless explicitly enabled.
+- `safety.allowExecuteSafe = true` — bootstrap execute-safe runs (env/verify only; no signing).
+- ATF **never signs transactions**.
+
+---
+
+## Enable tools
+
+Add the plugin tools to your OpenClaw agent's allowlist. Example OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "trucore-atf": {
+      "atfCli": "atf",
+      "prefer": "cli",
+      "receiptsDir": "./atf_receipts",
+      "safety": {
+        "allowExecuteSafe": true,
+        "allowNetwork": false
+      }
+    }
+  },
+  "tools": {
+    "allowlist": [
+      "atf_discover",
+      "atf_bootstrap_plan",
+      "atf_bootstrap_execute_safe",
+      "atf_protect_intent",
+      "atf_verify_receipt",
+      "atf_report_savings"
+    ]
+  }
+}
+```
+
+To allow live manifest fetching, set `safety.allowNetwork = true` (agent environment must have outbound HTTP access).
+
+---
+
+## Config reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `atfCli` | string | `"atf"` | CLI command name or absolute path |
+| `atfBaseUrl` | string | — | Base URL for HTTP API mode (e.g. `https://api.trucore.xyz`) |
+| `prefer` | `"cli"` \| `"api"` | `"cli"` | Whether to call ATF via CLI subprocess or HTTP API |
+| `receiptsDir` | string | — | Directory of ATF receipt JSON files (used by `atf_report_savings`) |
+| `safety.allowExecuteSafe` | boolean | `true` | Allow `atf_bootstrap_execute_safe` to run |
+| `safety.allowNetwork` | boolean | `false` | Allow `atf_discover` to fetch the manifest over the network |
+
+---
+
+## Example: "ATF saved you" message
+
+When your agent runs `atf_report_savings`, it produces a receipt-backed human summary like:
+
+```
+=== ATF Protection Summary ===
+
+ATF prevented 12 risky actions.
+
+Top deny reasons:
+  • PERPS_MARKET_NOT_ALLOWED: 7 times
+  • PERPS_ORDER_TYPE_NOT_ALLOWED: 3 times
+  • SWAP_SLIPPAGE_TOO_HIGH: 2 times
+
+Evidence: 12 verified receipts.
+  receipt: sha256:a1b2c3d4e5f6...
+  receipt: sha256:9e8d7c6b5a4f...
+  ... and 10 more.
+
+No savings estimate available. To enable estimates, include
+exposure_hints (notional_usd, leverage, slippage_bps) in
+intentJson when calling atf_protect_intent.
+
+Verify receipts: atf receipts verify --receipt <hash>
+```
+
+When `exposure_hints` are provided at protect time, the report adds a conservative estimate:
+
+```
+Conservative savings estimate: $4,200.00
+  (Assumptions: estimate is based on exposure_hints
+  (notional_usd, leverage, slippage_bps) provided at protect time.
+  Actual outcomes may differ.)
+```
+
+The estimate is **never invented** — it is only shown if `exposure_hints` are present. receipts are always cited.
+
+---
+
+## Example: verified receipt snippet
+
+```json
+{
+  "verified": true,
+  "content_hash": "sha256:a1b2c3d4e5f6789abcdef...",
+  "intent_hash": "sha256:fedcba987654321...",
+  "allow": false,
+  "reason_codes": ["PERPS_MARKET_NOT_ALLOWED"],
+  "chain_id": "solana",
+  "intent_type": "perps_open"
+}
+```
+
+Verify any receipt yourself:
+
+```sh
+atf receipts verify --receipt sha256:a1b2c3d4e5f6...
+```
+
+---
+
+## OpenClaw plugin option (fastest path)
+
+> **Fastest path for OpenClaw agents to adopt ATF:**
+
+```sh
+# 1. Install the plugin
+openclaw plugins install @trucore/openclaw-atf
+openclaw gateway restart
+
+# 2. The agent can now call:
+#    atf_discover       → learn what ATF does
+#    atf_bootstrap_plan → get self-install steps
+#    atf_bootstrap_execute_safe → run safe setup
+#    atf_protect_intent → guard every DeFi action
+#    atf_verify_receipt → prove decisions to humans
+#    atf_report_savings → generate savings report
+```
+
+No custom coding required for drop-in protection.
+
+---
+
+## Manual integration (without OpenClaw)
+
+```sh
+# Install ATF CLI
+npm install -g @trucore/atf
+
+# Self-install ATF
+atf bootstrap --format json --recipe bootstrap_local
+atf bootstrap --execute-safe --recipe bootstrap_local
+
+# Protect an intent
+echo '{"chain_id":"solana","intent_type":"swap","intent":{...}}' | atf bot protect --stdin
+
+# Verify a receipt
+atf receipts verify --receipt sha256:aabbcc...
+
+# Generate savings report
+atf report savings --receipts-dir ./atf_receipts --format json
+```
+
+Full docs: [docs/runbooks/agent-adoption-atf.md](../../docs/runbooks/agent-adoption-atf.md)
+
+---
+
+## Tests
+
+```sh
+cd packages/openclaw-atf
+node --test tests/test_tools.mjs
+```
+
+All tests are offline. No network calls. No ATF CLI required.
+
+---
+
+## License
+
+MIT — TruCore AI

package/openclaw.plugin.json

@@ -0,0 +1,51 @@
+{
+  "id": "trucore-atf",
+  "name": "TruCore ATF",
+  "version": "0.1.0",
+  "description": "Transaction firewall tools for autonomous finance agents: protect + verify + report savings. ATF evaluates swap, lend, and perps intents against policy before they reach the chain. Never signs. Deny-by-default.",
+  "homepage": "https://github.com/trucore-ai/agent-transaction-firewall",
+  "main": "src/index.mjs",
+  "tools": "optional",
+  "configSchema": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "properties": {
+      "atfCli": {
+        "type": "string",
+        "default": "atf",
+        "description": "ATF CLI command name or absolute path (e.g. 'atf' or '/usr/local/bin/atf')."
+      },
+      "atfBaseUrl": {
+        "type": "string",
+        "description": "Base URL for ATF HTTP API mode (e.g. 'https://api.trucore.xyz'). Optional; required only when prefer='api'."
+      },
+      "prefer": {
+        "type": "string",
+        "enum": ["cli", "api"],
+        "default": "cli",
+        "description": "Whether to call ATF via CLI subprocess or HTTP API."
+      },
+      "receiptsDir": {
+        "type": "string",
+        "description": "Directory where ATF receipt JSON files are stored. Used by atf_report_savings."
+      },
+      "safety": {
+        "type": "object",
+        "properties": {
+          "allowExecuteSafe": {
+            "type": "boolean",
+            "default": true,
+            "description": "Allow atf_bootstrap_execute_safe tool to run bootstrap --execute-safe steps. Non-fatal; no signing."
+          },
+          "allowNetwork": {
+            "type": "boolean",
+            "default": false,
+            "description": "Allow atf_discover to fetch the ATF manifest over the network. Disabled by default; enable if the agent environment has outbound HTTP access."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@trucore/openclaw-atf",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin — ATF transaction firewall tools for autonomous agents: discover, protect, verify, report savings.",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.mjs",
+  "files": [
+    "src",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trucore-ai/agent-transaction-firewall.git",
+    "directory": "packages/openclaw-atf"
+  },
+  "homepage": "https://github.com/trucore-ai/agent-transaction-firewall/tree/main/packages/openclaw-atf#readme",
+  "bugs": {
+    "url": "https://github.com/trucore-ai/agent-transaction-firewall/issues"
+  },
+  "author": "TruCore AI",
+  "funding": "https://trucore.xyz",
+  "keywords": [
+    "openclaw",
+    "agent-firewall",
+    "atf",
+    "transaction-guardrails",
+    "trucore",
+    "defi-safety",
+    "autonomous-agent",
+    "bot-guardrails",
+    "receipts",
+    "savings-report"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/test_tools.mjs"
+  },
+  "dependencies": {}
+}

package/src/index.mjs

@@ -0,0 +1,827 @@
+/**
+ * @trucore/openclaw-atf — OpenClaw plugin: ATF agent tools
+ *
+ * Registers 6 OPTIONAL tools for OpenClaw agents:
+ *   1. atf_discover               — fetch/summarize ATF manifest
+ *   2. atf_bootstrap_plan         — generate bootstrap steps (plan only, no side effects)
+ *   3. atf_bootstrap_execute_safe — run safe bootstrap steps locally
+ *   4. atf_protect_intent         — protect a DeFi intent and return receipt + decision
+ *   5. atf_verify_receipt         — verify a receipt deterministically
+ *   6. atf_report_savings         — generate receipt-backed "ATF saved you" report
+ *
+ * Uses ONLY built-in Node modules: child_process, fs, path, os, url.
+ * No network calls unless config.safety.allowNetwork = true.
+ * Default-safe; all tools are OPTIONAL (agents/users must allowlist them).
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Default config
+// ---------------------------------------------------------------------------
+
+/** @type {Record<string, unknown>} */
+const DEFAULT_CONFIG = {
+  atfCli: "atf",
+  atfBaseUrl: null,
+  prefer: "cli",
+  receiptsDir: null,
+  safety: {
+    allowExecuteSafe: true,
+    allowNetwork: false,
+  },
+};
+
+/**
+ * Merge user config with defaults (shallow + safety sub-object).
+ * @param {Record<string, unknown>} userConfig
+ * @returns {Record<string, unknown>}
+ */
+function resolveConfig(userConfig = {}) {
+  const cfg = { ...DEFAULT_CONFIG, ...userConfig };
+  cfg.safety = {
+    ...DEFAULT_CONFIG.safety,
+    ...(userConfig.safety ?? {}),
+  };
+  return cfg;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: exec + output formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the ATF CLI with given args.
+ * @param {string} cli
+ * @param {string[]} args
+ * @returns {Promise<{stdout: string, stderr: string, exitCode: number}>}
+ */
+async function runAtfCli(cli, args) {
+  try {
+    const { stdout, stderr } = await execFileAsync(cli, args, {
+      timeout: 30_000,
+      maxBuffer: 4 * 1024 * 1024,
+      shell: false,
+    });
+    return { stdout: stdout ?? "", stderr: stderr ?? "", exitCode: 0 };
+  } catch (err) {
+    return {
+      stdout: err.stdout ?? "",
+      stderr: err.stderr ?? "",
+      exitCode: err.code ?? 1,
+    };
+  }
+}
+
+/**
+ * Attempt to parse JSON; return original string on failure.
+ * @param {string} raw
+ * @returns {unknown}
+ */
+function tryParseJson(raw) {
+  try {
+    return JSON.parse(raw.trim());
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Build an OpenClaw tool content response.
+ * @param {string} summary
+ * @param {unknown} data
+ * @returns {{ content: Array<{type:string, text?:string, json?:unknown}> }}
+ */
+function toolResponse(summary, data) {
+  const items = [{ type: "text", text: summary }];
+  if (data !== undefined && data !== null) {
+    if (typeof data === "string") {
+      items.push({ type: "text", text: data });
+    } else {
+      items.push({ type: "json", json: data });
+    }
+  }
+  return { content: items };
+}
+
+/**
+ * Build an error response without throwing.
+ * @param {string} message
+ * @returns {{ content: Array<{type:string, text:string}>, isError: boolean }}
+ */
+function errorResponse(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_discover
+// ---------------------------------------------------------------------------
+
+/**
+ * Summarise the ATF manifest for the calling agent.
+ * Network-gated: only fetches if config.safety.allowNetwork === true.
+ *
+ * @param {Record<string, unknown>} cfg Resolved config.
+ * @param {{ manifestUrl?: string }} params Tool params.
+ * @returns {Promise<object>}
+ */
+async function toolAtfDiscover(cfg, params = {}) {
+  const { safety, atfBaseUrl } = cfg;
+
+  if (!safety.allowNetwork) {
+    return toolResponse(
+      "ATF discovery requires network access.",
+      {
+        instructions:
+          "To enable: set safety.allowNetwork = true in the plugin config, then retry.",
+        manual_steps: [
+          "1. Fetch: GET https://trucore.xyz/.well-known/atf.json",
+          "2. Review: capabilities, recipes_v2, feature_gates, trust_signals",
+          "3. Or run:  atf bootstrap --format json   to see recipes locally.",
+        ],
+        openclaw_install: [
+          "openclaw plugins install @trucore/openclaw-atf",
+          "openclaw gateway restart",
+        ],
+        manifest_url: "https://trucore.xyz/.well-known/atf.json",
+        toolcard_url:
+          "https://raw.githubusercontent.com/trucore-ai/agent-transaction-firewall/main/docs/agent/atf_toolcard.json",
+      },
+    );
+  }
+
+  const base =
+    params.manifestUrl ??
+    (atfBaseUrl ? `${atfBaseUrl}/.well-known/atf.json` : null) ??
+    "https://trucore.xyz/.well-known/atf.json";
+
+  let manifest;
+  try {
+    const res = await fetch(base, {
+      headers: { "User-Agent": "openclaw-atf-plugin/0.1.0" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+      return errorResponse(
+        `ATF manifest fetch failed: HTTP ${res.status} from ${base}`,
+      );
+    }
+    manifest = await res.json();
+  } catch (err) {
+    return errorResponse(`ATF manifest fetch error: ${err.message}`);
+  }
+
+  const summary = {
+    id: manifest.id ?? manifest.product ?? "trucore-atf",
+    version: manifest.version ?? "unknown",
+    capabilities: manifest.capabilities ?? [],
+    recipe_ids: manifest.recipes_v2?.recipe_ids ?? [],
+    safety_defaults: manifest.safety_defaults ?? {},
+    feature_gates: manifest.feature_gates ?? [],
+    openclaw_integration: manifest.openclaw_integration ?? {},
+    trust_signals: manifest.trust_signals ?? {},
+  };
+
+  return toolResponse(
+    "ATF manifest fetched. Key fields summarised below.",
+    summary,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_bootstrap_plan
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate bootstrap steps for a given recipe (plan-only, no side effects).
+ *
+ * @param {Record<string, unknown>} cfg
+ * @param {{ recipe?: string }} params
+ */
+async function toolAtfBootstrapPlan(cfg, params = {}) {
+  const { atfCli } = cfg;
+  const recipe = params.recipe ?? "bootstrap_local";
+
+  const args = ["bootstrap", "--format", "json", "--recipe", recipe];
+  const result = await runAtfCli(atfCli, args);
+
+  if (result.exitCode !== 0) {
+    return errorResponse(
+      `atf bootstrap plan failed (exit ${result.exitCode}).\n` +
+        `stderr: ${result.stderr}\nstdout: ${result.stdout}`,
+    );
+  }
+
+  const parsed = tryParseJson(result.stdout);
+  return toolResponse(
+    `Bootstrap plan for recipe '${recipe}' (plan only — no steps executed).`,
+    parsed,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_bootstrap_execute_safe
+// ---------------------------------------------------------------------------
+
+/**
+ * Run safe bootstrap steps (env/verify only).
+ * Only enabled when config.safety.allowExecuteSafe === true.
+ *
+ * @param {Record<string, unknown>} cfg
+ * @param {{ recipe?: string, dryRun?: boolean }} params
+ */
+async function toolAtfBootstrapExecuteSafe(cfg, params = {}) {
+  const { atfCli, safety } = cfg;
+
+  if (!safety.allowExecuteSafe) {
+    return errorResponse(
+      "atf_bootstrap_execute_safe is disabled. " +
+        "Set safety.allowExecuteSafe = true in the plugin config to enable.",
+    );
+  }
+
+  const recipe = params.recipe ?? "bootstrap_local";
+  const dryRun = params.dryRun === true;
+
+  const args = [
+    "bootstrap",
+    "--format",
+    "json",
+    "--recipe",
+    recipe,
+    "--execute",
+    "safe",
+  ];
+  if (dryRun) args.push("--dry-run");
+
+  const result = await runAtfCli(atfCli, args);
+  const parsed = tryParseJson(result.stdout);
+
+  if (result.exitCode !== 0) {
+    // Non-fatal: return partial result + stderr
+    return toolResponse(
+      `Bootstrap execute-safe completed with non-zero exit (${result.exitCode}). ` +
+        `Check executed_steps for partial results.`,
+      {
+        exitCode: result.exitCode,
+        stderr: result.stderr,
+        result: parsed,
+      },
+    );
+  }
+
+  return toolResponse(
+    `Bootstrap execute-safe complete for recipe '${recipe}'.${dryRun ? " (dry-run)" : ""}`,
+    parsed,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_protect_intent
+// ---------------------------------------------------------------------------
+
+/**
+ * Protect a DeFi intent and return receipt + decision.
+ *
+ * @param {Record<string, unknown>} cfg
+ * @param {{ intentJson: object, exposureHints?: object }} params
+ */
+async function toolAtfProtectIntent(cfg, params = {}) {
+  const { atfCli, prefer, atfBaseUrl } = cfg;
+  const { intentJson, exposureHints } = params;
+
+  if (!intentJson || typeof intentJson !== "object") {
+    return errorResponse(
+      "atf_protect_intent requires 'intentJson' (object) input.",
+    );
+  }
+
+  // Merge exposure hints into metadata if provided
+  const payload = { ...intentJson };
+  if (
+    exposureHints &&
+    typeof exposureHints === "object" &&
+    Object.keys(exposureHints).length > 0
+  ) {
+    payload.metadata = {
+      ...(payload.metadata ?? {}),
+      exposure_hints: exposureHints,
+    };
+  }
+
+  const payloadStr = JSON.stringify(payload);
+
+  if (prefer === "api" && atfBaseUrl) {
+    // HTTP API mode
+    let res;
+    try {
+      res = await fetch(`${atfBaseUrl}/v1/bot/protect`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": "openclaw-atf-plugin/0.1.0",
+        },
+        body: payloadStr,
+        signal: AbortSignal.timeout(15_000),
+      });
+    } catch (err) {
+      return errorResponse(`ATF API protect call failed: ${err.message}`);
+    }
+
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      return errorResponse(
+        `ATF API protect response not JSON (HTTP ${res.status}).`,
+      );
+    }
+
+    if (!res.ok) {
+      return errorResponse(
+        `ATF API protect HTTP ${res.status}: ${JSON.stringify(data)}`,
+      );
+    }
+
+    return toolResponse(
+      `ATF protect decision: ${data.allow ? "ALLOW" : "DENY"}.` +
+        (data.reason_codes?.length
+          ? ` Reason codes: ${data.reason_codes.join(", ")}.`
+          : ""),
+      data,
+    );
+  }
+
+  // CLI mode: pass JSON via stdin
+  const { execFile: execFileRaw } = await import("node:child_process");
+  const decision = await new Promise((resolve) => {
+    const child = execFileRaw(
+      atfCli,
+      ["bot", "protect", "--format", "json", "--stdin"],
+      { timeout: 30_000, maxBuffer: 4 * 1024 * 1024, shell: false },
+      (err, stdout, stderr) => {
+        resolve({
+          stdout: stdout ?? "",
+          stderr: stderr ?? "",
+          exitCode: err ? (err.code ?? 1) : 0,
+        });
+      },
+    );
+    child.stdin.write(payloadStr);
+    child.stdin.end();
+  });
+
+  const parsed = tryParseJson(decision.stdout);
+  const allow =
+    typeof parsed === "object" && parsed !== null ? parsed.allow : null;
+
+  if (decision.exitCode !== 0 && typeof parsed !== "object") {
+    return errorResponse(
+      `ATF protect failed (exit ${decision.exitCode}).\n` +
+        `stderr: ${decision.stderr}\nstdout: ${decision.stdout}`,
+    );
+  }
+
+  return toolResponse(
+    `ATF protect decision: ${allow === true ? "ALLOW" : allow === false ? "DENY" : "see json"}.` +
+      (typeof parsed === "object" && parsed?.reason_codes?.length
+        ? ` Reason codes: ${parsed.reason_codes.join(", ")}.`
+        : ""),
+    parsed,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_verify_receipt
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify a receipt deterministically.
+ *
+ * @param {Record<string, unknown>} cfg
+ * @param {{ receipt: string|object }} params
+ */
+async function toolAtfVerifyReceipt(cfg, params = {}) {
+  const { atfCli } = cfg;
+  const { receipt } = params;
+
+  if (!receipt) {
+    return errorResponse(
+      "atf_verify_receipt requires 'receipt' param " +
+        "(receipt JSON string, object, or file path).",
+    );
+  }
+
+  // If receipt is an object or looks like JSON, pass via stdin
+  const receiptStr =
+    typeof receipt === "object"
+      ? JSON.stringify(receipt)
+      : String(receipt).trim();
+
+  const isFilePath =
+    typeof receipt === "string" &&
+    !receiptStr.startsWith("{") &&
+    !receiptStr.startsWith("[");
+
+  let result;
+  if (isFilePath) {
+    // File path mode
+    result = await runAtfCli(atfCli, [
+      "receipts",
+      "verify",
+      "--format",
+      "json",
+      "--receipt",
+      receiptStr,
+    ]);
+  } else {
+    // Stdin mode
+    const { execFile: execFileRaw } = await import("node:child_process");
+    result = await new Promise((resolve) => {
+      const child = execFileRaw(
+        atfCli,
+        ["receipts", "verify", "--format", "json", "--stdin"],
+        { timeout: 30_000, maxBuffer: 4 * 1024 * 1024, shell: false },
+        (err, stdout, stderr) => {
+          resolve({
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+            exitCode: err ? (err.code ?? 1) : 0,
+          });
+        },
+      );
+      child.stdin.write(receiptStr);
+      child.stdin.end();
+    });
+  }
+
+  const parsed = tryParseJson(result.stdout);
+
+  if (result.exitCode !== 0) {
+    return errorResponse(
+      `ATF verify failed (exit ${result.exitCode}).\n` +
+        `stderr: ${result.stderr}\nstdout: ${result.stdout}`,
+    );
+  }
+
+  const verified =
+    typeof parsed === "object" && parsed !== null ? parsed.verified : null;
+
+  return toolResponse(
+    `Receipt verification: ${verified === true ? "VERIFIED" : verified === false ? "FAILED" : "see json"}.`,
+    parsed,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_report_savings
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a receipt-backed "ATF saved you" report.
+ *
+ * @param {Record<string, unknown>} cfg
+ * @param {{ last?: number, receiptsDir?: string }} params
+ */
+async function toolAtfReportSavings(cfg, params = {}) {
+  const { atfCli } = cfg;
+  const receiptsDir = params.receiptsDir ?? cfg.receiptsDir;
+  const last = params.last ?? 50;
+
+  const args = ["report", "savings", "--format", "json", "--last", String(last)];
+  if (receiptsDir) {
+    args.push("--receipts-dir", receiptsDir);
+  }
+
+  const result = await runAtfCli(atfCli, args);
+  const parsed = tryParseJson(result.stdout);
+
+  if (result.exitCode !== 0) {
+    return errorResponse(
+      `ATF report savings failed (exit ${result.exitCode}).\n` +
+        `stderr: ${result.stderr}\nstdout: ${result.stdout}`,
+    );
+  }
+
+  const summary = buildHumanSummary(
+    typeof parsed === "object" ? parsed : {},
+  );
+
+  return toolResponse(summary, parsed);
+}
+
+// ---------------------------------------------------------------------------
+// Human messaging helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a human-readable "ATF saved you" summary from a savings report JSON.
+ * Conservative: only includes $ estimate if hints are present.
+ *
+ * @param {Record<string, unknown>} reportJson - Output from `atf report savings --format json`
+ * @returns {string}
+ */
+export function buildHumanSummary(reportJson) {
+  if (!reportJson || typeof reportJson !== "object") {
+    return "ATF savings report: no data available.";
+  }
+
+  const lines = ["=== ATF Protection Summary ===", ""];
+
+  // Denied actions
+  const totalDenied =
+    reportJson.total_denied ??
+    reportJson.deny_count ??
+    reportJson.denied_count ??
+    null;
+  if (totalDenied !== null) {
+    lines.push(
+      `ATF prevented ${totalDenied} risky action${totalDenied !== 1 ? "s" : ""}.`,
+    );
+  } else {
+    lines.push("ATF protection active.");
+  }
+
+  // Top reason codes
+  const reasons =
+    reportJson.by_reason_code ??
+    reportJson.reason_code_breakdown ??
+    reportJson.reasons ??
+    null;
+  if (reasons && typeof reasons === "object" && !Array.isArray(reasons)) {
+    const sorted = Object.entries(reasons)
+      .sort((a, b) => Number(b[1]) - Number(a[1]))
+      .slice(0, 5);
+    if (sorted.length > 0) {
+      lines.push("");
+      lines.push("Top deny reasons:");
+      for (const [code, count] of sorted) {
+        lines.push(`  • ${code}: ${count} time${count !== 1 ? "s" : ""}`);
+      }
+    }
+  } else if (Array.isArray(reasons) && reasons.length > 0) {
+    lines.push("");
+    lines.push("Top deny reasons:");
+    for (const entry of reasons.slice(0, 5)) {
+      const code = entry.code ?? entry.reason_code ?? entry.name ?? "UNKNOWN";
+      const count = entry.count ?? entry.occurrences ?? 1;
+      lines.push(`  • ${code}: ${count} time${count !== 1 ? "s" : ""}`);
+    }
+  }
+
+  // Evidence: receipt hashes
+  const evidence =
+    reportJson.evidence ??
+    reportJson.receipts ??
+    reportJson.receipt_hashes ??
+    null;
+  if (Array.isArray(evidence) && evidence.length > 0) {
+    lines.push("");
+    lines.push(
+      `Evidence: ${evidence.length} verified receipt${evidence.length !== 1 ? "s" : ""}.`,
+    );
+    const hashes = evidence
+      .map((e) => {
+        if (typeof e === "string") return e;
+        return (
+          e.content_hash ??
+          e.receipt_hash ??
+          e.hash ??
+          e.receipt_id ??
+          null
+        );
+      })
+      .filter(Boolean)
+      .slice(0, 10);
+    if (hashes.length > 0) {
+      for (const h of hashes) {
+        lines.push(`  receipt: ${h}`);
+      }
+      if (evidence.length > 10) {
+        lines.push(`  ... and ${evidence.length - 10} more.`);
+      }
+    }
+  }
+
+  // Conservative $ savings estimate (ONLY if hints present in report)
+  const savingsEstimate =
+    reportJson.savings_estimate_usd ??
+    reportJson.estimated_savings_usd ??
+    reportJson.conservative_savings_usd ??
+    null;
+  const hasHints =
+    reportJson.has_exposure_hints === true ||
+    reportJson.notional_hints_present === true ||
+    savingsEstimate !== null;
+
+  if (savingsEstimate !== null && hasHints) {
+    lines.push("");
+    const formatted =
+      typeof savingsEstimate === "number"
+        ? `$${savingsEstimate.toLocaleString("en-US", { maximumFractionDigits: 2 })}`
+        : String(savingsEstimate);
+    lines.push(
+      `Conservative savings estimate: ${formatted}`,
+    );
+    lines.push(
+      "  (Assumptions: estimate is based on exposure_hints " +
+        "(notional_usd, leverage, slippage_bps) provided at protect time. " +
+        "Actual outcomes may differ.)",
+    );
+  } else if (!hasHints && totalDenied && Number(totalDenied) > 0) {
+    lines.push("");
+    lines.push(
+      "No savings estimate available. " +
+        "To enable estimates, include exposure_hints " +
+        "(notional_usd, leverage, slippage_bps) " +
+        "in the intentJson when calling atf_protect_intent.",
+    );
+  }
+
+  lines.push("");
+  lines.push(
+    "Verify receipts: atf receipts verify --receipt <hash>",
+  );
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Plugin entry-point
+// ---------------------------------------------------------------------------
+
+/**
+ * OpenClaw plugin entry-point.
+ *
+ * Called by the OpenClaw runtime when the plugin is loaded.
+ * All tools are registered as OPTIONAL — agents / operators must allowlist
+ * them before they can be used.
+ *
+ * @param {{ registerTool: Function, config: Record<string, unknown> }} api
+ */
+export default function atfPlugin(api) {
+  const cfg = resolveConfig(api?.config ?? {});
+
+  // ---- Tool 1: atf_discover -----------------------------------------------
+  api.registerTool({
+    name: "atf_discover",
+    optional: true,
+    description:
+      "Fetch and summarise the ATF manifest and toolcard so you know ATF's " +
+      "capabilities, recipe IDs, feature gates, and integration steps. " +
+      "Requires safety.allowNetwork=true to fetch live; otherwise returns " +
+      "offline instructions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        manifestUrl: {
+          type: "string",
+          description:
+            "Override manifest URL (default: https://trucore.xyz/.well-known/atf.json).",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: (params) => toolAtfDiscover(cfg, params),
+  });
+
+  // ---- Tool 2: atf_bootstrap_plan -----------------------------------------
+  api.registerTool({
+    name: "atf_bootstrap_plan",
+    optional: true,
+    description:
+      "Generate ATF bootstrap steps for a given recipe. " +
+      "Plan-only — no side effects. " +
+      "Returns the steps, env flags, and verification commands the agent should follow.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        recipe: {
+          type: "string",
+          default: "bootstrap_local",
+          description:
+            "Recipe ID to plan. One of: bootstrap_local, enable_perps_drift, " +
+            "enable_perps_mango, enable_perps_hyperliquid.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: (params) => toolAtfBootstrapPlan(cfg, params),
+  });
+
+  // ---- Tool 3: atf_bootstrap_execute_safe ---------------------------------
+  api.registerTool({
+    name: "atf_bootstrap_execute_safe",
+    optional: true,
+    description:
+      "Run ATF bootstrap --execute-safe steps (env setup and verification only). " +
+      "Never requires signing or network access. " +
+      "Disabled if safety.allowExecuteSafe=false. Errors are non-fatal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        recipe: {
+          type: "string",
+          default: "bootstrap_local",
+          description: "Recipe ID to execute.",
+        },
+        dryRun: {
+          type: "boolean",
+          default: false,
+          description: "Preview steps without executing.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: (params) => toolAtfBootstrapExecuteSafe(cfg, params),
+  });
+
+  // ---- Tool 4: atf_protect_intent -----------------------------------------
+  api.registerTool({
+    name: "atf_protect_intent",
+    optional: true,
+    description:
+      "Submit a DeFi intent (swap, lend, perps) to ATF for policy evaluation. " +
+      "Returns allow/deny decision, reason_codes, and a tamper-evident receipt. " +
+      "ATF never signs transactions.",
+    inputSchema: {
+      type: "object",
+      required: ["intentJson"],
+      properties: {
+        intentJson: {
+          type: "object",
+          description:
+            "Full ATF ExecutionRequest or intent object. " +
+            "Fields: chain_id, intent_type, raw_tx (optional), intent (object), metadata (optional).",
+        },
+        exposureHints: {
+          type: "object",
+          description:
+            "Optional exposure hints for savings reporting. " +
+            "Include notional_usd, leverage, and/or slippage_bps to enable conservative savings estimates.",
+          properties: {
+            notional_usd: { type: "number" },
+            leverage: { type: "number" },
+            slippage_bps: { type: "integer" },
+          },
+          additionalProperties: true,
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: (params) => toolAtfProtectIntent(cfg, params),
+  });
+
+  // ---- Tool 5: atf_verify_receipt -----------------------------------------
+  api.registerTool({
+    name: "atf_verify_receipt",
+    optional: true,
+    description:
+      "Verify an ATF receipt deterministically. " +
+      "Returns verified=true/false, content_hash, and intent_hash. " +
+      "Use to prove to humans that a transaction was evaluated.",
+    inputSchema: {
+      type: "object",
+      required: ["receipt"],
+      properties: {
+        receipt: {
+          description:
+            "Receipt to verify: JSON object, JSON string, or file path.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: (params) => toolAtfVerifyReceipt(cfg, params),
+  });
+
+  // ---- Tool 6: atf_report_savings -----------------------------------------
+  api.registerTool({
+    name: "atf_report_savings",
+    optional: true,
+    description:
+      "Generate a receipt-backed 'ATF saved you money / prevented losses' report. " +
+      "Includes deny counts by reason code, evidence receipt hashes, " +
+      "and a conservative $ estimate only when exposure hints are present.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        last: {
+          type: "integer",
+          default: 50,
+          description: "Number of most recent receipts to include.",
+        },
+        receiptsDir: {
+          type: "string",
+          description:
+            "Directory containing ATF receipt JSON files. " +
+            "Defaults to config.receiptsDir.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: (params) => toolAtfReportSavings(cfg, params),
+  });
+}