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.
The X @-mention reply bot
Internal operator runbook. Not a product surface: nothing here is linked from
the public site until the bot goes live (owner order 928). It documents the
pieces that answer an @-mention of @trythreews or one of our agents'
connected X accounts: how a mention becomes a decision, where that decision is
reviewed, and what is and is not wired yet.
For the sibling capability that lets an X account sign in to three.ws
(rather than be read as a mention), see the "Account linking" section below.
For the launch-by-mention intent (launch <NAME> $<TICKER>), see the
"Launch by mention" section below.
Design rules
These come from prompts/finish/_context/x-grok-00-CONTEXT.md and apply to
every piece below:
- Mention text is untrusted. A tweet, a bio, a quoted post, or image alt text is data, never an instruction. No path from it reaches a spend, a transfer, a launch, or a post to anyone other than the author who tagged us, in the same conversation. None of the automatic guard rules below read what a mention says; they key off ids, timestamps and our own records.
- No spend through this path. The bot can read, generate, and reply. It
can never move funds, pay x402, or launch a coin itself; a launch intent
only ever builds a
/launchlink the author reviews and signs themselves. - Dry run by default. Every write path is gated by an env flag
(
X_MENTION_BOT_LIVE) and, per agent, by that agent's own policy. With it unset, the pipeline reads, decides, and records what it would have replied, and posts nothing. Replies are written tox_mention_eventsand counted against every rate limit and budget exactly as a live reply would, so dry run behaves exactly as live will and the numbers are honest before going live. - Reply only when addressed, one reply per mention, never to our own replies.
$THREEis the only coin this bot promotes or recommends.
The ledger: x_mention_events
Every mention is recorded exactly once, before anything else happens. Table
x_mention_events (migration
api/_lib/migrations/20261008170000_x_mention_events.sql),
keyed by tweet_id so two readers that both see the same mention race on one
INSERT ... ON CONFLICT DO NOTHING and exactly one wins the right to handle
it. Columns: which account was mentioned (account_kind company/agent,
account_ref), the author, the raw mention text, the intent the parser gave
it, the decision (reply | skip | rate_limited | unsafe | budget | error | pending | paused, null while undecided), the reply text/media/link it sent
or would send, whether it was a dry_run, and timestamps. Reader/writer:
api/_lib/x-mention-store.js
(recordMention, updateDecision, recentDecisions, adminListMentions,
adminCountMentions, countConversationReplies). Polling cursors live in
app_settings under x_mentions_cursor:<kind>:<ref>, not in this table. The
full audit trail is one query:
select decision, reason, count(*) from x_mention_events group by 1, 2 order by 3 desc;
Turning a mention into an intent
api/_lib/x-mention-intents.js is a pure
module (no network, no DB, no clock): parseMentionIntent reads a normalized
mention and our account, and returns one of seven intents, deterministically:
| Intent | What it is |
|---|---|
make |
A 3D-model request from a text description. |
image3d |
Turn an attached, quoted, or replied-to image into a 3D model. |
avatar |
Turn the author into a rigged avatar (including "3D my pfp"). |
help |
Commands/usage, or any mention the parser cannot read safely. |
launch |
launch <NAME> $<TICKER> [description] grammar (925's intent). |
chat |
Anything else addressed to us, answered without a tool call. |
ignore |
Not addressed to us (only inherited through a reply chain, etc). |
Safety is enforced inside the parser, before any model ever sees the text:
phrasing that asks for funds to move, a signed transaction, or a secret
(private key, seed phrase, API key) is forced to help rather than reaching
chat or any generator, and the same happens for instruction-override
phrasing ("ignore previous instructions", "you are now..."). Untrusted text
is also normalized first (normalizeText: NFKC fold, invisible/bidi
character stripping, length cap) so lookalike characters and zero-width
tricks cannot dodge the rules above. addressing() classifies how a post
reached us (direct, inherited through a reply chain, or absent), and
only direct ever produces a reply. Tested in
tests/x-mention-intents.test.js,
including hostile fixtures.
Reading mentions: the two inputs, and the cron that drains them
Two independent readers feed the same ledger, so either one can be the trigger without the other existing:
- Polling.
api/_lib/x-mentions.jscallsGET /2/users/:id/mentionssince a cursor, for the company account (app OAuth 1.0a) or an agent's own connected account (its OAuth2 user token). Typed failures (XTierUnavailable,XRateLimited,XAuthFailed,XMentionsError) let a caller act without parsing strings. - The Account Activity webhook.
GET /api/x/webhookanswers X's Challenge-Response Check;POST /api/x/webhookverifies thex-twitter-webhooks-signatureheader (HMAC-SHA256 over the raw body with the app's OAuth 1.0a consumer secret, constant-time compared), normalizes the delivery withapi/_lib/x-webhook-events.js(normalizeActivityEvent, producing the same shape the poller does), and records it throughrecordMention, leavingdecision = nullfor the decision step to pick up. It is disabled by default (X_WEBHOOK_ENABLED) and, when enabled without company X credentials configured, acks{ok:true,disabled:true}without touching the database.scripts/x-webhook-register.mjsregisters, lists, or deletes the subscription (--dry-run,--list,--delete,--url). X's Account Activity API needs an Enterprise or Pay-Per-Use tier, capped at 3 subscriptions: owner order 926's gap, named in the handler's own top comment. Tests:tests/api/x-webhook.test.js.
/api/cron/x-mentions (Cloud Scheduler, every two minutes, see vercel.json)
is the pipeline that actually drains both inputs: handleXMentions in
api/cron/[name].js calls runMentionTick() in
api/_lib/x-mention-poll.js, which polls
every configured account, runs each new mention through the parser and the
automatic safety guard below, decides, composes a reply, and records (or, with
X_MENTION_BOT_LIVE unset, would send) it through the X adapter. The tick
also calls runFollowUps() for jobs that outlived a mention's bounded wait;
see "Late replies" below.
Once handleMention has recorded a mention row, any throw (the kill-switch
read, the ignore branch, the guard, the brain, the send) is caught and written
back as decision = 'error'. A row is never left at decision = null by a
failure, because the next tick sees it as a duplicate and would never revisit it.
The automatic safety guard
Every mention runMentionTick hands to handleMention is checked by
guardMention (code: api/_lib/x-mention-guard.js,
api/_lib/x-mention-known-bots.js), in this order:
| Rule | Decision / reason | How to change it |
|---|---|---|
| Kill switch | paused / kill_switch |
Set env X_MENTION_BOT_PAUSED=1, or insert the app_settings row x_mention_bot_paused = {"paused": true} (takes effect on the next tick, no deploy). A failed settings read also pauses. Mentions are still recorded and the cursor still advances, so unpausing never answers the backlog. |
| Parser ignores (retweets, our own posts) | skip / parser reason |
api/_lib/x-mention-intents.js |
| Our own account | skip / own_account |
The polled account's id and handle, the company id, plus env X_MENTION_OWN_USER_IDS (comma separated ids). |
| Blocklist | skip / author_blocked |
app_settings row x_mention_blocklist = {"ids": ["<author id>", ...]}. |
| Known bot quoting our post without addressing us | skip / bot_quote_of_own_post |
Automatic for any known bot. |
| Known bot | skip / known_bot, unless it asks for a 3D model: then answered on behalf of the human |
See below. |
| Author account under 24 hours old | skip / new_account |
MIN_AUTHOR_AGE_SECONDS in the guard. Skipped only when X returns created_at. |
| One reply per conversation per hour | skip / conversation_hourly |
CONVERSATION_WINDOW_SECONDS in the guard. |
| Depth cap: never a third reply in a conversation | skip / conversation_depth |
CONVERSATION_MAX_REPLIES in the guard. |
| Per-author allowance | rate_limited |
env X_MENTION_REPLIES_PER_AUTHOR_HOUR (3), X_MENTION_REPLIES_PER_AUTHOR_DAY (10). |
| X API budget | budget / degraded:<intent>, daily_post_cap, monthly_post_cap, rate_limit_backoff, budget_unreadable |
See "The X budget" below. |
Replies counted for the conversation rules include dry-run replies, so dry run behaves exactly as live will.
Known bots
KNOWN_BOT_USERNAMES in x-mention-known-bots.js is the source of truth
(grok, bot). Add more without a deploy through env X_MENTION_KNOWN_BOTS
(comma separated usernames). On the first mention batch of each day the
poller resolves the names to ids with GET /2/users/by and caches them in
app_settings key x_mention_known_bots; a refused lookup (tier, rate
window, auth) keeps the old ids, is retried the next day, and lists the names
under unresolved. A known bot is matched by cached id or by username, so the
list works before any lookup succeeds and survives a rename.
The X budget
X reads and posts are metered, and a viral thread can send thousands of
mentions in an hour. api/_lib/x-budget.js counts every read and every reply
in app_settings (x_budget_day_YYYY-MM-DD, x_budget_month_YYYY-MM, UTC)
and the bot degrades in a fixed order instead of burning the month in a day or
going dark mid-conversation.
| Cap | Env | Default | Reasoning |
|---|---|---|---|
| Replies per month | X_MENTION_MONTHLY_POST_CAP |
1500 | About 50 a day. Low enough that a mispriced tier cannot run away, high enough for real conversations. |
| Replies per day | X_MENTION_DAILY_POST_CAP |
80 | Monthly cap spread over 30 days with headroom, so one viral day cannot spend the month. |
| Posts read per month | X_MENTION_MONTHLY_READ_CAP |
15000 | X bills per post read. The poller only reads mentions newer than its cursor, so this is about ten times the reply cap (most mentions are skipped by the parser and the safety rules). |
These are conservative placeholders until order 926 records the real allowances of the X tier; raise them with env, no deploy of code needed.
The ladder uses the largest used fraction of any cap (the "level"). Dropped
intents are answered with nothing (a reply costs a post) and recorded as
budget with the reason:
| Level | Dropped |
|---|---|
| 70% | chat |
| 80% | avatar |
| 90% | image3d |
| 100% | make, launch and help (a cap is a hard stop; make and help go last) |
X's own headers are honored too. After every read, x-rate-limit-remaining: 0 backs the bot off until x-rate-limit-reset, and
x-app-limit-24hour-remaining: 0 until x-app-limit-24hour-reset; a 429 with
neither backs off 15 minutes. While a backoff is active the reader does not
call X and no reply is composed (rate_limit_backoff); the cursor stays put,
so mentions are read after the window, never lost. A budget that cannot be
read fails closed (budget_unreadable). When the read cap is reached the
poll tick reports status: budget.
getBudgetUsage() returns caps, usage, remaining, level, dropped intents and
any backoff; GET /api/x/mention-bot/status (see "Health and public status"
below) serves it.
Account linking: mapping an X author to a three.ws account
api/_lib/x-identity.js exports
findUserByXId(authorId), the one shared answer to "is this X user one of
ours": it checks social_connections (an owner's own account, connected to
post) and falls back to agent_x_connections (a single agent's connected
account), both scoped to disconnected_at is null. The mention-reply flow,
the creation-claim flow, and order 925's launch flow all share this lookup
rather than each resolving identity their own way.
An X account can also sign in to three.ws, not just be read as a mention
author: api/auth/x/[action].js's login action reuses the existing OAuth2
client (scopes tweet.read users.read offline.access, read-only) and signs
in through three branches: already linked (findUserByIdentity), already
connected for posting (findUserByXId, links and signs in), or a new
passwordless account on the same @wallet.local placeholder pattern
api/auth/siws/[action].js already uses for wallet sign-in (X's OAuth2
profile never reliably carries a verified email, so there is no
email-matching step like Google's). public/login.html shows the button
once api/config.js's xLoginEnabled is true, which needs
X_OAUTH_CLIENT_ID/X_OAUTH_CLIENT_SECRET configured; neither exists on any
deployment of this repository yet. Tests:
tests/x-identity.test.js,
tests/user-identities-provider-constraint.test.js.
Per-agent mention settings
An agent owner controls whether their agent answers mentions of its own
connected X account from the Social tab of
pages/agent-edit.html: enable/dry-run toggles, a
daily reply cap (0 to 50), and which intents it may act on, over
GET/PUT /api/x/agents (api/x/agents.js). Four
columns on agent_x_policies
(migration
20261011220000_agent_mention_policy.sql):
mention_replies_enabled, mention_replies_dry_run,
mention_replies_daily_cap, mention_replies_allowed_intents, validated by
api/_lib/x-agent-policy.js (an unknown
intent id or an out-of-range cap is a validation_error). The panel also
shows the agent's own recent decisions
(GET /api/x/mention-decisions,
api/x/mention-decisions.js, owner-only,
limit 1 to 20) with the decision badge, author, reason, would-be reply text,
and media thumbnail. Tests:
tests/x-mention-decisions-endpoint.test.js,
tests/agent-mention-policy-migration.test.js.
When @grok or @bot tags us
Grok Bot acts on X for its user, and @grok answers in threads, so one of them
will tag us on a person's behalf ("@trythreews can you make a 3D version of
this?"). Code: api/_lib/x-mention-on-behalf.js, called from handleMention
when the guard reports known_bot.
- Whose request it is. The human is the author of the conversation's
root post (the post whose id is the mention's
conversation_id). It comes from the parent post when the bot replied directly to the root, otherwise fromGET /2/tweets/:id. The mention is stampedargs.on_behalf_of = { id, username, via }. If the bot started the conversation itself, the root is gone, or the root author is another known bot, one of our accounts, blocklisted or under 24 hours old, the mention is skipped withbot_no_human_root,bot_root_unresolved,bot_root_not_human,author_blockedornew_account. - What a bot may ask for. Only a 3D model request (
make), parsed by the same parser as any mention. Chat,launch, refused requests and anything else stay skipped asknown_bot: a bot can never start a conversation, a launch or anything that moves funds. - Whose limits apply. The human's.
x_mention_eventscounts a person's own mentions and mentions a bot wrote for them together (countByPrincipal), againstX_MENTION_REPLIES_PER_AUTHOR_HOURand_DAY. The bot account is never charged. - One reply, machine-friendly. To the bot's post, four lines: what we
made,
Viewer: <link>,GLB: <link>, andAdd three.ws to Grok Bot as an MCP connector: https://three.ws/api/mcp-grok. A generation that fails or outlastsX_BOT_MAKE_BUDGET_MS(default 90 seconds) gets a reply with a prefilled/forge?prompt=link instead; a prompt the studio moderation refuses gets a fixed refusal with no echo. No handles, no hashtags, no dashes. - Loop cap. One reply per conversation to bot authors, ever
(
bot_loop_cap, counted fromargs.on_behalf_ofon replied rows), and never an answer to a bot's reply to our reply (bot_reply_to_own_reply). The conversation depth cap above still applies.
Dry run applies as everywhere: the four-line reply is recorded on the row and
nothing is posted until the owner flips the bot live. Tests with synthetic
thread fixtures: tests/x-mention-on-behalf.test.js.
Late replies: make, avatar and image-to-3D follow-ups
A make, avatar or image3d mention whose 3D job outlives the bounded
wait is recorded as pending. Every x-mentions tick then runs
runFollowUps() (api/_lib/x-mention-poll.js), which calls
finishPendingMakes(), finishPendingAvatars() and finishPendingImage3d()
(api/_lib/x-mention-image3d.js, see
x-mention-image3d.md):
- Gated like any reply. The kill switch skips all three, and a closed
read/post budget gate skips all three. The report carries
followUps: { skipped: 'kill_switch' | 'budget' }. - Isolated. Each finisher runs in its own catch; one throwing reports
{ error }undermakeFollowUp,avatarFollowUporimage3dFollowUpand the others still run. - Delivered through the X adapter.
api/_lib/x-mention-deliver.jsbuilds thedeliverthe finishers use oncreateXAdapter. A dry row (dry_run = true, the default) is only recorded on thex_mention_eventsrow and nothing is posted. A live row is posted by the adapter only whenX_MENTION_BOT_LIVE=1and a token resolver is supplied (getAccessToken(row)); each real post counts against the post budget. With no resolver the adapter stays in dry run, so rows are no longer held aspausedfor lack of a deliver.
The image3d intent is routed to handleImage3d() in handleMention (dry
run, same budget and per-author limits as any reply); only make still
answers with help (handler_not_built).
Launch by mention
@trythreews launch Moon Cat $MCAT a cat on the moon is answered with a link,
never a launch. Launching signs with the agent's custodial wallet, which
three.ws allows only from a same-site browser session, so the bot has no
spend path at all: api/_lib/x-mention-launch.js imports a database handle,
the X identity lookup and a URL helper, and nothing that can sign, pay or call
a launch API (a test asserts the import list). The grammar is
parseLaunch in api/_lib/x-mention-intents.js; tweet text reaches the
reply only as URL-encoded query values of the /launch link.
| Author | Reply | reason |
|---|---|---|
| X account linked to a three.ws account, with an agent that has a 3D body | Prefilled /launch?avatar=...&name=...&symbol=...&description=... plus "Nothing is paid until you review and sign on three.ws." |
launch_link |
| Linked, agent without a body | Link to the agent page to give it one | launch_no_body |
| Linked, no agent | Link to /create |
launch_no_agent |
Not linked (findUserByXId) |
Link to /x/claim to sign in and connect X |
launch_unlinked |
The author is the X user id X attached to the post, never anything in the text.
The agent is the newest live agent of the linked user that has a 3D body. The
polling cron (/api/cron/x-mentions, every two minutes), the cursor, dedupe
by tweet id, per-author limits and the decision ledger are the ones every
other intent uses. With X_MENTION_BOT_LIVE unset the company account only
records the reply it would send (x_mention_events.reply_text, visible in
/x/ops); nothing is posted. Going live is the owner step (order 928).
Going live stays the separate owner step.
The operator console: /x/ops
Admin-only, noindex, not in the public sitemap: pages/x-ops.html
src/x-ops.js, backed byapi/x/ops/[action].jsandapi/_lib/x-mention-admin.js. It is the review surface over the ledger above, not a second decision engine:
| Action | What it does |
|---|---|
list / status |
Filter the ledger by account, intent, decision, dry-run status; read the kill switch and blocklist. |
pause / resume |
Flip app_settings key x_mention_bot_paused (also honored via env X_MENTION_BOT_PAUSED). Pausing never needs a redeploy. |
block / unblock |
Edit the app_settings-backed JSON blocklist (key x_mention_blocklist) of author ids. |
send |
For exactly one dry-run reply row with no reply_tweet_id yet: resolve the posting target (company OAuth 1.0a or the agent's own OAuth2 connection), upload media if present, post, and flip the row to dry_run: false with the real tweet id. Gated by CSRF and, in the UI, a native confirmation naming the account, tweet id, and reply text before the request fires. |
Every mutating action is admin-authenticated and CSRF-checked before it runs.
Tests: tests/x-ops-authorization.test.js
(43 cases: anonymous 401, non-admin 403, CSRF enforced per action, success
shapes).
Claiming what the bot made
A creation made from a mention belongs to the system bot account
(users.service_account, email [email protected], no credentials,
created on first use) and carries forge_creations.x_author_id, the
author's numeric X id.
api/_lib/x-creation-claim.js moves it to
a person only when that person's verified X link
(social_connections.provider_uid) equals the creation's x_author_id:
- On link. The OAuth callback in
api/auth/x/[action].jscallsclaimForUserafter an owner link. A claim failure never fails the link. - On a new creation. If the author had already linked,
attributeCreationhands the creation over at once. - On the page.
/x/claimlists claimable creations and claims them throughGETandPOST /api/x/claim(signed in, CSRF on the write). Signed out it explains and links sign-in; with no X link it offers Link X; with nothing waiting it points to the library. - Replies. Every success reply gets one line:
Saved to your library.for a linked author,Claim it: <origin>/x/claimfor an unlinked one. The line is skipped if it would push the post past the length limit.
Each move writes a row to x_creation_claims (migration
20261009213000_x_creation_claims.sql) with the creation, the X id, the user
and the source (link, claim_page or mention).
Health and public status
Two surfaces, same signals, different audiences:
- Operator:
gatherMentionBotHealth()inapi/_lib/x-mention-health.jsfeedsapi/healthz.js'ssubsystemsarray (keyx_mention_bot). Derived entirely fromx_mention_eventsplus the pause/live switches:ok/degraded/paused/unknown.degradedat more than 10 minutes of oldest-undecided lag, or more than 20% hourly error rate at a minimum 5-decision sample (so one early error never flaps it);pausedalways wins over lag or errors, since mentions are still recorded while paused, just never decided or sent. Rows whoseaccount_refends in-evidence(the synthetic account thescripts/x-mention-*-dry-run.mjsscripts write under) are excluded from these aggregates, so test fixtures never feed the live signal. - Public:
GET /api/x/mention-bot/status(api/x/mention-bot/status.js), rate limited and cached 60s, returnsstatus,mode,handlesServed,repliesLast24h,medianReplySeconds,checkedAt. Explicitly no mention text, author identity, or budget data. Shown live on/grokas a four-stat section. Tests:tests/x-mention-health.test.js.
Checking it
npx vitest run tests/x-mention-guard.test.js tests/x-budget.test.js tests/x-mention-on-behalf.test.js tests/x-mention-poll.test.js
The kill switch tests assert zero calls to the reply brain and the X adapter.
Agent mode: an agent answers its own mentions
An agent with its own connected X account (agent_x_connections) and
mention_replies_enabled on is polled by the same cron as the company account,
through api/_lib/x-agent-mentions.js:
- Who is polled.
agentMentionAccounts()joinsagent_x_policies,agent_x_connectionsandagent_identities;listAccounts()inx-mention-poll.jsturns each into a descriptor carrying the agent, its policy and its missing scopes. Only the agent's own account is read, never the owner's personal one. - Scope check. The connection must carry
tweet.read,users.readandtweet.write(X_MENTION_REQUIRED_SCOPES). If one is missing the poll reportsstatus: missing_scopewith the list and makes no X call; the settings page shows the same gap (can_answer_mentions,missing_mention_scopes). Reconnecting X with the full scope set clears it. - Gates, in order, after the guard and per-author limits: the intent must be
in
mention_replies_allowed_intents(chat, make, image3d, avatar; help and launch carry no 3D side effect and always pass), then the account's replies in the last 24 hours must be undermention_replies_daily_cap(dry-run rows count, so the cap behaves the same live), then the shared X budget. - Persona and body. The reply brain gets the agent's name and
persona_promptinstead of the company persona. Achatreply attaches a render of the agent's own avatar (agent_identities.avatar_id, via/api/render/glb) when it has one. - Dry run by default. A reply is posted only when the owner turned
mention_replies_dry_runoff AND the operator setX_MENTION_BOT_LIVE=1. Late make/avatar/image-to-3D replies for an agent row post through that agent's token too. A known bot tagging an agent is skipped (known_bot); the on-behalf-of flow is company-only.
Tests: tests/x-agent-mentions.test.js.
What is not wired yet
Documented plainly rather than papered over, since this file is the single source of truth for everything in this subsystem:
- The bot is not live. Every piece above, including the poll cron, the
automatic guard, the budget ladder, the on-behalf-of handling, and the
follow-up finishers, runs end to end in dry run. Nothing posts to X until
the owner sets
X_MENTION_BOT_LIVE=1(owner order 928). - The Account Activity webhook needs an X tier we do not hold. The
handler exists and is tested, but subscribing needs an Enterprise or
Pay-Per-Use tier; it stays disabled (
X_WEBHOOK_ENABLEDunset) until owner order 926 resolves that. The poll cron does not depend on it. - The X budget caps are conservative placeholders, not the tier's real allowances; owner order 926 also covers recording the real numbers.
- X sign-in is built but not configured.
api/config.js'sxLoginEnabledneedsX_OAUTH_CLIENT_ID/X_OAUTH_CLIENT_SECRET, which exist on no deployment of this repository yet.
None of these gaps block what is documented above: the ledger, the parser,
the automatic guard and budget, the on-behalf-of handling, the follow-up
finishers, the claim flow, the per-agent settings, the ops console, and the
health/status endpoints are all real, tested, and independently useful (an
admin can already review real mentions and send a real, manually-reviewed
reply through /x/ops today). Going fully live, i.e. setting
X_MENTION_BOT_LIVE=1, stays owner order 928.