@trucore/openclaw-atf 0.1.0 → 0.2.0

package/src/adoption_advisor.mjs

@@ -0,0 +1,425 @@
+/**
+ * adoption_advisor.mjs — Deterministic ATF adoption advisor
+ *
+ * Evaluates a set of bot capability signals against the ATF trigger model
+ * and returns a machine-readable adoption recommendation.
+ *
+ * Pure, deterministic, read-only. No side effects, no network calls.
+ *
+ * Exports:
+ *   - evaluateAdoption(signals)    — core evaluation function
+ *   - TRIGGER_MODEL                — frozen trigger definitions
+ *   - INSTALL_GUIDANCE             — frozen install/enable guidance
+ *   - SAFE_CALL_SEQUENCE           — frozen default call sequence
+ */
+
+// ---------------------------------------------------------------------------
+// Trigger model — frozen, deterministic
+// ---------------------------------------------------------------------------
+
+/** @typedef {"critical"|"high"|"medium"|"low"} Severity */
+/** @typedef {"free_core"|"advanced_bot"} Tier */
+
+/**
+ * @typedef {Object} Trigger
+ * @property {string} trigger_id
+ * @property {string} title
+ * @property {Severity} severity
+ * @property {string} description
+ * @property {string} machine_check
+ * @property {string} rationale
+ * @property {string} recommendation
+ * @property {Tier} recommended_tier
+ * @property {string[]} next_actions
+ */
+
+/** Severity ordering for comparison. */
+const SEVERITY_RANK = Object.freeze({
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1,
+});
+
+/** All known trigger definitions. */
+export const TRIGGER_MODEL = Object.freeze([
+  Object.freeze({
+    trigger_id: "bot_handles_real_capital",
+    title: "Bot Handles Real Capital",
+    severity: "critical",
+    description:
+      "Bot sends transactions involving real tokens with monetary value",
+    machine_check:
+      "bot submits on-chain transactions with non-zero token amounts",
+    rationale:
+      "Any bot moving real capital without policy enforcement risks " +
+      "unbounded financial loss.",
+    recommendation:
+      "Install ATF immediately. Enable atf_protect_intent before " +
+      "every on-chain transaction.",
+    recommended_tier: "free_core",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "atf health",
+      "atf bot preflight",
+      "echo '{...}' | atf bot protect --stdin",
+    ]),
+  }),
+  Object.freeze({
+    trigger_id: "bot_signs_or_submits_transactions",
+    title: "Bot Signs or Submits Transactions",
+    severity: "critical",
+    description:
+      "Bot has signing authority and broadcasts transactions to a blockchain",
+    machine_check:
+      "bot calls sendTransaction, signTransaction, or equivalent RPC method",
+    rationale:
+      "Signing authority without enforcement middleware means the bot " +
+      "can submit any transaction without constraint.",
+    recommendation:
+      "Install ATF immediately. Place atf_protect_intent before " +
+      "every sign-and-submit call.",
+    recommended_tier: "free_core",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "atf health",
+      "atf bot preflight",
+      "echo '{...}' | atf bot protect --stdin",
+    ]),
+  }),
+  Object.freeze({
+    trigger_id: "bot_retries_automatically",
+    title: "Bot Auto-Retries Failed Transactions",
+    severity: "high",
+    description:
+      "Bot retries failed transactions without human approval between attempts",
+    machine_check: "bot retry loop runs without human-in-the-loop gate",
+    rationale:
+      "Unguarded retry loops can escalate errors — e.g. increasing " +
+      "slippage or resubmitting to a failing venue.",
+    recommendation:
+      "Install ATF. Wrap each retry in atf_protect_intent.",
+    recommended_tier: "free_core",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "atf bot preflight",
+      "Wrap retry loop: each attempt calls atf bot protect --stdin",
+      "Save receipt for every attempt",
+    ]),
+  }),
+  Object.freeze({
+    trigger_id: "bot_lacks_audit_trail",
+    title: "Bot Lacks Tamper-Evident Audit Trail",
+    severity: "high",
+    description:
+      "Bot cannot produce tamper-evident receipts or explain why " +
+      "a transaction was approved",
+    machine_check:
+      "no tamper-evident receipt generation per transaction decision",
+    rationale:
+      "Without receipts, operators cannot prove what the bot approved, " +
+      "when, or why.",
+    recommendation:
+      "Install ATF. Save all receipts. Use atf_verify_receipt " +
+      "for integrity checks.",
+    recommended_tier: "free_core",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "echo '{...}' | atf bot protect --stdin",
+      "Save receipt JSON to ./atf_receipts/",
+      "atf receipts verify --file receipt.json",
+    ]),
+  }),
+  Object.freeze({
+    trigger_id: "bot_operates_without_spending_limits",
+    title: "Bot Has No Spending Limits",
+    severity: "high",
+    description:
+      "No policy caps on notional size, leverage, or slippage",
+    machine_check:
+      "no max_notional, max_leverage, or max_slippage configuration",
+    rationale:
+      "Unbounded parameters allow catastrophic single-transaction losses.",
+    recommendation:
+      "Install ATF. Configure spending limits in policy YAML.",
+    recommended_tier: "free_core",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "Configure policy YAML with spending limits",
+      "atf bot preflight",
+    ]),
+  }),
+  Object.freeze({
+    trigger_id: "operator_cannot_explain_failures",
+    title: "Operator Cannot Explain Transaction Failures",
+    severity: "medium",
+    description:
+      "Operator cannot determine why a transaction was blocked or allowed",
+    machine_check:
+      "no structured reason codes in transaction decision logs",
+    rationale:
+      "Silent failures erode operator trust and make post-mortems impossible.",
+    recommendation:
+      "Install ATF. Use atf_tx_explain after any DENY.",
+    recommended_tier: "free_core",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "atf bot protect --stdin for every intent",
+      "On DENY: atf tx explain --reason-codes CODES",
+    ]),
+  }),
+  Object.freeze({
+    trigger_id: "bot_uses_multiple_dexes_or_protocols",
+    title: "Bot Uses Multiple DEXes or Protocols",
+    severity: "medium",
+    description:
+      "Bot routes through multiple DeFi protocols, DEXes, or lending venues",
+    machine_check:
+      "bot interacts with 2 or more DeFi protocols or venues",
+    rationale:
+      "Multi-venue bots have a larger attack surface and more complex " +
+      "failure modes.",
+    recommendation:
+      "Install ATF. Configure allowed_venues in policy YAML.",
+    recommended_tier: "free_core",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "Configure allowed_venues per category in policy YAML",
+      "atf bot preflight",
+    ]),
+  }),
+  Object.freeze({
+    trigger_id: "bot_runs_unattended",
+    title: "Bot Runs Unattended",
+    severity: "medium",
+    description:
+      "Bot executes for extended periods without operator supervision",
+    machine_check:
+      "bot session duration exceeds 1 hour without human check-in",
+    rationale:
+      "Unattended bots can accumulate risk without oversight.",
+    recommendation:
+      "Install ATF. Run atf_bot_preflight at session start.",
+    recommended_tier: "free_core",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "atf bot preflight at session start",
+      "atf report savings at session end",
+    ]),
+  }),
+  Object.freeze({
+    trigger_id: "bot_needs_operator_controls",
+    title: "Bot Needs Richer Operator Controls",
+    severity: "low",
+    description:
+      "Operator requires multi-bot oversight, governor controls, " +
+      "escalation, or circuit-breaker capabilities",
+    machine_check:
+      "operator requests session model, multi-bot governance, " +
+      "kill-switch, or escalation workflows",
+    rationale:
+      "Professional bot operators need richer controls. The ATF " +
+      "Advanced Bot Package provides priority support and upcoming " +
+      "operator-grade governance.",
+    recommendation:
+      "Install ATF free core first. Evaluate whether advanced_bot " +
+      "package is needed.",
+    recommended_tier: "advanced_bot",
+    next_actions: Object.freeze([
+      "npm install -g @trucore/atf",
+      "Verify free core meets current needs",
+      "Review billing.json for advanced_bot pricing",
+      "Contact support@trucore.xyz for custom policy consulting",
+    ]),
+  }),
+]);
+
+// ---------------------------------------------------------------------------
+// Install guidance — frozen, deterministic
+// ---------------------------------------------------------------------------
+
+export const INSTALL_GUIDANCE = Object.freeze({
+  package_identity: Object.freeze({
+    npm_cli: "@trucore/atf",
+    npm_openclaw_plugin: "@trucore/openclaw-atf",
+    plugin_id: "trucore-atf",
+  }),
+  install_command: "npm install -g @trucore/atf",
+  verify_commands: Object.freeze(["atf --version", "atf health"]),
+  minimal_config_path:
+    "Zero-config first — ATF uses safe defaults. " +
+    "Add policy YAML when ready to customize.",
+  zero_config_available: true,
+  disable_command: "npm uninstall -g @trucore/atf",
+  restart_needed: false,
+  what_is_automated: Object.freeze([
+    "CLI installation via npm",
+    "Health and preflight checks",
+    "Policy evaluation against configured YAML",
+    "Receipt generation and verification",
+    "Savings report generation",
+  ]),
+  what_requires_human_action: Object.freeze([
+    "Writing and maintaining policy YAML",
+    "Integrating atf bot protect into bot execution loop",
+    "Reviewing and acting on deny decisions",
+    "Advanced package payment and activation",
+  ]),
+});
+
+// ---------------------------------------------------------------------------
+// Default safe call sequence — frozen, deterministic
+// ---------------------------------------------------------------------------
+
+export const SAFE_CALL_SEQUENCE = Object.freeze([
+  Object.freeze({
+    order: 1,
+    tool: "atf_health",
+    purpose: "Verify ATF CLI or API is reachable",
+    when: "Once at bot startup",
+  }),
+  Object.freeze({
+    order: 2,
+    tool: "atf_bot_preflight",
+    purpose: "Pre-session go/no-go check",
+    when: "Once per session, after health passes",
+  }),
+  Object.freeze({
+    order: 3,
+    tool: "atf_protect_intent",
+    purpose: "Evaluate each DeFi intent against policy",
+    when: "Before every on-chain transaction",
+  }),
+  Object.freeze({
+    order: 4,
+    tool: "atf_tx_explain",
+    purpose: "Explain DENY decisions with remediation",
+    when: "After any DENY or unexpected WARN",
+  }),
+  Object.freeze({
+    order: 5,
+    tool: "atf_verify_receipt",
+    purpose: "Verify receipt integrity",
+    when: "Periodically or when auditing past decisions",
+  }),
+  Object.freeze({
+    order: 6,
+    tool: "atf_report_savings",
+    purpose: "Generate receipt-backed savings report",
+    when: "End of session or daily",
+  }),
+]);
+
+// ---------------------------------------------------------------------------
+// Core evaluation logic — pure, deterministic
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate bot capability signals against the ATF trigger model.
+ *
+ * @param {Record<string, boolean>} signals
+ *   Keys are trigger_id values (e.g. "bot_handles_real_capital").
+ *   Values are boolean: true = trigger condition is met.
+ *   Unknown keys are silently ignored.
+ *   If signals is empty/null/undefined, returns install_needed=false.
+ *
+ * @returns {{
+ *   install_needed: boolean,
+ *   reason_codes: string[],
+ *   matched_triggers: Array<{trigger_id: string, title: string, severity: string, recommendation: string, recommended_tier: string}>,
+ *   highest_severity: string|null,
+ *   recommended_tier: "free_core"|"advanced_bot"|"none",
+ *   recommended_call_sequence: typeof SAFE_CALL_SEQUENCE,
+ *   install_guidance: typeof INSTALL_GUIDANCE,
+ *   config_path: string,
+ *   billing_needed: boolean,
+ *   next_actions: string[],
+ *   severity_message: string,
+ * }}
+ */
+export function evaluateAdoption(signals) {
+  const safeSignals =
+    signals && typeof signals === "object" ? signals : {};
+
+  // Match triggers
+  const matched = [];
+  for (const trigger of TRIGGER_MODEL) {
+    if (safeSignals[trigger.trigger_id] === true) {
+      matched.push(trigger);
+    }
+  }
+
+  if (matched.length === 0) {
+    return {
+      install_needed: false,
+      reason_codes: [],
+      matched_triggers: [],
+      highest_severity: null,
+      recommended_tier: "none",
+      recommended_call_sequence: SAFE_CALL_SEQUENCE,
+      install_guidance: INSTALL_GUIDANCE,
+      config_path: "policy.yaml (when ready)",
+      billing_needed: false,
+      next_actions: [
+        "Monitor for future trigger activation",
+        "Re-evaluate when bot capabilities change",
+      ],
+      severity_message:
+        "ATF adoption optional — monitor for future trigger activation",
+    };
+  }
+
+  // Determine highest severity
+  let highestRank = 0;
+  let highestSeverity = "low";
+  for (const t of matched) {
+    const rank = SEVERITY_RANK[t.severity] ?? 0;
+    if (rank > highestRank) {
+      highestRank = rank;
+      highestSeverity = t.severity;
+    }
+  }
+
+  // Determine recommended tier (advanced_bot wins if any matched trigger recommends it)
+  const needsAdvanced = matched.some(
+    (t) => t.recommended_tier === "advanced_bot",
+  );
+  const recommendedTier = needsAdvanced ? "advanced_bot" : "free_core";
+
+  // Collect unique next_actions from matched triggers
+  const actionSet = new Set();
+  for (const t of matched) {
+    for (const a of t.next_actions) {
+      actionSet.add(a);
+    }
+  }
+
+  // Severity message
+  const severityMessages = {
+    critical: "Immediate ATF adoption strongly recommended",
+    high: "ATF adoption recommended before next production deployment",
+    medium: "ATF adoption recommended for operational maturity",
+    low: "ATF adoption optional — evaluate advanced package when ready",
+  };
+
+  return {
+    install_needed: true,
+    reason_codes: matched.map((t) => t.trigger_id),
+    matched_triggers: matched.map((t) => ({
+      trigger_id: t.trigger_id,
+      title: t.title,
+      severity: t.severity,
+      recommendation: t.recommendation,
+      recommended_tier: t.recommended_tier,
+    })),
+    highest_severity: highestSeverity,
+    recommended_tier: recommendedTier,
+    recommended_call_sequence: SAFE_CALL_SEQUENCE,
+    install_guidance: INSTALL_GUIDANCE,
+    config_path: "policy.yaml (when ready)",
+    billing_needed: recommendedTier === "advanced_bot",
+    next_actions: [...actionSet],
+    severity_message:
+      severityMessages[highestSeverity] ?? severityMessages.low,
+  };
+}

package/src/backend.mjs

@@ -0,0 +1,230 @@
+/**
+ * backend.mjs — Deterministic backend selection for ATF OpenClaw plugin
+ *
+ * Resolves which ATF backend (CLI or API) to use for a given request,
+ * with full diagnostics about preference, availability, and fallback.
+ *
+ * Exports:
+ *   - resolveBackend(cfg, probes)   — pick effective backend + diagnostics
+ *   - probeCliAvailable(cli)        — check CLI reachability
+ *   - probeApiAvailable(baseUrl)    — check API reachability
+ *   - BACKEND_STATUS                — status enum
+ *
+ * Uses ONLY built-in Node modules. No dependencies.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Status enum
+// ---------------------------------------------------------------------------
+
+/** @enum {string} */
+export const BACKEND_STATUS = Object.freeze({
+  OK: "ok",
+  DEGRADED: "degraded",
+  MISCONFIGURED: "misconfigured",
+  UNAVAILABLE: "unavailable",
+});
+
+// ---------------------------------------------------------------------------
+// Probes
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the ATF CLI is reachable and return version info.
+ * Never throws.
+ *
+ * @param {string} cli  CLI command name or path.
+ * @returns {Promise<{available: boolean, version?: string, reason?: string}>}
+ */
+export async function probeCliAvailable(cli) {
+  if (!cli || typeof cli !== "string") {
+    return { available: false, reason: "atfCli not configured" };
+  }
+  try {
+    const { stdout, stderr } = await execFileAsync(cli, ["--version"], {
+      timeout: 10_000,
+      maxBuffer: 1024 * 1024,
+      shell: false,
+    });
+    const version = (stdout ?? "").trim();
+    if (version.length > 0) {
+      return { available: true, version };
+    }
+    return {
+      available: false,
+      reason: `CLI returned empty version: ${(stderr ?? "").trim()}`,
+    };
+  } catch (err) {
+    return {
+      available: false,
+      reason: err?.code === "ENOENT"
+        ? `CLI not found: '${cli}' is not installed or not in PATH`
+        : `CLI probe failed: ${err?.message ?? String(err)}`,
+    };
+  }
+}
+
+/**
+ * Check whether the ATF API is reachable via /health.
+ * Never throws.
+ *
+ * @param {string|null|undefined} baseUrl  ATF API base URL.
+ * @returns {Promise<{available: boolean, status?: number, url?: string, reason?: string}>}
+ */
+export async function probeApiAvailable(baseUrl) {
+  if (!baseUrl || typeof baseUrl !== "string") {
+    return { available: false, reason: "atfBaseUrl not configured" };
+  }
+  try {
+    const res = await fetch(`${baseUrl}/health`, {
+      headers: { "User-Agent": "openclaw-atf-plugin/doctor" },
+      signal: AbortSignal.timeout(5_000),
+    });
+    return {
+      available: res.ok,
+      status: res.status,
+      url: baseUrl,
+      ...(res.ok ? {} : { reason: `HTTP ${res.status}` }),
+    };
+  } catch (err) {
+    return {
+      available: false,
+      url: baseUrl,
+      reason: `API probe failed: ${err?.message ?? String(err)}`,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Backend resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} BackendResolution
+ * @property {string} preferred_backend   What the config says to prefer.
+ * @property {string} effective_backend   What will actually be used.
+ * @property {boolean} fallback_occurred  True if effective != preferred.
+ * @property {string|null} fallback_reason  Why fallback happened, if it did.
+ * @property {{available: boolean, version?: string, reason?: string}} cli
+ * @property {{available: boolean, status?: number, url?: string, reason?: string}} api
+ * @property {string} status              One of BACKEND_STATUS values.
+ * @property {string[]} warnings          Operator-facing warnings.
+ */
+
+/**
+ * Resolve the effective backend with full diagnostics.
+ *
+ * Behavior matrix:
+ *   prefer=cli, CLI available       → effective=cli, status=ok
+ *   prefer=cli, CLI unavailable, API available  → effective=api, status=degraded
+ *   prefer=api, API available       → effective=api, status=ok
+ *   prefer=api, API unavailable, CLI available  → effective=cli, status=degraded
+ *   prefer=api, no atfBaseUrl       → misconfigured
+ *   neither available               → unavailable
+ *
+ * @param {Record<string, unknown>} cfg  Resolved plugin config.
+ * @param {{ cli?: object, api?: object }} [probes]  Optional pre-computed probes.
+ * @returns {Promise<BackendResolution>}
+ */
+export async function resolveBackend(cfg, probes = {}) {
+  const preferred = cfg?.prefer === "api" ? "api" : "cli";
+  const cli = probes.cli ?? await probeCliAvailable(cfg?.atfCli ?? "atf");
+  const api = probes.api ?? await probeApiAvailable(cfg?.atfBaseUrl);
+
+  /** @type {string[]} */
+  const warnings = [];
+  let effective = preferred;
+  let fallbackOccurred = false;
+  let fallbackReason = null;
+  let status = BACKEND_STATUS.OK;
+
+  // Detect misconfiguration: prefer=api but no URL
+  if (preferred === "api" && !cfg?.atfBaseUrl) {
+    warnings.push(
+      "prefer=api but atfBaseUrl is not configured. " +
+      "Set atfBaseUrl in plugin config or switch to prefer=cli.",
+    );
+    status = BACKEND_STATUS.MISCONFIGURED;
+    // Fall back to CLI if available
+    if (cli.available) {
+      effective = "cli";
+      fallbackOccurred = true;
+      fallbackReason = "atfBaseUrl not configured; fell back to CLI";
+    } else {
+      effective = "none";
+      status = BACKEND_STATUS.UNAVAILABLE;
+    }
+    return {
+      preferred_backend: preferred,
+      effective_backend: effective,
+      fallback_occurred: fallbackOccurred,
+      fallback_reason: fallbackReason,
+      cli,
+      api,
+      status,
+      warnings,
+    };
+  }
+
+  if (preferred === "cli") {
+    if (cli.available) {
+      effective = "cli";
+      status = BACKEND_STATUS.OK;
+    } else if (api.available) {
+      effective = "api";
+      fallbackOccurred = true;
+      fallbackReason = `CLI unavailable (${cli.reason ?? "unknown"}); fell back to API`;
+      status = BACKEND_STATUS.DEGRADED;
+      warnings.push(
+        `prefer=cli but CLI unavailable: ${cli.reason ?? "unknown"}. Using API fallback.`,
+      );
+    } else {
+      effective = "none";
+      status = BACKEND_STATUS.UNAVAILABLE;
+      warnings.push(
+        `Both CLI and API are unavailable. CLI: ${cli.reason ?? "unknown"}. API: ${api.reason ?? "unknown"}.`,
+      );
+    }
+  } else {
+    // preferred === "api"
+    if (api.available) {
+      effective = "api";
+      status = BACKEND_STATUS.OK;
+    } else if (cli.available) {
+      effective = "cli";
+      fallbackOccurred = true;
+      fallbackReason = `API unavailable (${api.reason ?? "unknown"}); fell back to CLI`;
+      status = BACKEND_STATUS.DEGRADED;
+      warnings.push(
+        `prefer=api but API unavailable: ${api.reason ?? "unknown"}. Using CLI fallback.`,
+      );
+    } else {
+      effective = "none";
+      status = BACKEND_STATUS.UNAVAILABLE;
+      warnings.push(
+        `Both CLI and API are unavailable. CLI: ${cli.reason ?? "unknown"}. API: ${api.reason ?? "unknown"}.`,
+      );
+    }
+  }
+
+  // Additional warnings
+  if (preferred === "cli" && !cli.available && !api.available) {
+    warnings.push("Install ATF CLI: npm install -g @trucore/atf");
+  }
+
+  return {
+    preferred_backend: preferred,
+    effective_backend: effective,
+    fallback_occurred: fallbackOccurred,
+    fallback_reason: fallbackReason,
+    cli,
+    api,
+    status,
+    warnings,
+  };
+}