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
// Clip Director, the content engine (pumpfun-trading-wedge §2.2 / §4.4).
// ---------------------------------------------------------------------------
// "We're a media company that happens to trade." Every notable close emits a
// piece of content: a ticker, a multiple, an avatar reaction, and a REASON. This
// module turns ONE real closed trade into the optimal shareable artifact per
// surface (X / Telegram / in-app Feed), the acquisition channel, not a nicety.
//
// It never invents a number: every stat traces to the closed round-trip it was
// handed. Losses get an honest card too (downside-transparency is the brand),
// never hidden. The LLM (free-first llmComplete chain) writes the copy; a
// deterministic director produces the same-shaped artifact when no provider is
// available, so the engine never fails.
//
// The avatar_gesture resolves to a REAL animation clip in the manifest so the
// arena / trader avatar can actually perform the reaction, not just label it.
import { llmComplete, llmConfigured, LlmUnavailableError } from './llm.js';
import { extractJson } from './bounty-judge.js';
export const SURFACES = new Set(['x', 'telegram', 'feed']);
// §4.4 gesture vocabulary -> a real playable clip in public/animations/manifest.json.
// "sweat" has no dedicated clip; the honest loss reaction is `defeated`.
const GESTURE_CLIP = {
celebrate: 'celebrate',
point: 'point',
wave: 'wave',
shrug: 'shrug',
sweat: 'defeated',
};
const GESTURES = Object.keys(GESTURE_CLIP);
const round2 = (x) => Math.round(x * 100) / 100;
const SYSTEM_PROMPT = `You turn ONE closed trade into the optimal shareable artifact for one surface. You are a content director, not a trader. Truthful, human, no hype, no price predictions.
Output STRICT JSON only, no prose, no code fence:
{ "hook": "<=80 chars, the scroll-stopping first line, true",
"feature_stat": "the single most compelling REAL number to headline",
"avatar_gesture": "celebrate|shrug|sweat|point|wave",
"body": "1-2 lines: what happened + why, plain language",
"cta": "fork-this-trade|copy-the-agent|view-track-record",
"alt_text": "accessibility description of the card" }
Rules: feature the real number. If the trade was a LOSS, still produce an honest card (brand = transparency) with a 'live to trade again' tone. Tune length/voice to the surface (X punchier, Telegram chattier, Feed mid). Name NO ticker other than the traded one. Always keep a verifiable angle (the record is on-chain). State NO number that is not in the input: every figure you write is machine-checked against the trade, and a card that states a ticker or a number the trade does not contain is discarded.`;
// Build the compact, real trade view the director reasons over. Accepts a raw
// agent_sniper_positions row (or an equivalent object) and derives only from
// present fields, hold time, multiple, realized P&L, never fabricating mcap.
export function tradeFromPosition(pos) {
const LAMPORTS = 1e9;
const lam = (v) => (v == null ? null : Number(v) / LAMPORTS);
const entrySol = lam(pos.entry_quote_lamports);
const exitSol = lam(pos.exit_quote_lamports);
const pnlSol = lam(pos.realized_pnl_lamports);
const multiple = entrySol && exitSol != null && entrySol > 0 ? round2(exitSol / entrySol) : null;
const pnlPct = pos.realized_pnl_pct != null ? round2(Number(pos.realized_pnl_pct)) : null;
let holdMin = null;
if (pos.opened_at && pos.closed_at) {
holdMin = Math.max(0, Math.round((new Date(pos.closed_at) - new Date(pos.opened_at)) / 60000));
}
return {
mint: pos.mint,
symbol: pos.symbol || null,
name: pos.name || null,
multiple,
pnl_pct: pnlPct,
entry_sol: entrySol == null ? null : round2(entrySol),
exit_sol: exitSol == null ? null : round2(exitSol),
realized_pnl_sol: pnlSol == null ? null : round2(pnlSol),
hold_min: holdMin,
exit_reason: pos.exit_reason || null,
quote_symbol: 'SOL',
is_win: pnlSol != null ? pnlSol >= 0 : (pnlPct != null ? pnlPct >= 0 : null),
sell_sig: pos.sell_sig || null,
};
}
export async function directClip({ agentName, avatarStyle = null, trade, copiedByCount = 0, surface = 'feed', userId = null } = {}) {
const surf = SURFACES.has(surface) ? surface : 'feed';
if (llmConfigured()) {
try {
const written = await llmClip({ agentName, avatarStyle, trade, copiedByCount, surface: surf, userId });
if (written) {
// The model writes the voice, never the facts. Check the FINALIZED
// card, not the raw artifact: finalize clamps the copy, and a clamp
// landing mid-number is its own way of shipping a figure the trade
// never contained.
const candidate = finalize({ artifact: written, source: 'llm', trade, surface: surf });
if (isGrounded(candidate, trade, { copiedByCount, agentName })) return candidate;
}
} catch (err) {
if (err instanceof LlmUnavailableError) { /* the deterministic director answers */ }
}
}
return finalize({
artifact: deterministicClip({ agentName, trade, copiedByCount, surface: surf }),
source: 'deterministic',
trade,
surface: surf,
});
}
async function llmClip({ agentName, avatarStyle, trade, copiedByCount, surface, userId }) {
const input = {
agent_name: agentName || 'the agent',
avatar_style: avatarStyle || 'default',
trade: {
symbol: trade.symbol || trade.name || trade.mint?.slice(0, 6),
multiple: trade.multiple,
pnl_pct: trade.pnl_pct,
entry_sol: trade.entry_sol,
exit_sol: trade.exit_sol,
hold_min: trade.hold_min,
exit_reason: trade.exit_reason,
realized_pnl_quote: trade.realized_pnl_sol,
quote_symbol: trade.quote_symbol,
is_win: trade.is_win,
},
copied_by_count: copiedByCount,
surface,
};
const out = await llmComplete({
system: SYSTEM_PROMPT,
user: JSON.stringify(input),
maxTokens: 600,
timeoutMs: 25_000,
track: userId ? { userId, tool: 'clip-director' } : null,
});
const parsed = extractJson(out?.text);
if (!parsed || typeof parsed.hook !== 'string') return null;
return parsed;
}
// ---------------------------------------------------------------------------
// Grounding: the one guarantee this page sells is "the real number, never a
// screenshot", so a generated card is checked against the trade it claims to
// describe before it is allowed out. This is not hypothetical: a provider in the
// chain answered a real +1.89x win on one coin with "-8.2% realized loss" on a
// completely different ticker, gesture "celebrate", every word fluent and every
// fact invented. Nothing downstream could have caught that. An artifact that
// names a foreign ticker or states a figure absent from the trade is rejected
// and the deterministic director answers instead.
// ---------------------------------------------------------------------------
/** @returns {string} the trade's ticker, no leading $, uppercase. */
function tickerOf(trade) {
const sym = trade.symbol || trade.name || (trade.mint ? trade.mint.slice(0, 4) : '');
return String(sym).replace(/^\$/, '').toUpperCase();
}
// Same rounding the API renders with, so "1.89" written by the model matches the
// 1.89 the card shows rather than a raw 1.8899999.
const normNum = (n) => String(Math.round(n * 100) / 100);
function groundedNumbers(trade, copiedByCount) {
const ok = new Set();
const add = (n) => {
if (n == null || !Number.isFinite(Number(n))) return;
const v = Number(n);
ok.add(normNum(v));
ok.add(normNum(Math.abs(v)));
ok.add(normNum(Math.round(v)));
};
add(trade.multiple);
add(trade.pnl_pct);
add(trade.entry_sol);
add(trade.exit_sol);
add(trade.realized_pnl_sol);
add(trade.hold_min);
// holdLabel renders the same duration in minutes, hours, or days; all three
// readings are the same real fact.
if (trade.hold_min != null && Number.isFinite(Number(trade.hold_min))) {
add(Math.round(Number(trade.hold_min) / 60));
add(Math.round(Number(trade.hold_min) / 1440));
}
add(copiedByCount);
return ok;
}
const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
/**
* Does every ticker and every number in the copy trace to this trade?
*
* Scope: `$TICKER` mentions and stated figures, which is what the observed
* failure got wrong and what a reader checks against the proof link. A bare
* capitalised word is not treated as a ticker; matching every capitalised noun
* would reject honest copy far more often than it would catch a lie.
*
* @param {object} artifact the generated card (raw artifact or finalized clip)
* @param {object} trade the real closed round-trip
* @param {{copiedByCount?: number, agentName?: string}} ctx the follower count is
* the one figure allowed from outside the trade; the agent's name is passed so
* a trader called "Swarm 2" does not read as an invented number
* @returns {boolean}
*/
export function isGrounded(artifact, trade, { copiedByCount = 0, agentName = '' } = {}) {
const copy = [artifact.hook, artifact.feature_stat, artifact.body, artifact.alt_text]
.filter((s) => typeof s === 'string').join(' ');
if (!copy.trim()) return false;
const allowedTickers = new Set([tickerOf(trade), String(trade.symbol || ''), String(trade.name || '')]
.filter(Boolean).map((t) => t.replace(/^\$/, '').toUpperCase()));
for (const m of copy.matchAll(/\$([A-Za-z][A-Za-z0-9_]*)/g)) {
if (!allowedTickers.has(m[1].toUpperCase())) return false;
}
// Names are stripped before digits are read, so a symbol like $W3B and an
// agent named "Swarm 2" contribute no numbers of their own.
let bare = copy.replace(/\$[A-Za-z][A-Za-z0-9_]*/g, ' ');
for (const name of [agentName, trade.symbol, trade.name].filter(Boolean)) {
bare = bare.replace(new RegExp(escapeRe(String(name)), 'gi'), ' ');
}
const allowed = groundedNumbers(trade, copiedByCount);
for (const m of bare.matchAll(/-?\d+(?:\.\d+)?/g)) {
if (!allowed.has(normNum(Number(m[0])))) return false;
}
return true;
}
// Deterministic director, honest, surface-tuned copy from the real numbers.
function deterministicClip({ agentName, trade, copiedByCount, surface }) {
const sym = trade.symbol || trade.name || (trade.mint ? `$${trade.mint.slice(0, 4).toUpperCase()}` : 'the coin');
const ticker = sym.startsWith('$') ? sym : `$${sym}`;
const win = trade.is_win !== false;
const mult = trade.multiple != null ? `${trade.multiple}x` : null;
const pnl = trade.realized_pnl_sol != null ? `${trade.realized_pnl_sol > 0 ? '+' : ''}${trade.realized_pnl_sol} SOL` : null;
const hold = trade.hold_min != null ? holdLabel(trade.hold_min) : null;
const featureStat = mult || pnl || (trade.pnl_pct != null ? `${trade.pnl_pct}%` : 'closed on-chain');
let hook;
let body;
let gesture;
if (win) {
gesture = trade.multiple != null && trade.multiple >= 2 ? 'celebrate' : 'point';
hook = surface === 'x'
? `${ticker} closed ${featureStat}${hold ? ` in ${hold}` : ''}. On-chain, no screenshots.`
: `${agentName || 'The agent'} closed ${ticker} for ${featureStat}${hold ? ` after ${hold}` : ''}.`;
body = `${trimReason(trade.exit_reason)} Every number is a real closed round-trip you can verify on-chain.`;
} else {
gesture = 'sweat';
hook = surface === 'x'
? `${ticker} stopped out ${pnl || featureStat}. We show the losers too.`
: `${agentName || 'The agent'} took a loss on ${ticker}: ${pnl || featureStat}. Shown, not hidden.`;
body = `${trimReason(trade.exit_reason)} Live to trade again. Every trade is on the record, wins and losses.`;
}
if (copiedByCount > 0) body += ` Copied by ${copiedByCount}.`;
return {
hook,
feature_stat: featureStat,
avatar_gesture: gesture,
body: surface === 'telegram' ? `${body} Fork it from the room and ride the next one.` : body,
cta: win ? 'copy-the-agent' : 'view-track-record',
alt_text: `${agentName || 'A three.ws agent'} ${win ? 'closed a winning' : 'closed a losing'} trade on ${ticker}: ${featureStat}${hold ? `, held ${hold}` : ''}. Verifiable on-chain.`,
};
}
function holdLabel(min) {
if (min < 60) return `${min}m`;
if (min < 1440) return `${Math.round(min / 60)}h`;
return `${Math.round(min / 1440)}d`;
}
function trimReason(reason) {
const map = {
take_profit: 'Took profit at target.',
stop_loss: 'Stopped out at the risk line.',
trailing_stop: 'Trailing stop locked the gain.',
timeout: 'Closed on the time exit.',
manual: 'Closed the position by hand.',
graduated: 'Rode it through graduation.',
kill_switch: 'Kill-switch closed it.',
error: 'Closed after an execution hiccup.',
};
return map[reason] || 'Position closed.';
}
const VALID_CTA = new Set(['fork-this-trade', 'copy-the-agent', 'view-track-record']);
// A gesture pointing the wrong way (celebrating a loss) reads as sarcasm at best
// and a bug at worst, so the reaction is constrained to the direction the trade
// actually went rather than trusted from the writer.
const LOSS_GESTURES = new Set(['sweat', 'shrug']);
const WIN_GESTURES = new Set(['celebrate', 'point', 'wave']);
function finalize({ artifact, source, trade, surface }) {
const asked = GESTURES.includes(artifact.avatar_gesture) ? artifact.avatar_gesture : null;
const allowed = trade.is_win === false ? LOSS_GESTURES : WIN_GESTURES;
const gesture = asked && allowed.has(asked) ? asked : (trade.is_win === false ? 'sweat' : 'celebrate');
const cta = VALID_CTA.has(artifact.cta) ? artifact.cta : (trade.is_win === false ? 'view-track-record' : 'copy-the-agent');
return {
source,
surface,
hook: String(artifact.hook || '').slice(0, 120).trim(),
feature_stat: String(artifact.feature_stat || '').slice(0, 60).trim(),
avatar_gesture: gesture,
gesture_clip: GESTURE_CLIP[gesture],
body: String(artifact.body || '').slice(0, 320).trim(),
cta,
alt_text: String(artifact.alt_text || '').slice(0, 300).trim(),
verifiable: true,
trade,
};
}