@octavus/docs 0.0.2 → 0.0.4

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

@@ -51,10 +51,16 @@ import { NextResponse } from 'next/server';
 import { octavus } from '@/lib/octavus';
 
 export async function POST(request: Request) {
-  const { agentId, input } = await request.json();
+  const { agentSlug, input } = await request.json();
 
-  // Create a new session
-  const sessionId = await octavus.agentSessions.create(agentId, input);
+  // Look up agent by slug to get its ID
+  const agent = await octavus.agents.getBySlug(agentSlug);
+  if (!agent) {
+    return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
+  }
+
+  // Create a new session using the agent ID
+  const sessionId = await octavus.agentSessions.create(agent.id, input);
 
   return NextResponse.json({ sessionId });
 }
@@ -227,7 +233,7 @@ export default function ChatPage() {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          agentId: 'support-chat',
+          agentSlug: 'support-chat',
           input: {
             COMPANY_NAME: 'Acme Corp',
             PRODUCT_NAME: 'Widget Pro',

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

@@ -7,6 +7,8 @@ description: Introduction to the Octavus Server SDK for backend integration.
 
 The `@octavus/server-sdk` package provides a Node.js SDK for integrating Octavus agents into your backend application. It handles session management, streaming, and the tool execution continuation loop.
 
+**Current version:** `{{VERSION:@octavus/server-sdk}}`
+
 ## Installation
 
 ```bash

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

@@ -148,12 +148,13 @@ sequenceDiagram
     participant UI as Your Frontend
 
     LLM->>Platform: 1. Decides to call tool
-    Platform-->>UI: tool-call-start, tool-call-args
+    Platform-->>UI: tool-input-start, tool-input-delta
+    Platform-->>UI: tool-input-available
     Platform-->>SDK: 2. tool-request (stream pauses)
     
     Note over SDK: 3. Execute handler<br/>tools['get-user']()
     
-    SDK-->>UI: 4. tool-call-result
+    SDK-->>UI: 4. tool-output-available
     SDK->>Platform: 5. POST /trigger with results
     Platform->>LLM: 6. Continue with results
     LLM-->>Platform: Response

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

@@ -28,7 +28,28 @@ return new Response(stream, {
 
 ## Event Types
 
-The stream emits various event types:
+The stream emits various event types. Octavus events align with the [Vercel AI SDK](https://sdk.vercel.ai/) naming conventions where applicable.
+
+### Lifecycle Events
+
+```typescript
+// Stream started
+{ type: 'start', messageId: '...' }
+
+// Stream completed
+{ type: 'finish', finishReason: 'stop' }
+
+// Possible finish reasons:
+// - 'stop': Normal completion
+// - 'tool-calls': Waiting for tool execution (handled by SDK)
+// - 'length': Max tokens reached
+// - 'content-filter': Content filtered
+// - 'error': Error occurred
+// - 'other': Other reason
+
+// Error event
+{ type: 'error', errorText: 'Something went wrong' }
+```
 
 ### Block Events
 
@@ -36,7 +57,7 @@ Track execution progress:
 
 ```typescript
 // Block started
-{ type: 'block-start', blockId: '...', blockName: 'Respond to user', blockType: 'next-message', display: 'stream' }
+{ type: 'block-start', blockId: '...', blockName: 'Respond to user', blockType: 'next-message', display: 'stream', thread: 'main' }
 
 // Block completed
 { type: 'block-end', blockId: '...', summary: 'Generated response' }
@@ -51,48 +72,54 @@ Streaming text content:
 { 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?' }
+{ type: 'text-delta', id: '...', delta: 'Hello' }
+{ type: 'text-delta', id: '...', delta: '!' }
+{ type: 'text-delta', id: '...', delta: ' How' }
+{ type: 'text-delta', id: '...', delta: ' can' }
+{ type: 'text-delta', id: '...', delta: ' I' }
+{ type: 'text-delta', id: '...', delta: ' help?' }
 
 // Text generation ended
 { type: 'text-end', id: '...' }
 ```
 
-### Tool Events
+### Reasoning Events
 
-Tool call lifecycle:
+Extended reasoning (for supported models like Claude):
 
 ```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"}' }
+// Reasoning started
+{ type: 'reasoning-start', id: '...' }
 
-// Tool completed successfully
-{ type: 'tool-call-result', toolCallId: '...', result: { name: 'Demo User', email: '...' } }
+// Reasoning content
+{ type: 'reasoning-delta', id: '...', delta: 'Let me analyze this request...' }
 
-// Tool failed
-{ type: 'tool-call-error', toolCallId: '...', error: 'User not found' }
+// Reasoning ended
+{ type: 'reasoning-end', id: '...' }
 ```
 
-### Thinking Events
+### Tool Events
 
-Extended reasoning (for supported models):
+Tool call lifecycle:
 
 ```typescript
-// Thinking started
-{ type: 'thinking-start', id: '...', thread: 'main' }
+// Tool input started
+{ type: 'tool-input-start', toolCallId: '...', toolName: 'get-user-account', title: 'Looking up account' }
+
+// Tool input/arguments streaming
+{ type: 'tool-input-delta', toolCallId: '...', inputTextDelta: '{"userId":"user-123"}' }
+
+// Tool input streaming ended
+{ type: 'tool-input-end', toolCallId: '...' }
 
-// Thinking content
-{ type: 'thinking-delta', content: 'Let me analyze this request...' }
+// Tool input is complete and available
+{ type: 'tool-input-available', toolCallId: '...', toolName: 'get-user-account', input: { userId: 'user-123' } }
 
-// Thinking ended
-{ type: 'thinking-end', id: '...' }
+// Tool output available (success)
+{ type: 'tool-output-available', toolCallId: '...', output: { name: 'Demo User', email: '...' } }
+
+// Tool output error (failure)
+{ type: 'tool-output-error', toolCallId: '...', errorText: 'User not found' }
 ```
 
 ### Resource Events
@@ -103,22 +130,6 @@ Resource updates:
 { 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:
@@ -136,63 +147,30 @@ Each block/tool specifies how it should appear to users:
 
 ```typescript
 type StreamEvent =
-  | TextDeltaEvent
+  // Lifecycle
+  | StartEvent
+  | FinishEvent
+  | ErrorEvent
+  // Text
   | TextStartEvent
+  | TextDeltaEvent
   | TextEndEvent
-  | ToolCallStartEvent
-  | ToolCallArgsEvent
-  | ToolCallResultEvent
-  | ToolCallErrorEvent
-  | ResourceUpdateEvent
+  // Reasoning
+  | ReasoningStartEvent
+  | ReasoningDeltaEvent
+  | ReasoningEndEvent
+  // Tool Input/Output
+  | ToolInputStartEvent
+  | ToolInputDeltaEvent
+  | ToolInputEndEvent
+  | ToolInputAvailableEvent
+  | ToolOutputAvailableEvent
+  | ToolOutputErrorEvent
+  // Octavus-Specific
   | 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;
-        }
-      }
-    }
-  }
-}
+  | ResourceUpdateEvent
+  | ToolRequestEvent;
 ```
 
 ## Error Recovery
@@ -201,11 +179,10 @@ The SDK handles common error scenarios:
 
 ```typescript
 // Network errors are caught and emitted
-{ type: 'error', message: 'Network request failed' }
+{ type: 'error', errorText: 'Network request failed' }
 
 // Tool errors are captured per-tool
-{ type: 'tool-call-error', toolCallId: '...', error: 'Handler threw exception' }
+{ type: 'tool-output-error', toolCallId: '...', errorText: 'Handler threw exception' }
 
-// The stream always ends with either 'done' or 'error'
+// The stream always ends with either 'finish' or 'error'
 ```
-

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

@@ -7,6 +7,8 @@ description: Introduction to the Octavus Client SDK for building chat interfaces
 
 The `@octavus/client-sdk` package provides React hooks for building chat interfaces with Octavus agents. It handles streaming, message state, and execution blocks.
 
+**Current version:** `{{VERSION:@octavus/client-sdk}}`
+
 ## Installation
 
 ```bash
@@ -61,7 +63,7 @@ Text streams incrementally as the LLM generates it:
 const { streamingText, streamingParts } = useOctavusChat({...});
 
 // streamingText: Current streaming text
-// streamingParts: Structured parts (text, thinking, tool calls)
+// streamingParts: Structured parts (text, reasoning, tool calls)
 ```
 
 ### Message History
@@ -77,7 +79,7 @@ const { messages } = useOctavusChat({...});
 // - content: Text content
 // - parts: Ordered content parts
 // - toolCalls: Tool call information
-// - thinking: Extended reasoning (if enabled)
+// - reasoning: Extended reasoning (if enabled)
 ```
 
 ### Execution Blocks
@@ -132,7 +134,7 @@ interface UseOctavusChatReturn {
   streamingText: string;
   streamingParts: MessagePart[];
   executionBlocks: ExecutionBlock[];
-  thinkingText: string;
+  reasoningText: string;
   
   // Actions
   addUserMessage: (content: string) => void;
@@ -145,4 +147,3 @@ interface UseOctavusChatReturn {
 - [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
-

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

@@ -16,7 +16,7 @@ interface Message {
   content: string;
   parts?: MessagePart[];
   toolCalls?: ToolCallWithDescription[];
-  thinking?: string;
+  reasoning?: string;
   visible?: boolean;
   createdAt: Date;
 }
@@ -28,9 +28,9 @@ For rich content display, use the `parts` array which preserves content ordering
 
 ```typescript
 interface MessagePart {
-  type: 'text' | 'thinking' | 'tool-call';
+  type: 'text' | 'reasoning' | 'tool-call';
   visible: boolean;
-  content?: string;      // For text and thinking
+  content?: string;      // For text and reasoning
   toolCall?: ToolCallInfo;  // For tool-call
   thread?: string;       // For non-main thread content
 }
@@ -77,7 +77,7 @@ function MessageList({ messages }: { messages: Message[] }) {
 
 ### Rich Rendering with Parts
 
-For messages with tool calls and thinking, render parts in order:
+For messages with tool calls and reasoning, render parts in order:
 
 ```tsx
 function MessageContent({ message }: { message: Message }) {
@@ -94,7 +94,7 @@ function MessageContent({ message }: { message: Message }) {
           case 'text':
             return <p key={i}>{part.content}</p>;
 
-          case 'thinking':
+          case 'reasoning':
             return (
               <details key={i} className="text-gray-500">
                 <summary>Thinking...</summary>
@@ -106,7 +106,7 @@ function MessageContent({ message }: { message: Message }) {
             return (
               <div key={i} className="bg-gray-100 p-2 rounded text-sm">
                 🔧 {part.toolCall?.name}
-                {part.toolCall?.status === 'completed' && ' ✓'}
+                {part.toolCall?.status === 'available' && ' ✓'}
               </div>
             );
 
@@ -129,7 +129,7 @@ interface ToolCallInfo {
   name: string;
   description?: string;
   arguments: Record<string, unknown>;
-  status: 'pending' | 'in_progress' | 'completed' | 'error';
+  status: 'pending' | 'streaming' | 'available' | 'error';
   result?: unknown;
   error?: string;
 }
@@ -147,7 +147,7 @@ function ToolCallCard({ toolCall }: { toolCall: ToolCallInfo }) {
         <StatusBadge status={toolCall.status} />
       </div>
       
-      {toolCall.status === 'completed' && toolCall.result && (
+      {toolCall.status === 'available' && toolCall.result && (
         <pre className="mt-2 text-xs bg-gray-50 p-2 rounded">
           {JSON.stringify(toolCall.result, null, 2)}
         </pre>
@@ -178,7 +178,7 @@ const initialMessages = sessionState.messages
     content: msg.content,
     parts: msg.parts,
     toolCalls: msg.toolCalls,
-    thinking: msg.reasoning,
+    reasoning: msg.reasoning,
     createdAt: new Date(msg.createdAt),
   }));
 
@@ -204,4 +204,3 @@ useOctavusChat({
   },
 });
 ```
-

package/content/03-client-sdk/03-streaming.md

@@ -13,7 +13,7 @@ The Client SDK provides real-time access to streaming content, enabling responsi
 const {
   streamingText,     // Current visible text being streamed
   streamingParts,    // Structured parts being streamed
-  thinkingText,      // Current thinking content
+  reasoningText,     // Current reasoning content
   status,            // 'idle' | 'loading' | 'streaming' | 'error'
   isLoading,         // true during loading or streaming
 } = useOctavusChat({...});
@@ -59,7 +59,7 @@ function StreamingContent() {
           case 'text':
             return <span key={i}>{part.content}</span>;
 
-          case 'thinking':
+          case 'reasoning':
             return (
               <div key={i} className="text-gray-500 italic">
                 💭 {part.content}
@@ -80,15 +80,15 @@ function StreamingContent() {
 }
 ```
 
-## Thinking Indicator
+## Reasoning Indicator
 
-Show when the model is "thinking" (extended reasoning):
+Show when the model is using extended reasoning:
 
 ```tsx
-function ThinkingIndicator() {
-  const { thinkingText, status } = useOctavusChat({...});
+function ReasoningIndicator() {
+  const { reasoningText, status } = useOctavusChat({...});
 
-  if (!thinkingText || status !== 'streaming') {
+  if (!reasoningText || status !== 'streaming') {
     return null;
   }
 
@@ -99,7 +99,7 @@ function ThinkingIndicator() {
         <span className="font-medium">Thinking...</span>
       </div>
       <p className="mt-2 text-sm text-gray-600 line-clamp-3">
-        {thinkingText}
+        {reasoningText}
       </p>
     </div>
   );
@@ -160,7 +160,7 @@ function ChatWithTools() {
 
   // Find active tool call
   const activeToolCall = streamingParts.find(
-    p => p.type === 'tool-call' && p.toolCall?.status === 'in_progress'
+    p => p.type === 'tool-call' && p.toolCall?.status === 'streaming'
   );
 
   return (
@@ -212,4 +212,3 @@ function StreamingContent() {
   );
 }
 ```
-

package/content/03-client-sdk/04-execution-blocks.md

@@ -20,7 +20,7 @@ interface ExecutionBlock {
   outputToChat: boolean;  // Whether output goes to main chat
   thread?: string;        // For named threads
   streamingText: string;  // Current streaming content
-  thinking?: string;      // Extended reasoning content
+  reasoning?: string;     // Extended reasoning content
   toolCalls: ToolCallWithDescription[];
   startedAt: Date;
   completedAt?: Date;
@@ -85,7 +85,7 @@ function ExecutionBlockCard({ block }: { block: ExecutionBlock }) {
           {block.toolCalls.map((tc) => (
             <div key={tc.id} className="text-sm flex items-center gap-1">
               🔧 {tc.description || tc.name}
-              {tc.status === 'completed' && ' ✓'}
+              {tc.status === 'available' && ' ✓'}
               {tc.status === 'error' && ' ✗'}
             </div>
           ))}
@@ -228,4 +228,3 @@ function getBlockLabel(block: ExecutionBlock): string {
 // ○ Creating a support ticket
 // ○ Respond with ticket info
 ```
-

package/content/04-protocol/01-overview.md

@@ -39,10 +39,12 @@ triggers:
   request-human:
     description: User clicks "Talk to Human"
 
-# Temporary variables for execution
+# Temporary variables for execution (with types)
 variables:
-  - SUMMARY
-  - TICKET
+  SUMMARY:
+    type: string
+  TICKET:
+    type: unknown
 
 # Tools the agent can use
 tools:

package/content/04-protocol/02-input-resources.md

@@ -41,7 +41,7 @@ input:
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `type` | Yes | Data type: `string`, `number`, `boolean`, `array`, `object` |
+| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |
 | `description` | No | Describes what this input is for |
 | `optional` | No | If true, consumer doesn't have to provide it |
 | `default` | No | Default value if not provided (defaults to `"NONE"`) |
@@ -74,20 +74,21 @@ Resources are persistent state that:
 
 ```yaml
 resources:
-  # Simple resource with default
+  # String resource with default
   CONVERSATION_SUMMARY:
+    type: string
     description: Running summary of the conversation
     default: ""
 
-  # Resource with type
+  # Resource with unknown type (for complex data)
   USER_CONTEXT:
-    type: object
+    type: unknown
     description: Cached user information
     default: {}
 
   # Read-only resource (agent can read but not write)
   SYSTEM_CONFIG:
-    type: object
+    type: unknown
     description: System configuration
     readonly: true
     default:
@@ -99,7 +100,7 @@ resources:
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `type` | No | Data type (defaults to string) |
+| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |
 | `description` | No | Describes the resource purpose |
 | `default` | No | Initial value |
 | `readonly` | No | If true, agent cannot write to it |
@@ -135,15 +136,29 @@ useOctavusChat({
 
 ## Variables
 
-Variables are temporary storage during execution. Unlike resources, they don't persist across triggers.
+Variables are internal state managed by block outputs. They persist across triggers but are not synced to the consumer (unlike resources).
 
 ```yaml
 variables:
-  - SUMMARY
-  - TICKET
-  - CONVERSATION_TEXT
+  SUMMARY:
+    type: string
+    description: Generated summary text
+  TICKET:
+    type: unknown
+    description: Ticket creation result
+  CONVERSATION_TEXT:
+    type: string
+    description: Serialized conversation
 ```
 
+### Variable Definition
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |
+| `description` | No | Describes what this variable stores |
+| `default` | No | Initial value |
+
 ### Using Variables
 
 Set variables as output from blocks:
@@ -170,31 +185,9 @@ handlers:
 
 ## Scoping
 
-| Type | Scope | Persistence |
-|------|-------|-------------|
-| `input` | Session | Read-only, set at creation |
-| `resources` | Session | Read/write, persists |
-| `variables` | Trigger execution | Temporary |
-
-```mermaid
-flowchart TB
-    subgraph Session["Session (persistent)"]
-        direction TB
-        Input["**input** (immutable)<br/>COMPANY_NAME, PRODUCT_NAME"]
-        Resources["**resources** (read/write)<br/>CONVERSATION_SUMMARY"]
-        
-        subgraph T1["Trigger: user-message"]
-            V1["**variables**: { }"]
-        end
-        
-        subgraph T2["Trigger: request-human"]
-            V2["**variables**: { SUMMARY, TICKET }"]
-        end
-    end
-    
-    Input -.-> T1
-    Input -.-> T2
-    Resources -.-> T1
-    Resources -.-> T2
-```
+| Type | Scope | Persistence | Synced to Consumer |
+|------|-------|-------------|---------------------|
+| `input` | Session | Immutable | Yes (at creation) |
+| `resources` | Session | Persists across triggers | Yes (via callbacks) |
+| `variables` | Session | Persists across triggers | No (internal only) |
 

package/content/04-protocol/03-triggers.md

@@ -58,7 +58,7 @@ triggers:
         type: string
       ANALYSIS_TYPE:
         type: string
-        enum: [summary, sentiment, extraction]
+        description: Type of analysis (summary, sentiment, extraction)
 ```
 
 ## Trigger Definition
@@ -69,7 +69,7 @@ triggers:
     description: Optional description
     input:
       VARIABLE_NAME:
-        type: string | number | boolean | array | object
+        type: string | number | boolean | unknown
         description: What this input is for
         optional: true | false  # defaults to false
         default: value  # default if optional and not provided
@@ -147,7 +147,7 @@ triggers:
     input:
       SEARCH_QUERY: { type: string }
       MAX_RESULTS: { type: number, optional: true, default: 10 }
-      CATEGORIES: { type: array, optional: true }
+      FILTER_CATEGORY: { type: string, optional: true }
 ```
 
 ## Best Practices
@@ -204,6 +204,6 @@ triggers:
   user-action:
     input:
       ACTION_TYPE: { type: string }  # "message" | "file" | "callback"
-      PAYLOAD: { type: object }      # Different structure per type
+      PAYLOAD: { type: unknown }     # Different structure per type
 ```