@octavus/docs 0.0.1

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

@@ -0,0 +1,207 @@
+---
+title: Messages
+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.
+
+## Message Structure
+
+```typescript
+interface Message {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  parts?: MessagePart[];
+  toolCalls?: ToolCallWithDescription[];
+  thinking?: string;
+  visible?: boolean;
+  createdAt: Date;
+}
+```
+
+### Message Parts
+
+For rich content display, use the `parts` array which preserves content ordering:
+
+```typescript
+interface MessagePart {
+  type: 'text' | 'thinking' | 'tool-call';
+  visible: boolean;
+  content?: string;      // For text and thinking
+  toolCall?: ToolCallInfo;  // For tool-call
+  thread?: string;       // For non-main thread content
+}
+```
+
+## Adding User 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 });
+}
+```
+
+**Important**: `addUserMessage` only updates UI state. You must call `triggerAction` to actually send the message to the agent.
+
+## Rendering Messages
+
+### Basic Rendering
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  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>
+      ))}
+    </div>
+  );
+}
+```
+
+### Rich Rendering with Parts
+
+For messages with tool calls and thinking, render parts in order:
+
+```tsx
+function MessageContent({ message }: { message: Message }) {
+  if (!message.parts) {
+    return <p>{message.content}</p>;
+  }
+
+  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 'thinking':
+            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 === 'completed' && ' ✓'}
+              </div>
+            );
+
+          default:
+            return null;
+        }
+      })}
+    </div>
+  );
+}
+```
+
+## Tool Calls in Messages
+
+Tool calls include status, arguments, and results:
+
+```typescript
+interface ToolCallInfo {
+  id: string;
+  name: string;
+  description?: string;
+  arguments: Record<string, unknown>;
+  status: 'pending' | 'in_progress' | 'completed' | 'error';
+  result?: unknown;
+  error?: string;
+}
+```
+
+### Rendering Tool Calls
+
+```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} />
+      </div>
+      
+      {toolCall.status === 'completed' && 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>
+  );
+}
+```
+
+## Session Restore
+
+When restoring a session, pass existing messages:
+
+```tsx
+// 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,
+    thinking: msg.reasoning,
+    createdAt: new Date(msg.createdAt),
+  }));
+
+// Pass to hook
+const { messages } = useOctavusChat({
+  initialMessages,
+  onTrigger: ...
+});
+```
+
+## Message Callbacks
+
+Get notified when messages are added:
+
+```tsx
+useOctavusChat({
+  onTrigger: ...,
+  onMessage: (message) => {
+    console.log('New message:', message.role, message.content);
+    
+    // Analytics, logging, etc.
+    trackMessage(message);
+  },
+});
+```
+

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

@@ -0,0 +1,215 @@
+---
+title: Streaming
+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.
+
+## Streaming State
+
+```tsx
+const {
+  streamingText,     // Current visible text being streamed
+  streamingParts,    // Structured parts being streamed
+  thinkingText,      // Current thinking content
+  status,            // 'idle' | 'loading' | 'streaming' | 'error'
+  isLoading,         // true during loading or streaming
+} = useOctavusChat({...});
+```
+
+## Basic Streaming UI
+
+```tsx
+function Chat() {
+  const { messages, streamingText, isLoading } = useOctavusChat({...});
+
+  return (
+    <div>
+      {/* Completed messages */}
+      {messages.map((msg) => (
+        <div key={msg.id}>{msg.content}</div>
+      ))}
+
+      {/* Currently streaming */}
+      {streamingText && (
+        <div className="animate-pulse">
+          {streamingText}
+          <span className="inline-block w-2 h-4 bg-gray-400 ml-1" />
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Streaming Parts
+
+For rich streaming UIs, use `streamingParts`:
+
+```tsx
+function StreamingContent() {
+  const { streamingParts } = useOctavusChat({...});
+
+  return (
+    <div>
+      {streamingParts.map((part, i) => {
+        switch (part.type) {
+          case 'text':
+            return <span key={i}>{part.content}</span>;
+
+          case 'thinking':
+            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>
+            );
+        }
+      })}
+    </div>
+  );
+}
+```
+
+## Thinking Indicator
+
+Show when the model is "thinking" (extended reasoning):
+
+```tsx
+function ThinkingIndicator() {
+  const { thinkingText, status } = useOctavusChat({...});
+
+  if (!thinkingText || status !== 'streaming') {
+    return null;
+  }
+
+  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>
+      <p className="mt-2 text-sm text-gray-600 line-clamp-3">
+        {thinkingText}
+      </p>
+    </div>
+  );
+}
+```
+
+## Status Indicator
+
+```tsx
+function StatusIndicator() {
+  const { status } = useOctavusChat({...});
+
+  switch (status) {
+    case 'idle':
+      return null;
+    case 'loading':
+      return <div>Starting...</div>;
+    case 'streaming':
+      return <div>Agent is responding...</div>;
+    case 'error':
+      return <div className="text-red-500">Something went wrong</div>;
+  }
+}
+```
+
+## Handling Stream Completion
+
+```tsx
+useOctavusChat({
+  onTrigger: ...,
+  onDone: () => {
+    console.log('Stream completed');
+    // Scroll to bottom, play sound, etc.
+  },
+  onError: (error) => {
+    console.error('Stream error:', error);
+    toast.error('Failed to get response');
+  },
+});
+```
+
+## Streaming with Tool Calls
+
+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
+```
+
+```tsx
+function ChatWithTools() {
+  const { messages, streamingText, streamingParts } = useOctavusChat({...});
+
+  // Find active tool call
+  const activeToolCall = streamingParts.find(
+    p => p.type === 'tool-call' && p.toolCall?.status === 'in_progress'
+  );
+
+  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>
+  );
+}
+```
+
+## Non-Main Thread Content
+
+Named threads (like summarization) stream separately:
+
+```tsx
+function StreamingContent() {
+  const { streamingParts } = useOctavusChat({...});
+
+  // Group by thread
+  const mainParts = streamingParts.filter(p => !p.thread || p.thread === 'main');
+  const otherParts = streamingParts.filter(p => p.thread && p.thread !== 'main');
+
+  return (
+    <div>
+      {/* Main conversation */}
+      <div>{mainParts.map(renderPart)}</div>
+
+      {/* Named thread (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>
+          {otherParts.map(renderPart)}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+

package/content/03-client-sdk/04-execution-blocks.md

@@ -0,0 +1,231 @@
+---
+title: Execution Blocks
+description: Tracking agent execution progress with the Client SDK.
+---
+
+# Execution Blocks
+
+Execution blocks let you show users what the agent is doing. Each block represents a step in the agent's execution flow.
+
+## Block Structure
+
+```typescript
+interface ExecutionBlock {
+  id: string;
+  name: string;           // Human-readable name from protocol
+  type: string;           // Block type (next-message, tool-call, etc.)
+  status: BlockStatus;    // pending | running | completed | error
+  display: DisplayMode;   // hidden | name | description | stream
+  description?: string;
+  outputToChat: boolean;  // Whether output goes to main chat
+  thread?: string;        // For named threads
+  streamingText: string;  // Current streaming content
+  thinking?: string;      // Extended reasoning content
+  toolCalls: ToolCallWithDescription[];
+  startedAt: Date;
+  completedAt?: Date;
+}
+```
+
+## Accessing Blocks
+
+```tsx
+const { executionBlocks, onBlockStart, onBlockEnd } = useOctavusChat({
+  onTrigger: ...,
+  onBlockStart: (block) => {
+    console.log('Block started:', block.name);
+  },
+  onBlockEnd: (block) => {
+    console.log('Block completed:', block.name, block.status);
+  },
+});
+```
+
+## Showing Execution Progress
+
+```tsx
+function ExecutionProgress() {
+  const { executionBlocks, status } = useOctavusChat({...});
+
+  if (status !== 'streaming' || executionBlocks.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="space-y-2">
+      {executionBlocks.map((block) => (
+        <ExecutionBlockCard key={block.id} block={block} />
+      ))}
+    </div>
+  );
+}
+
+function ExecutionBlockCard({ block }: { block: ExecutionBlock }) {
+  return (
+    <div className="border rounded p-3">
+      <div className="flex items-center gap-2">
+        <BlockStatusIcon status={block.status} />
+        <span className="font-medium">{block.name}</span>
+      </div>
+
+      {block.description && (
+        <p className="text-sm text-gray-500 mt-1">{block.description}</p>
+      )}
+
+      {/* Show streaming content for stream display mode */}
+      {block.display === 'stream' && block.streamingText && (
+        <div className="mt-2 text-sm">
+          {block.streamingText}
+        </div>
+      )}
+
+      {/* Show tool calls */}
+      {block.toolCalls.length > 0 && (
+        <div className="mt-2 space-y-1">
+          {block.toolCalls.map((tc) => (
+            <div key={tc.id} className="text-sm flex items-center gap-1">
+              🔧 {tc.description || tc.name}
+              {tc.status === 'completed' && ' ✓'}
+              {tc.status === 'error' && ' ✗'}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Display Modes
+
+Blocks have different display modes that control visibility:
+
+| Mode | Description | UI Recommendation |
+|------|-------------|-------------------|
+| `hidden` | Not shown to user | Don't render |
+| `name` | Shows block name | Show name only |
+| `description` | Shows description | Show name + description |
+| `stream` | Streams content | Show full streaming content |
+
+```tsx
+function ExecutionBlockCard({ block }: { block: ExecutionBlock }) {
+  // Hidden blocks aren't sent to client, but check just in case
+  if (block.display === 'hidden') {
+    return null;
+  }
+
+  return (
+    <div className="border rounded p-3">
+      {/* Always show name */}
+      <div className="font-medium">{block.name}</div>
+
+      {/* Show description if display mode is description or stream */}
+      {(block.display === 'description' || block.display === 'stream') && 
+        block.description && (
+          <p className="text-sm text-gray-500">{block.description}</p>
+        )}
+
+      {/* Show content if display mode is stream */}
+      {block.display === 'stream' && (
+        <div className="mt-2">
+          {block.streamingText}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Named Threads
+
+Blocks can belong to named threads (like "summary"). Use the `thread` property:
+
+```tsx
+function ExecutionProgress() {
+  const { executionBlocks } = useOctavusChat({...});
+
+  // Group by thread
+  const mainBlocks = executionBlocks.filter(b => !b.thread || b.thread === 'main');
+  const namedThreads = new Map<string, ExecutionBlock[]>();
+
+  executionBlocks.forEach(b => {
+    if (b.thread && b.thread !== 'main') {
+      if (!namedThreads.has(b.thread)) {
+        namedThreads.set(b.thread, []);
+      }
+      namedThreads.get(b.thread)!.push(b);
+    }
+  });
+
+  return (
+    <div>
+      {/* Main execution */}
+      <div className="space-y-2">
+        {mainBlocks.map(b => <BlockCard key={b.id} block={b} />)}
+      </div>
+
+      {/* Named threads */}
+      {Array.from(namedThreads.entries()).map(([thread, blocks]) => (
+        <div key={thread} className="mt-4 bg-orange-50 p-3 rounded">
+          <div className="text-orange-600 font-medium mb-2">
+            Thread: {thread}
+          </div>
+          {blocks.map(b => <BlockCard key={b.id} block={b} />)}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Block Status Icons
+
+```tsx
+function BlockStatusIcon({ status }: { status: BlockStatus }) {
+  switch (status) {
+    case 'pending':
+      return <Circle className="w-4 h-4 text-gray-400" />;
+    case 'running':
+      return <Loader className="w-4 h-4 text-blue-500 animate-spin" />;
+    case 'completed':
+      return <CheckCircle className="w-4 h-4 text-green-500" />;
+    case 'error':
+      return <XCircle className="w-4 h-4 text-red-500" />;
+  }
+}
+```
+
+## Example: Support Chat with Escalation
+
+When a user clicks "Talk to Human", the agent runs multiple blocks:
+
+```tsx
+function SupportChatProgress() {
+  const { executionBlocks } = useOctavusChat({...});
+
+  // Show blocks while streaming
+  return (
+    <div className="space-y-2">
+      {executionBlocks.map((block) => (
+        <div key={block.id} className="flex items-center gap-2">
+          <BlockStatusIcon status={block.status} />
+          <span>{getBlockLabel(block)}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function getBlockLabel(block: ExecutionBlock): string {
+  // Use description if available, otherwise name
+  return block.description || block.name;
+}
+
+// Example output during escalation:
+// ✓ Serialize conversation
+// ✓ Start summary thread
+// ● Summarizing your conversation (streaming...)
+// ○ Creating a support ticket
+// ○ Respond with ticket info
+```
+

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

@@ -0,0 +1,4 @@
+---
+title: Client SDK
+description: Frontend integration with @octavus/client-sdk for React applications.
+---