@octavus/docs 3.1.0 → 3.2.0

package/dist/sections.json

@@ -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:** `3.1.0`\n\n## Installation\n\n```bash\nnpm install @octavus/server-sdk\n```\n\nFor agent management (sync, validate), install the CLI as a dev dependency:\n\n```bash\nnpm install --save-dev @octavus/cli\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### Agent Management\n\nAgent definitions are managed via the CLI. See the [CLI documentation](/docs/server-sdk/cli) for details.\n\n```bash\n# Sync agent from local files\noctavus sync ./agents/support-chat\n\n# Output: Created: support-chat\n#         Agent ID: clxyz123abc456\n```\n\n### Session Management\n\nCreate and manage agent sessions using the agent ID:\n\n```typescript\n// Create a new session (use agent ID from CLI sync)\nconst sessionId = await client.agentSessions.create('clxyz123abc456', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n});\n\n// Get UI-ready session messages (for session restore)\nconst session = await client.agentSessions.getMessages(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\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// execute() returns an async generator of events\nconst events = session.execute({\n  type: 'trigger',\n  triggerName: 'user-message',\n  input: { USER_MESSAGE: 'Hello!' },\n});\n\n// Convert to SSE stream for HTTP responses\nreturn new Response(toSSEStream(events), {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n### Computer Capabilities\n\nGive agents access to browser, filesystem, and shell via MCP:\n\n```typescript\nimport { Computer } from '@octavus/computer';\n\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', ['--browser-url=...']),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [dir]),\n    shell: Computer.shell({ cwd: dir, mode: 'unrestricted' }),\n  },\n});\n\nawait computer.start();\n\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'set-chat-title': async (args) => ({ title: args.title }),\n  },\n});\n\nsession.setDynamicTools(computer);\n```\n\n### Workers\n\nExecute worker agents for task-based processing:\n\n```typescript\n// Non-streaming: get the output directly\nconst { output } = await client.workers.generate(agentId, {\n  TOPIC: 'AI safety',\n});\n\n// Streaming: observe events in real-time\nfor await (const event of client.workers.execute(agentId, input)) {\n  // Handle stream events\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  traceModelRequests?: boolean; // Enable model request tracing (default: false)\n}\n\nclass OctavusClient {\n  readonly agents: AgentsApi;\n  readonly agentSessions: AgentSessionsApi;\n  readonly workers: WorkersApi;\n  readonly files: FilesApi;\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 full session state (for debugging/internal use)\n  async get(sessionId: string): Promise<SessionState>;\n\n  // Get UI-ready messages (for client display)\n  async getMessages(sessionId: string): Promise<UISessionState>;\n\n  // Attach to a session for triggering\n  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;\n}\n\n// Full session state (internal format)\ninterface SessionState {\n  id: string;\n  agentId: string;\n  input: Record<string, unknown>;\n  variables: Record<string, unknown>;\n  resources: Record<string, unknown>;\n  messages: ChatMessage[]; // Internal message format\n  createdAt: string;\n  updatedAt: string;\n}\n\n// UI-ready session state\ninterface UISessionState {\n  sessionId: string;\n  agentId: string;\n  messages: UIMessage[]; // UI-ready messages for frontend\n}\n```\n\n### AgentSession\n\nHandles request execution and streaming for a specific session.\n\n```typescript\nclass AgentSession {\n  // Execute a request and stream parsed events\n  execute(request: SessionRequest, options?: TriggerOptions): AsyncGenerator<StreamEvent>;\n\n  // Get the session ID\n  getSessionId(): string;\n\n  // Register dynamic tools (e.g., pass a Computer or explicit DynamicTool[])\n  setDynamicTools(source: ToolProvider | DynamicTool[]): void;\n}\n\ntype SessionRequest = TriggerRequest | ContinueRequest;\n\ninterface TriggerRequest {\n  type: 'trigger';\n  triggerName: string;\n  input?: Record<string, unknown>;\n}\n\ninterface ContinueRequest {\n  type: 'continue';\n  executionId: string;\n  toolResults: ToolResult[];\n}\n\n// Helper to convert events to SSE stream\nfunction toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;\n```\n\n### FilesApi\n\nHandles file uploads for sessions.\n\n```typescript\nclass FilesApi {\n  // Get presigned URLs for file uploads\n  async getUploadUrls(sessionId: string, files: FileUploadRequest[]): Promise<UploadUrlsResponse>;\n}\n\ninterface FileUploadRequest {\n  filename: string;\n  mediaType: string;\n  size: number;\n}\n\ninterface UploadUrlsResponse {\n  files: {\n    id: string; // File ID for references\n    uploadUrl: string; // PUT to this URL\n    downloadUrl: string; // GET URL after upload\n  }[];\n}\n```\n\nThe client uploads files directly to S3 using the presigned upload URL. See [File Uploads](/docs/client-sdk/file-uploads) for the full integration pattern.\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- [Workers](/docs/server-sdk/workers) - Executing worker agents\n- [Debugging](/docs/server-sdk/debugging) - Model request tracing and debugging\n- [Computer](/docs/server-sdk/computer) - Browser, filesystem, and shell via MCP\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:** `3.2.0`\n\n## Installation\n\n```bash\nnpm install @octavus/server-sdk\n```\n\nFor agent management (sync, validate), install the CLI as a dev dependency:\n\n```bash\nnpm install --save-dev @octavus/cli\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### Agent Management\n\nAgent definitions are managed via the CLI. See the [CLI documentation](/docs/server-sdk/cli) for details.\n\n```bash\n# Sync agent from local files\noctavus sync ./agents/support-chat\n\n# Output: Created: support-chat\n#         Agent ID: clxyz123abc456\n```\n\n### Session Management\n\nCreate and manage agent sessions using the agent ID:\n\n```typescript\n// Create a new session (use agent ID from CLI sync)\nconst sessionId = await client.agentSessions.create('clxyz123abc456', {\n  COMPANY_NAME: 'Acme Corp',\n  PRODUCT_NAME: 'Widget Pro',\n});\n\n// Get UI-ready session messages (for session restore)\nconst session = await client.agentSessions.getMessages(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\nimport { toSSEStream } from '@octavus/server-sdk';\n\n// execute() returns an async generator of events\nconst events = session.execute({\n  type: 'trigger',\n  triggerName: 'user-message',\n  input: { USER_MESSAGE: 'Hello!' },\n});\n\n// Convert to SSE stream for HTTP responses\nreturn new Response(toSSEStream(events), {\n  headers: { 'Content-Type': 'text/event-stream' },\n});\n```\n\n### Computer Capabilities\n\nGive agents access to browser, filesystem, and shell via MCP:\n\n```typescript\nimport { Computer } from '@octavus/computer';\n\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', ['--browser-url=...']),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [dir]),\n    shell: Computer.shell({ cwd: dir, mode: 'unrestricted' }),\n  },\n});\n\nawait computer.start();\n\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'set-chat-title': async (args) => ({ title: args.title }),\n  },\n});\n\nsession.setDynamicTools(computer);\n```\n\n### Workers\n\nExecute worker agents for task-based processing:\n\n```typescript\n// Non-streaming: get the output directly\nconst { output } = await client.workers.generate(agentId, {\n  TOPIC: 'AI safety',\n});\n\n// Streaming: observe events in real-time\nfor await (const event of client.workers.execute(agentId, input)) {\n  // Handle stream events\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  traceModelRequests?: boolean; // Enable model request tracing (default: false)\n}\n\nclass OctavusClient {\n  readonly agents: AgentsApi;\n  readonly agentSessions: AgentSessionsApi;\n  readonly workers: WorkersApi;\n  readonly files: FilesApi;\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 full session state (for debugging/internal use)\n  async get(sessionId: string): Promise<SessionState>;\n\n  // Get UI-ready messages (for client display)\n  async getMessages(sessionId: string): Promise<UISessionState>;\n\n  // Attach to a session for triggering\n  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;\n}\n\n// Full session state (internal format)\ninterface SessionState {\n  id: string;\n  agentId: string;\n  input: Record<string, unknown>;\n  variables: Record<string, unknown>;\n  resources: Record<string, unknown>;\n  messages: ChatMessage[]; // Internal message format\n  createdAt: string;\n  updatedAt: string;\n}\n\n// UI-ready session state\ninterface UISessionState {\n  sessionId: string;\n  agentId: string;\n  messages: UIMessage[]; // UI-ready messages for frontend\n}\n```\n\n### AgentSession\n\nHandles request execution and streaming for a specific session.\n\n```typescript\nclass AgentSession {\n  // Execute a request and stream parsed events\n  execute(request: SessionRequest, options?: TriggerOptions): AsyncGenerator<StreamEvent>;\n\n  // Get the session ID\n  getSessionId(): string;\n\n  // Register dynamic tools (e.g., pass a Computer or explicit DynamicTool[])\n  setDynamicTools(source: ToolProvider | DynamicTool[]): void;\n}\n\ntype SessionRequest = TriggerRequest | ContinueRequest;\n\ninterface TriggerRequest {\n  type: 'trigger';\n  triggerName: string;\n  input?: Record<string, unknown>;\n}\n\ninterface ContinueRequest {\n  type: 'continue';\n  executionId: string;\n  toolResults: ToolResult[];\n}\n\n// Helper to convert events to SSE stream\nfunction toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;\n```\n\n### FilesApi\n\nHandles file uploads for sessions.\n\n```typescript\nclass FilesApi {\n  // Get presigned URLs for file uploads\n  async getUploadUrls(sessionId: string, files: FileUploadRequest[]): Promise<UploadUrlsResponse>;\n}\n\ninterface FileUploadRequest {\n  filename: string;\n  mediaType: string;\n  size: number;\n}\n\ninterface UploadUrlsResponse {\n  files: {\n    id: string; // File ID for references\n    uploadUrl: string; // PUT to this URL\n    downloadUrl: string; // GET URL after upload\n  }[];\n}\n```\n\nThe client uploads files directly to S3 using the presigned upload URL. See [File Uploads](/docs/client-sdk/file-uploads) for the full integration pattern.\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- [Workers](/docs/server-sdk/workers) - Executing worker agents\n- [Debugging](/docs/server-sdk/debugging) - Model request tracing and debugging\n- [Computer](/docs/server-sdk/computer) - Browser, filesystem, and shell via MCP\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
       },
@@ -72,7 +72,7 @@
         "section": "server-sdk",
         "title": "CLI",
         "description": "Command-line interface for validating and syncing agent definitions.",
-        "content": "\n# Octavus CLI\n\nThe `@octavus/cli` package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform.\n\n**Current version:** `3.1.0`\n\n## Installation\n\n```bash\nnpm install --save-dev @octavus/cli\n```\n\n## Configuration\n\nThe CLI requires an API key with the **Agents** permission.\n\n### Environment Variables\n\n| Variable              | Description                                    |\n| --------------------- | ---------------------------------------------- |\n| `OCTAVUS_CLI_API_KEY` | API key with \"Agents\" permission (recommended) |\n| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set      |\n| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`     |\n\n### Two-Key Strategy (Recommended)\n\nFor production deployments, use separate API keys with minimal permissions:\n\n```bash\n# CI/CD or .env.local (not committed)\nOCTAVUS_CLI_API_KEY=oct_sk_...  # \"Agents\" permission only\n\n# Production .env\nOCTAVUS_API_KEY=oct_sk_...      # \"Sessions\" permission only\n```\n\nThis ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.\n\n### Multiple Environments\n\nUse separate Octavus projects for staging and production, each with their own API keys. The `--env` flag lets you load different environment files:\n\n```bash\n# Local development (default: .env)\noctavus sync ./agents/my-agent\n\n# Staging project\noctavus --env .env.staging sync ./agents/my-agent\n\n# Production project\noctavus --env .env.production sync ./agents/my-agent\n```\n\nExample environment files:\n\n```bash\n# .env.staging (syncs to your staging project)\nOCTAVUS_CLI_API_KEY=oct_sk_staging_project_key...\n\n# .env.production (syncs to your production project)\nOCTAVUS_CLI_API_KEY=oct_sk_production_project_key...\n```\n\nEach project has its own agents, so you'll get different agent IDs per environment.\n\n## Global Options\n\n| Option         | Description                                             |\n| -------------- | ------------------------------------------------------- |\n| `--env <file>` | Load environment from a specific file (default: `.env`) |\n| `--help`       | Show help                                               |\n| `--version`    | Show version                                            |\n\n## Commands\n\n### `octavus sync <path>`\n\nSync an agent definition to the platform. Creates the agent if it doesn't exist, or updates it if it does.\n\n```bash\noctavus sync ./agents/my-agent\n```\n\n**Options:**\n\n- `--json` - Output as JSON (for CI/CD parsing)\n- `--quiet` - Suppress non-essential output\n\n**Example output:**\n\n```\nℹ Reading agent from ./agents/my-agent...\nℹ Syncing support-chat...\n✓ Created: support-chat\n  Agent ID: clxyz123abc456\n```\n\n### `octavus validate <path>`\n\nValidate an agent definition without saving. Useful for CI/CD pipelines.\n\n```bash\noctavus validate ./agents/my-agent\n```\n\n**Exit codes:**\n\n- `0` - Validation passed\n- `1` - Validation errors\n- `2` - Configuration errors (missing API key, etc.)\n\n### `octavus list`\n\nList all agents in your project.\n\n```bash\noctavus list\n```\n\n**Example output:**\n\n```\nSLUG                  NAME                            FORMAT        ID\n────────────────────────────────────────────────────────────────────────────\nsupport-chat          Support Chat Agent              interactive   clxyz123abc456\n\n1 agent(s)\n```\n\n### `octavus get <slug>`\n\nGet details about a specific agent by its slug.\n\n```bash\noctavus get support-chat\n```\n\n### `octavus archive <slug>`\n\nArchive an agent by slug (soft delete). Archived agents are removed from the active agent list and their slug is freed for reuse.\n\n```bash\noctavus archive support-chat\n```\n\n**Options:**\n\n- `--json` - Output as JSON (for CI/CD parsing)\n- `--quiet` - Suppress non-essential output\n\n**Example output:**\n\n```\nℹ Archiving support-chat...\n✓ Archived: support-chat\n  Agent ID: clxyz123abc456\n```\n\n### `octavus skills sync <path>`\n\nSync a skill to the platform. Packages the skill directory into a bundle (excluding `.env` files, `.git`, and `node_modules`), uploads it, and optionally pushes secrets from the skill's `.env` file.\n\n```bash\noctavus skills sync ./skills/github\n```\n\n**Options:**\n\n- `--json` - Output as JSON (for CI/CD parsing)\n- `--quiet` - Suppress non-essential output\n\n**Example output:**\n\n```\nℹ Reading skill from ./skills/github...\nℹ Packaging github...\n✓ Created: github\n  Skill ID: clxyz789def012\nℹ Pushing 2 secret(s)...\n✓ 2 secret(s) updated\n```\n\n**Secret handling:**\n\nIf the skill directory contains a `.env` file, secrets are pushed alongside the bundle. Secrets are cross-validated against the `secrets` declarations in `SKILL.md` - warnings are shown for undeclared or missing required secrets.\n\n```\nmy-skill/\n├── SKILL.md\n├── scripts/\n│   └── run.py\n└── .env              # Secrets (not included in bundle)\n```\n\nSee [Skills](/docs/protocol/skills) for details on skill format, secrets, and secure mode.\n\n## Agent Directory Structure\n\nThe CLI expects agent definitions in a specific directory structure:\n\n```\nmy-agent/\n├── settings.json     # Required: Agent metadata\n├── protocol.yaml     # Required: Agent protocol\n├── prompts/          # Optional: Prompt templates\n│   ├── system.md\n│   └── user-message.md\n└── references/       # Optional: Reference documents\n    └── api-guidelines.md\n```\n\n### references/\n\nReference files are markdown documents with YAML frontmatter containing a `description`. The agent can fetch these on demand during execution. See [References](/docs/protocol/references) for details.\n\n### settings.json\n\n```json\n{\n  \"slug\": \"my-agent\",\n  \"name\": \"My Agent\",\n  \"description\": \"A helpful assistant\",\n  \"format\": \"interactive\"\n}\n```\n\n### protocol.yaml\n\nSee the [Protocol documentation](/docs/protocol/overview) for details on protocol syntax.\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Validate and Sync Agents\n\non:\n  push:\n    branches: [main]\n    paths:\n      - 'agents/**'\n\njobs:\n  sync:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '22'\n\n      - run: npm install\n\n      - name: Validate agent\n        run: npx octavus validate ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n\n      - name: Sync agent\n        run: npx octavus sync ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n```\n\n### Package.json Scripts\n\nAdd sync scripts to your `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"agents:validate\": \"octavus validate ./agents/my-agent\",\n    \"agents:sync\": \"octavus sync ./agents/my-agent\"\n  },\n  \"devDependencies\": {\n    \"@octavus/cli\": \"^0.1.0\"\n  }\n}\n```\n\n## Workflow\n\nThe recommended workflow for managing agents:\n\n1. **Define agent locally** - Create `settings.json`, `protocol.yaml`, and prompts\n2. **Validate** - Run `octavus validate ./my-agent` to check for errors\n3. **Sync** - Run `octavus sync ./my-agent` to push to platform\n4. **Store agent ID** - Save the output ID in an environment variable\n5. **Use in app** - Read the ID from env and pass to `client.agentSessions.create()`\n\n```bash\n# After syncing: octavus sync ./agents/support-chat\n# Output: Agent ID: clxyz123abc456\n\n# Add to your .env file\nOCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456\n```\n\n```typescript\nconst agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;\n\nconst sessionId = await client.agentSessions.create(agentId, {\n  COMPANY_NAME: 'Acme Corp',\n});\n```\n",
+        "content": "\n# Octavus CLI\n\nThe `@octavus/cli` package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform.\n\n**Current version:** `3.2.0`\n\n## Installation\n\n```bash\nnpm install --save-dev @octavus/cli\n```\n\n## Configuration\n\nThe CLI requires an API key with the **Agents** permission.\n\n### Environment Variables\n\n| Variable              | Description                                    |\n| --------------------- | ---------------------------------------------- |\n| `OCTAVUS_CLI_API_KEY` | API key with \"Agents\" permission (recommended) |\n| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set      |\n| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`     |\n\n### Two-Key Strategy (Recommended)\n\nFor production deployments, use separate API keys with minimal permissions:\n\n```bash\n# CI/CD or .env.local (not committed)\nOCTAVUS_CLI_API_KEY=oct_sk_...  # \"Agents\" permission only\n\n# Production .env\nOCTAVUS_API_KEY=oct_sk_...      # \"Sessions\" permission only\n```\n\nThis ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.\n\n### Multiple Environments\n\nUse separate Octavus projects for staging and production, each with their own API keys. The `--env` flag lets you load different environment files:\n\n```bash\n# Local development (default: .env)\noctavus sync ./agents/my-agent\n\n# Staging project\noctavus --env .env.staging sync ./agents/my-agent\n\n# Production project\noctavus --env .env.production sync ./agents/my-agent\n```\n\nExample environment files:\n\n```bash\n# .env.staging (syncs to your staging project)\nOCTAVUS_CLI_API_KEY=oct_sk_staging_project_key...\n\n# .env.production (syncs to your production project)\nOCTAVUS_CLI_API_KEY=oct_sk_production_project_key...\n```\n\nEach project has its own agents, so you'll get different agent IDs per environment.\n\n## Global Options\n\n| Option         | Description                                             |\n| -------------- | ------------------------------------------------------- |\n| `--env <file>` | Load environment from a specific file (default: `.env`) |\n| `--help`       | Show help                                               |\n| `--version`    | Show version                                            |\n\n## Commands\n\n### `octavus sync <path>`\n\nSync an agent definition to the platform. Creates the agent if it doesn't exist, or updates it if it does.\n\n```bash\noctavus sync ./agents/my-agent\n```\n\n**Options:**\n\n- `--json` - Output as JSON (for CI/CD parsing)\n- `--quiet` - Suppress non-essential output\n\n**Example output:**\n\n```\nℹ Reading agent from ./agents/my-agent...\nℹ Syncing support-chat...\n✓ Created: support-chat\n  Agent ID: clxyz123abc456\n```\n\n### `octavus validate <path>`\n\nValidate an agent definition without saving. Useful for CI/CD pipelines.\n\n```bash\noctavus validate ./agents/my-agent\n```\n\n**Exit codes:**\n\n- `0` - Validation passed\n- `1` - Validation errors\n- `2` - Configuration errors (missing API key, etc.)\n\n### `octavus list`\n\nList all agents in your project.\n\n```bash\noctavus list\n```\n\n**Example output:**\n\n```\nSLUG                  NAME                            FORMAT        ID\n────────────────────────────────────────────────────────────────────────────\nsupport-chat          Support Chat Agent              interactive   clxyz123abc456\n\n1 agent(s)\n```\n\n### `octavus get <slug>`\n\nGet details about a specific agent by its slug.\n\n```bash\noctavus get support-chat\n```\n\n### `octavus archive <slug>`\n\nArchive an agent by slug (soft delete). Archived agents are removed from the active agent list and their slug is freed for reuse.\n\n```bash\noctavus archive support-chat\n```\n\n**Options:**\n\n- `--json` - Output as JSON (for CI/CD parsing)\n- `--quiet` - Suppress non-essential output\n\n**Example output:**\n\n```\nℹ Archiving support-chat...\n✓ Archived: support-chat\n  Agent ID: clxyz123abc456\n```\n\n### `octavus skills sync <path>`\n\nSync a skill to the platform. Packages the skill directory into a bundle (excluding `.env` files, `.git`, and `node_modules`), uploads it, and optionally pushes secrets from the skill's `.env` file.\n\n```bash\noctavus skills sync ./skills/github\n```\n\n**Options:**\n\n- `--json` - Output as JSON (for CI/CD parsing)\n- `--quiet` - Suppress non-essential output\n\n**Example output:**\n\n```\nℹ Reading skill from ./skills/github...\nℹ Packaging github...\n✓ Created: github\n  Skill ID: clxyz789def012\nℹ Pushing 2 secret(s)...\n✓ 2 secret(s) updated\n```\n\n**Secret handling:**\n\nIf the skill directory contains a `.env` file, secrets are pushed alongside the bundle. Secrets are cross-validated against the `secrets` declarations in `SKILL.md` - warnings are shown for undeclared or missing required secrets.\n\n```\nmy-skill/\n├── SKILL.md\n├── scripts/\n│   └── run.py\n└── .env              # Secrets (not included in bundle)\n```\n\nSee [Skills](/docs/protocol/skills) for details on skill format, secrets, and secure mode.\n\n## Agent Directory Structure\n\nThe CLI expects agent definitions in a specific directory structure:\n\n```\nmy-agent/\n├── settings.json     # Required: Agent metadata\n├── protocol.yaml     # Required: Agent protocol\n├── prompts/          # Optional: Prompt templates\n│   ├── system.md\n│   └── user-message.md\n└── references/       # Optional: Reference documents\n    └── api-guidelines.md\n```\n\n### references/\n\nReference files are markdown documents with YAML frontmatter containing a `description`. The agent can fetch these on demand during execution. See [References](/docs/protocol/references) for details.\n\n### settings.json\n\n```json\n{\n  \"slug\": \"my-agent\",\n  \"name\": \"My Agent\",\n  \"description\": \"A helpful assistant\",\n  \"format\": \"interactive\"\n}\n```\n\n### protocol.yaml\n\nSee the [Protocol documentation](/docs/protocol/overview) for details on protocol syntax.\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Validate and Sync Agents\n\non:\n  push:\n    branches: [main]\n    paths:\n      - 'agents/**'\n\njobs:\n  sync:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '22'\n\n      - run: npm install\n\n      - name: Validate agent\n        run: npx octavus validate ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n\n      - name: Sync agent\n        run: npx octavus sync ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n```\n\n### Package.json Scripts\n\nAdd sync scripts to your `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"agents:validate\": \"octavus validate ./agents/my-agent\",\n    \"agents:sync\": \"octavus sync ./agents/my-agent\"\n  },\n  \"devDependencies\": {\n    \"@octavus/cli\": \"^0.1.0\"\n  }\n}\n```\n\n## Workflow\n\nThe recommended workflow for managing agents:\n\n1. **Define agent locally** - Create `settings.json`, `protocol.yaml`, and prompts\n2. **Validate** - Run `octavus validate ./my-agent` to check for errors\n3. **Sync** - Run `octavus sync ./my-agent` to push to platform\n4. **Store agent ID** - Save the output ID in an environment variable\n5. **Use in app** - Read the ID from env and pass to `client.agentSessions.create()`\n\n```bash\n# After syncing: octavus sync ./agents/support-chat\n# Output: Agent ID: clxyz123abc456\n\n# Add to your .env file\nOCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456\n```\n\n```typescript\nconst agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;\n\nconst sessionId = await client.agentSessions.create(agentId, {\n  COMPANY_NAME: 'Acme Corp',\n});\n```\n",
         "excerpt": "Octavus CLI The  package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform. Current version:   Installation ...",
         "order": 5
       },
@@ -99,7 +99,7 @@
         "section": "server-sdk",
         "title": "Computer",
         "description": "Adding browser, filesystem, and shell capabilities to agents with @octavus/computer.",
-        "content": "\n# Computer\n\nThe `@octavus/computer` package gives agents access to a physical or virtual machine's browser, filesystem, and shell. It connects to [MCP](https://modelcontextprotocol.io) servers, discovers their tools, and provides them to the server-sdk.\n\n**Current version:** `3.1.0`\n\n## Installation\n\n```bash\nnpm install @octavus/computer\n```\n\n## Quick Start\n\n```typescript\nimport { Computer } from '@octavus/computer';\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', ['--browser-url=http://127.0.0.1:9222']),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', ['/path/to/workspace']),\n    shell: Computer.shell({ cwd: '/path/to/workspace', mode: 'unrestricted' }),\n  },\n});\n\nawait computer.start();\n\nconst client = new OctavusClient({\n  baseUrl: 'https://octavus.ai',\n  apiKey: 'your-api-key',\n});\n\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'set-chat-title': async (args) => ({ title: args.title }),\n  },\n});\n\nsession.setDynamicTools(computer);\n```\n\nDynamic tools are registered after attaching via `session.setDynamicTools()`. Pass the `computer` directly - the session extracts schemas and handlers from the `ToolProvider`. Tool schemas are sent to the platform on the next `execute()` call, and tool calls flow back through the existing execution loop.\n\n## How It Works\n\n1. You configure MCP servers with namespaces (e.g., `browser`, `filesystem`, `shell`)\n2. `computer.start()` connects to all servers in parallel and discovers their tools\n3. Each tool is namespaced with `__` (e.g., `browser__navigate_page`, `filesystem__read_file`)\n4. The server-sdk sends tool schemas to the platform and handles tool call execution\n\nThe agent's protocol must declare matching `mcpServers` with `source: device` - see [MCP Servers](/docs/protocol/mcp-servers).\n\n## Entry Types\n\nThe `Computer` class supports three types of MCP entries:\n\n### Stdio (MCP Subprocess)\n\nSpawns an MCP server as a child process, communicating via stdin/stdout:\n\n```typescript\nComputer.stdio(command: string, args?: string[], options?: {\n  env?: Record<string, string>;\n  cwd?: string;\n})\n```\n\nUse this for local MCP servers installed as npm packages or standalone executables:\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', [\n      '--browser-url=http://127.0.0.1:9222',\n      '--no-usage-statistics',\n    ]),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [\n      '/Users/me/projects/my-app',\n    ]),\n  },\n});\n```\n\n### HTTP (Remote MCP Endpoint)\n\nConnects to an MCP server over Streamable HTTP:\n\n```typescript\nComputer.http(url: string, options?: {\n  headers?: Record<string, string>;\n})\n```\n\nUse this for MCP servers running as HTTP services:\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    docs: Computer.http('http://localhost:3001/mcp', {\n      headers: { Authorization: 'Bearer token' },\n    }),\n  },\n});\n```\n\n### Shell (Built-in)\n\nProvides shell command execution without spawning an MCP subprocess:\n\n```typescript\nComputer.shell(options: {\n  cwd?: string;\n  mode: ShellMode;\n  timeout?: number;  // Default: 300,000ms (5 minutes)\n})\n```\n\nThis exposes a `run_command` tool (namespaced as `shell__run_command` when the key is `shell`). Commands execute in a login shell with the user's full environment.\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    shell: Computer.shell({\n      cwd: '/Users/me/projects/my-app',\n      mode: 'unrestricted',\n      timeout: 300_000,\n    }),\n  },\n});\n```\n\n#### Shell Safety Modes\n\n| Mode                                   | Description                                   |\n| -------------------------------------- | --------------------------------------------- |\n| `'unrestricted'`                       | All commands allowed (for dedicated machines) |\n| `{ allowedPatterns, blockedPatterns }` | Pattern-based command filtering               |\n\nPattern-based filtering:\n\n```typescript\nComputer.shell({\n  cwd: workspaceDir,\n  mode: {\n    blockedPatterns: [/rm\\s+-rf/, /sudo/],\n    allowedPatterns: [/^git\\s/, /^npm\\s/, /^ls\\s/],\n  },\n});\n```\n\nWhen `allowedPatterns` is set, only matching commands are permitted. When `blockedPatterns` is set, matching commands are rejected. Blocked patterns are checked first.\n\n## Lifecycle\n\n### Starting\n\n`computer.start()` connects to all configured MCP servers in parallel. If some servers fail to connect, the computer still starts with the remaining servers - only if _all_ connections fail does it throw an error.\n\n```typescript\nconst { errors } = await computer.start();\n\nif (errors.length > 0) {\n  console.warn('Some MCP servers failed to connect:', errors);\n}\n```\n\n### Stopping\n\n`computer.stop()` closes all MCP connections and kills managed processes:\n\n```typescript\nawait computer.stop();\n```\n\nAlways call `stop()` when the session ends to clean up MCP subprocesses. For managed processes (like Chrome), pass them in the config for automatic cleanup.\n\n## Chrome Launch Helper\n\nFor desktop applications that need to control a browser, `Computer.launchChrome()` launches Chrome with remote debugging enabled:\n\n```typescript\nconst browser = await Computer.launchChrome({\n  profileDir: '/Users/me/.my-app/chrome-profiles/agent-1',\n  debuggingPort: 9222, // Optional, auto-allocated if omitted\n  flags: ['--window-size=1280,800'],\n});\n\nconsole.log(`Chrome running on port ${browser.port}, PID ${browser.pid}`);\n```\n\nPass the browser to `managedProcesses` for automatic cleanup when the computer stops:\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', [\n      `--browser-url=http://127.0.0.1:${browser.port}`,\n    ]),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [workspaceDir]),\n    shell: Computer.shell({ cwd: workspaceDir, mode: 'unrestricted' }),\n  },\n  managedProcesses: [{ process: browser.process }],\n});\n```\n\n### ChromeLaunchOptions\n\n| Field           | Required | Description                                           |\n| --------------- | -------- | ----------------------------------------------------- |\n| `profileDir`    | Yes      | Directory for Chrome's user data (profile isolation)  |\n| `debuggingPort` | No       | Port for remote debugging (auto-allocated if omitted) |\n| `flags`         | No       | Additional Chrome launch flags                        |\n\n## ToolProvider Interface\n\n`Computer` implements the `ToolProvider` interface from `@octavus/core`:\n\n```typescript\ninterface ToolProvider {\n  toolHandlers(): Record<string, ToolHandler>;\n  toolSchemas(): ToolSchema[];\n}\n```\n\n`setDynamicTools()` accepts any `ToolProvider` directly - the session extracts schemas and handlers automatically:\n\n```typescript\nsession.setDynamicTools(computer);\n```\n\nYou can also pass a custom `ToolProvider`:\n\n```typescript\nconst customProvider: ToolProvider = {\n  toolHandlers() {\n    return {\n      custom__my_tool: async (args) => {\n        return { result: 'done' };\n      },\n    };\n  },\n  toolSchemas() {\n    return [\n      {\n        name: 'custom__my_tool',\n        description: 'A custom tool',\n        inputSchema: {\n          type: 'object',\n          properties: {\n            input: { type: 'string', description: 'Tool input' },\n          },\n          required: ['input'],\n        },\n      },\n    ];\n  },\n};\n\nconst session = client.agentSessions.attach(sessionId, {\n  tools: { 'set-chat-title': titleHandler },\n});\n\nsession.setDynamicTools(customProvider);\n```\n\nFor cases where you need explicit control, `setDynamicTools()` also accepts a `DynamicTool[]` array:\n\n```typescript\ninterface DynamicTool {\n  schema: ToolSchema;\n  handler: ToolHandler;\n}\n```\n\n## Complete Example\n\nA desktop application with browser, filesystem, and shell capabilities:\n\n```typescript\nimport { Computer } from '@octavus/computer';\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst WORKSPACE_DIR = '/Users/me/projects/my-app';\nconst PROFILE_DIR = '/Users/me/.my-app/chrome-profiles/agent';\n\nasync function startSession(sessionId: string) {\n  // 1. Launch Chrome with remote debugging\n  const browser = await Computer.launchChrome({\n    profileDir: PROFILE_DIR,\n  });\n\n  // 2. Create computer with all capabilities\n  const computer = new Computer({\n    mcpServers: {\n      browser: Computer.stdio('chrome-devtools-mcp', [\n        `--browser-url=http://127.0.0.1:${browser.port}`,\n        '--no-usage-statistics',\n      ]),\n      filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [WORKSPACE_DIR]),\n      shell: Computer.shell({\n        cwd: WORKSPACE_DIR,\n        mode: 'unrestricted',\n      }),\n    },\n    managedProcesses: [{ process: browser.process }],\n  });\n\n  // 3. Connect to all MCP servers\n  const { errors } = await computer.start();\n  if (errors.length > 0) {\n    console.warn('Failed to connect:', errors);\n  }\n\n  // 4. Attach to session and register dynamic tools\n  const client = new OctavusClient({\n    baseUrl: process.env.OCTAVUS_API_URL!,\n    apiKey: process.env.OCTAVUS_API_KEY!,\n  });\n\n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      'set-chat-title': async (args) => {\n        console.log('Chat title:', args.title);\n        return { success: true };\n      },\n    },\n  });\n\n  session.setDynamicTools(computer);\n\n  // 5. Execute and stream\n  const events = session.execute({\n    type: 'trigger',\n    triggerName: 'user-message',\n    input: { USER_MESSAGE: 'Navigate to github.com and take a screenshot' },\n  });\n\n  for await (const event of events) {\n    // Handle stream events\n  }\n\n  // 6. Clean up\n  await computer.stop();\n}\n```\n\n## API Reference\n\n### Computer\n\n```typescript\nclass Computer implements ToolProvider {\n  constructor(config: ComputerConfig);\n\n  // Static factories for MCP entries\n  static stdio(\n    command: string,\n    args?: string[],\n    options?: {\n      env?: Record<string, string>;\n      cwd?: string;\n    },\n  ): StdioConfig;\n\n  static http(\n    url: string,\n    options?: {\n      headers?: Record<string, string>;\n    },\n  ): HttpConfig;\n\n  static shell(options: { cwd?: string; mode: ShellMode; timeout?: number }): ShellConfig;\n\n  // Chrome launch helper\n  static launchChrome(options: ChromeLaunchOptions): Promise<ChromeInstance>;\n\n  // Lifecycle\n  start(): Promise<{ errors: string[] }>;\n  stop(): Promise<void>;\n\n  // ToolProvider implementation\n  toolHandlers(): Record<string, ToolHandler>;\n  toolSchemas(): ToolSchema[];\n}\n```\n\n### ComputerConfig\n\n```typescript\ninterface ComputerConfig {\n  mcpServers: Record<string, McpEntry>;\n  managedProcesses?: { process: ChildProcess }[];\n}\n\ntype McpEntry = StdioConfig | HttpConfig | ShellConfig;\ntype ShellMode =\n  | 'unrestricted'\n  | {\n      allowedPatterns?: RegExp[];\n      blockedPatterns?: RegExp[];\n    };\n```\n\n### ChromeInstance\n\n```typescript\ninterface ChromeInstance {\n  port: number;\n  process: ChildProcess;\n  pid: number;\n}\n```\n",
+        "content": "\n# Computer\n\nThe `@octavus/computer` package gives agents access to a physical or virtual machine's browser, filesystem, and shell. It connects to [MCP](https://modelcontextprotocol.io) servers, discovers their tools, and provides them to the server-sdk.\n\n**Current version:** `3.2.0`\n\n## Installation\n\n```bash\nnpm install @octavus/computer\n```\n\n## Quick Start\n\n```typescript\nimport { Computer } from '@octavus/computer';\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', ['--browser-url=http://127.0.0.1:9222']),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', ['/path/to/workspace']),\n    shell: Computer.shell({ cwd: '/path/to/workspace', mode: 'unrestricted' }),\n  },\n});\n\nawait computer.start();\n\nconst client = new OctavusClient({\n  baseUrl: 'https://octavus.ai',\n  apiKey: 'your-api-key',\n});\n\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    'set-chat-title': async (args) => ({ title: args.title }),\n  },\n});\n\nsession.setDynamicTools(computer);\n```\n\nDynamic tools are registered after attaching via `session.setDynamicTools()`. Pass the `computer` directly - the session extracts schemas and handlers from the `ToolProvider`. Tool schemas are sent to the platform on the next `execute()` call, and tool calls flow back through the existing execution loop.\n\n## How It Works\n\n1. You configure MCP servers with namespaces (e.g., `browser`, `filesystem`, `shell`)\n2. `computer.start()` connects to all servers in parallel and discovers their tools\n3. Each tool is namespaced with `__` (e.g., `browser__navigate_page`, `filesystem__read_file`)\n4. The server-sdk sends tool schemas to the platform and handles tool call execution\n\nThe agent's protocol must declare matching `mcpServers` with `source: device` - see [MCP Servers](/docs/protocol/mcp-servers).\n\n## Entry Types\n\nThe `Computer` class supports three types of MCP entries:\n\n### Stdio (MCP Subprocess)\n\nSpawns an MCP server as a child process, communicating via stdin/stdout:\n\n```typescript\nComputer.stdio(command: string, args?: string[], options?: {\n  env?: Record<string, string>;\n  cwd?: string;\n})\n```\n\nUse this for local MCP servers installed as npm packages or standalone executables:\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', [\n      '--browser-url=http://127.0.0.1:9222',\n      '--no-usage-statistics',\n    ]),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [\n      '/Users/me/projects/my-app',\n    ]),\n  },\n});\n```\n\n### HTTP (Remote MCP Endpoint)\n\nConnects to an MCP server over Streamable HTTP:\n\n```typescript\nComputer.http(url: string, options?: {\n  headers?: Record<string, string>;\n})\n```\n\nUse this for MCP servers running as HTTP services:\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    docs: Computer.http('http://localhost:3001/mcp', {\n      headers: { Authorization: 'Bearer token' },\n    }),\n  },\n});\n```\n\n### Shell (Built-in)\n\nProvides shell command execution without spawning an MCP subprocess:\n\n```typescript\nComputer.shell(options: {\n  cwd?: string;\n  mode: ShellMode;\n  timeout?: number;  // Default: 300,000ms (5 minutes)\n})\n```\n\nThis exposes a `run_command` tool (namespaced as `shell__run_command` when the key is `shell`). Commands execute in a login shell with the user's full environment.\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    shell: Computer.shell({\n      cwd: '/Users/me/projects/my-app',\n      mode: 'unrestricted',\n      timeout: 300_000,\n    }),\n  },\n});\n```\n\n#### Shell Safety Modes\n\n| Mode                                   | Description                                   |\n| -------------------------------------- | --------------------------------------------- |\n| `'unrestricted'`                       | All commands allowed (for dedicated machines) |\n| `{ allowedPatterns, blockedPatterns }` | Pattern-based command filtering               |\n\nPattern-based filtering:\n\n```typescript\nComputer.shell({\n  cwd: workspaceDir,\n  mode: {\n    blockedPatterns: [/rm\\s+-rf/, /sudo/],\n    allowedPatterns: [/^git\\s/, /^npm\\s/, /^ls\\s/],\n  },\n});\n```\n\nWhen `allowedPatterns` is set, only matching commands are permitted. When `blockedPatterns` is set, matching commands are rejected. Blocked patterns are checked first.\n\n## Lifecycle\n\n### Starting\n\n`computer.start()` connects to all configured MCP servers in parallel. If some servers fail to connect, the computer still starts with the remaining servers - only if _all_ connections fail does it throw an error.\n\n```typescript\nconst { errors } = await computer.start();\n\nif (errors.length > 0) {\n  console.warn('Some MCP servers failed to connect:', errors);\n}\n```\n\n### Stopping\n\n`computer.stop()` closes all MCP connections and kills managed processes:\n\n```typescript\nawait computer.stop();\n```\n\nAlways call `stop()` when the session ends to clean up MCP subprocesses. For managed processes (like Chrome), pass them in the config for automatic cleanup.\n\n## Chrome Launch Helper\n\nFor desktop applications that need to control a browser, `Computer.launchChrome()` launches Chrome with remote debugging enabled:\n\n```typescript\nconst browser = await Computer.launchChrome({\n  profileDir: '/Users/me/.my-app/chrome-profiles/agent-1',\n  debuggingPort: 9222, // Optional, auto-allocated if omitted\n  flags: ['--window-size=1280,800'],\n});\n\nconsole.log(`Chrome running on port ${browser.port}, PID ${browser.pid}`);\n```\n\nPass the browser to `managedProcesses` for automatic cleanup when the computer stops:\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', [\n      `--browser-url=http://127.0.0.1:${browser.port}`,\n    ]),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [workspaceDir]),\n    shell: Computer.shell({ cwd: workspaceDir, mode: 'unrestricted' }),\n  },\n  managedProcesses: [{ process: browser.process }],\n});\n```\n\n### ChromeLaunchOptions\n\n| Field           | Required | Description                                           |\n| --------------- | -------- | ----------------------------------------------------- |\n| `profileDir`    | Yes      | Directory for Chrome's user data (profile isolation)  |\n| `debuggingPort` | No       | Port for remote debugging (auto-allocated if omitted) |\n| `flags`         | No       | Additional Chrome launch flags                        |\n\n## ToolProvider Interface\n\n`Computer` implements the `ToolProvider` interface from `@octavus/core`:\n\n```typescript\ninterface ToolProvider {\n  toolHandlers(): Record<string, ToolHandler>;\n  toolSchemas(): ToolSchema[];\n}\n```\n\n`setDynamicTools()` accepts any `ToolProvider` directly - the session extracts schemas and handlers automatically:\n\n```typescript\nsession.setDynamicTools(computer);\n```\n\nYou can also pass a custom `ToolProvider`:\n\n```typescript\nconst customProvider: ToolProvider = {\n  toolHandlers() {\n    return {\n      custom__my_tool: async (args) => {\n        return { result: 'done' };\n      },\n    };\n  },\n  toolSchemas() {\n    return [\n      {\n        name: 'custom__my_tool',\n        description: 'A custom tool',\n        inputSchema: {\n          type: 'object',\n          properties: {\n            input: { type: 'string', description: 'Tool input' },\n          },\n          required: ['input'],\n        },\n      },\n    ];\n  },\n};\n\nconst session = client.agentSessions.attach(sessionId, {\n  tools: { 'set-chat-title': titleHandler },\n});\n\nsession.setDynamicTools(customProvider);\n```\n\nFor cases where you need explicit control, `setDynamicTools()` also accepts a `DynamicTool[]` array:\n\n```typescript\ninterface DynamicTool {\n  schema: ToolSchema;\n  handler: ToolHandler;\n}\n```\n\n## Complete Example\n\nA desktop application with browser, filesystem, and shell capabilities:\n\n```typescript\nimport { Computer } from '@octavus/computer';\nimport { OctavusClient } from '@octavus/server-sdk';\n\nconst WORKSPACE_DIR = '/Users/me/projects/my-app';\nconst PROFILE_DIR = '/Users/me/.my-app/chrome-profiles/agent';\n\nasync function startSession(sessionId: string) {\n  // 1. Launch Chrome with remote debugging\n  const browser = await Computer.launchChrome({\n    profileDir: PROFILE_DIR,\n  });\n\n  // 2. Create computer with all capabilities\n  const computer = new Computer({\n    mcpServers: {\n      browser: Computer.stdio('chrome-devtools-mcp', [\n        `--browser-url=http://127.0.0.1:${browser.port}`,\n        '--no-usage-statistics',\n      ]),\n      filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [WORKSPACE_DIR]),\n      shell: Computer.shell({\n        cwd: WORKSPACE_DIR,\n        mode: 'unrestricted',\n      }),\n    },\n    managedProcesses: [{ process: browser.process }],\n  });\n\n  // 3. Connect to all MCP servers\n  const { errors } = await computer.start();\n  if (errors.length > 0) {\n    console.warn('Failed to connect:', errors);\n  }\n\n  // 4. Attach to session and register dynamic tools\n  const client = new OctavusClient({\n    baseUrl: process.env.OCTAVUS_API_URL!,\n    apiKey: process.env.OCTAVUS_API_KEY!,\n  });\n\n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      'set-chat-title': async (args) => {\n        console.log('Chat title:', args.title);\n        return { success: true };\n      },\n    },\n  });\n\n  session.setDynamicTools(computer);\n\n  // 5. Execute and stream\n  const events = session.execute({\n    type: 'trigger',\n    triggerName: 'user-message',\n    input: { USER_MESSAGE: 'Navigate to github.com and take a screenshot' },\n  });\n\n  for await (const event of events) {\n    // Handle stream events\n  }\n\n  // 6. Clean up\n  await computer.stop();\n}\n```\n\n## API Reference\n\n### Computer\n\n```typescript\nclass Computer implements ToolProvider {\n  constructor(config: ComputerConfig);\n\n  // Static factories for MCP entries\n  static stdio(\n    command: string,\n    args?: string[],\n    options?: {\n      env?: Record<string, string>;\n      cwd?: string;\n    },\n  ): StdioConfig;\n\n  static http(\n    url: string,\n    options?: {\n      headers?: Record<string, string>;\n    },\n  ): HttpConfig;\n\n  static shell(options: { cwd?: string; mode: ShellMode; timeout?: number }): ShellConfig;\n\n  // Chrome launch helper\n  static launchChrome(options: ChromeLaunchOptions): Promise<ChromeInstance>;\n\n  // Lifecycle\n  start(): Promise<{ errors: string[] }>;\n  stop(): Promise<void>;\n\n  // ToolProvider implementation\n  toolHandlers(): Record<string, ToolHandler>;\n  toolSchemas(): ToolSchema[];\n}\n```\n\n### ComputerConfig\n\n```typescript\ninterface ComputerConfig {\n  mcpServers: Record<string, McpEntry>;\n  managedProcesses?: { process: ChildProcess }[];\n}\n\ntype McpEntry = StdioConfig | HttpConfig | ShellConfig;\ntype ShellMode =\n  | 'unrestricted'\n  | {\n      allowedPatterns?: RegExp[];\n      blockedPatterns?: RegExp[];\n    };\n```\n\n### ChromeInstance\n\n```typescript\ninterface ChromeInstance {\n  port: number;\n  process: ChildProcess;\n  pid: number;\n}\n```\n",
         "excerpt": "Computer The  package gives agents access to a physical or virtual machine's browser, filesystem, and shell. It connects to MCP servers, discovers their tools, and provides them to the server-sdk....",
         "order": 8
       }
@@ -116,7 +116,7 @@
         "section": "client-sdk",
         "title": "Overview",
         "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:** `3.1.0`\n\n### Other Frameworks\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n**Current version:** `3.1.0`\n\n## Transport Pattern\n\nThe Client SDK uses a **transport abstraction** to handle communication with your backend. This gives you flexibility in how events are delivered:\n\n| Transport               | Use Case                                     | Docs                                                  |\n| ----------------------- | -------------------------------------------- | ----------------------------------------------------- |\n| `createHttpTransport`   | HTTP/SSE (Next.js, Express, etc.)            | [HTTP Transport](/docs/client-sdk/http-transport)     |\n| `createSocketTransport` | WebSocket, SockJS, or other socket protocols | [Socket Transport](/docs/client-sdk/socket-transport) |\n\nWhen the transport changes (e.g., when `sessionId` changes), the `useOctavusChat` hook automatically reinitializes with the new transport.\n\n> **Recommendation**: Use HTTP transport unless you specifically need WebSocket features (custom real-time events, Meteor/Phoenix, etc.).\n\n## React Usage\n\nThe `useOctavusChat` hook provides state management and streaming for React applications:\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  // Create a stable transport instance (memoized on sessionId)\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n\n  const sendMessage = async (text: string) => {\n    await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });\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, createHttpTransport } from '@octavus/client-sdk';\n\nconst transport = createHttpTransport({\n  request: (payload, options) =>\n    fetch('/api/trigger', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ sessionId, ...payload }),\n      signal: options?.signal,\n    }),\n});\n\nconst chat = new OctavusChat({ transport });\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' }, { userMessage: { content: 'Hello' } });\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({ transport });\n\n// Add user message to UI and trigger agent\nawait send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });\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({ transport });\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({ transport });\n\n// status: 'idle' | 'streaming' | 'error' | 'awaiting-input'\n// 'awaiting-input' occurs when interactive client tools need user action\n```\n\n### Stop Streaming\n\n```tsx\nconst { stop } = useOctavusChat({ transport });\n\n// Stop current stream and finalize message\nstop();\n```\n\n### Retry Last Trigger\n\nRe-execute the last trigger from the same starting point. Messages are rolled back to the state before the trigger, the user message is re-added (if any), and the agent re-executes. Already-uploaded files are reused without re-uploading.\n\n```tsx\nconst { retry, canRetry } = useOctavusChat({ transport });\n\n// Retry after an error, cancellation, or unsatisfactory result\nif (canRetry) {\n  await retry();\n}\n```\n\n`canRetry` is `true` when a trigger has been sent and the chat is not currently streaming or awaiting input.\n\n## Hook Reference (React)\n\n### useOctavusChat\n\n```typescript\nfunction useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;\n\ninterface OctavusChatOptions {\n  // Required: Transport for streaming events\n  transport: Transport;\n\n  // Optional: Function to request upload URLs for file uploads\n  requestUploadUrls?: (\n    files: { filename: string; mediaType: string; size: number }[],\n  ) => Promise<UploadUrlsResponse>;\n\n  // Optional: Client-side tool handlers\n  // - Function: executes automatically and returns result\n  // - 'interactive': appears in pendingClientTools for user input\n  clientTools?: Record<string, ClientToolHandler>;\n\n  // Optional: Pre-populate with existing messages (session restore)\n  initialMessages?: UIMessage[];\n\n  // Optional: Callbacks\n  onError?: (error: OctavusError) => void; // Structured error with type, source, retryable\n  onFinish?: () => void;\n  onStop?: () => void; // Called when user stops generation\n  onResourceUpdate?: (name: string, value: unknown) => void;\n}\n\ninterface UseOctavusChatReturn {\n  // State\n  messages: UIMessage[];\n  status: ChatStatus; // 'idle' | 'streaming' | 'error' | 'awaiting-input'\n  error: OctavusError | null; // Structured error with type, source, retryable\n\n  // Connection (socket transport only - undefined for HTTP)\n  connectionState: ConnectionState | undefined; // 'disconnected' | 'connecting' | 'connected' | 'error'\n  connectionError: Error | undefined;\n\n  // Client tools (interactive tools awaiting user input)\n  pendingClientTools: Record<string, InteractiveTool[]>; // Keyed by tool name\n\n  // Actions\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput },\n  ) => Promise<void>;\n  stop: () => void;\n  retry: () => Promise<void>; // Retry last trigger from same starting point\n  canRetry: boolean; // Whether retry() can be called\n\n  // Connection management (socket transport only - undefined for HTTP)\n  connect: (() => Promise<void>) | undefined;\n  disconnect: (() => void) | undefined;\n\n  // File uploads (requires requestUploadUrls)\n  uploadFiles: (\n    files: FileList | File[],\n    onProgress?: (fileIndex: number, progress: number) => void,\n  ) => Promise<FileReference[]>;\n}\n\ninterface UserMessageInput {\n  content?: string;\n  files?: FileList | File[] | FileReference[];\n}\n```\n\n### useAutoScroll\n\nSmart auto-scroll for chat containers. Scrolls to bottom when content updates, but pauses if the user has scrolled up. See [Streaming - Auto-Scroll](/docs/client-sdk/streaming#auto-scroll) for full usage.\n\n```typescript\nfunction useAutoScroll(options?: UseAutoScrollOptions): {\n  scrollRef: RefObject<HTMLDivElement | null>;\n  handleScroll: () => void;\n  scrollOnUpdate: () => void;\n  resetAutoScroll: () => void;\n};\n\ninterface UseAutoScrollOptions {\n  scrollRef?: RefObject<HTMLDivElement | null>;\n  threshold?: number; // Distance from bottom in px (default: 80)\n}\n```\n\n## Transport Reference\n\n### createHttpTransport\n\nCreates an HTTP/SSE transport using native `fetch()`:\n\n```typescript\nimport { createHttpTransport } from '@octavus/react';\n\nconst transport = createHttpTransport({\n  request: (payload, options) =>\n    fetch('/api/trigger', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ sessionId, ...payload }),\n      signal: options?.signal,\n    }),\n});\n```\n\n### createSocketTransport\n\nCreates a WebSocket/SockJS transport for real-time connections:\n\n```typescript\nimport { createSocketTransport } from '@octavus/react';\n\nconst transport = createSocketTransport({\n  connect: () =>\n    new Promise((resolve, reject) => {\n      const ws = new WebSocket(`wss://api.example.com/stream?sessionId=${sessionId}`);\n      ws.onopen = () => resolve(ws);\n      ws.onerror = () => reject(new Error('Connection failed'));\n    }),\n});\n```\n\nSocket transport provides additional connection management:\n\n```typescript\n// Access connection state directly\ntransport.connectionState; // 'disconnected' | 'connecting' | 'connected' | 'error'\n\n// Subscribe to state changes\ntransport.onConnectionStateChange((state, error) => {\n  /* ... */\n});\n\n// Eager connection (instead of lazy on first send)\nawait transport.connect();\n\n// Manual disconnect\ntransport.disconnect();\n```\n\nFor detailed WebSocket/SockJS usage including custom events, reconnection patterns, and server-side implementation, see [Socket Transport](/docs/client-sdk/socket-transport).\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; // 'idle' | 'streaming' | 'error' | 'awaiting-input'\n  readonly error: OctavusError | null; // Structured error\n  readonly pendingClientTools: Record<string, InteractiveTool[]>; // Interactive tools\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- [HTTP Transport](/docs/client-sdk/http-transport) - HTTP/SSE integration (recommended)\n- [Socket Transport](/docs/client-sdk/socket-transport) - WebSocket and SockJS integration\n- [Messages](/docs/client-sdk/messages) - Working with message state\n- [Streaming](/docs/client-sdk/streaming) - Building streaming UIs\n- [Client Tools](/docs/client-sdk/client-tools) - Interactive browser-side tool handling\n- [Operations](/docs/client-sdk/execution-blocks) - Showing agent progress\n- [Error Handling](/docs/client-sdk/error-handling) - Handling errors with type guards\n- [File Uploads](/docs/client-sdk/file-uploads) - Uploading images and documents\n- [Examples](/docs/examples/overview) - Complete working examples\n",
+        "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:** `3.2.0`\n\n### Other Frameworks\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n**Current version:** `3.2.0`\n\n## Transport Pattern\n\nThe Client SDK uses a **transport abstraction** to handle communication with your backend. This gives you flexibility in how events are delivered:\n\n| Transport               | Use Case                                     | Docs                                                  |\n| ----------------------- | -------------------------------------------- | ----------------------------------------------------- |\n| `createHttpTransport`   | HTTP/SSE (Next.js, Express, etc.)            | [HTTP Transport](/docs/client-sdk/http-transport)     |\n| `createSocketTransport` | WebSocket, SockJS, or other socket protocols | [Socket Transport](/docs/client-sdk/socket-transport) |\n\nWhen the transport changes (e.g., when `sessionId` changes), the `useOctavusChat` hook automatically reinitializes with the new transport.\n\n> **Recommendation**: Use HTTP transport unless you specifically need WebSocket features (custom real-time events, Meteor/Phoenix, etc.).\n\n## React Usage\n\nThe `useOctavusChat` hook provides state management and streaming for React applications:\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  // Create a stable transport instance (memoized on sessionId)\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { messages, status, send } = useOctavusChat({ transport });\n\n  const sendMessage = async (text: string) => {\n    await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });\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, createHttpTransport } from '@octavus/client-sdk';\n\nconst transport = createHttpTransport({\n  request: (payload, options) =>\n    fetch('/api/trigger', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ sessionId, ...payload }),\n      signal: options?.signal,\n    }),\n});\n\nconst chat = new OctavusChat({ transport });\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' }, { userMessage: { content: 'Hello' } });\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({ transport });\n\n// Add user message to UI and trigger agent\nawait send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });\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({ transport });\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({ transport });\n\n// status: 'idle' | 'streaming' | 'error' | 'awaiting-input'\n// 'awaiting-input' occurs when interactive client tools need user action\n```\n\n### Stop Streaming\n\n```tsx\nconst { stop } = useOctavusChat({ transport });\n\n// Stop current stream and finalize message\nstop();\n```\n\n### Retry Last Trigger\n\nRe-execute the last trigger from the same starting point. Messages are rolled back to the state before the trigger, the user message is re-added (if any), and the agent re-executes. Already-uploaded files are reused without re-uploading.\n\n```tsx\nconst { retry, canRetry } = useOctavusChat({ transport });\n\n// Retry after an error, cancellation, or unsatisfactory result\nif (canRetry) {\n  await retry();\n}\n```\n\n`canRetry` is `true` when a trigger has been sent and the chat is not currently streaming or awaiting input.\n\n## Hook Reference (React)\n\n### useOctavusChat\n\n```typescript\nfunction useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;\n\ninterface OctavusChatOptions {\n  // Required: Transport for streaming events\n  transport: Transport;\n\n  // Optional: Function to request upload URLs for file uploads\n  requestUploadUrls?: (\n    files: { filename: string; mediaType: string; size: number }[],\n  ) => Promise<UploadUrlsResponse>;\n\n  // Optional: Client-side tool handlers\n  // - Function: executes automatically and returns result\n  // - 'interactive': appears in pendingClientTools for user input\n  clientTools?: Record<string, ClientToolHandler>;\n\n  // Optional: Pre-populate with existing messages (session restore)\n  initialMessages?: UIMessage[];\n\n  // Optional: Callbacks\n  onError?: (error: OctavusError) => void; // Structured error with type, source, retryable\n  onFinish?: () => void;\n  onStop?: () => void; // Called when user stops generation\n  onResourceUpdate?: (name: string, value: unknown) => void;\n}\n\ninterface UseOctavusChatReturn {\n  // State\n  messages: UIMessage[];\n  status: ChatStatus; // 'idle' | 'streaming' | 'error' | 'awaiting-input'\n  error: OctavusError | null; // Structured error with type, source, retryable\n\n  // Connection (socket transport only - undefined for HTTP)\n  connectionState: ConnectionState | undefined; // 'disconnected' | 'connecting' | 'connected' | 'error'\n  connectionError: Error | undefined;\n\n  // Client tools (interactive tools awaiting user input)\n  pendingClientTools: Record<string, InteractiveTool[]>; // Keyed by tool name\n\n  // Actions\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput },\n  ) => Promise<void>;\n  stop: () => void;\n  retry: () => Promise<void>; // Retry last trigger from same starting point\n  canRetry: boolean; // Whether retry() can be called\n\n  // Connection management (socket transport only - undefined for HTTP)\n  connect: (() => Promise<void>) | undefined;\n  disconnect: (() => void) | undefined;\n\n  // File uploads (requires requestUploadUrls)\n  uploadFiles: (\n    files: FileList | File[],\n    onProgress?: (fileIndex: number, progress: number) => void,\n  ) => Promise<FileReference[]>;\n}\n\ninterface UserMessageInput {\n  content?: string;\n  files?: FileList | File[] | FileReference[];\n}\n```\n\n### useAutoScroll\n\nSmart auto-scroll for chat containers. Scrolls to bottom when content updates, but pauses if the user has scrolled up. See [Streaming - Auto-Scroll](/docs/client-sdk/streaming#auto-scroll) for full usage.\n\n```typescript\nfunction useAutoScroll(options?: UseAutoScrollOptions): {\n  scrollRef: RefObject<HTMLDivElement | null>;\n  handleScroll: () => void;\n  scrollOnUpdate: () => void;\n  resetAutoScroll: () => void;\n};\n\ninterface UseAutoScrollOptions {\n  scrollRef?: RefObject<HTMLDivElement | null>;\n  threshold?: number; // Distance from bottom in px (default: 80)\n}\n```\n\n## Transport Reference\n\n### createHttpTransport\n\nCreates an HTTP/SSE transport using native `fetch()`:\n\n```typescript\nimport { createHttpTransport } from '@octavus/react';\n\nconst transport = createHttpTransport({\n  request: (payload, options) =>\n    fetch('/api/trigger', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ sessionId, ...payload }),\n      signal: options?.signal,\n    }),\n});\n```\n\n### createSocketTransport\n\nCreates a WebSocket/SockJS transport for real-time connections:\n\n```typescript\nimport { createSocketTransport } from '@octavus/react';\n\nconst transport = createSocketTransport({\n  connect: () =>\n    new Promise((resolve, reject) => {\n      const ws = new WebSocket(`wss://api.example.com/stream?sessionId=${sessionId}`);\n      ws.onopen = () => resolve(ws);\n      ws.onerror = () => reject(new Error('Connection failed'));\n    }),\n});\n```\n\nSocket transport provides additional connection management:\n\n```typescript\n// Access connection state directly\ntransport.connectionState; // 'disconnected' | 'connecting' | 'connected' | 'error'\n\n// Subscribe to state changes\ntransport.onConnectionStateChange((state, error) => {\n  /* ... */\n});\n\n// Eager connection (instead of lazy on first send)\nawait transport.connect();\n\n// Manual disconnect\ntransport.disconnect();\n```\n\nFor detailed WebSocket/SockJS usage including custom events, reconnection patterns, and server-side implementation, see [Socket Transport](/docs/client-sdk/socket-transport).\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; // 'idle' | 'streaming' | 'error' | 'awaiting-input'\n  readonly error: OctavusError | null; // Structured error\n  readonly pendingClientTools: Record<string, InteractiveTool[]>; // Interactive tools\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- [HTTP Transport](/docs/client-sdk/http-transport) - HTTP/SSE integration (recommended)\n- [Socket Transport](/docs/client-sdk/socket-transport) - WebSocket and SockJS integration\n- [Messages](/docs/client-sdk/messages) - Working with message state\n- [Streaming](/docs/client-sdk/streaming) - Building streaming UIs\n- [Client Tools](/docs/client-sdk/client-tools) - Interactive browser-side tool handling\n- [Operations](/docs/client-sdk/execution-blocks) - Showing agent progress\n- [Error Handling](/docs/client-sdk/error-handling) - Handling errors with type guards\n- [File Uploads](/docs/client-sdk/file-uploads) - Uploading images and documents\n- [Examples](/docs/examples/overview) - Complete working examples\n",
         "excerpt": "Client SDK Overview Octavus provides two packages for frontend integration: | Package               | Purpose                  | Use When                                              | |...",
         "order": 1
       },
@@ -125,7 +125,7 @@
         "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 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  | UISourcePart\n  | UIFilePart\n  | UIObjectPart;\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// Source references (from web search, document processing)\ninterface UISourcePart {\n  type: 'source';\n  sourceType: 'url' | 'document';\n  id: string;\n  url?: string; // For URL sources\n  title?: string;\n  mediaType?: string; // For document sources\n  filename?: string;\n  thread?: string;\n}\n\n// Generated files (from image generation, skills, code execution)\ninterface UIFilePart {\n  type: 'file';\n  id: string;\n  mediaType: string; // MIME type (e.g., 'image/png', 'image/webp')\n  url: string; // Download/display URL (presigned S3 URL)\n  filename?: string;\n  size?: number;\n  toolCallId?: string; // Present if from a tool call\n  thread?: string;\n}\n\n// Structured output (when responseType is used)\ninterface UIObjectPart {\n  type: 'object';\n  id: string;\n  typeName: string; // Type name from protocol (e.g., \"ChatResponse\")\n  partial?: unknown; // Partial object while streaming\n  object?: unknown; // Final object when done\n  status: 'streaming' | 'done' | 'error';\n  error?: string;\n  thread?: string;\n}\n```\n\n## Sending Messages\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { send } = useOctavusChat({ transport });\n\n  async function handleSend(text: string) {\n    // Add user message to UI and trigger agent\n    await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });\n  }\n\n  // ...\n}\n```\n\nThe `send` function:\n\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### Message Content Types\n\nThe `content` field in `userMessage` accepts both strings and objects:\n\n```tsx\n// Text content → creates a text part\nawait send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });\n\n// Object content → creates an object part (uses `type` field as typeName)\nconst selection = { type: 'product_selection', productId: 'abc123', action: 'select' };\nawait send('user-message', { USER_INPUT: selection }, { userMessage: { content: selection } });\n```\n\nWhen passing an object as `content`:\n\n- The SDK creates a `UIObjectPart` instead of a `UITextPart`\n- The object's `type` field is used as the `typeName` (defaults to `'object'` if not present)\n- This is useful for rich UI interactions like product selections, quick replies, etc.\n\n### Sending with Files\n\nInclude file attachments with messages:\n\n```tsx\nimport type { FileReference } from '@octavus/react';\n\nasync function handleSend(text: string, files?: FileReference[]) {\n  await send(\n    'user-message',\n    {\n      USER_MESSAGE: text,\n      FILES: files, // Array of FileReference\n    },\n    {\n      userMessage: {\n        content: text,\n        files: files, // Shows files in user message bubble\n      },\n    },\n  );\n}\n```\n\nSee [File Uploads](/docs/client-sdk/file-uploads) for complete upload flow.\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    case 'source':\n      return (\n        <div className=\"text-blue-500 text-sm\">📎 {part.title || part.url || part.filename}</div>\n      );\n\n    case 'file':\n      // Render images inline, other files as download links\n      if (part.mediaType.startsWith('image/')) {\n        return (\n          <img\n            src={part.url}\n            alt={part.filename || 'Generated image'}\n            className=\"max-w-full rounded-lg\"\n          />\n        );\n      }\n      return (\n        <a href={part.url} className=\"text-blue-500 text-sm underline\">\n          📄 {part.filename || 'Download file'}\n        </a>\n      );\n\n    case 'object':\n      // For structured output, render custom UI based on typeName\n      // See Structured Output guide for more details\n      return <ObjectPartRenderer part={part} />;\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, fetch messages from your backend and pass them to the hook:\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\ninterface ChatProps {\n  sessionId: string;\n  initialMessages: UIMessage[];\n}\n\nfunction Chat({ sessionId, initialMessages }: ChatProps) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  // Pass existing messages to restore the conversation\n  const { messages } = useOctavusChat({\n    transport,\n    initialMessages,\n  });\n\n  // ...\n}\n```\n\nOn your backend, use `agentSessions.getMessages()` to fetch UI-ready messages:\n\n```typescript\n// Server-side\nconst session = await client.agentSessions.getMessages(sessionId);\n// session.messages is UIMessage[] ready for the client\n```\n\n## Callbacks\n\n```tsx\nuseOctavusChat({\n  transport,\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",
+        "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  | UISourcePart\n  | UIFilePart\n  | UIObjectPart\n  | UITodoPart\n  | UIWorkerPart;\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// Source references (from web search, document processing)\ninterface UISourcePart {\n  type: 'source';\n  sourceType: 'url' | 'document';\n  id: string;\n  url?: string; // For URL sources\n  title?: string;\n  mediaType?: string; // For document sources\n  filename?: string;\n  thread?: string;\n}\n\n// Generated files (from image generation, skills, code execution)\ninterface UIFilePart {\n  type: 'file';\n  id: string;\n  mediaType: string; // MIME type (e.g., 'image/png', 'image/webp')\n  url: string; // Download/display URL (presigned S3 URL)\n  filename?: string;\n  size?: number;\n  toolCallId?: string; // Present if from a tool call\n  thread?: string;\n}\n\n// Structured output (when responseType is used)\ninterface UIObjectPart {\n  type: 'object';\n  id: string;\n  typeName: string; // Type name from protocol (e.g., \"ChatResponse\")\n  partial?: unknown; // Partial object while streaming\n  object?: unknown; // Final object when done\n  status: 'streaming' | 'done' | 'error';\n  error?: string;\n  thread?: string;\n}\n\n// Structured task list (when the agent uses octavus_todo_write)\ninterface UITodoPart {\n  type: 'todo';\n  todos: {\n    id: string;\n    content: string;\n    status: 'pending' | 'in_progress' | 'completed' | 'cancelled';\n  }[];\n  status: 'streaming' | 'done';\n  thread?: string;\n}\n\n// Sub-agent execution container (when an agent invokes a worker)\ninterface UIWorkerPart {\n  type: 'worker';\n  workerId: string;\n  workerSlug: string;\n  description?: string;\n  input?: Record<string, unknown>;\n  parts: UIMessagePart[]; // Nested parts from the worker (excluding nested workers)\n  output?: unknown;\n  error?: string;\n  status: 'running' | 'done' | 'error';\n}\n```\n\n## Sending Messages\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  const { send } = useOctavusChat({ transport });\n\n  async function handleSend(text: string) {\n    // Add user message to UI and trigger agent\n    await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });\n  }\n\n  // ...\n}\n```\n\nThe `send` function:\n\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### Message Content Types\n\nThe `content` field in `userMessage` accepts both strings and objects:\n\n```tsx\n// Text content → creates a text part\nawait send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });\n\n// Object content → creates an object part (uses `type` field as typeName)\nconst selection = { type: 'product_selection', productId: 'abc123', action: 'select' };\nawait send('user-message', { USER_INPUT: selection }, { userMessage: { content: selection } });\n```\n\nWhen passing an object as `content`:\n\n- The SDK creates a `UIObjectPart` instead of a `UITextPart`\n- The object's `type` field is used as the `typeName` (defaults to `'object'` if not present)\n- This is useful for rich UI interactions like product selections, quick replies, etc.\n\n### Sending with Files\n\nInclude file attachments with messages:\n\n```tsx\nimport type { FileReference } from '@octavus/react';\n\nasync function handleSend(text: string, files?: FileReference[]) {\n  await send(\n    'user-message',\n    {\n      USER_MESSAGE: text,\n      FILES: files, // Array of FileReference\n    },\n    {\n      userMessage: {\n        content: text,\n        files: files, // Shows files in user message bubble\n      },\n    },\n  );\n}\n```\n\nSee [File Uploads](/docs/client-sdk/file-uploads) for complete upload flow.\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    case 'source':\n      return (\n        <div className=\"text-blue-500 text-sm\">📎 {part.title || part.url || part.filename}</div>\n      );\n\n    case 'file':\n      // Render images inline, other files as download links\n      if (part.mediaType.startsWith('image/')) {\n        return (\n          <img\n            src={part.url}\n            alt={part.filename || 'Generated image'}\n            className=\"max-w-full rounded-lg\"\n          />\n        );\n      }\n      return (\n        <a href={part.url} className=\"text-blue-500 text-sm underline\">\n          📄 {part.filename || 'Download file'}\n        </a>\n      );\n\n    case 'object':\n      // For structured output, render custom UI based on typeName\n      // See Structured Output guide for more details\n      return <ObjectPartRenderer part={part} />;\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, fetch messages from your backend and pass them to the hook:\n\n```tsx\nimport { useMemo } from 'react';\nimport { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';\n\ninterface ChatProps {\n  sessionId: string;\n  initialMessages: UIMessage[];\n}\n\nfunction Chat({ sessionId, initialMessages }: ChatProps) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  // Pass existing messages to restore the conversation\n  const { messages } = useOctavusChat({\n    transport,\n    initialMessages,\n  });\n\n  // ...\n}\n```\n\nOn your backend, use `agentSessions.getMessages()` to fetch UI-ready messages:\n\n```typescript\n// Server-side\nconst session = await client.agentSessions.getMessages(sessionId);\n// session.messages is UIMessage[] ready for the client\n```\n\n## Callbacks\n\n```tsx\nuseOctavusChat({\n  transport,\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
       },
@@ -214,7 +214,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## Agent Formats\n\nOctavus supports two agent formats:\n\n| Format        | Use Case                       | Structure                         |\n| ------------- | ------------------------------ | --------------------------------- |\n| `interactive` | Chat and multi-turn dialogue   | `triggers` + `handlers` + `agent` |\n| `worker`      | Background tasks and pipelines | `steps` + `output`                |\n\n**Interactive agents** handle conversations - they respond to triggers (like user messages) and maintain session state across interactions.\n\n**Worker agents** execute tasks - they run steps sequentially and return an output value. Workers can be called independently or composed into interactive agents.\n\nSee [Workers](/docs/protocol/workers) for the worker protocol reference.\n\n## Interactive 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# MCP servers (remote services and device capabilities)\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\n# Octavus skills (provider-agnostic code execution)\nskills:\n  qr-code:\n    display: description\n    description: Generating QR codes\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  mcpServers: [figma] # Enable MCP servers\n  skills: [qr-code] # Enable skills\n  imageModel: google/gemini-2.5-flash-image # Enable image generation\n  webSearch: true # Enable web search\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      block: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n\n    Respond to user:\n      block: 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 (supports subdirectories)\n│   ├── system.md\n│   ├── user-message.md\n│   └── shared/\n│       ├── company-info.md\n│       └── formatting-rules.md\n└── references/            # On-demand context documents (optional)\n    └── api-guidelines.md\n```\n\nPrompts can be organized in subdirectories. In the protocol, reference nested prompts by their path relative to `prompts/` (without `.md`): `shared/company-info`.\n\nReferences are markdown files with YAML frontmatter that the agent can fetch on demand during execution. See [References](/docs/protocol/references).\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 `worker` (background)   |\n\n## Naming Conventions\n\n- **Slugs**: `lowercase-with-dashes`\n- **Variables**: `UPPERCASE_SNAKE_CASE`\n- **Prompts**: `lowercase-with-dashes.md` (paths use `/` for subdirectories)\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 -->\n\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, the placeholder is kept as-is.\n\n## Prompt Interpolation\n\nInclude other prompts inside a prompt with `{{@path.md}}`:\n\n```markdown\n<!-- prompts/system.md -->\n\nYou are a customer support agent.\n\n{{@shared/company-info.md}}\n\n{{@shared/formatting-rules.md}}\n\nHelp users with their questions.\n```\n\nThe referenced prompt content is inserted before variable interpolation, so variables in included prompts work the same way. Circular references are not allowed and will be caught during validation.\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- [MCP Servers](/docs/protocol/mcp-servers) - Remote services and device capabilities via MCP\n- [Skills](/docs/protocol/skills) - Code execution and knowledge packages\n- [References](/docs/protocol/references) - On-demand context documents\n- [Handlers](/docs/protocol/handlers) - Execution blocks\n- [Agent Config](/docs/protocol/agent-config) - Model and settings\n- [Workers](/docs/protocol/workers) - Worker agent format\n- [Provider Options](/docs/protocol/provider-options) - Provider-specific features\n- [Types](/docs/protocol/types) - Custom type definitions\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## Agent Formats\n\nOctavus supports two agent formats:\n\n| Format        | Use Case                       | Structure                         |\n| ------------- | ------------------------------ | --------------------------------- |\n| `interactive` | Chat and multi-turn dialogue   | `triggers` + `handlers` + `agent` |\n| `worker`      | Background tasks and pipelines | `steps` + `output`                |\n\n**Interactive agents** handle conversations - they respond to triggers (like user messages) and maintain session state across interactions.\n\n**Worker agents** execute tasks - they run steps sequentially and return an output value. Workers can be called independently or composed into interactive agents.\n\nSee [Workers](/docs/protocol/workers) for the worker protocol reference.\n\n## Interactive 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# MCP servers (remote services and device capabilities)\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\n# Octavus skills (provider-agnostic code execution)\nskills:\n  qr-code:\n    display: description\n    description: Generating QR codes\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  mcpServers: [figma] # Enable MCP servers\n  skills: [qr-code] # Enable skills\n  imageModel: google/gemini-2.5-flash-image # Enable image generation\n  webSearch: true # Enable web search\n  todoList: true # Enable structured task tracking\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      block: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n\n    Respond to user:\n      block: 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 (supports subdirectories)\n│   ├── system.md\n│   ├── user-message.md\n│   └── shared/\n│       ├── company-info.md\n│       └── formatting-rules.md\n└── references/            # On-demand context documents (optional)\n    └── api-guidelines.md\n```\n\nPrompts can be organized in subdirectories. In the protocol, reference nested prompts by their path relative to `prompts/` (without `.md`): `shared/company-info`.\n\nReferences are markdown files with YAML frontmatter that the agent can fetch on demand during execution. See [References](/docs/protocol/references).\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 `worker` (background)   |\n\n## Naming Conventions\n\n- **Slugs**: `lowercase-with-dashes`\n- **Variables**: `UPPERCASE_SNAKE_CASE`\n- **Prompts**: `lowercase-with-dashes.md` (paths use `/` for subdirectories)\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 -->\n\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, the placeholder is kept as-is.\n\n## Prompt Interpolation\n\nInclude other prompts inside a prompt with `{{@path.md}}`:\n\n```markdown\n<!-- prompts/system.md -->\n\nYou are a customer support agent.\n\n{{@shared/company-info.md}}\n\n{{@shared/formatting-rules.md}}\n\nHelp users with their questions.\n```\n\nThe referenced prompt content is inserted before variable interpolation, so variables in included prompts work the same way. Circular references are not allowed and will be caught during validation.\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- [MCP Servers](/docs/protocol/mcp-servers) - Remote services and device capabilities via MCP\n- [Skills](/docs/protocol/skills) - Code execution and knowledge packages\n- [References](/docs/protocol/references) - On-demand context documents\n- [Handlers](/docs/protocol/handlers) - Execution blocks\n- [Agent Config](/docs/protocol/agent-config) - Model and settings\n- [Workers](/docs/protocol/workers) - Worker agent format\n- [Provider Options](/docs/protocol/provider-options) - Provider-specific features\n- [Types](/docs/protocol/types) - Custom type definitions\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
       },
@@ -268,7 +268,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  mcpServers: [figma, browser] # MCP server connections\n  skills: [qr-code] # Available skills\n  references: [api-guidelines] # On-demand context documents\n```\n\n## Configuration Options\n\n| Field            | Required | Description                                                                    |\n| ---------------- | -------- | ------------------------------------------------------------------------------ |\n| `model`          | Yes      | Model identifier or variable reference                                         |\n| `backupModel`    | No       | Backup model for automatic failover on provider errors                         |\n| `system`         | Yes      | System prompt filename (without .md)                                           |\n| `input`          | No       | Variables to pass to the system prompt                                         |\n| `tools`          | No       | List of tools the LLM can call                                                 |\n| `mcpServers`     | No       | List of MCP servers to connect (see [MCP Servers](/docs/protocol/mcp-servers)) |\n| `skills`         | No       | List of Octavus skills the LLM can use                                         |\n| `references`     | No       | List of references the LLM can fetch on demand                                 |\n| `sandboxTimeout` | No       | Skill sandbox timeout in ms (default: 5 min, max: 1 hour)                      |\n| `imageModel`     | No       | Image generation model (enables agentic image generation)                      |\n| `webSearch`      | No       | Enable built-in web search tool (provider-agnostic)                            |\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| `cache`          | No       | Prompt caching mode: `auto` (default), `extended`, or `off`                    |\n| `anthropic`      | No       | Anthropic-specific options (tools, skills)                                     |\n\n## Models\n\nSpecify models in `provider/model-id` format. Any model supported by the provider's SDK will work.\n\n### Supported Providers\n\n| Provider  | Format                 | Examples                                                             |\n| --------- | ---------------------- | -------------------------------------------------------------------- |\n| Anthropic | `anthropic/{model-id}` | `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`           |\n| Google    | `google/{model-id}`    | `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash` |\n| OpenAI    | `openai/{model-id}`    | `gpt-5`, `gpt-4o`, `o4-mini`, `o3`, `o3-mini`, `o1`                  |\n\n### Examples\n\n```yaml\n# Anthropic Claude 4.5\nagent:\n  model: anthropic/claude-sonnet-4-5\n\n# Google Gemini 3\nagent:\n  model: google/gemini-3-flash-preview\n\n# OpenAI GPT-5\nagent:\n  model: openai/gpt-5\n\n# OpenAI reasoning models\nagent:\n  model: openai/o3-mini\n```\n\n> **Note**: Model IDs are passed directly to the provider SDK. Check the provider's documentation for the latest available models.\n\n### Dynamic Model Selection\n\nThe model field can also reference an input variable, allowing consumers to choose the model when creating a session:\n\n```yaml\ninput:\n  MODEL:\n    type: string\n    description: The LLM model to use\n\nagent:\n  model: MODEL # Resolved from session input\n  system: system\n```\n\nWhen creating a session, pass the model:\n\n```typescript\nconst sessionId = await client.agentSessions.create('my-agent', {\n  MODEL: 'anthropic/claude-sonnet-4-5',\n});\n```\n\nThis enables:\n\n- **Multi-provider support** - Same agent works with different providers\n- **A/B testing** - Test different models without protocol changes\n- **User preferences** - Let users choose their preferred model\n\nThe model value is validated at runtime to ensure it's in the correct `provider/model-id` format.\n\n> **Note**: When using dynamic models, provider-specific options (like `anthropic:`) may not apply if the model resolves to a different provider.\n\n## Backup Model\n\nConfigure a fallback model that activates automatically when the primary model encounters a transient provider error (rate limits, outages, timeouts):\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  backupModel: openai/gpt-4o\n  system: system\n```\n\nWhen a provider error occurs, the system retries once with the backup model. If the backup also fails, the original error is returned.\n\n**Key behaviors:**\n\n- Only transient provider errors trigger fallback - authentication and validation errors are not retried\n- Provider-specific options (like `anthropic:`) are only forwarded to the backup model if it uses the same provider\n- For streaming responses, fallback only occurs if no content has been sent to the client yet\n\nLike `model`, `backupModel` supports variable references:\n\n```yaml\ninput:\n  BACKUP_MODEL:\n    type: string\n    description: Fallback model for provider errors\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  backupModel: BACKUP_MODEL\n  system: system\n```\n\n> **Tip**: Use a different provider for your backup model (e.g., primary on Anthropic, backup on OpenAI) to maximize resilience against single-provider outages.\n\n## System Prompt\n\nThe system prompt sets the agent's persona and instructions. The `input` field controls which variables are available to the prompt - only variables listed in `input` are interpolated.\n\n```yaml\nagent:\n  system: system # Uses prompts/system.md\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n```\n\nVariables in `input` can come from `protocol.input`, `protocol.resources`, or `protocol.variables`.\n\n### Input Mapping Formats\n\n```yaml\n# Array format (same name)\ninput:\n  - COMPANY_NAME\n  - PRODUCT_NAME\n\n# Array format (rename)\ninput:\n  - CONTEXT: CONVERSATION_SUMMARY  # Prompt sees CONTEXT, value comes from CONVERSATION_SUMMARY\n\n# Object format (rename)\ninput:\n  CONTEXT: CONVERSATION_SUMMARY\n```\n\nThe left side (label) is what the prompt sees. The right side (source) is where the value comes from.\n\n### Example\n\n`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:**\n\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## Prompt Caching\n\nProviders charge less for tokens served from their prompt cache (often 10% of the uncached rate). Octavus exposes a single `cache` field that picks the right retention policy per provider, so the stable prefix of your agent - tools, system prompt, and historical messages - gets billed at the cache-read rate on repeat requests.\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  cache: auto # auto (default) | extended | off\n```\n\n| Mode       | Behavior                                                                      | When to use                                                                                             |\n| ---------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| `auto`     | Short-TTL caching. Default when omitted.                                      | Most agents. Free on all supported providers and pays for itself within the same session.               |\n| `extended` | Long-TTL caching. Trades a higher cache-write cost for much longer residency. | Agents triggered with gaps (daily reports, on-call assistants) where the prefix is reused across hours. |\n| `off`      | No opt-in caching emitted.                                                    | When you explicitly want to skip caching - e.g. debugging a non-deterministic prefix.                   |\n\n### Per-provider behavior\n\nThe `cache` field is provider-agnostic at the protocol level - each provider translates it into its own cache retention policy:\n\n| Provider  | `auto` TTL                | `extended` TTL |\n| --------- | ------------------------- | -------------- |\n| Anthropic | 5 minutes                 | 1 hour         |\n| OpenAI    | in-memory (~5–10 minutes) | 24 hours       |\n| Google    | Implicit (Gemini 2.5+)    | Implicit       |\n\nOn `off`, Octavus emits no explicit cache options. Providers that auto-cache (OpenAI on prefixes ≥ 1,024 tokens, Gemini 2.5+) may still cache transparently - `off` just disables Octavus's opt-in behavior.\n\n### Threads don't inherit\n\nNamed threads (created with `start-thread`) read their own `cache` field independently - they **do not** inherit the agent's cache value:\n\n```yaml\nagent:\n  cache: extended # 1-hour TTL on the main thread\n\nhandlers:\n  summarize:\n    Start summary:\n      block: start-thread\n      thread: summary\n      # No cache field → defaults to 'auto' (5-minute TTL), NOT 'extended'\n      system: summary-system\n```\n\nThis is intentional: named threads are often used for short, one-shot work (summarization, classification) where the long TTL would be wasted. Set `cache` explicitly on `start-thread` when you do want it.\n\n### Cost trade-offs\n\n- **Cache reads** are always much cheaper than uncached input on any provider - caching is effectively free if your prefix is stable.\n- **Cache writes** on Anthropic cost ~1.25× input for `auto` and 2× input for `extended`. OpenAI and Google don't charge separately for cache writes.\n- Use `extended` only when the same prefix is genuinely reused across sessions that span hours; otherwise the higher write cost dominates the savings.\n\n## Skills\n\nEnable Octavus skills for code execution and file generation:\n\n```yaml\nskills:\n  qr-code:\n    display: description\n    description: Generating QR codes\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  skills: [qr-code] # Enable skills\n  agentic: true\n```\n\nSkills provide provider-agnostic code execution in isolated sandboxes. When enabled, the LLM can execute Python/Bash code, run skill scripts, and generate files.\n\nSee [Skills](/docs/protocol/skills) for full documentation.\n\n## References\n\nEnable on-demand context loading via reference documents:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  references: [api-guidelines, error-codes]\n  agentic: true\n```\n\nReferences are markdown files stored in the agent's `references/` directory. When enabled, the LLM can list available references and read their content using `octavus_reference_list` and `octavus_reference_read` tools.\n\nSee [References](/docs/protocol/references) for full documentation.\n\n## Image Generation\n\nEnable the LLM to generate images autonomously:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  imageModel: google/gemini-2.5-flash-image\n  agentic: true\n```\n\nWhen `imageModel` is configured, the `octavus_generate_image` tool becomes available. The LLM can decide when to generate images based on user requests. The tool supports both text-to-image generation and image editing/transformation using reference images.\n\n### Supported Image Providers\n\n| Provider | Model Types                             | Examples                                                  |\n| -------- | --------------------------------------- | --------------------------------------------------------- |\n| OpenAI   | Dedicated image models                  | `gpt-image-1`                                             |\n| Google   | Gemini native (contains \"image\")        | `gemini-2.5-flash-image`, `gemini-3-flash-image-generate` |\n| Google   | Imagen dedicated (starts with \"imagen\") | `imagen-4.0-generate-001`                                 |\n\n> **Note**: Google has two image generation approaches. Gemini \"native\" models (containing \"image\" in the ID) generate images using the language model API with `responseModalities`. Imagen models (starting with \"imagen\") use a dedicated image generation API.\n\n### Image Sizes\n\nThe tool supports three image sizes:\n\n- `1024x1024` (default) - Square\n- `1792x1024` - Landscape (16:9)\n- `1024x1792` - Portrait (9:16)\n\n### Image Editing with Reference Images\n\nBoth the agentic tool and the `generate-image` block support reference images for editing and transformation. When reference images are provided, the prompt describes how to modify or use those images.\n\n| Provider | Models                           | Reference Image Support |\n| -------- | -------------------------------- | ----------------------- |\n| OpenAI   | `gpt-image-1`                    | Yes                     |\n| Google   | Gemini native (`gemini-*-image`) | Yes                     |\n| Google   | Imagen (`imagen-*`)              | No                      |\n\n### Agentic vs Deterministic\n\nUse `imageModel` in agent config when:\n\n- The LLM should decide when to generate or edit images\n- Users ask for images in natural language\n\nUse `generate-image` block (see [Handlers](/docs/protocol/handlers#generate-image)) when:\n\n- You want explicit control over image generation or editing\n- Building prompt engineering pipelines\n- Images are generated at specific handler steps\n\n## Web Search\n\nEnable the LLM to search the web for current information:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  webSearch: true\n  agentic: true\n```\n\nWhen `webSearch` is enabled, the `octavus_web_search` tool becomes available. The LLM can decide when to search the web based on the conversation. Search results include source URLs that are emitted as citations in the UI.\n\nThis is a **provider-agnostic** built-in tool - it works with any LLM provider (Anthropic, Google, OpenAI, etc.). For Anthropic's own web search implementation, see [Provider Options](/docs/protocol/provider-options).\n\nUse cases:\n\n- Current events and real-time data\n- Fact verification and documentation lookups\n- Any information that may have changed since the model's training\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\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## Provider Options\n\nEnable provider-specific features like Anthropic's built-in tools and skills:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  anthropic:\n    tools:\n      web-search:\n        display: description\n        description: Searching the web\n    skills:\n      pdf:\n        type: anthropic\n        description: Processing PDF\n```\n\nProvider options are validated against the model - using `anthropic:` with a non-Anthropic model will fail validation.\n\nSee [Provider Options](/docs/protocol/provider-options) for full documentation.\n\n## Thread-Specific Config\n\nOverride config for named threads:\n\n```yaml\nhandlers:\n  request-human:\n    Start summary thread:\n      block: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5 # Different model\n      backupModel: openai/gpt-4o # Failover model\n      thinking: low # Different thinking\n      cache: off # Different cache mode (does not inherit from agent)\n      maxSteps: 1 # Limit tool calls\n      system: escalation-summary # Different prompt\n      mcpServers: [figma, browser] # Thread-specific MCP servers\n      skills: [data-analysis] # Thread-specific skills\n      references: [escalation-policy] # Thread-specific references\n      imageModel: google/gemini-2.5-flash-image # Thread-specific image model\n      webSearch: true # Thread-specific web search\n```\n\nEach thread can have its own model, backup model, cache mode, MCP servers, skills, references, image model, and web search setting. Skills must be defined in the protocol's `skills:` section. References must exist in the agent's `references/` directory. Workers use this same pattern since they don't have a global `agent:` section.\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\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\nskills:\n  qr-code:\n    display: description\n    description: Generating QR codes\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  backupModel: openai/gpt-4o\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  mcpServers: [figma] # MCP server connections\n  skills: [qr-code] # Octavus skills\n  references: [support-policies] # On-demand context\n  webSearch: true # Built-in web search\n  agentic: true\n  maxSteps: 10\n  thinking: medium\n  # Anthropic-specific options\n  anthropic:\n    tools:\n      web-search:\n        display: description\n        description: Searching the web\n    skills:\n      pdf:\n        type: anthropic\n        description: Processing PDF\n\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\nhandlers:\n  user-message:\n    Add message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n\n    Respond:\n      block: next-message\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  mcpServers: [figma, browser] # MCP server connections\n  skills: [qr-code] # Available skills\n  references: [api-guidelines] # On-demand context documents\n```\n\n## Configuration Options\n\n| Field            | Required | Description                                                                    |\n| ---------------- | -------- | ------------------------------------------------------------------------------ |\n| `model`          | Yes      | Model identifier or variable reference                                         |\n| `backupModel`    | No       | Backup model for automatic failover on provider errors                         |\n| `system`         | Yes      | System prompt filename (without .md)                                           |\n| `input`          | No       | Variables to pass to the system prompt                                         |\n| `tools`          | No       | List of tools the LLM can call                                                 |\n| `mcpServers`     | No       | List of MCP servers to connect (see [MCP Servers](/docs/protocol/mcp-servers)) |\n| `skills`         | No       | List of Octavus skills the LLM can use                                         |\n| `references`     | No       | List of references the LLM can fetch on demand                                 |\n| `sandboxTimeout` | No       | Skill sandbox timeout in ms (default: 5 min, max: 1 hour)                      |\n| `imageModel`     | No       | Image generation model (enables agentic image generation)                      |\n| `webSearch`      | No       | Enable built-in web search tool (provider-agnostic)                            |\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| `cache`          | No       | Prompt caching mode: `auto` (default), `extended`, or `off`                    |\n| `anthropic`      | No       | Anthropic-specific options (tools, skills)                                     |\n\n## Models\n\nSpecify models in `provider/model-id` format. Any model supported by the provider's SDK will work.\n\n### Supported Providers\n\n| Provider  | Format                 | Examples                                                                                           |\n| --------- | ---------------------- | -------------------------------------------------------------------------------------------------- |\n| Anthropic | `anthropic/{model-id}` | `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-sonnet-4-5`, `claude-haiku-4-5` |\n| Google    | `google/{model-id}`    | `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash`                               |\n| OpenAI    | `openai/{model-id}`    | `gpt-5`, `gpt-4o`, `o4-mini`, `o3`, `o3-mini`, `o1`                                                |\n\n### Examples\n\n```yaml\n# Anthropic Claude 4.5\nagent:\n  model: anthropic/claude-sonnet-4-5\n\n# Google Gemini 3\nagent:\n  model: google/gemini-3-flash-preview\n\n# OpenAI GPT-5\nagent:\n  model: openai/gpt-5\n\n# OpenAI reasoning models\nagent:\n  model: openai/o3-mini\n```\n\n> **Note**: Model IDs are passed directly to the provider SDK. Check the provider's documentation for the latest available models.\n\n### Dynamic Model Selection\n\nThe model field can also reference an input variable, allowing consumers to choose the model when creating a session:\n\n```yaml\ninput:\n  MODEL:\n    type: string\n    description: The LLM model to use\n\nagent:\n  model: MODEL # Resolved from session input\n  system: system\n```\n\nWhen creating a session, pass the model:\n\n```typescript\nconst sessionId = await client.agentSessions.create('my-agent', {\n  MODEL: 'anthropic/claude-sonnet-4-5',\n});\n```\n\nThis enables:\n\n- **Multi-provider support** - Same agent works with different providers\n- **A/B testing** - Test different models without protocol changes\n- **User preferences** - Let users choose their preferred model\n\nThe model value is validated at runtime to ensure it's in the correct `provider/model-id` format.\n\n> **Note**: When using dynamic models, provider-specific options (like `anthropic:`) may not apply if the model resolves to a different provider.\n\n## Backup Model\n\nConfigure a fallback model that activates automatically when the primary model encounters a transient provider error (rate limits, outages, timeouts):\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  backupModel: openai/gpt-4o\n  system: system\n```\n\nWhen a provider error occurs, the system retries once with the backup model. If the backup also fails, the original error is returned.\n\n**Key behaviors:**\n\n- Only transient provider errors trigger fallback - authentication and validation errors are not retried\n- Provider-specific options (like `anthropic:`) are only forwarded to the backup model if it uses the same provider\n- For streaming responses, fallback only occurs if no content has been sent to the client yet\n\nLike `model`, `backupModel` supports variable references:\n\n```yaml\ninput:\n  BACKUP_MODEL:\n    type: string\n    description: Fallback model for provider errors\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  backupModel: BACKUP_MODEL\n  system: system\n```\n\n> **Tip**: Use a different provider for your backup model (e.g., primary on Anthropic, backup on OpenAI) to maximize resilience against single-provider outages.\n\n## System Prompt\n\nThe system prompt sets the agent's persona and instructions. The `input` field controls which variables are available to the prompt - only variables listed in `input` are interpolated.\n\n```yaml\nagent:\n  system: system # Uses prompts/system.md\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n```\n\nVariables in `input` can come from `protocol.input`, `protocol.resources`, or `protocol.variables`.\n\n### Input Mapping Formats\n\n```yaml\n# Array format (same name)\ninput:\n  - COMPANY_NAME\n  - PRODUCT_NAME\n\n# Array format (rename)\ninput:\n  - CONTEXT: CONVERSATION_SUMMARY  # Prompt sees CONTEXT, value comes from CONVERSATION_SUMMARY\n\n# Object format (rename)\ninput:\n  CONTEXT: CONVERSATION_SUMMARY\n```\n\nThe left side (label) is what the prompt sees. The right side (source) is where the value comes from.\n\n### Example\n\n`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:**\n\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    | Use Case            |\n| -------- | ------------------- |\n| `low`    | Simple reasoning    |\n| `medium` | Moderate complexity |\n| `high`   | Complex analysis    |\n\nThinking content streams to the UI and can be displayed to users.\n\n### How levels are applied\n\nEach provider translates `thinking` into its own reasoning controls:\n\n| Provider                                                                   | Level mapping                                                                                     |\n| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| Anthropic 4.6+ (`claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`) | Adaptive thinking - the model decides how much to reason, guided by `effort: low / medium / high` |\n| Anthropic older (4.5 and earlier)                                          | Fixed token budgets: `low` ~5,000, `medium` ~10,000, `high` ~20,000                               |\n| OpenAI (GPT-5.x, o-series)                                                 | `reasoningEffort: low / medium / high`                                                            |\n| Google (Gemini 3.x)                                                        | `thinkingLevel: low / high` (`medium` rounds up to `high`)                                        |\n| Google (Gemini 1.x / 2.x)                                                  | Token budgets: `low` 1,024, `medium` 8,192, `high` 24,576                                         |\n| OpenRouter                                                                 | Unified `reasoning.max_tokens` (translated upstream)                                              |\n| Vercel AI Gateway                                                          | Forwards the underlying provider's options                                                        |\n\n## Prompt Caching\n\nProviders charge less for tokens served from their prompt cache (often 10% of the uncached rate). Octavus exposes a single `cache` field that picks the right retention policy per provider, so the stable prefix of your agent - tools, system prompt, and historical messages - gets billed at the cache-read rate on repeat requests.\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  cache: auto # auto (default) | extended | off\n```\n\n| Mode       | Behavior                                                                      | When to use                                                                                             |\n| ---------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| `auto`     | Short-TTL caching. Default when omitted.                                      | Most agents. Free on all supported providers and pays for itself within the same session.               |\n| `extended` | Long-TTL caching. Trades a higher cache-write cost for much longer residency. | Agents triggered with gaps (daily reports, on-call assistants) where the prefix is reused across hours. |\n| `off`      | No opt-in caching emitted.                                                    | When you explicitly want to skip caching - e.g. debugging a non-deterministic prefix.                   |\n\n### Per-provider behavior\n\nThe `cache` field is provider-agnostic at the protocol level - each provider translates it into its own cache retention policy:\n\n| Provider  | `auto` TTL                | `extended` TTL |\n| --------- | ------------------------- | -------------- |\n| Anthropic | 5 minutes                 | 1 hour         |\n| OpenAI    | in-memory (~5–10 minutes) | 24 hours       |\n| Google    | Implicit (Gemini 2.5+)    | Implicit       |\n\nOn `off`, Octavus emits no explicit cache options. Providers that auto-cache (OpenAI on prefixes ≥ 1,024 tokens, Gemini 2.5+) may still cache transparently - `off` just disables Octavus's opt-in behavior.\n\n### Threads don't inherit\n\nNamed threads (created with `start-thread`) read their own `cache` field independently - they **do not** inherit the agent's cache value:\n\n```yaml\nagent:\n  cache: extended # 1-hour TTL on the main thread\n\nhandlers:\n  summarize:\n    Start summary:\n      block: start-thread\n      thread: summary\n      # No cache field → defaults to 'auto' (5-minute TTL), NOT 'extended'\n      system: summary-system\n```\n\nThis is intentional: named threads are often used for short, one-shot work (summarization, classification) where the long TTL would be wasted. Set `cache` explicitly on `start-thread` when you do want it.\n\n### Cost trade-offs\n\n- **Cache reads** are always much cheaper than uncached input on any provider - caching is effectively free if your prefix is stable.\n- **Cache writes** on Anthropic cost ~1.25× input for `auto` and 2× input for `extended`. OpenAI and Google don't charge separately for cache writes.\n- Use `extended` only when the same prefix is genuinely reused across sessions that span hours; otherwise the higher write cost dominates the savings.\n\n## Skills\n\nEnable Octavus skills for code execution and file generation:\n\n```yaml\nskills:\n  qr-code:\n    display: description\n    description: Generating QR codes\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  skills: [qr-code] # Enable skills\n  agentic: true\n```\n\nSkills provide provider-agnostic code execution in isolated sandboxes. When enabled, the LLM can execute Python/Bash code, run skill scripts, and generate files.\n\nSee [Skills](/docs/protocol/skills) for full documentation.\n\n## References\n\nEnable on-demand context loading via reference documents:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  references: [api-guidelines, error-codes]\n  agentic: true\n```\n\nReferences are markdown files stored in the agent's `references/` directory. When enabled, the LLM can list available references and read their content using `octavus_reference_list` and `octavus_reference_read` tools.\n\nSee [References](/docs/protocol/references) for full documentation.\n\n## Image Generation\n\nEnable the LLM to generate images autonomously:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  imageModel: google/gemini-2.5-flash-image\n  agentic: true\n```\n\nWhen `imageModel` is configured, the `octavus_generate_image` tool becomes available. The LLM can decide when to generate images based on user requests. The tool supports both text-to-image generation and image editing/transformation using reference images.\n\n### Supported Image Providers\n\n| Provider | Model Types                             | Examples                                                  |\n| -------- | --------------------------------------- | --------------------------------------------------------- |\n| OpenAI   | Dedicated image models                  | `gpt-image-1`                                             |\n| Google   | Gemini native (contains \"image\")        | `gemini-2.5-flash-image`, `gemini-3-flash-image-generate` |\n| Google   | Imagen dedicated (starts with \"imagen\") | `imagen-4.0-generate-001`                                 |\n\n> **Note**: Google has two image generation approaches. Gemini \"native\" models (containing \"image\" in the ID) generate images using the language model API with `responseModalities`. Imagen models (starting with \"imagen\") use a dedicated image generation API.\n\n### Image Sizes\n\nThe tool supports three image sizes:\n\n- `1024x1024` (default) - Square\n- `1792x1024` - Landscape (16:9)\n- `1024x1792` - Portrait (9:16)\n\n### Image Editing with Reference Images\n\nBoth the agentic tool and the `generate-image` block support reference images for editing and transformation. When reference images are provided, the prompt describes how to modify or use those images.\n\n| Provider | Models                           | Reference Image Support |\n| -------- | -------------------------------- | ----------------------- |\n| OpenAI   | `gpt-image-1`                    | Yes                     |\n| Google   | Gemini native (`gemini-*-image`) | Yes                     |\n| Google   | Imagen (`imagen-*`)              | No                      |\n\n### Agentic vs Deterministic\n\nUse `imageModel` in agent config when:\n\n- The LLM should decide when to generate or edit images\n- Users ask for images in natural language\n\nUse `generate-image` block (see [Handlers](/docs/protocol/handlers#generate-image)) when:\n\n- You want explicit control over image generation or editing\n- Building prompt engineering pipelines\n- Images are generated at specific handler steps\n\n## Web Search\n\nEnable the LLM to search the web for current information:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  webSearch: true\n  agentic: true\n```\n\nWhen `webSearch` is enabled, the `octavus_web_search` tool becomes available. The LLM can decide when to search the web based on the conversation. Search results include source URLs that are emitted as citations in the UI.\n\nThis is a **provider-agnostic** built-in tool - it works with any LLM provider (Anthropic, Google, OpenAI, etc.). For Anthropic's own web search implementation, see [Provider Options](/docs/protocol/provider-options).\n\nUse cases:\n\n- Current events and real-time data\n- Fact verification and documentation lookups\n- Any information that may have changed since the model's training\n\n## TODO List\n\nEnable the LLM to maintain a structured task list while it works:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  todoList: true\n  agentic: true\n```\n\nWhen `todoList` is enabled, the `octavus_todo_write` tool becomes available. The LLM creates and updates a list of items - each with `id`, `content`, and `status` (`pending`, `in_progress`, `completed`, `cancelled`) - and the platform emits a `todo-update` stream event with the resolved snapshot. The Client SDK accumulates updates into a single `UITodoPart` per assistant message, so consumers render an evolving \"Plan\" card without managing state themselves.\n\nThe list persists across messages: the LLM can use `merge=true` to update items by id (sending only the changed fields), or `merge=false` to replace the list entirely.\n\nUse cases:\n\n- Multi-step tasks where the user benefits from seeing progress\n- Long-running agentic loops that should communicate intent\n- Workflows where the agent plans before acting\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\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## Provider Options\n\nEnable provider-specific features like Anthropic's built-in tools and skills:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  anthropic:\n    tools:\n      web-search:\n        display: description\n        description: Searching the web\n    skills:\n      pdf:\n        type: anthropic\n        description: Processing PDF\n```\n\nProvider options are validated against the model - using `anthropic:` with a non-Anthropic model will fail validation.\n\nSee [Provider Options](/docs/protocol/provider-options) for full documentation.\n\n## Thread-Specific Config\n\nOverride config for named threads:\n\n```yaml\nhandlers:\n  request-human:\n    Start summary thread:\n      block: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5 # Different model\n      backupModel: openai/gpt-4o # Failover model\n      thinking: low # Different thinking\n      cache: off # Different cache mode (does not inherit from agent)\n      maxSteps: 1 # Limit tool calls\n      system: escalation-summary # Different prompt\n      mcpServers: [figma, browser] # Thread-specific MCP servers\n      skills: [data-analysis] # Thread-specific skills\n      references: [escalation-policy] # Thread-specific references\n      imageModel: google/gemini-2.5-flash-image # Thread-specific image model\n      webSearch: true # Thread-specific web search\n      todoList: true # Thread-specific task list\n```\n\nEach thread can have its own model, backup model, cache mode, MCP servers, skills, references, image model, web search setting, and task list setting. Skills must be defined in the protocol's `skills:` section. References must exist in the agent's `references/` directory. Workers use this same pattern since they don't have a global `agent:` section.\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\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\nskills:\n  qr-code:\n    display: description\n    description: Generating QR codes\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  backupModel: openai/gpt-4o\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  mcpServers: [figma] # MCP server connections\n  skills: [qr-code] # Octavus skills\n  references: [support-policies] # On-demand context\n  webSearch: true # Built-in web search\n  todoList: true # Structured task tracking\n  agentic: true\n  maxSteps: 10\n  thinking: medium\n  # Anthropic-specific options\n  anthropic:\n    tools:\n      web-search:\n        display: description\n        description: Searching the web\n    skills:\n      pdf:\n        type: anthropic\n        description: Processing PDF\n\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\nhandlers:\n  user-message:\n    Add message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n\n    Respond:\n      block: next-message\n```\n",
         "excerpt": "Agent Config The  section configures the LLM model, system prompt, tools, and behavior.  Basic Configuration  Configuration Options | Field            | Required | Description                        ...",
         "order": 7
       },
@@ -322,7 +322,7 @@
         "section": "protocol",
         "title": "MCP Servers",
         "description": "Connecting agents to external tools via Model Context Protocol (MCP).",
-        "content": "\n# MCP Servers\n\nMCP servers extend your agent with tools from external services. Define them in your protocol, and agents automatically discover and use their tools at runtime.\n\nThere are two types of MCP servers:\n\n| Source   | Description                                                        | Example                        |\n| -------- | ------------------------------------------------------------------ | ------------------------------ |\n| `remote` | HTTP-based MCP servers, managed by the platform                    | Figma, Sentry, GitHub          |\n| `device` | Local MCP servers running on the consumer's machine via server-sdk | Browser automation, filesystem |\n\n## Defining MCP Servers\n\nMCP servers are defined in the `mcpServers:` section. The key becomes the **namespace** for all tools from that server.\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\n  browser:\n    description: Chrome DevTools browser automation\n    source: device\n    display: name\n```\n\n### Fields\n\n| Field         | Required | Description                                                                           |\n| ------------- | -------- | ------------------------------------------------------------------------------------- |\n| `description` | Yes      | What the MCP server provides                                                          |\n| `source`      | Yes      | `remote` (platform-managed) or `device` (consumer-provided)                           |\n| `display`     | No       | How tool calls appear in UI: `hidden`, `name`, `description` (default: `description`) |\n\n### Display Modes\n\nDisplay modes control visibility of all tool calls from the MCP server, using the same modes as [regular tools](/docs/protocol/tools#display-modes):\n\n| Mode          | Behavior                               |\n| ------------- | -------------------------------------- |\n| `hidden`      | Tool calls run silently                |\n| `name`        | Shows tool name while executing        |\n| `description` | Shows tool description while executing |\n\n## Making MCP Servers Available\n\nLike tools, MCP servers defined in `mcpServers:` must be referenced in `agent.mcpServers` to be available:\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\n  sentry:\n    description: Error tracking and debugging\n    source: remote\n    display: name\n\n  browser:\n    description: Chrome DevTools browser automation\n    source: device\n    display: name\n\n  filesystem:\n    description: Filesystem access for reading and writing files\n    source: device\n    display: hidden\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  mcpServers: [figma, sentry, browser, filesystem]\n  tools: [set-chat-title]\n  agentic: true\n  maxSteps: 100\n```\n\n## Tool Namespacing\n\nAll MCP tools are automatically namespaced using `__` (double underscore) as a separator. The namespace comes from the `mcpServers` key.\n\nFor example, a server defined as `browser:` that exposes `navigate_page` and `click` produces:\n\n- `browser__navigate_page`\n- `browser__click`\n\nA server defined as `figma:` that exposes `get_design_context` produces:\n\n- `figma__get_design_context`\n\nThe namespace is stripped before calling the MCP server - the server receives the original tool name. This convention matches Anthropic's MCP integration in Claude Desktop and ensures tool names stay unique across servers.\n\n### What the LLM Sees\n\nWhen an agent has both regular tools and MCP servers configured, the LLM sees all tools combined:\n\n```\nProtocol tools:\n  set-chat-title\n\nRemote MCP tools (auto-discovered):\n  figma__get_design_context\n  figma__get_screenshot\n  sentry__get_issues\n  sentry__get_issue_details\n\nDevice MCP tools (auto-discovered):\n  browser__navigate_page\n  browser__click\n  browser__take_snapshot\n  filesystem__read_file\n  filesystem__write_file\n  filesystem__list_directory\n```\n\nYou don't define individual MCP tool schemas in the protocol - they're auto-discovered from each MCP server at runtime.\n\n## Remote MCP Servers\n\nRemote MCP servers (`source: remote`) connect to HTTP-based MCP endpoints. The platform manages the connection, authentication, and tool discovery.\n\nConfiguration happens in the Octavus platform UI:\n\n1. Add an MCP server to your project (URL + authentication)\n2. The server's slug must match the namespace in your protocol\n3. The platform connects, discovers tools, and makes them available to the agent\n\n### Authentication\n\nRemote MCP servers support multiple authentication methods:\n\n| Auth Type | Description                     |\n| --------- | ------------------------------- |\n| MCP OAuth | Standard MCP OAuth flow         |\n| API Key   | Static API key sent as a header |\n| Bearer    | Bearer token authentication     |\n| None      | No authentication required      |\n\nAuthentication is configured per-project - different projects can connect to the same MCP server with different credentials.\n\n## Device MCP Servers\n\nDevice MCP servers (`source: device`) run on the consumer's machine. The consumer provides the MCP tools via the `@octavus/computer` package (or any `ToolProvider` implementation) through the server-sdk.\n\nWhen an agent has device MCP servers:\n\n1. The consumer creates a `Computer` with matching namespaces\n2. `@octavus/computer` discovers tools from each MCP server\n3. Tool schemas are sent to the platform via the server-sdk\n4. Tool calls flow back to the consumer for execution\n\nSee [`@octavus/computer`](/docs/server-sdk/computer) for the full integration guide.\n\n### Namespace Matching\n\nThe `mcpServers` keys in the protocol must match the keys in the consumer's `Computer` configuration:\n\n```yaml\n# protocol.yaml\nmcpServers:\n  browser: # ← must match\n    source: device\n  filesystem: # ← must match\n    source: device\n```\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', ['--browser-url=...']),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [dir]),\n  },\n});\n```\n\nIf the consumer provides a namespace not declared in the protocol, the platform rejects it.\n\n## Thread-Level Scoping\n\nThreads can scope which MCP servers are available, the same way they scope [tools](/docs/protocol/handlers#start-thread):\n\n```yaml\nhandlers:\n  user-message:\n    Start research:\n      block: start-thread\n      thread: research\n      mcpServers: [figma, browser]\n      tools: [set-chat-title]\n      system: research-prompt\n```\n\nThis thread can use Figma and browser tools, but not sentry or filesystem - even if those are available on the main agent.\n\n## On-Demand MCP Servers\n\nBy default, an agent can only call MCP tools whose namespace is listed in `mcpServers`. With `onDemandMcpServers`, a scope can opt into **every connected MCP of a given source** at runtime, without enumerating each one in the protocol.\n\nRemote MCPs are connected at the project level from the Octavus dashboard. Normally, each connected MCP that the agent should be able to use has to be declared in the protocol - connecting a new MCP means editing the protocol and redeploying. `onDemandMcpServers` removes that round-trip: once a source is opted in, any MCP connected to the project under that source becomes available to the agent immediately.\n\nCurrently supported for `source: remote`.\n\n### Protocol-level declaration\n\nAdd an `onDemandMcpServers:` section alongside `mcpServers:`, keyed by source. Each entry configures how the matched MCPs appear in tool lists:\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\nonDemandMcpServers:\n  remote:\n    description: Additional connected integrations\n    display: name\n    contextRetention:\n      toolResults: { retainLast: 5 }\n```\n\n### Scope-level opt-in\n\nThe agent and individual `start-thread` blocks each choose whether to pick up on-demand MCPs, by listing the sources they want:\n\n```yaml\nagent:\n  mcpServers: [figma]\n  onDemandMcpServers: [remote]\n\nhandlers:\n  user-message:\n    focused:\n      block: start-thread\n      mcpServers: [figma]\n      # no onDemandMcpServers - this thread does NOT see on-demand MCPs\n    broad:\n      block: start-thread\n      mcpServers: [figma]\n      onDemandMcpServers: [remote]\n```\n\n### Rules\n\n- A scope's tool list includes every **connected** MCP of any referenced source, whether or not any protocol declares that slug.\n- Undeclared namespaces inherit `description`, `display`, and `contextRetention` from the per-source entry in `onDemandMcpServers`.\n- Scopes decide independently - threads do not inherit `onDemandMcpServers` from their parent, the same rule as `mcpServers:`.\n- Tool namespaces are always the connector's slug (for example `notion__search`, `linear__create_issue`). Source keys are never namespaces.\n\nWorkers opt into on-demand MCPs the same way: through `start-thread` blocks inside `steps`. A worker without a `start-thread` that lists a source won't see on-demand MCPs of that source.\n\n## Workers\n\nWorkers can declare and use MCP servers using the same `mcpServers:` syntax. Workers resolve their own MCP connections independently - they don't inherit from a parent interactive agent.\n\n```yaml\n# Worker protocol\nmcpServers:\n  sentry:\n    description: Error tracking and debugging\n    source: remote\n    display: name\n  browser:\n    description: Chrome DevTools browser automation\n    source: device\n    display: name\n\nsteps:\n  Start research:\n    block: start-thread\n    thread: research\n    model: anthropic/claude-sonnet-4-5\n    system: system\n    mcpServers: [sentry, browser]\n    maxSteps: 10\n```\n\nSince workers don't have a global `agent:` section, MCP servers are scoped per-thread via `start-thread` - the same way tools and skills work in workers. Remote MCP connections are project-scoped, so workers in the same project share the same OAuth connections.\n\nSee [Workers](/docs/protocol/workers) for the full worker protocol reference.\n\n## Full Example\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n  sentry:\n    description: Error tracking and debugging\n    source: remote\n    display: name\n  browser:\n    description: Chrome DevTools browser automation\n    source: device\n    display: name\n  filesystem:\n    description: Filesystem access for reading and writing files\n    source: device\n    display: hidden\n  shell:\n    description: Shell command execution\n    source: device\n    display: name\n\ntools:\n  set-chat-title:\n    description: Set the title of the current chat.\n    parameters:\n      title: { type: string, description: The title to set }\n\nagent:\n  model: anthropic/claude-opus-4-6\n  system: system\n  mcpServers: [figma, sentry, browser, filesystem, shell]\n  tools: [set-chat-title]\n  thinking: medium\n  maxSteps: 300\n  agentic: true\n\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\nhandlers:\n  user-message:\n    Add message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n\n    Respond:\n      block: next-message\n```\n\n### Cloud-Only Agent\n\nAgents that only use remote MCP servers don't need `@octavus/computer`:\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n  sentry:\n    description: Error tracking and debugging\n    source: remote\n    display: name\n\ntools:\n  submit-code:\n    description: Submit code to the user.\n    parameters:\n      code: { type: string }\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  mcpServers: [figma, sentry]\n  tools: [submit-code]\n  agentic: true\n```\n",
+        "content": "\n# MCP Servers\n\nMCP servers extend your agent with tools from external services. Define them in your protocol, and agents automatically discover and use their tools at runtime.\n\nThere are two types of MCP servers:\n\n| Source   | Description                                                        | Example                        |\n| -------- | ------------------------------------------------------------------ | ------------------------------ |\n| `remote` | HTTP-based MCP servers, managed by the platform                    | Figma, Sentry, GitHub          |\n| `device` | Local MCP servers running on the consumer's machine via server-sdk | Browser automation, filesystem |\n\n## Defining MCP Servers\n\nMCP servers are defined in the `mcpServers:` section. The key becomes the **namespace** for all tools from that server.\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\n  browser:\n    description: Chrome DevTools browser automation\n    source: device\n    display: name\n```\n\n### Fields\n\n| Field         | Required | Description                                                                           |\n| ------------- | -------- | ------------------------------------------------------------------------------------- |\n| `description` | Yes      | What the MCP server provides                                                          |\n| `source`      | Yes      | `remote` (platform-managed) or `device` (consumer-provided)                           |\n| `display`     | No       | How tool calls appear in UI: `hidden`, `name`, `description` (default: `description`) |\n| `connection`  | No       | When to connect: `eager` or `lazy` (default: `lazy`). Remote only.                    |\n\n### Display Modes\n\nDisplay modes control visibility of all tool calls from the MCP server, using the same modes as [regular tools](/docs/protocol/tools#display-modes):\n\n| Mode          | Behavior                               |\n| ------------- | -------------------------------------- |\n| `hidden`      | Tool calls run silently                |\n| `name`        | Shows tool name while executing        |\n| `description` | Shows tool description while executing |\n\n## Making MCP Servers Available\n\nLike tools, MCP servers defined in `mcpServers:` must be referenced in `agent.mcpServers` to be available:\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\n  sentry:\n    description: Error tracking and debugging\n    source: remote\n    display: name\n\n  browser:\n    description: Chrome DevTools browser automation\n    source: device\n    display: name\n\n  filesystem:\n    description: Filesystem access for reading and writing files\n    source: device\n    display: hidden\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  mcpServers: [figma, sentry, browser, filesystem]\n  tools: [set-chat-title]\n  agentic: true\n  maxSteps: 100\n```\n\n## Tool Namespacing\n\nAll MCP tools are automatically namespaced using `__` (double underscore) as a separator. The namespace comes from the `mcpServers` key.\n\nFor example, a server defined as `browser:` that exposes `navigate_page` and `click` produces:\n\n- `browser__navigate_page`\n- `browser__click`\n\nA server defined as `figma:` that exposes `get_design_context` produces:\n\n- `figma__get_design_context`\n\nThe namespace is stripped before calling the MCP server - the server receives the original tool name. This convention matches Anthropic's MCP integration in Claude Desktop and ensures tool names stay unique across servers.\n\n### What the LLM Sees\n\nWhen an agent has both regular tools and MCP servers configured, the LLM sees all tools combined:\n\n```\nProtocol tools:\n  set-chat-title\n\nRemote MCP tools (auto-discovered):\n  figma__get_design_context\n  figma__get_screenshot\n  sentry__get_issues\n  sentry__get_issue_details\n\nDevice MCP tools (auto-discovered):\n  browser__navigate_page\n  browser__click\n  browser__take_snapshot\n  filesystem__read_file\n  filesystem__write_file\n  filesystem__list_directory\n```\n\nYou don't define individual MCP tool schemas in the protocol - they're auto-discovered from each MCP server at runtime.\n\n## Remote MCP Servers\n\nRemote MCP servers (`source: remote`) connect to HTTP-based MCP endpoints. The platform manages the connection, authentication, and tool discovery.\n\nConfiguration happens in the Octavus platform UI:\n\n1. Add an MCP server to your project (URL + authentication)\n2. The server's slug must match the namespace in your protocol\n3. The platform connects, discovers tools, and makes them available to the agent\n\n### Connection Modes\n\nThe `connection` field controls when the platform connects to a remote MCP server:\n\n| Mode    | Behavior                                                                                                               |\n| ------- | ---------------------------------------------------------------------------------------------------------------------- |\n| `lazy`  | (default) The agent activates integrations on demand at runtime. The agent starts responding immediately.              |\n| `eager` | The platform connects and discovers tools before the first LLM request. Tools are guaranteed available from message 1. |\n\n```yaml\nmcpServers:\n  sentry:\n    source: remote\n    connection: eager # Always connected upfront\n    display: name\n\n  notion:\n    source: remote\n    # connection defaults to lazy - agent activates when needed\n    display: description\n```\n\nWith **lazy connection** (the default), the agent receives two built-in tools - one for listing available integrations and one for activating them. The agent decides which integrations it needs based on the conversation and activates them on demand. This avoids paying connection latency for integrations the agent doesn't end up using.\n\nWith **eager connection**, the platform connects to the MCP server before the first LLM request, exactly like a declared tool. Use this when the agent needs the MCP's tools from the very first message.\n\nThe `connection` field is only valid on `source: remote` - device MCPs have their own connection mechanism through the server-sdk.\n\n### Authentication\n\nRemote MCP servers support multiple authentication methods:\n\n| Auth Type | Description                     |\n| --------- | ------------------------------- |\n| MCP OAuth | Standard MCP OAuth flow         |\n| API Key   | Static API key sent as a header |\n| Bearer    | Bearer token authentication     |\n| None      | No authentication required      |\n\nAuthentication is configured per-project - different projects can connect to the same MCP server with different credentials.\n\n## Device MCP Servers\n\nDevice MCP servers (`source: device`) run on the consumer's machine. The consumer provides the MCP tools via the `@octavus/computer` package (or any `ToolProvider` implementation) through the server-sdk.\n\nWhen an agent has device MCP servers:\n\n1. The consumer creates a `Computer` with matching namespaces\n2. `@octavus/computer` discovers tools from each MCP server\n3. Tool schemas are sent to the platform via the server-sdk\n4. Tool calls flow back to the consumer for execution\n\nSee [`@octavus/computer`](/docs/server-sdk/computer) for the full integration guide.\n\n### Namespace Matching\n\nThe `mcpServers` keys in the protocol must match the keys in the consumer's `Computer` configuration:\n\n```yaml\n# protocol.yaml\nmcpServers:\n  browser: # ← must match\n    source: device\n  filesystem: # ← must match\n    source: device\n```\n\n```typescript\nconst computer = new Computer({\n  mcpServers: {\n    browser: Computer.stdio('chrome-devtools-mcp', ['--browser-url=...']),\n    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [dir]),\n  },\n});\n```\n\nIf the consumer provides a namespace not declared in the protocol, the platform rejects it.\n\n## Thread-Level Scoping\n\nThreads can scope which MCP servers are available, the same way they scope [tools](/docs/protocol/handlers#start-thread):\n\n```yaml\nhandlers:\n  user-message:\n    Start research:\n      block: start-thread\n      thread: research\n      mcpServers: [figma, browser]\n      tools: [set-chat-title]\n      system: research-prompt\n```\n\nThis thread can use Figma and browser tools, but not sentry or filesystem - even if those are available on the main agent.\n\n## On-Demand MCP Servers\n\nBy default, an agent can only call MCP tools whose namespace is listed in `mcpServers`. With `onDemandMcpServers`, a scope can opt into **every connected MCP of a given source** at runtime, without enumerating each one in the protocol.\n\nRemote MCPs are connected at the project level from the Octavus dashboard. Normally, each connected MCP that the agent should be able to use has to be declared in the protocol - connecting a new MCP means editing the protocol and redeploying. `onDemandMcpServers` removes that round-trip: once a source is opted in, any MCP connected to the project under that source becomes available to the agent immediately.\n\nCurrently supported for `source: remote`.\n\n### Protocol-level declaration\n\nAdd an `onDemandMcpServers:` section alongside `mcpServers:`, keyed by source. Each entry configures how the matched MCPs appear in tool lists:\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    display: description\n\nonDemandMcpServers:\n  remote:\n    description: Additional connected integrations\n    display: name\n    contextRetention:\n      toolResults: { retainLast: 5 }\n```\n\n### Scope-level opt-in\n\nThe agent and individual `start-thread` blocks each choose whether to pick up on-demand MCPs, by listing the sources they want:\n\n```yaml\nagent:\n  mcpServers: [figma]\n  onDemandMcpServers: [remote]\n\nhandlers:\n  user-message:\n    focused:\n      block: start-thread\n      mcpServers: [figma]\n      # no onDemandMcpServers - this thread does NOT see on-demand MCPs\n    broad:\n      block: start-thread\n      mcpServers: [figma]\n      onDemandMcpServers: [remote]\n```\n\n### Rules\n\n- A scope's tool list includes every **connected** MCP of any referenced source, whether or not any protocol declares that slug.\n- Undeclared namespaces inherit `description`, `display`, and `contextRetention` from the per-source entry in `onDemandMcpServers`.\n- Scopes decide independently - threads do not inherit `onDemandMcpServers` from their parent, the same rule as `mcpServers:`.\n- Tool namespaces are always the connector's slug (for example `notion__search`, `linear__create_issue`). Source keys are never namespaces.\n\nWorkers opt into on-demand MCPs the same way: through `start-thread` blocks inside `steps`. A worker without a `start-thread` that lists a source won't see on-demand MCPs of that source.\n\n## Workers\n\nWorkers can declare and use MCP servers using the same `mcpServers:` syntax. Workers resolve their own MCP connections independently - they don't inherit from a parent interactive agent.\n\n```yaml\n# Worker protocol\nmcpServers:\n  sentry:\n    description: Error tracking and debugging\n    source: remote\n    display: name\n  browser:\n    description: Chrome DevTools browser automation\n    source: device\n    display: name\n\nsteps:\n  Start research:\n    block: start-thread\n    thread: research\n    model: anthropic/claude-sonnet-4-5\n    system: system\n    mcpServers: [sentry, browser]\n    maxSteps: 10\n```\n\nSince workers don't have a global `agent:` section, MCP servers are scoped per-thread via `start-thread` - the same way tools and skills work in workers. Remote MCP connections are project-scoped, so workers in the same project share the same OAuth connections.\n\nSee [Workers](/docs/protocol/workers) for the full worker protocol reference.\n\n## Full Example\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    connection: eager\n    display: description\n  sentry:\n    description: Error tracking and debugging\n    source: remote\n    display: name\n  browser:\n    description: Chrome DevTools browser automation\n    source: device\n    display: name\n  filesystem:\n    description: Filesystem access for reading and writing files\n    source: device\n    display: hidden\n  shell:\n    description: Shell command execution\n    source: device\n    display: name\n\ntools:\n  set-chat-title:\n    description: Set the title of the current chat.\n    parameters:\n      title: { type: string, description: The title to set }\n\nagent:\n  model: anthropic/claude-opus-4-6\n  system: system\n  mcpServers: [figma, sentry, browser, filesystem, shell]\n  tools: [set-chat-title]\n  thinking: medium\n  maxSteps: 300\n  agentic: true\n\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE: { type: string }\n\nhandlers:\n  user-message:\n    Add message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n\n    Respond:\n      block: next-message\n```\n\n### Cloud-Only Agent\n\nAgents that only use remote MCP servers don't need `@octavus/computer`:\n\n```yaml\nmcpServers:\n  figma:\n    description: Figma design tool integration\n    source: remote\n    connection: eager # Need design tools from message 1\n    display: description\n  sentry:\n    description: Error tracking and debugging\n    source: remote\n    # Lazy (default) - agent activates when debugging is needed\n    display: name\n\ntools:\n  submit-code:\n    description: Submit code to the user.\n    parameters:\n      code: { type: string }\n\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  mcpServers: [figma, sentry]\n  tools: [submit-code]\n  agentic: true\n```\n",
         "excerpt": "MCP Servers MCP servers extend your agent with tools from external services. Define them in your protocol, and agents automatically discover and use their tools at runtime. There are two types of MCP...",
         "order": 13
       }

package/package.json

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