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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// The mention polling loop: read new mentions of our X accounts, record each
// once, decide, deliver one reply through the X adapter, record the outcome.
//
// Safe to run every two minutes forever:
// - a run lock (app_settings row with an expiry) stops overlapping ticks;
// - x_mention_events.tweet_id is the primary key, so a mention read twice is
// handled once;
// - the cursor only moves past mentions that are fully recorded, so a crash
// mid-batch re-reads the unrecorded tail and nothing else;
// - X being unavailable (tier, credits, rate window, bad credentials) is a
// quiet, recorded outcome, never a thrown error;
// - the first poll of an account only anchors the cursor at "now": the bot
// never answers an account's history.
//
// Dry run is the default. The adapter posts only when X_MENTION_BOT_LIVE is
// "1" AND a poster token resolver is supplied; this loop supplies none for the
// company account, so going live is the separate owner step (order 928). An
// agent account (x-agent-mentions.js) goes live only when its owner also turned
// its mention-reply dry run off.
//
// Mention text is untrusted data: it is parsed by the pure parser and quoted
// to the reply brain as data. The only action it can ever cause is one reply
// to the same author.
import { randomUUID } from 'node:crypto';
import { sql } from './db.js';
import * as mentionStore from './x-mention-store.js';
import { fetchMentions, resolveAccount, companyMentionsConfigured, XMentionsError, XTierUnavailable, XRateLimited, XAuthFailed } from './x-mentions.js';
import { parseMentionIntent } from './x-mention-intents.js';
import { composePublicReply, FIXED_HELP_REPLY } from './x-mention-reply.js';
import { createXAdapter } from './gateway/adapters/x.js';
import { guardMention, isPaused } from './x-mention-guard.js';
import { ensureKnownBots, loadKnownBots } from './x-mention-known-bots.js';
import { answerOnBehalf } from './x-mention-on-behalf.js';
import * as xBudget from './x-budget.js';
import { handleAvatar, finishPendingAvatars } from './x-mention-avatar.js';
import { finishPendingMakes } from './x-mention-make.js';
import { handleImage3d, finishPendingImage3d } from './x-mention-image3d.js';
import { composeLaunchReply } from './x-mention-launch.js';
import { selfOrigin } from './self-origin.js';
import { createDeliver } from './x-mention-deliver.js';
import { xBotLive } from './gateway/adapters/x.js';
import { agentMentionAccounts, agentPosterUrl, agentTokenResolver, intentAllowed, tokenResolverForRow } from './x-agent-mentions.js';
export const LOCK_KEY = 'x_mentions_lock';
const DEFAULT_LOCK_SECONDS = 110;
const DEFAULT_MAX_PER_ACCOUNT = 25;
const HOUR = 3600;
const DAY = 86400;
const REFUSED_REPLY = 'I cannot move funds or handle keys, and no one can ask me to. I make 3D models: try "make a red vintage scooter". https://three.ws/grok';
/** Intents whose dedicated handler is a later order; they answer with help until it lands. */
const UNBUILT_HANDLERS = Object.freeze(new Set(['make']));
function intEnv(env, name, fallback) {
const n = Number.parseInt(env[name] ?? '', 10);
return Number.isFinite(n) && n > 0 ? n : fallback;
}
/** Reply limits per author per account, configurable by env. */
export function replyLimits(env = process.env) {
return {
perHour: intEnv(env, 'X_MENTION_REPLIES_PER_AUTHOR_HOUR', 3),
perDay: intEnv(env, 'X_MENTION_REPLIES_PER_AUTHOR_DAY', 10),
};
}
/**
* Take the run lock. Succeeds when no lock row exists or the held one has
* expired. @returns {Promise<string|null>} the holder token, or null when held.
*/
export async function acquireLock(seconds = DEFAULT_LOCK_SECONDS) {
const holder = randomUUID();
const expiresAt = new Date(Date.now() + seconds * 1000).toISOString();
const value = JSON.stringify({ holder, expires_at: expiresAt });
const rows = await sql`
insert into app_settings (key, value) values (${LOCK_KEY}, ${value}::jsonb)
on conflict (key) do update
set value = excluded.value, updated_at = now()
where (app_settings.value->>'expires_at')::timestamptz < now()
returning key
`;
return rows.length ? holder : null;
}
export async function releaseLock(holder) {
await sql`delete from app_settings where key = ${LOCK_KEY} and value->>'holder' = ${holder}`;
}
/** Whether the author already used their reply allowance with this account. */
export async function overReplyLimit(authorId, account, limits, store = mentionStore) {
const hour = await store.countByAuthor(authorId, { windowSeconds: HOUR, decisions: ['reply'], account });
if (hour >= limits.perHour) return 'author_hourly_limit';
const day = await store.countByAuthor(authorId, { windowSeconds: DAY, decisions: ['reply'], account });
if (day >= limits.perDay) return 'author_daily_limit';
return null;
}
/** The text a parsed mention is answered with, or why it is not answered. */
async function composeAnswer({ mention, parsed, account, compose, agent = null, launch = composeLaunchReply }) {
if (parsed.intent === 'help') {
return { text: parsed.args?.topic === 'refused' ? REFUSED_REPLY : FIXED_HELP_REPLY, reason: parsed.reason };
}
if (parsed.intent === 'launch') {
const reply = await launch({ args: parsed.args, authorId: mention.userId || mention.author?.id || null, base: selfOrigin() });
return { text: reply.text, reason: reply.reason };
}
if (UNBUILT_HANDLERS.has(parsed.intent)) {
return { text: FIXED_HELP_REPLY, reason: 'handler_not_built' };
}
const reply = await compose(agent ? { agent, mention } : { company: { handle: account.handle }, mention });
return { text: reply.text, reason: reply.source === 'model' ? parsed.reason : `fallback:${reply.reason}`, provider: reply.provider, model: reply.model };
}
/**
* Handle one new mention end to end. Returns the decision recorded.
* Only ever throws for a store failure on the mention row itself, which the
* caller treats as "not fully recorded" and stops the batch there.
*/
export async function handleMention({ mention, account, limits, env, store = mentionStore, compose = composePublicReply, adapterFactory = createXAdapter, guard = guardMention, paused = isPaused, budget = xBudget, request = null, onBehalf = answerOnBehalf, knownBots = null, avatar = handleAvatar, image3d = handleImage3d, agentCtx = null, posterFor = agentPosterUrl, launch = composeLaunchReply }) {
const parsed = parseMentionIntent(mention, account);
// The company account is always dry run here. An agent answers for real only
// when its owner turned dry run off AND the operator's global switch is on.
const dryRun = agentCtx ? agentCtx.policy.dry_run || !xBotLive(env) : true;
const getAccessToken = agentCtx && !dryRun ? agentTokenResolver({ agentId: agentCtx.agentId, userId: agentCtx.userId }) : null;
const { inserted } = await store.recordMention({ mention, parsed, dryRun });
if (!inserted) return { tweetId: mention.id, decision: 'duplicate', reason: null };
try {
if (await paused(env)) {
await store.updateDecision(mention.id, { decision: 'paused', reason: 'kill_switch' });
return { tweetId: mention.id, intent: parsed.intent, decision: 'paused', reason: 'kill_switch' };
}
if (parsed.intent === 'ignore') {
await store.updateDecision(mention.id, { decision: 'skip', reason: parsed.reason });
return { tweetId: mention.id, intent: 'ignore', decision: 'skip', reason: parsed.reason };
}
const verdict = await guard({ mention, account: mention.account, env, store });
if (!verdict.allow && verdict.reason === 'known_bot' && !agentCtx) {
// A known xAI account tagged us: answer on behalf of the human at the
// root of the conversation, or skip with the reason (x-mention-on-behalf.js).
const allowedBot = await budget.budgetGate({ intent: parsed.intent, env });
if (!allowedBot.allow) {
await store.updateDecision(mention.id, { decision: 'budget', reason: allowedBot.reason });
return { tweetId: mention.id, intent: parsed.intent, decision: 'budget', reason: allowedBot.reason };
}
const answered = await onBehalf({
mention, parsed, account: mention.account, limits, env, store, adapterFactory,
bots: knownBots || (await loadKnownBots({ env })),
request: typeof request === 'function' ? await request() : request,
});
if (answered.decision === 'reply') await budget.recordPosts(1);
return answered;
}
if (!verdict.allow) {
await store.updateDecision(mention.id, { decision: verdict.decision, reason: verdict.reason });
return { tweetId: mention.id, intent: parsed.intent, decision: verdict.decision, reason: verdict.reason };
}
const limited = await overReplyLimit(mention.userId || mention.author?.id, mention.account, limits, store);
if (limited) {
await store.updateDecision(mention.id, { decision: 'rate_limited', reason: limited });
return { tweetId: mention.id, intent: parsed.intent, decision: 'rate_limited', reason: limited };
}
if (agentCtx) {
if (!intentAllowed(agentCtx.policy, parsed.intent)) {
const reason = `intent_not_allowed:${parsed.intent}`;
await store.updateDecision(mention.id, { decision: 'skip', reason });
return { tweetId: mention.id, intent: parsed.intent, decision: 'skip', reason };
}
const sentToday = await store.countAccountReplies(mention.account, { windowSeconds: DAY });
if (sentToday >= agentCtx.policy.daily_cap) {
await store.updateDecision(mention.id, { decision: 'rate_limited', reason: 'agent_daily_cap' });
return { tweetId: mention.id, intent: parsed.intent, decision: 'rate_limited', reason: 'agent_daily_cap' };
}
}
const allowed = await budget.budgetGate({ intent: parsed.intent, env });
if (!allowed.allow) {
await store.updateDecision(mention.id, { decision: 'budget', reason: allowed.reason });
return { tweetId: mention.id, intent: parsed.intent, decision: 'budget', reason: allowed.reason };
}
const lateDeps = getAccessToken ? { deliver: createDeliver({ env, adapterFactory, getAccessToken: () => getAccessToken }) } : undefined;
if (parsed.intent === 'avatar') {
const result = await avatar({ tweetId: mention.id, authorId: mention.userId || mention.author?.id, author: mention.author, dryRun }, lateDeps);
if (result.decision === 'reply') await budget.recordPosts(1);
return { tweetId: mention.id, intent: 'avatar', decision: result.decision, reason: result.reason, text: result.text, dry_run: dryRun };
}
if (parsed.intent === 'image3d') {
const result = await image3d({ tweetId: mention.id, authorId: mention.userId || mention.author?.id, args: parsed.args, dryRun }, lateDeps);
if (result.decision === 'reply') await budget.recordPosts(1);
return { tweetId: mention.id, intent: 'image3d', decision: result.decision, reason: result.reason, text: result.text, dry_run: dryRun };
}
const answer = await composeAnswer({ mention, parsed, account, compose, agent: agentCtx?.agent || null, launch });
const adapter = adapterFactory({ mention, parsed, env, policyDryRun: agentCtx ? dryRun : true, getAccessToken });
const poster = agentCtx && parsed.intent === 'chat' ? await posterFor(agentCtx.agent).catch(() => null) : null;
if (poster) await adapter.sendMedia(mention.id, { url: poster, caption: answer.text });
else await adapter.sendText(mention.id, answer.text);
await budget.recordPosts(1);
await store.updateDecision(mention.id, { reason: answer.reason });
return { tweetId: mention.id, intent: parsed.intent, decision: 'reply', reason: answer.reason, text: answer.text, dry_run: !adapter.live };
} catch (err) {
const message = String(err?.message || err).slice(0, 300);
await store.updateDecision(mention.id, { decision: 'error', reason: err?.code || 'handler_error', error: message });
return { tweetId: mention.id, intent: parsed.intent, decision: 'error', reason: err?.code || 'handler_error', error: message };
}
}
/**
* Poll one account and handle what is new.
* @returns {Promise<{ account: string, status: string, ... }>}
*/
export async function pollAccount({ descriptor, env = process.env, maxMentions = DEFAULT_MAX_PER_ACCOUNT, deps = {} }) {
const store = deps.store || mentionStore;
const fetcher = deps.fetchMentions || fetchMentions;
const limits = replyLimits(env);
const label = `${descriptor.kind}:${descriptor.ref}`;
if (descriptor.missingScopes?.length) return { account: label, status: 'missing_scope', missing: descriptor.missingScopes };
let sinceId;
try {
sinceId = await store.getCursor({ kind: descriptor.kind, ref: descriptor.ref });
} catch (err) {
return { account: label, status: 'error', error: String(err?.message || err).slice(0, 200) };
}
const budget = deps.budget || xBudget;
const gate = await budget.readGate({ env });
if (!gate.allow) return { account: label, status: 'budget', reason: gate.reason, until: gate.until || null };
let page;
try {
page = await fetcher({ account: descriptor.fetch, sinceId, env, request: deps.request || null, resolvedAccount: deps.resolvedAccount || null });
} catch (err) {
if (err instanceof XTierUnavailable) return { account: label, status: 'unavailable', reason: err.reason || 'tier_unavailable' };
if (err instanceof XRateLimited) {
const backoff = budget.backoffFromHeaders({ headers: err.headers, status: 429 });
await budget.setBackoff(backoff || { until: err.resetAt, reason: 'http_429' }).catch(() => {});
return { account: label, status: 'rate_limited', reset_at: err.resetAt };
}
if (err instanceof XAuthFailed) return { account: label, status: 'auth_failed' };
if (err instanceof XMentionsError) return { account: label, status: 'unavailable', reason: err.code };
throw err;
}
await budget.recordReads(page.mentions.length).catch(() => {});
await budget.noteResponse({ headers: page.headers }).catch(() => {});
if (!sinceId) {
if (page.newestId) await store.advanceCursor({ kind: descriptor.kind, ref: descriptor.ref }, page.newestId);
return { account: label, status: 'anchored', cursor: page.newestId };
}
const batch = page.mentions.slice(0, maxMentions);
const resolve = () => (deps.request ? Promise.resolve(deps.request) : resolveAccount(descriptor.fetch, env).then((r) => r.request));
if (batch.length) {
await (deps.ensureKnownBots || ensureKnownBots)({ env, request: async (...a) => (await resolve())(...a) }).catch(() => {});
}
const decisions = [];
let lastRecorded = null;
let stoppedAt = null;
for (const mention of batch) {
try {
decisions.push(await handleMention({ mention, account: page.account, limits, env, store, compose: deps.compose, adapterFactory: deps.adapterFactory, guard: deps.guard, paused: deps.paused, budget: deps.budget, request: resolve, onBehalf: deps.onBehalf, knownBots: deps.knownBots, avatar: deps.avatar, image3d: deps.image3d, agentCtx: descriptor.agentCtx || null, posterFor: deps.posterFor }));
lastRecorded = mention.id;
} catch (err) {
stoppedAt = mention.id;
console.error('[x-mentions] stopped before an unrecorded mention', mention.id, err?.message || err);
break;
}
}
if (lastRecorded) await store.advanceCursor({ kind: descriptor.kind, ref: descriptor.ref }, lastRecorded);
return {
account: label,
status: stoppedAt ? 'partial' : 'ok',
read: page.mentions.length,
handled: decisions.filter((d) => d.decision !== 'duplicate').length,
deferred: page.mentions.length - batch.length,
cursor: lastRecorded || sinceId,
decisions,
};
}
/**
* Accounts to poll: the company account when its credentials are present,
* then each agent account with mention replies enabled (`agentAccounts`,
* x-agent-mentions.js, from agent_x_policies and agent_x_connections).
*/
export async function listAccounts({ env = process.env, agentAccounts = agentMentionAccounts } = {}) {
const accounts = [];
if (companyMentionsConfigured(env)) {
accounts.push({ kind: 'company', ref: env.X_COMPANY_HANDLE || 'trythreews', fetch: { kind: 'company' } });
}
// A failing agent lookup must never stop the company account from being polled.
const agentRows = await agentAccounts().catch((err) => {
console.error('[x-mentions] agent account lookup failed', err?.message || err);
return [];
});
for (const a of agentRows) {
accounts.push({
kind: 'agent', ref: String(a.agentId), fetch: { kind: 'agent', agentId: a.agentId, userId: a.userId },
agentCtx: { agentId: String(a.agentId), userId: String(a.userId), agent: a.agent, policy: a.policy }, missingScopes: a.missingScopes || [],
});
}
return accounts;
}
/**
* Settle the make, avatar and image-to-3D jobs that outlived their mention. Gated like any
* other reply (kill switch, then the post budget), each finisher isolated so
* one failing never stops the others or the tick. Delivery goes through the X
* adapter: dry rows are recorded, live rows are posted.
*/
export async function runFollowUps({ env = process.env, deps = {} } = {}) {
const budget = deps.budget || xBudget;
if (await (deps.paused || isPaused)(env)) return { followUps: { skipped: 'kill_switch' } };
const gate = await budget.readGate({ env }).catch(() => ({ allow: true }));
if (!gate.allow) return { followUps: { skipped: 'budget', reason: gate.reason } };
const baseDeliver = deps.deliver || createDeliver({ env, adapterFactory: deps.adapterFactory, getAccessToken: deps.getAccessToken || tokenResolverForRow });
const deliver = async (args) => {
const id = await baseDeliver(args);
if (id) await budget.recordPosts(1).catch(() => {});
return id;
};
const run = (fn) => fn({}, { deliver }).catch((err) => ({ error: String(err?.message || err).slice(0, 200) }));
return {
makeFollowUp: await run(deps.finishPendingMakes || finishPendingMakes),
avatarFollowUp: await run(deps.finishPendingAvatars || finishPendingAvatars),
image3dFollowUp: await run(deps.finishPendingImage3d || finishPendingImage3d),
};
}
/** One cron tick: lock, poll every account, release. Never throws for X outages. */
export async function runMentionTick({ env = process.env, deps = {} } = {}) {
const holder = await (deps.acquireLock || acquireLock)(intEnv(env, 'X_MENTION_LOCK_SECONDS', DEFAULT_LOCK_SECONDS));
if (!holder) return { ok: true, skipped: 'locked' };
const report = { ok: true, accounts: [] };
try {
const accounts = await (deps.listAccounts || listAccounts)({ env, agentAccounts: deps.agentAccounts });
if (!accounts.length) return { ok: true, skipped: 'no_accounts_configured' };
for (const descriptor of accounts) {
try {
report.accounts.push(await pollAccount({ descriptor, env, deps }));
} catch (err) {
report.accounts.push({ account: `${descriptor.kind}:${descriptor.ref}`, status: 'error', error: String(err?.message || err).slice(0, 200) });
}
}
Object.assign(report, await runFollowUps({ env, deps }));
return report;
} finally {
await (deps.releaseLock || releaseLock)(holder).catch(() => {});
}
}