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.

28.0 KB
Raw Blame

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:

  1. 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.
  2. 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 /launch link the author reviews and signs themselves.
  3. 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 to x_mention_events and 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.
  4. Reply only when addressed, one reply per mention, never to our own replies.
  5. $THREE is 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.js calls GET /2/users/:id/mentions since 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/webhook answers X's Challenge-Response Check; POST /api/x/webhook verifies the x-twitter-webhooks-signature header (HMAC-SHA256 over the raw body with the app's OAuth 1.0a consumer secret, constant-time compared), normalizes the delivery with api/_lib/x-webhook-events.js (normalizeActivityEvent, producing the same shape the poller does), and records it through recordMention, leaving decision = null for 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.mjs registers, 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.

  1. 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 from GET /2/tweets/:id. The mention is stamped args.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 with bot_no_human_root, bot_root_unresolved, bot_root_not_human, author_blocked or new_account.
  2. 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 as known_bot: a bot can never start a conversation, a launch or anything that moves funds.
  3. Whose limits apply. The human's. x_mention_events counts a person's own mentions and mentions a bot wrote for them together (countByPrincipal), against X_MENTION_REPLIES_PER_AUTHOR_HOUR and _DAY. The bot account is never charged.
  4. One reply, machine-friendly. To the bot's post, four lines: what we made, Viewer: <link>, GLB: <link>, and Add three.ws to Grok Bot as an MCP connector: https://three.ws/api/mcp-grok. A generation that fails or outlasts X_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.
  5. Loop cap. One reply per conversation to bot authors, ever (bot_loop_cap, counted from args.on_behalf_of on 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 } under makeFollowUp, avatarFollowUp or image3dFollowUp and the others still run.
  • Delivered through the X adapter. api/_lib/x-mention-deliver.js builds the deliver the finishers use on createXAdapter. A dry row (dry_run = true, the default) is only recorded on the x_mention_events row and nothing is posted. A live row is posted by the adapter only when X_MENTION_BOT_LIVE=1 and 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 as paused for 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

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].js calls claimForUser after an owner link. A claim failure never fails the link.
  • On a new creation. If the author had already linked, attributeCreation hands the creation over at once.
  • On the page. /x/claim lists claimable creations and claims them through GET and POST /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/claim for 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() in api/_lib/x-mention-health.js feeds api/healthz.js's subsystems array (key x_mention_bot). Derived entirely from x_mention_events plus the pause/live switches: ok / degraded / paused / unknown. degraded at 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); paused always wins over lag or errors, since mentions are still recorded while paused, just never decided or sent. Rows whose account_ref ends in -evidence (the synthetic account the scripts/x-mention-*-dry-run.mjs scripts 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, returns status, mode, handlesServed, repliesLast24h, medianReplySeconds, checkedAt. Explicitly no mention text, author identity, or budget data. Shown live on /grok as 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() joins agent_x_policies, agent_x_connections and agent_identities; listAccounts() in x-mention-poll.js turns 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.read and tweet.write (X_MENTION_REQUIRED_SCOPES). If one is missing the poll reports status: missing_scope with 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 under mention_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_prompt instead of the company persona. A chat reply 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_run off AND the operator set X_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_ENABLED unset) 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's xLoginEnabled needs X_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.