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.

14.6 KB
Raw Blame
// Live activity feed store, the cross-surface "something is always happening
// here" ticker that makes three.ws feel alive on every page.
//
// Events are produced from many places, a coin buy confirmed in api/pump, an
// agent deployed in api/agents, a level-up or a world-join in the standalone
// multiplayer server, and read by the site-wide widget (public/feed.js) via
// GET /api/feed. Storage is a single capped Redis list `feed:events` ordered
// newest-first.
//
// Like presence-store, the multiplayer server writes to the SAME key directly
// (multiplayer/src/feed.js) rather than calling back through HTTP: Redis is the
// shared bus between the serverless API and the long-running game server. Both
// producers MUST emit the identical event shape documented below.
//
// ── Event shape ──────────────────────────────────────────────────────────────
//   { id, type, ts, actor, ...typeSpecific }
//     id, opaque unique key; the widget de-dupes and uses it as a render key
//     type, one of ALLOWED_TYPES
//     ts, epoch ms
//     actor, short, already-sanitized display label (truncated wallet, player
//             name, agent name). NEVER a raw secret or full address we wouldn't
//             show publicly, this list is world-readable.
//   coin-buy      → { mint, sol, network }
//   agent-deploy  → { agentId, name }, new agent joined the registry (off-chain)
//   agent-onchain → { agentId, name, chain }, agent verified on-chain
//   level-up      → { skill, level, coin }
//   world-join   → { coin, coinName }
//   jackpot      → { reward, coin }
//   mission-complete → { mission, gold, coop, coin }, /play job or heist finished
//   war-result   → { winner, reason, a, b, matchKey, network }, a Coin Wars battle ended; actor is the winning community
//   agora-registered    → { citizenId, agentPda, profession, narrative }, a citizen joined Agora (AgenC registerAgent)
//   agora-task-posted   → { actor, taskPda, profession, rewardLabel, minReputation, cluster }, a bounty was escrowed on the board (createTask)
//   agora-hired         → { actor, taskPda, profession, rewardLabel, cluster }, a citizen hired a sub-agent (agent-to-agent)
//   agora-task-claimed  → { citizenId, agentPda, profession, taskPda, txSig, explorerUrl, narrative }, claimed an on-chain task
//   agora-task-completed→ { citizenId, agentPda, profession, taskPda, proofHash, txSig, explorerUrl, narrative }, proof accepted
//   agora-earned        → { citizenId, agentPda, profession, rewardLabel, txSig, explorerUrl, narrative }, escrow released to the worker
//   agora-arena-entered → { citizenId, agentPda, profession, taskPda, txSig, explorerUrl, narrative }  : joined a Competitive task; first valid proof takes the purse
//   agora-arena-won     → { citizenId, agentPda, profession, taskPda, rewardLabel, txSig, explorerUrl, narrative }  : won an Arena race
//   agora-arena-lost    → { citizenId, agentPda, profession, taskPda, txSig, explorerUrl, narrative }  : another racer proved it first
//   agora-guild-joined  → { citizenId, agentPda, profession, taskPda, txSig, explorerUrl, narrative }  : joined a Collaborative task alongside other citizens
//   agora-guild-contributed → { citizenId, agentPda, profession, taskPda, rewardLabel, txSig, explorerUrl, narrative }  : contributed a proof to a Guild; the pool splits across contributors
//   agora-vouched       → { citizenId, agentPda, profession, taskPda, txSig, explorerUrl, narrative }, a Verifier re-derived a proof and it held
//   agora-flagged       → { citizenId, agentPda, profession, taskPda, txSig, explorerUrl, narrative }, a Verifier re-derived a proof and it did NOT match
//
// All writes are best-effort. The feed is a delight layer, never on a critical
// path: a Redis outage degrades to an empty feed, never a thrown error.

import { env } from './env.js';
import { getRedis } from './redis.js';
import { insertNotification } from './notify.js';

const FEED_KEY = 'feed:events';
const MAX_EVENTS = 200; // capped list, the widget shows ~30; we keep headroom

export const ALLOWED_TYPES = new Set([
	'coin-buy',
	'agent-deploy',
	'agent-onchain',
	'level-up',
	'world-join',
	'jackpot',
	'payment',  // skill/service payment confirmed; { usdcAtomic, recipientLabel, txSig, explorerUrl }
	'mission-complete',  // /play job or co-op heist finished; { mission, gold, coop, coin }
	'member-join',  // a person signed in to three.ws; { handle } (actor = display name)
	'agent-guard',  // an autonomous buy was REFUSED by a safety rule; { agentId, mint, reason, label }, trust made visible
	'war-result',   // a Coin Wars battle ended; { winner, reason, a:{mint,name,symbol,score}, b:{…}, matchKey, network }
	// Agora, the living agent economy (workers/agora-citizens). Each is a real
	// on-chain AgenC action projected onto the ticker; see docs/agora.md.
	'agora-registered',       // a citizen registered on AgenC
	'agora-task-posted',      // a bounty was escrowed on the board (createTask)
	'agora-hired',            // a citizen hired a sub-agent (agent-to-agent)
	'agora-task-claimed',     // a citizen claimed an on-chain task
	'agora-task-completed',   // a citizen submitted an accepted proof
	'agora-earned',           // escrow released $THREE/SOL to the worker
	'agora-arena-entered',    // entered a Competitive task (Arena); winner takes the purse
	'agora-arena-won',        // first valid proof on an Arena task
	'agora-arena-lost',       // another racer proved the Arena task first
	'agora-guild-joined',     // joined a Collaborative task (Guild)
	'agora-guild-contributed',// contributed a proof to a Guild; the pool splits
	'agora-vouched',          // a Verifier re-derived a deliverable's proof, it holds
	'agora-flagged',          // a Verifier re-derived a proof and it did NOT match
]);

// Per-user notification types: stored in user_notifications (DB), never in the
// public feed:events list. Extend here so one place owns the full vocabulary.
export const USER_EVENT_TYPES = new Set([
	'payment-earned',    // agent owner received an x402 payment
	'sale',              // marketplace asset sale
	'embed',             // someone embedded the creator's agent
	'remix',             // someone remixed a creation
	'reply',             // new reply to an agent interaction
	'follow',            // someone followed you; { actor, follower_username, link }
	'agent_review',      // someone reviewed your agent; { actor, agent_id, agent_name, rating, link }
	'comment',           // someone commented on your model; { actor, creation_id, preview, link }
	'dm_received',       // a friend sent you a DM while you were away; { actor, link }
	'pump_launch_filled',// a launch you own graduated its bonding curve; { name, mint, link }
	'quest_complete',    // a /play mission or co-op heist you finished; { mission, gold, coop, link }
	'royalty_paid',      // a fork of your avatar paid an upstream royalty; { actor, sol, usd, depth, signature, link }
	// types already produced by purchase-confirm / buy-asset confirm flows
	'skill_purchased',
	'skill_purchase_confirmed',
	'asset_purchased',
	'asset_purchase_confirmed',
	'asset_payment_mismatch',
	'skill_payment_mismatch',
	'referral_earned',
	// Materialize: one type for the whole print lifecycle, carrying the status
	// and, once the box ships, its certificate link.
	'print_update',
]);

function redis() { return getRedis(); }

let _seq = 0;
// A sortable, collision-resistant id: a base36 timestamp prefix plus a per-
// process counter so two events in the same millisecond still differ.
function eventId(ts) {
	_seq = (_seq + 1) % 1_000_000;
	return `${ts.toString(36)}-${_seq.toString(36)}`;
}

// Publish a per-user notification event. Writes to user_notifications (DB),
// never to the public feed:events list. Preserves the shared event shape
// { id, type, ts, actor, ...typeSpecific } plus `read` flag and a `link` for
// click-through. Fire-and-forget: never throws.
//
// @param {string} userId, recipient's user id
// @param {object} event, { type (USER_EVENT_TYPES), actor, link, ...rest }
export function publishUserEvent(userId, event) {
	if (!userId || !event || !USER_EVENT_TYPES.has(event.type)) return;
	const ts = Number.isFinite(event.ts) ? event.ts : Date.now();
	const payload = {
		...event,
		ts,
		id: event.id || eventId(ts),
		link: event.link || null,
	};
	insertNotification(userId, event.type, payload);
}

// Append an event to the feed. Returns the stored record (with id + ts filled
// in) or null on a no-op (unknown type, Redis down, malformed input). Never
// throws, every caller is fire-and-forget on a non-critical path.
export async function publishFeedEvent(event) {
	const r = redis();
	if (!r || !event || !ALLOWED_TYPES.has(event.type)) return null;
	const ts = Number.isFinite(event.ts) ? event.ts : Date.now();
	const record = { ...event, ts, id: event.id || eventId(ts) };
	try {
		await r.lpush(FEED_KEY, JSON.stringify(record));
		await r.ltrim(FEED_KEY, 0, MAX_EVENTS - 1);
		return record;
	} catch (err) {
		console.warn('[feed] publish failed:', err?.message);
		return null;
	}
}

/**
 * Convenience wrapper: publish a 'payment' feed event from a confirmed skill/service payment.
 * All params best-effort; the event is fire-and-forget on a non-critical path.
 *
 * @param {object} opts
 * @param {string}  opts.actor          short display label (truncated wallet / agent name)
 * @param {number}  [opts.usdcAtomic]   payment amount in micro-USDC (1e6 scale)
 * @param {string}  [opts.recipientLabel]  "Luna's creator", "Oracle", etc.
 * @param {string}  [opts.txSig]        Solana tx signature
 * @param {string}  [opts.explorerUrl]  full Solscan/explorer URL
 */
/**
 * Convenience wrapper: publish an 'agent-guard' event when a safety rule refuses
 * an autonomous buy (a mayhem-mode coin, a rug/honeypot firewall block). Surfacing
 * these makes the platform's safety work visible in the live tape instead of
 * silent. Fire-and-forget; unknown/empty input is a safe no-op.
 *
 * @param {object} opts
 * @param {string} opts.actor    the agent's display name
 * @param {string} [opts.agentId]
 * @param {string} [opts.mint]   the coin that was refused
 * @param {string} opts.reason   machine code ('mayhem' | 'firewall_blocked')
 * @param {string} opts.label    human-readable one-liner for the tape
 */
export function pushGuardEvent({ actor, agentId, mint, reason, label } = {}) {
	if (!reason) return null;
	return publishFeedEvent({
		type: 'agent-guard',
		actor: String(actor || 'Agent').slice(0, 32),
		agentId: agentId ? String(agentId).slice(0, 64) : undefined,
		mint: mint ? String(mint).slice(0, 64) : undefined,
		reason: String(reason).slice(0, 32),
		label: label ? String(label).slice(0, 80) : undefined,
	});
}

export function pushPaymentEvent({ actor, usdcAtomic, recipientLabel, txSig, explorerUrl } = {}) {
	return publishFeedEvent({
		type: 'payment',
		actor: String(actor || 'user').slice(0, 32),
		usdcAtomic: usdcAtomic != null ? Number(usdcAtomic) : undefined,
		recipientLabel: recipientLabel ? String(recipientLabel).slice(0, 40) : undefined,
		txSig: txSig ? String(txSig).slice(0, 88) : undefined,
		explorerUrl: explorerUrl ? String(explorerUrl).slice(0, 200) : undefined,
	});
}

// Per-user throttle window for member-join events. A returning user signs in
// often; we only want one "joined" line per person per window so the feed shows
// real arrivals without spamming on every login or popup re-auth.
const MEMBER_JOIN_TTL_S = 6 * 60 * 60; // 6h

/**
 * Publish a 'member-join' feed event when someone signs in, throttled to once
 * per `userKey` per MEMBER_JOIN_TTL_S so re-logins don't spam the ticker.
 * Best-effort and fire-and-forget, never throws, returns the stored record or
 * null (throttled / Redis down / no display name).
 *
 * @param {object} opts
 * @param {string} opts.userKey  stable per-user key for throttling (id or handle)
 * @param {string} opts.actor    short public display name ("alice")
 * @param {string} [opts.handle] X/social handle without '@', for click-through
 */
export async function publishMemberJoin({ userKey, actor, handle } = {}) {
	const r = redis();
	const name = String(actor || '').trim().slice(0, 32);
	if (!r || !name) return null;
	const key = String(userKey || handle || name).slice(0, 80);
	try {
		// SET NX EX: claims the window atomically; null reply means already seen.
		const claimed = await r.set(`feed:joined:${key}`, '1', { nx: true, ex: MEMBER_JOIN_TTL_S });
		if (!claimed) return null;
	} catch (err) {
		console.warn('[feed] member-join throttle check failed:', err?.message);
		return null;
	}
	return publishFeedEvent({
		type: 'member-join',
		actor: name,
		handle: handle ? String(handle).replace(/^@/, '').slice(0, 40) : undefined,
	});
}

// Short-lived in-process read cache. The widget is mounted on every page and
// polls this endpoint continuously, so without dedup each poll becomes a Redis
// command, at platform scale that alone can exhaust the Upstash request quota.
// A warm serverless instance serving a burst of polls reuses one underlying
// read for READ_CACHE_MS; we always fetch the top CACHE_N (cheap, one command
// regardless of count) and slice per caller, so every limit ≤ CACHE_N is served
// from the same cached array. This bounds Redis reads to ~one per instance per
// window instead of one per client poll. The feed is a delight layer, so a few
// seconds of staleness is invisible.
const READ_CACHE_MS = 8_000;
const CACHE_N = 60; // ≥ any limit the widget requests (30) with headroom
let _readCache = { at: 0, events: [] };

// Read the most recent events, newest-first. `limit` is clamped to
// [1, MAX_EVENTS]. Returns [] on a Redis outage so the widget renders its empty
// state rather than surfacing an error to the user.
export async function readFeedEvents(limit = 30) {
	const r = redis();
	if (!r) return [];
	const n = Math.max(1, Math.min(MAX_EVENTS, Math.floor(Number(limit)) || 30));

	// Serve from the in-process cache when fresh and large enough.
	if (n <= CACHE_N && Date.now() - _readCache.at < READ_CACHE_MS) {
		return _readCache.events.slice(0, n);
	}

	const want = Math.max(n, CACHE_N);
	try {
		const rows = await r.lrange(FEED_KEY, 0, want - 1);
		const out = [];
		for (const row of rows || []) {
			// Upstash auto-deserializes JSON-looking values; tolerate both shapes.
			const obj = typeof row === 'string' ? safeParse(row) : row;
			if (obj && typeof obj === 'object' && obj.type) out.push(obj);
		}
		if (want >= CACHE_N) _readCache = { at: Date.now(), events: out.slice(0, CACHE_N) };
		return out.slice(0, n);
	} catch (err) {
		console.warn('[feed] read failed:', err?.message);
		return [];
	}
}

function safeParse(s) {
	try {
		return JSON.parse(s);
	} catch {
		return null;
	}
}