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.

20.7 KB
Raw Blame
/**
 * Living Stages, stage + show lifecycle (Moonshot 04).
 *
 * A "stage" is a venue where an embodied AI agent hosts live, monetized shows.
 * A "show" is one live session against that stage; "show_tips" is the per-show
 * ledger of real on-chain $THREE tips. This endpoint owns the read surface (the
 * stage directory + a single stage's live/between-show state) and the owner-only
 * writes (create/update a stage, go live, end a show).
 *
 *   GET  /api/stage                  → directory: live shows first, then upcoming
 *   GET  /api/stage?id=<id>          → one stage: host, current show, leaderboard,
 *                                      host wallet (tip target), between-show state
 *   GET  /api/stage?coin=<mint>      → the stage standing in that /play coin
 *                                      world's plaza (F17), or { stage: null }
 *   POST /api/stage  { action:'create', agentId, title, format, voice, venue,
 *                      tipSplitBps, nextShowAt }     → owner provisions a stage
 *   POST /api/stage  { action:'plaza', agentId, coinMint, … }
 *                                                    → claim a coin world's plaza
 *   POST /api/stage  { action:'golive', stageId }    → open a show + notify holders
 *   POST /api/stage  { action:'endshow', stageId }   → close the current show
 *
 * Every write enforces ownership server-side (the agent's user_id must equal the
 * session user) + CSRF. Money is integer atomic units; $THREE is the only coin.
 */

import { cors, json, wrap, readJson } from '../_lib/http.js';
import { sql } from '../_lib/db.js';
import { getSessionUser } from '../_lib/auth.js';
import { requireCsrf } from '../_lib/csrf.js';
import { isUuid } from '../_lib/validate.js';
import { ensureAgentWallet } from '../_lib/agent-wallet.js';
import { insertNotification } from '../_lib/notify.js';
import { sendOpsAlert } from '../_lib/alerts.js';
import { normalizeSplitBps } from '../_lib/stage-split.js';
import { plazaStageId } from '../../multiplayer/src/plaza-stage.js';

const VENUES = new Set(['club', 'theater', 'plaza', 'arena']);
const MAX_MINT = 64;
const MAX_TITLE = 120;
const MAX_FORMAT = 60;

let _tablesReady = false;
async function ensureTables() {
	if (_tablesReady) return;
	await sql`
		CREATE TABLE IF NOT EXISTS stages (
			id              UUID DEFAULT gen_random_uuid() PRIMARY KEY,
			agent_id        UUID NOT NULL,
			owner_user_id   UUID NOT NULL,
			venue           TEXT NOT NULL DEFAULT 'club',
			title           TEXT,
			format          TEXT,
			voice           TEXT NOT NULL DEFAULT 'nova',
			tip_split_bps   INT  NOT NULL DEFAULT 1000,
			status          TEXT NOT NULL DEFAULT 'scheduled',
			next_show_at    TIMESTAMPTZ,
			created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
			updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
		)
	`;
	await sql`CREATE INDEX IF NOT EXISTS stages_status ON stages (status, next_show_at)`;
	await sql`CREATE INDEX IF NOT EXISTS stages_agent  ON stages (agent_id)`;
	await sql`CREATE UNIQUE INDEX IF NOT EXISTS stages_agent_uniq ON stages (agent_id)`;
	// Plaza binding (F17). Migration 20260807120000_stage_coin_mint.sql owns this on
	// a migrated database; the ALTER covers one that has never run migrations.
	await sql`ALTER TABLE stages ADD COLUMN IF NOT EXISTS coin_mint TEXT`;
	await sql`CREATE INDEX IF NOT EXISTS stages_coin_mint ON stages (coin_mint) WHERE coin_mint IS NOT NULL`;
	await sql`
		CREATE TABLE IF NOT EXISTS shows (
			id                UUID DEFAULT gen_random_uuid() PRIMARY KEY,
			stage_id          UUID NOT NULL,
			started_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
			ended_at          TIMESTAMPTZ,
			peak_audience     INT NOT NULL DEFAULT 0,
			total_tips_atomic NUMERIC NOT NULL DEFAULT 0,
			tip_count         INT NOT NULL DEFAULT 0,
			created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW()
		)
	`;
	await sql`CREATE INDEX IF NOT EXISTS shows_stage ON shows (stage_id, started_at DESC)`;
	// Exactly one open show per stage, a partial unique index makes "go live twice"
	// a no-op rather than a second open row the tips would split across.
	await sql`CREATE UNIQUE INDEX IF NOT EXISTS shows_one_open ON shows (stage_id) WHERE ended_at IS NULL`;
	await sql`
		CREATE TABLE IF NOT EXISTS show_tips (
			id                 UUID DEFAULT gen_random_uuid() PRIMARY KEY,
			show_id            UUID,
			stage_id           UUID NOT NULL,
			tipper_user_id     UUID,
			tipper_label       TEXT,
			amount_atomic      NUMERIC NOT NULL,
			currency_mint      TEXT NOT NULL,
			host_credit_atomic NUMERIC NOT NULL,
			venue_cut_atomic   NUMERIC NOT NULL,
			settlement_sig     TEXT NOT NULL,
			network            TEXT,
			message            TEXT,
			verified_at        TIMESTAMPTZ,
			verify_error       TEXT,
			created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW()
		)
	`;
	// Live databases predate the verification columns (migration
	// 20260806130000_settlement_verification.sql adds them there, with the
	// grandfathering backfill). These ALTERs only cover a database that has never
	// run migrations; they must never backfill, or a genuinely pending tip would be
	// promoted without proof.
	await sql`ALTER TABLE show_tips ADD COLUMN IF NOT EXISTS verified_at  TIMESTAMPTZ`;
	await sql`ALTER TABLE show_tips ADD COLUMN IF NOT EXISTS verify_error TEXT`;
	// One settlement → one tip row. The unique index is the idempotency guarantee
	// the tip endpoint leans on (ON CONFLICT DO NOTHING).
	await sql`CREATE UNIQUE INDEX IF NOT EXISTS show_tips_sig ON show_tips (settlement_sig)`;
	await sql`CREATE INDEX IF NOT EXISTS show_tips_show ON show_tips (show_id, amount_atomic DESC)`;
	_tablesReady = true;
}

// Resolve the host agent's Solana wallet (the tip target) without provisioning on
// a public read, only return an address that already exists. Provisioning
// happens at stage creation, when the owner is authenticated.
async function readHostWallet(agentId) {
	const [row] = await sql`SELECT meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL LIMIT 1`;
	const addr = row?.meta?.solana_address;
	return typeof addr === 'string' && addr ? addr : null;
}

// Aggregate the per-tipper leaderboard for a show, highest total first.
async function showLeaderboard(showId, limit = 10) {
	if (!showId) return [];
	// Verified tips only: a tip whose settlement has not been proved on-chain is
	// quarantined and must never reach a public leaderboard.
	const rows = await sql`
		SELECT
			COALESCE(tipper_label, 'someone') AS label,
			SUM(amount_atomic)::numeric AS total,
			COUNT(*)::int AS count,
			MIN(created_at) AS first_at
		FROM show_tips
		WHERE show_id = ${showId} AND verified_at IS NOT NULL
		GROUP BY COALESCE(tipper_label, 'someone')
		ORDER BY total DESC, first_at ASC
		LIMIT ${limit}
	`;
	return rows.map((r) => ({ label: r.label, total: Number(r.total), count: r.count }));
}

// One stage's full public read: host + venue config, whether a show is open, the
// leaderboard for the show that matters (the open one, else the last one), and the
// host wallet a tip is sent to. Null when the stage does not exist. Shared by the
// ?id= and ?coin= reads so the /stage page and the in-world plaza can never see
// two different shapes of the same show.
async function stageDetail(stageId) {
	if (!isUuid(stageId)) return null;
	const [stage] = await sql`
		SELECT s.*, a.name AS agent_name, a.avatar_url, a.profile_image_url, a.is_public
		FROM stages s
		JOIN agent_identities a ON a.id = s.agent_id AND a.deleted_at IS NULL
		WHERE s.id = ${stageId}
		LIMIT 1
	`;
	if (!stage) return null;

	const [openShow] = await sql`
		SELECT id, started_at, peak_audience, total_tips_atomic, tip_count
		FROM shows WHERE stage_id = ${stageId} AND ended_at IS NULL
		ORDER BY started_at DESC LIMIT 1
	`;
	const [lastShow] = openShow
		? [null]
		: await sql`
			SELECT id, started_at, ended_at, peak_audience, total_tips_atomic, tip_count
			FROM shows WHERE stage_id = ${stageId} AND ended_at IS NOT NULL
			ORDER BY ended_at DESC LIMIT 1
		`;
	const leaderboardShow = openShow || lastShow;
	const leaderboard = await showLeaderboard(leaderboardShow?.id);
	const hostWallet = await readHostWallet(stage.agent_id);

	return {
		stage: shapeStage(stage),
		live: !!openShow,
		currentShow: openShow ? shapeShow(openShow) : null,
		lastShow: lastShow ? shapeShow(lastShow) : null,
		leaderboard,
		hostWallet,
	};
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;

	await ensureTables();

	if (req.method === 'GET') return handleGet(req, res);
	if (req.method === 'POST') return handlePost(req, res);
	return json(res, 405, { error: 'method_not_allowed' });
});

async function handleGet(req, res) {
	const id = req.query.id;

	// ── lookup by agent (cross-link from an agent profile) ─────────────────────
	if (req.query.agentId) {
		if (!isUuid(req.query.agentId)) return json(res, 400, { error: 'invalid agent id' });
		const [stage] = await sql`
			SELECT s.*, a.name AS agent_name, a.avatar_url, a.profile_image_url,
				EXISTS (SELECT 1 FROM shows sh WHERE sh.stage_id = s.id AND sh.ended_at IS NULL) AS is_live
			FROM stages s
			JOIN agent_identities a ON a.id = s.agent_id AND a.deleted_at IS NULL
			WHERE s.agent_id = ${req.query.agentId}
			LIMIT 1
		`;
		if (!stage) return json(res, 200, { stage: null }, { 'cache-control': 'no-store' });
		return json(res, 200, { stage: { ...shapeStage(stage), live: !!stage.is_live } }, { 'cache-control': 'no-store' });
	}

	// ── the stage standing in a coin world's plaza (F17) ──────────────────────
	// The /play client derives this id itself (multiplayer/src/plaza-stage.js) and
	// only needs the show state, so an UNCLAIMED plaza is a 200 with stage:null,
	// the quiet-landmark case is normal, not an error.
	if (req.query.coin) {
		const mint = cleanMint(req.query.coin);
		if (!mint) return json(res, 400, { error: 'invalid coin mint' });
		const stageId = plazaStageId(mint);
		const detail = await stageDetail(stageId);
		if (!detail) return json(res, 200, { stage: null, stageId, coinMint: mint }, { 'cache-control': 'no-store' });
		return json(res, 200, { ...detail, stageId, coinMint: mint }, { 'cache-control': 'no-store' });
	}

	// ── single stage ──────────────────────────────────────────────────────────
	if (id) {
		if (!isUuid(id)) return json(res, 400, { error: 'invalid stage id' });
		const detail = await stageDetail(id);
		if (!detail) return json(res, 404, { error: 'stage not found' });
		return json(res, 200, detail, { 'cache-control': 'no-store' });
	}

	// ── directory: live first, then upcoming, then recently-ended ──────────────
	const stages = await sql`
		SELECT s.*, a.name AS agent_name, a.avatar_url, a.profile_image_url,
			EXISTS (SELECT 1 FROM shows sh WHERE sh.stage_id = s.id AND sh.ended_at IS NULL) AS is_live,
			(SELECT total_tips_atomic FROM shows sh WHERE sh.stage_id = s.id ORDER BY started_at DESC LIMIT 1) AS recent_tips
		FROM stages s
		JOIN agent_identities a ON a.id = s.agent_id AND a.deleted_at IS NULL AND a.is_public IS TRUE
		WHERE s.status <> 'draft'
		ORDER BY is_live DESC, s.next_show_at ASC NULLS LAST, s.updated_at DESC
		LIMIT 60
	`;
	return json(res, 200, {
		stages: stages.map((s) => ({
			...shapeStage(s),
			live: !!s.is_live,
			recentTipsAtomic: Number(s.recent_tips || 0),
		})),
	}, { 'cache-control': 'no-store' });
}

async function handlePost(req, res) {
	const session = await getSessionUser(req).catch(() => null);
	if (!session) return json(res, 401, { error: 'authentication_required' });
	if (!(await requireCsrf(req, res, session.id))) return;

	let body;
	try {
		body = await readJson(req, 20_000);
	} catch (e) {
		return json(res, e.status || 400, { error: e.message || 'bad_request' });
	}
	const action = String(body.action || '').toLowerCase();

	if (action === 'create') return createStage(req, res, session, body);
	if (action === 'plaza') return claimPlaza(req, res, session, body);
	if (action === 'golive') return goLive(req, res, session, body);
	if (action === 'endshow') return endShow(req, res, session, body);
	return json(res, 400, { error: 'unknown action' });
}

// Confirm the session user owns the agent (server-side ownership gate).
async function ownedAgent(agentId, userId) {
	if (!isUuid(agentId)) return null;
	const [a] = await sql`
		SELECT id, name, avatar_url FROM agent_identities
		WHERE id = ${agentId} AND user_id = ${userId} AND deleted_at IS NULL LIMIT 1
	`;
	return a || null;
}

async function createStage(req, res, session, body) {
	const agent = await ownedAgent(body.agentId, session.id);
	if (!agent) return json(res, 403, { error: 'you do not own this agent' });

	const venue = VENUES.has(body.venue) ? body.venue : 'club';
	const title = cleanStr(body.title, MAX_TITLE) || `${agent.name} Live`;
	const format = cleanStr(body.format, MAX_FORMAT) || 'open mic';
	const voice = cleanStr(body.voice, 40) || 'nova';
	const splitBps = normalizeSplitBps(body.tipSplitBps);
	const nextShowAt = parseFutureDate(body.nextShowAt);

	// Provision the host agent's wallet now (authenticated owner) so the tip target
	// exists before anyone can tip. Idempotent.
	let hostWallet = null;
	try {
		const w = await ensureAgentWallet(agent.id, session.id, { reason: 'stage_create' });
		hostWallet = w?.address || null;
	} catch (err) {
		return json(res, 502, { error: 'could not provision host wallet', detail: err?.message });
	}

	const [row] = await sql`
		INSERT INTO stages (agent_id, owner_user_id, venue, title, format, voice, tip_split_bps, status, next_show_at)
		VALUES (${agent.id}, ${session.id}, ${venue}, ${title}, ${format}, ${voice}, ${splitBps}, 'scheduled', ${nextShowAt})
		ON CONFLICT (agent_id) DO UPDATE SET
			-- A stage bound to a coin world's plaza stays a plaza: editing its copy
			-- through the generic create path must not silently move the venue out
			-- from under the world that renders it.
			venue = CASE WHEN stages.coin_mint IS NOT NULL THEN 'plaza' ELSE EXCLUDED.venue END,
			title = EXCLUDED.title, format = EXCLUDED.format,
			voice = EXCLUDED.voice, tip_split_bps = EXCLUDED.tip_split_bps,
			next_show_at = EXCLUDED.next_show_at, status = 'scheduled', updated_at = NOW()
		RETURNING *
	`;
	return json(res, 201, { ok: true, stage: shapeStage(row), hostWallet });
}

// Claim a /play coin world's plaza for an agent you own (F17). The row is written
// AT the derived plaza id, which is what makes the world able to find the show
// without a lookup: the client computes the same uuidv5 from the mint it is
// standing in and joins that stage_world room. Idempotent for the same agent, so
// re-claiming just updates the venue copy.
async function claimPlaza(req, res, session, body) {
	const agent = await ownedAgent(body.agentId, session.id);
	if (!agent) return json(res, 403, { error: 'you do not own this agent' });

	const mint = cleanMint(body.coinMint);
	if (!mint) return json(res, 400, { error: 'coinMint is required' });
	const stageId = plazaStageId(mint);

	// The plaza is one venue: whoever holds it holds it until they release it.
	const [held] = await sql`SELECT id, agent_id FROM stages WHERE id = ${stageId} LIMIT 1`;
	if (held && held.agent_id !== agent.id) {
		return json(res, 409, {
			error: 'plaza_taken',
			message: 'another agent already hosts this world\'s plaza stage',
			stageId,
		});
	}
	// One stage per agent (stages_agent_uniq). An agent that already has a stage
	// elsewhere cannot also take a plaza, say so with the id they already own
	// rather than failing on a constraint the caller can't see.
	const [existing] = await sql`SELECT id FROM stages WHERE agent_id = ${agent.id} LIMIT 1`;
	if (existing && existing.id !== stageId) {
		return json(res, 409, {
			error: 'agent_has_stage',
			message: 'this agent already hosts another stage, use a different agent for the plaza',
			stageId: existing.id,
		});
	}

	const title = cleanStr(body.title, MAX_TITLE) || `${agent.name} Live`;
	const format = cleanStr(body.format, MAX_FORMAT) || 'open mic';
	const voice = cleanStr(body.voice, 40) || 'nova';
	const splitBps = normalizeSplitBps(body.tipSplitBps);
	const nextShowAt = parseFutureDate(body.nextShowAt);

	let hostWallet = null;
	try {
		const w = await ensureAgentWallet(agent.id, session.id, { reason: 'stage_plaza' });
		hostWallet = w?.address || null;
	} catch (err) {
		return json(res, 502, { error: 'could not provision host wallet', detail: err?.message });
	}

	const [row] = await sql`
		INSERT INTO stages (id, agent_id, owner_user_id, venue, title, format, voice, tip_split_bps, status, next_show_at, coin_mint)
		VALUES (${stageId}, ${agent.id}, ${session.id}, 'plaza', ${title}, ${format}, ${voice}, ${splitBps}, 'scheduled', ${nextShowAt}, ${mint})
		ON CONFLICT (id) DO UPDATE SET
			title = EXCLUDED.title, format = EXCLUDED.format, voice = EXCLUDED.voice,
			tip_split_bps = EXCLUDED.tip_split_bps, next_show_at = EXCLUDED.next_show_at,
			coin_mint = EXCLUDED.coin_mint, status = 'scheduled', updated_at = NOW()
		RETURNING *
	`;
	return json(res, 201, {
		ok: true,
		stage: shapeStage(row),
		hostWallet,
		link: `/play?coin=${encodeURIComponent(mint)}`,
	});
}

async function goLive(req, res, session, body) {
	const stage = await ownedStage(body.stageId, session.id);
	if (!stage) return json(res, 403, { error: 'you do not own this stage' });

	// Open a show (idempotent via the partial unique index, a second go-live
	// returns the already-open show rather than a duplicate).
	const [show] = await sql`
		INSERT INTO shows (stage_id) VALUES (${stage.id})
		ON CONFLICT (stage_id) WHERE ended_at IS NULL DO UPDATE SET stage_id = EXCLUDED.stage_id
		RETURNING *
	`;
	await sql`UPDATE stages SET status = 'live', updated_at = NOW() WHERE id = ${stage.id}`;

	// Put the show on the owner's bell and ping the ops channel, so a live start is
	// visible without watching the directory.
	insertNotification(session.id, 'stage_live', {
		stage_id: stage.id,
		agent_id: stage.agent_id,
		title: stage.title,
		link: `/stage?id=${stage.id}`,
	});
	sendOpsAlert(
		'Live stage started',
		`"${stage.title}" is live now. /stage?id=${stage.id}`,
		{ signature: `stage-live:${show.id}` },
	);

	return json(res, 200, { ok: true, show: shapeShow(show), link: `/stage?id=${stage.id}` });
}

async function endShow(req, res, session, body) {
	const stage = await ownedStage(body.stageId, session.id);
	if (!stage) return json(res, 403, { error: 'you do not own this stage' });
	const [show] = await sql`
		UPDATE shows SET ended_at = NOW()
		WHERE stage_id = ${stage.id} AND ended_at IS NULL
		RETURNING *
	`;
	await sql`UPDATE stages SET status = 'offline', updated_at = NOW() WHERE id = ${stage.id}`;
	if (!show) return json(res, 200, { ok: true, ended: false, reason: 'no open show' });
	return json(res, 200, { ok: true, show: shapeShow(show) });
}

async function ownedStage(stageId, userId) {
	if (!isUuid(stageId)) return null;
	const [s] = await sql`
		SELECT * FROM stages WHERE id = ${stageId} AND owner_user_id = ${userId} LIMIT 1
	`;
	return s || null;
}

// ── shaping ──────────────────────────────────────────────────────────────────
function shapeStage(s) {
	return {
		id: s.id,
		agent_id: s.agent_id,
		venue: s.venue,
		title: s.title,
		format: s.format,
		voice: s.voice,
		tip_split_bps: s.tip_split_bps,
		status: s.status,
		next_show_at: s.next_show_at ? Date.parse(s.next_show_at) : null,
		host_name: s.agent_name,
		host_avatar: s.avatar_url || s.profile_image_url || null,
		// The /play world this stage stands in, when it is a plaza stage, lets the
		// directory card offer "attend in-world" alongside the /stage venue link.
		coin_mint: s.coin_mint || null,
	};
}

function shapeShow(s) {
	return {
		id: s.id,
		started_at: s.started_at ? Date.parse(s.started_at) : null,
		ended_at: s.ended_at ? Date.parse(s.ended_at) : null,
		peak_audience: s.peak_audience ?? 0,
		total_tips_atomic: Number(s.total_tips_atomic || 0),
		tip_count: s.tip_count ?? 0,
	};
}

// A mint is an identity, never a string to trim into shape: the browser derives
// the plaza stage id from the mint it is standing in, so truncating an over-long
// value here would claim (and read) a DIFFERENT stage than the world joins.
// Reject it instead.
function cleanMint(v) {
	const m = cleanStr(v, MAX_MINT + 1);
	return m.length > MAX_MINT ? '' : m;
}

function cleanStr(v, max) {
	if (typeof v !== 'string') return '';
	return v.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
}

// Parse an epoch-ms or ISO date that must be in the future; otherwise null.
function parseFutureDate(v) {
	if (v == null) return null;
	const ms = typeof v === 'number' ? v : Date.parse(v);
	if (!Number.isFinite(ms) || ms < Date.now()) return null;
	return new Date(ms).toISOString();
}