@octavus/docs 0.0.3 → 0.0.5

package/content/03-client-sdk/02-messages.md

@@ -5,159 +5,197 @@ description: Working with message state in the Client SDK.
 
 # Messages
 
-Messages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content.
+Messages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content through typed parts.
 
 ## Message Structure
 
 ```typescript
-interface Message {
+interface UIMessage {
   id: string;
-  role: 'user' | 'assistant' | 'system';
-  content: string;
-  parts?: MessagePart[];
-  toolCalls?: ToolCallWithDescription[];
-  reasoning?: string;
-  visible?: boolean;
+  role: 'user' | 'assistant';
+  parts: UIMessagePart[];
+  status: 'streaming' | 'done';
   createdAt: Date;
 }
 ```
 
 ### Message Parts
 
-For rich content display, use the `parts` array which preserves content ordering:
+Messages contain ordered `parts` that preserve content ordering:
 
 ```typescript
-interface MessagePart {
-  type: 'text' | 'reasoning' | 'tool-call';
-  visible: boolean;
-  content?: string;      // For text and reasoning
-  toolCall?: ToolCallInfo;  // For tool-call
-  thread?: string;       // For non-main thread content
+type UIMessagePart = 
+  | UITextPart 
+  | UIReasoningPart 
+  | UIToolCallPart 
+  | UIOperationPart;
+
+// Text content
+interface UITextPart {
+  type: 'text';
+  text: string;
+  status: 'streaming' | 'done';
+  thread?: string;  // For named threads (e.g., "summary")
+}
+
+// Extended reasoning/thinking
+interface UIReasoningPart {
+  type: 'reasoning';
+  text: string;
+  status: 'streaming' | 'done';
+  thread?: string;
+}
+
+// Tool execution
+interface UIToolCallPart {
+  type: 'tool-call';
+  toolCallId: string;
+  toolName: string;
+  displayName?: string;  // Human-readable name
+  args: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+  status: 'pending' | 'running' | 'done' | 'error';
+  thread?: string;
+}
+
+// Internal operations (set-resource, serialize-thread)
+interface UIOperationPart {
+  type: 'operation';
+  operationId: string;
+  name: string;
+  operationType: string;
+  status: 'running' | 'done';
+  thread?: string;
 }
 ```
 
-## Adding User Messages
+## Sending Messages
 
 ```tsx
-const { addUserMessage, triggerAction } = useOctavusChat({...});
-
-async function sendMessage(text: string) {
-  // 1. Add message to UI immediately
-  addUserMessage(text);
-  
-  // 2. Trigger the agent
-  await triggerAction('user-message', { USER_MESSAGE: text });
+const { send } = useOctavusChat({...});
+
+async function handleSend(text: string) {
+  // Add user message to UI and trigger agent
+  await send('user-message', { USER_MESSAGE: text }, {
+    userMessage: { content: text },
+  });
 }
 ```
 
-**Important**: `addUserMessage` only updates UI state. You must call `triggerAction` to actually send the message to the agent.
+The `send` function:
+1. Adds the user message to the UI immediately (if `userMessage` is provided)
+2. Triggers the agent with the specified trigger name and input
+3. Streams the assistant's response back
 
 ## Rendering Messages
 
 ### Basic Rendering
 
 ```tsx
-function MessageList({ messages }: { messages: Message[] }) {
+function MessageList({ messages }: { messages: UIMessage[] }) {
   return (
     <div className="space-y-4">
       {messages.map((msg) => (
-        <div
-          key={msg.id}
-          className={msg.role === 'user' ? 'text-right' : 'text-left'}
-        >
-          <div className="inline-block p-3 rounded-lg">
-            {msg.content}
-          </div>
-        </div>
+        <MessageBubble key={msg.id} message={msg} />
       ))}
     </div>
   );
 }
-```
 
-### Rich Rendering with Parts
-
-For messages with tool calls and reasoning, render parts in order:
-
-```tsx
-function MessageContent({ message }: { message: Message }) {
-  if (!message.parts) {
-    return <p>{message.content}</p>;
-  }
+function MessageBubble({ message }: { message: UIMessage }) {
+  const isUser = message.role === 'user';
 
   return (
-    <div className="space-y-2">
-      {message.parts.map((part, i) => {
-        if (!part.visible) return null;
-
-        switch (part.type) {
-          case 'text':
-            return <p key={i}>{part.content}</p>;
-
-          case 'reasoning':
-            return (
-              <details key={i} className="text-gray-500">
-                <summary>Thinking...</summary>
-                <pre className="text-sm">{part.content}</pre>
-              </details>
-            );
-
-          case 'tool-call':
-            return (
-              <div key={i} className="bg-gray-100 p-2 rounded text-sm">
-                🔧 {part.toolCall?.name}
-                {part.toolCall?.status === 'available' && ' ✓'}
-              </div>
-            );
-
-          default:
-            return null;
-        }
-      })}
+    <div className={isUser ? 'text-right' : 'text-left'}>
+      <div className="inline-block p-3 rounded-lg">
+        {message.parts.map((part, i) => (
+          <PartRenderer key={i} part={part} />
+        ))}
+      </div>
     </div>
   );
 }
 ```
 
-## Tool Calls in Messages
+### Rendering Parts
 
-Tool calls include status, arguments, and results:
+```tsx
+import { isOtherThread, type UIMessagePart } from '@octavus/client-sdk';
 
-```typescript
-interface ToolCallInfo {
-  id: string;
-  name: string;
-  description?: string;
-  arguments: Record<string, unknown>;
-  status: 'pending' | 'streaming' | 'available' | 'error';
-  result?: unknown;
-  error?: string;
+function PartRenderer({ part }: { part: UIMessagePart }) {
+  // Check if part belongs to a named thread (e.g., "summary")
+  if (isOtherThread(part)) {
+    return <OtherThreadPart part={part} />;
+  }
+
+  switch (part.type) {
+    case 'text':
+      return <TextPart part={part} />;
+
+    case 'reasoning':
+      return (
+        <details className="text-gray-500">
+          <summary>Thinking...</summary>
+          <pre className="text-sm">{part.text}</pre>
+        </details>
+      );
+
+    case 'tool-call':
+      return (
+        <div className="bg-gray-100 p-2 rounded text-sm">
+          🔧 {part.displayName || part.toolName}
+          {part.status === 'done' && ' ✓'}
+          {part.status === 'error' && ` ✗ ${part.error}`}
+        </div>
+      );
+
+    case 'operation':
+      return (
+        <div className="text-gray-500 text-sm">
+          {part.name}
+          {part.status === 'done' && ' ✓'}
+        </div>
+      );
+
+    default:
+      return null;
+  }
+}
+
+function TextPart({ part }: { part: UITextPart }) {
+  return (
+    <p>
+      {part.text}
+      {part.status === 'streaming' && (
+        <span className="inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1" />
+      )}
+    </p>
+  );
 }
 ```
 
-### Rendering Tool Calls
+## Named Threads
+
+Content from named threads (like "summary") is identified by the `thread` property. Use the `isOtherThread` helper:
 
 ```tsx
-function ToolCallCard({ toolCall }: { toolCall: ToolCallInfo }) {
-  return (
-    <div className="border rounded p-3">
-      <div className="flex items-center gap-2">
-        <span className="text-lg">🔧</span>
-        <span className="font-medium">{toolCall.description || toolCall.name}</span>
-        <StatusBadge status={toolCall.status} />
+import { isOtherThread } from '@octavus/client-sdk';
+
+function PartRenderer({ part }: { part: UIMessagePart }) {
+  if (isOtherThread(part)) {
+    // Render differently for named threads
+    return (
+      <div className="bg-amber-50 p-2 rounded border border-amber-200">
+        <span className="text-amber-600 text-sm">
+          {part.thread}: {part.type === 'text' && part.text}
+        </span>
       </div>
-      
-      {toolCall.status === 'available' && toolCall.result && (
-        <pre className="mt-2 text-xs bg-gray-50 p-2 rounded">
-          {JSON.stringify(toolCall.result, null, 2)}
-        </pre>
-      )}
-      
-      {toolCall.status === 'error' && (
-        <p className="mt-2 text-red-500 text-sm">{toolCall.error}</p>
-      )}
-    </div>
-  );
+    );
+  }
+
+  // Regular rendering for main thread
+  // ...
 }
 ```
 
@@ -169,38 +207,28 @@ When restoring a session, pass existing messages:
 // Fetch session state from your backend
 const sessionState = await fetchSession(sessionId);
 
-// Convert ChatMessage[] to Message[]
-const initialMessages = sessionState.messages
-  .filter(msg => msg.visible !== false)
-  .map(msg => ({
-    id: msg.id,
-    role: msg.role,
-    content: msg.content,
-    parts: msg.parts,
-    toolCalls: msg.toolCalls,
-    reasoning: msg.reasoning,
-    createdAt: new Date(msg.createdAt),
-  }));
-
 // Pass to hook
 const { messages } = useOctavusChat({
-  initialMessages,
+  initialMessages: sessionState.messages,
   onTrigger: ...
 });
 ```
 
-## Message Callbacks
-
-Get notified when messages are added:
+## Callbacks
 
 ```tsx
 useOctavusChat({
   onTrigger: ...,
-  onMessage: (message) => {
-    console.log('New message:', message.role, message.content);
-    
-    // Analytics, logging, etc.
-    trackMessage(message);
+  onFinish: () => {
+    console.log('Stream completed');
+    // Scroll to bottom, play sound, etc.
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+    toast.error('Failed to get response');
+  },
+  onResourceUpdate: (name, value) => {
+    console.log('Resource updated:', name, value);
   },
 });
 ```

package/content/03-client-sdk/03-streaming.md

@@ -5,105 +5,129 @@ description: Building streaming UIs with the Client SDK.
 
 # Streaming
 
-The Client SDK provides real-time access to streaming content, enabling responsive UIs that update as the agent generates responses.
+The Client SDK provides real-time access to streaming content through the message `parts` array. Each part has its own status, enabling responsive UIs that update as the agent generates responses.
 
 ## Streaming State
 
 ```tsx
-const {
-  streamingText,     // Current visible text being streamed
-  streamingParts,    // Structured parts being streamed
-  reasoningText,     // Current reasoning content
-  status,            // 'idle' | 'loading' | 'streaming' | 'error'
-  isLoading,         // true during loading or streaming
-} = useOctavusChat({...});
+const { messages, status, error } = useOctavusChat({...});
+
+// status: 'idle' | 'streaming' | 'error'
+// Each message has status: 'streaming' | 'done'
+// Each part has its own status too
 ```
 
-## Basic Streaming UI
+## Building a Streaming UI
 
 ```tsx
 function Chat() {
-  const { messages, streamingText, isLoading } = useOctavusChat({...});
+  const { messages, status, error, send, stop } = useOctavusChat({...});
 
   return (
     <div>
-      {/* Completed messages */}
+      {/* Messages with streaming parts */}
       {messages.map((msg) => (
-        <div key={msg.id}>{msg.content}</div>
+        <MessageBubble key={msg.id} message={msg} />
       ))}
 
-      {/* Currently streaming */}
-      {streamingText && (
-        <div className="animate-pulse">
-          {streamingText}
-          <span className="inline-block w-2 h-4 bg-gray-400 ml-1" />
-        </div>
+      {/* Error state */}
+      {error && (
+        <div className="text-red-500">{error.message}</div>
+      )}
+
+      {/* Stop button during streaming */}
+      {status === 'streaming' && (
+        <button onClick={stop}>Stop</button>
       )}
     </div>
   );
 }
 ```
 
-## Streaming Parts
+## Rendering Streaming Parts
 
-For rich streaming UIs, use `streamingParts`:
+Parts update in real-time during streaming. Use the part's `status` to show appropriate UI:
 
 ```tsx
-function StreamingContent() {
-  const { streamingParts } = useOctavusChat({...});
+import type { UITextPart, UIReasoningPart } from '@octavus/client-sdk';
 
+function TextPart({ part }: { part: UITextPart }) {
   return (
     <div>
-      {streamingParts.map((part, i) => {
-        switch (part.type) {
-          case 'text':
-            return <span key={i}>{part.content}</span>;
-
-          case 'reasoning':
-            return (
-              <div key={i} className="text-gray-500 italic">
-                💭 {part.content}
-              </div>
-            );
-
-          case 'tool-call':
-            return (
-              <div key={i} className="flex items-center gap-2">
-                <Spinner />
-                <span>{part.toolCall?.description}</span>
-              </div>
-            );
-        }
-      })}
+      {part.text}
+      {part.status === 'streaming' && (
+        <span className="inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1" />
+      )}
+    </div>
+  );
+}
+
+function ReasoningPart({ part }: { part: UIReasoningPart }) {
+  // Expand while streaming, collapse when done
+  const [expanded, setExpanded] = useState(part.status === 'streaming');
+
+  return (
+    <div className="bg-purple-50 p-3 rounded-lg">
+      <button onClick={() => setExpanded(!expanded)}>
+        {part.status === 'streaming' ? '💭 Thinking...' : '💭 Thought process'}
+        {expanded ? '▼' : '▶'}
+      </button>
+      
+      {expanded && (
+        <pre className="mt-2 text-sm text-gray-600">
+          {part.text}
+        </pre>
+      )}
     </div>
   );
 }
 ```
 
-## Reasoning Indicator
+## Tool Call States
 
-Show when the model is using extended reasoning:
+Tool calls progress through multiple states:
 
 ```tsx
-function ReasoningIndicator() {
-  const { reasoningText, status } = useOctavusChat({...});
-
-  if (!reasoningText || status !== 'streaming') {
-    return null;
-  }
+import type { UIToolCallPart } from '@octavus/client-sdk';
 
+function ToolCallPart({ part }: { part: UIToolCallPart }) {
   return (
-    <div className="bg-purple-50 p-3 rounded-lg">
-      <div className="flex items-center gap-2 text-purple-600">
-        <Brain className="w-4 h-4 animate-pulse" />
-        <span className="font-medium">Thinking...</span>
+    <div className="border rounded p-3">
+      <div className="flex items-center gap-2">
+        <span className="text-lg">🔧</span>
+        <span className="font-medium">
+          {part.displayName || part.toolName}
+        </span>
+        <StatusBadge status={part.status} />
       </div>
-      <p className="mt-2 text-sm text-gray-600 line-clamp-3">
-        {reasoningText}
-      </p>
+      
+      {/* Show result when done */}
+      {part.status === 'done' && part.result && (
+        <pre className="mt-2 text-xs bg-gray-50 p-2 rounded">
+          {JSON.stringify(part.result, null, 2)}
+        </pre>
+      )}
+      
+      {/* Show error if failed */}
+      {part.status === 'error' && (
+        <p className="mt-2 text-red-500 text-sm">{part.error}</p>
+      )}
     </div>
   );
 }
+
+function StatusBadge({ status }: { status: UIToolCallPart['status'] }) {
+  switch (status) {
+    case 'pending':
+      return <span className="text-gray-400">○</span>;
+    case 'running':
+      return <span className="text-blue-500 animate-spin">◐</span>;
+    case 'done':
+      return <span className="text-green-500">✓</span>;
+    case 'error':
+      return <span className="text-red-500">✗</span>;
+  }
+}
 ```
 
 ## Status Indicator
@@ -115,8 +139,6 @@ function StatusIndicator() {
   switch (status) {
     case 'idle':
       return null;
-    case 'loading':
-      return <div>Starting...</div>;
     case 'streaming':
       return <div>Agent is responding...</div>;
     case 'error':
@@ -125,12 +147,12 @@ function StatusIndicator() {
 }
 ```
 
-## Handling Stream Completion
+## Handling Completion
 
 ```tsx
 useOctavusChat({
   onTrigger: ...,
-  onDone: () => {
+  onFinish: () => {
     console.log('Stream completed');
     // Scroll to bottom, play sound, etc.
   },
@@ -141,71 +163,50 @@ useOctavusChat({
 });
 ```
 
-## Streaming with Tool Calls
+## Stop Function
 
-When tools are called, streaming continues after tool execution:
-
-```
-1. User sends message
-2. streamingText starts filling: "Let me look that up..."
-3. Tool call starts (visible in streamingParts)
-4. Tool executes (handled by server-sdk)
-5. streamingText continues: "I found your account..."
-6. Stream completes, message finalized
-```
+Stop the current stream and finalize any partial message:
 
 ```tsx
-function ChatWithTools() {
-  const { messages, streamingText, streamingParts } = useOctavusChat({...});
-
-  // Find active tool call
-  const activeToolCall = streamingParts.find(
-    p => p.type === 'tool-call' && p.toolCall?.status === 'streaming'
-  );
-
-  return (
-    <div>
-      {messages.map(msg => <Message key={msg.id} message={msg} />)}
-
-      {/* Show streaming text */}
-      {streamingText && <p>{streamingText}</p>}
-
-      {/* Show active tool */}
-      {activeToolCall && (
-        <div className="flex items-center gap-2 text-blue-600">
-          <Spinner />
-          {activeToolCall.toolCall?.description}
-        </div>
-      )}
-    </div>
-  );
-}
+const { status, stop } = useOctavusChat({...});
+
+// Stop button
+{status === 'streaming' && (
+  <button onClick={stop} className="text-gray-500">
+    Stop generating
+  </button>
+)}
 ```
 
-## Non-Main Thread Content
+When `stop()` is called:
+1. The current request is aborted
+2. Any partial message is finalized with current content
+3. Status changes to `'idle'`
+
+## Named Thread Content
 
-Named threads (like summarization) stream separately:
+Content from named threads (like "summary") streams separately and is identified by the `thread` property:
 
 ```tsx
-function StreamingContent() {
-  const { streamingParts } = useOctavusChat({...});
+import { isOtherThread } from '@octavus/client-sdk';
 
-  // Group by thread
-  const mainParts = streamingParts.filter(p => !p.thread || p.thread === 'main');
-  const otherParts = streamingParts.filter(p => p.thread && p.thread !== 'main');
+function MessageBubble({ message }: { message: UIMessage }) {
+  // Separate main thread from named threads
+  const mainParts = message.parts.filter(p => !isOtherThread(p));
+  const otherParts = message.parts.filter(p => isOtherThread(p));
 
   return (
     <div>
       {/* Main conversation */}
-      <div>{mainParts.map(renderPart)}</div>
+      {mainParts.map((part, i) => <PartRenderer key={i} part={part} />)}
 
-      {/* Named thread (e.g., summarization) */}
+      {/* Named thread content (e.g., summarization) */}
       {otherParts.length > 0 && (
-        <div className="bg-orange-50 p-3 rounded mt-4">
-          <div className="text-orange-600 font-medium">
-            Processing in background...
+        <div className="bg-amber-50 p-3 rounded mt-4 border border-amber-200">
+          <div className="text-amber-600 font-medium mb-2">
+            Background processing
           </div>
-          {otherParts.map(renderPart)}
+          {otherParts.map((part, i) => <PartRenderer key={i} part={part} />)}
         </div>
       )}
     </div>