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.

11.6 KB
Raw Blame
// 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 });
}