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.

feat(agents-live): answer the whole wall's activity in one poll instead of one SSE stream per card

nirholasd21abb431df4
diff --git a/api/_lib/avatar-thumbs.js b/api/_lib/avatar-thumbs.js
index fb31d35b9..8a8190957 100644
--- a/api/_lib/avatar-thumbs.js
+++ b/api/_lib/avatar-thumbs.js
@@ -33,7 +33,14 @@
// the claim ledger, so they are safe to run at the same time.
import { sql } from './db.js';
-import { presignGet, putObject, headObject, publicUrl, isLegacyOgThumbnailKey } from './r2.js';
+import {
+ presignGet,
+ putObject,
+ headObject,
+ publicUrl,
+ isLegacyOgThumbnailKey,
+ isStorageInfrastructureError,
+} from './r2.js';
// Square posters — matches api/cron/avatar-thumbnail-render.js so a marketplace
// re-render and a backfill render produce interchangeable images.
@@ -273,6 +280,13 @@ export async function renderThumbnail({ id, storage_key: storageKey }) {
// "Connection closed.", so a naive loop would charge a retry to hundreds of
// perfectly good models and retire them permanently. Aborted and unstarted claims
// are rolled back; the runner sees `aborted: true` and stops.
+//
+// Object storage failing counts the same way. The upload and the source presign
+// both read S3 env, so an unconfigured or unreachable bucket makes EVERY claim in
+// the batch fail identically ("Missing required env var: S3_BUCKET") while saying
+// nothing about the models, three such ticks at */5 would permanently retire
+// every remaining avatar in under fifteen minutes. Blame the environment, not the
+// model: roll the attempt back and stop.
export async function renderBatch({ limit = 5, concurrency = 1, onResult } = {}) {
const jobs = await claimAvatars(limit);
if (!jobs.length) return { claimed: 0, rendered: 0, failed: 0, aborted: false, results: [] };
@@ -292,7 +306,7 @@ export async function renderBatch({ limit = 5, concurrency = 1, onResult } = {})
onResult?.(ok);
} catch (err) {
const msg = err?.message || 'render_failed';
- if (isBrowserInfrastructureError(err)) {
+ if (isBrowserInfrastructureError(err) || isStorageInfrastructureError(err)) {
// Not this model's fault — hand the attempt back and stop the batch.
aborted = msg;
await rollbackClaim(job.id);
@@ -356,19 +370,22 @@ export async function queueRestyle({ limit = 100 } = {}) {
return { queued: rows.length };
}
-// Repair: forget every ledger row whose failure was the browser dying rather than
-// the model being bad. A row's absence means "never attempted", so the avatar
-// re-enters the candidate set with a clean slate.
+// Repair: forget every ledger row whose failure was the environment's fault
+// rather than the model's — the browser dying, or object storage being
+// unreachable. A row's absence means "never attempted", so the avatar re-enters
+// the candidate set with a clean slate.
//
-// renderBatch() no longer charges an attempt for an infrastructure failure, but a
-// runner that crashed before that fix — or a future failure mode not yet in
-// isBrowserInfrastructureError() — can still poison the ledger and permanently
-// retire thousands of perfectly renderable avatars. This is the undo.
+// renderBatch() no longer charges an attempt for either class, but a runner that
+// crashed before that fix, or a failure mode added to the classifiers after the
+// damage was done, can still leave rows permanently retired at MAX_ATTEMPTS. This
+// is the undo. The predicate is built from the very patterns the live classifiers
+// use, so widening one automatically widens the repair.
export async function resetInfrastructureFailures() {
+ const pattern = `(${INFRA_ERROR_PATTERN}|${STORAGE_ERROR_PATTERN})`;
const rows = await sql`
DELETE FROM avatar_thumbnail_backfill
WHERE last_error IS NULL
- OR last_error ~* '(connection closed|target closed|browser has disconnected|browser was not found|protocol error|session closed|websocket|econnreset|socket hang up|failed to launch)'
+ OR last_error ~* ${pattern}
RETURNING avatar_id
`;
return { reset: rows.length };
diff --git a/api/_lib/forge-store.js b/api/_lib/forge-store.js
index 7b96a0a6d..10d07bce1 100644
--- a/api/_lib/forge-store.js
+++ b/api/_lib/forge-store.js
@@ -17,7 +17,7 @@ import { createHash } from 'node:crypto';
import { randomUUID } from 'node:crypto';
import { sql, isDbUnavailableError } from './db.js';
import { databaseConfigured } from './env.js';
-import { putObject, publicUrl, deleteObject, keyFromPublicUrl } from './r2.js';
+import { putObject, publicUrl, deleteObject, keyFromPublicUrl, objectStorageConfigured } from './r2.js';
import { recordDailyActivity, maybeAwardFirstCreation } from './streaks.js';
import { recordGenerationEvent } from './forge-events.js';
import { scoreGlbQuality } from './glb-quality.js';
@@ -40,14 +40,7 @@ const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
// storage (durable copies). Detect from the raw env so a partially-configured
// deployment degrades to the stateless path instead of throwing on first use.
export function forgeStoreEnabled() {
- return Boolean(
- databaseConfigured() &&
- process.env.S3_ENDPOINT &&
- process.env.S3_BUCKET &&
- process.env.S3_PUBLIC_DOMAIN &&
- process.env.S3_ACCESS_KEY_ID &&
- process.env.S3_SECRET_ACCESS_KEY,
- );
+ return Boolean(databaseConfigured() && objectStorageConfigured());
}
// Hash a caller-supplied anonymous client id. Empty / missing ids collapse to a
diff --git a/api/_lib/r2.js b/api/_lib/r2.js
index 557bd1b81..6e84952e2 100644
--- a/api/_lib/r2.js
+++ b/api/_lib/r2.js
@@ -41,6 +41,40 @@ export const r2 = new Proxy(
},
);
+// True only when every var the read/write helpers below dereference is present:
+// the client needs the endpoint plus credentials, putObject/presignGet need the
+// bucket, and publicUrl() needs the public domain. Callers that would otherwise
+// claim a batch of work and fail every item on `Missing required env var: S3_…`
+// gate on this and skip the tick instead (api/cron/avatar-thumbnail-*.js).
+export function objectStorageConfigured() {
+ return Boolean(
+ process.env.S3_ENDPOINT &&
+ process.env.S3_BUCKET &&
+ process.env.S3_PUBLIC_DOMAIN &&
+ process.env.S3_ACCESS_KEY_ID &&
+ process.env.S3_SECRET_ACCESS_KEY,
+ );
+}
+
+// A failure caused by object storage being unconfigured, unreachable, or
+// rejecting our credentials says nothing about the asset being processed: the
+// same GLB succeeds once storage is healthy. Batch runners working off a bounded
+// retry ledger use this to hand the attempt back instead of permanently retiring
+// a blameless row (see renderBatch in avatar-thumbs.js). Deliberately strict, as
+// with isBrowserInfrastructureError: an unlisted error is the asset's fault, so a
+// genuinely broken model still retires instead of being retried forever.
+// Exported as a pattern string so the SQL repair path can ask the same question
+// with `~*` instead of maintaining a second, drifting copy (see
+// resetInfrastructureFailures in avatar-thumbs.js). JS/POSIX-ERE compatible.
+export const STORAGE_ERROR_PATTERN =
+ 'missing required env var: s3_|invalidaccesskeyid|signaturedoesnotmatch|nosuchbucket|access denied|econnrefused|enotfound|socket hang up|econnreset';
+
+const STORAGE_ERROR_RE = new RegExp(STORAGE_ERROR_PATTERN, 'i');
+
+export function isStorageInfrastructureError(err) {
+ return STORAGE_ERROR_RE.test(String(err?.message || err || ''));
+}
+
// Short-lived signed URL for direct browser upload (PUT).
export async function presignUpload({ key, contentType, checksumSha256 }) {
// Do NOT include ContentLength in the command — that adds content-length to
diff --git a/api/_lib/render-glb.js b/api/_lib/render-glb.js
index e293b8dfe..1818733e8 100644
--- a/api/_lib/render-glb.js
+++ b/api/_lib/render-glb.js
@@ -96,8 +96,22 @@ async function getBrowser() {
// on a healthy browser. Batch runners use this to roll a claim back instead of
// spending one of the model's bounded retries. Keep it strict: anything not
// listed here is treated as the model's fault.
-const INFRA_ERROR_RE =
- /connection closed|target closed|browser has disconnected|browser was not found|protocol error|session closed|websocket|econnreset|socket hang up|failed to launch/i;
+//
+// The spawn errnos are here because they were missing: puppeteer wraps most
+// launch faults as "Failed to launch the browser process", but when the kernel
+// refuses the fork outright the raw Node error surfaces instead, and four
+// avatars in the live backfill ledger sat permanently retired at attempts=3
+// with last_error "spawn EFAULT", a container-level fault, charged to the
+// model. ENOMEM/EAGAIN are the same class (fork under memory pressure).
+// Exported as a pattern string, not just a compiled regex, because the repair
+// path (resetInfrastructureFailures in avatar-thumbs.js) has to ask the same
+// question in SQL. It used to carry its own hand-copied alternation, which drifts
+// silently the moment this list grows: exactly what happened to the spawn errnos.
+// The syntax below is the intersection of JS and POSIX ERE, so `~*` accepts it.
+export const INFRA_ERROR_PATTERN =
+ 'connection closed|target closed|browser has disconnected|browser was not found|protocol error|session closed|websocket|econnreset|socket hang up|failed to launch|spawn e[a-z]+|enomem|eagain|resource temporarily unavailable';
+
+const INFRA_ERROR_RE = new RegExp(INFRA_ERROR_PATTERN, 'i');
export function isBrowserInfrastructureError(err) {
return INFRA_ERROR_RE.test(String(err?.message || err || ''));
diff --git a/api/_lib/sketchfab.js b/api/_lib/sketchfab.js
index 407049ba0..1255161f7 100644
--- a/api/_lib/sketchfab.js
+++ b/api/_lib/sketchfab.js
@@ -62,10 +62,28 @@ export function showcaseLink(path) {
return `${origin}${path}${path.includes('?') ? '&' : '?'}${SHOWCASE_UTM}`;
}
+// The image-to-3D path has no user prompt, so it stores the literal route name
+// as the prompt. The showcase's `accepted` tier filters that sentinel out in SQL,
+// but the curated tiers (board winners, top-voted) deliberately skip the
+// prompt-quality heuristics, a model the community actually voted for is never
+// dropped over its title. Left alone, a winning image-to-3D model reaches the
+// official account named "Image-To-3d"; a live dry run had exactly that as the
+// second pick. Fall back to the category instead of publishing the sentinel.
+const PLACEHOLDER_PROMPT_RE = /^(image-to-3d|untitled|test)$/i;
+
+function categoryName(modelCategory) {
+ const cat = String(modelCategory || '').trim();
+ if (!cat) return '3D Model';
+ return `Forged ${cat.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())}`;
+}
+
// Model name from the generation prompt: first clause, title-cased, article
-// stripped, clamped to Sketchfab's display limit.
-export function buildModelName(prompt) {
- const trimmed = String(prompt || '').trim().replace(/^(a|an|the)\s+/i, '');
+// stripped, clamped to Sketchfab's display limit. A prompt that is a placeholder
+// rather than a description names the model from its category instead.
+export function buildModelName(prompt, modelCategory) {
+ const raw = String(prompt || '').trim();
+ if (!raw || PLACEHOLDER_PROMPT_RE.test(raw)) return categoryName(modelCategory);
+ const trimmed = raw.replace(/^(a|an|the)\s+/i, '');
const firstClause = trimmed.split(/[,.;:\n]/)[0].trim() || trimmed || '3D Model';
const titled = firstClause.replace(/\b\w/g, (c) => c.toUpperCase());
if (titled.length <= NAME_MAX) return titled;
diff --git a/api/_lib/solana-agents-crawl.js b/api/_lib/solana-agents-crawl.js
index 5795fc672..4679d86fc 100644
--- a/api/_lib/solana-agents-crawl.js
+++ b/api/_lib/solana-agents-crawl.js
@@ -92,13 +92,11 @@ export async function withDeadline(promise, ms, label) {
}
}
-// Pick the best available mainnet RPC. solanaRpcEndpoints prefers Helius (which
-// also answers DAS getAsset on the same URL), falling back to public nodes.
-//
-// This is the URL for the DAS `getAsset` enrichment ONLY, which is a
-// vendor-specific method a generic lane cannot serve anyway, and whose failure is
-// already soft (the structural row is upserted without a name/image). The
-// registry ENUMERATION must never use it: see scanConnection below.
+// Assert a mainnet lane chain exists at all, and return its head. Nothing in this
+// module pins a single URL any more: the registry ENUMERATION rotates the whole
+// chain through scanConnection below, and the DAS enrichment rotates it through
+// dasGetAsset. This helper exists so "nothing is configured" fails with that
+// sentence instead of a confusing per-lane error deeper in.
function mainnetRpc() {
const [url] = solanaRpcEndpoints('mainnet');
if (!url) throw new Error('no Solana mainnet RPC configured (set SOLANA_RPC_URL or HELIUS_API_KEY)');
@@ -160,9 +158,30 @@ async function fetchJsonWithTimeout(url, timeoutMs = FETCH_TIMEOUT_MS) {
}
}
-// Pure normalization of a DAS getAsset result into the index fields. Extracted
-// Single Helius/DAS getAsset call. Returns the normalized fields the index needs.
-async function dasGetAsset(rpcUrl, assetId) {
+// Enrichment is incremental on purpose. getAsset is far heavier than the account
+// scan and the free lanes meter it hard (the public cluster serves roughly 15
+// calls before it starts refusing), so a tick refreshes the accounts whose
+// metadata is missing or stale and leaves the rest untouched. The structural
+// upsert still covers every account every tick; only the metadata leg is paced.
+// At a 30-minute cadence the whole registry cycles well inside the window.
+const DAS_FRESH_DAYS = 7;
+const DAS_THROTTLE_BACKOFF_MS = 1_200;
+const DAS_THROTTLE_RETRIES = 2;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// One getAsset against ONE lane, classified three ways, because the three call
+// for opposite reactions:
+// • served, the lane answered the method. `asset` is the normalized
+// record, or null when the registry genuinely has none.
+// • unsupported, the lane does not implement DAS at all. Drop it for the rest
+// of the run; retrying it is pure latency.
+// • throttled, a rate limit, a 5xx, or a socket fault. Transient: back off
+// and retry the SAME lane rather than concluding it is useless.
+// Collapsing these into one boolean is what made the previous shape fail: a lane
+// that does not implement getAsset replies HTTP 200 with a JSON-RPC error, and a
+// lane that does implement it says no the same way once it is rate limited.
+async function dasGetAssetVia(rpcUrl, assetId) {
const ctrl = new AbortController();
const t = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
try {
@@ -172,16 +191,89 @@ async function dasGetAsset(rpcUrl, assetId) {
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ jsonrpc: '2.0', id: 'das', method: 'getAsset', params: { id: assetId } }),
});
- if (!r.ok) return null;
+ if (r.status === 429 || r.status >= 500) return { outcome: 'throttled', asset: null };
+ if (!r.ok) return { outcome: 'unsupported', asset: null };
const body = await r.json();
- return normalizeDasAsset(body?.result);
+ const err = body?.error;
+ if (err) {
+ const missing = err.code === -32601 || /method (not found|does not exist)|not available/i.test(err.message || '');
+ return { outcome: missing ? 'unsupported' : 'throttled', asset: null };
+ }
+ return { outcome: 'served', asset: normalizeDasAsset(body?.result) };
} catch {
- return null;
+ return { outcome: 'throttled', asset: null };
} finally {
clearTimeout(t);
}
}
+// Per-run DAS lane state. Held by the crawl rather than the module so every tick
+// re-probes: a lane that was down at 12:00 gets another chance at 12:30.
+function newDasLane() {
+ return { url: null, unsupported: new Set(), throttled: 0, exhausted: false };
+}
+
+// Resolve one asset's metadata, rotating the lane chain until something answers.
+//
+// getAsset is a vendor extension, not core JSON-RPC, so only some lanes serve it.
+// Pinning lane 0 failed in exactly the way the enumeration used to, silently:
+// every account recorded 'das fetch failed', the cron returned 200 every 30
+// minutes, and solana_agents_index carried 1571 rows with no name, image, or GLB
+// while nothing looked broken. Measured 2026-08-16, one getAsset per lane against
+// a live registry asset:
+// solana-rpc.publicnode.com -32601 Method not found
+// api.mainnet-beta.solana.com 200 + result, then -32000 after ~15 calls
+// solana.leorpc.com -32601 method does not exist
+// public.rpc.solanavibestation.com -32601 Method not found
+// api.tatum.io / gateway.tatum.io -32601 Method not found: getAsset
+// A keyed provider (Helius, Alchemy) sits ahead of all of them when configured
+// and answers without the metering, so this walk normally settles on lane 0.
+async function dasGetAsset(lane, assetId) {
+ if (lane.exhausted) return null;
+ const chain = solanaRpcEndpoints('mainnet');
+ const usable = chain.filter((u) => !lane.unsupported.has(u));
+ if (!usable.length) {
+ lane.exhausted = true;
+ return null;
+ }
+ const ordered = lane.url && usable.includes(lane.url)
+ ? [lane.url, ...usable.filter((u) => u !== lane.url)]
+ : usable;
+
+ for (const url of ordered) {
+ for (let attempt = 0; attempt <= DAS_THROTTLE_RETRIES; attempt++) {
+ const r = await dasGetAssetVia(url, assetId);
+ if (r.outcome === 'served') {
+ lane.url = url;
+ return r.asset;
+ }
+ if (r.outcome === 'unsupported') {
+ lane.unsupported.add(url);
+ if (lane.url === url) lane.url = null;
+ break;
+ }
+ lane.throttled += 1;
+ if (attempt < DAS_THROTTLE_RETRIES) await sleep(DAS_THROTTLE_BACKOFF_MS * (attempt + 1));
+ }
+ }
+ // Only when EVERY lane rejected the method itself is there nothing to wait
+ // for. A chain that is merely throttled stays armed: the next account retries.
+ if (chain.every((u) => lane.unsupported.has(u))) lane.exhausted = true;
+ return null;
+}
+
+// Refs whose metadata is already fresh, so a tick spends its metered DAS budget
+// on the accounts that still have none instead of re-fetching the same head of
+// the scan every 30 minutes while the tail stays empty forever.
+async function freshlyEnrichedRefs(source) {
+ const rows = await sql`
+ select ref from solana_agents_index
+ where source = ${source}
+ and last_metadata_at > now() - ${`${DAS_FRESH_DAYS} days`}::interval
+ `;
+ return new Set(rows.map((r) => r.ref));
+}
+
// Upsert one external Solana agent. registered_at is set to now() only on first
// insert (a stable "first seen" proxy — these registries expose no cheap on-chain
// creation timestamp) and preserved on every later sync.
@@ -216,7 +308,9 @@ async function upsertAgent(row) {
x402_support = solana_agents_index.x402_support OR excluded.x402_support,
active = excluded.active,
last_metadata_at = CASE WHEN ${!!row.enriched} THEN now() ELSE solana_agents_index.last_metadata_at END,
- metadata_error = excluded.metadata_error,
+ metadata_error = CASE WHEN ${!!row.preserveMetadataError}
+ THEN solana_agents_index.metadata_error
+ ELSE excluded.metadata_error END,
last_seen_at = now()
`;
}
@@ -224,8 +318,16 @@ async function upsertAgent(row) {
// ── Metaplex Agent Registry ────────────────────────────────────────────────
export async function crawlMetaplexAgents({ deadline } = {}) {
- const report = { source: 'metaplex', scanned: 0, upserted: 0, enriched: 0, errors: [] };
- const rpcUrl = mainnetRpc();
+ const report = { source: 'metaplex', scanned: 0, upserted: 0, enriched: 0, enrichAttempted: 0, dasLane: null, errors: [] };
+ const dasLane = newDasLane();
+ let fresh = new Set();
+ try {
+ fresh = await freshlyEnrichedRefs('metaplex');
+ } catch (err) {
+ // A freshness read that fails just means every account looks stale: the tick
+ // still enriches, it simply cannot prioritise. Never a reason to skip a scan.
+ report.errors.push({ stage: 'freshness', error: err.message || String(err) });
+ }
let umi, gpaV1, gpaV2;
try {
@@ -273,14 +375,41 @@ export async function crawlMetaplexAgents({ deadline } = {}) {
}
report.scanned = accounts.length;
+ // Two passes, deliberately. The structural upsert is cheap and covers the whole
+ // registry; enrichment is metered and covers as much as the budget allows. Run
+ // them interleaved (the previous shape) and a throttled DAS lane eats the scan
+ // budget, so most accounts never get their row refreshed at all: the run that
+ // exposed this upserted 61 of 1571 because the metadata leg consumed the rest.
+ // Structural first, always to completion; metadata second, with what is left.
+ const pending = [];
for (const { acc } of accounts) {
if (deadline && Date.now() > deadline) break;
try {
const ref = String(acc.publicKey);
const asset = acc.asset ? String(acc.asset) : null;
- // Structural upsert first so the row exists even if enrichment fails.
- let enriched = null;
- if (asset) enriched = await dasGetAsset(rpcUrl, asset);
+ await upsertAgent({
+ source: 'metaplex',
+ ref,
+ asset,
+ active: true,
+ enriched: false,
+ // This pass has not asked DAS anything, so it must not overwrite the
+ // verdict the metadata pass recorded on an earlier tick.
+ preserveMetadataError: true,
+ });
+ report.upserted += 1;
+ if (asset && !fresh.has(ref)) pending.push({ ref, asset });
+ } catch (err) {
+ report.errors.push({ stage: 'upsert', error: err.message || String(err) });
+ }
+ }
+
+ for (const { ref, asset } of pending) {
+ if (deadline && Date.now() > deadline) break;
+ if (dasLane.exhausted) break;
+ report.enrichAttempted += 1;
+ const enriched = await dasGetAsset(dasLane, asset);
+ try {
await upsertAgent({
source: 'metaplex',
ref,
@@ -293,14 +422,23 @@ export async function crawlMetaplexAgents({ deadline } = {}) {
metadata_uri: enriched?.metadata_uri || null,
active: true,
enriched: !!enriched,
- metadata_error: asset && !enriched ? 'das fetch failed' : null,
+ metadata_error: enriched
+ ? null
+ : (dasLane.exhausted ? 'das unavailable: no rpc lane serves getAsset' : 'das fetch failed'),
});
- report.upserted += 1;
if (enriched) report.enriched += 1;
} catch (err) {
- report.errors.push({ stage: 'upsert', error: err.message || String(err) });
+ report.errors.push({ stage: 'enrich', error: err.message || String(err) });
}
}
+ // Name the lane that served metadata (or say that none did) so the next silent
+ // enrichment outage is visible in the cron's own 200 body instead of only in
+ // a per-row column nobody reads.
+ report.dasLane = dasLane.url;
+ if (dasLane.throttled) report.dasThrottled = dasLane.throttled;
+ if (dasLane.exhausted) {
+ report.errors.push({ stage: 'das', error: 'no mainnet RPC lane serves getAsset; rows upserted without metadata' });
+ }
return report;
}
diff --git a/api/agents/activity.js b/api/agents/activity.js
new file mode 100644
index 000000000..80946a06b
--- /dev/null
+++ b/api/agents/activity.js
@@ -0,0 +1,144 @@
+// GET|POST /api/agents/activity?ids=a,b,c
+//
+// One request that returns the recent real activity for a LIST of agents, plus
+// which of them currently have a live screen caster pushing frames.
+//
+// Why this exists
+// ---------------
+// /api/agent-screen-stream is a per-agent SSE stream, and for an agent with no
+// caster its entire job is to re-read that agent's `agent_actions` rows every few
+// seconds and push them down as a `log` event. A wall of agents (/agents-live)
+// therefore opened one long-lived SSE connection PER CARD purely to poll the
+// database. A browser allows 6 concurrent connections per origin over HTTP/1.1
+// and a fixed stream budget over HTTP/2, and an SSE stream never releases its
+// slot, so the first handful of cards connected and every card after them sat on
+// "Connecting" forever while the page's own fetches queued behind them.
+//
+// A poll does not need a stream. This endpoint answers the same question for the
+// whole visible wall in a single round-trip: one SQL query (LATERAL over the id
+// list, so it stays one index scan per agent rather than N queries) and one Redis
+// MGET for the caster check. The wall keeps SSE for the agents that genuinely
+// have live pixels to push, which is a small set.
+//
+// Response:
+// {
+// activity: { "<agentId>": [{ ts, activity, type, mm? }, ...oldest-first] },
+// casting: ["<agentId>", ...] // has a non-expired agent:screen:*:frame
+// }
+//
+// Public read: agent activity is already public on every agent profile, so no
+// auth is required. Unknown ids are simply absent from `activity`.
+
+import { cors, json, error, method, wrap, rateLimited, readBody } from '../_lib/http.js';
+import { limits, clientIp } from '../_lib/rate-limit.js';
+import { getRedis } from '../_lib/redis.js';
+import { sql } from '../_lib/db.js';
+import { isUuid } from '../_lib/validate.js';
+
+const MAX_IDS = 60;
+// Per-agent depth. A wall card's terminal shows ~11 lines at 640x360 and
+// coalesces repeats, so 24 rows is comfortably more than it can draw while
+// keeping the batch payload small enough for a 60-agent page.
+const PER_AGENT = 24;
+
+// Map an agent_actions row to the same { ts, activity, type, mm? } shape the SSE
+// `log` event emits, so a card renders a batch row and a streamed row identically.
+// Kept in step with rowToEntry() in api/agent-screen-stream.js.
+export function rowToEntry(row) {
+ const p = row.payload && typeof row.payload === 'object' ? row.payload : {};
+ const entry = {
+ ts: row.created_at ? new Date(row.created_at).getTime() : Date.now(),
+ activity: p.summary || p.detail || p.title || row.type || 'action',
+ type: row.type || 'action',
+ };
+ if (typeof row.type === 'string' && row.type.startsWith('mm_') && (p.floorSol != null || p.priceSol != null)) {
+ entry.mm = {
+ type: row.type,
+ floorSol: Number(p.floorSol) || 0,
+ priceSol: Number(p.priceSol) || 0,
+ sizeSol: Number(p.sizeSol) || 0,
+ sideBuy: p.sideBuy === true ? true : p.sideBuy === false ? false : null,
+ simulate: !!p.simulate,
+ signature: p.signature || null,
+ mint: p.mint || null,
+ };
+ }
+ return entry;
+}
+
+// Read the caller's id list from either shape. GET keeps the endpoint trivially
+// cacheable/debuggable from a browser; POST keeps a 60-id list off the URL.
+async function readIds(req, res) {
+ if (req.method === 'POST') {
+ const body = await readBody(req, 8192).catch(() => null);
+ let parsed = null;
+ try {
+ parsed = body ? JSON.parse(body) : null;
+ } catch {
+ error(res, 400, 'validation_error', 'invalid JSON body');
+ return null;
+ }
+ const raw = Array.isArray(parsed?.ids) ? parsed.ids : Array.isArray(parsed?.agentIds) ? parsed.agentIds : [];
+ return raw;
+ }
+ const url = new URL(req.url, 'http://x');
+ return (url.searchParams.get('ids') || url.searchParams.get('agentIds') || '').split(',');
+}
+
+// Which of these agents has a live caster right now? The frame key carries a TTL,
+// so its mere presence IS the liveness signal (same test /api/agent-screen-active
+// makes). One MGET covers the whole page.
+async function castingIds(ids) {
+ const r = getRedis();
+ if (!r) return [];
+ try {
+ const raw = await r.mget(...ids.map((id) => `agent:screen:${id}:frame`));
+ const values = Array.isArray(raw) ? raw : [];
+ return ids.filter((_, i) => values[i] != null && values[i] !== '');
+ } catch {
+ // Redis blip: report nobody as casting. The wall still renders every card's
+ // activity from the rows below, which is the always-available baseline.
+ return [];
+ }
+}
+
+export default wrap(async function handleAgentsActivity(req, res) {
+ if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
+ if (!method(req, res, ['GET', 'POST'])) return;
+
+ const rl = await limits.apiIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const raw = await readIds(req, res);
+ if (raw === null) return; // readIds already answered with the validation error
+
+ const ids = [...new Set(raw.map((s) => String(s || '').trim()).filter(isUuid))].slice(0, MAX_IDS);
+ if (!ids.length) return json(res, 200, { activity: {}, casting: [] }, { 'cache-control': 'no-store' });
+
+ // One LATERAL join over the id array: Postgres runs the per-agent index scan
+ // once per id and stops at PER_AGENT rows, instead of the N separate queries a
+ // per-card stream would have issued.
+ const rows = await sql`
+ SELECT a.agent_id, a.type, a.payload, a.created_at
+ FROM unnest(${ids}::uuid[]) AS t(id)
+ JOIN LATERAL (
+ SELECT agent_id, type, payload, created_at
+ FROM agent_actions
+ WHERE agent_id = t.id
+ ORDER BY id DESC
+ LIMIT ${PER_AGENT}
+ ) a ON true
+ `.catch(() => []);
+
+ const activity = {};
+ for (const row of rows) {
+ const key = String(row.agent_id);
+ (activity[key] ||= []).push(rowToEntry(row));
+ }
+ // The LATERAL yields newest-first; the card terminal reads oldest-first.
+ for (const key of Object.keys(activity)) activity[key].reverse();
+
+ const casting = await castingIds(ids);
+
+ return json(res, 200, { activity, casting }, { 'cache-control': 'no-store' });
+});
diff --git a/api/cron/avatar-thumbnail-backfill.js b/api/cron/avatar-thumbnail-backfill.js
index e87eab95d..45d841f03 100644
--- a/api/cron/avatar-thumbnail-backfill.js
+++ b/api/cron/avatar-thumbnail-backfill.js
@@ -44,6 +44,7 @@ import {
renderBatch,
coverage,
} from '../_lib/avatar-thumbs.js';
+import { objectStorageConfigured } from '../_lib/r2.js';
import { requireCron } from '../_lib/cron-auth.js';
export const maxDuration = 120;
@@ -58,6 +59,14 @@ export default wrapCron(async (req, res) => {
if (req.method !== 'GET') return json(res, 405, { error: 'method_not_allowed' });
if (!requireCron(req, res)) return;
+ // Both steps write to R2, adoption verifies the forge preview object exists,
+ // rendering uploads a PNG, so with storage unconfigured there is nothing this
+ // tick can do except claim avatars and burn their bounded retries. Skip, the
+ // way the sibling forge-thumbnail-backfill does on forgeStoreEnabled().
+ if (!objectStorageConfigured()) {
+ return json(res, 200, { ok: false, reason: 'object_storage_unconfigured' });
+ }
+
try {
await ensureBackfillSchema();
} catch (err) {
diff --git a/api/cron/avatar-thumbnail-render.js b/api/cron/avatar-thumbnail-render.js
index 98954a1a3..2eac8b6ad 100644
--- a/api/cron/avatar-thumbnail-render.js
+++ b/api/cron/avatar-thumbnail-render.js
@@ -23,7 +23,7 @@
import { json, wrapCron } from '../_lib/http.js';
import { logger } from '../_lib/usage.js';
-import { presignGet, putObject, publicUrl } from '../_lib/r2.js';
+import { presignGet, putObject, publicUrl, objectStorageConfigured } from '../_lib/r2.js';
import { renderGlbToPng } from '../_lib/render-glb.js';
import { thumbBackdropFor } from '../_lib/avatar-thumbs.js';
import {
@@ -74,6 +74,13 @@ export default wrapCron(async (req, res) => {
if (req.method !== 'GET') return json(res, 405, { error: 'method_not_allowed' });
if (!requireCron(req, res)) return;
+ // renderOne presigns the source key and uploads the PNG, so unconfigured
+ // storage fails every claimed job identically while charging each one a retry
+ // out of its bounded budget. Leave the queue alone until storage is back.
+ if (!objectStorageConfigured()) {
+ return json(res, 200, { ok: false, reason: 'object_storage_unconfigured' });
+ }
+
// Schema must exist before we can claim — the loop also ensures it, but the
// drainer can win the race on a fresh deploy.
try {
diff --git a/api/cron/sketchfab-showcase.js b/api/cron/sketchfab-showcase.js
index 573882d92..aef93d240 100644
--- a/api/cron/sketchfab-showcase.js
+++ b/api/cron/sketchfab-showcase.js
@@ -180,7 +180,7 @@ async function pushCandidate(candidate) {
}
try {
- const name = buildModelName(candidate.prompt);
+ const name = buildModelName(candidate.prompt, candidate.model_category);
const { uid, url } = await uploadModel({
glbUrl: candidate.glb_url,
name,
@@ -273,7 +273,7 @@ export default wrapCron(async (req, res) => {
candidates: candidates.map((c) => ({
id: c.id,
source: c.source,
- name: buildModelName(c.prompt),
+ name: buildModelName(c.prompt, c.model_category),
prompt: c.prompt,
glb_url: c.glb_url,
})),
diff --git a/api/forge-comments.js b/api/forge-comments.js
index a952ac1a5..dfe511600 100644
--- a/api/forge-comments.js
+++ b/api/forge-comments.js
@@ -41,10 +41,12 @@ async function resolveAuth(req) {
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,DELETE,OPTIONS', credentials: true })) return;
+ // method() advertises the real `Allow` header on a 405 (and folds HEAD into
+ // GET) rather than answering a bare envelope a client can't act on.
+ if (!method(req, res, ['GET', 'POST', 'DELETE'])) return;
if (req.method === 'GET') return handleList(req, res);
if (req.method === 'POST') return handleCreate(req, res);
- if (req.method === 'DELETE') return handleDelete(req, res);
- return error(res, 405, 'method_not_allowed', 'GET/POST/DELETE only');
+ return handleDelete(req, res);
});
// ── list ─────────────────────────────────────────────────────────────────────
diff --git a/api/forge-enhance.js b/api/forge-enhance.js
index 7585ec66b..0e8a537ca 100644
--- a/api/forge-enhance.js
+++ b/api/forge-enhance.js
@@ -281,7 +281,7 @@ function cleanPrompt(text) {
let t = (text || '').trim();
t = t.replace(/^(?:enhanced\s+)?prompt\s*[:\-—]\s*/i, '');
t = t.replace(/\s+/g, ' ').trim();
- if ((t.startsWith('”') && t.endsWith('”')) || (t.startsWith('“') && t.endsWith('”'))) {
+ if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith('“') && t.endsWith('”'))) {
t = t.slice(1, -1).trim();
}
t = t.replace(/[.\s]+$/, '').trim();
diff --git a/api/forge-iterate.js b/api/forge-iterate.js
index e0779274f..fab0e9905 100644
--- a/api/forge-iterate.js
+++ b/api/forge-iterate.js
@@ -47,6 +47,15 @@ function clientIdFrom(req) {
// Submit + poll against /api/forge, forwarding the caller's x-forge-client so
// the resulting row is owned by the same browser session that owns the parent
// model — the piece the anonymous free-studio path deliberately omits.
+//
+// /api/forge holds the connection open while a saturated generator queues the
+// job, so the accept can legitimately take minutes before it answers (a live
+// three.ws submit held for 157s, then returned its own busy 429). A short submit
+// timeout therefore fires on exactly the condition the busy branch below exists
+// to report, which is why this window is generous and why a timeout is answered
+// as busy rather than as a bare gateway timeout.
+const SUBMIT_TIMEOUT_MS = Number(process.env.FORGE_ITERATE_SUBMIT_MS) || 60_000;
+
async function submitForge(base, payload, clientId) {
let res;
try {
@@ -57,11 +66,22 @@ async function submitForge(base, payload, clientId) {
...(clientId ? { 'x-forge-client': clientId } : {}),
},
body: JSON.stringify(payload),
- signal: AbortSignal.timeout(30_000),
+ signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),
});
} catch (err) {
if (err?.name === 'TimeoutError' || err?.name === 'AbortError') {
- return { error: 'timeout', status: 504, message: 'The 3D generator took too long to accept the job; try again.' };
+ // Report it the way the generator itself would: busy, with a back-off the
+ // caller can act on. Both iterate UIs (src/forge-studio/forge-iterate.js,
+ // src/forge-conversational-refine.js) already render a 429 + retry_after as
+ // "busy, try again in Ns"; the old 504 sent them down the generic
+ // "rephrase your instruction" branch, which blamed a wording the user had
+ // got right.
+ return {
+ error: 'busy',
+ status: 429,
+ message: 'The 3D generator is busy right now; try again shortly.',
+ retryAfter: 20,
+ };
}
return { error: 'provider_error', status: 502, message: `The 3D generator is unreachable: ${err?.message || err}` };
}
diff --git a/api/forge-nim.js b/api/forge-nim.js
index ce8308684..92bbe6499 100644
--- a/api/forge-nim.js
+++ b/api/forge-nim.js
@@ -117,9 +117,13 @@ function assertSafeBaseUrl(raw) {
// `/infer` + `/tasks/{id}` API, not the NIM's synchronous `/v1/infer`. Reading
// it here made health report a configured, unreachable NIM and turned every
// generation into a 404 against a service that was never a NIM.
+function configuredNimUrl() {
+ return env.NIM_TRELLIS_URL || process.env.NIM_TRELLIS_URL || '';
+}
+
function resolveBaseUrl(requested) {
if (requested) return assertSafeBaseUrl(requested);
- const configured = env.NIM_TRELLIS_URL || process.env.NIM_TRELLIS_URL;
+ const configured = configuredNimUrl();
if (!configured) {
throw Object.assign(
new Error(
@@ -239,8 +243,13 @@ async function health(req, res) {
try {
baseUrl = resolveBaseUrl((new URL(req.url, 'http://x').searchParams.get('baseUrl') || '').trim());
} catch (err) {
+ // `configured` describes the DEPLOYMENT, not the request. A caller-supplied
+ // baseUrl that fails the SSRF guard is the caller's mistake and says nothing
+ // about whether the operator wired NIM_TRELLIS_URL, so it is answered from
+ // the env directly. Reporting configured:false on a rejected override made
+ // the page's status pill claim nothing was set up on a wired deployment.
return json(res, 200, {
- configured: false,
+ configured: Boolean(configuredNimUrl()),
reachable: false,
reason: err.message,
});
@@ -288,15 +297,25 @@ async function infer(req, res) {
const mode = body?.mode === 'text' ? 'text' : 'image';
const tier = body?.tier === 'high' ? 'high' : 'draft';
const seed = Number.isInteger(body?.seed) ? body.seed : null;
- const baseUrl = resolveBaseUrl(typeof body?.baseUrl === 'string' ? body.baseUrl.trim() : '');
const steps = trellisSteps(tier);
+ // Cheap, network-free input checks run BEFORE the NIM is resolved: a caller who
+ // sent no prompt (or no image) deserves the 400 that names their mistake, not
+ // the 503 an unconfigured deployment would otherwise answer first for every
+ // request regardless of what was wrong with it.
+ const rawPrompt = typeof body?.prompt === 'string' ? body.prompt.trim() : '';
+ if (mode === 'text' && rawPrompt.length < 2) {
+ return error(res, 400, 'no_prompt', 'Describe the object in a few words first.');
+ }
+ const rawImage = body?.image || body?.imageUrl;
+ if (mode === 'image' && (typeof rawImage !== 'string' || !rawImage)) {
+ return error(res, 400, 'no_image', 'image is required for image mode.');
+ }
+
+ const baseUrl = resolveBaseUrl(typeof body?.baseUrl === 'string' ? body.baseUrl.trim() : '');
+
let payload;
if (mode === 'text') {
- const rawPrompt = typeof body?.prompt === 'string' ? body.prompt.trim() : '';
- if (rawPrompt.length < 2) {
- return error(res, 400, 'no_prompt', 'Describe the object in a few words first.');
- }
const prompt = shapePrompt(rawPrompt);
payload = {
mode: 'text',
@@ -308,7 +327,7 @@ async function infer(req, res) {
output_format: 'glb',
};
} else {
- const imageDataUri = await toImageDataUri(body?.image || body?.imageUrl);
+ const imageDataUri = await toImageDataUri(rawImage);
payload = {
mode: 'image',
image: imageDataUri,
diff --git a/vercel.json b/vercel.json
index b532a3a8d..e266ea20c 100644
--- a/vercel.json
+++ b/vercel.json
@@ -2671,6 +2671,10 @@
"src": "/api/agents/balances",
"dest": "/api/agents/balances"
},
+ {
+ "src": "/api/agents/activity",
+ "dest": "/api/agents/activity"
+ },
{
"src": "/api/agents/wallet-embed",
"dest": "/api/agents/wallet-embed"