@volter/teams 0.1.62 → 0.1.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "type": "module",
   "description": "Volter Teams, the neutral team plane: machine identity and daemon core, the local door and server link, admission from machine grants, product doors, and the Teams server's neutral routes (company RFC 0008).",
   "license": "MIT",

package/session-follow.d.ts

@@ -33,7 +33,7 @@ export interface FollowTeamSessionOptions {
 export function followTeamSession(options: FollowTeamSessionOptions): { stop(): void; read(): Promise<TeamSessionSnapshot> };
 
 /** A message another session sent this one, from its envelope: its sender and body, or null for an ordinary turn. */
-export function peerMessage(text: string): { name: string; address: string; body: string } | null;
+export function peerMessage(text: string): { id: string | null; name: string; address: string; body: string; subject: string | null; via: string | null; inReplyTo: string | null } | null;
 
 /** Overlay actual envelopes, deduplicating copies already delivered into the native transcript. */
 export function withMail<Entry extends { id: string; ts: number | null; mail?: { id: string } }>(transcript: Entry[], rows: import('./browser-channel.js').MailHistoryEntry[], options?: { agentName?: string; agentId?: string; agentImage?(seed: string): string }): Array<Entry | { id: string; role: 'notice'; text: string; ts: number; truncated: boolean; mail: { id: string; from: string; to: string; direction: 'in' | 'out'; inReplyTo?: string | null; image?: string; via?: 'voice' } }>;

package/session-follow.mjs

@@ -15,29 +15,41 @@
  */
 export function followTeamSession({ origin, teamId, sessionId, token, tail = 300, onSnapshot, onLive = () => {}, onError = () => {}, onDeleted = () => {}, fetchImpl = globalThis.fetch, retryMs = 2000 }) {
   const base = `${origin}/api/v1/teams/${encodeURIComponent(teamId)}/sessions/${encodeURIComponent(sessionId)}`;
-  const decoder = new TextDecoder();
   const controller = new AbortController();
   const headers = async () => ({ Authorization: `Bearer ${await token()}` });
   const failure = (stage, status, message) => Object.assign(new Error(message), { stage, status });
-  let reading = null;
-  const read = () => (reading ??= (async () => {
-    try {
-      const response = await fetchImpl(`${base}/messages?tail=${tail}`, { headers: await headers(), signal: controller.signal });
-      if (!response.ok) throw failure('read', response.status, `reading the session failed (${response.status})`);
-      const body = await response.json();
-      onSnapshot(body.data ?? body);
-      return body.data ?? body;
-    } finally { reading = null; }
-  })());
+  let reading = null, requested = false;
+  const read = () => {
+    requested = true;
+    return reading ??= (async () => {
+      let snapshot;
+      do {
+        requested = false;
+        const response = await fetchImpl(`${base}/messages?tail=${tail}`, { headers: await headers(), signal: AbortSignal.any([controller.signal, AbortSignal.timeout(15000)]) });
+        if (!response.ok) throw failure('read', response.status, `reading the session failed (${response.status})`);
+        const body = await response.json();
+        if (controller.signal.aborted) throw new DOMException('Session follow stopped', 'AbortError');
+        snapshot = body.data ?? body;
+        onSnapshot(snapshot);
+        // A change during the HTTP read may be newer than the capture it
+        // returned. Coalesce the callers, but do not drop that invalidation.
+      } while (requested);
+      return snapshot;
+    })().finally(() => { reading = null; });
+  };
   (async () => {
-    let cursor = null;
+    let cursor = null, following = null, watched = null;
     while (!controller.signal.aborted) {
+      const connection = new AbortController();
+      following = connection;
+      let reader;
       try {
         if (!cursor) cursor = String((await read()).event_cursor ?? '') || null;
-        const response = await fetchImpl(`${base}/events?${cursor ? `after=${encodeURIComponent(cursor)}` : 'tail=1'}`, { headers: await headers(), signal: controller.signal });
+        const response = await fetchImpl(`${base}/events?${cursor ? `after=${encodeURIComponent(cursor)}` : 'tail=1'}`, { headers: await headers(), signal: AbortSignal.any([controller.signal, connection.signal]) });
         if (!response.ok) throw failure('follow', response.status, `following the session failed (${response.status})`);
         onLive(true);
-        const reader = response.body.getReader();
+        reader = response.body.getReader();
+        const decoder = new TextDecoder();
         let buffer = '';
         for (;;) {
           const { value, done } = await reader.read();
@@ -54,13 +66,33 @@ export function followTeamSession({ origin, teamId, sessionId, token, tail = 300
             // The server ends a stream it can no longer resume (a slow reader, a retired cursor): start from a snapshot.
             if (event.terminal && event.type === 'resync_required') cursor = null;
             if (event.type === 'snapshot') onSnapshot(event.data);
-            else if (event.type === 'session_changed') read().catch((error) => { if (!controller.signal.aborted) onError({ stage: error.stage ?? 'read', status: error.status ?? null, message: error.message }); });
+            else if (event.type === 'session_changed') {
+              const refresh = read();
+              // One recovery handler per coalesced read, including when a
+              // token-expiry reconnect overtakes the unfinished HTTP read.
+              if (watched !== refresh) {
+                watched = refresh;
+                void refresh.then(() => { if (watched === refresh) watched = null; }, (error) => {
+                  if (watched === refresh) watched = null;
+                  if (controller.signal.aborted) return;
+                  // Its event cursor advanced, but its snapshot was not read.
+                  // Recover even if no further message arrives.
+                  cursor = null;
+                  following?.abort();
+                  onError({ stage: error.stage ?? 'read', status: error.status ?? null, message: error.message, snapshot: true });
+                });
+              }
+            }
             else if (event.type === 'session_deleted') { onLive(false); onDeleted(); return; }
           }
         }
       } catch (error) {
         if (controller.signal.aborted) return;
-        onError({ stage: error.stage ?? 'follow', status: error.status ?? null, message: error.message, snapshot: Boolean(cursor) });
+        if (!connection.signal.aborted) onError({ stage: error.stage ?? 'follow', status: error.status ?? null, message: error.message, snapshot: Boolean(cursor) });
+      } finally {
+        if (following === connection) following = null;
+        connection.abort();
+        await reader?.cancel().catch(() => {});
       }
       onLive(false);
       await new Promise((resolve) => setTimeout(resolve, retryMs));
@@ -72,7 +104,7 @@ export function followTeamSession({ origin, teamId, sessionId, token, tail = 300
 /**
  * A message another session sent this one, as its harness delivers it: an envelope naming the sender (a
  * `cross-session-message` tag, the innermost one when the harness wraps it in its own) around the body. Returns
- * { name, address, body }, or null for an ordinary turn.
+ * { id, name, address, body, subject, via, inReplyTo }, or null for an ordinary turn.
  */
 export function peerMessage(text) {
   const close = text.search(/<\\?\/cross-session-message>/);
@@ -80,10 +112,15 @@ export function peerMessage(text) {
   const opens = [...text.slice(0, close).matchAll(/<\\?cross-session-message\b([^>]*)>/g)];
   if (!opens.length) return null;
   const inner = opens[opens.length - 1];
-  const attributes = (tag) => Object.fromEntries([...tag.matchAll(/([\w-]+)="([^"]*)"/g)].map((m) => [m[1], m[2]]));
+  // Match the producer's escaping, exactly once. An original literal &lt;
+  // arrives as &amp;lt; and must remain &lt;, rather than becoming a tag.
+  const entities = { amp: '&', lt: '<', gt: '>', quot: '"' };
+  const decodeAttribute = value => value.replace(/&(amp|lt|gt|quot);/g, (_, name) => entities[name]);
+  const attributes = (tag) => Object.fromEntries([...tag.matchAll(/([\w-]+)="([^"]*)"/g)].map((m) => [m[1], decodeAttribute(m[2])]));
   const own = attributes(inner[1]), outer = attributes(opens[0][1]);
-  const body = text.slice(inner.index + inner[0].length, close).trim();
-  return { id: own.id || outer.id || null, name: own['from-name'] || outer['from-name'] || own.from || outer.from || 'Another session', address: own.from || outer.from || '', body };
+  const body = text.slice(inner.index + inner[0].length, close).trim().replace(/&(amp|lt);/g, (_, name) => entities[name]);
+  return { id: own.id || outer.id || null, name: own['from-name'] || outer['from-name'] || own.from || outer.from || 'Another session', address: own.from || outer.from || '', body,
+    subject: own.subject || outer.subject || null, via: own.via || outer.via || null, inReplyTo: own['in-reply-to'] || outer['in-reply-to'] || null };
 }
 
 /** A known person's picture; an unnamed sender gets the neutral brand user icon. */
@@ -128,7 +165,7 @@ export function withPeople(transcript, messages, { agentName = null, sessionId =
     const peer = attributed ? null : peerMessage(entry.text);
     if (peer) {
       const seed = peer.address.startsWith('sc:') ? peer.address : peer.name;
-      return { ...entry, text: peer.body, mail: { id: peer.id || entry.id, from: peer.name, to: agentName || 'This session', direction: 'in' }, actor: { id: seed, name: peer.name, image: agent(seed), kind: 'agent' }, context: [{ id: `${entry.id}:envelope`, kind: 'envelope', label: 'Delivered by supercode', detail: entry.text }] };
+      return { ...entry, text: peer.body, mail: { id: peer.id || entry.id, from: peer.name, to: agentName || 'This session', direction: 'in', ...(peer.subject ? { subject: peer.subject } : {}), ...(peer.via === 'voice' ? { via: 'voice' } : {}), ...(peer.inReplyTo ? { inReplyTo: peer.inReplyTo } : {}) }, actor: { id: seed, name: peer.name, image: agent(seed), kind: 'agent' }, context: [{ id: `${entry.id}:envelope`, kind: 'envelope', label: 'Delivered by supercode', detail: entry.text }] };
     }
     const name = metadata.source_name || null;
     const seed = name ? (metadata.source_principal_id || name) : '';