@futurity/chat-react 0.0.2 → 0.1.0

package/README.md

@@ -1,13 +1,15 @@
 # @futurity/chat-react
 
-React hooks and utilities for embedding Futurity chat in any React application.
+React hooks and utilities for embedding Futurity chat in any React application. For non-React apps, the framework-agnostic `WebSocketConnection` class is also exported.
 
 ## Installation
 
 ```bash
-npm install @futurity/chat-react @futurity/chat-protocol react zod
+npm install @futurity/chat-react
 ```
 
+Peer dependencies: `react` (^18 or ^19) and `zod` (^4). `@futurity/chat-protocol` is included as a direct dependency.
+
 ## Quick Start
 
 ```tsx
@@ -26,33 +28,6 @@ function Chat({ chatId, apiUrl }: { chatId: string; apiUrl: string }) {
   } = useStreamChat({
     chatId,
     wsUrl: `${apiUrl}/api/v2/chat/${chatId}`,
-    onStart: (id) => {
-      // A new assistant message is about to stream
-      setMessages((prev) => [
-        ...prev,
-        { id, role: "assistant", parts: [{ type: "text", text: "" }] },
-      ]);
-    },
-    onDelta: (id, delta, consolidated) => {
-      // Append or replace the latest part
-      setMessages((prev) =>
-        prev.map((m) => {
-          if (m.id !== id) return m;
-          const parts = m.parts ?? [];
-          return {
-            ...m,
-            parts: consolidated
-              ? [...parts.slice(0, -1), delta]
-              : [...parts, delta],
-          };
-        }),
-      );
-    },
-    onResume: (id, parts) => {
-      setMessages((prev) =>
-        prev.map((m) => (m.id !== id ? m : { ...m, parts })),
-      );
-    },
     onHistory: (history) => {
       setMessages(history.initialPath);
     },
@@ -66,8 +41,12 @@ function Chat({ chatId, apiUrl }: { chatId: string; apiUrl: string }) {
       {messages.map((msg) => (
         <div key={msg.id}>
           <strong>{msg.role}:</strong>
-          {msg.parts
-            .filter((p): p is { type: "text"; text: string } => p.type === "text")
+          {msg.processedParts
+            .filter((p) => p.type === "regular")
+            .map((p) => p.type === "regular" ? p.part : null)
+            .filter((p): p is { type: "text"; text: string } =>
+              typeof p === "object" && p !== null && "type" in p && p.type === "text"
+            )
             .map((p, i) => (
               <span key={i}>{p.text}</span>
             ))}
@@ -94,60 +73,148 @@ function Chat({ chatId, apiUrl }: { chatId: string; apiUrl: string }) {
 }
 ```
 
+## Stream Accumulation
+
+`useStreamChat` handles all stream protocol internally. Messages returned in the `messages` array include a `processedParts` field that provides structured, pre-accumulated content:
+
+- **Text streaming**: Raw `text-start`/`text-delta`/`text-end` chunks are assembled into complete `{ type: "text", text: "..." }` parts.
+- **Tool calls**: Input deltas are accumulated and JSON-parsed incrementally. Output states are tracked through `input-streaming` → `input-available` → `output-available`.
+- **Subagent groups**: `data-split`/`data-endsplit`/`data-subagent-part` markers are grouped into `split-group` processed parts with their inner content accumulated.
+- **Inject handling**: `inject_ack` and `inject_split` server messages automatically create placeholder assistant messages so subsequent stream deltas land correctly.
+
+Each `processedPart` is either:
+- `{ type: "regular", part, originalIndex }` — a single accumulated part
+- `{ type: "split-group", title, subtitle, parts, startIndex, endIndex, desktopSessionId }` — a group of subagent parts
+
+Consumers no longer need `onDelta` or `onResume` callbacks — stream accumulation is handled internally.
+
+## Authentication
+
+The WebSocket endpoint requires a valid access token. Pass it as a query parameter in the URL:
+
+```ts
+useStreamChat({
+  chatId,
+  wsUrl: `wss://api.example.com/api/v2/chat/${chatId}?token=${accessToken}`,
+  // ...
+});
+```
+
+See the [external multi-tenant auth docs](https://github.com/futuritywork/api/blob/main/docs/external-multi-tenant-auth.md) for how to obtain tokens via OAuth 2.0 delegation.
+
 ## API
 
 ### `useStreamChat(options)`
 
-The main hook for connecting to a Futurity chat WebSocket.
+The main hook for connecting to a Futurity chat WebSocket. Manages the full lifecycle: connection, history loading, streaming, cancellation, and clarification flows. Stream deltas are accumulated internally — messages include pre-computed `processedParts`.
 
 **Options:**
 
-| Option     | Type       | Description                                               |
-| ---------- | ---------- | --------------------------------------------------------- |
-| `chatId`   | `string`   | The chat ID to connect to                                 |
-| `wsUrl`    | `string`   | Full WebSocket URL (e.g. `wss://api.example.com/api/v2/chat/<id>`) |
-| `onStart`  | `function` | Called when a new assistant message starts                 |
-| `onDelta`  | `function` | Called on each stream delta                                |
-| `onResume` | `function` | Called when a stream resumes with accumulated parts        |
-| `onFinish` | `function` | Called when streaming finishes                             |
-| `onError`  | `function` | Called on protocol errors                                  |
-| `onHistory`| `function` | Called when chat history is received                       |
+| Option     | Type       | Required | Description                                               |
+| ---------- | ---------- | -------- | --------------------------------------------------------- |
+| `chatId`   | `string`   | Yes      | The chat ID to connect to                                 |
+| `wsUrl`    | `string`   | Yes      | Full WebSocket URL (e.g. `wss://api.example.com/api/v2/chat/<id>`) |
+| `onStart`  | `(id: string) => void` | No | Called when a new assistant message starts streaming |
+| `onFinish` | `() => void` | No | Called when streaming finishes |
+| `onError`  | `(error: { error?: string; message?: string }) => void` | No | Called on protocol errors |
+| `onHistory`| `(history: TransformedHistory) => void` | No | Called when chat history is received. History includes `messages`, `tree`, `byId`, `initialPath`, and `activeMessageId` |
 
 **Returns:**
 
 | Property             | Type                    | Description                            |
 | -------------------- | ----------------------- | -------------------------------------- |
-| `messages`           | `ChatMessage[]`         | Current messages in the active branch  |
+| `messages`           | `ChatMessage[]`         | Current messages with `processedParts` |
 | `setMessages`        | `SetState<ChatMessage[]>` | Replace the message list             |
-| `sendMessage`        | `(payload) => Promise`  | Send a new user message                |
-| `injectMessage`      | `(text) => Promise`     | Inject text into an active stream      |
-| `status`             | `ChatStatus`            | `"ready"` / `"submitted"` / `"streaming"` / `"error"` |
-| `stop`               | `() => Promise`         | Cancel the current generation          |
+| `sendMessage`        | `(payload: SendMessagePayload) => Promise<void>` | Send a new user message |
+| `injectMessage`      | `(text: string) => Promise<void>` | Inject text into an active stream |
+| `status`             | `ChatStatus`            | `"ready"` \| `"submitted"` \| `"streaming"` \| `"error"` |
+| `stop`               | `() => Promise<void>`   | Cancel the current generation          |
 | `reset`              | `() => void`            | Reset all chat state                   |
 | `isConnected`        | `boolean`               | WebSocket connection status            |
 | `pendingClarify`     | `object \| null`        | Pending clarification request          |
-| `sendClarifyResponse`| `(answers) => void`     | Submit clarification answers           |
+| `sendClarifyResponse`| `(answers: Record<string, string>) => void` | Submit clarification answers |
 
 ### `useReconnectingWebSocket(options)`
 
-A generic WebSocket hook with automatic reconnection, heartbeat, and message queuing. Used internally by `useStreamChat`, but also available for custom WebSocket connections.
+A generic WebSocket hook with automatic reconnection, heartbeat (ping/pong), exponential backoff, and message queuing while disconnected. Used internally by `useStreamChat`, but available for custom WebSocket connections.
+
+```ts
+const { send, isConnected, ensureConnected, reconnect } =
+  useReconnectingWebSocket<ServerMsg, ClientCmd>({
+    url: "wss://api.example.com/ws",
+    onMessage: (msg) => console.log(msg),
+    enabled: true,
+  });
+```
+
+**Options:** `url`, `onMessage`, `onConnectionChange`, `onError`, `enabled`, `heartbeatInterval` (default 5s), `heartbeatTimeout` (default 10s), `initialReconnectDelay` (default 1s), `maxReconnectDelay` (default 30s), `debugPrefix`.
+
+**Returns:** `connectionState`, `isConnected`, `send()`, `ensureConnected()`, `reconnect()`.
+
+### `WebSocketConnection` (framework-agnostic)
+
+The underlying WebSocket class with no React dependency. Use this for Vue, Svelte, vanilla JS, or server-side integrations.
+
+```ts
+import { WebSocketConnection } from "@futurity/chat-react";
+
+const ws = new WebSocketConnection({
+  url: "wss://api.example.com/api/v2/chat/abc123",
+  onMessage: (data) => {
+    // data is already JSON-parsed
+    console.log(data);
+  },
+  onConnectionChange: (state) => {
+    // "disconnected" | "connecting" | "connected"
+    console.log("Connection:", state);
+  },
+});
+
+ws.connect();
+ws.send({ type: "get_chat", data: { chat_id: "abc123" } });
+
+// Later:
+ws.disconnect();
+```
+
+Features: automatic reconnection with exponential backoff, heartbeat ping/pong, message queuing while disconnected, JSON serialization.
 
 ### Tree Utilities
 
-- `buildTree(messages, byId)` - Build a navigable message tree from a flat array
-- `findLatestPath(tree, byId)` - Find the latest conversation path in a tree
-- `MessageNode` - Tree node class with `getChildren()`, `parent_id`, and `message`
+For branching conversation support (navigating conversation forks):
+
+```ts
+import { buildTree, findLatestPath, MessageNode } from "@futurity/chat-react";
+
+// Build a tree from flat messages (uses metadata.parent_id)
+const byId = new Map<string, MessageNode>();
+const roots = buildTree(messages, byId);
+
+// Find the latest conversation branch
+const latestPath = findLatestPath(roots, byId);
+```
 
 ### Protocol Types
 
-All chat WebSocket protocol types are re-exported from `@futurity/chat-protocol`:
+All chat protocol types are re-exported from `@futurity/chat-protocol`:
 
 ```ts
 import type {
+  MessagePart,
   WsClientCommand,
   WsServerMessage,
   WsStreamMessage,
   WsClarifyQuestion,
   WsVaultItem,
+  ChatMessage,
+  ChatStatus,
+  StreamDelta,
+  SendMessagePayload,
+  ProcessedPart,
+  PreprocessorState,
 } from "@futurity/chat-react";
 ```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -11,6 +11,82 @@ import { z } from 'zod';
 
 declare function parseServerMessage(data: unknown): WsServerMessage | null;
 
+type ProcessedPart = {
+    type: "regular";
+    part: MessagePart;
+    originalIndex: number;
+} | {
+    type: "split-group";
+    title?: string;
+    subtitle?: string;
+    parts: MessagePart[];
+    startIndex: number;
+    endIndex: number;
+    desktopSessionId?: string;
+};
+/**
+ * Incrementally accumulates raw UI message stream protocol chunks into
+ * rendered message parts. Maintains internal state so repeated calls with a
+ * growing `rawParts` array only process newly appended chunks.
+ *
+ * Internally tracks mutable objects via `Chunk` maps (text-by-id, tool-by-id)
+ * and casts to `MessagePart` at the output boundary. The constructed shapes
+ * conform to the `MessagePart` union at runtime.
+ */
+declare class StreamAccumulator {
+    readonly parts: MessagePart[];
+    private textById;
+    private reasoningById;
+    private toolById;
+    private partialToolText;
+    private processedCount;
+    private push;
+    /** Process any new raw chunks and return the full accumulated parts array. */
+    accumulate(rawParts: unknown[]): MessagePart[];
+}
+type PendingGroup = {
+    startIndex: number;
+    title?: string;
+    subtitle?: string;
+    desktopSessionId?: string;
+    subAgentId: string;
+    /** Raw stream protocol chunks from data-subagent-part messages (pre-accumulation). */
+    innerParts: unknown[];
+    endIndex: number | null;
+};
+type PreprocessorState = {
+    messageId: string | null;
+    /** How many raw parts pass 1 has already scanned. */
+    scannedLength: number;
+    /** Indices consumed by subAgentId-based groups. */
+    claimedIndices: Set<number>;
+    /** Groups still collecting inner parts (keyed by subAgentId). */
+    openGroups: Map<string, PendingGroup>;
+    /** All groups keyed by their startIndex (for pass 2 lookup). */
+    groupsByStartIndex: Map<number, PendingGroup>;
+    /** Reverse lookup: subAgentId → group (includes closed groups). */
+    groupBySubAgentId: Map<string, PendingGroup>;
+    /** Per-group stream accumulators (keyed by group startIndex). */
+    accumulators: Map<number, StreamAccumulator>;
+};
+declare function createPreprocessorState(messageId?: string): PreprocessorState;
+/**
+ * Incrementally preprocess message parts to group subagent content.
+ *
+ * Pass 1 (incremental): only scans parts appended since the last call,
+ * building group data structures without re-parsing already-seen parts.
+ *
+ * Per-group accumulation (incremental): each group's stream protocol chunks
+ * are accumulated via a stateful {@link StreamAccumulator} that only processes
+ * new chunks on each call.
+ *
+ * Pass 2 (rebuild): constructs the output array from cached state. This is
+ * cheap — O(n) Map/Set lookups with no Zod parsing for subAgentId groups.
+ *
+ * Falls back to legacy greedy scanning for old messages without subAgentId.
+ */
+declare function incrementalPreprocess(state: PreprocessorState, parts: MessagePart[]): ProcessedPart[];
+
 declare const messageMetadataSchema: z.ZodObject<{
     parent_id: z.ZodNullable<z.ZodUUID>;
 }, z.core.$strip>;
@@ -20,6 +96,8 @@ type ChatMessage = {
     id: string;
     role: "user" | "assistant" | "system";
     parts: MessagePart[];
+    /** Pre-computed processed parts with subagent grouping and stream accumulation. */
+    processedParts: ProcessedPart[];
     createdAt?: Date;
     metadata?: MessageMetadata;
 };
@@ -373,10 +451,6 @@ type UseStreamChatOptions = {
     wsUrl: string;
     /** Called when a new assistant message starts streaming. */
     onStart?: (id: string) => void;
-    /** Called on each stream delta. */
-    onDelta?: (id: string, delta: StreamDelta, consolidated: boolean) => void;
-    /** Called when a stream resumes with accumulated parts. */
-    onResume?: (id: string, parts: MessagePart[]) => void;
     /** Called when streaming finishes. */
     onFinish?: () => void;
     /** Called on a protocol error. */
@@ -409,6 +483,6 @@ type UseStreamChatReturn = {
     /** Submit answers to a clarification request. */
     sendClarifyResponse: (answers: Record<string, string>) => void;
 };
-declare function useStreamChat({ chatId, wsUrl, onStart, onDelta, onResume, onFinish, onError, onHistory, }: UseStreamChatOptions): UseStreamChatReturn;
+declare function useStreamChat({ chatId, wsUrl, onStart, onFinish, onError, onHistory, }: UseStreamChatOptions): UseStreamChatReturn;
 
-export { type ChatMessage, type ChatStatus, type ClarifyData, type ConnectionState, type MessageMetadata, MessageNode, type SendMessageFn, type SendMessagePayload, type StreamDelta, type UseStreamChatOptions, type UseStreamChatReturn, WebSocketConnection, type WebSocketConnectionOptions, type WebSocketOptions, type WebSocketResult, Z_ChatMessage, buildTree, findLatestPath, messageMetadataSchema, parseServerMessage, useReconnectingWebSocket, useStreamChat };
+export { type ChatMessage, type ChatStatus, type ClarifyData, type ConnectionState, type MessageMetadata, MessageNode, type PreprocessorState, type ProcessedPart, type SendMessageFn, type SendMessagePayload, StreamAccumulator, type StreamDelta, type UseStreamChatOptions, type UseStreamChatReturn, WebSocketConnection, type WebSocketConnectionOptions, type WebSocketOptions, type WebSocketResult, Z_ChatMessage, buildTree, createPreprocessorState, findLatestPath, incrementalPreprocess, messageMetadataSchema, parseServerMessage, useReconnectingWebSocket, useStreamChat };