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
fix(chat): answer a throttled free lane with capacity, not "sign in"
nirholas57fe53493330
diff --git a/api/chat.js b/api/chat.jsindex 2db8f9f5a..326dd6cb1 100644--- a/api/chat.js+++ b/api/chat.js@@ -490,7 +490,24 @@ export default wrap(async (req, res) => {return error(res, 503, 'chat_unavailable', 'no chat provider is configured');}if (anonymous && !ANON_PROVIDERS.has(route.name)) {- return error(res, 401, 'unauthorized', 'sign in to chat with the agent');+ // Reaching here means an anon-eligible provider IS configured (the missing-key+ // case already 401'd above) but pickProvider still landed outside the anon set.+ // The pin above requests a free lane, and a requested provider only loses that+ // pin to an *auth* cooldown, so this is a free tier whose key came back+ // 401/402/403 with no other free lane left to take it: a capacity problem, not+ // an authentication one. Answering 401 told signed-out visitors to "sign in"+ // for a throttle they cannot fix, and the assistant widget (whose whole free+ // lane is anonymous, with no sign-in anywhere in it) surfaced that as its dead+ // end. Same shape as the exhausted-chain branch below, so every client backs+ // off and retries on one code path.+ res.setHeader('Retry-After', '20');+ return error(+ res,+ 503,+ 'rate_limited',+ 'The AI chat is at capacity right now. Please try again in a few seconds.',+ { providers_tried: [...ANON_PROVIDERS].filter((name) => cooldown.has(name)), retry_after: 20 },+ );}// When inference is billed to the host's key (the caller supplied none for thediff --git a/docs/assistant-widget.md b/docs/assistant-widget.mdindex 946197b7c..b41b01166 100644--- a/docs/assistant-widget.md+++ b/docs/assistant-widget.md@@ -124,7 +124,7 @@ Ask your agent something like "build a 3D assistant widget named Aria with an oc- The launcher and panel are plain DOM injected by [`public/assistant/v1.js`](https://github.com/nirholas/three.ws/blob/main/public/assistant/v1.js), the minified build of the [`@three-ws/assistant`](https://github.com/nirholas/three.ws/tree/main/assistant-sdk) loader (no dependencies, idempotent). The avatar, chat, and speech run inside an iframe on `https://three.ws/assistant-frame`, so your page never sees model keys and the frame never sees your DOM.- The frame ([`src/assistant-frame.js`](https://github.com/nirholas/three.ws/blob/main/src/assistant-frame.js)) renders the avatar with Three.js, retargets the platform's canonical animation clips onto it (idle, wave greeting, a talking loop while speaking), and anchors the speech bubble to the avatar's head projection every frame.-- Free-lane chat posts to `POST /api/chat` (SSE stream, anonymous access, server-side rate limits; three.ws applies no content filter of its own, so any refusal is the serving model's). BYOK chat streams directly from the visitor's browser to Groq or OpenRouter with their key; the key lives in `localStorage` on the three.ws origin and is never sent to three.ws servers or the host page.+- Free-lane chat posts to `POST /api/chat` (SSE stream, anonymous access, server-side rate limits; three.ws applies no content filter of its own, so any refusal is the serving model's). BYOK chat streams directly from the visitor's browser to Groq or OpenRouter with their key; the key lives in `localStorage` on the three.ws origin and is never sent to three.ws servers or the host page. When every free provider is throttled at once, the route answers `503 rate_limited` with a `retry_after`, and the widget shows that wait in the bubble alongside the settings panel as the way out (a visitor's own key is never subject to the platform's capacity).- Speak mode and spoken chat replies use the Web Speech API (`speechSynthesis`). Voice pick persists per browser. When the browser has no TTS or voice is muted, the bubble and talking animation still run for the estimated duration, so the widget never silently stalls.- Every config param is re-validated inside the frame by [`src/assistant-widget-core.js`](https://github.com/nirholas/three.ws/blob/main/src/assistant-widget-core.js) (strict background/color grammars, length clamps, avatar host allow-list), so a hostile embedding page cannot inject CSS or URLs into the frame.diff --git a/prompts/swarm-100/route-assistant.md b/prompts/swarm-100/route-assistant.mddeleted file mode 100644index bedaabe7e..000000000--- a/prompts/swarm-100/route-assistant.md+++ /dev/null@@ -1,119 +0,0 @@-# Route audit: /assistant (Assistant widget)--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. This route's declared entry (path, description, added date):-- node -e "const p=require('./data/pages.json');for(const s of p.sections)for(const g of s.pages)if(g.path==='/assistant')console.log(JSON.stringify(g,null,2))"--2. Find the serving implementation: grep "/assistant" in vercel.json (the live- route table server/index.mjs boots from), then list matching files in- pages/ and src/. STRUCTURE.md maps every surface to its directory if the- grep is ambiguous.-3. Production right now:-- curl -so /dev/null -w '%{http_code}\n' https://three.ws/assistant--4. Start (or reuse) the local dev server: npm run dev (vite, port 3000).--## Task: audit this one route end to end, then fix everything found--Route: /assistant ("Assistant widget", section "build").-Declared purpose: Put a 3D avatar assistant on any website with one script tag. A floating launcher opens a real animated avatar, against your page, a color, or a gradient, with a chatbot mode (free models or your own Groq/OpenRouter key) and a speak mode where the avatar says whatever you type out loud in a speech bubble.--Drive the page in a real headless browser. Playwright is already a dev-dependency; keep your probe script in the session scratchpad, never in the-repo.--1. Load http://localhost:3000/assistant. Record the HTTP status, every console- error and warning, and every failed network request.-2. Exercise it like a first-time user: click the primary actions, run the- primary flow if one exists, follow the page's internal links. Every button- must do something real; every link must resolve. If the page renders data,- prove in the network log that it came from a live endpoint, not a baked-in- fallback array.-3. States: verify populated, empty, loading, and error states are designed and- reachable. Block the page's primary fetch in Playwright and confirm an- actionable error state appears, not a blank void or a raw exception.-4. Responsive: render at 320, 768, and 1440 px. No horizontal page scroll, no- overlapping or clipped controls.-5. Accessibility basics: one h1; interactive elements are real buttons or- links with visible focus states; images carry alt text; form fields have- labels.-6. Head: a specific title tag and meta description that match the declared- purpose above.-7. Fix every defect at its root in the page's real source files and re-run the- probe until clean. Defects in shared modules are in scope when this route- exercises them.--## Definition of done--- [ ] Local load of /assistant: HTTP 200, zero console errors, zero unhandled- failed requests (a third-party outage must land in a designed fallback,- not a broken page).-- [ ] No dead interactive element on the page: no stub href="#", no button- without a handler, no link to a missing path.-- [ ] Empty, loading, error, and populated states verified.-- [ ] 320 / 768 / 1440 px renders verified clean.-- [ ] Title and meta description present and specific.-- [ ] npm test passes; npm run check:rules -- --paths <touched files> exits 0.-- [ ] Production status from step 0 recorded in the report; if production- needs a deploy to pick up a fix, the report says so (deploys stay- owner-gated).--## 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/route-assistant.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/chat-anon-cooldown-capacity.test.js b/tests/api/chat-anon-cooldown-capacity.test.jsnew file mode 100644index 000000000..cde31dae6--- /dev/null+++ b/tests/api/chat-anon-cooldown-capacity.test.js@@ -0,0 +1,125 @@+/**+ * POST /api/chat - a throttled free lane is capacity, not authentication.+ *+ * Signed-out callers are pinned to the free providers (groq / openrouter /+ * nvidia, plus the vertex-gemini credits anchor). When every one of those is in+ * a health cooldown, pickProvider falls through to a provider outside the anon+ * set, and the handler used to answer `401 sign in to chat with the agent`.+ *+ * That reads as an auth problem and is unactionable: the assistant widget+ * (/assistant) runs its whole free lane anonymously and has no sign-in anywhere+ * in it, so its visitors were told to do something the surface cannot do, for a+ * throttle that clears on its own. The route must report the same+ * `503 rate_limited` + Retry-After it returns when the fallback chain is+ * exhausted, so every client backs off and retries on one code path.+ */++import { describe, it, expect, vi, beforeEach } from 'vitest';++// An *auth* cooldown is the precondition that reaches the branch under test:+// pickProvider lets an explicitly requested provider ride out a transient health+// cooldown, but skips one whose key came back 401/402/403, so a signed-out+// request pinned to groq lands on the next configured provider instead - one+// outside the anonymous set.+const cooling = ['groq', 'openrouter', 'nvidia', 'vertex-gemini'];++vi.mock('../../api/_lib/rate-limit.js', () => ({+ limits: {+ chatIp: vi.fn(async () => ({ success: true, reset: Date.now() + 60_000 })),+ chatUser: vi.fn(async () => ({ success: true, reset: Date.now() + 60_000 })),+ chatHostKeyGlobal: vi.fn(async () => ({ success: true, reset: Date.now() + 60_000 })),+ },+ clientIp: () => '127.0.0.1',+}));++vi.mock('../../api/_lib/provider-health.js', () => ({+ providersInCooldown: vi.fn(async () => new Map(cooling.map((n) => [n, 'auth']))),+ markProviderCooldown: vi.fn(async () => {}),+ AUTH_COOLDOWN_SECONDS: 900,+ isBillingQuotaError: () => false,+}));++vi.mock('../../api/_lib/auth.js', () => ({+ getSessionUser: vi.fn(async () => null),+ authenticateBearer: vi.fn(async () => null),+ extractBearer: () => null,+}));++vi.mock('../../api/_lib/db.js', () => ({ sql: vi.fn(async () => []) }));++const { default: handler } = await import('../../api/chat.js');++function makeReq(body) {+ return {+ method: 'POST',+ url: '/api/chat',+ headers: { origin: 'https://three.ws', 'content-type': 'application/json' },+ socket: { remoteAddress: '127.0.0.1' },+ body,+ };+}++function makeRes() {+ const r = { statusCode: 200, _h: {}, _b: null, headersSent: false };+ r.setHeader = (k, v) => {+ r._h[String(k).toLowerCase()] = v;+ };+ r.getHeader = (k) => r._h[String(k).toLowerCase()];+ r.writeHead = (code, headers) => {+ r.statusCode = code;+ Object.assign(r._h, headers || {});+ r.headersSent = true;+ return r;+ };+ r.write = () => true;+ r.end = (chunk) => {+ if (chunk !== undefined) r._b = String(chunk);+ r.headersSent = true;+ return r;+ };+ return r;+}++async function callChat() {+ const res = makeRes();+ await handler(makeReq({ message: 'hello', history: [], system_prompt: 'test' }), res);+ let payload = null;+ try {+ payload = JSON.parse(res._b);+ } catch {+ payload = null;+ }+ return { res, payload };+}++describe('anonymous /api/chat with every free lane cooling', () => {+ beforeEach(() => {+ // The missing-key branch legitimately 401s; this test is about configured+ // keys that are merely throttled, so give the free lanes real-looking keys.+ process.env.GROQ_API_KEY = 'test-groq-key';+ process.env.OPENROUTER_API_KEY = 'test-openrouter-key';+ // A configured provider outside the anonymous set, so pickProvider has+ // somewhere to land once every free lane is skipped.+ process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';+ });++ it('answers 503 rate_limited, never 401', async () => {+ const { res, payload } = await callChat();+ expect(res.statusCode).toBe(503);+ expect(payload?.error).toBe('rate_limited');+ expect(payload?.error_description).toMatch(/capacity/i);+ });++ it('sends a Retry-After the client can back off on', async () => {+ const { res, payload } = await callChat();+ expect(String(res.getHeader('Retry-After'))).toBe('20');+ expect(payload?.retry_after).toBe(20);+ });++ it('names the cooling free lanes so the failure is diagnosable', async () => {+ const { payload } = await callChat();+ expect(payload?.providers_tried).toEqual(+ expect.arrayContaining(['groq', 'openrouter', 'nvidia']),+ );+ });+});