@amodalai/runtime 0.2.0 → 0.2.2

package/dist/src/events/event-bus.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Runtime event bus.
+ *
+ * Centralized pub/sub for server-level state changes (session created,
+ * automation triggered, store updated, manifest reloaded). Clients
+ * subscribe via the `/api/events` SSE endpoint and use these events to
+ * drive live UI updates instead of polling.
+ *
+ * Each event gets a monotonic sequence number assigned at emit time.
+ * A ring buffer of recent events lets reconnecting clients catch up
+ * via the `Last-Event-ID` SSE header without missing any state changes.
+ */
+import type { RuntimeEvent, RuntimeEventPayload } from '@amodalai/types';
+export type RuntimeEventListener = (event: RuntimeEvent) => void;
+export interface EventBusOptions {
+    /** Max events retained for reconnect-and-resume. Default 200. */
+    bufferSize?: number;
+    /**
+     * Called when a listener throws. The bus never rethrows listener errors
+     * (one bad subscriber shouldn't break the broadcast to others), but a
+     * throwing listener is a bug worth surfacing. Wire this to a logger.
+     */
+    onListenerError?: (err: unknown, event: RuntimeEvent) => void;
+}
+export declare class RuntimeEventBus {
+    private listeners;
+    private seq;
+    private readonly bufferSize;
+    private readonly onListenerError;
+    private buffer;
+    constructor(options?: EventBusOptions);
+    /**
+     * Emit an event. The bus assigns `seq` and `timestamp`.
+     * Returns the fully-populated event.
+     */
+    emit(payload: RuntimeEventPayload): RuntimeEvent;
+    /**
+     * Subscribe to events. Returns an unsubscribe function.
+     *
+     * If `sinceSeq` is provided, buffered events with `seq > sinceSeq`
+     * are delivered synchronously before the listener starts receiving
+     * live events. Used for reconnect-and-resume.
+     */
+    subscribe(listener: RuntimeEventListener, sinceSeq?: number): () => void;
+    /** Count of currently subscribed listeners (for observability) */
+    get listenerCount(): number;
+    /** Current sequence number (for tests + observability) */
+    get currentSeq(): number;
+}

package/dist/src/events/event-bus.js

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/** Maximum number of events kept in the replay buffer */
+const DEFAULT_BUFFER_SIZE = 200;
+export class RuntimeEventBus {
+    listeners = new Set();
+    seq = 0;
+    bufferSize;
+    onListenerError;
+    buffer = [];
+    constructor(options = {}) {
+        this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
+        this.onListenerError = options.onListenerError;
+    }
+    /**
+     * Emit an event. The bus assigns `seq` and `timestamp`.
+     * Returns the fully-populated event.
+     */
+    emit(payload) {
+        this.seq += 1;
+        // The payload's discriminant `type` field carries through; we only
+        // add `seq` and `timestamp`. Shape-preserving by construction.
+        const event = {
+            ...payload,
+            seq: this.seq,
+            timestamp: new Date().toISOString(),
+        };
+        // Append to ring buffer
+        this.buffer.push(event);
+        if (this.buffer.length > this.bufferSize) {
+            this.buffer.shift();
+        }
+        // Fan out to listeners. Errors in one listener must not break the
+        // broadcast to others — so we catch, surface via `onListenerError`
+        // (for observability), and continue. Not a silent swallow: the
+        // caller sees every failure via the injected callback.
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                this.onListenerError?.(err, event);
+            }
+        }
+        return event;
+    }
+    /**
+     * Subscribe to events. Returns an unsubscribe function.
+     *
+     * If `sinceSeq` is provided, buffered events with `seq > sinceSeq`
+     * are delivered synchronously before the listener starts receiving
+     * live events. Used for reconnect-and-resume.
+     */
+    subscribe(listener, sinceSeq) {
+        if (sinceSeq !== undefined) {
+            for (const event of this.buffer) {
+                if (event.seq > sinceSeq) {
+                    try {
+                        listener(event);
+                    }
+                    catch (err) {
+                        this.onListenerError?.(err, event);
+                    }
+                }
+            }
+        }
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Count of currently subscribed listeners (for observability) */
+    get listenerCount() {
+        return this.listeners.size;
+    }
+    /** Current sequence number (for tests + observability) */
+    get currentSeq() {
+        return this.seq;
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/src/events/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../src/events/event-bus.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH,yDAAyD;AACzD,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAehC,MAAM,OAAO,eAAe;IAClB,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC5C,GAAG,GAAG,CAAC,CAAC;IACC,UAAU,CAAS;IACnB,eAAe,CAAqC;IAC7D,MAAM,GAAmB,EAAE,CAAC;IAEpC,YAAY,UAA2B,EAAE;QACvC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAC5D,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IACjD,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,OAA4B;QAC/B,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACd,mEAAmE;QACnE,+DAA+D;QAC/D,MAAM,KAAK,GAAG;YACZ,GAAG,OAAO;YACV,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpB,CAAC;QAElB,wBAAwB;QACxB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACzC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC;QAED,kEAAkE;QAClE,mEAAmE;QACnE,+DAA+D;QAC/D,uDAAuD;QACvD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,QAA8B,EAAE,QAAiB;QACzD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,IAAI,KAAK,CAAC,GAAG,GAAG,QAAQ,EAAE,CAAC;oBACzB,IAAI,CAAC;wBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;oBAClB,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;oBACrC,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAED,kEAAkE;IAClE,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,0DAA0D;IAC1D,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;CACF"}

package/dist/src/events/event-bus.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};

package/dist/src/events/event-bus.test.js

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { RuntimeEventBus } from './event-bus.js';
+describe('RuntimeEventBus', () => {
+    it('assigns monotonic sequence numbers starting at 1', () => {
+        const bus = new RuntimeEventBus();
+        const a = bus.emit({ type: 'session_created', sessionId: 's1', appId: 'local' });
+        const b = bus.emit({ type: 'session_updated', sessionId: 's1', appId: 'local' });
+        const c = bus.emit({ type: 'manifest_changed' });
+        expect(a.seq).toBe(1);
+        expect(b.seq).toBe(2);
+        expect(c.seq).toBe(3);
+    });
+    it('stamps ISO timestamps on every event', () => {
+        const bus = new RuntimeEventBus();
+        const event = bus.emit({ type: 'manifest_changed' });
+        expect(event.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+    });
+    it('delivers events to all subscribed listeners', () => {
+        const bus = new RuntimeEventBus();
+        const listener1 = vi.fn();
+        const listener2 = vi.fn();
+        bus.subscribe(listener1);
+        bus.subscribe(listener2);
+        bus.emit({ type: 'session_created', sessionId: 's1', appId: 'local' });
+        expect(listener1).toHaveBeenCalledTimes(1);
+        expect(listener2).toHaveBeenCalledTimes(1);
+    });
+    it('unsubscribe stops delivery to that listener', () => {
+        const bus = new RuntimeEventBus();
+        const listener = vi.fn();
+        const unsub = bus.subscribe(listener);
+        bus.emit({ type: 'manifest_changed' });
+        unsub();
+        bus.emit({ type: 'manifest_changed' });
+        expect(listener).toHaveBeenCalledTimes(1);
+    });
+    it('replays buffered events when sinceSeq is provided', () => {
+        const bus = new RuntimeEventBus();
+        bus.emit({ type: 'session_created', sessionId: 's1', appId: 'local' }); // seq 1
+        bus.emit({ type: 'session_created', sessionId: 's2', appId: 'local' }); // seq 2
+        bus.emit({ type: 'session_created', sessionId: 's3', appId: 'local' }); // seq 3
+        const listener = vi.fn();
+        bus.subscribe(listener, 1);
+        expect(listener).toHaveBeenCalledTimes(2);
+        expect(listener.mock.calls[0]?.[0].seq).toBe(2);
+        expect(listener.mock.calls[1]?.[0].seq).toBe(3);
+    });
+    it('ring buffer evicts oldest events past capacity', () => {
+        const bus = new RuntimeEventBus({ bufferSize: 3 });
+        for (let i = 0; i < 5; i++) {
+            bus.emit({ type: 'manifest_changed' });
+        }
+        const listener = vi.fn();
+        bus.subscribe(listener, 0);
+        expect(listener).toHaveBeenCalledTimes(3);
+        expect(listener.mock.calls[0]?.[0].seq).toBe(3);
+        expect(listener.mock.calls[2]?.[0].seq).toBe(5);
+    });
+    it('a throwing listener does not block other listeners', () => {
+        const bus = new RuntimeEventBus();
+        const bad = vi.fn(() => { throw new Error('oops'); });
+        const good = vi.fn();
+        bus.subscribe(bad);
+        bus.subscribe(good);
+        bus.emit({ type: 'manifest_changed' });
+        expect(bad).toHaveBeenCalledTimes(1);
+        expect(good).toHaveBeenCalledTimes(1);
+    });
+    it('surfaces listener errors via onListenerError callback', () => {
+        const onListenerError = vi.fn();
+        const bus = new RuntimeEventBus({ onListenerError });
+        bus.subscribe(() => { throw new Error('oops'); });
+        bus.emit({ type: 'manifest_changed' });
+        expect(onListenerError).toHaveBeenCalledTimes(1);
+        const [err, event] = onListenerError.mock.calls[0] ?? [];
+        expect(err).toBeInstanceOf(Error);
+        expect(err.message).toBe('oops');
+        expect(event.type).toBe('manifest_changed');
+    });
+    it('listenerCount tracks active subscriptions', () => {
+        const bus = new RuntimeEventBus();
+        expect(bus.listenerCount).toBe(0);
+        const unsub1 = bus.subscribe(() => { });
+        const unsub2 = bus.subscribe(() => { });
+        expect(bus.listenerCount).toBe(2);
+        unsub1();
+        expect(bus.listenerCount).toBe(1);
+        unsub2();
+        expect(bus.listenerCount).toBe(0);
+    });
+    it('preserves event data fields through emit', () => {
+        const bus = new RuntimeEventBus();
+        const event = bus.emit({
+            type: 'store_updated',
+            storeName: 'leads',
+            operation: 'put',
+            count: 5,
+        });
+        expect(event.type).toBe('store_updated');
+        if (event.type === 'store_updated') {
+            expect(event.storeName).toBe('leads');
+            expect(event.operation).toBe('put');
+            expect(event.count).toBe(5);
+        }
+    });
+});
+//# sourceMappingURL=event-bus.test.js.map

package/dist/src/events/event-bus.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.test.js","sourceRoot":"","sources":["../../../src/events/event-bus.test.ts"],"names":[],"mappings":"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"}

package/dist/src/events/events-route.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * SSE route for the runtime event bus.
+ *
+ * GET /api/events
+ *
+ * Clients open a single EventSource and receive every server-emitted
+ * runtime event (session_created, automation_triggered, store_updated,
+ * etc.) without polling.
+ *
+ * Reconnect-and-resume: clients may send a `Last-Event-ID` header
+ * (EventSource does this automatically on reconnect). The bus replays
+ * any buffered events with seq > Last-Event-ID before streaming live.
+ *
+ * Heartbeats: a comment line is sent every 15s so proxies don't close
+ * the connection during quiet periods.
+ */
+import { Router } from 'express';
+import type { RuntimeEventBus } from './event-bus.js';
+/** Minimal logger surface — matches the runtime's Logger interface. */
+interface EventsRouterLogger {
+    debug(event: string, data?: Record<string, unknown>): void;
+}
+export interface EventsRouterOptions {
+    bus: RuntimeEventBus;
+    /** Heartbeat interval in ms. Default 15000. */
+    heartbeatMs?: number;
+    /** Optional logger for connect/disconnect observability */
+    logger?: EventsRouterLogger;
+}
+export declare function createEventsRouter(options: EventsRouterOptions): Router;
+export {};

package/dist/src/events/events-route.js

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * SSE route for the runtime event bus.
+ *
+ * GET /api/events
+ *
+ * Clients open a single EventSource and receive every server-emitted
+ * runtime event (session_created, automation_triggered, store_updated,
+ * etc.) without polling.
+ *
+ * Reconnect-and-resume: clients may send a `Last-Event-ID` header
+ * (EventSource does this automatically on reconnect). The bus replays
+ * any buffered events with seq > Last-Event-ID before streaming live.
+ *
+ * Heartbeats: a comment line is sent every 15s so proxies don't close
+ * the connection during quiet periods.
+ */
+import { Router } from 'express';
+const HEARTBEAT_DEFAULT_MS = 15_000;
+export function createEventsRouter(options) {
+    const router = Router();
+    const { bus, logger } = options;
+    const heartbeatMs = options.heartbeatMs ?? HEARTBEAT_DEFAULT_MS;
+    router.get('/api/events', (req, res) => {
+        // Parse optional Last-Event-ID for reconnect-and-resume
+        const lastIdHeader = req.header('Last-Event-ID');
+        let sinceSeq;
+        if (lastIdHeader) {
+            const parsed = Number.parseInt(lastIdHeader, 10);
+            if (Number.isFinite(parsed) && parsed >= 0) {
+                sinceSeq = parsed;
+            }
+        }
+        logger?.debug('events_client_connected', {
+            sinceSeq,
+            listenerCount: bus.listenerCount + 1,
+        });
+        // SSE response headers
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache, no-transform');
+        res.setHeader('Connection', 'keep-alive');
+        // Disable nginx response buffering for SSE
+        res.setHeader('X-Accel-Buffering', 'no');
+        res.flushHeaders();
+        // Subscribe to the bus. `subscribe` replays buffered events > sinceSeq
+        // synchronously, then hands live events to the listener.
+        const unsubscribe = bus.subscribe((event) => {
+            // SSE frame: id + event + data. `id:` lets EventSource resume.
+            res.write(`id: ${String(event.seq)}\n`);
+            res.write(`event: ${event.type}\n`);
+            res.write(`data: ${JSON.stringify(event)}\n\n`);
+        }, sinceSeq);
+        // Heartbeat: SSE comment line every N seconds. Keeps proxies from
+        // closing an idle connection and lets the client detect drops.
+        const heartbeat = setInterval(() => {
+            res.write(':\n\n');
+        }, heartbeatMs);
+        // Clean up on disconnect
+        let cleanedUp = false;
+        const cleanup = () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
+            clearInterval(heartbeat);
+            unsubscribe();
+            logger?.debug('events_client_disconnected', {
+                listenerCount: bus.listenerCount,
+            });
+        };
+        req.on('close', cleanup);
+        req.on('error', cleanup);
+        res.on('close', cleanup);
+    });
+    return router;
+}
+//# sourceMappingURL=events-route.js.map

package/dist/src/events/events-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-route.js","sourceRoot":"","sources":["../../../src/events/events-route.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,SAAS,CAAC;AAiB/B,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAEpC,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,MAAM,EAAC,GAAG,EAAE,MAAM,EAAC,GAAG,OAAO,CAAC;IAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAEhE,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;QACxD,wDAAwD;QACxD,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QACjD,IAAI,QAA4B,CAAC;QACjC,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;YACjD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;gBAC3C,QAAQ,GAAG,MAAM,CAAC;YACpB,CAAC;QACH,CAAC;QAED,MAAM,EAAE,KAAK,CAAC,yBAAyB,EAAE;YACvC,QAAQ;YACR,aAAa,EAAE,GAAG,CAAC,aAAa,GAAG,CAAC;SACrC,CAAC,CAAC;QAEH,uBAAuB;QACvB,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC;QACnD,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAAC;QACzD,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAC1C,2CAA2C;QAC3C,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;QACzC,GAAG,CAAC,YAAY,EAAE,CAAC;QAEnB,uEAAuE;QACvE,yDAAyD;QACzD,MAAM,WAAW,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YAC1C,+DAA+D;YAC/D,GAAG,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACxC,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;YACpC,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClD,CAAC,EAAE,QAAQ,CAAC,CAAC;QAEb,kEAAkE;QAClE,+DAA+D;QAC/D,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YACjC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC,EAAE,WAAW,CAAC,CAAC;QAEhB,yBAAyB;QACzB,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,IAAI,SAAS;gBAAE,OAAO;YACtB,SAAS,GAAG,IAAI,CAAC;YACjB,aAAa,CAAC,SAAS,CAAC,CAAC;YACzB,WAAW,EAAE,CAAC;YACd,MAAM,EAAE,KAAK,CAAC,4BAA4B,EAAE;gBAC1C,aAAa,EAAE,GAAG,CAAC,aAAa;aACjC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/events/events-route.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};

package/dist/src/events/events-route.test.js

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import express from 'express';
+import { RuntimeEventBus } from './event-bus.js';
+import { createEventsRouter } from './events-route.js';
+function startServer(bus) {
+    const app = express();
+    app.use(createEventsRouter({ bus, heartbeatMs: 60_000 }));
+    return new Promise((resolve) => {
+        const server = app.listen(0, () => {
+            const address = server.address();
+            const port = address && typeof address === 'object' ? address.port : 0;
+            resolve({ port, server, bus });
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+}
+async function collectEvents(url, expected, opts = {}) {
+    const headers = { Accept: 'text/event-stream' };
+    if (opts.lastEventId)
+        headers['Last-Event-ID'] = opts.lastEventId;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs ?? 2000);
+    const res = await fetch(url, { headers, signal: controller.signal });
+    if (!res.body)
+        throw new Error('no response body');
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    const collected = [];
+    let buffer = '';
+    try {
+        while (collected.length < expected) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buffer.indexOf('\n\n')) !== -1) {
+                const frame = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                const dataLine = frame.split('\n').find((l) => l.startsWith('data:'));
+                if (dataLine) {
+                    const json = dataLine.slice(5).trim();
+                    collected.push(JSON.parse(json));
+                    if (collected.length >= expected)
+                        break;
+                }
+            }
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        controller.abort();
+        reader.cancel().catch(() => { });
+    }
+    return collected;
+}
+describe('events SSE route', () => {
+    let harness = null;
+    afterEach(async () => {
+        if (harness) {
+            await closeServer(harness.server);
+            harness = null;
+        }
+    });
+    it('streams emitted events to connected clients', async () => {
+        const bus = new RuntimeEventBus();
+        harness = await startServer(bus);
+        const url = `http://127.0.0.1:${String(harness.port)}/api/events`;
+        const eventsPromise = collectEvents(url, 2, { timeoutMs: 2000 });
+        setTimeout(() => {
+            bus.emit({ type: 'session_created', sessionId: 's1', appId: 'local' });
+            bus.emit({ type: 'manifest_changed' });
+        }, 50);
+        const events = await eventsPromise;
+        expect(events).toHaveLength(2);
+        expect(events[0]?.['type']).toBe('session_created');
+        expect(events[0]?.['seq']).toBe(1);
+        expect(events[1]?.['type']).toBe('manifest_changed');
+        expect(events[1]?.['seq']).toBe(2);
+    });
+    it('replays buffered events matching Last-Event-ID', async () => {
+        const bus = new RuntimeEventBus();
+        harness = await startServer(bus);
+        const url = `http://127.0.0.1:${String(harness.port)}/api/events`;
+        bus.emit({ type: 'session_created', sessionId: 's1', appId: 'local' });
+        bus.emit({ type: 'session_created', sessionId: 's2', appId: 'local' });
+        bus.emit({ type: 'session_created', sessionId: 's3', appId: 'local' });
+        const events = await collectEvents(url, 2, { lastEventId: '1', timeoutMs: 2000 });
+        expect(events).toHaveLength(2);
+        expect(events[0]?.['seq']).toBe(2);
+        expect(events[1]?.['seq']).toBe(3);
+    });
+    it('includes id and event headers in SSE frames', async () => {
+        const bus = new RuntimeEventBus();
+        harness = await startServer(bus);
+        const url = `http://127.0.0.1:${String(harness.port)}/api/events`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 2000);
+        const res = await fetch(url, {
+            headers: { Accept: 'text/event-stream' },
+            signal: controller.signal,
+        });
+        if (!res.body)
+            throw new Error('no response body');
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        setTimeout(() => {
+            bus.emit({ type: 'manifest_changed' });
+        }, 50);
+        let raw = '';
+        while (!raw.includes('\n\n')) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            raw += decoder.decode(value, { stream: true });
+        }
+        clearTimeout(timeout);
+        controller.abort();
+        reader.cancel().catch(() => { });
+        expect(raw).toContain('id: 1');
+        expect(raw).toContain('event: manifest_changed');
+        expect(raw).toContain('data: {"type":"manifest_changed"');
+    });
+});
+//# sourceMappingURL=events-route.test.js.map

package/dist/src/events/events-route.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-route.test.js","sourceRoot":"","sources":["../../../src/events/events-route.test.ts"],"names":[],"mappings":"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"}

package/dist/src/events/store-event-wrapper.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Wraps a `StoreBackend` so every successful write emits a `store_updated`
+ * event to the runtime event bus. Read operations pass through unchanged.
+ *
+ * Instrumenting at the backend level (rather than each call site: tools,
+ * REST routes, admin file tools, task execution) means we cover every
+ * write path through one seam.
+ */
+import type { StoreBackend, RuntimeEventPayload } from '@amodalai/types';
+interface StoreEventSink {
+    emit: (payload: RuntimeEventPayload) => unknown;
+}
+export declare function wrapStoreBackendWithEvents(inner: StoreBackend, bus: StoreEventSink): StoreBackend;
+export {};

package/dist/src/events/store-event-wrapper.js

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export function wrapStoreBackendWithEvents(inner, bus) {
+    return {
+        initialize(stores) {
+            return inner.initialize(stores);
+        },
+        get(appId, store, key) {
+            return inner.get(appId, store, key);
+        },
+        list(appId, store, opts) {
+            return inner.list(appId, store, opts);
+        },
+        history(appId, store, key) {
+            return inner.history(appId, store, key);
+        },
+        async put(appId, store, key, payload, meta) {
+            const result = await inner.put(appId, store, key, payload, meta);
+            bus.emit({
+                type: 'store_updated',
+                storeName: store,
+                operation: 'put',
+            });
+            return result;
+        },
+        async delete(appId, store, key) {
+            const result = await inner.delete(appId, store, key);
+            if (result) {
+                bus.emit({
+                    type: 'store_updated',
+                    storeName: store,
+                    operation: 'delete',
+                });
+            }
+            return result;
+        },
+        async purgeExpired(appId, store) {
+            const count = await inner.purgeExpired(appId, store);
+            if (count > 0) {
+                bus.emit({
+                    type: 'store_updated',
+                    storeName: store ?? '*',
+                    operation: 'delete',
+                    count,
+                });
+            }
+            return count;
+        },
+        close() {
+            return inner.close();
+        },
+    };
+}
+//# sourceMappingURL=store-event-wrapper.js.map

package/dist/src/events/store-event-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-event-wrapper.js","sourceRoot":"","sources":["../../../src/events/store-event-wrapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH,MAAM,UAAU,0BAA0B,CACxC,KAAmB,EACnB,GAAmB;IAEnB,OAAO;QACL,UAAU,CAAC,MAAqB;YAC9B,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,GAAG,CAAC,KAAa,EAAE,KAAa,EAAE,GAAW;YAC3C,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,CAAC,KAAa,EAAE,KAAa,EAAE,IAAuB;YACxD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,CAAC,KAAa,EAAE,KAAa,EAAE,GAAW;YAC/C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,GAAG,CACP,KAAa,EACb,KAAa,EACb,GAAW,EACX,OAAgC,EAChC,IAAgC;YAEhC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;YACjE,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;YACH,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,KAAa,EAAE,GAAW;YACpD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;YACrD,IAAI,MAAM,EAAE,CAAC;gBACX,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,eAAe;oBACrB,SAAS,EAAE,KAAK;oBAChB,SAAS,EAAE,QAAQ;iBACpB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,KAAa,EAAE,KAAc;YAC9C,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACrD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,eAAe;oBACrB,SAAS,EAAE,KAAK,IAAI,GAAG;oBACvB,SAAS,EAAE,QAAQ;oBACnB,KAAK;iBACN,CAAC,CAAC;YACL,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,KAAK;YACH,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/events/store-event-wrapper.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};