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
feat(glance): ship the agent glance widget, adaptive SVG cards and its service worker
nirholas21caa3fe85b4
diff --git a/packages/agent-glance/bin/agent-glance.js b/packages/agent-glance/bin/agent-glance.jsnew file mode 100755index 000000000..02d8ebdaf--- /dev/null+++ b/packages/agent-glance/bin/agent-glance.js@@ -0,0 +1,109 @@+#!/usr/bin/env node+/**+ * agent-glance — a three.ws agent card, in your terminal or in your repo.+ *+ * npx @three-ws/agent-glance <agent-id> print the card+ * npx @three-ws/agent-glance <agent-id> --json the raw card model+ * npx @three-ws/agent-glance <agent-id> --markdown a README snippet+ * npx @three-ws/agent-glance <agent-id> --html an embed snippet+ * npx @three-ws/agent-glance <agent-id> --svg card.svg+ * npx @three-ws/agent-glance <agent-id> --watch 60 refresh every 60s+ *+ * Options: --size small|medium|large, --theme auto|light|dark, --no-color,+ * --origin https://three.ws+ */++import { writeFile } from 'node:fs/promises';+import {+ fetchGlanceCard,+ glanceImageUrl,+ glanceMarkdown,+ glanceEmbedHtml,+ renderGlanceAnsi,+ GlanceError,+} from '../src/index.js';++const USAGE = `agent-glance <agent-id> [options]++ --json print the card model as JSON+ --markdown print a README snippet (image linked to the agent)+ --html print an embed snippet for a web page+ --svg <file> write the card image to a file+ --watch [seconds] redraw on an interval (default 60)+ --size <s> small | medium | large (default medium)+ --theme <t> auto | light | dark (default auto)+ --origin <url> API origin (default https://three.ws)+ --no-color plain text, no ANSI+ -h, --help this message+`;++function parseArgs(argv) {+ const opts = { color: true, size: 'medium', theme: 'auto', watch: 0 };+ const rest = [];+ for (let i = 0; i < argv.length; i++) {+ const arg = argv[i];+ if (arg === '--json') opts.json = true;+ else if (arg === '--markdown' || arg === '--md') opts.markdown = true;+ else if (arg === '--html' || arg === '--embed') opts.html = true;+ else if (arg === '--svg') opts.svg = argv[++i];+ else if (arg === '--size') opts.size = argv[++i];+ else if (arg === '--theme') opts.theme = argv[++i];+ else if (arg === '--origin') opts.origin = argv[++i];+ else if (arg === '--no-color') opts.color = false;+ else if (arg === '--watch') {+ const next = Number(argv[i + 1]);+ opts.watch = Number.isFinite(next) && next > 0 ? (i++, next) : 60;+ } else if (arg === '-h' || arg === '--help') opts.help = true;+ else rest.push(arg);+ }+ opts.agentId = rest[0];+ return opts;+}++async function printOnce(opts) {+ const card = await fetchGlanceCard(opts.agentId, { origin: opts.origin });+ if (opts.json) return console.log(JSON.stringify(card, null, 2));+ console.log(renderGlanceAnsi(card, { color: opts.color && process.stdout.isTTY !== false }));+ return card;+}++async function main() {+ const opts = parseArgs(process.argv.slice(2));+ if (opts.help || !opts.agentId) {+ console.log(USAGE);+ process.exit(opts.agentId ? 0 : 1);+ }++ if (opts.markdown) return console.log(glanceMarkdown(opts.agentId, opts));+ if (opts.html) return console.log(glanceEmbedHtml(opts.agentId, opts));++ if (opts.svg) {+ const url = glanceImageUrl(opts.agentId, opts);+ const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });+ if (!res.ok) throw new GlanceError(`three.ws answered ${res.status}`, { status: res.status });+ await writeFile(opts.svg, await res.text(), 'utf8');+ console.log(`wrote ${opts.svg}`);+ return;+ }++ await printOnce(opts);+ if (!opts.watch) return;++ // Watch mode redraws in place: one card that stays current, not a scroll of+ // stale copies.+ const tick = async () => {+ try {+ process.stdout.write('\u001b[2J\u001b[H');+ await printOnce(opts);+ console.log(`\nrefreshing every ${opts.watch}s, ctrl+c to stop`);+ } catch (err) {+ console.error(`glance: ${err.message}`);+ }+ };+ setInterval(tick, opts.watch * 1000);+}++main().catch((err) => {+ console.error(`glance: ${err instanceof GlanceError ? err.message : err?.message || err}`);+ process.exit(1);+});diff --git a/packages/agent-glance/package.json b/packages/agent-glance/package.jsonnew file mode 100644index 000000000..58c5cab71--- /dev/null+++ b/packages/agent-glance/package.json@@ -0,0 +1,43 @@+{+ "name": "@three-ws/agent-glance",+ "version": "0.1.0",+ "description": "Put a three.ws agent on any surface that has a slot: home screen widgets, README badges, Slack unfurls, and a live <agent-glance> web component.",+ "keywords": [+ "three.ws",+ "agent",+ "widget",+ "home-screen",+ "adaptive-card",+ "web-component",+ "svg",+ "badge",+ "pwa"+ ],+ "author": "three.ws <[email protected]> (https://three.ws)",+ "license": "Apache-2.0",+ "homepage": "https://three.ws/glance",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/nirholas/three.ws.git",+ "directory": "packages/agent-glance"+ },+ "type": "module",+ "main": "./src/index.js",+ "exports": {+ ".": "./src/index.js"+ },+ "bin": {+ "agent-glance": "./bin/agent-glance.js"+ },+ "files": [+ "src",+ "bin",+ "README.md"+ ],+ "engines": {+ "node": ">=18"+ },+ "publishConfig": {+ "access": "public"+ }+}diff --git a/packages/agent-glance/src/index.js b/packages/agent-glance/src/index.jsnew file mode 100644index 000000000..47bc9f6b3--- /dev/null+++ b/packages/agent-glance/src/index.js@@ -0,0 +1,183 @@+/**+ * @three-ws/agent-glance+ *+ * A glance card is one three.ws agent reduced to what fits in a home screen+ * slot: who it is, one live number, and a way back into it. The platform+ * serves that card as JSON, as an SVG image, and as an Adaptive Card; this+ * package is the client for all three, with no dependencies and no build step.+ *+ * import { fetchGlanceCard, glanceImageUrl } from '@three-ws/agent-glance';+ *+ * const card = await fetchGlanceCard('0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34');+ * console.log(card.name, card.metric.value, card.metric.label);+ *+ * Every function here works in a browser, in Node 18+, in a service worker,+ * and in an edge runtime: the only I/O is `fetch`.+ */++export const GLANCE_ORIGIN = 'https://three.ws';+export const GLANCE_SIZES = ['small', 'medium', 'large'];+export const GLANCE_THEMES = ['auto', 'light', 'dark'];++// Every network call here is bounded. A card is decoration on someone else's+// page: it must never be the reason that page hangs.+const DEFAULT_TIMEOUT_MS = 8000;++export class GlanceError extends Error {+ constructor(message, { status = 0, agentId = null, cause } = {}) {+ super(message);+ this.name = 'GlanceError';+ this.status = status;+ this.agentId = agentId;+ if (cause) this.cause = cause;+ }+}++function assertAgentId(agentId) {+ const id = String(agentId || '').trim();+ if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {+ throw new GlanceError(`"${agentId}" is not a three.ws agent id (expected a uuid)`, {+ agentId,+ });+ }+ return id;+}++function buildUrl(path, params, origin) {+ const url = new URL(path, origin || GLANCE_ORIGIN);+ for (const [key, value] of Object.entries(params)) {+ if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, value);+ }+ return url.toString();+}++/**+ * The JSON endpoint for one agent's card.+ * @param {string} agentId+ * @param {{ origin?: string }} [opts]+ */+export function glanceCardUrl(agentId, opts = {}) {+ return buildUrl('/api/glance/card', { agent: assertAgentId(agentId) }, opts.origin);+}++/**+ * An <img>-ready SVG of the card. This is the one to put in a README, a Slack+ * message, or any host that only takes a picture.+ * @param {string} agentId+ * @param {{ size?: 'small'|'medium'|'large', theme?: 'auto'|'light'|'dark', origin?: string }} [opts]+ */+export function glanceImageUrl(agentId, opts = {}) {+ const size = GLANCE_SIZES.includes(opts.size) ? opts.size : 'medium';+ const theme = GLANCE_THEMES.includes(opts.theme) ? opts.theme : 'auto';+ return buildUrl(+ '/api/glance/card',+ { agent: assertAgentId(agentId), format: 'svg', size, theme },+ opts.origin,+ );+}++/**+ * Fetch the card model.+ * @param {string} agentId+ * @param {{ origin?: string, timeoutMs?: number, signal?: AbortSignal, fetchImpl?: typeof fetch }} [opts]+ * @returns {Promise<object>} the card+ */+export async function fetchGlanceCard(agentId, opts = {}) {+ const id = assertAgentId(agentId);+ const doFetch = opts.fetchImpl || globalThis.fetch;+ if (typeof doFetch !== 'function') {+ throw new GlanceError('no fetch implementation available', { agentId: id });+ }+ const signal = opts.signal || AbortSignal.timeout(opts.timeoutMs || DEFAULT_TIMEOUT_MS);+ let res;+ try {+ res = await doFetch(glanceCardUrl(id, opts), {+ headers: { accept: 'application/json' },+ signal,+ });+ } catch (err) {+ throw new GlanceError(`could not reach three.ws: ${err?.message || err}`, {+ agentId: id,+ cause: err,+ });+ }+ if (res.status === 404) throw new GlanceError('no such agent on three.ws', { status: 404, agentId: id });+ if (!res.ok) throw new GlanceError(`three.ws answered ${res.status}`, { status: res.status, agentId: id });+ return res.json();+}++/**+ * Fetch the card already shaped as an Adaptive Card, for a host that renders+ * one directly (Windows widgets board, Teams, an Adaptive Card renderer).+ */+export async function fetchGlanceAdaptiveCard(agentId, opts = {}) {+ const id = assertAgentId(agentId);+ const doFetch = opts.fetchImpl || globalThis.fetch;+ const signal = opts.signal || AbortSignal.timeout(opts.timeoutMs || DEFAULT_TIMEOUT_MS);+ const res = await doFetch(+ buildUrl('/api/glance/card', { agent: id, format: 'adaptive' }, opts.origin),+ { headers: { accept: 'application/json' }, signal },+ );+ if (!res.ok) throw new GlanceError(`three.ws answered ${res.status}`, { status: res.status, agentId: id });+ return res.json();+}++/** Markdown for a README: the card image, linked to the agent. */+export function glanceMarkdown(agentId, opts = {}) {+ const id = assertAgentId(agentId);+ const alt = opts.alt || 'three.ws agent';+ return `[})](${GLANCE_ORIGIN}/agents/${id})`;+}++/** HTML for a page: the live element, with the image as the no-script fallback. */+export function glanceEmbedHtml(agentId, opts = {}) {+ const id = assertAgentId(agentId);+ const size = GLANCE_SIZES.includes(opts.size) ? opts.size : 'medium';+ const theme = GLANCE_THEMES.includes(opts.theme) ? opts.theme : 'auto';+ return [+ `<script type="module" src="${opts.origin || GLANCE_ORIGIN}/glance/element.js"></script>`,+ `<agent-glance agent="${id}" size="${size}" theme="${theme}"></agent-glance>`,+ ].join('\n');+}++/**+ * Render the card as ANSI for a terminal (the CLI uses this, and so can any+ * dashboard that lives in a shell).+ * @param {object} card+ * @param {{ color?: boolean, width?: number }} [opts]+ */+export function renderGlanceAnsi(card, opts = {}) {+ const color = opts.color !== false;+ const width = Math.max(34, Math.min(80, opts.width || 46));+ const c = (code, text) => (color ? `\u001b[${code}m${text}\u001b[0m` : String(text));+ const dot = { active: '32', idle: '33', new: '90' }[card.status] || '90';+ const pad = (text) => {+ const clipped = clip(text, width - 4);+ return `${clipped}${' '.repeat(Math.max(0, width - 4 - visibleLength(clipped)))}`;+ };+ const line = (text) => `${c('90', '│')} ${pad(text)} ${c('90', '│')}`;+ const stats = (card.stats || []).map((s) => `${s.label} ${c('1', s.value)}`).join(' ');++ return [+ c('90', `╭${'─'.repeat(width - 2)}╮`),+ line(`${c('1', clip(card.name, 24))} ${c(dot, '●')} ${c('90', card.status)}`),+ line(c('90', clip(card.description || card.headline, width - 6))),+ line(''),+ line(`${c('1', String(card.metric.value))} ${c('90', card.metric.label.toLowerCase())}`),+ line(c('90', stats)),+ line(''),+ line(c('90', card.url)),+ c('90', `╰${'─'.repeat(width - 2)}╯`),+ ].join('\n');+}++function clip(text, max) {+ const value = String(text ?? '');+ return value.length <= max ? value : `${value.slice(0, Math.max(1, max - 1))}…`;+}++// Length as the terminal sees it: ANSI escapes take no columns.+function visibleLength(text) {+ // eslint-disable-next-line no-control-regex+ return String(text).replace(/\u001b\[[0-9;]*m/g, '').length;+}