@ayni.org/ayni-ui-core 0.3.1 → 0.3.2

package/README.md

@@ -24,5 +24,20 @@ The browser's stylesheet is the reference: tests in this repository compare it,
 with these values, so a change made on one side only fails. The app builds its styles from the same values. A change
 of look or wording on one of these surfaces starts here.
 
+## One conversation, every device
+
+A conversation shows the same transcript on every device of a person (AG-UI profile PROF-STREAM-005,
+PROF-HIST-007). The agent sends a session what the person's other devices add; the reducer places a text message
+by its role and its id, so a message typed elsewhere lands on the person's side. For what a client missed while it
+was away:
+
+| Function | What it does |
+| --- | --- |
+| `readCatchUp(transcript, read)` | Reads the newest pages of history, going back until one reaches what the transcript holds, history ends, or four pages were read; then merges them. |
+| `catchUp(transcript, pages)` | The merge itself. The transcript keeps its own paging position; when more was missed than was read, it starts over from the pages, so it never shows a hole. |
+| `reachesTranscript(transcript, page)` | Whether a page of history holds a message the transcript already has. |
+
+A client calls `readCatchUp` every time a session's stream attaches.
+
 Published to npm from this repository by the `npm-publish` workflow whenever `package.json` carries a version that is
 not on npm yet.

package/dist/reducer.d.ts

@@ -19,3 +19,23 @@ export declare function reactionsOf(page: Record<string, unknown>[]): Record<str
 }[]>;
 /** Merges a history page (newest last) into the transcript without duplicates (UI-CONV-012, UI-PRIV-003). */
 export declare function mergeHistory(transcript: Transcript, page: Record<string, unknown>[], nextBefore: string | null): Transcript;
+/** A page of history as the agent returns it (PROF-HIST-001): newest last, with where the page before it starts. */
+export interface HistoryPage {
+    messages: Record<string, unknown>[];
+    nextBefore: string | null;
+}
+/** Whether a page of history reaches what the transcript holds: one of its messages is already there. */
+export declare function reachesTranscript(transcript: Transcript, page: Record<string, unknown>[]): boolean;
+/**
+ * What a device missed while it was away, merged into the transcript it holds (UI-CONV-022, PROF-HIST-007): a
+ * conversation continued from another device, or events its stream could not replay. `pages` are the newest pages
+ * of history, newest first, read until one reached the transcript or history ended. The transcript keeps its own
+ * paging position when a page reached it. When none did, more was missed than was read: the transcript starts
+ * over from the pages, so it never shows a hole between what it held and what it read.
+ */
+export declare function catchUp(transcript: Transcript, pages: readonly HistoryPage[]): Transcript;
+/**
+ * Reads what `catchUp` needs: the newest pages of history, going back until one reaches the transcript, history
+ * ends, or `maxPages` were read; then merges them.
+ */
+export declare function readCatchUp(transcript: Transcript, read: (before?: string) => Promise<HistoryPage>, maxPages?: number): Promise<Transcript>;

package/dist/reducer.js

@@ -75,9 +75,13 @@ export function reduce(transcript, session, event, fromRun, isOnScreen) {
             break;
         case 'TEXT_MESSAGE_START': {
             const role = event.role === 'user' ? 'user' : event.role === 'system' ? 'system' : 'assistant';
+            const id = String(event.messageId);
+            // a message already held comes again when a stream replays it after a reconnect: it keeps its time, so
+            // it stays where it is in the transcript
+            const held = t.messages.find((m) => m.id === id);
             t = {
                 ...t,
-                messages: upsertMessage(t.messages, { id: String(event.messageId), role, content: '', at, streaming: true }),
+                messages: upsertMessage(t.messages, { id, role, content: '', at: held?.at ?? at, streaming: true }),
             };
             break;
         }
@@ -308,3 +312,50 @@ export function mergeHistory(transcript, page, nextBefore) {
         complete: nextBefore === null || page.length === 0,
     };
 }
+/** Whether a page of history reaches what the transcript holds: one of its messages is already there. */
+export function reachesTranscript(transcript, page) {
+    const known = new Set(transcript.messages.map((m) => m.id));
+    return page.some((m) => {
+        const external = m.metadata?.externalId;
+        return known.has(String(m.id)) || (!!external && known.has(external));
+    });
+}
+/**
+ * What a device missed while it was away, merged into the transcript it holds (UI-CONV-022, PROF-HIST-007): a
+ * conversation continued from another device, or events its stream could not replay. `pages` are the newest pages
+ * of history, newest first, read until one reached the transcript or history ended. The transcript keeps its own
+ * paging position when a page reached it. When none did, more was missed than was read: the transcript starts
+ * over from the pages, so it never shows a hole between what it held and what it read.
+ */
+export function catchUp(transcript, pages) {
+    if (!pages.length)
+        return transcript;
+    const held = transcript.messages.length > 0;
+    const reached = !held || pages.some((p) => p.nextBefore === null || reachesTranscript(transcript, p.messages));
+    let merged = reached ? transcript : { ...transcript, messages: [], reactions: {} };
+    for (const page of pages)
+        merged = mergeHistory(merged, page.messages, page.nextBefore);
+    return held && reached
+        ? { ...merged, oldestLoadedId: transcript.oldestLoadedId, complete: transcript.complete }
+        : merged;
+}
+/**
+ * Reads what `catchUp` needs: the newest pages of history, going back until one reaches the transcript, history
+ * ends, or `maxPages` were read; then merges them.
+ */
+export async function readCatchUp(transcript, read, maxPages = 4) {
+    const pages = [];
+    let before;
+    for (let i = 0; i < maxPages; i++) {
+        const page = await read(before);
+        pages.push(page);
+        const done = page.nextBefore === null ||
+            page.messages.length === 0 ||
+            transcript.messages.length === 0 ||
+            reachesTranscript(transcript, page.messages);
+        if (done)
+            break;
+        before = page.nextBefore ?? undefined;
+    }
+    return catchUp(transcript, pages);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayni.org/ayni-ui-core",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Framework-independent core of the Ayni UI (UI-SHELL-004): agents and controllers, trust resolution, sessions and binding, the conversation reducer, the local store and sync; shared by the browser UI and the Ayni app",
   "type": "module",
   "main": "./dist/index.js",