@octavus/docs 2.5.0 → 2.7.0

package/dist/content.js

@@ -5,7 +5,7 @@ import {
   getDocSlugs,
   getDocsData,
   getSectionBySlug
-} from "./chunk-RI24MRSN.js";
+} from "./chunk-YS5UYKHB.js";
 export {
   getAllDocs,
   getDocBySlug,

package/dist/docs.json

@@ -22,7 +22,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:** `2.5.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## API Reference\n\n### OctavusClient\n\nThe main entry point for interacting with Octavus.\n\n```typescript\ninterface OctavusClientConfig {\n  baseUrl: string; // Octavus API URL\n  apiKey?: string; // Your API key\n}\n\nclass OctavusClient {\n  readonly agents: AgentsApi;\n  readonly agentSessions: AgentSessionsApi;\n  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\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",
+    "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:** `2.7.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## API Reference\n\n### OctavusClient\n\nThe main entry point for interacting with Octavus.\n\n```typescript\ninterface OctavusClientConfig {\n  baseUrl: string; // Octavus API URL\n  apiKey?: string; // Your API key\n}\n\nclass OctavusClient {\n  readonly agents: AgentsApi;\n  readonly agentSessions: AgentSessionsApi;\n  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\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",
     "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
   },
@@ -58,7 +58,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:** `2.5.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## 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```\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:** `2.7.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## 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```\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
   },
@@ -76,7 +76,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:** `2.5.0`\n\n### Other Frameworks\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n**Current version:** `2.5.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## 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\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## 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:** `2.7.0`\n\n### Other Frameworks\n\n```bash\nnpm install @octavus/client-sdk\n```\n\n**Current version:** `2.7.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## 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\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## 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
   },
@@ -157,7 +157,7 @@
     "section": "client-sdk",
     "title": "Client Tools",
     "description": "Handling tool calls on the client side for interactive UI and browser-only operations.",
-    "content": "\n# Client Tools\n\nBy default, tools execute on your server where you have access to databases and APIs. However, some tools are better suited for client-side execution:\n\n- **Browser-only operations** — Geolocation, clipboard, local storage\n- **Interactive UIs** — Confirmation dialogs, form inputs, selections\n- **Real-time feedback** — Progress indicators, approval workflows\n\n## How Client Tools Work\n\nWhen the agent calls a tool, the Server SDK checks for a registered handler:\n\n1. **Handler exists** → Execute on server, continue automatically\n2. **No handler** → Forward to client as `client-tool-request` event\n\nThe client SDK receives pending tool calls, executes them (automatically or via user interaction), and sends results back to continue the conversation.\n\n```mermaid\nsequenceDiagram\n    participant LLM\n    participant Platform\n    participant Server as Server SDK\n    participant Client as Client SDK\n    participant User\n\n    LLM->>Platform: Call get-location\n    Platform->>Server: tool-request\n    Note over Server: No handler for<br/>get-location\n    Server->>Client: client-tool-request\n    Client->>User: Request permission\n    User->>Client: Grant\n    Client->>Server: Tool results\n    Server->>Platform: Continue with results\n    Platform->>LLM: Process results\n```\n\n## Setup\n\n### Server Side\n\nDefine tools in your protocol but don't register handlers for client tools:\n\n```typescript\n// Only register server-side tools\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    // Server tools have handlers\n    'get-user-account': async (args) => {\n      return await db.users.findById(args.userId);\n    },\n    // Client tools have NO handler here\n    // 'get-browser-location' - handled on client\n    // 'request-feedback' - handled on client\n  },\n});\n```\n\n### Client Side\n\nRegister client tool handlers when creating the chat:\n\n```typescript\nconst { messages, status, pendingClientTools } = useOctavusChat({\n  transport,\n  clientTools: {\n    // Automatic client tool\n    'get-browser-location': async () => {\n      const pos = await new Promise((resolve, reject) => {\n        navigator.geolocation.getCurrentPosition(resolve, reject);\n      });\n      return { lat: pos.coords.latitude, lng: pos.coords.longitude };\n    },\n\n    // Interactive client tool (requires user action)\n    'request-feedback': 'interactive',\n  },\n});\n```\n\n## Automatic Client Tools\n\nAutomatic tools execute immediately when called. Use these for browser operations that don't require user input.\n\n### Example: Geolocation\n\n```typescript\nconst { messages, status } = useOctavusChat({\n  transport,\n  clientTools: {\n    'get-browser-location': async (args, ctx) => {\n      // ctx provides toolCallId, toolName, and abort signal\n      const pos = await new Promise<GeolocationPosition>((resolve, reject) => {\n        navigator.geolocation.getCurrentPosition(resolve, reject, {\n          timeout: 10000,\n        });\n      });\n\n      return {\n        latitude: pos.coords.latitude,\n        longitude: pos.coords.longitude,\n        accuracy: pos.coords.accuracy,\n      };\n    },\n  },\n});\n```\n\n### Example: Clipboard\n\n```typescript\nclientTools: {\n  'copy-to-clipboard': async (args) => {\n    await navigator.clipboard.writeText(args.text as string);\n    return { success: true };\n  },\n\n  'read-clipboard': async () => {\n    const text = await navigator.clipboard.readText();\n    return { text };\n  },\n}\n```\n\n### Context Object\n\nAutomatic handlers receive a context object:\n\n```typescript\ninterface ClientToolContext {\n  toolCallId: string; // Unique ID for this call\n  toolName: string; // Name of the tool\n  signal: AbortSignal; // Aborted if user stops generation\n}\n```\n\nUse the signal to cancel long-running operations:\n\n```typescript\n'fetch-external-data': async (args, ctx) => {\n  const response = await fetch(args.url, {\n    signal: ctx.signal,  // Cancels if user stops\n  });\n  return await response.json();\n}\n```\n\n## Interactive Client Tools\n\nInteractive tools require user input before completing. Use these for confirmations, forms, or any UI that needs user action.\n\nMark a tool as interactive by setting its handler to `'interactive'`:\n\n```typescript\nconst { messages, status, pendingClientTools } = useOctavusChat({\n  transport,\n  clientTools: {\n    'request-feedback': 'interactive',\n    'confirm-action': 'interactive',\n    'select-option': 'interactive',\n  },\n});\n```\n\n### Accessing Pending Tools\n\nInteractive tools appear in `pendingClientTools`, keyed by tool name:\n\n```typescript\n// pendingClientTools structure:\n{\n  'request-feedback': [\n    {\n      toolCallId: 'call_abc123',\n      toolName: 'request-feedback',\n      args: { question: 'How would you rate this response?' },\n      submit: (result) => void,  // Call with user's input\n      cancel: (reason?) => void, // Call if user dismisses\n    }\n  ],\n  'confirm-action': [\n    // Multiple calls to same tool are possible\n  ]\n}\n```\n\n### Rendering Interactive UIs\n\n```tsx\nfunction Chat() {\n  const { messages, status, pendingClientTools, send } = useOctavusChat({\n    transport,\n    clientTools: {\n      'request-feedback': 'interactive',\n    },\n  });\n\n  const feedbackTools = pendingClientTools['request-feedback'] ?? [];\n\n  return (\n    <div>\n      {/* Chat messages */}\n      <MessageList messages={messages} />\n\n      {/* Interactive tool UIs */}\n      {feedbackTools.map((tool) => (\n        <FeedbackModal\n          key={tool.toolCallId}\n          question={tool.args.question as string}\n          onSubmit={(rating, comment) => {\n            tool.submit({ rating, comment });\n          }}\n          onCancel={() => {\n            tool.cancel('User dismissed');\n          }}\n        />\n      ))}\n\n      {/* Input disabled while awaiting user action */}\n      <ChatInput disabled={status === 'awaiting-input'} />\n    </div>\n  );\n}\n```\n\n### Example: Confirmation Dialog\n\n```tsx\nfunction ConfirmationDialog({ tool }: { tool: InteractiveTool }) {\n  const { action, description } = tool.args as {\n    action: string;\n    description: string;\n  };\n\n  return (\n    <div className=\"fixed inset-0 bg-black/50 flex items-center justify-center\">\n      <div className=\"bg-white p-6 rounded-lg max-w-md\">\n        <h3 className=\"text-lg font-semibold\">Confirm {action}</h3>\n        <p className=\"mt-2 text-gray-600\">{description}</p>\n        <div className=\"mt-4 flex gap-3 justify-end\">\n          <button onClick={() => tool.cancel()} className=\"px-4 py-2 border rounded\">\n            Cancel\n          </button>\n          <button\n            onClick={() => tool.submit({ confirmed: true })}\n            className=\"px-4 py-2 bg-blue-500 text-white rounded\"\n          >\n            Confirm\n          </button>\n        </div>\n      </div>\n    </div>\n  );\n}\n```\n\n### Example: Form Input\n\n```tsx\nfunction FormInputTool({ tool }: { tool: InteractiveTool }) {\n  const [values, setValues] = useState<Record<string, string>>({});\n  const fields = tool.args.fields as { name: string; label: string; type: string }[];\n\n  const handleSubmit = (e: React.FormEvent) => {\n    e.preventDefault();\n    tool.submit(values);\n  };\n\n  return (\n    <form onSubmit={handleSubmit} className=\"p-4 border rounded-lg\">\n      {fields.map((field) => (\n        <div key={field.name} className=\"mb-4\">\n          <label className=\"block text-sm font-medium\">{field.label}</label>\n          <input\n            type={field.type}\n            value={values[field.name] ?? ''}\n            onChange={(e) => setValues({ ...values, [field.name]: e.target.value })}\n            className=\"mt-1 w-full px-3 py-2 border rounded\"\n          />\n        </div>\n      ))}\n      <div className=\"flex gap-2 justify-end\">\n        <button type=\"button\" onClick={() => tool.cancel()} className=\"px-4 py-2 border rounded\">\n          Cancel\n        </button>\n        <button type=\"submit\" className=\"px-4 py-2 bg-blue-500 text-white rounded\">\n          Submit\n        </button>\n      </div>\n    </form>\n  );\n}\n```\n\n## Status: awaiting-input\n\nWhen interactive tools are pending, the chat status changes to `'awaiting-input'`:\n\n```typescript\ntype ChatStatus = 'idle' | 'streaming' | 'error' | 'awaiting-input';\n```\n\nUse this to:\n\n- Disable the send button\n- Show \"Waiting for input\" indicators\n- Prevent new messages until tools complete\n\n```tsx\nfunction ChatInput({ status }: { status: ChatStatus }) {\n  const isDisabled = status === 'streaming' || status === 'awaiting-input';\n\n  return (\n    <div>\n      {status === 'awaiting-input' && (\n        <div className=\"text-amber-600 text-sm mb-2\">\n          Please respond to the prompt above to continue\n        </div>\n      )}\n      <input disabled={isDisabled} placeholder=\"Type a message...\" />\n    </div>\n  );\n}\n```\n\n## Mixed Server and Client Tools\n\nTools can be split between server and client based on where they should execute:\n\n```typescript\n// Server (API route)\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    // Server tools - data access, mutations\n    'get-user-account': async (args) => db.users.findById(args.userId),\n    'create-order': async (args) => orderService.create(args),\n  },\n});\n\n// Client\nconst chat = useOctavusChat({\n  transport,\n  clientTools: {\n    // Automatic - browser capabilities\n    'get-browser-location': async () => getGeolocation(),\n\n    // Interactive - user confirmation\n    'confirm-order': 'interactive',\n  },\n});\n```\n\nWhen the LLM calls multiple tools in one turn:\n\n1. Server tools execute first on the server\n2. Server results are included in the `client-tool-request` event\n3. Client tools execute (automatic immediately, interactive waits)\n4. All results are sent together to continue\n\n## HTTP Transport\n\nThe HTTP transport handles client tool continuation automatically via a unified request pattern:\n\n```typescript\nconst transport = createHttpTransport({\n  // Single request handler for both triggers and continuations\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\nYour API route handles both request types:\n\n```typescript\n// app/api/trigger/route.ts\nexport async function POST(request: Request) {\n  const body = await request.json();\n  const { sessionId, ...payload } = body;\n\n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      // Server tools only\n    },\n  });\n\n  // execute() handles both triggers and continuations\n  const events = session.execute(payload, { signal: request.signal });\n\n  return new Response(toSSEStream(events), {\n    headers: { 'Content-Type': 'text/event-stream' },\n  });\n}\n```\n\n## Socket Transport\n\nThe socket transport sends a `continue` message with tool results:\n\n### Client → Server Messages\n\n```typescript\n// Trigger (start new conversation turn)\n{ type: 'trigger', triggerName: string, input?: object }\n\n// Continue (after client tool handling)\n{ type: 'continue', executionId: string, toolResults: ToolResult[] }\n\n// Stop (cancel current operation)\n{ type: 'stop' }\n```\n\n### Server Handler\n\n```typescript\nasync function handleMessage(rawData: string, conn: Connection, session: AgentSession) {\n  const msg = JSON.parse(rawData);\n\n  if (msg.type === 'stop') {\n    abortController?.abort();\n    return;\n  }\n\n  // execute() handles both trigger and continue\n  const events = session.execute(msg, { signal: abortController?.signal });\n\n  for await (const event of events) {\n    conn.write(JSON.stringify(event));\n  }\n}\n```\n\n## Error Handling\n\n### Automatic Tool Errors\n\nErrors in automatic handlers are caught and sent back to the LLM:\n\n```typescript\nclientTools: {\n  'get-browser-location': async () => {\n    // If geolocation fails, the error is captured\n    const pos = await new Promise((resolve, reject) => {\n      navigator.geolocation.getCurrentPosition(resolve, reject);\n    });\n    return { lat: pos.coords.latitude, lng: pos.coords.longitude };\n  },\n}\n```\n\nThe LLM receives: `\"Tool error: User denied geolocation\"`\n\n### Interactive Tool Cancellation\n\nWhen users cancel interactive tools, provide a reason:\n\n```typescript\ntool.cancel('User chose not to confirm');\n```\n\nThe LLM receives the cancellation reason and can respond appropriately.\n\n### Missing Handlers\n\nIf a client tool has no handler registered, an error is sent automatically:\n\n```\n\"No client handler for tool: some-tool-name\"\n```\n\n## Best Practices\n\n### 1. Keep Server Tools on Server\n\nDon't move database or API operations to client tools:\n\n```typescript\n// Good - data access on server\n// Server:\ntools: { 'get-user': async (args) => db.users.find(args.id) }\n\n// Bad - exposing data access to client\n// Client:\nclientTools: { 'get-user': async (args) => fetch('/api/users/' + args.id) }\n```\n\n### 2. Use Interactive for Confirmations\n\nAny destructive or important action should confirm with the user:\n\n```typescript\nclientTools: {\n  'confirm-delete': 'interactive',\n  'confirm-purchase': 'interactive',\n  'confirm-send-email': 'interactive',\n}\n```\n\n### 3. Handle Cancellation Gracefully\n\nAlways provide cancel buttons for interactive tools:\n\n```tsx\n<Dialog>\n  <button onClick={() => tool.submit(result)}>Confirm</button>\n  <button onClick={() => tool.cancel()}>Cancel</button>\n</Dialog>\n```\n\n### 4. Validate Results\n\nValidate user input before submitting:\n\n```typescript\nconst handleSubmit = () => {\n  if (!rating || rating < 1 || rating > 5) {\n    setError('Please select a rating');\n    return;\n  }\n  tool.submit({ rating });\n};\n```\n\n## Type Reference\n\n```typescript\n// Handler types\ntype ClientToolHandler =\n  | ((args: Record<string, unknown>, ctx: ClientToolContext) => Promise<unknown>)\n  | 'interactive';\n\ninterface ClientToolContext {\n  toolCallId: string;\n  toolName: string;\n  signal: AbortSignal;\n}\n\n// Interactive tool (with bound methods)\ninterface InteractiveTool {\n  toolCallId: string;\n  toolName: string;\n  args: Record<string, unknown>;\n  submit: (result: unknown) => void;\n  cancel: (reason?: string) => void;\n}\n\n// Chat status\ntype ChatStatus = 'idle' | 'streaming' | 'error' | 'awaiting-input';\n```\n",
+    "content": "\n# Client Tools\n\nBy default, tools execute on your server where you have access to databases and APIs. However, some tools are better suited for client-side execution:\n\n- **Browser-only operations** — Geolocation, clipboard, local storage\n- **Interactive UIs** — Confirmation dialogs, form inputs, selections\n- **Real-time feedback** — Progress indicators, approval workflows\n\n## How Client Tools Work\n\nWhen the agent calls a tool, the Server SDK checks for a registered handler:\n\n1. **Handler exists** → Execute on server, continue automatically\n2. **No handler** → Forward to client as `client-tool-request` event\n\nThe client SDK receives pending tool calls, executes them (automatically or via user interaction), and sends results back to continue the conversation.\n\n```mermaid\nsequenceDiagram\n    participant LLM\n    participant Platform\n    participant Server as Server SDK\n    participant Client as Client SDK\n    participant User\n\n    LLM->>Platform: Call get-location\n    Platform->>Server: tool-request\n    Note over Server: No handler for<br/>get-location\n    Server->>Client: client-tool-request\n    Client->>User: Request permission\n    User->>Client: Grant\n    Client->>Server: Tool results\n    Server->>Platform: Continue with results\n    Platform->>LLM: Process results\n```\n\n## Setup\n\n### Server Side\n\nDefine tools in your protocol but don't register handlers for client tools:\n\n```typescript\n// Only register server-side tools\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    // Server tools have handlers\n    'get-user-account': async (args) => {\n      return await db.users.findById(args.userId);\n    },\n    // Client tools have NO handler here\n    // 'get-browser-location' - handled on client\n    // 'request-feedback' - handled on client\n  },\n});\n```\n\n### Client Side\n\nRegister client tool handlers when creating the chat:\n\n```typescript\nconst { messages, status, pendingClientTools } = useOctavusChat({\n  transport,\n  clientTools: {\n    // Automatic client tool\n    'get-browser-location': async () => {\n      const pos = await new Promise((resolve, reject) => {\n        navigator.geolocation.getCurrentPosition(resolve, reject);\n      });\n      return { lat: pos.coords.latitude, lng: pos.coords.longitude };\n    },\n\n    // Interactive client tool (requires user action)\n    'request-feedback': 'interactive',\n  },\n});\n```\n\n## Automatic Client Tools\n\nAutomatic tools execute immediately when called. Use these for browser operations that don't require user input.\n\n### Example: Geolocation\n\n```typescript\nconst { messages, status } = useOctavusChat({\n  transport,\n  clientTools: {\n    'get-browser-location': async (args, ctx) => {\n      // ctx provides toolCallId, toolName, and abort signal\n      const pos = await new Promise<GeolocationPosition>((resolve, reject) => {\n        navigator.geolocation.getCurrentPosition(resolve, reject, {\n          timeout: 10000,\n        });\n      });\n\n      return {\n        latitude: pos.coords.latitude,\n        longitude: pos.coords.longitude,\n        accuracy: pos.coords.accuracy,\n      };\n    },\n  },\n});\n```\n\n### Example: Clipboard\n\n```typescript\nclientTools: {\n  'copy-to-clipboard': async (args) => {\n    await navigator.clipboard.writeText(args.text as string);\n    return { success: true };\n  },\n\n  'read-clipboard': async () => {\n    const text = await navigator.clipboard.readText();\n    return { text };\n  },\n}\n```\n\n### Context Object\n\nAutomatic handlers receive a context object:\n\n```typescript\ninterface ClientToolContext {\n  toolCallId: string; // Unique ID for this call\n  toolName: string; // Name of the tool\n  signal: AbortSignal; // Aborted if user stops generation\n  addFile: (file: FileReference) => void; // Attach a file to the result\n}\n```\n\nUse the signal to cancel long-running operations:\n\n```typescript\n'fetch-external-data': async (args, ctx) => {\n  const response = await fetch(args.url, {\n    signal: ctx.signal,  // Cancels if user stops\n  });\n  return await response.json();\n}\n```\n\nTools that produce files (e.g., screenshots) can call `ctx.addFile()` to attach them to the result. Attached files are sent to the platform alongside the tool result so the LLM can see them as visual content on the next turn.\n\n## Interactive Client Tools\n\nInteractive tools require user input before completing. Use these for confirmations, forms, or any UI that needs user action.\n\nMark a tool as interactive by setting its handler to `'interactive'`:\n\n```typescript\nconst { messages, status, pendingClientTools } = useOctavusChat({\n  transport,\n  clientTools: {\n    'request-feedback': 'interactive',\n    'confirm-action': 'interactive',\n    'select-option': 'interactive',\n  },\n});\n```\n\n### Accessing Pending Tools\n\nInteractive tools appear in `pendingClientTools`, keyed by tool name:\n\n```typescript\n// pendingClientTools structure:\n{\n  'request-feedback': [\n    {\n      toolCallId: 'call_abc123',\n      toolName: 'request-feedback',\n      args: { question: 'How would you rate this response?' },\n      submit: (result) => void,  // Call with user's input\n      cancel: (reason?) => void, // Call if user dismisses\n    }\n  ],\n  'confirm-action': [\n    // Multiple calls to same tool are possible\n  ]\n}\n```\n\n### Rendering Interactive UIs\n\n```tsx\nfunction Chat() {\n  const { messages, status, pendingClientTools, send } = useOctavusChat({\n    transport,\n    clientTools: {\n      'request-feedback': 'interactive',\n    },\n  });\n\n  const feedbackTools = pendingClientTools['request-feedback'] ?? [];\n\n  return (\n    <div>\n      {/* Chat messages */}\n      <MessageList messages={messages} />\n\n      {/* Interactive tool UIs */}\n      {feedbackTools.map((tool) => (\n        <FeedbackModal\n          key={tool.toolCallId}\n          question={tool.args.question as string}\n          onSubmit={(rating, comment) => {\n            tool.submit({ rating, comment });\n          }}\n          onCancel={() => {\n            tool.cancel('User dismissed');\n          }}\n        />\n      ))}\n\n      {/* Input disabled while awaiting user action */}\n      <ChatInput disabled={status === 'awaiting-input'} />\n    </div>\n  );\n}\n```\n\n### Example: Confirmation Dialog\n\n```tsx\nfunction ConfirmationDialog({ tool }: { tool: InteractiveTool }) {\n  const { action, description } = tool.args as {\n    action: string;\n    description: string;\n  };\n\n  return (\n    <div className=\"fixed inset-0 bg-black/50 flex items-center justify-center\">\n      <div className=\"bg-white p-6 rounded-lg max-w-md\">\n        <h3 className=\"text-lg font-semibold\">Confirm {action}</h3>\n        <p className=\"mt-2 text-gray-600\">{description}</p>\n        <div className=\"mt-4 flex gap-3 justify-end\">\n          <button onClick={() => tool.cancel()} className=\"px-4 py-2 border rounded\">\n            Cancel\n          </button>\n          <button\n            onClick={() => tool.submit({ confirmed: true })}\n            className=\"px-4 py-2 bg-blue-500 text-white rounded\"\n          >\n            Confirm\n          </button>\n        </div>\n      </div>\n    </div>\n  );\n}\n```\n\n### Example: Form Input\n\n```tsx\nfunction FormInputTool({ tool }: { tool: InteractiveTool }) {\n  const [values, setValues] = useState<Record<string, string>>({});\n  const fields = tool.args.fields as { name: string; label: string; type: string }[];\n\n  const handleSubmit = (e: React.FormEvent) => {\n    e.preventDefault();\n    tool.submit(values);\n  };\n\n  return (\n    <form onSubmit={handleSubmit} className=\"p-4 border rounded-lg\">\n      {fields.map((field) => (\n        <div key={field.name} className=\"mb-4\">\n          <label className=\"block text-sm font-medium\">{field.label}</label>\n          <input\n            type={field.type}\n            value={values[field.name] ?? ''}\n            onChange={(e) => setValues({ ...values, [field.name]: e.target.value })}\n            className=\"mt-1 w-full px-3 py-2 border rounded\"\n          />\n        </div>\n      ))}\n      <div className=\"flex gap-2 justify-end\">\n        <button type=\"button\" onClick={() => tool.cancel()} className=\"px-4 py-2 border rounded\">\n          Cancel\n        </button>\n        <button type=\"submit\" className=\"px-4 py-2 bg-blue-500 text-white rounded\">\n          Submit\n        </button>\n      </div>\n    </form>\n  );\n}\n```\n\n## Status: awaiting-input\n\nWhen interactive tools are pending, the chat status changes to `'awaiting-input'`:\n\n```typescript\ntype ChatStatus = 'idle' | 'streaming' | 'error' | 'awaiting-input';\n```\n\nUse this to:\n\n- Disable the send button\n- Show \"Waiting for input\" indicators\n- Prevent new messages until tools complete\n\n```tsx\nfunction ChatInput({ status }: { status: ChatStatus }) {\n  const isDisabled = status === 'streaming' || status === 'awaiting-input';\n\n  return (\n    <div>\n      {status === 'awaiting-input' && (\n        <div className=\"text-amber-600 text-sm mb-2\">\n          Please respond to the prompt above to continue\n        </div>\n      )}\n      <input disabled={isDisabled} placeholder=\"Type a message...\" />\n    </div>\n  );\n}\n```\n\n## Mixed Server and Client Tools\n\nTools can be split between server and client based on where they should execute:\n\n```typescript\n// Server (API route)\nconst session = client.agentSessions.attach(sessionId, {\n  tools: {\n    // Server tools - data access, mutations\n    'get-user-account': async (args) => db.users.findById(args.userId),\n    'create-order': async (args) => orderService.create(args),\n  },\n});\n\n// Client\nconst chat = useOctavusChat({\n  transport,\n  clientTools: {\n    // Automatic - browser capabilities\n    'get-browser-location': async () => getGeolocation(),\n\n    // Interactive - user confirmation\n    'confirm-order': 'interactive',\n  },\n});\n```\n\nWhen the LLM calls multiple tools in one turn:\n\n1. Server tools execute first on the server\n2. Server results are included in the `client-tool-request` event\n3. Client tools execute (automatic immediately, interactive waits)\n4. All results are sent together to continue\n\n## HTTP Transport\n\nThe HTTP transport handles client tool continuation automatically via a unified request pattern:\n\n```typescript\nconst transport = createHttpTransport({\n  // Single request handler for both triggers and continuations\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\nYour API route handles both request types:\n\n```typescript\n// app/api/trigger/route.ts\nexport async function POST(request: Request) {\n  const body = await request.json();\n  const { sessionId, ...payload } = body;\n\n  const session = client.agentSessions.attach(sessionId, {\n    tools: {\n      // Server tools only\n    },\n  });\n\n  // execute() handles both triggers and continuations\n  const events = session.execute(payload, { signal: request.signal });\n\n  return new Response(toSSEStream(events), {\n    headers: { 'Content-Type': 'text/event-stream' },\n  });\n}\n```\n\n## Socket Transport\n\nThe socket transport sends a `continue` message with tool results:\n\n### Client → Server Messages\n\n```typescript\n// Trigger (start new conversation turn)\n{ type: 'trigger', triggerName: string, input?: object }\n\n// Continue (after client tool handling)\n{ type: 'continue', executionId: string, toolResults: ToolResult[] }\n\n// Stop (cancel current operation)\n{ type: 'stop' }\n```\n\n### Server Handler\n\n```typescript\nasync function handleMessage(rawData: string, conn: Connection, session: AgentSession) {\n  const msg = JSON.parse(rawData);\n\n  if (msg.type === 'stop') {\n    abortController?.abort();\n    return;\n  }\n\n  // execute() handles both trigger and continue\n  const events = session.execute(msg, { signal: abortController?.signal });\n\n  for await (const event of events) {\n    conn.write(JSON.stringify(event));\n  }\n}\n```\n\n## Error Handling\n\n### Automatic Tool Errors\n\nErrors in automatic handlers are caught and sent back to the LLM:\n\n```typescript\nclientTools: {\n  'get-browser-location': async () => {\n    // If geolocation fails, the error is captured\n    const pos = await new Promise((resolve, reject) => {\n      navigator.geolocation.getCurrentPosition(resolve, reject);\n    });\n    return { lat: pos.coords.latitude, lng: pos.coords.longitude };\n  },\n}\n```\n\nThe LLM receives: `\"Tool error: User denied geolocation\"`\n\n### Interactive Tool Cancellation\n\nWhen users cancel interactive tools, provide a reason:\n\n```typescript\ntool.cancel('User chose not to confirm');\n```\n\nThe LLM receives the cancellation reason and can respond appropriately.\n\n### Missing Handlers\n\nIf a client tool has no handler registered, an error is sent automatically:\n\n```\n\"No client handler for tool: some-tool-name\"\n```\n\n## Best Practices\n\n### 1. Keep Server Tools on Server\n\nDon't move database or API operations to client tools:\n\n```typescript\n// Good - data access on server\n// Server:\ntools: { 'get-user': async (args) => db.users.find(args.id) }\n\n// Bad - exposing data access to client\n// Client:\nclientTools: { 'get-user': async (args) => fetch('/api/users/' + args.id) }\n```\n\n### 2. Use Interactive for Confirmations\n\nAny destructive or important action should confirm with the user:\n\n```typescript\nclientTools: {\n  'confirm-delete': 'interactive',\n  'confirm-purchase': 'interactive',\n  'confirm-send-email': 'interactive',\n}\n```\n\n### 3. Handle Cancellation Gracefully\n\nAlways provide cancel buttons for interactive tools:\n\n```tsx\n<Dialog>\n  <button onClick={() => tool.submit(result)}>Confirm</button>\n  <button onClick={() => tool.cancel()}>Cancel</button>\n</Dialog>\n```\n\n### 4. Validate Results\n\nValidate user input before submitting:\n\n```typescript\nconst handleSubmit = () => {\n  if (!rating || rating < 1 || rating > 5) {\n    setError('Please select a rating');\n    return;\n  }\n  tool.submit({ rating });\n};\n```\n\n## Type Reference\n\n```typescript\n// Handler types\ntype ClientToolHandler =\n  | ((args: Record<string, unknown>, ctx: ClientToolContext) => Promise<unknown>)\n  | 'interactive';\n\ninterface ClientToolContext {\n  toolCallId: string;\n  toolName: string;\n  signal: AbortSignal;\n  addFile: (file: FileReference) => void;\n}\n\n// Interactive tool (with bound methods)\ninterface InteractiveTool {\n  toolCallId: string;\n  toolName: string;\n  args: Record<string, unknown>;\n  submit: (result: unknown) => void;\n  cancel: (reason?: string) => void;\n}\n\n// Chat status\ntype ChatStatus = 'idle' | 'streaming' | 'error' | 'awaiting-input';\n```\n",
     "excerpt": "Client Tools By default, tools execute on your server where you have access to databases and APIs. However, some tools are better suited for client-side execution: - Browser-only operations —...",
     "order": 10
   },
@@ -211,7 +211,7 @@
     "section": "protocol",
     "title": "Handlers",
     "description": "Defining execution handlers with blocks.",
-    "content": "\n# Handlers\n\nHandlers define what happens when a trigger fires. They contain execution blocks that run in sequence.\n\n## Handler Structure\n\n```yaml\nhandlers:\n  trigger-name:\n    Block Name:\n      block: block-kind\n      # block-specific properties\n\n    Another Block:\n      block: another-kind\n      # ...\n```\n\nEach block has a human-readable name (shown in debug UI) and a `block` field that determines its behavior.\n\n## Block Kinds\n\n### next-message\n\nGenerate a response from the LLM:\n\n```yaml\nhandlers:\n  user-message:\n    Respond to user:\n      block: next-message\n      # Uses main conversation thread by default\n      # Display defaults to 'stream'\n```\n\nWith options:\n\n```yaml\nGenerate summary:\n  block: next-message\n  thread: summary # Use named thread\n  display: stream # Show streaming content\n  independent: true # Don't add to main chat\n  output: SUMMARY # Store output in variable\n  description: Generating summary # Shown in UI\n```\n\nFor structured output (typed JSON response):\n\n```yaml\nRespond with suggestions:\n  block: next-message\n  responseType: ChatResponse # Type defined in types section\n  output: RESPONSE # Stores the parsed object\n```\n\nWhen `responseType` is specified:\n\n- The LLM generates JSON matching the type schema\n- The `output` variable receives the parsed object (not plain text)\n- The client receives a `UIObjectPart` for custom rendering\n\nSee [Types](/docs/protocol/types#structured-output) for more details.\n\n### add-message\n\nAdd a message to the conversation:\n\n```yaml\nAdd user message:\n  block: add-message\n  role: user # user | assistant | system\n  prompt: user-message # Reference to prompt file\n  input: [USER_MESSAGE] # Variables to interpolate\n  display: hidden # Don't show in UI\n```\n\nFor internal directives (LLM sees it, user doesn't):\n\n```yaml\nAdd internal directive:\n  block: add-message\n  role: user\n  prompt: ticket-directive\n  input: [TICKET_DETAILS]\n  visible: false # LLM sees this, user doesn't\n```\n\nFor structured user input (object shown in UI, prompt for LLM context):\n\n```yaml\nAdd user message:\n  block: add-message\n  role: user\n  prompt: user-message # Rendered for LLM context (hidden from UI)\n  input: [USER_INPUT]\n  uiContent: USER_INPUT # Variable shown in UI (object → object part)\n  display: hidden\n```\n\nWhen `uiContent` is set:\n\n- The variable value is shown in the UI (string → text part, object → object part)\n- The prompt text is hidden from the UI but kept for LLM context\n- Useful for rich UI interactions where the visual differs from the LLM context\n\n### tool-call\n\nCall a tool deterministically:\n\n```yaml\nCreate ticket:\n  block: tool-call\n  tool: create-support-ticket\n  input:\n    summary: SUMMARY # Variable reference\n    priority: medium # Literal value\n  output: TICKET # Store result\n```\n\n### set-resource\n\nUpdate a persistent resource:\n\n```yaml\nSave summary:\n  block: set-resource\n  resource: CONVERSATION_SUMMARY\n  value: SUMMARY # Variable to save\n  display: name # Show block name\n```\n\n### start-thread\n\nCreate a named conversation thread:\n\n```yaml\nStart summary thread:\n  block: start-thread\n  thread: summary # Thread name\n  model: anthropic/claude-sonnet-4-5 # Optional: different model\n  thinking: low # Extended reasoning level\n  maxSteps: 1 # Tool call limit\n  system: escalation-summary # System prompt\n  input: [COMPANY_NAME] # Variables for prompt\n```\n\nThe `model` field can also reference a variable for dynamic model selection:\n\n```yaml\nStart summary thread:\n  block: start-thread\n  thread: summary\n  model: SUMMARY_MODEL # Resolved from input variable\n  system: escalation-summary\n```\n\n### serialize-thread\n\nConvert conversation to text:\n\n```yaml\nSerialize conversation:\n  block: serialize-thread\n  thread: main # Which thread (default: main)\n  format: markdown # markdown | json\n  output: CONVERSATION_TEXT # Variable to store result\n```\n\n### generate-image\n\nGenerate an image from a prompt variable:\n\n```yaml\nGenerate image:\n  block: generate-image\n  prompt: OPTIMIZED_PROMPT # Variable containing the prompt\n  imageModel: google/gemini-2.5-flash-image # Required image model\n  size: 1024x1024 # 1024x1024 | 1792x1024 | 1024x1792\n  output: GENERATED_IMAGE # Store URL in variable\n  description: Generating your image... # Shown in UI\n```\n\nThis block is for deterministic image generation pipelines where the prompt is constructed programmatically (e.g., via prompt engineering in a separate thread).\n\nFor agentic image generation where the LLM decides when to generate, configure `imageModel` in the [agent config](/docs/protocol/agent-config#image-generation).\n\n## Display Modes\n\nEvery block has a `display` property:\n\n| Mode          | Default For               | Behavior          |\n| ------------- | ------------------------- | ----------------- |\n| `hidden`      | add-message               | Not shown to user |\n| `name`        | set-resource              | Shows block name  |\n| `description` | tool-call, generate-image | Shows description |\n| `stream`      | next-message              | Streams content   |\n\n## Complete Example\n\n```yaml\nhandlers:\n  user-message:\n    # Add the user's message to conversation\n    Add user message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n\n    # Generate response (LLM may call tools)\n    Respond to user:\n      block: next-message\n      # display: stream (default)\n\n  request-human:\n    # Step 1: Serialize conversation for summary\n    Serialize conversation:\n      block: serialize-thread\n      format: markdown\n      output: CONVERSATION_TEXT\n\n    # Step 2: Create separate thread for summarization\n    Start summary thread:\n      block: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5\n      thinking: low\n      system: escalation-summary\n      input: [COMPANY_NAME]\n\n    # Step 3: Add request to summary thread\n    Add summarize request:\n      block: add-message\n      thread: summary\n      role: user\n      prompt: summarize-request\n      input:\n        - CONVERSATION: CONVERSATION_TEXT\n\n    # Step 4: Generate summary\n    Generate summary:\n      block: next-message\n      thread: summary\n      display: stream\n      description: Summarizing your conversation\n      independent: true\n      output: SUMMARY\n\n    # Step 5: Save to resource\n    Save summary:\n      block: set-resource\n      resource: CONVERSATION_SUMMARY\n      value: SUMMARY\n\n    # Step 6: Create support ticket\n    Create ticket:\n      block: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY\n        priority: medium\n      output: TICKET\n\n    # Step 7: Add directive for response\n    Add directive:\n      block: add-message\n      role: user\n      prompt: ticket-directive\n      input: [TICKET_DETAILS: TICKET]\n      visible: false\n\n    # Step 8: Respond to user\n    Respond:\n      block: next-message\n```\n\n## Block Input Mapping\n\nMap variables to block inputs:\n\n```yaml\n# Simple list (variable name = prompt variable)\ninput: [USER_MESSAGE, COMPANY_NAME]\n\n# Mapping (different names)\ninput:\n  - CONVERSATION: CONVERSATION_TEXT  # CONVERSATION in prompt = CONVERSATION_TEXT\n  - TICKET_DETAILS: TICKET\n```\n\n## Independent Blocks\n\nUse `independent: true` for content that shouldn't go to the main chat:\n\n```yaml\nGenerate summary:\n  block: next-message\n  thread: summary\n  independent: true # Output stored in variable, not main chat\n  output: SUMMARY\n```\n\nThis is useful for:\n\n- Background processing\n- Summarization in separate threads\n- Generating content for tools\n",
+    "content": "\n# Handlers\n\nHandlers define what happens when a trigger fires. They contain execution blocks that run in sequence.\n\n## Handler Structure\n\n```yaml\nhandlers:\n  trigger-name:\n    Block Name:\n      block: block-kind\n      # block-specific properties\n\n    Another Block:\n      block: another-kind\n      # ...\n```\n\nEach block has a human-readable name (shown in debug UI) and a `block` field that determines its behavior.\n\n## Block Kinds\n\n### next-message\n\nGenerate a response from the LLM:\n\n```yaml\nhandlers:\n  user-message:\n    Respond to user:\n      block: next-message\n      # Uses main conversation thread by default\n      # Display defaults to 'stream'\n```\n\nWith options:\n\n```yaml\nGenerate summary:\n  block: next-message\n  thread: summary # Use named thread\n  display: stream # Show streaming content\n  independent: true # Don't add to main chat\n  output: SUMMARY # Store output in variable\n  description: Generating summary # Shown in UI\n```\n\nFor structured output (typed JSON response):\n\n```yaml\nRespond with suggestions:\n  block: next-message\n  responseType: ChatResponse # Type defined in types section\n  output: RESPONSE # Stores the parsed object\n```\n\nWhen `responseType` is specified:\n\n- The LLM generates JSON matching the type schema\n- The `output` variable receives the parsed object (not plain text)\n- The client receives a `UIObjectPart` for custom rendering\n\nSee [Types](/docs/protocol/types#structured-output) for more details.\n\n### add-message\n\nAdd a message to the conversation:\n\n```yaml\nAdd user message:\n  block: add-message\n  role: user # user | assistant | system\n  prompt: user-message # Reference to prompt file\n  input: [USER_MESSAGE] # Variables to interpolate\n  display: hidden # Don't show in UI\n```\n\nFor internal directives (LLM sees it, user doesn't):\n\n```yaml\nAdd internal directive:\n  block: add-message\n  role: user\n  prompt: ticket-directive\n  input: [TICKET_DETAILS]\n  visible: false # LLM sees this, user doesn't\n```\n\nFor structured user input (object shown in UI, prompt for LLM context):\n\n```yaml\nAdd user message:\n  block: add-message\n  role: user\n  prompt: user-message # Rendered for LLM context (hidden from UI)\n  input: [USER_INPUT]\n  uiContent: USER_INPUT # Variable shown in UI (object → object part)\n  display: hidden\n```\n\nWhen `uiContent` is set:\n\n- The variable value is shown in the UI (string → text part, object → object part)\n- The prompt text is hidden from the UI but kept for LLM context\n- Useful for rich UI interactions where the visual differs from the LLM context\n\n### tool-call\n\nCall a tool deterministically:\n\n```yaml\nCreate ticket:\n  block: tool-call\n  tool: create-support-ticket\n  input:\n    summary: SUMMARY # Variable reference\n    priority: medium # Literal value\n  output: TICKET # Store result\n```\n\n### set-resource\n\nUpdate a persistent resource:\n\n```yaml\nSave summary:\n  block: set-resource\n  resource: CONVERSATION_SUMMARY\n  value: SUMMARY # Variable to save\n  display: name # Show block name\n```\n\n### start-thread\n\nCreate a named conversation thread:\n\n```yaml\nStart summary thread:\n  block: start-thread\n  thread: summary # Thread name\n  model: anthropic/claude-sonnet-4-5 # Optional: different model\n  thinking: low # Extended reasoning level\n  maxSteps: 1 # Tool call limit\n  system: escalation-summary # System prompt\n  input: [COMPANY_NAME] # Variables for prompt\n```\n\nThe `model` field can also reference a variable for dynamic model selection:\n\n```yaml\nStart summary thread:\n  block: start-thread\n  thread: summary\n  model: SUMMARY_MODEL # Resolved from input variable\n  system: escalation-summary\n```\n\n### serialize-thread\n\nConvert conversation to text:\n\n```yaml\nSerialize conversation:\n  block: serialize-thread\n  thread: main # Which thread (default: main)\n  format: markdown # markdown | json\n  output: CONVERSATION_TEXT # Variable to store result\n```\n\n### generate-image\n\nGenerate an image from a prompt variable:\n\n```yaml\nGenerate image:\n  block: generate-image\n  prompt: OPTIMIZED_PROMPT # Variable containing the prompt\n  imageModel: google/gemini-2.5-flash-image # Required image model\n  size: 1024x1024 # 1024x1024 | 1792x1024 | 1024x1792\n  output: GENERATED_IMAGE # Store URL in variable\n  description: Generating your image... # Shown in UI\n```\n\nEdit an existing image using reference images:\n\n```yaml\nEdit image:\n  block: generate-image\n  prompt: EDIT_INSTRUCTIONS # e.g., \"Remove the background\"\n  referenceImages: [SOURCE_IMAGE_URL] # Variable(s) containing image URLs\n  imageModel: google/gemini-2.5-flash-image\n  output: EDITED_IMAGE\n  description: Editing image...\n```\n\n| Field             | Required | Description                                                     |\n| ----------------- | -------- | --------------------------------------------------------------- |\n| `prompt`          | Yes      | Variable name containing the image prompt or edit instructions  |\n| `imageModel`      | Yes      | Image model identifier (e.g., `google/gemini-2.5-flash-image`)  |\n| `size`            | No       | Image dimensions: `1024x1024`, `1792x1024`, or `1024x1792`      |\n| `referenceImages` | No       | Variable names containing image URLs for editing/transformation |\n| `output`          | No       | Variable name to store the generated image URL                  |\n| `thread`          | No       | Thread to associate the output file with                        |\n| `description`     | No       | Description shown in the UI during generation                   |\n\nThis block is for deterministic image generation pipelines where the prompt is constructed programmatically (e.g., via prompt engineering in a separate thread). When `referenceImages` are provided, the prompt describes how to modify those images.\n\nFor agentic image generation where the LLM decides when to generate, configure `imageModel` in the [agent config](/docs/protocol/agent-config#image-generation).\n\n## Display Modes\n\nEvery block has a `display` property:\n\n| Mode          | Default For               | Behavior          |\n| ------------- | ------------------------- | ----------------- |\n| `hidden`      | add-message               | Not shown to user |\n| `name`        | set-resource              | Shows block name  |\n| `description` | tool-call, generate-image | Shows description |\n| `stream`      | next-message              | Streams content   |\n\n## Complete Example\n\n```yaml\nhandlers:\n  user-message:\n    # Add the user's message to conversation\n    Add user message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input: [USER_MESSAGE]\n      display: hidden\n\n    # Generate response (LLM may call tools)\n    Respond to user:\n      block: next-message\n      # display: stream (default)\n\n  request-human:\n    # Step 1: Serialize conversation for summary\n    Serialize conversation:\n      block: serialize-thread\n      format: markdown\n      output: CONVERSATION_TEXT\n\n    # Step 2: Create separate thread for summarization\n    Start summary thread:\n      block: start-thread\n      thread: summary\n      model: anthropic/claude-sonnet-4-5\n      thinking: low\n      system: escalation-summary\n      input: [COMPANY_NAME]\n\n    # Step 3: Add request to summary thread\n    Add summarize request:\n      block: add-message\n      thread: summary\n      role: user\n      prompt: summarize-request\n      input:\n        - CONVERSATION: CONVERSATION_TEXT\n\n    # Step 4: Generate summary\n    Generate summary:\n      block: next-message\n      thread: summary\n      display: stream\n      description: Summarizing your conversation\n      independent: true\n      output: SUMMARY\n\n    # Step 5: Save to resource\n    Save summary:\n      block: set-resource\n      resource: CONVERSATION_SUMMARY\n      value: SUMMARY\n\n    # Step 6: Create support ticket\n    Create ticket:\n      block: tool-call\n      tool: create-support-ticket\n      input:\n        summary: SUMMARY\n        priority: medium\n      output: TICKET\n\n    # Step 7: Add directive for response\n    Add directive:\n      block: add-message\n      role: user\n      prompt: ticket-directive\n      input: [TICKET_DETAILS: TICKET]\n      visible: false\n\n    # Step 8: Respond to user\n    Respond:\n      block: next-message\n```\n\n## Block Input Mapping\n\nMap variables to block inputs:\n\n```yaml\n# Simple list (variable name = prompt variable)\ninput: [USER_MESSAGE, COMPANY_NAME]\n\n# Mapping (different names)\ninput:\n  - CONVERSATION: CONVERSATION_TEXT  # CONVERSATION in prompt = CONVERSATION_TEXT\n  - TICKET_DETAILS: TICKET\n```\n\n## Independent Blocks\n\nUse `independent: true` for content that shouldn't go to the main chat:\n\n```yaml\nGenerate summary:\n  block: next-message\n  thread: summary\n  independent: true # Output stored in variable, not main chat\n  output: SUMMARY\n```\n\nThis is useful for:\n\n- Background processing\n- Summarization in separate threads\n- Generating content for tools\n",
     "excerpt": "Handlers Handlers define what happens when a trigger fires. They contain execution blocks that run in sequence.  Handler Structure Each block has a human-readable name (shown in debug UI) and a ...",
     "order": 6
   },
@@ -220,7 +220,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  skills: [qr-code] # Available skills\n```\n\n## Configuration Options\n\n| Field         | Required | Description                                               |\n| ------------- | -------- | --------------------------------------------------------- |\n| `model`       | Yes      | Model identifier or variable reference                    |\n| `system`      | Yes      | System prompt filename (without .md)                      |\n| `input`       | No       | Variables to interpolate in system prompt                 |\n| `tools`       | No       | List of tools the LLM can call                            |\n| `skills`      | No       | List of Octavus skills the LLM can use                    |\n| `imageModel`  | No       | Image generation model (enables agentic image generation) |\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| `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## System Prompt\n\nThe system prompt sets the agent's persona and instructions:\n\n```yaml\nagent:\n  system: system # Uses prompts/system.md\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n```\n\nExample `prompts/system.md`:\n\n```markdown\nYou are a friendly support agent for {{COMPANY_NAME}}.\n\n## Your Role\n\nHelp users with questions about {{PRODUCT_NAME}}.\n\n## Guidelines\n\n- Be helpful and professional\n- If you can't help, offer to escalate\n- Never share internal information\n```\n\n## Agentic Mode\n\nEnable multi-step tool calling:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools: [get-user-account, search-docs, create-ticket]\n  agentic: true # LLM can call multiple tools\n  maxSteps: 10 # Limit cycles to prevent runaway\n```\n\n**How it works:**\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## 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## 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.\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### Agentic vs Deterministic\n\nUse `imageModel` in agent config when:\n\n- The LLM should decide when to generate 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\n- Building prompt engineering pipelines\n- Images are generated at specific handler steps\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      thinking: low # Different thinking\n      maxSteps: 1 # Limit tool calls\n      system: escalation-summary # Different prompt\n```\n\n## Full Example\n\n```yaml\ninput:\n  COMPANY_NAME: { type: string }\n  PRODUCT_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\nresources:\n  CONVERSATION_SUMMARY:\n    type: string\n    default: ''\n\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n\n  search-docs:\n    description: Search help documentation\n    parameters:\n      query: { type: string }\n\n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string } # low, medium, high\n\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  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n  tools:\n    - get-user-account\n    - search-docs\n    - create-support-ticket\n  skills: [qr-code] # Octavus skills\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  skills: [qr-code] # Available skills\n```\n\n## Configuration Options\n\n| Field         | Required | Description                                               |\n| ------------- | -------- | --------------------------------------------------------- |\n| `model`       | Yes      | Model identifier or variable reference                    |\n| `system`      | Yes      | System prompt filename (without .md)                      |\n| `input`       | No       | Variables to interpolate in system prompt                 |\n| `tools`       | No       | List of tools the LLM can call                            |\n| `skills`      | No       | List of Octavus skills the LLM can use                    |\n| `imageModel`  | No       | Image generation model (enables agentic image generation) |\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| `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## System Prompt\n\nThe system prompt sets the agent's persona and instructions:\n\n```yaml\nagent:\n  system: system # Uses prompts/system.md\n  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n```\n\nExample `prompts/system.md`:\n\n```markdown\nYou are a friendly support agent for {{COMPANY_NAME}}.\n\n## Your Role\n\nHelp users with questions about {{PRODUCT_NAME}}.\n\n## Guidelines\n\n- Be helpful and professional\n- If you can't help, offer to escalate\n- Never share internal information\n```\n\n## Agentic Mode\n\nEnable multi-step tool calling:\n\n```yaml\nagent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  tools: [get-user-account, search-docs, create-ticket]\n  agentic: true # LLM can call multiple tools\n  maxSteps: 10 # Limit cycles to prevent runaway\n```\n\n**How it works:**\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## 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## 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## 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      thinking: low # Different thinking\n      maxSteps: 1 # Limit tool calls\n      system: escalation-summary # Different prompt\n```\n\n## Full Example\n\n```yaml\ninput:\n  COMPANY_NAME: { type: string }\n  PRODUCT_NAME: { type: string }\n  USER_ID: { type: string, optional: true }\n\nresources:\n  CONVERSATION_SUMMARY:\n    type: string\n    default: ''\n\ntools:\n  get-user-account:\n    description: Look up user account\n    parameters:\n      userId: { type: string }\n\n  search-docs:\n    description: Search help documentation\n    parameters:\n      query: { type: string }\n\n  create-support-ticket:\n    description: Create a support ticket\n    parameters:\n      summary: { type: string }\n      priority: { type: string } # low, medium, high\n\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  input:\n    - COMPANY_NAME\n    - PRODUCT_NAME\n  tools:\n    - get-user-account\n    - search-docs\n    - create-support-ticket\n  skills: [qr-code] # Octavus skills\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
   },

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   getDocBySlug,
   getDocSections,
   getDocSlugs
-} from "./chunk-RI24MRSN.js";
+} from "./chunk-YS5UYKHB.js";
 export {
   getDocBySlug,
   getDocSections,