@octavus/docs 0.0.4 → 0.0.6

package/dist/sections.json

@@ -10,7 +10,7 @@
         "section": "getting-started",
         "title": "Introduction",
         "description": "Overview of Octavus AI - an agent orchestration platform for developers.",
-        "content": "\n# Introduction to Octavus\n\nOctavus is an agent orchestration platform that lets developers define, manage, and deploy AI agents through a unified service. It handles the orchestration layer so teams can focus on their agent logic and business requirements.\n\n## What is Octavus?\n\nBuilding and managing AI agents is complex. Developers face challenges with:\n\n- **Fragmented tooling** — No unified way to define, manage, and deploy agents\n- **Prompt management** — Prompts are scattered across codebases, hard to version and iterate\n- **Integration complexity** — Connecting agents to tools, resources, and other agents requires significant custom work\n- **Observability** — Difficult to debug, monitor, and understand agent behavior in production\n- **Infrastructure overhead** — Teams rebuild the same agent infrastructure repeatedly\n\nOctavus solves these problems by providing:\n\n- A **protocol-based approach** to defining agent behavior\n- **Server and client SDKs** for easy integration\n- **Built-in streaming** support for real-time responses\n- **Tool execution** that runs on your servers with your data\n- **Session management** for stateful conversations\n\n## Core Concepts\n\n### Agents\n\nAn **Agent** is the main entity in Octavus — a self-contained unit that defines how an AI agent behaves. Agents are defined using YAML protocols that specify:\n\n- Input variables the agent accepts\n- Triggers that invoke the agent (user messages, button clicks, API calls)\n- Tools the agent can use\n- Handlers that define execution flow\n\n### Sessions\n\nA **Session** represents a conversation with an agent. Sessions:\n\n- Store conversation history\n- Track resources and variables\n- Enable stateful interactions across multiple messages\n\n### Triggers\n\n**Triggers** define how an agent is invoked:\n\n- **User Message** — Respond to a text message in a chat interface\n- **User Action** — Respond to UI actions (button clicks, form submissions)\n- **API Call** — Direct invocation via SDK\n\n### Tools\n\n**Tools** extend what agents can do:\n\n- **External Tools** — Consumer-defined tools that call back to your systems\n- **Internal Tools** — Built-in capabilities (web search, code execution)\n\nTools execute on your server, not on Octavus, giving you full control over data and authentication.\n\n## Architecture Overview\n\n```mermaid\nsequenceDiagram\n    participant App as Your App\n    participant API as Octavus API\n    participant LLM as LLM Provider\n\n    App->>API: 1. Trigger action\n    API->>LLM: 2. Execute protocol\n    LLM-->>API: Response\n    API-->>App: 3. Stream events\n    \n    Note over App: Tool request received\n    API-->>App: 4. Tool request\n    Note over App: 5. Execute tool locally\n    App->>API: 6. Return results\n    \n    API->>LLM: 7. Continue\n    LLM-->>API: Response\n    API-->>App: 8. Stream response\n```\n\n## Next Steps\n\n- [Quick Start](/docs/getting-started/quickstart) — Get your first agent running in minutes\n- [Server SDK](/docs/server-sdk/overview) — Learn about backend integration\n- [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React\n- [Protocol Reference](/docs/protocol/overview) — Deep dive into agent protocols\n\n",
+        "content": "\n# Introduction to Octavus\n\nOctavus is an agent orchestration platform that lets developers define, manage, and deploy AI agents through a unified service. It handles the orchestration layer so teams can focus on their agent logic and business requirements.\n\n## What is Octavus?\n\nBuilding and managing AI agents is complex. Developers face challenges with:\n\n- **Fragmented tooling** — No unified way to define, manage, and deploy agents\n- **Prompt management** — Prompts are scattered across codebases, hard to version and iterate\n- **Integration complexity** — Connecting agents to tools, resources, and other agents requires significant custom work\n- **Observability** — Difficult to debug, monitor, and understand agent behavior in production\n- **Infrastructure overhead** — Teams rebuild the same agent infrastructure repeatedly\n\nOctavus solves these problems by providing:\n\n- A **protocol-based approach** to defining agent behavior\n- **Server and client SDKs** for easy integration\n- **Built-in streaming** support for real-time responses\n- **Tool execution** that runs on your servers with your data\n- **Session management** for stateful conversations\n\n## Core Concepts\n\n### Agents\n\nAn **Agent** is the main entity in Octavus — a self-contained unit that defines how an AI agent behaves. Agents are defined using YAML protocols that specify:\n\n- Input variables the agent accepts\n- Triggers that invoke the agent (user messages, button clicks, API calls)\n- Tools the agent can use\n- Handlers that define execution flow\n\n### Sessions\n\nA **Session** represents a conversation with an agent. Sessions:\n\n- Store conversation history\n- Track resources and variables\n- Enable stateful interactions across multiple messages\n\n### Triggers\n\n**Triggers** define how an agent is invoked:\n\n- **User Message** — Respond to a text message in a chat interface\n- **User Action** — Respond to UI actions (button clicks, form submissions)\n- **API Call** — Direct invocation via SDK\n\n### Tools\n\n**Tools** extend what agents can do:\n\n- **External Tools** — Consumer-defined tools that call back to your systems\n- **Internal Tools** — Built-in capabilities (web search, code execution)\n\nTools execute on your server, not on Octavus, giving you full control over data and authentication.\n\n## Architecture Overview\n\n```mermaid\nsequenceDiagram\n    participant App as Your App\n    participant API as Octavus API\n    participant LLM as LLM Provider\n\n    App->>API: 1. Trigger action\n    API->>LLM: 2. Execute protocol\n    LLM-->>API: Response\n    API-->>App: 3. Stream events\n    \n    Note over App: Tool request received\n    API-->>App: 4. Tool request\n    Note over App: 5. Execute tool locally\n    App->>API: 6. Return results\n    \n    API->>LLM: 7. Continue\n    LLM-->>API: Response\n    API-->>App: 8. Stream response\n```\n\n## Next Steps\n\n- [Quick Start](/docs/getting-started/quickstart) — Get your first agent running in minutes\n- [Server SDK](/docs/server-sdk/overview) — Learn about backend integration\n- [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React (or other frameworks)\n- [Protocol Reference](/docs/protocol/overview) — Deep dive into agent protocols\n\n",
         "excerpt": "Introduction to Octavus Octavus is an agent orchestration platform that lets developers define, manage, and deploy AI agents through a unified service. It handles the orchestration layer so teams can...",
         "order": 1
       },
@@ -19,7 +19,7 @@
         "section": "getting-started",
         "title": "Quick Start",
         "description": "Get your first Octavus agent running in minutes.",
-        "content": "\n# Quick Start\n\nThis guide will walk you through integrating Octavus into your application in under 10 minutes.\n\n## Prerequisites\n\n- Node.js 18+\n- An Octavus account with API key\n- A Next.js application (or any Node.js backend)\n\n## Installation\n\nInstall the Octavus SDKs in your project:\n\n```bash\n# Server SDK for backend\nnpm install @octavus/server-sdk\n\n# Client SDK for frontend (React)\nnpm install @octavus/client-sdk\n```\n\n## Backend Setup\n\n### 1. Initialize the Client\n\nCreate an Octavus client instance in your backend:\n\n```typescript\n// lib/octavus.ts\nimport { OctavusClient } from '@octavus/server-sdk';\n\nexport const octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n```\n\n### 2. Create a Session Endpoint\n\nCreate an API endpoint that creates sessions and returns the session ID:\n\n```typescript\n// app/api/chat/create/route.ts\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { agentSlug, input } = await request.json();\n\n  // Look up agent by slug to get its ID\n  const agent = await octavus.agents.getBySlug(agentSlug);\n  if (!agent) {\n    return NextResponse.json({ error: 'Agent not found' }, { status: 404 });\n  }\n\n  // Create a new session using the agent ID\n  const sessionId = await octavus.agentSessions.create(agent.id, input);\n\n  return NextResponse.json({ sessionId });\n}\n```\n\n### 3. Create a Trigger Endpoint\n\nCreate an endpoint that handles triggers and streams responses:\n\n```typescript\n// app/api/trigger/route.ts\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, triggerName, input } = await request.json();\n\n  // Attach to session with tool handlers\n  const session = octavus.agentSessions.attach(sessionId, {\n    tools: {\n      // Define tool handlers that run on your server\n      'get-user-account': async (args) => {\n        const userId = args.userId as string;\n        // Fetch from your database\n        return {\n          name: 'Demo User',\n          email: 'demo@example.com',\n          plan: 'pro',\n        };\n      },\n      'create-support-ticket': async (args) => {\n        // Create ticket in your system\n        return {\n          ticketId: 'TICKET-123',\n          estimatedResponse: '24 hours',\n        };\n      },\n    },\n  });\n\n  // Trigger the action and get the stream\n  const { stream } = session.trigger(triggerName, input);\n\n  // Return as streaming response\n  return new Response(stream, {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n    },\n  });\n}\n```\n\n## Frontend Setup\n\n### 1. Create a Chat Component\n\nUse the `useOctavusChat` hook to build a chat interface:\n\n```tsx\n// components/chat.tsx\n'use client';\n\nimport { useOctavusChat } from '@octavus/client-sdk';\nimport { useState } from 'react';\n\ninterface ChatProps {\n  sessionId: string;\n}\n\nexport function Chat({ sessionId }: ChatProps) {\n  const [inputValue, setInputValue] = useState('');\n\n  const {\n    messages,\n    status,\n    isLoading,\n    streamingText,\n    addUserMessage,\n    triggerAction,\n  } = useOctavusChat({\n    onTrigger: async (triggerName, input) => {\n      return fetch('/api/trigger', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, triggerName, input }),\n      });\n    },\n  });\n\n  const handleSubmit = async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (!inputValue.trim() || isLoading) return;\n\n    const message = inputValue.trim();\n    setInputValue('');\n\n    // Add user message to UI\n    addUserMessage(message);\n\n    // Trigger the agent\n    await triggerAction('user-message', { USER_MESSAGE: message });\n  };\n\n  return (\n    <div className=\"flex flex-col h-full\">\n      {/* Messages */}\n      <div className=\"flex-1 overflow-y-auto p-4 space-y-4\">\n        {messages.map((msg) => (\n          <div\n            key={msg.id}\n            className={`p-3 rounded-lg ${\n              msg.role === 'user'\n                ? 'bg-blue-500 text-white ml-auto max-w-xs'\n                : 'bg-gray-100 max-w-md'\n            }`}\n          >\n            {msg.content}\n          </div>\n        ))}\n\n        {/* Streaming text */}\n        {streamingText && (\n          <div className=\"bg-gray-100 p-3 rounded-lg max-w-md\">\n            {streamingText}\n          </div>\n        )}\n      </div>\n\n      {/* Input */}\n      <form onSubmit={handleSubmit} className=\"p-4 border-t\">\n        <div className=\"flex gap-2\">\n          <input\n            type=\"text\"\n            value={inputValue}\n            onChange={(e) => setInputValue(e.target.value)}\n            placeholder=\"Type a message...\"\n            className=\"flex-1 px-4 py-2 border rounded-lg\"\n            disabled={isLoading}\n          />\n          <button\n            type=\"submit\"\n            disabled={isLoading}\n            className=\"px-4 py-2 bg-blue-500 text-white rounded-lg disabled:opacity-50\"\n          >\n            Send\n          </button>\n        </div>\n      </form>\n    </div>\n  );\n}\n```\n\n### 2. Create Session and Render Chat\n\n```tsx\n// app/chat/page.tsx\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { Chat } from '@/components/chat';\n\nexport default function ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    async function createSession() {\n      const response = await fetch('/api/chat/create', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          agentSlug: 'support-chat',\n          input: {\n            COMPANY_NAME: 'Acme Corp',\n            PRODUCT_NAME: 'Widget Pro',\n          },\n        }),\n      });\n      const { sessionId } = await response.json();\n      setSessionId(sessionId);\n    }\n\n    createSession();\n  }, []);\n\n  if (!sessionId) {\n    return <div>Loading...</div>;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\n## Environment Variables\n\nAdd these to your `.env.local`:\n\n```bash\nOCTAVUS_API_URL=https://octavus.ai\nOCTAVUS_API_KEY=your-api-key-here\n```\n\n## What's Next?\n\nNow that you have a basic integration working:\n\n- [Learn about the protocol](/docs/protocol/overview) to define custom agent behavior\n- [Explore the Server SDK](/docs/server-sdk/overview) for advanced backend features\n- [Build rich UIs](/docs/client-sdk/overview) with the Client SDK\n\n",
+        "content": "\n# Quick Start\n\nThis guide will walk you through integrating Octavus into your application in under 10 minutes.\n\n## Prerequisites\n\n- Node.js 18+\n- An Octavus account with API key\n- A Next.js application (or any Node.js backend)\n\n## Installation\n\nInstall the Octavus SDKs in your project:\n\n```bash\n# Server SDK for backend\nnpm install @octavus/server-sdk\n\n# React bindings for frontend\nnpm install @octavus/react\n```\n\n## Backend Setup\n\n### 1. Initialize the Client\n\nCreate an Octavus client instance in your backend:\n\n```typescript\n// lib/octavus.ts\nimport { OctavusClient } from '@octavus/server-sdk';\n\nexport const octavus = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n```\n\n### 2. Create a Session Endpoint\n\nCreate an API endpoint that creates sessions and returns the session ID:\n\n```typescript\n// app/api/chat/create/route.ts\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { agentSlug, input } = await request.json();\n\n  // Look up agent by slug to get its ID\n  const agent = await octavus.agents.getBySlug(agentSlug);\n  if (!agent) {\n    return NextResponse.json({ error: 'Agent not found' }, { status: 404 });\n  }\n\n  // Create a new session using the agent ID\n  const sessionId = await octavus.agentSessions.create(agent.id, input);\n\n  return NextResponse.json({ sessionId });\n}\n```\n\n### 3. Create a Trigger Endpoint\n\nCreate an endpoint that handles triggers and streams responses:\n\n```typescript\n// app/api/trigger/route.ts\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, triggerName, input } = await request.json();\n\n  // Attach to session with tool handlers\n  const session = octavus.agentSessions.attach(sessionId, {\n    tools: {\n      // Define tool handlers that run on your server\n      'get-user-account': async (args) => {\n        const userId = args.userId as string;\n        // Fetch from your database\n        return {\n          name: 'Demo User',\n          email: 'demo@example.com',\n          plan: 'pro',\n        };\n      },\n      'create-support-ticket': async (args) => {\n        // Create ticket in your system\n        return {\n          ticketId: 'TICKET-123',\n          estimatedResponse: '24 hours',\n        };\n      },\n    },\n  });\n\n  // Trigger the action and get the stream\n  const { stream } = session.trigger(triggerName, input);\n\n  // Return as streaming response\n  return new Response(stream, {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n    },\n  });\n}\n```\n\n## Frontend Setup\n\n### 1. Create a Chat Component\n\nUse the `useOctavusChat` hook to build a chat interface:\n\n```tsx\n// components/chat.tsx\n'use client';\n\nimport { useOctavusChat, type UIMessage } from '@octavus/react';\nimport { useState } from 'react';\n\ninterface ChatProps {\n  sessionId: string;\n}\n\nexport function Chat({ sessionId }: ChatProps) {\n  const [inputValue, setInputValue] = useState('');\n\n  const { messages, status, error, send } = useOctavusChat({\n    onTrigger: async (triggerName, input) => {\n      return fetch('/api/trigger', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, triggerName, input }),\n      });\n    },\n  });\n\n  const isStreaming = status === 'streaming';\n\n  const handleSubmit = async (e: React.FormEvent) => {\n    e.preventDefault();\n    if (!inputValue.trim() || isStreaming) return;\n\n    const message = inputValue.trim();\n    setInputValue('');\n\n    // Add user message and trigger in one call\n    await send('user-message', { USER_MESSAGE: message }, {\n      userMessage: { content: message },\n    });\n  };\n\n  return (\n    <div className=\"flex flex-col h-full\">\n      {/* Messages */}\n      <div className=\"flex-1 overflow-y-auto p-4 space-y-4\">\n        {messages.map((msg) => (\n          <MessageBubble key={msg.id} message={msg} />\n        ))}\n      </div>\n\n      {/* Input */}\n      <form onSubmit={handleSubmit} className=\"p-4 border-t\">\n        <div className=\"flex gap-2\">\n          <input\n            type=\"text\"\n            value={inputValue}\n            onChange={(e) => setInputValue(e.target.value)}\n            placeholder=\"Type a message...\"\n            className=\"flex-1 px-4 py-2 border rounded-lg\"\n            disabled={isStreaming}\n          />\n          <button\n            type=\"submit\"\n            disabled={isStreaming}\n            className=\"px-4 py-2 bg-blue-500 text-white rounded-lg disabled:opacity-50\"\n          >\n            Send\n          </button>\n        </div>\n      </form>\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  const isUser = message.role === 'user';\n\n  return (\n    <div className={`flex ${isUser ? 'justify-end' : 'justify-start'}`}>\n      <div\n        className={`p-3 rounded-lg max-w-md ${\n          isUser ? 'bg-blue-500 text-white' : 'bg-gray-100'\n        }`}\n      >\n        {message.parts.map((part, i) => {\n          if (part.type === 'text') {\n            return <p key={i}>{part.text}</p>;\n          }\n          return null;\n        })}\n        \n        {/* Streaming indicator */}\n        {message.status === 'streaming' && (\n          <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n        )}\n      </div>\n    </div>\n  );\n}\n```\n\n### 2. Create Session and Render Chat\n\n```tsx\n// app/chat/page.tsx\n'use client';\n\nimport { useEffect, useState } from 'react';\nimport { Chat } from '@/components/chat';\n\nexport default function ChatPage() {\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  useEffect(() => {\n    async function createSession() {\n      const response = await fetch('/api/chat/create', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          agentSlug: 'support-chat',\n          input: {\n            COMPANY_NAME: 'Acme Corp',\n            PRODUCT_NAME: 'Widget Pro',\n          },\n        }),\n      });\n      const { sessionId } = await response.json();\n      setSessionId(sessionId);\n    }\n\n    createSession();\n  }, []);\n\n  if (!sessionId) {\n    return <div>Loading...</div>;\n  }\n\n  return <Chat sessionId={sessionId} />;\n}\n```\n\n## Environment Variables\n\nAdd these to your `.env.local`:\n\n```bash\nOCTAVUS_API_URL=https://octavus.ai\nOCTAVUS_API_KEY=your-api-key-here\n```\n\n## What's Next?\n\nNow that you have a basic integration working:\n\n- [Learn about the protocol](/docs/protocol/overview) to define custom agent behavior\n- [Explore the Server SDK](/docs/server-sdk/overview) for advanced backend features\n- [Build rich UIs](/docs/client-sdk/overview) with the Client SDK\n",
         "excerpt": "Quick Start This guide will walk you through integrating Octavus into your application in under 10 minutes.  Prerequisites - Node.js 18+ - An Octavus account with API key - A Next.js application (or...",
         "order": 2
       }
@@ -36,7 +36,7 @@
         "section": "server-sdk",
         "title": "Overview",
         "description": "Introduction to the Octavus Server SDK for backend integration.",
-        "content": "\n# Server SDK Overview\n\nThe `@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.\n\n**Current version:** `0.0.4`\n\n## Installation\n\n```bash\nnpm install @octavus/server-sdk\n```\n\n## Basic Usage\n\n```typescript\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: 'https://octavus.ai',\n  apiKey: 'your-api-key',\n});\n```\n\n## Key Features\n\n### Session Management\n\nCreate and manage agent sessions:\n\n```typescript\n// Create a new session\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n});\n\n// Get session state\nconst state = await client.agentSessions.get(sessionId);\n```\n\n### Tool Handlers\n\nTools run on your server with your data:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      // Access your database, APIs, etc.\n      return await db.users.findById(args.userId);\n    },\n  },\n});\n```\n\n### Streaming\n\nAll responses stream in real-time:\n\n```typescript\nconst { stream } = session.trigger('user-message', { \n  USER_MESSAGE: 'Hello!' \n});\n\n// Use as a streaming response\nreturn new Response(stream, {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n## API Reference\n\n### OctavusClient\n\nThe main entry point for interacting with Octavus.\n\n```typescript\ninterface OctavusClientConfig {\n  baseUrl: string;  // Octavus API URL\n  apiKey?: string;  // Your API key\n}\n\nclass OctavusClient {\n  readonly agents: AgentsApi;\n  readonly agentSessions: AgentSessionsApi;\n  \n  constructor(config: OctavusClientConfig);\n}\n```\n\n### AgentSessionsApi\n\nManages agent sessions.\n\n```typescript\nclass AgentSessionsApi {\n  // Create a new session\n  async create(agentId: string, input?: Record<string, unknown>): Promise<string>;\n  \n  // Get session state\n  async get(sessionId: string): Promise<SessionState>;\n  \n  // Attach to a session for triggering\n  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;\n}\n```\n\n### AgentSession\n\nHandles triggering and streaming for a specific session.\n\n```typescript\nclass AgentSession {\n  // Trigger an action and stream the response\n  trigger(\n    triggerName: string,\n    input?: Record<string, unknown>\n  ): { stream: ReadableStream<Uint8Array> };\n  \n  // Get the session ID\n  getSessionId(): string;\n}\n```\n\n## Next Steps\n\n- [Sessions](/docs/server-sdk/sessions) — Deep dive into session management\n- [Tools](/docs/server-sdk/tools) — Implementing tool handlers\n- [Streaming](/docs/server-sdk/streaming) — Understanding stream events\n\n",
+        "content": "\n# Server SDK Overview\n\nThe `@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.\n\n**Current version:** `0.0.6`\n\n## Installation\n\n```bash\nnpm install @octavus/server-sdk\n```\n\n## Basic Usage\n\n```typescript\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: 'https://octavus.ai',\n  apiKey: 'your-api-key',\n});\n```\n\n## Key Features\n\n### Session Management\n\nCreate and manage agent sessions:\n\n```typescript\n// Create a new session\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n});\n\n// Get session state\nconst state = await client.agentSessions.get(sessionId);\n```\n\n### Tool Handlers\n\nTools run on your server with your data:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      // Access your database, APIs, etc.\n      return await db.users.findById(args.userId);\n    },\n  },\n});\n```\n\n### Streaming\n\nAll responses stream in real-time:\n\n```typescript\nconst { stream } = session.trigger('user-message', { \n  USER_MESSAGE: 'Hello!' \n});\n\n// Use as a streaming response\nreturn new Response(stream, {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n## API Reference\n\n### OctavusClient\n\nThe main entry point for interacting with Octavus.\n\n```typescript\ninterface OctavusClientConfig {\n  baseUrl: string;  // Octavus API URL\n  apiKey?: string;  // Your API key\n}\n\nclass OctavusClient {\n  readonly agents: AgentsApi;\n  readonly agentSessions: AgentSessionsApi;\n  \n  constructor(config: OctavusClientConfig);\n}\n```\n\n### AgentSessionsApi\n\nManages agent sessions.\n\n```typescript\nclass AgentSessionsApi {\n  // Create a new session\n  async create(agentId: string, input?: Record<string, unknown>): Promise<string>;\n  \n  // Get session state (includes UI-ready messages)\n  async get(sessionId: string): Promise<UISessionState>;\n  \n  // Attach to a session for triggering\n  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;\n}\n\ninterface UISessionState {\n  id: string;\n  agentId: string;\n  input: Record<string, unknown>;\n  variables: Record<string, unknown>;\n  resources: Record<string, unknown>;\n  messages: UIMessage[];  // UI-ready messages for session restore\n  createdAt: string;\n  updatedAt: string;\n}\n```\n\n### AgentSession\n\nHandles triggering and streaming for a specific session.\n\n```typescript\nclass AgentSession {\n  // Trigger an action and stream the response\n  trigger(\n    triggerName: string,\n    input?: Record<string, unknown>\n  ): { stream: ReadableStream<Uint8Array> };\n  \n  // Get the session ID\n  getSessionId(): string;\n}\n```\n\n## Next Steps\n\n- [Sessions](/docs/server-sdk/sessions) — Deep dive into session management\n- [Tools](/docs/server-sdk/tools) — Implementing tool handlers\n- [Streaming](/docs/server-sdk/streaming) — Understanding stream events\n",
         "excerpt": "Server SDK Overview The  package provides a Node.js SDK for integrating Octavus agents into your backend application. It handles session management, streaming, and the tool execution continuation...",
         "order": 1
       },
@@ -45,7 +45,7 @@
         "section": "server-sdk",
         "title": "Sessions",
         "description": "Managing agent sessions with the Server SDK.",
-        "content": "\n# Sessions\n\nSessions represent conversations with an agent. They store conversation history, track resources and variables, and enable stateful interactions.\n\n## Creating Sessions\n\nCreate a session by specifying the agent ID and initial input variables:\n\n```typescript\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\n// Create a session with the support-chat agent\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n  USER_ID: 'user-123', // Optional inputs\n});\n\nconsole.log('Session created:', sessionId);\n```\n\n## Session State\n\nRetrieve the current state of a session:\n\n```typescript\nconst state = await client.agentSessions.get(sessionId);\n\nconsole.log({\n  id: state.id,\n  agentId: state.agentId,\n  messages: state.messages.length,\n  resources: state.resources,\n  variables: state.variables,\n  createdAt: state.createdAt,\n  updatedAt: state.updatedAt,\n});\n```\n\n### SessionState Interface\n\n```typescript\ninterface SessionState {\n  id: string;\n  agentId: string;\n  input: Record<string, unknown>;      // Initial input (immutable)\n  variables: Record<string, unknown>;  // Mutable session variables\n  resources: Record<string, unknown>;  // Resources (synced to consumer)\n  messages: ChatMessage[];             // Conversation history\n  createdAt: string;\n  updatedAt: string;\n}\n```\n\n## Attaching to Sessions\n\nTo trigger actions on a session, you need to attach to it first:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    // Tool handlers (see Tools documentation)\n  },\n  resources: [\n    // Resource watchers (optional)\n  ],\n});\n```\n\n## Triggering Actions\n\nOnce attached, trigger actions on the session:\n\n```typescript\nconst { stream } = session.trigger('user-message', {\n  USER_MESSAGE: 'How do I reset my password?',\n});\n\n// Return the stream to your frontend\nreturn new Response(stream, {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n## Session Lifecycle\n\n```mermaid\nflowchart TD\n    A[1. CREATE] --> B[2. ATTACH]\n    B --> C[3. TRIGGER]\n    C --> C\n    C --> D[4. RETRIEVE]\n    D --> C\n    C --> E[5. EXPIRE]\n\n    A -.- A1[\"`**client.agentSessions.create()**\n    Returns sessionId\n    Initializes state`\"]\n    \n    B -.- B1[\"`**client.agentSessions.attach()**\n    Configure tool handlers\n    Configure resource watchers`\"]\n    \n    C -.- C1[\"`**session.trigger()**\n    Execute handler\n    Stream events\n    Update state`\"]\n    \n    D -.- D1[\"`**client.agentSessions.get()**\n    Get current state\n    Restore conversation`\"]\n    \n    E -.- E1[\"`Sessions expire after\n    24 hours (configurable)`\"]\n```\n\n## Restoring Sessions\n\nWhen a user returns to your app, restore their session:\n\n```typescript\n// On page load\nconst state = await client.agentSessions.get(sessionId);\n\n// Pass messages to frontend to restore UI\nreturn {\n  sessionId,\n  messages: state.messages,\n  resources: state.resources,\n};\n```\n\nThe `messages` array includes all conversation history with proper content ordering (text, tool calls, thinking blocks), enabling accurate UI restoration.\n\n## Error Handling\n\n```typescript\nimport { ApiError } from '@octavus/server-sdk';\n\ntry {\n  const state = await client.agentSessions.get(sessionId);\n} catch (error) {\n  if (error instanceof ApiError) {\n    if (error.status === 404) {\n      // Session not found or expired\n      console.log('Session expired, create a new one');\n    } else {\n      console.error('API Error:', error.message);\n    }\n  }\n  throw error;\n}\n```\n\n",
+        "content": "\n# Sessions\n\nSessions represent conversations with an agent. They store conversation history, track resources and variables, and enable stateful interactions.\n\n## Creating Sessions\n\nCreate a session by specifying the agent ID and initial input variables:\n\n```typescript\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst client = new OctavusClient({\n  baseUrl: process.env.OCTAVUS_API_URL!,\n  apiKey: process.env.OCTAVUS_API_KEY!,\n});\n\n// Create a session with the support-chat agent\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n  USER_ID: 'user-123', // Optional inputs\n});\n\nconsole.log('Session created:', sessionId);\n```\n\n## Getting Session Messages\n\nTo restore a conversation on page load, use `getMessages()` to retrieve UI-ready messages:\n\n```typescript\nconst session = await client.agentSessions.getMessages(sessionId);\n\nconsole.log({\n  sessionId: session.sessionId,\n  agentId: session.agentId,\n  messages: session.messages.length,  // UIMessage[] ready for frontend\n});\n```\n\nThe returned messages can be passed directly to the client SDK's `initialMessages` option.\n\n### UISessionState Interface\n\n```typescript\ninterface UISessionState {\n  sessionId: string;\n  agentId: string;\n  messages: UIMessage[];  // UI-ready conversation history\n}\n```\n\n## Full Session State (Debug)\n\nFor debugging or internal use, you can retrieve the complete session state including all variables and internal message format:\n\n```typescript\nconst state = await client.agentSessions.get(sessionId);\n\nconsole.log({\n  id: state.id,\n  agentId: state.agentId,\n  messages: state.messages.length,  // ChatMessage[] (internal format)\n  resources: state.resources,\n  variables: state.variables,\n  createdAt: state.createdAt,\n  updatedAt: state.updatedAt,\n});\n```\n\n> **Note**: Use `getMessages()` for client-facing code. The `get()` method returns internal message format that includes hidden content not intended for end users.\n\n## Attaching to Sessions\n\nTo trigger actions on a session, you need to attach to it first:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    // Tool handlers (see Tools documentation)\n  },\n  resources: [\n    // Resource watchers (optional)\n  ],\n});\n```\n\n## Triggering Actions\n\nOnce attached, trigger actions on the session:\n\n```typescript\nconst { stream } = session.trigger('user-message', {\n  USER_MESSAGE: 'How do I reset my password?',\n});\n\n// Return the stream to your frontend\nreturn new Response(stream, {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n## Session Lifecycle\n\n```mermaid\nflowchart TD\n    A[1. CREATE] --> B[2. ATTACH]\n    B --> C[3. TRIGGER]\n    C --> C\n    C --> D[4. RETRIEVE]\n    D --> C\n    C --> E[5. EXPIRE]\n\n    A -.- A1[\"`**client.agentSessions.create()**\n    Returns sessionId\n    Initializes state`\"]\n    \n    B -.- B1[\"`**client.agentSessions.attach()**\n    Configure tool handlers\n    Configure resource watchers`\"]\n    \n    C -.- C1[\"`**session.trigger()**\n    Execute handler\n    Stream events\n    Update state`\"]\n    \n    D -.- D1[\"`**client.agentSessions.getMessages()**\n    Get UI-ready messages\n    Restore conversation`\"]\n    \n    E -.- E1[\"`Sessions expire after\n    24 hours (configurable)`\"]\n```\n\n## Restoring Sessions\n\nWhen a user returns to your app, restore their session:\n\n```typescript\n// On page load\nconst session = await client.agentSessions.getMessages(sessionId);\n\n// Pass messages to frontend - they're already UI-ready\nreturn {\n  sessionId: session.sessionId,\n  messages: session.messages,  // UIMessage[] with parts\n};\n```\n\nThe `messages` array contains `UIMessage` objects with properly structured `parts`, enabling direct use with the client SDK's `initialMessages` option.\n\n## Error Handling\n\n```typescript\nimport { ApiError } from '@octavus/server-sdk';\n\ntry {\n  const session = await client.agentSessions.getMessages(sessionId);\n} catch (error) {\n  if (error instanceof ApiError) {\n    if (error.status === 404) {\n      // Session not found or expired\n      console.log('Session expired, create a new one');\n    } else {\n      console.error('API Error:', error.message);\n    }\n  }\n  throw error;\n}\n```\n",
         "excerpt": "Sessions Sessions represent conversations with an agent. They store conversation history, track resources and variables, and enable stateful interactions.  Creating Sessions Create a session by...",
         "order": 2
       },
@@ -72,16 +72,16 @@
   {
     "slug": "client-sdk",
     "title": "Client SDK",
-    "description": "Frontend integration with @octavus/client-sdk for React applications.",
+    "description": "Frontend integration with @octavus/react for React applications and @octavus/client-sdk for other frameworks.",
     "order": 3,
     "docs": [
       {
         "slug": "client-sdk/overview",
         "section": "client-sdk",
         "title": "Overview",
-        "description": "Introduction to the Octavus Client SDK for building chat interfaces.",
-        "content": "\n# Client SDK Overview\n\nThe `@octavus/client-sdk` package provides React hooks for building chat interfaces with Octavus agents. It handles streaming, message state, and execution blocks.\n\n**Current version:** `0.0.4`\n\n## Installation\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n## Basic Usage\n\n```tsx\nimport { useOctavusChat } from '@octavus/client-sdk';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const {\n    messages,\n    status,\n    isLoading,\n    streamingText,\n    addUserMessage,\n    triggerAction,\n  } = useOctavusChat({\n    onTrigger: async (triggerName, input) => {\n      return fetch(`/api/chat/${sessionId}/trigger`, {\n        method: 'POST',\n        body: JSON.stringify({ triggerName, input }),\n      });\n    },\n  });\n\n  const sendMessage = async (text: string) => {\n    addUserMessage(text);\n    await triggerAction('user-message', { USER_MESSAGE: text });\n  };\n\n  return (\n    <div>\n      {messages.map((msg) => (\n        <div key={msg.id}>{msg.content}</div>\n      ))}\n      {streamingText && <div>{streamingText}</div>}\n    </div>\n  );\n}\n```\n\n## Key Features\n\n### Real-time Streaming\n\nText streams incrementally as the LLM generates it:\n\n```tsx\nconst { streamingText, streamingParts } = useOctavusChat({...});\n\n// streamingText: Current streaming text\n// streamingParts: Structured parts (text, reasoning, tool calls)\n```\n\n### Message History\n\nMessages are tracked automatically:\n\n```tsx\nconst { messages } = useOctavusChat({...});\n\n// Each message includes:\n// - id: Unique identifier\n// - role: 'user' | 'assistant'\n// - content: Text content\n// - parts: Ordered content parts\n// - toolCalls: Tool call information\n// - reasoning: Extended reasoning (if enabled)\n```\n\n### Execution Blocks\n\nTrack what the agent is doing:\n\n```tsx\nconst { executionBlocks } = useOctavusChat({...});\n\n// Shows active execution steps\n// Useful for progress indicators\n```\n\n### Status Tracking\n\n```tsx\nconst { status, isLoading } = useOctavusChat({...});\n\n// status: 'idle' | 'loading' | 'streaming' | 'error'\n// isLoading: true during loading or streaming\n```\n\n## Hook Reference\n\n### useOctavusChat\n\n```typescript\nfunction useOctavusChat(options: UseOctavusChatOptions): UseOctavusChatReturn;\n\ninterface UseOctavusChatOptions {\n  // Required: Function that calls your backend trigger endpoint\n  onTrigger: TriggerFunction;\n  \n  // Optional: Pre-populate with existing messages (session restore)\n  initialMessages?: Message[];\n  \n  // Optional: Callbacks\n  onMessage?: (message: Message) => void;\n  onError?: (error: Error) => void;\n  onDone?: () => void;\n  onResourceUpdate?: (name: string, value: unknown) => void;\n  onBlockStart?: (block: ExecutionBlock) => void;\n  onBlockEnd?: (block: ExecutionBlock) => void;\n}\n\ninterface UseOctavusChatReturn {\n  // State\n  messages: Message[];\n  status: ChatStatus;\n  isLoading: boolean;\n  error: Error | null;\n  streamingText: string;\n  streamingParts: MessagePart[];\n  executionBlocks: ExecutionBlock[];\n  reasoningText: string;\n  \n  // Actions\n  addUserMessage: (content: string) => void;\n  triggerAction: (triggerName: string, input?: Record<string, unknown>) => Promise<void>;\n}\n```\n\n## Next Steps\n\n- [Messages](/docs/client-sdk/messages) — Working with message state\n- [Streaming](/docs/client-sdk/streaming) — Building streaming UIs\n- [Execution Blocks](/docs/client-sdk/execution-blocks) — Showing agent progress\n",
-        "excerpt": "Client SDK Overview The  package provides React hooks for building chat interfaces with Octavus agents. It handles streaming, message state, and execution blocks. Current version:   Installation ...",
+        "description": "Introduction to the Octavus Client SDKs for building chat interfaces.",
+        "content": "\n# Client SDK Overview\n\nOctavus provides two packages for frontend integration:\n\n| Package | Purpose | Use When |\n|---------|---------|----------|\n| `@octavus/react` | React hooks and bindings | Building React applications |\n| `@octavus/client-sdk` | Framework-agnostic core | Using Vue, Svelte, vanilla JS, or custom integrations |\n\n**Most users should install `@octavus/react`** — it includes everything from `@octavus/client-sdk` plus React-specific hooks.\n\n## Installation\n\n### React Applications\n\n```bash\nnpm install @octavus/react\n```\n\n**Current version:** `0.0.6`\n\n### Other Frameworks\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n**Current version:** `0.0.6`\n\n## React Usage\n\nThe `useOctavusChat` hook provides state management and streaming for React applications:\n\n```tsx\nimport { useOctavusChat, type UIMessage } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const { messages, status, send } = useOctavusChat({\n    onTrigger: async (triggerName, input) => {\n      return fetch(`/api/trigger`, {\n        method: 'POST',\n        body: JSON.stringify({ sessionId, triggerName, input }),\n      });\n    },\n  });\n\n  const sendMessage = async (text: string) => {\n    await send('user-message', { USER_MESSAGE: text }, {\n      userMessage: { content: text },\n    });\n  };\n\n  return (\n    <div>\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => {\n        if (part.type === 'text') {\n          return <p key={i}>{part.text}</p>;\n        }\n        return null;\n      })}\n    </div>\n  );\n}\n```\n\n## Framework-Agnostic Usage\n\nThe `OctavusChat` class can be used with any framework or vanilla JavaScript:\n\n```typescript\nimport { OctavusChat } from '@octavus/client-sdk';\n\nconst chat = new OctavusChat({\n  onTrigger: async (triggerName, input) => {\n    return fetch('/api/trigger', {\n      method: 'POST',\n      body: JSON.stringify({ sessionId, triggerName, input }),\n    });\n  },\n});\n\n// Subscribe to state changes\nconst unsubscribe = chat.subscribe(() => {\n  console.log('Messages:', chat.messages);\n  console.log('Status:', chat.status);\n  // Update your UI here\n});\n\n// Send a message\nawait chat.send('user-message', { USER_MESSAGE: 'Hello' }, {\n  userMessage: { content: 'Hello' },\n});\n\n// Cleanup when done\nunsubscribe();\n```\n\n## Key Features\n\n### Unified Send Function\n\nThe `send` function handles both user message display and agent triggering in one call:\n\n```tsx\nconst { send } = useOctavusChat({...});\n\n// Add user message to UI and trigger agent\nawait send('user-message', { USER_MESSAGE: text }, {\n  userMessage: { content: text },\n});\n\n// Trigger without adding a user message (e.g., button click)\nawait send('request-human');\n```\n\n### Message Parts\n\nMessages contain ordered `parts` for rich content:\n\n```tsx\nconst { messages } = useOctavusChat({...});\n\n// Each message has typed parts\nmessage.parts.map((part) => {\n  switch (part.type) {\n    case 'text':       // Text content\n    case 'reasoning':  // Extended reasoning/thinking\n    case 'tool-call':  // Tool execution\n    case 'operation':  // Internal operations (set-resource, etc.)\n  }\n});\n```\n\n### Status Tracking\n\n```tsx\nconst { status } = useOctavusChat({...});\n\n// status: 'idle' | 'streaming' | 'error'\n```\n\n### Stop Streaming\n\n```tsx\nconst { stop } = useOctavusChat({...});\n\n// Stop current stream and finalize message\nstop();\n```\n\n## Hook Reference (React)\n\n### useOctavusChat\n\n```typescript\nfunction useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;\n\ninterface OctavusChatOptions {\n  // Required: Function that calls your backend trigger endpoint\n  onTrigger: TriggerFunction;\n  \n  // Optional: Pre-populate with existing messages (session restore)\n  initialMessages?: UIMessage[];\n  \n  // Optional: Callbacks\n  onError?: (error: Error) => void;\n  onFinish?: () => void;\n  onResourceUpdate?: (name: string, value: unknown) => void;\n}\n\ninterface UseOctavusChatReturn {\n  // State\n  messages: UIMessage[];\n  status: ChatStatus;  // 'idle' | 'streaming' | 'error'\n  error: Error | null;\n  \n  // Actions\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput }\n  ) => Promise<void>;\n  stop: () => void;\n}\n\ntype TriggerFunction = (\n  triggerName: string,\n  input?: Record<string, unknown>,\n) => Promise<Response>;\n\ninterface UserMessageInput {\n  content: string;\n}\n```\n\n## Class Reference (Framework-Agnostic)\n\n### OctavusChat\n\n```typescript\nclass OctavusChat {\n  constructor(options: OctavusChatOptions);\n  \n  // State (read-only)\n  readonly messages: UIMessage[];\n  readonly status: ChatStatus;\n  readonly error: Error | null;\n  \n  // Actions\n  send(\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput }\n  ): Promise<void>;\n  stop(): void;\n  \n  // Subscription\n  subscribe(callback: () => void): () => void;  // Returns unsubscribe function\n}\n```\n\n## Next Steps\n\n- [Messages](/docs/client-sdk/messages) — Working with message state\n- [Streaming](/docs/client-sdk/streaming) — Building streaming UIs\n- [Execution Blocks](/docs/client-sdk/execution-blocks) — Showing agent progress\n",
+        "excerpt": "Client SDK Overview Octavus provides two packages for frontend integration: | Package | Purpose | Use When | |---------|---------|----------| |  | React hooks and bindings | Building React...",
         "order": 1
       },
       {
@@ -89,8 +89,8 @@
         "section": "client-sdk",
         "title": "Messages",
         "description": "Working with message state in the Client SDK.",
-        "content": "\n# Messages\n\nMessages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content.\n\n## Message Structure\n\n```typescript\ninterface Message {\n  id: string;\n  role: 'user' | 'assistant' | 'system';\n  content: string;\n  parts?: MessagePart[];\n  toolCalls?: ToolCallWithDescription[];\n  reasoning?: string;\n  visible?: boolean;\n  createdAt: Date;\n}\n```\n\n### Message Parts\n\nFor rich content display, use the `parts` array which preserves content ordering:\n\n```typescript\ninterface MessagePart {\n  type: 'text' | 'reasoning' | 'tool-call';\n  visible: boolean;\n  content?: string;      // For text and reasoning\n  toolCall?: ToolCallInfo;  // For tool-call\n  thread?: string;       // For non-main thread content\n}\n```\n\n## Adding User Messages\n\n```tsx\nconst { addUserMessage, triggerAction } = useOctavusChat({...});\n\nasync function sendMessage(text: string) {\n  // 1. Add message to UI immediately\n  addUserMessage(text);\n  \n  // 2. Trigger the agent\n  await triggerAction('user-message', { USER_MESSAGE: text });\n}\n```\n\n**Important**: `addUserMessage` only updates UI state. You must call `triggerAction` to actually send the message to the agent.\n\n## Rendering Messages\n\n### Basic Rendering\n\n```tsx\nfunction MessageList({ messages }: { messages: Message[] }) {\n  return (\n    <div className=\"space-y-4\">\n      {messages.map((msg) => (\n        <div\n          key={msg.id}\n          className={msg.role === 'user' ? 'text-right' : 'text-left'}\n        >\n          <div className=\"inline-block p-3 rounded-lg\">\n            {msg.content}\n          </div>\n        </div>\n      ))}\n    </div>\n  );\n}\n```\n\n### Rich Rendering with Parts\n\nFor messages with tool calls and reasoning, render parts in order:\n\n```tsx\nfunction MessageContent({ message }: { message: Message }) {\n  if (!message.parts) {\n    return <p>{message.content}</p>;\n  }\n\n  return (\n    <div className=\"space-y-2\">\n      {message.parts.map((part, i) => {\n        if (!part.visible) return null;\n\n        switch (part.type) {\n          case 'text':\n            return <p key={i}>{part.content}</p>;\n\n          case 'reasoning':\n            return (\n              <details key={i} className=\"text-gray-500\">\n                <summary>Thinking...</summary>\n                <pre className=\"text-sm\">{part.content}</pre>\n              </details>\n            );\n\n          case 'tool-call':\n            return (\n              <div key={i} className=\"bg-gray-100 p-2 rounded text-sm\">\n                🔧 {part.toolCall?.name}\n                {part.toolCall?.status === 'available' && ' ✓'}\n              </div>\n            );\n\n          default:\n            return null;\n        }\n      })}\n    </div>\n  );\n}\n```\n\n## Tool Calls in Messages\n\nTool calls include status, arguments, and results:\n\n```typescript\ninterface ToolCallInfo {\n  id: string;\n  name: string;\n  description?: string;\n  arguments: Record<string, unknown>;\n  status: 'pending' | 'streaming' | 'available' | 'error';\n  result?: unknown;\n  error?: string;\n}\n```\n\n### Rendering Tool Calls\n\n```tsx\nfunction ToolCallCard({ toolCall }: { toolCall: ToolCallInfo }) {\n  return (\n    <div className=\"border rounded p-3\">\n      <div className=\"flex items-center gap-2\">\n        <span className=\"text-lg\">🔧</span>\n        <span className=\"font-medium\">{toolCall.description || toolCall.name}</span>\n        <StatusBadge status={toolCall.status} />\n      </div>\n      \n      {toolCall.status === 'available' && toolCall.result && (\n        <pre className=\"mt-2 text-xs bg-gray-50 p-2 rounded\">\n          {JSON.stringify(toolCall.result, null, 2)}\n        </pre>\n      )}\n      \n      {toolCall.status === 'error' && (\n        <p className=\"mt-2 text-red-500 text-sm\">{toolCall.error}</p>\n      )}\n    </div>\n  );\n}\n```\n\n## Session Restore\n\nWhen restoring a session, pass existing messages:\n\n```tsx\n// Fetch session state from your backend\nconst sessionState = await fetchSession(sessionId);\n\n// Convert ChatMessage[] to Message[]\nconst initialMessages = sessionState.messages\n  .filter(msg => msg.visible !== false)\n  .map(msg => ({\n    id: msg.id,\n    role: msg.role,\n    content: msg.content,\n    parts: msg.parts,\n    toolCalls: msg.toolCalls,\n    reasoning: msg.reasoning,\n    createdAt: new Date(msg.createdAt),\n  }));\n\n// Pass to hook\nconst { messages } = useOctavusChat({\n  initialMessages,\n  onTrigger: ...\n});\n```\n\n## Message Callbacks\n\nGet notified when messages are added:\n\n```tsx\nuseOctavusChat({\n  onTrigger: ...,\n  onMessage: (message) => {\n    console.log('New message:', message.role, message.content);\n    \n    // Analytics, logging, etc.\n    trackMessage(message);\n  },\n});\n```\n",
-        "excerpt": "Messages Messages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content.  Message Structure  Message Parts For rich content...",
+        "content": "\n# Messages\n\nMessages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content through typed parts.\n\n## Message Structure\n\n```typescript\ninterface UIMessage {\n  id: string;\n  role: 'user' | 'assistant';\n  parts: UIMessagePart[];\n  status: 'streaming' | 'done';\n  createdAt: Date;\n}\n```\n\n### Message Parts\n\nMessages contain ordered `parts` that preserve content ordering:\n\n```typescript\ntype UIMessagePart = \n  | UITextPart \n  | UIReasoningPart \n  | UIToolCallPart \n  | UIOperationPart;\n\n// Text content\ninterface UITextPart {\n  type: 'text';\n  text: string;\n  status: 'streaming' | 'done';\n  thread?: string;  // For named threads (e.g., \"summary\")\n}\n\n// Extended reasoning/thinking\ninterface UIReasoningPart {\n  type: 'reasoning';\n  text: string;\n  status: 'streaming' | 'done';\n  thread?: string;\n}\n\n// Tool execution\ninterface UIToolCallPart {\n  type: 'tool-call';\n  toolCallId: string;\n  toolName: string;\n  displayName?: string;  // Human-readable name\n  args: Record<string, unknown>;\n  result?: unknown;\n  error?: string;\n  status: 'pending' | 'running' | 'done' | 'error';\n  thread?: string;\n}\n\n// Internal operations (set-resource, serialize-thread)\ninterface UIOperationPart {\n  type: 'operation';\n  operationId: string;\n  name: string;\n  operationType: string;\n  status: 'running' | 'done';\n  thread?: string;\n}\n```\n\n## Sending Messages\n\n```tsx\nconst { send } = useOctavusChat({...});\n\nasync function handleSend(text: string) {\n  // Add user message to UI and trigger agent\n  await send('user-message', { USER_MESSAGE: text }, {\n    userMessage: { content: text },\n  });\n}\n```\n\nThe `send` function:\n1. Adds the user message to the UI immediately (if `userMessage` is provided)\n2. Triggers the agent with the specified trigger name and input\n3. Streams the assistant's response back\n\n## Rendering Messages\n\n### Basic Rendering\n\n```tsx\nfunction MessageList({ messages }: { messages: UIMessage[] }) {\n  return (\n    <div className=\"space-y-4\">\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n    </div>\n  );\n}\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  const isUser = message.role === 'user';\n\n  return (\n    <div className={isUser ? 'text-right' : 'text-left'}>\n      <div className=\"inline-block p-3 rounded-lg\">\n        {message.parts.map((part, i) => (\n          <PartRenderer key={i} part={part} />\n        ))}\n      </div>\n    </div>\n  );\n}\n```\n\n### Rendering Parts\n\n```tsx\nimport { isOtherThread, type UIMessagePart } from '@octavus/react';\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  // Check if part belongs to a named thread (e.g., \"summary\")\n  if (isOtherThread(part)) {\n    return <OtherThreadPart part={part} />;\n  }\n\n  switch (part.type) {\n    case 'text':\n      return <TextPart part={part} />;\n\n    case 'reasoning':\n      return (\n        <details className=\"text-gray-500\">\n          <summary>Thinking...</summary>\n          <pre className=\"text-sm\">{part.text}</pre>\n        </details>\n      );\n\n    case 'tool-call':\n      return (\n        <div className=\"bg-gray-100 p-2 rounded text-sm\">\n          🔧 {part.displayName || part.toolName}\n          {part.status === 'done' && ' ✓'}\n          {part.status === 'error' && ` ✗ ${part.error}`}\n        </div>\n      );\n\n    case 'operation':\n      return (\n        <div className=\"text-gray-500 text-sm\">\n          {part.name}\n          {part.status === 'done' && ' ✓'}\n        </div>\n      );\n\n    default:\n      return null;\n  }\n}\n\nfunction TextPart({ part }: { part: UITextPart }) {\n  return (\n    <p>\n      {part.text}\n      {part.status === 'streaming' && (\n        <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n      )}\n    </p>\n  );\n}\n```\n\n## Named Threads\n\nContent from named threads (like \"summary\") is identified by the `thread` property. Use the `isOtherThread` helper:\n\n```tsx\nimport { isOtherThread } from '@octavus/react';\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  if (isOtherThread(part)) {\n    // Render differently for named threads\n    return (\n      <div className=\"bg-amber-50 p-2 rounded border border-amber-200\">\n        <span className=\"text-amber-600 text-sm\">\n          {part.thread}: {part.type === 'text' && part.text}\n        </span>\n      </div>\n    );\n  }\n\n  // Regular rendering for main thread\n  // ...\n}\n```\n\n## Session Restore\n\nWhen restoring a session, pass existing messages:\n\n```tsx\n// Fetch session state from your backend\nconst sessionState = await fetchSession(sessionId);\n\n// Pass to hook\nconst { messages } = useOctavusChat({\n  initialMessages: sessionState.messages,\n  onTrigger: ...\n});\n```\n\n## Callbacks\n\n```tsx\nuseOctavusChat({\n  onTrigger: ...,\n  onFinish: () => {\n    console.log('Stream completed');\n    // Scroll to bottom, play sound, etc.\n  },\n  onError: (error) => {\n    console.error('Error:', error);\n    toast.error('Failed to get response');\n  },\n  onResourceUpdate: (name, value) => {\n    console.log('Resource updated:', name, value);\n  },\n});\n```\n",
+        "excerpt": "Messages Messages represent the conversation history. The Client SDK tracks messages automatically and provides structured access to their content through typed parts.  Message Structure  Message...",
         "order": 2
       },
       {
@@ -98,17 +98,17 @@
         "section": "client-sdk",
         "title": "Streaming",
         "description": "Building streaming UIs with the Client SDK.",
-        "content": "\n# Streaming\n\nThe Client SDK provides real-time access to streaming content, enabling responsive UIs that update as the agent generates responses.\n\n## Streaming State\n\n```tsx\nconst {\n  streamingText,     // Current visible text being streamed\n  streamingParts,    // Structured parts being streamed\n  reasoningText,     // Current reasoning content\n  status,            // 'idle' | 'loading' | 'streaming' | 'error'\n  isLoading,         // true during loading or streaming\n} = useOctavusChat({...});\n```\n\n## Basic Streaming UI\n\n```tsx\nfunction Chat() {\n  const { messages, streamingText, isLoading } = useOctavusChat({...});\n\n  return (\n    <div>\n      {/* Completed messages */}\n      {messages.map((msg) => (\n        <div key={msg.id}>{msg.content}</div>\n      ))}\n\n      {/* Currently streaming */}\n      {streamingText && (\n        <div className=\"animate-pulse\">\n          {streamingText}\n          <span className=\"inline-block w-2 h-4 bg-gray-400 ml-1\" />\n        </div>\n      )}\n    </div>\n  );\n}\n```\n\n## Streaming Parts\n\nFor rich streaming UIs, use `streamingParts`:\n\n```tsx\nfunction StreamingContent() {\n  const { streamingParts } = useOctavusChat({...});\n\n  return (\n    <div>\n      {streamingParts.map((part, i) => {\n        switch (part.type) {\n          case 'text':\n            return <span key={i}>{part.content}</span>;\n\n          case 'reasoning':\n            return (\n              <div key={i} className=\"text-gray-500 italic\">\n                💭 {part.content}\n              </div>\n            );\n\n          case 'tool-call':\n            return (\n              <div key={i} className=\"flex items-center gap-2\">\n                <Spinner />\n                <span>{part.toolCall?.description}</span>\n              </div>\n            );\n        }\n      })}\n    </div>\n  );\n}\n```\n\n## Reasoning Indicator\n\nShow when the model is using extended reasoning:\n\n```tsx\nfunction ReasoningIndicator() {\n  const { reasoningText, status } = useOctavusChat({...});\n\n  if (!reasoningText || status !== 'streaming') {\n    return null;\n  }\n\n  return (\n    <div className=\"bg-purple-50 p-3 rounded-lg\">\n      <div className=\"flex items-center gap-2 text-purple-600\">\n        <Brain className=\"w-4 h-4 animate-pulse\" />\n        <span className=\"font-medium\">Thinking...</span>\n      </div>\n      <p className=\"mt-2 text-sm text-gray-600 line-clamp-3\">\n        {reasoningText}\n      </p>\n    </div>\n  );\n}\n```\n\n## Status Indicator\n\n```tsx\nfunction StatusIndicator() {\n  const { status } = useOctavusChat({...});\n\n  switch (status) {\n    case 'idle':\n      return null;\n    case 'loading':\n      return <div>Starting...</div>;\n    case 'streaming':\n      return <div>Agent is responding...</div>;\n    case 'error':\n      return <div className=\"text-red-500\">Something went wrong</div>;\n  }\n}\n```\n\n## Handling Stream Completion\n\n```tsx\nuseOctavusChat({\n  onTrigger: ...,\n  onDone: () => {\n    console.log('Stream completed');\n    // Scroll to bottom, play sound, etc.\n  },\n  onError: (error) => {\n    console.error('Stream error:', error);\n    toast.error('Failed to get response');\n  },\n});\n```\n\n## Streaming with Tool Calls\n\nWhen tools are called, streaming continues after tool execution:\n\n```\n1. User sends message\n2. streamingText starts filling: \"Let me look that up...\"\n3. Tool call starts (visible in streamingParts)\n4. Tool executes (handled by server-sdk)\n5. streamingText continues: \"I found your account...\"\n6. Stream completes, message finalized\n```\n\n```tsx\nfunction ChatWithTools() {\n  const { messages, streamingText, streamingParts } = useOctavusChat({...});\n\n  // Find active tool call\n  const activeToolCall = streamingParts.find(\n    p => p.type === 'tool-call' && p.toolCall?.status === 'streaming'\n  );\n\n  return (\n    <div>\n      {messages.map(msg => <Message key={msg.id} message={msg} />)}\n\n      {/* Show streaming text */}\n      {streamingText && <p>{streamingText}</p>}\n\n      {/* Show active tool */}\n      {activeToolCall && (\n        <div className=\"flex items-center gap-2 text-blue-600\">\n          <Spinner />\n          {activeToolCall.toolCall?.description}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n\n## Non-Main Thread Content\n\nNamed threads (like summarization) stream separately:\n\n```tsx\nfunction StreamingContent() {\n  const { streamingParts } = useOctavusChat({...});\n\n  // Group by thread\n  const mainParts = streamingParts.filter(p => !p.thread || p.thread === 'main');\n  const otherParts = streamingParts.filter(p => p.thread && p.thread !== 'main');\n\n  return (\n    <div>\n      {/* Main conversation */}\n      <div>{mainParts.map(renderPart)}</div>\n\n      {/* Named thread (e.g., summarization) */}\n      {otherParts.length > 0 && (\n        <div className=\"bg-orange-50 p-3 rounded mt-4\">\n          <div className=\"text-orange-600 font-medium\">\n            Processing in background...\n          </div>\n          {otherParts.map(renderPart)}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n",
-        "excerpt": "Streaming The Client SDK provides real-time access to streaming content, enabling responsive UIs that update as the agent generates responses.  Streaming State  Basic Streaming UI  Streaming Parts...",
+        "content": "\n# Streaming\n\nThe Client SDK provides real-time access to streaming content through the message `parts` array. Each part has its own status, enabling responsive UIs that update as the agent generates responses.\n\n## Streaming State\n\n```tsx\nconst { messages, status, error } = useOctavusChat({...});\n\n// status: 'idle' | 'streaming' | 'error'\n// Each message has status: 'streaming' | 'done'\n// Each part has its own status too\n```\n\n## Building a Streaming UI\n\n```tsx\nfunction Chat() {\n  const { messages, status, error, send, stop } = useOctavusChat({...});\n\n  return (\n    <div>\n      {/* Messages with streaming parts */}\n      {messages.map((msg) => (\n        <MessageBubble key={msg.id} message={msg} />\n      ))}\n\n      {/* Error state */}\n      {error && (\n        <div className=\"text-red-500\">{error.message}</div>\n      )}\n\n      {/* Stop button during streaming */}\n      {status === 'streaming' && (\n        <button onClick={stop}>Stop</button>\n      )}\n    </div>\n  );\n}\n```\n\n## Rendering Streaming Parts\n\nParts update in real-time during streaming. Use the part's `status` to show appropriate UI:\n\n```tsx\nimport type { UITextPart, UIReasoningPart } from '@octavus/react';\n\nfunction TextPart({ part }: { part: UITextPart }) {\n  return (\n    <div>\n      {part.text}\n      {part.status === 'streaming' && (\n        <span className=\"inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1\" />\n      )}\n    </div>\n  );\n}\n\nfunction ReasoningPart({ part }: { part: UIReasoningPart }) {\n  // Expand while streaming, collapse when done\n  const [expanded, setExpanded] = useState(part.status === 'streaming');\n\n  return (\n    <div className=\"bg-purple-50 p-3 rounded-lg\">\n      <button onClick={() => setExpanded(!expanded)}>\n        {part.status === 'streaming' ? '💭 Thinking...' : '💭 Thought process'}\n        {expanded ? '▼' : '▶'}\n      </button>\n      \n      {expanded && (\n        <pre className=\"mt-2 text-sm text-gray-600\">\n          {part.text}\n        </pre>\n      )}\n    </div>\n  );\n}\n```\n\n## Tool Call States\n\nTool calls progress through multiple states:\n\n```tsx\nimport type { UIToolCallPart } from '@octavus/react';\n\nfunction ToolCallPart({ part }: { part: UIToolCallPart }) {\n  return (\n    <div className=\"border rounded p-3\">\n      <div className=\"flex items-center gap-2\">\n        <span className=\"text-lg\">🔧</span>\n        <span className=\"font-medium\">\n          {part.displayName || part.toolName}\n        </span>\n        <StatusBadge status={part.status} />\n      </div>\n      \n      {/* Show result when done */}\n      {part.status === 'done' && part.result && (\n        <pre className=\"mt-2 text-xs bg-gray-50 p-2 rounded\">\n          {JSON.stringify(part.result, null, 2)}\n        </pre>\n      )}\n      \n      {/* Show error if failed */}\n      {part.status === 'error' && (\n        <p className=\"mt-2 text-red-500 text-sm\">{part.error}</p>\n      )}\n    </div>\n  );\n}\n\nfunction StatusBadge({ status }: { status: UIToolCallPart['status'] }) {\n  switch (status) {\n    case 'pending':\n      return <span className=\"text-gray-400\">○</span>;\n    case 'running':\n      return <span className=\"text-blue-500 animate-spin\">◐</span>;\n    case 'done':\n      return <span className=\"text-green-500\">✓</span>;\n    case 'error':\n      return <span className=\"text-red-500\">✗</span>;\n  }\n}\n```\n\n## Status Indicator\n\n```tsx\nfunction StatusIndicator() {\n  const { status } = useOctavusChat({...});\n\n  switch (status) {\n    case 'idle':\n      return null;\n    case 'streaming':\n      return <div>Agent is responding...</div>;\n    case 'error':\n      return <div className=\"text-red-500\">Something went wrong</div>;\n  }\n}\n```\n\n## Handling Completion\n\n```tsx\nuseOctavusChat({\n  onTrigger: ...,\n  onFinish: () => {\n    console.log('Stream completed');\n    // Scroll to bottom, play sound, etc.\n  },\n  onError: (error) => {\n    console.error('Stream error:', error);\n    toast.error('Failed to get response');\n  },\n});\n```\n\n## Stop Function\n\nStop the current stream and finalize any partial message:\n\n```tsx\nconst { status, stop } = useOctavusChat({...});\n\n// Stop button\n{status === 'streaming' && (\n  <button onClick={stop} className=\"text-gray-500\">\n    Stop generating\n  </button>\n)}\n```\n\nWhen `stop()` is called:\n1. The current request is aborted\n2. Any partial message is finalized with current content\n3. Status changes to `'idle'`\n\n## Named Thread Content\n\nContent from named threads (like \"summary\") streams separately and is identified by the `thread` property:\n\n```tsx\nimport { isOtherThread } from '@octavus/react';\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  // Separate main thread from named threads\n  const mainParts = message.parts.filter(p => !isOtherThread(p));\n  const otherParts = message.parts.filter(p => isOtherThread(p));\n\n  return (\n    <div>\n      {/* Main conversation */}\n      {mainParts.map((part, i) => <PartRenderer key={i} part={part} />)}\n\n      {/* Named thread content (e.g., summarization) */}\n      {otherParts.length > 0 && (\n        <div className=\"bg-amber-50 p-3 rounded mt-4 border border-amber-200\">\n          <div className=\"text-amber-600 font-medium mb-2\">\n            Background processing\n          </div>\n          {otherParts.map((part, i) => <PartRenderer key={i} part={part} />)}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n",
+        "excerpt": "Streaming The Client SDK provides real-time access to streaming content through the message  array. Each part has its own status, enabling responsive UIs that update as the agent generates responses....",
         "order": 3
       },
       {
         "slug": "client-sdk/execution-blocks",
         "section": "client-sdk",
-        "title": "Execution Blocks",
-        "description": "Tracking agent execution progress with the Client SDK.",
-        "content": "\n# Execution Blocks\n\nExecution blocks let you show users what the agent is doing. Each block represents a step in the agent's execution flow.\n\n## Block Structure\n\n```typescript\ninterface ExecutionBlock {\n  id: string;\n  name: string;           // Human-readable name from protocol\n  type: string;           // Block type (next-message, tool-call, etc.)\n  status: BlockStatus;    // pending | running | completed | error\n  display: DisplayMode;   // hidden | name | description | stream\n  description?: string;\n  outputToChat: boolean;  // Whether output goes to main chat\n  thread?: string;        // For named threads\n  streamingText: string;  // Current streaming content\n  reasoning?: string;     // Extended reasoning content\n  toolCalls: ToolCallWithDescription[];\n  startedAt: Date;\n  completedAt?: Date;\n}\n```\n\n## Accessing Blocks\n\n```tsx\nconst { executionBlocks, onBlockStart, onBlockEnd } = useOctavusChat({\n  onTrigger: ...,\n  onBlockStart: (block) => {\n    console.log('Block started:', block.name);\n  },\n  onBlockEnd: (block) => {\n    console.log('Block completed:', block.name, block.status);\n  },\n});\n```\n\n## Showing Execution Progress\n\n```tsx\nfunction ExecutionProgress() {\n  const { executionBlocks, status } = useOctavusChat({...});\n\n  if (status !== 'streaming' || executionBlocks.length === 0) {\n    return null;\n  }\n\n  return (\n    <div className=\"space-y-2\">\n      {executionBlocks.map((block) => (\n        <ExecutionBlockCard key={block.id} block={block} />\n      ))}\n    </div>\n  );\n}\n\nfunction ExecutionBlockCard({ block }: { block: ExecutionBlock }) {\n  return (\n    <div className=\"border rounded p-3\">\n      <div className=\"flex items-center gap-2\">\n        <BlockStatusIcon status={block.status} />\n        <span className=\"font-medium\">{block.name}</span>\n      </div>\n\n      {block.description && (\n        <p className=\"text-sm text-gray-500 mt-1\">{block.description}</p>\n      )}\n\n      {/* Show streaming content for stream display mode */}\n      {block.display === 'stream' && block.streamingText && (\n        <div className=\"mt-2 text-sm\">\n          {block.streamingText}\n        </div>\n      )}\n\n      {/* Show tool calls */}\n      {block.toolCalls.length > 0 && (\n        <div className=\"mt-2 space-y-1\">\n          {block.toolCalls.map((tc) => (\n            <div key={tc.id} className=\"text-sm flex items-center gap-1\">\n              🔧 {tc.description || tc.name}\n              {tc.status === 'available' && ' ✓'}\n              {tc.status === 'error' && ' ✗'}\n            </div>\n          ))}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n\n## Display Modes\n\nBlocks have different display modes that control visibility:\n\n| Mode | Description | UI Recommendation |\n|------|-------------|-------------------|\n| `hidden` | Not shown to user | Don't render |\n| `name` | Shows block name | Show name only |\n| `description` | Shows description | Show name + description |\n| `stream` | Streams content | Show full streaming content |\n\n```tsx\nfunction ExecutionBlockCard({ block }: { block: ExecutionBlock }) {\n  // Hidden blocks aren't sent to client, but check just in case\n  if (block.display === 'hidden') {\n    return null;\n  }\n\n  return (\n    <div className=\"border rounded p-3\">\n      {/* Always show name */}\n      <div className=\"font-medium\">{block.name}</div>\n\n      {/* Show description if display mode is description or stream */}\n      {(block.display === 'description' || block.display === 'stream') && \n        block.description && (\n          <p className=\"text-sm text-gray-500\">{block.description}</p>\n        )}\n\n      {/* Show content if display mode is stream */}\n      {block.display === 'stream' && (\n        <div className=\"mt-2\">\n          {block.streamingText}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n\n## Named Threads\n\nBlocks can belong to named threads (like \"summary\"). Use the `thread` property:\n\n```tsx\nfunction ExecutionProgress() {\n  const { executionBlocks } = useOctavusChat({...});\n\n  // Group by thread\n  const mainBlocks = executionBlocks.filter(b => !b.thread || b.thread === 'main');\n  const namedThreads = new Map<string, ExecutionBlock[]>();\n\n  executionBlocks.forEach(b => {\n    if (b.thread && b.thread !== 'main') {\n      if (!namedThreads.has(b.thread)) {\n        namedThreads.set(b.thread, []);\n      }\n      namedThreads.get(b.thread)!.push(b);\n    }\n  });\n\n  return (\n    <div>\n      {/* Main execution */}\n      <div className=\"space-y-2\">\n        {mainBlocks.map(b => <BlockCard key={b.id} block={b} />)}\n      </div>\n\n      {/* Named threads */}\n      {Array.from(namedThreads.entries()).map(([thread, blocks]) => (\n        <div key={thread} className=\"mt-4 bg-orange-50 p-3 rounded\">\n          <div className=\"text-orange-600 font-medium mb-2\">\n            Thread: {thread}\n          </div>\n          {blocks.map(b => <BlockCard key={b.id} block={b} />)}\n        </div>\n      ))}\n    </div>\n  );\n}\n```\n\n## Block Status Icons\n\n```tsx\nfunction BlockStatusIcon({ status }: { status: BlockStatus }) {\n  switch (status) {\n    case 'pending':\n      return <Circle className=\"w-4 h-4 text-gray-400\" />;\n    case 'running':\n      return <Loader className=\"w-4 h-4 text-blue-500 animate-spin\" />;\n    case 'completed':\n      return <CheckCircle className=\"w-4 h-4 text-green-500\" />;\n    case 'error':\n      return <XCircle className=\"w-4 h-4 text-red-500\" />;\n  }\n}\n```\n\n## Example: Support Chat with Escalation\n\nWhen a user clicks \"Talk to Human\", the agent runs multiple blocks:\n\n```tsx\nfunction SupportChatProgress() {\n  const { executionBlocks } = useOctavusChat({...});\n\n  // Show blocks while streaming\n  return (\n    <div className=\"space-y-2\">\n      {executionBlocks.map((block) => (\n        <div key={block.id} className=\"flex items-center gap-2\">\n          <BlockStatusIcon status={block.status} />\n          <span>{getBlockLabel(block)}</span>\n        </div>\n      ))}\n    </div>\n  );\n}\n\nfunction getBlockLabel(block: ExecutionBlock): string {\n  // Use description if available, otherwise name\n  return block.description || block.name;\n}\n\n// Example output during escalation:\n// ✓ Serialize conversation\n// ✓ Start summary thread\n// ● Summarizing your conversation (streaming...)\n// ○ Creating a support ticket\n// ○ Respond with ticket info\n```\n",
-        "excerpt": "Execution Blocks Execution blocks let you show users what the agent is doing. Each block represents a step in the agent's execution flow.  Block Structure  Accessing Blocks  Showing Execution...",
+        "title": "Operations",
+        "description": "Showing agent operations and progress with the Client SDK.",
+        "content": "\n# Operations\n\nOperations 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.\n\n## Operation Structure\n\n```typescript\ninterface UIOperationPart {\n  type: 'operation';\n  operationId: string;\n  name: string;           // Human-readable name\n  operationType: string;  // e.g., 'set-resource', 'serialize-thread'\n  status: 'running' | 'done';\n  thread?: string;        // For named threads\n}\n```\n\n## Rendering Operations\n\nOperations are typically shown as compact status indicators:\n\n```tsx\nimport type { UIOperationPart } from '@octavus/react';\n\nfunction OperationCard({ operation }: { operation: UIOperationPart }) {\n  return (\n    <div className=\"flex items-center gap-2 text-sm text-gray-500\">\n      {operation.status === 'running' ? (\n        <span className=\"h-2 w-2 animate-pulse rounded-full bg-blue-500\" />\n      ) : (\n        <span className=\"text-green-500\">✓</span>\n      )}\n      <span>{operation.name}</span>\n    </div>\n  );\n}\n```\n\n## Operations in Messages\n\nOperations appear alongside text, reasoning, and tool calls in the message's `parts` array:\n\n```tsx\nimport type { UIMessage, UIMessagePart } from '@octavus/react';\n\nfunction MessageBubble({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => (\n        <PartRenderer key={i} part={part} />\n      ))}\n    </div>\n  );\n}\n\nfunction PartRenderer({ part }: { part: UIMessagePart }) {\n  switch (part.type) {\n    case 'text':\n      return <TextPart part={part} />;\n    case 'reasoning':\n      return <ReasoningPart part={part} />;\n    case 'tool-call':\n      return <ToolCallCard part={part} />;\n    case 'operation':\n      return <OperationCard operation={part} />;\n    default:\n      return null;\n  }\n}\n```\n\n## Common Operation Types\n\n| Type | Description |\n|------|-------------|\n| `set-resource` | Updating a resource value |\n| `serialize-thread` | Converting thread messages to text |\n\n## Example: Progress During Escalation\n\nWhen a user clicks \"Talk to Human\", multiple operations may occur:\n\n```tsx\nfunction EscalationProgress({ message }: { message: UIMessage }) {\n  const operations = message.parts.filter(\n    (p): p is UIOperationPart => p.type === 'operation'\n  );\n\n  return (\n    <div className=\"space-y-2\">\n      {operations.map((op) => (\n        <div key={op.operationId} className=\"flex items-center gap-2 text-sm\">\n          {op.status === 'running' ? '⏳' : '✓'}\n          <span>{op.name}</span>\n        </div>\n      ))}\n    </div>\n  );\n}\n\n// Example output during escalation:\n// ✓ Serialize conversation\n// ✓ Save conversation summary\n// ⏳ Creating support ticket...\n```\n\n## Display Modes\n\nOperations 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.\n\nThis means you can safely render all operations without checking display mode — hidden ones won't be in the message parts.\n\n## Named Thread Operations\n\nOperations can belong to named threads. Use the `thread` property to identify them:\n\n```tsx\nfunction OperationCard({ operation }: { operation: UIOperationPart }) {\n  return (\n    <div className=\"flex items-center gap-2 text-sm\">\n      {operation.thread && (\n        <span className=\"text-amber-500\">[{operation.thread}]</span>\n      )}\n      <span>{operation.name}</span>\n      {operation.status === 'done' && <span className=\"text-green-500\">✓</span>}\n    </div>\n  );\n}\n```\n",
+        "excerpt": "Operations Operations represent internal agent activities like setting resources or serializing threads. They appear as  parts in messages and help users understand what the agent is doing. ...",
         "order": 4
       }
     ]
@@ -124,7 +124,7 @@
         "section": "protocol",
         "title": "Overview",
         "description": "Introduction to Octavus agent protocols.",
-        "content": "\n# Protocol Overview\n\nAgent protocols define how an AI agent behaves. They're written in YAML and specify inputs, triggers, tools, and execution handlers.\n\n## Why Protocols?\n\nProtocols provide:\n\n- **Declarative definition** — Define behavior, not implementation\n- **Portable agents** — Move agents between projects\n- **Versioning** — Track changes with git\n- **Validation** — Catch errors before runtime\n- **Visualization** — Debug execution flows\n\n## Protocol Structure\n\n```yaml\n# Agent inputs (provided when creating a session)\ninput:\n  COMPANY_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\n# Persistent resources the agent can read/write\nresources:\n  CONVERSATION_SUMMARY:\n    description: Summary for handoff\n    default: \"\"\n\n# How the agent can be invoked\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n  request-human:\n    description: User clicks \"Talk to Human\"\n\n# Temporary variables for execution (with types)\nvariables:\n  SUMMARY:\n    type: string\n  TICKET:\n    type: unknown\n\n# Tools the agent can use\ntools:\n  get-user-account:\n    description: Looking up your account\n    parameters:\n      userId: { type: string }\n    returns:\n      name: { type: string }\n      email: { type: string }\n\n# Agent configuration (model, tools, etc.)\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system            # References prompts/system.md\n  tools: [get-user-account]\n  agentic: true             # Allow multiple tool calls\n  thinking: medium          # Extended reasoning\n\n# What happens when triggers fire\nhandlers:\n  user-message:\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n    \n    Respond to user:\n      type: next-message\n```\n\n## File Structure\n\nEach agent is a folder with:\n\n```\nmy-agent/\n├── protocol.yaml           # Main logic (required)\n├── settings.json           # Agent metadata (required)\n└── prompts/               # Prompt templates\n    ├── system.md\n    ├── user-message.md\n    └── escalation-summary.md\n```\n\n### settings.json\n\n```json\n{\n  \"slug\": \"my-agent\",\n  \"name\": \"My Agent\",\n  \"description\": \"What this agent does\",\n  \"format\": \"interactive\"\n}\n```\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `slug` | Yes | URL-safe identifier (lowercase, digits, dashes) |\n| `name` | Yes | Human-readable name |\n| `description` | No | Brief description |\n| `format` | Yes | `interactive` (chat) or `generation` (background) |\n\n## Naming Conventions\n\n- **Slugs**: `lowercase-with-dashes`\n- **Variables**: `UPPERCASE_SNAKE_CASE`\n- **Prompts**: `lowercase-with-dashes.md`\n- **Tools**: `lowercase-with-dashes`\n- **Triggers**: `lowercase-with-dashes`\n\n## Variables in Prompts\n\nReference variables with `{{VARIABLE_NAME}}`:\n\n```markdown\n<!-- prompts/system.md -->\nYou are a support agent for {{COMPANY_NAME}}.\n\nHelp users with their {{PRODUCT_NAME}} questions.\n\n## Support Policies\n\n{{SUPPORT_POLICIES}}\n```\n\nVariables are replaced with their values at runtime. If a variable is not provided, it's replaced with an empty string.\n\n## Next Steps\n\n- [Input & Resources](/docs/protocol/input-resources) — Defining agent inputs\n- [Triggers](/docs/protocol/triggers) — How agents are invoked\n- [Tools](/docs/protocol/tools) — External capabilities\n- [Handlers](/docs/protocol/handlers) — Execution blocks\n- [Agent Config](/docs/protocol/agent-config) — Model and settings\n\n",
+        "content": "\n# Protocol Overview\n\nAgent protocols define how an AI agent behaves. They're written in YAML and specify inputs, triggers, tools, and execution handlers.\n\n## Why Protocols?\n\nProtocols provide:\n\n- **Declarative definition** — Define behavior, not implementation\n- **Portable agents** — Move agents between projects\n- **Versioning** — Track changes with git\n- **Validation** — Catch errors before runtime\n- **Visualization** — Debug execution flows\n\n## Protocol Structure\n\n```yaml\n# Agent inputs (provided when creating a session)\ninput:\n  COMPANY_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\n# Persistent resources the agent can read/write\nresources:\n  CONVERSATION_SUMMARY:\n    description: Summary for handoff\n    default: \"\"\n\n# How the agent can be invoked\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n  request-human:\n    description: User clicks \"Talk to Human\"\n\n# Temporary variables for execution (with types)\nvariables:\n  SUMMARY:\n    type: string\n  TICKET:\n    type: unknown\n\n# Tools the agent can use\ntools:\n  get-user-account:\n    description: Looking up your account\n    parameters:\n      userId: { type: string }\n\n# Agent configuration (model, tools, etc.)\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system            # References prompts/system.md\n  tools: [get-user-account]\n  agentic: true             # Allow multiple tool calls\n  thinking: medium          # Extended reasoning\n\n# What happens when triggers fire\nhandlers:\n  user-message:\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n    \n    Respond to user:\n      type: next-message\n```\n\n## File Structure\n\nEach agent is a folder with:\n\n```\nmy-agent/\n├── protocol.yaml           # Main logic (required)\n├── settings.json           # Agent metadata (required)\n└── prompts/               # Prompt templates\n    ├── system.md\n    ├── user-message.md\n    └── escalation-summary.md\n```\n\n### settings.json\n\n```json\n{\n  \"slug\": \"my-agent\",\n  \"name\": \"My Agent\",\n  \"description\": \"What this agent does\",\n  \"format\": \"interactive\"\n}\n```\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `slug` | Yes | URL-safe identifier (lowercase, digits, dashes) |\n| `name` | Yes | Human-readable name |\n| `description` | No | Brief description |\n| `format` | Yes | `interactive` (chat) or `generation` (background) |\n\n## Naming Conventions\n\n- **Slugs**: `lowercase-with-dashes`\n- **Variables**: `UPPERCASE_SNAKE_CASE`\n- **Prompts**: `lowercase-with-dashes.md`\n- **Tools**: `lowercase-with-dashes`\n- **Triggers**: `lowercase-with-dashes`\n\n## Variables in Prompts\n\nReference variables with `{{VARIABLE_NAME}}`:\n\n```markdown\n<!-- prompts/system.md -->\nYou are a support agent for {{COMPANY_NAME}}.\n\nHelp users with their {{PRODUCT_NAME}} questions.\n\n## Support Policies\n\n{{SUPPORT_POLICIES}}\n```\n\nVariables are replaced with their values at runtime. If a variable is not provided, it's replaced with an empty string.\n\n## Next Steps\n\n- [Input & Resources](/docs/protocol/input-resources) — Defining agent inputs\n- [Triggers](/docs/protocol/triggers) — How agents are invoked\n- [Tools](/docs/protocol/tools) — External capabilities\n- [Handlers](/docs/protocol/handlers) — Execution blocks\n- [Agent Config](/docs/protocol/agent-config) — Model and settings\n\n",
         "excerpt": "Protocol Overview Agent protocols define how an AI agent behaves. They're written in YAML and specify inputs, triggers, tools, and execution handlers.  Why Protocols? Protocols provide: - Declarative...",
         "order": 1
       },
@@ -133,7 +133,7 @@
         "section": "protocol",
         "title": "Input & Resources",
         "description": "Defining agent inputs and persistent resources.",
-        "content": "\n# Input & Resources\n\nInputs are provided when creating a session. Resources are persistent state the agent can read and write.\n\n## Input Variables\n\nDefine inputs that consumers must (or may) provide:\n\n```yaml\ninput:\n  # Required input\n  COMPANY_NAME:\n    type: string\n    description: The company name to use in responses\n\n  # Required input with description\n  PRODUCT_NAME:\n    type: string\n    description: Product being supported\n\n  # Optional input (defaults to \"NONE\")\n  SUPPORT_POLICIES:\n    type: string\n    description: Company policies for support\n    optional: true\n\n  # Optional input with custom default\n  USER_ID:\n    type: string\n    description: Current user's ID\n    optional: true\n    default: \"\"\n```\n\n### Input Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this input is for |\n| `optional` | No | If true, consumer doesn't have to provide it |\n| `default` | No | Default value if not provided (defaults to `\"NONE\"`) |\n\n### Using Inputs\n\nWhen creating a session, pass input values:\n\n```typescript\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n  SUPPORT_POLICIES: 'Refunds within 30 days...',\n  // USER_ID is optional, not provided\n});\n```\n\nIn prompts, reference with `{{INPUT_NAME}}`:\n\n```markdown\nYou are a support agent for {{COMPANY_NAME}}.\n```\n\n## Resources\n\nResources are persistent state that:\n- Survive across triggers\n- Can be read and written by the agent\n- Are synced to the consumer's application\n\n```yaml\nresources:\n  # String resource with default\n  CONVERSATION_SUMMARY:\n    type: string\n    description: Running summary of the conversation\n    default: \"\"\n\n  # Resource with unknown type (for complex data)\n  USER_CONTEXT:\n    type: unknown\n    description: Cached user information\n    default: {}\n\n  # Read-only resource (agent can read but not write)\n  SYSTEM_CONFIG:\n    type: unknown\n    description: System configuration\n    readonly: true\n    default:\n      maxRetries: 3\n      timeout: 30000\n```\n\n### Resource Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes the resource purpose |\n| `default` | No | Initial value |\n| `readonly` | No | If true, agent cannot write to it |\n\n### Writing Resources\n\nUse the `set-resource` block in handlers:\n\n```yaml\nhandlers:\n  request-human:\n    # ... generate summary ...\n    \n    Save summary:\n      type: set-resource\n      resource: CONVERSATION_SUMMARY\n      value: SUMMARY  # Variable containing the value\n```\n\n### Resource Events\n\nWhen a resource is updated, the client SDK receives a `resource-update` event:\n\n```typescript\nuseOctavusChat({\n  onResourceUpdate: (name, value) => {\n    if (name === 'CONVERSATION_SUMMARY') {\n      console.log('Summary updated:', value);\n    }\n  },\n});\n```\n\n## Variables\n\nVariables are internal state managed by block outputs. They persist across triggers but are not synced to the consumer (unlike resources).\n\n```yaml\nvariables:\n  SUMMARY:\n    type: string\n    description: Generated summary text\n  TICKET:\n    type: unknown\n    description: Ticket creation result\n  CONVERSATION_TEXT:\n    type: string\n    description: Serialized conversation\n```\n\n### Variable Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this variable stores |\n| `default` | No | Initial value |\n\n### Using Variables\n\nSet variables as output from blocks:\n\n```yaml\nhandlers:\n  request-human:\n    Serialize conversation:\n      type: serialize-thread\n      format: markdown\n      output: CONVERSATION_TEXT  # Stores result in variable\n    \n    Generate summary:\n      type: next-message\n      output: SUMMARY  # LLM output stored in variable\n    \n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY  # Use variable as input\n      output: TICKET\n```\n\n## Scoping\n\n| Type | Scope | Persistence | Synced to Consumer |\n|------|-------|-------------|---------------------|\n| `input` | Session | Immutable | Yes (at creation) |\n| `resources` | Session | Persists across triggers | Yes (via callbacks) |\n| `variables` | Session | Persists across triggers | No (internal only) |\n\n",
+        "content": "\n# Input & Resources\n\nInputs are provided when creating a session. Resources are persistent state the agent can read and write.\n\n## Input Variables\n\nDefine inputs that consumers must (or may) provide:\n\n```yaml\ninput:\n  # Required input\n  COMPANY_NAME:\n    type: string\n    description: The company name to use in responses\n\n  # Required input with description\n  PRODUCT_NAME:\n    type: string\n    description: Product being supported\n\n  # Optional input (defaults to \"NONE\")\n  SUPPORT_POLICIES:\n    type: string\n    description: Company policies for support\n    optional: true\n\n  # Optional input with custom default\n  USER_ID:\n    type: string\n    description: Current user's ID\n    optional: true\n    default: \"\"\n```\n\n### Input Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this input is for |\n| `optional` | No | If true, consumer doesn't have to provide it |\n| `default` | No | Default value if not provided (defaults to `\"NONE\"`) |\n\n### Using Inputs\n\nWhen creating a session, pass input values:\n\n```typescript\nconst sessionId = await client.agentSessions.create('support-chat', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n  SUPPORT_POLICIES: 'Refunds within 30 days...',\n  // USER_ID is optional, not provided\n});\n```\n\nIn prompts, reference with `{{INPUT_NAME}}`:\n\n```markdown\nYou are a support agent for {{COMPANY_NAME}}.\n```\n\n> **Note:** Variables must be `UPPER_SNAKE_CASE`. Nested properties (dot notation like `{{VAR.property}}`) are not supported. Objects are serialized as JSON when interpolated.\n\n## Resources\n\nResources are persistent state that:\n- Survive across triggers\n- Can be read and written by the agent\n- Are synced to the consumer's application\n\n```yaml\nresources:\n  # String resource with default\n  CONVERSATION_SUMMARY:\n    type: string\n    description: Running summary of the conversation\n    default: \"\"\n\n  # Resource with unknown type (for complex data)\n  USER_CONTEXT:\n    type: unknown\n    description: Cached user information\n    default: {}\n\n  # Read-only resource (agent can read but not write)\n  SYSTEM_CONFIG:\n    type: unknown\n    description: System configuration\n    readonly: true\n    default:\n      maxRetries: 3\n      timeout: 30000\n```\n\n### Resource Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes the resource purpose |\n| `default` | No | Initial value |\n| `readonly` | No | If true, agent cannot write to it |\n\n### Writing Resources\n\nUse the `set-resource` block in handlers:\n\n```yaml\nhandlers:\n  request-human:\n    # ... generate summary ...\n    \n    Save summary:\n      type: set-resource\n      resource: CONVERSATION_SUMMARY\n      value: SUMMARY  # Variable containing the value\n```\n\n### Resource Events\n\nWhen a resource is updated, the client SDK receives a `resource-update` event:\n\n```typescript\nuseOctavusChat({\n  onResourceUpdate: (name, value) => {\n    if (name === 'CONVERSATION_SUMMARY') {\n      console.log('Summary updated:', value);\n    }\n  },\n});\n```\n\n## Variables\n\nVariables are internal state managed by block outputs. They persist across triggers but are not synced to the consumer (unlike resources).\n\n```yaml\nvariables:\n  SUMMARY:\n    type: string\n    description: Generated summary text\n  TICKET:\n    type: unknown\n    description: Ticket creation result\n  CONVERSATION_TEXT:\n    type: string\n    description: Serialized conversation\n```\n\n### Variable Definition\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this variable stores |\n| `default` | No | Initial value |\n\n### Using Variables\n\nSet variables as output from blocks:\n\n```yaml\nhandlers:\n  request-human:\n    Serialize conversation:\n      type: serialize-thread\n      format: markdown\n      output: CONVERSATION_TEXT  # Stores result in variable\n    \n    Generate summary:\n      type: next-message\n      output: SUMMARY  # LLM output stored in variable\n    \n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY  # Use variable as input\n      output: TICKET\n```\n\n## Scoping\n\n| Type | Scope | Persistence | Synced to Consumer |\n|------|-------|-------------|---------------------|\n| `input` | Session | Immutable | Yes (at creation) |\n| `resources` | Session | Persists across triggers | Yes (via callbacks) |\n| `variables` | Session | Persists across triggers | No (internal only) |\n\n",
         "excerpt": "Input & Resources Inputs are provided when creating a session. Resources are persistent state the agent can read and write.  Input Variables Define inputs that consumers must (or may) provide:  Input...",
         "order": 2
       },
@@ -142,7 +142,7 @@
         "section": "protocol",
         "title": "Triggers",
         "description": "Defining how agents are invoked.",
-        "content": "\n# Triggers\n\nTriggers define how an agent can be invoked. Each trigger has a name, optional inputs, and a corresponding handler.\n\n## Trigger Types\n\n### User Message\n\nThe most common trigger — when a user sends a chat message:\n\n```yaml\ntriggers:\n  user-message:\n    description: User sends a chat message\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n```\n\n### User Action\n\nFor UI interactions like button clicks:\n\n```yaml\ntriggers:\n  request-human:\n    description: User clicks \"Talk to Human\" button\n    # No input needed - action is implicit\n  \n  submit-feedback:\n    description: User submits feedback form\n    input:\n      RATING:\n        type: number\n        description: Rating from 1-5\n      COMMENT:\n        type: string\n        description: Optional comment\n        optional: true\n```\n\n### API Trigger\n\nDirect invocation through the SDK:\n\n```yaml\ntriggers:\n  analyze-document:\n    description: Analyze an uploaded document\n    input:\n      DOCUMENT_URL:\n        type: string\n      ANALYSIS_TYPE:\n        type: string\n        description: Type of analysis (summary, sentiment, extraction)\n```\n\n## Trigger Definition\n\n```yaml\ntriggers:\n  trigger-name:\n    description: Optional description\n    input:\n      VARIABLE_NAME:\n        type: string | number | boolean | unknown\n        description: What this input is for\n        optional: true | false  # defaults to false\n        default: value  # default if optional and not provided\n```\n\n## Invoking Triggers\n\n### From Client SDK\n\n```typescript\n// User message trigger\nawait triggerAction('user-message', { \n  USER_MESSAGE: 'How do I reset my password?' \n});\n\n// User action trigger (no input)\nawait triggerAction('request-human');\n\n// Action with input\nawait triggerAction('submit-feedback', { \n  RATING: 5, \n  COMMENT: 'Great help!' \n});\n```\n\n### From Server SDK\n\n```typescript\nconst { stream } = session.trigger('user-message', { \n  USER_MESSAGE: 'Help me with billing' \n});\n\nconst { stream } = session.trigger('request-human');\n```\n\n## Handlers\n\nEach trigger must have a corresponding handler:\n\n```yaml\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\n  request-human:\n    description: Escalate to human support\n\nhandlers:\n  user-message:\n    # Blocks executed when user-message is triggered\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n    \n    Respond:\n      type: next-message\n\n  request-human:\n    # Blocks executed when request-human is triggered\n    Summarize:\n      type: serialize-thread\n      # ...\n```\n\n## Trigger Input Naming\n\nTrigger inputs use `UPPERCASE_SNAKE_CASE`:\n\n```yaml\ntriggers:\n  search-products:\n    input:\n      SEARCH_QUERY: { type: string }\n      MAX_RESULTS: { type: number, optional: true, default: 10 }\n      FILTER_CATEGORY: { type: string, optional: true }\n```\n\n## Best Practices\n\n### 1. Use Descriptive Names\n\n```yaml\n# Good\ntriggers:\n  user-message:       # Clear - user sends chat message\n  request-human:      # Clear - wants human support\n  cancel-subscription: # Clear - specific action\n\n# Avoid\ntriggers:\n  trigger1:           # Unclear\n  msg:                # Too abbreviated\n  do-thing:           # Vague\n```\n\n### 2. Document Triggers\n\n```yaml\ntriggers:\n  escalate-to-tier2:\n    description: >\n      Escalate the conversation to tier 2 support.\n      Should be called when the issue cannot be resolved\n      at tier 1 level.\n    input:\n      REASON:\n        type: string\n        description: Why escalation is needed\n```\n\n### 3. Keep Triggers Focused\n\nEach trigger should do one thing:\n\n```yaml\n# Good - focused triggers\ntriggers:\n  send-message:\n    input: { MESSAGE: { type: string } }\n  \n  upload-file:\n    input: { FILE_URL: { type: string } }\n  \n  request-callback:\n    input: { PHONE: { type: string } }\n\n# Avoid - overloaded trigger\ntriggers:\n  user-action:\n    input:\n      ACTION_TYPE: { type: string }  # \"message\" | \"file\" | \"callback\"\n      PAYLOAD: { type: unknown }     # Different structure per type\n```\n\n",
+        "content": "\n# Triggers\n\nTriggers define how an agent can be invoked. Each trigger has a name, optional inputs, and a corresponding handler.\n\n## Trigger Types\n\n### User Message\n\nThe most common trigger — when a user sends a chat message:\n\n```yaml\ntriggers:\n  user-message:\n    description: User sends a chat message\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n```\n\n### User Action\n\nFor UI interactions like button clicks:\n\n```yaml\ntriggers:\n  request-human:\n    description: User clicks \"Talk to Human\" button\n    # No input needed - action is implicit\n  \n  submit-feedback:\n    description: User submits feedback form\n    input:\n      RATING:\n        type: number\n        description: Rating from 1-5\n      COMMENT:\n        type: string\n        description: Optional comment\n        optional: true\n```\n\n### API Trigger\n\nDirect invocation through the SDK:\n\n```yaml\ntriggers:\n  analyze-document:\n    description: Analyze an uploaded document\n    input:\n      DOCUMENT_URL:\n        type: string\n      ANALYSIS_TYPE:\n        type: string\n        description: Type of analysis (summary, sentiment, extraction)\n```\n\n## Trigger Definition\n\n```yaml\ntriggers:\n  trigger-name:\n    description: Optional description\n    input:\n      VARIABLE_NAME:\n        type: string | number | boolean | unknown\n        description: What this input is for\n        optional: true | false  # defaults to false\n        default: value  # default if optional and not provided\n```\n\n## Invoking Triggers\n\n### From Client SDK\n\n```typescript\nconst { send } = useOctavusChat({...});\n\n// User message trigger with UI message\nawait send('user-message', { USER_MESSAGE: text }, {\n  userMessage: { content: text },\n});\n\n// User action trigger (no input, no UI message)\nawait send('request-human');\n\n// Action with input\nawait send('submit-feedback', { RATING: 5, COMMENT: 'Great help!' });\n```\n\n### From Server SDK\n\n```typescript\nconst { stream } = session.trigger('user-message', { \n  USER_MESSAGE: 'Help me with billing' \n});\n\nconst { stream } = session.trigger('request-human');\n```\n\n## Handlers\n\nEach trigger must have a corresponding handler:\n\n```yaml\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\n  request-human:\n    description: Escalate to human support\n\nhandlers:\n  user-message:\n    # Blocks executed when user-message is triggered\n    Add user message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n    \n    Respond:\n      type: next-message\n\n  request-human:\n    # Blocks executed when request-human is triggered\n    Summarize:\n      type: serialize-thread\n      # ...\n```\n\n## Trigger Input Naming\n\nTrigger inputs use `UPPERCASE_SNAKE_CASE`:\n\n```yaml\ntriggers:\n  search-products:\n    input:\n      SEARCH_QUERY: { type: string }\n      MAX_RESULTS: { type: number, optional: true, default: 10 }\n      FILTER_CATEGORY: { type: string, optional: true }\n```\n\n## Best Practices\n\n### 1. Use Descriptive Names\n\n```yaml\n# Good\ntriggers:\n  user-message:       # Clear - user sends chat message\n  request-human:      # Clear - wants human support\n  cancel-subscription: # Clear - specific action\n\n# Avoid\ntriggers:\n  trigger1:           # Unclear\n  msg:                # Too abbreviated\n  do-thing:           # Vague\n```\n\n### 2. Document Triggers\n\n```yaml\ntriggers:\n  escalate-to-tier2:\n    description: >\n      Escalate the conversation to tier 2 support.\n      Should be called when the issue cannot be resolved\n      at tier 1 level.\n    input:\n      REASON:\n        type: string\n        description: Why escalation is needed\n```\n\n### 3. Keep Triggers Focused\n\nEach trigger should do one thing:\n\n```yaml\n# Good - focused triggers\ntriggers:\n  send-message:\n    input: { MESSAGE: { type: string } }\n  \n  upload-file:\n    input: { FILE_URL: { type: string } }\n  \n  request-callback:\n    input: { PHONE: { type: string } }\n\n# Avoid - overloaded trigger\ntriggers:\n  user-action:\n    input:\n      ACTION_TYPE: { type: string }  # \"message\" | \"file\" | \"callback\"\n      PAYLOAD: { type: unknown }     # Different structure per type\n```\n\n",
         "excerpt": "Triggers Triggers define how an agent can be invoked. Each trigger has a name, optional inputs, and a corresponding handler.  Trigger Types  User Message The most common trigger — when a user sends a...",
         "order": 3
       },
@@ -151,7 +151,7 @@
         "section": "protocol",
         "title": "Tools",
         "description": "Defining external tools agents can use.",
-        "content": "\n# Tools\n\nTools extend what agents can do. They're defined in the protocol and implemented in your backend.\n\n## Tool Definition\n\n```yaml\ntools:\n  get-user-account:\n    description: Looking up your account information\n    display: description\n    parameters:\n      userId:\n        type: string\n        description: The user ID to look up\n    returns:\n      name: { type: string }\n      email: { type: string }\n      plan: { type: string }\n      createdAt: { type: string }\n```\n\n### Tool Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `description` | Yes | What the tool does (shown to LLM and optionally user) |\n| `display` | No | How to show in UI: `hidden`, `name`, `description`, `stream` |\n| `parameters` | No | Input parameters the tool accepts |\n| `required` | No | List of required parameter names |\n| `returns` | No | Schema of the return value (for documentation) |\n\n### Display Modes\n\n| Mode | Behavior |\n|------|----------|\n| `hidden` | Tool runs silently, user doesn't see it |\n| `name` | Shows tool name while executing |\n| `description` | Shows description while executing (default) |\n| `stream` | Streams tool progress if available |\n\n## Parameter Types\n\nSupported types: `string`, `number`, `boolean`, `unknown`\n\n```yaml\ntools:\n  search-products:\n    description: Search the product catalog\n    parameters:\n      query:\n        type: string\n        description: Search query\n      \n      category:\n        type: string\n        description: Filter by category (electronics, clothing, books, home)\n      \n      maxPrice:\n        type: number\n        description: Maximum price filter\n      \n      inStock:\n        type: boolean\n        description: Only show in-stock items\n```\n\n## Making Tools Available\n\nTools defined in `tools:` are available. To make them usable by the LLM, add them to `agent.tools`:\n\n```yaml\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n  \n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string }  # low, medium, high, urgent\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools:\n    - get-user-account\n    - create-support-ticket  # LLM can decide when to call these\n  agentic: true\n```\n\n## Tool Invocation Modes\n\n### LLM-Decided (Agentic)\n\nThe LLM decides when to call tools based on the conversation:\n\n```yaml\nagent:\n  tools: [get-user-account, create-support-ticket]\n  agentic: true  # Allow multiple tool calls\n  maxSteps: 10   # Max tool call cycles\n```\n\n### Deterministic (Block-Based)\n\nForce tool calls at specific points in the handler:\n\n```yaml\nhandlers:\n  request-human:\n    # Always create a ticket when escalating\n    Create support ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY  # From variable\n        priority: medium  # Literal value\n      output: TICKET      # Store result\n```\n\n## Tool Results\n\n### In Prompts\n\nReference tool results in prompts:\n\n```markdown\n<!-- prompts/ticket-directive.md -->\nA support ticket has been created:\n- Ticket ID: {{TICKET.ticketId}}\n- Estimated Response: {{TICKET.estimatedResponse}}\n\nLet the user know their ticket has been created.\n```\n\n### In Variables\n\nStore tool results for later use:\n\n```yaml\nhandlers:\n  request-human:\n    Get account:\n      type: tool-call\n      tool: get-user-account\n      input:\n        userId: USER_ID\n      output: ACCOUNT  # Result stored here\n    \n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY\n        priority: medium\n        # Can reference ACCOUNT here\n        email: ACCOUNT.email\n      output: TICKET\n```\n\n## Implementing Tools\n\nTools are implemented in your backend:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      const userId = args.userId as string;\n      const user = await db.users.findById(userId);\n      \n      return {\n        name: user.name,\n        email: user.email,\n        plan: user.subscription.plan,\n        createdAt: user.createdAt.toISOString(),\n      };\n    },\n    \n    'create-support-ticket': async (args) => {\n      const ticket = await ticketService.create({\n        summary: args.summary as string,\n        priority: args.priority as string,\n      });\n      \n      return {\n        ticketId: ticket.id,\n        estimatedResponse: getEstimatedTime(args.priority),\n      };\n    },\n  },\n});\n```\n\n## Tool Best Practices\n\n### 1. Clear Descriptions\n\n```yaml\ntools:\n  # Good - clear and specific\n  get-user-account:\n    description: >\n      Retrieves the user's account information including name, email,\n      subscription plan, and account creation date. Use this when the\n      user asks about their account or you need to verify their identity.\n  \n  # Avoid - vague\n  get-data:\n    description: Gets some data\n```\n\n### 2. Define Expected Returns\n\n```yaml\ntools:\n  search-products:\n    description: Search products\n    parameters:\n      query: { type: string }\n    returns:\n      products:\n        type: unknown\n        description: Array of product objects\n      totalCount:\n        type: number\n```\n\n### 3. Document Constrained Values\n\n```yaml\ntools:\n  create-support-ticket:\n    parameters:\n      priority:\n        type: string\n        description: Ticket priority level (low, medium, high, urgent)\n```\n\n",
+        "content": "\n# Tools\n\nTools extend what agents can do. They're defined in the protocol and implemented in your backend.\n\n## Tool Definition\n\n```yaml\ntools:\n  get-user-account:\n    description: Looking up your account information\n    display: description\n    parameters:\n      userId:\n        type: string\n        description: The user ID to look up\n```\n\n### Tool Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `description` | Yes | What the tool does (shown to LLM and optionally user) |\n| `display` | No | How to show in UI: `hidden`, `name`, `description`, `stream` |\n| `parameters` | No | Input parameters the tool accepts |\n\n### Display Modes\n\n| Mode | Behavior |\n|------|----------|\n| `hidden` | Tool runs silently, user doesn't see it |\n| `name` | Shows tool name while executing |\n| `description` | Shows description while executing (default) |\n| `stream` | Streams tool progress if available |\n\n## Parameters\n\n### Parameter Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |\n| `description` | No | Describes what this parameter is for |\n| `optional` | No | If true, parameter is not required (default: false) |\n\n### Optional Parameters\n\nParameters are **required by default**. Use `optional: true` to make a parameter optional:\n\n```yaml\ntools:\n  search-products:\n    description: Search the product catalog\n    parameters:\n      query:\n        type: string\n        description: Search query\n      \n      category:\n        type: string\n        description: Filter by category\n        optional: true\n      \n      maxPrice:\n        type: number\n        description: Maximum price filter\n        optional: true\n      \n      inStock:\n        type: boolean\n        description: Only show in-stock items\n        optional: true\n```\n\n## Making Tools Available\n\nTools defined in `tools:` are available. To make them usable by the LLM, add them to `agent.tools`:\n\n```yaml\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n  \n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string }  # low, medium, high, urgent\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools:\n    - get-user-account\n    - create-support-ticket  # LLM can decide when to call these\n  agentic: true\n```\n\n## Tool Invocation Modes\n\n### LLM-Decided (Agentic)\n\nThe LLM decides when to call tools based on the conversation:\n\n```yaml\nagent:\n  tools: [get-user-account, create-support-ticket]\n  agentic: true  # Allow multiple tool calls\n  maxSteps: 10   # Max tool call cycles\n```\n\n### Deterministic (Block-Based)\n\nForce tool calls at specific points in the handler:\n\n```yaml\nhandlers:\n  request-human:\n    # Always create a ticket when escalating\n    Create support ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY  # From variable\n        priority: medium  # Literal value\n      output: TICKET      # Store result\n```\n\n## Tool Results\n\n### In Prompts\n\nReference tool results in prompts:\n\n```markdown\n<!-- prompts/ticket-directive.md -->\nA support ticket has been created:\n- Ticket ID: {{TICKET.ticketId}}\n- Estimated Response: {{TICKET.estimatedResponse}}\n\nLet the user know their ticket has been created.\n```\n\n### In Variables\n\nStore tool results for later use:\n\n```yaml\nhandlers:\n  request-human:\n    Get account:\n      type: tool-call\n      tool: get-user-account\n      input:\n        userId: USER_ID\n      output: ACCOUNT  # Result stored here\n    \n    Create ticket:\n      type: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY\n        priority: medium\n        # Can reference ACCOUNT here\n        email: ACCOUNT.email\n      output: TICKET\n```\n\n## Implementing Tools\n\nTools are implemented in your backend:\n\n```typescript\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'get-user-account': async (args) => {\n      const userId = args.userId as string;\n      const user = await db.users.findById(userId);\n      \n      return {\n        name: user.name,\n        email: user.email,\n        plan: user.subscription.plan,\n        createdAt: user.createdAt.toISOString(),\n      };\n    },\n    \n    'create-support-ticket': async (args) => {\n      const ticket = await ticketService.create({\n        summary: args.summary as string,\n        priority: args.priority as string,\n      });\n      \n      return {\n        ticketId: ticket.id,\n        estimatedResponse: getEstimatedTime(args.priority),\n      };\n    },\n  },\n});\n```\n\n## Tool Best Practices\n\n### 1. Clear Descriptions\n\n```yaml\ntools:\n  # Good - clear and specific\n  get-user-account:\n    description: >\n      Retrieves the user's account information including name, email,\n      subscription plan, and account creation date. Use this when the\n      user asks about their account or you need to verify their identity.\n  \n  # Avoid - vague\n  get-data:\n    description: Gets some data\n```\n\n### 2. Document Constrained Values\n\n```yaml\ntools:\n  create-support-ticket:\n    parameters:\n      priority:\n        type: string\n        description: Ticket priority level (low, medium, high, urgent)\n```\n\n",
         "excerpt": "Tools Tools extend what agents can do. They're defined in the protocol and implemented in your backend.  Tool Definition  Tool Fields | Field | Required | Description |...",
         "order": 4
       },
@@ -169,7 +169,7 @@
         "section": "protocol",
         "title": "Agent Config",
         "description": "Configuring the agent model and behavior.",
-        "content": "\n# Agent Config\n\nThe `agent` section configures the LLM model, system prompt, tools, and behavior.\n\n## Basic Configuration\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system              # References prompts/system.md\n  tools: [get-user-account]   # Available tools\n```\n\n## Configuration Options\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `model` | Yes | Model identifier (provider/model-id) |\n| `system` | Yes | System prompt filename (without .md) |\n| `input` | No | Variables to interpolate in system prompt |\n| `tools` | No | List of tools the LLM can call |\n| `agentic` | No | Allow multiple tool call cycles |\n| `maxSteps` | No | Maximum agentic steps (default: 10) |\n| `temperature` | No | Model temperature (0-2) |\n| `thinking` | No | Extended reasoning level |\n\n## Models\n\nSpecify models in `provider/model-id` format:\n\n```yaml\n# Anthropic\nagent:\n  model: anthropic/claude-sonnet-4-5   # Claude 4.5 Sonnet\n  model: anthropic/claude-opus-4       # Claude 4 Opus\n\n# OpenAI\nagent:\n  model: openai/gpt-4o                 # GPT-4o\n  model: openai/gpt-4o-mini            # GPT-4o Mini\n  model: openai/o1                     # O1\n  model: openai/o3-mini                # O3 Mini\n```\n\n## System Prompt\n\nThe system prompt sets the agent's persona and instructions:\n\n```yaml\nagent:\n  system: system  # Uses prompts/system.md\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n    - SUPPORT_POLICIES\n```\n\nExample `prompts/system.md`:\n\n```markdown\nYou are a friendly support agent for {{COMPANY_NAME}}.\n\n## Your Role\n\nHelp users with questions about {{PRODUCT_NAME}}.\n\n## Guidelines\n\n- Be helpful and professional\n- If you can't help, offer to escalate\n- Never share internal information\n\n{{#if SUPPORT_POLICIES}}\n## Support Policies\n\n{{SUPPORT_POLICIES}}\n{{/if}}\n```\n\n## Agentic Mode\n\nEnable multi-step tool calling:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools: [get-user-account, search-docs, create-ticket]\n  agentic: true    # LLM can call multiple tools\n  maxSteps: 10     # Limit cycles to prevent runaway\n```\n\n**How it works:**\n1. LLM receives user message\n2. LLM decides to call a tool\n3. Tool executes, result returned to LLM\n4. LLM decides if more tools needed\n5. Repeat until LLM responds or maxSteps reached\n\n## Extended Thinking\n\nEnable extended reasoning for complex tasks:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  thinking: medium  # low | medium | high\n```\n\n| Level | Token Budget | Use Case |\n|-------|-------------|----------|\n| `low` | ~5,000 | Simple reasoning |\n| `medium` | ~10,000 | Moderate complexity |\n| `high` | ~20,000 | Complex analysis |\n\nThinking content streams to the UI and can be displayed to users.\n\n## Temperature\n\nControl response randomness:\n\n```yaml\nagent:\n  model: openai/gpt-4o\n  temperature: 0.7  # 0 = deterministic, 2 = creative\n```\n\n**Guidelines:**\n- `0 - 0.3`: Factual, consistent responses\n- `0.4 - 0.7`: Balanced (good default)\n- `0.8 - 1.2`: Creative, varied responses\n- `> 1.2`: Very creative (may be inconsistent)\n\n## Thread-Specific Config\n\nOverride config for named threads:\n\n```yaml\nhandlers:\n  request-human:\n    Start summary thread:\n      type: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5  # Different model\n      thinking: low                        # Different thinking\n      maxSteps: 1                          # Limit tool calls\n      system: escalation-summary           # Different prompt\n```\n\n## Full Example\n\n```yaml\ninput:\n  COMPANY_NAME: { type: string }\n  PRODUCT_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\nresources:\n  CONVERSATION_SUMMARY:\n    type: string\n    default: \"\"\n\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n  \n  search-docs:\n    description: Search help documentation\n    parameters:\n      query: { type: string }\n  \n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string }  # low, medium, high\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n  tools:\n    - get-user-account\n    - search-docs\n    - create-support-ticket\n  agentic: true\n  maxSteps: 10\n  thinking: medium\n\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\nhandlers:\n  user-message:\n    Add message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n    \n    Respond:\n      type: next-message\n```\n\n",
+        "content": "\n# Agent Config\n\nThe `agent` section configures the LLM model, system prompt, tools, and behavior.\n\n## Basic Configuration\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system              # References prompts/system.md\n  tools: [get-user-account]   # Available tools\n```\n\n## Configuration Options\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `model` | Yes | Model identifier (provider/model-id) |\n| `system` | Yes | System prompt filename (without .md) |\n| `input` | No | Variables to interpolate in system prompt |\n| `tools` | No | List of tools the LLM can call |\n| `agentic` | No | Allow multiple tool call cycles |\n| `maxSteps` | No | Maximum agentic steps (default: 10) |\n| `temperature` | No | Model temperature (0-2) |\n| `thinking` | No | Extended reasoning level |\n\n## Models\n\nSpecify models in `provider/model-id` format:\n\n```yaml\n# Anthropic\nagent:\n  model: anthropic/claude-sonnet-4-5   # Claude 4.5 Sonnet\n  model: anthropic/claude-opus-4       # Claude 4 Opus\n\n# OpenAI\nagent:\n  model: openai/gpt-4o                 # GPT-4o\n  model: openai/gpt-4o-mini            # GPT-4o Mini\n  model: openai/o1                     # O1\n  model: openai/o3-mini                # O3 Mini\n```\n\n## System Prompt\n\nThe system prompt sets the agent's persona and instructions:\n\n```yaml\nagent:\n  system: system  # Uses prompts/system.md\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n```\n\nExample `prompts/system.md`:\n\n```markdown\nYou are a friendly support agent for {{COMPANY_NAME}}.\n\n## Your Role\n\nHelp users with questions about {{PRODUCT_NAME}}.\n\n## Guidelines\n\n- Be helpful and professional\n- If you can't help, offer to escalate\n- Never share internal information\n```\n\n## Agentic Mode\n\nEnable multi-step tool calling:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools: [get-user-account, search-docs, create-ticket]\n  agentic: true    # LLM can call multiple tools\n  maxSteps: 10     # Limit cycles to prevent runaway\n```\n\n**How it works:**\n1. LLM receives user message\n2. LLM decides to call a tool\n3. Tool executes, result returned to LLM\n4. LLM decides if more tools needed\n5. Repeat until LLM responds or maxSteps reached\n\n## Extended Thinking\n\nEnable extended reasoning for complex tasks:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  thinking: medium  # low | medium | high\n```\n\n| Level | Token Budget | Use Case |\n|-------|-------------|----------|\n| `low` | ~5,000 | Simple reasoning |\n| `medium` | ~10,000 | Moderate complexity |\n| `high` | ~20,000 | Complex analysis |\n\nThinking content streams to the UI and can be displayed to users.\n\n## Temperature\n\nControl response randomness:\n\n```yaml\nagent:\n  model: openai/gpt-4o\n  temperature: 0.7  # 0 = deterministic, 2 = creative\n```\n\n**Guidelines:**\n- `0 - 0.3`: Factual, consistent responses\n- `0.4 - 0.7`: Balanced (good default)\n- `0.8 - 1.2`: Creative, varied responses\n- `> 1.2`: Very creative (may be inconsistent)\n\n## Thread-Specific Config\n\nOverride config for named threads:\n\n```yaml\nhandlers:\n  request-human:\n    Start summary thread:\n      type: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5  # Different model\n      thinking: low                        # Different thinking\n      maxSteps: 1                          # Limit tool calls\n      system: escalation-summary           # Different prompt\n```\n\n## Full Example\n\n```yaml\ninput:\n  COMPANY_NAME: { type: string }\n  PRODUCT_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\nresources:\n  CONVERSATION_SUMMARY:\n    type: string\n    default: \"\"\n\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n  \n  search-docs:\n    description: Search help documentation\n    parameters:\n      query: { type: string }\n  \n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string }  # low, medium, high\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n  tools:\n    - get-user-account\n    - search-docs\n    - create-support-ticket\n  agentic: true\n  maxSteps: 10\n  thinking: medium\n\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\nhandlers:\n  user-message:\n    Add message:\n      type: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n    \n    Respond:\n      type: next-message\n```\n\n",
         "excerpt": "Agent Config The  section configures the LLM model, system prompt, tools, and behavior.  Basic Configuration  Configuration Options | Field | Required | Description |...",
         "order": 6
       }
@@ -195,7 +195,7 @@
         "section": "api-reference",
         "title": "Sessions",
         "description": "Session management API endpoints.",
-        "content": "\n# Sessions API\n\nSessions represent conversations with agents. They store conversation history, resources, and variables.\n\n## Create Session\n\nCreate a new agent session.\n\n```\nPOST /api/agent-sessions\n```\n\n### Request Body\n\n```json\n{\n  \"agentId\": \"cm5xvz7k80001abcd\",\n  \"input\": {\n    \"COMPANY_NAME\": \"Acme Corp\",\n    \"PRODUCT_NAME\": \"Widget Pro\",\n    \"USER_ID\": \"user-123\"\n  }\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `agentId` | string | Yes | Agent ID (the `id` field, not `slug`) |\n| `input` | object | No | Input variables for the agent |\n\n> To get the agent ID, copy it from the platform URL, use [Get Agent by slug](/docs/api-reference/agents#get-agent) (`GET /api/agents/:slug?by=slug`), or the SDK's `agents.getBySlug()` method.\n\n### Response\n\n```json\n{\n  \"sessionId\": \"cm5xyz123abc456def\"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"agentId\": \"cm5xvz7k80001abcd\",\n    \"input\": {\n      \"COMPANY_NAME\": \"Acme Corp\",\n      \"PRODUCT_NAME\": \"Widget Pro\"\n    }\n  }'\n```\n\n## Get Session\n\nRetrieve session state including messages and resources.\n\n```\nGET /api/agent-sessions/:sessionId\n```\n\n### Response\n\n```json\n{\n  \"id\": \"cm5xyz123abc456def\",\n  \"agentId\": \"cm5xvz7k80001abcd\",\n  \"input\": {\n    \"COMPANY_NAME\": \"Acme Corp\",\n    \"PRODUCT_NAME\": \"Widget Pro\"\n  },\n  \"variables\": {},\n  \"resources\": {\n    \"CONVERSATION_SUMMARY\": \"\"\n  },\n  \"messages\": [\n    {\n      \"id\": \"1702345800000-xyz789a\",\n      \"role\": \"user\",\n      \"parts\": [\n        { \"type\": \"text\", \"visible\": true, \"content\": \"How do I reset my password?\" }\n      ],\n      \"content\": \"How do I reset my password?\",\n      \"createdAt\": \"2024-01-15T10:30:00Z\"\n    },\n    {\n      \"id\": \"1702345805000-def456b\",\n      \"role\": \"assistant\",\n      \"parts\": [\n        { \"type\": \"text\", \"visible\": true, \"content\": \"I can help you reset your password...\" }\n      ],\n      \"content\": \"I can help you reset your password...\",\n      \"createdAt\": \"2024-01-15T10:30:05Z\"\n    }\n  ],\n  \"createdAt\": \"2024-01-15T10:30:00Z\",\n  \"updatedAt\": \"2024-01-15T10:30:05Z\"\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agent-sessions/:sessionId \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n## Trigger Session\n\nExecute a trigger on a session. Returns a Server-Sent Events stream.\n\n```\nPOST /api/agent-sessions/:sessionId/trigger\n```\n\n### Request Body\n\n```json\n{\n  \"triggerName\": \"user-message\",\n  \"input\": {\n    \"USER_MESSAGE\": \"How do I reset my password?\"\n  },\n  \"toolResults\": []\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `triggerName` | string | Yes | Name of the trigger to execute |\n| `input` | object | No | Input variables for the trigger |\n| `toolResults` | array | No | Tool results for continuation (handled by SDK) |\n\n### Response\n\nReturns `text/event-stream` with SSE events:\n\n```\ndata: {\"type\":\"start\",\"messageId\":\"msg-123\"}\n\ndata: {\"type\":\"block-start\",\"blockId\":\"b1\",\"blockName\":\"Add user message\",\"blockType\":\"add-message\",\"display\":\"hidden\"}\n\ndata: {\"type\":\"block-end\",\"blockId\":\"b1\"}\n\ndata: {\"type\":\"block-start\",\"blockId\":\"b2\",\"blockName\":\"Respond to user\",\"blockType\":\"next-message\",\"display\":\"stream\",\"outputToChat\":true}\n\ndata: {\"type\":\"text-start\",\"id\":\"t1\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\"I\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" can\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" help\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" you\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" reset\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" your\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" password\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\"!\"}\n\ndata: {\"type\":\"text-end\",\"id\":\"t1\"}\n\ndata: {\"type\":\"block-end\",\"blockId\":\"b2\"}\n\ndata: {\"type\":\"finish\",\"finishReason\":\"stop\"}\n\ndata: [DONE]\n```\n\n### Event Types\n\n| Event | Description |\n|-------|-------------|\n| `start` | Stream started |\n| `finish` | Execution complete |\n| `error` | Error occurred |\n| `block-start` | Execution block started |\n| `block-end` | Execution block completed |\n| `text-start` | Text generation started |\n| `text-delta` | Incremental text content |\n| `text-end` | Text generation ended |\n| `reasoning-start` | Extended reasoning started |\n| `reasoning-delta` | Reasoning content |\n| `reasoning-end` | Extended reasoning ended |\n| `tool-input-start` | Tool call initiated |\n| `tool-input-delta` | Tool arguments streaming |\n| `tool-input-end` | Tool arguments streaming ended |\n| `tool-input-available` | Tool input complete |\n| `tool-output-available` | Tool completed with result |\n| `tool-output-error` | Tool failed |\n| `tool-request` | Platform requesting tool execution |\n| `resource-update` | Resource value changed |\n\n### Example\n\n```bash\ncurl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/trigger \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"triggerName\": \"user-message\",\n    \"input\": { \"USER_MESSAGE\": \"How do I reset my password?\" }\n  }'\n```\n\n## Tool Continuation\n\nWhen the agent calls external tools, you'll receive a `tool-request` event. Execute the tools and send results back:\n\n```json\n{\n  \"triggerName\": \"user-message\",\n  \"input\": { \"USER_MESSAGE\": \"...\" },\n  \"toolResults\": [\n    {\n      \"toolCallId\": \"tc_123\",\n      \"toolName\": \"get-user-account\",\n      \"result\": {\n        \"name\": \"Demo User\",\n        \"email\": \"demo@example.com\"\n      }\n    }\n  ]\n}\n```\n\nThe Server SDK handles this continuation pattern automatically.\n",
+        "content": "\n# Sessions API\n\nSessions represent conversations with agents. They store conversation history, resources, and variables.\n\n## Create Session\n\nCreate a new agent session.\n\n```\nPOST /api/agent-sessions\n```\n\n### Request Body\n\n```json\n{\n  \"agentId\": \"cm5xvz7k80001abcd\",\n  \"input\": {\n    \"COMPANY_NAME\": \"Acme Corp\",\n    \"PRODUCT_NAME\": \"Widget Pro\",\n    \"USER_ID\": \"user-123\"\n  }\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `agentId` | string | Yes | Agent ID (the `id` field, not `slug`) |\n| `input` | object | No | Input variables for the agent |\n\n> To get the agent ID, copy it from the platform URL, use [Get Agent by slug](/docs/api-reference/agents#get-agent) (`GET /api/agents/:slug?by=slug`), or the SDK's `agents.getBySlug()` method.\n\n### Response\n\n```json\n{\n  \"sessionId\": \"cm5xyz123abc456def\"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"agentId\": \"cm5xvz7k80001abcd\",\n    \"input\": {\n      \"COMPANY_NAME\": \"Acme Corp\",\n      \"PRODUCT_NAME\": \"Widget Pro\"\n    }\n  }'\n```\n\n## Get Session\n\nRetrieve session state including UI-ready messages and resources.\n\n```\nGET /api/agent-sessions/:sessionId\n```\n\n### Response\n\nThe response includes `UIMessage` objects that can be passed directly to the client SDK's `initialMessages` option:\n\n```json\n{\n  \"id\": \"cm5xyz123abc456def\",\n  \"agentId\": \"cm5xvz7k80001abcd\",\n  \"input\": {\n    \"COMPANY_NAME\": \"Acme Corp\",\n    \"PRODUCT_NAME\": \"Widget Pro\"\n  },\n  \"variables\": {},\n  \"resources\": {\n    \"CONVERSATION_SUMMARY\": \"\"\n  },\n  \"messages\": [\n    {\n      \"id\": \"1702345800000-xyz789a\",\n      \"role\": \"user\",\n      \"parts\": [\n        { \"type\": \"text\", \"text\": \"How do I reset my password?\", \"status\": \"done\" }\n      ],\n      \"status\": \"done\",\n      \"createdAt\": \"2024-01-15T10:30:00.000Z\"\n    },\n    {\n      \"id\": \"1702345805000-def456b\",\n      \"role\": \"assistant\",\n      \"parts\": [\n        { \"type\": \"text\", \"text\": \"I can help you reset your password...\", \"status\": \"done\" }\n      ],\n      \"status\": \"done\",\n      \"createdAt\": \"2024-01-15T10:30:05.000Z\"\n    }\n  ],\n  \"createdAt\": \"2024-01-15T10:30:00Z\",\n  \"updatedAt\": \"2024-01-15T10:30:05Z\"\n}\n```\n\n### UIMessage Parts\n\nMessages contain typed `parts` that preserve content ordering:\n\n| Part Type | Description |\n|-----------|-------------|\n| `text` | Text content with `text` and `status` fields |\n| `reasoning` | Extended reasoning with `text` and `status` fields |\n| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |\n| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agent-sessions/:sessionId \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n## Trigger Session\n\nExecute a trigger on a session. Returns a Server-Sent Events stream.\n\n```\nPOST /api/agent-sessions/:sessionId/trigger\n```\n\n### Request Body\n\n```json\n{\n  \"triggerName\": \"user-message\",\n  \"input\": {\n    \"USER_MESSAGE\": \"How do I reset my password?\"\n  },\n  \"toolResults\": []\n}\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `triggerName` | string | Yes | Name of the trigger to execute |\n| `input` | object | No | Input variables for the trigger |\n| `toolResults` | array | No | Tool results for continuation (handled by SDK) |\n\n### Response\n\nReturns `text/event-stream` with SSE events:\n\n```\ndata: {\"type\":\"start\",\"messageId\":\"msg-123\"}\n\ndata: {\"type\":\"block-start\",\"blockId\":\"b1\",\"blockName\":\"Add user message\",\"blockType\":\"add-message\",\"display\":\"hidden\"}\n\ndata: {\"type\":\"block-end\",\"blockId\":\"b1\"}\n\ndata: {\"type\":\"block-start\",\"blockId\":\"b2\",\"blockName\":\"Respond to user\",\"blockType\":\"next-message\",\"display\":\"stream\",\"outputToChat\":true}\n\ndata: {\"type\":\"text-start\",\"id\":\"t1\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\"I\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" can\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" help\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" you\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" reset\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" your\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\" password\"}\n\ndata: {\"type\":\"text-delta\",\"id\":\"t1\",\"delta\":\"!\"}\n\ndata: {\"type\":\"text-end\",\"id\":\"t1\"}\n\ndata: {\"type\":\"block-end\",\"blockId\":\"b2\"}\n\ndata: {\"type\":\"finish\",\"finishReason\":\"stop\"}\n\ndata: [DONE]\n```\n\n### Event Types\n\n| Event | Description |\n|-------|-------------|\n| `start` | Stream started |\n| `finish` | Execution complete |\n| `error` | Error occurred |\n| `block-start` | Execution block started |\n| `block-end` | Execution block completed |\n| `text-start` | Text generation started |\n| `text-delta` | Incremental text content |\n| `text-end` | Text generation ended |\n| `reasoning-start` | Extended reasoning started |\n| `reasoning-delta` | Reasoning content |\n| `reasoning-end` | Extended reasoning ended |\n| `tool-input-start` | Tool call initiated |\n| `tool-input-delta` | Tool arguments streaming |\n| `tool-input-end` | Tool arguments streaming ended |\n| `tool-input-available` | Tool input complete |\n| `tool-output-available` | Tool completed with result |\n| `tool-output-error` | Tool failed |\n| `tool-request` | Platform requesting tool execution |\n| `resource-update` | Resource value changed |\n\n### Example\n\n```bash\ncurl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/trigger \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"triggerName\": \"user-message\",\n    \"input\": { \"USER_MESSAGE\": \"How do I reset my password?\" }\n  }'\n```\n\n## Tool Continuation\n\nWhen the agent calls external tools, you'll receive a `tool-request` event. Execute the tools and send results back:\n\n```json\n{\n  \"triggerName\": \"user-message\",\n  \"input\": { \"USER_MESSAGE\": \"...\" },\n  \"toolResults\": [\n    {\n      \"toolCallId\": \"tc_123\",\n      \"toolName\": \"get-user-account\",\n      \"result\": {\n        \"name\": \"Demo User\",\n        \"email\": \"demo@example.com\"\n      }\n    }\n  ]\n}\n```\n\nThe Server SDK handles this continuation pattern automatically.\n",
         "excerpt": "Sessions API Sessions represent conversations with agents. They store conversation history, resources, and variables.  Create Session Create a new agent session.  Request Body | Field | Type |...",
         "order": 2
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octavus/docs",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Documentation content for Octavus SDKs",
   "license": "MIT",
   "author": "Octavus AI <hello@octavus.ai>",