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.

7.3 KB
Raw Blame
// One chat message -> one copilot turn, delivered back to the chat.
//
// The turn is the same one the web copilot runs (api/_lib/copilot-engine.js)
// over the agent's cross-channel thread (api/_lib/agent-thread.js), so a
// conversation started on the web continues here and the other way round. While
// the agent works, the chat shows a typing indicator and one compact status
// line ("working: get_quote") edited in place, on platforms that can edit a
// message (SMS, Signal and email cannot, so they get neither). Every trade or
// limit change the agent proposes becomes a preview with Approve and Cancel
// buttons, or on a channel without buttons a single-use reply code
// (./reply-codes.js); nothing in the reply text can execute one. When the
// owner turned on voice replies for the chat, the reply is also spoken
// (./voice.js).

import { runCopilotTurn } from '../copilot-engine.js';
import { resolveAgentBrain } from '../agent-brain.js';
import { appendThreadMessage, threadHistoryForModel } from '../agent-thread.js';
import { resolveChatAgent, listAccountAgents } from './agents.js';
import { createPreview, setPreviewMessageRef, PREVIEW_TTL_MINUTES } from './store.js';
import { chunkText, describeProposal, plainText, MAX_TEXT, PLATFORM_LABEL, appOrigin } from './format.js';
import { maybeSpeakReply } from './voice.js';

export const APPROVE = 'gw:ap:';
export const CANCEL = 'gw:cx:';
const TYPING_EVERY_MS = 4500;

/** Whether a gateway renders buttons (true unless it says otherwise). */
export function hasButtons(gw) {
	return gw.buttons !== false;
}

function surfaceNote(platform, { buttons = true } = {}) {
	const where = PLATFORM_LABEL[platform] || platform;
	const approval = buttons
		? 'Every propose_* card you surface reaches the owner as a preview message with Approve and Cancel buttons. Tell them to press Approve to execute it or Cancel to discard it, and that it expires in ten minutes. Never claim a trade happened.'
		: 'Every propose_* card you surface reaches the owner as a preview message ending with a six-digit code. Tell them to reply APPROVE and that code to execute it, or CANCEL and the code to discard it, and that it expires in ten minutes. Never claim a trade happened.';
	const brevity = platform === 'sms' ? ' This is SMS: answer in two or three short sentences.' : ' Keep it short.';
	return [
		`SURFACE: you are replying in a ${where} chat with your owner. Write plain text: no tables, no headings, no code blocks.${brevity}`,
		approval,
	].join('\n');
}

/** Keep the platform's typing indicator alive until stop() is called. */
function keepTyping(gw, chatId) {
	if (typeof gw.typing !== 'function') return () => {};
	let stopped = false;
	const tick = () => { if (!stopped) Promise.resolve(gw.typing(chatId)).catch(() => {}); };
	tick();
	const timer = setInterval(tick, TYPING_EVERY_MS);
	return () => { stopped = true; clearInterval(timer); };
}

/**
 * The status line: sent on the first tool call, edited on every one after, and
 * left behind as a compact record of what the agent looked at.
 */
function statusLine(gw, chatId) {
	// A channel that cannot edit would get one new message per tool call; on
	// SMS that is a bill, so those channels skip the status line entirely.
	if (gw.canEdit === false) return { working() {}, async finish() {} };
	let ref = null;
	let chain = Promise.resolve();
	const used = [];
	const put = (text) => {
		chain = chain.then(async () => {
			if (ref) await gw.editMessage(ref, text);
			else ref = await gw.sendText(chatId, text);
		}).catch(() => {});
	};
	return {
		working(name) {
			if (!used.includes(name)) used.push(name);
			put(`working: ${name}`);
		},
		async finish() {
			if (used.length) put(`used: ${used.join(', ')}`);
			await chain;
		},
	};
}

function choicesFor(preview, proposal) {
	const blocked = proposal.kind === 'buy' && proposal.safety?.verdict === 'block';
	const unpriced = (proposal.kind === 'buy' || proposal.kind === 'sell') && (!proposal.quote || proposal.quote.error);
	if (blocked || unpriced) return [{ id: `${CANCEL}${preview.id}`, label: 'Dismiss', style: 'secondary' }];
	return [
		{ id: `${APPROVE}${preview.id}`, label: 'Approve', style: 'primary' },
		{ id: `${CANCEL}${preview.id}`, label: 'Cancel', style: 'danger' },
	];
}

export function previewText(proposal) {
	const blocked = proposal.kind === 'buy' && proposal.safety?.verdict === 'block';
	const tail = blocked
		? 'The safety firewall blocked this buy, so it cannot be approved.'
		: `Approve to execute, Cancel to discard. Expires in ${PREVIEW_TTL_MINUTES} minutes.`;
	return `${describeProposal(proposal)}\n\n${tail}`;
}

async function sendPreviews({ gw, event, link, agent, proposals }) {
	for (const p of proposals) {
		const preview = await createPreview({ linkId: link.id, userId: link.user_id, agentId: agent.id, kind: p.kind, proposal: p });
		const ref = await gw.sendChoice(event.chatId, previewText(p), choicesFor(preview, p), { link });
		if (ref) await setPreviewMessageRef(preview.id, ref);
	}
}

async function sendReply(gw, chatId, text) {
	for (const part of chunkText(text, MAX_TEXT[gw.platform] || 1900)) await gw.sendText(chatId, part);
}

/**
 * Run one turn for `text` in a paired chat.
 * @param {{ gw:object, event:object, link:object, text:string }} ctx
 */
export async function converse({ gw, event, link, text }) {
	const agent = await resolveChatAgent(link);
	if (!agent) {
		const agents = await listAccountAgents(link.user_id);
		return gw.sendText(event.chatId, agents.length
			? 'Pick which agent this chat talks to first: send /agents, then /use <number>.'
			: `Your account has no agents yet. Create one at ${appOrigin()}/create, then come back and say hi.`);
	}

	const channel = event.platform;
	const history = await threadHistoryForModel({ agentId: agent.id, userId: link.user_id, since: link.context_reset_at, limit: 23 });
	history.push({ role: 'user', content: text.slice(0, 4000) });
	await appendThreadMessage({ agentId: agent.id, userId: link.user_id, role: 'user', content: text, channel });

	const stopTyping = keepTyping(gw, event.chatId);
	const status = statusLine(gw, event.chatId);
	let turn;
	try {
		const brain = await resolveAgentBrain({ agent, purpose: 'run', lenient: true });
		turn = await runCopilotTurn({
			agent,
			history,
			chain: brain.chain,
			network: 'mainnet',
			surfaceNote: surfaceNote(event.platform, { buttons: hasButtons(gw) }),
			emit: (name, data) => { if (name === 'tool_start') status.working(data.name); },
		});
	} catch (e) {
		stopTyping();
		await status.finish();
		const msg = e?.code === 'llm_unavailable'
			? 'Your agent cannot think right now: no language model is reachable. Try again shortly.'
			: 'Your agent hit an error answering that. Try again in a moment.';
		console.error('[gateway] turn failed', e?.message);
		return gw.sendText(event.chatId, msg);
	}
	stopTyping();
	await status.finish();

	const reply = plainText(turn.reply) || (turn.proposals.length ? 'Here is what I prepared:' : 'I have nothing to add to that.');
	await sendReply(gw, event.chatId, reply);
	await maybeSpeakReply({ gw, chatId: event.chatId, link, text: reply, agentId: agent.id });
	if (turn.proposals.length) await sendPreviews({ gw, event, link, agent, proposals: turn.proposals });

	await appendThreadMessage({
		agentId: agent.id, userId: link.user_id, role: 'assistant', content: turn.reply || reply, channel,
		toolCalls: turn.toolCalls,
	});
	return turn;
}