@dremio/js-sdk 0.45.2 → 0.45.4

package/README.md

@@ -360,6 +360,43 @@ const history = await conversation.history();
 console.log(`Conversation has ${history.length} events`);
 ```
 
+#### Stop a Run
+
+Stop the currently active run for a conversation:
+
+```typescript
+await conversation.stopRun(runId);
+```
+
+Note: Only one run can be active per conversation at a time.
+
+#### Clone a Conversation
+
+Create a copy of the conversation instance:
+
+```typescript
+const conversationCopy = conversation.clone();
+```
+
+#### Serialize Conversation
+
+Convert the conversation to a plain JSON object:
+
+```typescript
+const json = conversation.toJSON();
+console.log(json);
+// {
+//   id: "...",
+//   title: "...",
+//   createdAt: Temporal.Instant,
+//   modifiedAt: Temporal.Instant,
+//   currentRunId: "..." | null,
+//   modelName: "..." | null,
+//   modelProviderId: "..." | null,
+//   tag: "..."
+// }
+```
+
 ### Working with Chat Events
 
 The state of a conversation is represented as a stream of `ChatEvent` objects. These events include user messages, tool call requests and results, and Agent replies. While the event stream enables incremental UI updates, it contains implicit relationships that need to be made explicit for easier consumption.
@@ -371,16 +408,36 @@ The state of a conversation is represented as a stream of `ChatEvent` objects. T
 - `toolRequest` - A request to execute a tool (tool calls can run in parallel)
 - `toolResponse` - The result of a tool execution
 - `error` - An error message
+- `conversationUpdate` - Updates to conversation metadata (title, summary)
+- `endOfStream` - Marks the end of a run's event stream
 
 #### Building a Conversation Snapshot
 
-The `AgentConversation.reduceChatEvents()` method transforms a stream of chat events into a structured snapshot that makes implicit relationships explicit:
+The `AgentConversation.reduceChatEvents()` method is a pure reducer function that transforms a stream of chat events into a structured snapshot that makes implicit relationships explicit.
+
+**Function Signature:**
+
+```typescript
+function reduceChatEvents(
+  state: ConversationExchange[],
+  chatEvents: ChatEvent[],
+): ConversationExchange[];
+```
+
+**What it does:**
 
 - **Groups events by exchange** - Each user-agent interaction (identified by `runId`) becomes a separate exchange
 - **Pairs tool calls** - Tool requests and responses are matched by `callId` and combined into a single object
-- **Derives tool state** - Automatically determines if a tool call is `pending`, `success`, or `error`
-- **Handles duplicates** - Efficiently filters duplicate events when merging history and live streams
-- **Preserves order** - Maintains insertion order for messages and tool calls
+- **Derives tool state** - Automatically determines if a tool call is `pending`, `success`, `error`, or `canceled`
+  - `pending` - Tool request received but no response yet
+  - `success` - Tool response received without error
+  - `error` - Tool response received with error message
+  - `canceled` - End of stream reached without receiving a response
+- **Handles duplicates** - Efficiently filters duplicate events when merging history and live streams (events with the same `id` are deduplicated)
+- **Preserves order** - Maintains insertion order for messages and tool calls using `Map` data structures
+- **Immutable updates** - Uses structural sharing to efficiently create new snapshots without mutating the original state
+
+**Basic Usage:**
 
 ```typescript
 import { AgentConversation } from "@dremio/js-sdk/enterprise/ai";
@@ -404,12 +461,110 @@ type ConversationExchange = {
   submittedUserMessage?: UserChatMessage;
 };
 
+type ConversationExchangeMessage =
+  | ChatEventWithChunkType<"error">
+  | ChatEventWithChunkType<"model">
+  | ChatEventWithChunkType<"userMessage">;
+
 type AgentToolCall = {
   id: string;
-  state: "error" | "pending" | "success";
+  state: "canceled" | "error" | "pending" | "success";
   request: ChatEventWithChunkType<"toolRequest"> | undefined;
   result: ChatEventWithChunkType<"toolResponse"> | undefined;
 };
+
+// ChatEvent is the base type for all events in the stream
+type ChatEvent = {
+  id: string;
+  conversationId: string;
+  runId: string;
+  createdAt: Temporal.Instant;
+  modelName: string;
+  modelProviderId: string;
+  role: "agent" | "user";
+  content:
+    | { chunkType: "conversationUpdate"; title?: string; summary?: string }
+    | { chunkType: "endOfStream" }
+    | { chunkType: "error"; message: string }
+    | { chunkType: "model"; name: string; result: Record<string, unknown> }
+    | {
+        chunkType: "toolRequest";
+        callId: string;
+        name: string;
+        arguments: Record<string, unknown>;
+        commentary?: string;
+        summarizedTitle?: string;
+      }
+    | {
+        chunkType: "toolResponse";
+        callId: string;
+        name: string;
+        result: Record<string, unknown>;
+        commentary?: string;
+      }
+    | { chunkType: "userMessage"; text: string };
+};
+
+// ChatEventWithChunkType is a helper type to extract events by their chunk type
+type ChatEventWithChunkType<T extends ChatEvent["content"]["chunkType"]> =
+  Extract<ChatEvent, { content: { chunkType: T } }>;
+```
+
+#### UI Rendering and React Reconciliation
+
+The conversation snapshot produced by the reducer (and automatically managed by the `AgentConversationMachine`) is designed specifically for modern declarative UIs like React, Vue, Svelte, or Ink.
+
+**You do not need to manually track message IDs, buffer stream chunks, or manage parallel tool call states.**
+
+The reducer performs highly optimized, **immutable updates** as new events arrive. Because the top-level references change only when the underlying data changes, you can directly map over the snapshot in your render function. It is safe to pass these objects into memoized components (e.g., `React.memo`) without writing complex deep-equality checks or manual diffing logic.
+
+**React Example:**
+
+```typescript
+import { createActor } from "xstate";
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
+
+const actor = createActor(conversationMachine, {
+  input: { conversationId: null },
+});
+
+// Subscribe to state changes and update React state
+actor.subscribe((snapshot) => {
+  setExchanges(snapshot.context.conversationSnapshot ?? []);
+});
+
+actor.start();
+
+// In your render function - direct mapping, no manual diffing needed
+return (
+  <div>
+    {exchanges.map((exchange) => (
+      <Exchange key={exchange.id} exchange={exchange} />
+    ))}
+  </div>
+);
+```
+
+**Why this works:**
+
+- The reducer uses **structural sharing** via the `mutative` library, creating new object references only for changed data
+- Unchanged exchanges and messages retain their original references, enabling efficient React reconciliation
+- Maps preserve insertion order and provide O(1) lookups by ID
+- Tool calls are automatically paired and their state is derived, eliminating manual tracking logic
+
+**Vue/Svelte Example:**
+
+```typescript
+// The same principle applies - just bind to the snapshot
+actor.subscribe((snapshot) => {
+  conversationSnapshot = snapshot.context.conversationSnapshot ?? [];
+});
+```
+
+```svelte
+{#each conversationSnapshot as exchange (exchange.id)}
+  <Exchange {exchange} />
+{/each}
 ```
 
 #### Incremental Updates
@@ -504,16 +659,60 @@ actor.send({
 - `uninitialized` - Initial state before conversation is created
 - `creating_conversation` - Creating a new conversation
 - `retrieving_history` - Fetching conversation history
+- `retrieve_history_failed` - Error state when history retrieval fails
 - `idle` - Ready to accept new messages
 - `submitting_message` - Sending a user message
-- `streaming` - Receiving agent responses
-- `retrieve_history_failed` - Error state when history retrieval fails
+- `submitting_message_failed` - Error state when message submission fails
+- `streaming` - Receiving agent responses (with substates: `monitoring_replies`, `stopping`)
 
 #### Machine Events
 
-- `SUBMIT_USER_MESSAGE` - Send a new message
+- `SUBMIT_USER_MESSAGE` - Send a new message with a `UserChatMessage`
+- `RETRY_MESSAGE` - Retry sending the last failed message
 - `REFRESH_HISTORY` - Reload conversation history
-- `CANCEL_RUN` - Cancel the current run
+- `STOP_RUN` - Stop the current run
+
+#### Machine Context
+
+The machine maintains the following context:
+
+```typescript
+type ConversationMachineContext = {
+  conversationId: string | null;
+  conversationSnapshot?: ConversationExchange[];
+  currentRunId?: string | null;
+  lastError?: unknown;
+  messageAttempt?: UserChatMessage;
+};
+```
+
+#### Machine Emitted Events
+
+The machine emits the following events that can be subscribed to:
+
+```typescript
+type ConversationMachineEmitted =
+  | { type: "apiError"; error: HttpError }
+  | { type: "chatEventReceived"; chatEvent: ChatEvent }
+  | { type: "conversationCreated"; id: string };
+```
+
+Subscribe to emitted events:
+
+```typescript
+actor.subscribe((snapshot) => {
+  // Access emitted events through snapshot
+  console.log("State:", snapshot.value);
+  console.log("Context:", snapshot.context);
+});
+
+// Or use the system to listen for specific events
+actor.system.subscribe((event) => {
+  if (event.type === "chatEventReceived") {
+    console.log("New chat event:", event.chatEvent);
+  }
+});
+```
 
 ## Catalog
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dremio/js-sdk",
-  "version": "0.45.2",
+  "version": "0.45.4",
   "description": "JavaScript library for the Dremio API",
   "keywords": [
     "dremio",