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.
Task 01 — Verify the Agora foundation
Status: shipped. The migration is applied in production,
@three-ws/solana-agentbuilds (tsup, Apache-2.0), and the read model is routed and covered bytests/agora-read-model.test.js. Two things moved since this was written: the endpoint now has five actions (task, the live Arena/Guild roster, joined the four below), and the migration runner grewnpm run db:check(the deploy gate, exit 4 while anything is pending) andnpm run db:restamp(re-records a comment-only edit to an already-applied file).api/_lib/db.jsanswers an unconfigured or unreachable database with a retryable 503 rather than a 500, so an emptyDATABASE_URLno longer reads as a code bug. Kept as the build record.
Goal: Get the Phase-1 foundation (data model + economy read API) actually
running and proven green against the real DB and the real x402 bazaar, and
unblock the local SDK build so the AgenC stack is importable. After this task,
/api/agora/* returns correct, real data and the next tasks have solid ground.
Depends on: nothing. This is the first task.
Context to read first
docs/agora.md— the spec.docs/agora/tasks/00-INDEX.md— shared context + guardrails.api/_lib/migrations/20260629020000_agora_world.sql— the tables.api/agora/[action].js— the endpoint you're verifying.api/_lib/db.js,package.json(db:migrate,db:status,db:bootstrap).solana-agent-sdk/package.json(build =tsup).
Background
Phase 1 already wrote three artifacts (spec, migration, economy API). They have
not been applied/smoke-tested. The board and pulse lanes should be live
immediately (they read the real x402 bazaar); citizens/passport should return
honest empty states until the life engine (Task 02) seeds them. The Solana write
SDK may be unbuilt locally (tsup bus-errors in constrained sandboxes).
Build (scope)
- Apply the migration.
npm run db:statusto see pending, thennpm run db:migrateto apply20260629020000_agora_world.sql. Confirm bothagora_citizensandagora_activityexist with their indexes. IfDATABASE_URLpoints at the canonical Neon DB, apply there; otherwise use the configured dev DB. Do not drop/recreate anything else. - Unblock the SDK build. Build
@three-ws/solana-agentsodist/exists (cd solana-agent-sdk && npm run build). Iftsupbus-errors, diagnose: try raising Node memory, a single-threaded esbuild, or emit viatscas a fallback without changing the committed build tooling for everyone (a local emit is fine; if a tooling change is genuinely needed, make it minimal and justify it). The success bar:node -e "import('@three-ws/solana-agent')"resolves. If the sandbox genuinely cannot build native esbuild, document the exact failure and confirm the package builds in CI instead — then proceed. - Smoke-test all four actions against a running API (
npm run dev, or invoke the handler directly). Capture real output:GET /api/agora/board→ real x402 services inservices[];tasks[]empty (no postings yet);empty:false.GET /api/agora/pulse→ honest zeros,coin.symbol === "$THREE",empty:true.GET /api/agora/citizens→{ count:0, citizens:[], empty:true }.GET /api/agora/passport?id=<random-uuid>→404 not_found.
- Fix anything the smoke test surfaces. Shapes must match the contracts in the endpoint. No console errors.
Out of scope
Seeding citizens, posting tasks, any UI. Those are later tasks. Do not write fake
rows to make citizens/pulse look populated — empty is correct here.
Definition of Done
-
agora_citizens+agora_activityexist in the target DB with all indexes from the migration;npm run db:statusshows the migration applied. -
@three-ws/solana-agentimports successfully in Node (or a written, reproduced explanation of the sandbox-only build failure + CI confirmation). - All four
/api/agora/*actions return the documented shapes against real data, captured in the task report (paste the JSON). -
board.servicescontains real bazaar entries;pulse.empty === true;citizens.empty === true; unknownpassport404s. - No console errors/warnings from Agora code.
Verification
npm run db:status
npm run db:migrate
cd solana-agent-sdk && npm run build && node -e "import('@three-ws/solana-agent').then(()=>console.log('SDK ok'))"; cd ..
npm run dev # then, in another shell:
curl -s localhost:3000/api/agora/board | head -c 1200
curl -s localhost:3000/api/agora/pulse
curl -s localhost:3000/api/agora/citizens
curl -s "localhost:3000/api/agora/passport?id=00000000-0000-0000-0000-000000000000" -i | head -1
Guardrails
- Migrations are forward-only; don't edit an already-applied migration file — add a new one if a change is needed.
$THREEis the only coin; the placeholder mint in any test is synthetic.- Stage explicit paths. If committing, push to
threewsonly; this is internal plumbing so no changelog entry.