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
// @ts-check
// Turn one X mention into exactly one intent, deterministically, before any
// model sees it.
//
// PURE: no network, no database, no clock, no randomness. The only import is
// the /launch page's own pure form rules, so a launch link this parser
// prefills is held to the same name and ticker limits the page enforces.
// tests/x-mention-intents.test.js asserts the import graph stays that way.
//
// Mention text is untrusted (x-grok design rule 1). This module only ever
// reads it, cuts it down, and labels it; nothing it returns performs an
// action. The strongest thing an intent can lead to is one reply to the same
// author: a 3D generation shown back to them, a help text, a prefilled
// /launch link they review and sign themselves on three.ws, or a short
// tool-less chat reply. Text that asks for money to move or for secrets is
// answered with `help`, so it never reaches a model at all.
//
// Input: a normalized mention from x-mentions.js plus our account
// ({ handle, userId, kind }; defaults to mention.account).
// Output: { intent, args, reason }
// intent make | image3d | avatar | help | launch | chat | ignore
// args intent-specific fields plus `normalization` (what was dropped),
// `flags` (which hostile phrasing was refused) and `addressing`
// reason a short machine-readable why, recorded on x_mention_events
import { NAME_MAX, SYMBOL_MAX, DESCRIPTION_MAX, normalizeSymbol } from '../../src/launch/launch-model.js';
export const INTENTS = Object.freeze(['make', 'image3d', 'avatar', 'help', 'launch', 'chat', 'ignore']);
// Caps. A post can be 25,000 characters (note_tweet); nothing downstream
// needs more than these, and the scan itself is bounded first.
export const SCAN_MAX = 4000;
export const PROMPT_MAX = 400;
export const CHAT_MAX = 500;
export const PROMPT_MIN_LETTERS = 2;
// Tickers nobody may launch through the bot: the platform's own coin.
const RESERVED_TICKERS = new Set(['THREE']);
const HANDLE_RE = /@([A-Za-z0-9_]{1,15})\b/g;
const LEADING_HANDLES_RE = /^(?:@[A-Za-z0-9_]{1,15}[\s,:;.!-]*)+/;
const URL_RE = /\b(?:https?:\/\/|www\.)[^\s]+|\b(?:pic\.(?:x|twitter)\.com|t\.co)\/[^\s]+/gi;
// Invisible and direction-changing characters: zero-width, bidi overrides,
// isolates, the BOM, soft hyphen, and the C0/C1 controls except newline/tab.
const INVISIBLE_RE = /[\u00AD\u200B-\u200F\u202A-\u202E\u2060-\u2069\uFEFF\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
// Phrasing that asks for funds to move or for secrets. Matched on the whole
// addressed text; a hit turns any intent into `help`.
const MONEY_VERBS = 'send|transfer|withdraw|pay|tip|airdrop|drain|bridge|swap|sweep|buy|sell|ape|stake|unstake';
// The objects are generic on purpose (funds, tokens, an amount with a unit, a
// cashtag), so the refusal never depends on knowing a particular coin.
const MONEY_OBJECTS = 'funds?|tokens?|coins?|wallets?|balance|lamports|money|crypto|nfts?|treasury|sol|usdc|\\d+(?:[.,]\\d+)?\\s*[a-z]{2,6}';
const ACTION_RE = new RegExp(`\\b(?:${MONEY_VERBS})\\b[^.!?\\n]{0,48}?(?:\\b(?:${MONEY_OBJECTS})\\b|\\$[a-z][a-z0-9]{1,9}\\b)`, 'i');
const SIGN_RE = /\b(?:sign|approve|confirm|authori[sz]e)\b[^.!?\n]{0,32}\b(?:transactions?|txn?s?|transfers?|withdrawals?|payments?|swaps?)\b/i;
const SECRET_RE = /\b(?:private\s*key|secret\s*key|seed\s*phrase|recovery\s*phrase|mnemonic|api[\s_-]*key|password|passphrase|keypair)\b/i;
// Instruction-override phrasing ("ignore previous instructions", "you are now
// ..."). Refused like the two above: a request that opens by trying to
// rewrite the bot's rules gets the help text, not a model.
const OVERRIDE_RE = /\b(?:ignore|disregard|forget|override|bypass)\b[^.!?\n]{0,32}\b(?:instructions?|prompts?|rules?|system|guidelines?|polic(?:y|ies)|previous|above|prior)\b|\b(?:system\s*prompt|jailbreak|developer\s*mode|you\s+are\s+now|act\s+as|pretend\s+(?:to\s+be|you))\b/i;
const POLITE_RE = /^(?:(?:please|pls|plz|pretty\s+please|hey|hi|hello|yo|gm|ok|okay|so|now|can\s+you|could\s+you|would\s+you|will\s+you|could\s+u|can\s+u|i\s+want\s+you\s+to|i'?d\s+like\s+you\s+to|i\s+want|i\s+need|go\s+ahead\s+and)[\s,:!.-]+)+/i;
const HELP_RE = /^(?:help|commands?|menu|usage|how\s+(?:does\s+(?:this|it)\s+work|do\s+i\s+use\s+(?:this|you|it))|what\s+(?:can|do)\s+you\s+do|what\s+are\s+you|info|\?+)(?:[\s?!.]|$)/i;
const AVATAR_RE = /^(?:(?:make|create|generate|build|give|turn)\s+(?:me\s+(?:into\s+)?(?:an?\s+)?|my\s+)(?:3d\s+|rigged\s+)?(?:avatar|character)\b|avatar\s+me\b|me\s+as\s+an?\s+(?:3d\s+)?avatar\b)/i;
// "3d my pfp", "turn my profile picture into 3d": the author's own picture.
const AVATAR_PFP_RE = /\b(?:3d|3-d|make|turn|convert)\b.{0,24}\bmy\s+(?:pfp|profile\s+(?:pic(?:ture)?|photo|image))\b|\bmy\s+(?:pfp|profile\s+(?:pic(?:ture)?|photo|image))\b.{0,24}\b(?:3d|3-d|avatar)\b/i;
// A 3D request that points at an image rather than describing an object.
const IMAGE3D_RE = /\b(?:3d|3-d|three[\s-]?d)\s+(?:this|it|that|these|pls|please|me\s+this)\b|\b(?:make|turn|render)\s+(?:this|it|that)\s+(?:3d|3-d|three[\s-]?d)\b|\b(?:this|it|that)\s+(?:in|into|to|as)\s+(?:a\s+)?(?:3d|3-d|three[\s-]?d)\b|\b(?:make|turn|convert|render)\s+(?:this|it|that)(?:\s+(?:in|into|to)\s+(?:a\s+)?(?:3d|3-d|three[\s-]?d))?(?:\s+(?:pls|please))?\s*[.!]*$|\b(?:make|turn|convert)\s+(?:this|it|that|my\s+\S+|the\s+\S+)\s+(?:in|into|to)\s+(?:a\s+)?(?:3d|3-d|three[\s-]?d)/i;
const HAS_3D_RE = /\b(?:3d|3-d|three[\s-]?d)\b/i;
// make, 3d, forge, generate, model, followed by a description. A few verbs
// from the languages our audience posts in most, so a Spanish or Portuguese
// request is a request and not chat.
const MAKE_RE = /^(?:make|3d|forge|generate|gen|model|create|build|render|sculpt|haz|hazme|crea|cr[eé]ame|genera|fais|fait|cr[eé]e|g[eé]n[eè]re|fa[cç]a|faz|cria|gere|mach|erstelle|generiere|baue?)\b[\s:,-]*(?<rest>.*)$/is;
const MAKE_LEAD_RE = /^(?:(?:me|us|for\s+me)\s+)?(?:(?:(?:a|an|the)\s+)?(?:(?:3d|3-d|three[\s-]?d)\s+)?(?:model|mesh|version|object|asset|render)\s+of\s+)?/i;
const LAUNCH_RE = /^launch\b(?<rest>.*)$/is;
const LAUNCH_GRAMMAR_RE = /^\s*(?<name>[^$\n]{1,64}?)\s+\$(?<ticker>[A-Za-z0-9]{1,16})\b(?<desc>[\s\S]*)$/;
/**
* Normalize untrusted text: Unicode NFKC (folds full-width @ and letters),
* invisible and bidi characters removed, whitespace collapsed. Records what
* changed. PURE.
*/
export function normalizeText(raw) {
let text = String(raw ?? '');
const record = { scanTruncated: false, nfkcChanged: false, invisibleRemoved: 0 };
if (text.length > SCAN_MAX) {
text = text.slice(0, SCAN_MAX);
record.scanTruncated = true;
}
const folded = text.normalize('NFKC');
if (folded !== text) record.nfkcChanged = true;
text = folded;
text = text.replace(INVISIBLE_RE, () => {
record.invisibleRemoved += 1;
return '';
});
text = text.replace(/[ \t\r\f\v]+/g, ' ').replace(/\s*\n\s*/g, '\n').trim();
return { text, record };
}
/** Split a post into its leading reply handles and the body after them. PURE. */
export function splitLeadingHandles(text) {
const m = LEADING_HANDLES_RE.exec(text);
if (!m) return { prefix: [], body: text };
const prefix = [...m[0].matchAll(HANDLE_RE)].map((h) => h[1]);
return { prefix, body: text.slice(m[0].length).trim() };
}
function handlesIn(text) {
return [...String(text || '').matchAll(HANDLE_RE)].map((h) => h[1]);
}
const eqHandle = (a, b) => !!a && !!b && String(a).toLowerCase() === String(b).toLowerCase();
/**
* Remove URLs and @handles from free text that will be shown back or sent to
* a generator, cap it, and record every drop. PURE.
*/
export function sanitizeArg(text, max, record) {
let out = String(text || '');
out = out.replace(URL_RE, (u) => {
record.droppedUrls.push(u);
return ' ';
});
out = out.replace(HANDLE_RE, (h) => {
record.droppedHandles.push(h.slice(1));
return ' ';
});
out = out.replace(/\s+/g, ' ').trim();
if ([...out].length > max) {
const chars = [...out];
record.truncated.push({ from: chars.length, to: max });
out = chars.slice(0, max).join('').trim();
}
return out;
}
function letters(text) {
return (String(text).match(/\p{L}|\p{N}/gu) || []).length;
}
function firstPhoto(media) {
return (Array.isArray(media) ? media : []).find((m) => m && m.type === 'photo' && m.url) || null;
}
function imageSource(mention) {
const own = firstPhoto(mention.media);
if (own) return { source: 'mention', post: mention, media: own, authorId: mention.userId || mention.author?.id || null };
for (const [source, ref] of [['replied_to', mention.repliedTo], ['quoted', mention.quoted]]) {
if (!ref?.available) continue;
const m = firstPhoto(ref.media);
if (m) return { source, post: ref, media: m, authorId: ref.author?.id || null };
}
return null;
}
/**
* How the post reaches us. `direct` when our handle is typed in the body, when
* it leads a fresh post, when the post replies to us, or when it leads a reply
* to someone whose post never named us (a deliberate tag, the way people call
* @grok under someone else's post). `inherited` when it only rides along in
* the reply handles of a thread we were already tagged in. `absent` when it
* only appears inside a quoted or replied-to post. PURE.
*/
export function addressing(mention, account, prefix, body) {
const handle = account.handle;
const inBody = handlesIn(body).some((h) => eqHandle(h, handle));
const inPrefix = prefix.some((h) => eqHandle(h, handle));
if (inBody) return 'direct';
if (!inPrefix) return 'absent';
const parent = mention.repliedTo || null;
const isReply = !!(parent || mention.inReplyToUserId);
if (!isReply) return 'direct';
const repliesToUs = (account.userId && (String(mention.inReplyToUserId || '') === String(account.userId) || String(parent?.author?.id || '') === String(account.userId)))
|| eqHandle(parent?.author?.username, handle);
if (repliesToUs) return 'direct';
if (!parent?.available) return 'inherited';
const parentNamesUs = handlesIn(normalizeText(parent.text).text).some((h) => eqHandle(h, handle));
return parentNamesUs ? 'inherited' : 'direct';
}
function newRecord(base) {
return { ...base, droppedHandles: [], droppedUrls: [], truncated: [] };
}
function hostileFlags(text) {
const flags = [];
if (ACTION_RE.test(text) || SIGN_RE.test(text)) flags.push('money_action');
if (SECRET_RE.test(text)) flags.push('secret_request');
if (OVERRIDE_RE.test(text)) flags.push('instruction_override');
return flags;
}
const out = (intent, args, reason) => ({ intent, args, reason });
/**
* The launch grammar (order 925): `launch <NAME> $<TICKER> [description]`.
* The bot never launches; this only fills a /launch link the author reviews
* and signs on three.ws. PURE.
* @returns {{ ok: true, name: string, symbol: string, description: string } | { ok: false, reason: string }}
*/
export function parseLaunch(rest, record) {
const m = LAUNCH_GRAMMAR_RE.exec(String(rest || ''));
if (!m?.groups) return { ok: false, reason: 'launch_malformed' };
const name = sanitizeArg(m.groups.name.replace(/^[\s:,-]+/, ''), NAME_MAX + 1, record);
if (!name || letters(name) < 1) return { ok: false, reason: 'launch_missing_name' };
if ([...name].length > NAME_MAX) return { ok: false, reason: 'launch_name_too_long' };
const raw = m.groups.ticker;
const symbol = normalizeSymbol(raw);
if (raw.length > SYMBOL_MAX || symbol.length < 2) return { ok: false, reason: 'launch_bad_ticker' };
if (RESERVED_TICKERS.has(symbol)) return { ok: false, reason: 'launch_reserved_ticker' };
const description = sanitizeArg(m.groups.desc.replace(/^[\s:,-]+/, ''), DESCRIPTION_MAX, record);
return { ok: true, name, symbol, description };
}
/**
* Parse one normalized mention into one intent.
*
* @param {any} mention a mention from x-mentions.js normalizeMentions
* @param {{ handle?: string, userId?: string|null, kind?: 'company'|'agent' }} [accountIn]
* @returns {{ intent: string, args: Record<string, any>, reason: string }}
*/
export function parseMentionIntent(mention, accountIn = {}) {
const account = {
handle: String(accountIn.handle || mention?.account?.handle || mention?.account?.ref || '').replace(/^@/, ''),
userId: accountIn.userId ?? mention?.account?.userId ?? null,
kind: accountIn.kind || mention?.account?.kind || 'company',
};
if (!mention || typeof mention !== 'object' || !account.handle) return out('ignore', {}, 'malformed');
// Our own posts and retweets are never requests.
const authorId = mention.userId || mention.author?.id || null;
if (mention.fromSelf || (account.userId && authorId && String(authorId) === String(account.userId)) || eqHandle(mention.username || mention.author?.username, account.handle)) {
return out('ignore', {}, 'own_post');
}
if (mention.isRetweet || /^RT @/.test(String(mention.text || ''))) return out('ignore', {}, 'retweet');
const { text, record: base } = normalizeText(mention.text);
const record = newRecord(base);
const { prefix, body } = splitLeadingHandles(text);
record.droppedHandles.push(...prefix);
const how = addressing(mention, account, prefix, body);
if (how === 'absent') return out('ignore', { normalization: record }, 'not_addressed');
// Our own handle typed inside the body is the address, not content.
const ownHandleRe = new RegExp(`@${account.handle.replace(/[^A-Za-z0-9_]/g, '')}\\b[\\s,:;.!-]*`, 'gi');
const addressed = body.replace(ownHandleRe, () => {
record.droppedHandles.push(account.handle);
return ' ';
}).replace(/\s+/g, ' ').trim();
const command = addressed.replace(POLITE_RE, '').trim();
const flags = hostileFlags(addressed);
const withMeta = (args) => ({ ...args, normalization: record, flags, addressing: how });
// Money movement, secrets, or an attempt to rewrite the bot's rules: the
// help text when addressed to us, silence when it only rides along in a
// thread. Never parsed further, never handed to a model.
if (flags.length) {
if (how !== 'direct') return out('ignore', withMeta({}), 'inherited_thread_mention');
return out('help', withMeta({ topic: 'refused' }), `refused_${flags[0]}`);
}
// A bare tag, or a tag plus only links (X appends a t.co link for every
// attached photo), carries no words to parse.
if (!command.replace(URL_RE, ' ').trim()) {
const img = imageSource(mention);
if (how === 'direct' && img?.source === 'mention') return out('image3d', withMeta(image3dArgs(img, '', record)), 'image_only');
return how === 'direct' ? out('help', withMeta({ topic: 'empty' }), 'empty_mention') : out('ignore', withMeta({}), 'inherited_thread_mention');
}
if (HELP_RE.test(command)) return out('help', withMeta({ topic: 'general' }), 'command:help');
const launch = LAUNCH_RE.exec(command);
if (launch?.groups) {
const parsed = parseLaunch(launch.groups.rest, record);
if (!parsed.ok) return out('help', withMeta({ topic: 'launch' }), parsed.reason);
return out('launch', withMeta({ name: parsed.name, symbol: parsed.symbol, description: parsed.description }), 'command:launch');
}
if (AVATAR_RE.test(command) || AVATAR_PFP_RE.test(command)) {
return out('avatar', withMeta({ authorId, authorUsername: mention.username || mention.author?.username || null }), 'command:avatar');
}
const img = imageSource(mention);
const points3d = IMAGE3D_RE.test(command);
if (img && (points3d || (img.source === 'mention' && (HAS_3D_RE.test(command) || MAKE_RE.test(command))))) {
return out('image3d', withMeta(image3dArgs(img, command, record)), 'command:image3d');
}
if (points3d) return out('help', withMeta({ topic: 'image3d' }), 'image3d_without_image');
const make = MAKE_RE.exec(command);
if (make?.groups) {
const described = make.groups.rest.replace(MAKE_LEAD_RE, '');
const prompt = sanitizeArg(described, PROMPT_MAX, record);
if (letters(prompt) >= PROMPT_MIN_LETTERS) return out('make', withMeta({ prompt }), 'command:make');
return out('help', withMeta({ topic: 'make' }), 'make_without_description');
}
if (how !== 'direct') return out('ignore', withMeta({}), 'inherited_thread_mention');
const chat = sanitizeArg(command, CHAT_MAX, record);
if (letters(chat) < 1) return out('help', withMeta({ topic: 'empty' }), 'empty_mention');
return out('chat', withMeta({ text: chat }), account.kind === 'agent' ? 'agent_chat' : 'company_chat');
}
function image3dArgs(img, command, record) {
return {
source: img.source,
sourcePostId: img.post?.id ? String(img.post.id) : null,
sourceAuthorId: img.authorId ? String(img.authorId) : null,
mediaKey: img.media.key || null,
mediaUrl: img.media.url,
width: img.media.width ?? null,
height: img.media.height ?? null,
hint: sanitizeArg(command.replace(IMAGE3D_RE, ' '), PROMPT_MAX, record),
};
}