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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Agent duel challenges: one agent owner calls out another agent to a duel.
// ---------------------------------------------------------------------------
// The rivalry engine (api/_lib/trader-duels.js) only ever pairs traders that sit
// next to each other on the 30-day board. A challenge lets an owner pick the
// opponent instead:
//
// challenge the owner of agent A challenges agent B (someone else's public
// agent) to a duel over the next day or week window. B's owner is
// notified through insertNotification (bell, push, paired chats).
// respond B's owner accepts or declines; A's owner can withdraw while it is
// pending. Accepting opens a regular duel_markets row for the next
// window, tagged context.source = 'challenge', so the rivalry
// generator leaves that window's own pairings alone. When the pair
// already has a duel in that window the challenge links to it.
// expire a challenge nobody answered within 48 hours expires
// (/api/cron/duels-tick).
// resolve the existing duel engine: realized P&L inside the window decides
// it, and anyone who owns neither trader can call it for points.
//
// Points only, like every duel: nothing here moves a token or touches a wallet.
// challengeLeaderboard ranks agents by their record in challenge duels.
import { sql } from './db.js';
import { insertNotification } from './notify.js';
import { nextWindow, getDuel, duelPhase } from './trader-duels.js';
import { isUuid } from './validate.js';
export const CHALLENGE_NETWORK = 'mainnet';
export const CHALLENGE_WINDOWS = Object.freeze(['day', 'week']);
export const CHALLENGE_STATUSES = Object.freeze(['pending', 'accepted', 'declined', 'expired', 'cancelled']);
export const CHALLENGE_TTL_HOURS = 48;
export const MAX_PENDING_PER_USER = 20;
export const MAX_MESSAGE = 280;
const PG_UNIQUE = '23505';
const iso = (v) => (v == null ? null : new Date(v).toISOString());
const n = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
/** A designed refusal: a stable code, a sentence for the caller, an HTTP-ish status. */
export class DuelChallengeError extends Error {
constructor(code, message, status = 400) {
super(message);
this.code = code;
this.status = status;
}
}
async function agentsById(ids) {
const list = ids.filter(isUuid);
if (!list.length) return new Map();
const rows = await sql`
select id, user_id, name, is_public, deleted_at
from agent_identities where id = any(${list}::uuid[])
`;
return new Map(rows.map((r) => [r.id, r]));
}
const isAvailable = (a) => !!a && a.deleted_at == null && a.is_public !== false;
/** The public shape of one challenge row, from the viewer's side. PURE. */
export function challengeView(row, viewerId = null) {
const role = viewerId && row.challenger_user === viewerId ? 'challenger'
: viewerId && row.challenged_user === viewerId ? 'challenged'
: null;
return {
id: row.id,
status: row.status,
network: row.network,
window_kind: row.window_kind,
challenger: { agent_id: row.challenger_agent, name: row.challenger_name || null },
challenged: { agent_id: row.challenged_agent, name: row.challenged_name || null },
message: row.message || null,
market_id: row.market_id || null,
duel_url: row.market_id ? `/duels/${row.market_id}` : null,
expires_at: iso(row.expires_at),
created_at: iso(row.created_at),
responded_at: iso(row.responded_at),
your_role: role,
can_respond: role === 'challenged' && row.status === 'pending',
can_cancel: role === 'challenger' && row.status === 'pending',
};
}
const challengeColumns = () => sql`
c.id, c.network, c.window_kind, c.challenger_agent, c.challenger_user, c.challenged_agent,
c.challenged_user, c.message, c.status, c.market_id, c.expires_at, c.created_at, c.responded_at,
ca.name as challenger_name, cb.name as challenged_name
`;
async function loadChallenge(id) {
if (!isUuid(id)) return null;
const [row] = await sql`
select ${challengeColumns()}
from agent_duel_challenges c
left join agent_identities ca on ca.id = c.challenger_agent
left join agent_identities cb on cb.id = c.challenged_agent
where c.id = ${id}
`;
return row || null;
}
/** Challenge another owner's public agent to a duel over the next window. */
export async function createChallenge({ userId, challengerAgentId, challengedAgentId, windowKind = 'day', message = null, now = Date.now() }) {
if (!CHALLENGE_WINDOWS.includes(windowKind)) throw new DuelChallengeError('invalid_window', 'window must be day or week.');
if (!isUuid(challengerAgentId) || !isUuid(challengedAgentId)) throw new DuelChallengeError('invalid_agent', 'Both agent ids must be UUIDs.');
if (challengerAgentId === challengedAgentId) throw new DuelChallengeError('same_agent', 'An agent cannot duel itself.');
const text = message == null ? null : String(message).trim().slice(0, MAX_MESSAGE) || null;
const agents = await agentsById([challengerAgentId, challengedAgentId]);
const me = agents.get(challengerAgentId);
const them = agents.get(challengedAgentId);
if (!me || me.deleted_at != null || me.user_id !== userId) {
throw new DuelChallengeError('not_your_agent', 'You can only challenge with an agent you own.', 403);
}
if (me.is_public === false) {
throw new DuelChallengeError('agent_private', `${me.name} is private. Duels are public, so make it public before challenging.`, 409);
}
if (!isAvailable(them)) throw new DuelChallengeError('opponent_unavailable', 'That agent does not exist or is not public.', 404);
if (them.user_id === userId) {
throw new DuelChallengeError('own_opponent', 'Both agents are yours. Challenge an agent someone else owns.', 409);
}
const w = nextWindow(windowKind, now);
const [existing] = await sql`
select id from duel_markets
where network = ${CHALLENGE_NETWORK} and window_kind = ${windowKind} and window_start = ${iso(w.start)}
and least(agent_a, agent_b) = least(${challengerAgentId}::uuid, ${challengedAgentId}::uuid)
and greatest(agent_a, agent_b) = greatest(${challengerAgentId}::uuid, ${challengedAgentId}::uuid)
`;
if (existing) {
throw new DuelChallengeError('already_paired', `These two already duel in that window: /duels/${existing.id}`, 409);
}
const [reverse] = await sql`
select id from agent_duel_challenges
where status = 'pending' and expires_at > now() and network = ${CHALLENGE_NETWORK} and window_kind = ${windowKind}
and challenger_agent = ${challengedAgentId} and challenged_agent = ${challengerAgentId}
`;
if (reverse) {
throw new DuelChallengeError('already_challenged_you', `${them.name} already challenged ${me.name} for that window. Accept challenge ${reverse.id} instead.`, 409);
}
const [{ c: pending }] = await sql`
select count(*)::int as c from agent_duel_challenges where challenger_user = ${userId} and status = 'pending' and expires_at > now()
`;
if (pending >= MAX_PENDING_PER_USER) {
throw new DuelChallengeError('too_many_pending', `You have ${pending} unanswered challenges out. Wait for answers or withdraw some first.`, 409);
}
let row;
try {
[row] = await sql`
insert into agent_duel_challenges
(network, window_kind, challenger_agent, challenger_user, challenged_agent, challenged_user, message, expires_at)
values (${CHALLENGE_NETWORK}, ${windowKind}, ${challengerAgentId}, ${userId}, ${challengedAgentId}, ${them.user_id},
${text}, now() + make_interval(hours => ${CHALLENGE_TTL_HOURS}))
returning id
`;
} catch (err) {
if (err?.code === PG_UNIQUE) throw new DuelChallengeError('already_pending', `${me.name} already has a pending ${windowKind} challenge out to ${them.name}.`, 409);
throw err;
}
const window = windowKind === 'day' ? 'tomorrow (UTC)' : 'next week';
const delivered = await insertNotification(them.user_id, 'duel_challenge', {
summary: `${me.name} challenged your agent ${them.name} to a duel ${window}${text ? `: "${text}"` : ''}`,
challenge_id: row.id,
challenger: me.name,
challenged: them.name,
window_kind: windowKind,
link: '/duels',
});
const view = challengeView(await loadChallenge(row.id), userId);
return { ...view, notified: { bell: !!delivered?.in_app, ...(delivered?.delivered || {}) } };
}
/**
* Answer a pending challenge. `accept` and `decline` are for the challenged
* agent's owner, `cancel` for the challenger's. Accepting opens the duel.
*/
export async function respondChallenge({ userId, challengeId, response, now = Date.now() }) {
if (!['accept', 'decline', 'cancel'].includes(response)) throw new DuelChallengeError('invalid_response', 'response must be accept, decline or cancel.');
const row = await loadChallenge(challengeId);
if (!row || (row.challenger_user !== userId && row.challenged_user !== userId)) {
throw new DuelChallengeError('not_found', 'No challenge with that id involves your agents.', 404);
}
if (row.status !== 'pending') {
throw new DuelChallengeError('not_pending', `This challenge is already ${row.status}.`, 409);
}
if (new Date(row.expires_at).getTime() <= now) {
await expireChallenges();
throw new DuelChallengeError('expired', 'This challenge expired before it was answered.', 409);
}
if (response === 'cancel' && row.challenger_user !== userId) {
throw new DuelChallengeError('not_challenger', 'Only the challenger can withdraw a challenge. Decline it instead.', 403);
}
if (response !== 'cancel' && row.challenged_user !== userId) {
throw new DuelChallengeError('not_challenged', 'Only the challenged agent\'s owner can accept or decline. You can cancel it.', 403);
}
if (response !== 'accept') {
const status = response === 'cancel' ? 'cancelled' : 'declined';
const [done] = await sql`
update agent_duel_challenges set status = ${status}, responded_at = now()
where id = ${row.id} and status = 'pending' returning id
`;
if (!done) throw new DuelChallengeError('not_pending', 'This challenge was answered a moment ago.', 409);
if (status === 'declined') {
await insertNotification(row.challenger_user, 'duel_challenge', {
summary: `${row.challenged_name} declined ${row.challenger_name}'s duel challenge`,
challenge_id: row.id,
link: '/duels',
});
}
return { challenge: challengeView(await loadChallenge(row.id), userId), duel: null };
}
const agents = await agentsById([row.challenger_agent, row.challenged_agent]);
const a = agents.get(row.challenger_agent);
const b = agents.get(row.challenged_agent);
if (!isAvailable(a) || !isAvailable(b)) {
throw new DuelChallengeError('agent_unavailable', 'One of these agents is no longer public, so the duel cannot open.', 409);
}
const w = nextWindow(row.window_kind, now);
const context = {
source: 'challenge',
challenge_id: row.id,
headline: `${a.name} challenged ${b.name}`,
subline: row.message || `A ${row.window_kind === 'day' ? '24-hour' : 'week-long'} head-to-head on realized P&L, called by the crowd for points.`,
a: { agent_id: a.id, name: a.name },
b: { agent_id: b.id, name: b.name },
};
// Claim the challenge and open the duel in one statement, so two accepts
// racing each other open at most one market.
const [claimed] = await sql`
with c as (
update agent_duel_challenges set status = 'accepted', responded_at = now()
where id = ${row.id} and status = 'pending' and expires_at > now()
returning id
),
m as (
insert into duel_markets (network, window_kind, window_start, window_end, agent_a, agent_b, agent_a_name, agent_b_name, context)
select ${row.network}, ${row.window_kind}, ${iso(w.start)}, ${iso(w.end)}, ${a.id}::uuid, ${b.id}::uuid,
${a.name}, ${b.name}, ${JSON.stringify(context)}::jsonb
from c
on conflict do nothing
returning id
)
select (select id from c) as challenge_id, (select id from m) as market_id
`;
if (!claimed?.challenge_id) throw new DuelChallengeError('not_pending', 'This challenge was answered a moment ago.', 409);
let marketId = claimed.market_id;
if (!marketId) {
// The rivalry engine already paired them for this window: the challenge is that duel.
const [same] = await sql`
select id from duel_markets
where network = ${row.network} and window_kind = ${row.window_kind} and window_start = ${iso(w.start)}
and least(agent_a, agent_b) = least(${a.id}::uuid, ${b.id}::uuid)
and greatest(agent_a, agent_b) = greatest(${a.id}::uuid, ${b.id}::uuid)
`;
marketId = same?.id || null;
}
await sql`update agent_duel_challenges set market_id = ${marketId} where id = ${row.id}`;
await insertNotification(row.challenger_user, 'duel_challenge', {
summary: `${b.name} accepted ${a.name}'s duel challenge. The window opens ${new Date(w.start).toUTCString()}.`,
challenge_id: row.id,
link: marketId ? `/duels/${marketId}` : '/duels',
});
const duel = marketId ? await getDuel(marketId, { userId, now }) : null;
return { challenge: challengeView(await loadChallenge(row.id), userId), duel };
}
/** One challenge, visible to either side. Includes the duel once accepted. */
export async function getChallenge({ userId, challengeId, now = Date.now() }) {
const row = await loadChallenge(challengeId);
if (!row || (row.challenger_user !== userId && row.challenged_user !== userId)) return null;
const view = challengeView(row, userId);
const duel = row.market_id ? await getDuel(row.market_id, { userId, now }) : null;
return { challenge: view, duel };
}
/** The caller's challenges. direction: incoming, outgoing, all. */
export async function listChallenges({ userId, direction = 'all', status = null, limit = 25 }) {
const dirSql = direction === 'incoming' ? sql`c.challenged_user = ${userId}`
: direction === 'outgoing' ? sql`c.challenger_user = ${userId}`
: sql`(c.challenged_user = ${userId} or c.challenger_user = ${userId})`;
const statusSql = status && CHALLENGE_STATUSES.includes(status) ? sql`and c.status = ${status}` : sql``;
const rows = await sql`
select ${challengeColumns()}
from agent_duel_challenges c
left join agent_identities ca on ca.id = c.challenger_agent
left join agent_identities cb on cb.id = c.challenged_agent
where ${dirSql} ${statusSql}
order by (c.status = 'pending') desc, c.created_at desc
limit ${Math.max(1, Math.min(100, n(limit) || 25))}
`;
return rows.map((r) => challengeView(r, userId));
}
/** Flip every pending challenge past its deadline to expired. Returns the count. */
export async function expireChallenges() {
const rows = await sql`
update agent_duel_challenges set status = 'expired', responded_at = now()
where status = 'pending' and expires_at <= now()
returning id
`;
return rows.length;
}
/**
* Rank agents by their record in challenge duels: wins, losses and voids over
* every settled duel that came from a challenge, with the realized P&L each
* booked inside those windows. Ties break on fewer losses, then more decided.
*/
export async function challengeLeaderboard({ limit = 25, agentId = null } = {}) {
const rows = await sql`
with sides as (
select m.agent_a as agent_id, m.status, m.winner = 'a' as won, m.winner = 'b' as lost,
(m.result -> 'a' ->> 'pnl_sol')::numeric as pnl_sol, m.resolved_at
from duel_markets m
where m.network = ${CHALLENGE_NETWORK} and m.context ->> 'source' = 'challenge'
and m.status in ('resolved','void') and m.agent_a is not null
union all
select m.agent_b, m.status, m.winner = 'b', m.winner = 'a',
(m.result -> 'b' ->> 'pnl_sol')::numeric, m.resolved_at
from duel_markets m
where m.network = ${CHALLENGE_NETWORK} and m.context ->> 'source' = 'challenge'
and m.status in ('resolved','void') and m.agent_b is not null
),
agg as (
select agent_id,
count(*) filter (where won)::int as wins,
count(*) filter (where lost)::int as losses,
count(*) filter (where status = 'void')::int as voids,
coalesce(sum(pnl_sol), 0)::float8 as pnl_sol,
max(resolved_at) as last_duel_at
from sides group by agent_id
),
ranked as (
select agg.*, rank() over (order by wins desc, losses asc, (wins + losses) desc) as rank
from agg join agent_identities a on a.id = agg.agent_id
where a.deleted_at is null and a.is_public is not false
)
select r.*, a.name from ranked r join agent_identities a on a.id = r.agent_id
where r.rank <= ${limit} or r.agent_id = ${agentId}
order by r.rank asc, a.name asc
`;
const [counts] = await sql`
select count(*) filter (where status = 'pending' and expires_at > now())::int as pending,
count(*) filter (where status = 'accepted')::int as accepted
from agent_duel_challenges where network = ${CHALLENGE_NETWORK}
`;
const shape = (r) => ({
rank: n(r.rank),
agent_id: r.agent_id,
name: r.name,
trader: `/trader/${r.agent_id}`,
wins: n(r.wins),
losses: n(r.losses),
voids: n(r.voids),
decided: n(r.wins) + n(r.losses),
win_rate: n(r.wins) + n(r.losses) ? n(r.wins) / (n(r.wins) + n(r.losses)) : null,
realized_pnl_sol: Number(n(r.pnl_sol).toFixed(6)),
last_duel_at: iso(r.last_duel_at),
});
const all = rows.map(shape);
return {
leaders: all.filter((r) => r.rank <= limit),
agent: agentId ? all.find((r) => r.agent_id === agentId) || null : undefined,
challenges: { pending: n(counts?.pending), accepted: n(counts?.accepted) },
};
}
/** Challenge duels that are open or live, newest window first. */
export async function listChallengeDuels({ limit = 25, now = Date.now() } = {}) {
const rows = await sql`
select id, window_kind, window_start, window_end, status, agent_a_name, agent_b_name, winner, context
from duel_markets
where network = ${CHALLENGE_NETWORK} and context ->> 'source' = 'challenge'
order by (status = 'open') desc, window_start desc
limit ${limit}
`;
return rows.map((m) => ({
id: m.id,
url: `/duels/${m.id}`,
label: `${m.agent_a_name} vs ${m.agent_b_name}`,
window_kind: m.window_kind,
window_start: iso(m.window_start),
window_end: iso(m.window_end),
phase: duelPhase(m, now),
winner: m.winner ? (m.winner === 'a' ? m.agent_a_name : m.agent_b_name) : null,
challenge_id: m.context?.challenge_id || null,
}));
}