clawpowers 1.1.4 → 2.2.0

package/runtime/payments/ledger.js

@@ -1,305 +0,0 @@
-#!/usr/bin/env node
-// runtime/payments/ledger.js — Payment decision ledger
-//
-// Records every payment decision (approve, deny, dry-run) to a persistent
-// JSONL log at ~/.clawpowers/logs/payments.jsonl. Provides CLI commands to
-// review recent decisions and summarize spending by skill, chain, and outcome.
-//
-// Usage (CLI):
-//   node ledger.js log [--limit <n>]
-//   node ledger.js summary
-//
-// Usage (module):
-//   const { logPaymentDecision, getPaymentSummary } = require('./ledger');
-//   await logPaymentDecision({ skill: 'agent-payments', url: '...', ... });
-//   const summary = getPaymentSummary();
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-// Logs directory — contains payments.jsonl and other audit logs
-const LOGS_DIR = path.join(
-  process.env.CLAWPOWERS_DIR || path.join(os.homedir(), '.clawpowers'),
-  'logs'
-);
-
-/** Absolute path to the payment ledger file. */
-const LEDGER_FILE = path.join(LOGS_DIR, 'payments.jsonl');
-
-/**
- * Creates the logs directory if it doesn't already exist.
- * Mode 0o700 restricts access to the current user only.
- */
-function ensureLogsDir() {
-  if (!fs.existsSync(LOGS_DIR)) {
-    fs.mkdirSync(LOGS_DIR, { recursive: true, mode: 0o700 });
-  }
-}
-
-/**
- * Returns an ISO 8601 timestamp without milliseconds.
- *
- * @returns {string} e.g. "2026-03-22T21:42:00Z"
- */
-function isoTimestamp() {
-  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-}
-
-/**
- * Records a payment decision to the JSONL ledger.
- *
- * Each entry captures what happened at a payment gate: the skill that
- * encountered the payment requirement, the URL that required payment,
- * the amount and asset, the policy evaluation result, and whether payment
- * would have been (or was) made.
- *
- * The entry is appended as a single JSON line to `~/.clawpowers/logs/payments.jsonl`.
- * The file is created if it doesn't exist.
- *
- * @param {object} entry - Payment decision details.
- * @param {string} [entry.skill='unknown'] - Skill that triggered the payment gate.
- * @param {string} [entry.type='decision'] - Entry type: 'decision' | 'payment' | 'denial'.
- * @param {string} [entry.url=''] - Resource URL that required payment.
- * @param {string} [entry.required_amount='0'] - Amount required (in smallest asset unit).
- * @param {string} [entry.asset='USDC'] - Asset symbol (e.g. 'USDC', 'ETH').
- * @param {string} [entry.chain='base'] - Chain name (e.g. 'base', 'base-sepolia').
- * @param {string} [entry.policy_result='dry_run'] - Policy outcome: 'dry_run' | 'approved' | 'denied' | 'disabled'.
- * @param {string} [entry.reason=''] - Human-readable reason for the policy result.
- * @param {boolean} [entry.would_have_paid=false] - Whether payment would have succeeded if live.
- * @returns {object} The complete entry as written to the ledger (including timestamp).
- */
-function logPaymentDecision(entry) {
-  ensureLogsDir();
-
-  /** @type {object} Full ledger record with timestamp and defaults applied. */
-  const record = {
-    timestamp: isoTimestamp(),
-    skill: entry.skill || 'unknown',
-    type: entry.type || 'decision',
-    url: entry.url || '',
-    required_amount: entry.required_amount || '0',
-    asset: entry.asset || 'USDC',
-    chain: entry.chain || 'base',
-    policy_result: entry.policy_result || 'dry_run',
-    reason: entry.reason || '',
-    would_have_paid: Boolean(entry.would_have_paid),
-  };
-
-  // Append as a single JSON line — safe for concurrent appends
-  const line = JSON.stringify(record) + '\n';
-  fs.appendFileSync(LEDGER_FILE, line);
-  try { fs.chmodSync(LEDGER_FILE, 0o600); } catch (_) { /* non-fatal on Windows */ }
-
-  return record;
-}
-
-/**
- * Reads all payment decision records from the ledger.
- * Malformed JSON lines are silently skipped.
- *
- * @returns {object[]} Array of parsed ledger records in chronological order.
- */
-function loadLedger() {
-  if (!fs.existsSync(LEDGER_FILE)) return [];
-
-  const content = fs.readFileSync(LEDGER_FILE, 'utf8');
-  const records = [];
-  for (const line of content.split('\n')) {
-    if (!line.trim()) continue;
-    try {
-      records.push(JSON.parse(line));
-    } catch (_) {
-      // Skip malformed lines — don't crash on a single bad record
-    }
-  }
-  return records;
-}
-
-/**
- * Computes a payment summary aggregated by skill, chain, and policy outcome.
- *
- * Returns totals broken down by:
- * - Skill name: which skills hit payment gates most often
- * - Chain: which networks were targeted for payment
- * - Outcome: how many were dry_run vs approved vs denied vs disabled
- *
- * @returns {{
- *   total: number,
- *   by_skill: Object.<string, number>,
- *   by_chain: Object.<string, number>,
- *   by_outcome: Object.<string, number>,
- *   would_have_paid: number,
- *   records: object[]
- * }} Aggregated summary object.
- */
-function getPaymentSummary() {
-  const records = loadLedger();
-
-  /** @type {Object.<string, number>} Count per skill name. */
-  const by_skill = {};
-  /** @type {Object.<string, number>} Count per chain name. */
-  const by_chain = {};
-  /** @type {Object.<string, number>} Count per policy_result value. */
-  const by_outcome = {};
-  let would_have_paid = 0;
-
-  for (const r of records) {
-    // Tally by skill
-    by_skill[r.skill] = (by_skill[r.skill] || 0) + 1;
-    // Tally by chain
-    by_chain[r.chain] = (by_chain[r.chain] || 0) + 1;
-    // Tally by outcome
-    by_outcome[r.policy_result] = (by_outcome[r.policy_result] || 0) + 1;
-    // Count would-have-paid scenarios (dry-run hits)
-    if (r.would_have_paid) would_have_paid++;
-  }
-
-  return {
-    total: records.length,
-    by_skill,
-    by_chain,
-    by_outcome,
-    would_have_paid,
-    records,
-  };
-}
-
-/**
- * `log` CLI command — prints recent payment decisions to stdout.
- * Defaults to the last 20 records. Use --limit to change.
- *
- * @param {string[]} argv - Arguments after 'log'.
- */
-function cmdLog(argv) {
-  // Parse optional --limit flag
-  let limit = 20;
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === '--limit' && argv[i + 1]) {
-      limit = parseInt(argv[i + 1], 10);
-      i++;
-    }
-  }
-
-  const records = loadLedger();
-  if (records.length === 0) {
-    console.log('No payment decisions recorded yet.');
-    console.log(`Ledger location: ${LEDGER_FILE}`);
-    return;
-  }
-
-  const slice = records.slice(Math.max(0, records.length - limit));
-  console.log(`Recent payment decisions (last ${slice.length} of ${records.length}):`);
-  console.log('');
-  for (const r of slice) {
-    const paid = r.would_have_paid ? '[would pay]' : '[would skip]';
-    console.log(`  ${r.timestamp} | ${r.skill} | ${r.policy_result} ${paid}`);
-    if (r.url) console.log(`    URL: ${r.url}`);
-    if (r.required_amount !== '0') {
-      console.log(`    Amount: ${r.required_amount} ${r.asset} on ${r.chain}`);
-    }
-    if (r.reason) console.log(`    Reason: ${r.reason}`);
-    console.log('');
-  }
-}
-
-/**
- * `summary` CLI command — prints aggregated payment totals to stdout.
- * Shows totals by skill, chain, and outcome.
- */
-function cmdSummary() {
-  const summary = getPaymentSummary();
-
-  if (summary.total === 0) {
-    console.log('No payment decisions recorded yet.');
-    console.log(`Ledger location: ${LEDGER_FILE}`);
-    return;
-  }
-
-  console.log(`Payment Decision Summary`);
-  console.log(`========================`);
-  console.log(`Total decisions: ${summary.total}`);
-  console.log(`Would have paid: ${summary.would_have_paid}`);
-  console.log('');
-
-  console.log('By skill:');
-  for (const [skill, count] of Object.entries(summary.by_skill).sort()) {
-    console.log(`  ${skill}: ${count}`);
-  }
-  console.log('');
-
-  console.log('By chain:');
-  for (const [chain, count] of Object.entries(summary.by_chain).sort()) {
-    console.log(`  ${chain}: ${count}`);
-  }
-  console.log('');
-
-  console.log('By outcome:');
-  for (const [outcome, count] of Object.entries(summary.by_outcome).sort()) {
-    const pct = Math.round(count / summary.total * 100);
-    console.log(`  ${outcome}: ${count} (${pct}%)`);
-  }
-}
-
-/**
- * Prints usage information for the ledger CLI to stdout.
- */
-function printUsage() {
-  console.log(`Usage: ledger.js <command> [options]
-
-Commands:
-  log [--limit <n>]   Show recent payment decisions (default: last 20)
-  summary             Show totals by skill, chain, and outcome
-
-Ledger file: ~/.clawpowers/logs/payments.jsonl
-
-Examples:
-  ledger.js log
-  ledger.js log --limit 50
-  ledger.js summary`);
-}
-
-/**
- * CLI dispatch — routes argv to the appropriate command.
- *
- * @param {string[]} argv - Argument array (typically process.argv.slice(2)).
- */
-function main(argv) {
-  const [cmd, ...rest] = argv;
-
-  switch (cmd) {
-    case 'log':
-      cmdLog(rest);
-      break;
-    case 'summary':
-      cmdSummary();
-      break;
-    case 'help':
-    case '-h':
-    case '--help':
-      printUsage();
-      break;
-    case undefined:
-    case '':
-      printUsage();
-      process.exit(1);
-      break;
-    default:
-      process.stderr.write(`Unknown command: ${cmd}\n`);
-      printUsage();
-      process.exit(1);
-  }
-}
-
-// Guard: only run CLI dispatch when invoked directly, not when require()'d
-if (require.main === module) {
-  try {
-    main(process.argv.slice(2));
-  } catch (err) {
-    process.stderr.write(`Error: ${err.message}\n`);
-    process.exit(1);
-  }
-}
-
-module.exports = { logPaymentDecision, getPaymentSummary, LEDGER_FILE, LOGS_DIR };

package/runtime/payments/ledger.sh

@@ -1,262 +0,0 @@
-#!/usr/bin/env bash
-# runtime/payments/ledger.sh — Payment decision ledger (bash version)
-#
-# Records payment decisions to ~/.clawpowers/logs/payments.jsonl.
-# Provides CLI commands to review recent decisions and summarize spending.
-#
-# Usage:
-#   bash ledger.sh log [--limit <n>]
-#   bash ledger.sh summary
-#   bash ledger.sh record --skill <name> --url <url> --amount <amt> \
-#                         --asset <asset> --chain <chain> \
-#                         --policy <result> --reason <text> [--would-pay]
-set -euo pipefail
-
-# Runtime root — override with CLAWPOWERS_DIR for testing
-CLAWPOWERS_DIR="${CLAWPOWERS_DIR:-$HOME/.clawpowers}"
-LOGS_DIR="$CLAWPOWERS_DIR/logs"
-LEDGER_FILE="$LOGS_DIR/payments.jsonl"
-
-## === Helpers ===
-
-# Ensures the logs directory exists with correct permissions.
-ensure_logs_dir() {
-  if [[ ! -d "$LOGS_DIR" ]]; then
-    mkdir -p "$LOGS_DIR"
-    chmod 700 "$LOGS_DIR"
-  fi
-}
-
-# Returns an ISO 8601 timestamp (seconds precision).
-iso_timestamp() {
-  date -u +"%Y-%m-%dT%H:%M:%SZ"
-}
-
-# Escapes a string for safe embedding in a JSON value.
-# Handles backslash, double-quote, and common control characters.
-json_escape() {
-  local s="$1"
-  s="${s//\\/\\\\}"   # backslash
-  s="${s//\"/\\\"}"   # double quote
-  s="${s//$'\t'/\\t}" # tab
-  s="${s//$'\n'/\\n}" # newline
-  printf '%s' "$s"
-}
-
-## === record command ===
-
-# Appends a single payment decision JSON line to the ledger.
-#
-# Options:
-#   --skill <name>    Skill that triggered the payment gate
-#   --type <type>     Entry type: decision | payment | denial (default: decision)
-#   --url <url>       Resource URL that required payment
-#   --amount <n>      Required amount in smallest unit (default: 0)
-#   --asset <sym>     Asset symbol: USDC, ETH, etc. (default: USDC)
-#   --chain <name>    Chain name: base, base-sepolia, etc. (default: base)
-#   --policy <result> Policy outcome: dry_run | approved | denied | disabled
-#   --reason <text>   Human-readable reason for the policy result
-#   --would-pay       Flag: set would_have_paid=true
-cmd_record() {
-  local skill="unknown"
-  local type="decision"
-  local url=""
-  local amount="0"
-  local asset="USDC"
-  local chain="base"
-  local policy="dry_run"
-  local reason=""
-  local would_pay="false"
-
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --skill)   skill="$2"; shift 2 ;;
-      --type)    type="$2"; shift 2 ;;
-      --url)     url="$2"; shift 2 ;;
-      --amount)  amount="$2"; shift 2 ;;
-      --asset)   asset="$2"; shift 2 ;;
-      --chain)   chain="$2"; shift 2 ;;
-      --policy)  policy="$2"; shift 2 ;;
-      --reason)  reason="$2"; shift 2 ;;
-      --would-pay) would_pay="true"; shift ;;
-      *) echo "Unknown option: $1" >&2; exit 1 ;;
-    esac
-  done
-
-  ensure_logs_dir
-
-  local ts
-  ts=$(iso_timestamp)
-
-  # Build the JSON line manually (no jq dependency required)
-  local line
-  line="{\"timestamp\":\"$(json_escape "$ts")\","
-  line+="\"skill\":\"$(json_escape "$skill")\","
-  line+="\"type\":\"$(json_escape "$type")\","
-  line+="\"url\":\"$(json_escape "$url")\","
-  line+="\"required_amount\":\"$(json_escape "$amount")\","
-  line+="\"asset\":\"$(json_escape "$asset")\","
-  line+="\"chain\":\"$(json_escape "$chain")\","
-  line+="\"policy_result\":\"$(json_escape "$policy")\","
-  line+="\"reason\":\"$(json_escape "$reason")\","
-  line+="\"would_have_paid\":$would_pay}"
-
-  echo "$line" >> "$LEDGER_FILE"
-  chmod 600 "$LEDGER_FILE" 2>/dev/null || true
-
-  echo "Recorded: $skill → $policy ($(basename "$LEDGER_FILE"))"
-}
-
-## === log command ===
-
-# Shows recent payment decisions from the ledger.
-#
-# Options:
-#   --limit <n>   Maximum records to show (default: 20)
-cmd_log() {
-  local limit=20
-
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --limit) limit="$2"; shift 2 ;;
-      *) echo "Unknown option: $1" >&2; exit 1 ;;
-    esac
-  done
-
-  if [[ ! -f "$LEDGER_FILE" ]]; then
-    echo "No payment decisions recorded yet."
-    echo "Ledger location: $LEDGER_FILE"
-    return
-  fi
-
-  local total
-  total=$(wc -l < "$LEDGER_FILE" | tr -d ' ')
-
-  if [[ "$total" -eq 0 ]]; then
-    echo "No payment decisions recorded yet."
-    return
-  fi
-
-  echo "Recent payment decisions (last $limit of $total):"
-  echo ""
-
-  # tail the last N lines and pretty-print each JSON record
-  tail -n "$limit" "$LEDGER_FILE" | while IFS= read -r line; do
-    [[ -z "$line" ]] && continue
-
-    # Extract fields using basic shell tools (no jq dependency)
-    local ts skill policy would_pay url amount asset chain reason
-    ts=$(echo "$line" | grep -o '"timestamp":"[^"]*"' | cut -d'"' -f4)
-    skill=$(echo "$line" | grep -o '"skill":"[^"]*"' | cut -d'"' -f4)
-    policy=$(echo "$line" | grep -o '"policy_result":"[^"]*"' | cut -d'"' -f4)
-    would_pay=$(echo "$line" | grep -o '"would_have_paid":[a-z]*' | cut -d: -f2)
-    url=$(echo "$line" | grep -o '"url":"[^"]*"' | cut -d'"' -f4)
-    amount=$(echo "$line" | grep -o '"required_amount":"[^"]*"' | cut -d'"' -f4)
-    asset=$(echo "$line" | grep -o '"asset":"[^"]*"' | cut -d'"' -f4)
-    chain=$(echo "$line" | grep -o '"chain":"[^"]*"' | cut -d'"' -f4)
-    reason=$(echo "$line" | grep -o '"reason":"[^"]*"' | cut -d'"' -f4)
-
-    local paid_label="[would skip]"
-    [[ "$would_pay" == "true" ]] && paid_label="[would pay]"
-
-    echo "  $ts | $skill | $policy $paid_label"
-    [[ -n "$url" ]] && echo "    URL: $url"
-    [[ "$amount" != "0" ]] && echo "    Amount: $amount $asset on $chain"
-    [[ -n "$reason" ]] && echo "    Reason: $reason"
-    echo ""
-  done
-}
-
-## === summary command ===
-
-# Shows aggregated payment totals by skill, chain, and outcome.
-cmd_summary() {
-  if [[ ! -f "$LEDGER_FILE" ]]; then
-    echo "No payment decisions recorded yet."
-    echo "Ledger location: $LEDGER_FILE"
-    return
-  fi
-
-  local total
-  total=$(grep -c '.' "$LEDGER_FILE" 2>/dev/null || echo 0)
-
-  if [[ "$total" -eq 0 ]]; then
-    echo "No payment decisions recorded yet."
-    return
-  fi
-
-  local would_have_paid
-  would_have_paid=$(grep -c '"would_have_paid":true' "$LEDGER_FILE" 2>/dev/null || echo 0)
-
-  echo "Payment Decision Summary"
-  echo "========================"
-  echo "Total decisions: $total"
-  echo "Would have paid: $would_have_paid"
-  echo ""
-
-  echo "By skill:"
-  grep -o '"skill":"[^"]*"' "$LEDGER_FILE" | \
-    cut -d'"' -f4 | sort | uniq -c | sort -rn | \
-    while read -r count skill; do echo "  $skill: $count"; done
-  echo ""
-
-  echo "By chain:"
-  grep -o '"chain":"[^"]*"' "$LEDGER_FILE" | \
-    cut -d'"' -f4 | sort | uniq -c | sort -rn | \
-    while read -r count chain; do echo "  $chain: $count"; done
-  echo ""
-
-  echo "By outcome:"
-  grep -o '"policy_result":"[^"]*"' "$LEDGER_FILE" | \
-    cut -d'"' -f4 | sort | uniq -c | sort -rn | \
-    while read -r count outcome; do echo "  $outcome: $count"; done
-}
-
-## === usage ===
-
-print_usage() {
-  echo "Usage: ledger.sh <command> [options]"
-  echo ""
-  echo "Commands:"
-  echo "  log [--limit <n>]   Show recent payment decisions (default: last 20)"
-  echo "  summary             Show totals by skill, chain, and outcome"
-  echo "  record [options]    Record a payment decision"
-  echo ""
-  echo "record options:"
-  echo "  --skill <name>      Skill name (default: unknown)"
-  echo "  --type <type>       decision | payment | denial (default: decision)"
-  echo "  --url <url>         Resource URL"
-  echo "  --amount <n>        Required amount"
-  echo "  --asset <sym>       Asset symbol (default: USDC)"
-  echo "  --chain <name>      Chain name (default: base)"
-  echo "  --policy <result>   dry_run | approved | denied | disabled"
-  echo "  --reason <text>     Reason for policy result"
-  echo "  --would-pay         Set would_have_paid=true"
-  echo ""
-  echo "Ledger file: ~/.clawpowers/logs/payments.jsonl"
-}
-
-## === main dispatch ===
-
-main() {
-  local cmd="${1:-}"
-  shift || true
-
-  case "$cmd" in
-    log)     cmd_log "$@" ;;
-    summary) cmd_summary "$@" ;;
-    record)  cmd_record "$@" ;;
-    help|-h|--help) print_usage ;;
-    "")
-      print_usage
-      exit 1
-      ;;
-    *)
-      echo "Unknown command: $cmd" >&2
-      print_usage >&2
-      exit 1
-      ;;
-  esac
-}
-
-main "$@"