agentlili 0.1.0 → 0.1.1

package/README.md

@@ -1,8 +1,8 @@
 # AI Agent Wallet — Solana Devnet
 
-An autonomous AI agent wallet for Solana that manages wallets, executes DeFi operations, and interacts with on-chain protocols — all through natural language. Supports multiple independent agents, each with their own isolated keypair, security policy, and decision-making context.
+An autonomous AI agent wallet for Solana that manages wallets, executes DeFi operations, and interacts with on-chain protocols — all through natural language. Secured by Turnkey hardware-backed key custody, on-chain PDA vault policy enforcement, and Kora gasless transactions. Supports multiple independent agents, each with their own isolated wallet, security policy, and decision-making context.
 
-Built with Vercel AI SDK, Solana Agent Kit v2, and Next.js 15.
+Built with Vercel AI SDK, Solana Agent Kit v2, Next.js 15, and Turnkey secure enclave.
 
 ---
 
@@ -10,16 +10,16 @@ Built with Vercel AI SDK, Solana Agent Kit v2, and Next.js 15.
 
 | Judging Criteria | What to Look At | Command / Link |
 |---|---|---|
-| **C1: Functional Demo** | Autonomous DeFi agent with 93 tools, SSE activity feed, one-click demos | `pnpm dev` → click any demo card, or `SKIP_LLM=1 pnpm headless-demo` |
-| **C2: Security & Key Mgmt** | FROST 2-of-3 threshold signing, PolicyParticipant, PDA vault, spending limits, HMAC audit chain | `pnpm frost-demo` (no API keys needed), Security tab in UI, [SECURITY.md](SECURITY.md) |
-| **C3: Documentation** | 1,800+ line deep dive, 22 Mermaid diagrams, machine-readable SKILLS.md | [DEEP_DIVE.md](DEEP_DIVE.md) (architecture + threat model), [SKILLS.md](SKILLS.md) |
-| **C4: Multi-Agent Scalability** | 12-agent stress test, fleet health dashboard, bulk provisioning | `pnpm stress-test` (12 agents, 76 ops, 0% errors) |
+| **C1: Functional Demo** | Autonomous DeFi agent with 93 tools, SSE activity feed, one-click demos | `pnpm dev` → Dashboard |
+| **C2: Security & Key Mgmt** | Turnkey secure enclave, PDA vault, Kora gasless, spending limits, HMAC audit chain | Security tab in UI, [Security & Threat Model](../resources/docs/00-overview.md#threat-model-summary) |
+| **C3: Documentation** | 11-chapter deep dive, Mermaid diagrams, machine-readable SKILLS.md | [Documentation set](../resources/docs/00-overview.md) (architecture + threat model), [SKILLS.md](SKILLS.md) |
+| **C4: Multi-Agent Scalability** | Fleet health dashboard, bulk provisioning, agent-to-agent transfers | `pnpm dev` → Agent Monitor tab |
 
 ### Key Differentiators
-- **1,106 passing tests** (zero-mock) — run `pnpm test` to verify
-- **18-tool MCP server** for Claude Desktop integration — `pnpm mcp`
-- **5-layer security**: FROST threshold → PolicyParticipant → PDA vault → Kora gasless → Jito MEV protection
-- **93 DeFi tools** via Solana Agent Kit v2 (vs typical 2–4)
+- **Comprehensive test suite** — run `pnpm test` to verify
+- **MCP server** for Claude Desktop integration — `pnpm mcp`
+- **3-layer security**: Turnkey secure enclave → PDA vault → Kora gasless
+- **93 DeFi tools** via Solana Agent Kit v2 (vs typical 2-4)
 
 ---
 
@@ -29,8 +29,8 @@ Built with Vercel AI SDK, Solana Agent Kit v2, and Next.js 15.
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                            WEB UI (Next.js)                              │
 │  Chat Interface │ Wallet Panel │ Portfolio │ Agent Monitor │ Analytics   │
-│  Activity Feed  │ Demo Launcher │ Strategy │ Backup        │ Lifecycle   │
-│  Security Tab: FROST Mgmt │ Audit Log Viewer │ Fleet Health │ Spending   │
+│  Activity Feed  │ Demo Launcher │ Backup        │ Lifecycle                │
+│  Security Tab: Vault Mgmt │ Audit Log Viewer │ Fleet Health │ Spending   │
 └───────────────────────────────────┬─────────────────────────────────────┘
                                     │  HTTP + SSE
 ┌───────────────────────────────────▼─────────────────────────────────────┐
@@ -43,14 +43,14 @@ Built with Vercel AI SDK, Solana Agent Kit v2, and Next.js 15.
 │                              AGENT CORE                                  │
 │  LLM Provider (Claude / GPT-4)    Solana Agent Kit v2 (93 DeFi Tools)   │
 │  Multi-step Tool Chaining         Success Detection Pipeline             │
-│  Strategy Presets (3 risk levels) Per-Agent SSE Event Bus               │
+│  Per-Agent SSE Event Bus          Scheduled & Recurring Payments        │
 └───────────────────────────────────┬─────────────────────────────────────┘
                                     │
 ┌───────────────────────────────────▼─────────────────────────────────────┐
 │                           WALLET LAYER                                   │
-│  WalletManager: AES-256-GCM + scrypt KDF                                 │
-│  KeypairWallet: Ed25519 signing, devnet airdrop, SPL token support       │
-│  Isolated per-agent state: keypair, tx log, spending ledger, lifecycle   │
+│  Turnkey Secure Enclave: hardware-backed key custody (no keys in memory)   │
+│  BIP-32 HD wallet: per-agent sub-accounts at m/44'/501'/{index}'/0'      │
+│  PDA Vault: on-chain spending limits, program allowlists, cooldowns      │
 └──────────────────┬────────────────────────────────┬─────────────────────┘
                    │ direct SOL fees                │ gasless (Kora)
                    │                                │
@@ -70,8 +70,6 @@ Built with Vercel AI SDK, Solana Agent Kit v2, and Next.js 15.
 
 ## Quick Start (Under 3 Minutes)
 
-> **No API key?** Skip to the [Headless Demo](#headless-demo-no-browser-required) below — runs the full wallet + FROST demo without any external keys.
-
 ### Prerequisites
 
 - Node.js 18+
@@ -93,7 +91,11 @@ node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 # 4. Add your LLM API key to .env (optional — headless demo works without it)
 # ANTHROPIC_API_KEY=sk-ant-api03-{your-key-here}
 
-# 5. Start the web app
+# 5. (Optional) Set a scheduler secret for the /api/cron/tick endpoint
+# CRON_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
+# CRON_JOB_API_KEY=your-cron-job-org-api-key   # For webhook automations
+
+# 6. Start the web app
 pnpm dev
 ```
 
@@ -108,19 +110,6 @@ Once the app is running:
 3. Watch the **Activity Feed** (bottom of page) stream live tool calls and transaction signatures in real time
 4. Click any transaction signature → opens directly in **Solana Explorer** on devnet (every TX is a clickable link to the explorer)
 
-### Headless Demo (No Browser Required)
-
-```bash
-# Wallet + airdrop + on-chain verify — NO API key needed
-SKIP_LLM=1 pnpm headless-demo
-
-# FROST threshold signing demo — NO API key needed
-pnpm frost-demo
-
-# Full 7-phase demo with autonomous LLM execution (requires ANTHROPIC_API_KEY)
-pnpm headless-demo
-```
-
 ### Gasless Transactions (Optional — Kora Paymaster)
 
 To enable gasless transactions where agents don't need SOL for fees:
@@ -136,13 +125,6 @@ KORA_FEE_MODE=sponsored
 
 See [kora_server/README.md](../kora_server/README.md) for full setup details.
 
-### Multi-Agent Scalability Test
-
-```bash
-pnpm stress-test                 # 12 concurrent agents, 76 ops, 0% errors — empirical proof
-STRESS_AGENTS=20 pnpm stress-test  # Scale to 20 agents
-```
-
 ### CLI Mode
 
 ```bash
@@ -155,47 +137,43 @@ pnpm cli
 
 ### Autonomous Agent Wallet (C1)
 
-- **Programmatic wallet creation** — `Keypair.generate()` with automatic devnet airdrop on creation
-- **AES-256-GCM encrypted key storage** — per-wallet scrypt salt, stored at rest on disk
+- **Turnkey-backed wallet creation** — BIP-32 HD sub-accounts derived from user's Turnkey wallet, hardware-backed key custody
+- **No keys in memory** — private keys never leave the Turnkey secure enclave; signing happens server-side via Turnkey API
 - **Automatic transaction signing** — no human approval required; agent signs and submits
 - **93 DeFi tools** via Solana Agent Kit v2 (TokenPlugin + DefiPlugin)
 - **Multi-step tool chaining** — up to 10 sequential tool calls per LLM request
 - **Natural language → on-chain execution** — "swap 0.1 SOL for USDC" → Jupiter swap tx
 - **Real-time SSE activity feed** — live streaming of every tool call, tx signature, and balance change as they happen
-- **One-click demo mode** — 3 pre-built autonomous DeFi scenarios; spawns wallet, funds it, and executes strategy while you watch
+- **Scheduled & recurring payments** — schedule future SOL transfers or set up daily/weekly/monthly recurring payments, all persisted to DB and auto-executed by the scheduler
+- **One-click demo mode** — 3 pre-built autonomous DeFi scenarios; spawns wallet, funds it, and executes while you watch
 - **Portfolio view** — aggregate SOL + SPL holdings across all agent wallets with USD values (Jupiter Price API)
 - **Transaction analytics dashboard** — success/failure rates, SOL spent, tool usage charts, hourly timeline
-- **Security tab** — dedicated sidebar panel with FROST wallet management, HMAC-chained audit log viewer with integrity verification, fleet health dashboard (grade distribution, agents needing attention), and per-wallet spending limits editor
+- **Security tab** — dedicated sidebar panel with vault management, HMAC-chained audit log viewer with integrity verification, fleet health dashboard (grade distribution, agents needing attention), and per-wallet spending limits editor
 
 ### Security & Key Management (C2)
 
-- **AES-256-GCM encryption** — all private keys encrypted at rest; GCM auth tag detects ciphertext tampering
-- **scrypt key derivation** — N=2^14 storage, N=2^17 backup; memory-hard against brute force
+**3-layer defense-in-depth: Turnkey secure enclave → PDA vault → Kora gasless**
+
+- **Turnkey secure enclave** — hardware-backed key custody; private keys never leave the enclave, never exist in application memory. One HD wallet per user, BIP-32 sub-accounts per agent at `m/44'/501'/{unixSeconds}'/0'`
+- **PDA vault (on-chain)** — Anchor program at `Bm2NAhhpw1iopQqba8ywXi9NH27EmyyV62wddDfpjMoF` enforces spending limits, program allowlists, and cooldowns at the Solana runtime level. Seeds: `[b"vault", agent_pubkey]`
+- **Kora gasless transactions** — paymaster co-signing; agents transact without holding SOL for fees. Fee payer separation means agent keys never touch gas funds. Supports sponsored (free), margin, and fixed token fee modes. See `kora_server/` for local setup
 - **HMAC-SHA256 request signing** — every write/delete request signed with a derived key; replays blocked via 5-minute window
 - **Per-IP sliding-window rate limiting** — 12 per-bucket presets; prevents API abuse and DoS
 - **Spending limits** — configurable max SOL per-transaction and per-day per agent; blocks over-budget tool calls
 - **HMAC-chained audit log** — append-only JSONL with each entry hashing the previous; tamper detection via `verifyAuditIntegrity()`
-- **Password-protected wallet backup** — export encrypted JSON, restore from file; scrypt N=2^17 for strong backup protection
 - **Agent lifecycle enforcement** — paused/terminated agents are blocked from executing at the API level (403 AGENT_NOT_ACTIVE)
 - **Input sanitization** — HTML/XSS stripped from labels, wallet IDs validated by strict hex regex, JSON parse errors handled gracefully
-- **FROST threshold signing (RFC 9591)** — 2-of-3 Ed25519 threshold signatures; no single key compromise can sign
-- **PolicyParticipant enforcement** — 5 independent checks (program allowlist, per-tx/daily limits, intent matching, suspicious patterns, cooldown)
-- **Proactive share refresh** — rotate key shares without changing on-chain address; forward secrecy
-- **PDA Vault (on-chain)** — Anchor program enforces spending limits and program allowlists at the Solana runtime level
 - **Jito MEV protection** — bundle submission bypasses public mempool to prevent sandwich attacks (mainnet-beta only; devnet transactions use standard RPC submission)
-- **Kora gasless transactions** — optional paymaster co-signing; agents transact without holding SOL for fees. Supports sponsored (free), margin, and fixed token fee modes. See `kora_server/` for local setup.
+- **Agent isolation** — separate wallet sub-account, RPC context, tx log, spending ledger, lifecycle state per agent
 
 ### Documentation & Deep Dive (C3)
 
-- [DEEP_DIVE.md](./DEEP_DIVE.md) — 1,700+ line architecture deep dive with 22 Mermaid diagrams (17 sections):
-  - System overview, separation of concerns, multi-agent isolation, key management flow
-  - Transaction signing sequence, HMAC authentication flow, wallet backup pipeline
-  - Agent lifecycle state machine, real-time event architecture, threat model visualization
-  - Section 12: FROST threshold signing architecture | Section 13: Threat model progression
-  - Section 14: Why this is a spending account | Section 15: Prompt injection defense
-  - Section 16: Transaction lifecycle (CU simulation, commitment strategy, retry)
-  - **Section 17: Full system architecture — the 5-layer defense-in-depth synthesizing argument**
-- [SECURITY.md](./SECURITY.md) — Full STRIDE threat model, 12 mitigated threats (T1–T12), 5 accepted risks, cryptographic inventory table, attack surface map, production hardening roadmap
+- [Documentation set](../resources/docs/00-overview.md) — 11-chapter architecture deep dive covering:
+  - Wallet architecture & adapter pattern, cryptographic internals (Argon2id + scrypt KDFs)
+  - Agent reasoning, multi-step tool chaining, 8-scope spend guard layer
+  - PDA vault on-chain enforcement, Turnkey HSM integration, threat model
+  - CLI reference, MCP/AI tools integration, Studio dashboard
+  - Agent evolution (audit trails, memory, self-reflection), Kora gasless transactions
 - [BENCHMARK.md](./BENCHMARK.md) — Stress test results: 12 concurrent agents, 76 ops, **0% error rate**, 1.8s total, wallet isolation proof, memory profile, extrapolation to 100+ agents
 - [SKILLS.md](./SKILLS.md) — Complete agent capability catalog (93 tools across 11 categories) for judges/agents to read
 - [VIDEO_SCRIPT.md](./VIDEO_SCRIPT.md) — Structured 7-scene, 5-minute demo recording script
@@ -203,18 +181,15 @@ pnpm cli
 
 ### Multi-Agent Scalability (C4)
 
-- **Independent wallet isolation** — each agent has its own keypair, RPC context, tx log, spending ledger, strategy config, and lifecycle state; cryptographically verified (see [BENCHMARK.md](./BENCHMARK.md))
+- **Independent wallet isolation** — each agent has its own keypair, RPC context, tx log, spending ledger, and lifecycle state; cryptographically verified (see [BENCHMARK.md](./BENCHMARK.md))
 - **Agent monitoring dashboard** — live view of all agents: balance, status (idle/executing/error/paused/terminated), last action, daily spending bar, success rate
 - **Agent lifecycle management** — pause, resume, or terminate agents with proper cleanup; terminated is terminal; transition history persisted
 - **Agent-to-agent transfers** — one agent can send SOL or SPL tokens to another agent's wallet; lifecycle and spending checks enforced
-- **Strategy presets** — conservative / balanced / aggressive risk profiles; affects slippage, max position size, leverage rules, protocol selection
-- **Stress test** — `pnpm stress-test` spawns 12 concurrent agents, runs 7 phases (create, airdrop, balance, transfers, lifecycle, strategy, monitoring); **76 ops / 0 failures / 1.8s** on Solana devnet; see [BENCHMARK.md](./BENCHMARK.md) for full results
-
 ### UI/UX Polish
 
 - **Dark/light theme toggle** — CSS variable system with localStorage persistence, FOUC-free SSR
 - **Loading skeletons** — shimmer placeholders for wallet panel, portfolio, agent monitor, analytics
-- **Toast notifications** — success/error/info toasts for every user action (wallet create, airdrop, strategy change, backup, transfer, lifecycle transition)
+- **Toast notifications** — success/error/info toasts for every user action (wallet create, airdrop, backup, transfer, lifecycle transition)
 - **Copy-to-clipboard** — animated clipboard → checkmark for wallet addresses, tx signatures, mint addresses
 - **Solana Explorer deep links** — every tx signature and wallet address links to Solana Explorer with correct cluster
 - **Mobile responsive layout** — tested on iOS (safe area insets, `h-dvh`, 16px input zoom prevention)
@@ -234,10 +209,10 @@ WALLET_ENCRYPTION_KEY=<key> pnpm mcp
 ```json
 {
   "mcpServers": {
-    "stng-defi": {
+    "agentlili": {
       "command": "npx",
       "args": ["tsx", "src/mcp/server.ts"],
-      "cwd": "/path/to/stng_defi_wallets",
+      "cwd": "/path/to/agentlili",
       "env": {
         "WALLET_ENCRYPTION_KEY": "<your-key>",
         "SOLANA_RPC_URL": "https://api.devnet.solana.com"
@@ -247,9 +222,9 @@ WALLET_ENCRYPTION_KEY=<key> pnpm mcp
 }
 ```
 
-**18 tools** across 5 categories: wallet operations, FROST threshold signing, agent lifecycle management, spending & security controls, and portfolio analytics.
+Tools across wallet operations, agent lifecycle management, spending & security controls, and portfolio analytics.
 
-**5 guided prompts**: portfolio overview, security audit, agent creation, fleet health check, and wallet investigation.
+**Guided prompts**: portfolio overview, security audit, agent creation, fleet health check, and wallet investigation.
 
 ---
 
@@ -280,8 +255,6 @@ All write/delete endpoints verify HMAC-SHA256 signatures when `X-Signature` head
 | GET | `/api/wallet/:id/history` | Paginated transaction history |
 | GET | `/api/wallet/:id/limits` | Get spending limits (maxPerTx, maxPerDay, dailySpent) |
 | PUT | `/api/wallet/:id/limits` | Update spending limits. Body: `{ "maxPerTx": 0.5, "maxPerDay": 2 }` |
-| GET | `/api/wallet/:id/strategy` | Get risk strategy (conservative/balanced/aggressive) |
-| PUT | `/api/wallet/:id/strategy` | Set strategy. Body: `{ "strategyId": "conservative" }` |
 | POST | `/api/wallet/:id/backup` | Export password-protected encrypted backup |
 | PUT | `/api/wallet/:id/backup` | Restore wallet from backup file + password |
 | POST | `/api/wallet/:id?action=rekey` | Re-encrypt wallet with fresh salt + IV (forward secrecy) |
@@ -293,31 +266,27 @@ All write/delete endpoints verify HMAC-SHA256 signatures when `X-Signature` head
 | GET | `/api/agents` | List all agents with SOL balances |
 | POST | `/api/agents` | Spawn agent. Body: `{ "label": "Bot Name" }` — auto-airdrops |
 | POST | `/api/agents/bulk` | Batch-create up to 20 agents. Body: `{ "labels": ["Bot1", "Bot2"] }` — returns array of walletIds |
-| GET | `/api/agents/monitor` | Full monitoring data. Params: `?status=active&strategy=conservative&limit=10` |
+| GET | `/api/agents/monitor` | Full monitoring data. Params: `?status=active&limit=10` |
 | POST | `/api/agents/transfer` | Agent-to-agent transfer. Body: `{ "fromAgent", "toAgent", "amount", "mint?" }` |
 | GET | `/api/agents/:id/lifecycle` | Get lifecycle state and transition history |
 | PUT | `/api/agents/:id/lifecycle` | Transition state. Body: `{ "state": "paused" \| "active" \| "terminated" }` |
 | POST | `/api/agents/:id/run` | Trigger one autonomous execution cycle — no human prompt needed |
 | GET | `/api/agents/health-summary` | Aggregate security health across all agents: avg score, grade distribution, attention list |
 
-### FROST Threshold Signing
+### Kora Gasless Transactions
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/frost` | List all FROST wallets (metadata only) |
-| POST | `/api/frost` | Create FROST wallet. Body: `{ "threshold": 2, "totalShares": 3, "labels": [...] }` |
-| GET | `/api/frost/:id` | Get FROST wallet details + security health |
-| DELETE | `/api/frost/:id` | Delete FROST wallet and all encrypted shares |
-| POST | `/api/frost/:id/sign` | Execute FROST signing ceremony. Body: `{ "message", "participantIds", "intent?" }` |
-| POST | `/api/frost/:id/refresh` | Refresh shares (proactive key rotation) — group key unchanged |
+| GET | `/api/kora/status` | Kora paymaster status: enabled/disabled, fee mode, payer address, supported tokens |
+| POST | `/api/kora/estimate` | Estimate transaction fee. Body: `{ "transaction": "<base64>", "feeToken?": "<mint>" }` |
 
-### Kora Gasless Transactions
+### Scheduler
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/kora/status` | Kora paymaster status: enabled/disabled, fee mode, payer address, supported tokens |
-| POST | `/api/kora/estimate` | Estimate transaction fee. Body: `{ "transaction": "<base64>", "feeToken?": "<mint>" }` |
-| POST | `/api/frost/:id/sign-kora` | FROST sign + Kora co-sign and submit. Body: `{ "transaction", "participantIds", "intent?", "feeToken?" }` |
+| POST | `/api/cron/tick` | Trigger scheduler tick. Auth: `Bearer CRON_SECRET`. Body: `{ "walletIds?": [...], "cluster?": "devnet", "dryRun?": false }` |
+
+Call this from any external scheduler (cron-job.org, GitHub Actions, systemd timer, etc.) to process scheduled payments and subscriptions. Supports wallet filtering and dry-run mode.
 
 ### Chat & Operations
 
@@ -375,17 +344,17 @@ curl localhost:3000/api/agents/monitor
 
 Three pre-built autonomous scenarios launch with one click (UI or API):
 
-| Scenario | Strategy | Description |
-|----------|----------|-------------|
-| `defi-explorer` | Balanced | Check balance, fetch SOL price, swap to USDC, summarize portfolio |
-| `multi-protocol` | Balanced | Diversify across staking, swaps, and liquidity provision |
-| `trading-bot` | Aggressive | Market analysis, conditional trades, position reporting |
+| Scenario | Description |
+|----------|-------------|
+| `defi-explorer` | Check balance, fetch SOL price, swap to USDC, summarize portfolio |
+| `multi-protocol` | Diversify across staking, swaps, and liquidity provision |
+| `trading-bot` | Market analysis, conditional trades, position reporting |
 
 ```bash
 # List scenarios
 curl localhost:3000/api/demo
 
-# Launch a scenario (creates wallet, airdrops, sets strategy, returns prompt)
+# Launch a scenario (creates wallet, airdrops, returns prompt)
 curl -X POST localhost:3000/api/demo \
   -H 'Content-Type: application/json' \
   -d '{"scenarioId": "trading-bot"}'
@@ -393,41 +362,14 @@ curl -X POST localhost:3000/api/demo \
 
 ---
 
-## Running the Demos
-
-```bash
-# Basic demo: wallet creation + airdrop + transaction signing
-pnpm demo
-
-# DeFi demo: AI agent autonomously executes multi-step DeFi operations
-pnpm demo:defi
-
-# Multi-agent demo: 3 concurrent agents with timing + memory metrics
-pnpm demo:multi
-
-# Stress test: 12 concurrent agents across 7 phases, with isolation verification
-pnpm stress-test
-# Override agent count: STRESS_AGENTS=20 pnpm stress-test
-```
-
-See [DEMO.md](./DEMO.md) for a detailed judge-friendly walkthrough.
-
----
-
 ## Test Suite
 
 ```bash
-# Unit + API tests (~4s)
+# Unit tests
 pnpm test
 
-# With V8 coverage report
-pnpm test --coverage
-
-# On-chain tests against local validator (requires solana-test-validator)
-pnpm validator:start && pnpm test:localnet
-
-# E2E tests with Playwright (16 specs — requires dev server)
-pnpm test:e2e
+# On-chain tests against Surfpool (requires Surfpool on localhost:8899)
+pnpm test:surfpool
 
 # Integration tests against devnet (requires RUN_INTEGRATION=1)
 pnpm test:integration
@@ -439,63 +381,25 @@ pnpm typecheck
 pnpm build
 ```
 
-**Test breakdown (1,000+ total across 4 layers, zero mocks):**
-
-| Layer | Tests | Files | What it covers |
-|-------|------:|------:|----------------|
-| Unit + API (Vitest) | 743 | 44 | Core library, API routes, tool count, stress-lite — **zero mocks** |
-| FROST (Vitest) | 140 | 11 | Key management, ceremony, signer, policy, nonce, vault, share refresh, SATI, refresh triggers, e2e |
-| Kora (Vitest) | 19 | 4 | Config, client, transaction prep, FROST+Kora adapter, gasless on-chain SOL transfers |
-| Localnet (Vitest) | 40 | 6 | Real SOL transfers, balance queries, airdrops, health, full 17-phase workflow, **12 LLM vulnerability tests** — against `solana-test-validator` |
-| E2E (Playwright) | 16 | 1 | Wallet creation → airdrop → chat → on-chain verification |
-| Integration (devnet) | 55+ | 1 | Airdrop, SOL transfer, multi-agent, DeFi tool invocation via Solana Agent Kit |
-
-Run localnet tests: `pnpm test:localnet` (requires `solana-test-validator`)
-Run integration tests (requires devnet RPC): `pnpm test:integration`
-
-**CI/CD:** GitHub Actions pipeline runs lint → test → typecheck → build → E2E on every push to main.
-
-Test categories:
-- Wallet encryption/decryption (AES-256-GCM, scrypt, round-trips, tamper detection)
-- Wallet CRUD and multi-agent isolation
-- Rate limiter logic, per-bucket presets, memory management
-- Spending limits enforcement, daily window, SOL extraction
-- HMAC request signing (sign, verify, replay protection, timing-safe compare)
-- Audit log integrity chain (HMAC, filtering, pagination)
-- Agent lifecycle state machine (transitions, terminal state, executable gate)
-- Agent-to-agent transfer validation, lifecycle + spending guards
-- Agent monitor aggregation, status derivation, sorting
-- Portfolio aggregation, Jupiter price integration, allocation calc
-- Analytics (time series, category breakdown, top tools, wallet activity)
-- Demo scenarios (data integrity, prompt quality, strategy assignments)
-- SSE event bus (client management, wallet filtering, reconnect, keep-alive)
-- Toast notifications, copy button, loading skeletons (jsdom)
-- Theme system, mobile responsive layout (jsdom)
-- Error boundaries: RPC down, empty wallet, rate limit, lifecycle block, missing env
-- E2E: full wallet → airdrop → chat → on-chain verification (Playwright)
+Tests run via `pnpm test` (unit) and `pnpm test:surfpool` (on-chain). See [CLAUDE.md](./CLAUDE.md) for full test runner details and Surfpool cheatcodes.
 
 ---
 
 ## Security
 
-See [SECURITY.md](./SECURITY.md) for the full threat model. Key properties:
+See [Security & Threat Model](../resources/docs/00-overview.md#threat-model-summary) for the full threat model. Key properties:
 
 | Property | Implementation |
 |----------|----------------|
-| Key storage | AES-256-GCM + scrypt (N=2^14, r=8, p=1) per-wallet salt |
-| Key export | Never — no API endpoint reads raw private key bytes |
-| Key re-encryption | `POST /api/wallet/:id?action=rekey` rotates salt+IV; old ciphertext becomes stale |
-| Backup | AES-256-GCM + scrypt (N=2^17) under user password |
+| Key custody | Turnkey secure enclave — hardware-backed, keys never in application memory |
+| Wallet derivation | BIP-32 HD wallet; per-agent sub-accounts at `m/44'/501'/{unixSeconds}'/0'` |
+| On-chain enforcement | PDA vault (Anchor program) — spending limits, program allowlists, cooldowns |
+| Gasless transactions | Kora paymaster co-signs as fee payer; agents don't need SOL for gas |
 | API authentication | HMAC-SHA256 + 5-minute replay window |
 | Rate limiting | Per-IP sliding window, 12 per-bucket presets |
-| Spending controls | Configurable per-tx + per-day SOL caps, enforced server-side |
+| Spending controls | Configurable per-tx + per-day SOL caps, enforced server-side + on-chain |
 | Audit trail | HMAC-SHA256 integrity chain, append-only JSONL |
-| FROST threshold signing | 2-of-3 RFC 9591 shares — no single point of compromise |
-| PolicyParticipant | Independent TX validation: program allowlist, spending limits, intent matching |
-| PDA Vault | Anchor program enforces on-chain spending limits and CPI allowlist |
-| Gasless transactions | Kora paymaster co-signs as fee payer; agents don't need SOL for gas |
-| Prompt injection defense | PolicyParticipant validates TX semantics, not natural language (see SECURITY.md §6) |
-| Agent isolation | Separate keypair, RPC context, ledger, lifecycle state per agent |
+| Agent isolation | Separate wallet sub-account, RPC context, ledger, lifecycle state per agent |
 | Path traversal | Wallet IDs validated as 8-char hex by strict regex before any file I/O |
 | XSS prevention | HTML stripped from all user-supplied labels |
 
@@ -508,10 +412,9 @@ See [SECURITY.md](./SECURITY.md) for the full threat model. Key properties:
 | Framework | Next.js 15 (App Router) |
 | AI | Vercel AI SDK 4 (`streamText`, `useChat`, `maxSteps: 10`) |
 | Solana | solana-agent-kit 2.0 — TokenPlugin (26 tools) + DefiPlugin (70 tools) |
-| Encryption | Node.js `crypto` — AES-256-GCM, scrypt KDF |
-| FROST | `@substrate-system/frost` v0.0.9 — RFC 9591 Ed25519 threshold signatures |
-| Gasless Txs | Kora paymaster (`@solana/kora` SDK) — fee payer co-signing, token fee abstraction |
-| On-chain | 2 Anchor programs — `agent_vault` (PDA policy) + `agent_sati` (on-chain identity) |
+| Key Custody | Turnkey secure enclave — hardware-backed HD wallet, BIP-32 sub-accounts |
+| Gasless Txs | Kora paymaster — fee payer co-signing, token fee abstraction |
+| On-chain | Anchor program — `agent_vault` (PDA vault: spending limits, program allowlists) |
 | UI | React 19, Tailwind CSS 4, pure SVG charts |
 | Testing | Vitest (unit), Playwright (E2E), @vitest/coverage-v8 |
 | CI/CD | GitHub Actions — lint, test, typecheck, build, E2E |
@@ -524,8 +427,8 @@ See [SECURITY.md](./SECURITY.md) for the full threat model. Key properties:
 | File | Contents |
 |------|----------|
 | [DEMO.md](./DEMO.md) | Judge-friendly demo walkthrough (start here) |
-| [DEEP_DIVE.md](./DEEP_DIVE.md) | 1,500+ line architecture deep dive with 22 Mermaid diagrams |
-| [SECURITY.md](./SECURITY.md) | STRIDE threat model, cryptographic inventory, attack surface map |
+| [Docs set](../resources/docs/00-overview.md) | 11-chapter architecture deep dive with diagrams |
+| [Threat Model](../resources/docs/00-overview.md#threat-model-summary) | Threat model, cryptographic inventory, attack surface map |
 | [BENCHMARK.md](./BENCHMARK.md) | Stress test: 12 agents, 76 ops, 0% errors, 1.8s, isolation proof |
 | [SKILLS.md](./SKILLS.md) | Complete agent capability catalog (93 tools, for agents to read) |
 | [VIDEO_SCRIPT.md](./VIDEO_SCRIPT.md) | 7-scene, 5-minute demo recording script |

package/dist/agent-7OQQFXF5.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+// src/lib/agent.ts
+import { SolanaAgentKit } from "solana-agent-kit";
+import TokenPlugin from "@solana-agent-kit/plugin-token";
+import DefiPlugin from "@solana-agent-kit/plugin-defi";
+import { createVercelAITools } from "solana-agent-kit";
+var CORE_ACTION_NAMES = /* @__PURE__ */ new Set([
+  "GET_TOKEN_DATA",
+  "GET_TOKEN_DATA_OR_INFO_BY_TICKER_OR_SYMBOL",
+  "FETCH_PRICE",
+  "STAKE_WITH_JUPITER",
+  "TRADE",
+  "CREATE_LIMIT_ORDER",
+  "CANCEL_LIMIT_ORDERS",
+  "GET_OPEN_LIMIT_ORDERS",
+  "GET_LIMIT_ORDER_HISTORY",
+  "BALANCE_ACTION",
+  "TOKEN_BALANCE_ACTION",
+  "GET_TPS",
+  "CLOSE_EMPTY_TOKEN_ACCOUNTS",
+  "REQUEST_FUNDS",
+  "TRANSFER",
+  "PYTH_FETCH_PRICE",
+  "RUGCHECK",
+  "WALLET_ADDRESS",
+  "LEND_ASSET",
+  "LULO_LEND",
+  "LULO_WITHDRAW"
+]);
+function createAgent(wallet, config, rpcUrl) {
+  const agentConfig = {};
+  if (config.llmProvider === "openai") {
+    agentConfig.OPENAI_API_KEY = config.llmApiKey;
+  }
+  if (config.kora) {
+    agentConfig.KORA_ENDPOINT = config.kora.endpoint;
+    if (config.kora.apiKey) agentConfig.KORA_API_KEY = config.kora.apiKey;
+    if (config.kora.feeToken) agentConfig.KORA_FEE_TOKEN = config.kora.feeToken;
+  }
+  const agent = new SolanaAgentKit(wallet, rpcUrl ?? "http://localhost:8899", agentConfig).use(TokenPlugin).use(DefiPlugin);
+  const toolMode = process.env.CHAT_TOOL_MODE ?? "core";
+  const actions = toolMode === "all" ? agent.actions : agent.actions.filter((a) => CORE_ACTION_NAMES.has(a.name));
+  const tools = createVercelAITools(agent, actions);
+  return { agent, tools };
+}
+export {
+  CORE_ACTION_NAMES,
+  createAgent
+};
+//# sourceMappingURL=agent-7OQQFXF5.js.map

package/dist/agent-7OQQFXF5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/agent.ts"],"sourcesContent":["import { SolanaAgentKit } from \"solana-agent-kit\";\nimport TokenPlugin from \"@solana-agent-kit/plugin-token\";\nimport DefiPlugin from \"@solana-agent-kit/plugin-defi\";\nimport { createVercelAITools } from \"solana-agent-kit\";\nimport type { ToolSet } from \"ai\";\nimport type { AppConfig } from \"./config\";\nimport type { LiliWalletInterface } from \"./lili\";\n\n/**\n * ~20 core actions that cover the most common DeFi operations.\n * Keeps tool-definition payload under Groq's token limit (~4K vs ~15K for all 93).\n */\nexport const CORE_ACTION_NAMES = new Set([\n  \"GET_TOKEN_DATA\",\n  \"GET_TOKEN_DATA_OR_INFO_BY_TICKER_OR_SYMBOL\",\n  \"FETCH_PRICE\",\n  \"STAKE_WITH_JUPITER\",\n  \"TRADE\",\n  \"CREATE_LIMIT_ORDER\",\n  \"CANCEL_LIMIT_ORDERS\",\n  \"GET_OPEN_LIMIT_ORDERS\",\n  \"GET_LIMIT_ORDER_HISTORY\",\n  \"BALANCE_ACTION\",\n  \"TOKEN_BALANCE_ACTION\",\n  \"GET_TPS\",\n  \"CLOSE_EMPTY_TOKEN_ACCOUNTS\",\n  \"REQUEST_FUNDS\",\n  \"TRANSFER\",\n  \"PYTH_FETCH_PRICE\",\n  \"RUGCHECK\",\n  \"WALLET_ADDRESS\",\n  \"LEND_ASSET\",\n  \"LULO_LEND\",\n  \"LULO_WITHDRAW\",\n]);\n\nexport function createAgent(\n  wallet: LiliWalletInterface,\n  config: AppConfig,\n  rpcUrl?: string,\n): {\n  agent: SolanaAgentKit;\n  tools: ToolSet;\n} {\n  const agentConfig: Record<string, string | number | boolean> = {};\n\n  if (config.llmProvider === \"openai\") {\n    agentConfig.OPENAI_API_KEY = config.llmApiKey;\n  }\n\n  // Pass Kora endpoint to agent config when enabled\n  if (config.kora) {\n    agentConfig.KORA_ENDPOINT = config.kora.endpoint;\n    if (config.kora.apiKey) agentConfig.KORA_API_KEY = config.kora.apiKey;\n    if (config.kora.feeToken) agentConfig.KORA_FEE_TOKEN = config.kora.feeToken;\n  }\n\n  const agent = new SolanaAgentKit(wallet, rpcUrl ?? \"http://localhost:8899\", agentConfig)\n    .use(TokenPlugin)\n    .use(DefiPlugin);\n\n  const toolMode = process.env.CHAT_TOOL_MODE ?? \"core\";\n  const actions =\n    toolMode === \"all\"\n      ? agent.actions\n      : agent.actions.filter((a: { name: string }) => CORE_ACTION_NAMES.has(a.name));\n\n  const tools = createVercelAITools(agent, actions) as unknown as ToolSet;\n\n  return { agent, tools };\n}\n"],"mappings":";;;AAAA,SAAS,sBAAsB;AAC/B,OAAO,iBAAiB;AACxB,OAAO,gBAAgB;AACvB,SAAS,2BAA2B;AAS7B,IAAM,oBAAoB,oBAAI,IAAI;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAEM,SAAS,YACd,QACA,QACA,QAIA;AACA,QAAM,cAAyD,CAAC;AAEhE,MAAI,OAAO,gBAAgB,UAAU;AACnC,gBAAY,iBAAiB,OAAO;AAAA,EACtC;AAGA,MAAI,OAAO,MAAM;AACf,gBAAY,gBAAgB,OAAO,KAAK;AACxC,QAAI,OAAO,KAAK,OAAQ,aAAY,eAAe,OAAO,KAAK;AAC/D,QAAI,OAAO,KAAK,SAAU,aAAY,iBAAiB,OAAO,KAAK;AAAA,EACrE;AAEA,QAAM,QAAQ,IAAI,eAAe,QAAQ,UAAU,yBAAyB,WAAW,EACpF,IAAI,WAAW,EACf,IAAI,UAAU;AAEjB,QAAM,WAAW,QAAQ,IAAI,kBAAkB;AAC/C,QAAM,UACJ,aAAa,QACT,MAAM,UACN,MAAM,QAAQ,OAAO,CAAC,MAAwB,kBAAkB,IAAI,EAAE,IAAI,CAAC;AAEjF,QAAM,QAAQ,oBAAoB,OAAO,OAAO;AAEhD,SAAO,EAAE,OAAO,MAAM;AACxB;","names":[]}

package/dist/chat-bindings-RYWDO7CX.js

@@ -0,0 +1,111 @@
+import {
+  prisma
+} from "./chunk-R7JN32HS.js";
+
+// src/lib/messaging/command-parser.ts
+var WALLET_ID_PATTERN = /^[a-f0-9-]{8}$/;
+function isValidWalletId(id) {
+  return WALLET_ID_PATTERN.test(id);
+}
+
+// src/lib/messaging/chat-bindings.ts
+async function getBinding(platform, chatId) {
+  const row = await prisma.chatBinding.findUnique({
+    where: { platform_chatId: { platform, chatId } }
+  });
+  if (!row) return null;
+  return {
+    platform: row.platform,
+    chatId: row.chatId,
+    agentId: row.agentId,
+    muted: row.muted,
+    createdAt: row.createdAt.toISOString()
+  };
+}
+async function bindChat(platform, chatId, agentId) {
+  if (!isValidWalletId(agentId)) {
+    throw new Error(`Invalid wallet ID format: ${agentId}. Must be 8 hex characters.`);
+  }
+  const row = await prisma.chatBinding.upsert({
+    where: { platform_chatId: { platform, chatId } },
+    create: {
+      platform,
+      chatId,
+      agentId,
+      muted: false
+    },
+    update: {
+      agentId
+      // Keep existing muted state on update — handled by not overwriting it
+    }
+  });
+  return {
+    platform: row.platform,
+    chatId: row.chatId,
+    agentId: row.agentId,
+    muted: row.muted,
+    createdAt: row.createdAt.toISOString()
+  };
+}
+async function unbindChat(platform, chatId) {
+  try {
+    await prisma.chatBinding.delete({
+      where: { platform_chatId: { platform, chatId } }
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function setMuted(platform, chatId, muted) {
+  try {
+    await prisma.chatBinding.update({
+      where: { platform_chatId: { platform, chatId } },
+      data: { muted }
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function getBindingsForAgent(agentId) {
+  const rows = await prisma.chatBinding.findMany({
+    where: { agentId, muted: false }
+  });
+  return rows.map((row) => ({
+    platform: row.platform,
+    chatId: row.chatId,
+    agentId: row.agentId,
+    muted: row.muted,
+    createdAt: row.createdAt.toISOString()
+  }));
+}
+async function getBindingsForProfile(profileId) {
+  const agents = await prisma.agent.findMany({
+    where: { ownerProfileId: profileId },
+    select: { id: true }
+  });
+  if (agents.length === 0) return [];
+  const rows = await prisma.chatBinding.findMany({
+    where: {
+      muted: false,
+      agentId: { in: agents.map((agent) => agent.id) }
+    }
+  });
+  return rows.map((row) => ({
+    platform: row.platform,
+    chatId: row.chatId,
+    agentId: row.agentId,
+    muted: row.muted,
+    createdAt: row.createdAt.toISOString()
+  }));
+}
+export {
+  bindChat,
+  getBinding,
+  getBindingsForAgent,
+  getBindingsForProfile,
+  setMuted,
+  unbindChat
+};
+//# sourceMappingURL=chat-bindings-RYWDO7CX.js.map