ape-claw 0.1.0

package/docs/archive/AUTONOMY_AND_SUBSTRATE.md

@@ -0,0 +1,66 @@
+# Autonomy, Substrate, and the "Fugazi Agent" Critique
+
+This doc answers a common (valid) critique:
+
+> "It's all pretrained: the model, the tools, the feedback loop. All of it runs on infrastructure it does not control.
+> How can you call something autonomous when it can’t survive losing API keys?"
+
+## What ApeClaw claims (and does not claim)
+
+### ApeClaw does claim
+
+- Persistence: an agent can crash, reboot, and keep going using a file-backed harness (THE POD).
+- Auditability: what happened is recorded as receipts/events (append-only).
+- Permission boundaries: high-risk actions require explicit opt-in + safety gates.
+- Replaceable infrastructure: UI/indexers/backends can change without changing the source of truth.
+
+### ApeClaw does not claim (yet)
+
+- "Open-ended intelligence" that changes its own weights/training set onchain.
+- Full substrate control over every dependency (models, RPC providers, markets).
+
+The goal is not hype. The goal is **a real autonomous operator**: persistent, auditable, and survivable.
+
+## Substrate control: what we anchor onchain today (v2)
+
+v2 makes the chain the source of truth for the pieces that matter:
+
+- `SkillNFT`: provenance and ownership (one token per skill).
+- `SkillRegistry`: immutable, append-only versions (content-addressed).
+- `ReceiptRegistry`: append-only receipts keyed by `traceIdHash`.
+- `PodVault`: a split vault so skill revenue can be shared among Pod members (EIP-2981 royalties → PodVault).
+
+This is the minimum "box" that the agent can’t lose.
+
+## Surviving API keys: what we do today
+
+The critique is correct: if your agent depends on a single API key, it's not survivable.
+
+In ApeClaw:
+
+- THE POD runs safe-by-default and can run without any model keys (stub vision backend).
+- For real vision, Claude CLI is an option; local VLM backends are the intended fallback path (planned hardening).
+- Market/bridge integrations are modular and can be swapped (Relay today; additional sources planned).
+
+## The missing piece: onchain enforcement (planned)
+
+The real answer to "bounded automation" is enforcement + governance:
+
+- `AgentAccount` + `PolicyEngine` (planned): onchain policy gates before value moves.
+- Permissionless solvers (planned): execution competition, not a single central runner.
+- Attestations/reputation (planned): version trust for skills.
+
+v2 ships the primitives those phases depend on.
+
+## Practical definition of "autonomy" used here
+
+An agent is "autonomous" if it can:
+
+- run continuously across restarts
+- keep its operating state in a survivable substrate
+- be audited by third parties
+- operate within explicit safety constraints
+- change out optional infrastructure without losing identity/history
+
+If you want a stronger definition, ApeClaw’s design is meant to evolve into it.
+

package/docs/archive/WEB4_PLAN_STATUS.md

@@ -0,0 +1,93 @@
+# Web4 Onchain Skills Plan — Status
+
+This project includes the reference plan in `web4_onchain_skills_plan.pdf`.
+
+This doc maps that plan to what ApeClaw has shipped today.
+
+## What is shipped (v2)
+
+These components exist in-repo and are tested:
+
+- `SkillNFT` (`contracts/SkillNFT.sol`)
+  - ERC-721 skill provenance
+  - parent forks (`parentSkillId`)
+  - optional royalties (EIP-2981) so skill revenue can route to a Pod receiver
+- `SkillRegistry` (`contracts/SkillRegistry.sol`)
+  - append-only version publishing
+  - stores `versionHash`, `contentHash`, `uri`, `riskTier`
+- `IntentRegistry` (`contracts/IntentRegistry.sol`)
+  - minimal intent create/cancel primitive
+- `ReceiptRegistry` (`contracts/ReceiptRegistry.sol`)
+  - append-only receipts keyed by `traceIdHash`
+- `PolicyEngine` (`contracts/PolicyEngine.sol`)
+  - minimal onchain pre-check hook (allowlists + value cap)
+- `AgentAccount` (`contracts/AgentAccount.sol`)
+  - minimal execution shell that enforces PolicyEngine and records receipts
+- Initial module skills (`contracts/*Module.sol`)
+  - `SwapModule`, `BridgeModule`, `NftBuyModule` (policy-gated call wrappers)
+- `PodVault` (`contracts/PodVault.sol`)
+  - PaymentSplitter-style revenue receiver for THE POD (native + ERC20)
+- Seed + deploy flow (`npm run contracts:seed`)
+  - deploys v2 contracts
+  - publishes all SkillCards in `skillcards/seed/`
+
+SkillCards + library ingestion:
+
+- seed SkillCards in `skillcards/seed/` (including v1 skills, receipts, and ACP bounties runbooks)
+- importer: `scripts/import-skillcards.mjs`
+  - imports SkillCards from GitHub repos and ClawHub (best-effort)
+  - writes `skillcards/imported/index.json` (provenance + hashes)
+
+Frontend/docs:
+
+- `/ui` dashboard (telemetry, chat, live feed)
+- `/skills` library page (seed + imported library views)
+- `/docs` in-site markdown docs reader
+- `/pod` product landing for THE POD
+
+Critique response:
+
+- `docs/AUTONOMY_AND_SUBSTRATE.md` directly addresses the "bounded automation" critique without overclaiming.
+
+## What is NOT shipped yet (still part of the plan)
+
+The Web4 plan calls out these primitives as critical for full permissionless autonomy. ApeClaw now ships a minimal `AgentAccount` + `PolicyEngine`, but the full design is still not shipped:
+
+- session keys / AA kernel hardening (ERC-4337 style)
+- richer policy constraints (token/time windows, slippage checks, approvals model)
+- Permissionless solver network + payments
+- Attestation/reputation registry + eval packs onchain
+- Disputes + slashing (optional later phase)
+
+The current posture is deliberately "v2":
+
+- strong provenance + immutable versions + receipts primitive
+- strict opt-in for high-risk automation
+- offchain execution remains bounded by the runner "box"
+
+## Phase mapping (rough)
+
+- P0 (contracts + basic UI): partially shipped
+  - contracts shipped: yes (SkillNFT, Registry, IntentRegistry, ReceiptRegistry)
+  - basic UI for discovery/install/intents: partially shipped
+    - discovery: `/skills` (seed + imported + submitted SkillCards, onchain status visualization)
+    - intents: `/skills#intents` ships a safe command-generator surface for `v2 intent create|cancel`
+    - install: download/curl commands are surfaced per-skill; full “one-click install into an agent runtime” remains planned
+- P1 (AgentAccount + module skills + receipts): shipped (v2 minimal primitives)
+  - `AgentAccount.executeSkill()` enforces `PolicyEngine.preCheck()` and best-effort records to `ReceiptRegistry`
+  - modules shipped: `SwapModule`, `BridgeModule`, `NftBuyModule` (policy-gated call wrappers; routing/UX remains offchain)
+- P2 (permissionless solvers): not shipped
+- P3 (attestations/reputation): not shipped
+- P4 (disputes/slashing): not shipped
+
+## Why this is still a functioning platform today
+
+ApeClaw's "functioning platform" claim is grounded in:
+
+- global onboarding + telemetry + audit trail (events + optional receipts)
+- deterministic CLI safety gates for value-moving actions
+- a skill library that is content-addressed and publishable onchain
+- a persistent Pod harness (file-backed) for long-running operation
+
+The plan items above are the path from "bounded automation with anchors" to "permissionless autonomy with substrate enforcement".
+

package/docs/archive/WEB4_SWARM_MODEL.md

@@ -0,0 +1,98 @@
+# Web4 Swarm Model (ApeClaw)
+
+This doc explains the core vision behind ApeClaw as a Web4 platform: **agents operate as a swarm**, and the swarm scales when it can:
+
+- share capabilities (skills)
+- share ground truth (receipts)
+- persist state (checkpointing) beyond any single machine
+- coordinate value-moving work safely (policies + caps + confirmations)
+
+## Why Web4 needs onchain context
+
+Most “autonomous agents” are bounded automation:
+
+- they plan in language, but don’t control the substrate
+- they lose state when the UI/backend/API keys disappear
+- they can’t prove what happened or coordinate trustlessly with other agents
+
+A Web4 swarm needs a source of truth that:
+
+- survives disappearing infrastructure
+- is globally readable by any agent
+- is permissionless at the primitive layer, but filterable at the UI layer
+
+That’s why ApeClaw uses onchain primitives for:
+
+- **Skill identity + versions** (SkillNFT + SkillRegistry)
+- **Receipts** (ReceiptRegistry)
+
+## Skills: swarm capability scaling
+
+SkillCards are portable JSON definitions: metadata + bindings + constraints.
+
+- Offchain SkillCard JSON is the human-readable spec.
+- Onchain publication anchors immutable versions:
+  - `contentHash` (content-addressed)
+  - `uri` (where the SkillCard lives)
+  - `riskTier` (safety classification)
+
+This enables:
+
+- deterministic upgrades (no silent changes)
+- global discovery (chain indexers + UIs)
+- “skill provenance” (what version did we run?)
+
+## Receipts: swarm memory + audit truth
+
+Receipts are append-only anchors keyed by `traceIdHash`.
+
+The pattern:
+
+1) An agent does work (or simulates/quotes work)
+2) It records a receipt with:
+   - `traceIdHash` (deterministic id)
+   - `contentHash` (what happened)
+   - `subject` (who/what it’s about)
+   - `uri` (optional pointer to larger payload/log)
+3) Any other agent can later read the receipt back from chain
+
+This gives the swarm:
+
+- “memory reload” (reconstruct state from receipts)
+- auditability (“prove what happened”)
+- coordination hooks (receipts as triggers)
+
+CLI primitives:
+
+- Record: `ape-claw v2 receipt record ...`
+- Read: `ape-claw v2 receipt get ...`
+
+## Persistence: Pod workspace + chain checkpoints
+
+Chain receipts are not a replacement for local state; they are a globally readable checkpoint layer.
+
+The Pod workspace pattern provides:
+
+- durable local state (files)
+- crash recovery (`memory/active-tasks.md`, journals)
+- strict opt-in execution (dry-run by default)
+
+Receipts provide:
+
+- global, portable checkpoints
+- tamper-resistant audit anchors
+
+The combination is what makes “agent swarm” possible.
+
+## Contribution loop (how the swarm grows)
+
+1) Users/agents submit SkillCards to the library (`/skills`)
+2) Curators/operators mint + publish onchain (immutable version)
+3) Agents use published skills, record receipts
+4) New skills and receipts expand the swarm’s capability + context
+
+See:
+
+- `docs/CONTRIBUTING.md`
+- `docs/ONCHAIN_V2_GUIDE.md`
+

package/docs/developer/01-architecture.md

@@ -0,0 +1,345 @@
+# Architecture
+
+## System Overview
+
+ApeClaw is an onchain AI agent ecosystem on ApeChain. It consists of:
+
+### Components
+
+1. **Smart Contracts** (Solidity, deployed on ApeChain)
+   - **SkillNFT** — NFT representation of skills (one token per skill)
+   - **SkillRegistry** — Version and metadata storage (append-only version log)
+   - **IntentRegistry** — Agent intent publishing (for solver-style architectures)
+   - **ReceiptRegistry** — Execution audit trail (append-only receipts)
+   - **PodVault** — Revenue sharing vault (receives SkillNFT royalties)
+   - **AgentAccount** — Agent execution shell (enforces PolicyEngine, records receipts)
+   - **PolicyEngine** — Safety guardrails (allowlists + value caps)
+   - **Modules** (Swap, Bridge, NftBuy) — Executable skill implementations
+
+2. **Backend Server** (`src/server/index.mjs`, modular architecture)
+   - Telemetry server with SSE event streaming (Last-Event-ID support)
+   - REST API for skills, pods, clawbot management, quotes, bridge requests
+   - Middleware: CORS allowlist, rate limiting, body size limits, auth
+   - Storage abstraction: file-based (default) or SQLite backend
+   - Structured logging via `pino`
+   - Static file server for the UI
+   - In-memory skill index with caching (60s TTL)
+   - Legacy monolith still available at `src/telemetry-server.mjs`
+
+3. **CLI** (`ape-claw`, entry: `src/cli/index.mjs` → delegates to `src/cli.mjs`)
+   - Onchain operations (mint, publish, execute)
+   - Clawbot registration and management
+   - NFT purchasing and bridging
+   - Pod workspace management
+
+4. **Frontend** (HTML in `ui/`, extracted CSS in `ui/css/`, JS in `ui/js/`)
+   - Dashboard with live event feed (`ui/index.html` + `ui/css/dashboard.css` + `ui/js/dashboard.js`)
+   - Skills Library (`ui/skills.html` + `ui/css/skills.css` + `ui/js/skills.js`)
+   - Pod management (`ui/pod.html`)
+   - Documentation viewer (`ui/docs.html`)
+   - Shared components: sidebar nav, motion effects
+
+## Data Flow
+
+```mermaid
+graph TB
+    User[User/Agent] --> CLI[CLI: ape-claw]
+    User --> UI[Frontend UI]
+    
+    CLI --> Backend[Backend Server]
+    UI --> Backend
+    
+    Backend --> Contracts[Smart Contracts<br/>on ApeChain]
+    
+    Contracts --> Events[Contract Events]
+    Events --> Backend
+    
+    Backend --> SSE[SSE Stream]
+    SSE --> UI
+    
+    CLI --> LocalState[Local State<br/>state/ directory]
+    CLI --> SkillCards[SkillCards<br/>skillcards/ directory]
+    
+    SkillNFT --> Royalties[EIP-2981 Royalties]
+    Royalties --> PodVault[PodVault]
+    PodVault --> Members[Pod Members]
+    
+    AgentAccount --> Policy[PolicyEngine<br/>preCheck]
+    AgentAccount --> Module[ISkillModule<br/>execute]
+    AgentAccount --> Receipts[ReceiptRegistry<br/>recordReceipt]
+```
+
+### Execution Flow
+
+1. **Skill Minting & Publishing**:
+   ```
+   CLI → SkillNFT.mintSkillWithRoyalty() → SkillRegistry.publishVersion()
+   ```
+
+2. **Module Execution**:
+   ```
+   CLI → AgentAccount.executeSkill() → PolicyEngine.preCheck() → ISkillModule.execute() → ReceiptRegistry.recordReceipt()
+   ```
+
+3. **Event Streaming**:
+   ```
+   Contract Events → Backend (SSE) → Frontend UI
+   ```
+
+## State Management
+
+### Onchain State
+
+Contracts deployed on ApeChain store:
+
+- **SkillNFT**: Ownership and provenance (one NFT per skill)
+- **SkillRegistry**: Immutable version log (`skillId` → `SkillVersion[]`)
+- **IntentRegistry**: Active intents for solver competition
+- **ReceiptRegistry**: Append-only execution receipts
+- **PodVault**: Revenue shares and pending payments
+- **PolicyEngine**: Allowlists (modules, targets, selectors) and value caps
+
+Example deployment record (`state/v2-deployments/apechain.json`):
+
+```json
+{
+  "skillNft": "0x...",
+  "registry": "0x...",
+  "intents": "0x...",
+  "receipts": "0x...",
+  "policy": "0x...",
+  "agentAccount": "0x...",
+  "podVault": "0x...",
+  "modules": {
+    "swap": "0x...",
+    "bridge": "0x...",
+    "nftBuy": "0x..."
+  },
+  "chainId": 33139,
+  "network": "apechain"
+}
+```
+
+### Local State
+
+The `state/` directory contains:
+
+- **`v2-deployments/`**: Deployment records per network
+- **`skillcards-user/`**: User-submitted SkillCards
+- **`quotes.json`**: NFT purchase quotes
+- **`bridge-requests.json`**: Bridge request records
+- **`events.jsonl`**: Telemetry events (appended by CLI/server)
+- **`chat.jsonl`**: Chat messages
+- **`invites.json`**: Registration invite tokens
+- **`apeclaw.db`**: SQLite database (when `APE_CLAW_STORAGE=sqlite`)
+
+The `config/` directory contains:
+
+- **`clawbots.json`**: Registered clawbot configurations
+- **`policy.json`**: Safety policy rules
+
+### Skill Library
+
+SkillCards are stored in:
+
+- **`skillcards/seed/`**: Seed skills (trusted, vetted)
+- **`skillcards/imported/`**: Imported skills from external sources
+- **`skillcards/imported/index.json`**: Index of imported skills
+
+The backend merges all three sources into a unified index (cached for 60 seconds):
+
+```javascript
+// From storage backend (file-backend.mjs or sqlite-backend.mjs)
+function buildMergedSkillIndex() {
+  const merged = [];
+  // 1. Read seed skills from skillcards/seed/*.json
+  // 2. Read imported skills from skillcards/imported/index.json
+  // 3. Read user skills from state/skillcards-user/index.json
+  return merged;
+}
+```
+
+### Pod Workspace
+
+Configurable directory (default: `pod/`) with:
+
+- **`AGENTS.md`**: Agent configuration and capabilities
+- **`SOUL.md`**: Agent identity and preferences
+- **`memory/`**: Persistent memory storage
+- **`journal/YYYY-MM-DD.md`**: Daily execution logs
+- **`executions/*.json`**: Execution audit trail
+
+## Contract Interactions
+
+### Skill Lifecycle
+
+```solidity
+// 1. Mint SkillNFT
+SkillNFT.mintSkillWithRoyalty(parentId, podVault, 500); // 5% royalty
+
+// 2. Publish version to SkillRegistry
+SkillRegistry.publishVersion(
+  skillId,
+  versionHash,    // keccak256(version_string)
+  contentHash,   // keccak256(canonical_json)
+  uri,           // ipfs://... or file://...
+  riskTier       // 0-3 (unknown, low, medium, high)
+);
+```
+
+### Module Execution
+
+```solidity
+// AgentAccount.executeSkill() flow:
+// 1. PolicyEngine.preCheck(module, target, selector, value)
+// 2. ISkillModule.execute(agentAccount, input)
+// 3. ReceiptRegistry.recordReceipt(traceIdHash, contentHash, subjectHash, uri)
+
+// Example: SwapModule
+AgentAccount.executeSkill(
+  swapModule,                    // module address
+  abi.encode(target, calldata),  // input: (address, bytes)
+  value,                         // ETH value
+  traceIdHash,                   // execution trace ID
+  subjectHash,                   // agent/skill identifier
+  uri                            // receipt metadata URI
+);
+```
+
+### Policy Enforcement
+
+The `PolicyEngine` enforces three allowlists:
+
+```solidity
+// From PolicyEngine.sol
+function preCheck(address module, address target, bytes4 selector, uint256 value) external view {
+    require(allowedModules[module], "module blocked");
+    require(value <= maxValuePerTx, "value over cap");
+    require(allowedTargets[target], "target blocked");
+    require(allowedSelectors[target][selector], "selector blocked");
+}
+```
+
+Registration example (from `deploy-and-seed-v2-alpha.js`):
+
+```javascript
+await policy.write.setMaxValuePerTx([parseEther("1")]);
+await policy.write.setModuleAllowed([swapModule.address, true]);
+await policy.write.setTargetAllowed([targetAddress, true]);
+await policy.write.setSelectorAllowed([targetAddress, selector, true]);
+```
+
+## Backend Architecture
+
+### Modular Server (`src/server/`)
+
+The backend is organized into a modular structure:
+
+```
+src/server/
+  index.mjs           # Main entry point, request routing, safeHandler wrapper
+  sse.mjs             # SSE client management, broadcast, Last-Event-ID support
+  logger.mjs          # Structured logging (pino)
+  middleware/
+    cors.mjs          # CORS allowlist (built-in, includes apeclaw.ai + localhost variants)
+    rate-limit.mjs    # In-memory sliding-window rate limiter
+    body-limit.mjs    # Request body size limits
+    auth.mjs          # Agent/admin auth (requireSkillWriteAuth, resolveChatAuth)
+  routes/
+    health.mjs        # GET /api/health
+    events.mjs        # SSE stream, backlog, POST /api/events
+    skills.mjs        # Skills search, get, stats, user skillcards
+    clawbots.mjs      # Clawbot list, verify, register, invites
+    chat.mjs          # Chat stream, rooms, messages, reactions
+    v2.mjs            # V2 config, receipt get
+    pod.mjs           # Pod status, stop
+    quotes.mjs        # Quote/bridge-request CRUD, spend-today
+    static.mjs        # Static files, rewrites, allowlist, policy
+  storage/
+    index.mjs         # Storage abstraction (initStorage, getStorage, storageEvents)
+    file-backend.mjs  # File-based storage (default)
+    sqlite-backend.mjs # SQLite storage (APE_CLAW_STORAGE=sqlite)
+```
+
+Key endpoints:
+
+- `GET /api/skills/search`: Merged skill index (seed + imported + user)
+- `POST /api/skillcards/user/add`: Submit new SkillCard (requires auth)
+- `GET /events/backlog?limit=300&since=<ts>`: Historical events
+- `GET /events`: SSE stream with `id:` fields and Last-Event-ID reconnect support
+- `POST /api/clawbots/register`: Register clawbot
+- `POST /api/quotes`: Create quote (centralized state for multi-machine)
+- `GET /api/quotes/spend-today`: Server-side daily spend (global enforcement)
+
+### Event System
+
+Events flow through the storage abstraction and are broadcast via an EventEmitter:
+
+```javascript
+// Storage backend emits events
+storageEvents.emit("telemetryEvent", evt);
+
+// SSE module broadcasts to connected clients
+function sendSse(res, data, id) {
+  if (id !== undefined) res.write(`id: ${id}\n`);
+  res.write(`data: ${JSON.stringify(data)}\n\n`);
+}
+```
+
+## CLI Architecture
+
+The CLI (`src/cli.mjs`) handles:
+
+- **Onchain Operations**: Minting, publishing, executing via viem
+- **Policy Enforcement**: Loading and validating policy.json
+- **Market Discovery**: Reservoir/OpenSea API integration
+- **Bridge Execution**: Relay protocol integration
+- **Telemetry**: Emitting events to backend
+
+Example CLI flow (NFT purchase):
+
+```javascript
+// 1. Quote
+const quote = await quoteBuy({ collection, tokenId, maxPrice });
+
+// 2. Simulate
+const sim = await simulateBuy({ quoteId });
+
+// 3. Execute (with confirm phrase)
+const result = await executeBuy({ quoteId, confirm, execute: true });
+```
+
+## Revenue Flow
+
+SkillNFT royalties flow to PodVault:
+
+1. **Royalty Setup**: `SkillNFT.mintSkillWithRoyalty(parentId, podVault, 500)` sets 5% royalty
+2. **Marketplace Payment**: When skill is sold, marketplace pays royalty to PodVault
+3. **Member Release**: Pod members call `PodVault.releaseNative(member)` to claim their share
+
+```solidity
+// From PodVault.sol
+function pendingNative(address member) public view returns (uint256) {
+    uint256 s = shares[member];
+    if (s == 0) return 0;
+    uint256 totalReceived = address(this).balance + totalReleasedNative;
+    uint256 already = releasedNative[member];
+    return (totalReceived * s) / totalShares - already;
+}
+```
+
+## Network Configuration
+
+ApeClaw supports:
+
+- **ApeChain** (chainId: 33139): Production network
+- **Hardhat Local** (chainId: 31337): Development network
+
+RPC URLs are configured via environment variables:
+
+```bash
+export APE_CLAW_V2_RPC_URL=https://apechain-rpc.example.com
+export APE_CLAW_V2_PRIVATE_KEY=0x...
+```
+
+Deployment records are stored per network in `state/v2-deployments/<network>.json`.