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(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.md
index 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 are
approved by name on the consent screen. Ask for them in the `scope` parameter of
the 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-roll
diff --git a/prompts/swarm-100/api-top-10.md b/prompts/swarm-100/api-top-10.md
deleted file mode 100644
index 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.js
new file mode 100644
index 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');
+ });
+});