clawpowers 1.1.2 → 1.1.3

package/README.md

@@ -27,7 +27,7 @@ ClawPowers gives your coding agent superpowers that go beyond instructions. Whil
 | Windows native support | ✅ | ❌ |
 | Zero dependencies | ✅ | ✅ |
 
-**25 skills.** 14 cover everything static frameworks do (TDD, subagent dev, debugging, planning, code review, git worktrees). 6 go where they can't — payments, security, content, prospecting, market intelligence, and metacognitive learning. 4 are things no other framework even attempts — self-healing code, agents that rewrite their own methodology, cross-project knowledge transfer, and property-based formal verification.
+**26 skills.** 14 cover everything static frameworks do (TDD, subagent dev, debugging, planning, code review, git worktrees). 6 go where they can't — payments, security, content, prospecting, market intelligence, and metacognitive learning. 4 are things no other framework even attempts — self-healing code, agents that rewrite their own methodology, cross-project knowledge transfer, and property-based formal verification.
 
 ## Requirements
 
@@ -230,7 +230,7 @@ These skills don't exist in any other framework. They require runtime execution,
 
 ```
 clawpowers/
-├── skills/                    # 25 skill directories, each with SKILL.md
+├── skills/                    # 26 skill directories, each with SKILL.md
 ├── runtime/
 │   ├── persistence/           # Cross-session state (store.js + store.sh)
 │   ├── metrics/               # Outcome tracking (collector.js + collector.sh)
@@ -281,6 +281,40 @@ npx clawpowers store get <key>                         # Retrieve state
 npx clawpowers store list [prefix]                     # List stored keys
 ```
 
+## Payments Are Optional (and Safe by Default)
+
+ClawPowers works without any wallet.
+
+When you hit a paid boundary (HTTP 402 "Payment Required", premium tools, or agent-to-agent settlements), ClawPowers can pay **only if** you enable it and set spending limits.
+
+**Default mode: Dry Run**
+- We detect payment requirements.
+- We evaluate your spending policy (limits + allowlist).
+- We log exactly what would happen.
+- **No funds move until you explicitly enable live payments.**
+
+### Enable payments (2 minutes)
+
+```bash
+npx clawpowers init
+npx clawpowers payments setup
+```
+
+Choose:
+- Keep disabled
+- Enable Dry Run (observe what would happen)
+- Enable Live Payments (set per-tx and daily limits)
+
+All logs are local at `~/.clawpowers/` (never share this directory).
+
+### Try it risk-free
+
+```bash
+npx clawpowers demo x402
+```
+
+Runs a local mock x402 merchant — see the full 402 → pay → 200 flow without any real money.
+
 ## Security Model
 
 ClawPowers takes agent autonomy seriously — which means taking agent *limits* seriously.
@@ -398,6 +432,14 @@ We welcome contributions. Unlike some frameworks, we don't dismiss legitimate sk
 
 **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."
 
+## Open Standard + Defensive Patent
+
+We support the open x402 standard and encourage interoperable implementations. Our [provisional patent filing](https://github.com/up2itnow0822) is defensive — intended to prevent hostile monopolization and protect builders' ability to use open payment rails. Our goal is to be the safest, fastest, most complete implementation, and to help the ecosystem adopt secure agent payments.
+
+## Disclaimer
+
+ClawPowers and agentwallet-sdk are non-custodial developer tooling. You control your own keys and set your own spending limits. You are responsible for compliance with applicable laws in your jurisdiction. This software is provided as-is under the MIT license. Nothing in this project constitutes financial advice, custody services, or money transmission.
+
 ## License
 
 MIT

package/bin/clawpowers.js

@@ -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}`);
   }
 }
 

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 [https://www.coinbase.com/faucets/base-ethereum-goerli-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
+   [https://sepolia.basescan.org](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
+   [https://sepolia.basescan.org](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.3",
   "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/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