@cef-ai/widget-runtime 2.2.2 → 2.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Browser runtime for CEF widgets. It boots from `window.WidgetSandbox.manifest`,
 resolves the user's identity, exposes `window.WidgetRuntime`
-(`query` / `publish` / `connect` / `connectAgent` / `agentStatus` / `identity`),
+(`query` / `publish` / `subscribe` / `connect` / `connectAgent` / `agentStatus` / `identity`),
 and renders config-driven widget kinds (record / list / dashboard / submit /
 conversation / composite) plus custom widgets. It also carries the audio
 capture/upload path. The runtime **reads** a manifest; the `@cef-ai/cli` build
@@ -12,6 +12,28 @@ The esbuild IIFE build emits `dist/widget-runtime.js` (the browser bundle) and
 `dist/widget.html` (the shell); `tsc` emits the library entry (`dist/index.js`)
 for consumers that import the helpers directly.
 
+## Following a stream
+
+`subscribe` polls one stream of the widget's scope (the scope `publish` writes
+to) and hands each poll's new events to the callback as one ordered,
+de-duplicated batch:
+
+```js
+const { requestId } = …;
+await WidgetRuntime.publish('workflow.start', input, requestId, { target });
+const stop = WidgetRuntime.subscribe(
+  requestId,
+  { types: ['agent.progress'], intervalMs: 2500 },
+  (events) => events.forEach(render),
+);
+// later: stop();
+```
+
+It polls every 2500ms by default, backs off (doubling, up to `maxBackoffMs`,
+default 30s) while polls fail and reports each failure to `onError`, and stops
+when the returned function is called. Reading a stream needs `ddc-read` and a
+read grant on the scope, which a widget's delegation carries.
+
 ## Identity (multi-source)
 
 The runtime resolves a signing identity from the best available source:

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { buildWidgetManifest, type BuildManifestInput } from './manifest.js';
 export { injectWidgetBridge, type BridgeInput } from './bridge.js';
-export type { WidgetManifest, WidgetRuntimeApi, Identity, QueryResult } from './types.js';
+export type { WidgetManifest, WidgetRuntimeApi, Identity, QueryResult, PublishOptions, SubscribeOptions, WidgetEvent } from './types.js';
 export { AgentNotConnectedError } from './types.js';
 export { validateConfig } from './validate-config.js';
 export { mountKind } from './mount.js';

package/dist/runtime.js

@@ -37,7 +37,7 @@ export function createWidgetRuntime(manifest, deps) {
     }
     return {
         async query(ref, params) { return (await ensureClient()).query(ref, params); },
-        async publish(type, payload, context) { return (await ensureClient()).publish(type, payload, context); },
+        async publish(type, payload, context, options) { return (await ensureClient()).publish(type, payload, context, options); },
         async identity() {
             await ensureClient();
             return { publicKey, status, ...(context ? { context } : {}) };
@@ -49,5 +49,28 @@ export function createWidgetRuntime(manifest, deps) {
         async connectAgent() { await (await ensureClient()).connectAgent(); },
         async agentStatus() { return (await ensureClient()).agentStatus(); },
         onIdentityChange(cb) { subs.add(cb); return () => subs.delete(cb); },
+        /*
+         * SIGN-OUT STOPS IT. The runtime's only way to `anon` is a sign-in that
+         * failed — once a client is built it is kept, and nothing upstream says a
+         * session ended — so a subscription made before or during that sign-in is
+         * the one sign-out can strand, and it ends here, with the reason handed to
+         * `onError` so the widget is not left waiting on events that cannot come.
+         */
+        subscribe(streamContext, opts, onEvents) {
+            let cancelled = false;
+            let stopClient;
+            ensureClient().then((client) => { if (!cancelled)
+                stopClient = client.subscribe(streamContext, opts, onEvents); }, (err) => {
+                if (cancelled)
+                    return;
+                (opts.onError ?? ((e) => { console.warn('[widget-runtime] subscribe failed:', e); }))(err);
+            });
+            return () => {
+                if (cancelled)
+                    return;
+                cancelled = true;
+                stopClient?.();
+            };
+        },
     };
 }

package/dist/types.d.ts

@@ -108,9 +108,49 @@ export interface QueryResult {
         rowCount: number;
     };
 }
+export interface PublishOptions {
+    /** The one agent this event is for, `<asPubkey>:<name>`. */
+    target?: string;
+}
+/** One event from a vault stream, as {@link WidgetRuntimeApi.subscribe} delivers it. */
+export interface WidgetEvent<P = unknown> {
+    eventId: string;
+    type: string;
+    context: string;
+    payload: P;
+    /** Who published it — `app`, `agent:<id>`, … — when the vault recorded one. */
+    from?: string;
+    /** When the vault accepted it (RFC 3339). */
+    timestamp: string;
+}
+export interface SubscribeOptions {
+    /** Deliver only these event types. All types when absent. */
+    types?: string[];
+    /** Poll interval in ms. Default 2500. */
+    intervalMs?: number;
+    /**
+     * Ceiling for the wait between polls while they keep failing: it doubles
+     * from `intervalMs` up to this, and resets on the next success. Default 30000.
+     */
+    maxBackoffMs?: number;
+    /**
+     * A failed poll, or a failure to open the vault at all. Polling carries on
+     * (backing off) after a failed poll; it stops when the vault cannot be
+     * opened. Default: console.warn.
+     */
+    onError?: (err: unknown) => void;
+}
 export interface WidgetRuntimeApi {
     query(ref: string, params?: unknown[]): Promise<QueryResult>;
-    publish(type: string, payload: unknown, context?: string): Promise<{
+    /**
+     * Publish an event into the widget's scope.
+     *
+     * `target` addresses one agent (`<asPubkey>:<name>`). A workflow is started
+     * this way: its manifest handles the runner's fixed set (`workflow.start`,
+     * …), never the trigger's own event type, so an untargeted `workflow.start`
+     * would start every workflow connected in the scope.
+     */
+    publish(type: string, payload: unknown, context?: string, options?: PublishOptions): Promise<{
         eventId: string;
     }>;
     identity(): Promise<Identity>;
@@ -118,6 +158,20 @@ export interface WidgetRuntimeApi {
     connectAgent(): Promise<void>;
     agentStatus(): Promise<'connected' | 'disconnected'>;
     onIdentityChange(cb: (id: Identity) => void): () => void;
+    /**
+     * Follow one stream of the widget's scope — the scope `publish` writes to —
+     * and get its events as they arrive.
+     *
+     * `onEvents` receives each poll's new events as one batch, in stream order,
+     * each event at most once (de-duplicated by `eventId`); an empty poll calls
+     * nothing. Events already in the stream when you subscribe are delivered in
+     * the first batch, so subscribing just after a `publish` misses nothing.
+     *
+     * Returns the unsubscribe function. Polling also stops by itself when the
+     * reader's identity drops to `anon`. A failed poll never throws out of the
+     * timer: it goes to `onError`, and the next poll waits longer.
+     */
+    subscribe<P = unknown>(context: string, opts: SubscribeOptions, onEvents: (events: WidgetEvent<P>[]) => void): () => void;
 }
 export declare class AgentNotConnectedError extends Error {
     readonly agentId: string;

package/dist/vault-client.d.ts

@@ -1,4 +1,8 @@
-import { type QueryResult, type WidgetManifest } from './types.js';
+import { type QueryResult, type WidgetManifest, type PublishOptions, type SubscribeOptions, type WidgetEvent } from './types.js';
+/** Default poll interval for {@link VaultClient.subscribe}. */
+export declare const SUBSCRIBE_INTERVAL_MS = 2500;
+/** Default ceiling for the error backoff of {@link VaultClient.subscribe}. */
+export declare const SUBSCRIBE_MAX_BACKOFF_MS = 30000;
 export interface VaultSdkLike {
     vault: {
         ensure: (opts?: {
@@ -71,15 +75,7 @@ interface VaultLike {
             settings?: Record<string, unknown>;
         }) => Promise<AgentHandleLike>;
     };
-    scope: (name: string) => {
-        publish: (input: {
-            type: string;
-            context: string;
-            payload: unknown;
-        }) => Promise<{
-            eventId: string;
-        }>;
-    };
+    scope: (name: string) => ScopeLike;
     /**
      * The agent-SERVICE cubbies: one database per service, global within the
      * vault, so a widget reads what its agent's siblings wrote wherever the run
@@ -95,6 +91,30 @@ interface VaultLike {
      */
     memory?: MemoryLike;
 }
+interface ScopeLike {
+    publish: (input: {
+        type: string;
+        context: string;
+        payload: unknown;
+    }) => Promise<{
+        eventId: string;
+    }>;
+    /**
+     * vault-sdk's stream poller. Optional on the structural type for the same
+     * reason `service` is: an older vault-sdk does not have the backoff option,
+     * or (older still) the method.
+     */
+    subscribe?: (filter: {
+        context: string;
+        types?: string[];
+    }, handler: (event: WidgetEvent) => void, opts: {
+        intervalMs?: number;
+        maxBackoffMs?: number;
+        onError?: (err: unknown) => void;
+    }) => {
+        unsubscribe(): void;
+    };
+}
 /** The bank's read surface, as much of it as a widget can name. */
 interface MemoryLike {
     search: (match: string, opts?: {
@@ -115,11 +135,12 @@ interface AgentHandleLike {
 }
 export interface VaultClient {
     query(ref: string, params?: unknown[]): Promise<QueryResult>;
-    publish(type: string, payload: unknown, context?: string): Promise<{
+    publish(type: string, payload: unknown, context?: string, options?: PublishOptions): Promise<{
         eventId: string;
     }>;
     connectAgent(): Promise<void>;
     agentStatus(): Promise<'connected' | 'disconnected'>;
+    subscribe<P = unknown>(context: string, opts: SubscribeOptions, onEvents: (events: WidgetEvent<P>[]) => void): () => void;
 }
 export declare function createVaultClient(manifest: WidgetManifest, makeSdk: () => VaultSdkLike, 
 /**

package/dist/vault-client.js

@@ -1,5 +1,9 @@
 // packages/widget-runtime/src/vault-client.ts
 import {} from './types.js';
+/** Default poll interval for {@link VaultClient.subscribe}. */
+export const SUBSCRIBE_INTERVAL_MS = 2500;
+/** Default ceiling for the error backoff of {@link VaultClient.subscribe}. */
+export const SUBSCRIBE_MAX_BACKOFF_MS = 30000;
 /**
  * The host named a vault this widget cannot open.
  *
@@ -218,9 +222,80 @@ hostVaultId) {
             }
             return normaliseQueryResult(await queryService(decl ?? { id: ref, label: ref, sql: ref }, params ?? []));
         },
-        async publish(type, payload, context) {
+        async publish(type, payload, context, options) {
             const vault = await getVault();
-            return vault.scope(manifest.scope).publish({ type, context: context ?? '', payload });
+            return vault.scope(manifest.scope).publish({
+                type,
+                context: context ?? '',
+                payload,
+                ...(options?.target ? { target: options.target } : {}),
+            });
+        },
+        subscribe(context, opts, onEvents) {
+            const onError = opts.onError
+                ?? ((err) => { console.warn('[widget-runtime] subscribe poll failed:', err); });
+            let stopped = false;
+            let sub;
+            let batch = [];
+            let flushTimer;
+            /*
+             * ONE CALLBACK PER POLL, NOT PER EVENT. vault-sdk hands events over one
+             * at a time, synchronously within a poll, and the next poll is a network
+             * round-trip away — so a zero-delay timer armed by the first event of a
+             * poll fires once that poll's events are all in. A renderer gets the
+             * batch it can pace, instead of N re-renders it cannot tell apart.
+             */
+            const flush = () => {
+                flushTimer = undefined;
+                const out = batch;
+                batch = [];
+                if (out.length === 0)
+                    return;
+                try {
+                    onEvents(out);
+                }
+                catch (err) {
+                    onError(err);
+                }
+            };
+            void getVault().then((vault) => {
+                if (stopped)
+                    return;
+                const scope = vault.scope(manifest.scope);
+                if (typeof scope.subscribe !== 'function') {
+                    throw new Error('[widget-runtime] this host\'s vault-sdk cannot follow a stream (no scope.subscribe)');
+                }
+                sub = scope.subscribe({ context, ...(opts.types ? { types: opts.types } : {}) }, (event) => {
+                    if (stopped)
+                        return;
+                    batch.push({
+                        eventId: event.eventId,
+                        type: event.type,
+                        context: event.context,
+                        payload: event.payload,
+                        ...(event.from ? { from: event.from } : {}),
+                        timestamp: event.timestamp,
+                    });
+                    flushTimer ?? (flushTimer = setTimeout(flush, 0));
+                }, {
+                    intervalMs: opts.intervalMs ?? SUBSCRIBE_INTERVAL_MS,
+                    maxBackoffMs: opts.maxBackoffMs ?? SUBSCRIBE_MAX_BACKOFF_MS,
+                    onError,
+                });
+            }).catch((err) => {
+                // The vault would not open (signed out, unreachable): nothing to poll.
+                if (!stopped)
+                    onError(err);
+            });
+            return () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                if (flushTimer !== undefined)
+                    clearTimeout(flushTimer);
+                batch = [];
+                sub?.unsubscribe();
+            };
         },
         async connectAgent() {
             const vault = await getVault();