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.

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.js
index 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, then
diff --git a/prompts/swarm-100/route-community.md b/prompts/swarm-100/route-community.md
deleted file mode 100644
index 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.js
index 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.js
index 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.js
index 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),
);
}