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
/**
* Glance card model + renderers.
* ------------------------------
* One agent, reduced to what fits in a home screen slot: who it is, one live
* number, and a way back into the app. The same model feeds four consumers, so
* it is built once here rather than four times at the edges:
*
* - JSON -> the Windows 11 widgets board (Adaptive Card data binding),
* the <agent-glance> element, and any third-party surface.
* - SVG -> README badges, Slack unfurls, docs, and any <img> slot.
* - Adaptive -> a fully bound Adaptive Card for consumers that render one
* without doing their own templating.
*
* No widget runtime on any of those platforms can execute WebGL, which is why
* a glance card is a flat card and not the live 3D avatar: the avatar's own
* thumbnail is the image, and the 3D lives one tap away on the agent page.
*
* Everything here reads real platform state (agent_identities, agent_actions).
* A card for an agent that has never acted is a designed state, not an error.
*/
import { sql } from './db.js';
import { getRedis } from './redis.js';
import { thumbnailUrl } from './r2.js';
import { sha256 } from './crypto.js';
export const GLANCE_CARD_VERSION = 1;
// Long enough that a widget board polling every few minutes mostly hits cache,
// short enough that "moves today" is not visibly stale on a busy agent.
export const GLANCE_CACHE_TTL_S = 120;
const CACHE_KEY = (id) => `glance:card:v${GLANCE_CARD_VERSION}:${id}`;
const SITE = 'https://three.ws';
/**
* Load an agent's glance card from real platform state.
*
* @param {string} agentId agent uuid (caller validates the shape)
* @param {{ fresh?: boolean }} [opts]
* @returns {Promise<object|null>} card model, or null when no such agent
*/
export async function loadGlanceCard(agentId, { fresh = false } = {}) {
const redis = await getRedis();
if (!fresh && redis) {
try {
const cached = await redis.get(CACHE_KEY(agentId));
if (cached) return { ...cached, cache: 'hit' };
} catch {
/* cache unavailable: recompute, never fail the read */
}
}
const [[agent], [activity], [last]] = await Promise.all([
sql`
SELECT i.id, i.name, i.description, i.skills, i.created_at,
a.thumbnail_key AS avatar_thumbnail_key,
a.visibility AS avatar_visibility
FROM agent_identities i
LEFT JOIN avatars a ON a.id = i.avatar_id AND a.deleted_at IS NULL
WHERE i.id = ${agentId} AND i.deleted_at IS NULL
LIMIT 1
`,
sql`
SELECT
count(*)::int AS total,
count(*) FILTER (WHERE created_at > now() - interval '24 hours')::int AS day,
count(*) FILTER (WHERE created_at > now() - interval '7 days')::int AS week
FROM agent_actions
WHERE agent_id = ${agentId}
`,
sql`
SELECT type, created_at
FROM agent_actions
WHERE agent_id = ${agentId}
ORDER BY created_at DESC
LIMIT 1
`,
]);
if (!agent) return null;
const card = buildGlanceCard({ agent, activity: activity || {}, last: last || null });
if (redis) {
try {
await redis.set(CACHE_KEY(agentId), card, { ex: GLANCE_CACHE_TTL_S });
} catch {
/* a cache write failure must never fail the read */
}
}
return { ...card, cache: 'miss' };
}
/**
* Shape the card from already-loaded rows. Pure, so the renderers and the
* tests can build a card without touching the database.
*/
export function buildGlanceCard({ agent, activity = {}, last = null, now = new Date() }) {
const day = Number(activity.day) || 0;
const total = Number(activity.total) || 0;
const week = Number(activity.week) || 0;
const skills = Array.isArray(agent.skills) ? agent.skills.length : 0;
const lastAt = last?.created_at ? new Date(last.created_at) : null;
const createdAt = agent.created_at ? new Date(agent.created_at) : null;
// The avatar thumbnail only resolves for an avatar the public may see;
// a private or missing one falls back to the generated monogram, never to
// a broken image.
const publicAvatar =
agent.avatar_visibility === 'public' || agent.avatar_visibility === 'unlisted';
const image =
publicAvatar && agent.avatar_thumbnail_key ? thumbnailUrl(agent.avatar_thumbnail_key) : null;
const name = String(agent.name || 'Untitled agent').slice(0, 64);
const status = deriveStatus({ total, lastAt, now });
return {
version: GLANCE_CARD_VERSION,
id: agent.id,
name,
description: agent.description ? String(agent.description).slice(0, 160) : null,
url: `${SITE}/agents/${agent.id}`,
createUrl: `${SITE}/create`,
image,
monogram: monogramOf(name),
accent: accentOf(String(agent.id)),
status,
headline: HEADLINE[status],
metric: { label: 'Moves today', value: day },
stats: [
{ label: 'This week', value: week },
{ label: 'All time', value: total },
// Skills only when the agent actually has some: a flat "Skills 0" tells
// the owner nothing, while "Days live" is true of every agent.
skills > 0
? { label: 'Skills', value: skills }
: { label: 'Days live', value: createdAt ? Math.max(0, Math.floor((now - createdAt) / 86_400_000)) : 0 },
],
lastAction: lastAt
? {
type: String(last.type || 'action').slice(0, 40),
at: lastAt.toISOString(),
relative: relativeTime(lastAt, now),
}
: null,
bornAt: createdAt ? createdAt.toISOString() : null,
ageDays: createdAt ? Math.max(0, Math.floor((now - createdAt) / 86_400_000)) : null,
updatedAt: now.toISOString(),
ttl: GLANCE_CACHE_TTL_S,
};
}
const HEADLINE = {
// The empty state has to earn its slot too: it says what to do next
// rather than showing a zero and leaving the owner to guess.
new: 'Not started yet. Open to give it a first job.',
idle: 'Quiet today. Tap to put it back to work.',
active: 'Working.',
};
function deriveStatus({ total, lastAt, now }) {
if (!total || !lastAt) return 'new';
return now - lastAt < 86_400_000 ? 'active' : 'idle';
}
export function monogramOf(name) {
const words = String(name || '')
.trim()
.split(/\s+/)
.filter(Boolean);
if (!words.length) return '3';
const first = [...words[0]][0] || '';
const second = words.length > 1 ? [...words[1]][0] || '' : '';
return (first + second).toUpperCase().slice(0, 2);
}
/**
* A stable pair of hues per agent, so a card without a thumbnail still looks
* like that specific agent and not like every other blank card.
*/
export function accentOf(seed) {
let h = 2166136261;
for (let i = 0; i < seed.length; i++) {
h ^= seed.charCodeAt(i);
h = Math.imul(h, 16777619);
}
const hue = Math.abs(h) % 360;
return { from: `hsl(${hue} 82% 58%)`, to: `hsl(${(hue + 48) % 360} 84% 46%)`, hue };
}
export function relativeTime(then, now = new Date()) {
const s = Math.max(0, Math.floor((now - then) / 1000));
if (s < 60) return 'just now';
const m = Math.floor(s / 60);
if (m < 60) return `${m}m ago`;
const h = Math.floor(m / 60);
if (h < 24) return `${h}h ago`;
const d = Math.floor(h / 24);
if (d < 30) return `${d}d ago`;
const mo = Math.floor(d / 30);
if (mo < 12) return `${mo}mo ago`;
return `${Math.floor(mo / 12)}y ago`;
}
/**
* A card that carries a message instead of an agent: the signed-out slot, the
* unlinked widget, the account with no agent yet, the id nobody owns. It is
* shaped exactly like an agent card so every renderer (SVG, PNG, Adaptive
* Card, the element) draws it with no special case, and it always says what
* to do next, because a widget that shows an error is a widget people remove.
*
* @param {{ name: string, headline: string, url: string, monogram?: string, description?: string|null }} notice
*/
export function noticeCard({ name, headline, url, monogram = '3', description = null }) {
const now = new Date();
return {
version: GLANCE_CARD_VERSION,
id: 'notice',
name: String(name).slice(0, 64),
description: description ? String(description).slice(0, 160) : null,
url,
createUrl: `${SITE}/create`,
image: null,
monogram: String(monogram).slice(0, 2),
accent: { from: '#64748b', to: '#334155', hue: 215 },
status: 'new',
headline: String(headline).slice(0, 160),
metric: { label: 'Moves today', value: 0 },
stats: [
{ label: 'This week', value: 0 },
{ label: 'All time', value: 0 },
{ label: 'Days live', value: 0 },
],
lastAction: null,
bornAt: null,
ageDays: null,
updatedAt: now.toISOString(),
ttl: GLANCE_CACHE_TTL_S,
};
}
export async function glanceEtag(card) {
const digest = await sha256(
[card.id, card.metric.value, card.stats.map((s) => s.value).join(','), card.status].join('|'),
);
return `W/"glance-${GLANCE_CARD_VERSION}-${digest.slice(0, 24)}"`;
}