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 chat gateway core: one platform-neutral handler for every inbound chat
// event, driven by a platform adapter (workers/agent-gateway/src/telegram.js,
// workers/agent-gateway/src/discord.js).
//
// An adapter turns platform updates into events and implements the Gateway
// interface below; everything else (pairing, commands, conversation, previews,
// approvals) lives here, so Telegram and Discord behave identically.
//
// @typedef {object} GatewayEvent
// @property {'telegram'|'discord'} platform
// @property {string} chatId the chat, DM channel or guild channel
// @property {string} [chatType] private | group | supergroup | dm | guild
// @property {string} [chatTitle]
// @property {string} userId the platform user who sent it
// @property {string} [username]
// @property {string} [text] a plain message
// @property {string} [command] a slash command, lowercased, without the slash
// @property {string} [args] everything after the command
// @property {{ verb:'approve'|'cancel', previewId:string }} [action] a button press
// @property {{ verb:'approve'|'deny', approvalId:string, exp:number, mac:string }} [approvalAction]
// a signed Approve/Deny press on an approval request
// @property {boolean} [forwarded] the message was forwarded, or posted through
// another bot: someone else's words, never an instruction
// @property {{ fetch:() => Promise<{buffer:Buffer, mimeType:string}> }} [voice]
// @property {{ fetch:() => Promise<{buffer:Buffer, mimeType:string}>, caption?:string }} [photo]
// @property {object} [messageRef] the pressed message, for button events
//
// @typedef {object} Gateway
// @property {'telegram'|'discord'} platform
// @property {(chatId:string, text:string) => Promise<object>} sendText returns a message ref
// @property {(chatId:string, text:string, choices:{id:string,label:string,style?:string}[]) => Promise<object>} sendChoice
// @property {(ref:object, text:string, opts?:{choices?:object[]}) => Promise<void>} editMessage choices [] removes buttons
// @property {(chatId:string, media:{url:string, caption?:string}) => Promise<object>} sendMedia
// @property {(chatId:string) => Promise<void>} typing
// @property {(event:GatewayEvent, text?:string) => Promise<void>} ackAction answer a button press
import { limits } from '../rate-limit.js';
import { getLiveLink, touchLink, issueChatCode, redeemSiteCode, createLink, GatewayError } from './store.js';
import { normalizePairCode, formatPairCode } from './codes.js';
import { COMMAND_HANDLERS, helpText } from './commands.js';
import { converse } from './conversation.js';
import { handlePendingConfirmation, handleTradeText } from './trade-commands.js';
import { handleAction } from './approvals.js';
import { handleApprovalPress } from './approval-buttons.js';
import { transcribeVoice, describePhoto, MediaError } from './media.js';
import { appOrigin } from './format.js';
import { sql } from '../db.js';
import { logAudit } from '../audit.js';
import { claimLinkCode, LinkCodeError } from '../account-link/link-codes.js';
import { claimMagicToken, isMagicToken } from '../account-link/telegram-login.js';
function identityOf(event) {
return {
platform: event.platform,
platformUserId: String(event.userId),
platformUsername: event.username || null,
chatId: String(event.chatId),
chatType: event.chatType || null,
chatTitle: event.chatTitle || null,
};
}
async function pairingPrompt(gw, event) {
const rl = await limits.gatewayPair(`${event.platform}:${event.chatId}`);
if (!rl.success) return gw.sendText(event.chatId, 'Too many pairing codes for this chat. Wait an hour, or generate a code on the site and send /link <code> here.');
const { code, expiresInMinutes } = await issueChatCode(identityOf(event));
const pretty = formatPairCode(code);
return gw.sendText(event.chatId, [
'Connect this chat to your three.ws agent.',
'',
`Your pairing code: ${pretty}`,
`Open ${appOrigin()}/settings/connections?code=${code}`,
`sign in, and confirm. The code expires in ${expiresInMinutes} minutes.`,
'',
`Already on the site? Generate a code there and send /link <code> here instead.`,
].join('\n'));
}
// A sign-in magic link that reached the worker (the webhook claims these
// inline; a worker that polls Telegram directly lands here instead).
async function cmdMagic({ gw, event }) {
const result = await claimMagicToken({
token: String(event.args || '').trim(),
from: { id: event.userId, username: event.username, first_name: event.firstName || event.username || null },
chat: { id: event.chatId, type: event.chatType || 'private', title: event.chatTitle || null },
});
if (result.ok) return gw.sendText(event.chatId, result.intent === 'link' ? 'Got it. Go back to three.ws: your Telegram account is being linked there now.' : 'Got it. Go back to three.ws: you are being signed in there now.');
const why = {
group: 'Sign-in links only work in a private chat with me.',
expired: 'That sign-in link has expired or was already used. Go back to three.ws and start again.',
in_use: 'This Telegram account already signs in to a different three.ws account.',
};
return gw.sendText(event.chatId, why[result.reason] || 'That is not a sign-in link I recognise. Go back to three.ws and start again.');
}
// A code minted on /dashboard/account for a Telegram chat (link codes,
// api/_lib/account-link/link-codes.js) is claimed here with this chat's
// identity; the person then confirms on the site, where they see exactly
// which chat is asking, and the pairing is created on that confirmation.
async function claimAccountLinkCode({ gw, event, code }) {
try {
const claimed = await claimLinkCode({
code,
expectKind: 'telegram',
claim: {
name: event.chatTitle || (event.username ? `@${event.username}` : 'Telegram chat'),
platform: 'telegram',
telegram: {
chat_id: String(event.chatId),
platform_user_id: String(event.userId),
username: event.username || null,
chat_type: event.chatType || 'private',
chat_title: event.chatTitle || null,
},
},
});
return gw.sendText(event.chatId, `Code received. Confirm it on three.ws (${appOrigin()}/dashboard/account#linked-devices) to pair this chat. The request expires at ${new Date(claimed.expires_at).toUTCString()}.`);
} catch (e) {
if (e instanceof LinkCodeError) {
if (e.code === 'unknown_code' || e.code === 'wrong_kind') return null;
return gw.sendText(event.chatId, e.message);
}
throw e;
}
}
async function cmdLink({ gw, event, link }) {
if (isMagicToken(String(event.args || '').trim())) return cmdMagic({ gw, event });
const code = normalizePairCode(event.args);
if (!code) {
if (link) return gw.sendText(event.chatId, `This chat is already paired. Send /help to see what you can do, or /unlink to disconnect.`);
return pairingPrompt(gw, event);
}
// Site-minted pairing codes and account link codes share one alphabet, so
// the account link table is tried first and a miss falls through.
const accountLinked = await claimAccountLinkCode({ gw, event, code });
if (accountLinked) return accountLinked;
try {
await redeemSiteCode({ code, identity: identityOf(event) });
} catch (e) {
if (e instanceof GatewayError) return gw.sendText(event.chatId, e.message);
throw e;
}
return gw.sendText(event.chatId, `Paired. This chat now talks to your three.ws account.\n\n${helpText()}`);
}
// A private chat from a Telegram account that signs in to three.ws resolves
// to that account without a pairing code: signing in with Telegram already
// proved the person controls it. Groups still pair explicitly, because a
// group is shared and the pairing names which account it serves.
async function resolveLinkedIdentity(event) {
if (event.platform !== 'telegram' || (event.chatType && event.chatType !== 'private')) return null;
const [identity] = await sql`
select u.id as user_id from user_identities i join users u on u.id = i.user_id
where i.provider = 'telegram' and i.subject = ${String(event.userId)} and u.deleted_at is null limit 1
`;
if (!identity) return null;
try {
const link = await createLink({ ...identityOf(event), userId: identity.user_id });
logAudit({ userId: identity.user_id, action: 'link_chat_telegram', resourceId: link.id, meta: { chat_id: String(event.chatId), via: 'telegram_identity' } });
return link;
} catch (e) {
if (e instanceof GatewayError) return null;
throw e;
}
}
async function textFromMedia(gw, event) {
try {
if (event.voice) {
const { buffer, mimeType } = await event.voice.fetch();
const heard = await transcribeVoice({ buffer, mimeType });
await gw.sendText(event.chatId, `Heard: "${heard}"`);
return heard;
}
const { buffer, mimeType } = await event.photo.fetch();
return await describePhoto({ buffer, mimeType, caption: event.photo.caption || '' });
} catch (e) {
if (e instanceof MediaError) {
await gw.sendText(event.chatId, e.message);
return null;
}
console.error('[gateway] media failed', e?.code || e?.message);
await gw.sendText(event.chatId, event.voice
? 'I could not transcribe that voice note. Try again, or type it.'
: 'I could not read that photo. Try again, or describe it in text.');
return null;
}
}
/**
* Handle one inbound chat event end to end.
* @param {GatewayEvent} event
* @param {Gateway} gw
*/
export async function handleEvent(event, gw) {
const link = (await getLiveLink(event.platform, event.chatId)) || (await resolveLinkedIdentity(event));
if (event.approvalAction) return handleApprovalPress({ gw, event, link });
if (event.action) return handleAction({ gw, event, link });
// A forwarded message carries another person's words. Running it as a
// command (a forwarded /link would pair this chat to someone else's
// account), or handing it to the agent as the owner's request, would let
// anyone who gets a message in front of the owner steer their agent.
if (event.forwarded) {
if (!link || String(event.userId) !== String(link.platform_user_id)) return;
return gw.sendText(event.chatId, 'Forwarded messages are never treated as instructions, so your agent did not act on that. Type the request yourself if you want it done.');
}
if (event.command === 'start' || event.command === 'link') return cmdLink({ gw, event, link });
if (event.command === 'help') return gw.sendText(event.chatId, link ? helpText() : `${helpText()}\n\nThis chat is not paired yet: send /start to get a pairing code.`);
if (!link) return pairingPrompt(gw, event);
// A paired group chat still belongs to one person: everyone else is told so,
// and never reaches the owner's agent or wallet.
if (String(event.userId) !== String(link.platform_user_id)) {
return gw.sendText(event.chatId, 'This chat is paired to another person\'s three.ws account. Only they can talk to the agent here.');
}
const rl = await limits.gatewayMessage(link.id);
if (!rl.success) return gw.sendText(event.chatId, 'You are sending messages faster than your agent can answer. Wait a minute and try again.');
await touchLink(link.id);
// A trade waiting for its typed yes sees this message first: the exact word
// executes it, anything else cancels it.
if (await handlePendingConfirmation({ gw, event, link })) return;
if (event.command) {
const run = COMMAND_HANDLERS[event.command];
if (run) return run({ gw, event, link });
return gw.sendText(event.chatId, `Unknown command /${event.command}. Send /help for the list.`);
}
if (!event.voice && !event.photo && (await handleTradeText({ gw, event, link }))) return;
const text = event.voice || event.photo ? await textFromMedia(gw, event) : String(event.text || '').trim();
if (!text) return;
return converse({ gw, event, link, text });
}