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(walk-sdk): let a message be delivered by the sender's own avatar

nirholas587bd94369d6
diff --git a/tests/notification-herald.test.js b/tests/notification-herald.test.js
new file mode 100644
index 000000000..c99be7374
--- /dev/null
+++ b/tests/notification-herald.test.js
@@ -0,0 +1,161 @@
+// Unit tests for the notification herald's decision rules
+// (src/notification-herald.js): what the corner avatar is allowed to walk on
+// screen and say out loud, and what it must stay quiet about.
+//
+// Only the pure exports are exercised here. The module touches no DOM at import
+// time on purpose (every browser dependency is a dynamic import inside a
+// function), so it loads in the node test environment as-is.
+
+import { describe, it, expect } from 'vitest';
+import {
+ holdMsFor,
+ isFresh,
+ categoryFor,
+ announcesCategory,
+ pickAnnouncements,
+ emoteFor,
+} from '../src/notification-herald.js';
+import { typeCategoryMap } from '../api/_lib/notify-prefs.js';
+
+const NOW = Date.parse('2026-08-28T12:00:00.000Z');
+const ago = (ms) => new Date(NOW - ms).toISOString();
+
+const TYPES = typeCategoryMap();
+
+// Announce sales; stay quiet about everything else.
+const PREFS = {
+ categories: {
+ sales: { in_app: true, push: true, email: true, telegram: false, avatar: true },
+ social: { in_app: true, push: true, email: false, telegram: false, avatar: false },
+ account: { in_app: true, push: true, email: true, telegram: false, avatar: true },
+ },
+};
+
+function notif(over = {}) {
+ return {
+ id: over.id || 'n1',
+ type: over.type || 'sale',
+ payload: over.payload || {},
+ read_at: over.read_at ?? null,
+ created_at: over.created_at || ago(60_000),
+ };
+}
+
+describe('holdMsFor', () => {
+ it('scales the dwell with the length of the line', () => {
+ expect(holdMsFor('short')).toBeLessThan(holdMsFor('a considerably longer line of copy'));
+ });
+
+ it('never parks the avatar on screen, however long the payload', () => {
+ expect(holdMsFor('x'.repeat(5000))).toBe(12_000);
+ });
+
+ it('handles a missing line without throwing', () => {
+ expect(holdMsFor(undefined)).toBeGreaterThan(0);
+ });
+});
+
+describe('isFresh', () => {
+ it('accepts a notification from the last quarter hour', () => {
+ expect(isFresh(ago(60_000), NOW)).toBe(true);
+ expect(isFresh(ago(14 * 60_000), NOW)).toBe(true);
+ });
+
+ it('rejects anything older: that is inbox history, not news', () => {
+ expect(isFresh(ago(16 * 60_000), NOW)).toBe(false);
+ expect(isFresh(ago(48 * 3600_000), NOW)).toBe(false);
+ });
+
+ it('rejects a far-future timestamp and unparseable input', () => {
+ expect(isFresh(new Date(NOW + 3600_000).toISOString(), NOW)).toBe(false);
+ expect(isFresh('not a date', NOW)).toBe(false);
+ expect(isFresh(undefined, NOW)).toBe(false);
+ });
+});
+
+describe('categoryFor', () => {
+ it('uses the map the server sends', () => {
+ expect(categoryFor('sale', TYPES)).toBe('sales');
+ expect(categoryFor('follow', TYPES)).toBe('social');
+ expect(categoryFor('forge_complete', TYPES)).toBe('creations');
+ });
+
+ it('falls back to account for an unmapped type, exactly like the server', () => {
+ expect(categoryFor('brand_new_type', TYPES)).toBe('account');
+ expect(categoryFor('sale', undefined)).toBe('account');
+ });
+});
+
+describe('announcesCategory', () => {
+ it('requires an explicit true: an absent matrix announces nothing', () => {
+ expect(announcesCategory(PREFS, 'sales')).toBe(true);
+ expect(announcesCategory(PREFS, 'social')).toBe(false);
+ expect(announcesCategory(PREFS, 'irl')).toBe(false);
+ expect(announcesCategory(null, 'sales')).toBe(false);
+ expect(announcesCategory({}, 'sales')).toBe(false);
+ });
+});
+
+describe('pickAnnouncements', () => {
+ const base = { prefs: PREFS, typeCategories: TYPES, announced: new Set(), now: NOW };
+
+ it('announces a fresh, unread, opted-in notification', () => {
+ const { deliver, overflow } = pickAnnouncements([notif()], base);
+ expect(deliver.map((n) => n.id)).toEqual(['n1']);
+ expect(overflow).toBe(0);
+ });
+
+ it('skips read, stale, muted-category, and already-announced rows', () => {
+ const rows = [
+ notif({ id: 'read', read_at: ago(1000) }),
+ notif({ id: 'stale', created_at: ago(60 * 60_000) }),
+ notif({ id: 'muted', type: 'follow' }),
+ notif({ id: 'said' }),
+ ];
+ const { deliver } = pickAnnouncements(rows, {
+ ...base,
+ announced: new Set(['said']),
+ });
+ expect(deliver).toEqual([]);
+ });
+
+ it('delivers newest first', () => {
+ const rows = [
+ notif({ id: 'older', created_at: ago(9 * 60_000) }),
+ notif({ id: 'newer', created_at: ago(60_000) }),
+ ];
+ expect(pickAnnouncements(rows, base).deliver.map((n) => n.id)).toEqual(['newer', 'older']);
+ });
+
+ it('caps the batch at two and reports the rest as overflow', () => {
+ const rows = [1, 2, 3, 4, 5].map((i) =>
+ notif({ id: `n${i}`, created_at: ago(i * 60_000) }),
+ );
+ const { deliver, overflow } = pickAnnouncements(rows, base);
+ expect(deliver.map((n) => n.id)).toEqual(['n1', 'n2']);
+ expect(overflow).toBe(3);
+ });
+
+ it('tolerates junk input rather than throwing at delivery time', () => {
+ expect(pickAnnouncements(null, base).deliver).toEqual([]);
+ expect(pickAnnouncements([null, {}, notif()], base).deliver.map((n) => n.id)).toEqual(['n1']);
+ });
+
+ it('an unmapped type follows the account row, which announces by default', () => {
+ const rows = [notif({ id: 'x', type: 'brand_new_type' })];
+ expect(pickAnnouncements(rows, base).deliver.map((n) => n.id)).toEqual(['x']);
+ });
+});
+
+describe('emoteFor', () => {
+ it('celebrates money and finished work', () => {
+ expect(emoteFor('sale')).toBe('dance');
+ expect(emoteFor('royalty_paid')).toBe('dance');
+ expect(emoteFor('forge_complete')).toBe('dance');
+ });
+
+ it('waves for everything else, including a type it has never seen', () => {
+ expect(emoteFor('forge_failed')).toBe('wave');
+ expect(emoteFor('brand_new_type')).toBe('wave');
+ });
+});
diff --git a/walk-sdk/src/companion.js b/walk-sdk/src/companion.js
index f70d7bcef..abe5caeed 100644
--- a/walk-sdk/src/companion.js
+++ b/walk-sdk/src/companion.js
@@ -814,11 +814,16 @@ export function createWalkCompanion(opts = {}) {
* @param {string} [opts.emote='wave'] gesture played on arrival; falls back
* to a wave on rigs that don't carry it.
* @param {Array<{label:string, href?:string, onClick?:Function}>} [opts.actions]
+ * @param {string|object} [opts.avatar] deliver as somebody else: a roster
+ * id, or an entry from `makeGuestAvatarEntry(glbUrl, { name })`. The
+ * swap is not persisted and the visitor's own avatar comes back once
+ * the message is over, which is what lets a message from a contact be
+ * delivered by that contact's own body.
* @returns {Promise<boolean>} false when no avatar could be shown (route
* excluded, no WebGL, inside an iframe) so the caller can fall back to
* its own UI. True once the message is on screen.
*/
- async announce(message, { hold = 7000, tone = 'alert', emote = 'wave', actions } = {}) {
+ async announce(message, { hold = 7000, tone = 'alert', emote = 'wave', actions, avatar = null } = {}) {
if (!message) return false;
const summoned = !instance?.mounted;
// Transient only when the visitor has not turned the companion on: an
@@ -831,17 +836,43 @@ export function createWalkCompanion(opts = {}) {
if (!instance.mounted) return false;
}
const inst = instance;
+
+ // Guest delivery: whoever the message is from arrives in their own
+ // body, and the visitor's companion is restored afterwards. A swap
+ // that fails leaves the current avatar in place and the line is
+ // still delivered, so a missing GLB never costs the message.
+ let restore = null;
+ if (avatar) {
+ const guest = typeof avatar === 'string' ? resolveAvatarEntry(avatar, config) : avatar;
+ const currentId = inst._currentEntry?.id || lsGet(config.keys.avatar) || config.defaultAvatarId;
+ if (guest && guest.id !== currentId) {
+ restore = inst._currentEntry || resolveAvatarEntry(currentId, config);
+ await inst.setAvatar(guest, { persist: false, chatter: false });
+ }
+ }
+
try {
if (!inst.controller?.playEmote?.(emote)) inst.controller?.playWave?.();
} catch {
/* rig without emotes: the bubble still carries the message */
}
inst.say(message, { hold, tone, actions });
- if (!transient) return true;
- await new Promise((r) => setTimeout(r, hold + ANNOUNCE_RETREAT_MS));
- // The visitor may have turned the companion on (or swapped instances)
- // while it was delivering; never yank it away in that case.
- if (!isEnabled() && instance === inst && inst.mounted) inst.unmount();
+
+ const settle = async () => {
+ await new Promise((r) => setTimeout(r, hold + ANNOUNCE_RETREAT_MS));
+ if (instance !== inst || !inst.mounted) return;
+ if (restore) await inst.setAvatar(restore, { persist: false, chatter: false });
+ // The visitor may have turned the companion on (or swapped
+ // instances) while it was delivering; never yank it away then.
+ if (transient && !isEnabled() && instance === inst && inst.mounted) inst.unmount();
+ };
+ // A persistent companion returns as soon as the line is up; only a
+ // summoned-for-this-message one waits for its own retreat.
+ if (!transient) {
+ if (restore) settle();
+ return true;
+ }
+ await settle();
return true;
},
diff --git a/walk-sdk/src/index.js b/walk-sdk/src/index.js
index 643f6906e..603984d6c 100644
--- a/walk-sdk/src/index.js
+++ b/walk-sdk/src/index.js
@@ -46,6 +46,7 @@ export {
defaultAvatar,
listCategories,
makeApiAvatarEntry,
+ makeGuestAvatarEntry,
resolveAvatarUrl,
} from './roster.js';
diff --git a/walk-sdk/src/roster.js b/walk-sdk/src/roster.js
index 4c3deca03..bd2700702 100644
--- a/walk-sdk/src/roster.js
+++ b/walk-sdk/src/roster.js
@@ -260,6 +260,32 @@ export function makeApiAvatarEntry(id, { name, accent } = {}) {
};
}
+/**
+ * Build a roster-shaped entry for a GLB served from anywhere: a contact's
+ * avatar, an avatar generated from a selfie, a customer's own character. The
+ * URL is used verbatim (absolute URLs pass through resolveAvatarUrl untouched),
+ * and the rig is driven by the shared retargeted library, which is what lets an
+ * arbitrary humanoid GLB walk and gesture without shipping its own clips.
+ *
+ * @param {string} url absolute or root-relative GLB URL.
+ * @param {{ id?:string, name?:string, accent?:string, rig?:'shared'|'embedded' }} [opts]
+ */
+export function makeGuestAvatarEntry(url, { id, name, accent, rig = 'shared' } = {}) {
+ return {
+ id: id || `guest:${url}`,
+ name: name || 'Guest',
+ emoji: '👤',
+ blurb: 'A guest avatar delivering a message.',
+ category: 'Guests',
+ asset: url,
+ source: 'static',
+ rig,
+ clips: DEFAULT_SHARED_CLIPS,
+ accent: accent || '#7aa2ff',
+ tags: ['guest'],
+ };
+}
+
/**
* Resolve the GLB URL for a roster entry.
* - static entries: `assetBase` + the entry's asset path.