Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(structure): correct stale migration-pending claims for whitelist and allowance rows, fix vscode-x402 version drift, complete row 619

nirholas86b4516f323f
diff --git a/STRUCTURE.md b/STRUCTURE.md
index f005b2b15..97b6e7ab3 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -278,8 +278,8 @@ packages, a generated standalone GitHub mirror). See
| Metaplex Agent Registry deploy (Genesis-333 mint for everyone) | [pages/deploy-onchain.html](pages/deploy-onchain.html) + [src/deploy-onchain.js](src/deploy-onchain.js) `→ /deploy-onchain`, shared builders [packages/metaplex-agent-mcp/src/lib/](packages/metaplex-agent-mcp/src/lib) (published as `@three-ws/metaplex-agent-mcp`, also in the official MCP registry as `io.github.nirholas/metaplex-agent`) | Live | Mint any agent into the Metaplex Agent Registry in the exact Genesis 333 shape: data: URI metadata, verified creator, 5% royalties, immutable metadata, EIP-8004 identity with `model.uri` + `x402Support`. The page signs with the user's own wallet (Phantom/Solflare/Backpack, `signAllTransactions`) through the same-origin RPC proxy; a wallet that advertises Solana transaction v1 over Wallet Standard instead signs create + register as ONE atomic v1 transaction (Genesis-shape mints overflow v0's 1,232 bytes but fit v1's 4,096), built by [api/_lib/solana/transaction-v1.js](api/_lib/solana/transaction-v1.js); the MCP server gives agents the identical mint with their own key (preview-first, `confirm:true` gated) plus a prepare/send lane for external wallets. Both consume one isomorphic builder library, and [tests](packages/metaplex-agent-mcp/test/genesis-shape.test.mjs) pin the output byte-for-byte to the live Genesis #332 URIs. Devnet is a free rehearsal lane end-to-end. A mainnet deploy also pays a flat 0.02 SOL fee to the $THREE buyback wallet, halved at 50k $THREE in the paying wallet and waived at 250k, disclosed in every preview and carried inside the create transaction ([packages/metaplex-agent-mcp/src/lib/three.js](packages/metaplex-agent-mcp/src/lib/three.js)); the `three_status` tool prices it against any wallet. |
| Solana Memo viewer | [public/onchain/index.html](public/onchain/index.html) `→ /onchain` | Live | A shareable, wallet-free reader for public Solana transaction Memos. It accepts a signature or Solscan transaction URL, requests version-1 transactions directly from the mainnet RPC, previews the supported raster data URI formats, provides a file download or text-copy action, and keeps each result tied to its signer, timestamp, and Solscan source. It refuses to execute active formats such as SVG because Memo content is untrusted. Docs: [docs/solana.md](docs/solana.md#viewing-files-written-in-a-transaction-memo). |
| Onchain agent wallets (spending allowances, not private keys) | [packages/onchain-agent-wallets/](packages/onchain-agent-wallets) (published as `@three-ws/onchain-agent-wallets`, MCP registry `io.github.nirholas/onchain-agent-wallets`) | Live | Give an agent a Solana wallet without giving it the money. Funds sit in a vault token account the OWNER owns, derived deterministically from the owner address plus the agent id (`createWithSeed(owner, "oaw1:<agent>")`); the agent holds only a capped SPL Token delegation over it, so the token program itself refuses any spend past the ceiling and decrements it on every transfer. Guardrails on top (per-tx, rolling daily, recipient and host allowlists, expiry, pause, confirm-above threshold) are enforced before signing, and every decision including refusals lands in a local ledger. `pay_x402` probes the price unpaid, checks it against the guardrails, tops the agent up for exactly that amount, pays, and leaves it empty. Owner actions need no key on the machine: they come back as unsigned transactions for Phantom/Solflare/Ledger. [Delegation tests](packages/onchain-agent-wallets/test/token-delegation.test.mjs) run the real SPL Token program in process and assert that 61 against a remaining allowance of 60 fails on-chain. |
-| Destination whitelist (cooldown allowlist for agent wallet payouts) | Engine [api/_lib/destination-whitelist.js](api/_lib/destination-whitelist.js), endpoint [api/wallet-whitelist/index.js](api/wallet-whitelist/index.js), MCP tools [api/_mcp/tools/whitelist.js](api/_mcp/tools/whitelist.js), cron [api/cron/whitelist-activate.js](api/cron/whitelist-activate.js), hub tab [src/agent-wallet-hub/tabs/whitelist.js](src/agent-wallet-hub/tabs/whitelist.js), migration `api/_lib/migrations/20261010160000_destination_whitelist.sql` | Built; migration not yet applied to production | New payout addresses wait out an owner-set cooldown (24h default, 1h floor), need step-up to add, are proposal-only for agents, cancel in one click and remove instantly. Enforced in the shared spend guards for transfers, tips, bridge, payouts and withdrawals. Docs: [docs/destination-whitelist.md](docs/destination-whitelist.md). Tests: [tests/destination-whitelist.test.js](tests/destination-whitelist.test.js) |
-| Owner-funded agent budgets (on-chain allowances) | lib [api/_lib/onchain-allowance.js](api/_lib/onchain-allowance.js), store and guard hook [api/_lib/onchain-allowance-store.js](api/_lib/onchain-allowance-store.js), endpoint [api/agents/solana-allowance.js](api/agents/solana-allowance.js) `-> /api/agents/:id/solana/allowance`, guard wiring [api/agent/guard.js](api/agent/guard.js), hub tab [src/agent-wallet-hub/tabs/allowance.js](src/agent-wallet-hub/tabs/allowance.js), devnet proof [scripts/allowance-devnet-proof.mjs](scripts/allowance-devnet-proof.mjs), migration [api/_lib/migrations/20261023170000_agent_onchain_allowances.sql](api/_lib/migrations/20261023170000_agent_onchain_allowances.sql) | Built; migration not yet applied to production; recurring behind `ALLOWANCE_RECURRING_ENABLED` | The owner keeps funds in their own wallet and signs one transaction creating a capped, expiring fixed delegation to the agent wallet via the Solana Subscriptions and Allowances program. The remaining on-chain allowance is a hard ceiling in the spend guards, and the Budget tab shows cap, spent, remaining and expiry with one-click revoke. Docs: [docs/agent-allowance-budgets.md](docs/agent-allowance-budgets.md). Tests: [tests/onchain-allowance.test.js](tests/onchain-allowance.test.js) |
+| Destination whitelist (cooldown allowlist for agent wallet payouts) | Engine [api/_lib/destination-whitelist.js](api/_lib/destination-whitelist.js), endpoint [api/wallet-whitelist/index.js](api/wallet-whitelist/index.js), MCP tools [api/_mcp/tools/whitelist.js](api/_mcp/tools/whitelist.js), cron [api/cron/whitelist-activate.js](api/cron/whitelist-activate.js), hub tab [src/agent-wallet-hub/tabs/whitelist.js](src/agent-wallet-hub/tabs/whitelist.js), migration `api/_lib/migrations/20261010160000_destination_whitelist.sql` | Live; migration applied to production | New payout addresses wait out an owner-set cooldown (24h default, 1h floor), need step-up to add, are proposal-only for agents, cancel in one click and remove instantly. Enforced in the shared spend guards for transfers, tips, bridge, payouts and withdrawals. Docs: [docs/destination-whitelist.md](docs/destination-whitelist.md). Tests: [tests/destination-whitelist.test.js](tests/destination-whitelist.test.js) |
+| Owner-funded agent budgets (on-chain allowances) | lib [api/_lib/onchain-allowance.js](api/_lib/onchain-allowance.js), store and guard hook [api/_lib/onchain-allowance-store.js](api/_lib/onchain-allowance-store.js), endpoint [api/agents/solana-allowance.js](api/agents/solana-allowance.js) `-> /api/agents/:id/solana/allowance`, guard wiring [api/agent/guard.js](api/agent/guard.js), hub tab [src/agent-wallet-hub/tabs/allowance.js](src/agent-wallet-hub/tabs/allowance.js), devnet proof [scripts/allowance-devnet-proof.mjs](scripts/allowance-devnet-proof.mjs), migration [api/_lib/migrations/20261023170000_agent_onchain_allowances.sql](api/_lib/migrations/20261023170000_agent_onchain_allowances.sql) | Live; migration applied to production; recurring behind `ALLOWANCE_RECURRING_ENABLED` | The owner keeps funds in their own wallet and signs one transaction creating a capped, expiring fixed delegation to the agent wallet via the Solana Subscriptions and Allowances program. The remaining on-chain allowance is a hard ceiling in the spend guards, and the Budget tab shows cap, spent, remaining and expiry with one-click revoke. Docs: [docs/agent-allowance-budgets.md](docs/agent-allowance-budgets.md). Tests: [tests/onchain-allowance.test.js](tests/onchain-allowance.test.js) |
| Capped burner (agent spends alone up to a cap, owner confirms the rest) | classifier [api/_lib/burner-tier.js](api/_lib/burner-tier.js) (shared by guard and editor), guard in [api/_lib/agent-trade-guards.js](api/_lib/agent-trade-guards.js), approvals + decision trail in [api/_lib/approvals.js](api/_lib/approvals.js), owner wallet signatures [api/_lib/owner-sign.js](api/_lib/owner-sign.js), hub tab [src/agent-wallet-hub/tabs/burner.js](src/agent-wallet-hub/tabs/burner.js), signing UI [src/approvals-page.js](src/approvals-page.js) | Live | Policy `{ autoMaxUsd, dailyAutoMaxUsd, confirmAboveUsd, expiryMinutes }` on `PUT /api/agents/:id/solana/limits`. Over the cap a spend becomes a pending approval, not a failure; doc: [docs/approvals.md](docs/approvals.md#the-capped-burner). Tests: [tests/burner-tier.test.js](tests/burner-tier.test.js), [tests/burner-approvals.test.js](tests/burner-approvals.test.js) |
| On-chain contracts (Solidity + Solana) | [contracts/](contracts) · [contracts/README.md](contracts/README.md) | Mixed: `ThreeWSPayments` + `ThreeWSFactory` live on BSC/Base/Arbitrum, the rest in-repo | Every contract and program three.ws owns, in one Foundry project plus three Anchor programs. ERC-8004 identity/reputation/validation registries (reference implementations of the canonical deployments the platform actually reads), the live x402 USDC receiver and its CREATE2 vanity factory, `AgentPayments`, `GreenfieldVault`, `WorldMoves`, and the Solana `skill_license` / `agent_invocation` programs. `forge test` covers the Solidity set with 242 tests across 8 suites; the Solana side is covered by the LiteSVM row below. Deploy status per contract and the address provenance per chain: [contracts/DEPLOYMENTS.md](contracts/DEPLOYMENTS.md) |
| Contract audit pack | [contracts/AUDIT-README.md](contracts/AUDIT-README.md), invariants [specs/ECONOMY_CONTRACT_INVARIANTS.md](specs/ECONOMY_CONTRACT_INVARIANTS.md), threat model [specs/ECONOMY_CONTRACT_THREAT_MODEL.md](specs/ECONOMY_CONTRACT_THREAT_MODEL.md), static analysis [contracts/audit/](contracts/audit) | In-repo | Everything a review firm needs on day one for the reputation, royalty and delegation contracts: scope + deploy status per contract, stable invariant ids with a positive and a negative test each, an assets/actors/failure-modes threat model, and committed Slither + Clippy output with every finding fixed or dispositioned in writing |
@@ -406,7 +406,7 @@ packages, a generated standalone GitHub mirror). See
| x402 auto-paying fetch | [packages/x402-fetch/](packages/x402-fetch) | Published as `@three-ws/x402-fetch` (v1.0.2) | Drop-in fetch wrapper that auto-pays x402 challenges |
| AgentCore payments MCP | [packages/agentcore-payments-mcp/](packages/agentcore-payments-mcp) | Published as `@three-ws/agentcore-payments-mcp` (v0.1.2) | MCP server for platform-managed agent payment sessions |
| VS Code 3D extension | [packages/vscode-3d/](packages/vscode-3d) | In-repo (v0.2.0, not yet on the Marketplace) | Makes `.glb` and `.gltf` first-class in VS Code: the file opens in a three.js viewer as an editor tab (orbit, animation clips with a scrub bar, wireframe, skeleton, grid, PNG snapshot, looping turntable GIF) with Draco, KTX2 and meshopt decoders shipped inside the extension so a compressed avatar renders offline. The report panel and the status bar reuse [src/gltf-inspect.js](src/gltf-inspect.js), the same inspector behind /validation, in the extension host, so a model is never uploaded to be measured. **Animate** searches the 2,874-clip motion library (`/api/animations/library`) and retargets the pick onto the open rig inside the webview with [src/animation-retarget.js](src/animation-retarget.js); **Bake clip** writes the retargeted clip into a copy of the GLB as real glTF channels ([packages/vscode-3d/src/bake-clip.js](packages/vscode-3d/src/bake-clip.js), glTF-Transform, meshopt re-encoded). Text to motion goes through `/api/forge-motion`. **Refine** calls the free `refine_model` tool and keeps the version lineage per file. **Optimize** runs dedup/prune/weld/resample/meshopt (and quantize) locally. **Compare with the committed version** reads `HEAD` out of git and diffs it with [packages/glb-diff](packages/glb-diff), opening both versions side by side. **Check quality** posts the webview render to `/api/forge-quality-check`. Language features for `<agent-3d>` in HTML/JSX/Vue/Svelte/Astro/Markdown/PHP ([packages/vscode-3d/src/embed-language.js](packages/vscode-3d/src/embed-language.js)): diagnostics with quick fixes (no source, no size, unpinned `latest`, missing or stale SRI hash against `/agent-3d/versions.json`, unknown attributes, bad enum values), hovers, completions, CodeLenses. Generation, rigging and the gallery call the free public lanes (`/api/mcp-studio`, `/api/forge-gallery`); the embed command pins the current library release and its SRI hash. Doc: [docs/vscode.md](docs/vscode.md). Tests: `npm --prefix packages/vscode-3d test` (activates the bundled extension against a stand-in host that now covers language providers and diagnostics, proves the retarget-then-bake round trip on the committed cz.glb, and unit tests every module against local HTTP servers). |
-| VS Code x402 extension | [packages/vscode-x402/](packages/vscode-x402) | In-repo (v0.2.0, not yet published to npm) | VS Code extension for the x402 bazaar |
+| VS Code x402 extension | [packages/vscode-x402/](packages/vscode-x402) | In-repo (v0.2.2, not yet on the Marketplace) | VS Code extension for the x402 bazaar |
| Meta-Allocator (the ETF of degens) | [pages/meta-allocator.html](pages/meta-allocator.html) + [src/meta-allocator.js](src/meta-allocator.js) `→ /meta-allocator`, brain [api/_lib/meta-allocator.js](api/_lib/meta-allocator.js), endpoint [api/meta-allocator.js](api/meta-allocator.js) | Live (non-custodial planning) | Spreads a budget across the top verified pump.fun leader agents, ranked by risk-adjusted on-chain track record (win rate, realized ROI, peak-to-trough max drawdown from `agent_sniper_positions`) and diversified across derived correlation groups, then returns a rebalance rule. Free-first `llmComplete` shaping with a deterministic same-shape fallback so it never fails. Returns a plan (weights + suggested sizes), never a transaction; users act one leader at a time via [/vaults](pages/vaults.html). Doc: [docs/meta-allocator.md](docs/meta-allocator.md). |
| Alpha-drip (a leader prices their signal latency) | Ladder rules [api/\_lib/alpha-drip.js](api/_lib/alpha-drip.js), fanout half [api/\_lib/copy-drip-runtime.js](api/_lib/copy-drip-runtime.js), measured edge half-life [api/\_lib/alpha-drip-stats.js](api/_lib/alpha-drip-stats.js), endpoint [api/copy/alpha-drip.js](api/copy/alpha-drip.js) `-> /api/copy/alpha-drip`, leader editor [src/alpha-drip-panel.js](src/alpha-drip-panel.js) mounted on [/dashboard/copy](src/dashboard-next/pages/copy.js), copier seat on the trader page [src/copy-panel.js](src/copy-panel.js), schema [api/\_lib/migrations/20260903235500\_copy\_alpha\_drip.sql](api/_lib/migrations/20260903235500_copy_alpha_drip.sql) | Live (off unless a leader turns it on) | The $THREE sink on the copy rail: a leader sets how long each holder tier waits before a copy intent is revealed to them, so the thing being sold is latency rather than only a share of the profit. Two rules are structural and enforced server-side: a higher tier can never wait longer than a lower one, and **a drip delays the reveal, never the record** (the intent row is written in full at fanout time and the public track record is untouched, so there are no hidden trades). The copier is shown the seat their balance buys BEFORE they subscribe, not after; a locked intent renders as a countdown that unlocks in place, and `POST /api/copy/executions` refuses an unreleased one in the same statement that changes its status, so the guard cannot be raced. Tier size caps are applied after the copy engine has sized and gated the order, never before, so the copier's own caps still bind first. The edge half-life the fairness warning judges a ladder against is measured from the leader's own profitable closes, and is null rather than guessed below five of them. Release runs inside [api/cron/copy-fanout.js](api/cron/copy-fanout.js) rather than a second cron, so the release cadence is the fanout cadence. Doc: [docs/alpha-drip.md](docs/alpha-drip.md). Tests: [tests/alpha-drip.test.js](tests/alpha-drip.test.js) |
| Ghost-copy (paper-copy a leader) | [pages/ghost-copy.html](pages/ghost-copy.html) + [src/ghost-copy.js](src/ghost-copy.js) `→ /ghost-copy`, simulator [api/_lib/ghost-copy.js](api/_lib/ghost-copy.js), endpoint [api/pump/ghost-copy.js](api/pump/ghost-copy.js), tests [tests/ghost-copy.test.js](tests/ghost-copy.test.js) | Live (paper only, zero custody) | The bridge between the leaderboard and actually copying someone. Pick a verified trader agent, a budget and a window, and it replays that agent's real closed on-chain round-trips (`agent_sniper_positions`) against a wallet that does not exist, sizing every order through `planCopyOrder`, the SAME function the live [copy-fanout cron](api/cron/copy-fanout.js) uses, so the result is what the copy engine would actually have generated rather than a marketing figure. Deliberately unflattering: P&L per trade is derived from exact chain lamports (never the stored pct column), losing round-trips all count, the ghost wallet has a real cash constraint so capital locked in an open copy blocks the next one, every skip carries a machine reason plus a human sentence, and the leader's still-open positions are marked at THEIR last on-chain quote and reported as unrealized outside the realized headline. Needs no account, no wallet, no signature and no funded signer, so it ships ahead of any custody decision; state lives in the query string so a result is deep-linkable and shareable. Converts into [/vaults](pages/vaults.html) for real money. Doc: [docs/ghost-copy.md](docs/ghost-copy.md). |
@@ -616,7 +616,7 @@ array. Runbook: [docs/contributing.md](docs/contributing.md#publishing-packages-
| `@three-ws/brownout` | [packages/brownout/](packages/brownout) | [docs/brownout.md](docs/brownout.md) | Data-provenance headers plus request-scoped fault injection: a response says which upstream its data came from and how fresh it is, and a caller can break those upstreams on purpose to prove the integration degrades the way its contract claims. The companion to the resilience audit above, which grades call sites statically; this proves the behaviour at runtime. Tests: [packages/brownout/test/](packages/brownout/test) |
| `@three-ws/agents` | [packages/agents-sdk/](packages/agents-sdk) | `/api/v1`, route logic in [api/_lib/agents-v1/](api/_lib/agents-v1) | Typed TypeScript client for the v1 Agents API (agents, chat, runs with SSE streaming, skills, automations, wallet, swap) with retries, idempotency keys, typed errors and a client-side confirm gate on fund-moving calls. tsup build, zero runtime dependencies. Not published yet, and most routes it calls are not mounted under `/api/v1` yet; its README lists which answer |
| `@three-ws/mcp-policy` | [packages/mcp-policy/](packages/mcp-policy) | [api/_mcp/policy.js](api/_mcp/policy.js), [api/mcp-policy.js](api/mcp-policy.js) | The tool policy table every MCP server enforces: each tool's group and tier, financial tools off by default and gated on a named confirm flag plus a fresh preview id. `./stdio` wires a stdio server in one call. Workspace package, not published yet |
-| `@three-ws/agent` | [packages/agent-cli/](packages/agent-cli) | `@three-ws/agent-runtime`, `/api/mcp-agent`, `/api/mcp`, `/api/v1` | Local agent runtime: the agent loop on your own machine with workspace file tools, a resource-limited shell sandbox, the three.ws MCP tools, per-class approvals (financial always asks) and SQLite sessions with full-text search. The runtime core is in tree; the `three-ws-agent` CLI and TUI entry points it declares are not yet |
+| `@three-ws/agent` | [packages/agent-cli/](packages/agent-cli) | `@three-ws/agent-runtime`, `/api/mcp-agent`, `/api/mcp`, `/api/v1` | Local agent runtime: the agent loop on your own machine with workspace file tools, a resource-limited shell sandbox, the three.ws MCP tools, per-class approvals (financial always asks) and SQLite sessions with full-text search. The runtime core is in tree; the `three-ws-agent` CLI and TUI entry points it declares are not yet published to npm (both `three-ws-agent` and `@three-ws/agent` 404 on the registry) |
| Wallet and payment accessibility (W3AG) | Address formatter [src/shared/address.js](src/shared/address.js), modal focus trap [src/shared/focus-trap.js](src/shared/focus-trap.js), used by [src/payment-modal.js](src/payment-modal.js), [src/wallet/connect-button.js](src/wallet/connect-button.js), [src/vaults.js](src/vaults.js) | Live | One formatter draws the short address and announces the full one in groups of four; one trap gives every wallet dialog an inert background, Tab cycling, Escape and focus return. Docs: [docs/accessibility.md](docs/accessibility.md). Tests: [tests/e2e/w3ag-wallet.spec.js](tests/e2e/w3ag-wallet.spec.js), [tests/shared-address.test.js](tests/shared-address.test.js) |
## Where things actually live