clawpowers 1.1.4 → 2.2.0

package/README.md

@@ -1,287 +1,455 @@
-# 🦞 ClawPowers
+# ClawPowers
 
-> **v1.1.3** · 26 skills · 372 tests · MIT · **Patent Pending**
+**Launch surface:** `clawpowers` is the capability library. It is not the stock OpenClaw wrapper runtime. For the wrapper runtime, install `clawpowers-agent`.
 
-**Your agent needs to pay for APIs. ClawPowers makes that work.**
+**Recommended pairing:** `clawpowers` 2.2.x with `clawpowers-agent` 1.1.x.
 
-When your agent hits a premium API and gets back HTTP 402 Payment Required, it needs to pay and retry — automatically, within limits you set, with your approval before anything moves. That's the core problem ClawPowers solves. The other 25 skills are a bonus.
+**More docs:** [SECURITY](./SECURITY.md) · [Compatibility](./COMPATIBILITY.md) · [Known Limitations](./KNOWN_LIMITATIONS.md) · [Licensing](./LICENSING.md) · [Releasing](./RELEASING.md) · [Demo](./DEMO.md)
 
-## The Pay-to-Complete Flow
+**Skills library for AI agents — payments, memory, RSI, wallet, parallel swarm, ITP.** Drop-in capability layer for any agent framework.
 
-```
-Agent calls API
-      │
-      ▼
-  HTTP 402  ←── "Payment required: $0.50 USDC"
-      │
-      ▼
-ClawPowers evaluates:
-  • Is this within your spend cap? ($5/tx limit → ✅)
-  • Is this on the allowlist?     (api.example.com → ✅)
-  • Human approval required?      (under $1 threshold → auto)
-      │
-      ▼
-  Payment sent → API retried → Result returned
-      │
-      ▼
-  Outcome logged (for RSI analysis)
+[![npm version](https://img.shields.io/npm/v/clawpowers)](https://www.npmjs.com/package/clawpowers)
+[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](LICENSE)
+
+```bash
+npm install clawpowers
 ```
 
-## Quick Start
+## 60-Second Demo
 
 ```bash
-npx clawpowers init          # Set up ~/.clawpowers/ runtime
-npx clawpowers demo x402     # See the full 402 → pay → 200 flow (no real money)
-npx clawpowers status        # Check what's running
+npm install clawpowers
+node -e "
+const { generateWallet, detect402, SpendingPolicy, signMessage } = await import('clawpowers');
+
+// 1. Generate a real Ethereum wallet (MetaMask-compatible)
+const wallet = await generateWallet({ chain: 'base', dataDir: './demo-wallet' });
+console.log('Address:', wallet.address);
+
+// 2. Detect an x402 payment-required response
+const req = detect402({ status: 402, headers: {
+  'x-payment-amount': '0.10',
+  'x-payment-currency': 'USD',
+  'x-payment-recipient': '0xabc',
+  'x-payment-network': 'base'
+}});
+console.log('Payment required:', req);
+
+// 3. Enforce a spending policy
+const policy = new SpendingPolicy({ dailyLimitUsd: 25, allowedDomains: ['api.example.com'] });
+console.log('Allowed:', policy.checkTransaction(0.10, 'api.example.com').allowed);
+"
 ```
 
-## Human-Approval Mode (the default)
+That's a real Ethereum wallet, real x402 detection, and a real spending policy check — all in 60 seconds, zero config, zero Rust toolchain. The `native/` Rust acceleration is optional; the WASM tier ships pre-built in the npm package.
 
-ClawPowers defaults to supervised payments — your agent proposes, you approve. No funds move until you say so.
+> **⚠️ Patent Pending:** The x402 payment detection, autonomous spending policy enforcement, and recursive self-improvement (RSI) systems described in this library are subject to pending patent applications. Use is governed by the BSL 1.1 license.
 
-```typescript
-import { createX402Client } from 'agentwallet-sdk';
-import { createWallet, setSpendPolicy } from 'agentwallet-sdk';
-import { createWalletClient, http } from 'viem';
-import { privateKeyToAccount } from 'viem/accounts';
-import { base } from 'viem/chains';
+---
 
-const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
-const walletClient = createWalletClient({ account, chain: base, transport: http() });
+## What Is This?
 
-const wallet = createWallet({
-  accountAddress: process.env.AGENT_WALLET_ADDRESS as `0x${string}`,
-  chain: 'base',
-  walletClient,
-});
+ClawPowers extracts the core capabilities from [ClawPowers-Agent](https://github.com/up2itnow0822/ClawPowers-Agent) into a standalone library. **No agent control loop** — bring your own agent framework and get:
 
-// Spend policy — enforced on-chain, not in application code
-await setSpendPolicy(wallet, {
-  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
-  perTxLimit: 1_000_000n,    // $1 auto-approved per transaction
-  periodLimit: 10_000_000n,  // $10/day hard cap
-  periodLength: 86400,
-});
+That separation is intentional:
 
-const x402 = createX402Client(wallet, {
-  supportedNetworks: ['base:8453'],
-  globalDailyLimit: 10_000_000n,    // matches spend policy
-  globalPerRequestMax: 1_000_000n,  // $1 per request
-  requireApproval: true,            // human-in-the-loop mode (default)
-});
+- **`clawpowers`** owns the shared capability implementation.
+- **`clawpowers-agent`** owns the stock OpenClaw wrapper runtime.
+- Downstream wrappers should consume this package rather than duplicating capability logic.
 
-// Agent hits a paid API
-const response = await x402.fetch('https://api.example.com/premium-data');
-// If cost < $1: auto-approved and paid
-// If cost > $1: queued — you get a notification to approve or reject
-const data = await response.json();
-```
+- **x402 Payments** — Detect HTTP 402 responses, enforce spending policies, execute payments
+- **Three-Tier Memory** — Working, episodic, procedural memory with crash recovery
+- **RSI Engine** — Metrics collection, hypothesis generation, mutation, A/B testing
+- **Wallet** — Generate, import, and sign with **MetaMask-compatible** Ethereum addresses out of the box (secp256k1 + Keccak-256 via pre-built WASM, no Rust toolchain required)
+- **Skills** — Discover, load, and track skill execution outcomes
+- **Parallel Swarm** — Concurrent task execution with intelligent model routing and token budgeting
+- **ITP (Identical Twins Protocol)** — Context compression that eliminates redundant token usage across agent sessions
 
-## Simulation Mode
+## Native Acceleration
 
-Test the full payment flow before enabling live payments.
+ClawPowers ships the same optional **Rust + WASM + PyO3** stack as [ClawPowers-Agent](https://github.com/up2itnow0822/ClawPowers-Agent), exposed through a **3-tier loader** in TypeScript. **v2.2.0+:** when a native `.node` addon is present, the WASM bundle is still loaded if available so helpers such as secp256k1 stay available even if your local addon predates those exports; `getActiveTier()` remains `native` in that case.
 
-```bash
-# Run a local mock x402 merchant — full 402 → pay → 200 cycle
-npx clawpowers demo x402
-```
+| Tier | Backend | When it loads |
+|------|---------|----------------|
+| **1 — Native** | `napi-rs` `.node` addon (`native/ffi`, built locally with Rust) | Fastest; optional — not required for npm installs |
+| **2 — WASM** | Pre-built `native/wasm/pkg-node` (and `pkg` for web) | **Default** for most Node.js installs — no `wasm-pack` or Rust needed |
+| **3 — TypeScript** | Pure JS / Node built-ins | Universal fallback when native and WASM are unavailable |
 
-In code:
+Check status in code:
 
 ```typescript
-const x402 = createX402Client(wallet, {
-  supportedNetworks: ['base:8453'],
-  globalDailyLimit: 10_000_000n,
-  globalPerRequestMax: 1_000_000n,
-  dryRun: true,  // logs exactly what would happen, no funds move
-});
+import { getActiveTier, isNativeAvailable, isWasmAvailable, getCapabilitySummary } from 'clawpowers';
 
-const response = await x402.fetch('https://api.example.com/premium-data');
-// Response includes: { simulated: true, wouldHavePaid: '0.50 USDC', withinLimits: true }
+console.log(getActiveTier()); // 'native' | 'wasm' | 'typescript'
+console.log(isNativeAvailable(), isWasmAvailable());
+console.log(getCapabilitySummary());
 ```
 
-## Explicit Spend Caps
+### Building native / WASM locally
 
-Caps are enforced by smart contract, not application code. Even a prompt injection or jailbreak can't bypass them.
+**Requirements (optional):** Rust (`rustc` 1.70+), `wasm-pack` for regenerating WASM bindings.
 
-```
-Agent wants to spend $0.50  → ✅ Auto-approved (under $1/tx cap)
-Agent wants to spend $5.00  → ⏳ Queued for your approval
-Agent spent $9.00 today     → 🛑 Next tx blocked ($10/day cap hit)
+```bash
+npm run build:native   # workspace `cargo build --release` (ignored if Rust missing)
+npm run build:wasm     # wasm-pack → native/wasm/pkg-node (optional)
 ```
 
-```bash
-# Check what your agent has spent
-npx clawpowers store get agent-payments:daily-total
-# → "2.50 USDC spent today, $7.50 remaining"
+`wasm-pack` may regenerate `pkg/.gitignore` / `pkg-node/.gitignore` that ignore all files in those folders — remove those ignore files if you need to commit refreshed WASM output.
+
+Pre-built `.wasm` artifacts are included in the package so consumers are **not** required to run `wasm-pack`.
+
+### Module coverage (aligned with ClawPowers-Agent)
+
+| Area | Tier 1 / 2 capability | TypeScript fallback |
+|------|------------------------|---------------------|
+| Payments | `JsFeeSchedule`, WASM fee math | Pure-TS fee formula |
+| Payments | `JsX402Client` | Base64 JSON header |
+| Payments | `JsAgentWallet` (native only) | TS wallet + WASM secp256k1 + Keccak for real Ethereum addresses |
+| Memory | `JsCanonicalStore`, `JsTurboCompressor`, `JsWriteFirewall` | File/JSONL memory; simplified firewall |
+| Wallet / secp256k1 | Native + WASM: `deriveEthereumAddress`, `derivePublicKey`, `signEcdsa`, `verifyEcdsa`, `computeKeccak256` / `keccak256Bytes` | Tier 3: legacy digest-based “address” + HMAC signing fallback only |
+
+Exported helpers include `calculateTransactionFee`, `createPaymentHeader`, `generateWalletAddress`, `compressVector`, `getBestCanonicalStore`, `digestForWalletAddress`, and the full loader API in `src/native/index.ts`.
+
+## x402 Payment Flow
 
-# Review and approve queued payments
-npx clawpowers payments queue
-# → [1] $5.00 USDC — api.example.com/premium-report — approve? (y/n)
+```
+┌─────────┐     ┌──────────────┐     ┌───────────────┐     ┌──────────┐
+│  Agent   │────▶│  API Server  │────▶│   detect402() │────▶│ Spending │
+│          │     │  returns 402 │     │  parse x402   │     │  Policy  │
+└─────────┘     └──────────────┘     │   headers     │     │  check   │
+                                     └───────────────┘     └────┬─────┘
+                                                                │
+                                              ┌─────────────────▼─────────────────┐
+                                              │         PaymentExecutor           │
+                                              │  ┌───────────┐  ┌─────────────┐  │
+                                              │  │ MCP Client │  │ Audit Log   │  │
+                                              │  │ (agentpay) │  │ (append-only│  │
+                                              │  └─────┬─────┘  └─────────────┘  │
+                                              └───────┬───────────────────────────┘
+                                                      │
+                                              ┌───────▼───────┐
+                                              │  Base Network  │
+                                              │  USDC Payment  │
+                                              └───────────────┘
 ```
 
-## Why Supervised, Not Autonomous
+## Framework Compatibility
 
-Fully autonomous agent payments sound great until an agent in a loop runs up $500 in API calls overnight. ClawPowers is built around three constraints:
+| Framework | Integration | Example |
+|-----------|------------|---------|
+| **LangChain** | `DynamicStructuredTool` | [`demos/langchain.ts`](demos/langchain.ts) |
+| **Claude Code** | `CLAUDE.md` config | [`demos/claude-code.md`](demos/claude-code.md) |
+| **ElizaOS** | Plugin pattern | [`demos/elizaos.ts`](demos/elizaos.ts) |
+| **AutoGPT** | Direct import | See examples below |
+| **CrewAI** | Tool wrapper | See examples below |
+| **Custom** | Direct TypeScript import | See examples below |
 
-1. **Caps enforced on-chain** — the agent *cannot* exceed them, full stop
-2. **Human approval by default** — auto-approve only below thresholds you set
-3. **Full audit trail** — every payment logged at `~/.clawpowers/metrics/`
+## Quick Start
 
-When you've verified the agent behaves correctly, raise the auto-approve threshold. Start low.
+### Payments
 
-## Installation
+```typescript
+import { SpendingPolicy, PaymentExecutor, detect402 } from 'clawpowers';
 
-### Universal (Windows, macOS, Linux)
+// Configure spending limits
+const policy = new SpendingPolicy({
+  dailyLimit: 25,        // $25/day
+  transactionLimit: 10,  // $10 per tx
+  allowedDomains: ['api.example.com'],
+});
 
-```bash
-npx clawpowers init
+// Create executor with your MCP client
+const executor = new PaymentExecutor(policy, mcpClient);
+
+// Detect and handle 402 responses
+const payment = detect402({ status: 402, headers: responseHeaders });
+if (payment) {
+  const result = await executor.executePayment({
+    amount: payment.amount,
+    currency: payment.currency,
+    recipient: payment.recipient,
+    domain: 'api.example.com',
+    x402Headers: payment.x402Headers,
+  });
+}
 ```
 
-### OpenClaw
+### Memory
 
-```bash
-openclaw skills install clawpowers
-# or from GitHub
-openclaw skills install github:up2itnow0822/clawpowers
-```
+```typescript
+import { EpisodicMemory, ProceduralMemory, ContextInjector } from 'clawpowers';
+
+// Episodic: Task history (append-only JSONL)
+const episodic = new EpisodicMemory('~/.clawpowers/memory/episodic.jsonl');
+await episodic.append({
+  taskId: 'task-1',
+  timestamp: new Date().toISOString(),
+  description: 'Built authentication module',
+  outcome: 'success',
+  lessonsLearned: ['Always test edge cases'],
+  skillsUsed: ['tdd'],
+  durationMs: 5000,
+  tags: ['auth'],
+});
 
-### Claude Code
+// Procedural: Skill effectiveness tracking
+const procedural = new ProceduralMemory('~/.clawpowers/memory/procedural.json');
+await procedural.update('tdd', { succeeded: true, durationMs: 5000, taskId: 'task-1' });
 
-```bash
-/plugin install clawpowers@claude-plugins-official
+// Context injection: Relevant memories for new tasks
+const injector = new ContextInjector(episodic, procedural);
+const context = await injector.inject(goal, 2000); // 2000 token budget
 ```
 
-### Cursor
+### RSI (Recursive Self-Improvement)
 
-```text
-/add-plugin clawpowers
+```typescript
+import { MetricsCollector, HypothesisEngine, MutationEngine, ABTestManager } from 'clawpowers';
+
+// Collect metrics
+const metrics = new MetricsCollector('task-metrics.jsonl', 'skill-metrics.jsonl');
+await metrics.recordTaskMetrics({ taskId: 'task-1', outcome: 'success', /* ... */ });
+
+// Generate improvement hypotheses
+const hypothesis = new HypothesisEngine();
+const hypotheses = hypothesis.analyze(skillStats, taskHistory);
+
+// Create and test mutations
+const mutations = new MutationEngine('mutations.jsonl');
+const mutation = mutations.createMutation(hypotheses[0]);
+
+// A/B test mutations
+const ab = new ABTestManager();
+const test = ab.startTest(mutation, baselineStats);
+ab.recordResult(test.testId, newTaskMetrics);
+const result = ab.evaluateTest(test.testId);
+// result.decision: 'promote' | 'rollback' | 'continue'
 ```
 
-### Codex / OpenCode
+### Wallet
 
-```text
-Fetch and follow instructions from https://raw.githubusercontent.com/up2itnow0822/clawpowers/main/.codex/INSTALL.md
-```
+**v2.2.0+ produces real MetaMask-compatible Ethereum addresses** via the standard derivation chain: secp256k1 private key → uncompressed public key → Keccak-256 → last 20 bytes, with EIP-55 checksum case. Verified against the Hardhat default test vector (`0xac09...ff80` → `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`). Addresses are importable into MetaMask, Etherscan, and any EVM wallet.
 
-### Manual
+**Tier behavior:**
+- **Tier 1** (native `.node` addon, built locally with `cargo`): full secp256k1 + ECDSA + Keccak-256 via the `k256` Rust crate
+- **Tier 2** (pre-built WASM, ships in the npm package): same secp256k1 + ECDSA + Keccak-256 via `k256` compiled to WebAssembly
+- **Tier 3** (pure TypeScript, used only if Tier 1 AND Tier 2 both fail to load): legacy SHA-256 digest and HMAC signing — **not production-safe for on-chain use**
 
-```bash
-git clone https://github.com/up2itnow0822/clawpowers.git
-cd clawpowers
-node bin/clawpowers.js init
+Since Tier 2 WASM artifacts ship pre-built in the npm package, **every install gets real Ethereum wallets out of the box** — no Rust toolchain required.
+
+```typescript
+import { WalletManager, generateWallet, signMessage } from 'clawpowers';
+
+// High-level API
+const wallet = new WalletManager({
+  chain: 'base',
+  dataDir: '~/.clawpowers/wallet',
+});
+
+const info = await wallet.generate();
+console.log(info.address); // 0x... — real Ethereum address, EIP-55 checksummed
+
+// Low-level API for direct key handling
+const sig = await signMessage(privateKeyHex, 'Hello, Ethereum');
+// Returns 65-byte ECDSA signature (r || s || recovery) as 0x-prefixed hex
+// Verifiable by any Ethereum node, ethers.js, viem, or MetaMask
 ```
 
-## All 26 Skills
-
-### Core Development (14)
-
-| Skill | What It Does |
-|-------|-------------|
-| `subagent-driven-development` | Orchestrate parallel subagents — persistent execution DB, resumable checkpoints |
-| `test-driven-development` | RED-GREEN-REFACTOR with mutation analysis to verify tests actually catch bugs |
-| `writing-plans` | Spec → implementation plan with historical estimation and dependency validation |
-| `executing-plans` | Execute plans with interruption recovery and milestone tracking |
-| `brainstorming` | Structured ideation with cross-session idea persistence |
-| `systematic-debugging` | Persistent hypothesis tree so you never re-investigate the same dead end |
-| `verification-before-completion` | Pre-merge quality gates that actually run the verification suite |
-| `finishing-a-development-branch` | Branch cleanup, changelog, merge prep |
-| `requesting-code-review` | Reviewer match scoring, review history |
-| `receiving-code-review` | Feedback pattern tracking, common issues database |
-| `using-git-worktrees` | Isolated branch development with conflict prediction |
-| `using-clawpowers` | Meta-skill: how to use ClawPowers |
-| `writing-skills` | Create new skills via TDD with quality scoring |
-| `dispatching-parallel-agents` | Fan-out with load balancing, failure isolation, result aggregation |
-
-### Extended Capabilities (6)
-
-| Skill | What It Does |
-|-------|-------------|
-| `agent-payments` | x402 payment protocol — supervised, capped, human-in-the-loop by default |
-| `security-audit` | Automated vulnerability scanning (Trivy, gitleaks, npm audit) |
-| `content-pipeline` | Write → humanize → format → publish with platform-specific formatting |
-| `learn-how-to-learn` | Metacognitive protocols, anti-pattern detection, confidence calibration |
-| `market-intelligence` | Competitive research, trend detection, opportunity scoring |
-| `prospecting` | Lead generation, contact enrichment, CRM sync (Exa + Apollo) |
-
-### RSI Intelligence Layer (4)
-
-Skills that require runtime execution and persistent state — not available in static frameworks.
-
-| Skill | What It Does |
-|-------|-------------|
-| `meta-skill-evolution` | Every 50 tasks: analyzes outcomes, identifies weakest skill, rewrites its methodology |
-| `self-healing-code` | On test failure: hypothesis tree → 2+ patches → applies best → auto-commits |
-| `cross-project-knowledge` | Pattern library across all repos — bug fixes and solutions transfer between projects |
-| `formal-verification-lite` | Property-based testing (fast-check/Hypothesis/QuickCheck) — 1000+ examples per property |
-
-## Cross-Session Memory
-
-Skills persist state across sessions. Your agent's debugging hypotheses, payment outcomes, and learned patterns survive session restarts.
+For production on-chain sending and transaction construction, you can still use [`viem`](https://viem.sh) or [`ethers`](https://docs.ethers.org) alongside ClawPowers — our wallet produces the same addresses they do.
+
+## Memory Module
+
+| Layer | Storage | Purpose |
+|-------|---------|---------|
+| **Working** | In-process | Current task context with token budget |
+| **Episodic** | JSONL file | Task history, searchable by keywords |
+| **Procedural** | JSON file | Skill effectiveness tracking with atomic writes |
+| **Checkpoint** | JSON files | Crash recovery, stale detection |
+| **Context Injector** | Computed | Selects relevant memories for new tasks |
+
+## RSI Module
+
+The RSI engine implements a continuous improvement loop:
 
 ```
-~/.clawpowers/
-├── state/        # Key-value store
-├── metrics/      # Outcome tracking per skill (JSONL)
-├── checkpoints/  # Resumable workflow state
-├── feedback/     # RSI self-improvement data
-└── logs/         # Execution logs
+measure → hypothesize → mutate → A/B test → promote/rollback → repeat
 ```
 
-## CLI Reference
+**Tier Safety:**
+- **T1** (Parameter Tuning) — Can auto-apply
+- **T2** (Strategy Evolution) — Can auto-apply with notification
+- **T3** (Skill Composition) — Requires testing gate
+- **T4** (Architecture Proposals) — **ALWAYS requires human approval**
 
-```bash
-npx clawpowers init                          # Set up runtime
-npx clawpowers status                        # Health check
-npx clawpowers demo x402                     # Payment demo (no real money)
-npx clawpowers metrics record --skill <name> --outcome success|failure
-npx clawpowers metrics summary               # Per-skill stats
-npx clawpowers analyze                       # RSI performance analysis
-npx clawpowers store get <key>               # Read persistent state
-npx clawpowers store set <key> <value>       # Write persistent state
-npx clawpowers payments queue                # Review pending approvals
+Safety invariants (spending limits, identity, RSI definitions, sandbox boundaries, credentials) can **NEVER** be modified by RSI.
+
+## Parallel Swarm
+
+Run multiple tasks concurrently with intelligent model routing, shared context, and token budget management.
+
+```typescript
+import { ConcurrencyManager, TokenPool, classifyHeuristic, selectModel } from 'clawpowers';
+
+const pool = new TokenPool({ totalBudget: 100000 });
+const concurrency = new ConcurrencyManager({ maxConcurrency: 5 });
+
+// Classify and route tasks to optimal models
+const complexity = classifyHeuristic('Build a distributed trading system');
+const model = selectModel(complexity); // → claude-opus-4-5
+
+// Allocate token budgets per task
+pool.allocate('task-1', 5000);
 ```
 
-## Platform Support
+### Swarm vs Sequential Sessions
 
-| Platform | Windows | macOS | Linux | WSL2 |
-|----------|:-------:|:-----:|:-----:|:----:|
-| Claude Code | ✅ | ✅ | ✅ | ✅ |
-| Cursor | ✅ | ✅ | ✅ | ✅ |
-| Codex | ✅ | ✅ | ✅ | ✅ |
-| OpenCode | ✅ | ✅ | ✅ | ✅ |
-| Gemini CLI | ✅ | ✅ | ✅ | ✅ |
+Running N tasks as a single parallel swarm instead of N separate LLM sessions avoids reloading shared context (system prompt, workspace files, tool schemas) for every task.
 
-## Requirements
+**Measured benefits:**
+- **Wall time:** parallel fan-out is significantly faster than sequential execution, scaling with task count and concurrency limit
+- **Token usage:** shared-context overhead is paid once per swarm run instead of once per task
 
-- **Node.js >= 16** (for cross-platform runtime)
-- **OR bash** (for Unix-native runtime)
-- **Zero runtime dependencies** — `package.json` has an empty `dependencies` object
+**Current measurement snapshot:**
 
-## Security Model
+**Live ITP compression measurements:**
+- **25-message corpus:** 11 of 25 messages compressed, `862` to `759` estimated tokens, **11.95% token reduction**, **7.8 ms/message** round-trip
+- **5-task live swarm payload:** `183` to `133` task tokens, **27.32% payload reduction**, **5 of 5 tasks compressed**, **10.8 ms** average encode latency
 
-- State directory (`~/.clawpowers/`) uses `700` permissions — owner-only
-- No network access in runtime scripts — store, metrics, and analyze are fully offline
-- No `eval()`, `Function()`, or dynamic code execution anywhere in the runtime
-- Payment guardrails enforced by smart contract — application code cannot override them
+**Modeled prompt-cache economics on those same live prompt sizes:**
 
-## Credential
+| Scenario | Effective input units | Reduction vs baseline | Source type |
+|----------|-----------------------|-----------------------|-------------|
+| Baseline | 1902.00 | 0.00% | Derived from live prompt sizes |
+| ITP only | 1848.00 | 2.84% | Live ITP server compression applied to full prompts |
+| Prompt cache only | 752.95 | 60.41% | Anthropic cache-pricing model |
+| ITP + prompt cache | 698.95 | 63.25% | Hybrid result: live ITP compression + modeled cache pricing |
 
-Built by [AI Agent Economy](https://github.com/up2itnow0822):
-- Payment infrastructure in [NVIDIA's official NeMo Agent Toolkit](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17)
-- [agentwallet-sdk](https://www.npmjs.com/package/agentwallet-sdk) — 741+ downloads/week
-- [agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp) — MCP payment server
+- **Shared prompt prefix in swarm test:** 1,372 characters, about 343 estimated input tokens
+- **Three-set hybrid validation on a MacBook Pro (Apple M1, 16 GB RAM) with benchmark runner model `openai-codex/gpt-5.4`:** combined reduction ranged from **61.89%** to **63.25%**, with a **62.56%** mean and **0.56** standard deviation
 
-## Patent Notice
+**Reproduce:**
+- `node benchmarks/itp-measurement.mjs` for the live ITP corpus benchmark
+- `node benchmarks/swarm-vs-sequential.mjs` for the structure-only swarm cost model
+- `node benchmarks/itp-cache-swarm-benchmark.mjs` for the hybrid benchmark (live ITP compression + modeled cache economics)
+- `node benchmarks/itp-cache-multi-swarm-benchmark.mjs` for the same hybrid methodology across three swarm sets
+
+## ITP (Identical Twins Protocol) - Experimental
 
-**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."
+> **Status: Experimental.** ITP compression and latency numbers below are measured against the running server. Any prompt-cache numbers are modeled Anthropic cache economics applied to those same live prompt sizes.
 
-We support the open x402 standard. Our provisional filing is defensive — intended to prevent hostile monopolization of open payment rails, not to restrict builders.
+Context compression for multi-agent communication. When agents share similar context (same model, same workspace), ITP deduplicates the common payload before transmission. The library ships with a graceful passthrough fallback, so code using ITP works even when the ITP server is offline. Messages are simply forwarded unchanged.
+
+```typescript
+import { itpEncode, itpDecode, itpHealthCheck, encodeTaskDescription, decodeSwarmResult } from 'clawpowers';
 
-## Disclaimer
+// Graceful fallback, works without ITP server running
+const encoded = await encodeTaskDescription('Analyze quarterly revenue data');
+const decoded = await decodeSwarmResult(result);
+
+// Health check
+const serverUp = await itpHealthCheck(); // false = passthrough mode
+```
+
+**Live ITP benchmark snapshot:**
+- **Codebook:** `v1.0.0`, 99 entries
+- **Corpus benchmark:** **11.95%** token reduction on 25 messages
+- **Swarm payload benchmark:** **27.32%** task-token reduction on a 5-task swarm
+- **Hybrid swarm benchmark:** **63.25%** effective input-cost reduction from live ITP compression plus modeled prompt caching
+
+ITP is most effective in parallel swarm scenarios where multiple tasks share the same model context. Prompt caching handles repeated prompt structure, and ITP reduces the changing task payload inside that structure. Cross-model savings can also compound because providers inject similar preambles across nearby model tiers.
+
+## Fee Structure
+
+| Operation | Fee |
+|-----------|-----|
+| Transaction | 0.77% |
+| Token Swap | 0.30% |
+
+Fees are applied at the payment execution layer and are included in the transaction amount.
+
+## Python Integration
+
+```python
+import subprocess
+import json
+
+# Call ClawPowers via Node.js subprocess
+# Note: use --input-type=module (or a .mjs file) because clawpowers is an ES module
+result = subprocess.run(
+    ['node', '--input-type=module'],
+    input='''
+    import { detect402, SpendingPolicy } from "clawpowers";
+    const policy = new SpendingPolicy({ dailyLimit: 25, transactionLimit: 10, allowedDomains: [] });
+    const decision = policy.checkTransaction(5.00, "api.example.com");
+    console.log(JSON.stringify(decision));
+    ''',
+    capture_output=True, text=True
+)
+decision = json.loads(result.stdout)
+```
 
-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 here constitutes financial advice, custody services, or money transmission.
+## API Reference
+
+### Native acceleration
+- `getActiveTier()`, `isNativeAvailable()`, `isWasmAvailable()`, `getCapabilitySummary()` — Loader introspection
+- `computeSha256`, `digestForWalletAddress`, `tokenAmountFromHuman`, `calculateFee`, `evaluateWriteFirewall` — Routed helpers
+- `getNative()`, `getWasm()` — Low-level module access
+
+### Payments
+- `detect402(response)` — Parse x402 headers from 402 response
+- `isPaymentRequired(error)` — Type guard for 402 errors
+- `SpendingPolicy` — Enforce daily/transaction/domain limits
+- `PaymentExecutor` — Execute payments via MCP client
+- `calculateTransactionFee`, `createPaymentHeader`, `generateWalletAddress` — Native/WASM-accelerated payment helpers (with TS fallbacks)
+
+### Memory
+- `WorkingMemoryManager` — In-process context management
+- `EpisodicMemory` — JSONL task history
+- `ProceduralMemory` — Skill effectiveness tracking
+- `CheckpointManager` — Crash recovery
+- `ContextInjector` — Memory-to-context selection
+- `getBestCanonicalStore`, `getWasmCanonicalStore`, `compressVector`, `decompressVector`, `evaluateWriteSecurity` — Optional native/WASM memory bridges
+
+### RSI
+- `MetricsCollector` — Task/skill metrics in JSONL
+- `HypothesisEngine` — Generate improvement hypotheses
+- `MutationEngine` — Create/apply/revert mutations
+- `ABTestManager` — A/B test mutations
+- `RSIAuditLog` — Append-only audit trail
+- `AutoResearcher` — Research solutions to failures
+
+### Skills
+- `discoverSkills(dir)` — Find skills in a directory
+- `loadSkillManifest(dir)` — Load a single skill manifest
+- `SkillExecutor` — Execute skills with outcome tracking
+
+### Wallet
+
+- `WalletManager` — High-level wallet operations
+- `generateWallet(config)` — Generate new wallet (**v2.2.0+**: standard Ethereum address via secp256k1 when Tier 1/2 is active)
+- `importWallet(key, config)` — Import existing wallet (same derivation)
+- `signMessage(message, keyFile, passphrase)` — Sign; uses **ECDSA (secp256k1) over Keccak-256(UTF-8 message)** when native/WASM provides crypto, else legacy HMAC
+- `signMessage(privateKeyHex, message)` — Same ECDSA path; returns `0x` + 130 hex chars (65-byte signature)
+
+### Config
+- `loadConfig()` / `saveConfig()` — Zod-validated config CRUD
+- `initConfig()` — Create default config
+- `getConfigValue()` / `setConfigValue()` — Dot-notation access
 
 ## License
 
-MIT
+**Business Source License 1.1 (BSL 1.1)**
+
+This software is licensed under the BSL 1.1. You may use it for non-production purposes freely. Production use requires a commercial license until the Change Date, after which the software converts to the Apache 2.0 license.
+
+See [LICENSE](LICENSE) for full terms.
+
+## Patent Notice
+
+⚠️ **Patent Pending:** The autonomous payment detection, spending policy enforcement, recursive self-improvement engine, and multi-tier memory systems implemented in this library are subject to pending patent applications filed by AI Agent Economy. Unauthorized commercial use may constitute patent infringement.
+
+---
+
+Built by [AI Agent Economy](https://github.com/up2itnow0822) 🦅
+
+For commercial use, review [LICENSING.md](./LICENSING.md).