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(herald): pull announcements from real sources and drive the page from them

nirholas588310da9f98
diff --git a/herald-sdk/src/index.js b/herald-sdk/src/index.js
index d930d2444..24009052e 100644
--- a/herald-sdk/src/index.js
+++ b/herald-sdk/src/index.js
@@ -187,17 +187,22 @@ export function createHerald(options = {}) {
try {
const presenter = await pickPresenter();
- const shown = await presenter.present(message, { dwellMs, actions });
+ // The presenter's promise resolves when the message LEAVES the screen
+ // (which is what keeps deliveries one at a time), so the delivery is
+ // counted when it goes UP. Anything else would report a message the
+ // person is looking at right now as undelivered for its whole dwell.
+ const showing = presenter.present(message, { dwellMs, actions });
+ stats.delivered += 1;
+ opts.onDeliver?.(message);
// A presenter that reports it could not render is not a delivery: fall
// through to the card so the message still reaches a human.
- if (shown === false && presenter.name !== 'card') {
+ if ((await showing) === false && presenter.name !== 'card') {
await presenters.card.present(message, { dwellMs, actions });
}
- stats.delivered += 1;
- opts.onDeliver?.(message);
} catch {
- // A presenter that throws must not wedge the queue; the message is
- // counted as dropped so `stats()` never over-reports delivery.
+ // A presenter that throws must not wedge the queue, and must not leave
+ // a delivery counted that nobody ever saw.
+ stats.delivered = Math.max(0, stats.delivered - 1);
record(message, 'presenter-failed');
} finally {
busy = false;
diff --git a/herald-sdk/src/sources/index.js b/herald-sdk/src/sources/index.js
index d963a1c93..b14466faa 100644
--- a/herald-sdk/src/sources/index.js
+++ b/herald-sdk/src/sources/index.js
@@ -90,6 +90,9 @@ function defaultSelect(body) {
* @param {string[]} [opts.events=['message']] event names to listen for
* @param {boolean} [opts.withCredentials=true]
* @param {(data:any)=>any} [opts.map]
+ * @param {() => void} [opts.onOpen] the stream connected
+ * @param {(err:any) => void} [opts.onError] the stream dropped; EventSource
+ * reconnects on its own, so this is for status, not for recovery
* @param {typeof EventSource} [opts.EventSourceImpl]
*/
export function sseSource({
@@ -97,13 +100,20 @@ export function sseSource({
events = ['message'],
withCredentials = true,
map = (x) => x,
+ onOpen,
+ onError,
EventSourceImpl = globalThis.EventSource,
}) {
return {
name: `sse:${url}`,
start(emit) {
- if (!EventSourceImpl) return () => {};
+ if (!EventSourceImpl) {
+ onError?.(new Error('EventSource is unavailable in this environment'));
+ return () => {};
+ }
const es = new EventSourceImpl(url, { withCredentials });
+ if (onOpen) es.addEventListener('open', () => onOpen());
+ if (onError) es.addEventListener('error', (e) => onError(e));
const handler = (e) => {
let payload = e.data;
try {
@@ -133,13 +143,17 @@ export function sseSource({
*
* @param {object} [opts]
* @param {string} [opts.origin='https://three.ws'] rail origin
+ * @param {() => void} [opts.onOpen]
+ * @param {(err:any) => void} [opts.onError]
* @param {typeof EventSource} [opts.EventSourceImpl]
*/
-export function railSource({ origin = 'https://three.ws', EventSourceImpl } = {}) {
+export function railSource({ origin = 'https://three.ws', onOpen, onError, EventSourceImpl } = {}) {
const base = String(origin || '').replace(/\/$/, '');
const source = sseSource({
url: `${base}/api/herald/stream`,
events: ['announce'],
+ onOpen,
+ onError,
EventSourceImpl,
});
return { ...source, name: 'rail' };
diff --git a/src/herald-page.js b/src/herald-page.js
index 9a9f81495..08c85669d 100644
--- a/src/herald-page.js
+++ b/src/herald-page.js
@@ -92,20 +92,20 @@ function isAuthed() {
function connectRail() {
if (!('EventSource' in window)) return setRail('off', 'This browser has no EventSource');
setRail('', 'Connecting…');
- // Same-origin: the SDK's railSource defaults to three.ws, but on a preview
- // origin (or localhost) the stream lives here, not there.
- railStop = herald.source(railSource({ origin: window.location.origin }));
-
- // EventSource reports readiness through its own events; the source hides the
- // instance, so we probe the endpoint once for an honest label rather than
- // claiming a connection we cannot see.
- fetch('/api/herald/stream', { method: 'HEAD', credentials: 'include' })
- .then((res) => {
- if (res.status === 401) setRail('off', 'Sign in to use your rail');
- else if (res.ok || res.status === 405) setRail('live', 'Listening on your rail');
- else setRail('off', `Rail unavailable (${res.status})`);
- })
- .catch(() => setRail('off', 'Rail unreachable'));
+ // The stream itself is the status: EventSource tells us when it is open and
+ // when it drops, so the label is what is actually true rather than the
+ // result of a separate probe request.
+ railStop = herald.source(
+ railSource({
+ // Same-origin: the SDK defaults to three.ws, but on a preview origin
+ // (or localhost) the stream lives here, not there.
+ origin: window.location.origin,
+ onOpen: () => setRail('live', 'Listening on your rail'),
+ // EventSource reconnects on its own, so a drop is a status change, not
+ // a failure to recover from.
+ onError: () => setRail('off', 'Rail disconnected, retrying…'),
+ }),
+ );
}
function setRail(state, label) {