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(companion): let a person tune the avatar presenter and the quiet window

nirholas2dcdecd9fdfa
diff --git a/api/companion/settings.js b/api/companion/settings.js
index 3be4ddff4..39be89e0d 100644
--- a/api/companion/settings.js
+++ b/api/companion/settings.js
@@ -27,8 +27,19 @@ const patchBody = z.object({
const postBody = z.object({ rotate_token: z.literal(true) });
+// The bridge URL is copy-pasted into an iOS Shortcut and a shell script, so it
+// has to be the one that actually works from where the page was served. Behind
+// the load balancer that is the forwarded proto; on a laptop talking to a local
+// server over http, guessing https produced a URL whose every request died with
+// ERR_SSL_PROTOCOL_ERROR, including the page's own "Send a test" button.
+function originOf(req) {
+ const forwarded = String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim();
+ const proto = forwarded || (req.socket?.encrypted ? 'https' : 'http');
+ return `${proto}://${req.headers.host || 'three.ws'}`;
+}
+
function shape(row, req) {
- const origin = `${req.headers['x-forwarded-proto'] || 'https'}://${req.headers.host || 'three.ws'}`;
+ const origin = originOf(req);
return {
settings: {
enabled: row.enabled,
diff --git a/herald-sdk/src/presenters/avatar.js b/herald-sdk/src/presenters/avatar.js
index ea2f91f53..55dff4eaf 100644
--- a/herald-sdk/src/presenters/avatar.js
+++ b/herald-sdk/src/presenters/avatar.js
@@ -7,30 +7,39 @@
// CDN build) and hand it a line.
//
// Resolution order, cheapest first:
-// 1. `window.__walkCompanion`: three.ws pages already run one, and reusing
+// 1. A companion the integrator passed in (`companion` option). If you
+// already build one, hand it over: nothing else has to resolve.
+// 2. `window.__walkCompanion`: three.ws pages already run one, and reusing
// it means the visitor's own avatar delivers the message instead of a
// second character appearing beside it.
-// 2. A companion the integrator passed in (`companion` option).
-// 3. `import('@three-ws/walk')`: bundlers resolve this at build time.
-// 4. `import(cdn)`: a plain <script type="module"> page with no bundler.
+// 3. `walkModule`: a module URL (or bare specifier) to import at runtime.
+// Either it exports `createWalkCompanion`, or it installs the global on
+// import, which is how the three.ws build serves it at /walk-companion.js.
// Every rung is optional. If none resolve, `ready()` is false and the runtime
// falls back to the card presenter, which needs nothing at all.
-
-const DEFAULT_CDN = 'https://three.ws/agent-3d/latest/walk.mjs';
+//
+// The import is deliberately NOT a static specifier: a bundler that resolved
+// `@three-ws/walk` at build time would make an optional peer dependency a hard
+// build-time one, and a missing dist/ would fail the whole build rather than
+// costing one delivery its 3D body.
/**
* @param {object} [opts]
* @param {object} [opts.companion] a control object from createWalkCompanion()
* @param {object} [opts.companionOptions] options used when this presenter
* creates its own companion (avatars, defaultAvatarId, assetBase, apiBase...)
- * @param {string|null} [opts.cdn] module URL used when the package is absent
+ * @param {string|null} [opts.walkModule] module URL or specifier to import when
+ * no companion was passed and none is live on the page
* @param {(name: string) => any} [opts.globalLookup] test seam for window lookups
+ * @param {(spec: string) => Promise<any>} [opts.importModule] test seam for the
+ * dynamic import
*/
export function createAvatarPresenter({
companion = null,
companionOptions = null,
- cdn = DEFAULT_CDN,
+ walkModule = null,
globalLookup = (name) => globalThis?.[name],
+ importModule = (spec) => import(/* @vite-ignore */ spec),
} = {}) {
let control = companion;
let resolving = null;
@@ -41,13 +50,23 @@ export function createAvatarPresenter({
resolving = (async () => {
const live = globalLookup('__walkCompanion');
if (live && typeof live.announce === 'function') return live;
+ if (!walkModule) return null;
- const mod = await importWalk(cdn);
- if (!mod?.createWalkCompanion) return null;
- const created = mod.createWalkCompanion(companionOptions || {});
- // Never flip the visitor's persisted companion preference on: the
- // SDK borrows the corner for a message and gives it straight back.
- return created;
+ let mod = null;
+ try {
+ mod = await importModule(walkModule);
+ } catch {
+ return null;
+ }
+ if (typeof mod?.createWalkCompanion === 'function') {
+ // Never flip the visitor's persisted companion preference on: the
+ // SDK borrows the corner for a message and gives it straight back.
+ return mod.createWalkCompanion(companionOptions || {});
+ }
+ // A module that installs the global on import (the three.ws build at
+ // /walk-companion.js) rather than exporting a factory.
+ const installed = globalLookup('__walkCompanion');
+ return installed && typeof installed.announce === 'function' ? installed : null;
})()
.catch(() => null)
.then((resolved) => {
@@ -92,18 +111,3 @@ export function createAvatarPresenter({
return { name: 'avatar', ready, present, stop, get control() { return control; } };
}
-
-// Kept separate so a bundler that cannot resolve the optional package still
-// produces a working build: the failure is caught and the CDN rung runs.
-async function importWalk(cdn) {
- try {
- return await import(/* @vite-ignore */ '@three-ws/walk');
- } catch {
- if (!cdn) return null;
- try {
- return await import(/* @vite-ignore */ cdn);
- } catch {
- return null;
- }
- }
-}
diff --git a/src/stream-demo.js b/src/stream-demo.js
index cb603d2be..6f1ec7839 100644
--- a/src/stream-demo.js
+++ b/src/stream-demo.js
@@ -61,7 +61,12 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
* Meter a byte payload against a downlink budget.
* Resolves only once the last byte would have arrived at the given rate.
*/
-async function meter(byteLength, bytesPerSecond, onProgress) {
+function abortError() {
+ return new DOMException('The run was superseded', 'AbortError');
+}
+
+async function meter(byteLength, bytesPerSecond, onProgress, signal) {
+ if (signal?.aborted) throw abortError();
if (!Number.isFinite(bytesPerSecond)) {
onProgress?.(byteLength);
return;
@@ -69,15 +74,19 @@ async function meter(byteLength, bytesPerSecond, onProgress) {
const totalMs = (byteLength / bytesPerSecond) * 1000;
const started = performance.now();
let delivered = 0;
- // Tick often enough to animate, rarely enough to stay cheap.
+ // Tick often enough to animate, rarely enough to stay cheap. Changing the
+ // avatar or the downlink mid-run must stop this loop, or a superseded run
+ // keeps writing into panels the new run has already reset.
while (delivered < byteLength) {
await sleep(Math.min(50, Math.max(8, totalMs / 40)));
+ if (signal?.aborted) throw abortError();
const elapsed = performance.now() - started;
delivered = Math.min(byteLength, (elapsed / 1000) * bytesPerSecond);
onProgress?.(delivered);
}
const remaining = totalMs - (performance.now() - started);
if (remaining > 0) await sleep(remaining);
+ if (signal?.aborted) throw abortError();
onProgress?.(byteLength);
}
@@ -240,8 +249,7 @@ async function runClassic(panel, avatar, bytesPerSecond, signal) {
panel.log(`GET ${avatar.src}`);
panel.log(`${fmtBytes(buffer.byteLength)} to download before the first pixel`);
- await meter(buffer.byteLength, bytesPerSecond, (delivered) => panel.progress(delivered, buffer.byteLength));
- if (signal.aborted) return null;
+ await meter(buffer.byteLength, bytesPerSecond, (delivered) => panel.progress(delivered, buffer.byteLength), signal);
const loader = new GLTFLoader();
await configureLoader(loader);
@@ -270,7 +278,7 @@ async function runStream(panel, avatar, bytesPerSecond, signal) {
const buffer = new Uint8Array(await response.arrayBuffer());
await meter(buffer.byteLength, bytesPerSecond, (delivered) => {
panel.progress(transferred + delivered, totalBytes);
- });
+ }, signal);
transferred += buffer.byteLength;
return {
ok: response.ok,
@@ -301,7 +309,6 @@ async function runStream(panel, avatar, bytesPerSecond, signal) {
};
panel.statusEl.textContent = 'refining';
await player.refine();
- if (signal.aborted) return null;
panel.stage.playClips(player.animations);
panel.finish();
panel.bytesEl.textContent = fmtBytes(transferred);