@octavus/docs 0.0.1

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

@@ -0,0 +1,242 @@
+---
+title: Tools
+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.
+
+## Why Tools Run on Your Server
+
+Unlike traditional AI platforms where tools run in a sandbox, Octavus tools execute in your backend:
+
+- ✅ **Full data access** — Query your database directly
+- ✅ **Your authentication** — Use your existing auth context
+- ✅ **No data exposure** — Sensitive data never leaves your infrastructure
+- ✅ **Custom logic** — Any complexity you need
+
+## Defining Tool Handlers
+
+Tool handlers are async functions that receive arguments and return results:
+
+```typescript
+import type { ToolHandlers } from '@octavus/server-sdk';
+
+const tools: ToolHandlers = {
+  'get-user-account': async (args) => {
+    const userId = args.userId as string;
+    
+    // Query your database
+    const user = await db.users.findById(userId);
+    
+    return {
+      name: user.name,
+      email: user.email,
+      plan: user.subscription.plan,
+      createdAt: user.createdAt.toISOString(),
+    };
+  },
+  
+  'create-support-ticket': async (args) => {
+    const summary = args.summary as string;
+    const priority = args.priority as string;
+    
+    // Create ticket in your system
+    const ticket = await ticketService.create({
+      summary,
+      priority,
+      source: 'ai-chat',
+    });
+    
+    return {
+      ticketId: ticket.id,
+      estimatedResponse: getEstimatedResponse(priority),
+    };
+  },
+};
+```
+
+## Using Tools in Sessions
+
+Pass tool handlers when attaching to a session:
+
+```typescript
+const session = client.agentSessions.attach(sessionId, {
+  tools: {
+    'get-user-account': async (args) => {
+      // Implementation
+    },
+    'create-support-ticket': async (args) => {
+      // Implementation
+    },
+  },
+});
+```
+
+## Tool Handler Signature
+
+```typescript
+type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
+type ToolHandlers = Record<string, ToolHandler>;
+```
+
+### Arguments
+
+Arguments are passed as a `Record<string, unknown>`. Type-check as needed:
+
+```typescript
+'search-products': async (args) => {
+  const query = args.query as string;
+  const category = args.category as string | undefined;
+  const maxPrice = args.maxPrice as number | undefined;
+  
+  return await productSearch({ query, category, maxPrice });
+}
+```
+
+### Return Values
+
+Return any JSON-serializable value. The result is:
+1. Sent back to the LLM as context
+2. Stored in session state
+3. Optionally stored in a variable for protocol use
+
+```typescript
+// Return object
+return { id: '123', status: 'created' };
+
+// Return array
+return [{ id: '1' }, { id: '2' }];
+
+// Return primitive
+return 42;
+
+// Return null for "no result"
+return null;
+```
+
+## Error Handling
+
+Throw errors for failures. They're captured and sent to the LLM:
+
+```typescript
+'get-user-account': async (args) => {
+  const userId = args.userId as string;
+  
+  const user = await db.users.findById(userId);
+  
+  if (!user) {
+    throw new Error(`User not found: ${userId}`);
+  }
+  
+  return user;
+}
+```
+
+The LLM receives the error message and can respond appropriately (e.g., "I couldn't find that account").
+
+## Tool Execution Flow
+
+When the LLM calls a tool:
+
+```mermaid
+sequenceDiagram
+    participant LLM
+    participant Platform as Octavus Platform
+    participant SDK as Server SDK
+    participant UI as Your Frontend
+
+    LLM->>Platform: 1. Decides to call tool
+    Platform-->>UI: tool-call-start, tool-call-args
+    Platform-->>SDK: 2. tool-request (stream pauses)
+    
+    Note over SDK: 3. Execute handler<br/>tools['get-user']()
+    
+    SDK-->>UI: 4. tool-call-result
+    SDK->>Platform: 5. POST /trigger with results
+    Platform->>LLM: 6. Continue with results
+    LLM-->>Platform: Response
+    Platform-->>UI: text-delta events
+    
+    Note over LLM,UI: 7. Repeat if more tools needed
+```
+
+## Accessing Request Context
+
+For request-specific data (auth, headers), create handlers dynamically:
+
+```typescript
+// In your API route
+export async function POST(request: Request) {
+  const authToken = request.headers.get('Authorization');
+  const user = await validateToken(authToken);
+  
+  const session = client.agentSessions.attach(sessionId, {
+    tools: {
+      'get-user-account': async (args) => {
+        // Use request context
+        return await db.users.findById(user.id);
+      },
+      'create-order': async (args) => {
+        // Create with user context
+        return await orderService.create({
+          ...args,
+          userId: user.id,
+          createdBy: user.email,
+        });
+      },
+    },
+  });
+  
+  const { stream } = session.trigger(triggerName, input);
+  return new Response(stream);
+}
+```
+
+## Best Practices
+
+### 1. Validate Arguments
+
+```typescript
+'create-ticket': async (args) => {
+  const summary = args.summary;
+  if (typeof summary !== 'string' || summary.length === 0) {
+    throw new Error('Summary is required');
+  }
+  // ...
+}
+```
+
+### 2. Handle Timeouts
+
+```typescript
+'external-api-call': async (args) => {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 10000);
+  
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    return await response.json();
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+```
+
+### 3. Log Tool Calls
+
+```typescript
+'search-products': async (args) => {
+  console.log('Tool call: search-products', { args });
+  
+  const result = await productSearch(args);
+  
+  console.log('Tool result: search-products', { 
+    resultCount: result.length 
+  });
+  
+  return result;
+}
+```
+

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

@@ -0,0 +1,211 @@
+---
+title: Streaming
+description: Understanding stream events from the Server SDK.
+---
+
+# Streaming
+
+All Octavus responses stream in real-time using Server-Sent Events (SSE). This enables responsive UX with incremental updates.
+
+## Stream Response
+
+When you trigger an action, you get a readable stream:
+
+```typescript
+const { stream } = session.trigger('user-message', { 
+  USER_MESSAGE: 'Hello!' 
+});
+
+// Return to frontend as streaming response
+return new Response(stream, {
+  headers: {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+  },
+});
+```
+
+## Event Types
+
+The stream emits various event types:
+
+### Block Events
+
+Track execution progress:
+
+```typescript
+// Block started
+{ type: 'block-start', blockId: '...', blockName: 'Respond to user', blockType: 'next-message', display: 'stream' }
+
+// Block completed
+{ type: 'block-end', blockId: '...', summary: 'Generated response' }
+```
+
+### Text Events
+
+Streaming text content:
+
+```typescript
+// Text generation started
+{ type: 'text-start', id: '...' }
+
+// Incremental text (most common event)
+{ type: 'text-delta', content: 'Hello' }
+{ type: 'text-delta', content: '!' }
+{ type: 'text-delta', content: ' How' }
+{ type: 'text-delta', content: ' can' }
+{ type: 'text-delta', content: ' I' }
+{ type: 'text-delta', content: ' help?' }
+
+// Text generation ended
+{ type: 'text-end', id: '...' }
+```
+
+### Tool Events
+
+Tool call lifecycle:
+
+```typescript
+// Tool call initiated
+{ type: 'tool-call-start', toolCallId: '...', toolName: 'get-user-account', toolDescription: 'Looking up account' }
+
+// Tool arguments (JSON string)
+{ type: 'tool-call-args', toolCallId: '...', argsJson: '{"userId":"user-123"}' }
+
+// Tool completed successfully
+{ type: 'tool-call-result', toolCallId: '...', result: { name: 'Demo User', email: '...' } }
+
+// Tool failed
+{ type: 'tool-call-error', toolCallId: '...', error: 'User not found' }
+```
+
+### Thinking Events
+
+Extended reasoning (for supported models):
+
+```typescript
+// Thinking started
+{ type: 'thinking-start', id: '...', thread: 'main' }
+
+// Thinking content
+{ type: 'thinking-delta', content: 'Let me analyze this request...' }
+
+// Thinking ended
+{ type: 'thinking-end', id: '...' }
+```
+
+### Resource Events
+
+Resource updates:
+
+```typescript
+{ type: 'resource-update', name: 'CONVERSATION_SUMMARY', value: 'User asked about...' }
+```
+
+### Completion Events
+
+```typescript
+// Stream completed
+{ type: 'done', finishReason: 'stop' }
+
+// Possible finish reasons:
+// - 'stop': Normal completion
+// - 'tool-calls': Waiting for tool execution (handled by SDK)
+// - 'length': Max tokens reached
+// - 'error': Error occurred
+
+// Error event
+{ type: 'error', message: 'Something went wrong', code: 'EXECUTION_ERROR' }
+```
+
+## Display Modes
+
+Each block/tool specifies how it should appear to users:
+
+| Mode | Description |
+|------|-------------|
+| `hidden` | Not shown to user (background work) |
+| `name` | Shows block/tool name |
+| `description` | Shows description text |
+| `stream` | Streams content to chat |
+
+**Note**: Hidden events are filtered before reaching the client SDK. Your frontend only sees user-facing events.
+
+## Stream Event Type
+
+```typescript
+type StreamEvent =
+  | TextDeltaEvent
+  | TextStartEvent
+  | TextEndEvent
+  | ToolCallStartEvent
+  | ToolCallArgsEvent
+  | ToolCallResultEvent
+  | ToolCallErrorEvent
+  | ResourceUpdateEvent
+  | BlockStartEvent
+  | BlockEndEvent
+  | ThinkingStartEvent
+  | ThinkingDeltaEvent
+  | ThinkingEndEvent
+  | DoneEvent
+  | ErrorEvent;
+```
+
+## Handling Streams Manually
+
+If you need to process the stream server-side:
+
+```typescript
+import { safeParseStreamEvent } from '@octavus/core';
+
+const { stream } = session.trigger('user-message', { USER_MESSAGE: 'Hello' });
+
+const reader = stream.getReader();
+const decoder = new TextDecoder();
+
+let buffer = '';
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  
+  buffer += decoder.decode(value, { stream: true });
+  const lines = buffer.split('\n');
+  buffer = lines.pop() ?? '';
+  
+  for (const line of lines) {
+    if (line.startsWith('data: ') && line !== 'data: [DONE]') {
+      const parsed = safeParseStreamEvent(JSON.parse(line.slice(6)));
+      if (parsed.success) {
+        const event = parsed.data;
+        
+        switch (event.type) {
+          case 'text-delta':
+            process.stdout.write(event.content);
+            break;
+          case 'done':
+            console.log('\nDone:', event.finishReason);
+            break;
+        }
+      }
+    }
+  }
+}
+```
+
+## Error Recovery
+
+The SDK handles common error scenarios:
+
+```typescript
+// Network errors are caught and emitted
+{ type: 'error', message: 'Network request failed' }
+
+// Tool errors are captured per-tool
+{ type: 'tool-call-error', toolCallId: '...', error: 'Handler threw exception' }
+
+// The stream always ends with either 'done' or 'error'
+```
+

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

@@ -0,0 +1,4 @@
+---
+title: Server SDK
+description: Backend integration with @octavus/server-sdk for Node.js applications.
+---

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

@@ -0,0 +1,148 @@
+---
+title: Overview
+description: Introduction to the Octavus Client SDK for building chat interfaces.
+---
+
+# Client SDK Overview
+
+The `@octavus/client-sdk` package provides React hooks for building chat interfaces with Octavus agents. It handles streaming, message state, and execution blocks.
+
+## Installation
+
+```bash
+npm install @octavus/client-sdk
+```
+
+## Basic Usage
+
+```tsx
+import { useOctavusChat } from '@octavus/client-sdk';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const {
+    messages,
+    status,
+    isLoading,
+    streamingText,
+    addUserMessage,
+    triggerAction,
+  } = useOctavusChat({
+    onTrigger: async (triggerName, input) => {
+      return fetch(`/api/chat/${sessionId}/trigger`, {
+        method: 'POST',
+        body: JSON.stringify({ triggerName, input }),
+      });
+    },
+  });
+
+  const sendMessage = async (text: string) => {
+    addUserMessage(text);
+    await triggerAction('user-message', { USER_MESSAGE: text });
+  };
+
+  return (
+    <div>
+      {messages.map((msg) => (
+        <div key={msg.id}>{msg.content}</div>
+      ))}
+      {streamingText && <div>{streamingText}</div>}
+    </div>
+  );
+}
+```
+
+## Key Features
+
+### Real-time Streaming
+
+Text streams incrementally as the LLM generates it:
+
+```tsx
+const { streamingText, streamingParts } = useOctavusChat({...});
+
+// streamingText: Current streaming text
+// streamingParts: Structured parts (text, thinking, tool calls)
+```
+
+### Message History
+
+Messages are tracked automatically:
+
+```tsx
+const { messages } = useOctavusChat({...});
+
+// Each message includes:
+// - id: Unique identifier
+// - role: 'user' | 'assistant'
+// - content: Text content
+// - parts: Ordered content parts
+// - toolCalls: Tool call information
+// - thinking: Extended reasoning (if enabled)
+```
+
+### Execution Blocks
+
+Track what the agent is doing:
+
+```tsx
+const { executionBlocks } = useOctavusChat({...});
+
+// Shows active execution steps
+// Useful for progress indicators
+```
+
+### Status Tracking
+
+```tsx
+const { status, isLoading } = useOctavusChat({...});
+
+// status: 'idle' | 'loading' | 'streaming' | 'error'
+// isLoading: true during loading or streaming
+```
+
+## Hook Reference
+
+### useOctavusChat
+
+```typescript
+function useOctavusChat(options: UseOctavusChatOptions): UseOctavusChatReturn;
+
+interface UseOctavusChatOptions {
+  // Required: Function that calls your backend trigger endpoint
+  onTrigger: TriggerFunction;
+  
+  // Optional: Pre-populate with existing messages (session restore)
+  initialMessages?: Message[];
+  
+  // Optional: Callbacks
+  onMessage?: (message: Message) => void;
+  onError?: (error: Error) => void;
+  onDone?: () => void;
+  onResourceUpdate?: (name: string, value: unknown) => void;
+  onBlockStart?: (block: ExecutionBlock) => void;
+  onBlockEnd?: (block: ExecutionBlock) => void;
+}
+
+interface UseOctavusChatReturn {
+  // State
+  messages: Message[];
+  status: ChatStatus;
+  isLoading: boolean;
+  error: Error | null;
+  streamingText: string;
+  streamingParts: MessagePart[];
+  executionBlocks: ExecutionBlock[];
+  thinkingText: string;
+  
+  // Actions
+  addUserMessage: (content: string) => void;
+  triggerAction: (triggerName: string, input?: Record<string, unknown>) => Promise<void>;
+}
+```
+
+## Next Steps
+
+- [Messages](/docs/client-sdk/messages) — Working with message state
+- [Streaming](/docs/client-sdk/streaming) — Building streaming UIs
+- [Execution Blocks](/docs/client-sdk/execution-blocks) — Showing agent progress
+