@octavus/docs 2.11.0 → 2.12.0

package/content/02-server-sdk/05-cli.md

@@ -169,11 +169,17 @@ The CLI expects agent definitions in a specific directory structure:
 my-agent/
 ├── settings.json     # Required: Agent metadata
 ├── protocol.yaml     # Required: Agent protocol
-└── prompts/          # Optional: Prompt templates
-    ├── system.md
-    └── user-message.md
+├── prompts/          # Optional: Prompt templates
+│   ├── system.md
+│   └── user-message.md
+└── references/       # Optional: Reference documents
+    └── api-guidelines.md
 ```
 
+### references/
+
+Reference files are markdown documents with YAML frontmatter containing a `description`. The agent can fetch these on demand during execution. See [References](/docs/protocol/references) for details.
+
 ### settings.json
 
 ```json

package/content/03-client-sdk/08-file-uploads.md

@@ -77,6 +77,12 @@ function Chat({ sessionId }: { sessionId: string }) {
   const { messages, status, send, uploadFiles } = useOctavusChat({
     transport,
     requestUploadUrls,
+    // Optional: configure upload timeout and retry behavior
+    uploadOptions: {
+      timeoutMs: 60_000, // Per-file timeout (default: 60s, set to 0 to disable)
+      maxRetries: 2, // Retry attempts on transient failures (default: 2)
+      retryDelayMs: 1_000, // Delay between retries (default: 1s)
+    },
   });
 
   // ...
@@ -176,6 +182,54 @@ async function handleSend(message: string, files?: File[]) {
 
 The SDK automatically uploads the files before sending. Note: This doesn't provide upload progress.
 
+## Upload Reliability
+
+Uploads include built-in timeout and retry logic for handling transient failures (network errors, server issues, mobile network switches).
+
+**Default behavior:**
+
+- **Timeout**: 60 seconds per file — prevents uploads from hanging on stalled connections
+- **Retries**: 2 automatic retries on transient failures (network errors, 5xx, 429)
+- **Retry delay**: 1 second between retries
+- **Non-retryable errors** (4xx like 403, 404) fail immediately without retrying
+
+Only the S3 upload is retried — the presigned URL stays valid for 15 minutes. On retry, the progress callback resets to 0%.
+
+Configure via `uploadOptions`:
+
+```typescript
+const { send, uploadFiles } = useOctavusChat({
+  transport,
+  requestUploadUrls,
+  uploadOptions: {
+    timeoutMs: 120_000, // 2 minutes for large files
+    maxRetries: 3,
+    retryDelayMs: 2_000,
+  },
+});
+```
+
+To disable timeout or retries:
+
+```typescript
+uploadOptions: {
+  timeoutMs: 0,    // No timeout
+  maxRetries: 0,   // No retries
+}
+```
+
+### Using `OctavusChat` Directly
+
+When using the `OctavusChat` class directly (without the React hook), pass `uploadOptions` in the constructor:
+
+```typescript
+const chat = new OctavusChat({
+  transport,
+  requestUploadUrls,
+  uploadOptions: { timeoutMs: 120_000, maxRetries: 3 },
+});
+```
+
 ## FileReference Type
 
 File references contain metadata and URLs:
@@ -234,15 +288,15 @@ The `file` type is a built-in type representing uploaded files. Use `file[]` for
 | Type      | Media Types                                                          |
 | --------- | -------------------------------------------------------------------- |
 | Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |
+| Video     | `video/mp4`, `video/webm`, `video/quicktime`, `video/mpeg`           |
 | Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |
 
 ## File Limits
 
 | Limit                 | Value      |
 | --------------------- | ---------- |
-| Max file size         | 10 MB      |
-| Max total per request | 50 MB      |
-| Max files per request | 20         |
+| Max file size         | 100 MB     |
+| Max total per request | 200 MB     |
 | Upload URL expiry     | 15 minutes |
 | Download URL expiry   | 24 hours   |
 

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

@@ -105,16 +105,20 @@ Each agent is a folder with:
 my-agent/
 ├── protocol.yaml           # Main logic (required)
 ├── settings.json           # Agent metadata (required)
-└── prompts/               # Prompt templates (supports subdirectories)
-    ├── system.md
-    ├── user-message.md
-    └── shared/
-        ├── company-info.md
-        └── formatting-rules.md
+├── prompts/               # Prompt templates (supports subdirectories)
+│   ├── system.md
+│   ├── user-message.md
+│   └── shared/
+│       ├── company-info.md
+│       └── formatting-rules.md
+└── references/            # On-demand context documents (optional)
+    └── api-guidelines.md
 ```
 
 Prompts can be organized in subdirectories. In the protocol, reference nested prompts by their path relative to `prompts/` (without `.md`): `shared/company-info`.
 
+References are markdown files with YAML frontmatter that the agent can fetch on demand during execution. See [References](/docs/protocol/references).
+
 ### settings.json
 
 ```json
@@ -183,6 +187,7 @@ The referenced prompt content is inserted before variable interpolation, so vari
 - [Triggers](/docs/protocol/triggers) — How agents are invoked
 - [Tools](/docs/protocol/tools) — External capabilities
 - [Skills](/docs/protocol/skills) — Code execution and knowledge packages
+- [References](/docs/protocol/references) — On-demand context documents
 - [Handlers](/docs/protocol/handlers) — Execution blocks
 - [Agent Config](/docs/protocol/agent-config) — Model and settings
 - [Workers](/docs/protocol/workers) — Worker agent format

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

@@ -15,6 +15,7 @@ agent:
   system: system # References prompts/system.md
   tools: [get-user-account] # Available tools
   skills: [qr-code] # Available skills
+  references: [api-guidelines] # On-demand context documents
 ```
 
 ## Configuration Options
@@ -26,6 +27,7 @@ agent:
 | `input`          | No       | Variables to pass to the system prompt                    |
 | `tools`          | No       | List of tools the LLM can call                            |
 | `skills`         | No       | List of Octavus skills the LLM can use                    |
+| `references`     | No       | List of references the LLM can fetch on demand            |
 | `sandboxTimeout` | No       | Skill sandbox timeout in ms (default: 5 min, max: 1 hour) |
 | `imageModel`     | No       | Image generation model (enables agentic image generation) |
 | `agentic`        | No       | Allow multiple tool call cycles                           |
@@ -212,6 +214,22 @@ Skills provide provider-agnostic code execution in isolated sandboxes. When enab
 
 See [Skills](/docs/protocol/skills) for full documentation.
 
+## References
+
+Enable on-demand context loading via reference documents:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  references: [api-guidelines, error-codes]
+  agentic: true
+```
+
+References are markdown files stored in the agent's `references/` directory. When enabled, the LLM can list available references and read their content using `octavus_reference_list` and `octavus_reference_read` tools.
+
+See [References](/docs/protocol/references) for full documentation.
+
 ## Image Generation
 
 Enable the LLM to generate images autonomously:
@@ -321,10 +339,11 @@ handlers:
       maxSteps: 1 # Limit tool calls
       system: escalation-summary # Different prompt
       skills: [data-analysis] # Thread-specific skills
+      references: [escalation-policy] # Thread-specific references
       imageModel: google/gemini-2.5-flash-image # Thread-specific image model
 ```
 
-Each thread can have its own skills and image model. Skills referenced here must be defined in the protocol's `skills:` section. Workers use this same pattern since they don't have a global `agent:` section.
+Each thread can have its own skills, references, and image model. Skills must be defined in the protocol's `skills:` section. References must exist in the agent's `references/` directory. Workers use this same pattern since they don't have a global `agent:` section.
 
 ## Full Example
 
@@ -372,6 +391,7 @@ agent:
     - search-docs
     - create-support-ticket
   skills: [qr-code] # Octavus skills
+  references: [support-policies] # On-demand context
   agentic: true
   maxSteps: 10
   thinking: medium

package/content/04-protocol/12-references.md

@@ -0,0 +1,189 @@
+---
+title: References
+description: Using references for on-demand context loading in agents.
+---
+
+# References
+
+References are markdown documents that agents can fetch on demand. Instead of loading everything into the system prompt upfront, references let the agent decide what context it needs and load it when relevant.
+
+## Overview
+
+References are useful for:
+
+- **Large context** — Documents too long to include in every system prompt
+- **Selective loading** — Let the agent decide which context is relevant
+- **Shared knowledge** — Reusable documents across threads
+
+### How References Work
+
+1. **Definition**: Reference files live in the `references/` directory alongside your agent
+2. **Configuration**: List available references in `agent.references` or `start-thread.references`
+3. **Discovery**: The agent sees reference names and descriptions in its system prompt
+4. **Fetching**: The agent calls reference tools to read the full content when needed
+
+## Creating References
+
+Each reference is a markdown file with YAML frontmatter in the `references/` directory:
+
+```
+my-agent/
+├── settings.json
+├── protocol.yaml
+├── prompts/
+│   └── system.md
+└── references/
+    ├── api-guidelines.md
+    └── error-codes.md
+```
+
+### Reference Format
+
+```markdown
+---
+description: >
+  API design guidelines including naming conventions,
+  error handling patterns, and pagination standards.
+---
+
+# API Guidelines
+
+## Naming Conventions
+
+Use lowercase with dashes for URL paths...
+
+## Error Handling
+
+All errors return a standard error envelope...
+```
+
+The `description` field is required. It tells the agent what the reference contains so it can decide when to fetch it.
+
+### Naming Convention
+
+Reference filenames use `lowercase-with-dashes`:
+
+- `api-guidelines.md`
+- `error-codes.md`
+- `coding-standards.md`
+
+The filename (without `.md`) becomes the reference name used in the protocol.
+
+## Enabling References
+
+After creating reference files, specify which references are available in the protocol.
+
+### Interactive Agents
+
+List references in `agent.references`:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  references: [api-guidelines, error-codes]
+  agentic: true
+```
+
+### Workers and Named Threads
+
+List references per-thread in `start-thread.references`:
+
+```yaml
+steps:
+  Start thread:
+    block: start-thread
+    thread: worker
+    model: anthropic/claude-sonnet-4-5
+    system: system
+    references: [api-guidelines]
+    maxSteps: 10
+```
+
+Different threads can have different references.
+
+## Reference Tools
+
+When references are enabled, the agent has access to two tools:
+
+| Tool                     | Purpose                                         |
+| ------------------------ | ----------------------------------------------- |
+| `octavus_reference_list` | List all available references with descriptions |
+| `octavus_reference_read` | Read the full content of a specific reference   |
+
+The agent also sees reference names and descriptions in its system prompt, so it knows what's available without calling `octavus_reference_list`.
+
+## Example
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  tools: [review-pull-request]
+  references: [coding-standards, api-guidelines]
+  agentic: true
+
+handlers:
+  user-message:
+    Add message:
+      block: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+
+    Respond:
+      block: next-message
+```
+
+With `references/coding-standards.md`:
+
+```markdown
+---
+description: >
+  Team coding standards including naming conventions,
+  code organization, and review checklist.
+---
+
+# Coding Standards
+
+## Naming Conventions
+
+- Files: kebab-case
+- Variables: camelCase
+- Constants: UPPER_SNAKE_CASE
+  ...
+```
+
+When a user asks the agent to review code, the agent will:
+
+1. See "coding-standards" and "api-guidelines" in its system prompt
+2. Decide which references are relevant to the review
+3. Call `octavus_reference_read` to load the relevant reference
+4. Use the loaded context to provide an informed review
+
+## Validation
+
+The CLI and platform validate references during sync and deployment:
+
+- **Undefined references** — Referencing a name that doesn't have a matching file in `references/`
+- **Unused references** — A reference file exists but isn't listed in any `agent.references` or `start-thread.references`
+- **Invalid names** — Names that don't follow the `lowercase-with-dashes` convention
+- **Missing description** — Reference files without the required `description` in frontmatter
+
+## References vs Skills
+
+| Aspect        | References                    | Skills                          |
+| ------------- | ----------------------------- | ------------------------------- |
+| **Purpose**   | On-demand context documents   | Code execution and file output  |
+| **Content**   | Markdown text                 | Documentation + scripts         |
+| **Execution** | Synchronous text retrieval    | Sandboxed code execution (E2B)  |
+| **Scope**     | Per-agent (stored with agent) | Per-organization (shared)       |
+| **Tools**     | List and read (2 tools)       | Read, list, run, code (6 tools) |
+
+Use **references** when the agent needs access to text-based knowledge. Use **skills** when the agent needs to execute code or generate files.
+
+## Next Steps
+
+- [Agent Config](/docs/protocol/agent-config) — Configuring references in agent settings
+- [Skills](/docs/protocol/skills) — Code execution and knowledge packages
+- [Workers](/docs/protocol/workers) — Using references in worker agents

package/content/05-api-reference/03-agents.md

@@ -5,7 +5,7 @@ description: Agent management API endpoints.
 
 # Agents API
 
-Manage agent definitions including protocols and prompts.
+Manage agent definitions including protocols, prompts, and references.
 
 ## Permissions
 
@@ -82,6 +82,13 @@ GET /api/agents/:id
       "name": "user-message",
       "content": "{{USER_MESSAGE}}"
     }
+  ],
+  "references": [
+    {
+      "name": "api-guidelines",
+      "description": "API design guidelines and conventions",
+      "content": "# API Guidelines\n\nUse lowercase with dashes..."
+    }
   ]
 }
 ```
@@ -119,18 +126,26 @@ POST /api/agents
       "name": "system",
       "content": "You are a support agent..."
     }
+  ],
+  "references": [
+    {
+      "name": "api-guidelines",
+      "description": "API design guidelines and conventions",
+      "content": "# API Guidelines\n..."
+    }
   ]
 }
 ```
 
-| Field                  | Type   | Required | Description               |
-| ---------------------- | ------ | -------- | ------------------------- |
-| `settings.slug`        | string | Yes      | URL-safe identifier       |
-| `settings.name`        | string | Yes      | Display name              |
-| `settings.description` | string | No       | Agent description         |
-| `settings.format`      | string | Yes      | `interactive` or `worker` |
-| `protocol`             | string | Yes      | YAML protocol definition  |
-| `prompts`              | array  | Yes      | Prompt files              |
+| Field                  | Type   | Required | Description                                      |
+| ---------------------- | ------ | -------- | ------------------------------------------------ |
+| `settings.slug`        | string | Yes      | URL-safe identifier                              |
+| `settings.name`        | string | Yes      | Display name                                     |
+| `settings.description` | string | No       | Agent description                                |
+| `settings.format`      | string | Yes      | `interactive` or `worker`                        |
+| `protocol`             | string | Yes      | YAML protocol definition                         |
+| `prompts`              | array  | Yes      | Prompt files                                     |
+| `references`           | array  | No       | Reference documents (name, description, content) |
 
 ### Response
 
@@ -178,6 +193,13 @@ PATCH /api/agents/:id
       "name": "system",
       "content": "Updated system prompt..."
     }
+  ],
+  "references": [
+    {
+      "name": "api-guidelines",
+      "description": "Updated description",
+      "content": "Updated content..."
+    }
   ]
 }
 ```

package/dist/{chunk-EIUCL4CP.js → chunk-PQ5AGOPY.js}

@@ -513,7 +513,7 @@ See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list
     section: "client-sdk",
     title: "File Uploads",
     description: "Uploading images and files for vision models and document processing.",
-    content: "\n# File Uploads\n\nThe Client SDK supports uploading images and documents that can be sent with messages. This enables vision model capabilities (analyzing images) and document processing.\n\n## Overview\n\nFile uploads follow a two-step flow:\n\n1. **Request upload URLs** from the platform via your backend\n2. **Upload files directly to S3** using presigned URLs\n3. **Send file references** with your message\n\nThis architecture keeps your API key secure on the server while enabling fast, direct uploads.\n\n## Setup\n\n### Backend: Upload URLs Endpoint\n\nCreate an endpoint that proxies upload URL requests to the Octavus platform:\n\n```typescript\n// app/api/upload-urls/route.ts (Next.js)\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, files } = await request.json();\n\n  // Get presigned URLs from Octavus\n  const result = await octavus.files.getUploadUrls(sessionId, files);\n\n  return NextResponse.json(result);\n}\n```\n\n### Client: Configure File Uploads\n\nPass `requestUploadUrls` to the chat hook:\n\n```tsx\nimport { useMemo, useCallback } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  // Request upload URLs from your backend\n  const requestUploadUrls = useCallback(\n    async (files: { filename: string; mediaType: string; size: number }[]) => {\n      const response = await fetch('/api/upload-urls', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, files }),\n      });\n      return response.json();\n    },\n    [sessionId],\n  );\n\n  const { messages, status, send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  // ...\n}\n```\n\n## Uploading Files\n\n### Method 1: Upload Before Sending\n\nFor the best UX (showing upload progress), upload files first, then send:\n\n```tsx\nimport { useState, useRef } from 'react';\nimport type { FileReference } from '@octavus/react';\n\nfunction ChatInput({ sessionId }: { sessionId: string }) {\n  const [pendingFiles, setPendingFiles] = useState<FileReference[]>([]);\n  const [uploading, setUploading] = useState(false);\n  const fileInputRef = useRef<HTMLInputElement>(null);\n\n  const { send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  async function handleFileSelect(event: React.ChangeEvent<HTMLInputElement>) {\n    const files = event.target.files;\n    if (!files?.length) return;\n\n    setUploading(true);\n    try {\n      // Upload files with progress tracking\n      const fileRefs = await uploadFiles(files, (fileIndex, progress) => {\n        console.log(`File ${fileIndex}: ${progress}%`);\n      });\n      setPendingFiles((prev) => [...prev, ...fileRefs]);\n    } finally {\n      setUploading(false);\n    }\n  }\n\n  async function handleSend(message: string) {\n    await send(\n      'user-message',\n      {\n        USER_MESSAGE: message,\n        FILES: pendingFiles.length > 0 ? pendingFiles : undefined,\n      },\n      {\n        userMessage: {\n          content: message,\n          files: pendingFiles.length > 0 ? pendingFiles : undefined,\n        },\n      },\n    );\n    setPendingFiles([]);\n  }\n\n  return (\n    <div>\n      {/* File preview */}\n      {pendingFiles.map((file) => (\n        <img key={file.id} src={file.url} alt={file.filename} className=\"h-16\" />\n      ))}\n\n      <input\n        ref={fileInputRef}\n        type=\"file\"\n        accept=\"image/*,.pdf\"\n        multiple\n        onChange={handleFileSelect}\n        className=\"hidden\"\n      />\n\n      <button onClick={() => fileInputRef.current?.click()} disabled={uploading}>\n        {uploading ? 'Uploading...' : 'Attach'}\n      </button>\n    </div>\n  );\n}\n```\n\n### Method 2: Upload on Send (Automatic)\n\nFor simpler implementations, pass `File` objects directly:\n\n```tsx\nasync function handleSend(message: string, files?: File[]) {\n  await send(\n    'user-message',\n    { USER_MESSAGE: message, FILES: files },\n    { userMessage: { content: message, files } },\n  );\n}\n```\n\nThe SDK automatically uploads the files before sending. Note: This doesn't provide upload progress.\n\n## FileReference Type\n\nFile references contain metadata and URLs:\n\n```typescript\ninterface FileReference {\n  /** Unique file ID (platform-generated) */\n  id: string;\n  /** IANA media type (e.g., 'image/png', 'application/pdf') */\n  mediaType: string;\n  /** Presigned download URL (S3) */\n  url: string;\n  /** Original filename */\n  filename?: string;\n  /** File size in bytes */\n  size?: number;\n}\n```\n\n## Protocol Integration\n\nTo accept files in your agent protocol, use the `file[]` type:\n\n```yaml\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n      FILES:\n        type: file[]\n        optional: true\n        description: User-attached images for vision analysis\n\nhandlers:\n  user-message:\n    Add user message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input:\n        - USER_MESSAGE\n      files:\n        - FILES # Attach files to the message\n      display: hidden\n\n    Respond to user:\n      block: next-message\n```\n\nThe `file` type is a built-in type representing uploaded files. Use `file[]` for arrays of files.\n\n## Supported File Types\n\n| Type      | Media Types                                                          |\n| --------- | -------------------------------------------------------------------- |\n| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |\n| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |\n\n## File Limits\n\n| Limit                 | Value      |\n| --------------------- | ---------- |\n| Max file size         | 10 MB      |\n| Max total per request | 50 MB      |\n| Max files per request | 20         |\n| Upload URL expiry     | 15 minutes |\n| Download URL expiry   | 24 hours   |\n\n## Rendering User Files\n\nUser-uploaded files appear as `UIFilePart` in user messages:\n\n```tsx\nfunction UserMessage({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => {\n        if (part.type === 'file') {\n          if (part.mediaType.startsWith('image/')) {\n            return (\n              <img\n                key={i}\n                src={part.url}\n                alt={part.filename || 'Uploaded image'}\n                className=\"max-h-48 rounded-lg\"\n              />\n            );\n          }\n          return (\n            <a key={i} href={part.url} className=\"text-blue-500\">\n              \u{1F4C4} {part.filename}\n            </a>\n          );\n        }\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## Server SDK: Files API\n\nThe Server SDK provides direct access to the Files API:\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// Get presigned upload URLs\nconst { files } = await client.files.getUploadUrls(sessionId, [\n  { filename: 'photo.jpg', mediaType: 'image/jpeg', size: 102400 },\n  { filename: 'doc.pdf', mediaType: 'application/pdf', size: 204800 },\n]);\n\n// files[0].id - Use in FileReference\n// files[0].uploadUrl - PUT to this URL to upload\n// files[0].downloadUrl - Use as FileReference.url\n```\n\n## Complete Example\n\nHere's a full chat input component with file upload:\n\n```tsx\n'use client';\n\nimport { useState, useRef, useMemo, useCallback } from 'react';\nimport { useOctavusChat, createHttpTransport, type FileReference } from '@octavus/react';\n\ninterface PendingFile {\n  file: File;\n  id: string;\n  status: 'uploading' | 'done' | 'error';\n  progress: number;\n  fileRef?: FileReference;\n  error?: string;\n}\n\nexport function Chat({ sessionId }: { sessionId: string }) {\n  const [input, setInput] = useState('');\n  const [pendingFiles, setPendingFiles] = useState<PendingFile[]>([]);\n  const fileInputRef = useRef<HTMLInputElement>(null);\n  const fileIdCounter = useRef(0);\n\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 requestUploadUrls = useCallback(\n    async (files: { filename: string; mediaType: string; size: number }[]) => {\n      const res = await fetch('/api/upload-urls', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, files }),\n      });\n      return res.json();\n    },\n    [sessionId],\n  );\n\n  const { messages, status, send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  const isUploading = pendingFiles.some((f) => f.status === 'uploading');\n  const hasErrors = pendingFiles.some((f) => f.status === 'error');\n  const allReady = pendingFiles.every((f) => f.status === 'done');\n\n  async function handleFileSelect(e: React.ChangeEvent<HTMLInputElement>) {\n    const files = Array.from(e.target.files ?? []);\n    if (!files.length) return;\n    e.target.value = '';\n\n    const newPending: PendingFile[] = files.map((file) => ({\n      file,\n      id: `pending-${++fileIdCounter.current}`,\n      status: 'uploading',\n      progress: 0,\n    }));\n\n    setPendingFiles((prev) => [...prev, ...newPending]);\n\n    for (const pending of newPending) {\n      try {\n        const [fileRef] = await uploadFiles([pending.file], (_, progress) => {\n          setPendingFiles((prev) =>\n            prev.map((f) => (f.id === pending.id ? { ...f, progress } : f)),\n          );\n        });\n        setPendingFiles((prev) =>\n          prev.map((f) => (f.id === pending.id ? { ...f, status: 'done', fileRef } : f)),\n        );\n      } catch (err) {\n        setPendingFiles((prev) =>\n          prev.map((f) =>\n            f.id === pending.id ? { ...f, status: 'error', error: String(err) } : f,\n          ),\n        );\n      }\n    }\n  }\n\n  async function handleSubmit() {\n    if ((!input.trim() && !pendingFiles.length) || !allReady) return;\n\n    const fileRefs = pendingFiles.filter((f) => f.fileRef).map((f) => f.fileRef!);\n\n    await send(\n      'user-message',\n      {\n        USER_MESSAGE: input,\n        FILES: fileRefs.length > 0 ? fileRefs : undefined,\n      },\n      {\n        userMessage: {\n          content: input,\n          files: fileRefs.length > 0 ? fileRefs : undefined,\n        },\n      },\n    );\n\n    setInput('');\n    setPendingFiles([]);\n  }\n\n  return (\n    <div>\n      {/* Messages */}\n      {messages.map((msg) => (\n        <div key={msg.id}>{/* ... render message */}</div>\n      ))}\n\n      {/* Pending files */}\n      {pendingFiles.length > 0 && (\n        <div className=\"flex gap-2\">\n          {pendingFiles.map((f) => (\n            <div key={f.id} className=\"relative\">\n              <img\n                src={URL.createObjectURL(f.file)}\n                alt={f.file.name}\n                className=\"h-16 w-16 object-cover rounded\"\n              />\n              {f.status === 'uploading' && (\n                <div className=\"absolute inset-0 flex items-center justify-center bg-black/50\">\n                  <span className=\"text-white text-xs\">{f.progress}%</span>\n                </div>\n              )}\n              <button\n                onClick={() => setPendingFiles((prev) => prev.filter((p) => p.id !== f.id))}\n                className=\"absolute -top-2 -right-2 bg-red-500 text-white rounded-full w-5 h-5\"\n              >\n                \xD7\n              </button>\n            </div>\n          ))}\n        </div>\n      )}\n\n      {/* Input */}\n      <div className=\"flex gap-2\">\n        <input type=\"file\" ref={fileInputRef} onChange={handleFileSelect} hidden />\n        <button onClick={() => fileInputRef.current?.click()}>\u{1F4CE}</button>\n        <input\n          value={input}\n          onChange={(e) => setInput(e.target.value)}\n          placeholder=\"Type a message...\"\n          className=\"flex-1\"\n        />\n        <button onClick={handleSubmit} disabled={isUploading || hasErrors}>\n          {isUploading ? 'Uploading...' : 'Send'}\n        </button>\n      </div>\n    </div>\n  );\n}\n```\n",
+    content: "\n# File Uploads\n\nThe Client SDK supports uploading images and documents that can be sent with messages. This enables vision model capabilities (analyzing images) and document processing.\n\n## Overview\n\nFile uploads follow a two-step flow:\n\n1. **Request upload URLs** from the platform via your backend\n2. **Upload files directly to S3** using presigned URLs\n3. **Send file references** with your message\n\nThis architecture keeps your API key secure on the server while enabling fast, direct uploads.\n\n## Setup\n\n### Backend: Upload URLs Endpoint\n\nCreate an endpoint that proxies upload URL requests to the Octavus platform:\n\n```typescript\n// app/api/upload-urls/route.ts (Next.js)\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, files } = await request.json();\n\n  // Get presigned URLs from Octavus\n  const result = await octavus.files.getUploadUrls(sessionId, files);\n\n  return NextResponse.json(result);\n}\n```\n\n### Client: Configure File Uploads\n\nPass `requestUploadUrls` to the chat hook:\n\n```tsx\nimport { useMemo, useCallback } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  // Request upload URLs from your backend\n  const requestUploadUrls = useCallback(\n    async (files: { filename: string; mediaType: string; size: number }[]) => {\n      const response = await fetch('/api/upload-urls', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, files }),\n      });\n      return response.json();\n    },\n    [sessionId],\n  );\n\n  const { messages, status, send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n    // Optional: configure upload timeout and retry behavior\n    uploadOptions: {\n      timeoutMs: 60_000, // Per-file timeout (default: 60s, set to 0 to disable)\n      maxRetries: 2, // Retry attempts on transient failures (default: 2)\n      retryDelayMs: 1_000, // Delay between retries (default: 1s)\n    },\n  });\n\n  // ...\n}\n```\n\n## Uploading Files\n\n### Method 1: Upload Before Sending\n\nFor the best UX (showing upload progress), upload files first, then send:\n\n```tsx\nimport { useState, useRef } from 'react';\nimport type { FileReference } from '@octavus/react';\n\nfunction ChatInput({ sessionId }: { sessionId: string }) {\n  const [pendingFiles, setPendingFiles] = useState<FileReference[]>([]);\n  const [uploading, setUploading] = useState(false);\n  const fileInputRef = useRef<HTMLInputElement>(null);\n\n  const { send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  async function handleFileSelect(event: React.ChangeEvent<HTMLInputElement>) {\n    const files = event.target.files;\n    if (!files?.length) return;\n\n    setUploading(true);\n    try {\n      // Upload files with progress tracking\n      const fileRefs = await uploadFiles(files, (fileIndex, progress) => {\n        console.log(`File ${fileIndex}: ${progress}%`);\n      });\n      setPendingFiles((prev) => [...prev, ...fileRefs]);\n    } finally {\n      setUploading(false);\n    }\n  }\n\n  async function handleSend(message: string) {\n    await send(\n      'user-message',\n      {\n        USER_MESSAGE: message,\n        FILES: pendingFiles.length > 0 ? pendingFiles : undefined,\n      },\n      {\n        userMessage: {\n          content: message,\n          files: pendingFiles.length > 0 ? pendingFiles : undefined,\n        },\n      },\n    );\n    setPendingFiles([]);\n  }\n\n  return (\n    <div>\n      {/* File preview */}\n      {pendingFiles.map((file) => (\n        <img key={file.id} src={file.url} alt={file.filename} className=\"h-16\" />\n      ))}\n\n      <input\n        ref={fileInputRef}\n        type=\"file\"\n        accept=\"image/*,.pdf\"\n        multiple\n        onChange={handleFileSelect}\n        className=\"hidden\"\n      />\n\n      <button onClick={() => fileInputRef.current?.click()} disabled={uploading}>\n        {uploading ? 'Uploading...' : 'Attach'}\n      </button>\n    </div>\n  );\n}\n```\n\n### Method 2: Upload on Send (Automatic)\n\nFor simpler implementations, pass `File` objects directly:\n\n```tsx\nasync function handleSend(message: string, files?: File[]) {\n  await send(\n    'user-message',\n    { USER_MESSAGE: message, FILES: files },\n    { userMessage: { content: message, files } },\n  );\n}\n```\n\nThe SDK automatically uploads the files before sending. Note: This doesn't provide upload progress.\n\n## Upload Reliability\n\nUploads include built-in timeout and retry logic for handling transient failures (network errors, server issues, mobile network switches).\n\n**Default behavior:**\n\n- **Timeout**: 60 seconds per file \u2014 prevents uploads from hanging on stalled connections\n- **Retries**: 2 automatic retries on transient failures (network errors, 5xx, 429)\n- **Retry delay**: 1 second between retries\n- **Non-retryable errors** (4xx like 403, 404) fail immediately without retrying\n\nOnly the S3 upload is retried \u2014 the presigned URL stays valid for 15 minutes. On retry, the progress callback resets to 0%.\n\nConfigure via `uploadOptions`:\n\n```typescript\nconst { send, uploadFiles } = useOctavusChat({\n  transport,\n  requestUploadUrls,\n  uploadOptions: {\n    timeoutMs: 120_000, // 2 minutes for large files\n    maxRetries: 3,\n    retryDelayMs: 2_000,\n  },\n});\n```\n\nTo disable timeout or retries:\n\n```typescript\nuploadOptions: {\n  timeoutMs: 0,    // No timeout\n  maxRetries: 0,   // No retries\n}\n```\n\n### Using `OctavusChat` Directly\n\nWhen using the `OctavusChat` class directly (without the React hook), pass `uploadOptions` in the constructor:\n\n```typescript\nconst chat = new OctavusChat({\n  transport,\n  requestUploadUrls,\n  uploadOptions: { timeoutMs: 120_000, maxRetries: 3 },\n});\n```\n\n## FileReference Type\n\nFile references contain metadata and URLs:\n\n```typescript\ninterface FileReference {\n  /** Unique file ID (platform-generated) */\n  id: string;\n  /** IANA media type (e.g., 'image/png', 'application/pdf') */\n  mediaType: string;\n  /** Presigned download URL (S3) */\n  url: string;\n  /** Original filename */\n  filename?: string;\n  /** File size in bytes */\n  size?: number;\n}\n```\n\n## Protocol Integration\n\nTo accept files in your agent protocol, use the `file[]` type:\n\n```yaml\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n      FILES:\n        type: file[]\n        optional: true\n        description: User-attached images for vision analysis\n\nhandlers:\n  user-message:\n    Add user message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input:\n        - USER_MESSAGE\n      files:\n        - FILES # Attach files to the message\n      display: hidden\n\n    Respond to user:\n      block: next-message\n```\n\nThe `file` type is a built-in type representing uploaded files. Use `file[]` for arrays of files.\n\n## Supported File Types\n\n| Type      | Media Types                                                          |\n| --------- | -------------------------------------------------------------------- |\n| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |\n| Video     | `video/mp4`, `video/webm`, `video/quicktime`, `video/mpeg`           |\n| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |\n\n## File Limits\n\n| Limit                 | Value      |\n| --------------------- | ---------- |\n| Max file size         | 100 MB     |\n| Max total per request | 200 MB     |\n| Upload URL expiry     | 15 minutes |\n| Download URL expiry   | 24 hours   |\n\n## Rendering User Files\n\nUser-uploaded files appear as `UIFilePart` in user messages:\n\n```tsx\nfunction UserMessage({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => {\n        if (part.type === 'file') {\n          if (part.mediaType.startsWith('image/')) {\n            return (\n              <img\n                key={i}\n                src={part.url}\n                alt={part.filename || 'Uploaded image'}\n                className=\"max-h-48 rounded-lg\"\n              />\n            );\n          }\n          return (\n            <a key={i} href={part.url} className=\"text-blue-500\">\n              \u{1F4C4} {part.filename}\n            </a>\n          );\n        }\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## Server SDK: Files API\n\nThe Server SDK provides direct access to the Files API:\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// Get presigned upload URLs\nconst { files } = await client.files.getUploadUrls(sessionId, [\n  { filename: 'photo.jpg', mediaType: 'image/jpeg', size: 102400 },\n  { filename: 'doc.pdf', mediaType: 'application/pdf', size: 204800 },\n]);\n\n// files[0].id - Use in FileReference\n// files[0].uploadUrl - PUT to this URL to upload\n// files[0].downloadUrl - Use as FileReference.url\n```\n\n## Complete Example\n\nHere's a full chat input component with file upload:\n\n```tsx\n'use client';\n\nimport { useState, useRef, useMemo, useCallback } from 'react';\nimport { useOctavusChat, createHttpTransport, type FileReference } from '@octavus/react';\n\ninterface PendingFile {\n  file: File;\n  id: string;\n  status: 'uploading' | 'done' | 'error';\n  progress: number;\n  fileRef?: FileReference;\n  error?: string;\n}\n\nexport function Chat({ sessionId }: { sessionId: string }) {\n  const [input, setInput] = useState('');\n  const [pendingFiles, setPendingFiles] = useState<PendingFile[]>([]);\n  const fileInputRef = useRef<HTMLInputElement>(null);\n  const fileIdCounter = useRef(0);\n\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 requestUploadUrls = useCallback(\n    async (files: { filename: string; mediaType: string; size: number }[]) => {\n      const res = await fetch('/api/upload-urls', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, files }),\n      });\n      return res.json();\n    },\n    [sessionId],\n  );\n\n  const { messages, status, send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  const isUploading = pendingFiles.some((f) => f.status === 'uploading');\n  const hasErrors = pendingFiles.some((f) => f.status === 'error');\n  const allReady = pendingFiles.every((f) => f.status === 'done');\n\n  async function handleFileSelect(e: React.ChangeEvent<HTMLInputElement>) {\n    const files = Array.from(e.target.files ?? []);\n    if (!files.length) return;\n    e.target.value = '';\n\n    const newPending: PendingFile[] = files.map((file) => ({\n      file,\n      id: `pending-${++fileIdCounter.current}`,\n      status: 'uploading',\n      progress: 0,\n    }));\n\n    setPendingFiles((prev) => [...prev, ...newPending]);\n\n    for (const pending of newPending) {\n      try {\n        const [fileRef] = await uploadFiles([pending.file], (_, progress) => {\n          setPendingFiles((prev) =>\n            prev.map((f) => (f.id === pending.id ? { ...f, progress } : f)),\n          );\n        });\n        setPendingFiles((prev) =>\n          prev.map((f) => (f.id === pending.id ? { ...f, status: 'done', fileRef } : f)),\n        );\n      } catch (err) {\n        setPendingFiles((prev) =>\n          prev.map((f) =>\n            f.id === pending.id ? { ...f, status: 'error', error: String(err) } : f,\n          ),\n        );\n      }\n    }\n  }\n\n  async function handleSubmit() {\n    if ((!input.trim() && !pendingFiles.length) || !allReady) return;\n\n    const fileRefs = pendingFiles.filter((f) => f.fileRef).map((f) => f.fileRef!);\n\n    await send(\n      'user-message',\n      {\n        USER_MESSAGE: input,\n        FILES: fileRefs.length > 0 ? fileRefs : undefined,\n      },\n      {\n        userMessage: {\n          content: input,\n          files: fileRefs.length > 0 ? fileRefs : undefined,\n        },\n      },\n    );\n\n    setInput('');\n    setPendingFiles([]);\n  }\n\n  return (\n    <div>\n      {/* Messages */}\n      {messages.map((msg) => (\n        <div key={msg.id}>{/* ... render message */}</div>\n      ))}\n\n      {/* Pending files */}\n      {pendingFiles.length > 0 && (\n        <div className=\"flex gap-2\">\n          {pendingFiles.map((f) => (\n            <div key={f.id} className=\"relative\">\n              <img\n                src={URL.createObjectURL(f.file)}\n                alt={f.file.name}\n                className=\"h-16 w-16 object-cover rounded\"\n              />\n              {f.status === 'uploading' && (\n                <div className=\"absolute inset-0 flex items-center justify-center bg-black/50\">\n                  <span className=\"text-white text-xs\">{f.progress}%</span>\n                </div>\n              )}\n              <button\n                onClick={() => setPendingFiles((prev) => prev.filter((p) => p.id !== f.id))}\n                className=\"absolute -top-2 -right-2 bg-red-500 text-white rounded-full w-5 h-5\"\n              >\n                \xD7\n              </button>\n            </div>\n          ))}\n        </div>\n      )}\n\n      {/* Input */}\n      <div className=\"flex gap-2\">\n        <input type=\"file\" ref={fileInputRef} onChange={handleFileSelect} hidden />\n        <button onClick={() => fileInputRef.current?.click()}>\u{1F4CE}</button>\n        <input\n          value={input}\n          onChange={(e) => setInput(e.target.value)}\n          placeholder=\"Type a message...\"\n          className=\"flex-1\"\n        />\n        <button onClick={handleSubmit} disabled={isUploading || hasErrors}>\n          {isUploading ? 'Uploading...' : 'Send'}\n        </button>\n      </div>\n    </div>\n  );\n}\n```\n",
     excerpt: "File Uploads The Client SDK supports uploading images and documents that can be sent with messages. This enables vision model capabilities (analyzing images) and document processing.  Overview File...",
     order: 8
   },
@@ -1236,7 +1236,7 @@ See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list
         section: "client-sdk",
         title: "File Uploads",
         description: "Uploading images and files for vision models and document processing.",
-        content: "\n# File Uploads\n\nThe Client SDK supports uploading images and documents that can be sent with messages. This enables vision model capabilities (analyzing images) and document processing.\n\n## Overview\n\nFile uploads follow a two-step flow:\n\n1. **Request upload URLs** from the platform via your backend\n2. **Upload files directly to S3** using presigned URLs\n3. **Send file references** with your message\n\nThis architecture keeps your API key secure on the server while enabling fast, direct uploads.\n\n## Setup\n\n### Backend: Upload URLs Endpoint\n\nCreate an endpoint that proxies upload URL requests to the Octavus platform:\n\n```typescript\n// app/api/upload-urls/route.ts (Next.js)\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, files } = await request.json();\n\n  // Get presigned URLs from Octavus\n  const result = await octavus.files.getUploadUrls(sessionId, files);\n\n  return NextResponse.json(result);\n}\n```\n\n### Client: Configure File Uploads\n\nPass `requestUploadUrls` to the chat hook:\n\n```tsx\nimport { useMemo, useCallback } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  // Request upload URLs from your backend\n  const requestUploadUrls = useCallback(\n    async (files: { filename: string; mediaType: string; size: number }[]) => {\n      const response = await fetch('/api/upload-urls', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, files }),\n      });\n      return response.json();\n    },\n    [sessionId],\n  );\n\n  const { messages, status, send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  // ...\n}\n```\n\n## Uploading Files\n\n### Method 1: Upload Before Sending\n\nFor the best UX (showing upload progress), upload files first, then send:\n\n```tsx\nimport { useState, useRef } from 'react';\nimport type { FileReference } from '@octavus/react';\n\nfunction ChatInput({ sessionId }: { sessionId: string }) {\n  const [pendingFiles, setPendingFiles] = useState<FileReference[]>([]);\n  const [uploading, setUploading] = useState(false);\n  const fileInputRef = useRef<HTMLInputElement>(null);\n\n  const { send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  async function handleFileSelect(event: React.ChangeEvent<HTMLInputElement>) {\n    const files = event.target.files;\n    if (!files?.length) return;\n\n    setUploading(true);\n    try {\n      // Upload files with progress tracking\n      const fileRefs = await uploadFiles(files, (fileIndex, progress) => {\n        console.log(`File ${fileIndex}: ${progress}%`);\n      });\n      setPendingFiles((prev) => [...prev, ...fileRefs]);\n    } finally {\n      setUploading(false);\n    }\n  }\n\n  async function handleSend(message: string) {\n    await send(\n      'user-message',\n      {\n        USER_MESSAGE: message,\n        FILES: pendingFiles.length > 0 ? pendingFiles : undefined,\n      },\n      {\n        userMessage: {\n          content: message,\n          files: pendingFiles.length > 0 ? pendingFiles : undefined,\n        },\n      },\n    );\n    setPendingFiles([]);\n  }\n\n  return (\n    <div>\n      {/* File preview */}\n      {pendingFiles.map((file) => (\n        <img key={file.id} src={file.url} alt={file.filename} className=\"h-16\" />\n      ))}\n\n      <input\n        ref={fileInputRef}\n        type=\"file\"\n        accept=\"image/*,.pdf\"\n        multiple\n        onChange={handleFileSelect}\n        className=\"hidden\"\n      />\n\n      <button onClick={() => fileInputRef.current?.click()} disabled={uploading}>\n        {uploading ? 'Uploading...' : 'Attach'}\n      </button>\n    </div>\n  );\n}\n```\n\n### Method 2: Upload on Send (Automatic)\n\nFor simpler implementations, pass `File` objects directly:\n\n```tsx\nasync function handleSend(message: string, files?: File[]) {\n  await send(\n    'user-message',\n    { USER_MESSAGE: message, FILES: files },\n    { userMessage: { content: message, files } },\n  );\n}\n```\n\nThe SDK automatically uploads the files before sending. Note: This doesn't provide upload progress.\n\n## FileReference Type\n\nFile references contain metadata and URLs:\n\n```typescript\ninterface FileReference {\n  /** Unique file ID (platform-generated) */\n  id: string;\n  /** IANA media type (e.g., 'image/png', 'application/pdf') */\n  mediaType: string;\n  /** Presigned download URL (S3) */\n  url: string;\n  /** Original filename */\n  filename?: string;\n  /** File size in bytes */\n  size?: number;\n}\n```\n\n## Protocol Integration\n\nTo accept files in your agent protocol, use the `file[]` type:\n\n```yaml\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n      FILES:\n        type: file[]\n        optional: true\n        description: User-attached images for vision analysis\n\nhandlers:\n  user-message:\n    Add user message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input:\n        - USER_MESSAGE\n      files:\n        - FILES # Attach files to the message\n      display: hidden\n\n    Respond to user:\n      block: next-message\n```\n\nThe `file` type is a built-in type representing uploaded files. Use `file[]` for arrays of files.\n\n## Supported File Types\n\n| Type      | Media Types                                                          |\n| --------- | -------------------------------------------------------------------- |\n| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |\n| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |\n\n## File Limits\n\n| Limit                 | Value      |\n| --------------------- | ---------- |\n| Max file size         | 10 MB      |\n| Max total per request | 50 MB      |\n| Max files per request | 20         |\n| Upload URL expiry     | 15 minutes |\n| Download URL expiry   | 24 hours   |\n\n## Rendering User Files\n\nUser-uploaded files appear as `UIFilePart` in user messages:\n\n```tsx\nfunction UserMessage({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => {\n        if (part.type === 'file') {\n          if (part.mediaType.startsWith('image/')) {\n            return (\n              <img\n                key={i}\n                src={part.url}\n                alt={part.filename || 'Uploaded image'}\n                className=\"max-h-48 rounded-lg\"\n              />\n            );\n          }\n          return (\n            <a key={i} href={part.url} className=\"text-blue-500\">\n              \u{1F4C4} {part.filename}\n            </a>\n          );\n        }\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## Server SDK: Files API\n\nThe Server SDK provides direct access to the Files API:\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// Get presigned upload URLs\nconst { files } = await client.files.getUploadUrls(sessionId, [\n  { filename: 'photo.jpg', mediaType: 'image/jpeg', size: 102400 },\n  { filename: 'doc.pdf', mediaType: 'application/pdf', size: 204800 },\n]);\n\n// files[0].id - Use in FileReference\n// files[0].uploadUrl - PUT to this URL to upload\n// files[0].downloadUrl - Use as FileReference.url\n```\n\n## Complete Example\n\nHere's a full chat input component with file upload:\n\n```tsx\n'use client';\n\nimport { useState, useRef, useMemo, useCallback } from 'react';\nimport { useOctavusChat, createHttpTransport, type FileReference } from '@octavus/react';\n\ninterface PendingFile {\n  file: File;\n  id: string;\n  status: 'uploading' | 'done' | 'error';\n  progress: number;\n  fileRef?: FileReference;\n  error?: string;\n}\n\nexport function Chat({ sessionId }: { sessionId: string }) {\n  const [input, setInput] = useState('');\n  const [pendingFiles, setPendingFiles] = useState<PendingFile[]>([]);\n  const fileInputRef = useRef<HTMLInputElement>(null);\n  const fileIdCounter = useRef(0);\n\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 requestUploadUrls = useCallback(\n    async (files: { filename: string; mediaType: string; size: number }[]) => {\n      const res = await fetch('/api/upload-urls', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, files }),\n      });\n      return res.json();\n    },\n    [sessionId],\n  );\n\n  const { messages, status, send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  const isUploading = pendingFiles.some((f) => f.status === 'uploading');\n  const hasErrors = pendingFiles.some((f) => f.status === 'error');\n  const allReady = pendingFiles.every((f) => f.status === 'done');\n\n  async function handleFileSelect(e: React.ChangeEvent<HTMLInputElement>) {\n    const files = Array.from(e.target.files ?? []);\n    if (!files.length) return;\n    e.target.value = '';\n\n    const newPending: PendingFile[] = files.map((file) => ({\n      file,\n      id: `pending-${++fileIdCounter.current}`,\n      status: 'uploading',\n      progress: 0,\n    }));\n\n    setPendingFiles((prev) => [...prev, ...newPending]);\n\n    for (const pending of newPending) {\n      try {\n        const [fileRef] = await uploadFiles([pending.file], (_, progress) => {\n          setPendingFiles((prev) =>\n            prev.map((f) => (f.id === pending.id ? { ...f, progress } : f)),\n          );\n        });\n        setPendingFiles((prev) =>\n          prev.map((f) => (f.id === pending.id ? { ...f, status: 'done', fileRef } : f)),\n        );\n      } catch (err) {\n        setPendingFiles((prev) =>\n          prev.map((f) =>\n            f.id === pending.id ? { ...f, status: 'error', error: String(err) } : f,\n          ),\n        );\n      }\n    }\n  }\n\n  async function handleSubmit() {\n    if ((!input.trim() && !pendingFiles.length) || !allReady) return;\n\n    const fileRefs = pendingFiles.filter((f) => f.fileRef).map((f) => f.fileRef!);\n\n    await send(\n      'user-message',\n      {\n        USER_MESSAGE: input,\n        FILES: fileRefs.length > 0 ? fileRefs : undefined,\n      },\n      {\n        userMessage: {\n          content: input,\n          files: fileRefs.length > 0 ? fileRefs : undefined,\n        },\n      },\n    );\n\n    setInput('');\n    setPendingFiles([]);\n  }\n\n  return (\n    <div>\n      {/* Messages */}\n      {messages.map((msg) => (\n        <div key={msg.id}>{/* ... render message */}</div>\n      ))}\n\n      {/* Pending files */}\n      {pendingFiles.length > 0 && (\n        <div className=\"flex gap-2\">\n          {pendingFiles.map((f) => (\n            <div key={f.id} className=\"relative\">\n              <img\n                src={URL.createObjectURL(f.file)}\n                alt={f.file.name}\n                className=\"h-16 w-16 object-cover rounded\"\n              />\n              {f.status === 'uploading' && (\n                <div className=\"absolute inset-0 flex items-center justify-center bg-black/50\">\n                  <span className=\"text-white text-xs\">{f.progress}%</span>\n                </div>\n              )}\n              <button\n                onClick={() => setPendingFiles((prev) => prev.filter((p) => p.id !== f.id))}\n                className=\"absolute -top-2 -right-2 bg-red-500 text-white rounded-full w-5 h-5\"\n              >\n                \xD7\n              </button>\n            </div>\n          ))}\n        </div>\n      )}\n\n      {/* Input */}\n      <div className=\"flex gap-2\">\n        <input type=\"file\" ref={fileInputRef} onChange={handleFileSelect} hidden />\n        <button onClick={() => fileInputRef.current?.click()}>\u{1F4CE}</button>\n        <input\n          value={input}\n          onChange={(e) => setInput(e.target.value)}\n          placeholder=\"Type a message...\"\n          className=\"flex-1\"\n        />\n        <button onClick={handleSubmit} disabled={isUploading || hasErrors}>\n          {isUploading ? 'Uploading...' : 'Send'}\n        </button>\n      </div>\n    </div>\n  );\n}\n```\n",
+        content: "\n# File Uploads\n\nThe Client SDK supports uploading images and documents that can be sent with messages. This enables vision model capabilities (analyzing images) and document processing.\n\n## Overview\n\nFile uploads follow a two-step flow:\n\n1. **Request upload URLs** from the platform via your backend\n2. **Upload files directly to S3** using presigned URLs\n3. **Send file references** with your message\n\nThis architecture keeps your API key secure on the server while enabling fast, direct uploads.\n\n## Setup\n\n### Backend: Upload URLs Endpoint\n\nCreate an endpoint that proxies upload URL requests to the Octavus platform:\n\n```typescript\n// app/api/upload-urls/route.ts (Next.js)\nimport { NextResponse } from 'next/server';\nimport { octavus } from '@/lib/octavus';\n\nexport async function POST(request: Request) {\n  const { sessionId, files } = await request.json();\n\n  // Get presigned URLs from Octavus\n  const result = await octavus.files.getUploadUrls(sessionId, files);\n\n  return NextResponse.json(result);\n}\n```\n\n### Client: Configure File Uploads\n\nPass `requestUploadUrls` to the chat hook:\n\n```tsx\nimport { useMemo, useCallback } from 'react';\nimport { useOctavusChat, createHttpTransport } from '@octavus/react';\n\nfunction Chat({ sessionId }: { sessionId: string }) {\n  const transport = useMemo(\n    () =>\n      createHttpTransport({\n        request: (payload, options) =>\n          fetch('/api/trigger', {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ sessionId, ...payload }),\n            signal: options?.signal,\n          }),\n      }),\n    [sessionId],\n  );\n\n  // Request upload URLs from your backend\n  const requestUploadUrls = useCallback(\n    async (files: { filename: string; mediaType: string; size: number }[]) => {\n      const response = await fetch('/api/upload-urls', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, files }),\n      });\n      return response.json();\n    },\n    [sessionId],\n  );\n\n  const { messages, status, send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n    // Optional: configure upload timeout and retry behavior\n    uploadOptions: {\n      timeoutMs: 60_000, // Per-file timeout (default: 60s, set to 0 to disable)\n      maxRetries: 2, // Retry attempts on transient failures (default: 2)\n      retryDelayMs: 1_000, // Delay between retries (default: 1s)\n    },\n  });\n\n  // ...\n}\n```\n\n## Uploading Files\n\n### Method 1: Upload Before Sending\n\nFor the best UX (showing upload progress), upload files first, then send:\n\n```tsx\nimport { useState, useRef } from 'react';\nimport type { FileReference } from '@octavus/react';\n\nfunction ChatInput({ sessionId }: { sessionId: string }) {\n  const [pendingFiles, setPendingFiles] = useState<FileReference[]>([]);\n  const [uploading, setUploading] = useState(false);\n  const fileInputRef = useRef<HTMLInputElement>(null);\n\n  const { send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  async function handleFileSelect(event: React.ChangeEvent<HTMLInputElement>) {\n    const files = event.target.files;\n    if (!files?.length) return;\n\n    setUploading(true);\n    try {\n      // Upload files with progress tracking\n      const fileRefs = await uploadFiles(files, (fileIndex, progress) => {\n        console.log(`File ${fileIndex}: ${progress}%`);\n      });\n      setPendingFiles((prev) => [...prev, ...fileRefs]);\n    } finally {\n      setUploading(false);\n    }\n  }\n\n  async function handleSend(message: string) {\n    await send(\n      'user-message',\n      {\n        USER_MESSAGE: message,\n        FILES: pendingFiles.length > 0 ? pendingFiles : undefined,\n      },\n      {\n        userMessage: {\n          content: message,\n          files: pendingFiles.length > 0 ? pendingFiles : undefined,\n        },\n      },\n    );\n    setPendingFiles([]);\n  }\n\n  return (\n    <div>\n      {/* File preview */}\n      {pendingFiles.map((file) => (\n        <img key={file.id} src={file.url} alt={file.filename} className=\"h-16\" />\n      ))}\n\n      <input\n        ref={fileInputRef}\n        type=\"file\"\n        accept=\"image/*,.pdf\"\n        multiple\n        onChange={handleFileSelect}\n        className=\"hidden\"\n      />\n\n      <button onClick={() => fileInputRef.current?.click()} disabled={uploading}>\n        {uploading ? 'Uploading...' : 'Attach'}\n      </button>\n    </div>\n  );\n}\n```\n\n### Method 2: Upload on Send (Automatic)\n\nFor simpler implementations, pass `File` objects directly:\n\n```tsx\nasync function handleSend(message: string, files?: File[]) {\n  await send(\n    'user-message',\n    { USER_MESSAGE: message, FILES: files },\n    { userMessage: { content: message, files } },\n  );\n}\n```\n\nThe SDK automatically uploads the files before sending. Note: This doesn't provide upload progress.\n\n## Upload Reliability\n\nUploads include built-in timeout and retry logic for handling transient failures (network errors, server issues, mobile network switches).\n\n**Default behavior:**\n\n- **Timeout**: 60 seconds per file \u2014 prevents uploads from hanging on stalled connections\n- **Retries**: 2 automatic retries on transient failures (network errors, 5xx, 429)\n- **Retry delay**: 1 second between retries\n- **Non-retryable errors** (4xx like 403, 404) fail immediately without retrying\n\nOnly the S3 upload is retried \u2014 the presigned URL stays valid for 15 minutes. On retry, the progress callback resets to 0%.\n\nConfigure via `uploadOptions`:\n\n```typescript\nconst { send, uploadFiles } = useOctavusChat({\n  transport,\n  requestUploadUrls,\n  uploadOptions: {\n    timeoutMs: 120_000, // 2 minutes for large files\n    maxRetries: 3,\n    retryDelayMs: 2_000,\n  },\n});\n```\n\nTo disable timeout or retries:\n\n```typescript\nuploadOptions: {\n  timeoutMs: 0,    // No timeout\n  maxRetries: 0,   // No retries\n}\n```\n\n### Using `OctavusChat` Directly\n\nWhen using the `OctavusChat` class directly (without the React hook), pass `uploadOptions` in the constructor:\n\n```typescript\nconst chat = new OctavusChat({\n  transport,\n  requestUploadUrls,\n  uploadOptions: { timeoutMs: 120_000, maxRetries: 3 },\n});\n```\n\n## FileReference Type\n\nFile references contain metadata and URLs:\n\n```typescript\ninterface FileReference {\n  /** Unique file ID (platform-generated) */\n  id: string;\n  /** IANA media type (e.g., 'image/png', 'application/pdf') */\n  mediaType: string;\n  /** Presigned download URL (S3) */\n  url: string;\n  /** Original filename */\n  filename?: string;\n  /** File size in bytes */\n  size?: number;\n}\n```\n\n## Protocol Integration\n\nTo accept files in your agent protocol, use the `file[]` type:\n\n```yaml\ntriggers:\n  user-message:\n    input:\n      USER_MESSAGE:\n        type: string\n        description: The user's message\n      FILES:\n        type: file[]\n        optional: true\n        description: User-attached images for vision analysis\n\nhandlers:\n  user-message:\n    Add user message:\n      block: add-message\n      role: user\n      prompt: user-message\n      input:\n        - USER_MESSAGE\n      files:\n        - FILES # Attach files to the message\n      display: hidden\n\n    Respond to user:\n      block: next-message\n```\n\nThe `file` type is a built-in type representing uploaded files. Use `file[]` for arrays of files.\n\n## Supported File Types\n\n| Type      | Media Types                                                          |\n| --------- | -------------------------------------------------------------------- |\n| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |\n| Video     | `video/mp4`, `video/webm`, `video/quicktime`, `video/mpeg`           |\n| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |\n\n## File Limits\n\n| Limit                 | Value      |\n| --------------------- | ---------- |\n| Max file size         | 100 MB     |\n| Max total per request | 200 MB     |\n| Upload URL expiry     | 15 minutes |\n| Download URL expiry   | 24 hours   |\n\n## Rendering User Files\n\nUser-uploaded files appear as `UIFilePart` in user messages:\n\n```tsx\nfunction UserMessage({ message }: { message: UIMessage }) {\n  return (\n    <div>\n      {message.parts.map((part, i) => {\n        if (part.type === 'file') {\n          if (part.mediaType.startsWith('image/')) {\n            return (\n              <img\n                key={i}\n                src={part.url}\n                alt={part.filename || 'Uploaded image'}\n                className=\"max-h-48 rounded-lg\"\n              />\n            );\n          }\n          return (\n            <a key={i} href={part.url} className=\"text-blue-500\">\n              \u{1F4C4} {part.filename}\n            </a>\n          );\n        }\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## Server SDK: Files API\n\nThe Server SDK provides direct access to the Files API:\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// Get presigned upload URLs\nconst { files } = await client.files.getUploadUrls(sessionId, [\n  { filename: 'photo.jpg', mediaType: 'image/jpeg', size: 102400 },\n  { filename: 'doc.pdf', mediaType: 'application/pdf', size: 204800 },\n]);\n\n// files[0].id - Use in FileReference\n// files[0].uploadUrl - PUT to this URL to upload\n// files[0].downloadUrl - Use as FileReference.url\n```\n\n## Complete Example\n\nHere's a full chat input component with file upload:\n\n```tsx\n'use client';\n\nimport { useState, useRef, useMemo, useCallback } from 'react';\nimport { useOctavusChat, createHttpTransport, type FileReference } from '@octavus/react';\n\ninterface PendingFile {\n  file: File;\n  id: string;\n  status: 'uploading' | 'done' | 'error';\n  progress: number;\n  fileRef?: FileReference;\n  error?: string;\n}\n\nexport function Chat({ sessionId }: { sessionId: string }) {\n  const [input, setInput] = useState('');\n  const [pendingFiles, setPendingFiles] = useState<PendingFile[]>([]);\n  const fileInputRef = useRef<HTMLInputElement>(null);\n  const fileIdCounter = useRef(0);\n\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 requestUploadUrls = useCallback(\n    async (files: { filename: string; mediaType: string; size: number }[]) => {\n      const res = await fetch('/api/upload-urls', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, files }),\n      });\n      return res.json();\n    },\n    [sessionId],\n  );\n\n  const { messages, status, send, uploadFiles } = useOctavusChat({\n    transport,\n    requestUploadUrls,\n  });\n\n  const isUploading = pendingFiles.some((f) => f.status === 'uploading');\n  const hasErrors = pendingFiles.some((f) => f.status === 'error');\n  const allReady = pendingFiles.every((f) => f.status === 'done');\n\n  async function handleFileSelect(e: React.ChangeEvent<HTMLInputElement>) {\n    const files = Array.from(e.target.files ?? []);\n    if (!files.length) return;\n    e.target.value = '';\n\n    const newPending: PendingFile[] = files.map((file) => ({\n      file,\n      id: `pending-${++fileIdCounter.current}`,\n      status: 'uploading',\n      progress: 0,\n    }));\n\n    setPendingFiles((prev) => [...prev, ...newPending]);\n\n    for (const pending of newPending) {\n      try {\n        const [fileRef] = await uploadFiles([pending.file], (_, progress) => {\n          setPendingFiles((prev) =>\n            prev.map((f) => (f.id === pending.id ? { ...f, progress } : f)),\n          );\n        });\n        setPendingFiles((prev) =>\n          prev.map((f) => (f.id === pending.id ? { ...f, status: 'done', fileRef } : f)),\n        );\n      } catch (err) {\n        setPendingFiles((prev) =>\n          prev.map((f) =>\n            f.id === pending.id ? { ...f, status: 'error', error: String(err) } : f,\n          ),\n        );\n      }\n    }\n  }\n\n  async function handleSubmit() {\n    if ((!input.trim() && !pendingFiles.length) || !allReady) return;\n\n    const fileRefs = pendingFiles.filter((f) => f.fileRef).map((f) => f.fileRef!);\n\n    await send(\n      'user-message',\n      {\n        USER_MESSAGE: input,\n        FILES: fileRefs.length > 0 ? fileRefs : undefined,\n      },\n      {\n        userMessage: {\n          content: input,\n          files: fileRefs.length > 0 ? fileRefs : undefined,\n        },\n      },\n    );\n\n    setInput('');\n    setPendingFiles([]);\n  }\n\n  return (\n    <div>\n      {/* Messages */}\n      {messages.map((msg) => (\n        <div key={msg.id}>{/* ... render message */}</div>\n      ))}\n\n      {/* Pending files */}\n      {pendingFiles.length > 0 && (\n        <div className=\"flex gap-2\">\n          {pendingFiles.map((f) => (\n            <div key={f.id} className=\"relative\">\n              <img\n                src={URL.createObjectURL(f.file)}\n                alt={f.file.name}\n                className=\"h-16 w-16 object-cover rounded\"\n              />\n              {f.status === 'uploading' && (\n                <div className=\"absolute inset-0 flex items-center justify-center bg-black/50\">\n                  <span className=\"text-white text-xs\">{f.progress}%</span>\n                </div>\n              )}\n              <button\n                onClick={() => setPendingFiles((prev) => prev.filter((p) => p.id !== f.id))}\n                className=\"absolute -top-2 -right-2 bg-red-500 text-white rounded-full w-5 h-5\"\n              >\n                \xD7\n              </button>\n            </div>\n          ))}\n        </div>\n      )}\n\n      {/* Input */}\n      <div className=\"flex gap-2\">\n        <input type=\"file\" ref={fileInputRef} onChange={handleFileSelect} hidden />\n        <button onClick={() => fileInputRef.current?.click()}>\u{1F4CE}</button>\n        <input\n          value={input}\n          onChange={(e) => setInput(e.target.value)}\n          placeholder=\"Type a message...\"\n          className=\"flex-1\"\n        />\n        <button onClick={handleSubmit} disabled={isUploading || hasErrors}>\n          {isUploading ? 'Uploading...' : 'Send'}\n        </button>\n      </div>\n    </div>\n  );\n}\n```\n",
         excerpt: "File Uploads The Client SDK supports uploading images and documents that can be sent with messages. This enables vision model capabilities (analyzing images) and document processing.  Overview File...",
         order: 8
       },
@@ -1486,4 +1486,4 @@ export {
   getDocSlugs,
   getSectionBySlug
 };
-//# sourceMappingURL=chunk-EIUCL4CP.js.map
+//# sourceMappingURL=chunk-PQ5AGOPY.js.map