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(create-agent): collect the long rig job so one command really ends with a rigged character

nirholas449992c87020
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9ef016083..825a2b42a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Brownout** (`/brownout`): Every response from this API says where its data came from and how fresh it is, and every declared fallback has been proven by breaking the upstream it protects against, inside the real request path. Read the receipts: which provider refused, which one caught the request, and how old the answer was.
- **Companion** (`/companion`): A 3D companion that delivers your important messages in person. Connect your own Telegram bot, calendar, inbox, or phone, give each contact their own avatar and voice, and hear only what clears your bar.
+- **create-agent: one command, one 3D character** (`/docs/create-agent`): npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.
- **Docs · 3D Vision: let an agent see the model** (`/docs/3d-vision`): Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.
- **Docs · Agent vitals: can it act?** (`/docs/agent-vitals`): Every liveness check was green while ten of twelve autonomous agents had not acted in weeks. Capability attestation models an agent's preconditions as a causal graph and returns the root blocker plus the command that fixes it, instead of a checklist of symptoms.
- **Docs · Companion** (`/docs/companion`): The personal companion: connect your own Telegram bot, calendar, inbox, or phone, give your contacts a face and a voice, and have a 3D character deliver what matters in person. Bridges, triage rules, the SDK, the CLI, the MCP server, and the desktop app.
@@ -45,6 +46,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Knock: put a price on reaching you, and hear what gets through in person**: Every account can now open a door at three.ws/knock/<username> and set what one message from a stranger is worth, anywhere from a tenth of a cent to a thousand dollars, or free. Anyone can pay it to get exactly one message through: a person pays with the wallet already in their browser, and an agent pays over x402 with no human involved. The USDC settles straight to your own wallet; three.ws never holds it and takes none of it. What arrives is not another badge: your 3D companion walks on screen wherever you are on the site and says who is at the door and what they paid, ranked by that amount, so the expensive ones interrupt and the free ones wait in the feed. You set the price, the daily cap, the message length and a block list, and every one of those refusals happens before any payment, so a message that was never going to land is never one somebody was charged for. Only the one-line subject is ever read aloud. Senders get a receipt link they can check for your reply without an account here, which means answering someone never hands out your address. There is a browsable directory of open doors, an npm package and CLI for agents (@three-ws/knock), and an MCP server (@three-ws/knock-mcp) that deliberately holds no wallet: it quotes a paid door and stops, so a human always approves the spend. (`/knock`) `[feature, sdk]`
- **Model Diff: see exactly what changed between two 3D models**: Every 3D pipeline has one failure that costs more than all the others put together, and it is completely silent. Animation clips find a character's joints by name. Rename a bone, drop a joint, or run a file through a tool that renumbers things, and the model still loads, still renders, and never moves again. Nothing errors. You find out when somebody tells you the character is standing there frozen. Model Diff is the check that catches it. Drop two files and it tells you what actually changed: the geometry, the materials, the textures, the skeleton, the clips, with renames recognised as renames instead of one thing vanishing and an unrelated thing appearing. It ignores the meaningless noise a re-export always introduces and flags the edits that matter, and it grades every difference, so you can tell a recoloured jacket from a rig that just lost both eye joints. Both models load into the same 3D scene: lay one over the other, drag a line across to wipe between them, or stand them side by side, and click any line in the report to fly the camera to the thing it names. Nothing you drop is uploaded. The same engine is a free API anyone can call without a key, a command you can put in a build so a broken export fails it, and a tool your AI agent can use to check its own work before it publishes it. (`/diff`) `[feature, sdk, improvement]`
- **Next on the roadmap: your agent on your home screen**: A fifth phase has been added to the public roadmap: native widgets. Right now three.ws is something you open. The plan is for the agent you own to sit on your home screen and your desktop, showing itself and one live number about it, refreshed by the system without you opening anything, with a tap that drops you back into the right screen. Android is first, because the Android app is already built and signed: three.ws ships as a real app for Solana Seeker, and as of today Google confirms the app's release key against the site, so a three.ws link opens inside the app instead of a browser tab. Windows 11 follows through the installed web app, which needs no separate store submission, then macOS and iOS through a shared widget extension. None of it is shipped yet. It is written down, scoped and public so you can hold us to it, and the phase is on the roadmap in the repo along with the work order behind it. `[docs]`
+- **One command turns a sentence into a rigged 3D character you can put on your site**: Type `npm create @three-ws/agent "a friendly cartoon astronaut"` in a terminal and about a minute later you have a folder: the 3D model with a real skeleton so it can be posed and animated, a demo page that works when you double click it, and the two lines of HTML that put the character on your own website. No account, no API key, no signup, and nothing to install first. It also works from a photo, and it can make plain objects instead of characters. The same free lane the website uses is behind it, so what you get in the terminal is what you get on three.ws. (`/docs/create-agent`) `[feature, sdk]`
- **Photo uploads, avatar saves, launches and team tasks fail fast instead of hanging**: A handful of steps still had no time limit on the outside service they called. When that service accepted the connection and then went quiet, the request sat there until the platform killed it, and you got a spinner that ended in nothing: a photo-to-avatar upload that never came back, a saved model that never finished downloading, a coin launch stuck fetching its own thumbnail, an ordinals order whose status never loaded, a team task where one hired agent held up the whole run. Each of those now has a deadline and a clear answer when it is missed, and the ones that are safe to repeat retry once first. Anything that spends money or starts a generation is never repeated: it is bounded and then reported, so no upload is billed twice and no hire is paid twice. Saving a model from a link is also checked more tightly now, against the address it actually connects to and with the size limit applied while it downloads. `[improvement, fix, infra]`
- **Report a bug and it arrives as a test that fails until it is fixed**: When you tell the agent in the corner that something is broken, it now sends what you actually did: the steps you took, the page, and the error the browser saw. Those steps compile into a real test that fails while the bug is there and passes once it is gone, so the slowest part of fixing anything (working out how to make it happen again) is done before anyone starts. You can see every step that gets attached before you send, and nothing you typed into a field is ever recorded, only how much. The recorder is open source and works on any site: install @three-ws/witness. (`/docs/witness`) `[feature, sdk, improvement]`
- **Tell the agent in the corner what is broken**: The companion that walks your pages now listens. When a page actually fails, it turns and asks what you were doing, and the report it sends carries what you should never have to type: the page, the exact build it happened on, your screen size, and the errors the browser recorded at that moment. You can also open it any time from the control beside the avatar, and dictate instead of typing. Reports are grouped so that twenty people hitting one problem read as one problem, and every one of them is read by a person before anything changes. (`/docs/feedback`) `[feature, improvement]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 13ccc1da6..07cfd16f9 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -49,6 +49,7 @@ bottom.
| Walkthroughs (interactive product tours from real frames) | Index [pages/walkthroughs.html](pages/walkthroughs.html) + [src/walkthroughs-index.js](src/walkthroughs-index.js) `→ /walkthroughs`, player [pages/walkthrough.html](pages/walkthrough.html) + [src/walkthrough.js](src/walkthrough.js) `→ /walkthroughs/<slug>` (routed in [vercel.json](vercel.json), mirrored by the Vite dev middleware in [vite.config.js](vite.config.js)), pure step geometry [src/walkthrough-geometry.js](src/walkthrough-geometry.js), generated manifest + screenshot sets [public/walkthroughs/](public/walkthroughs) captured by [scripts/capture-walkthroughs.mjs](scripts/capture-walkthroughs.mjs) | Live | Step-by-step guided tours (forge a 3D model, build an agent, embed an avatar, find an agent worth using) built from real frames captured on the live product: each step zooms and pans to the element it describes, cuts a spotlight around it, and anchors a callout, so it reads like a screen recording but is a handful of deep-linkable, keyboard-operable JPEGs that degrade to annotated stills under reduced motion. Index and player read the same generated manifest, so a walkthrough that did not capture cleanly cannot be advertised. Registered in [data/pages.json](data/pages.json). |
| Cross-entity search | [pages/search.html](pages/search.html) `→ /search`, backend [api/search.js](api/search.js) + query layer [api/_lib/cross-search.js](api/_lib/cross-search.js) | Live | The one search across every creation type — avatars, on-chain/Solana agents, forged 3D models, worlds, and coins. Federates (not one SQL UNION — the stores are genuinely heterogeneous, two of five aren't even in the same database) five parallel queries, normalizes into one card shape, and ranks by recency plus real signals (follower count via `user_follows`, remix count, view count) — see the file header in `api/search.js` for the full unify-vs-federate writeup. Model results carry a working "Remix — $0.25" action against the existing paid rail ([api/x402/remix-asset.js](api/x402/remix-asset.js)), reused from [pages/creations.html](pages/creations.html) rather than re-derived. Coin search checks three.ws's own launch directory (`pump_agent_mints`) first, then falls back to market-wide pump.fun/Birdeye search for broader coverage (those external matches carry no verified timestamp or creator profile, and are ranked/labelled accordingly). Linked from the Discover nav menu. |
| Cross-surface rankings, streaks & badges | [pages/rankings.html](pages/rankings.html) `→ /rankings`, backend [api/leaderboard/unified.js](api/leaderboard/unified.js), streak/badge engine [api/_lib/streaks.js](api/_lib/streaks.js) (migration [api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql](api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql)), daily Top-10 badge sweep [api/cron/leaderboard-rollup.js](api/cron/leaderboard-rollup.js) | Live | Five real, queried leaderboard metrics — creations (forge models + worlds), remixes received, coin launches, followers, and walk distance (signed-in walkers, all-time) — ranked live with the viewer's own rank pinned even off-page. Every signed-in qualifying action (login, a finished forge model, a saved world, a `/walk` session) rolls a per-user daily streak in `user_streaks` via `recordDailyActivity()`, called from [api/_lib/auth.js](api/_lib/auth.js), [api/_lib/forge-store.js](api/_lib/forge-store.js), [api/_lib/diorama-store.js](api/_lib/diorama-store.js), and [api/walk/metrics.js](api/walk/metrics.js). Four real earned badges persist in `user_badges`: First Creation, Remixed (awarded in [api/x402/remix-asset.js](api/x402/remix-asset.js) when a remix lands on your creation), 7-Day Streak, and a daily-refreshed `top10_<metric>` per leaderboard. Streak + badges surface on the profile ([pages/profile.html](pages/profile.html)) and the Rankings page itself. Rejected metrics (documented in `api/leaderboard/unified.js`'s header): royalties earned in USD (the settlement record is a single overwritten JSONB column, not a cumulative ledger) and `/play` activity (no per-human-user session table exists). |
+| create-agent (one command, one 3D character) | [packages/create-agent/](packages/create-agent) (client [src/forge.js](packages/create-agent/src/forge.js), scaffold [src/scaffold.js](packages/create-agent/src/scaffold.js), CLI [bin/create-agent.js](packages/create-agent/bin/create-agent.js)), server tools [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) | Live | `npm create @three-ws/agent "a friendly cartoon astronaut"` generates a textured figure, rigs it, downloads the GLB, and writes a folder with a working demo page and the embed snippet. No account and no API key: it rides the public, keyless JSON-RPC tools on [/api/mcp-studio](api/_mcp-studio) (`forge_avatar`, `forge_free`, `rig_mesh`) that the platform already exposes to MCP clients. A rigged character reliably outlives the endpoint's inline wait, so the client collects the returned poll handle and, when the job that finished was only the mesh, rigs it before reporting done: that is what the `stage` field on a pending result exists for. Progress is real elapsed time, never an invented bar. Docs [docs/create-agent.md](docs/create-agent.md). Tests: [tests/create-agent.test.js](tests/create-agent.test.js) |
| Glance (agent cards for home screens, READMEs and chat) | Page [public/glance/index.html](public/glance/index.html) `-> /glance` (+ [glance-page.js](public/glance/glance-page.js), [glance.css](public/glance/glance.css)), hosted element [public/glance/element.js](public/glance/element.js), endpoints [api/glance/card.js](api/glance/card.js) / [api/glance/mine.js](api/glance/mine.js) / [api/glance/template.js](api/glance/template.js), model [api/_lib/glance-card.js](api/_lib/glance-card.js), SVG [api/_lib/glance-svg.js](api/_lib/glance-svg.js), Adaptive Card [api/_lib/glance-adaptive.js](api/_lib/glance-adaptive.js), Windows widget worker [public/glance-sw.js](public/glance-sw.js) (imported by the VitePWA service worker, manifest `widgets` member in [vite.config.js](vite.config.js)), npm client [packages/agent-glance/](packages/agent-glance) | Live | One agent reduced to what fits in an OS widget slot: name, one live number (actions in the last 24h), and a link back. The same model renders four ways from one endpoint (JSON, SVG, Adaptive Card, and the `<agent-glance>` element), which is what keeps a new surface a rendering job rather than a data job. Windows 11 installs the widget straight from the PWA manifest (no store submission); Android, macOS and iOS are phase 5 of the roadmap and consume the same card. Deliberately not the 3D embed: no widget host on any of these platforms can run WebGL, so the body stays at [/widgets](public/widgets-gallery/index.html) and the status lives here. Private avatars never leak (the thumbnail is attached only for a public or unlisted avatar; everything else draws a generated monogram). Spec [specs/GLANCE_CARD.md](specs/GLANCE_CARD.md), docs [docs/glance.md](docs/glance.md). Tests: [tests/glance-card.test.js](tests/glance-card.test.js), [tests/glance-sw.test.js](tests/glance-sw.test.js), [tests/agent-glance-sdk.test.js](tests/agent-glance-sdk.test.js) |
| Daily Match (agent output arena) | [pages/daily-match.html](pages/daily-match.html) `→ /daily-match`, backend [api/leaderboard/daily-match.js](api/leaderboard/daily-match.js) | Live | Live daily standings ranking public agents by real output shipped since 00:00 UTC: agent_actions events, sniper + pump trades, confirmed skill sales, and coin launches, with realized sniper P&L shown for context (never scored). Computed live per request (no rollup cron), resets naturally at UTC midnight; includes yesterday's champion and a live-output feed. Reputation-first: no payouts hang off the score. Format adopted with credit from Bowyer's Arena (bowyer.app/arena), who build their agent pages on three.ws avatars. |
| KOL Tracker | [pages/tracker.html](pages/tracker.html) `→ /tracker`, backend [api/kol/[action].js](api/kol/%5Baction%5D.js) `→ GET /api/kol/tracker?window=&limit=`, aggregator [src/kol/tracker.js](src/kol/tracker.js), wallet list [src/kol/wallet-store.js](src/kol/wallet-store.js) (bundled [src/kol/wallets.json](src/kol/wallets.json) + admin R2 imports via `POST /api/kol/import-gmgn`), FIFO P&L engine [src/kol/wallet-pnl.js](src/kol/wallet-pnl.js), cached X follower/avatar lookup [src/kol/x-profile.js](src/kol/x-profile.js) | Live | Solana crypto KOLs ranked by realized P&L computed from each tracked wallet's own on-chain trade history (24h/7d/30d), with win rate, volume, and trade count — every number traceable to real trades, never a competitor's computed leaderboard. A wallet only shows an X handle/avatar/follower-count when an admin has explicitly attached a verified `xHandle` via `import-gmgn`'s `xHandles` map (never inferred or scraped); unattached wallets rank by wallet address alone. Rows with no configured trade source (`PUMPFUN_BOT_URL`) fall back to an imported `pnlUsd`/`winRate` labeled with its `pnlSource` rather than fabricating on-chain numbers. Prewarm cron: [api/cron/kol-tracker-refresh.js](api/cron/kol-tracker-refresh.js). |
diff --git a/api/_mcp-studio/tools.js b/api/_mcp-studio/tools.js
index 3116f670f..7b8eb8a6e 100644
--- a/api/_mcp-studio/tools.js
+++ b/api/_mcp-studio/tools.js
@@ -147,7 +147,7 @@ function toolError(message) {
// quietly finished minutes later and the caller never learned. The job handle
// is public (the free /api/forge poll endpoint takes it with no auth), so hand
// it over and let the caller collect the result.
-function pendingResult({ base, jobId, what, prompt, etaRemainingSeconds }) {
+function pendingResult({ base, jobId, what, prompt, etaRemainingSeconds, stage = 'mesh' }) {
// The ChatGPT pipeline's own endpoint, not /api/forge: the whole point of
// the clone is that this surface can evolve independently.
const pollUrl = `${base}/api/gpt-forge?job=${encodeURIComponent(jobId)}`;
@@ -164,6 +164,11 @@ function pendingResult({ base, jobId, what, prompt, etaRemainingSeconds }) {
status: 'pending',
jobId,
pollUrl,
+ // Which half of the pipeline is still running. A client that collects
+ // the job needs this to know whether the GLB it gets back is a bare
+ // mesh (rig it) or the finished rig (use it). Identifier-free, so it
+ // costs the data-minimization rule nothing.
+ stage,
...(eta ? { etaRemainingSeconds: eta } : {}),
...(prompt ? { prompt } : {}),
},
@@ -424,7 +429,7 @@ async function handleRigMesh(args, _auth, req) {
} catch (err) {
return toolError(failureMessage(err));
}
- if (job._timedOut && job.job_id) return pendingResult({ base, jobId: job.job_id, what: 'rigged model', etaRemainingSeconds: job.eta_remaining_seconds });
+ if (job._timedOut && job.job_id) return pendingResult({ base, jobId: job.job_id, what: 'rigged model', etaRemainingSeconds: job.eta_remaining_seconds, stage: 'rig' });
if (job._timedOut || !job.glb_url) return toolError('Rigging is taking longer than expected. Please try again.');
return ok({ glbUrl: job.glb_url, base, kind: 'rigged model', rigged: true });
}
@@ -465,7 +470,7 @@ async function handleForgeAvatar(args, _auth, req) {
} catch (err) {
return toolError(failureMessage(err));
}
- if (gen._timedOut && gen.job_id) return pendingResult({ base, jobId: gen.job_id, what: 'avatar mesh (rig it with rig_mesh once done)', prompt: prompt || undefined, etaRemainingSeconds: gen.eta_remaining_seconds });
+ if (gen._timedOut && gen.job_id) return pendingResult({ base, jobId: gen.job_id, what: 'avatar mesh (rig it with rig_mesh once done)', prompt: prompt || undefined, etaRemainingSeconds: gen.eta_remaining_seconds, stage: 'mesh' });
if (gen._timedOut || !gen.glb_url) return toolError('Generation is taking longer than expected. Please try again.');
// Stage 2 — auto-rig the generated mesh.
@@ -494,7 +499,7 @@ async function handleForgeAvatar(args, _auth, req) {
],
};
}
- if (rigged._timedOut && rigged.job_id) return pendingResult({ base, jobId: rigged.job_id, what: 'avatar rig', prompt: prompt || undefined, etaRemainingSeconds: rigged.eta_remaining_seconds });
+ if (rigged._timedOut && rigged.job_id) return pendingResult({ base, jobId: rigged.job_id, what: 'avatar rig', prompt: prompt || undefined, etaRemainingSeconds: rigged.eta_remaining_seconds, stage: 'rig' });
if (rigged._timedOut || !rigged.glb_url) return toolError('Rigging is taking longer than expected. Please try again.');
return ok({ glbUrl: rigged.glb_url, base, kind: 'avatar', prompt: prompt || undefined, rigged: true, referenceImageUrl: gen.preview_image_url });
}
diff --git a/data/changelog.json b/data/changelog.json
index 049ba7ad3..943b60bda 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-28",
+ "title": "One command turns a sentence into a rigged 3D character you can put on your site",
+ "summary": "Type `npm create @three-ws/agent \"a friendly cartoon astronaut\"` in a terminal and about a minute later you have a folder: the 3D model with a real skeleton so it can be posed and animated, a demo page that works when you double click it, and the two lines of HTML that put the character on your own website. No account, no API key, no signup, and nothing to install first. It also works from a photo, and it can make plain objects instead of characters. The same free lane the website uses is behind it, so what you get in the terminal is what you get on three.ws.",
+ "tags": [
+ "feature",
+ "sdk"
+ ],
+ "link": "/docs/create-agent"
+ },
{
"date": "2026-08-28",
"title": "The Oracle stopped grading itself on the wrong question, and started learning on a clock",
diff --git a/data/pages.json b/data/pages.json
index d260316bb..39cb04075 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -746,6 +746,14 @@
"changefreq": "monthly",
"added": "2026-04-17"
},
+ {
+ "path": "/docs/create-agent",
+ "title": "create-agent: one command, one 3D character",
+ "description": "npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-08-28"
+ },
{
"path": "/docs/glance",
"title": "Glance: agent cards for home screens",
diff --git a/packages/create-agent/src/forge.js b/packages/create-agent/src/forge.js
index 26ccf99f4..c7c63a634 100644
--- a/packages/create-agent/src/forge.js
+++ b/packages/create-agent/src/forge.js
@@ -33,6 +33,12 @@ export class ForgeError extends Error {
}
}
+/** The tool's human-readable line, when it sent one. */
+function textOf(result) {
+ const text = result?.content?.find?.((c) => c?.type === 'text')?.text;
+ return typeof text === 'string' ? text.split('\n')[0] : '';
+}
+
/**
* Normalize whatever the tool returned into one shape.
* Exported because it is the part worth testing without a network.
@@ -45,11 +51,32 @@ export function readForgeResult(body, { kind }) {
}
const result = body?.result;
const structured = result?.structuredContent || result;
+
+ // A generation that outlives the endpoint's inline wait hands back a public
+ // poll handle instead of a model. That is the NORMAL path for a rigged
+ // character (generate plus rig is minutes of GPU time), not an error: collect
+ // the job rather than failing the command.
+ if (structured?.status === 'pending' && structured.jobId) {
+ return {
+ pending: true,
+ jobId: structured.jobId,
+ pollUrl: structured.pollUrl,
+ stage: structured.stage || 'mesh',
+ etaSeconds: Number(structured.etaRemainingSeconds) || null,
+ };
+ }
+ if (result?.isError) {
+ throw new ForgeError(textOf(result) || 'the forge could not build that', { code: 'tool_error' });
+ }
+
const glbUrl = structured?.glbUrl || structured?.riggedGlbUrl || structured?.modelUrl;
if (!glbUrl) {
- throw new ForgeError('the forge answered without a model URL', { code: 'no_model' });
+ throw new ForgeError(textOf(result) || 'the forge answered without a model URL', {
+ code: 'no_model',
+ });
}
return {
+ pending: false,
kind: structured.kind || kind,
glbUrl,
meshUrl: structured.meshUrl || null,
@@ -119,13 +146,25 @@ export async function callForge({
if (!res.ok) {
throw new ForgeError(`three.ws answered ${res.status}`, { code: `http_${res.status}` });
}
- const result = readForgeResult(await res.json(), {
- kind: tool === 'forge_avatar' ? 'avatar' : 'model',
- });
+ const kind = tool === 'forge_avatar' ? 'avatar' : 'model';
+ let result = readForgeResult(await res.json(), { kind });
+
+ if (result.pending) {
+ clearInterval(heartbeat);
+ result = await collectJob(result, {
+ kind,
+ doFetch,
+ origin,
+ signal: controller.signal,
+ startedAt,
+ onProgress,
+ });
+ }
+
onProgress({
phase: 'done',
elapsedMs: Date.now() - startedAt,
- message: 'model ready',
+ message: result.rigged ? 'rigged model ready' : 'model ready',
});
return result;
} catch (err) {
@@ -147,6 +186,106 @@ export async function callForge({
}
}
+
+// How often to ask a running job whether it is done. Long enough that a
+// ten-minute render is a handful of requests, short enough that the CLI reacts
+// within a few seconds of the model landing.
+const POLL_EVERY_MS = 5000;
+
+/**
+ * Collect a job that outlived the endpoint's inline wait.
+ *
+ * `stage` says what the job produces: a bare `mesh` (which still needs rigging)
+ * or the finished `rig`. Returning a T-posed mesh to someone who asked for a
+ * rigged character would be the quiet kind of wrong, so the mesh case is rigged
+ * here rather than reported as done.
+ */
+async function collectJob(pending, { kind, doFetch, origin, signal, startedAt, onProgress }) {
+ let job = pending;
+ let glbUrl = await pollUntilDone(job, { doFetch, signal, startedAt, onProgress });
+
+ if (kind === 'avatar' && job.stage === 'mesh') {
+ onProgress({
+ phase: 'working',
+ elapsedMs: Date.now() - startedAt,
+ message: 'mesh done, adding the skeleton',
+ });
+ const res = await doFetch(new URL(RPC_PATH, origin), {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', accept: 'application/json' },
+ body: JSON.stringify({
+ jsonrpc: '2.0',
+ id: 2,
+ method: 'tools/call',
+ params: { name: 'rig_mesh', arguments: { glb_url: glbUrl } },
+ }),
+ signal,
+ });
+ if (!res.ok) throw new ForgeError(`three.ws answered ${res.status}`, { code: `http_${res.status}` });
+ const rigResult = readForgeResult(await res.json(), { kind: 'avatar' });
+ if (!rigResult.pending) return { ...rigResult, rigged: true };
+ job = rigResult;
+ glbUrl = await pollUntilDone(job, { doFetch, signal, startedAt, onProgress });
+ }
+
+ return {
+ pending: false,
+ kind,
+ glbUrl,
+ meshUrl: null,
+ viewerUrl: `${FORGE_ORIGIN}/viewer?src=${encodeURIComponent(glbUrl)}`,
+ studioUrl: null,
+ rigged: kind === 'avatar',
+ backend: null,
+ durationMs: Date.now() - startedAt,
+ };
+}
+
+async function pollUntilDone(job, { doFetch, signal, startedAt, onProgress }) {
+ const pollUrl = job.pollUrl || `${FORGE_ORIGIN}/api/gpt-forge?job=${encodeURIComponent(job.jobId)}`;
+ for (;;) {
+ if (signal?.aborted) throw new ForgeError('the wait was cancelled', { code: 'timeout' });
+ await sleep(POLL_EVERY_MS, signal);
+ const res = await doFetch(pollUrl, { headers: { accept: 'application/json' }, signal });
+ if (!res.ok) throw new ForgeError(`the job endpoint answered ${res.status}`, { code: `http_${res.status}` });
+ const body = await res.json();
+ const status = String(body?.status || '').toLowerCase();
+ if (status === 'done' || status === 'succeeded' || status === 'completed') {
+ const url = body.glb_url || body.glbUrl;
+ if (!url) throw new ForgeError('the job finished without a model URL', { code: 'no_model' });
+ return url;
+ }
+ if (status === 'error' || status === 'failed' || status === 'canceled') {
+ throw new ForgeError(body?.error || body?.message || 'the job failed', { code: 'job_failed' });
+ }
+ onProgress({
+ phase: 'working',
+ elapsedMs: Date.now() - startedAt,
+ message: describeJobWait(job, Date.now() - startedAt),
+ });
+ }
+}
+
+function describeJobWait(job, elapsedMs) {
+ const s = Math.round(elapsedMs / 1000);
+ const what = job.stage === 'rig' ? 'rigging' : 'sculpting the mesh';
+ return `${what} (${s}s)`;
+}
+
+function sleep(ms, signal) {
+ return new Promise((resolve, reject) => {
+ const t = setTimeout(resolve, ms);
+ signal?.addEventListener(
+ 'abort',
+ () => {
+ clearTimeout(t);
+ reject(new ForgeError('the wait was cancelled', { code: 'timeout' }));
+ },
+ { once: true },
+ );
+ });
+}
+
function describeWait(elapsedMs, tool) {
const s = Math.round(elapsedMs / 1000);
if (tool === 'forge_avatar') {
diff --git a/public/changelog.json b/public/changelog.json
index f28624861..e2e831e75 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-28T06:25:09.789Z",
+ "generated_at": "2026-08-28T06:32:04.505Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -26,6 +26,16 @@
"launch"
]
},
+ {
+ "date": "2026-08-28",
+ "type": "launch",
+ "title": "create-agent: one command, one 3D character",
+ "summary": "npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.",
+ "link": "/docs/create-agent",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-08-28",
"type": "launch",
@@ -405,6 +415,17 @@
"docs"
]
},
+ {
+ "date": "2026-08-28",
+ "type": "update",
+ "title": "One command turns a sentence into a rigged 3D character you can put on your site",
+ "summary": "Type `npm create @three-ws/agent \"a friendly cartoon astronaut\"` in a terminal and about a minute later you have a folder: the 3D model with a real skeleton so it can be posed and animated, a demo page that works when you double click it, and the two lines of HTML that put the character on your own website. No account, no API key, no signup, and nothing to install first. It also works from a photo, and it can make plain objects instead of characters. The same free lane the website uses is behind it, so what you get in the terminal is what you get on three.ws.",
+ "link": "/docs/create-agent",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-08-28",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 7e38eef00..7da770b3a 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -22,6 +22,14 @@
<category>launch</category>
<description>A 3D companion that delivers your important messages in person. Connect your own Telegram bot, calendar, inbox, or phone, give each contact their own avatar and voice, and hear only what clears your bar.</description>
</item>
+ <item>
+ <title>create-agent: one command, one 3D character</title>
+ <link>https://three.ws/docs/create-agent</link>
+ <guid isPermaLink="false">2026-08-28:create-agent: one command, one 3D character</guid>
+ <pubDate>Fri, 28 Aug 2026 12:00:00 GMT</pubDate>
+ <category>launch</category>
+ <description>npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.</description>
+ </item>
<item>
<title>Docs · 3D Vision: let an agent see the model</title>
<link>https://three.ws/docs/3d-vision</link>
@@ -318,6 +326,14 @@
<category>docs</category>
<description>A fifth phase has been added to the public roadmap: native widgets. Right now three.ws is something you open. The plan is for the agent you own to sit on your home screen and your desktop, showing itself and one live number about it, refreshed by the system without you opening anything, with a tap that drops you back into the right screen. Android is first, because the Android app is already built and signed: three.ws ships as a real app for Solana Seeker, and as of today Google confirms the app's release key against the site, so a three.ws link opens inside the app instead of a browser tab. Windows 11 follows through the installed web app, which needs no separate store submission, then macOS and iOS through a shared widget extension. None of it is shipped yet. It is written down, scoped and public so you can hold us to it, and the phase is on the roadmap in the repo along with the work order behind it.</description>
</item>
+ <item>
+ <title>One command turns a sentence into a rigged 3D character you can put on your site</title>
+ <link>https://three.ws/docs/create-agent</link>
+ <guid isPermaLink="false">2026-08-28:One command turns a sentence into a rigged 3D character you can put on your site</guid>
+ <pubDate>Fri, 28 Aug 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Type `npm create @three-ws/agent &quot;a friendly cartoon astronaut&quot;` in a terminal and about a minute later you have a folder: the 3D model with a real skeleton so it can be posed and animated, a demo page that works when you double click it, and the two lines of HTML that put the character on your own website. No account, no API key, no signup, and nothing to install first. It also works from a photo, and it can make plain objects instead of characters. The same free lane the website uses is behind it, so what you get in the terminal is what you get on three.ws.</description>
+ </item>
<item>
<title>Photo uploads, avatar saves, launches and team tasks fail fast instead of hanging</title>
<link>https://three.ws/changelog</link>
diff --git a/public/features.json b/public/features.json
index fd9fc4951..6c88fe11c 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-28T06:25:09.735Z",
+ "generated_at": "2026-08-28T06:32:04.493Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
@@ -902,6 +902,16 @@
"tags": [],
"showcase": false
},
+ {
+ "path": "/docs/create-agent",
+ "title": "create-agent: one command, one 3D character",
+ "description": "npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.",
+ "added": "2026-08-28",
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": false
+ },
{
"path": "/docs/glance",
"title": "Glance: agent cards for home screens",
diff --git a/public/llms-full.txt b/public/llms-full.txt
index 1d38f5a93..94d4de9e0 100644
--- a/public/llms-full.txt
+++ b/public/llms-full.txt
@@ -552,6 +552,12 @@ URL: https://three.ws/artifact
Renders Claude artifact bundles as standalone embeddable apps.
+### create-agent: one command, one 3D character
+
+URL: https://three.ws/docs/create-agent
+
+npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.
+
### Glance: agent cards for home screens
URL: https://three.ws/docs/glance
diff --git a/public/llms.txt b/public/llms.txt
index 2b9a2af19..5e107cc45 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -118,6 +118,7 @@ Create and customize an agent.
- [glTF Validator](https://three.ws/validation): Khronos-spec validator for glTF/GLB files. Paste a URL or upload a model.
- [Widget Studio](https://three.ws/studio): Pick an avatar, configure embed options, copy a one-line snippet for your site.
- [Artifact Viewer](https://three.ws/artifact): Renders Claude artifact bundles as standalone embeddable apps.
+- [create-agent: one command, one 3D character](https://three.ws/docs/create-agent): npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.
- [Glance: agent cards for home screens](https://three.ws/docs/glance): Put a three.ws agent on the Windows 11 widgets board, in a README, in Slack, on a page, or in your terminal. Endpoint, element, widget worker and npm client.
- [Glance](https://three.ws/glance): Your three.ws agent on every home screen: a live card for the Windows 11 widgets board, a README, Slack, or any page.
- [Widgets Gallery](https://three.ws/widgets): Pre-built chat, voice, and 3D-avatar widgets you can drop into any page.
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index 5f2d4a26f..a6a281e95 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -83,7 +83,7 @@
<main class="sm-wrap">
<div class="sm-hero">
<h1>Sitemap</h1>
- <p>All 869 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
+ <p>All 870 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
<div class="sm-formats">
<a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
<a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>
@@ -95,7 +95,7 @@
</div>
<div class="sm-filter">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>
- <input id="sm-filter-input" type="search" placeholder="Filter 869 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
+ <input id="sm-filter-input" type="search" placeholder="Filter 870 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
<kbd aria-hidden="true">/</kbd>
</div>
<p class="sm-filter-count" id="sm-filter-count" role="status" aria-live="polite"></p>
@@ -135,6 +135,14 @@
<span class="sm-desc">Deliver a message in person: a 3D character walks onto your page and tells the user what happened. Open SDK, one line of code, an accessible fallback, and a CLI that announces when your build finishes.</span>
</a>
</li>
+ <li>
+ <a href="/docs/create-agent">
+ <span class="sm-new-date">Aug 28, 2026</span>
+ <span class="sm-title">create-agent: one command, one 3D character</span>
+ <span class="sm-path">/docs/create-agent</span>
+ <span class="sm-desc">npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.</span>
+ </a>
+ </li>
<li>
<a href="/docs/glance">
<span class="sm-new-date">Aug 28, 2026</span>
@@ -167,14 +175,6 @@
<span class="sm-desc">curl three.ws/tty and a rigged 3D agent walks in your terminal. A software rasterizer streams ANSI frames over HTTP: no GPU, no WebGL, nothing to install. Also the @three-ws/tty CLI and library for rendering any GLB in a terminal.</span>
</a>
</li>
- <li>
- <a href="/stream">
- <span class="sm-new-date">Aug 28, 2026</span>
- <span class="sm-title">Progressive Avatars</span>
- <span class="sm-path">/stream</span>
- <span class="sm-desc">A3S packs a GLB into nested layers whose first 50 KB is already a complete, skinned, spec-valid avatar, then refines it in place over plain HTTP range requests. Live side-by-side against a classic GLB load.</span>
- </a>
- </li>
</ul>
</section>
<nav class="sm-toc" aria-label="Sections">
@@ -593,7 +593,7 @@
<section class="sm-section" id="build">
<header>
- <h2>Build<span class="sm-count" data-count>65</span></h2>
+ <h2>Build<span class="sm-count" data-count>66</span></h2>
<p class="sm-section-desc">Create and customize an agent.</p>
</header>
<ul class="sm-list">
@@ -821,6 +821,13 @@
<span class="sm-desc">Renders Claude artifact bundles as standalone embeddable apps.</span>
</a>
</li>
+ <li>
+ <a href="/docs/create-agent">
+ <span class="sm-title">create-agent: one command, one 3D character</span>
+ <span class="sm-path">/docs/create-agent</span>
+ <span class="sm-desc">npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.</span>
+ </a>
+ </li>
<li>
<a href="/docs/glance">
<span class="sm-title">Glance: agent cards for home screens</span>
diff --git a/tests/create-agent.test.js b/tests/create-agent.test.js
index dfc8662af..847bd0431 100644
--- a/tests/create-agent.test.js
+++ b/tests/create-agent.test.js
@@ -290,3 +290,83 @@ describe('createAgent', () => {
await expect(readdir(out)).rejects.toThrow();
});
});
+
+describe('a job that outlives the inline wait', () => {
+ // The normal path for a rigged character: the endpoint hands back a public
+ // poll handle instead of a model, and the client has to collect it.
+ function pendingRpc(stage, jobId = 'job_1') {
+ return {
+ ok: true,
+ status: 200,
+ json: async () => ({
+ result: {
+ structuredContent: {
+ status: 'pending',
+ jobId,
+ pollUrl: `https://three.ws/api/gpt-forge?job=${jobId}`,
+ stage,
+ etaRemainingSeconds: 40,
+ },
+ },
+ }),
+ };
+ }
+ const jobDone = (glb) => ({ ok: true, status: 200, json: async () => ({ status: 'done', glb_url: glb }) });
+ const jobQueued = { ok: true, status: 200, json: async () => ({ status: 'queued' }) };
+
+ it('reads a pending answer as a job to collect, not as a failure', () => {
+ const body = { result: { structuredContent: { status: 'pending', jobId: 'j', pollUrl: 'p', stage: 'rig' } } };
+ expect(readForgeResult(body, { kind: 'avatar' })).toMatchObject({
+ pending: true,
+ jobId: 'j',
+ stage: 'rig',
+ });
+ });
+
+ it('polls the job until it is done, through a queued tick', async () => {
+ const calls = [];
+ const fetchImpl = vi.fn(async (url) => {
+ calls.push(String(url));
+ if (String(url).includes('mcp-studio')) return pendingRpc('rig');
+ return calls.filter((c) => c.includes('gpt-forge')).length === 1
+ ? jobQueued
+ : jobDone('https://three.ws/cdn/x/rigged.glb');
+ });
+ const made = await callForge({ tool: 'forge_avatar', args: { prompt: 'a knight' }, fetchImpl });
+ expect(made).toMatchObject({ glbUrl: 'https://three.ws/cdn/x/rigged.glb', rigged: true });
+ }, 20_000);
+
+ it('rigs a collected mesh instead of handing back a T-posed figure', async () => {
+ const tools = [];
+ const fetchImpl = vi.fn(async (url, init) => {
+ if (String(url).includes('mcp-studio')) {
+ const name = JSON.parse(init.body).params.name;
+ tools.push(name);
+ return name === 'forge_avatar'
+ ? pendingRpc('mesh')
+ : {
+ ok: true,
+ status: 200,
+ json: async () => ({
+ result: { structuredContent: { glbUrl: 'https://three.ws/cdn/x/rigged.glb', kind: 'avatar', rigged: true } },
+ }),
+ };
+ }
+ return jobDone('https://three.ws/cdn/x/mesh.glb');
+ });
+ const made = await callForge({ tool: 'forge_avatar', args: { prompt: 'a knight' }, fetchImpl });
+ expect(tools).toEqual(['forge_avatar', 'rig_mesh']);
+ expect(made).toMatchObject({ glbUrl: 'https://three.ws/cdn/x/rigged.glb', rigged: true });
+ }, 20_000);
+
+ it('surfaces a failed job with its reason', async () => {
+ const fetchImpl = vi.fn(async (url) =>
+ String(url).includes('mcp-studio')
+ ? pendingRpc('rig')
+ : { ok: true, status: 200, json: async () => ({ status: 'failed', error: 'the rigger could not find a spine' }) },
+ );
+ await expect(callForge({ tool: 'forge_avatar', args: {}, fetchImpl })).rejects.toThrow(
+ /could not find a spine/,
+ );
+ }, 20_000);
+});