@trucore/openclaw-atf 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TruCore AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,18 +15,78 @@ openclaw gateway restart
 
 ---
 
+## Quick Start — Install, Enable, Verify, Disable
+
+### 1. Install
+
+```sh
+openclaw plugins install @trucore/openclaw-atf
+```
+
+### 2. Enable (minimal config — zero keys required)
+
+Add to your OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "trucore-atf": {}
+  }
+}
+```
+
+That's it. All defaults are safe and correct for most environments.
+
+### 3. Restart and verify
+
+```sh
+openclaw gateway restart
+openclaw tool call atf_integration_doctor
+```
+
+**Healthy state checklist:**
+- `status` = `"ok"`
+- `plugin_loaded` = `true`
+- `native_tools_available` lists all 13 tools
+- `native_tools_missing` is empty `[]`
+- `config_validation.valid` = `true`
+- `warnings` is empty or contains only informational items
+
+### 4. Disable (if needed)
+
+Remove `trucore-atf` from your plugins config:
+
+```json
+{
+  "plugins": {}
+}
+```
+
+Then: `openclaw gateway restart`. This has zero effect on ATF CLI/API.
+
+**See also:** [examples/](examples/) for copy-paste-safe config files.
+
+---
+
 ## What this plugin does
 
-This plugin registers **6 optional agent tools** into OpenClaw:
+This plugin registers **13 optional agent tools** into OpenClaw:
 
 | Tool | Purpose |
 |---|---|
+| `atf_health` | Check ATF CLI/API availability and readiness |
 | `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 |
+| `atf_integration_doctor` | Run integration readiness check — reports plugin/backend/tool status |
+| `atf_bot_preflight` | Pre-session readiness check — returns go/no-go with backend + config diagnostics |
+| `atf_tx_explain` | Explain ATF deny decisions — maps reason codes to human-readable explanations |
+| `atf_billing_info` | Billing/pricing metadata for the advanced bot package |
+| `atf_billing_claim` | Verify on-chain payment and process billing claim |
+| `atf_adoption_advisor` | Deterministic adoption recommendation for bots |
 
 All tools are **optional** — agents and operators must opt in via OpenClaw's tool allowlist. Default-safe:
 
@@ -34,33 +94,47 @@ All tools are **optional** — agents and operators must opt in via OpenClaw's t
 - `safety.allowExecuteSafe = true` — bootstrap execute-safe runs (env/verify only; no signing).
 - ATF **never signs transactions**.
 
+### Diagnostic tools
+
+`atf_bot_preflight` is a lightweight readiness check designed for bot startup:
+it probes CLI/API availability, validates plugin config, and returns a single
+`ready: true/false` signal with remediation steps if needed.
+
+`atf_tx_explain` maps ATF deny reason codes to structured human-readable
+explanations with category, description, and remediation guidance.  It works
+offline and requires no backend — it reads from the built-in reason code
+catalog.  Pass either a `reasonCodes` array or a full `receipt` object.
+
 ---
 
 ## Enable tools
 
-Add the plugin tools to your OpenClaw agent's allowlist. Example OpenClaw config:
+The simplest config enables all plugin tools with safe defaults:
+
+```json
+{
+  "plugins": {
+    "trucore-atf": {}
+  }
+}
+```
+
+To explicitly allowlist individual tools and customize settings:
 
 ```json
 {
   "plugins": {
     "trucore-atf": {
-      "atfCli": "atf",
       "prefer": "cli",
-      "receiptsDir": "./atf_receipts",
-      "safety": {
-        "allowExecuteSafe": true,
-        "allowNetwork": false
-      }
+      "receiptsDir": "./atf_receipts"
     }
   },
   "tools": {
     "allowlist": [
-      "atf_discover",
-      "atf_bootstrap_plan",
-      "atf_bootstrap_execute_safe",
+      "atf_health",
       "atf_protect_intent",
       "atf_verify_receipt",
-      "atf_report_savings"
+      "atf_integration_doctor"
     ]
   }
 }
@@ -83,6 +157,40 @@ To allow live manifest fetching, set `safety.allowNetwork = true` (agent environ
 
 ---
 
+## Integration Doctor
+
+Validate the full integration in one step:
+
+```sh
+openclaw tool call atf_integration_doctor
+```
+
+Returns a structured readiness report including:
+- Plugin loading status
+- CLI / API availability
+- Backend preference vs effective backend (with fallback details)
+- Registered tool inventory
+- Configuration warnings and remediation steps
+
+Status values: `ok`, `degraded`, `misconfigured`, `unavailable`.
+
+See the [operator runbook](../../docs/runbooks/openclaw-plugin-operations.md) for expected outputs and troubleshooting.
+
+---
+
+## Backend preference
+
+The plugin supports two backends:
+
+| Backend | When to use |
+|---|---|
+| `cli` (default) | Local dev, offline, ATF CLI installed |
+| `api` | Hosted environments, shared infra, centrally deployed ATF API |
+
+Set `prefer` in your plugin config. If the preferred backend is unavailable, the plugin falls back to the other automatically. Both `atf_health` and `atf_integration_doctor` report what was preferred, what was chosen, and why fallback occurred.
+
+---
+
 ## Example: "ATF saved you" message
 
 When your agent runs `atf_report_savings`, it produces a receipt-backed human summary like:
@@ -242,12 +350,71 @@ work identically via direct CLI.
 cd packages/openclaw-atf
 node --test tests/test_tools.mjs
 node --test tests/test_plugin_package.mjs
+node --test tests/test_integration_hardening.mjs
+node --test tests/test_doctor.mjs
+node --test tests/test_config_ux.mjs
+node --test tests/test_activate_validation.mjs
+node --test tests/test_native_tools.mjs
 ```
 
 All tests are offline. No network calls. No ATF CLI required.
 
 ---
 
+## Plugin exports
+
+The plugin provides the following entry-points:
+
+| Export | Type | Purpose |
+|---|---|---|
+| `default` | `function(api)` | Legacy single-function entry (calls `register(api)`) |
+| `register(api)` | `function` | OpenClaw lifecycle: register tools |
+| `activate(ctx)` | `function` | OpenClaw lifecycle: activate (runs non-blocking config validation) |
+| `deactivate()` | `function` | OpenClaw lifecycle: deactivate (no-op for stateless ATF) |
+| `PLUGIN_ID` | `string` | Canonical plugin identity: `trucore-atf` |
+| `PLUGIN_VERSION` | `string` | Current plugin version |
+| `buildHumanSummary(report)` | `function` | Human messaging helper for savings reports |
+| `REASON_CODE_CATALOG` | `object` | Frozen map of deny reason codes → `{category, explanation, remediation}` |
+| `ATF_BILLING_MANIFEST` | `object` | Machine-readable billing/pricing metadata |
+| `evaluateAdoption` | `function` | Adoption advisor evaluation function |
+| `verifyBillingClaim` | `function` | Billing claim verification function |
+| `CLAIM_STATUS` | `object` | Claim status enum |
+| `CLAIM_DENY_CODES` | `object` | Claim deny code catalog |
+| `TREASURY_ADDRESS` | `string` | Canonical treasury address |
+| `USDC_MINT` | `string` | Canonical Solana mainnet USDC mint address |
+| `CONTRACT_FAMILIES` | `object` | Universal contract family definitions |
+| `TOOL_FAMILY_MAP` | `object` | Tool → contract family mapping |
+| `CANONICAL_TOOLS` | `array` | Frozen list of all 13 tool names |
+| `CANONICAL_TOOL_COUNT` | `number` | Number of canonical tools (13) |
+
+The canonical plugin ID is `trucore-atf` everywhere: manifest, package.json, config, docs.
+
+---
+
+## Activation-time config validation
+
+When the plugin activates, it validates the config and surfaces any issues as `console.warn` messages. **Invalid config never blocks activation.** The plugin always loads and remains operational.
+
+- **Valid config** — activates silently, no warnings.
+- **Config with warnings** — activates normally; warnings logged with `[trucore-atf]` prefix.
+- **Config with errors / unsupported keys** — activates normally; errors and unsupported keys logged clearly.
+- Warnings include remediation guidance and recommend running `atf_integration_doctor` for full details.
+
+This gives operators immediate feedback at startup without breaking the integration.
+
+---
+
+## Graceful degradation
+
+- If ATF CLI is not installed, tools return clear error messages — never crash.
+- If ATF API is unreachable, tools degrade to CLI fallback or return errors.
+- If the plugin receives an invalid `api` object, it logs a warning and skips registration.
+- If activate() receives invalid or missing context, it degrades silently.
+- All tool handlers are wrapped in a safe-handler that catches runtime errors.
+- Plugin failure never breaks the OpenClaw gateway or other plugins.
+
+---
+
 ## License
 
 MIT — TruCore AI

package/examples/README.md

@@ -0,0 +1,134 @@
+# OpenClaw ATF Plugin — Config Examples
+
+Canonical config examples for the TruCore ATF OpenClaw plugin.
+
+All examples use the canonical plugin ID: `trucore-atf`.
+
+---
+
+## Minimal Enable (recommended starting point)
+
+**File:** [minimal-enable.json](minimal-enable.json)
+
+```json
+{
+  "plugins": {
+    "trucore-atf": {}
+  }
+}
+```
+
+Zero config keys needed. The plugin uses safe defaults:
+- `prefer: "cli"` — uses ATF CLI subprocess
+- `safety.allowExecuteSafe: true`
+- `safety.allowNetwork: false`
+
+This is the **fastest path** to enable ATF in OpenClaw.
+
+---
+
+## Prefer CLI (explicit)
+
+**File:** [prefer-cli.json](prefer-cli.json)
+
+```json
+{
+  "plugins": {
+    "trucore-atf": {
+      "prefer": "cli"
+    }
+  }
+}
+```
+
+Same as minimal enable, but explicitly declares CLI preference.
+Best for: local dev, offline environments, ATF CLI installed locally.
+
+---
+
+## Prefer API
+
+**File:** [prefer-api.json](prefer-api.json)
+
+```json
+{
+  "plugins": {
+    "trucore-atf": {
+      "prefer": "api",
+      "atfBaseUrl": "https://api.trucore.xyz"
+    }
+  }
+}
+```
+
+Routes tool calls through the ATF HTTP API.
+Best for: hosted environments, shared infra, centrally deployed ATF API.
+
+**Note:** `atfBaseUrl` is required when `prefer` is `"api"`.
+
+---
+
+## Full Config
+
+**File:** [full-config.json](full-config.json)
+
+```json
+{
+  "plugins": {
+    "trucore-atf": {
+      "prefer": "cli",
+      "receiptsDir": "./atf_receipts",
+      "safety": {
+        "allowExecuteSafe": true,
+        "allowNetwork": false
+      }
+    }
+  }
+}
+```
+
+Shows all commonly used keys. Only set keys you want to change from defaults.
+
+---
+
+## Disable Plugin
+
+**File:** [disable-plugin.json](disable-plugin.json)
+
+```json
+{
+  "plugins": {}
+}
+```
+
+Remove the `"trucore-atf"` key from `plugins` and restart the gateway.
+This has zero effect on ATF CLI or API operations.
+
+---
+
+## Config Reference
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `atfCli` | string | `"atf"` | CLI command name or absolute path |
+| `atfBaseUrl` | string | — | ATF HTTP API URL (required for `prefer: "api"`) |
+| `prefer` | `"cli"` \| `"api"` | `"cli"` | Backend preference |
+| `receiptsDir` | string | — | Receipt storage directory |
+| `safety.allowExecuteSafe` | boolean | `true` | Allow bootstrap execute-safe |
+| `safety.allowNetwork` | boolean | `false` | Allow live manifest fetch |
+
+No other keys are accepted (`additionalProperties: false`).
+
+---
+
+## Verify After Enabling
+
+```bash
+# Restart the gateway
+openclaw gateway restart
+
+# Run integration doctor
+openclaw tool call atf_integration_doctor
+
+# Expected: status = "ok", all 8 tools available
+```

package/examples/disable-plugin.json

@@ -0,0 +1,3 @@
+{
+  "plugins": {}
+}

package/examples/full-config.json

@@ -0,0 +1,12 @@
+{
+  "plugins": {
+    "trucore-atf": {
+      "prefer": "cli",
+      "receiptsDir": "./atf_receipts",
+      "safety": {
+        "allowExecuteSafe": true,
+        "allowNetwork": false
+      }
+    }
+  }
+}

package/examples/minimal-enable.json

@@ -0,0 +1,5 @@
+{
+  "plugins": {
+    "trucore-atf": {}
+  }
+}

package/examples/prefer-api.json

@@ -0,0 +1,8 @@
+{
+  "plugins": {
+    "trucore-atf": {
+      "prefer": "api",
+      "atfBaseUrl": "https://api.trucore.xyz"
+    }
+  }
+}

package/examples/prefer-cli.json

@@ -0,0 +1,7 @@
+{
+  "plugins": {
+    "trucore-atf": {
+      "prefer": "cli"
+    }
+  }
+}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "trucore-atf",
   "name": "TruCore ATF",
-  "version": "0.1.1",
+  "version": "0.2.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",

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@trucore/openclaw-atf",
-  "version": "0.1.1",
+  "version": "0.2.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",
+    "examples",
     "openclaw.plugin.json",
     "README.md",
     "LICENSE"
@@ -56,7 +57,8 @@
   "scripts": {
     "test": "node --test tests/test_tools.mjs",
     "validate": "node tests/test_plugin_package.mjs",
-    "prepublishOnly": "npm run validate && npm run test"
+    "check-versions": "python3 ../../scripts/check_openclaw_versions.py",
+    "prepublishOnly": "npm run check-versions && npm run validate && npm run test"
   },
   "dependencies": {}
 }