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(x-grok): health and status for the X mention reply bot

nirholas5c4e37a5ca73
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 99297a1cb..52e08f81c 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
- **An agent set to Grok now answers as Grok everywhere, with a badge when it can't**: Profile chat, the agent editor's copilot, scheduled strategy runs, and the gateway all now read an agent's chosen brain through the same resolver, so picking Grok for an agent actually means Grok on every surface, not just the one where it was set. A Grok pick first tries the agent owner's own saved xAI key, then the platform's, before falling back to the free default chain. When Grok genuinely can't answer (no key reachable anywhere), profile chat now shows a small badge naming which model answered instead, so it's never a silent swap. `[improvement]`
- **Sentiment Scout's X reads gained a second, independent path through xAI**: The Sentiment Scout reads X for posts quoting a coin's exact contract address, as evidence a holder can open and check. When our own X search credentials are unavailable or rate limited, it now fails over to xAI's x_search tool, a second route to the same posts, metered by its own daily cap so an outage on one path never silently costs more than planned on the other. No change for anyone reading the Scout: the evidence looks the same either way. (`/docs/sentiment-scout`) `[improvement, infra]`
+- **The @-mention reply bot now reports its own status, and /grok shows it live**: A new public endpoint, /api/x/mention-bot/status, answers whether the @-mention reply bot is live, in dry run, or paused, how many handles it has replied on, how many replies it sent in the last 24 hours, and its median reply time. No mention text or author identity is included. The /grok page now shows this as a live section, and /api/healthz carries the same signal as a platform subsystem, so an operator sees a wedged reply queue or a rising error rate within the hour it starts, instead of the bot quietly going silent with no signature anywhere. (`/grok`) `[feature, improvement]`
## 2026-10-10
diff --git a/api/_lib/ops/subsystem-health.js b/api/_lib/ops/subsystem-health.js
index cdb18986c..533e9f772 100644
--- a/api/_lib/ops/subsystem-health.js
+++ b/api/_lib/ops/subsystem-health.js
@@ -40,6 +40,7 @@ import { gatherForgeHealth } from './forge-health-sensor.js';
import { gatherObjectStorageHealth } from './object-storage-health.js';
import { gatherIndexLagHealth } from './index-lag.js';
import { gatherHomeHealth } from './home-health.js';
+import { gatherMentionBotHealth } from '../x-mention-health.js';
import { describeSolvency } from '../sniper-solvency.js';
import { treasuryWalletOrNull, rewardsWalletOrNull } from '../token/config.js';
@@ -639,6 +640,9 @@ export async function gatherSubsystemHealth({ probeDb = true } = {}) {
// no XMTP delivery), and until it was hosted it had no health surface at
// all: the listing was flagged offline by OKX before anyone here noticed.
probeDb ? checkOkxChatBot() : Promise.resolve({ name: 'okx_chat_bot', label: 'OKX marketplace chat bot (agent #2632)', status: 'unknown', detail: 'probe skipped' }),
+ // X @-mention reply bot. Reads x_mention_events only (webhook + any future
+ // poller both write through it), so it shares the probeDb gate.
+ probeDb ? gatherMentionBotHealth() : Promise.resolve({ name: 'x_mention_bot', label: 'X mention bot', status: 'unknown', detail: 'mention bot read skipped' }),
];
const subsystems = await Promise.all(checks);
diff --git a/api/_lib/x-mention-health.js b/api/_lib/x-mention-health.js
new file mode 100644
index 000000000..a1c0e3249
--- /dev/null
+++ b/api/_lib/x-mention-health.js
@@ -0,0 +1,196 @@
+// @ts-check
+// Health of the X mention bot (x-grok 42): "is it polling, how far behind,
+// and how much runway is left". api/healthz.js's own docblock names exactly
+// this failure mode: a bot that answers nothing looks dead to a user and
+// broken to the owner unless some subsystem says so out loud.
+//
+// Every signal here is a read of x_mention_events, the one ledger both
+// ingestion paths (the Account Activity webhook today, a future poll cron)
+// write through on the tweet id primary key, plus the operator pause switch
+// (x-mention-admin.js: app_settings x_mention_bot_paused) and the live-send
+// flag (X_MENTION_BOT_LIVE, api/_lib/gateway/adapters/x.js). No X call, no
+// secret read: this is a DB-only sensor, cheap enough for a per-request path.
+//
+// readMentionBotSignals() does the IO; mentionBotVerdict() is pure given its
+// output, so the status vocabulary (ok/degraded/paused/unknown) is testable
+// without a live database, the same split as api/_lib/ops/index-lag.js.
+
+import { sql } from './db.js';
+import { isPaused } from './x-mention-admin.js';
+import { isXMentionBotLive } from './gateway/adapters/x.js';
+
+const QUERY_TIMEOUT_MS = 4_000;
+
+// How far behind "decide what we already read" may fall before it is a fault,
+// and how error-heavy the last hour of decisions may run. Chosen by the work
+// order (x-grok 42): generous enough that one slow tick never flaps, tight
+// enough that a wedged decision path is visible within the hour it broke in.
+export const LAG_DEGRADED_MS = 10 * 60 * 1000;
+export const ERROR_RATE_DEGRADED = 0.2;
+// Below this many decisions in the last hour, an error rate is noise, not a
+// signal: one error out of two decided is "100%" and tells nobody anything.
+const ERROR_RATE_MIN_SAMPLE = 5;
+
+// Conservative placeholders until the real X tier is on this deployment (see
+// x-grok 926); raised with env, no deploy of code needed. Same env names the
+// budget design (docs/x-mention-bot.md on the branch that has it) already
+// uses, so a future port of that module needs no data migration here.
+const DAILY_POST_CAP = Number(process.env.X_MENTION_DAILY_POST_CAP) > 0 ? Number(process.env.X_MENTION_DAILY_POST_CAP) : 80;
+const MONTHLY_POST_CAP = Number(process.env.X_MENTION_MONTHLY_POST_CAP) > 0 ? Number(process.env.X_MENTION_MONTHLY_POST_CAP) : 1500;
+
+function withTimeout(promise, ms) {
+ return Promise.race([
+ promise,
+ new Promise((_, reject) => setTimeout(() => reject(new Error('mention bot health query timed out')), ms)),
+ ]);
+}
+
+/**
+ * One round trip over the whole ledger. Pure counts and timestamps; no
+ * per-row data leaves this function (callers decide what is safe to publish).
+ *
+ * @returns {Promise<{
+ * live: boolean, paused: boolean,
+ * lastEventAt: string|null, lastEventAgeMs: number|null,
+ * unprocessed: number, oldestUnprocessedAt: string|null, unprocessedLagMs: number|null,
+ * decidedLastHour: number, errorsLastHour: number, errorRate: number|null,
+ * handlesServed: number, replies24h: number, medianReplySeconds: number|null,
+ * budget: { dailyCap: number, dailyUsed: number, dailyRemaining: number,
+ * monthlyCap: number, monthlyUsed: number, monthlyRemaining: number },
+ * }>}
+ */
+export async function readMentionBotSignals({ env = process.env } = {}) {
+ const [paused, rows] = await Promise.all([
+ isPaused(),
+ withTimeout(
+ sql`
+ select
+ max(created_at) as last_event_at,
+ count(*) filter (where decision is null)::int as unprocessed,
+ min(created_at) filter (where decision is null) as oldest_unprocessed_at,
+ count(*) filter (where decided_at > now() - interval '1 hour')::int as decided_last_hour,
+ count(*) filter (where decision = 'error' and decided_at > now() - interval '1 hour')::int as errors_last_hour,
+ count(*) filter (where decision = 'reply' and created_at > now() - interval '1 day')::int as replies_24h,
+ count(*) filter (where decision = 'reply' and created_at >= date_trunc('day', now()))::int as replies_today,
+ count(*) filter (where decision = 'reply' and created_at >= date_trunc('month', now()))::int as replies_month,
+ count(distinct (account_kind || ':' || account_ref))::int as handles_served,
+ percentile_disc(0.5) within group (order by extract(epoch from (decided_at - created_at)))
+ filter (where decision = 'reply' and decided_at is not null and created_at > now() - interval '1 day') as median_reply_seconds
+ from x_mention_events
+ `,
+ QUERY_TIMEOUT_MS,
+ ),
+ ]);
+
+ const r = rows[0] || {};
+ const now = Date.now();
+ const lastEventAt = r.last_event_at ? new Date(r.last_event_at).toISOString() : null;
+ const oldestUnprocessedAt = r.oldest_unprocessed_at ? new Date(r.oldest_unprocessed_at).toISOString() : null;
+ const decidedLastHour = Number(r.decided_last_hour || 0);
+ const errorsLastHour = Number(r.errors_last_hour || 0);
+ const dailyUsed = Number(r.replies_today || 0);
+ const monthlyUsed = Number(r.replies_month || 0);
+
+ return {
+ live: isXMentionBotLive(env),
+ paused,
+ lastEventAt,
+ lastEventAgeMs: lastEventAt ? now - new Date(lastEventAt).getTime() : null,
+ unprocessed: Number(r.unprocessed || 0),
+ oldestUnprocessedAt,
+ unprocessedLagMs: oldestUnprocessedAt ? now - new Date(oldestUnprocessedAt).getTime() : null,
+ decidedLastHour,
+ errorsLastHour,
+ errorRate: decidedLastHour > 0 ? errorsLastHour / decidedLastHour : null,
+ handlesServed: Number(r.handles_served || 0),
+ replies24h: Number(r.replies_24h || 0),
+ medianReplySeconds: r.median_reply_seconds != null ? Math.round(Number(r.median_reply_seconds)) : null,
+ budget: {
+ dailyCap: DAILY_POST_CAP,
+ dailyUsed,
+ dailyRemaining: Math.max(0, DAILY_POST_CAP - dailyUsed),
+ monthlyCap: MONTHLY_POST_CAP,
+ monthlyUsed,
+ monthlyRemaining: Math.max(0, MONTHLY_POST_CAP - monthlyUsed),
+ },
+ };
+}
+
+/**
+ * Roll the bot's signals into one verdict. Pure: takes the shape
+ * readMentionBotSignals() returns (or any subset of it) and does no IO.
+ *
+ * Paused is a chosen state, never a fault, so it reports `paused` regardless
+ * of lag or errors underneath it (mentions are still recorded while paused;
+ * nothing is decided or sent, so both would otherwise always read "stuck").
+ * No event ever recorded is `unknown` (warming up), not a fault either.
+ *
+ * @param {{ paused: boolean, live: boolean, lastEventAgeMs: number|null,
+ * unprocessedLagMs: number|null, errorRate: number|null, decidedLastHour?: number }} signals
+ * @returns {{ status: 'ok'|'degraded'|'paused'|'unknown', mode: 'live'|'dry_run'|'paused', detail: string }}
+ */
+export function mentionBotVerdict({ paused, live, lastEventAgeMs, unprocessedLagMs, errorRate, decidedLastHour = 0 }) {
+ if (paused) {
+ return { status: 'paused', mode: 'paused', detail: 'paused by operator: mentions are still recorded, nothing is decided or sent' };
+ }
+ const mode = live ? 'live' : 'dry_run';
+ if (lastEventAgeMs == null) {
+ return { status: 'unknown', mode, detail: 'no mentions recorded yet' };
+ }
+
+ const lagDegraded = unprocessedLagMs != null && unprocessedLagMs > LAG_DEGRADED_MS;
+ const errorDegraded = decidedLastHour >= ERROR_RATE_MIN_SAMPLE && errorRate != null && errorRate > ERROR_RATE_DEGRADED;
+
+ if (!lagDegraded && !errorDegraded) {
+ return { status: 'ok', mode, detail: `${mode === 'live' ? 'live' : 'dry run'}, last mention ${Math.round(lastEventAgeMs / 1000)}s ago` };
+ }
+
+ const reasons = [];
+ if (lagDegraded) reasons.push(`oldest undecided mention is ${Math.round(unprocessedLagMs / 60_000)}m old (limit ${Math.round(LAG_DEGRADED_MS / 60_000)}m)`);
+ if (errorDegraded) reasons.push(`${Math.round(errorRate * 100)}% of the last hour's ${decidedLastHour} decisions errored`);
+ return { status: 'degraded', mode, detail: reasons.join('; ') };
+}
+
+/**
+ * Subsystem-health record for api/healthz.js's `subsystems` block. Never
+ * throws: an unreadable ledger reports `unknown`, like every other sensor.
+ * @returns {Promise<{ name: string, label: string, status: string, detail: string, metrics?: object }>}
+ */
+export async function gatherMentionBotHealth() {
+ const base = { name: 'x_mention_bot', label: 'X mention bot' };
+ let signals;
+ try {
+ signals = await readMentionBotSignals();
+ } catch (err) {
+ return { ...base, status: 'unknown', detail: err?.message || 'mention bot signals unreadable' };
+ }
+ const verdict = mentionBotVerdict(signals);
+ return { ...base, status: verdict.status, detail: verdict.detail, metrics: signals };
+}
+
+/**
+ * The public shape for GET /api/x/mention-bot/status: mode, aggregate
+ * activity, no row-level or budget data (no mention text, no author ids, no
+ * X tier caps). Never throws: a read failure reports `unknown` with zeroed
+ * activity rather than a 500, so the status surface itself never looks down
+ * because of its own probe.
+ * @returns {Promise<{ status: string, mode: string, handlesServed: number,
+ * repliesLast24h: number, medianReplySeconds: number|null, checkedAt: string }>}
+ */
+export async function publicMentionBotStatus() {
+ let signals;
+ try {
+ signals = await readMentionBotSignals();
+ } catch {
+ return { status: 'unknown', mode: 'unknown', handlesServed: 0, repliesLast24h: 0, medianReplySeconds: null, checkedAt: new Date().toISOString() };
+ }
+ const verdict = mentionBotVerdict(signals);
+ return {
+ status: verdict.status,
+ mode: verdict.mode,
+ handlesServed: signals.handlesServed,
+ repliesLast24h: signals.replies24h,
+ medianReplySeconds: signals.medianReplySeconds,
+ checkedAt: new Date().toISOString(),
+ };
+}
diff --git a/api/x/mention-bot/status.js b/api/x/mention-bot/status.js
new file mode 100644
index 000000000..48961bba6
--- /dev/null
+++ b/api/x/mention-bot/status.js
@@ -0,0 +1,34 @@
+// @ts-check
+// GET /api/x/mention-bot/status
+//
+// Public status for the X @-mention reply bot: mode, how many handles it has
+// replied on, how many replies it sent in the last day, and how fast. No
+// private data: no mention text, no author identities, no budget caps, no
+// row-level ledger content. Anyone can call this; it only ever aggregates.
+//
+// Cached 60s (cacheGet/cacheSet, matching api/status.js's own subsystem
+// snapshot) so a page load never pays for its own DB aggregate query twice.
+
+import { cors, json, method, rateLimited, wrap } from '../../_lib/http.js';
+import { clientIp, limits } from '../../_lib/rate-limit.js';
+import { cacheGet, cacheSet } from '../../_lib/cache.js';
+import { publicMentionBotStatus } from '../../_lib/x-mention-health.js';
+
+const CACHE_KEY = 'x:mention-bot:public-status';
+const CACHE_TTL_S = 60;
+
+export default wrap(async (req, res) => {
+ if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
+ if (!method(req, res, ['GET'])) return;
+
+ const rl = await limits.publicIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ let body = await cacheGet(CACHE_KEY);
+ if (!body) {
+ body = await publicMentionBotStatus();
+ await cacheSet(CACHE_KEY, body, CACHE_TTL_S);
+ }
+
+ return json(res, 200, { ...body, note: 'aggregate counts only, no private data' });
+});
diff --git a/data/changelog.json b/data/changelog.json
index f106ffe58..98f3b01e5 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$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, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-11",
+ "title": "The @-mention reply bot now reports its own status, and /grok shows it live",
+ "summary": "A new public endpoint, /api/x/mention-bot/status, answers whether the @-mention reply bot is live, in dry run, or paused, how many handles it has replied on, how many replies it sent in the last 24 hours, and its median reply time. No mention text or author identity is included. The /grok page now shows this as a live section, and /api/healthz carries the same signal as a platform subsystem, so an operator sees a wedged reply queue or a rising error rate within the hour it starts, instead of the bot quietly going silent with no signature anywhere.",
+ "tags": ["feature", "improvement"],
+ "link": "/grok"
+ },
{
"date": "2026-10-11",
"title": "An agent set to Grok now answers as Grok everywhere, with a badge when it can't",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 1265e72c8..c1f4c6313 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -9259,6 +9259,48 @@ Details: [docs/home-privacy.md](./home-privacy.md).
---
+## X Mention Bot API
+
+Agents on three.ws can reply to their own @-mentions on X through the same connector tools Grok uses (see [docs/grok.md](./grok.md)). This is the one public, unauthenticated read: an aggregate status for the bot as a whole, with no private data.
+
+### Bot status
+
+```
+GET /api/x/mention-bot/status
+```
+
+No session required. Rate limited like every other public read (`/api/x/mention-bot/status` shares the platform's public-IP limiter). Cached 60 seconds, so a page load never pays for its own aggregate query twice.
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "mode": "dry_run",
+ "handlesServed": 2,
+ "repliesLast24h": 25,
+ "medianReplySeconds": 42,
+ "checkedAt": "2026-10-11T08:04:31.903Z",
+ "note": "aggregate counts only, no private data"
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `status` | `ok`, `degraded`, `paused`, or `unknown`. Mirrors the `x_mention_bot` entry in [`/api/healthz`](#platform-stats-api)'s `subsystems` block. |
+| `mode` | `live` (replies actually post), `dry_run` (replies are composed and recorded but never sent), or `paused` (an operator switched the bot off; mentions are still recorded, nothing is decided or sent). |
+| `handlesServed` | Distinct agent/company handles the bot has ever recorded a mention for. |
+| `repliesLast24h` | Replies decided in the last 24 hours, across every handle. |
+| `medianReplySeconds` | Median time from a mention being recorded to its reply being decided, over the last 24 hours. `null` when there is no reply to measure yet. |
+
+No mention text, author identity, or send-budget data is ever included in this response; that detail is admin-only, through the operator console at `/api/x/ops/*` (list, status, pause, resume, block, unblock, send).
+
+```bash
+curl https://three.ws/api/x/mention-bot/status
+```
+
+---
+
## Pagination
Paginated list endpoints use `limit`/`offset` query parameters unless noted otherwise (each endpoint's own parameter table is authoritative; some small per-user lists, like `/api/agents` and `/api/widgets`, return everything with no pagination).
diff --git a/pages/grok.html b/pages/grok.html
index dd91e13e3..d301ac9d5 100644
--- a/pages/grok.html
+++ b/pages/grok.html
@@ -233,6 +233,15 @@
.gk-fact p { margin: 0; font-size: 0.84rem; line-height: 1.55; color: var(--ink-dim); }
.gk-fact a { text-decoration: underline; text-underline-offset: 3px; }
.gk-fact a:hover { color: var(--ink); }
+
+ /* ── mention bot status ────────────────────────────────────────── */
+ .gk-bot { display: grid; grid-template-columns: repeat(auto-fit, minmax(170px, 1fr)); gap: 10px; }
+ .gk-bot-stat { padding: 15px 16px; border: 1px solid var(--stroke); border-radius: var(--radius-md, 10px); background: var(--surface-1, rgba(255,255,255,0.03)); }
+ .gk-bot-label { margin: 0 0 6px; font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.05em; color: var(--ink-dim); }
+ .gk-bot-value { margin: 0; font-size: 1.4rem; font-weight: 650; color: var(--ink-bright, var(--ink)); }
+ .gk-bot-mode[data-tone="ok"] { color: var(--success); }
+ .gk-bot-mode[data-tone="degraded"] { color: var(--danger); }
+ .gk-bot-mode[data-tone="paused"], .gk-bot-mode[data-tone="unknown"] { color: var(--ink-dim); }
.gk-next { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 30px; }
@media (max-width: 860px) {
@@ -534,6 +543,17 @@ print(chat.sample().content)</pre>
<p class="gk-note" id="gk-tools-note" hidden></p>
</section>
+ <section class="gk-sec" aria-labelledby="gk-bot-h">
+ <div class="gk-sec-head">
+ <h2 id="gk-bot-h">The @-mention reply bot, live</h2>
+ <p>Mention an agent on X and it can reply through the same tools Grok uses. Aggregate activity only, read live from the bot's own ledger.</p>
+ </div>
+ <div class="gk-bot" id="gk-bot" aria-busy="true">
+ <div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div>
+ </div>
+ <p class="gk-note" id="gk-bot-note" hidden></p>
+ </section>
+
<section class="gk-sec" aria-labelledby="gk-facts-h">
<div class="gk-sec-head"><h2 id="gk-facts-h">Built for an agent that works while you sleep</h2></div>
<div class="gk-facts">
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 9fcaa2905..7dbdb2f53 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-10-11T01:08:21.068Z",
+ "generated_at": "2026-10-11T08:10:44.766Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 3853,
+ "total": 3854,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -30,6 +30,17 @@
"infra"
]
},
+ {
+ "date": "2026-10-11",
+ "type": "update",
+ "title": "The @-mention reply bot now reports its own status, and /grok shows it live",
+ "summary": "A new public endpoint, /api/x/mention-bot/status, answers whether the @-mention reply bot is live, in dry run, or paused, how many handles it has replied on, how many replies it sent in the last 24 hours, and its median reply time. No mention text or author identity is included. The /grok page now shows this as a live section, and /api/healthz carries the same signal as a platform subsystem, so an operator sees a wedged reply queue or a rising error rate within the hour it starts, instead of the bot quietly going silent with no signature anywhere.",
+ "link": "/grok",
+ "tags": [
+ "feature",
+ "improvement"
+ ]
+ },
{
"date": "2026-10-10",
"type": "launch",
@@ -1549,17 +1560,6 @@
"fix",
"improvement"
]
- },
- {
- "date": "2026-09-18",
- "type": "update",
- "title": "The $THREE page now has a live DEXTools chart and the Social Boost wins",
- "summary": "The $THREE page shows a live candle chart of the three / SOL pair, drawn by DEXTools. Below the platform's own buybacks there is a new section for the community's: the three DEXTools Social Boost prizes $THREE has won so far, $11,382 of buybacks in total, each with a link to its receipt on DEXTools. Social Boost ranks tokens by visits to their DEXTools page, so the section also links straight there. Every visit counts toward the next win.",
- "link": "/three-token",
- "tags": [
- "feature",
- "improvement"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index e82fcc7ef..ad76fbea4 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-11T01:08:21.048Z",
+ "generated_at": "2026-10-11T08:10:44.739Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -27,6 +27,17 @@
"infra"
]
},
+ {
+ "date": "2026-10-11",
+ "type": "update",
+ "title": "The @-mention reply bot now reports its own status, and /grok shows it live",
+ "summary": "A new public endpoint, /api/x/mention-bot/status, answers whether the @-mention reply bot is live, in dry run, or paused, how many handles it has replied on, how many replies it sent in the last 24 hours, and its median reply time. No mention text or author identity is included. The /grok page now shows this as a live section, and /api/healthz carries the same signal as a platform subsystem, so an operator sees a wedged reply queue or a rising error rate within the hour it starts, instead of the bot quietly going silent with no signature anywhere.",
+ "link": "/grok",
+ "tags": [
+ "feature",
+ "improvement"
+ ]
+ },
{
"date": "2026-10-10",
"type": "launch",
diff --git a/public/changelog.xml b/public/changelog.xml
index c0c84d83b..ca7c56af4 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -22,6 +22,14 @@
<category>improvement</category>
<description>The Sentiment Scout reads X for posts quoting a coin's exact contract address, as evidence a holder can open and check. When our own X search credentials are unavailable or rate limited, it now fails over to xAI's x_search tool, a second route to the same posts, metered by its own daily cap so an outage on one path never silently costs more than planned on the other. No change for anyone reading the Scout: the evidence looks the same either way.</description>
</item>
+ <item>
+ <title>The @-mention reply bot now reports its own status, and /grok shows it live</title>
+ <link>https://three.ws/grok</link>
+ <guid isPermaLink="false">2026-10-11:The @-mention reply bot now reports its own status, and /grok shows it live</guid>
+ <pubDate>Sun, 11 Oct 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>A new public endpoint, /api/x/mention-bot/status, answers whether the @-mention reply bot is live, in dry run, or paused, how many handles it has replied on, how many replies it sent in the last 24 hours, and its median reply time. No mention text or author identity is included. The /grok page now shows this as a live section, and /api/healthz carries the same signal as a platform subsystem, so an operator sees a wedged reply queue or a rising error rate within the hour it starts, instead of the bot quietly going silent with no signature anywhere.</description>
+ </item>
<item>
<title>Docs · Grok Bot recipes</title>
<link>https://three.ws/docs/tutorials/grok-bot-recipes</link>
diff --git a/src/grok-page.js b/src/grok-page.js
index 1ae9e293c..de280642f 100644
--- a/src/grok-page.js
+++ b/src/grok-page.js
@@ -524,6 +524,72 @@ async function loadSkill() {
}
}
+// ── @-mention reply bot status ────────────────────────────────────────────
+
+const BOT_MODE_LABEL = { live: 'Live', dry_run: 'Dry run', paused: 'Paused', unknown: 'Starting up' };
+
+function botStat(label, value) {
+ const card = document.createElement('div');
+ card.className = 'gk-bot-stat';
+ const l = document.createElement('p');
+ l.className = 'gk-bot-label';
+ l.textContent = label;
+ const v = document.createElement('p');
+ v.className = 'gk-bot-value';
+ v.textContent = value;
+ card.append(l, v);
+ return card;
+}
+
+function formatReplyTime(seconds) {
+ if (seconds == null) return 'n/a';
+ if (seconds < 60) return `${seconds}s`;
+ return `${Math.round(seconds / 60)}m`;
+}
+
+async function loadMentionBotStatus() {
+ const grid = $('gk-bot');
+ const note = $('gk-bot-note');
+ grid.setAttribute('aria-busy', 'true');
+ note.hidden = true;
+ try {
+ const res = await fetch('/api/x/mention-bot/status', { headers: { accept: 'application/json' } });
+ if (!res.ok) throw new Error(`status answered ${res.status}`);
+ const data = await res.json();
+ const mode = document.createElement('div');
+ mode.className = 'gk-bot-stat';
+ const l = document.createElement('p');
+ l.className = 'gk-bot-label';
+ l.textContent = 'Mode';
+ const v = document.createElement('p');
+ v.className = 'gk-bot-value gk-bot-mode';
+ v.dataset.tone = data.status;
+ v.textContent = BOT_MODE_LABEL[data.mode] || data.mode;
+ mode.append(l, v);
+ grid.replaceChildren(
+ mode,
+ botStat('Handles served', String(data.handlesServed ?? 0)),
+ botStat('Replies, last 24h', String(data.repliesLast24h ?? 0)),
+ botStat('Median reply time', formatReplyTime(data.medianReplySeconds)),
+ );
+ note.hidden = false;
+ note.removeAttribute('data-tone');
+ note.textContent = 'Aggregate counts only, no private data: no mention text, no author identities.';
+ } catch (err) {
+ grid.replaceChildren();
+ note.hidden = false;
+ note.dataset.tone = 'error';
+ note.textContent = `Could not load bot status (${err?.message || 'network error'}). `;
+ const retry = document.createElement('button');
+ retry.type = 'button';
+ retry.textContent = 'Try again';
+ retry.addEventListener('click', loadMentionBotStatus, { once: true });
+ note.append(retry);
+ } finally {
+ grid.setAttribute('aria-busy', 'false');
+ }
+}
+
wireCopy();
wireTabs();
mountConnector();
@@ -531,3 +597,4 @@ loadStrip();
startDemo();
loadSkill();
loadTools();
+loadMentionBotStatus();
diff --git a/tests/x-mention-health.test.js b/tests/x-mention-health.test.js
new file mode 100644
index 000000000..65a6fa33e
--- /dev/null
+++ b/tests/x-mention-health.test.js
@@ -0,0 +1,87 @@
+/**
+ * X mention bot health sensor, unit test (x-grok 42).
+ *
+ * The bot has no reachability signature of its own: the webhook always
+ * answers 200 to X whether or not it actually decided anything, so a wedged
+ * decision path or a silently error-heavy hour looked identical to healthy
+ * from the outside. This pins the verdict logic that now distinguishes them,
+ * including the one state that must never read as a fault: an operator who
+ * paused the bot on purpose.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { mentionBotVerdict, LAG_DEGRADED_MS, ERROR_RATE_DEGRADED } from '../api/_lib/x-mention-health.js';
+
+describe('mentionBotVerdict', () => {
+ it('reads unknown before any mention has ever been recorded', () => {
+ const v = mentionBotVerdict({ paused: false, live: false, lastEventAgeMs: null, unprocessedLagMs: null, errorRate: null });
+ expect(v.status).toBe('unknown');
+ expect(v.mode).toBe('dry_run');
+ });
+
+ it('reads ok in dry run with fresh mentions and no lag', () => {
+ const v = mentionBotVerdict({ paused: false, live: false, lastEventAgeMs: 5_000, unprocessedLagMs: 1_000, errorRate: 0, decidedLastHour: 10 });
+ expect(v.status).toBe('ok');
+ expect(v.mode).toBe('dry_run');
+ expect(v.detail).toMatch(/dry run/);
+ });
+
+ it('reads ok and live when the bot is actually sending', () => {
+ const v = mentionBotVerdict({ paused: false, live: true, lastEventAgeMs: 5_000, unprocessedLagMs: 1_000, errorRate: 0, decidedLastHour: 10 });
+ expect(v.status).toBe('ok');
+ expect(v.mode).toBe('live');
+ expect(v.detail).toMatch(/live/);
+ });
+
+ it('degrades when the oldest undecided mention exceeds the lag threshold', () => {
+ const v = mentionBotVerdict({
+ paused: false,
+ live: true,
+ lastEventAgeMs: 30_000,
+ unprocessedLagMs: LAG_DEGRADED_MS + 60_000,
+ errorRate: 0,
+ decidedLastHour: 10,
+ });
+ expect(v.status).toBe('degraded');
+ expect(v.detail).toMatch(/undecided mention/);
+ });
+
+ it('degrades when the last hour error rate exceeds the threshold at real sample size', () => {
+ const v = mentionBotVerdict({
+ paused: false,
+ live: true,
+ lastEventAgeMs: 5_000,
+ unprocessedLagMs: 0,
+ errorRate: ERROR_RATE_DEGRADED + 0.1,
+ decidedLastHour: 20,
+ });
+ expect(v.status).toBe('degraded');
+ expect(v.detail).toMatch(/errored/);
+ });
+
+ it('does not degrade on a high error rate from too small a sample', () => {
+ const v = mentionBotVerdict({
+ paused: false,
+ live: true,
+ lastEventAgeMs: 5_000,
+ unprocessedLagMs: 0,
+ errorRate: 1,
+ decidedLastHour: 1,
+ });
+ expect(v.status).toBe('ok');
+ });
+
+ it('reads paused, never down, when an operator switched the bot off on purpose', () => {
+ const v = mentionBotVerdict({
+ paused: true,
+ live: true,
+ lastEventAgeMs: LAG_DEGRADED_MS * 100,
+ unprocessedLagMs: LAG_DEGRADED_MS * 100,
+ errorRate: 1,
+ decidedLastHour: 50,
+ });
+ expect(v.status).toBe('paused');
+ expect(v.mode).toBe('paused');
+ expect(v.status).not.toBe('down');
+ });
+});