@octavus/docs 0.0.6 → 0.0.7

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

@@ -118,14 +118,14 @@ export async function POST(request: Request) {
 
 ### 1. Create a Chat Component
 
-Use the `useOctavusChat` hook to build a chat interface:
+Use the `useOctavusChat` hook with the HTTP transport:
 
 ```tsx
 // components/chat.tsx
 'use client';
 
-import { useOctavusChat, type UIMessage } from '@octavus/react';
-import { useState } from 'react';
+import { useState, useMemo } from 'react';
+import { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';
 
 interface ChatProps {
   sessionId: string;
@@ -134,15 +134,21 @@ interface ChatProps {
 export function Chat({ sessionId }: ChatProps) {
   const [inputValue, setInputValue] = useState('');
 
-  const { messages, status, error, send } = useOctavusChat({
-    onTrigger: async (triggerName, input) => {
-      return fetch('/api/trigger', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ sessionId, triggerName, input }),
-      });
-    },
-  });
+  // Create a stable transport instance
+  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 } = useOctavusChat({ transport });
 
   const isStreaming = status === 'streaming';
 
@@ -154,9 +160,11 @@ export function Chat({ sessionId }: ChatProps) {
     setInputValue('');
 
     // Add user message and trigger in one call
-    await send('user-message', { USER_MESSAGE: message }, {
-      userMessage: { content: message },
-    });
+    await send(
+      'user-message',
+      { USER_MESSAGE: message },
+      { userMessage: { content: message } },
+    );
   };
 
   return (
@@ -208,7 +216,7 @@ function MessageBubble({ message }: { message: UIMessage }) {
           }
           return null;
         })}
-        
+
         {/* Streaming indicator */}
         {message.status === 'streaming' && (
           <span className="inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1" />

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

@@ -34,13 +34,13 @@ Create and manage agent sessions:
 
 ```typescript
 // Create a new session
-const sessionId = await client.agentSessions.create('support-chat', {
+const sessionId = await client.agentSessions.create('agent-id', {
   COMPANY_NAME: 'Acme Corp',
   PRODUCT_NAME: 'Widget Pro',
 });
 
-// Get session state
-const state = await client.agentSessions.get(sessionId);
+// Get UI-ready session messages (for session restore)
+const session = await client.agentSessions.getMessages(sessionId);
 ```
 
 ### Tool Handlers
@@ -63,8 +63,8 @@ const session = client.agentSessions.attach(sessionId, {
 All responses stream in real-time:
 
 ```typescript
-const { stream } = session.trigger('user-message', { 
-  USER_MESSAGE: 'Hello!' 
+const { stream } = session.trigger('user-message', {
+  USER_MESSAGE: 'Hello!',
 });
 
 // Use as a streaming response
@@ -88,7 +88,7 @@ interface OctavusClientConfig {
 class OctavusClient {
   readonly agents: AgentsApi;
   readonly agentSessions: AgentSessionsApi;
-  
+
   constructor(config: OctavusClientConfig);
 }
 ```
@@ -101,24 +101,35 @@ Manages agent sessions.
 class AgentSessionsApi {
   // Create a new session
   async create(agentId: string, input?: Record<string, unknown>): Promise<string>;
-  
-  // Get session state (includes UI-ready messages)
-  async get(sessionId: string): Promise<UISessionState>;
-  
+
+  // Get full session state (for debugging/internal use)
+  async get(sessionId: string): Promise<SessionState>;
+
+  // Get UI-ready messages (for client display)
+  async getMessages(sessionId: string): Promise<UISessionState>;
+
   // Attach to a session for triggering
   attach(sessionId: string, options?: SessionAttachOptions): AgentSession;
 }
 
-interface UISessionState {
+// Full session state (internal format)
+interface SessionState {
   id: string;
   agentId: string;
   input: Record<string, unknown>;
   variables: Record<string, unknown>;
   resources: Record<string, unknown>;
-  messages: UIMessage[];  // UI-ready messages for session restore
+  messages: ChatMessage[];  // Internal message format
   createdAt: string;
   updatedAt: string;
 }
+
+// UI-ready session state
+interface UISessionState {
+  sessionId: string;
+  agentId: string;
+  messages: UIMessage[];  // UI-ready messages for frontend
+}
 ```
 
 ### AgentSession
@@ -132,7 +143,7 @@ class AgentSession {
     triggerName: string,
     input?: Record<string, unknown>
   ): { stream: ReadableStream<Uint8Array> };
-  
+
   // Get the session ID
   getSessionId(): string;
 }

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

@@ -32,27 +32,46 @@ npm install @octavus/client-sdk
 
 **Current version:** `{{VERSION:@octavus/client-sdk}}`
 
+## Transport Pattern
+
+The Client SDK uses a **transport abstraction** to handle communication with your backend. This gives you flexibility in how events are delivered:
+
+| Transport | Use Case |
+|-----------|----------|
+| `createHttpTransport` | HTTP/SSE (Next.js, Express, etc.) |
+| `createSocketTransport` | WebSocket, SockJS, or other socket protocols |
+
 ## React Usage
 
 The `useOctavusChat` hook provides state management and streaming for React applications:
 
 ```tsx
-import { useOctavusChat, type UIMessage } from '@octavus/react';
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';
 
 function Chat({ sessionId }: { sessionId: string }) {
-  const { messages, status, send } = useOctavusChat({
-    onTrigger: async (triggerName, input) => {
-      return fetch(`/api/trigger`, {
-        method: 'POST',
-        body: JSON.stringify({ sessionId, triggerName, input }),
-      });
-    },
-  });
+  // Create a stable transport instance (memoized on sessionId)
+  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, send } = useOctavusChat({ transport });
 
   const sendMessage = async (text: string) => {
-    await send('user-message', { USER_MESSAGE: text }, {
-      userMessage: { content: text },
-    });
+    await send(
+      'user-message',
+      { USER_MESSAGE: text },
+      { userMessage: { content: text } },
+    );
   };
 
   return (
@@ -83,17 +102,19 @@ function MessageBubble({ message }: { message: UIMessage }) {
 The `OctavusChat` class can be used with any framework or vanilla JavaScript:
 
 ```typescript
-import { OctavusChat } from '@octavus/client-sdk';
+import { OctavusChat, createHttpTransport } from '@octavus/client-sdk';
 
-const chat = new OctavusChat({
-  onTrigger: async (triggerName, input) => {
-    return fetch('/api/trigger', {
+const transport = createHttpTransport({
+  triggerRequest: (triggerName, input) =>
+    fetch('/api/trigger', {
       method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ sessionId, triggerName, input }),
-    });
-  },
+    }),
 });
 
+const chat = new OctavusChat({ transport });
+
 // Subscribe to state changes
 const unsubscribe = chat.subscribe(() => {
   console.log('Messages:', chat.messages);
@@ -102,9 +123,11 @@ const unsubscribe = chat.subscribe(() => {
 });
 
 // Send a message
-await chat.send('user-message', { USER_MESSAGE: 'Hello' }, {
-  userMessage: { content: 'Hello' },
-});
+await chat.send(
+  'user-message',
+  { USER_MESSAGE: 'Hello' },
+  { userMessage: { content: 'Hello' } },
+);
 
 // Cleanup when done
 unsubscribe();
@@ -117,12 +140,14 @@ unsubscribe();
 The `send` function handles both user message display and agent triggering in one call:
 
 ```tsx
-const { send } = useOctavusChat({...});
+const { send } = useOctavusChat({ transport });
 
 // Add user message to UI and trigger agent
-await send('user-message', { USER_MESSAGE: text }, {
-  userMessage: { content: text },
-});
+await send(
+  'user-message',
+  { USER_MESSAGE: text },
+  { userMessage: { content: text } },
+);
 
 // Trigger without adding a user message (e.g., button click)
 await send('request-human');
@@ -133,7 +158,7 @@ await send('request-human');
 Messages contain ordered `parts` for rich content:
 
 ```tsx
-const { messages } = useOctavusChat({...});
+const { messages } = useOctavusChat({ transport });
 
 // Each message has typed parts
 message.parts.map((part) => {
@@ -149,7 +174,7 @@ message.parts.map((part) => {
 ### Status Tracking
 
 ```tsx
-const { status } = useOctavusChat({...});
+const { status } = useOctavusChat({ transport });
 
 // status: 'idle' | 'streaming' | 'error'
 ```
@@ -157,7 +182,7 @@ const { status } = useOctavusChat({...});
 ### Stop Streaming
 
 ```tsx
-const { stop } = useOctavusChat({...});
+const { stop } = useOctavusChat({ transport });
 
 // Stop current stream and finalize message
 stop();
@@ -171,12 +196,12 @@ stop();
 function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;
 
 interface OctavusChatOptions {
-  // Required: Function that calls your backend trigger endpoint
-  onTrigger: TriggerFunction;
-  
+  // Required: Transport for streaming events
+  transport: Transport;
+
   // Optional: Pre-populate with existing messages (session restore)
   initialMessages?: UIMessage[];
-  
+
   // Optional: Callbacks
   onError?: (error: Error) => void;
   onFinish?: () => void;
@@ -188,7 +213,7 @@ interface UseOctavusChatReturn {
   messages: UIMessage[];
   status: ChatStatus;  // 'idle' | 'streaming' | 'error'
   error: Error | null;
-  
+
   // Actions
   send: (
     triggerName: string,
@@ -198,16 +223,49 @@ interface UseOctavusChatReturn {
   stop: () => void;
 }
 
-type TriggerFunction = (
-  triggerName: string,
-  input?: Record<string, unknown>,
-) => Promise<Response>;
-
 interface UserMessageInput {
   content: string;
 }
 ```
 
+## Transport Reference
+
+### createHttpTransport
+
+Creates an HTTP/SSE transport using native `fetch()`:
+
+```typescript
+import { createHttpTransport } from '@octavus/react';
+
+const transport = createHttpTransport({
+  triggerRequest: (triggerName, input) =>
+    fetch('/api/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, triggerName, input }),
+    }),
+});
+```
+
+### createSocketTransport
+
+Creates a WebSocket/SockJS transport for real-time connections:
+
+```typescript
+import { createSocketTransport } from '@octavus/react';
+
+const transport = createSocketTransport({
+  connect: () =>
+    new Promise((resolve, reject) => {
+      const ws = new WebSocket(`wss://api.example.com/stream?sessionId=${sessionId}`);
+      ws.onopen = () => resolve(ws);
+      ws.onerror = () => reject(new Error('Connection failed'));
+    }),
+});
+```
+
+For detailed WebSocket/SockJS usage including custom events, reconnection patterns, and server-side implementation, see [Socket Transport](/docs/client-sdk/socket-transport).
+
 ## Class Reference (Framework-Agnostic)
 
 ### OctavusChat
@@ -215,12 +273,12 @@ interface UserMessageInput {
 ```typescript
 class OctavusChat {
   constructor(options: OctavusChatOptions);
-  
+
   // State (read-only)
   readonly messages: UIMessage[];
   readonly status: ChatStatus;
   readonly error: Error | null;
-  
+
   // Actions
   send(
     triggerName: string,
@@ -228,7 +286,7 @@ class OctavusChat {
     options?: { userMessage?: UserMessageInput }
   ): Promise<void>;
   stop(): void;
-  
+
   // Subscription
   subscribe(callback: () => void): () => void;  // Returns unsubscribe function
 }
@@ -238,4 +296,5 @@ class OctavusChat {
 
 - [Messages](/docs/client-sdk/messages) — Working with message state
 - [Streaming](/docs/client-sdk/streaming) — Building streaming UIs
-- [Execution Blocks](/docs/client-sdk/execution-blocks) — Showing agent progress
+- [Operations](/docs/client-sdk/execution-blocks) — Showing agent progress
+- [Socket Transport](/docs/client-sdk/socket-transport) — WebSocket and SockJS integration

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

@@ -24,10 +24,10 @@ interface UIMessage {
 Messages contain ordered `parts` that preserve content ordering:
 
 ```typescript
-type UIMessagePart = 
-  | UITextPart 
-  | UIReasoningPart 
-  | UIToolCallPart 
+type UIMessagePart =
+  | UITextPart
+  | UIReasoningPart
+  | UIToolCallPart
   | UIOperationPart;
 
 // Text content
@@ -73,13 +73,35 @@ interface UIOperationPart {
 ## Sending Messages
 
 ```tsx
-const { send } = 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],
+  );
 
-async function handleSend(text: string) {
-  // Add user message to UI and trigger agent
-  await send('user-message', { USER_MESSAGE: text }, {
-    userMessage: { content: text },
-  });
+  const { send } = useOctavusChat({ transport });
+
+  async function handleSend(text: string) {
+    // Add user message to UI and trigger agent
+    await send(
+      'user-message',
+      { USER_MESSAGE: text },
+      { userMessage: { content: text } },
+    );
+  }
+
+  // ...
 }
 ```
 
@@ -201,24 +223,54 @@ function PartRenderer({ part }: { part: UIMessagePart }) {
 
 ## Session Restore
 
-When restoring a session, pass existing messages:
+When restoring a session, fetch messages from your backend and pass them to the hook:
 
 ```tsx
-// Fetch session state from your backend
-const sessionState = await fetchSession(sessionId);
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';
 
-// Pass to hook
-const { messages } = useOctavusChat({
-  initialMessages: sessionState.messages,
-  onTrigger: ...
-});
+interface ChatProps {
+  sessionId: string;
+  initialMessages: UIMessage[];
+}
+
+function Chat({ sessionId, initialMessages }: ChatProps) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  // Pass existing messages to restore the conversation
+  const { messages } = useOctavusChat({
+    transport,
+    initialMessages,
+  });
+
+  // ...
+}
+```
+
+On your backend, use `agentSessions.getMessages()` to fetch UI-ready messages:
+
+```typescript
+// Server-side
+const session = await client.agentSessions.getMessages(sessionId);
+// session.messages is UIMessage[] ready for the client
 ```
 
 ## Callbacks
 
 ```tsx
 useOctavusChat({
-  onTrigger: ...,
+  transport,
   onFinish: () => {
     console.log('Stream completed');
     // Scroll to bottom, play sound, etc.

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>
   );
 }
@@ -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>
   );
@@ -95,19 +105,17 @@ function ToolCallPart({ part }: { part: UIToolCallPart }) {
     <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/react';
+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>