@octavus/docs 0.0.5 → 0.0.7

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

@@ -10,7 +10,7 @@ The Client SDK provides real-time access to streaming content through the messag
 ## Streaming State
 
 ```tsx
-const { messages, status, error } = useOctavusChat({...});
+const { messages, status, error } = useOctavusChat({ transport });
 
 // status: 'idle' | 'streaming' | 'error'
 // Each message has status: 'streaming' | 'done'
@@ -20,8 +20,24 @@ const { messages, status, error } = useOctavusChat({...});
 ## Building a Streaming UI
 
 ```tsx
-function Chat() {
-  const { messages, status, error, send, stop } = useOctavusChat({...});
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { messages, status, error, send, stop } = useOctavusChat({ transport });
 
   return (
     <div>
@@ -31,14 +47,10 @@ function Chat() {
       ))}
 
       {/* Error state */}
-      {error && (
-        <div className="text-red-500">{error.message}</div>
-      )}
+      {error && <div className="text-red-500">{error.message}</div>}
 
       {/* Stop button during streaming */}
-      {status === 'streaming' && (
-        <button onClick={stop}>Stop</button>
-      )}
+      {status === 'streaming' && <button onClick={stop}>Stop</button>}
     </div>
   );
 }
@@ -49,7 +61,7 @@ function Chat() {
 Parts update in real-time during streaming. Use the part's `status` to show appropriate UI:
 
 ```tsx
-import type { UITextPart, UIReasoningPart } from '@octavus/client-sdk';
+import type { UITextPart, UIReasoningPart } from '@octavus/react';
 
 function TextPart({ part }: { part: UITextPart }) {
   return (
@@ -72,11 +84,9 @@ function ReasoningPart({ part }: { part: UIReasoningPart }) {
         {part.status === 'streaming' ? '💭 Thinking...' : '💭 Thought process'}
         {expanded ? '▼' : '▶'}
       </button>
-      
+
       {expanded && (
-        <pre className="mt-2 text-sm text-gray-600">
-          {part.text}
-        </pre>
+        <pre className="mt-2 text-sm text-gray-600">{part.text}</pre>
       )}
     </div>
   );
@@ -88,26 +98,24 @@ function ReasoningPart({ part }: { part: UIReasoningPart }) {
 Tool calls progress through multiple states:
 
 ```tsx
-import type { UIToolCallPart } from '@octavus/client-sdk';
+import type { UIToolCallPart } from '@octavus/react';
 
 function ToolCallPart({ part }: { part: UIToolCallPart }) {
   return (
     <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>
+        <span className="font-medium">{part.displayName || part.toolName}</span>
         <StatusBadge status={part.status} />
       </div>
-      
+
       {/* 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>
@@ -133,9 +141,7 @@ function StatusBadge({ status }: { status: UIToolCallPart['status'] }) {
 ## Status Indicator
 
 ```tsx
-function StatusIndicator() {
-  const { status } = useOctavusChat({...});
-
+function StatusIndicator({ status }: { status: ChatStatus }) {
   switch (status) {
     case 'idle':
       return null;
@@ -151,7 +157,7 @@ function StatusIndicator() {
 
 ```tsx
 useOctavusChat({
-  onTrigger: ...,
+  transport,
   onFinish: () => {
     console.log('Stream completed');
     // Scroll to bottom, play sound, etc.
@@ -168,7 +174,7 @@ useOctavusChat({
 Stop the current stream and finalize any partial message:
 
 ```tsx
-const { status, stop } = useOctavusChat({...});
+const { status, stop } = useOctavusChat({ transport });
 
 // Stop button
 {status === 'streaming' && (
@@ -188,17 +194,19 @@ When `stop()` is called:
 Content from named threads (like "summary") streams separately and is identified by the `thread` property:
 
 ```tsx
-import { isOtherThread } from '@octavus/client-sdk';
+import { isOtherThread, type UIMessage } from '@octavus/react';
 
 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));
+  const mainParts = message.parts.filter((p) => !isOtherThread(p));
+  const otherParts = message.parts.filter((p) => isOtherThread(p));
 
   return (
     <div>
       {/* Main conversation */}
-      {mainParts.map((part, i) => <PartRenderer key={i} part={part} />)}
+      {mainParts.map((part, i) => (
+        <PartRenderer key={i} part={part} />
+      ))}
 
       {/* Named thread content (e.g., summarization) */}
       {otherParts.length > 0 && (
@@ -206,7 +214,9 @@ function MessageBubble({ message }: { message: UIMessage }) {
           <div className="text-amber-600 font-medium mb-2">
             Background processing
           </div>
-          {otherParts.map((part, i) => <PartRenderer key={i} part={part} />)}
+          {otherParts.map((part, i) => (
+            <PartRenderer key={i} part={part} />
+          ))}
         </div>
       )}
     </div>

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

@@ -25,7 +25,7 @@ interface UIOperationPart {
 Operations are typically shown as compact status indicators:
 
 ```tsx
-import type { UIOperationPart } from '@octavus/client-sdk';
+import type { UIOperationPart } from '@octavus/react';
 
 function OperationCard({ operation }: { operation: UIOperationPart }) {
   return (
@@ -46,7 +46,7 @@ function OperationCard({ operation }: { operation: UIOperationPart }) {
 Operations appear alongside text, reasoning, and tool calls in the message's `parts` array:
 
 ```tsx
-import type { UIMessage, UIMessagePart } from '@octavus/client-sdk';
+import type { UIMessage, UIMessagePart } from '@octavus/react';
 
 function MessageBubble({ message }: { message: UIMessage }) {
   return (

package/content/03-client-sdk/05-socket-transport.md

@@ -0,0 +1,304 @@
+---
+title: Socket Transport
+description: Using WebSocket or SockJS for real-time streaming with Octavus.
+---
+
+# Socket Transport
+
+The socket transport enables real-time bidirectional communication using WebSocket or SockJS. Use this when you need persistent connections, custom server events, or when HTTP/SSE isn't suitable for your infrastructure.
+
+## When to Use Socket Transport
+
+| Use Case | Recommended Transport |
+|----------|----------------------|
+| Standard web apps (Next.js, etc.) | HTTP (`createHttpTransport`) |
+| Real-time apps with custom events | Socket (`createSocketTransport`) |
+| Apps behind proxies that don't support SSE | Socket |
+| Need for typing indicators, presence, etc. | Socket |
+| Meteor, Phoenix, or socket-based frameworks | Socket |
+
+## Basic Setup
+
+### Native WebSocket
+
+```typescript
+import { useMemo } from 'react';
+import { useOctavusChat, createSocketTransport } from '@octavus/react';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const transport = useMemo(
+    () =>
+      createSocketTransport({
+        connect: () =>
+          new Promise((resolve, reject) => {
+            const ws = new WebSocket(
+              `wss://your-server.com/octavus?sessionId=${sessionId}`
+            );
+            ws.onopen = () => resolve(ws);
+            ws.onerror = () => reject(new Error('WebSocket connection failed'));
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { messages, status, send } = useOctavusChat({ transport });
+
+  // ... rest of your component
+}
+```
+
+### SockJS
+
+SockJS provides WebSocket-like functionality with fallbacks for older browsers:
+
+```typescript
+import SockJS from 'sockjs-client';
+import { createSocketTransport } from '@octavus/react';
+
+const transport = createSocketTransport({
+  connect: () =>
+    new Promise((resolve, reject) => {
+      const sock = new SockJS('/octavus-stream');
+      sock.onopen = () => resolve(sock);
+      sock.onerror = () => reject(new Error('SockJS connection failed'));
+    }),
+});
+```
+
+## Custom Events
+
+The socket transport can handle custom events alongside Octavus stream events. Use the `onMessage` callback to process any message your server sends:
+
+```typescript
+const transport = createSocketTransport({
+  connect: () => /* ... */,
+
+  onMessage: (data) => {
+    const msg = data as { type: string; [key: string]: unknown };
+
+    switch (msg.type) {
+      case 'typing-indicator':
+        setAgentTyping(msg.isTyping as boolean);
+        break;
+
+      case 'presence-update':
+        setOnlineUsers(msg.users as string[]);
+        break;
+
+      case 'notification':
+        showToast(msg.message as string);
+        break;
+
+      // Octavus events (text-delta, finish, etc.) are handled automatically
+      // No need to handle them here
+    }
+  },
+});
+```
+
+> **Note**: Octavus stream events (`text-delta`, `finish`, `tool-input-start`, etc.) are automatically processed by the transport. The `onMessage` callback is for your custom events only.
+
+## Connection Management
+
+### Handling Disconnections
+
+Use the `onClose` callback for cleanup or reconnection logic:
+
+```typescript
+const transport = createSocketTransport({
+  connect: () => /* ... */,
+
+  onClose: () => {
+    console.log('Socket disconnected');
+    setConnectionStatus('disconnected');
+
+    // Optional: trigger reconnection
+    // reconnect();
+  },
+});
+```
+
+### Reconnection Pattern
+
+For production apps, implement reconnection with exponential backoff:
+
+```typescript
+import { useRef, useCallback, useMemo } from 'react';
+import { createSocketTransport, type SocketLike } from '@octavus/react';
+
+function useReconnectingTransport(sessionId: string) {
+  const reconnectAttempts = useRef(0);
+  const maxAttempts = 5;
+
+  const connect = useCallback((): Promise<SocketLike> => {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(`wss://your-server.com/octavus?sessionId=${sessionId}`);
+
+      ws.onopen = () => {
+        reconnectAttempts.current = 0; // Reset on success
+        resolve(ws);
+      };
+
+      ws.onerror = () => {
+        if (reconnectAttempts.current < maxAttempts) {
+          reconnectAttempts.current++;
+          const delay = Math.min(1000 * 2 ** reconnectAttempts.current, 30000);
+          console.log(`Reconnecting in ${delay}ms (attempt ${reconnectAttempts.current})`);
+          setTimeout(() => connect().then(resolve).catch(reject), delay);
+        } else {
+          reject(new Error('Max reconnection attempts reached'));
+        }
+      };
+    });
+  }, [sessionId]);
+
+  return useMemo(
+    () =>
+      createSocketTransport({
+        connect,
+        onClose: () => {
+          console.log('Connection closed');
+        },
+      }),
+    [connect],
+  );
+}
+```
+
+## Server-Side Implementation
+
+Your server needs to handle socket connections and forward events from the Octavus platform. Here's a basic pattern:
+
+### Express + ws (WebSocket)
+
+```typescript
+import { WebSocketServer } from 'ws';
+import { OctavusClient } from '@octavus/server-sdk';
+
+const octavus = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+const wss = new WebSocketServer({ server });
+
+wss.on('connection', (ws, req) => {
+  const sessionId = new URL(req.url!, 'http://localhost').searchParams.get('sessionId');
+
+  ws.on('message', async (data) => {
+    const message = JSON.parse(data.toString());
+
+    if (message.type === 'trigger') {
+      const session = octavus.agentSessions.attach(sessionId!, {
+        tools: {
+          // Your tool handlers
+        },
+      });
+
+      const { stream } = session.trigger(message.triggerName, message.input);
+
+      // Forward SSE stream to WebSocket
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const text = decoder.decode(value);
+        // Parse SSE format and send as JSON
+        for (const line of text.split('\n')) {
+          if (line.startsWith('data: ') && line !== 'data: [DONE]') {
+            ws.send(line.slice(6)); // Send JSON directly
+          }
+        }
+      }
+    }
+
+    if (message.type === 'stop') {
+      // Handle stop request
+    }
+  });
+});
+```
+
+### Express + SockJS
+
+```typescript
+import sockjs from 'sockjs';
+import { OctavusClient } from '@octavus/server-sdk';
+
+const octavus = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+const sockServer = sockjs.createServer();
+
+sockServer.on('connection', (conn) => {
+  let sessionId: string | null = null;
+
+  conn.on('data', async (data) => {
+    const message = JSON.parse(data);
+
+    if (message.type === 'init') {
+      sessionId = message.sessionId;
+      return;
+    }
+
+    if (message.type === 'trigger' && sessionId) {
+      const session = octavus.agentSessions.attach(sessionId, {
+        tools: {
+          // Your tool handlers
+        },
+      });
+
+      const { stream } = session.trigger(message.triggerName, message.input);
+
+      // Forward stream events
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const text = decoder.decode(value);
+        for (const line of text.split('\n')) {
+          if (line.startsWith('data: ') && line !== 'data: [DONE]') {
+            conn.write(line.slice(6));
+          }
+        }
+      }
+    }
+  });
+});
+
+sockServer.installHandlers(server, { prefix: '/octavus-stream' });
+```
+
+## Protocol Reference
+
+### Client → Server Messages
+
+```typescript
+// Trigger an action
+{ type: 'trigger', triggerName: string, input?: Record<string, unknown> }
+
+// Stop current stream
+{ type: 'stop' }
+```
+
+### Server → Client Messages
+
+The server sends Octavus `StreamEvent` objects as JSON. See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list.
+
+```typescript
+// Examples
+{ type: 'start', messageId: '...' }
+{ type: 'text-delta', id: '...', delta: 'Hello' }
+{ type: 'tool-input-start', toolCallId: '...', toolName: 'get-user' }
+{ type: 'finish', finishReason: 'stop' }
+```
+
+

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

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

package/content/04-protocol/02-input-resources.md

@@ -65,6 +65,8 @@ In prompts, reference with `{{INPUT_NAME}}`:
 You are a support agent for {{COMPANY_NAME}}.
 ```
 
+> **Note:** Variables must be `UPPER_SNAKE_CASE`. Nested properties (dot notation like `{{VAR.property}}`) are not supported. Objects are serialized as JSON when interpolated.
+
 ## Resources
 
 Resources are persistent state that:

package/content/04-protocol/03-triggers.md

@@ -32,7 +32,7 @@ triggers:
   request-human:
     description: User clicks "Talk to Human" button
     # No input needed - action is implicit
-  
+
   submit-feedback:
     description: User submits feedback form
     input:
@@ -79,26 +79,46 @@ triggers:
 
 ### From Client SDK
 
-```typescript
-const { send } = useOctavusChat({...});
-
-// User message trigger with UI message
-await send('user-message', { USER_MESSAGE: text }, {
-  userMessage: { content: text },
-});
-
-// User action trigger (no input, no UI message)
-await send('request-human');
-
-// Action with input
-await send('submit-feedback', { RATING: 5, COMMENT: 'Great help!' });
+```tsx
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { send } = useOctavusChat({ transport });
+
+  // User message trigger with UI message
+  await send(
+    'user-message',
+    { USER_MESSAGE: text },
+    { userMessage: { content: text } },
+  );
+
+  // User action trigger (no input, no UI message)
+  await send('request-human');
+
+  // Action with input
+  await send('submit-feedback', { RATING: 5, COMMENT: 'Great help!' });
+}
 ```
 
 ### From Server SDK
 
 ```typescript
-const { stream } = session.trigger('user-message', { 
-  USER_MESSAGE: 'Help me with billing' 
+const { stream } = session.trigger('user-message', {
+  USER_MESSAGE: 'Help me with billing',
 });
 
 const { stream } = session.trigger('request-human');
@@ -125,7 +145,7 @@ handlers:
       role: user
       prompt: user-message
       input: [USER_MESSAGE]
-    
+
     Respond:
       type: next-message
 
@@ -191,10 +211,10 @@ Each trigger should do one thing:
 triggers:
   send-message:
     input: { MESSAGE: { type: string } }
-  
+
   upload-file:
     input: { FILE_URL: { type: string } }
-  
+
   request-callback:
     input: { PHONE: { type: string } }
 
@@ -205,4 +225,3 @@ triggers:
       ACTION_TYPE: { type: string }  # "message" | "file" | "callback"
       PAYLOAD: { type: unknown }     # Different structure per type
 ```
-