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(avatars): end a job that loses the quota race instead of retrying it forever
nirholas659b1b0ef94e
diff --git a/api/avatars/_actions.js b/api/avatars/_actions.jsindex 6fda0ccab..b16047224 100644--- a/api/avatars/_actions.js+++ b/api/avatars/_actions.js@@ -3,7 +3,7 @@import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';import { presignUpload, headObject, r2, publicUrl, putObject } from '../_lib/r2.js';-import { storageKeyFor, enforceQuotas, searchPublicAvatars, stripOwnerFor } from '../_lib/avatars.js';+import { storageKeyFor, enforceQuotas, searchPublicAvatars, stripOwnerFor, assertAvatarSlotAvailable, isPlanLimitError } from '../_lib/avatars.js';import { listAvatars } from '../_lib/avatars.js';import { env } from '../_lib/env.js';import { sql } from '../_lib/db.js';@@ -519,6 +519,32 @@ const handleRegenerate = wrap(async (req, res) => {// ── regenerate-status ─────────────────────────────────────────────────────────+// Copy shown to a user whose library is full when a job reaches materialization.+// handleReconstruct pre-flights the same quota, so this only fires on the race+// (another avatar landed while the mesh was generating), but a job that loses+// that race must still end somewhere the user can act on.+const PLAN_LIMIT_JOB_ERROR =+ 'Your avatar library is full on this plan. Delete an avatar or upgrade, then build this one again.';++/**+ * A materialize stage threw. If the cause was a plan-limit refusal, terminate+ * the job as failed with caller-facing copy rather than leaving it at 'done'+ * with no avatar, that state is invisible to every recovery cron (they filter+ * on queued/running) and re-runs the same doomed materialization on every poll,+ * so the browser retries forever against a generic engine-fault message. Marked+ * error_kind 'input' so the wire relays the copy verbatim.+ * @returns {Promise<any|null>} the updated job row, or null if err was not a plan limit+ */+async function failJobOnPlanLimit({ userId, jobId, job, err }) {+ if (!isPlanLimitError(err)) return null;+ await sql`+ update avatar_regen_jobs+ set status = 'failed', error = ${PLAN_LIMIT_JOB_ERROR}, error_kind = 'input', updated_at = now()+ where job_id = ${jobId} and user_id = ${userId}+ `;+ return { ...job, status: 'failed', error: PLAN_LIMIT_JOB_ERROR, error_kind: 'input' };+}+const handleRegenerateStatus = wrap(async (req, res) => {if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;if (!method(req, res, ['GET'])) return;@@ -624,7 +650,10 @@ const handleRegenerateStatus = wrap(async (req, res) => {const result = await pollRiggingStage({ userId, jobId, job });job = { ...job, status: result.status, result_avatar_id: result.resultAvatarId ?? job.result_avatar_id };} catch (err) {- job = { ...job, error: job.error || `rig stage failed: ${err?.message}` };+ job = (await failJobOnPlanLimit({ userId, jobId, job, err })) ?? {+ ...job,+ error: job.error || `rig stage failed: ${err?.message}`,+ };}}@@ -643,7 +672,10 @@ const handleRegenerateStatus = wrap(async (req, res) => {const result = await finalizeReconstructStage({ userId, jobId, job, glbUrl: job.result_glb_url });job = { ...job, status: result.status, result_avatar_id: result.resultAvatarId ?? job.result_avatar_id };} catch (err) {- job = { ...job, error: job.error || `materialize failed: ${err?.message}` };+ job = (await failJobOnPlanLimit({ userId, jobId, job, err })) ?? {+ ...job,+ error: job.error || `materialize failed: ${err?.message}`,+ };}}@@ -667,7 +699,10 @@ const handleRegenerateStatus = wrap(async (req, res) => {const result = await finalizeAutoRigStage({ userId, jobId, job, glbUrl: job.result_glb_url });job = { ...job, status: result.status, result_avatar_id: result.resultAvatarId ?? job.result_avatar_id };} catch (err) {- job = { ...job, error: job.error || `auto-rig finalize failed: ${err?.message}` };+ job = (await failJobOnPlanLimit({ userId, jobId, job, err })) ?? {+ ...job,+ error: job.error || `auto-rig finalize failed: ${err?.message}`,+ };}}@@ -685,6 +720,11 @@ const handleRegenerateStatus = wrap(async (req, res) => {? String(job.error).slice(0, 300): sanitizeJobError(job.error);if (maskedError) response.error = maskedError;+ // Tell the client WHICH kind of copy it just received. Without this the+ // browser has to guess, and its keyword-matching fallback rewrites the+ // caller-facing text we deliberately relayed verbatim into a generic+ // "try a clearer photo" that is wrong for a quota or a plan refusal.+ if (job.error_kind === 'input' && maskedError) response.errorKind = 'input';if (job.provider) response.provider = job.provider;return json(res, 200, response);});@@ -1077,6 +1117,28 @@ const handleReconstruct = wrap(async (req, res) => {if (!rl.success) return rateLimited(res, rl);const body = parse(reconstructSchema, await readJson(req));+ // A library that is already at its plan ceiling cannot accept the avatar this+ // job would produce, and nothing downstream discovers that until+ // materialization, about ninety seconds of GPU reconstruction (plus a Flux+ // reference image on the prompt lane) after the user pressed the button. The+ // job then strands at 'done' with no avatar and the browser shows the generic+ // engine-fault copy, which is both a lie and a dead end: every retry burns the+ // same spend and lands in the same place. Refuse here instead, with the 402+ // the client already renders as "Avatar quota reached".+ try {+ await assertAvatarSlotAvailable(userId);+ } catch (err) {+ if (isPlanLimitError(err)) {+ return error(+ res,+ 402,+ 'plan_limit',+ 'Your avatar library is full on this plan. Delete an avatar or upgrade to build another.',+ );+ }+ throw err;+ }+// ── Provider resolution ──────────────────────────────────────────────────// Build the ordered list of providers to try. Every configured platform// provider leads (primary first), then the caller's BYOK keys (inline, thendiff --git a/prompts/swarm-100/route-community.md b/prompts/swarm-100/route-community.mddeleted file mode 100644index 2ad9caf56..000000000--- a/prompts/swarm-100/route-community.md+++ /dev/null@@ -1,119 +0,0 @@-# Route audit: /community (Community)--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==='/community')console.log(JSON.stringify(g,null,2))"--2. Find the serving implementation: grep "/community" 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/community--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: /community ("Community", section "main").-Declared purpose: Live platform activity plus where to follow, contribute, and connect with three.ws creators.--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/community. 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 /community: 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-community.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/src/coin3d/main.js b/src/coin3d/main.jsindex 30f33faa0..10ebeeb2f 100644--- a/src/coin3d/main.js+++ b/src/coin3d/main.js@@ -815,9 +815,11 @@ async function fetchMarket(mintAddr) {if (!r.ok) return null;const body = await r.json();const candles = Array.isArray(body?.data) ? body.data : [];- if (!candles.length) return null;+ // An answer with no candles is a fact about the coin ("nothing has traded+ // yet"); a failure is a fact about us. They get different copy.+ if (!candles.length) return { empty: true };const closes = candles.map((c) => Number(c.c)).filter(Number.isFinite);- if (!closes.length) return null;+ if (!closes.length) return { empty: true };const price = closes[closes.length - 1];const first = closes[0];const change = first > 0 ? (price - first) / first : null;@@ -1039,11 +1041,13 @@ function gradLabel(s) {function applyMarket(m) {const sparkSlot = document.getElementById('c3d-spark');- if (!m) {- // No candles for this mint (a brand-new coin, or the history provider is- // down). Say so once rather than pulsing a skeleton that never resolves.+ if (!m || m.empty) {+ // Replace the skeleton rather than pulsing forever. The next 60s refresh+ // still overwrites this with a real sparkline once one exists.if (sparkSlot?.querySelector('.c3d-spark-empty')) {- sparkSlot.innerHTML = '<p class="c3d-spark-none">No price history yet.</p>';+ sparkSlot.innerHTML = `<p class="c3d-spark-none">${+ m ? 'No price history yet.' : 'Price history unavailable.'+ }</p>`;}return;}diff --git a/src/constellation/main.js b/src/constellation/main.jsindex 8ebe178f8..0482048f4 100644--- a/src/constellation/main.js+++ b/src/constellation/main.js@@ -432,12 +432,13 @@ function selectNode(index, { fromKeyboard = false } = {}) {$('c-panel-mcap').textContent = token.market_cap_usd ? formatUsd(token.market_cap_usd) : '…';// Price is optional in the live feed. Hide the stat entirely rather than// leaving a permanently empty tile next to the numbers that do arrive.- $('c-panel-price').textContent = token.price_usd ? formatPrice(token.price_usd) : '—';+ $('c-panel-price').textContent = token.price_usd ? formatPrice(token.price_usd) : '…';$('c-stat-price').hidden = !token.price_usd;$('c-panel-rank').textContent = `#${token.rank}`;const neigh = nearestNeighbors(index, 3);- $('c-panel-neighbors').textContent = neigh.length ? neigh.map((x) => x.token.symbol).join(', ') : '—';+ // No neighbor list until the embedding vectors land; say "not yet", not "none".+ $('c-panel-neighbors').textContent = neigh.length ? neigh.map((x) => x.token.symbol).join(', ') : '…';const links = $('c-panel-links');links.innerHTML = '';diff --git a/src/selfie-pipeline.js b/src/selfie-pipeline.jsindex 7e298e7fb..911760711 100644--- a/src/selfie-pipeline.js+++ b/src/selfie-pipeline.js@@ -29,6 +29,8 @@ const JPEG_QUALITY = 0.88;const POLL_INTERVAL_MS = 3000;const POLL_TIMEOUT_MS = 8 * 60 * 1000;const RATE_LIMIT_COOLDOWN_MS = 60_000;+/** Extra polls to allow a 'done' job whose avatar has not materialized yet. */+const MATERIALIZE_RETRY_POLLS = 3;// BYOK key session storage keys — readable by the page to pre-populate the// key entry form and by the pipeline to attach the key to submit requests.@@ -279,6 +281,12 @@ async function pollUntilDone(jobId) {const deadline = Date.now() + POLL_TIMEOUT_MS;let attempt = 0;let consecutiveErrors = 0;+ // A 'done' job with no avatar id means the server's materialize stage threw+ // after the mesh was already generated. That stage re-runs on every poll, so+ // a transient (a storage blip, a lock) clears itself if we look again instead+ // of failing the user out of a reconstruction they already waited through.+ // Bounded: a deterministic failure must not spin until the poll deadline.+ let unmaterializedPolls = 0;const url = `${STATUS_ENDPOINT}?jobId=${encodeURIComponent(jobId)}`;while (Date.now() < deadline) {@@ -324,11 +332,22 @@ async function pollUntilDone(jobId) {detail: { label: statusLabel(job.status, attempt, elapsed), attempt },}));- if (job.status === 'done') return job;+ if (job.status === 'done') {+ if (job.resultAvatarId) return job;+ unmaterializedPolls += 1;+ if (unmaterializedPolls <= MATERIALIZE_RETRY_POLLS) continue;+ return job;+ }if (job.status === 'failed') {+ // errorKind 'input' means the API already vetted this string as+ // caller-facing copy (a plan refusal, a worker's "no face detected").+ // Running it back through friendlyJobError's keyword match would+ // overwrite an exact reason with a guess, "your library is full"+ // becomes "try again with a clearer photo", which sends the user off+ // to retake a photo that was never the problem.throw withMessage(new Error(job.error || 'reconstruct failed'),- friendlyJobError(job.error),+ job.errorKind === 'input' && job.error ? job.error : friendlyJobError(job.error),inferFailingSlot(job.error),);}