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.

17.2 KB
Raw Blame
// /api/agents/:id/mirror — the custodial copy-trade (mirror) social graph.
//
// Owner-only to configure (create/edit/pause/kill/sync); public to read a
// leader's follower count + honest track record. Every mirrored trade executes
// through the task-05 engine inside the follower's spend policy — this surface
// only manages the follow edges and triggers the fanout; it never bypasses a
// guard. See api/_lib/agent-mirror.js for the guarded executor.
//
//   GET    /api/agents/:id/mirror                following list + recent fills + counts (owner)
//   POST   /api/agents/:id/mirror                create / update a follow (owner)
//   POST   /api/agents/:id/mirror/unfollow       remove a follow edge (owner)
//   POST   /api/agents/:id/mirror/kill           toggle the agent-wide mirror kill switch (owner)
//   POST   /api/agents/:id/mirror/sync           process pending leader trades now (owner)
//   GET    /api/agents/:id/mirror/followers      who mirrors this agent (public)
//   GET    /api/agents/:id/mirror/track-record   this leader's real stats (public)
//   GET    /api/agents/:id/mirror/fills          recent mirror fills feed (owner)

import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { assertBearerMaySpend } from '../_lib/spend-scope.js';
import { sql } from '../_lib/db.js';
import { cors, json, method, error, readJson, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { requireCsrf } from '../_lib/csrf.js';
import { requireRealFundsAgreement } from '../_lib/real-funds-agreement.js';
import { isUuid } from '../_lib/validate.js';
import { logAudit } from '../_lib/audit.js';
import { normalizeFollowInput, SKIP_LABELS } from '../_lib/mirror-engine.js';
import { leaderTrackRecord } from '../_lib/mirror-stats.js';
import { syncFollow } from '../_lib/agent-mirror.js';

const NETWORKS = new Set(['mainnet', 'devnet']);
const netOf = (v) => (NETWORKS.has(v) ? v : 'mainnet');

async function resolveAuth(req) {
	const session = await getSessionUser(req);
	if (session) return { userId: session.id };
	const bearer = assertBearerMaySpend(await authenticateBearer(extractBearer(req)), req, { kind: 'trade' });
	if (bearer) return { userId: bearer.userId };
	return null;
}

// Owner gate → returns { auth, row } or sends the response and returns null.
async function loadOwned(req, res, id) {
	const auth = await resolveAuth(req);
	if (!auth) { error(res, 401, 'unauthorized', 'sign in to manage mirroring'); return null; }
	const [row] = await sql`SELECT id, user_id, name, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
	if (!row) { error(res, 404, 'not_found', 'agent not found'); return null; }
	if (row.user_id !== auth.userId) { error(res, 403, 'forbidden', 'only the owner can manage this agent’s mirroring'); return null; }
	return { auth, row };
}

// Hydrate follow rows with leader name/avatar for the management UI.
async function hydrateFollows(rows) {
	if (!rows.length) return [];
	const leaderIds = [...new Set(rows.map((r) => r.leader_agent_id))];
	const leaders = await sql`SELECT id, name, avatar_url, profile_image_url FROM agent_identities WHERE id = ANY(${leaderIds})`.catch(() => []);
	const byId = new Map(leaders.map((l) => [l.id, l]));
	return rows.map((r) => {
		const l = byId.get(r.leader_agent_id) || {};
		return {
			id: Number(r.id),
			leader_agent_id: r.leader_agent_id,
			leader_name: l.name || null,
			leader_avatar: l.avatar_url || l.profile_image_url || null,
			network: r.network,
			enabled: r.enabled,
			sizing_mode: r.sizing_mode,
			fixed_sol: r.fixed_sol,
			proportion_pct: r.proportion_pct,
			pct_balance: r.pct_balance,
			max_per_trade_sol: r.max_per_trade_sol,
			daily_budget_sol: r.daily_budget_sol,
			min_leader_sol: r.min_leader_sol,
			copy_sells: r.copy_sells,
			mint_allowlist: r.mint_allowlist || [],
			mint_denylist: r.mint_denylist || [],
			created_at: r.created_at,
			updated_at: r.updated_at,
		};
	});
}

// ── GET /mirror — owner management view ───────────────────────────────────────
async function handleList(req, res, id) {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET'])) return;
	const owned = await loadOwned(req, res, id);
	if (!owned) return;

	const rl = await limits.walletRead(owned.auth.userId);
	if (!rl.success) return rateLimited(res, rl);

	const [follows, fills, followerCount] = await Promise.all([
		sql`SELECT * FROM agent_mirror_follows WHERE follower_agent_id = ${id} ORDER BY created_at DESC`.catch(() => []),
		sql`
			SELECT f.*, a.name AS leader_name, a.avatar_url AS leader_avatar
			FROM agent_mirror_fills f
			LEFT JOIN agent_identities a ON a.id = f.leader_agent_id
			WHERE f.follower_agent_id = ${id}
			ORDER BY f.created_at DESC LIMIT 30
		`.catch(() => []),
		sql`SELECT count(*)::int AS c, count(*) FILTER (WHERE enabled)::int AS active FROM agent_mirror_follows WHERE leader_agent_id = ${id}`.catch(() => [{ c: 0, active: 0 }]),
	]);

	return json(res, 200, {
		data: {
			is_owner: true,
			killed: owned.row.meta?.mirror_killed === true,
			following: await hydrateFollows(follows),
			following_count: follows.length,
			followers_count: Number(followerCount[0]?.c || 0),
			active_followers: Number(followerCount[0]?.active || 0),
			recent: fills.map(serializeFill),
		},
	});
}

function serializeFill(f) {
	return {
		id: Number(f.id),
		leader_agent_id: f.leader_agent_id,
		leader_name: f.leader_name || null,
		leader_avatar: f.leader_avatar || null,
		side: f.side,
		mint: f.mint,
		leader_sol: f.leader_sol,
		planned_sol: f.planned_sol,
		status: f.status,
		skip_reason: f.skip_reason,
		skip_label: f.skip_reason ? (SKIP_LABELS[f.skip_reason] || f.skip_reason) : null,
		signature: f.signature,
		usd: f.usd,
		price_impact_pct: f.price_impact_pct,
		at: f.created_at,
	};
}

// ── POST /mirror — create / update a follow edge ──────────────────────────────
async function handleUpsert(req, res, id) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;
	const owned = await loadOwned(req, res, id);
	if (!owned) return;

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	let body;
	try { body = await readJson(req); }
	catch (e) { return error(res, 400, 'bad_request', e?.message || 'invalid body'); }

	const leaderId = typeof body.leader_agent_id === 'string' ? body.leader_agent_id.trim() : '';
	if (!isUuid(leaderId)) return error(res, 400, 'validation_error', 'leader_agent_id must be a UUID');
	if (leaderId === id) return error(res, 400, 'cannot_follow_self', 'an agent cannot mirror itself');

	const network = netOf(body.network);
	const enabled = body.enabled === false ? false : true;

	// An enabled follow trades the follower's custodial wallet autonomously, so it
	// needs signed real-funds agreements. Saving a paused follow does not. Checked
	// before CSRF so a refusal does not burn the owner's single-use token.
	if (enabled && !(await requireRealFundsAgreement(req, res, { userId: owned.auth.userId, network, context: 'mirror' }))) return;
	if (!(await requireCsrf(req, res, owned.auth.userId))) return;

	// The leader must exist and be public (you can only copy a transparent agent).
	const [leader] = await sql`SELECT id, name, is_public FROM agent_identities WHERE id = ${leaderId} AND deleted_at IS NULL`;
	if (!leader) return error(res, 404, 'leader_not_found', 'that leader agent does not exist');
	if (leader.is_public === false) return error(res, 403, 'leader_private', 'that agent is private and cannot be mirrored');

	// Block a circular follow (A→B and B→A would feed each other forever).
	const [reverse] = await sql`SELECT 1 FROM agent_mirror_follows WHERE follower_agent_id = ${leaderId} AND leader_agent_id = ${id} LIMIT 1`;
	if (reverse) return error(res, 409, 'circular_follow', 'that agent already mirrors this one — circular mirroring is not allowed');

	const norm = normalizeFollowInput(body);
	if (!norm.ok) return error(res, 400, 'validation_error', norm.error);
	const v = norm.value;

	// Cursor starts at the leader's latest trade so a new follow mirrors only
	// trades made AFTER the follow began — never backfills history.
	const [latest] = await sql`
		SELECT COALESCE(MAX(id), 0) AS id FROM agent_custody_events
		WHERE agent_id = ${leaderId} AND network = ${network} AND category = 'trade'
	`.catch(() => [{ id: 0 }]);

	const [row] = await sql`
		INSERT INTO agent_mirror_follows (
			follower_agent_id, leader_agent_id, owner_user_id, network, enabled,
			sizing_mode, fixed_sol, proportion_pct, pct_balance,
			max_per_trade_sol, daily_budget_sol, min_leader_sol, copy_sells,
			mint_allowlist, mint_denylist, last_leader_event_id
		) VALUES (
			${id}, ${leaderId}, ${owned.auth.userId}, ${network}, ${enabled},
			${v.sizing_mode}, ${v.fixed_sol}, ${v.proportion_pct}, ${v.pct_balance},
			${v.max_per_trade_sol}, ${v.daily_budget_sol}, ${v.min_leader_sol}, ${v.copy_sells},
			${v.mint_allowlist}, ${v.mint_denylist}, ${Number(latest?.id || 0)}
		)
		ON CONFLICT (follower_agent_id, leader_agent_id) DO UPDATE SET
			enabled = ${enabled}, network = ${network},
			sizing_mode = ${v.sizing_mode}, fixed_sol = ${v.fixed_sol},
			proportion_pct = ${v.proportion_pct}, pct_balance = ${v.pct_balance},
			max_per_trade_sol = ${v.max_per_trade_sol}, daily_budget_sol = ${v.daily_budget_sol},
			min_leader_sol = ${v.min_leader_sol}, copy_sells = ${v.copy_sells},
			mint_allowlist = ${v.mint_allowlist}, mint_denylist = ${v.mint_denylist},
			updated_at = now()
		RETURNING *
	`;

	logAudit({ userId: owned.auth.userId, action: 'mirror.follow', resourceId: id, meta: { leader_agent_id: leaderId, sizing_mode: v.sizing_mode, enabled }, req });
	const [hydrated] = await hydrateFollows([row]);
	return json(res, 200, { data: { follow: hydrated } });
}

// ── POST /mirror/unfollow ─────────────────────────────────────────────────────
async function handleUnfollow(req, res, id) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;
	const owned = await loadOwned(req, res, id);
	if (!owned) return;
	if (!(await requireCsrf(req, res, owned.auth.userId))) return;

	let body;
	try { body = await readJson(req); } catch { body = {}; }
	const leaderId = typeof body.leader_agent_id === 'string' ? body.leader_agent_id.trim() : '';
	if (!isUuid(leaderId)) return error(res, 400, 'validation_error', 'leader_agent_id must be a UUID');

	const del = await sql`DELETE FROM agent_mirror_follows WHERE follower_agent_id = ${id} AND leader_agent_id = ${leaderId} RETURNING id`;
	logAudit({ userId: owned.auth.userId, action: 'mirror.unfollow', resourceId: id, meta: { leader_agent_id: leaderId }, req });
	return json(res, 200, { data: { removed: del.length > 0 } });
}

// ── POST /mirror/kill — agent-wide kill switch ────────────────────────────────
async function handleKill(req, res, id) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;
	const owned = await loadOwned(req, res, id);
	if (!owned) return;
	if (!(await requireCsrf(req, res, owned.auth.userId))) return;

	let body;
	try { body = await readJson(req); } catch { body = {}; }
	const killed = body.killed === true;

	const meta = { ...(owned.row.meta || {}), mirror_killed: killed };
	await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${id}`;
	logAudit({ userId: owned.auth.userId, action: killed ? 'mirror.kill_on' : 'mirror.kill_off', resourceId: id, meta: {}, req });
	return json(res, 200, { data: { killed } });
}

// ── POST /mirror/sync — process pending leader trades now ─────────────────────
async function handleSync(req, res, id) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;
	const owned = await loadOwned(req, res, id);
	if (!owned) return;

	const follows = await sql`SELECT * FROM agent_mirror_follows WHERE follower_agent_id = ${id} AND enabled = true`;
	// Syncing executes mirrored trades from the custodial wallet. Devnet-only
	// follows are exempt; checked before CSRF so a refusal keeps the token.
	const syncNetwork = follows.some((f) => f.network !== 'devnet') ? 'mainnet' : 'devnet';
	if (follows.length && !(await requireRealFundsAgreement(req, res, { userId: owned.auth.userId, network: syncNetwork, context: 'mirror' }))) return;
	if (!(await requireCsrf(req, res, owned.auth.userId))) return;

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	if (owned.row.meta?.mirror_killed === true) {
		return error(res, 409, 'mirror_killed', 'mirroring is paused by the kill switch — turn it off to sync');
	}

	const out = [];
	for (const f of follows) {
		// Attach leader name for the custody label without an extra round trip later.
		const [leader] = await sql`SELECT name FROM agent_identities WHERE id = ${f.leader_agent_id}`.catch(() => []);
		f.leader_name = leader?.name || null;
		const r = await syncFollow(f, { maxEvents: 15 }).catch((e) => ({ processed: 0, results: [], error: (e?.message || 'error').slice(0, 120) }));
		out.push({ leader_agent_id: f.leader_agent_id, ...r });
	}
	return json(res, 200, { data: { synced: out } });
}

// ── GET /mirror/followers — public ────────────────────────────────────────────
async function handleFollowers(req, res, id) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.publicIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const rows = await sql`
		SELECT f.follower_agent_id, f.enabled, f.created_at, a.name, a.avatar_url, a.profile_image_url
		FROM agent_mirror_follows f
		JOIN agent_identities a ON a.id = f.follower_agent_id AND a.deleted_at IS NULL
		WHERE f.leader_agent_id = ${id}
		ORDER BY f.created_at DESC LIMIT 60
	`.catch(() => []);
	return json(res, 200, {
		data: {
			count: rows.length,
			active: rows.filter((r) => r.enabled).length,
			followers: rows.map((r) => ({
				agent_id: r.follower_agent_id,
				name: r.name,
				avatar: r.avatar_url || r.profile_image_url || null,
				enabled: r.enabled,
				since: r.created_at,
			})),
		},
	});
}

// ── GET /mirror/track-record — public, real stats ─────────────────────────────
async function handleTrackRecord(req, res, id) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.publicIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const network = netOf(new URL(req.url, 'http://x').searchParams.get('network'));
	const [agent] = await sql`SELECT name, avatar_url, profile_image_url FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`.catch(() => []);
	if (!agent) return error(res, 404, 'not_found', 'agent not found');
	const record = await leaderTrackRecord(id, network);
	return json(res, 200, { data: { agent: { id, name: agent.name, avatar: agent.avatar_url || agent.profile_image_url || null }, record } });
}

// ── GET /mirror/fills — owner feed (paginated) ────────────────────────────────
async function handleFills(req, res, id) {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET'])) return;
	const owned = await loadOwned(req, res, id);
	if (!owned) return;

	const url = new URL(req.url, 'http://x');
	const limit = Math.min(100, Math.max(1, parseInt(url.searchParams.get('limit') || '40', 10) || 40));
	const beforeId = parseInt(url.searchParams.get('before') || '0', 10) || null;

	const rows = await sql`
		SELECT f.*, a.name AS leader_name, a.avatar_url AS leader_avatar
		FROM agent_mirror_fills f
		LEFT JOIN agent_identities a ON a.id = f.leader_agent_id
		WHERE f.follower_agent_id = ${id}
		  ${beforeId ? sql`AND f.id < ${beforeId}` : sql``}
		ORDER BY f.id DESC LIMIT ${limit}
	`.catch(() => []);
	return json(res, 200, { data: { items: rows.map(serializeFill), next: rows.length === limit ? Number(rows[rows.length - 1].id) : null } });
}

export default async function handler(req, res, id, action) {
	if (!isUuid(id)) { if (cors(req, res)) return; return error(res, 404, 'not_found', 'agent not found'); }
	switch (action) {
		case undefined:
		case '':
			return req.method === 'POST' ? handleUpsert(req, res, id) : handleList(req, res, id);
		case 'unfollow': return handleUnfollow(req, res, id);
		case 'kill': return handleKill(req, res, id);
		case 'sync': return handleSync(req, res, id);
		case 'followers': return handleFollowers(req, res, id);
		case 'track-record': return handleTrackRecord(req, res, id);
		case 'fills': return handleFills(req, res, id);
		default:
			if (cors(req, res)) return;
			return error(res, 404, 'not_found', 'unknown mirror action');
	}
}