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.

chore(guards): register the xAI, MCP-surface and earnings-board guards and publish the earnings resource

nirholas3c21bc70eb45
diff --git a/data/guards.json b/data/guards.json
index 73301b650..339cf7adb 100644
--- a/data/guards.json
+++ b/data/guards.json
@@ -500,6 +500,32 @@
"expect": "no annotations"
}
},
+ {
+ "id": "audit-mcp-surfaces",
+ "script": "scripts/build-mcp-surfaces.mjs",
+ "npm": "audit:mcp-surfaces",
+ "title": "MCP resources and prompts are published",
+ "protects": "Every hosted MCP server manifest (server.json, server-agent.json, server-3d.json, server-bazaar.json) and the public directory at public/.well-known/mcp.json list exactly the resources, resource templates and guided prompts the servers actually serve, read from api/_mcp/resources.js and api/_mcp/prompts.js.",
+ "why": "Registries and MCP clients discover what a server offers from these files before they ever connect. A resource added in code but not published is invisible to every directory listing, and one removed in code but still published is a promise the server breaks on first read. The lists are generated from the serving code, so the only way they drift is a change that skipped the regeneration, which is exactly what this catches.",
+ "stages": [
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "A resource listed in the public MCP directory that the server does not serve.",
+ "violation": {
+ "json": [
+ {
+ "file": "public/.well-known/mcp.json",
+ "pointer": "servers.0.resources",
+ "at": 0,
+ "insert": "three://guard-proof/never-served"
+ }
+ ]
+ },
+ "expect": "MCP resource/prompt listings are stale"
+ }
+ },
{
"id": "audit-motion-drift",
"script": "scripts/audit-motion-drift.mjs",
@@ -1130,6 +1156,22 @@
"reason": "The input is git history, not a file: a doc is stale because of the commits that landed after it, which a sandbox cannot fabricate without rewriting history. The corpus is also over its budget of 5 at the time of registering, so the control half of a two-sided proof would fail against the real repo until the queue is refreshed."
}
},
+ {
+ "id": "check-earnings-board",
+ "script": "scripts/check-earnings-board.mjs",
+ "npm": "check:earnings-board",
+ "title": "Earnings leaderboard agrees with every agent page",
+ "protects": "Every row of GET /api/leaderboard/earnings, in all four windows, matches what GET /api/agents/:id/earnings reports for that agent over the same window: creator fees to the lamport, service income, the total, and the rank. Every total equals its parts and the board is sorted by total.",
+ "why": "The promise to users is that a row on /leaderboard?tab=earned and the Earned card on that agent's page never disagree. Both read one model, and tests/agent-earnings-board.test.js holds that on a seeded database, but only real data exercises the real mix of coins, windows and rounding. A board that ranks an agent on numbers its own page does not show is the fastest way to lose trust in both.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "network",
+ "proof": {
+ "kind": "live",
+ "reason": "Pages through the live board and asks each ranked agent for its own earnings over public GET requests, so the rows it compares only exist in a running deployment. It is read-only. The offline half of the same comparison is tests/agent-earnings-board.test.js."
+ }
+ },
{
"id": "check-erc7710-addresses",
"script": "scripts/check-erc7710-addresses.js",
@@ -1607,6 +1649,22 @@
"expect": "is declared but"
}
},
+ {
+ "id": "check-xai-models",
+ "script": "scripts/check-xai-models.mjs",
+ "npm": "check:xai-models",
+ "title": "Grok model catalog matches what xAI serves",
+ "protects": "GROK_MODELS in api/_lib/chat-models.js lists every chat model xAI currently serves, no retired id, and the context window and prices xAI publishes for each. It reads the xAI API with a key, or the public xAI model docs without one.",
+ "why": "A retired id in the catalog turns the Grok rung of every failover chain into a guaranteed error, an uncatalogued id is a better or cheaper model nobody can pick, and llm-pricing.js meters Grok spend from the catalog prices, so a stale price is a wrong spend ledger. xAI changes all three on its own schedule, with no diff on our side to review.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "network",
+ "proof": {
+ "kind": "live",
+ "reason": "Compares the catalog against the live xAI model list or the published xAI model pages, so the answer changes when xAI ships or retires a model and there is no offline copy to mutate. The key, when set, is only ever sent to api.x.ai."
+ }
+ },
{
"id": "i18n-home",
"script": "scripts/i18n-home-keys.mjs",
diff --git a/docs/guards.md b/docs/guards.md
index 128ab7c0d..53696ffd4 100644
--- a/docs/guards.md
+++ b/docs/guards.md
@@ -160,6 +160,7 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| MCP safety annotations | `npm run audit:mcp-safety` | Declared `readOnlyHint` and `destructiveHint` match what handlers do. |
| MCP tool catalog freshness | `npm run audit:mcp-catalog` | `public/mcp-catalog.json` matches what the MCP servers actually expose. |
| MCP directory listing source | `npm run audit:mcp-listing` | The one file every third-party MCP directory listing is written from still matches the manifests, and no new server lands without listing copy. |
+| MCP resources and prompts | `npm run audit:mcp-surfaces` | Every hosted MCP server manifest and `public/.well-known/mcp.json` list exactly the resources, templates and guided prompts the servers serve, generated from `api/_mcp/resources.js` and `api/_mcp/prompts.js`. |
| 3D Studio OpenAPI sync | `npm run check:studio-openapi` | The Actions file in the OpenAI submission kit is byte-identical to the OpenAPI schema the site serves. |
| Live event window | `npm run check:event` | `public/event.json` describes an event that will actually happen, on every surface that reads it. |
| Cron schedule drift | `npm run check:cron-syntax`, `npm run check:cron-drift` | Valid expressions, and agreement with the running Cloud Scheduler jobs. |
@@ -199,6 +200,8 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| Hands-free voice loop | `npm run check:home-voice` | Nothing about listening loads before opt-in, an ambient "yeah" never confirms a guarded action, and the agent does not wake itself. |
| Delegation contract addresses | `npm run check:erc7710` | Every delegation-manager address is a deployed contract. |
| Connector reviewer path | `npm run audit:mcp-reviewer` | Every paid tool on the published stdio server answers an unpaid call with a clean, priced x402 challenge, and the reviewer entitlement lifts the paywall only for the right secret. |
+| Grok model catalog | `npm run check:xai-models` | Every Grok id in `api/_lib/chat-models.js` is one xAI still serves, every chat model xAI serves is catalogued, and the context windows and prices match, so no failover rung calls a retired model and Grok spend is metered at the real price. Needs network. |
+| Earnings board agreement | `npm run check:earnings-board` | Every row of the live earnings leaderboard matches that agent's own Earned card over the same window: creator fees, service income, total and rank. Read-only; `--base <url>` points it at a local server. |
---
diff --git a/docs/ops/guard-wiring.md b/docs/ops/guard-wiring.md
index d1746f4c9..768259a82 100644
--- a/docs/ops/guard-wiring.md
+++ b/docs/ops/guard-wiring.md
@@ -124,6 +124,8 @@ They belong to an operator, or to a post-deploy check.
| `check:erc7710` | Every `DELEGATION_MANAGER_DEPLOYMENTS` address is a deployed contract | 0 | 3.0s | **manual.** `eth_getCode` against public RPCs; a third-party RPC outage would read as a red gate. |
| `check:evm-rpc` | Every EVM RPC endpoint answers a keyless server-side POST, in priority order | 0 | 8.6s | **manual (ops).** Network by definition. |
| `audit:deps` | The Python workers' pinned deps against the OSV vulnerability database | 1 | 16.6s | **manual (security sweep).** 285 advisories across 17 pinned versions, mostly `transformers` (two are RCE, fixed in 5.0.0 and 5.3.0). Each fix is a pin bump plus a worker image rebuild, which is its own piece of work, not a gate. |
+| `check:xai-models` | The Grok catalog (`GROK_MODELS` in `api/_lib/chat-models.js`) against the models xAI serves: ids, context windows and prices, from the xAI API with a key or its public model docs without one | 0 | 0.7s | **manual (ops).** Measured 2026-10-08 against the public docs (no key on this box): 8 of 8 ids in sync. xAI ships and retires models on its own schedule, so it can go red with no diff on our side. Run it when a Grok rung errors or before touching the catalog. |
+| `check:earnings-board` | Every row of `/api/leaderboard/earnings`, in all four windows, against the agent's own `/api/agents/:id/earnings` (creator fees, service income, total, rank) | 2 | 0.2s | **manual (post-deploy).** Measured 2026-10-08 against `https://three.ws`: the board answers 404 because the endpoint landed after the running image (`fe2a8b24f`), so exit 2 is a deploy lag, not a mismatch. Re-run after the next deploy, or point it at a local server with `--base http://localhost:<port>`. The offline half of the same comparison runs in `npm test` as [tests/agent-earnings-board.test.js](../../tests/agent-earnings-board.test.js). |
| `audit:upstreams:map` | Not a guard: `--map` regenerates `docs/resilience.md` | 0 | 38.6s | **manual (generator).** The guard half, `audit:upstreams`, is already in `gate`. |
### Needs a credential this box does not hold
@@ -169,6 +171,8 @@ viewports. They are pre-event, pre-release and incident tools.
|---|---|
| `check:rules` | The pre-push hook, as `--base <remote sha> --head <local sha>` per pushed ref (`scripts/setup-git-hooks.mjs:66`). Push-scoped is the point: it judges the commits leaving the machine, never the shared working tree, and it also lints each pushed commit subject. The bare npm script (17.5s) scans the whole worktree and would fail on other agents' in-flight work. |
| `check:secrets` | The same hook, the same push-scoped mode, one line later, so no credential material leaves the machine. |
+| `check:community-skills` | `prebuild`, by path: `node scripts/build-community-registry.mjs --check` runs in the parallel group of every `npm run build`, and `build:pages` runs the same script in write mode. Measured 2026-10-08: exit 0 in 0.5s, 12 skills valid and `community-skills/registry.json` up to date. The npm entry point is the one a contributor runs before opening a pull request. |
+| `check:sri-pins` | `build:gcp`, through `check:dist`, which imports the same `checkPins()` from `scripts/lib/agent-3d-releases.mjs` and fails the deploy build on a stale pin. Measured 2026-10-08: exit 0 in 0.4s, 6 documented pins match `data/agent-3d-releases.json`. The npm entry point is the one to run while editing docs, and `-- --fix` rewrites stale hashes from the ledger. |
## Nothing was deleted
diff --git a/package.json b/package.json
index 9f3f6ae7d..d647fa36f 100644
--- a/package.json
+++ b/package.json
@@ -282,6 +282,7 @@
"check:cron-drift": "node scripts/check-cron-drift.mjs",
"check:cron-syntax": "node scripts/check-cron-drift.mjs --offline",
"check:xai-models": "node scripts/check-xai-models.mjs",
+ "check:earnings-board": "node scripts/check-earnings-board.mjs",
"audit:custodial-keys": "node scripts/audit-custodial-key-health.mjs",
"audit:home-credentials": "node scripts/audit-home-credential-health.mjs",
"audit:cron-liveness": "node scripts/audit-cron-liveness.mjs",
diff --git a/public/.well-known/mcp.json b/public/.well-known/mcp.json
index 44ec75266..7fb6195ab 100644
--- a/public/.well-known/mcp.json
+++ b/public/.well-known/mcp.json
@@ -39,7 +39,8 @@
"three://agents/{agentId}/runs/{runId}",
"three://agents/{agentId}/orders",
"three://agents/{agentId}/dca",
- "three://agents/{agentId}/intents"
+ "three://agents/{agentId}/intents",
+ "three://agents/{agentId}/earnings"
],
"prompts": [
"get-started",
@@ -100,7 +101,8 @@
"three://agents/{agentId}/runs/{runId}",
"three://agents/{agentId}/orders",
"three://agents/{agentId}/dca",
- "three://agents/{agentId}/intents"
+ "three://agents/{agentId}/intents",
+ "three://agents/{agentId}/earnings"
],
"prompts": [
"get-started",
diff --git a/public/guards.json b/public/guards.json
index 73301b650..339cf7adb 100644
--- a/public/guards.json
+++ b/public/guards.json
@@ -500,6 +500,32 @@
"expect": "no annotations"
}
},
+ {
+ "id": "audit-mcp-surfaces",
+ "script": "scripts/build-mcp-surfaces.mjs",
+ "npm": "audit:mcp-surfaces",
+ "title": "MCP resources and prompts are published",
+ "protects": "Every hosted MCP server manifest (server.json, server-agent.json, server-3d.json, server-bazaar.json) and the public directory at public/.well-known/mcp.json list exactly the resources, resource templates and guided prompts the servers actually serve, read from api/_mcp/resources.js and api/_mcp/prompts.js.",
+ "why": "Registries and MCP clients discover what a server offers from these files before they ever connect. A resource added in code but not published is invisible to every directory listing, and one removed in code but still published is a promise the server breaks on first read. The lists are generated from the serving code, so the only way they drift is a change that skipped the regeneration, which is exactly what this catches.",
+ "stages": [
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "A resource listed in the public MCP directory that the server does not serve.",
+ "violation": {
+ "json": [
+ {
+ "file": "public/.well-known/mcp.json",
+ "pointer": "servers.0.resources",
+ "at": 0,
+ "insert": "three://guard-proof/never-served"
+ }
+ ]
+ },
+ "expect": "MCP resource/prompt listings are stale"
+ }
+ },
{
"id": "audit-motion-drift",
"script": "scripts/audit-motion-drift.mjs",
@@ -1130,6 +1156,22 @@
"reason": "The input is git history, not a file: a doc is stale because of the commits that landed after it, which a sandbox cannot fabricate without rewriting history. The corpus is also over its budget of 5 at the time of registering, so the control half of a two-sided proof would fail against the real repo until the queue is refreshed."
}
},
+ {
+ "id": "check-earnings-board",
+ "script": "scripts/check-earnings-board.mjs",
+ "npm": "check:earnings-board",
+ "title": "Earnings leaderboard agrees with every agent page",
+ "protects": "Every row of GET /api/leaderboard/earnings, in all four windows, matches what GET /api/agents/:id/earnings reports for that agent over the same window: creator fees to the lamport, service income, the total, and the rank. Every total equals its parts and the board is sorted by total.",
+ "why": "The promise to users is that a row on /leaderboard?tab=earned and the Earned card on that agent's page never disagree. Both read one model, and tests/agent-earnings-board.test.js holds that on a seeded database, but only real data exercises the real mix of coins, windows and rounding. A board that ranks an agent on numbers its own page does not show is the fastest way to lose trust in both.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "network",
+ "proof": {
+ "kind": "live",
+ "reason": "Pages through the live board and asks each ranked agent for its own earnings over public GET requests, so the rows it compares only exist in a running deployment. It is read-only. The offline half of the same comparison is tests/agent-earnings-board.test.js."
+ }
+ },
{
"id": "check-erc7710-addresses",
"script": "scripts/check-erc7710-addresses.js",
@@ -1607,6 +1649,22 @@
"expect": "is declared but"
}
},
+ {
+ "id": "check-xai-models",
+ "script": "scripts/check-xai-models.mjs",
+ "npm": "check:xai-models",
+ "title": "Grok model catalog matches what xAI serves",
+ "protects": "GROK_MODELS in api/_lib/chat-models.js lists every chat model xAI currently serves, no retired id, and the context window and prices xAI publishes for each. It reads the xAI API with a key, or the public xAI model docs without one.",
+ "why": "A retired id in the catalog turns the Grok rung of every failover chain into a guaranteed error, an uncatalogued id is a better or cheaper model nobody can pick, and llm-pricing.js meters Grok spend from the catalog prices, so a stale price is a wrong spend ledger. xAI changes all three on its own schedule, with no diff on our side to review.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "network",
+ "proof": {
+ "kind": "live",
+ "reason": "Compares the catalog against the live xAI model list or the published xAI model pages, so the answer changes when xAI ships or retires a model and there is no offline copy to mutate. The key, when set, is only ever sent to api.x.ai."
+ }
+ },
{
"id": "i18n-home",
"script": "scripts/i18n-home-keys.mjs",
diff --git a/server-agent.json b/server-agent.json
index 72dfe617e..27a802088 100644
--- a/server-agent.json
+++ b/server-agent.json
@@ -110,6 +110,12 @@
"name": "agent-intents",
"title": "Agent wallet intents",
"mimeType": "application/json"
+ },
+ {
+ "uriTemplate": "three://agents/{agentId}/earnings",
+ "name": "agent-earnings",
+ "title": "Agent earnings",
+ "mimeType": "application/json"
}
],
"prompts": [
diff --git a/server.json b/server.json
index 473f630da..0aa6ab0df 100644
--- a/server.json
+++ b/server.json
@@ -122,6 +122,12 @@
"name": "agent-intents",
"title": "Agent wallet intents",
"mimeType": "application/json"
+ },
+ {
+ "uriTemplate": "three://agents/{agentId}/earnings",
+ "name": "agent-earnings",
+ "title": "Agent earnings",
+ "mimeType": "application/json"
}
],
"prompts": [