@octavus/docs 0.0.6 → 0.0.7

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/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
 ```
-

package/content/04-protocol/04-tools.md

@@ -59,17 +59,17 @@ tools:
       query:
         type: string
         description: Search query
-      
+
       category:
         type: string
         description: Filter by category
         optional: true
-      
+
       maxPrice:
         type: number
         description: Maximum price filter
         optional: true
-      
+
       inStock:
         type: boolean
         description: Only show in-stock items
@@ -86,7 +86,7 @@ tools:
     description: Look up user account
     parameters:
       userId: { type: string }
-  
+
   create-support-ticket:
     description: Create a support ticket
     parameters:
@@ -136,17 +136,30 @@ handlers:
 
 ### In Prompts
 
-Reference tool results in prompts:
+Tool results are stored in variables. Reference the variable in prompts:
 
 ```markdown
 <!-- prompts/ticket-directive.md -->
 A support ticket has been created:
-- Ticket ID: {{TICKET.ticketId}}
-- Estimated Response: {{TICKET.estimatedResponse}}
+{{TICKET}}
+
+Let the user know their ticket has been created.
+```
+
+When the `TICKET` variable contains an object, it's automatically serialized as JSON in the prompt:
+
+```
+A support ticket has been created:
+{
+  "ticketId": "TKT-123ABC",
+  "estimatedResponse": "24 hours"
+}
 
 Let the user know their ticket has been created.
 ```
 
+> **Note**: Variables use `{{VARIABLE_NAME}}` syntax with `UPPERCASE_SNAKE_CASE`. Dot notation (like `{{TICKET.ticketId}}`) is not supported. Objects are automatically JSON-serialized.
+
 ### In Variables
 
 Store tool results for later use:
@@ -160,15 +173,13 @@ handlers:
       input:
         userId: USER_ID
       output: ACCOUNT  # Result stored here
-    
+
     Create ticket:
       type: tool-call
       tool: create-support-ticket
       input:
         summary: SUMMARY
         priority: medium
-        # Can reference ACCOUNT here
-        email: ACCOUNT.email
       output: TICKET
 ```
 
@@ -182,7 +193,7 @@ const session = client.agentSessions.attach(sessionId, {
     'get-user-account': async (args) => {
       const userId = args.userId as string;
       const user = await db.users.findById(userId);
-      
+
       return {
         name: user.name,
         email: user.email,
@@ -190,13 +201,13 @@ const session = client.agentSessions.attach(sessionId, {
         createdAt: user.createdAt.toISOString(),
       };
     },
-    
+
     'create-support-ticket': async (args) => {
       const ticket = await ticketService.create({
         summary: args.summary as string,
         priority: args.priority as string,
       });
-      
+
       return {
         ticketId: ticket.id,
         estimatedResponse: getEstimatedTime(args.priority),
@@ -218,7 +229,7 @@ tools:
       Retrieves the user's account information including name, email,
       subscription plan, and account creation date. Use this when the
       user asks about their account or you need to verify their identity.
-  
+
   # Avoid - vague
   get-data:
     description: Gets some data
@@ -234,4 +245,3 @@ tools:
         type: string
         description: Ticket priority level (low, medium, high, urgent)
 ```
-