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(agent-vitals): explain capability attestation and register it for discovery

nirholasd1c13a3971b9
diff --git a/data/pages.json b/data/pages.json
index 553f6a2af..529029fe4 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -737,6 +737,14 @@
"changefreq": "monthly",
"added": "2026-04-17"
},
+ {
+ "path": "/glance",
+ "title": "Glance",
+ "description": "Your three.ws agent on every home screen: a live card for the Windows 11 widgets board, a README, Slack, or any page.",
+ "priority": 0.7,
+ "changefreq": "weekly",
+ "added": "2026-08-28"
+ },
{
"path": "/widgets",
"title": "Widgets Gallery",
@@ -1197,6 +1205,14 @@
"changefreq": "realtime",
"added": "2026-06-16"
},
+ {
+ "path": "/oracle-lab",
+ "title": "Oracle Lab: the model, published",
+ "description": "The Oracle's conviction model in full: every bucket weight with the number of labeled launches behind it and what happened to them, the held-out reliability curve for each tier, the version history of every refit including the ones that were refused, and a live scorer that runs the real weights in your browser. Download it and reproduce any score offline.",
+ "priority": 0.8,
+ "changefreq": "daily",
+ "added": "2026-08-28"
+ },
{
"path": "/oracle/docs",
"title": "Oracle Docs: the conviction engine, end to end",
@@ -3274,6 +3290,12 @@
"description": "Reference for the <agent-3d> custom element.",
"added": "2026-04-27"
},
+ {
+ "path": "/docs/companion",
+ "title": "Docs · Companion",
+ "description": "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.",
+ "added": "2026-08-28"
+ },
{
"path": "/docs/mcp",
"title": "Docs · MCP",
@@ -4608,6 +4630,14 @@
"priority": 0.6,
"changefreq": "monthly"
},
+ {
+ "path": "/docs/oracle-model",
+ "title": "Docs · The Oracle model, and how to run it yourself",
+ "description": "How the three.ws conviction model is fitted, what its three heads predict, why the outcome labels had to be made independent of the SOL price, how the promotion gate decides which model ships, and how to score launches locally with @three-ws/oracle-model.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-08-28"
+ },
{
"path": "/docs/x402-distribution",
"title": "Docs · x402 distribution",
@@ -5266,14 +5296,14 @@
"changefreq": "monthly",
"added": "2026-08-24"
},
- {
- "path": "/docs/agent-vitals",
- "title": "Docs \u00b7 Agent vitals: can it act?",
- "description": "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.",
- "priority": 0.6,
- "changefreq": "monthly",
- "added": "2026-08-28"
- }
+ {
+ "path": "/docs/agent-vitals",
+ "title": "Docs · Agent vitals: can it act?",
+ "description": "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.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-08-28"
+ }
]
},
{
diff --git a/docs/agent-vitals.md b/docs/agent-vitals.md
new file mode 100644
index 000000000..c505633a8
--- /dev/null
+++ b/docs/agent-vitals.md
@@ -0,0 +1,177 @@
+# Agent vitals: can it act?
+
+Every liveness check three.ws had was correct, and none of them could tell us
+that ten of twelve armed trading agents had not attempted an action in weeks.
+
+`agent-vitals` is the answer to the question those checks could not ask: **not
+"is it up" but "can it act right now, and if not, what is the one thing to
+fix".**
+
+- Engine (framework-agnostic, zero dependencies): [`packages/agent-vitals`](../packages/agent-vitals/README.md)
+- three.ws wiring: [`api/_lib/agent-vitals/`](../api/_lib/agent-vitals/)
+- Operator CLI: `npm run agent:vitals`
+- HTTP: `GET /api/agents/vitals` (ops-gated)
+
+## The failure it was built for
+
+On 2026-08-28 an audit of the autonomous sniper fleet found twelve arms armed,
+the worker `Ready:True` at `minScale: 1`, the launch feed streaming, and every
+strategy row `enabled = true`. Ten arms had not attempted an entry in weeks.
+
+Three unrelated things were wrong, and none was visible to anything we measured:
+
+1. The deployed worker image predated commit `8f16c071b`, which moved every free
+ LLM rung onto models that still exist. The whole chain answered `404`/`410`.
+2. The providers behind the surviving rungs were out of credit (`402`) or on a
+ GCP billing hold (`403`).
+3. Several arm wallets could not fund a single entry.
+
+Liveness measures the process. Acting needs a chain of preconditions the process
+knows nothing about. The agents were healthy and structurally unable to work.
+
+## The model
+
+Preconditions are declared as **vitals** with `needs` edges between them, and
+actions as **capabilities** that AND over vitals. Attesting the graph returns
+the *root* blocker, never a symptom.
+
+```
+deploy-fresh ──> cognition ──┐
+ ├──> [enter]
+armed, solvency, feed, rpc ──┘
+
+rpc ─────────────────────────────> [exit]
+```
+
+Two things fall out of that shape and both matter:
+
+- **`exit` deliberately depends on neither the feed nor a model.** When the
+ model chain died, the fleet could still close its open positions. Collapsing
+ that into one health bit would have told an operator their risk was stranded
+ when it was not.
+- **`deploy-fresh` only feeds `cognition` for an arm that actually uses a
+ model.** A stale image is a hypothesis about why a model chain died, not by
+ itself a reason an agent cannot act. Wiring it as a universal precondition
+ reported an arm that had entered a position two minutes earlier, on that very
+ image, as definitively unable.
+
+## The vitals
+
+| vital | reads | `down` means |
+|---|---|---|
+| `armed` | `agent_sniper_strategies` | the owner disabled it or engaged its kill switch |
+| `solvency` | live wallet balance via `walletTradeState()` | the wallet cannot fund one entry at the executor's own sizing rule |
+| `rpc` | `getSlot` on a Solana RPC | no endpoint is answering, so neither a quote nor a broadcast is possible |
+| `feed` | the live pump.fun launch feed | no candidate seen in 30 minutes, an upstream outage rather than a quiet market |
+| `deploy-fresh` | Artifact Registry image create time | the running image is over 7 days old and may predate current config |
+| `cognition` | a real completion through `api/_lib/llm.js` | every rung of the provider chain failed |
+
+`solvency` asks [`api/_lib/sniper-solvency.js`](../api/_lib/sniper-solvency.js),
+which calls the executor's own `resolveEntrySize()`. Re-deriving that threshold
+is how a report drifts into calling a wallet tradeable that the executor sits
+out, which is the exact bug that module exists to catch.
+
+## Reading the output
+
+```
+$ npm run agent:vitals
+
+SHARED READINGS (taken once for the whole fleet)
+ RPC up slot 442250266
+ model up ovh answered across 3 configured rung(s)
+ feed newest launch at 2026-08-28 03:26
+ image built 2026-08-11
+
+PER ARM
+
+ Crosshair [oracle-strict] CAN ACT
+ last entry attempt 2 min ago
+ every precondition is up
+
+ Swarm 9 [llm-claude] CANNOT ACT
+ last entry attempt 33 days ago (STALLED)
+ ROOT deploy-fresh is down: worker image is 17 days old
+ fix: gcloud builds submit --config workers/agent-sniper/cloudbuild.yaml ...
+ (blocked downstream, not probed: cognition)
+
+ Swarm 7 [rules-classic] CAN ACT
+ last entry attempt 55 days ago (STALLED)
+ every precondition is up: this arm is capable and its entry filters are simply not matching
+
+WORK QUEUE (deduplicated across the fleet, widest blast radius first)
+ solvency blocks 5 arms: Nadirah, Boost Ride, Kimi Judge, Swarm 5, three
+ send 0.0437 SOL to D5BGRDsX...rXypu
+ ...
+ deploy-fresh blocks 4 arms: Kimi Judge, Swarm 2, Swarm 5, Swarm 9
+ gcloud builds submit --config workers/agent-sniper/cloudbuild.yaml ...
+```
+
+Three things to notice:
+
+- **CAN ACT + STALLED is the most useful line in the report.** Nothing is broken,
+ so the arm's entry filters are the answer. That stops an operator hunting
+ infrastructure that is already fine.
+- **`(blocked downstream, not probed)`** means exactly that. A vital behind a
+ known failure is never probed, because it would spend a timeout to rediscover
+ something already known. In the outage that motivated this, that mistake made
+ every decision walk ten dead provider rungs, which saturated the decision queue,
+ which looked like a third independent fault.
+- **The work queue is deduplicated by cause but not by fix.** One stale image is
+ one redeploy; five starved wallets are five different transfers to five
+ different addresses, so every distinct remedy is printed.
+
+## Unreadable is never failed
+
+A probe that throws, times out, or returns no verdict is `unknown`, and a
+capability with an unreadable precondition is `null` (cannot say), not `false`
+(cannot act). An unread balance is not a balance of zero, and one flaky RPC call
+must not page someone to a healthy fleet.
+
+This propagates through blocks: blocking on an *unreadable* dependency leaves
+the capability `unknown`, and only a block tracing back to something genuinely
+`down` makes it `unable`.
+
+Concretely, running the CLI without Google credentials reports the image as
+`unread` and the LLM arms as `UNKNOWN`, never as broken.
+
+## When the model is wrong
+
+A capability model is a model, and this one has been wrong. Every arm is
+therefore checked against the position ledger: if the graph says `unable` and
+the arm demonstrably attempted an entry within the last hour, the report prints
+
+```
+ CONTRADICTION attested UNABLE but this arm attempted an entry 2 min ago:
+ the vitals model is wrong, not the arm
+```
+
+A health tool that cannot notice it is wrong will be trusted right up until it
+matters.
+
+## Commands
+
+```bash
+npm run agent:vitals # attest the mainnet fleet
+node scripts/agent-vitals.mjs --json # machine-readable
+node scripts/agent-vitals.mjs --no-llm # skip the model probe (it spends a few tokens)
+node scripts/agent-vitals.mjs --network devnet
+npm run test:agent-vitals # the engine's own suite
+```
+
+Requires `DATABASE_URL` (in `.env.local`). `SOLANA_RPC_URL` and Google
+credentials are optional; without them those probes report `unknown`. The CLI
+falls back to the `gcloud` CLI for the image reading when no platform credential
+is present, because that reading is the one that closed the case.
+
+## HTTP
+
+`GET /api/agents/vitals?network=mainnet&llm=1`, gated by `authorizeOps` (admin
+session or `x-ops-secret`, never `CRON_SECRET`). The response names wallet
+addresses, funding deficits and deploy commands, which is an operator view
+rather than a public one.
+
+## Related
+
+- [docs/ops/trading-bot-report.md](ops/trading-bot-report.md) counts what the fleet did. This explains why it did not.
+- [packages/agent-vitals/README.md](../packages/agent-vitals/README.md) is the engine, usable on any autonomous agent.
+- [docs/ops/gcp-production.md](ops/gcp-production.md) is the deploy runbook the remedies point at.