@octavus/docs 0.0.7 → 0.0.8

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

@@ -17,13 +17,138 @@ The socket transport enables real-time bidirectional communication using WebSock
 | Need for typing indicators, presence, etc. | Socket |
 | Meteor, Phoenix, or socket-based frameworks | Socket |
 
-## Basic Setup
+## Patterns Overview
 
-### Native WebSocket
+There are two main patterns for socket-based integrations:
+
+| Pattern | When to Use |
+|---------|-------------|
+| [Server-Managed Sessions](#server-managed-sessions-recommended) | **Recommended.** Server creates sessions lazily. Client doesn't need sessionId. |
+| [Client-Provided Session ID](#client-provided-session-id) | When client must control session creation or pass sessionId from URL. |
+
+## Server-Managed Sessions (Recommended)
+
+The cleanest pattern is to have the server manage session lifecycle. The client never needs to know about `sessionId` — the server creates it lazily on first message.
+
+### Client Setup
+
+```typescript
+import { useMemo } from 'react';
+import SockJS from 'sockjs-client';
+import { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';
+
+function connectSocket(): Promise<SocketLike> {
+  return new Promise((resolve, reject) => {
+    const sock = new SockJS('/octavus');
+    sock.onopen = () => resolve(sock);
+    sock.onerror = () => reject(new Error('Connection failed'));
+  });
+}
+
+function Chat() {
+  // Transport is stable — no dependencies on sessionId
+  const transport = useMemo(
+    () => createSocketTransport({ connect: connectSocket }),
+    [],
+  );
+
+  const { messages, status, send } = useOctavusChat({ transport });
+
+  const sendMessage = async (text: string) => {
+    await send(
+      'user-message',
+      { USER_MESSAGE: text },
+      { userMessage: { content: text } },
+    );
+  };
+
+  // ... render messages
+}
+```
+
+### Server Setup (Express + SockJS)
+
+The server creates a session on first trigger message:
+
+```typescript
+import sockjs from 'sockjs';
+import { OctavusClient, type AgentSession } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+function createSocketHandler() {
+  return (conn: sockjs.Connection) => {
+    let session: AgentSession | null = null;
+    let abortController: AbortController | null = null;
+
+    conn.on('data', (rawData: string) => {
+      void handleMessage(rawData);
+    });
+
+    async function handleMessage(rawData: string) {
+      const msg = JSON.parse(rawData);
+
+      if (msg.type === 'stop') {
+        abortController?.abort();
+        return;
+      }
+
+      if (msg.type === 'trigger') {
+        // Create session lazily on first trigger
+        if (!session) {
+          const sessionId = await client.agentSessions.create('your-agent-id', {
+            // Initial input variables
+            COMPANY_NAME: 'Acme Corp',
+          });
+          session = client.agentSessions.attach(sessionId, {
+            tools: {
+              // Your tool handlers
+            },
+          });
+        }
+
+        abortController = new AbortController();
+
+        // Iterate events directly — no SSE parsing needed
+        const events = session.trigger(msg.triggerName, msg.input);
+
+        try {
+          for await (const event of events) {
+            if (abortController.signal.aborted) break;
+            conn.write(JSON.stringify(event));
+          }
+        } catch {
+          // Handle errors
+        }
+      }
+    }
+
+    conn.on('close', () => abortController?.abort());
+  };
+}
+
+const sockServer = sockjs.createServer({ prefix: '/octavus' });
+sockServer.on('connection', createSocketHandler());
+sockServer.installHandlers(httpServer);
+```
+
+**Benefits of this pattern:**
+- Client code is simple — no sessionId management
+- No transport caching issues
+- Session is created only when needed
+- Server controls session configuration
+
+## Client-Provided Session ID
+
+If you need the client to control the session (e.g., resuming a specific session from URL), pass the sessionId in an init message after connecting:
 
 ```typescript
 import { useMemo } from 'react';
-import { useOctavusChat, createSocketTransport } from '@octavus/react';
+import SockJS from 'sockjs-client';
+import { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';
 
 function Chat({ sessionId }: { sessionId: string }) {
   const transport = useMemo(
@@ -31,47 +156,131 @@ function Chat({ sessionId }: { sessionId: string }) {
       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'));
+            const sock = new SockJS('/octavus');
+            sock.onopen = () => {
+              // Send init message with sessionId
+              sock.send(JSON.stringify({ type: 'init', sessionId }));
+              resolve(sock);
+            };
+            sock.onerror = () => reject(new Error('Connection failed'));
           }),
       }),
     [sessionId],
   );
 
   const { messages, status, send } = useOctavusChat({ transport });
-
-  // ... rest of your component
+  // ... render chat
 }
 ```
 
-### SockJS
+When `sessionId` changes, the hook automatically reinitializes with the new transport.
+
+### Server Handler with Init Message
 
-SockJS provides WebSocket-like functionality with fallbacks for older browsers:
+When using client-provided sessionId, the server must handle an `init` message:
 
 ```typescript
-import SockJS from 'sockjs-client';
-import { createSocketTransport } from '@octavus/react';
+sockServer.on('connection', (conn) => {
+  let session: AgentSession | null = null;
+  let abortController: AbortController | null = null;
 
-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'));
-    }),
+  conn.on('data', (rawData: string) => {
+    void handleMessage(rawData);
+  });
+
+  async function handleMessage(rawData: string) {
+    const msg = JSON.parse(rawData);
+
+    // Handle session initialization
+    if (msg.type === 'init') {
+      session = client.agentSessions.attach(msg.sessionId, {
+        tools: { /* ... */ },
+      });
+      return;
+    }
+
+    if (msg.type === 'stop') {
+      abortController?.abort();
+      return;
+    }
+
+    // All other messages require initialized session
+    if (!session) {
+      conn.write(JSON.stringify({
+        type: 'error',
+        errorText: 'Session not initialized. Send init message first.',
+      }));
+      return;
+    }
+
+    if (msg.type === 'trigger') {
+      // ... handle trigger (same as server-managed pattern)
+    }
+  }
 });
 ```
 
+## Async Session ID
+
+When the session ID is fetched asynchronously (e.g., from an API), you have two options:
+
+### Option 1: Conditionally Render (Recommended)
+
+Don't render the chat component until `sessionId` is available:
+
+```tsx
+function ChatPage() {
+  const [sessionId, setSessionId] = useState<string | null>(null);
+
+  useEffect(() => {
+    api.createSession().then(res => setSessionId(res.sessionId));
+  }, []);
+
+  // Don't render until sessionId is ready
+  if (!sessionId) {
+    return <LoadingSpinner />;
+  }
+
+  return <Chat sessionId={sessionId} />;
+}
+```
+
+This is the cleanest approach — the `Chat` component always receives a valid `sessionId`.
+
+### Option 2: Server-Managed Sessions
+
+Use the [server-managed sessions pattern](#server-managed-sessions-recommended) where the server creates the session lazily. The client never needs to know about `sessionId`.
+
+## Native WebSocket
+
+If you're using native WebSocket instead of SockJS, you can pass sessionId via URL:
+
+```typescript
+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],
+);
+```
+
+When `sessionId` changes, the hook automatically reinitializes with the new transport.
+
 ## Custom Events
 
-The socket transport can handle custom events alongside Octavus stream events. Use the `onMessage` callback to process any message your server sends:
+Handle custom events alongside Octavus stream events:
 
 ```typescript
 const transport = createSocketTransport({
-  connect: () => /* ... */,
+  connect: connectSocket,
 
   onMessage: (data) => {
     const msg = data as { type: string; [key: string]: unknown };
@@ -90,198 +299,96 @@ const transport = createSocketTransport({
         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: () => /* ... */,
+  connect: connectSocket,
 
   onClose: () => {
     console.log('Socket disconnected');
     setConnectionStatus('disconnected');
-
-    // Optional: trigger reconnection
-    // reconnect();
   },
 });
 ```
 
-### Reconnection Pattern
-
-For production apps, implement reconnection with exponential backoff:
+### Reconnection with Exponential Backoff
 
 ```typescript
 import { useRef, useCallback, useMemo } from 'react';
 import { createSocketTransport, type SocketLike } from '@octavus/react';
 
-function useReconnectingTransport(sessionId: string) {
+function useReconnectingTransport() {
   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}`);
+      const sock = new SockJS('/octavus');
 
-      ws.onopen = () => {
-        reconnectAttempts.current = 0; // Reset on success
-        resolve(ws);
+      sock.onopen = () => {
+        reconnectAttempts.current = 0;
+        resolve(sock);
       };
 
-      ws.onerror = () => {
+      sock.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})`);
+          console.log(`Reconnecting in ${delay}ms...`);
           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');
-        },
-      }),
+    () => createSocketTransport({ connect }),
     [connect],
   );
 }
 ```
 
-## Server-Side Implementation
+## Framework Notes
 
-Your server needs to handle socket connections and forward events from the Octavus platform. Here's a basic pattern:
+### Meteor
 
-### Express + ws (WebSocket)
+Meteor's bundler may have issues with ES6 imports of `sockjs-client`. Use `require()` instead:
 
 ```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
-          }
-        }
-      }
-    }
+// ❌ May fail in Meteor
+import SockJS from 'sockjs-client';
 
-    if (message.type === 'stop') {
-      // Handle stop request
-    }
-  });
-});
+// ✅ Works in Meteor
+const SockJS: typeof import('sockjs-client') = require('sockjs-client');
 ```
 
-### 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;
+### SockJS vs WebSocket
 
-  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' });
-```
+| Feature | WebSocket | SockJS |
+|---------|-----------|--------|
+| Browser support | Modern browsers | All browsers (with fallbacks) |
+| Session ID | Via URL query params | Via init message |
+| Proxy compatibility | Varies | Excellent (polling fallback) |
+| Setup complexity | Lower | Higher (requires server library) |
 
 ## Protocol Reference
 
 ### Client → Server Messages
 
 ```typescript
+// Initialize session (only for client-provided sessionId pattern)
+{ type: 'init', sessionId: string }
+
 // Trigger an action
 { type: 'trigger', triggerName: string, input?: Record<string, unknown> }
 
@@ -299,6 +406,9 @@ The server sends Octavus `StreamEvent` objects as JSON. See [Streaming Events](/
 { type: 'text-delta', id: '...', delta: 'Hello' }
 { type: 'tool-input-start', toolCallId: '...', toolName: 'get-user' }
 { type: 'finish', finishReason: 'stop' }
+{ type: 'error', errorText: 'Something went wrong' }
 ```
 
+## Full Example
 
+For a complete walkthrough of building a chat interface with SockJS, see the [Socket Chat Example](/docs/examples/socket-chat).