clawpowers 1.1.1 → 1.1.2

package/README.md

@@ -394,6 +394,10 @@ Built by [AI Agent Economy](https://github.com/up2itnow0822) — the team behind
 
 We welcome contributions. Unlike some frameworks, we don't dismiss legitimate skill proposals with one-word responses. Open an issue or PR — every submission gets a genuine technical review.
 
+## Patent Notice
+
+**Patent Pending** — The underlying financial infrastructure (agentwallet-sdk, agentpay-mcp) is covered by USPTO provisional patent application filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents."
+
 ## License
 
 MIT

package/bin/clawpowers.js

@@ -25,6 +25,7 @@ const ANALYZE_JS    = path.join(REPO_ROOT, 'runtime', 'feedback', 'analyze.js');
 const STORE_JS      = path.join(REPO_ROOT, 'runtime', 'persistence', 'store.js');
 const COLLECTOR_JS  = path.join(REPO_ROOT, 'runtime', 'metrics', 'collector.js');
 const SESSION_JS    = path.join(REPO_ROOT, 'hooks', 'session-start.js');
+const LEDGER_JS     = path.join(REPO_ROOT, 'runtime', 'payments', 'ledger.js');
 
 /**
  * Prints the top-level command usage to stdout.
@@ -41,6 +42,8 @@ Commands:
   metrics <cmd>      Record or query skill execution metrics
   analyze [opts]     RSI feedback analysis of skill performance
   store <cmd>        Key-value state store operations
+  payments <cmd>     Payment setup, log, and summary commands
+  demo <cmd>         Run interactive demos (e.g. x402 mock merchant)
 
 Examples:
   npx clawpowers init
@@ -50,6 +53,10 @@ Examples:
   npx clawpowers analyze --skill systematic-debugging
   npx clawpowers store set "my:key" "my value"
   npx clawpowers store get "my:key"
+  npx clawpowers payments setup
+  npx clawpowers payments log
+  npx clawpowers payments summary
+  npx clawpowers demo x402
 
 Run 'npx clawpowers <command> help' for command-specific help.`);
 }
@@ -356,6 +363,216 @@ function delegateToNode(script, args) {
   process.exit(result.status || 0);
 }
 
+/**
+ * `clawpowers payments setup` — Interactive wallet activation wizard.
+ *
+ * Guides the user through enabling or configuring the payment subsystem.
+ * Never asks for private keys — those belong in .env.
+ * Reads and writes ~/.clawpowers/config.json (created by init if missing).
+ *
+ * Wizard steps:
+ * 1. Explain that payments are optional
+ * 2. Ask user to choose a mode: disabled / dry run / live
+ * 3. If dry run: update config payments.mode = "dry_run", payments.enabled = true
+ * 4. If live: ask for per_tx_limit and daily_limit, then update config
+ * 5. Confirm where logs are stored
+ */
+function cmdPaymentsSetup() {
+  const readline = require('readline');
+  const CLAWPOWERS_DIR = process.env.CLAWPOWERS_DIR || path.join(os.homedir(), '.clawpowers');
+  const configFile = path.join(CLAWPOWERS_DIR, 'config.json');
+
+  // Load existing config or fall back to defaults
+  let config = {};
+  if (fs.existsSync(configFile)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    } catch (_) {
+      config = {};
+    }
+  }
+  // Ensure payments section exists with safe defaults
+  if (!config.payments) {
+    config.payments = {
+      enabled: false,
+      mode: 'dry_run',
+      per_tx_limit_usd: 0,
+      daily_limit_usd: 0,
+      weekly_limit_usd: 0,
+      allowlist: [],
+      require_approval_above_usd: 0,
+    };
+  }
+
+  const logsPath = path.join(CLAWPOWERS_DIR, 'logs', 'payments.jsonl');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  const ask = (question) => new Promise((resolve) => rl.question(question, resolve));
+
+  async function run() {
+    console.log('');
+    console.log('╔══════════════════════════════════════════════════╗');
+    console.log('║        ClawPowers Payment Setup Wizard          ║');
+    console.log('╚══════════════════════════════════════════════════╝');
+    console.log('');
+    console.log('Payments are optional. ClawPowers works without a wallet.');
+    console.log('When enabled, agents can autonomously pay for premium APIs');
+    console.log('and services using the x402 protocol.');
+    console.log('');
+    console.log('⚠  Private keys belong in .env — this wizard never asks for them.');
+    console.log('');
+    console.log('Choose a mode:');
+    console.log('  [1] Keep disabled  (default — no payments, no wallet required)');
+    console.log('  [2] Enable Dry Run (detect payment gates, log what WOULD happen)');
+    console.log('  [3] Enable Live    (real payments within configured limits)');
+    console.log('');
+
+    const choice = (await ask('Enter choice [1/2/3]: ')).trim();
+
+    if (choice === '1' || choice === '') {
+      config.payments.enabled = false;
+      config.payments.mode = 'dry_run';
+      console.log('');
+      console.log('✓ Payments remain disabled. No wallet required.');
+
+    } else if (choice === '2') {
+      config.payments.enabled = true;
+      config.payments.mode = 'dry_run';
+      console.log('');
+      console.log('✓ Dry Run mode enabled.');
+      console.log('  Agents will detect payment requirements and log what would happen.');
+      console.log('  No funds will move. Review the log after 10+ cycles, then');
+      console.log('  run this wizard again to go live with confidence.');
+
+    } else if (choice === '3') {
+      console.log('');
+      console.log('Live payment mode requires spending limits to protect your wallet.');
+      console.log('');
+
+      const perTxRaw = (await ask('Per-transaction limit (USD, e.g. 0.10): ')).trim();
+      const dailyRaw = (await ask('Daily limit (USD, e.g. 5.00): ')).trim();
+
+      const perTxLimit = parseFloat(perTxRaw) || 0;
+      const dailyLimit = parseFloat(dailyRaw) || 0;
+
+      config.payments.enabled = true;
+      config.payments.mode = 'live';
+      config.payments.per_tx_limit_usd = perTxLimit;
+      config.payments.daily_limit_usd = dailyLimit;
+
+      console.log('');
+      console.log(`✓ Live payments enabled.`);
+      console.log(`  Per-transaction limit: $${perTxLimit.toFixed(2)}`);
+      console.log(`  Daily limit:           $${dailyLimit.toFixed(2)}`);
+      console.log('');
+      console.log('  Add your private key or mnemonic to ~/.clawpowers/.env');
+      console.log('  (never commit this file — it is gitignored by default)');
+
+    } else {
+      console.log('');
+      console.log('Invalid choice. No changes made.');
+      rl.close();
+      return;
+    }
+
+    // Save updated config
+    if (!fs.existsSync(CLAWPOWERS_DIR)) {
+      fs.mkdirSync(CLAWPOWERS_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+
+    console.log('');
+    console.log(`✓ Configuration saved to: ${configFile}`);
+    console.log(`  All payment logs are stored locally at: ${logsPath}`);
+    console.log('');
+    console.log('  Review logs with:  npx clawpowers payments log');
+    console.log('  See summary with:  npx clawpowers payments summary');
+    console.log('');
+
+    rl.close();
+  }
+
+  run().catch((err) => {
+    process.stderr.write(`Error: ${err.message}\n`);
+    rl.close();
+    process.exit(1);
+  });
+}
+
+/**
+ * `clawpowers payments <subcmd> [args]` — Payment ledger and setup commands.
+ *
+ * Subcommands:
+ *   setup   — Interactive payment mode wizard
+ *   log     — Show recent payment decisions
+ *   summary — Show payment totals by skill, chain, outcome
+ *
+ * @param {string[]} args - Remaining argv after 'payments'.
+ */
+function cmdPayments(args) {
+  const [subcmd, ...rest] = args;
+
+  if (!subcmd || subcmd === 'help' || subcmd === '--help' || subcmd === '-h') {
+    console.log(`Usage: clawpowers payments <command> [options]
+
+Commands:
+  setup              Interactive payment mode wizard
+  log [--limit <n>]  Show recent payment decisions (default: last 20)
+  summary            Show totals by skill, chain, and outcome`);
+    return;
+  }
+
+  switch (subcmd) {
+    case 'setup':
+      cmdPaymentsSetup();
+      break;
+    case 'log':
+      requireModule(LEDGER_JS).cmdLog ? requireModule(LEDGER_JS).cmdLog(rest)
+        : delegateToNode(LEDGER_JS, ['log', ...rest]);
+      break;
+    case 'summary':
+      requireModule(LEDGER_JS).cmdSummary ? requireModule(LEDGER_JS).cmdSummary()
+        : delegateToNode(LEDGER_JS, ['summary']);
+      break;
+    default:
+      process.stderr.write(`Unknown payments subcommand: ${subcmd}\n`);
+      process.stderr.write('Run: npx clawpowers payments help\n');
+      process.exit(1);
+  }
+}
+
+/**
+ * `clawpowers demo x402` — Start the x402 mock merchant server for demo purposes.
+ * Delegates to runtime/demo/x402-mock-server.js.
+ *
+ * @param {string[]} args - Remaining argv after 'demo'.
+ */
+function cmdDemo(args) {
+  const [subcmd] = args;
+
+  if (!subcmd || subcmd === 'help' || subcmd === '--help' || subcmd === '-h') {
+    console.log(`Usage: clawpowers demo <command>
+
+Commands:
+  x402   Start the x402 mock merchant server`);
+    return;
+  }
+
+  if (subcmd === 'x402') {
+    const MOCK_SERVER_JS = path.join(REPO_ROOT, 'runtime', 'demo', 'x402-mock-server.js');
+    if (!fs.existsSync(MOCK_SERVER_JS)) {
+      process.stderr.write(`Error: runtime module not found: ${MOCK_SERVER_JS}\n`);
+      process.exit(1);
+    }
+    delegateToNode(MOCK_SERVER_JS, []);
+  } else {
+    process.stderr.write(`Unknown demo subcommand: ${subcmd}\n`);
+    process.stderr.write('Run: npx clawpowers demo help\n');
+    process.exit(1);
+  }
+}
+
 // ============================================================
 // Main dispatch — parse the first positional argument as the command
 // ============================================================
@@ -363,16 +580,18 @@ const [cmd, ...args] = process.argv.slice(2);
 
 try {
   switch (cmd) {
-    case 'init':    cmdInit(); break;
-    case 'status':  cmdStatus(); break;
-    case 'update':  cmdUpdate(); break;
-    case 'inject':  cmdInject(); break;
-    case 'metrics': cmdMetrics(args); break;
-    case 'analyze': cmdAnalyze(args); break;
-    case 'store':   cmdStore(args); break;
+    case 'init':     cmdInit(); break;
+    case 'status':   cmdStatus(); break;
+    case 'update':   cmdUpdate(); break;
+    case 'inject':   cmdInject(); break;
+    case 'metrics':  cmdMetrics(args); break;
+    case 'analyze':  cmdAnalyze(args); break;
+    case 'store':    cmdStore(args); break;
+    case 'payments': cmdPayments(args); break;
+    case 'demo':     cmdDemo(args); break;
     case 'help':
     case '-h':
-    case '--help':  printUsage(); break;
+    case '--help':   printUsage(); break;
     // No command or empty string: show usage and exit 1 (non-zero for scripts)
     case undefined:
     case '':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawpowers",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "The skills framework that actually does something — runtime execution, persistent memory, self-improvement, and autonomous payments for coding agents.",
   "license": "MIT",
   "author": "AI Agent Economy <https://github.com/up2itnow0822>",

package/runtime/demo/x402-mock-server.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// runtime/demo/x402-mock-server.js — x402 Mock Merchant Demo Server
+//
+// Starts a local HTTP server that demonstrates the x402 payment-required flow:
+//   1. GET /api/premium-data without payment header → 402 Payment Required
+//   2. GET /api/premium-data with 'x-payment: mock-proof' header → 200 OK with data
+//
+// This server is for DEMO and DEVELOPMENT ONLY — it does not process real payments.
+//
+// Usage:
+//   node runtime/demo/x402-mock-server.js
+//   npx clawpowers demo x402
+//
+// The server picks a random available port and prints instructions on startup.
+// Press Ctrl+C to stop.
+'use strict';
+
+const http = require('http');
+const os = require('os');
+
+// Track requests for demo visibility
+let requestCount = 0;
+
+/**
+ * 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');
+}
+
+/**
+ * Logs a request to stdout with timestamp and key details.
+ * Allows the demo runner to see exactly what is happening.
+ *
+ * @param {string} method - HTTP method (GET, POST, etc.)
+ * @param {string} url - Request URL path
+ * @param {number} status - Response HTTP status code
+ * @param {string} [note=''] - Optional human-readable note about this request
+ */
+function logRequest(method, url, status, note = '') {
+  const ts = isoTimestamp();
+  const noteStr = note ? ` — ${note}` : '';
+  console.log(`  [${ts}] ${method} ${url} → ${status}${noteStr}`);
+}
+
+/**
+ * Builds the x402 Payment Required response body for the mock merchant.
+ * This mimics the response a real x402-compliant API would return.
+ *
+ * @param {number} port - The port this server is running on (embedded in the resource URL).
+ * @returns {object} x402 payment requirements object.
+ */
+function buildPaymentRequired(port) {
+  return {
+    x402Version: 1,
+    accepts: [
+      {
+        scheme: 'exact',
+        network: 'base-sepolia',
+        maxAmountRequired: '100000',
+        resource: `http://localhost:${port}/api/premium-data`,
+        asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+        payTo: '0xff86829393C6C26A4EC122bE0Cc3E466Ef876AdD',
+      },
+    ],
+    error: 'Payment Required',
+  };
+}
+
+/**
+ * Builds the mock premium data response returned after (simulated) payment.
+ *
+ * @returns {object} Mock API data payload.
+ */
+function buildPremiumData() {
+  return {
+    status: 'ok',
+    data: {
+      market: 'AGENT/USDC',
+      price: '4.20',
+      volume_24h: '1234567.89',
+      change_24h: '+12.3%',
+      source: 'mock-premium-api',
+      paid_with: 'x402',
+      timestamp: isoTimestamp(),
+    },
+    message: 'Payment accepted. Here is your premium data.',
+  };
+}
+
+/**
+ * Main HTTP request handler for the mock x402 merchant.
+ *
+ * Routes:
+ *   GET /api/premium-data  — Returns 402 or 200 depending on x-payment header
+ *   GET /                  — Returns a simple HTML help page
+ *   All others             — Returns 404
+ *
+ * @param {http.IncomingMessage} req - Incoming HTTP request
+ * @param {http.ServerResponse} res - HTTP response object
+ */
+function handleRequest(req, res) {
+  requestCount++;
+  const url = req.url || '/';
+  const method = req.method || 'GET';
+
+  // CORS headers — allow curl and browser requests during demo
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Headers', 'x-payment, content-type');
+
+  if (url === '/api/premium-data' && method === 'GET') {
+    const paymentHeader = req.headers['x-payment'];
+
+    if (!paymentHeader) {
+      // No payment header — return 402 Payment Required with x402 spec body
+      const body = JSON.stringify(buildPaymentRequired(server.address().port), null, 2);
+      res.setHeader('Content-Type', 'application/json');
+      res.writeHead(402);
+      res.end(body);
+      logRequest(method, url, 402, 'No x-payment header — returning payment requirements');
+    } else {
+      // Payment header present — simulate successful payment verification
+      const body = JSON.stringify(buildPremiumData(), null, 2);
+      res.setHeader('Content-Type', 'application/json');
+      res.writeHead(200);
+      res.end(body);
+      logRequest(method, url, 200, `x-payment: ${paymentHeader} — payment accepted, returning data`);
+    }
+
+  } else if (url === '/' && method === 'GET') {
+    // Help page — shows curl examples
+    const port = server.address().port;
+    const body = [
+      '<html><body><pre>',
+      'x402 Mock Merchant Demo',
+      '=======================',
+      '',
+      'Try these curl commands:',
+      '',
+      `# Step 1: Request without payment (returns 402)`,
+      `curl -i http://localhost:${port}/api/premium-data`,
+      '',
+      `# Step 2: Request with payment header (returns 200 + data)`,
+      `curl -i -H "x-payment: mock-proof" http://localhost:${port}/api/premium-data`,
+      '</pre></body></html>',
+    ].join('\n');
+    res.setHeader('Content-Type', 'text/html');
+    res.writeHead(200);
+    res.end(body);
+    logRequest(method, url, 200, 'help page');
+
+  } else {
+    res.setHeader('Content-Type', 'application/json');
+    res.writeHead(404);
+    res.end(JSON.stringify({ error: 'Not Found', path: url }));
+    logRequest(method, url, 404);
+  }
+}
+
+/**
+ * Finds a random available port by binding to port 0 and reading what the OS assigned.
+ * Returns a Promise that resolves to the chosen port number.
+ *
+ * @returns {Promise<number>} Available port number.
+ */
+function getAvailablePort() {
+  return new Promise((resolve, reject) => {
+    const tmp = http.createServer();
+    tmp.listen(0, '127.0.0.1', () => {
+      const port = tmp.address().port;
+      tmp.close(() => resolve(port));
+    });
+    tmp.on('error', reject);
+  });
+}
+
+// The server object is referenced inside handleRequest for the port — declare before use
+/** @type {http.Server} */
+const server = http.createServer(handleRequest);
+
+/**
+ * Main entry point: picks a port, starts the server, and prints instructions.
+ * Waits for Ctrl+C (SIGINT) or SIGTERM to shut down cleanly.
+ */
+async function main() {
+  let port;
+  try {
+    port = await getAvailablePort();
+  } catch (_) {
+    // If dynamic port detection fails, fall back to a fixed high port
+    port = 18402;
+  }
+
+  server.listen(port, '127.0.0.1', () => {
+    console.log('');
+    console.log('╔══════════════════════════════════════════════════════════════╗');
+    console.log('║             x402 Mock Merchant — Demo Server               ║');
+    console.log('╚══════════════════════════════════════════════════════════════╝');
+    console.log('');
+    console.log(`  Mock x402 merchant running on http://localhost:${port}`);
+    console.log('');
+    console.log('  Try:');
+    console.log(`    curl http://localhost:${port}/api/premium-data`);
+    console.log('');
+    console.log('  The server will return 402 (Payment Required) on first request.');
+    console.log('');
+    console.log(`    curl -H 'x-payment: mock-proof' http://localhost:${port}/api/premium-data`);
+    console.log('');
+    console.log("  Send with header 'x-payment: mock-proof' to simulate payment.");
+    console.log('');
+    console.log('  Request log:');
+  });
+
+  // Handle Ctrl+C and process termination signals cleanly
+  const shutdown = () => {
+    console.log('');
+    console.log(`  Shutting down after ${requestCount} request(s). Goodbye.`);
+    server.close(() => process.exit(0));
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((err) => {
+  process.stderr.write(`Error starting mock server: ${err.message}\n`);
+  process.exit(1);
+});

package/runtime/init.js

@@ -13,7 +13,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const VERSION = '1.0.0';
+const VERSION = '1.1.1';
 
 // Runtime root — override with CLAWPOWERS_DIR env var for testing or custom locations
 const CLAWPOWERS_DIR = process.env.CLAWPOWERS_DIR || path.join(os.homedir(), '.clawpowers');
@@ -96,6 +96,43 @@ function writeReadme() {
   }
 }
 
+/**
+ * Default configuration written to ~/.clawpowers/config.json on first init.
+ * Users can edit this file to enable payments, telemetry, or change skill behavior.
+ * Never overwritten once created — user settings are always preserved.
+ */
+const DEFAULT_CONFIG = {
+  version: VERSION,
+  payments: {
+    enabled: false,
+    mode: 'dry_run',
+    per_tx_limit_usd: 0,
+    daily_limit_usd: 0,
+    weekly_limit_usd: 0,
+    allowlist: [],
+    require_approval_above_usd: 0,
+  },
+  telemetry: {
+    enabled: false,
+  },
+  skills: {
+    auto_load: true,
+  },
+};
+
+/**
+ * Writes the default config.json to CLAWPOWERS_DIR on first initialization.
+ * No-op if config.json already exists — user settings are always preserved.
+ * The config file is written with mode 0o600 (owner read/write only).
+ */
+function writeConfig() {
+  const configFile = path.join(CLAWPOWERS_DIR, 'config.json');
+  if (!fs.existsSync(configFile)) {
+    const content = JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n';
+    fs.writeFileSync(configFile, content, { mode: 0o600 });
+  }
+}
+
 /**
  * Updates the version stamp in .version after initialization.
  * Currently a no-op placeholder for actual schema migrations; the version
@@ -139,6 +176,7 @@ function main() {
   const created = createStructure();
   writeVersion();
   writeReadme();
+  writeConfig();
 
   // Only run migrations when .version exists (i.e., after writeVersion)
   if (fs.existsSync(path.join(CLAWPOWERS_DIR, '.version'))) {
@@ -169,4 +207,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { main, CLAWPOWERS_DIR, VERSION };
+module.exports = { main, CLAWPOWERS_DIR, VERSION, writeConfig, DEFAULT_CONFIG };

package/runtime/init.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 
 # Runtime root — override with CLAWPOWERS_DIR env var for testing or custom locations
 CLAWPOWERS_DIR="${CLAWPOWERS_DIR:-$HOME/.clawpowers}"
-VERSION="1.0.0"
+VERSION="1.1.1"
 
 ## === Directory Setup ===
 
@@ -93,6 +93,38 @@ EOF
   fi
 }
 
+## === Config File ===
+
+# Writes the default config.json on first initialization.
+# No-op if config.json already exists — user settings are always preserved.
+# The file is written with mode 600 (owner read/write only).
+write_config() {
+  local config_file="$CLAWPOWERS_DIR/config.json"
+  if [[ ! -f "$config_file" ]]; then
+    cat > "$config_file" << EOF
+{
+  "version": "$VERSION",
+  "payments": {
+    "enabled": false,
+    "mode": "dry_run",
+    "per_tx_limit_usd": 0,
+    "daily_limit_usd": 0,
+    "weekly_limit_usd": 0,
+    "allowlist": [],
+    "require_approval_above_usd": 0
+  },
+  "telemetry": {
+    "enabled": false
+  },
+  "skills": {
+    "auto_load": true
+  }
+}
+EOF
+    chmod 600 "$config_file"
+  fi
+}
+
 ## === Migrations ===
 
 # Updates the version stamp in .version to the current version.
@@ -120,6 +152,7 @@ main() {
 
   write_version
   write_readme
+  write_config
 
   # Migrations only apply when the version file exists (guaranteed after write_version)
   if [[ -f "$CLAWPOWERS_DIR/.version" ]]; then