@octavus/docs 2.0.0 → 2.1.0

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

@@ -162,6 +162,35 @@ const events = session.execute(request, {
 
 When the client aborts the request, the signal propagates through to the LLM provider, stopping generation immediately. Any partial content is preserved.
 
+## WebSocket Handling
+
+For WebSocket integrations, use `handleSocketMessage()` which manages abort controller lifecycle internally:
+
+```typescript
+import type { SocketMessage } from '@octavus/server-sdk';
+
+// In your socket handler
+conn.on('data', async (rawData: string) => {
+  const msg = JSON.parse(rawData);
+
+  if (msg.type === 'trigger' || msg.type === 'continue' || msg.type === 'stop') {
+    await session.handleSocketMessage(msg as SocketMessage, {
+      onEvent: (event) => conn.write(JSON.stringify(event)),
+      onFinish: () => sendMessagesUpdate(), // Optional callback after streaming
+    });
+  }
+});
+```
+
+The `handleSocketMessage()` method:
+
+- Handles `trigger`, `continue`, and `stop` messages
+- Automatically aborts previous requests when a new one arrives
+- Streams events via the `onEvent` callback
+- Calls `onFinish` after streaming completes (not called if aborted)
+
+See [Socket Chat Example](/docs/examples/socket-chat) for a complete implementation.
+
 ## Session Lifecycle
 
 ```mermaid

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

@@ -131,7 +131,7 @@ The server creates a session on first trigger message:
 
 ```typescript
 import sockjs from 'sockjs';
-import { OctavusClient, type AgentSession } from '@octavus/server-sdk';
+import { OctavusClient, type AgentSession, type SocketMessage } from '@octavus/server-sdk';
 
 const client = new OctavusClient({
   baseUrl: process.env.OCTAVUS_API_URL!,
@@ -141,7 +141,8 @@ const client = new OctavusClient({
 function createSocketHandler() {
   return (conn: sockjs.Connection) => {
     let session: AgentSession | null = null;
-    let abortController: AbortController | null = null;
+
+    const send = (data: unknown) => conn.write(JSON.stringify(data));
 
     conn.on('data', (rawData: string) => {
       void handleMessage(rawData);
@@ -150,17 +151,10 @@ function createSocketHandler() {
     async function handleMessage(rawData: string) {
       const msg = JSON.parse(rawData);
 
-      if (msg.type === 'stop') {
-        abortController?.abort();
-        return;
-      }
-
-      // Handle both trigger and continue messages
-      if (msg.type === 'trigger' || msg.type === 'continue') {
+      if (msg.type === 'trigger' || msg.type === 'continue' || msg.type === 'stop') {
         // Create session lazily on first trigger
         if (!session && msg.type === 'trigger') {
           const sessionId = await client.agentSessions.create('your-agent-id', {
-            // Initial input variables
             COMPANY_NAME: 'Acme Corp',
           });
           session = client.agentSessions.attach(sessionId, {
@@ -173,24 +167,14 @@ function createSocketHandler() {
 
         if (!session) return;
 
-        abortController = new AbortController();
-
-        // execute() handles both triggers and continuations
-        const events = session.execute(msg, {
-          signal: abortController.signal,
+        // handleSocketMessage manages abort controller internally
+        await session.handleSocketMessage(msg as SocketMessage, {
+          onEvent: send,
         });
-
-        try {
-          for await (const event of events) {
-            conn.write(JSON.stringify(event));
-          }
-        } catch {
-          // Handle errors
-        }
       }
     }
 
-    conn.on('close', () => abortController?.abort());
+    conn.on('close', () => {});
   };
 }
 
@@ -245,9 +229,12 @@ When `sessionId` changes, the hook automatically reinitializes with the new tran
 When using client-provided sessionId, the server must handle an `init` message:
 
 ```typescript
+import type { SocketMessage } from '@octavus/server-sdk';
+
 sockServer.on('connection', (conn) => {
   let session: AgentSession | null = null;
-  let abortController: AbortController | null = null;
+
+  const send = (data: unknown) => conn.write(JSON.stringify(data));
 
   conn.on('data', (rawData: string) => {
     void handleMessage(rawData);
@@ -266,35 +253,23 @@ sockServer.on('connection', (conn) => {
       return;
     }
 
-    if (msg.type === 'stop') {
-      abortController?.abort();
-      return;
-    }
-
     // All other messages require initialized session
     if (!session) {
-      conn.write(
-        JSON.stringify({
-          type: 'error',
-          errorType: 'validation_error',
-          message: 'Session not initialized. Send init message first.',
-          source: 'platform',
-          retryable: false,
-        }),
-      );
+      send({
+        type: 'error',
+        errorType: 'validation_error',
+        message: 'Session not initialized. Send init message first.',
+        source: 'platform',
+        retryable: false,
+      });
       return;
     }
 
-    // Handle both trigger and continue messages
-    if (msg.type === 'trigger' || msg.type === 'continue') {
-      abortController = new AbortController();
-
-      // execute() handles both triggers and continuations
-      const events = session.execute(msg, { signal: abortController.signal });
-
-      for await (const event of events) {
-        conn.write(JSON.stringify(event));
-      }
+    // handleSocketMessage handles trigger, continue, and stop
+    if (msg.type === 'trigger' || msg.type === 'continue' || msg.type === 'stop') {
+      await session.handleSocketMessage(msg as SocketMessage, {
+        onEvent: send,
+      });
     }
   }
 });

package/content/06-examples/03-socket-chat.md

@@ -79,7 +79,7 @@ This is the core of socket integration. Each connection gets its own session:
 ```typescript
 // server/octavus/socket-handler.ts
 import type { Connection } from 'sockjs';
-import { OctavusClient, type AgentSession } from '@octavus/server-sdk';
+import { OctavusClient, type AgentSession, type SocketMessage } from '@octavus/server-sdk';
 
 const octavus = new OctavusClient({
   baseUrl: process.env.OCTAVUS_API_URL!,
@@ -91,7 +91,8 @@ const AGENT_ID = process.env.OCTAVUS_AGENT_ID!;
 export function createSocketHandler() {
   return (conn: Connection) => {
     let session: AgentSession | null = null;
-    let abortController: AbortController | null = null;
+
+    const send = (data: unknown) => conn.write(JSON.stringify(data));
 
     conn.on('data', (rawData: string) => {
       void handleMessage(rawData);
@@ -100,57 +101,36 @@ export function createSocketHandler() {
     async function handleMessage(rawData: string) {
       const msg = JSON.parse(rawData);
 
-      // Handle stop request
-      if (msg.type === 'stop') {
-        abortController?.abort();
-        return;
-      }
-
-      // Handle trigger and continue messages
-      if (msg.type === 'trigger' || msg.type === 'continue') {
+      // Handle trigger, continue, and stop messages
+      if (msg.type === 'trigger' || msg.type === 'continue' || msg.type === 'stop') {
         // Create session lazily on first trigger
         if (!session && msg.type === 'trigger') {
           const sessionId = await octavus.agentSessions.create(AGENT_ID, {
-            // Initial input variables from your protocol
             COMPANY_NAME: 'Acme Corp',
           });
 
           session = octavus.agentSessions.attach(sessionId, {
             tools: {
-              // Server-side tool handlers
               'get-user-account': async () => {
-                // Fetch from your database
                 return { name: 'Demo User', plan: 'pro' };
               },
               'create-support-ticket': async () => {
                 return { ticketId: 'TKT-123', estimatedResponse: '24h' };
               },
-              // Tools without handlers are forwarded to the client
             },
           });
         }
 
         if (!session) return;
 
-        abortController = new AbortController();
-
-        // execute() handles both triggers and continuations
-        const events = session.execute(msg, { signal: abortController.signal });
-
-        try {
-          for await (const event of events) {
-            if (abortController.signal.aborted) break;
-            conn.write(JSON.stringify(event));
-          }
-        } catch {
-          // Handle errors
-        }
+        // handleSocketMessage manages abort controller internally
+        await session.handleSocketMessage(msg as SocketMessage, {
+          onEvent: send,
+        });
       }
     }
 
-    conn.on('close', () => {
-      abortController?.abort();
-    });
+    conn.on('close', () => {});
   };
 }
 ```
@@ -373,13 +353,13 @@ The socket handler receives messages and forwards them to Octavus:
 // Client sends continuation (after client tool handling):
 { type: 'continue', executionId: '...', toolResults: [...] }
 
-// Server handles both:
-if (msg.type === 'trigger' || msg.type === 'continue') {
-  const events = session.execute(msg);
-  for await (const event of events) {
-    conn.write(JSON.stringify(event));
-  }
-}
+// Client sends stop:
+{ type: 'stop' }
+
+// Server handles all three with handleSocketMessage:
+await session.handleSocketMessage(msg, {
+  onEvent: (event) => conn.write(JSON.stringify(event)),
+});
 ```
 
 ### Tools