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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(mcp-agent): say which resource the wallet server charges for, and cover the loom and locale helpers
nirholas3579d706ffb9
diff --git a/docs/mcp-agent.md b/docs/mcp-agent.mdindex 2e65f0e7a..c548bd01b 100644--- a/docs/mcp-agent.md+++ b/docs/mcp-agent.md@@ -39,6 +39,17 @@ may be requested by any client (including dynamically-registered ones), and areapproved by name on the consent screen. Ask for them in the `scope` parameter ofthe authorization request; re-authorize an existing connection to add one.+## Calling it without an account (x402)++A client with no OAuth token can still reach the priced tools by paying per+call. The 402 challenge this endpoint issues is scoped to itself: `resource.url`+and every `accepts[].resource` read `https://three.ws/api/mcp-agent`, under the+service name `three.ws Agent MCP`. Facilitators (CDP Bazaar, agentic.market,+x402scan) index it from that same envelope, whose `extensions.bazaar` example is+the read-only `find_services` call, so a crawler probing the documented shape can+never move a caller's funds. `initialize`, `tools/list`, `ping`, and+`getting_started` stay free for plain clients and crawlers.+## How payment works`pay_and_call` reuses the audited SDK payment path — it does **not** hand-rolldiff --git a/prompts/swarm-100/api-top-10.md b/prompts/swarm-100/api-top-10.mddeleted file mode 100644index 70831441e..000000000--- a/prompts/swarm-100/api-top-10.md+++ /dev/null@@ -1,110 +0,0 @@-# API audit: api/*.js batch 10 (10 files)--How to run: paste this file's repo path into a fresh Claude Code chat in this-repository and say "run this work order". This file is fully self-contained:-it depends on no other prompt file anywhere. If neighboring files in-prompts/swarm-100/ are gone, that work is done; if present, ignore them.-Every claim below rots; step 0 re-measures, and what you measure wins.--## Operating clause (binding)--- Read CLAUDE.md first. Its rules override everything, including this file.-- Finish 100% in this session. Never end the turn with a question, an option- list, or an unexecuted plan. A judgment call goes in one line of the final- report; it never becomes a question that halts work.-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real- funds or any irreversible on-chain write, git push or a production deploy,- committing content that references a crypto project other than $THREE, and- destroying unrecoverable data.-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no- commented-out code. Real APIs and real integrations only.-- The em-dash and en-dash characters are banned in everything you write.-- Concurrent agents share this worktree: stage explicit paths only (never a- bare add-everything), and commit finished work promptly.-- Before committing, run: npm run check:rules -- --paths <files you touched>.- It must exit 0.--## Step 0: re-derive the current state--1. Confirm each file below still exists; deleted ones are done, skip them.-2. For each, decide routability: grep its path in vercel.json and read how- server/index.mjs maps filesystem handlers. Routed files get an endpoint- audit; internal modules get a code and test audit.-3. Start a local server for endpoint checks: node server/index.mjs with .env- loaded, on a free PORT if 3000 is busy.--## Task: audit these api files, then fix everything found--Files in this batch:--- api/input-multiview.js-- api/input-photo.js-- api/instant-agent.js-- api/leaderboard.js-- api/locale.js-- api/loom.js-- api/marketplace.js-- api/material-studio.js-- api/mcp-3d.js-- api/mcp-agent.js--For every routed handler:--1. Exercise it with curl against the local server: the success path returns- real data with the correct status; malformed input returns a 4xx JSON- error, never a stack trace or an HTML error page; auth is enforced where- the code intends it; CORS matches neighboring handlers.-2. Hard-rule scan: no mock fallbacks, no fake-data arrays, no stubbed- responses, no unfinished markers. Errors are handled at the boundary and- internal code trusts itself.-3. Do not spend funds or sign anything on-chain while probing. Payment and- trading handlers get their validation and error paths exercised, never a- live settlement.--For every internal (non-routed) module:--4. Something must import it; if nothing does, delete it as dead code (verify- with a repo-wide grep first).-5. Its main path and one failure path must be covered in tests/; add the- missing test if not.--## Definition of done--- [ ] Every listed file has recorded evidence: a curl transcript for routed- handlers, a passing test or a deletion for internal modules.-- [ ] Zero hard-rule violations remain in these files.-- [ ] vitest run passes; npm run check:rules -- --paths <touched files>- exits 0.--## Never blocked--| Blocker | Resolution (act, do not ask) |-|---|---|-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |-| Playwright browser missing | npx playwright install chromium |-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |--## Close out (required)--1. Verify every Definition of done line with the actual command output in- front of you. Never claim a line you did not verify.-2. Commit with explicit paths and a subject that describes the diff (house- style: type(scope): what changed and why a reader cares).-3. Delete this prompt file in that same commit:-- git rm prompts/swarm-100/api-top-10.md-- The shrinking directory is this campaign's only progress ledger; there is- no progress log to update.-4. Final report: what step 0 measured, what changed (file list), evidence per- Definition of done line, and any one-line judgment calls. No trailing- questions, no unexecuted plans.--If a line genuinely cannot pass inside this session (an external party must-respond, or an owner-gated action is the final step), finish everything else,-leave this file in place, and state exactly which line remains and who owns-it. Never delete this file on a partial.diff --git a/tests/api/loom-locale-helpers.test.js b/tests/api/loom-locale-helpers.test.jsnew file mode 100644index 000000000..7ac010472--- /dev/null+++ b/tests/api/loom-locale-helpers.test.js@@ -0,0 +1,208 @@+/**+ * Two public read surfaces whose exported helpers are shared beyond their own+ * handler and had no coverage.+ *+ * api/loom.js is the store behind the world-readable creations gallery, and+ * api/creations.js reads through the same helpers. Its sanitizers and the GLB+ * host allowlist are the only thing between an anonymous POST and an arbitrary+ * URL rendered to every visitor.+ *+ * api/locale.js slices a translation catalog down to the namespaces a page+ * asks for. The slice is CDN-cached per (locale, namespace-set), so namespace+ * normalization has to be order- and duplicate-insensitive or the cache key+ * fragments and the origin serves every permutation.+ */+import { describe, it, expect } from 'vitest';+import { Readable } from 'node:stream';++const {+ sanitizePrompt,+ sanitizeAuthor,+ sanitizeOptionalString,+ validateGlbUrl,+ writeCreation,+ readFeed,+ readOne,+} = await import('../../api/loom.js');+const { normalizeNamespaces, sliceFor, default: localeHandler } = await import(+ '../../api/locale.js',+);++describe('loom sanitizers', () => {+ it('collapses whitespace and control characters in a prompt', () => {+ expect(sanitizePrompt(' a brass telescope on a tripod ')).toBe(+ 'a brass telescope on a tripod',+ );+ expect(sanitizePrompt('abcd')).toBe('abcd');+ });++ it('falls back to the anonymous author and caps the length', () => {+ expect(sanitizeAuthor(' Ada ')).toBe('Ada');+ expect(sanitizeAuthor(' ')).toBe('anon');+ expect(sanitizeAuthor(null)).toBe('anon');+ expect(sanitizeAuthor(42)).toBe('anon');+ expect(sanitizeAuthor('z'.repeat(200))).toHaveLength(40);+ });++ it('returns null rather than an empty string for optional fields', () => {+ expect(sanitizeOptionalString('draft', 40)).toBe('draft');+ expect(sanitizeOptionalString(' ', 40)).toBeNull();+ expect(sanitizeOptionalString(undefined, 40)).toBeNull();+ expect(sanitizeOptionalString('y'.repeat(100), 10)).toHaveLength(10);+ });+});++describe('loom validateGlbUrl', () => {+ it('accepts the hosts a forged GLB can actually live on', () => {+ for (const url of [+ 'https://three.ws/models/a.glb',+ 'https://cdn.three.ws/models/a.glb',+ 'https://pub-abc.r2.dev/forge/a.glb',+ 'https://acct.r2.cloudflarestorage.com/a.glb',+ 'https://replicate.delivery/pbxt/a.glb',+ 'https://raw.githubusercontent.com/o/r/main/a.glb',+ ]) {+ expect(validateGlbUrl(url), url).toBeTruthy();+ }+ });++ it('rejects other hosts, other schemes, and junk', () => {+ for (const url of [+ 'https://evil.example.com/a.glb',+ 'https://three.ws.evil.com/a.glb',+ 'https://notthree.ws/a.glb',+ 'http://three.ws/a.glb',+ 'javascript:alert(1)',+ 'not a url',+ '',+ null,+ { href: 'https://three.ws/a.glb' },+ ]) {+ expect(validateGlbUrl(url), String(url)).toBeNull();+ }+ });+});++describe('loom feed store (in-memory backend, no Redis configured)', () => {+ it('reads a written creation back by id and newest-first from the feed', async () => {+ const rec = {+ id: 'test-creation-1',+ prompt: 'a brass telescope',+ glbUrl: 'https://three.ws/models/test-1.glb',+ previewImageUrl: null,+ author: 'anon',+ tier: null,+ backend: null,+ createdAt: 1_700_000_000_000,+ };+ await writeCreation(rec);+ expect(await readOne('test-creation-1')).toEqual(rec);+ expect(await readOne('no-such-id')).toBeNull();+ expect(await readOne('')).toBeNull();++ const feed = await readFeed(10, NaN);+ expect(feed[0].id).toBe('test-creation-1');+ });++ it('pages backwards with the `before` cursor', async () => {+ await writeCreation({ id: 'older', glbUrl: 'x', createdAt: 1_700_000_000_001 });+ await writeCreation({ id: 'newer', glbUrl: 'y', createdAt: 1_700_000_000_002 });+ const page = await readFeed(10, 1_700_000_000_002);+ expect(page.map((r) => r.id)).not.toContain('newer');+ expect(page.map((r) => r.id)).toContain('older');+ });++ it('clamps the page size into the documented range', async () => {+ expect((await readFeed(0, NaN)).length).toBeLessThanOrEqual(120);+ expect((await readFeed(9999, NaN)).length).toBeLessThanOrEqual(120);+ });+});++describe('locale normalizeNamespaces', () => {+ it('is order- and duplicate-insensitive so one cache key serves every caller', () => {+ expect(normalizeNamespaces('nav,play')).toEqual(['nav', 'play']);+ expect(normalizeNamespaces('play,nav')).toEqual(['nav', 'play']);+ expect(normalizeNamespaces(' play , nav , play ')).toEqual(['nav', 'play']);+ });++ it('drops anything that is not a plain namespace identifier', () => {+ expect(normalizeNamespaces('nav,../../etc/passwd,play')).toEqual(['nav', 'play']);+ expect(normalizeNamespaces('a-b,c.d,e/f')).toEqual([]);+ expect(normalizeNamespaces('')).toEqual([]);+ expect(normalizeNamespaces(null)).toEqual([]);+ });+});++describe('locale sliceFor', () => {+ it('returns only the requested sections of a real catalog', () => {+ const body = sliceFor('en', ['nav']);+ expect(body).toBeTruthy();+ expect(Object.keys(JSON.parse(body))).toEqual(['nav']);+ });++ it('omits a section the catalog does not carry instead of nulling it', () => {+ const parsed = JSON.parse(sliceFor('en', ['nav', 'definitely_not_a_section']));+ expect(parsed).not.toHaveProperty('definitely_not_a_section');+ });++ it('returns null for a catalog file that does not exist', () => {+ expect(sliceFor('zz-not-a-locale', ['nav'])).toBeNull();+ });+});++function makeRes() {+ return {+ statusCode: 200,+ headers: {},+ body: null,+ setHeader(name, value) {+ this.headers[String(name).toLowerCase()] = value;+ },+ getHeader(name) {+ return this.headers[String(name).toLowerCase()];+ },+ end(body) {+ this.body = body ?? null;+ },+ };+}++function makeReq(url) {+ const req = Readable.from([]);+ req.method = 'GET';+ req.url = url;+ req.headers = {};+ return req;+}++describe('GET /api/locale', () => {+ it('serves the requested slice with a cacheable response', async () => {+ const res = makeRes();+ await localeHandler(makeReq('/api/locale?code=en&ns=nav'), res);+ expect(res.statusCode).toBe(200);+ expect(res.headers['cache-control']).toContain('s-maxage=');+ expect(Object.keys(JSON.parse(res.body))).toEqual(['nav']);+ });++ it('rejects an unpublished locale without reflecting an unbounded probe', async () => {+ const res = makeRes();+ const probe = 'A'.repeat(500);+ await localeHandler(makeReq(`/api/locale?code=${probe}&ns=nav`), res);+ expect(res.statusCode).toBe(400);+ expect(JSON.parse(res.body).error).toBe('unknown_locale');+ expect(res.body.length).toBeLessThan(200);+ });++ it('requires at least one namespace and caps how many can be asked for', async () => {+ const missing = makeRes();+ await localeHandler(makeReq('/api/locale?code=en'), missing);+ expect(missing.statusCode).toBe(400);+ expect(JSON.parse(missing.body).error).toBe('missing_ns');++ const tooMany = makeRes();+ const ns = Array.from({ length: 70 }, (_, i) => `ns${i}`).join(',');+ await localeHandler(makeReq(`/api/locale?code=en&ns=${ns}`), tooMany);+ expect(tooMany.statusCode).toBe(400);+ expect(JSON.parse(tooMany.body).error).toBe('too_many_ns');+ });+});