@octavus/docs 0.0.3 → 0.0.5

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

@@ -1,230 +1,134 @@
 ---
-title: Execution Blocks
-description: Tracking agent execution progress with the Client SDK.
+title: Operations
+description: Showing agent operations and progress with the Client SDK.
 ---
 
-# Execution Blocks
+# Operations
 
-Execution blocks let you show users what the agent is doing. Each block represents a step in the agent's execution flow.
+Operations represent internal agent activities like setting resources or serializing threads. They appear as `operation` parts in messages and help users understand what the agent is doing.
 
-## Block Structure
+## Operation Structure
 
 ```typescript
-interface ExecutionBlock {
-  id: string;
-  name: string;           // Human-readable name from protocol
-  type: string;           // Block type (next-message, tool-call, etc.)
-  status: BlockStatus;    // pending | running | completed | error
-  display: DisplayMode;   // hidden | name | description | stream
-  description?: string;
-  outputToChat: boolean;  // Whether output goes to main chat
+interface UIOperationPart {
+  type: 'operation';
+  operationId: string;
+  name: string;           // Human-readable name
+  operationType: string;  // e.g., 'set-resource', 'serialize-thread'
+  status: 'running' | 'done';
   thread?: string;        // For named threads
-  streamingText: string;  // Current streaming content
-  reasoning?: string;     // Extended reasoning content
-  toolCalls: ToolCallWithDescription[];
-  startedAt: Date;
-  completedAt?: Date;
 }
 ```
 
-## Accessing Blocks
+## Rendering Operations
 
-```tsx
-const { executionBlocks, onBlockStart, onBlockEnd } = useOctavusChat({
-  onTrigger: ...,
-  onBlockStart: (block) => {
-    console.log('Block started:', block.name);
-  },
-  onBlockEnd: (block) => {
-    console.log('Block completed:', block.name, block.status);
-  },
-});
-```
-
-## Showing Execution Progress
+Operations are typically shown as compact status indicators:
 
 ```tsx
-function ExecutionProgress() {
-  const { executionBlocks, status } = useOctavusChat({...});
-
-  if (status !== 'streaming' || executionBlocks.length === 0) {
-    return null;
-  }
+import type { UIOperationPart } from '@octavus/client-sdk';
 
+function OperationCard({ operation }: { operation: UIOperationPart }) {
   return (
-    <div className="space-y-2">
-      {executionBlocks.map((block) => (
-        <ExecutionBlockCard key={block.id} block={block} />
-      ))}
-    </div>
-  );
-}
-
-function ExecutionBlockCard({ block }: { block: ExecutionBlock }) {
-  return (
-    <div className="border rounded p-3">
-      <div className="flex items-center gap-2">
-        <BlockStatusIcon status={block.status} />
-        <span className="font-medium">{block.name}</span>
-      </div>
-
-      {block.description && (
-        <p className="text-sm text-gray-500 mt-1">{block.description}</p>
-      )}
-
-      {/* Show streaming content for stream display mode */}
-      {block.display === 'stream' && block.streamingText && (
-        <div className="mt-2 text-sm">
-          {block.streamingText}
-        </div>
-      )}
-
-      {/* Show tool calls */}
-      {block.toolCalls.length > 0 && (
-        <div className="mt-2 space-y-1">
-          {block.toolCalls.map((tc) => (
-            <div key={tc.id} className="text-sm flex items-center gap-1">
-              🔧 {tc.description || tc.name}
-              {tc.status === 'available' && ' ✓'}
-              {tc.status === 'error' && ' ✗'}
-            </div>
-          ))}
-        </div>
+    <div className="flex items-center gap-2 text-sm text-gray-500">
+      {operation.status === 'running' ? (
+        <span className="h-2 w-2 animate-pulse rounded-full bg-blue-500" />
+      ) : (
+        <span className="text-green-500">✓</span>
       )}
+      <span>{operation.name}</span>
     </div>
   );
 }
 ```
 
-## Display Modes
-
-Blocks have different display modes that control visibility:
+## Operations in Messages
 
-| Mode | Description | UI Recommendation |
-|------|-------------|-------------------|
-| `hidden` | Not shown to user | Don't render |
-| `name` | Shows block name | Show name only |
-| `description` | Shows description | Show name + description |
-| `stream` | Streams content | Show full streaming content |
+Operations appear alongside text, reasoning, and tool calls in the message's `parts` array:
 
 ```tsx
-function ExecutionBlockCard({ block }: { block: ExecutionBlock }) {
-  // Hidden blocks aren't sent to client, but check just in case
-  if (block.display === 'hidden') {
-    return null;
-  }
+import type { UIMessage, UIMessagePart } from '@octavus/client-sdk';
 
+function MessageBubble({ message }: { message: UIMessage }) {
   return (
-    <div className="border rounded p-3">
-      {/* Always show name */}
-      <div className="font-medium">{block.name}</div>
-
-      {/* Show description if display mode is description or stream */}
-      {(block.display === 'description' || block.display === 'stream') && 
-        block.description && (
-          <p className="text-sm text-gray-500">{block.description}</p>
-        )}
-
-      {/* Show content if display mode is stream */}
-      {block.display === 'stream' && (
-        <div className="mt-2">
-          {block.streamingText}
-        </div>
-      )}
+    <div>
+      {message.parts.map((part, i) => (
+        <PartRenderer key={i} part={part} />
+      ))}
     </div>
   );
 }
+
+function PartRenderer({ part }: { part: UIMessagePart }) {
+  switch (part.type) {
+    case 'text':
+      return <TextPart part={part} />;
+    case 'reasoning':
+      return <ReasoningPart part={part} />;
+    case 'tool-call':
+      return <ToolCallCard part={part} />;
+    case 'operation':
+      return <OperationCard operation={part} />;
+    default:
+      return null;
+  }
+}
 ```
 
-## Named Threads
+## Common Operation Types
+
+| Type | Description |
+|------|-------------|
+| `set-resource` | Updating a resource value |
+| `serialize-thread` | Converting thread messages to text |
+
+## Example: Progress During Escalation
 
-Blocks can belong to named threads (like "summary"). Use the `thread` property:
+When a user clicks "Talk to Human", multiple operations may occur:
 
 ```tsx
-function ExecutionProgress() {
-  const { executionBlocks } = useOctavusChat({...});
-
-  // Group by thread
-  const mainBlocks = executionBlocks.filter(b => !b.thread || b.thread === 'main');
-  const namedThreads = new Map<string, ExecutionBlock[]>();
-
-  executionBlocks.forEach(b => {
-    if (b.thread && b.thread !== 'main') {
-      if (!namedThreads.has(b.thread)) {
-        namedThreads.set(b.thread, []);
-      }
-      namedThreads.get(b.thread)!.push(b);
-    }
-  });
+function EscalationProgress({ message }: { message: UIMessage }) {
+  const operations = message.parts.filter(
+    (p): p is UIOperationPart => p.type === 'operation'
+  );
 
   return (
-    <div>
-      {/* Main execution */}
-      <div className="space-y-2">
-        {mainBlocks.map(b => <BlockCard key={b.id} block={b} />)}
-      </div>
-
-      {/* Named threads */}
-      {Array.from(namedThreads.entries()).map(([thread, blocks]) => (
-        <div key={thread} className="mt-4 bg-orange-50 p-3 rounded">
-          <div className="text-orange-600 font-medium mb-2">
-            Thread: {thread}
-          </div>
-          {blocks.map(b => <BlockCard key={b.id} block={b} />)}
+    <div className="space-y-2">
+      {operations.map((op) => (
+        <div key={op.operationId} className="flex items-center gap-2 text-sm">
+          {op.status === 'running' ? '⏳' : '✓'}
+          <span>{op.name}</span>
         </div>
       ))}
     </div>
   );
 }
+
+// Example output during escalation:
+// ✓ Serialize conversation
+// ✓ Save conversation summary
+// ⏳ Creating support ticket...
 ```
 
-## Block Status Icons
+## Display Modes
 
-```tsx
-function BlockStatusIcon({ status }: { status: BlockStatus }) {
-  switch (status) {
-    case 'pending':
-      return <Circle className="w-4 h-4 text-gray-400" />;
-    case 'running':
-      return <Loader className="w-4 h-4 text-blue-500 animate-spin" />;
-    case 'completed':
-      return <CheckCircle className="w-4 h-4 text-green-500" />;
-    case 'error':
-      return <XCircle className="w-4 h-4 text-red-500" />;
-  }
-}
-```
+Operations are only sent to the client if their protocol block has a visible display mode (`name`, `description`, or `stream`). Hidden operations (`display: hidden`) are filtered out by the platform before reaching the client.
 
-## Example: Support Chat with Escalation
+This means you can safely render all operations without checking display mode — hidden ones won't be in the message parts.
 
-When a user clicks "Talk to Human", the agent runs multiple blocks:
+## Named Thread Operations
 
-```tsx
-function SupportChatProgress() {
-  const { executionBlocks } = useOctavusChat({...});
+Operations can belong to named threads. Use the `thread` property to identify them:
 
-  // Show blocks while streaming
+```tsx
+function OperationCard({ operation }: { operation: UIOperationPart }) {
   return (
-    <div className="space-y-2">
-      {executionBlocks.map((block) => (
-        <div key={block.id} className="flex items-center gap-2">
-          <BlockStatusIcon status={block.status} />
-          <span>{getBlockLabel(block)}</span>
-        </div>
-      ))}
+    <div className="flex items-center gap-2 text-sm">
+      {operation.thread && (
+        <span className="text-amber-500">[{operation.thread}]</span>
+      )}
+      <span>{operation.name}</span>
+      {operation.status === 'done' && <span className="text-green-500">✓</span>}
     </div>
   );
 }
-
-function getBlockLabel(block: ExecutionBlock): string {
-  // Use description if available, otherwise name
-  return block.description || block.name;
-}
-
-// Example output during escalation:
-// ✓ Serialize conversation
-// ✓ Start summary thread
-// ● Summarizing your conversation (streaming...)
-// ○ Creating a support ticket
-// ○ Respond with ticket info
 ```

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

@@ -52,9 +52,6 @@ tools:
     description: Looking up your account
     parameters:
       userId: { type: string }
-    returns:
-      name: { type: string }
-      email: { type: string }
 
 # Agent configuration (model, tools, etc.)
 agent:

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

@@ -80,19 +80,18 @@ triggers:
 ### From Client SDK
 
 ```typescript
-// User message trigger
-await triggerAction('user-message', { 
-  USER_MESSAGE: 'How do I reset my password?' 
+const { send } = useOctavusChat({...});
+
+// User message trigger with UI message
+await send('user-message', { USER_MESSAGE: text }, {
+  userMessage: { content: text },
 });
 
-// User action trigger (no input)
-await triggerAction('request-human');
+// User action trigger (no input, no UI message)
+await send('request-human');
 
 // Action with input
-await triggerAction('submit-feedback', { 
-  RATING: 5, 
-  COMMENT: 'Great help!' 
-});
+await send('submit-feedback', { RATING: 5, COMMENT: 'Great help!' });
 ```
 
 ### From Server SDK

package/content/04-protocol/04-tools.md

@@ -18,11 +18,6 @@ tools:
       userId:
         type: string
         description: The user ID to look up
-    returns:
-      name: { type: string }
-      email: { type: string }
-      plan: { type: string }
-      createdAt: { type: string }
 ```
 
 ### Tool Fields
@@ -32,8 +27,6 @@ tools:
 | `description` | Yes | What the tool does (shown to LLM and optionally user) |
 | `display` | No | How to show in UI: `hidden`, `name`, `description`, `stream` |
 | `parameters` | No | Input parameters the tool accepts |
-| `required` | No | List of required parameter names |
-| `returns` | No | Schema of the return value (for documentation) |
 
 ### Display Modes
 
@@ -44,9 +37,19 @@ tools:
 | `description` | Shows description while executing (default) |
 | `stream` | Streams tool progress if available |
 
-## Parameter Types
+## Parameters
 
-Supported types: `string`, `number`, `boolean`, `unknown`
+### Parameter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |
+| `description` | No | Describes what this parameter is for |
+| `optional` | No | If true, parameter is not required (default: false) |
+
+### Optional Parameters
+
+Parameters are **required by default**. Use `optional: true` to make a parameter optional:
 
 ```yaml
 tools:
@@ -59,15 +62,18 @@ tools:
       
       category:
         type: string
-        description: Filter by category (electronics, clothing, books, home)
+        description: Filter by category
+        optional: true
       
       maxPrice:
         type: number
         description: Maximum price filter
+        optional: true
       
       inStock:
         type: boolean
         description: Only show in-stock items
+        optional: true
 ```
 
 ## Making Tools Available
@@ -218,23 +224,7 @@ tools:
     description: Gets some data
 ```
 
-### 2. Define Expected Returns
-
-```yaml
-tools:
-  search-products:
-    description: Search products
-    parameters:
-      query: { type: string }
-    returns:
-      products:
-        type: unknown
-        description: Array of product objects
-      totalCount:
-        type: number
-```
-
-### 3. Document Constrained Values
+### 2. Document Constrained Values
 
 ```yaml
 tools:

package/content/04-protocol/06-agent-config.md

@@ -57,7 +57,6 @@ agent:
   input:
     - COMPANY_NAME
     - PRODUCT_NAME
-    - SUPPORT_POLICIES
 ```
 
 Example `prompts/system.md`:
@@ -74,12 +73,6 @@ Help users with questions about {{PRODUCT_NAME}}.
 - Be helpful and professional
 - If you can't help, offer to escalate
 - Never share internal information
-
-{{#if SUPPORT_POLICIES}}
-## Support Policies
-
-{{SUPPORT_POLICIES}}
-{{/if}}
 ```
 
 ## Agentic Mode

package/content/05-api-reference/02-sessions.md

@@ -60,7 +60,7 @@ curl -X POST https://octavus.ai/api/agent-sessions \
 
 ## Get Session
 
-Retrieve session state including messages and resources.
+Retrieve session state including UI-ready messages and resources.
 
 ```
 GET /api/agent-sessions/:sessionId
@@ -68,6 +68,8 @@ GET /api/agent-sessions/:sessionId
 
 ### Response
 
+The response includes `UIMessage` objects that can be passed directly to the client SDK's `initialMessages` option:
+
 ```json
 {
   "id": "cm5xyz123abc456def",
@@ -85,19 +87,19 @@ GET /api/agent-sessions/:sessionId
       "id": "1702345800000-xyz789a",
       "role": "user",
       "parts": [
-        { "type": "text", "visible": true, "content": "How do I reset my password?" }
+        { "type": "text", "text": "How do I reset my password?", "status": "done" }
       ],
-      "content": "How do I reset my password?",
-      "createdAt": "2024-01-15T10:30:00Z"
+      "status": "done",
+      "createdAt": "2024-01-15T10:30:00.000Z"
     },
     {
       "id": "1702345805000-def456b",
       "role": "assistant",
       "parts": [
-        { "type": "text", "visible": true, "content": "I can help you reset your password..." }
+        { "type": "text", "text": "I can help you reset your password...", "status": "done" }
       ],
-      "content": "I can help you reset your password...",
-      "createdAt": "2024-01-15T10:30:05Z"
+      "status": "done",
+      "createdAt": "2024-01-15T10:30:05.000Z"
     }
   ],
   "createdAt": "2024-01-15T10:30:00Z",
@@ -105,6 +107,17 @@ GET /api/agent-sessions/:sessionId
 }
 ```
 
+### UIMessage Parts
+
+Messages contain typed `parts` that preserve content ordering:
+
+| Part Type | Description |
+|-----------|-------------|
+| `text` | Text content with `text` and `status` fields |
+| `reasoning` | Extended reasoning with `text` and `status` fields |
+| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |
+| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |
+
 ### Example
 
 ```bash