@arcote.tech/arc-chat 0.5.7 → 0.5.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-chat",
   "type": "module",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "private": false,
   "description": "Chat module with AI integration for Arc framework",
   "main": "./src/index.ts",
@@ -10,11 +10,11 @@
     "type-check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.5.7",
-    "@arcote.tech/arc-ai": "^0.5.7",
-    "@arcote.tech/arc-auth": "^0.5.7",
-    "@arcote.tech/arc-ds": "^0.5.7",
-    "@arcote.tech/platform": "^0.5.7",
+    "@arcote.tech/arc": "^0.5.8",
+    "@arcote.tech/arc-ai": "^0.5.8",
+    "@arcote.tech/arc-auth": "^0.5.8",
+    "@arcote.tech/arc-ds": "^0.5.8",
+    "@arcote.tech/platform": "^0.5.8",
     "lucide-react": ">=0.400.0",
     "react": ">=18.0.0",
     "typescript": "^5.0.0"

package/src/aggregates/message.ts

@@ -107,36 +107,55 @@ export const createMessageAggregate = <
       },
     )
 
-    // ─── assistantResponded — AI generates one turn ─────────────
-    // The `blocks` field is the JSON-serialized AssistantContentBlock[]
-    // produced by the provider for this single turn — text and tool_call
-    // blocks interleaved in the order the model emitted them.
+    // ─── assistantTurnStarted — new assistant row, isGenerating=true ─
+    // Created at the start of each LLM turn. The row exists in DB without
+    // blocks; the frontend detects `isGenerating: true` and subscribes to the
+    // SSE stream identified by `sessionId`.
     .publicEvent(
-      "assistantResponded",
+      "assistantTurnStarted",
       {
         messageId,
         scopeId,
         sessionId: string(),
-        blocks: string(),
         model: string().optional(),
-        previousResponseId: string().optional(),
-        isGenerating: boolean().optional(),
       },
       async (ctx, event) => {
         const p = event.payload;
         await ctx.set(p.messageId, {
           scopeId: p.scopeId,
           role: "assistant",
-          blocks: p.blocks,
           model: p.model,
           sessionId: p.sessionId,
-          previousResponseId: p.previousResponseId,
-          isGenerating: p.isGenerating,
+          isGenerating: true,
           createdAt: event.createdAt,
         });
       },
     )
 
+    // ─── assistantTurnCompleted — finalize an in-progress turn row ───
+    // Partial update on the SAME row — fills `blocks`, flips
+    // `isGenerating` to false, optionally records `previousResponseId`,
+    // `usage`, or `error`.
+    .publicEvent(
+      "assistantTurnCompleted",
+      {
+        messageId,
+        blocks: string(),
+        previousResponseId: string().optional(),
+        usage: string().optional(),
+        error: string().optional(),
+      },
+      async (ctx, event) => {
+        const p = event.payload;
+        await ctx.modify(p.messageId, {
+          blocks: p.blocks,
+          previousResponseId: p.previousResponseId,
+          usage: p.usage,
+          isGenerating: false,
+        } as any);
+      },
+    )
+
     // ─── toolExecuted — server tool returns result ──────────────
     .publicEvent(
       "toolExecuted",
@@ -188,25 +207,6 @@ export const createMessageAggregate = <
       },
     )
 
-    // ─── generationCompleted — AI loop finished ─────────────────
-    .publicEvent(
-      "generationCompleted",
-      {
-        messageId,
-        sessionId: string(),
-        usage: string().optional(),
-      },
-      async (ctx, event) => {
-        const p = event.payload;
-        // PARTIAL update — `ctx.set` replaces the whole row and would null
-        // out scopeId/role/blocks. Use `modify` to only flip isGenerating.
-        await ctx.modify(p.messageId, {
-          isGenerating: false,
-          usage: p.usage,
-        } as any);
-      },
-    )
-
     // ─── sendMessage — user sends message, creates session ──────
     .mutateMethod(
       "sendMessage",
@@ -233,36 +233,55 @@ export const createMessageAggregate = <
       ),
     )
 
-    // ─── saveAssistantMessage ───────────────────────────────────
-    // `blocks` is the JSON-serialized AssistantContentBlock[] from the
-    // provider's response — single source of truth for the model's output.
+    // ─── startAssistantTurn — open an in-progress assistant row ────
+    // Generates a fresh messageId, emits `assistantTurnStarted`. The row
+    // exists with `isGenerating: true` and no `blocks` until
+    // `completeAssistantTurn` fills them in.
     .mutateMethod(
-      "saveAssistantMessage",
+      "startAssistantTurn",
       (fn) => fn.withParams({
         scopeId,
         sessionId: string(),
-        blocks: string(),
         model: string().optional(),
-        previousResponseId: string().optional(),
-        isGenerating: boolean().optional(),
       }).handle(
         ONLY_SERVER &&
         (async (ctx, params) => {
           const msgId = messageId.generate();
-          await ctx.assistantResponded.emit({
+          await ctx.assistantTurnStarted.emit({
             messageId: msgId,
             scopeId: params.scopeId,
             sessionId: params.sessionId,
-            blocks: params.blocks,
             model: params.model,
-            previousResponseId: params.previousResponseId,
-            isGenerating: params.isGenerating,
           });
           return { messageId: msgId };
         }),
       ),
     )
 
+    // ─── completeAssistantTurn — partial update of the open turn row ─
+    .mutateMethod(
+      "completeAssistantTurn",
+      (fn) => fn.withParams({
+        messageId,
+        blocks: string(),
+        previousResponseId: string().optional(),
+        usage: string().optional(),
+        error: string().optional(),
+      }).handle(
+        ONLY_SERVER &&
+        (async (ctx, params) => {
+          await ctx.assistantTurnCompleted.emit({
+            messageId: params.messageId,
+            blocks: params.blocks,
+            previousResponseId: params.previousResponseId,
+            usage: params.usage,
+            error: params.error,
+          });
+          return { ok: true };
+        }),
+      ),
+    )
+
     // ─── saveToolResult — server tool executed ──────────────────
     .mutateMethod(
       "saveToolResult",
@@ -291,26 +310,6 @@ export const createMessageAggregate = <
       ),
     )
 
-    // ─── completeGeneration ─────────────────────────────────────
-    .mutateMethod(
-      "completeGeneration",
-      (fn) => fn.withParams({
-        generationMessageId: messageId,
-        sessionId: string(),
-        usage: string().optional(),
-      }).handle(
-        ONLY_SERVER &&
-        (async (ctx, params) => {
-          await ctx.generationCompleted.emit({
-            messageId: params.generationMessageId,
-            sessionId: params.sessionId,
-            usage: params.usage,
-          });
-          return { ok: true };
-        }),
-      ),
-    )
-
     // ─── respondToTool — user answers interactive tool ──────────
     .mutateMethod(
       "respondToTool",

package/src/index.ts

@@ -7,12 +7,7 @@ export { createMessageAggregate, createMessageId } from "./aggregates/message";
 export type { MessageAggregate, MessageId } from "./aggregates/message";
 
 // --- Streaming ---
-export {
-  createStreamSession,
-  getStreamSession,
-  deleteStreamSession,
-} from "./streaming/stream-registry";
-export type { StreamSession } from "./streaming/stream-registry";
+export { broadcast, endStream, hasActiveStream, subscribe } from "./streaming/stream-registry";
 
 // --- Listener ---
 export { createAiGenerationListener } from "./listeners/ai-generation-listener";

package/src/listeners/ai-generation-listener.ts

@@ -182,7 +182,6 @@ interface RunLoopConfig {
   toolDefs: any[] | undefined;
   serverToolsMap: Map<string, ArcToolAny>;
   interactiveToolNames: Set<string>;
-  generationMessageId: string;
   scopeId: string;
   sessionId: string;
   maxExecutionCount: number;
@@ -199,7 +198,6 @@ async function runGenerationLoop(config: RunLoopConfig) {
     toolDefs,
     serverToolsMap,
     interactiveToolNames,
-    generationMessageId,
     scopeId,
     sessionId,
     maxExecutionCount,
@@ -210,6 +208,11 @@ async function runGenerationLoop(config: RunLoopConfig) {
   let history = config.history;
   let newTurnsStartIdx = config.initialNewTurnsStartIdx;
   let executionCount = 0;
+  /** The in-progress assistant row for the CURRENT iteration. Set at the top
+   *  of every iteration via `startAssistantTurn`; closed at the bottom via
+   *  `completeAssistantTurn`. The error handler uses it to mark the open turn
+   *  as failed. */
+  let currentTurnId: string | undefined;
 
   try {
     while (executionCount <= maxExecutionCount) {
@@ -230,6 +233,14 @@ async function runGenerationLoop(config: RunLoopConfig) {
         newTurnsStartIdx,
       );
 
+      // Open a new in-progress assistant row before the stream starts. The
+      // frontend detects `isGenerating: true` on this row and subscribes to
+      // the SSE stream identified by `sessionId`.
+      const turnStart = await ctx
+        .mutate(messageElement)
+        .startAssistantTurn({ scopeId, sessionId, model });
+      currentTurnId = turnStart.messageId;
+
       const result = await provider.streamComplete(
         {
           model,
@@ -255,17 +266,6 @@ async function runGenerationLoop(config: RunLoopConfig) {
         },
       );
 
-      // Persist this turn's assistant blocks as a single message row.
-      if (result.blocks.length > 0) {
-        await ctx.mutate(messageElement).saveAssistantMessage({
-          scopeId,
-          sessionId,
-          blocks: JSON.stringify(result.blocks),
-          model,
-          previousResponseId: result.responseId,
-        });
-      }
-
       // Append to local history so the next iteration sees this turn.
       const assistantTurn: ConversationTurn = {
         role: "assistant",
@@ -285,12 +285,18 @@ async function runGenerationLoop(config: RunLoopConfig) {
       const hasToolCalls =
         result.finishReason === "tool_call" && toolCalls.length > 0;
 
+      // Close the turn row — same row that was opened above. The final turn
+      // (no tool calls) carries the usage; intermediate turns carry only the
+      // blocks + responseId.
+      await ctx.mutate(messageElement).completeAssistantTurn({
+        messageId: currentTurnId!,
+        blocks: JSON.stringify(result.blocks),
+        previousResponseId: result.responseId,
+        usage: hasToolCalls ? undefined : JSON.stringify(result.usage),
+      });
+      currentTurnId = undefined;
+
       if (!hasToolCalls) {
-        await ctx.mutate(messageElement).completeGeneration({
-          generationMessageId,
-          sessionId,
-          usage: JSON.stringify(result.usage),
-        });
         broadcast(sessionId, {
           type: "done",
           sessionId,
@@ -390,18 +396,22 @@ async function runGenerationLoop(config: RunLoopConfig) {
       executionCount++;
     }
   } catch (err) {
+    const errorMsg = `AI error: ${err instanceof Error ? err.message : String(err)}`;
     broadcast(sessionId, {
       type: "error",
       sessionId,
-      error: `AI error: ${err instanceof Error ? err.message : String(err)}`,
+      error: errorMsg,
       executionCount,
     });
-    try {
-      await ctx.mutate(messageElement).completeGeneration({
-        generationMessageId,
-        sessionId,
-      });
-    } catch {}
+    if (currentTurnId) {
+      try {
+        await ctx.mutate(messageElement).completeAssistantTurn({
+          messageId: currentTurnId,
+          blocks: "[]",
+          error: errorMsg,
+        });
+      } catch {}
+    }
     endStream(sessionId);
   }
 }
@@ -458,18 +468,6 @@ export function createAiGenerationListener(config: AiGenerationListenerConfig) {
       const newTurnsStartIdx = history.length;
       history.push({ role: "user", content: userContent });
 
-      // Placeholder assistant message so the UI can render "AI is typing".
-      // Empty blocks; the real one is saved by the loop after streaming.
-      const generationResult = await ctx
-        .mutate(messageElement)
-        .saveAssistantMessage({
-          scopeId,
-          sessionId,
-          blocks: "[]",
-          model,
-          isGenerating: true,
-        });
-
       await runGenerationLoop({
         ctx,
         messageElement,
@@ -480,7 +478,6 @@ export function createAiGenerationListener(config: AiGenerationListenerConfig) {
         toolDefs,
         serverToolsMap,
         interactiveToolNames,
-        generationMessageId: generationResult.messageId,
         scopeId,
         sessionId,
         maxExecutionCount,
@@ -557,17 +554,6 @@ export function createAiResumeListener(config: AiGenerationListenerConfig) {
       const provider = resolveProvider(model, scopeId);
       if (!provider) return;
 
-      // Placeholder assistant message for "AI is typing"
-      const generationResult = await ctx
-        .mutate(messageElement)
-        .saveAssistantMessage({
-          scopeId,
-          sessionId,
-          blocks: "[]",
-          model,
-          isGenerating: true,
-        });
-
       void toolName;
       void toolResult;
 
@@ -581,7 +567,6 @@ export function createAiResumeListener(config: AiGenerationListenerConfig) {
         toolDefs,
         serverToolsMap,
         interactiveToolNames,
-        generationMessageId: generationResult.messageId,
         scopeId,
         sessionId,
         maxExecutionCount,

package/src/react/chat-component.tsx

@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef, useEffect, type ComponentType, createElement, type ReactNode } from "react";
+import { useState, useCallback, useMemo, useRef, useEffect, type ComponentType, createElement, type ReactNode } from "react";
 import type { ChatStreamEvent, ArcToolAny } from "@arcote.tech/arc-ai";
 import type { ChatLabels, ChatMessageData, SendMessageOptions } from "@arcote.tech/arc-ds";
 import { Chat, ChatMessage, ChatInputProvider, ChatLabelsProvider, ChatToolLog, useChatLabels } from "@arcote.tech/arc-ds";
@@ -53,7 +53,6 @@ export function createChatComponent(
     const [isStreaming, setIsStreaming] = useState(false);
     const sessionIdRef = useRef<string | null>(null);
     const currentAssistantIdRef = useRef<string | null>(null);
-    const lastHistoryLenRef = useRef(0);
     const resumedSessionRef = useRef<string | null>(null);
 
     const queries = scope.useQuery();
@@ -68,11 +67,24 @@ export function createChatComponent(
     const historyData = historyResult?.[0];
     const historyLen = historyData?.length ?? 0;
 
+    // Stable signature of all messages — `[id]:[isGenerating]:[hasBlocks]:[contentLen]`.
+    // Changes on insert AND on partial update (e.g. ctx.modify flipping
+    // isGenerating to false), so the timeline-rebuild effect refires for
+    // both cases. `historyLen` alone misses updates that don't change count.
+    const historySig = useMemo(
+      () =>
+        historyData
+          ?.map(
+            (m: any) =>
+              `${m._id}:${m.isGenerating ? 1 : 0}:${m.blocks ? "f" : "e"}:${m.content?.length ?? 0}`,
+          )
+          .join("|") ?? "",
+      [historyData],
+    );
+
     // ─── Restore timeline from DB history ───────────────────────
     useEffect(() => {
       if (isStreaming || !historyData || historyLen === 0) return;
-      if (historyLen === lastHistoryLenRef.current) return;
-      lastHistoryLenRef.current = historyLen;
 
       const resultIds = new Set<string>();
       const resultMap = new Map<string, { content: string; isError?: boolean }>();
@@ -103,22 +115,30 @@ export function createChatComponent(
         }
 
         if (msg.role === "assistant") {
-          // Placeholder row created at the start of generation. We track its
-          // session for SSE reconnect, but don't render it yet — the loop
-          // will save the real assistant row with `blocks` once streaming
-          // completes.
-          const blocksStr = msg.blocks ?? "";
-          if (msg.isGenerating && !blocksStr) {
+          // Open turn (in progress). The row exists with `isGenerating: true`
+          // and no blocks; the SSE stream identified by `sessionId` will
+          // populate this bubble live. Use msg._id as the bubble id so the
+          // next rebuild (after `assistantTurnCompleted` flips the flag and
+          // sets blocks) replaces this bubble naturally.
+          if (msg.isGenerating === true) {
             if (msg.sessionId) sessionIdRef.current = msg.sessionId;
             hasActiveGeneration = true;
+            items.push({
+              type: "message",
+              id: msg._id,
+              role: "assistant",
+              content: "",
+              isStreaming: true,
+            });
+            currentAssistantIdRef.current = msg._id;
             continue;
           }
 
-          // Walk the assistant's blocks in order — each TextBlock becomes a
+          // Closed turn — render from blocks. Each TextBlock becomes a
           // message item, each ToolCallBlock becomes a tool item paired with
           // its result row.
           const blocks =
-            (tryParseJson(blocksStr) as Array<
+            (tryParseJson(msg.blocks ?? "") as Array<
               | { type: "text"; text: string }
               | {
                   type: "tool_call";
@@ -154,8 +174,6 @@ export function createChatComponent(
             }
             blockIdx++;
           }
-
-          if (msg.isGenerating === true) hasActiveGeneration = true;
         }
       }
 
@@ -163,7 +181,7 @@ export function createChatComponent(
       if (!isStreaming && hasActiveGeneration) {
         setIsStreaming(true);
       }
-    }, [historyLen, isStreaming]);
+    }, [historySig, isStreaming]);
 
     // ─── SSE stream consumer ────────────────────────────────────
     // Reusable: handles fetch + read loop + processEvent dispatch.

package/src/streaming/stream-registry.ts

@@ -1,11 +1,24 @@
 import type { ChatStreamEvent } from "@arcote.tech/arc-ai";
 
-// ─── ChatStreamManager — per message ID streaming ──────────────
+// ─── ChatStreamManager — per session SSE registry with replay buffer ───
+//
+// Per-session state:
+//  - `streams[sessionId]` — live controllers currently subscribed
+//  - `buffers[sessionId]` — every event broadcast since the session started,
+//    so a late subscriber (e.g. after a page refresh mid-generation) gets
+//    the full prefix replayed before going live
+//  - `keepAliveIntervals[sessionId]` — heartbeat ping interval
 
 const streams = new Map<string, Set<ReadableStreamDefaultController<Uint8Array>>>();
+const buffers = new Map<string, ChatStreamEvent[]>();
 const keepAliveIntervals = new Map<string, ReturnType<typeof setInterval>>();
 const encoder = new TextEncoder();
 
+/** Hard cap on per-session buffer size. Each typical generation produces a
+ *  few hundred chunks; 5000 is generous but bounds memory if a stream
+ *  somehow runs without `endStream`. */
+const MAX_BUFFER = 5000;
+
 function encode(event: ChatStreamEvent): Uint8Array {
   return encoder.encode(`data: ${JSON.stringify(event)}\n\n`);
 }
@@ -14,9 +27,18 @@ function encodePing(): Uint8Array {
   return encoder.encode(`: ping\n\n`);
 }
 
-export function broadcast(messageId: string, event: ChatStreamEvent): void {
-  const controllers = streams.get(messageId);
-  if (!controllers) return;
+export function broadcast(sessionId: string, event: ChatStreamEvent): void {
+  // Append to the replay buffer first — even if no client is currently
+  // subscribed (initial connect race) the event survives for replay.
+  let buf = buffers.get(sessionId);
+  if (!buf) {
+    buf = [];
+    buffers.set(sessionId, buf);
+  }
+  if (buf.length < MAX_BUFFER) buf.push(event);
+
+  const controllers = streams.get(sessionId);
+  if (!controllers || controllers.size === 0) return;
   const data = encode(event);
   for (const controller of controllers) {
     try {
@@ -27,42 +49,64 @@ export function broadcast(messageId: string, event: ChatStreamEvent): void {
   }
 }
 
-export function subscribe(messageId: string): ReadableStream<Uint8Array> {
+export function subscribe(sessionId: string): ReadableStream<Uint8Array> {
   return new ReadableStream<Uint8Array>({
     start(controller) {
-      let set = streams.get(messageId);
+      // Replay any buffered events before going live, so a client that
+      // connects mid-stream sees the full prefix.
+      const buf = buffers.get(sessionId);
+      if (buf) {
+        for (const e of buf) {
+          try {
+            controller.enqueue(encode(e));
+          } catch {
+            return;
+          }
+        }
+      }
+
+      let set = streams.get(sessionId);
       if (!set) {
         set = new Set();
-        streams.set(messageId, set);
+        streams.set(sessionId, set);
       }
       set.add(controller);
 
       // Start keep-alive if not running
-      if (!keepAliveIntervals.has(messageId)) {
+      if (!keepAliveIntervals.has(sessionId)) {
         const interval = setInterval(() => {
-          const s = streams.get(messageId);
+          const s = streams.get(sessionId);
           if (s && s.size > 0) {
             const ping = encodePing();
             for (const c of s) {
               try { c.enqueue(ping); } catch { s.delete(c); }
             }
-          } else {
-            cleanup(messageId);
+          } else if (!buffers.has(sessionId)) {
+            // Stream truly inactive: no live clients AND no buffer. Stop
+            // pinging. We never proactively drop the buffer here — that
+            // happens in `endStream` so a late re-subscribe still gets the
+            // full replay.
+            cleanup(sessionId);
           }
         }, 5000);
-        keepAliveIntervals.set(messageId, interval);
+        keepAliveIntervals.set(sessionId, interval);
       }
     },
     cancel() {
-      // One client disconnected — don't cleanup everything
+      // One client disconnected — don't tear down session state. The buffer
+      // and other subscribers (if any) remain.
     },
   });
 }
 
-export function endStream(messageId: string): void {
-  const controllers = streams.get(messageId);
+/** Called by the AI generation listener when a turn finishes (success or
+ *  error). Closes all live SSE streams and drops the replay buffer. After
+ *  this, a fresh `subscribe(sessionId)` returns an empty stream — the
+ *  client should fall back to reading the final `blocks` from DB. */
+export function endStream(sessionId: string): void {
+  const controllers = streams.get(sessionId);
   if (controllers) {
-    const done = encode({ type: "done", sessionId: messageId } as any);
+    const done = encode({ type: "done", sessionId } as any);
     for (const controller of controllers) {
       try {
         controller.enqueue(done);
@@ -70,45 +114,20 @@ export function endStream(messageId: string): void {
       } catch {}
     }
   }
-  cleanup(messageId);
+  cleanup(sessionId);
 }
 
-export function hasActiveStream(messageId: string): boolean {
-  const s = streams.get(messageId);
+export function hasActiveStream(sessionId: string): boolean {
+  const s = streams.get(sessionId);
   return !!s && s.size > 0;
 }
 
-function cleanup(messageId: string): void {
-  const interval = keepAliveIntervals.get(messageId);
+function cleanup(sessionId: string): void {
+  const interval = keepAliveIntervals.get(sessionId);
   if (interval) {
     clearInterval(interval);
-    keepAliveIntervals.delete(messageId);
+    keepAliveIntervals.delete(sessionId);
   }
-  streams.delete(messageId);
-}
-
-// ─── Legacy exports (for respondToTool compatibility) ───────────
-// TODO: remove after full migration
-
-export interface StreamSession {
-  readonly sessionId: string;
-  push(event: ChatStreamEvent): void;
-  close(): void;
-  isClosed(): boolean;
-}
-
-export function createStreamSession(sessionId: string): StreamSession {
-  let closed = false;
-  return {
-    sessionId,
-    push(event) { broadcast(sessionId, event); },
-    close() { closed = true; },
-    isClosed() { return closed; },
-  };
+  streams.delete(sessionId);
+  buffers.delete(sessionId);
 }
-
-export function getStreamSession(sessionId: string): StreamSession | undefined {
-  return undefined;
-}
-
-export function deleteStreamSession(sessionId: string): void {}