clawpowers 1.1.2 → 1.1.4

package/bin/clawpowers.js

@@ -9,7 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync, spawnSync } = require('child_process');
+const { spawnSync } = require('child_process');
 
 // __dirname is the bin/ directory; repo root is one level up
 const SCRIPT_DIR = __dirname;
@@ -107,19 +107,35 @@ function cmdStatus() {
  */
 function cmdUpdate() {
   const repoUrl = 'https://github.com/up2itnow0822/clawpowers';
-  const result = spawnSync('git', ['-C', REPO_ROOT, 'pull', '--ff-only', 'origin', 'main'], {
-    stdio: 'inherit',
-    // On Windows, git must be launched through the shell so PATH is resolved
-    shell: os.platform() === 'win32',
-  });
 
-  if (result.error) {
-    // git binary not found or OS-level spawn error
-    console.log(`git not found or failed. Visit ${repoUrl} to update manually.`);
-  } else if (result.status !== 0) {
-    console.log(`Warning: could not auto-update. Visit ${repoUrl} for latest.`);
+  // Check if we're in a git repo (git clone install) or npm install
+  const gitDir = path.join(REPO_ROOT, '.git');
+  const isGitInstall = fs.existsSync(gitDir);
+
+  if (isGitInstall) {
+    // Git install: pull latest
+    const result = spawnSync('git', ['-C', REPO_ROOT, 'pull', '--ff-only', 'origin', 'main'], {
+      stdio: 'inherit',
+      shell: os.platform() === 'win32',
+    });
+
+    if (result.error) {
+      console.log(`git not found or failed. Visit ${repoUrl} to update manually.`);
+    } else if (result.status !== 0) {
+      console.log(`Warning: could not auto-update. Visit ${repoUrl} for latest.`);
+    } else {
+      console.log('Updated to latest version.');
+    }
   } else {
-    console.log('Pulling latest skill definitions...');
+    // npm/npx install: instruct user to reinstall via npm
+    console.log('ClawPowers was installed via npm. To update:');
+    console.log('');
+    console.log('  npx clawpowers@latest init');
+    console.log('');
+    console.log('This will update the CLI and re-initialize the runtime');
+    console.log('(your existing state, metrics, and config are preserved).');
+    console.log('');
+    console.log(`Or visit: ${repoUrl}`);
   }
 }
 
@@ -146,7 +162,7 @@ function cmdInject() {
  * @param {string[]} args - Remaining argv after 'metrics'.
  */
 function cmdMetrics(args) {
-  const collector = requireModule(COLLECTOR_JS);
+  const _collector = requireModule(COLLECTOR_JS);
   const [subcmd, ...rest] = args;
 
   // No subcommand or explicit help request: print metrics-specific usage

package/docs/quickstart-first-transaction.md

@@ -0,0 +1,204 @@
+# 5-Minute First Transaction
+
+Get your AI agent sending real (testnet) transactions in under 5 minutes.
+Two paths — pick the one that matches your stack.
+
+> **Testnet only.** Both paths use **Base Sepolia** so no real money moves.
+> Switch `CHAIN_NAME=base` when you're ready for mainnet.
+
+---
+
+## Prerequisites
+
+1. **Testnet wallet** — any EOA private key (generate one with `cast wallet new` from Foundry, or MetaMask)
+2. **Deployed AgentAccountV2** — run `npx clawpowers payments setup` for the interactive wizard
+3. **Base Sepolia ETH (gas)** — free from the [Coinbase Base Sepolia Faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet)
+
+---
+
+## .env Setup
+
+Create a `.env` file (never commit this):
+
+```bash
+# .env — agent wallet config
+AGENT_PRIVATE_KEY=0x...       # EOA signing key (32-byte hex)
+AGENT_WALLET_ADDRESS=0x...    # AgentAccountV2 contract address
+CHAIN_NAME=base-sepolia       # Use Base Sepolia for testing
+RPC_URL=https://sepolia.base.org
+
+# Spending limits (USDC, 6 decimals)
+SPEND_LIMIT_PER_TX=1.00       # Max USDC per single transaction
+SPEND_LIMIT_DAILY=10.00       # Max USDC per 24-hour period
+```
+
+---
+
+## Path A: JavaScript (agentwallet-sdk direct)
+
+**Under 10 lines.** Uses the `walletFromEnv()` convenience wrapper so there's
+no viem boilerplate.
+
+```bash
+npm install agentwallet-sdk dotenv
+```
+
+```javascript
+// first-tx.mjs
+import 'dotenv/config';
+import { walletFromEnv, setPolicyFromEnv, agentExecute } from 'agentwallet-sdk';
+
+const wallet = await walletFromEnv();           // reads AGENT_PRIVATE_KEY + AGENT_WALLET_ADDRESS
+await setPolicyFromEnv(wallet);                 // applies SPEND_LIMIT_PER_TX + SPEND_LIMIT_DAILY
+
+const result = await agentExecute(wallet, {
+  to: '0x000000000000000000000000000000000000dEaD', // burn address (safe test target)
+  value: 1n,                                         // 1 wei — near-zero cost
+});
+
+console.log(`✅ txHash: ${result.txHash}`);
+console.log(`   executed immediately: ${result.executed}`);
+```
+
+```bash
+node first-tx.mjs
+```
+
+**Expected output:**
+```
+✅ txHash: 0x3a7f...c9e2
+   executed immediately: true
+```
+
+> If `executed: false` — the transaction was queued for owner approval because
+> the amount exceeded your spend policy. Approve it with:
+> ```bash
+> node -e "
+> import('agentwallet-sdk').then(async ({ walletFromEnv, getPendingApprovals, approveTransaction }) => {
+>   const w = walletFromEnv();
+>   const pending = await getPendingApprovals(w);
+>   if (pending.length > 0) await approveTransaction(w, pending[0].txId);
+>   console.log('Approved');
+> });
+> "
+> ```
+
+### What just happened
+
+1. `walletFromEnv()` read your private key from `AGENT_PRIVATE_KEY`, connected
+   to Base Sepolia via `RPC_URL`, and instantiated the `AgentAccountV2` smart
+   wallet at `AGENT_WALLET_ADDRESS`.
+2. `setPolicyFromEnv()` wrote a spend policy on-chain: USDC transfers up to
+   `SPEND_LIMIT_PER_TX` per tx and `SPEND_LIMIT_DAILY` per day execute
+   autonomously. Anything above is queued.
+3. `agentExecute()` called `agentExecute()` on the smart contract, which checked
+   the native ETH policy and sent 1 wei to the burn address.
+4. The tx hash was returned immediately — you can verify it on
+   View on [Base Sepolia Explorer](https://sepolia.basescan.org/tx/{txHash}).
+
+---
+
+## Path B: Python (via agentpay-mcp over MCP)
+
+**Under 15 lines.** Uses the official `mcp` Python SDK to connect to the
+`agentpay-mcp` server and call `send_payment` over the Model Context Protocol.
+
+```bash
+pip install mcp python-dotenv
+npx clawpowers mcp start   # starts agentpay-mcp on stdio or a local port
+```
+
+```python
+# first_tx.py
+import asyncio
+import os
+from dotenv import load_dotenv
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+load_dotenv()
+
+async def main():
+    server = StdioServerParameters(
+        command="npx",
+        args=["agentpay-mcp"],
+        env={**os.environ},     # passes AGENT_PRIVATE_KEY, AGENT_WALLET_ADDRESS, etc.
+    )
+    async with stdio_client(server) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            result = await session.call_tool("send_payment", {
+                "to": "0x000000000000000000000000000000000000dEaD",
+                "amount": "0.001",          # USDC
+                "asset": "USDC",
+                "chain": "base-sepolia",
+                "reason": "first transaction test",
+            })
+            print(f"✅ txHash: {result.content[0].text}")
+
+asyncio.run(main())
+```
+
+```bash
+python first_tx.py
+```
+
+**Expected output:**
+```
+✅ txHash: 0x8b2d...f410
+```
+
+### What just happened
+
+1. `stdio_client` spawned `agentpay-mcp` as a subprocess — the MCP server
+   loaded your `.env` credentials and connected to Base Sepolia.
+2. `session.call_tool("send_payment", ...)` sent an MCP tool call over stdio,
+   which the server translated into an `agentTransferToken()` call on your
+   `AgentAccountV2` smart wallet.
+3. The server returned the transaction hash, which you can verify at
+   View on [Base Sepolia Explorer](https://sepolia.basescan.org).
+
+> **Python + MCP** is ideal when your agent framework is Python-based
+> (LangChain, AutoGen, CrewAI) and you want to avoid writing viem/TypeScript.
+> The MCP server handles all wallet logic; your Python code just calls tools.
+
+---
+
+## Verify Your Transaction
+
+Both paths produce a `txHash`. Verify on-chain:
+
+```bash
+# Quick verification via cast (Foundry)
+cast tx $TX_HASH --rpc-url https://sepolia.base.org
+
+# Or open in browser
+echo "https://sepolia.basescan.org/tx/$TX_HASH"
+```
+
+---
+
+## Next Steps
+
+| Goal | Resource |
+|------|----------|
+| Set up x402 automatic payments | `skills/agent-payments/SKILL.md` |
+| Enable premium enrichment in prospecting | `skills/prospecting/SKILL.md` → "Premium Enrichment" section |
+| Post a task bounty for another agent | `skills/agent-bounties/SKILL.md` |
+| Review payment history | `npx clawpowers payments log` |
+| Configure spending limits interactively | `npx clawpowers payments setup` (setup wizard) |
+| Demo — see the full x402 flow in 60s | `runtime/demo/README.md` |
+
+---
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `AGENT_PRIVATE_KEY environment variable is required` | Check your `.env` file exists and is loaded |
+| `Unsupported chain: base-sepolia` | Ensure `agentwallet-sdk` is v0.3+ |
+| `executed: false` (queued) | Amount > spend policy; lower `SPEND_LIMIT_PER_TX` or approve manually |
+| `insufficient funds` | Get Base Sepolia ETH from the faucet link above |
+| `nonce too low` | Another tx is pending; wait for confirmation or reset nonce |
+| MCP: `spawn npx ENOENT` | Run `npm install -g agentpay-mcp` or use `npx --yes` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawpowers",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "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>",
@@ -30,7 +30,8 @@
   },
   "scripts": {
     "init": "node bin/clawpowers.js init",
-    "test": "bash tests/run_all.sh"
+    "test": "bash tests/run_all.sh",
+    "lint": "eslint bin/ runtime/"
   },
   "files": [
     "bin/",
@@ -51,5 +52,8 @@
   "engines": {
     "node": ">=16.0.0"
   },
-  "dependencies": {}
+  "devDependencies": {
+    "eslint": "10.1.0",
+    "globals": "17.4.0"
+  }
 }

package/runtime/demo/README.md

@@ -0,0 +1,78 @@
+# x402 Demo — Agent Payments in 60 Seconds
+
+HTTP has a 402 status code that basically nobody used — until agents needed to pay.
+
+This demo runs a local mock x402 merchant so you can see the full payment flow without any real money.
+
+## Quick Start
+
+```bash
+# Terminal 1: Start the mock merchant
+npx clawpowers demo x402
+
+# Terminal 2: Hit the paid endpoint
+curl http://localhost:PORT/api/premium-data
+# → Returns 402 with payment requirements
+
+# Simulate payment
+curl -H "x-payment: mock-proof" http://localhost:PORT/api/premium-data
+# → Returns 200 with data
+```
+
+## What's Happening
+
+1. Your agent calls a premium API
+2. The server returns **HTTP 402 Payment Required** with x402 payment requirements (amount, asset, recipient, network)
+3. ClawPowers evaluates the payment against your spending policy (limits, allowlist, mode)
+4. In **dry-run mode**: logs what would happen, no funds move
+5. In **live mode**: signs a payment proof via `agentwallet-sdk`, sends payment, retries the request
+6. Server validates payment proof and returns the data
+
+## The x402 Flow
+
+```
+Agent                    Mock Merchant
+  |                           |
+  |-- GET /api/premium-data ->|
+  |<- 402 + requirements -----|
+  |                           |
+  | [evaluate policy]         |
+  | [sign payment proof]      |
+  |                           |
+  |-- GET + x-payment ------->|
+  |<- 200 + data -------------|
+```
+
+## Payment Requirements Format
+
+The 402 response includes a JSON body:
+
+```json
+{
+  "x402Version": 1,
+  "accepts": [{
+    "scheme": "exact",
+    "network": "base-sepolia",
+    "maxAmountRequired": "100000",
+    "resource": "https://localhost:PORT/api/premium-data",
+    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    "payTo": "0xff86829393C6C26A4EC122bE0Cc3E466Ef876AdD"
+  }],
+  "error": "Payment Required"
+}
+```
+
+## Check Payment Logs
+
+After running the demo, inspect the payment decisions:
+
+```bash
+npx clawpowers payments log
+npx clawpowers payments summary
+```
+
+## Next Steps
+
+- Read the [agent-payments skill](../../skills/agent-payments/SKILL.md) for full methodology
+- Run `npx clawpowers payments setup` to configure spending limits
+- See the [Security Model](../../README.md#security-model) for guardrails

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

@@ -16,7 +16,7 @@
 'use strict';
 
 const http = require('http');
-const os = require('os');
+
 
 // Track requests for demo visibility
 let requestCount = 0;

package/runtime/init.sh

@@ -132,7 +132,7 @@ EOF
 # The sed command replaces the version= line in place; .bak is cleaned up immediately.
 run_migrations() {
   local current_version
-  current_version=$(grep "^version=" "$CLAWPOWERS_DIR/.version" 2>/dev/null | cut -d= -f2 || echo "0.0.0")
+  # current_version=$(grep "^version=" "$CLAWPOWERS_DIR/.version" 2>/dev/null | cut -d= -f2 || echo "0.0.0")
 
   # Future migration hooks go here, e.g.:
   # if [[ "$current_version" < "2.0.0" ]]; then