@octavus/docs 1.0.0 → 2.1.0

package/content/05-api-reference/03-agents.md

@@ -7,6 +7,18 @@ description: Agent management API endpoints.
 
 Manage agent definitions including protocols and prompts.
 
+## Permissions
+
+| Endpoint               | Method | Permission Required |
+| ---------------------- | ------ | ------------------- |
+| `/api/agents`          | GET    | Agents OR Sessions  |
+| `/api/agents/:id`      | GET    | Agents OR Sessions  |
+| `/api/agents`          | POST   | Agents              |
+| `/api/agents/:id`      | PATCH  | Agents              |
+| `/api/agents/validate` | POST   | Agents              |
+
+Read endpoints work with either permission since both the CLI (for sync) and Server SDK (for sessions) need to read agent definitions.
+
 ## List Agents
 
 Get all agents in the project.

package/content/06-examples/02-nextjs-chat.md

@@ -114,12 +114,13 @@ 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 the session with tool handlers
   const session = octavus.agentSessions.attach(sessionId, {
     tools: {
-      // Tool handlers run on YOUR server, not Octavus
+      // Server-side tool handlers run on YOUR server, not Octavus
       'get-user-account': async (args) => {
         const userId = args.userId as string;
         // Fetch from your database
@@ -143,11 +144,14 @@ export async function POST(request: Request) {
           estimatedResponse: '24 hours',
         };
       },
+
+      // Tools without handlers here are forwarded to the client
+      // See Client Tools docs for handling on frontend
     },
   });
 
-  // trigger() returns parsed events, toSSEStream() converts to SSE format
-  const events = session.trigger(triggerName, input);
+  // execute() handles both triggers and client tool continuations
+  const events = session.execute(payload, { signal: request.signal });
 
   return new Response(toSSEStream(events), {
     headers: {
@@ -159,7 +163,7 @@ export async function POST(request: Request) {
 }
 ```
 
-**Protocol Note:** Tool names and arguments are defined in your agent's protocol YAML. The tool handlers here must match those definitions.
+**Protocol Note:** Tool names and arguments are defined in your agent's protocol YAML. The tool handlers here must match those definitions. Tools without server handlers are forwarded to the client.
 
 ## Step 7: Build the Chat Component
 
@@ -181,11 +185,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],

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,25 +101,17 @@ 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
-      if (msg.type === 'trigger') {
+      // Handle trigger, continue, and stop messages
+      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 octavus.agentSessions.create(AGENT_ID, {
-            // Initial input variables from your protocol
             COMPANY_NAME: 'Acme Corp',
           });
 
           session = octavus.agentSessions.attach(sessionId, {
             tools: {
               'get-user-account': async () => {
-                // Fetch from your database
                 return { name: 'Demo User', plan: 'pro' };
               },
               'create-support-ticket': async () => {
@@ -128,25 +121,16 @@ export function createSocketHandler() {
           });
         }
 
-        abortController = new AbortController();
+        if (!session) return;
 
-        // trigger() returns parsed events — iterate directly
-        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
-        }
+        // handleSocketMessage manages abort controller internally
+        await session.handleSocketMessage(msg as SocketMessage, {
+          onEvent: send,
+        });
       }
     }
 
-    conn.on('close', () => {
-      abortController?.abort();
-    });
+    conn.on('close', () => {});
   };
 }
 ```
@@ -358,26 +342,29 @@ conn.write(
 
 ## Protocol Integration
 
-### Triggers
+### Messages
 
-The socket handler receives trigger messages and forwards them to Octavus:
+The socket handler receives messages and forwards them to Octavus:
 
 ```typescript
-// Client sends:
+// Client sends trigger:
 { type: 'trigger', triggerName: 'user-message', input: { USER_MESSAGE: 'Hello' } }
 
-// Server handles:
-if (msg.type === 'trigger') {
-  const events = session.trigger(msg.triggerName, msg.input);
-  for await (const event of events) {
-    conn.write(JSON.stringify(event));
-  }
-}
+// Client sends continuation (after client tool handling):
+{ type: 'continue', executionId: '...', toolResults: [...] }
+
+// Client sends stop:
+{ type: 'stop' }
+
+// Server handles all three with handleSocketMessage:
+await session.handleSocketMessage(msg, {
+  onEvent: (event) => conn.write(JSON.stringify(event)),
+});
 ```
 
 ### Tools
 
-Tools are defined in your agent's protocol and handled server-side:
+Tools are defined in your agent's protocol. Server-side tools have handlers, client-side tools don't:
 
 ```yaml
 # protocol.yaml
@@ -387,18 +374,25 @@ tools:
     parameters:
       userId:
         type: string
+
+  get-browser-location:
+    description: Get user's location from browser
+    # No server handler - handled on client
 ```
 
 ```typescript
-// Server tool handler
+// Server tool handlers (only for server tools)
 tools: {
   'get-user-account': async (args) => {
     const userId = args.userId as string;
     return await db.users.find(userId);
   },
+  // get-browser-location has no handler - forwarded to client
 }
 ```
 
+See [Client Tools](/docs/client-sdk/client-tools) for handling tools on the frontend.
+
 ## Meteor Integration Note
 
 Meteor's bundler may have issues with ES6 imports of `sockjs-client`:

package/content/07-migration/01-v1-to-v2.md

@@ -0,0 +1,366 @@
+---
+title: Migrating from v1 to v2
+description: Complete guide for upgrading from Octavus SDK v1.x to v2.0.
+---
+
+# Migrating from v1 to v2
+
+This guide covers all breaking changes and new features in Octavus SDK v2.0.0.
+
+## Overview
+
+Version 2.0.0 introduces **client-side tool execution**, allowing tools to run in the browser with support for both automatic execution and interactive user input. This required changes to the transport layer and streaming protocol.
+
+## Breaking Changes
+
+### HTTP Transport Configuration
+
+The `triggerRequest` option has been renamed to `request` and the function signature changed to support both trigger and continuation requests.
+
+**Before (v1):**
+
+```typescript
+import { createHttpTransport } from '@octavus/client-sdk';
+
+const transport = createHttpTransport({
+  triggerRequest: (triggerName, input, options) =>
+    fetch('/api/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, triggerName, input }),
+      signal: options?.signal,
+    }),
+});
+```
+
+**After (v2):**
+
+```typescript
+import { createHttpTransport } from '@octavus/client-sdk';
+
+const transport = createHttpTransport({
+  request: (payload, options) =>
+    fetch('/api/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, ...payload }),
+      signal: options?.signal,
+    }),
+});
+```
+
+The `payload` parameter is a discriminated union with `type: 'trigger' | 'continue'`:
+
+- **Trigger request:** `{ type: 'trigger', triggerName: string, input?: Record<string, unknown> }`
+- **Continue request:** `{ type: 'continue', executionId: string, toolResults: ToolResult[] }`
+
+### Server SDK Route Handler
+
+Server-side route handlers should use the new `execute()` method which handles both triggers and continuations via the request type.
+
+**Before (v1):**
+
+```typescript
+// app/api/trigger/route.ts
+import { AgentSession, toSSEStream } from '@octavus/server-sdk';
+
+export async function POST(request: Request) {
+  const { sessionId, triggerName, input } = await request.json();
+
+  const session = new AgentSession({
+    sessionId,
+    agentId: 'your-agent-id',
+    apiKey: process.env.OCTAVUS_API_KEY!,
+  });
+
+  const events = session.trigger(triggerName, input, { signal: request.signal });
+  return new Response(toSSEStream(events), {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
+```
+
+**After (v2):**
+
+```typescript
+// app/api/trigger/route.ts
+import { AgentSession, toSSEStream, type SessionRequest } from '@octavus/server-sdk';
+
+export async function POST(request: Request) {
+  const body = (await request.json()) as { sessionId: string } & SessionRequest;
+  const { sessionId, ...sessionRequest } = body;
+
+  const session = new AgentSession({
+    sessionId,
+    agentId: 'your-agent-id',
+    apiKey: process.env.OCTAVUS_API_KEY!,
+  });
+
+  const events = session.execute(sessionRequest, { signal: request.signal });
+  return new Response(toSSEStream(events), {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
+```
+
+The `SessionRequest` type is a discriminated union:
+
+- **Trigger:** `{ type: 'trigger', triggerName: string, input?: Record<string, unknown> }`
+- **Continue:** `{ type: 'continue', executionId: string, toolResults: ToolResult[] }`
+
+### Export Changes
+
+The SDKs no longer use star exports (`export * from '@octavus/core'`). Instead, they use explicit type exports and value exports. This improves tree-shaking but may require import adjustments.
+
+**If you were importing schemas:**
+
+Some Zod schemas are no longer re-exported from `@octavus/server-sdk`. If you need validation schemas, import them directly from `@octavus/core`:
+
+```typescript
+// Before (v1) - some schemas were re-exported
+import { fileUploadRequestSchema } from '@octavus/server-sdk';
+
+// After (v2) - import from core if needed
+import { fileReferenceSchema } from '@octavus/core';
+```
+
+**Type imports remain the same:**
+
+```typescript
+// Types are still available
+import type { StreamEvent, UIMessage, FileReference } from '@octavus/client-sdk';
+```
+
+### Custom Transport Interface
+
+Custom transport implementations must now implement the `continueWithToolResults()` method:
+
+```typescript
+interface Transport {
+  trigger(triggerName: string, input?: Record<string, unknown>): AsyncIterable<StreamEvent>;
+  continueWithToolResults(executionId: string, results: ToolResult[]): AsyncIterable<StreamEvent>;
+  stop(): void;
+}
+```
+
+### New ChatStatus Value
+
+The `ChatStatus` type now includes `'awaiting-input'`:
+
+```typescript
+// v1
+type ChatStatus = 'idle' | 'streaming' | 'error';
+
+// v2
+type ChatStatus = 'idle' | 'streaming' | 'error' | 'awaiting-input';
+```
+
+Update any status checks that assume only three values.
+
+### Stream Event Changes
+
+Two stream events have been modified:
+
+**StartEvent and FinishEvent now include executionId:**
+
+```typescript
+interface StartEvent {
+  type: 'start';
+  messageId?: string;
+  executionId?: string; // New in v2
+}
+
+interface FinishEvent {
+  type: 'finish';
+  finishReason: FinishReason;
+  executionId?: string; // New in v2
+}
+```
+
+**New FinishReason:**
+
+```typescript
+// Added 'client-tool-calls' to FinishReason
+type FinishReason =
+  | 'stop'
+  | 'tool-calls'
+  | 'client-tool-calls' // New in v2
+  | 'length'
+  | 'content-filter'
+  | 'error'
+  | 'other';
+```
+
+**New ClientToolRequestEvent:**
+
+```typescript
+interface ClientToolRequestEvent {
+  type: 'client-tool-request';
+  executionId: string;
+  toolCalls: PendingToolCall[];
+  serverToolResults?: ToolResult[];
+}
+```
+
+## New Features
+
+### Client-Side Tools
+
+v2 introduces client-side tool execution, allowing tools to run in the browser. This is useful for:
+
+- Accessing browser APIs (geolocation, clipboard, etc.)
+- Interactive tools requiring user input (confirmations, forms, selections)
+- Tools that need access to client-side state
+
+See the [Client Tools guide](/docs/client-sdk/client-tools) for full documentation.
+
+#### Automatic Client Tools
+
+Tools that execute automatically without user interaction:
+
+```typescript
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat() {
+  const { messages, send, status } = useOctavusChat({
+    transport: createHttpTransport({
+      request: (payload, options) =>
+        fetch('/api/trigger', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ sessionId, ...payload }),
+          signal: options?.signal,
+        }),
+    }),
+    clientTools: {
+      'get-browser-location': async (args, ctx) => {
+        const pos = await new Promise((resolve, reject) => {
+          navigator.geolocation.getCurrentPosition(resolve, reject);
+        });
+        return { lat: pos.coords.latitude, lng: pos.coords.longitude };
+      },
+      'get-clipboard': async () => {
+        return await navigator.clipboard.readText();
+      },
+    },
+  });
+
+  // ... rest of component
+}
+```
+
+#### Interactive Client Tools
+
+Tools that require user interaction before completing:
+
+```typescript
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat() {
+  const { messages, send, status, pendingClientTools } = useOctavusChat({
+    transport: createHttpTransport({
+      request: (payload, options) =>
+        fetch('/api/trigger', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ sessionId, ...payload }),
+          signal: options?.signal,
+        }),
+    }),
+    clientTools: {
+      'request-confirmation': 'interactive',
+      'select-option': 'interactive',
+    },
+  });
+
+  // Render UI for pending interactive tools
+  const confirmationTools = pendingClientTools['request-confirmation'] ?? [];
+
+  return (
+    <div>
+      {/* Chat messages */}
+
+      {/* Interactive tool UI */}
+      {confirmationTools.map((tool) => (
+        <ConfirmationModal
+          key={tool.toolCallId}
+          message={tool.args.message as string}
+          onConfirm={() => tool.submit({ confirmed: true })}
+          onCancel={() => tool.cancel('User declined')}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+### New Types for Client Tools
+
+```typescript
+// Context provided to automatic tool handlers
+interface ClientToolContext {
+  toolCallId: string;
+  toolName: string;
+  signal: AbortSignal;
+}
+
+// Handler types
+type ClientToolHandler =
+  | ((args: Record<string, unknown>, ctx: ClientToolContext) => Promise<unknown>)
+  | 'interactive';
+
+// Interactive tool with bound submit/cancel methods
+interface InteractiveTool {
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+  submit: (result: unknown) => void;
+  cancel: (reason?: string) => void;
+}
+```
+
+### pendingClientTools Property
+
+Both `OctavusChat` and `useOctavusChat` now expose `pendingClientTools`:
+
+```typescript
+// Record keyed by tool name, with array of pending tools
+const pendingClientTools: Record<string, InteractiveTool[]>;
+```
+
+This allows multiple simultaneous calls to the same tool (e.g., batch confirmations).
+
+## Migration Checklist
+
+Use this checklist to ensure you've addressed all breaking changes:
+
+- [ ] Update all Octavus packages to v2.0.0
+- [ ] Update HTTP transport from `triggerRequest` to `request` with new signature
+- [ ] Update server route handlers to use `execute()` with `SessionRequest` type
+- [ ] Update any status checks to handle `'awaiting-input'`
+- [ ] Update custom transport implementations to include `continueWithToolResults()`
+- [ ] Review any direct schema imports and update if needed
+- [ ] (Optional) Add client-side tools for browser-based functionality
+
+## Package Versions
+
+All packages should be updated together to ensure compatibility:
+
+```json
+{
+  "dependencies": {
+    "@octavus/core": "^2.0.0",
+    "@octavus/client-sdk": "^2.0.0",
+    "@octavus/server-sdk": "^2.0.0",
+    "@octavus/react": "^2.0.0"
+  }
+}
+```
+
+## Need Help?
+
+If you encounter issues during migration:
+
+- Check the [Client Tools documentation](/docs/client-sdk/client-tools) for the new features
+- Review the [HTTP Transport](/docs/client-sdk/http-transport) and [Server SDK Sessions](/docs/server-sdk/sessions) docs for updated APIs
+- [Open an issue](https://github.com/octavus-ai/js-sdk/issues) on GitHub if you find a bug

package/content/07-migration/_meta.md

@@ -0,0 +1,4 @@
+---
+title: Migration
+description: Upgrade guides for migrating between major versions of the Octavus SDKs.
+---