@dremio/js-sdk 0.45.2 → 0.45.3

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,53 @@ 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 } }>;
 ```
 
 #### Incremental Updates
@@ -504,16 +602,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.3",
   "description": "JavaScript library for the Dremio API",
   "keywords": [
     "dremio",