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.

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.js
new file mode 100755
index 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.json
new file mode 100644
index 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.js
new file mode 100644
index 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 `[![${alt}](${glanceImageUrl(id, opts)})](${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;
+}