@octavus/docs 0.0.4 → 0.0.6

package/content/01-getting-started/01-introduction.md

@@ -88,6 +88,6 @@ sequenceDiagram
 
 - [Quick Start](/docs/getting-started/quickstart) — Get your first agent running in minutes
 - [Server SDK](/docs/server-sdk/overview) — Learn about backend integration
-- [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React
+- [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React (or other frameworks)
 - [Protocol Reference](/docs/protocol/overview) — Deep dive into agent protocols
 

package/content/01-getting-started/02-quickstart.md

@@ -21,8 +21,8 @@ Install the Octavus SDKs in your project:
 # Server SDK for backend
 npm install @octavus/server-sdk
 
-# Client SDK for frontend (React)
-npm install @octavus/client-sdk
+# React bindings for frontend
+npm install @octavus/react
 ```
 
 ## Backend Setup
@@ -124,7 +124,7 @@ Use the `useOctavusChat` hook to build a chat interface:
 // components/chat.tsx
 'use client';
 
-import { useOctavusChat } from '@octavus/client-sdk';
+import { useOctavusChat, type UIMessage } from '@octavus/react';
 import { useState } from 'react';
 
 interface ChatProps {
@@ -134,14 +134,7 @@ interface ChatProps {
 export function Chat({ sessionId }: ChatProps) {
   const [inputValue, setInputValue] = useState('');
 
-  const {
-    messages,
-    status,
-    isLoading,
-    streamingText,
-    addUserMessage,
-    triggerAction,
-  } = useOctavusChat({
+  const { messages, status, error, send } = useOctavusChat({
     onTrigger: async (triggerName, input) => {
       return fetch('/api/trigger', {
         method: 'POST',
@@ -151,18 +144,19 @@ export function Chat({ sessionId }: ChatProps) {
     },
   });
 
+  const isStreaming = status === 'streaming';
+
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
-    if (!inputValue.trim() || isLoading) return;
+    if (!inputValue.trim() || isStreaming) return;
 
     const message = inputValue.trim();
     setInputValue('');
 
-    // Add user message to UI
-    addUserMessage(message);
-
-    // Trigger the agent
-    await triggerAction('user-message', { USER_MESSAGE: message });
+    // Add user message and trigger in one call
+    await send('user-message', { USER_MESSAGE: message }, {
+      userMessage: { content: message },
+    });
   };
 
   return (
@@ -170,24 +164,8 @@ export function Chat({ sessionId }: ChatProps) {
       {/* Messages */}
       <div className="flex-1 overflow-y-auto p-4 space-y-4">
         {messages.map((msg) => (
-          <div
-            key={msg.id}
-            className={`p-3 rounded-lg ${
-              msg.role === 'user'
-                ? 'bg-blue-500 text-white ml-auto max-w-xs'
-                : 'bg-gray-100 max-w-md'
-            }`}
-          >
-            {msg.content}
-          </div>
+          <MessageBubble key={msg.id} message={msg} />
         ))}
-
-        {/* Streaming text */}
-        {streamingText && (
-          <div className="bg-gray-100 p-3 rounded-lg max-w-md">
-            {streamingText}
-          </div>
-        )}
       </div>
 
       {/* Input */}
@@ -199,11 +177,11 @@ export function Chat({ sessionId }: ChatProps) {
             onChange={(e) => setInputValue(e.target.value)}
             placeholder="Type a message..."
             className="flex-1 px-4 py-2 border rounded-lg"
-            disabled={isLoading}
+            disabled={isStreaming}
           />
           <button
             type="submit"
-            disabled={isLoading}
+            disabled={isStreaming}
             className="px-4 py-2 bg-blue-500 text-white rounded-lg disabled:opacity-50"
           >
             Send
@@ -213,6 +191,32 @@ export function Chat({ sessionId }: ChatProps) {
     </div>
   );
 }
+
+function MessageBubble({ message }: { message: UIMessage }) {
+  const isUser = message.role === 'user';
+
+  return (
+    <div className={`flex ${isUser ? 'justify-end' : 'justify-start'}`}>
+      <div
+        className={`p-3 rounded-lg max-w-md ${
+          isUser ? 'bg-blue-500 text-white' : 'bg-gray-100'
+        }`}
+      >
+        {message.parts.map((part, i) => {
+          if (part.type === 'text') {
+            return <p key={i}>{part.text}</p>;
+          }
+          return null;
+        })}
+        
+        {/* Streaming indicator */}
+        {message.status === 'streaming' && (
+          <span className="inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1" />
+        )}
+      </div>
+    </div>
+  );
+}
 ```
 
 ### 2. Create Session and Render Chat
@@ -271,4 +275,3 @@ Now that you have a basic integration working:
 - [Learn about the protocol](/docs/protocol/overview) to define custom agent behavior
 - [Explore the Server SDK](/docs/server-sdk/overview) for advanced backend features
 - [Build rich UIs](/docs/client-sdk/overview) with the Client SDK
-

package/content/02-server-sdk/01-overview.md

@@ -102,12 +102,23 @@ class AgentSessionsApi {
   // Create a new session
   async create(agentId: string, input?: Record<string, unknown>): Promise<string>;
   
-  // Get session state
-  async get(sessionId: string): Promise<SessionState>;
+  // Get session state (includes UI-ready messages)
+  async get(sessionId: string): Promise<UISessionState>;
   
   // Attach to a session for triggering
   attach(sessionId: string, options?: SessionAttachOptions): AgentSession;
 }
+
+interface UISessionState {
+  id: string;
+  agentId: string;
+  input: Record<string, unknown>;
+  variables: Record<string, unknown>;
+  resources: Record<string, unknown>;
+  messages: UIMessage[];  // UI-ready messages for session restore
+  createdAt: string;
+  updatedAt: string;
+}
 ```
 
 ### AgentSession
@@ -132,4 +143,3 @@ class AgentSession {
 - [Sessions](/docs/server-sdk/sessions) — Deep dive into session management
 - [Tools](/docs/server-sdk/tools) — Implementing tool handlers
 - [Streaming](/docs/server-sdk/streaming) — Understanding stream events
-

package/content/02-server-sdk/02-sessions.md

@@ -29,9 +29,35 @@ const sessionId = await client.agentSessions.create('support-chat', {
 console.log('Session created:', sessionId);
 ```
 
-## Session State
+## Getting Session Messages
 
-Retrieve the current state of a session:
+To restore a conversation on page load, use `getMessages()` to retrieve UI-ready messages:
+
+```typescript
+const session = await client.agentSessions.getMessages(sessionId);
+
+console.log({
+  sessionId: session.sessionId,
+  agentId: session.agentId,
+  messages: session.messages.length,  // UIMessage[] ready for frontend
+});
+```
+
+The returned messages can be passed directly to the client SDK's `initialMessages` option.
+
+### UISessionState Interface
+
+```typescript
+interface UISessionState {
+  sessionId: string;
+  agentId: string;
+  messages: UIMessage[];  // UI-ready conversation history
+}
+```
+
+## Full Session State (Debug)
+
+For debugging or internal use, you can retrieve the complete session state including all variables and internal message format:
 
 ```typescript
 const state = await client.agentSessions.get(sessionId);
@@ -39,7 +65,7 @@ const state = await client.agentSessions.get(sessionId);
 console.log({
   id: state.id,
   agentId: state.agentId,
-  messages: state.messages.length,
+  messages: state.messages.length,  // ChatMessage[] (internal format)
   resources: state.resources,
   variables: state.variables,
   createdAt: state.createdAt,
@@ -47,20 +73,7 @@ console.log({
 });
 ```
 
-### SessionState Interface
-
-```typescript
-interface SessionState {
-  id: string;
-  agentId: string;
-  input: Record<string, unknown>;      // Initial input (immutable)
-  variables: Record<string, unknown>;  // Mutable session variables
-  resources: Record<string, unknown>;  // Resources (synced to consumer)
-  messages: ChatMessage[];             // Conversation history
-  createdAt: string;
-  updatedAt: string;
-}
-```
+> **Note**: Use `getMessages()` for client-facing code. The `get()` method returns internal message format that includes hidden content not intended for end users.
 
 ## Attaching to Sessions
 
@@ -116,8 +129,8 @@ flowchart TD
     Stream events
     Update state`"]
     
-    D -.- D1["`**client.agentSessions.get()**
-    Get current state
+    D -.- D1["`**client.agentSessions.getMessages()**
+    Get UI-ready messages
     Restore conversation`"]
     
     E -.- E1["`Sessions expire after
@@ -130,17 +143,16 @@ When a user returns to your app, restore their session:
 
 ```typescript
 // On page load
-const state = await client.agentSessions.get(sessionId);
+const session = await client.agentSessions.getMessages(sessionId);
 
-// Pass messages to frontend to restore UI
+// Pass messages to frontend - they're already UI-ready
 return {
-  sessionId,
-  messages: state.messages,
-  resources: state.resources,
+  sessionId: session.sessionId,
+  messages: session.messages,  // UIMessage[] with parts
 };
 ```
 
-The `messages` array includes all conversation history with proper content ordering (text, tool calls, thinking blocks), enabling accurate UI restoration.
+The `messages` array contains `UIMessage` objects with properly structured `parts`, enabling direct use with the client SDK's `initialMessages` option.
 
 ## Error Handling
 
@@ -148,7 +160,7 @@ The `messages` array includes all conversation history with proper content order
 import { ApiError } from '@octavus/server-sdk';
 
 try {
-  const state = await client.agentSessions.get(sessionId);
+  const session = await client.agentSessions.getMessages(sessionId);
 } catch (error) {
   if (error instanceof ApiError) {
     if (error.status === 404) {
@@ -161,4 +173,3 @@ try {
   throw error;
 }
 ```
-

package/content/03-client-sdk/01-overview.md

@@ -1,144 +1,236 @@
 ---
 title: Overview
-description: Introduction to the Octavus Client SDK for building chat interfaces.
+description: Introduction to the Octavus Client SDKs for building chat interfaces.
 ---
 
 # Client SDK Overview
 
-The `@octavus/client-sdk` package provides React hooks for building chat interfaces with Octavus agents. It handles streaming, message state, and execution blocks.
+Octavus provides two packages for frontend integration:
 
-**Current version:** `{{VERSION:@octavus/client-sdk}}`
+| Package | Purpose | Use When |
+|---------|---------|----------|
+| `@octavus/react` | React hooks and bindings | Building React applications |
+| `@octavus/client-sdk` | Framework-agnostic core | Using Vue, Svelte, vanilla JS, or custom integrations |
+
+**Most users should install `@octavus/react`** — it includes everything from `@octavus/client-sdk` plus React-specific hooks.
 
 ## Installation
 
+### React Applications
+
+```bash
+npm install @octavus/react
+```
+
+**Current version:** `{{VERSION:@octavus/react}}`
+
+### Other Frameworks
+
 ```bash
 npm install @octavus/client-sdk
 ```
 
-## Basic Usage
+**Current version:** `{{VERSION:@octavus/client-sdk}}`
+
+## React Usage
+
+The `useOctavusChat` hook provides state management and streaming for React applications:
 
 ```tsx
-import { useOctavusChat } from '@octavus/client-sdk';
+import { useOctavusChat, type UIMessage } from '@octavus/react';
 
 function Chat({ sessionId }: { sessionId: string }) {
-  const {
-    messages,
-    status,
-    isLoading,
-    streamingText,
-    addUserMessage,
-    triggerAction,
-  } = useOctavusChat({
+  const { messages, status, send } = useOctavusChat({
     onTrigger: async (triggerName, input) => {
-      return fetch(`/api/chat/${sessionId}/trigger`, {
+      return fetch(`/api/trigger`, {
         method: 'POST',
-        body: JSON.stringify({ triggerName, input }),
+        body: JSON.stringify({ sessionId, triggerName, input }),
       });
     },
   });
 
   const sendMessage = async (text: string) => {
-    addUserMessage(text);
-    await triggerAction('user-message', { USER_MESSAGE: text });
+    await send('user-message', { USER_MESSAGE: text }, {
+      userMessage: { content: text },
+    });
   };
 
   return (
     <div>
       {messages.map((msg) => (
-        <div key={msg.id}>{msg.content}</div>
+        <MessageBubble key={msg.id} message={msg} />
       ))}
-      {streamingText && <div>{streamingText}</div>}
+    </div>
+  );
+}
+
+function MessageBubble({ message }: { message: UIMessage }) {
+  return (
+    <div>
+      {message.parts.map((part, i) => {
+        if (part.type === 'text') {
+          return <p key={i}>{part.text}</p>;
+        }
+        return null;
+      })}
     </div>
   );
 }
 ```
 
+## Framework-Agnostic Usage
+
+The `OctavusChat` class can be used with any framework or vanilla JavaScript:
+
+```typescript
+import { OctavusChat } from '@octavus/client-sdk';
+
+const chat = new OctavusChat({
+  onTrigger: async (triggerName, input) => {
+    return fetch('/api/trigger', {
+      method: 'POST',
+      body: JSON.stringify({ sessionId, triggerName, input }),
+    });
+  },
+});
+
+// Subscribe to state changes
+const unsubscribe = chat.subscribe(() => {
+  console.log('Messages:', chat.messages);
+  console.log('Status:', chat.status);
+  // Update your UI here
+});
+
+// Send a message
+await chat.send('user-message', { USER_MESSAGE: 'Hello' }, {
+  userMessage: { content: 'Hello' },
+});
+
+// Cleanup when done
+unsubscribe();
+```
+
 ## Key Features
 
-### Real-time Streaming
+### Unified Send Function
 
-Text streams incrementally as the LLM generates it:
+The `send` function handles both user message display and agent triggering in one call:
 
 ```tsx
-const { streamingText, streamingParts } = useOctavusChat({...});
+const { send } = useOctavusChat({...});
+
+// Add user message to UI and trigger agent
+await send('user-message', { USER_MESSAGE: text }, {
+  userMessage: { content: text },
+});
 
-// streamingText: Current streaming text
-// streamingParts: Structured parts (text, reasoning, tool calls)
+// Trigger without adding a user message (e.g., button click)
+await send('request-human');
 ```
 
-### Message History
+### Message Parts
 
-Messages are tracked automatically:
+Messages contain ordered `parts` for rich content:
 
 ```tsx
 const { messages } = useOctavusChat({...});
 
-// Each message includes:
-// - id: Unique identifier
-// - role: 'user' | 'assistant'
-// - content: Text content
-// - parts: Ordered content parts
-// - toolCalls: Tool call information
-// - reasoning: Extended reasoning (if enabled)
+// Each message has typed parts
+message.parts.map((part) => {
+  switch (part.type) {
+    case 'text':       // Text content
+    case 'reasoning':  // Extended reasoning/thinking
+    case 'tool-call':  // Tool execution
+    case 'operation':  // Internal operations (set-resource, etc.)
+  }
+});
 ```
 
-### Execution Blocks
-
-Track what the agent is doing:
+### Status Tracking
 
 ```tsx
-const { executionBlocks } = useOctavusChat({...});
+const { status } = useOctavusChat({...});
 
-// Shows active execution steps
-// Useful for progress indicators
+// status: 'idle' | 'streaming' | 'error'
 ```
 
-### Status Tracking
+### Stop Streaming
 
 ```tsx
-const { status, isLoading } = useOctavusChat({...});
+const { stop } = useOctavusChat({...});
 
-// status: 'idle' | 'loading' | 'streaming' | 'error'
-// isLoading: true during loading or streaming
+// Stop current stream and finalize message
+stop();
 ```
 
-## Hook Reference
+## Hook Reference (React)
 
 ### useOctavusChat
 
 ```typescript
-function useOctavusChat(options: UseOctavusChatOptions): UseOctavusChatReturn;
+function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;
 
-interface UseOctavusChatOptions {
+interface OctavusChatOptions {
   // Required: Function that calls your backend trigger endpoint
   onTrigger: TriggerFunction;
   
   // Optional: Pre-populate with existing messages (session restore)
-  initialMessages?: Message[];
+  initialMessages?: UIMessage[];
   
   // Optional: Callbacks
-  onMessage?: (message: Message) => void;
   onError?: (error: Error) => void;
-  onDone?: () => void;
+  onFinish?: () => void;
   onResourceUpdate?: (name: string, value: unknown) => void;
-  onBlockStart?: (block: ExecutionBlock) => void;
-  onBlockEnd?: (block: ExecutionBlock) => void;
 }
 
 interface UseOctavusChatReturn {
   // State
-  messages: Message[];
-  status: ChatStatus;
-  isLoading: boolean;
+  messages: UIMessage[];
+  status: ChatStatus;  // 'idle' | 'streaming' | 'error'
   error: Error | null;
-  streamingText: string;
-  streamingParts: MessagePart[];
-  executionBlocks: ExecutionBlock[];
-  reasoningText: string;
   
   // Actions
-  addUserMessage: (content: string) => void;
-  triggerAction: (triggerName: string, input?: Record<string, unknown>) => Promise<void>;
+  send: (
+    triggerName: string,
+    input?: Record<string, unknown>,
+    options?: { userMessage?: UserMessageInput }
+  ) => Promise<void>;
+  stop: () => void;
+}
+
+type TriggerFunction = (
+  triggerName: string,
+  input?: Record<string, unknown>,
+) => Promise<Response>;
+
+interface UserMessageInput {
+  content: string;
+}
+```
+
+## Class Reference (Framework-Agnostic)
+
+### OctavusChat
+
+```typescript
+class OctavusChat {
+  constructor(options: OctavusChatOptions);
+  
+  // State (read-only)
+  readonly messages: UIMessage[];
+  readonly status: ChatStatus;
+  readonly error: Error | null;
+  
+  // Actions
+  send(
+    triggerName: string,
+    input?: Record<string, unknown>,
+    options?: { userMessage?: UserMessageInput }
+  ): Promise<void>;
+  stop(): void;
+  
+  // Subscription
+  subscribe(callback: () => void): () => void;  // Returns unsubscribe function
 }
 ```