@octavus/docs 0.0.6 → 0.0.8

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

@@ -72,6 +72,7 @@ Create an endpoint that handles triggers and streams responses:
 
 ```typescript
 // app/api/trigger/route.ts
+import { toSSEStream } from '@octavus/server-sdk';
 import { octavus } from '@/lib/octavus';
 
 export async function POST(request: Request) {
@@ -100,11 +101,11 @@ export async function POST(request: Request) {
     },
   });
 
-  // Trigger the action and get the stream
-  const { stream } = session.trigger(triggerName, input);
+  // Trigger the action and convert to SSE stream
+  const events = session.trigger(triggerName, input);
 
   // Return as streaming response
-  return new Response(stream, {
+  return new Response(toSSEStream(events), {
     headers: {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
@@ -118,14 +119,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 +135,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 +161,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 +217,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,12 +63,15 @@ const session = client.agentSessions.attach(sessionId, {
 All responses stream in real-time:
 
 ```typescript
-const { stream } = session.trigger('user-message', { 
-  USER_MESSAGE: 'Hello!' 
+import { toSSEStream } from '@octavus/server-sdk';
+
+// trigger() returns an async generator of events
+const events = session.trigger('user-message', {
+  USER_MESSAGE: 'Hello!',
 });
 
-// Use as a streaming response
-return new Response(stream, {
+// Convert to SSE stream for HTTP responses
+return new Response(toSSEStream(events), {
   headers: { 'Content-Type': 'text/event-stream' },
 });
 ```
@@ -88,7 +91,7 @@ interface OctavusClientConfig {
 class OctavusClient {
   readonly agents: AgentsApi;
   readonly agentSessions: AgentSessionsApi;
-  
+
   constructor(config: OctavusClientConfig);
 }
 ```
@@ -101,24 +104,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
@@ -127,15 +141,18 @@ Handles triggering and streaming for a specific session.
 
 ```typescript
 class AgentSession {
-  // Trigger an action and stream the response
+  // Trigger an action and stream parsed events
   trigger(
     triggerName: string,
     input?: Record<string, unknown>
-  ): { stream: ReadableStream<Uint8Array> };
-  
+  ): AsyncGenerator<StreamEvent>;
+
   // Get the session ID
   getSessionId(): string;
 }
+
+// Helper to convert events to SSE stream
+function toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;
 ```
 
 ## Next Steps

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

@@ -95,12 +95,15 @@ const session = client.agentSessions.attach(sessionId, {
 Once attached, trigger actions on the session:
 
 ```typescript
-const { stream } = session.trigger('user-message', {
+import { toSSEStream } from '@octavus/server-sdk';
+
+// trigger() returns an async generator of events
+const events = session.trigger('user-message', {
   USER_MESSAGE: 'How do I reset my password?',
 });
 
-// Return the stream to your frontend
-return new Response(stream, {
+// Convert to SSE stream for HTTP responses
+return new Response(toSSEStream(events), {
   headers: { 'Content-Type': 'text/event-stream' },
 });
 ```

package/content/02-server-sdk/03-tools.md

@@ -168,6 +168,8 @@ sequenceDiagram
 For request-specific data (auth, headers), create handlers dynamically:
 
 ```typescript
+import { toSSEStream } from '@octavus/server-sdk';
+
 // In your API route
 export async function POST(request: Request) {
   const authToken = request.headers.get('Authorization');
@@ -190,8 +192,8 @@ export async function POST(request: Request) {
     },
   });
   
-  const { stream } = session.trigger(triggerName, input);
-  return new Response(stream);
+  const events = session.trigger(triggerName, input);
+  return new Response(toSSEStream(events));
 }
 ```
 

package/content/02-server-sdk/04-streaming.md

@@ -9,21 +9,29 @@ All Octavus responses stream in real-time using Server-Sent Events (SSE). This e
 
 ## Stream Response
 
-When you trigger an action, you get a readable stream:
+When you trigger an action, you get an async generator of parsed events:
 
 ```typescript
-const { stream } = session.trigger('user-message', { 
+import { toSSEStream } from '@octavus/server-sdk';
+
+// trigger() returns an async generator of StreamEvent
+const events = session.trigger('user-message', { 
   USER_MESSAGE: 'Hello!' 
 });
 
-// Return to frontend as streaming response
-return new Response(stream, {
+// For HTTP endpoints, convert to SSE stream
+return new Response(toSSEStream(events), {
   headers: {
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache',
     'Connection': 'keep-alive',
   },
 });
+
+// For sockets, iterate events directly
+for await (const event of events) {
+  conn.write(JSON.stringify(event));
+}
 ```
 
 ## Event Types

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

@@ -32,27 +32,50 @@ 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 | Docs |
+|-----------|----------|------|
+| `createHttpTransport` | HTTP/SSE (Next.js, Express, etc.) | [HTTP Transport](/docs/client-sdk/http-transport) |
+| `createSocketTransport` | WebSocket, SockJS, or other socket protocols | [Socket Transport](/docs/client-sdk/socket-transport) |
+
+When the transport changes (e.g., when `sessionId` changes), the `useOctavusChat` hook automatically reinitializes with the new transport.
+
+> **Recommendation**: Use HTTP transport unless you specifically need WebSocket features (custom real-time events, Meteor/Phoenix, etc.).
+
 ## 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 +106,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 +127,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 +144,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 +162,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 +178,7 @@ message.parts.map((part) => {
 ### Status Tracking
 
 ```tsx
-const { status } = useOctavusChat({...});
+const { status } = useOctavusChat({ transport });
 
 // status: 'idle' | 'streaming' | 'error'
 ```
@@ -157,7 +186,7 @@ const { status } = useOctavusChat({...});
 ### Stop Streaming
 
 ```tsx
-const { stop } = useOctavusChat({...});
+const { stop } = useOctavusChat({ transport });
 
 // Stop current stream and finalize message
 stop();
@@ -171,12 +200,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 +217,7 @@ interface UseOctavusChatReturn {
   messages: UIMessage[];
   status: ChatStatus;  // 'idle' | 'streaming' | 'error'
   error: Error | null;
-  
+
   // Actions
   send: (
     triggerName: string,
@@ -198,16 +227,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 +277,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 +290,7 @@ class OctavusChat {
     options?: { userMessage?: UserMessageInput }
   ): Promise<void>;
   stop(): void;
-  
+
   // Subscription
   subscribe(callback: () => void): () => void;  // Returns unsubscribe function
 }
@@ -236,6 +298,9 @@ class OctavusChat {
 
 ## Next Steps
 
+- [HTTP Transport](/docs/client-sdk/http-transport) — HTTP/SSE integration (recommended)
+- [Socket Transport](/docs/client-sdk/socket-transport) — WebSocket and SockJS integration
 - [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
+- [Examples](/docs/examples/overview) — Complete working examples

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.