@trucore/openclaw-atf 0.1.1 → 0.2.0

package/src/index.mjs

@@ -1,13 +1,44 @@
 /**
  * @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
+ * Registers OPTIONAL tools for OpenClaw agents:
+ *   1. atf_health                 — check ATF CLI / API availability
+ *   2. atf_discover               — fetch/summarize ATF manifest
+ *   3. atf_bootstrap_plan         — generate bootstrap steps (plan only, no side effects)
+ *   4. atf_bootstrap_execute_safe — run safe bootstrap steps locally
+ *   5. atf_protect_intent         — protect a DeFi intent and return receipt + decision
+ *   6. atf_verify_receipt         — verify a receipt deterministically
+ *   7. atf_report_savings         — generate receipt-backed "ATF saved you" report
+ *   8. atf_integration_doctor     — integration readiness / troubleshooting
+ *   9. atf_bot_preflight          — pre-session readiness check (go/no-go)
+ *  10. atf_tx_explain             — explain a receipt or deny decision in human terms
+ *  11. atf_billing_info           — billing/pricing metadata for advanced bot package
+ *  12. atf_adoption_advisor       — deterministic adoption recommendation for bots
+ *  13. atf_billing_claim          — verify on-chain payment and process billing claim
+ *
+ * Exports:
+ *   - default: atfPlugin(api)        — legacy single-function entry
+ *   - register(api)                  — OpenClaw lifecycle: register tools
+ *   - activate(api)                  — OpenClaw lifecycle: activate plugin (config validation)
+ *   - deactivate()                   — OpenClaw lifecycle: deactivate plugin
+ *   - PLUGIN_ID                      — canonical plugin identity constant
+ *   - PLUGIN_VERSION                 — plugin version constant
+ *   - buildHumanSummary(reportJson)  — human messaging helper
+ *   - REASON_CODE_CATALOG            — deny reason code explanations
+ *   - ATF_BILLING_MANIFEST           — machine-readable billing metadata
+ *   - evaluateAdoption               — adoption advisor evaluation function
+ *   - TRIGGER_MODEL                  — frozen trigger definitions
+ *   - INSTALL_GUIDANCE               — frozen install/enable guidance
+ *   - SAFE_CALL_SEQUENCE             — frozen default call sequence
+ *   - verifyBillingClaim             — billing claim verification function
+ *   - CLAIM_STATUS                   — claim status enum
+ *   - CLAIM_DENY_CODES               — claim deny code catalog
+ *   - TREASURY_ADDRESS               — canonical treasury address
+ *   - USDC_MINT                      — canonical USDC mint address
+ *   - CONTRACT_FAMILIES              — universal contract family definitions
+ *   - TOOL_FAMILY_MAP                — tool → contract family mapping
+ *   - CANONICAL_TOOLS                — frozen list of all tool names
+ *   - CANONICAL_TOOL_COUNT           — number of canonical tools
  *
  * Uses ONLY built-in Node modules: child_process, fs, path, os, url.
  * No network calls unless config.safety.allowNetwork = true.
@@ -17,8 +48,59 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
+// Config validation — used by activate() for non-blocking warnings.
+// Imported as a module reference so activate() can call it synchronously.
+import * as _configModule from "./config.mjs";
+
+// Adoption advisor — deterministic trigger evaluation and recommendation.
+import {
+  evaluateAdoption,
+  TRIGGER_MODEL,
+  INSTALL_GUIDANCE,
+  SAFE_CALL_SEQUENCE,
+} from "./adoption_advisor.mjs";
+
+// Billing claim verification — deterministic on-chain payment verification.
+import {
+  verifyBillingClaim,
+  CLAIM_STATUS,
+  CLAIM_DENY_CODES,
+  TREASURY_ADDRESS,
+  USDC_MINT,
+  KNOWN_PACKAGES,
+  checkDuplicate,
+  _resetClaimTracking,
+} from "./billing_claim.mjs";
+
+// Standardized response helpers — OpenClaw adapter envelope builders.
+import {
+  nativeToolSuccess,
+  nativeToolError,
+  RESPONSE_STATUS,
+} from "./tool_response.mjs";
+
+// Universal contract layer — canonical schemas, codes, and result builders.
+// Re-exported so consumers can access the universal layer through the plugin.
+import {
+  REASON_CODE_CATALOG as _REASON_CODE_CATALOG,
+  CONTRACT_FAMILIES,
+  TOOL_FAMILY_MAP,
+  CANONICAL_TOOLS,
+  CANONICAL_TOOL_COUNT,
+} from "./contracts/index.mjs";
+
 const execFileAsync = promisify(execFile);
 
+// ---------------------------------------------------------------------------
+// Canonical plugin identity — use ONLY these constants everywhere
+// ---------------------------------------------------------------------------
+
+/** Canonical plugin ID. Must match openclaw.plugin.json `id` field. */
+export const PLUGIN_ID = "trucore-atf";
+
+/** Plugin version. Must match package.json + openclaw.plugin.json `version`. */
+export const PLUGIN_VERSION = "0.2.0";
+
 // ---------------------------------------------------------------------------
 // Default config
 // ---------------------------------------------------------------------------
@@ -89,33 +171,6 @@ function tryParseJson(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
 // ---------------------------------------------------------------------------
@@ -132,7 +187,8 @@ async function toolAtfDiscover(cfg, params = {}) {
   const { safety, atfBaseUrl } = cfg;
 
   if (!safety.allowNetwork) {
-    return toolResponse(
+    return nativeToolSuccess(
+      "atf_discover",
       "ATF discovery requires network access.",
       {
         instructions:
@@ -150,6 +206,7 @@ async function toolAtfDiscover(cfg, params = {}) {
         toolcard_url:
           "https://raw.githubusercontent.com/trucore-ai/agent-transaction-firewall/main/docs/agent/atf_toolcard.json",
       },
+      { status: RESPONSE_STATUS.UNAVAILABLE },
     );
   }
 
@@ -161,20 +218,24 @@ async function toolAtfDiscover(cfg, params = {}) {
   let manifest;
   try {
     const res = await fetch(base, {
-      headers: { "User-Agent": "openclaw-atf-plugin/0.1.0" },
+      headers: { "User-Agent": "openclaw-atf-plugin/0.2.0" },
       signal: AbortSignal.timeout(10_000),
     });
     if (!res.ok) {
-      return errorResponse(
+      return nativeToolError(
+        "atf_discover",
         `ATF manifest fetch failed: HTTP ${res.status} from ${base}`,
       );
     }
     manifest = await res.json();
   } catch (err) {
-    return errorResponse(`ATF manifest fetch error: ${err.message}`);
+    return nativeToolError(
+      "atf_discover",
+      `ATF manifest fetch error: ${err.message}`,
+    );
   }
 
-  const summary = {
+  const manifestSummary = {
     id: manifest.id ?? manifest.product ?? "trucore-atf",
     version: manifest.version ?? "unknown",
     capabilities: manifest.capabilities ?? [],
@@ -185,9 +246,10 @@ async function toolAtfDiscover(cfg, params = {}) {
     trust_signals: manifest.trust_signals ?? {},
   };
 
-  return toolResponse(
+  return nativeToolSuccess(
+    "atf_discover",
     "ATF manifest fetched. Key fields summarised below.",
-    summary,
+    manifestSummary,
   );
 }
 
@@ -209,16 +271,18 @@ async function toolAtfBootstrapPlan(cfg, params = {}) {
   const result = await runAtfCli(atfCli, args);
 
   if (result.exitCode !== 0) {
-    return errorResponse(
+    return nativeToolError(
+      "atf_bootstrap_plan",
       `atf bootstrap plan failed (exit ${result.exitCode}).\n` +
         `stderr: ${result.stderr}\nstdout: ${result.stdout}`,
     );
   }
 
   const parsed = tryParseJson(result.stdout);
-  return toolResponse(
+  return nativeToolSuccess(
+    "atf_bootstrap_plan",
     `Bootstrap plan for recipe '${recipe}' (plan only — no steps executed).`,
-    parsed,
+    typeof parsed === "object" && parsed !== null ? parsed : { raw: parsed },
   );
 }
 
@@ -237,9 +301,11 @@ async function toolAtfBootstrapExecuteSafe(cfg, params = {}) {
   const { atfCli, safety } = cfg;
 
   if (!safety.allowExecuteSafe) {
-    return errorResponse(
+    return nativeToolError(
+      "atf_bootstrap_execute_safe",
       "atf_bootstrap_execute_safe is disabled. " +
         "Set safety.allowExecuteSafe = true in the plugin config to enable.",
+      { remediation: ["Set safety.allowExecuteSafe = true in plugin config."] },
     );
   }
 
@@ -261,8 +327,9 @@ async function toolAtfBootstrapExecuteSafe(cfg, params = {}) {
   const parsed = tryParseJson(result.stdout);
 
   if (result.exitCode !== 0) {
-    // Non-fatal: return partial result + stderr
-    return toolResponse(
+    // Non-fatal: return partial result + stderr with degraded status
+    return nativeToolSuccess(
+      "atf_bootstrap_execute_safe",
       `Bootstrap execute-safe completed with non-zero exit (${result.exitCode}). ` +
         `Check executed_steps for partial results.`,
       {
@@ -270,12 +337,14 @@ async function toolAtfBootstrapExecuteSafe(cfg, params = {}) {
         stderr: result.stderr,
         result: parsed,
       },
+      { status: RESPONSE_STATUS.DEGRADED },
     );
   }
 
-  return toolResponse(
+  return nativeToolSuccess(
+    "atf_bootstrap_execute_safe",
     `Bootstrap execute-safe complete for recipe '${recipe}'.${dryRun ? " (dry-run)" : ""}`,
-    parsed,
+    typeof parsed === "object" && parsed !== null ? parsed : { raw: parsed },
   );
 }
 
@@ -294,8 +363,10 @@ async function toolAtfProtectIntent(cfg, params = {}) {
   const { intentJson, exposureHints } = params;
 
   if (!intentJson || typeof intentJson !== "object") {
-    return errorResponse(
+    return nativeToolError(
+      "atf_protect_intent",
       "atf_protect_intent requires 'intentJson' (object) input.",
+      { remediation: ["Provide an intentJson object with chain_id, intent_type, and intent fields."] },
     );
   }
 
@@ -322,31 +393,37 @@ async function toolAtfProtectIntent(cfg, params = {}) {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          "User-Agent": "openclaw-atf-plugin/0.1.0",
+          "User-Agent": "openclaw-atf-plugin/0.2.0",
         },
         body: payloadStr,
         signal: AbortSignal.timeout(15_000),
       });
     } catch (err) {
-      return errorResponse(`ATF API protect call failed: ${err.message}`);
+      return nativeToolError(
+        "atf_protect_intent",
+        `ATF API protect call failed: ${err.message}`,
+      );
     }
 
     let data;
     try {
       data = await res.json();
     } catch {
-      return errorResponse(
+      return nativeToolError(
+        "atf_protect_intent",
         `ATF API protect response not JSON (HTTP ${res.status}).`,
       );
     }
 
     if (!res.ok) {
-      return errorResponse(
+      return nativeToolError(
+        "atf_protect_intent",
         `ATF API protect HTTP ${res.status}: ${JSON.stringify(data)}`,
       );
     }
 
-    return toolResponse(
+    return nativeToolSuccess(
+      "atf_protect_intent",
       `ATF protect decision: ${data.allow ? "ALLOW" : "DENY"}.` +
         (data.reason_codes?.length
           ? ` Reason codes: ${data.reason_codes.join(", ")}.`
@@ -379,18 +456,20 @@ async function toolAtfProtectIntent(cfg, params = {}) {
     typeof parsed === "object" && parsed !== null ? parsed.allow : null;
 
   if (decision.exitCode !== 0 && typeof parsed !== "object") {
-    return errorResponse(
+    return nativeToolError(
+      "atf_protect_intent",
       `ATF protect failed (exit ${decision.exitCode}).\n` +
         `stderr: ${decision.stderr}\nstdout: ${decision.stdout}`,
     );
   }
 
-  return toolResponse(
+  return nativeToolSuccess(
+    "atf_protect_intent",
     `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,
+    typeof parsed === "object" && parsed !== null ? parsed : { raw: parsed },
   );
 }
 
@@ -409,9 +488,11 @@ async function toolAtfVerifyReceipt(cfg, params = {}) {
   const { receipt } = params;
 
   if (!receipt) {
-    return errorResponse(
+    return nativeToolError(
+      "atf_verify_receipt",
       "atf_verify_receipt requires 'receipt' param " +
         "(receipt JSON string, object, or file path).",
+      { remediation: ["Provide a receipt JSON object, JSON string, or file path."] },
     );
   }
 
@@ -461,7 +542,8 @@ async function toolAtfVerifyReceipt(cfg, params = {}) {
   const parsed = tryParseJson(result.stdout);
 
   if (result.exitCode !== 0) {
-    return errorResponse(
+    return nativeToolError(
+      "atf_verify_receipt",
       `ATF verify failed (exit ${result.exitCode}).\n` +
         `stderr: ${result.stderr}\nstdout: ${result.stdout}`,
     );
@@ -470,9 +552,10 @@ async function toolAtfVerifyReceipt(cfg, params = {}) {
   const verified =
     typeof parsed === "object" && parsed !== null ? parsed.verified : null;
 
-  return toolResponse(
+  return nativeToolSuccess(
+    "atf_verify_receipt",
     `Receipt verification: ${verified === true ? "VERIFIED" : verified === false ? "FAILED" : "see json"}.`,
-    parsed,
+    typeof parsed === "object" && parsed !== null ? parsed : { raw: parsed },
   );
 }
 
@@ -500,7 +583,8 @@ async function toolAtfReportSavings(cfg, params = {}) {
   const parsed = tryParseJson(result.stdout);
 
   if (result.exitCode !== 0) {
-    return errorResponse(
+    return nativeToolError(
+      "atf_report_savings",
       `ATF report savings failed (exit ${result.exitCode}).\n` +
         `stderr: ${result.stderr}\nstdout: ${result.stdout}`,
     );
@@ -510,7 +594,11 @@ async function toolAtfReportSavings(cfg, params = {}) {
     typeof parsed === "object" ? parsed : {},
   );
 
-  return toolResponse(summary, parsed);
+  return nativeToolSuccess(
+    "atf_report_savings",
+    summary,
+    typeof parsed === "object" && parsed !== null ? parsed : { raw: parsed },
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -649,6 +737,678 @@ export function buildHumanSummary(reportJson) {
   return lines.join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// Tool: atf_health — lightweight availability check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the ATF CLI or API backend is reachable.
+ * Never throws. Returns structured health status with backend resolution.
+ * Uses standardized nativeToolSuccess/nativeToolError response shapes.
+ *
+ * @param {Record<string, unknown>} cfg Resolved config.
+ * @returns {Promise<object>}
+ */
+async function toolAtfHealth(cfg) {
+  const { atfCli, prefer, atfBaseUrl } = cfg;
+
+  // Use shared backend probes
+  const { probeCliAvailable, probeApiAvailable, resolveBackend } =
+    await import("./backend.mjs");
+
+  const cli = await probeCliAvailable(atfCli);
+  const api = await probeApiAvailable(atfBaseUrl);
+  const backend = await resolveBackend(cfg, { cli, api });
+
+  const anyAvailable = cli.available === true || api.available === true;
+
+  const summary = anyAvailable
+    ? `ATF backend available (prefer=${prefer}, effective=${backend.effective_backend}).` +
+      (cli.available ? ` CLI: ${cli.version}.` : "") +
+      (api.available ? ` API: ${atfBaseUrl}.` : "") +
+      (backend.fallback_occurred ? ` [FALLBACK: ${backend.fallback_reason}]` : "")
+    : "ATF backend unavailable. CLI and API both unreachable. " +
+      "Tools will return errors until a backend is available.";
+
+  const status = anyAvailable
+    ? (backend.fallback_occurred ? RESPONSE_STATUS.DEGRADED : RESPONSE_STATUS.OK)
+    : RESPONSE_STATUS.UNAVAILABLE;
+
+  return nativeToolSuccess("atf_health", summary, {
+    healthy: anyAvailable,
+    cli,
+    api,
+  }, {
+    status,
+    backend,
+    warnings: backend.warnings,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_integration_doctor — readiness / troubleshooting
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the integration doctor and return a structured readiness report.
+ * Answers: Is the plugin loaded? CLI/API available? Tools registered?
+ * What should the operator do next?
+ * Uses standardized nativeToolSuccess response shape.
+ *
+ * @param {Record<string, unknown>} cfg  Resolved config.
+ * @param {string[]} registeredToolNames  Names of tools registered with this plugin.
+ * @returns {Promise<object>}
+ */
+async function toolAtfIntegrationDoctor(cfg, registeredToolNames) {
+  const { runDoctor } = await import("./doctor.mjs");
+  const { resolveBackend, probeCliAvailable, probeApiAvailable } =
+    await import("./backend.mjs");
+
+  const report = await runDoctor(cfg, registeredToolNames);
+
+  // Resolve backend for meta
+  const cli = await probeCliAvailable(cfg?.atfCli ?? "atf");
+  const api = await probeApiAvailable(cfg?.atfBaseUrl);
+  const backend = await resolveBackend(cfg, { cli, api });
+
+  const statusLine = {
+    ok: "Integration healthy. All systems operational.",
+    degraded: "Integration degraded. Some capabilities limited — see warnings.",
+    misconfigured: "Integration misconfigured. Check warnings and remediation steps.",
+    unavailable: "Integration unavailable. No ATF backend reachable.",
+  }[report.status] ?? `Integration status: ${report.status}`;
+
+  const responseStatus = {
+    ok: RESPONSE_STATUS.OK,
+    degraded: RESPONSE_STATUS.DEGRADED,
+    misconfigured: RESPONSE_STATUS.ERROR,
+    unavailable: RESPONSE_STATUS.UNAVAILABLE,
+  }[report.status] ?? RESPONSE_STATUS.ERROR;
+
+  return nativeToolSuccess("atf_integration_doctor", statusLine, report, {
+    status: responseStatus,
+    backend,
+    warnings: report.warnings,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Reason code catalog — sourced from universal contract layer
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical reason code catalog: re-exported from the universal contract
+ * layer (contracts/deny_codes.mjs). Used by atf_tx_explain and any future
+ * surface that needs to explain a deny decision.
+ *
+ * @type {Readonly<Record<string, {category: string, explanation: string, remediation: string}>>}
+ */
+export const REASON_CODE_CATALOG = _REASON_CODE_CATALOG;
+
+
+// ---------------------------------------------------------------------------
+// Tool: atf_bot_preflight — pre-session readiness check
+// ---------------------------------------------------------------------------
+
+/**
+ * Lightweight pre-session readiness check. Returns a structured go/no-go
+ * signal based on backend availability and config validity. Thinner than
+ * the full integration doctor — designed for agents to call before starting
+ * a bot session.
+ *
+ * Uses shared backend resolution + config validation. Never throws.
+ *
+ * @param {Record<string, unknown>} cfg  Resolved config.
+ * @param {Record<string, unknown>} [rawUserConfig]  Original user config for validation.
+ * @returns {Promise<object>}
+ */
+async function toolAtfBotPreflight(cfg, rawUserConfig) {
+  const { probeCliAvailable, probeApiAvailable, resolveBackend } =
+    await import("./backend.mjs");
+  const { validateConfig } = await import("./config.mjs");
+
+  const cli = await probeCliAvailable(cfg?.atfCli ?? "atf");
+  const api = await probeApiAvailable(cfg?.atfBaseUrl);
+  const backend = await resolveBackend(cfg, { cli, api });
+  const configResult = validateConfig(rawUserConfig ?? cfg);
+
+  const backendReady = backend.effective_backend !== "none";
+  const configValid = configResult.valid;
+  const ready = backendReady && configValid;
+
+  /** @type {string[]} */
+  const warnings = [...backend.warnings];
+  /** @type {string[]} */
+  const remediation = [];
+
+  if (!configValid) {
+    for (const err of configResult.errors) {
+      warnings.push(`Config: ${err}`);
+    }
+    for (const rem of configResult.remediation) {
+      remediation.push(rem);
+    }
+  }
+  for (const w of configResult.warnings) {
+    warnings.push(`Config: ${w}`);
+  }
+
+  if (!backendReady) {
+    remediation.push("Install ATF CLI: npm install -g @trucore/atf");
+    if (cfg?.prefer === "api") {
+      remediation.push("Or set atfBaseUrl to a reachable ATF API.");
+    }
+  }
+
+  const status = ready
+    ? (backend.fallback_occurred ? RESPONSE_STATUS.DEGRADED : RESPONSE_STATUS.OK)
+    : RESPONSE_STATUS.UNAVAILABLE;
+
+  const summary = ready
+    ? `Preflight OK. Backend: ${backend.effective_backend}.` +
+      (backend.fallback_occurred ? ` [FALLBACK: ${backend.fallback_reason}]` : "") +
+      " Ready to protect intents."
+    : "Preflight FAILED. " +
+      (!backendReady ? "No ATF backend available. " : "") +
+      (!configValid ? "Config has errors. " : "") +
+      "Run atf_integration_doctor for full details.";
+
+  return nativeToolSuccess("atf_bot_preflight", summary, {
+    ready,
+    backend_ready: backendReady,
+    config_valid: configValid,
+    config_errors: configResult.errors,
+    config_warnings: configResult.warnings,
+    cli_available: cli.available,
+    api_available: api.available,
+    remediation,
+  }, {
+    status,
+    backend,
+    warnings,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_tx_explain — explain a receipt or deny decision
+// ---------------------------------------------------------------------------
+
+/**
+ * Explain a receipt or deny decision in human-readable terms.
+ * Maps reason codes to explanations from the REASON_CODE_CATALOG.
+ * Thin adapter: does not re-evaluate policy, only explains.
+ *
+ * Accepts either:
+ *   - { reasonCodes: ["CODE1", "CODE2"] }
+ *   - { receipt: { reason_codes: [...], ... } }
+ *
+ * @param {Record<string, unknown>} _cfg  Resolved config (unused, for consistency).
+ * @param {{ reasonCodes?: string[], receipt?: object }} params
+ * @returns {object}
+ */
+function toolAtfTxExplain(_cfg, params = {}) {
+  const { reasonCodes: rawCodes, receipt } = params;
+
+  // Extract reason codes from receipt or params
+  let codes = [];
+  let decision = null;
+  let receiptMeta = null;
+
+  if (receipt && typeof receipt === "object") {
+    codes = receipt.reason_codes ?? receipt.reasonCodes ?? [];
+    decision = receipt.decision?.status ?? receipt.status ?? null;
+    receiptMeta = {
+      content_hash: receipt.content_hash ?? null,
+      intent_hash: receipt.intent_hash ?? null,
+      chain_id: receipt.chain_id ?? null,
+      intent_type: receipt.intent_type ?? null,
+      venue: receipt.venue ?? null,
+    };
+  }
+
+  if (Array.isArray(rawCodes) && rawCodes.length > 0) {
+    codes = rawCodes;
+  }
+
+  if (!Array.isArray(codes) || codes.length === 0) {
+    return nativeToolError(
+      "atf_tx_explain",
+      "atf_tx_explain requires 'reasonCodes' (string[]) or 'receipt' (object with reason_codes).",
+      { remediation: ["Provide reasonCodes array or a receipt object with reason_codes field."] },
+    );
+  }
+
+  // Map each code to explanation
+  const explanations = codes.map((code) => {
+    const entry = REASON_CODE_CATALOG[code];
+    if (entry) {
+      return {
+        code,
+        category: entry.category,
+        explanation: entry.explanation,
+        remediation: entry.remediation,
+      };
+    }
+    return {
+      code,
+      category: "unknown",
+      explanation: `Reason code '${code}' is not in the known catalog. Check docs/DENY_CODES.md for the full list.`,
+      remediation: "Consult ATF documentation for this deny code.",
+    };
+  });
+
+  // Build human summary
+  const lines = [];
+  if (decision) {
+    lines.push(`Decision: ${decision}`);
+  }
+  if (receiptMeta?.venue) {
+    lines.push(`Venue: ${receiptMeta.venue}`);
+  }
+  if (receiptMeta?.intent_type) {
+    lines.push(`Intent type: ${receiptMeta.intent_type}`);
+  }
+  lines.push("");
+  lines.push(`${codes.length} reason code${codes.length !== 1 ? "s" : ""} explained:`);
+  for (const exp of explanations) {
+    lines.push(`  • ${exp.code}: ${exp.explanation}`);
+  }
+
+  const summary = lines.join("\n");
+
+  return nativeToolSuccess("atf_tx_explain", summary, {
+    decision,
+    reason_codes: codes,
+    explanations,
+    receipt_meta: receiptMeta,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Billing manifest — machine-readable pricing/package metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * ATF billing manifest — machine-readable metadata for the Advanced Bot Package.
+ *
+ * Bots use this to discover pricing, accepted payment rails, and activation
+ * guidance without needing to parse docs or reverse-engineer billing logic.
+ *
+ * Exported so tests can validate structural integrity.
+ *
+ * @type {Readonly<Record<string, unknown>>}
+ */
+export const ATF_BILLING_MANIFEST = Object.freeze({
+  schema_version: "1",
+  product: "TruCore ATF",
+  id: "trucore-atf",
+  billing_manifest_version: "1.0.0",
+  packages: Object.freeze([
+    Object.freeze({
+      package_id: "atf_free_core",
+      package_name: "ATF Free Core",
+      package_tier: "free",
+      summary:
+        "Core transaction firewall capabilities — always free, no payment required.",
+      billing_model: "free",
+      price: null,
+    }),
+    Object.freeze({
+      package_id: "atf_advanced_bot",
+      package_name: "ATF Advanced Bot Package",
+      package_tier: "advanced",
+      summary:
+        "Premium capabilities for professional bot operators — " +
+        "priority support, advanced analytics, and premium integrations.",
+      billing_model: "subscription",
+      billing_interval: "monthly",
+      price: Object.freeze({
+        amount: "25.00",
+        currency: "USDC",
+        chain: "solana",
+      }),
+      price_alternatives: Object.freeze([
+        Object.freeze({
+          amount: "0.1",
+          currency: "SOL",
+          chain: "solana",
+          note: "Approximate SOL equivalent (~0.1 SOL/month) — confirm current rate before sending.",
+        }),
+      ]),
+      status: "accepting_payments",
+    }),
+  ]),
+  payment_rails: Object.freeze({
+    chain: "solana",
+    network: "mainnet-beta",
+    accepted_assets: Object.freeze([
+      Object.freeze({
+        asset: "USDC",
+        mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+        decimals: 6,
+        preferred: true,
+      }),
+      Object.freeze({
+        asset: "SOL",
+        mint: "native",
+        decimals: 9,
+        preferred: false,
+      }),
+    ]),
+    recipient: Object.freeze({
+      address: "GFHVjxUiPWLs214QZToMvJ8PcacBkkzpiQugE5gXGSmx",
+      label: "TruCore Treasury",
+      note: "TruCore treasury on Solana mainnet-beta. " +
+        "Verify this address before sending funds.",
+    }),
+    memo_requirements: Object.freeze({
+      required: true,
+      format: "atf:<package_id>:<your_identifier>",
+      example: "atf:atf_advanced_bot:my-bot-v1",
+    }),
+    confirmation_expectations: Object.freeze({
+      confirmations: "confirmed",
+      estimated_time_seconds: 5,
+    }),
+  }),
+  free_vs_advanced: Object.freeze({
+    free_core_tools: Object.freeze([
+      "atf_health",
+      "atf_discover",
+      "atf_bootstrap_plan",
+      "atf_bootstrap_execute_safe",
+      "atf_protect_intent",
+      "atf_verify_receipt",
+      "atf_report_savings",
+      "atf_integration_doctor",
+      "atf_bot_preflight",
+      "atf_tx_explain",
+      "atf_billing_info",
+      "atf_adoption_advisor",
+      "atf_billing_claim",
+    ]),
+    advanced_package_features: Object.freeze([
+      "priority_support",
+      "advanced_analytics",
+      "custom_policy_review",
+      "early_access_modules",
+      "priority_bug_fixes",
+      "multi_bot_oversight",
+      "bot_governor",
+      "escalation_controls",
+      "circuit_breaker",
+    ]),
+    note: "All core ATF enforcement tools remain free. " +
+      "The advanced package adds premium support surfaces and " +
+      "future operator controls. No existing free tool will be " +
+      "moved behind a paywall.",
+  }),
+  activation: Object.freeze({
+    method: "pay_then_claim",
+    current_reality:
+      "Payment is accepted on-chain. Claim verification is automated via " +
+      "atf_billing_claim — submit your transaction signature and receive a " +
+      "deterministic verification result. Entitlement provisioning after " +
+      "verification is currently semi-automated.",
+    automated_entitlement: "claim_verification",
+    support_contact: "support@trucore.xyz",
+  }),
+  warnings: Object.freeze([
+    "Early-stage billing — pricing and payment flow may change. Always check this manifest for current rates.",
+    "SOL pricing is approximate — confirm current SOL/USD exchange rate before sending.",
+    "Claim verification is automated via atf_billing_claim. Entitlement provisioning after verification is semi-automated.",
+    "Anti-replay duplicate detection is in-memory and resets on process restart.",
+    "Pricing is subject to change — always check this manifest for current rates.",
+    "This billing manifest is informational — it does not execute payments.",
+  ]),
+});
+
+// ---------------------------------------------------------------------------
+// Tool: atf_adoption_advisor — deterministic adoption recommendation
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate bot capability signals and return a deterministic adoption
+ * recommendation including install_needed, recommended_tier, reason_codes,
+ * call sequence, and install guidance.
+ *
+ * Read-only, pure metadata. No side effects, no network calls.
+ *
+ * @param {Record<string, unknown>} _cfg  Resolved config (unused).
+ * @param {{ signals?: Record<string, boolean> }} params
+ * @returns {object}
+ */
+function toolAtfAdoptionAdvisor(_cfg, params = {}) {
+  const { signals } = params;
+
+  // Validate signals shape
+  if (signals !== undefined && signals !== null) {
+    if (typeof signals !== "object" || Array.isArray(signals)) {
+      return nativeToolError(
+        "atf_adoption_advisor",
+        "Invalid 'signals' parameter: must be an object mapping " +
+          "trigger_id keys to boolean values. Example: " +
+          '{"bot_handles_real_capital": true, "bot_retries_automatically": false}',
+        {
+          remediation: [
+            "Provide signals as an object: {trigger_id: true/false, ...}",
+            "Omit signals entirely to evaluate with no triggers matched.",
+            "Valid trigger_ids: " +
+              TRIGGER_MODEL.map((t) => t.trigger_id).join(", "),
+          ],
+        },
+      );
+    }
+  }
+
+  const result = evaluateAdoption(signals ?? {});
+
+  const summary = result.install_needed
+    ? `ATF adoption recommended (${result.recommended_tier}). ` +
+      `${result.matched_triggers.length} trigger(s) matched. ` +
+      `Highest severity: ${result.highest_severity}.`
+    : "ATF adoption not currently needed. No triggers matched. " +
+      "Monitor for future trigger activation.";
+
+  return nativeToolSuccess("atf_adoption_advisor", summary, result);
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_billing_info — billing / pricing metadata discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Return machine-readable billing and package metadata for ATF.
+ *
+ * Read-only metadata tool — does NOT execute payments or check entitlements.
+ * Bots use this to discover:
+ *   - which packages/tiers exist (free core vs advanced)
+ *   - pricing and accepted payment assets
+ *   - payment rail details (chain, recipient, memo format)
+ *   - activation/claim flow guidance
+ *   - free-vs-advanced capability split
+ *
+ * Always succeeds (pure metadata, no backend dependency).
+ *
+ * @param {Record<string, unknown>} _cfg  Resolved config (unused, for consistency).
+ * @param {{ packageId?: string }} params
+ * @returns {object}
+ */
+function toolAtfBillingInfo(_cfg, params = {}) {
+  const { packageId } = params;
+
+  // If a specific package is requested, filter
+  if (packageId && typeof packageId === "string") {
+    const pkg = ATF_BILLING_MANIFEST.packages.find(
+      (p) => p.package_id === packageId,
+    );
+    if (!pkg) {
+      return nativeToolError(
+        "atf_billing_info",
+        `Unknown package_id: '${packageId}'. ` +
+          `Available: ${ATF_BILLING_MANIFEST.packages.map((p) => p.package_id).join(", ")}.`,
+        {
+          remediation: [
+            "Use one of the available package IDs, or omit packageId to see all packages.",
+          ],
+        },
+      );
+    }
+
+    return nativeToolSuccess(
+      "atf_billing_info",
+      `Billing info for package '${pkg.package_name}' (${pkg.package_tier} tier).`,
+      {
+        package: pkg,
+        payment_rails: ATF_BILLING_MANIFEST.payment_rails,
+        activation: ATF_BILLING_MANIFEST.activation,
+        warnings: ATF_BILLING_MANIFEST.warnings,
+      },
+    );
+  }
+
+  // Full manifest
+  return nativeToolSuccess(
+    "atf_billing_info",
+    "ATF billing metadata: 2 packages (free core + advanced bot). " +
+      "Payment accepted on Solana (USDC preferred). " +
+      "See result for full pricing, payment rails, and activation guidance.",
+    {
+      packages: ATF_BILLING_MANIFEST.packages,
+      payment_rails: ATF_BILLING_MANIFEST.payment_rails,
+      free_vs_advanced: ATF_BILLING_MANIFEST.free_vs_advanced,
+      activation: ATF_BILLING_MANIFEST.activation,
+      warnings: ATF_BILLING_MANIFEST.warnings,
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tool: atf_billing_claim — verify on-chain payment and process claim
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify an on-chain Solana payment and process a billing claim for
+ * the ATF Advanced Bot Package.
+ *
+ * Checks: tx exists, finalized, recipient = treasury, asset + amount match
+ * package pricing, no duplicate claim.
+ *
+ * @param {Record<string, unknown>} cfg  Resolved config.
+ * @param {object} params
+ * @param {string} params.tx_signature   Solana transaction signature.
+ * @param {string} params.wallet         Claimant wallet address.
+ * @param {string} params.package_id     Package being claimed.
+ * @param {string} [params.asset_symbol] Optional asset hint: "USDC" or "SOL".
+ * @param {string} [params.cluster]      Optional cluster: "mainnet-beta" (default).
+ * @returns {Promise<object>}
+ */
+async function toolAtfBillingClaim(cfg, params = {}) {
+  const { tx_signature, wallet, package_id, asset_symbol, cluster } = params;
+
+  // Build fetchTransaction from config if RPC access is available
+  let fetchTransaction = null;
+  const rpcUrl = cfg?.solanaRpcUrl;
+  if (rpcUrl && typeof rpcUrl === "string") {
+    fetchTransaction = async (sig, _cluster) => {
+      const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "getTransaction",
+        params: [
+          sig,
+          {
+            encoding: "jsonParsed",
+            maxSupportedTransactionVersion: 0,
+            commitment: "confirmed",
+          },
+        ],
+      });
+
+      const res = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+        signal: AbortSignal.timeout(15_000),
+      });
+
+      if (!res.ok) {
+        throw new Error(`RPC HTTP ${res.status}`);
+      }
+
+      const json = await res.json();
+      if (json.error) {
+        throw new Error(json.error.message ?? JSON.stringify(json.error));
+      }
+
+      const tx = json.result;
+      if (!tx) return null;
+
+      // Attach confirmationStatus from RPC response context if available
+      if (!tx.confirmationStatus && json.result?.slot) {
+        tx.confirmationStatus = "confirmed";
+      }
+      return tx;
+    };
+  }
+
+  const claimResult = await verifyBillingClaim(
+    { tx_signature, wallet, package_id, asset_symbol, cluster },
+    { fetchTransaction },
+  );
+
+  // Map claim result to native response envelope
+  if (claimResult.claim_status === CLAIM_STATUS.VERIFIED) {
+    return nativeToolSuccess(
+      "atf_billing_claim",
+      `Billing claim verified: ${claimResult.amount_received} ` +
+        `${claimResult.asset_symbol} received for package ` +
+        `'${claimResult.package_id}'. Entitlement: ${claimResult.entitlement_status}.`,
+      claimResult,
+      { warnings: claimResult.warnings },
+    );
+  }
+
+  // Denied or error
+  const summary =
+    `Billing claim ${claimResult.claim_status}: ` +
+    `${claimResult.deny_code ?? "unknown error"}. ` +
+    (claimResult.remediation.length > 0
+      ? claimResult.remediation[0]
+      : "See result for details.");
+
+  return nativeToolError("atf_billing_claim", summary, {
+    remediation: claimResult.remediation,
+    warnings: claimResult.warnings,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Safe handler wrapper — graceful degradation for all tool handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a tool handler so runtime errors never crash the gateway.
+ * Returns an errorResponse on any uncaught exception.
+ *
+ * @param {string} toolName
+ * @param {Function} handler
+ * @returns {Function}
+ */
+function safeHandler(toolName, handler) {
+  return async (params) => {
+    try {
+      return await handler(params);
+    } catch (err) {
+      return nativeToolError(
+        toolName,
+        `[${PLUGIN_ID}] ${toolName} failed: ${err?.message ?? String(err)}. ` +
+          "ATF core CLI fallback is still available.",
+      );
+    }
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Plugin entry-point
 // ---------------------------------------------------------------------------
@@ -660,11 +1420,42 @@ export function buildHumanSummary(reportJson) {
  * All tools are registered as OPTIONAL — agents / operators must allowlist
  * them before they can be used.
  *
+ * Safe: catches all registration errors, logs warnings, never throws.
+ *
  * @param {{ registerTool: Function, config: Record<string, unknown> }} api
  */
 export default function atfPlugin(api) {
+  if (!api || typeof api.registerTool !== "function") {
+    // Defensive: if api is missing or malformed, log and bail out silently.
+    // This prevents crashing the OpenClaw gateway on bad plugin load.
+    if (typeof console !== "undefined") {
+      console.warn(
+        `[${PLUGIN_ID}] Plugin loaded with invalid api object. ` +
+          "Skipping tool registration. ATF CLI fallback is still available.",
+      );
+    }
+    return;
+  }
+
   const cfg = resolveConfig(api?.config ?? {});
 
+  // ---- Tool 0: atf_health -------------------------------------------------
+  api.registerTool({
+    name: "atf_health",
+    optional: true,
+    description:
+      "Check ATF CLI and API backend availability. " +
+      "Returns structured health status including version, reachability, " +
+      "and preferred mode. Use this to verify ATF is ready before calling " +
+      "other ATF tools.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    handler: safeHandler("atf_health", () => toolAtfHealth(cfg)),
+  });
+
   // ---- Tool 1: atf_discover -----------------------------------------------
   api.registerTool({
     name: "atf_discover",
@@ -685,7 +1476,7 @@ export default function atfPlugin(api) {
       },
       additionalProperties: false,
     },
-    handler: (params) => toolAtfDiscover(cfg, params),
+    handler: safeHandler("atf_discover", (params) => toolAtfDiscover(cfg, params)),
   });
 
   // ---- Tool 2: atf_bootstrap_plan -----------------------------------------
@@ -709,7 +1500,7 @@ export default function atfPlugin(api) {
       },
       additionalProperties: false,
     },
-    handler: (params) => toolAtfBootstrapPlan(cfg, params),
+    handler: safeHandler("atf_bootstrap_plan", (params) => toolAtfBootstrapPlan(cfg, params)),
   });
 
   // ---- Tool 3: atf_bootstrap_execute_safe ---------------------------------
@@ -736,7 +1527,7 @@ export default function atfPlugin(api) {
       },
       additionalProperties: false,
     },
-    handler: (params) => toolAtfBootstrapExecuteSafe(cfg, params),
+    handler: safeHandler("atf_bootstrap_execute_safe", (params) => toolAtfBootstrapExecuteSafe(cfg, params)),
   });
 
   // ---- Tool 4: atf_protect_intent -----------------------------------------
@@ -772,7 +1563,7 @@ export default function atfPlugin(api) {
       },
       additionalProperties: false,
     },
-    handler: (params) => toolAtfProtectIntent(cfg, params),
+    handler: safeHandler("atf_protect_intent", (params) => toolAtfProtectIntent(cfg, params)),
   });
 
   // ---- Tool 5: atf_verify_receipt -----------------------------------------
@@ -794,7 +1585,7 @@ export default function atfPlugin(api) {
       },
       additionalProperties: false,
     },
-    handler: (params) => toolAtfVerifyReceipt(cfg, params),
+    handler: safeHandler("atf_verify_receipt", (params) => toolAtfVerifyReceipt(cfg, params)),
   });
 
   // ---- Tool 6: atf_report_savings -----------------------------------------
@@ -822,6 +1613,313 @@ export default function atfPlugin(api) {
       },
       additionalProperties: false,
     },
-    handler: (params) => toolAtfReportSavings(cfg, params),
+    handler: safeHandler("atf_report_savings", (params) => toolAtfReportSavings(cfg, params)),
   });
+
+  // ---- Tool 7: atf_integration_doctor ------------------------------------
+  // Collect registered tool names for the doctor report.
+  // We need to register it after all other tools so it can see them.
+  const registeredToolNames = [...api.tools?.keys?.() ?? []];
+  // The doctor + remaining tools are about to be added
+  registeredToolNames.push(
+    "atf_integration_doctor",
+    "atf_bot_preflight",
+    "atf_tx_explain",
+    "atf_billing_info",
+    "atf_adoption_advisor",
+    "atf_billing_claim",
+  );
+
+  api.registerTool({
+    name: "atf_integration_doctor",
+    optional: true,
+    description:
+      "Run ATF integration readiness check. Reports plugin loading status, " +
+      "CLI/API availability, backend preference vs effective backend, " +
+      "registered tools, configuration warnings, and remediation steps. " +
+      "Use this to validate and troubleshoot the ATF OpenClaw integration.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    handler: safeHandler(
+      "atf_integration_doctor",
+      () => toolAtfIntegrationDoctor(cfg, registeredToolNames),
+    ),
+  });
+
+  // ---- Tool 8: atf_bot_preflight ------------------------------------------
+  api.registerTool({
+    name: "atf_bot_preflight",
+    optional: true,
+    description:
+      "Pre-session readiness check: is ATF ready to protect intents right now? " +
+      "Returns a structured go/no-go signal with backend availability, " +
+      "config validity, and remediation steps. Lighter than atf_integration_doctor — " +
+      "use this before starting a bot session to confirm ATF is operational.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    handler: safeHandler(
+      "atf_bot_preflight",
+      () => toolAtfBotPreflight(cfg, api?.config),
+    ),
+  });
+
+  // ---- Tool 9: atf_tx_explain ---------------------------------------------
+  api.registerTool({
+    name: "atf_tx_explain",
+    optional: true,
+    description:
+      "Explain an ATF deny decision or receipt in human terms. " +
+      "Maps each reason code to a structured explanation with category, " +
+      "plain-language description, and remediation guidance. " +
+      "Does not re-evaluate policy — only explains existing decisions. " +
+      "Accepts either 'reasonCodes' (string[]) or 'receipt' (object with reason_codes).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reasonCodes: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Array of ATF reason codes to explain (e.g. ['DEX_VENUE_NOT_ALLOWED']).",
+        },
+        receipt: {
+          type: "object",
+          description:
+            "An ATF receipt or decision object with a reason_codes field. " +
+            "If provided, reason codes are extracted from this object.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: safeHandler(
+      "atf_tx_explain",
+      (params) => toolAtfTxExplain(cfg, params),
+    ),
+  });
+
+  // ---- Tool 10: atf_billing_info ------------------------------------------
+  api.registerTool({
+    name: "atf_billing_info",
+    optional: true,
+    description:
+      "Discover ATF billing, pricing, and package metadata. " +
+      "Returns machine-readable info about free-core vs advanced-package tiers, " +
+      "accepted payment assets (USDC, SOL on Solana), payment rail details, " +
+      "and activation/claim flow guidance. " +
+      "Read-only metadata — does NOT execute payments.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        packageId: {
+          type: "string",
+          description:
+            "Optional package ID to filter (e.g. 'atf_free_core' or 'atf_advanced_bot'). " +
+            "Omit to see all packages.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: safeHandler(
+      "atf_billing_info",
+      (params) => toolAtfBillingInfo(cfg, params),
+    ),
+  });
+
+  // ---- Tool 11: atf_adoption_advisor --------------------------------------
+  api.registerTool({
+    name: "atf_adoption_advisor",
+    optional: true,
+    description:
+      "Evaluate bot capability signals and return a deterministic ATF " +
+      "adoption recommendation. Returns install_needed, recommended_tier " +
+      "(free_core / advanced_bot / none), matched triggers with severity, " +
+      "safe default call sequence, install/enable guidance, and next actions. " +
+      "Read-only, pure metadata — no side effects.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        signals: {
+          type: "object",
+          description:
+            "Map of trigger_id to boolean. Example: " +
+            '{"bot_handles_real_capital": true, "bot_retries_automatically": false}. ' +
+            "Valid trigger_ids: bot_handles_real_capital, " +
+            "bot_signs_or_submits_transactions, bot_retries_automatically, " +
+            "bot_lacks_audit_trail, bot_operates_without_spending_limits, " +
+            "operator_cannot_explain_failures, " +
+            "bot_uses_multiple_dexes_or_protocols, " +
+            "bot_runs_unattended, bot_needs_operator_controls. " +
+            "Omit to evaluate with no triggers (returns install_needed=false).",
+          additionalProperties: { type: "boolean" },
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: safeHandler(
+      "atf_adoption_advisor",
+      (params) => toolAtfAdoptionAdvisor(cfg, params),
+    ),
+  });
+
+  // ---- Tool 12: atf_billing_claim ----------------------------------------
+  api.registerTool({
+    name: "atf_billing_claim",
+    optional: true,
+    description:
+      "Verify an on-chain Solana payment and process a billing claim for " +
+      "the ATF Advanced Bot Package. Checks transaction existence, finality, " +
+      "treasury recipient, asset type (USDC or SOL), and amount against " +
+      "published pricing. Returns a deterministic claim result with " +
+      "entitlement status. Requires tx_signature, wallet, and package_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tx_signature: {
+          type: "string",
+          description:
+            "Solana transaction signature (base58). " +
+            "The payment transaction to verify.",
+        },
+        wallet: {
+          type: "string",
+          description:
+            "Claimant wallet address (Solana public key). " +
+            "The wallet that made the payment.",
+        },
+        package_id: {
+          type: "string",
+          description:
+            "Package to claim. Currently: 'atf_advanced_bot'. " +
+            "Use atf_billing_info to discover available packages.",
+        },
+        asset_symbol: {
+          type: "string",
+          description:
+            "Optional: asset hint — 'USDC' or 'SOL'. " +
+            "If omitted, both are checked automatically.",
+        },
+        cluster: {
+          type: "string",
+          description:
+            "Optional: Solana cluster — 'mainnet-beta' (default). " +
+            "Production entitlements require mainnet-beta.",
+        },
+      },
+      required: ["tx_signature", "wallet", "package_id"],
+      additionalProperties: false,
+    },
+    handler: safeHandler(
+      "atf_billing_claim",
+      (params) => toolAtfBillingClaim(cfg, params),
+    ),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// OpenClaw lifecycle exports: register / activate / deactivate
+// ---------------------------------------------------------------------------
+
+/**
+ * OpenClaw lifecycle: register tools.
+ * Equivalent to the default export (atfPlugin). Provided as a named export
+ * to match the expected OpenClaw plugin contract.
+ *
+ * Safe: never throws. If api is invalid, logs a warning and returns.
+ *
+ * @param {{ registerTool: Function, config: Record<string, unknown> }} api
+ */
+export function register(api) {
+  try {
+    atfPlugin(api);
+  } catch (err) {
+    if (typeof console !== "undefined") {
+      console.warn(
+        `[${PLUGIN_ID}] register() failed: ${err?.message ?? String(err)}. ` +
+          "ATF CLI fallback is still available.",
+      );
+    }
+  }
+}
+
+/**
+ * OpenClaw lifecycle: activate plugin.
+ * Called after register() succeeds. Runs non-blocking config validation
+ * and surfaces warnings/errors to the operator via console.warn.
+ *
+ * CRITICAL RULE: Config validation NEVER blocks activation.
+ * Invalid config → warn + degrade gracefully. Never throw.
+ *
+ * @param {{ config?: Record<string, unknown> }} [ctx]
+ */
+export function activate(ctx) {
+  try {
+    // Import config validation lazily to avoid circular dependency
+    // at module-evaluation time (config.mjs is side-effect-free).
+    const { validateConfig, formatActivationWarnings } = /** @type {any} */ (
+      // Dynamic import would be async—config.mjs is already loaded at this
+      // point (register imports it transitively via doctor.mjs), so we use
+      // a synchronous re-export pattern instead. The helper is pure &
+      // deterministic, so calling it synchronously is safe.
+      _configModule
+    );
+
+    const rawConfig = ctx?.config ?? undefined;
+    const result = validateConfig(rawConfig);
+    const lines = formatActivationWarnings(result);
+
+    if (lines.length > 0 && typeof console !== "undefined") {
+      for (const line of lines) {
+        console.warn(line);
+      }
+    }
+  } catch {
+    // Activation must NEVER fail. Swallow any unexpected error.
+    if (typeof console !== "undefined") {
+      console.warn(
+        `[${PLUGIN_ID}] activate() config validation failed unexpectedly. ` +
+          "Plugin is still operational. Run atf_integration_doctor for details.",
+      );
+    }
+  }
+}
+
+/**
+ * OpenClaw lifecycle: deactivate plugin.
+ * Called when the plugin is disabled or the gateway shuts down.
+ * Currently a no-op. Provided for forward compatibility.
+ */
+export function deactivate() {
+  // No-op: ATF holds no persistent connections or state.
 }
+
+// REASON_CODE_CATALOG is exported at definition site (above).
+
+// Re-export adoption advisor primitives for external consumers.
+export { evaluateAdoption, TRIGGER_MODEL, INSTALL_GUIDANCE, SAFE_CALL_SEQUENCE };
+
+// Re-export billing claim primitives for external consumers and tests.
+export {
+  verifyBillingClaim,
+  CLAIM_STATUS,
+  CLAIM_DENY_CODES,
+  TREASURY_ADDRESS,
+  USDC_MINT,
+  KNOWN_PACKAGES,
+  checkDuplicate,
+  _resetClaimTracking,
+};
+
+// Re-export universal contract layer for external consumers,
+// future adapters, and SDK/CLI surfaces.
+export {
+  CONTRACT_FAMILIES,
+  TOOL_FAMILY_MAP,
+  CANONICAL_TOOLS,
+  CANONICAL_TOOL_COUNT,
+};