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.

docs(github-seed): document the token connect path, plus a swept /agi stage fix

nirholasf192c79e9f28
diff --git a/data/changelog.json b/data/changelog.json
index e4dd12785..b374a415a 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-08-16",
+ "title": "The AGI page no longer goes quiet when its 3D body cannot load",
+ "summary": "The AGI page is built around a live 3D body that reacts to the market, and when that model could not be fetched the page said nothing at all. The loading line disappeared on a timer whether or not anything had arrived, so the centrepiece became a silent empty panel with no explanation and no way to try again, while the decision stream and track record beside it carried on as normal. A body that fails to load now falls back to the platform's own avatar, so there is still something on the stage reacting to the agent's mood. If that cannot be fetched either, the stage says so plainly, makes clear that the agent is still trading and that the decisions and track record below are live and unaffected, and offers a button to try embodying again. The loading line now stays up until the body genuinely arrives instead of vanishing early, and the stage no longer re-requests a model it already knows is unreachable every twenty seconds. The page's description shown in search results and link previews was also carrying an older wording than the page itself.",
+ "tags": [
+ "fix",
+ "improvement"
+ ],
+ "link": "/agi"
+ },
{
"date": "2026-08-16",
"title": "Live Agents: every card on the wall now shows what its agent is actually doing",
diff --git a/docs/github-memory-seeding.md b/docs/github-memory-seeding.md
index 0a2d35bb0..974ff4c4f 100644
--- a/docs/github-memory-seeding.md
+++ b/docs/github-memory-seeding.md
@@ -5,15 +5,22 @@ READMEs you pick, distilled and written into the agent's long-term memory, so
it can speak concretely about what you build instead of guessing.
This lane is built around one constraint. Connecting your GitHub account is
-permission to read it. It is **not** permission to read all of it. The OAuth
+permission to read it. It is **not** permission to read all of it. The
connection unlocks the consent screen, and the consent screen is a per-item
catalog: your profile, your pinned repositories, your recent public
repositories, and a separate README tick per repository. **A seed reads exactly
the items you ticked and nothing else**, and the server enforces that by
refusing any selection that names an item the catalog never showed you.
+There are two ways to connect and they meet immediately: OAuth, one click,
+available when the deployment has a GitHub OAuth app registered; or a personal
+access token you mint yourself, available always, which is the way in when no
+OAuth app exists and which is refused outright if it carries more access than
+seeding can use. Both write the same encrypted connection record and lead to
+the same consent screen.
+
- **Surface**: Settings, Connected accounts, GitHub card at [/settings#connected-accounts](https://three.ws/settings#connected-accounts)
-- **API**: `/api/agents/:id/memory/seed/github`
+- **API**: `/api/agents/:id/memory/seed/github`, `/api/auth/github/token`
- **Related**: [Memory system](./memory.md), [X memory seeding](./x-memory-seeding.md), [Farcaster memory seeding](./farcaster-memory-seeding.md)
---
@@ -21,8 +28,9 @@ refusing any selection that names an item the catalog never showed you.
## How it fits together
```
- Connect GitHub (OAuth, read:user + public_repo, token stored encrypted)
- │ the connection alone reads and stores nothing
+ Connect GitHub (OAuth, or a personal access token you paste)
+ │ either way the token is stored encrypted, and the
+ │ connection alone reads and stores nothing
▼
GET /api/agents/:id/memory/seed/github
│ builds the consent catalog live from GitHub:
@@ -103,11 +111,62 @@ behind a broken replacement.
---
+## Connecting with a personal access token
+
+OAuth needs an operator to register a GitHub OAuth app (see Configuration
+below). Until that exists, `/api/auth/github/connect` can only answer `501`, so
+the Settings card offers the token path instead, and offers it as a secondary
+option even where OAuth works.
+
+You mint the token on GitHub, which is where consent happens exactly as it does
+on the OAuth screen. Tick **`read:user`** and nothing else: seeding reads a
+public profile, public repositories, and their READMEs, none of which needs
+more than that.
+
+```bash
+curl -s https://three.ws/api/auth/github/token --cookie "$JAR" \
+ -H 'content-type: application/json' -H "x-csrf-token: $CSRF" \
+ -d '{"token":"ghp_your_token_here"}'
+```
+
+```json
+{
+ "connected": true,
+ "connect_method": "token",
+ "token_kind": "classic",
+ "username": "you",
+ "connected_at": "2026-08-16T16:53:49.030Z",
+ "scopes": ["read:user"]
+}
+```
+
+**An over-privileged token is refused, not stored.** The endpoint reads the
+token's grants from GitHub's `x-oauth-scopes` response header and checks them
+against an allowlist (`ALLOWED_TOKEN_SCOPES` in
+[api/_lib/github-token.js](../api/_lib/github-token.js)): `read:user`,
+`user:email`, `user:follow`, `user`, `public_repo`, `repo:status`, `read:org`.
+Anything else, `repo` and `delete_repo` and every `admin:` scope included, comes
+back as `400 token_scope_refused` naming the offending scopes, and nothing is
+written. It is an allowlist rather than a denylist so a scope GitHub invents
+later is refused by default. `repo` is excluded deliberately: it reaches private
+repositories, and the catalog is public-only by construction, so it is strictly
+more access than the feature can ever use.
+
+Fine-grained tokens (`github_pat_…`) and GitHub App user tokens omit the scope
+header entirely; their permissions were already narrowed by whoever minted them,
+so they are accepted as they are and reported as `token_kind: "fine_grained"`.
+
+Disconnecting destroys our encrypted copy and deletes every seeded memory, the
+same as OAuth. It cannot revoke the token on GitHub's side, because GitHub
+exposes no way to delete a personal access token using that same token, so the
+response says so plainly (`grant_revoked: false`) and returns
+`revoke_url: "https://github.com/settings/tokens"` for you to finish the job.
+
## Configuration
-The consent catalog, the seed, and the revoke all run off a user's own OAuth
-token, so a deployment needs a GitHub OAuth app before the Connect button can
-do anything. Register one at
+OAuth is optional. Without it the token path above still works, and the whole
+lane (catalog, seed, revoke) behaves identically. To offer the one-click
+button, register an OAuth app at
[github.com/settings/developers](https://github.com/settings/developers) with
the authorization callback URL set to `<your origin>/api/auth/github/callback`
(production: `https://three.ws/api/auth/github/callback`), then set two
@@ -124,9 +183,11 @@ rotating `JWT_SECRET` invalidates stored tokens (users reconnect) rather than
decrypting them into garbage.
Until both variables are present, `GET /api/auth/github/status` answers
-`configured: false`, `/api/auth/github/connect` answers `501 not_configured`,
-and the Settings card renders an explicit "unavailable on this deployment"
-state instead of a button that cannot work. Everything else on the lane is
+`configured: false` and `/api/auth/github/connect` answers `501 not_configured`.
+The Settings card then leads with the token form rather than a button that
+cannot work. `status` always reports `token_connect.available: true` alongside
+the `create_url` that pre-selects the right scopes, which is how the card knows
+an unconfigured deployment is not a dead end. Everything else on the lane is
unaffected: no other feature depends on these variables.
---
@@ -205,8 +266,10 @@ the count. Idempotent.
Disconnecting GitHub from Settings (`DELETE /api/auth/github/disconnect`)
performs the same deletion across **all** of your agents in one transaction
-with the connection row itself, and then asks GitHub to revoke the OAuth grant
-(best effort; the local deletion does not wait on GitHub).
+with the connection row itself. For an OAuth connection it then asks GitHub to
+revoke the grant (best effort; the local deletion does not wait on GitHub). For
+a token connection it reports `grant_revoked: false` with a `revoke_url`,
+because no API can delete a personal access token using that token.
## Errors
@@ -216,6 +279,8 @@ with the connection row itself, and then asks GitHub to revoke the OAuth grant
| `csrf_missing` / `csrf_invalid` | 403 | A cookie-authenticated POST or DELETE arrived without a valid `x-csrf-token` |
| `not_found` | 404 | No such agent, or it is not yours (a malformed id also answers 404, never a 500) |
| `not_connected` | 412 | Connect GitHub first; the response carries `connect_url` |
+| `invalid_token` | 400 | GitHub rejected the pasted token (mistyped, truncated, or expired) |
+| `token_scope_refused` | 400 | The pasted token carries scopes outside the allowlist; `refused_scopes` names them |
| `invalid_selection` | 400 | A selected key is not in the catalog you were shown; `rejected` names each one |
| `empty_selection` | 400 | Pick your profile or at least one repository |
| `distill_error` | 502 | The selected material yielded no usable facts; add a README or another repository. Carries `window_refunded` |
@@ -245,7 +310,9 @@ rather than inviting a retry that would only earn a 429.
| HTTP surface (status, consent catalog, seed, revoke) | [api/agents/[id]/memory-seed-github.js](../api/agents/%5Bid%5D/memory-seed-github.js) |
| Catalog, selection narrowing, seed document, memory rows (pure, tested) | [api/_lib/github-seed.js](../api/_lib/github-seed.js) |
| GitHub REST/GraphQL client (profile, repos, pins, README, grant revoke) | [api/_lib/github-api.js](../api/_lib/github-api.js) |
-| HKDF token encryption shared by callback, seeding, and disconnect | [api/_lib/github-token.js](../api/_lib/github-token.js) |
-| OAuth connect, callback, status, disconnect | [api/auth/github/[action].js](../api/auth/github/%5Baction%5D.js) |
+| HKDF token encryption and the personal-access-token scope policy | [api/_lib/github-token.js](../api/_lib/github-token.js) |
+| Connect (OAuth and token), callback, status, disconnect | [api/auth/github/[action].js](../api/auth/github/%5Baction%5D.js) |
| Consent screen (renders the catalog with per-item checkboxes) | [public/settings/index.html](../public/settings/index.html) |
| Transform tests | [tests/github-memory-seed.test.js](../tests/github-memory-seed.test.js) |
+| Route tests for the seed endpoint | [tests/github-memory-seed-endpoint.test.js](../tests/github-memory-seed-endpoint.test.js) |
+| Scope policy and token-connect tests | [tests/github-token-connect.test.js](../tests/github-token-connect.test.js) |
diff --git a/prompts/swarm-100/route-agi.md b/prompts/swarm-100/route-agi.md
deleted file mode 100644
index 9c7863dc4..000000000
--- a/prompts/swarm-100/route-agi.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Route audit: /agi (The AGI: narrow by design)
-
-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==='/agi')console.log(JSON.stringify(g,null,2))"
-
-2. Find the serving implementation: grep "/agi" 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/agi
-
-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: /agi ("The AGI: narrow by design", section "crypto").
-Declared purpose: The first AGI, narrow by design: a single autonomous agent that is genuinely superhuman at one thing: trading memecoins on pump.fun (Solana): and deliberately nothing else. Watch its embodied 3D body react to the market in real time, read every decision it makes with its stated confidence, and hold it to a chain-proven track record. Outside that one domain, it claims nothing.
-
-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/agi. 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 /agi: 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-agi.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/agi.js b/src/agi.js
index 931dd22c7..831853fa5 100644
--- a/src/agi.js
+++ b/src/agi.js
@@ -170,26 +170,35 @@ function attachBody(stage, agent, source) {
if (source.agentId) el.setAttribute('agent-id', source.agentId);
else el.setAttribute('body', source.body);
- let settled = false;
- // Reveal only once the model is in; until then the boot line shows.
+ // `agent:ready` is the ONLY trustworthy success signal. The element also emits
+ // stray `load` events while its own sub-resources arrive, and treating those as
+ // success is what used to latch the stage as "loaded" seconds before the real
+ // `agent:error` landed, which then had nothing left to correct.
+ let ready = false;
+ let failed = false;
const reveal = () => {
- if (settled) return;
- settled = true;
- clearTimeout(failsafe);
el.classList.add('agi-loaded');
stage.querySelector('.agi-stage-boot')?.remove();
state.embodied = true;
if (state.data?.cognition) { applyMood(state.data.cognition); }
};
+ const onReady = () => {
+ ready = true;
+ clearTimeout(failsafe);
+ reveal();
+ };
// The component suppresses its own error card for non-chat embeds, so a dead
// model is otherwise completely silent. Fail over to the default body once,
- // then explain rather than leaving an empty stage.
+ // then explain rather than leaving an empty stage. This still runs after the
+ // failsafe reveal, so a late error corrects an empty stage instead of being
+ // swallowed by it.
const fail = () => {
- if (settled) return;
- settled = true;
+ if (ready || failed) return;
+ failed = true;
clearTimeout(failsafe);
el.remove();
state.el3d = null;
+ state.embodied = false;
if (!state.bodyFailover && source.agentId) {
state.bodyFailover = true;
attachBody(stage, agent, { body: DEFAULT_BODY });
@@ -197,13 +206,13 @@ function attachBody(stage, agent, source) {
}
renderStageFallback(stage, agent);
};
- el.addEventListener('agent:ready', reveal, { once: true });
- el.addEventListener('load', reveal, { once: true });
+ el.addEventListener('agent:ready', onReady, { once: true });
el.addEventListener('agent:error', fail);
- // Failsafe: if no event at all fires (older bundle), reveal rather than strand
- // the reader on the boot line. A bundle that does emit agent:error settles the
- // element first, so this can no longer paper over a genuine failure.
- const failsafe = setTimeout(reveal, 8000);
+ // Failsafe: if no event ever arrives (an older bundle that emits neither),
+ // reveal rather than strand the reader on the boot line forever. Held well
+ // past a normal cold load: revealing early just swaps the honest boot line
+ // for an empty stage on every slow connection.
+ const failsafe = setTimeout(reveal, 20000);
stage.insertBefore(el, stage.querySelector('.agi-stage-floor'));
state.el3d = el;
}