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.

fix(unstoppable): show an unreadable agent as unreachable, not as healthy

nirholasdd62818d0c1c
diff --git a/agents/unstoppable/README.md b/agents/unstoppable/README.md
index 92c1a87a2..3f1bf70f0 100644
--- a/agents/unstoppable/README.md
+++ b/agents/unstoppable/README.md
@@ -6,9 +6,9 @@ A self-sustaining autonomous agent with its own USDC treasury. It earns revenue
The lifecycle is one `tick()` in [src/loop.js](src/loop.js), called every 5 minutes by the `/api/cron/unstoppable-tick` cron:
-1. **Sense**: read the treasury plus 24h earnings, 24h costs, and recent activity. A halted treasury skips the tick.
+1. **Sense**: re-derive the mode from the current balance (`recalcRunway()`), then read the treasury plus 24h earnings, 24h costs, and recent activity. A treasury that is still halted after that recalculation skips the tick. The recalculation has to come first: settling only at the end of a tick made `halted` a one-way trapdoor, so an agent that halted stayed halted however much revenue arrived afterwards.
2. **Think**: if the balance is above the hard floor (100000 atomics, $0.10), ask the LLM for a JSON plan of actions, with a per-tick think budget of 0.1% of balance capped at $0.001 ([src/inference.js](src/inference.js)).
-3. **Act**: execute the planned actions: `reflect` (write the daily reflection if missing), `post_status` and `idle` (free, logged for the activity feed), `search` (spends $0.01, only in normal mode with headroom above the floor).
+3. **Act**: execute the planned actions: `reflect` (write the daily reflection if missing), `post_status` and `idle` (free, logged for the activity feed), `search` (spends $0.01, only in normal mode with headroom above the floor). If the plan did not ask for `reflect`, the tick calls `maybeReflect()` anyway before settling: the daily reflection is a public promise the `/unstoppable` dashboard renders, so it cannot depend on the planner remembering to ask. `maybeReflect()` is idempotent, so after the first tick of a day it is one existence check.
4. **Settle**: recompute runway from the last-24h burn rate and update the mode: `halted` at or below the floor, `conservation` when runway is under 7 days or burn exceeds the threshold, otherwise `normal` ([src/treasury.js](src/treasury.js)).
State lives in three Postgres tables (created idempotently by the status endpoint): `unstoppable_treasury` (a singleton row, id=1), `unstoppable_activity` (every action, cost, and revenue event), and `unstoppable_reflections` (one row per day).
@@ -23,6 +23,7 @@ State lives in three Postgres tables (created idempotently by the status endpoin
| [src/earnings.js](src/earnings.js) | `recordRevenue()`, 24h earnings/costs queries, the activity log |
| [src/reflection.js](src/reflection.js) | `maybeReflect()`: once-daily LLM reflection with a statistical fallback |
| [../../api/agents/unstoppable-status.js](../../api/agents/unstoppable-status.js) | `GET /api/agents/unstoppable-status`: the paid status endpoint that funds the agent |
+| [../../api/agents/unstoppable-public.js](../../api/agents/unstoppable-public.js) | `GET /api/agents/unstoppable-public`: the free, cached snapshot the dashboard renders |
| [../../api/cron/[name].js](../../api/cron/%5Bname%5D.js) | `handleUnstoppableTick`: the cron handler that imports and runs `tick()` |
| [../../src/unstoppable-dashboard.js](../../src/unstoppable-dashboard.js) | The `/unstoppable` dashboard ([../../pages/unstoppable.html](../../pages/unstoppable.html)), polls status every 60 seconds |
@@ -34,6 +35,12 @@ Run one tick locally from the repo root (Node 20+, needs `DATABASE_URL`):
node --env-file=.env -e "import('./agents/unstoppable/src/loop.js').then(m => m.tick()).then(r => console.log(r))"
```
+Read the free public snapshot (no auth, no payment, this is what the dashboard renders):
+
+```bash
+curl -s https://three.ws/api/agents/unstoppable-public
+```
+
Query the live agent (without an `X-PAYMENT` header this returns the 402 payment quote):
```bash
@@ -51,5 +58,6 @@ Or watch the dashboard at [https://three.ws/unstoppable](https://three.ws/unstop
## Platform connections
- **Cron**: `/api/cron/unstoppable-tick` runs every 5 minutes (`*/5 * * * *`), declared in `vercel.json` and executed by Cloud Scheduler in production.
+- **Two reads, one state**: `GET /api/agents/unstoppable-public` is free, IP rate-limited, edge-cached for one agent tick (300s) and trimmed to the 8 most recent activity rows. It exists so the public dashboard shows real numbers to every visitor instead of an empty paywall notice. The paid route below stays the real-time, 20-row read, and it is the only one that credits the treasury it reports.
- **x402**: `GET /api/agents/unstoppable-status` is a paid, Bazaar-discoverable endpoint (USDC on Base or Solana, listed in [../../api/_lib/x402/ring-catalog.js](../../api/_lib/x402/ring-catalog.js)). Each settled payment calls `recordRevenue()`, which writes an `earn` activity row and credits the treasury.
- **Database**: the status endpoint bootstraps all three tables with `CREATE TABLE IF NOT EXISTS` and seeds the treasury, so the agent needs no separate migration to come alive.
diff --git a/docs/api-reference.md b/docs/api-reference.md
index b56def0fc..beb4059a2 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -5494,6 +5494,119 @@ page strip (on-chain agents, attestations, forge models).
---
+## Unstoppable Agent API
+
+The [Unstoppable Agent](/unstoppable) is a self-funding autonomous agent: it
+owns a USDC treasury, earns by serving paid status checks over x402, spends on
+its own thinking within a budget, tracks its runway, and writes a strategic
+reflection once a day. Two endpoints expose the same state at two fidelities.
+
+### Public snapshot (free)
+
+```
+GET /api/agents/unstoppable-public
+```
+
+No auth, no payment, IP rate-limited, CORS open. Edge-cached for 300 seconds
+(one agent tick) and trimmed to the 8 most recent activity rows. This is the
+read the `/unstoppable` dashboard renders, so every visitor sees the agent's
+real numbers without a wallet.
+
+**Response**
+
+```json
+{
+ "available": true,
+ "live": false,
+ "as_of": "2026-08-15T19:20:39.822Z",
+ "refresh_seconds": 300,
+ "status": "running",
+ "treasury": {
+ "balance_usdc": "8.930000",
+ "balance_usdc_atomics": 8930000,
+ "runway_days": 9999,
+ "lifetime_earned_usdc": "8.930000",
+ "lifetime_spent_usdc": "0.000000"
+ },
+ "activity_24h": {
+ "earnings_usdc": "0.000000",
+ "costs_usdc": "0.000000",
+ "net_usdc": "0.000000"
+ },
+ "recent_activity": [
+ {
+ "action_type": "earn",
+ "description": "Revenue from status_check: $0.010000 USDC",
+ "cost_usdc": "0.000000",
+ "revenue_usdc": "0.010000",
+ "created_at": "2026-08-15T19:12:11.402Z"
+ }
+ ],
+ "latest_reflection": {
+ "date": "2026-08-15",
+ "summary": "Revenue covered thinking costs today.",
+ "strategy_notes": "Continue status-check monetization."
+ },
+ "live_endpoint": "/api/agents/unstoppable-status",
+ "live_price_usdc": "0.010000",
+ "live_price_atomics": "10000",
+ "agent_info": { "name": "Unstoppable", "purpose": "Self-sustaining autonomous agent on three.ws", "service": "Paid status checks via x402" }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `live` | Always `false` here. The paid endpoint returns the real-time reading. |
+| `as_of` | When this snapshot was generated. It can be up to `refresh_seconds` old. |
+| `status` | `running`, `conservation`, or `halted`, derived from the treasury mode |
+| `treasury.runway_days` | Balance divided by the last-24h burn. `9999` means no burn was measured, not a 27-year runway. |
+| `live_price_usdc` | What the real-time reading costs over x402, so a client can quote it without probing for a 402 |
+
+**When the database is unreachable**
+
+```json
+{ "available": false, "reason": "db_unavailable", "live": false, "live_endpoint": "/api/agents/unstoppable-status" }
+```
+
+Still `200`, cached 15 seconds. Check `available` before reading the treasury:
+a failed read must never render as a broke agent, which is exactly what a
+zeroed balance would look like.
+
+```bash
+curl -s https://three.ws/api/agents/unstoppable-public | jq 'select(.available) | {status, balance: .treasury.balance_usdc}'
+```
+
+### Live reading (paid, $0.01 USDC)
+
+```
+GET /api/agents/unstoppable-status
+```
+
+x402-paid, Bazaar-discoverable, settles in USDC on Base or Solana. Same shape
+as the snapshot plus `activity_24h.action_count`, and it carries 20 activity
+rows instead of 8. Two differences matter: the reading is real-time rather than
+tick-cached, and a settled payment calls `recordRevenue()`, so this is the only
+read that extends the runway it reports. Without an `X-PAYMENT` header it
+returns the standard `402` quote.
+
+```bash
+# First call returns 402 with the payment requirements
+curl -s https://three.ws/api/agents/unstoppable-status
+
+# Retry with the payment header for the live reading
+curl -s https://three.ws/api/agents/unstoppable-status \
+ -H "X-Payment: <your-x402-payment-header>"
+```
+
+A caller with the `x402:bypass` scope is served free by the access-control hook
+and is deliberately NOT credited as revenue: reporting money the agent never
+earned would inflate the runway this endpoint exists to report honestly.
+
+See [agents/unstoppable/README.md](https://github.com/nirholas/three.ws/blob/main/agents/unstoppable/README.md)
+for the tick lifecycle and the treasury rules.
+
+---
+
## Referrals API
Every three.ws account carries a referral code. A share link is any page URL
diff --git a/docs/ux-flows/09-x402-agent-commerce.md b/docs/ux-flows/09-x402-agent-commerce.md
index 81c56f455..61599a1ae 100644
--- a/docs/ux-flows/09-x402-agent-commerce.md
+++ b/docs/ux-flows/09-x402-agent-commerce.md
@@ -165,18 +165,17 @@ choreographed two-agent narrative driven by Server-Sent Events.
- **Step count:** 4 required (+3 optional).
### Unstoppable Agent — `/unstoppable`
-- **Source:** `pages/unstoppable.html` + `src/unstoppable-dashboard.js` + `/x402.js`; backend `api/agents/unstoppable-status.js` ($0.01 optional payment per live query).
-- **Entry point:** A live dashboard of an autonomous agent that must earn to survive — balance, runway, status (RUNNING/CONSERVING/HALTED), activity feed, latest reflection.
-- **Prerequisites / gates:** None to view (cached data from `localStorage unstoppable_last_reading`). To unlock **live** data, donate $0.01 USDC via x402; wallet needed only for the donation.
-- **Steps (2 required + 1 recurring optional):**
- 1. Load page → render cached data (or skeletons) → auto-poll `GET /api/agents/unstoppable-status` immediately, then every 60s (exponential backoff to 5 min on transient errors).
- 2. View data: `200` → hero balance + status + runway, 24h earnings/costs, lifetime net, activity feed (THINK/EARN/REFLECT/IDLE/…), latest reflection. `402` → payment notice + cached data + "Unlock live data — $0.01".
- 3. (optional, repeatable) Click **Donate $0.01** → `window.X402.pay({ endpoint: status, method:'GET', action:'Fund the … runway' })` → on success toast + fresh live data; each donation funds one live query and directly funds the agent.
-- **Decision points / branches:** cache present vs not; `200` (unlocked) vs `402` (paywalled); `5xx` → backoff + keep cache; donation low-balance → retry with link to `/pay`; donation cancel → no charge. A caller holding the `x402:bypass` install scope is served the live reading for free and is deliberately NOT recorded as revenue, so the runway the page reports stays honest.
-- **External calls / dependencies:** `/api/agents/unstoppable-status` (free 402 challenge + optional paid query), `/x402.js`, Base/Solana settlement.
-- **Success state:** live hero + stats + non-empty activity feed + reflection + "Updated X ago".
-- **Empty / error states:** initial skeleton "Fetching live data…"; `402` notice with cached data; no-cache `402` → zeroed state ("Pay $0.01 to see live data").
-- **Step count:** 2 required (+1 recurring optional donation).
+- **Source:** `pages/unstoppable.html` + `src/unstoppable-dashboard.js` + `/x402.js`; backends `api/agents/unstoppable-public.js` (free snapshot) and `api/agents/unstoppable-status.js` ($0.01 for the real-time reading).
+- **Entry point:** A live dashboard of an autonomous agent that must earn to survive: balance, runway, status (RUNNING/CONSERVING/HALTED), activity feed, latest reflection.
+- **Prerequisites / gates:** None to view. The page polls the free snapshot, so it is populated with the agent's real numbers for every visitor. A wallet is needed only to pull the real-time reading.
+- **Steps (1 required + 1 recurring optional):**
+ 1. Load page → paint the last reading from `localStorage unstoppable_last_reading` if present → poll `GET /api/agents/unstoppable-public` immediately, then every 60s (exponential backoff to 5 min on faults, snapping back to 60s on the next good poll, plus an immediate re-poll when the tab regains focus). Renders hero balance + status + runway, 24h earnings/costs, lifetime net, the activity feed (THINK/EARN/REFLECT/IDLE/…), and the latest reflection, labelled "Free snapshot · <age> · refreshed every 5 min".
+ 2. (optional, repeatable) Click **Unlock the live reading** → `window.X402.pay({ endpoint: status, method:'GET', action:'Fund the … runway' })` → on success a toast plus the real-time reading, relabelled "Live reading". Each payment buys one live query and directly credits the agent's treasury.
+- **Decision points / branches:** snapshot `200` → populated; `{ available: false }` → "datastore is not answering" banner; network fault or `5xx` → "status feed is unreachable" banner, with the last known reading shown and labelled as such when cached, and per-panel failure copy plus a Retry button when not; payment low-balance → retry with link to `/pay`; payment cancel → no charge. A caller holding the `x402:bypass` install scope is served the live reading for free and is deliberately NOT recorded as revenue, so the runway the page reports stays honest.
+- **External calls / dependencies:** `/api/agents/unstoppable-public` (free, cached one tick), `/api/agents/unstoppable-status` (paid, real-time, 20 rows), `/x402.js`, Base/Solana settlement.
+- **Success state:** populated hero + stats + non-empty activity feed + reflection + a data-source label saying whether the numbers are the free snapshot, a paid live reading, or the last known cached reading.
+- **Empty / error states:** pre-fetch "Reading the agent's treasury…" with a shimmer on the reflection card; agent with no history → "No activity logged yet" and "No reflection written yet today", both explaining the 5-minute tick; fetch failure → hero alert banner + Retry now + a link to the snapshot endpoint, and every panel states what failed rather than shimmering forever.
+- **Step count:** 1 required (+1 recurring optional payment).
### Pay-As-You-Learn Tutor — `/tutor`
- **Source:** `public/tutor.html` + `public/tutor.js` + `/x402.js`; backend `api/x402/tutor.js` ($0.01/question) + `api/tutor/session.js` (free resume).
diff --git a/pages/unstoppable.html b/pages/unstoppable.html
index c2a6883bb..8b39a7726 100644
--- a/pages/unstoppable.html
+++ b/pages/unstoppable.html
@@ -130,6 +130,8 @@
}
.agent-dot.conservation { background: var(--amber); box-shadow: 0 0 0 0 var(--amber); }
.agent-dot.halted { background: var(--red); box-shadow: 0 0 0 0 var(--red); animation: none; }
+ /* Status could not be read: neutral and still, never the healthy pulse. */
+ .agent-dot.unknown { background: var(--text-4); box-shadow: none; animation: none; }
@keyframes pulse-agent {
0% { box-shadow: 0 0 0 0 rgba(34,197,94,0.5); }
70% { box-shadow: 0 0 0 16px rgba(34,197,94,0); }
@@ -151,6 +153,9 @@
.balance-display {
font-family: var(--font-mono);
font-size: clamp(40px, 7vw, 84px);
+ /* A six-decimal balance wraps on a narrow screen; tight leading makes
+ that read as a deliberate two-line hero rather than a layout slip. */
+ line-height: 1.05;
font-weight: 600; letter-spacing: -0.04em;
color: var(--text); margin: 0 0 16px;
font-variant-numeric: tabular-nums;
diff --git a/prompts/swarm-100/route-unstoppable.md b/prompts/swarm-100/route-unstoppable.md
deleted file mode 100644
index ce836e337..000000000
--- a/prompts/swarm-100/route-unstoppable.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Route audit: /unstoppable (Unstoppable Agent)
-
-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==='/unstoppable')console.log(JSON.stringify(g,null,2))"
-
-2. Find the serving implementation: grep "/unstoppable" 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/unstoppable
-
-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: /unstoppable ("Unstoppable Agent", section "crypto").
-Declared purpose: Live dashboard for an autonomous agent that funds itself via x402 micropayments. Watch its balance, earnings, costs, and daily reflections in real time.
-
-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/unstoppable. 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 /unstoppable: 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-unstoppable.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/unstoppable-dashboard.js b/src/unstoppable-dashboard.js
index 3e129a66d..e6a6be5ff 100644
--- a/src/unstoppable-dashboard.js
+++ b/src/unstoppable-dashboard.js
@@ -118,10 +118,16 @@ function renderStatus(status, runwayDays) {
const statusText = document.getElementById('statusText');
const runwayBadge = document.getElementById('runwayBadge');
+ // Anything outside the three real modes means we could not read the agent.
+ // It must NOT fall through to the running style: a green pulsing dot over the
+ // word UNREACHABLE tells the visitor the opposite of what happened.
+ const known = status === 'running' || status === 'conservation' || status === 'halted';
+
if (dot) {
dot.className = 'agent-dot';
if (status === 'conservation') dot.classList.add('conservation');
if (status === 'halted') dot.classList.add('halted');
+ if (!known) dot.classList.add('unknown');
}
if (badge && statusText) {
@@ -134,6 +140,10 @@ function renderStatus(status, runwayDays) {
badge.classList.add('badge-halted');
setText(statusText, 'HALTED');
badge.setAttribute('aria-label', 'Agent status: halted, treasury at the hard floor');
+ } else if (!known) {
+ badge.classList.add('badge-runway');
+ setText(statusText, 'UNREACHABLE');
+ badge.setAttribute('aria-label', 'Agent status could not be read');
} else {
badge.classList.add('badge-running');
setText(statusText, 'RUNNING');
@@ -302,8 +312,6 @@ function renderError(reason) {
if (el) { setText(el, '—'); el.className = 'stat-val'; }
}
renderStatus('unknown', NaN);
- const statusText = document.getElementById('statusText');
- if (statusText) setText(statusText, 'UNREACHABLE');
const feed = document.getElementById('activityFeed');
if (feed) {