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(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.js
index 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_backfill
diff --git a/docs/x-memory-seeding.md b/docs/x-memory-seeding.md
index 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 handler
answers `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 not
The 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 than
the 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 at
https://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.html
index 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-zoom
fix, and the 44px tap-target floor. Loaded last so it wins on
diff --git a/public/app-next.css b/public/app-next.css
index 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.json
index 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.mjs
index 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.js
index 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 skeleton
diff --git a/src/agora/passport-panel.js b/src/agora/passport-panel.js
index 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.js
index 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
});
}