@octavus/docs 1.0.0 → 2.0.0

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

@@ -106,7 +106,8 @@ import { toSSEStream } from '@octavus/server-sdk';
 import { octavus } from '@/lib/octavus';
 
 export async function POST(request: Request) {
-  const { sessionId, triggerName, input } = await request.json();
+  const body = await request.json();
+  const { sessionId, ...payload } = body;
 
   // Attach to session with tool handlers
   const session = octavus.agentSessions.attach(sessionId, {
@@ -131,8 +132,8 @@ export async function POST(request: Request) {
     },
   });
 
-  // Trigger the action and convert to SSE stream
-  const events = session.trigger(triggerName, input);
+  // Execute the request and convert to SSE stream
+  const events = session.execute(payload, { signal: request.signal });
 
   // Return as streaming response
   return new Response(toSSEStream(events), {
@@ -169,11 +170,12 @@ export function Chat({ sessionId }: ChatProps) {
   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],
@@ -307,3 +309,4 @@ Now that you have a basic integration working:
 - [Learn about the protocol](/docs/protocol/overview) to define custom agent behavior
 - [Explore the Server SDK](/docs/server-sdk/overview) for advanced backend features
 - [Build rich UIs](/docs/client-sdk/overview) with the Client SDK
+- [Handle tools on the client](/docs/client-sdk/client-tools) for interactive UIs and browser APIs

package/content/02-server-sdk/01-overview.md

@@ -83,9 +83,11 @@ All responses stream in real-time:
 ```typescript
 import { toSSEStream } from '@octavus/server-sdk';
 
-// trigger() returns an async generator of events
-const events = session.trigger('user-message', {
-  USER_MESSAGE: 'Hello!',
+// execute() returns an async generator of events
+const events = session.execute({
+  type: 'trigger',
+  triggerName: 'user-message',
+  input: { USER_MESSAGE: 'Hello!' },
 });
 
 // Convert to SSE stream for HTTP responses
@@ -156,17 +158,31 @@ interface UISessionState {
 
 ### AgentSession
 
-Handles triggering and streaming for a specific session.
+Handles request execution and streaming for a specific session.
 
 ```typescript
 class AgentSession {
-  // Trigger an action and stream parsed events
-  trigger(triggerName: string, input?: Record<string, unknown>): AsyncGenerator<StreamEvent>;
+  // Execute a request and stream parsed events
+  execute(request: SessionRequest, options?: TriggerOptions): AsyncGenerator<StreamEvent>;
 
   // Get the session ID
   getSessionId(): string;
 }
 
+type SessionRequest = TriggerRequest | ContinueRequest;
+
+interface TriggerRequest {
+  type: 'trigger';
+  triggerName: string;
+  input?: Record<string, unknown>;
+}
+
+interface ContinueRequest {
+  type: 'continue';
+  executionId: string;
+  toolResults: ToolResult[];
+}
+
 // Helper to convert events to SSE stream
 function toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;
 ```

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

@@ -90,17 +90,18 @@ const session = client.agentSessions.attach(sessionId, {
 });
 ```
 
-## Triggering Actions
+## Executing Requests
 
-Once attached, trigger actions on the session:
+Once attached, execute requests on the session using `execute()`:
 
 ```typescript
 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?',
-});
+// execute() handles both triggers and client tool continuations
+const events = session.execute(
+  { type: 'trigger', triggerName: 'user-message', input: { USER_MESSAGE: 'Hello!' } },
+  { signal: request.signal },
+);
 
 // Convert to SSE stream for HTTP responses
 return new Response(toSSEStream(events), {
@@ -108,13 +109,53 @@ return new Response(toSSEStream(events), {
 });
 ```
 
+### Request Types
+
+The `execute()` method accepts a discriminated union:
+
+```typescript
+type SessionRequest = 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[];
+}
+```
+
+This makes it easy to pass requests through from the client:
+
+```typescript
+// Simple passthrough from HTTP request body
+export async function POST(request: Request) {
+  const body = await request.json();
+  const { sessionId, ...payload } = body;
+
+  const session = client.agentSessions.attach(sessionId, {
+    tools: {
+      /* ... */
+    },
+  });
+  const events = session.execute(payload, { signal: request.signal });
+
+  return new Response(toSSEStream(events));
+}
+```
+
 ### Stop Support
 
 Pass an abort signal to allow clients to stop generation:
 
 ```typescript
-// In your API route handler
-const events = session.trigger(triggerName, input, {
+const events = session.execute(request, {
   signal: request.signal, // Forward the client's abort signal
 });
 ```
@@ -143,8 +184,8 @@ flowchart TD
     Configure tool handlers
     Configure resource watchers`"]
 
-    C -.- C1["`**session.trigger()**
-    Execute handler
+    C -.- C1["`**session.execute()**
+    Execute request
     Stream events
     Update state`"]
 

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

@@ -5,11 +5,25 @@ description: Implementing tool handlers with the Server SDK.
 
 # Tools
 
-Tools extend what agents can do. In Octavus, tools execute on your server, giving you full control over data access and authentication.
+Tools extend what agents can do. In Octavus, tools can execute either on your server or on the client side.
 
-## Why Tools Run on Your Server
+## Server Tools vs Client Tools
 
-Unlike traditional AI platforms where tools run in a sandbox, Octavus tools execute in your backend:
+| Location   | Use Case                                          | Registration                            |
+| ---------- | ------------------------------------------------- | --------------------------------------- |
+| **Server** | Database queries, API calls, sensitive operations | Register handler in `attach()`          |
+| **Client** | Browser APIs, interactive UIs, confirmations      | No server handler (forwarded to client) |
+
+When the Server SDK encounters a tool call:
+
+1. **Handler exists** → Execute on server, continue automatically
+2. **No handler** → Forward to client via `client-tool-request` event
+
+For client-side tool handling, see [Client Tools](/docs/client-sdk/client-tools).
+
+## Why Server Tools
+
+Server-side tools give you full control:
 
 - ✅ **Full data access** — Query your database directly
 - ✅ **Your authentication** — Use your existing auth context
@@ -146,22 +160,29 @@ sequenceDiagram
     participant LLM
     participant Platform as Octavus Platform
     participant SDK as Server SDK
-    participant UI as Your Frontend
+    participant Client as Client SDK
 
     LLM->>Platform: 1. Decides to call tool
-    Platform-->>UI: tool-input-start, tool-input-delta
-    Platform-->>UI: tool-input-available
+    Platform-->>Client: tool-input-start, tool-input-delta
+    Platform-->>Client: tool-input-available
     Platform-->>SDK: 2. tool-request (stream pauses)
 
-    Note over SDK: 3. Execute handler<br/>tools['get-user']()
-
-    SDK-->>UI: 4. tool-output-available
-    SDK->>Platform: 5. POST /trigger with results
-    Platform->>LLM: 6. Continue with results
+    alt Has server handler
+        Note over SDK: 3a. Execute handler<br/>tools['get-user']()
+        SDK-->>Client: tool-output-available
+        SDK->>Platform: Continue with results
+    else No server handler
+        SDK-->>Client: 3b. client-tool-request
+        Note over Client: Execute client tool<br/>or show interactive UI
+        Client->>SDK: Tool results
+        SDK->>Platform: Continue with results
+    end
+
+    Platform->>LLM: 4. Process results
     LLM-->>Platform: Response
-    Platform-->>UI: text-delta events
+    Platform-->>Client: text-delta events
 
-    Note over LLM,UI: 7. Repeat if more tools needed
+    Note over LLM,Client: 5. Repeat if more tools needed
 ```
 
 ## Accessing Request Context
@@ -173,6 +194,9 @@ import { toSSEStream } from '@octavus/server-sdk';
 
 // In your API route
 export async function POST(request: Request) {
+  const body = await request.json();
+  const { sessionId, ...payload } = body;
+
   const authToken = request.headers.get('Authorization');
   const user = await validateToken(authToken);
 
@@ -190,10 +214,11 @@ export async function POST(request: Request) {
           createdBy: user.email,
         });
       },
+      // Tools without handlers here are forwarded to the client
     },
   });
 
-  const events = session.trigger(triggerName, input);
+  const events = session.execute(payload, { signal: request.signal });
   return new Response(toSSEStream(events));
 }
 ```

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

@@ -9,14 +9,16 @@ All Octavus responses stream in real-time using Server-Sent Events (SSE). This e
 
 ## Stream Response
 
-When you trigger an action, you get an async generator of parsed events:
+When you execute a request, you get an async generator of parsed events:
 
 ```typescript
 import { toSSEStream } from '@octavus/server-sdk';
 
-// trigger() returns an async generator of StreamEvent
-const events = session.trigger('user-message', {
-  USER_MESSAGE: 'Hello!',
+// execute() returns an async generator of StreamEvent
+const events = session.execute({
+  type: 'trigger',
+  triggerName: 'user-message',
+  input: { USER_MESSAGE: 'Hello!' },
 });
 
 // For HTTP endpoints, convert to SSE stream
@@ -42,14 +44,15 @@ The stream emits various event types for lifecycle, text, reasoning, and tool in
 
 ```typescript
 // Stream started
-{ type: 'start', messageId: '...' }
+{ type: 'start', messageId: '...', executionId: '...' }
 
 // Stream completed
 { type: 'finish', finishReason: 'stop' }
 
 // Possible finish reasons:
 // - 'stop': Normal completion
-// - 'tool-calls': Waiting for tool execution (handled by SDK)
+// - 'tool-calls': Waiting for server tool execution (handled by SDK internally)
+// - 'client-tool-calls': Waiting for client tool execution
 // - 'length': Max tokens reached
 // - 'content-filter': Content filtered
 // - 'error': Error occurred
@@ -178,9 +181,54 @@ type StreamEvent =
   | BlockStartEvent
   | BlockEndEvent
   | ResourceUpdateEvent
-  | ToolRequestEvent;
+  | ToolRequestEvent
+  | ClientToolRequestEvent;
 ```
 
+### Client Tool Request
+
+When a tool has no server handler registered, the SDK emits a `client-tool-request` event:
+
+```typescript
+{
+  type: 'client-tool-request',
+  executionId: 'exec_abc123',       // Use this to continue execution
+  toolCalls: [                       // Tools for client to handle
+    {
+      toolCallId: 'call_xyz',
+      toolName: 'get-browser-location',
+      args: {}
+    }
+  ],
+  serverToolResults: [               // Results from server tools in same batch
+    {
+      toolCallId: 'call_def',
+      toolName: 'get-user-account',
+      result: { name: 'Demo User' }
+    }
+  ]
+}
+```
+
+After the client handles the tools, send a `continue` request with all results:
+
+```typescript
+session.execute({
+  type: 'continue',
+  executionId: 'exec_abc123',
+  toolResults: [
+    ...serverToolResults, // Include server results from the event
+    {
+      toolCallId: 'call_xyz',
+      toolName: 'get-browser-location',
+      result: { lat: 40.7128, lng: -74.006 },
+    },
+  ],
+});
+```
+
+See [Client Tools](/docs/client-sdk/client-tools) for full client-side implementation.
+
 ## Error Events
 
 Errors are emitted as structured events with type classification:

package/content/02-server-sdk/05-cli.md

@@ -17,26 +17,26 @@ npm install --save-dev @octavus/cli
 
 ## Configuration
 
-The CLI requires an API key with agent management permissions.
+The CLI requires an API key with the **Agents** permission.
 
 ### Environment Variables
 
-| Variable              | Description                                             |
-| --------------------- | ------------------------------------------------------- |
-| `OCTAVUS_CLI_API_KEY` | API key with agent management permissions (recommended) |
-| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set               |
-| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`              |
+| Variable              | Description                                    |
+| --------------------- | ---------------------------------------------- |
+| `OCTAVUS_CLI_API_KEY` | API key with "Agents" permission (recommended) |
+| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set      |
+| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`     |
 
 ### Two-Key Strategy (Recommended)
 
-For production deployments, use separate API keys:
+For production deployments, use separate API keys with minimal permissions:
 
 ```bash
 # CI/CD or .env.local (not committed)
-OCTAVUS_CLI_API_KEY=oct_sk_...  # Agent management permissions
+OCTAVUS_CLI_API_KEY=oct_sk_...  # "Agents" permission only
 
 # Production .env
-OCTAVUS_API_KEY=oct_sk_...      # Session-only permissions
+OCTAVUS_API_KEY=oct_sk_...      # "Sessions" permission only
 ```
 
 This ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.

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

@@ -58,11 +58,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],
@@ -105,11 +106,12 @@ The `OctavusChat` class can be used with any framework or vanilla JavaScript:
 import { OctavusChat, createHttpTransport } from '@octavus/client-sdk';
 
 const transport = 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,
     }),
 });
 
@@ -168,7 +170,8 @@ message.parts.map((part) => {
 ```tsx
 const { status } = useOctavusChat({ transport });
 
-// status: 'idle' | 'streaming' | 'error'
+// status: 'idle' | 'streaming' | 'error' | 'awaiting-input'
+// 'awaiting-input' occurs when interactive client tools need user action
 ```
 
 ### Stop Streaming
@@ -196,6 +199,11 @@ interface OctavusChatOptions {
     files: { filename: string; mediaType: string; size: number }[],
   ) => Promise<UploadUrlsResponse>;
 
+  // Optional: Client-side tool handlers
+  // - Function: executes automatically and returns result
+  // - 'interactive': appears in pendingClientTools for user input
+  clientTools?: Record<string, ClientToolHandler>;
+
   // Optional: Pre-populate with existing messages (session restore)
   initialMessages?: UIMessage[];
 
@@ -209,13 +217,16 @@ interface OctavusChatOptions {
 interface UseOctavusChatReturn {
   // State
   messages: UIMessage[];
-  status: ChatStatus; // 'idle' | 'streaming' | 'error'
+  status: ChatStatus; // 'idle' | 'streaming' | 'error' | 'awaiting-input'
   error: OctavusError | null; // Structured error with type, source, retryable
 
   // Connection (socket transport only - undefined for HTTP)
   connectionState: ConnectionState | undefined; // 'disconnected' | 'connecting' | 'connected' | 'error'
   connectionError: Error | undefined;
 
+  // Client tools (interactive tools awaiting user input)
+  pendingClientTools: Record<string, InteractiveTool[]>; // Keyed by tool name
+
   // Actions
   send: (
     triggerName: string,
@@ -251,11 +262,11 @@ Creates an HTTP/SSE transport using native `fetch()`:
 import { createHttpTransport } from '@octavus/react';
 
 const transport = 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,
     }),
 });
@@ -308,8 +319,9 @@ class OctavusChat {
 
   // State (read-only)
   readonly messages: UIMessage[];
-  readonly status: ChatStatus;
+  readonly status: ChatStatus; // 'idle' | 'streaming' | 'error' | 'awaiting-input'
   readonly error: OctavusError | null; // Structured error
+  readonly pendingClientTools: Record<string, InteractiveTool[]>; // Interactive tools
 
   // Actions
   send(
@@ -330,6 +342,7 @@ class OctavusChat {
 - [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
+- [Client Tools](/docs/client-sdk/client-tools) — Interactive browser-side tool handling
 - [Operations](/docs/client-sdk/execution-blocks) — Showing agent progress
 - [Error Handling](/docs/client-sdk/error-handling) — Handling errors with type guards
 - [File Uploads](/docs/client-sdk/file-uploads) — Uploading images and documents

package/content/03-client-sdk/02-messages.md

@@ -119,11 +119,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],
@@ -346,11 +347,12 @@ function Chat({ sessionId, initialMessages }: ChatProps) {
   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/03-streaming.md

@@ -12,7 +12,8 @@ The Client SDK provides real-time access to streaming content through the messag
 ```tsx
 const { messages, status, error } = useOctavusChat({ transport });
 
-// status: 'idle' | 'streaming' | 'error'
+// status: 'idle' | 'streaming' | 'error' | 'awaiting-input'
+// 'awaiting-input' occurs when interactive client tools need user action
 // Each message has status: 'streaming' | 'done'
 // Each part has its own status too
 ```
@@ -27,11 +28,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],
@@ -148,6 +150,8 @@ function StatusIndicator({ status }: { status: ChatStatus }) {
       return null;
     case 'streaming':
       return <div>Agent is responding...</div>;
+    case 'awaiting-input':
+      return <div className="text-amber-500">Waiting for your input...</div>;
     case 'error':
       return <div className="text-red-500">Something went wrong</div>;
   }

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

@@ -155,24 +155,28 @@ function createSocketHandler() {
         return;
       }
 
-      if (msg.type === 'trigger') {
+      // Handle both trigger and continue messages
+      if (msg.type === 'trigger' || msg.type === 'continue') {
         // 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
             },
           });
         }
 
+        if (!session) return;
+
         abortController = new AbortController();
 
-        // Iterate events directly — no SSE parsing needed
-        const events = session.trigger(msg.triggerName, msg.input, {
+        // execute() handles both triggers and continuations
+        const events = session.execute(msg, {
           signal: abortController.signal,
         });
 
@@ -256,7 +260,7 @@ sockServer.on('connection', (conn) => {
     if (msg.type === 'init') {
       session = client.agentSessions.attach(msg.sessionId, {
         tools: {
-          /* ... */
+          // Server-side tool handlers
         },
       });
       return;
@@ -281,8 +285,16 @@ sockServer.on('connection', (conn) => {
       return;
     }
 
-    if (msg.type === 'trigger') {
-      // ... handle trigger (same as server-managed pattern)
+    // 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));
+      }
     }
   }
 });
@@ -505,9 +517,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 +533,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).