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(agora): land the passport panel, player mode and avatar thumbnail backfill work
nirholasa2c367832807
diff --git a/api/_lib/avatar-thumbs.js b/api/_lib/avatar-thumbs.jsindex 8a8190957..222159ccb 100644--- a/api/_lib/avatar-thumbs.js+++ b/api/_lib/avatar-thumbs.js@@ -40,6 +40,7 @@ import {publicUrl,isLegacyOgThumbnailKey,isStorageInfrastructureError,+ STORAGE_ERROR_PATTERN,} from './r2.js';// Square posters — matches api/cron/avatar-thumbnail-render.js so a marketplace@@ -381,6 +382,9 @@ export async function queueRestyle({ limit = 100 } = {}) {// 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() {+ // Lazy, for the same reason renderThumbnail defers it: a static import would+ // pull the chromium dependency tree into every route that touches this module.+ const { INFRA_ERROR_PATTERN } = await import('./render-glb.js');const pattern = `(${INFRA_ERROR_PATTERN}|${STORAGE_ERROR_PATTERN})`;const rows = await sql`DELETE FROM avatar_thumbnail_backfilldiff --git a/docs/x-memory-seeding.md b/docs/x-memory-seeding.mdindex 2039bd951..19fa99527 100644--- a/docs/x-memory-seeding.md+++ b/docs/x-memory-seeding.md@@ -20,7 +20,8 @@ yes on a screen that tells you exactly what will be read and stored.## How it fits together```- Connect X (OAuth 2.0 PKCE, read scopes only)+ Connect X (OAuth 2.0 PKCE, /api/auth/x/connect?scope=read)+ │ the seeding card asks X for read scopes only: no permission to post│ the connection alone changes nothing in memory▼GET /api/agents/:id/memory/seed/x@@ -43,7 +44,14 @@ yes on a screen that tells you exactly what will be read and stored.nothing distilled from your account survives```-Three properties fall out of that shape:+Four properties fall out of that shape:++- **Connecting for seeding never grants permission to post.** The X card's+ Connect button asks X for `tweet.read users.read offline.access` and nothing+ else, so an owner who only wants their agent to sound like them is never asked+ to hand over write access to their timeline. Posting is a separate connect+ (`?scope=full`), offered next to it and labelled as such, and reconnecting+ keeps the shape of the grant you already made.- **A POST without consent is refused before anything is read.** The handleranswers `403 consent_required` with the disclosure attached, and the@@ -57,6 +65,27 @@ Three properties fall out of that shape:consent id that produced it. Revoking, or disconnecting X from Settings,deletes exactly those rows, including any a superseded grant left behind.+## Connecting: two grants, deliberately separate++| | Seeding | Posting |+|---|---|---|+| Connect link | `/api/auth/x/connect?scope=read` | `/api/auth/x/connect?scope=full` |+| Scopes X is asked for | `tweet.read users.read offline.access` | the read set plus `tweet.write media.write` |+| Where it is offered | the X card in Settings, Connected accounts | the agent editor's Social tab, the share and walk-capture flows |+| What it can do | read your profile and recent posts, once, when you consent | publish posts and upload media as you |++A three.ws account holds exactly one X connection (`social_connections` is+unique on user and provider), so the sets are not additive: a read-only connect+replaces a posting connection with a read-only one, and the+posting lane then answers `insufficient_scope` with the reconnect link rather+than failing at the X API. The scope sets and both guards live in+[api/_lib/x-scopes.js](../api/_lib/x-scopes.js); an unrecognised `scope=` value+resolves to the full set, so a typo can never silently narrow what a posting+surface asks for.++Connections made before scopes were recorded store an empty scope string. Those+are treated as unknown rather than as empty, so neither guard blocks them.+## What is read, and what is notThe consent screen shows this list verbatim from the server; the same module@@ -115,6 +144,9 @@ curl -s https://three.ws/api/agents/$AGENT_ID/memory/seed/x --cookie "$JAR""configured": true,"username": "you","connection_scopes": "tweet.read users.read offline.access",+ "required_scopes": ["tweet.read", "users.read"],+ "missing_scopes": [],+ "scopes_ok": true,"seeded_at": "2026-08-12T16:00:00.000Z","fact_count": 5,"scope_version": "2026-08-11.1",@@ -137,6 +169,13 @@ the disclosure moved (the old grant no longer authorizes seeds), and`account_changed` when the connection now points at a different X account thanthe one you consented for.+`scopes_ok` is false when the live connection cannot cover the read the+disclosure describes (you unticked a permission on X's screen, or the account is+connected for posting only under a scope set that dropped `tweet.read`).+`missing_scopes` names exactly what it lacks. The card shows a reconnect instead+of the consent panel in that state, so nobody consents to a seed that could not+run.+### `POST /api/agents/:id/memory/seed/x`Grant consent (first call) and seed. Without a live grant the body must carry@@ -185,13 +224,16 @@ distilled posts behind on an agent you forgot about.| `unauthorized` | 401 | Sign-in required || `not_found` / `forbidden` | 404 / 403 | No such agent, or it is not yours || `not_connected` | 400 | Connect X first (Settings, Connected accounts) |+| `insufficient_scope` | 400 | The connection cannot read your profile and posts; the body names the missing scopes. Reconnect with `?scope=read` || `consent_required` | 403 | No live grant; the response carries the disclosure to show || `account_mismatch` | 409 | The consent was granted for a different X account || rate limited | 429 | One seed per agent per 6 hours |## Enabling it on a deployment-The lane needs an X app with OAuth 2.0 and read scopes, created at+The lane needs an X app with OAuth 2.0 and, at minimum, the `tweet.read`,+`users.read` and `offline.access` scopes enabled (add `tweet.write` and+`media.write` if the deployment also posts), created athttps://developer.twitter.com with `https://<your-domain>/api/auth/x/callback`registered as the callback. Its two credentials are the only configuration:@@ -235,5 +277,7 @@ Seeded rows in `agent_memories` are found by tag (`tags && '{x_seed}'`) and by| Disclosure text, selection, sanitisation, memory rows (pure, tested) | [api/_lib/x-memory-seed.js](../api/_lib/x-memory-seed.js) || Revocation shared by DELETE, disconnect, and account switch | [api/_lib/x-seed-consent.js](../api/_lib/x-seed-consent.js) || OAuth 2.0 PKCE connect and callback | [api/auth/x/[action].js](../api/auth/x/%5Baction%5D.js) |+| Scope sets, and the read/write guard each lane applies | [api/_lib/x-scopes.js](../api/_lib/x-scopes.js) || Consent screen (renders the server's disclosure verbatim) | [public/settings/index.html](../public/settings/index.html) || Transform tests | [tests/api/x-memory-seed-transform.test.js](../tests/api/x-memory-seed-transform.test.js), [tests/api/agents-memory-seed.test.js](../tests/api/agents-memory-seed.test.js) |+| Consent gate, scope gate and revocation tests | [tests/api/x-memory-seed-consent.test.js](../tests/api/x-memory-seed-consent.test.js), [tests/api/x-scopes.test.js](../tests/api/x-scopes.test.js) |diff --git a/public/agents/index.html b/public/agents/index.htmlindex 9d07c9947..6dbdb9ab9 100644--- a/public/agents/index.html+++ b/public/agents/index.html@@ -160,11 +160,16 @@@media (max-width: 600px) {.controls { gap: 6px; }.hero h1 { font-size: 26px; }- /* Site-wide 44px tap-target floor. mobile.css sets it for the fields by- id; these chips and CTAs carry page-local classes it cannot know. */- .chip, .btn { min-height: 44px; }.src-chips { gap: 8px; }}+ /* Site-wide 44px tap-target floor. mobile.css sets it for the fields by id;+ these chips and CTAs carry page-local classes it cannot know. Gated on+ pointer type rather than width, for the reason mobile.css gives: a 768px+ tablet is still touch-only, and a width gate left the source chips at+ 39px there. inline-flex keeps the label centred in the taller box. */+ @media (hover: none) and (pointer: coarse) {+ .chip, .btn { min-height: 44px; display: inline-flex; align-items: center; }+ }</style><!-- Site-wide mobile polish: horizontal-scroll guard, iOS focus-zoomfix, and the 44px tap-target floor. Loaded last so it wins ondiff --git a/public/app-next.css b/public/app-next.cssindex 8fd7c4b55..c7777b897 100644--- a/public/app-next.css+++ b/public/app-next.css@@ -767,8 +767,9 @@ body.app-next-body {}.nxt-anim-search:focus {- border-color: rgba(255, 255, 255, 0.22);+ border-color: rgba(255, 255, 255, 0.45);background: rgba(255, 255, 255, 0.08);+ box-shadow: 0 0 0 3px rgba(255, 255, 255, 0.22);}.nxt-anim-grid {@@ -1041,9 +1042,12 @@ body.app-next-body.is-dragover::before {transition: border-color 0.15s, box-shadow 0.15s;}+/* The input itself carries `outline: none`, so the wrap is the only thing that+ can show focus. A 6%-alpha ring was effectively invisible on the dark glass:+ keyboard users had no way to tell the field was focused. */.nxt-chat-input-wrap:focus-within {- border-color: rgba(255, 255, 255, 0.20);- box-shadow: 0 0 0 3px rgba(255, 255, 255, 0.06), 0 28px 64px rgba(0, 0, 0, 0.55);+ border-color: rgba(255, 255, 255, 0.45);+ box-shadow: 0 0 0 3px rgba(255, 255, 255, 0.28), 0 28px 64px rgba(0, 0, 0, 0.55);}.nxt-chat-input-icon {@@ -1282,7 +1286,8 @@ body.app-next-body.is-dragover::before {.nxt-share-copy input:focus,.nxt-share-copy textarea:focus {- border-color: rgba(255, 255, 255, 0.22);+ border-color: rgba(255, 255, 255, 0.45);+ box-shadow: 0 0 0 3px rgba(255, 255, 255, 0.22);}.nxt-share-copy button {diff --git a/public/features.json b/public/features.jsonindex 04f031fd9..4cd680dbc 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-16T16:45:09.136Z",+ "generated_at": "2026-08-16T17:00:52.599Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/scripts/backfill-avatar-thumbnails.mjs b/scripts/backfill-avatar-thumbnails.mjsindex 522303bc6..d0cc6b071 100644--- a/scripts/backfill-avatar-thumbnails.mjs+++ b/scripts/backfill-avatar-thumbnails.mjs@@ -38,10 +38,15 @@* --adopt-only run phase 1 only, never boot chromium* --render-only skip phase 1* --loop keep refilling the budget until nothing is left to claim- * --reset-infra un-retire avatars whose only failures were a dead browser- * (an OOM-killed chromium fails every render in the batch- * with "Connection closed."; genuinely broken models record a- * model-attributable error and are never reset)+ * --reset-infra un-retire avatars whose only failures were the+ * environment's fault: a dead browser (an OOM-killed+ * chromium fails every render in the batch with+ * "Connection closed.") or unreachable object storage.+ * Genuinely broken models record a model-attributable+ * error (e.g. "glb fetch failed") and are never reset.+ * --repair-only run --reset-infra / --restyle and stop before touching+ * R2. Needs DATABASE_URL only, so the undo still works+ * while object storage is the thing that is broken.* --restyle=N re-queue up to N posters baked by an older renderer so* they re-render with the current camera/backdrop. Only* server-rendered thumb/<uuid>.png keys are cleared; user@@ -75,10 +80,18 @@ const ADOPT_ONLY = has('adopt-only');const RENDER_ONLY = has('render-only');const LOOP = has('loop');+// The ledger repairs are pure Postgres work: they delete rows or clear a column,+// and never presign, render, or upload. --repair-only runs them and stops, so it+// needs no S3_* set. That matters because storage being broken is precisely when+// an operator needs the repair, and sending them to fetch Cloud Run credentials+// first made the undo unreachable at the only moment it counts.+const REPAIR_ONLY = has('repair-only');+const NEEDS_STORAGE = !has('status') && !REPAIR_ONLY;+// DATABASE_URL ships in .env.local, but the S3_* set does not: its authoritative// copy is the Cloud Run service env. Pointing every miss at --env-file sends the// operator back to the file that just failed them, so name the real source.-for (const required of ['DATABASE_URL', 'S3_BUCKET', 'S3_ACCESS_KEY_ID']) {+for (const required of ['DATABASE_URL', ...(NEEDS_STORAGE ? ['S3_BUCKET', 'S3_ACCESS_KEY_ID'] : [])]) {if (!process.env[required]) {const where = required.startsWith('S3_')? 'export the S3_* set from the Cloud Run service first (see docs/avatar-thumbnails.md, "Operating the backfill")'@@ -124,6 +137,9 @@ async function main() {console.log(`[backfill] restyle: cleared ${queued} old server-rendered poster(s) for re-render`);}+ // Repairs done; everything past here touches R2.+ if (REPAIR_ONLY) return;+// ── Phase 1: free adoption ────────────────────────────────────────────────if (!RENDER_ONLY) {let totalAdopted = 0;diff --git a/src/agents-live.js b/src/agents-live.jsindex 8c572737d..98fb232db 100644--- a/src/agents-live.js+++ b/src/agents-live.js@@ -13,12 +13,20 @@// at, and tear it down when they leave. That keeps live pixels available for any// agent on demand without paying for an idle browser per agent.//-// The SSE listeners are POOLED, not one-per-card. A browser caps concurrent-// connections per origin (6 on HTTP/1.1; the server's stream limit on HTTP/2),-// and an SSE stream is long-lived, so opening one per card meant the roster's-// first handful connected and every card after them sat on "Connecting" forever.-// Streams are now attached as a card nears the viewport and released once it is-// well past it, bounded by a pool sized from the origin's real transport.+// Two layers feed those screens, because they answer different questions:+//+// • Every mounted card gets its real activity from ONE batched request to+// /api/agents/activity (whole page, one round-trip), refreshed on a slow+// cadence. That is a poll, and a poll does not need a socket.+// • Cards near the viewport additionally hold a real SSE listener for live+// pixels, reactions and market-maker pushes, bounded by a pool sized from+// the origin's actual transport.+//+// It used to be one SSE stream per card. A browser caps concurrent connections+// per origin (6 on HTTP/1.1, a stream budget on HTTP/2) and an SSE stream never+// releases its slot, so on a 48-card roster the first six connected and the+// other 42 sat on "Connecting" forever while the page's own fetches queued+// behind them.import { parsePnlDelta, formatSol, formatUsd } from './shared/trade-pnl.js';import { mountAgentReactions } from './agent-reactions.js';@@ -944,6 +952,95 @@ function getStreamObserver() {return _streamObserver;}+// ── batched activity hydration ───────────────────────────────────────────────+// The always-available layer under the stream pool: one request returns the real+// agent_actions tail for every mounted card plus the set that currently has a+// live caster. This is what makes a card meaningful the moment it mounts, no+// matter how far down the wall it sits, and it is how a card outside the stream+// pool keeps a truthful terminal instead of a permanent "Standing by".++const ACTIVITY_BATCH_MAX = 60; // matches MAX_IDS in api/agents/activity.js+const ACTIVITY_BATCH_MS = 20_000; // refresh cadence for non-streamed cards+let _activityTimer = null;+let _activityInFlight = false;++// Fold a batch of DB-sourced entries into a card exactly as the SSE `log` event+// would, so a batch row and a streamed row render identically.+function applyActivityEntries(state, entries) {+ if (!Array.isArray(entries) || !entries.length) return;+ // A streaming card owns its own log; the batch must not overwrite fresher+ // caster-pushed history with the DB tail.+ if (state.es && state.entries.length) return;+ state.entries = entries;+ const newestTs = entries.reduce((m, en) => Math.max(m, Number(en?.ts) || 0), 0);+ if (newestTs > state.lastActionAt) state.lastActionAt = newestTs;+ entries.forEach((entry) => ingestCardPnl(state, entry));+ for (let i = entries.length - 1; i >= 0; i--) {+ if (entries[i]?.mm) { updateMmBadge(state, entries[i].mm, false); break; }+ }+ const lastForge = [...entries].reverse().map(parseForgeFrame).find(Boolean);+ if (lastForge && state.action) {+ state.action.textContent = lastForge.prompt ? `✦ forged: ${lastForge.prompt}` : '✦ forged a new avatar';+ state.card.classList.add('al-card--forged');+ }+ const lastHire = [...entries].reverse().find((e) => e?.meta?.kind === 'a2a_hire');+ if (lastHire) updateHireFlash(state, lastHire.meta, false);+ if (!isLiveNow(state)) {+ paintActivity(state);+ renderAge(state);+ const statusEl = state.card.querySelector('[data-status]');+ if (statusEl && !state.es && statusEl.textContent !== 'Paused') statusEl.textContent = 'Active';+ }+}++async function hydrateActivity(ids) {+ if (!ids.length || _activityInFlight) return;+ _activityInFlight = true;+ try {+ const res = await apiFetch('/api/agents/activity', {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ ids }),+ allowAnonymous: true,+ });+ if (!res.ok) return;+ const { activity, casting } = await res.json();+ for (const [id, entries] of Object.entries(activity || {})) {+ const state = _cards.get(id);+ if (state) applyActivityEntries(state, entries);+ }+ // An agent with live pixels earns a stream slot even if it sits outside the+ // pre-warm band: that is the whole point of a live wall.+ for (const id of casting || []) {+ const state = _cards.get(id);+ if (state && !state.es) ensureStream(state);+ }+ } catch { /* the cards keep whatever they last rendered */ }+ finally { _activityInFlight = false; }+}++// Hydrate the cards that have no stream of their own. One batch cannot cover an+// endlessly scrolled wall, so it is spent where it shows: what the viewer can+// reach right now first, then anything still holding a blank terminal, then the+// rest of the tail.+function flushActivity() {+ if (document.hidden) return;+ const near = [], blank = [], rest = [];+ for (const [id, state] of _cards) {+ if (state.es) continue;+ if (_nearView.has(id)) near.push(id);+ else if (!state.entries.length) blank.push(id);+ else rest.push(id);+ }+ const ids = [...near, ...blank, ...rest].slice(0, ACTIVITY_BATCH_MAX);+ hydrateActivity(ids);+}++function startActivityHydration() {+ if (_activityTimer) return;+ _activityTimer = setInterval(flushActivity, ACTIVITY_BATCH_MS);+}+// ── lifecycle ──────────────────────────────────────────────────────────────────function mountAgent(agent) {@@ -1109,6 +1206,9 @@ async function loadMore() {return;}agents.forEach(mountAgent);+ // One request gives the whole new page a real terminal straight away, before+ // the stream pool has reached any of it.+ flushActivity();updateStats();_arena.schedule();_showrunner?.refreshLive(); // fold the new page into the program@@ -1640,6 +1740,7 @@ startIdleRepaint();startWatchPings();startInfiniteScroll();startNetworthHydration();+startActivityHydration();_arena.start();// Boot the director once the first roster page is mounted: show the skeletondiff --git a/src/agora/passport-panel.js b/src/agora/passport-panel.jsindex 45e28aca1..b60f5fc17 100644--- a/src/agora/passport-panel.js+++ b/src/agora/passport-panel.js@@ -12,7 +12,7 @@// world stays interactive behind it. Esc closes; focus moves into the panel on// open and returns to the trigger on close.-import { professionColor } from './citizen-avatar.js';+import { professionColor, primaryProfessionKey, citizenProfessionLabel } from './citizen-avatar.js';import { fetchPassport } from './api.js';import { renderHandshake, parseIdentityProofs, hasDualIdentity } from './handshake.js';import { injectTrustSurfaceCss } from './trust-surface.css.js';@@ -229,9 +229,19 @@ export class PassportPanel {const reputation = onchain?.reputation ?? c.reputation ?? 0;const stake = onchain?.stakeAmount ?? c.stakeLamports;const grade = reputationGrade(reputation);- const professions = (c.professions && c.professions.length)- ? c.professions.map((p) => p.label)- : [c.profession || 'Citizen'];+ // Every capability the citizen may claim, but led by the craft it is known+ // for. The API returns the decoded bitmap in bit order, which always opens+ // with Fetcher (the baseline bit every citizen carries), so an Appraiser's+ // passport used to introduce her as a Fetcher under an Appraiser-coloured+ // dot. Hoist the primary; the rest keep their bit order.+ const primaryKey = primaryProfessionKey(c);+ const decoded = (c.professions && c.professions.length) ? c.professions.slice() : [];+ const professions = decoded.length+ ? [+ ...decoded.filter((p) => p.key === primaryKey),+ ...decoded.filter((p) => p.key !== primaryKey),+ ].map((p) => p.label)+ : [citizenProfessionLabel(c)];const stats = [{ label: 'Reputation', value: Number(reputation).toLocaleString('en-US'), sub: grade.label },diff --git a/src/agora/player-mode.js b/src/agora/player-mode.jsindex abc0c1b86..469cba1a7 100644--- a/src/agora/player-mode.js+++ b/src/agora/player-mode.js@@ -28,7 +28,7 @@ import {CLIP_IDLE, CLIP_WALK,} from '../game/avatar-rig.js';import { WalkNet } from '../walk-net.js';-import { buildLabelSprite } from './citizen-avatar.js';+import { buildLabelSprite, citizenProfessionLabel } from './citizen-avatar.js';import { CITY_HALF } from '../city/city-map.js';import {JUMP_VEL, GRAVITY,@@ -530,7 +530,7 @@ export async function mountPlayerMode(ctx) {x: pos.x,z: pos.z,name: c.displayName || 'Citizen',- profession: c.professions?.[0]?.label || c.profession || 'Citizen',+ profession: citizenProfessionLabel(c),busy: !!inst.busy, // live economy state — set when a real claim walks them to work});}