@octavus/docs 1.0.0 → 2.1.0

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,43 +151,30 @@ function createSocketHandler() {
     async function handleMessage(rawData: string) {
       const msg = JSON.parse(rawData);
 
-      if (msg.type === 'stop') {
-        abortController?.abort();
-        return;
-      }
-
-      if (msg.type === 'trigger') {
+      if (msg.type === 'trigger' || msg.type === 'continue' || msg.type === 'stop') {
         // Create session lazily on first trigger
-        if (!session) {
+        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, {
             tools: {
-              // Your tool handlers
+              // Server-side tool handlers only
+              // Tools without handlers are forwarded to the client
             },
           });
         }
 
-        abortController = new AbortController();
+        if (!session) return;
 
-        // Iterate events directly — no SSE parsing needed
-        const events = session.trigger(msg.triggerName, msg.input, {
-          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', () => {});
   };
 }
 
@@ -241,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);
@@ -256,33 +247,29 @@ sockServer.on('connection', (conn) => {
     if (msg.type === 'init') {
       session = client.agentSessions.attach(msg.sessionId, {
         tools: {
-          /* ... */
+          // Server-side tool handlers
         },
       });
       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;
     }
 
-    if (msg.type === 'trigger') {
-      // ... handle trigger (same as server-managed pattern)
+    // handleSocketMessage handles trigger, continue, and stop
+    if (msg.type === 'trigger' || msg.type === 'continue' || msg.type === 'stop') {
+      await session.handleSocketMessage(msg as SocketMessage, {
+        onEvent: send,
+      });
     }
   }
 });
@@ -505,9 +492,12 @@ const SockJS: typeof import('sockjs-client') = require('sockjs-client');
 // Initialize session (only for client-provided sessionId pattern)
 { type: 'init', sessionId: string }
 
-// Trigger an action
+// Trigger an action (start a new conversation turn)
 { type: 'trigger', triggerName: string, input?: Record<string, unknown> }
 
+// Continue execution (after client-side tool handling)
+{ type: 'continue', executionId: string, toolResults: ToolResult[] }
+
 // Stop current stream
 { type: 'stop' }
 ```
@@ -518,13 +508,19 @@ The server sends Octavus `StreamEvent` objects as JSON. See [Streaming Events](/
 
 ```typescript
 // Examples
-{ type: 'start', messageId: '...' }
+{ type: 'start', messageId: '...', executionId: '...' }
 { type: 'text-delta', id: '...', delta: 'Hello' }
 { type: 'tool-input-start', toolCallId: '...', toolName: 'get-user' }
 { type: 'finish', finishReason: 'stop' }
 { type: 'error', errorType: 'internal_error', message: 'Something went wrong', source: 'platform', retryable: false }
+
+// Client tool request (tools without server handlers)
+{ type: 'client-tool-request', executionId: '...', toolCalls: [...], serverToolResults: [...] }
+{ type: 'finish', finishReason: 'client-tool-calls', executionId: '...' }
 ```
 
+When a `client-tool-request` event is received, the client handles the tools and sends a `continue` message to resume.
+
 ## Full Example
 
 For a complete walkthrough of building a chat interface with SockJS, see the [Socket Chat Example](/docs/examples/socket-chat).

package/content/03-client-sdk/06-http-transport.md

@@ -28,11 +28,11 @@ function Chat({ sessionId }: { sessionId: string }) {
   const transport = useMemo(
     () =>
       createHttpTransport({
-        triggerRequest: (triggerName, input, options) =>
+        request: (payload, options) =>
           fetch('/api/trigger', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId, triggerName, input }),
+            body: JSON.stringify({ sessionId, ...payload }),
             signal: options?.signal,
           }),
       }),
@@ -61,7 +61,8 @@ const client = new OctavusClient({
 });
 
 export async function POST(request: Request) {
-  const { sessionId, triggerName, input } = await request.json();
+  const body = await request.json();
+  const { sessionId, ...payload } = body;
 
   const session = client.agentSessions.attach(sessionId, {
     tools: {
@@ -71,8 +72,8 @@ export async function POST(request: Request) {
     },
   });
 
-  // trigger() returns an async generator, toSSEStream() converts to SSE format
-  const events = session.trigger(triggerName, input, { signal: request.signal });
+  // execute() handles both triggers and client tool continuations
+  const events = session.execute(payload, { signal: request.signal });
 
   return new Response(toSSEStream(events), {
     headers: {
@@ -197,7 +198,7 @@ return (
 );
 ```
 
-> **Important**: For stop to work end-to-end, pass the `options.signal` to your `fetch()` call and forward `request.signal` to `session.trigger()` on the server.
+> **Important**: For stop to work end-to-end, pass the `options.signal` to your `fetch()` call and forward `request.signal` to `session.execute()` on the server.
 
 ## Express Server
 
@@ -208,21 +209,25 @@ import express from 'express';
 import { OctavusClient, toSSEStream } from '@octavus/server-sdk';
 
 const app = express();
+app.use(express.json());
+
 const client = new OctavusClient({
   baseUrl: process.env.OCTAVUS_API_URL!,
   apiKey: process.env.OCTAVUS_API_KEY!,
 });
 
 app.post('/api/trigger', async (req, res) => {
-  const { sessionId, triggerName, input } = req.body;
+  const { sessionId, ...payload } = req.body;
 
   const session = client.agentSessions.attach(sessionId, {
     tools: {
-      // Your tool handlers
+      // Server-side tool handlers only
+      // Tools without handlers are forwarded to the client
     },
   });
 
-  const events = session.trigger(triggerName, input);
+  // execute() handles both triggers and continuations
+  const events = session.execute(payload);
   const stream = toSSEStream(events);
 
   // Set SSE headers
@@ -250,27 +255,56 @@ app.post('/api/trigger', async (req, res) => {
 
 ```typescript
 interface HttpTransportOptions {
-  triggerRequest: (
-    triggerName: string,
-    input?: Record<string, unknown>,
-    options?: TriggerRequestOptions,
-  ) => Promise<Response>;
+  // Single request handler for both triggers and continuations
+  request: (request: HttpRequest, options?: HttpRequestOptions) => Promise<Response>;
 }
 
-interface TriggerRequestOptions {
+interface HttpRequestOptions {
   signal?: AbortSignal;
 }
+
+// Discriminated union for request types
+type HttpRequest = TriggerRequest | ContinueRequest;
+
+// Start a new conversation turn
+interface TriggerRequest {
+  type: 'trigger';
+  triggerName: string;
+  input?: Record<string, unknown>;
+}
+
+// Continue after client-side tool handling
+interface ContinueRequest {
+  type: 'continue';
+  executionId: string;
+  toolResults: ToolResult[];
+}
+```
+
+The `request` function receives a discriminated union. Spread the request onto your payload:
+
+```typescript
+request: (payload, options) =>
+  fetch('/api/trigger', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sessionId, ...payload }),
+    signal: options?.signal,
+  });
 ```
 
 ## Protocol
 
 ### Request Format
 
-The `triggerRequest` function should send a POST request with:
+The `request` function receives a discriminated union with `type` to identify the request kind:
+
+**Trigger Request** (start a new turn):
 
 ```json
 {
   "sessionId": "sess_abc123",
+  "type": "trigger",
   "triggerName": "user-message",
   "input": {
     "USER_MESSAGE": "Hello"
@@ -278,12 +312,29 @@ The `triggerRequest` function should send a POST request with:
 }
 ```
 
+**Continue Request** (after client tool handling):
+
+```json
+{
+  "sessionId": "sess_abc123",
+  "type": "continue",
+  "executionId": "exec_xyz789",
+  "toolResults": [
+    {
+      "toolCallId": "call_abc",
+      "toolName": "get-browser-location",
+      "result": { "lat": 40.7128, "lng": -74.006 }
+    }
+  ]
+}
+```
+
 ### Response Format
 
 The server responds with an SSE stream:
 
 ```
-data: {"type":"start","messageId":"msg_xyz"}
+data: {"type":"start","messageId":"msg_xyz","executionId":"exec_xyz789"}
 
 data: {"type":"text-delta","id":"msg_xyz","delta":"Hello"}
 
@@ -294,11 +345,24 @@ data: {"type":"finish","finishReason":"stop"}
 data: [DONE]
 ```
 
+If client tools are needed, the stream pauses with a `client-tool-request` event:
+
+```
+data: {"type":"client-tool-request","executionId":"exec_xyz789","toolCalls":[...]}
+
+data: {"type":"finish","finishReason":"client-tool-calls","executionId":"exec_xyz789"}
+
+data: [DONE]
+```
+
+The client handles the tools and sends a `continue` request to resume.
+
 See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list of event types.
 
 ## Next Steps
 
 - [Quick Start](/docs/getting-started/quickstart) — Complete Next.js integration guide
+- [Client Tools](/docs/client-sdk/client-tools) — Handling tools on the client side
 - [Messages](/docs/client-sdk/messages) — Working with message state
 - [Streaming](/docs/client-sdk/streaming) — Building streaming UIs
 - [Error Handling](/docs/client-sdk/error-handling) — Handling errors with type guards

package/content/03-client-sdk/07-structured-output.md

@@ -288,11 +288,12 @@ function Chat({ sessionId }: { sessionId: string }) {
   const transport = useMemo(
     () =>
       createHttpTransport({
-        triggerRequest: (triggerName, input) =>
+        request: (payload, options) =>
           fetch('/api/trigger', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId, triggerName, input }),
+            body: JSON.stringify({ sessionId, ...payload }),
+            signal: options?.signal,
           }),
       }),
     [sessionId],

package/content/03-client-sdk/08-file-uploads.md

@@ -50,11 +50,12 @@ function Chat({ sessionId }: { sessionId: string }) {
   const transport = useMemo(
     () =>
       createHttpTransport({
-        triggerRequest: (triggerName, input) =>
+        request: (payload, options) =>
           fetch('/api/trigger', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId, triggerName, input }),
+            body: JSON.stringify({ sessionId, ...payload }),
+            signal: options?.signal,
           }),
       }),
     [sessionId],
@@ -332,11 +333,12 @@ export function Chat({ sessionId }: { sessionId: string }) {
   const transport = useMemo(
     () =>
       createHttpTransport({
-        triggerRequest: (triggerName, input) =>
+        request: (payload, options) =>
           fetch('/api/trigger', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId, triggerName, input }),
+            body: JSON.stringify({ sessionId, ...payload }),
+            signal: options?.signal,
           }),
       }),
     [sessionId],