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.

23.0 KB
Raw Blame
// The local agent runtime. Runs agents, strategies, orders and automations on
// this machine. Signing keys live in the keystore (OS keychain), state lives in
// a plain JSON file with no key material, and every action that signs or moves
// funds in live mode waits for an explicit yes carrying the payload hash the
// owner was shown (the same canonical-JSON sha256 the web flow uses).
//
// Pure of Electron: main.js injects the keystore, the store and the callbacks,
// the smoke test injects the same real pieces with a temp directory.

import { randomUUID } from 'node:crypto';
import { canonicalJson, payloadHash, confirmationTable, confirmationText } from './hash.js';
import { validateStrategyConfig, matchesEntry, shouldExit, effectivePriceImpactPct } from './strategy-schema.js';
import { createPumpFeed, cleanTokenLabel } from './feed.js';
import { quoteBuy, quoteSell } from './curve.js';

export const APPROVAL_TTL_MS = 15 * 60 * 1000;
export const AGENT_STATES = ['idle', 'working', 'waiting_approval', 'paused', 'error', 'killed'];
const MAX_RECEIPTS = 500;

export class RuntimeError extends Error {
	constructor(code, message, status = 400) {
		super(message);
		this.code = code;
		this.status = status;
	}
}

const emptyState = () => ({ version: 1, agents: {}, positions: [], approvals: {}, receipts: [], seen: {} });

export function createRuntime({ stateStore, keystore, log, feed = createPumpFeed(), live = null, onEvent = () => {}, now = Date.now }) {
	const state = { ...emptyState(), ...(stateStore.read() || {}) };
	const persist = () => stateStore.write(state);
	const emit = (type, data) => {
		try {
			onEvent({ type, ...data });
		} catch (err) {
			log.warn('event_handler_failed', { type, err });
		}
	};

	const agentOf = (id) => {
		const a = state.agents[id];
		if (!a) throw new RuntimeError('agent_not_found', `No agent ${id}.`, 404);
		return a;
	};

	function setStatus(agent, status, detail = null) {
		if (agent.status === status && agent.detail === detail) return;
		agent.status = status;
		agent.detail = detail;
		persist();
		emit('status', { agent: publicAgent(agent), face: face() });
	}

	// ── agents ───────────────────────────────────────────────────────────────
	function createAgent({ name, mode = 'paper', network = 'mainnet', strategy = {} }) {
		const cleanName = String(name || '').trim().slice(0, 60);
		if (!cleanName) throw new RuntimeError('invalid_name', 'An agent needs a name.');
		if (!['paper', 'live'].includes(mode)) throw new RuntimeError('invalid_mode', 'Mode must be paper or live.');
		if (!['mainnet', 'devnet'].includes(network)) throw new RuntimeError('invalid_network', 'Network must be mainnet or devnet.');
		if (mode === 'live' && !keystore.encrypted()) {
			throw new RuntimeError('keychain_unavailable', 'Live agents need the OS keychain to protect their signing key, and it is not available on this machine. Paper mode works without it.', 409);
		}
		const v = validateStrategyConfig({ ...strategy, network });
		if (!v.valid) throw new RuntimeError('invalid_strategy', v.errors.map((e) => `${e.field}: ${e.message}`).join(' '));
		const id = `ag_${randomUUID().slice(0, 12)}`;
		const wallet = keystore.create(id);
		state.agents[id] = {
			id, name: cleanName, mode, network, strategy: v.config, address: wallet.address,
			status: 'idle', detail: null, orders: [], automations: [], created_at: now(), last_sweep_at: null, last_cooldown_at: 0,
		};
		persist();
		log.info('agent_created', { id, mode, network });
		emit('status', { agent: publicAgent(state.agents[id]), face: face() });
		return publicAgent(state.agents[id]);
	}

	function pause(id) {
		const a = agentOf(id);
		if (a.status === 'killed') throw new RuntimeError('agent_killed', 'A killed agent cannot be paused.', 409);
		setStatus(a, 'paused');
		return publicAgent(a);
	}

	function resume(id) {
		const a = agentOf(id);
		if (a.status === 'killed') throw new RuntimeError('agent_killed', 'A killed agent cannot be resumed.', 409);
		setStatus(a, 'idle');
		return publicAgent(a);
	}

	/** Stop the agent for good: denies its pending approvals and disables orders and automations. Receipts and positions stay. */
	function kill(id) {
		const a = agentOf(id);
		for (const ap of Object.values(state.approvals)) {
			if (ap.agent_id === id && ap.status === 'pending') decideLocal(ap, 'denied', 'kill');
		}
		a.orders = [];
		a.automations = [];
		setStatus(a, 'killed');
		log.info('agent_killed', { id });
		return publicAgent(a);
	}

	function remove(id) {
		const a = agentOf(id);
		if (a.status !== 'killed') throw new RuntimeError('agent_active', 'Kill the agent before removing it.', 409);
		if (state.positions.some((p) => p.agent_id === id && p.status === 'open')) {
			throw new RuntimeError('open_positions', 'Close the open positions before removing the agent.', 409);
		}
		keystore.remove(id);
		delete state.agents[id];
		persist();
		return { removed: id };
	}

	function addOrder(id, order) {
		const a = agentOf(id);
		if (a.status === 'killed') throw new RuntimeError('agent_killed', 'The agent is killed.', 409);
		const side = order.side === 'sell' ? 'sell' : 'buy';
		if (!order.mint || typeof order.mint !== 'string') throw new RuntimeError('invalid_order', 'An order needs a mint.');
		const below = Number(order.trigger?.price_sol_below);
		const above = Number(order.trigger?.price_sol_above);
		const hasBelow = Number.isFinite(below) && below > 0;
		const hasAbove = Number.isFinite(above) && above > 0;
		if (!hasBelow && !hasAbove) throw new RuntimeError('invalid_order', 'An order needs price_sol_below or price_sol_above.');
		const amount = Number(order.amount_sol);
		if (side === 'buy' && !(amount > 0 && amount <= a.strategy.sizing.amount_sol * 10)) {
			throw new RuntimeError('invalid_order', 'Buy size must be positive and within ten times the strategy size.');
		}
		const o = { id: `or_${randomUUID().slice(0, 10)}`, mint: order.mint, side, amount_sol: side === 'buy' ? amount : null, trigger: { ...(hasBelow && { price_sol_below: below }), ...(hasAbove && { price_sol_above: above }) }, created_at: now() };
		a.orders.push(o);
		persist();
		return o;
	}

	function removeOrder(id, orderId) {
		const a = agentOf(id);
		a.orders = a.orders.filter((o) => o.id !== orderId);
		persist();
	}

	function addAutomation(id, auto) {
		const a = agentOf(id);
		if (a.status === 'killed') throw new RuntimeError('agent_killed', 'The agent is killed.', 409);
		const every = Number(auto.every_minutes);
		if (!(every >= 1 && every <= 10080)) throw new RuntimeError('invalid_automation', 'every_minutes must be between 1 and 10080.');
		if (!['sweep', 'expire_sweep'].includes(auto.action)) throw new RuntimeError('invalid_automation', 'action must be sweep or expire_sweep.');
		const x = { id: `au_${randomUUID().slice(0, 10)}`, action: auto.action, every_minutes: every, last_run_at: 0 };
		a.automations.push(x);
		persist();
		return x;
	}

	// ── approvals ────────────────────────────────────────────────────────────
	function decideLocal(ap, status, via) {
		ap.status = status;
		ap.decided_at = now();
		ap.via = via;
		emit('approval', { approval: publicApproval(ap) });
	}

	/** The exact action that will run, plus the table and hash the owner is shown. */
	function fileApproval(agent, payload, row) {
		const dupe = Object.values(state.approvals).find((ap) => ap.agent_id === agent.id && ap.status === 'pending' && ap.payload.idempotency_key === payload.idempotency_key);
		if (dupe) return dupe;
		const ap = {
			id: `ap_${randomUUID().slice(0, 12)}`, agent_id: agent.id, status: 'pending', payload,
			hash: payloadHash(payload), row, created_at: now(), expires_at: now() + APPROVAL_TTL_MS,
		};
		state.approvals[ap.id] = ap;
		persist();
		setStatus(agent, 'waiting_approval', `${row.amount} ${row.asset} to ${row.recipient_label || row.recipient}`);
		emit('approval', { approval: publicApproval(ap), notify: true });
		return ap;
	}

	function publicApproval(ap) {
		return {
			id: ap.id, agent_id: ap.agent_id, status: effectiveStatus(ap), hash: ap.hash, payload: ap.payload,
			row: ap.row, table: confirmationTable(ap.row), text: confirmationText(ap.row), created_at: ap.created_at, expires_at: ap.expires_at, decided_at: ap.decided_at || null,
		};
	}

	const effectiveStatus = (ap) => (ap.status === 'pending' && ap.expires_at <= now() ? 'expired' : ap.status);

	function listApprovals({ status = null, agentId = null } = {}) {
		return Object.values(state.approvals)
			.filter((ap) => (!agentId || ap.agent_id === agentId) && (!status || effectiveStatus(ap) === status))
			.sort((a, b) => b.created_at - a.created_at)
			.map(publicApproval);
	}

	function refreshWaiting(agent) {
		const waiting = Object.values(state.approvals).some((ap) => ap.agent_id === agent.id && effectiveStatus(ap) === 'pending');
		if (agent.status === 'waiting_approval' && !waiting) setStatus(agent, 'idle');
	}

	/**
	 * Approve or deny. An approval must present the hash it was shown; the stored
	 * payload is re-hashed here so neither a stale view nor an edited state file
	 * can run an action that differs from what the owner saw.
	 */
	async function decide(approvalId, { decision, hash, via = 'desktop' }) {
		const ap = state.approvals[approvalId];
		if (!ap) throw new RuntimeError('approval_not_found', 'No such approval.', 404);
		if (!['approve', 'deny'].includes(decision)) throw new RuntimeError('invalid_decision', 'Decision must be approve or deny.');
		if (effectiveStatus(ap) === 'expired' && ap.status === 'pending') {
			decideLocal(ap, 'expired', 'timeout');
			persist();
			throw new RuntimeError('approval_expired', 'This approval expired. Nothing was run.', 410);
		}
		if (ap.status !== 'pending') throw new RuntimeError('approval_not_pending', `This approval is already ${ap.status}.`, 409);
		const agent = agentOf(ap.agent_id);
		if (decision === 'deny') {
			decideLocal(ap, 'denied', via);
			persist();
			refreshWaiting(agent);
			return publicApproval(ap);
		}
		if (agent.status === 'killed') throw new RuntimeError('agent_killed', 'The agent was killed. Nothing was run.', 409);
		if (typeof hash !== 'string' || hash.toLowerCase() !== ap.hash) {
			throw new RuntimeError('hash_mismatch', 'The hash does not match the action on file. Nothing was run.', 409);
		}
		if (payloadHash(ap.payload) !== ap.hash) {
			throw new RuntimeError('payload_changed', 'The stored action changed after it was filed. Nothing was run.', 409);
		}
		ap.status = 'executing';
		persist();
		try {
			const receipt = await execute(agent, ap.payload, { approval: ap });
			ap.status = 'executed';
			ap.decided_at = now();
			ap.via = via;
			ap.receipt_id = receipt.id;
		} catch (err) {
			ap.status = 'failed';
			ap.decided_at = now();
			ap.error = String(err.message || err).slice(0, 300);
			setStatus(agent, 'error', ap.error);
			log.error('approval_execute_failed', { id: ap.id, err });
		}
		persist();
		emit('approval', { approval: publicApproval(ap) });
		refreshWaiting(agent);
		return publicApproval(ap);
	}

	// ── execution ────────────────────────────────────────────────────────────
	function recordReceipt(r) {
		const receipt = { id: `rc_${randomUUID().slice(0, 12)}`, at: now(), ...r };
		state.receipts.unshift(receipt);
		if (state.receipts.length > MAX_RECEIPTS) state.receipts.length = MAX_RECEIPTS;
		persist();
		emit('receipt', { receipt });
		return receipt;
	}

	async function execute(agent, payload, { approval = null } = {}) {
		if (payload.side === 'buy') return executeBuy(agent, payload, approval);
		return executeSell(agent, payload, approval);
	}

	async function executeBuy(agent, p, approval) {
		const coin = await feed.coin(p.mint, { symbol: p.symbol });
		if (!coin) throw new RuntimeError('quote_unavailable', 'The launch feed has no data for this coin right now.', 502);
		const q = quoteBuy(coin, p.amount_sol);
		if (p.max_price_impact_pct != null && q.impact_pct > p.max_price_impact_pct) {
			throw new RuntimeError('price_impact', `Price impact ${q.impact_pct.toFixed(2)}% exceeds the ${p.max_price_impact_pct}% cap.`, 409);
		}
		let signature = null;
		if (agent.mode === 'live') {
			if (!live) throw new RuntimeError('live_unavailable', 'Live execution is not configured on this install.', 409);
			signature = await live.buy({ agent, payload: p, quote: q });
		}
		state.positions.push({
			id: `po_${randomUUID().slice(0, 10)}`, agent_id: agent.id, mint: p.mint, symbol: coin.symbol || null, status: 'open',
			entry_lamports: Math.round(p.amount_sol * 1e9), tokens: q.tokens, peak_value_lamports: Math.round(p.amount_sol * 1e9),
			opened_at: now(), network: agent.network, mode: agent.mode,
		});
		agent.last_cooldown_at = now();
		return recordReceipt({ agent_id: agent.id, kind: 'buy', mode: agent.mode, network: agent.network, mint: p.mint, symbol: coin.symbol || null, sol: p.amount_sol, tokens: q.tokens, impact_pct: q.impact_pct, signature, approval_id: approval?.id || null, payload_hash: approval?.hash || null });
	}

	async function executeSell(agent, p, approval) {
		const pos = state.positions.find((x) => x.id === p.position_id && x.status === 'open');
		if (!pos) throw new RuntimeError('position_not_found', 'That position is not open.', 404);
		const coin = await feed.coin(pos.mint, { symbol: pos.symbol });
		if (!coin) throw new RuntimeError('quote_unavailable', 'The launch feed has no data for this coin right now.', 502);
		const q = quoteSell(coin, pos.tokens);
		let signature = null;
		if (agent.mode === 'live') {
			if (!live) throw new RuntimeError('live_unavailable', 'Live execution is not configured on this install.', 409);
			signature = await live.sell({ agent, payload: p, position: pos, quote: q });
		}
		pos.status = 'closed';
		pos.closed_at = now();
		pos.exit_lamports = q.lamports;
		pos.exit_reason = p.reason || 'manual';
		return recordReceipt({ agent_id: agent.id, kind: 'sell', mode: agent.mode, network: agent.network, mint: pos.mint, symbol: pos.symbol, sol: q.lamports / 1e9, tokens: pos.tokens, pnl_pct: ((q.lamports - pos.entry_lamports) / pos.entry_lamports) * 100, reason: pos.exit_reason, signature, approval_id: approval?.id || null, payload_hash: approval?.hash || null });
	}

	/** Paper never needs a yes (nothing signs). Live needs one unless the strategy is explicitly 'auto'. */
	const needsApproval = (agent) => agent.mode === 'live' && agent.strategy.mode !== 'auto';

	async function act(agent, payload, row) {
		if (needsApproval(agent)) return fileApproval(agent, payload, row);
		return execute(agent, payload);
	}

	const buyRow = (agent, p, symbol) => ({
		recipient: p.mint, recipient_label: cleanTokenLabel(symbol) ? `$${cleanTokenLabel(symbol)}` : null, amount: p.amount_sol, asset: 'SOL', chain: 'solana', network: agent.network, side: 'buy',
	});

	// ── scheduler ────────────────────────────────────────────────────────────
	function buyPayload(agent, mint, symbol = null) {
		const c = agent.strategy;
		return {
			kind: 'local_strategy_buy', agent_id: agent.id, symbol, strategy: c.name || 'local', network: agent.network, mint, side: 'buy',
			amount_sol: c.sizing.amount_sol, slippage_bps: c.sizing.max_slippage_bps,
			max_price_impact_pct: effectivePriceImpactPct(c, null), idempotency_key: `${agent.id}:${mint}`,
		};
	}

	async function sweepEntries(agent) {
		const c = agent.strategy;
		const launches = await feed.launches({ network: agent.network });
		const open = state.positions.filter((p) => p.agent_id === agent.id && p.status === 'open');
		const pending = Object.values(state.approvals).filter((ap) => ap.agent_id === agent.id && effectiveStatus(ap) === 'pending').length;
		let slots = c.risk.max_concurrent_positions - open.length - pending;
		const seen = new Set(state.seen[agent.id] || []);
		const decisions = [];
		for (const launch of launches) {
			if (slots <= 0) break;
			if (seen.has(launch.mint)) continue;
			if (c.risk.cooldown_minutes > 0 && now() - agent.last_cooldown_at < c.risk.cooldown_minutes * 60000) break;
			const verdict = matchesEntry(c, launch, now());
			if (!verdict.pass) seen.add(launch.mint);
			decisions.push({ mint: launch.mint, pass: verdict.pass, reasons: verdict.reasons });
			if (!verdict.pass) continue;
			const payload = buyPayload(agent, launch.mint, launch.symbol);
			try {
				await act(agent, payload, buyRow(agent, payload, launch.symbol));
				seen.add(launch.mint);
				slots -= 1;
			} catch (err) {
				log.warn('entry_failed', { agent: agent.id, mint: launch.mint, err });
				if (err.code === 'quote_unavailable') break;
			}
		}
		state.seen[agent.id] = [...seen].slice(-500);
		return decisions;
	}

	async function sweepExits(agent) {
		const open = state.positions.filter((p) => p.agent_id === agent.id && p.status === 'open');
		for (const pos of open) {
			const coin = await feed.coin(pos.mint, { symbol: pos.symbol });
			if (!coin) continue;
			const q = quoteSell(coin, pos.tokens);
			pos.peak_value_lamports = Math.max(pos.peak_value_lamports, q.lamports);
			const verdict = shouldExit(agent.strategy, pos, q.lamports, now());
			if (!verdict.exit) continue;
			const payload = { kind: 'local_strategy_sell', agent_id: agent.id, network: agent.network, mint: pos.mint, side: 'sell', position_id: pos.id, reason: verdict.reason, idempotency_key: `${agent.id}:${pos.id}:sell` };
			try {
				await act(agent, payload, { recipient: pos.mint, recipient_label: pos.symbol ? `$${pos.symbol}` : null, amount: q.lamports / 1e9, asset: 'SOL', chain: 'solana', network: agent.network, side: 'sell' });
			} catch (err) {
				log.warn('exit_failed', { agent: agent.id, mint: pos.mint, err });
			}
		}
		persist();
	}

	async function runOrders(agent) {
		for (const order of [...agent.orders]) {
			const coin = await feed.coin(order.mint);
			if (!coin || !(Number(coin.virtual_token_reserves) > 0)) continue;
			const price = Number(coin.virtual_sol_reserves) / 1e9 / (Number(coin.virtual_token_reserves) / 1e6);
			const hit = (order.trigger.price_sol_below && price <= order.trigger.price_sol_below) || (order.trigger.price_sol_above && price >= order.trigger.price_sol_above);
			if (!hit) continue;
			agent.orders = agent.orders.filter((o) => o.id !== order.id);
			persist();
			if (order.side === 'buy') {
				const payload = { ...buyPayload(agent, order.mint, null), amount_sol: order.amount_sol, kind: 'local_order_buy', idempotency_key: `${agent.id}:${order.id}` };
				await act(agent, payload, buyRow(agent, payload, coin.symbol));
			} else {
				const pos = state.positions.find((x) => x.agent_id === agent.id && x.mint === order.mint && x.status === 'open');
				if (!pos) continue;
				const q = quoteSell(coin, pos.tokens);
				const payload = { kind: 'local_order_sell', agent_id: agent.id, network: agent.network, mint: pos.mint, side: 'sell', position_id: pos.id, reason: 'order', idempotency_key: `${agent.id}:${order.id}` };
				await act(agent, payload, { recipient: pos.mint, recipient_label: pos.symbol ? `$${pos.symbol}` : null, amount: q.lamports / 1e9, asset: 'SOL', chain: 'solana', network: agent.network, side: 'sell' });
			}
		}
	}

	function expireSweep() {
		for (const ap of Object.values(state.approvals)) {
			if (ap.status === 'pending' && ap.expires_at <= now()) decideLocal(ap, 'expired', 'timeout');
		}
		persist();
		for (const a of Object.values(state.agents)) refreshWaiting(a);
	}

	/** One scheduler pass for one agent. Returns what it decided, for logs and tests. */
	async function tickAgent(agent) {
		if (agent.status === 'paused' || agent.status === 'killed') return { skipped: agent.status };
		const wasWaiting = agent.status === 'waiting_approval';
		setStatus(agent, 'working');
		try {
			expireSweep();
			await sweepExits(agent);
			await runOrders(agent);
			const decisions = await sweepEntries(agent);
			for (const au of agent.automations) {
				if (now() - au.last_run_at >= au.every_minutes * 60000) {
					au.last_run_at = now();
					if (au.action === 'expire_sweep') expireSweep();
				}
			}
			agent.last_sweep_at = now();
			const waiting = Object.values(state.approvals).some((ap) => ap.agent_id === agent.id && effectiveStatus(ap) === 'pending');
			setStatus(agent, waiting ? 'waiting_approval' : 'idle', waiting ? agent.detail : null);
			persist();
			return { decisions };
		} catch (err) {
			log.error('tick_failed', { agent: agent.id, err });
			setStatus(agent, 'error', String(err.message || err).slice(0, 200));
			return { error: err.message, wasWaiting };
		}
	}

	let timer = null;
	let inflight = null;
	/** One pass over every agent. A pass already running is awaited, never doubled. */
	function tick() {
		if (inflight) return inflight;
		inflight = (async () => {
			for (const agent of Object.values(state.agents)) {
				if (agent.status === 'error') setStatus(agent, 'idle');
				await tickAgent(agent);
			}
		})().finally(() => {
			inflight = null;
		});
		return inflight;
	}

	function start({ intervalMs = 30_000 } = {}) {
		if (timer) return;
		timer = setInterval(() => void tick(), intervalMs);
		timer.unref?.();
		void tick();
	}

	function stop() {
		if (timer) clearInterval(timer);
		timer = null;
	}

	// ── views ────────────────────────────────────────────────────────────────
	function publicAgent(a) {
		const open = state.positions.filter((p) => p.agent_id === a.id && p.status === 'open').length;
		const pending = Object.values(state.approvals).filter((ap) => ap.agent_id === a.id && effectiveStatus(ap) === 'pending').length;
		return {
			id: a.id, name: a.name, mode: a.mode, network: a.network, address: a.address, status: a.status, detail: a.detail,
			strategy: a.strategy, orders: a.orders, automations: a.automations, open_positions: open, pending_approvals: pending,
			last_sweep_at: a.last_sweep_at, created_at: a.created_at,
		};
	}

	/** What the mascot shows: the most urgent state across all agents. */
	function face() {
		const statuses = Object.values(state.agents).map((a) => a.status);
		const order = ['error', 'waiting_approval', 'working', 'idle', 'paused', 'killed'];
		const top = order.find((s) => statuses.includes(s)) || 'none';
		return { state: top, agents: statuses.length };
	}

	return {
		createAgent, pause, resume, kill, remove, addOrder, removeOrder, addAutomation,
		listAgents: () => Object.values(state.agents).map(publicAgent),
		getAgent: (id) => publicAgent(agentOf(id)),
		listApprovals, decide, tick, tickAgent, start, stop, face,
		positions: ({ agentId = null } = {}) => state.positions.filter((p) => !agentId || p.agent_id === agentId),
		receipts: ({ agentId = null, limit = 100 } = {}) => state.receipts.filter((r) => !agentId || r.agent_id === agentId).slice(0, limit),
		exportConfig: () => ({ agents: Object.values(state.agents).map((a) => ({ id: a.id, name: a.name, mode: a.mode, network: a.network, address: a.address, strategy: a.strategy, status: a.status })) }),
		canonicalJson,
	};
}