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.
Run receipts: what each stage was expected to do, and what it did
Every generation the free 3D Studio starts (forge_avatar, text_to_avatar, mesh_forge, forge_free, rig_mesh) writes a run receipt. refine_model does not write one. A receipt walks the pipeline stage by stage. For each stage it records:
- the expected result
- the observed result
- a verdict
- the cause whenever the verdict is not a clean pass
The finished record is hashed and signed with ed25519, so it cannot be edited after the fact without the edit showing.
Browse them at three.ws/runs. Each receipt has its own page, /runs/rr_…, and every Studio result links to its receipt in the text and in structuredContent.receipt.
Why this exists
A generation pipeline that answers "here is your model" and nothing else hides everything that matters when a result is disappointing. When the director model timed out, the prompt went in as written. When the high-detail lane was full, the job ran on the standard tier. When the rigger returned a skeleton with no legs, the walk cycle can never play. A receipt makes each of those visible as it happens, in the same response, written by the pipeline itself rather than reconstructed afterwards.
Verdicts
| Verdict | Meaning |
|---|---|
met |
The stage did what it was expected to do. |
recovered |
The stage did not do the expected thing, but a named fallback carried the run (a different tier, the prompt used as written, an automatic regeneration). |
missed |
The stage did not do what was expected, and the receipt says why (cause). |
skipped |
The stage did not run (a reference image skips the brief; draft and standard tiers skip the vision check; rig_mesh never checks the subject). A skip is never counted as a pass: the summary of a run with a skipped stage reads "Every stage that ran met its contract" and names the skipped stages. |
pending |
The stage was still running when the tool answered. Only check_job completes the receipt; the server stores a hash of the job handle, not the handle, so it cannot collect the job itself. A receipt still pending an hour later is shown as never collected. |
Stages
| Stage | Expected | How it is observed |
|---|---|---|
| Input | A prompt or reference image that passes the content-safety check. | The safety check and image guard. A refused prompt is not stored. |
| Subject check | A humanoid subject, since rigging builds a two-legged skeleton. | forge_avatar: the same humanoid classifier the tool already gates on. rig_mesh: always skipped, with the cause stated, because a caller-supplied mesh is rigged as given and nothing checks that it depicts a body. A lamp still receives a full humanoid skeleton, and the receipt says so instead of letting a met Rig stage imply otherwise. |
| Brief | A director-written 3D specification. | Whether the director's brief was used, or the exact reason it was set aside (too long, with its length; unfinished; carried a link; added nothing; no reply), or a known-mark brief applied. |
| Mesh | A textured mesh from the requested tier. | The engine and tier that actually ran, from the terminal job frame. |
| Geometry check | A valid GLB with real, textured geometry. | The deterministic geometry score the forge computes on every file (triangles, vertices, textures). |
| Visual check | A render that reads as a clean, complete subject. | The vision QA gate's verdict, score and defects, where the tier runs it. |
| Rig | A skinned humanoid skeleton with torso, arms and legs mapped. | Read back from the delivered file, using the same analysis as Rig Doctor (src/rig-report.js), not taken from the rigger's own report. |
| Delivery | A permanent first-party link. | Whether the file landed on three.ws storage or only on the engine's temporary link. |
Each run's overall outcome is one of the following:
delivereddelivered_with_issuespartial(for example the mesh shipped but the rig failed)pendingrefusedfailed
The outcome is derived from the stages. A tool can only state a worse outcome than the stages imply, never a better one.
The receipt object
A real one, from a proof run on 2026-10-11 (stages trimmed to three of eight):
{
"type": "three-run-receipt/v1",
"id": "rr_81qbfUbiZNqSTD6rVmjCoA",
"tool": "forge_avatar",
"plan": { "rig": true, "tier": "high" },
"started_at": "2026-10-11T02:31:35.330Z",
"finished_at": "2026-10-11T02:32:52.928Z",
"duration_ms": 77598,
"input": { "prompt": "a friendly cartoon astronaut in a white suit with an orange visor", "reference_image": false },
"stages": [
{ "id": "brief", "label": "Brief", "ms": 7738, "expected": "A director-written brief that frames the whole figure head to toe in a neutral A-pose.", "observed": "The fixed full-body brief was appended to the prompt as written.", "verdict": "recovered", "cause": "The director reply stopped mid-sentence, so it was treated as clipped and set aside. The fixed brief keeps the framing." },
{ "id": "mesh", "label": "Mesh", "ms": 47093, "expected": "A textured 3D mesh from the high-detail tier.", "observed": "A mesh from the high-detail tier on TRELLIS (free).", "verdict": "met", "metrics": { "tier": "high", "engine": "TRELLIS (free)" } },
{ "id": "rig", "label": "Rig", "ms": 22654, "expected": "A skinned humanoid skeleton the animation library can drive: torso, arms and legs mapped.", "observed": "52 joints (Mixamo), 52 mapped to the canonical skeleton; torso, arms and legs all driven.", "verdict": "met", "metrics": { "joints": 52, "mapped": 52, "skinned": true, "convention": "Mixamo" } }
],
"outcome": "delivered",
"summary": "Delivered as expected. 1 carried by a fallback (Brief).",
"issues": [ { "stage": "brief", "label": "Brief", "verdict": "recovered", "expected": "…", "observed": "…", "cause": "The director reply stopped mid-sentence, so it was treated as clipped and set aside. The fixed brief keeps the framing." } ],
"output": { "glb_url": "https://three.ws/cdn/forge/anon/9d23314f-a385-432d-bd4c-41513c5119f6.glb", "viewer_url": "https://three.ws/viewer?src=…" }
}
It is stored inside a signed envelope:
{ "receipt": { … }, "sha256": "<hex of the canonical bytes>", "signature": "<base58 ed25519>", "signer": "<base58 public key>" }
The signature covers three-run-receipt/v1 + \n + the canonical JSON of the receipt (keys sorted, no whitespace).
Verify one yourself
The server verifies every receipt it serves, but you do not have to trust it:
node scripts/run-receipt-verify.mjs rr_81qbfUbiZNqSTD6rVmjCoA
node scripts/run-receipt-verify.mjs https://three.ws/runs/rr_81qbfUbiZNqSTD6rVmjCoA --signer <pinned key>
node scripts/run-receipt-verify.mjs ./downloaded-receipt.json --json
The verifier fetches the envelope (or reads a downloaded file). It then recomputes the hash and checks the ed25519 signature locally, and optionally checks the signer against a key you pinned. It prints every stage and exits non-zero on any failed check. Changing one character of any stage breaks it.
The signing key is the platform attestation key (ATTEST_AGENT_SECRET_KEY). Its public half is returned as signer by GET /api/runs?stats=1. A deployment without the key still writes receipts, hashed but marked unsigned, and the page says so.
API
| Call | Returns |
|---|---|
GET /api/runs?id=rr_… |
The envelope plus a fresh server-side verification ({ ok, checks[] }). 400 for a malformed id, 404 if unknown. |
GET /api/runs?stats=1&days=7 |
Aggregate counts over 1 to 90 days: outcomes, delivery rate, clean rate, per-tool totals, per-stage verdict counts and met rate, and the most common causes. Counts only; no prompts. |
Both are public, CORS-open and keyless.
Privacy
- A receipt id is an unguessable handle (
rr_plus 16 random bytes in base58). Receipts are not listed individually anywhere. Only the person holding the link can open one. - The job handle is stored only as a one-way hash, so a receipt never exposes a job token.
- A prompt refused by the safety check is not stored.
- The aggregate view at
/runsshows counts and causes, never prompts.
Failure behavior
A receipt never changes a tool's result; it only adds to it.
- If the database is unreachable, the tool still answers and carries the receipt inline, without a link.
- Saving waits at most 2.5 s.
- Reading the rig back has a 10 s budget. If it fails, the rig stage is
skippedwith the cause, never a guess. - A link is only attached once the receipt is actually stored, so a receipt link never 404s.
Code
- Core (stages, verdicts, signing, verification): api/_lib/run-receipt.js
- Storage, stats, and rig read-back: api/_lib/run-receipt-store.js
- Table: api/_lib/migrations/20261014000000_run_receipts.sql
- Studio wiring: api/_mcp-studio/receipts.js, api/_mcp-studio/tools.js
- API: api/runs.js
- Page: pages/runs.html, src/runs.js
- Offline verifier: scripts/run-receipt-verify.mjs
- Tests: tests/run-receipt.test.js
Related
- 3D Studio MCP: the tools that write receipts
- Reasoning Ledger: the same idea for agent decisions