@octavus/docs 2.11.0 → 2.13.0

package/content/02-server-sdk/02-sessions.md

@@ -121,6 +121,7 @@ interface TriggerRequest {
   type: 'trigger';
   triggerName: string;
   input?: Record<string, unknown>;
+  rollbackAfterMessageId?: string | null; // For retry: truncate messages after this ID
 }
 
 // Continue after client-side tool handling

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/01-overview.md

@@ -183,6 +183,21 @@ const { stop } = useOctavusChat({ transport });
 stop();
 ```
 
+### Retry Last Trigger
+
+Re-execute the last trigger from the same starting point. Messages are rolled back to the state before the trigger, the user message is re-added (if any), and the agent re-executes. Already-uploaded files are reused without re-uploading.
+
+```tsx
+const { retry, canRetry } = useOctavusChat({ transport });
+
+// Retry after an error, cancellation, or unsatisfactory result
+if (canRetry) {
+  await retry();
+}
+```
+
+`canRetry` is `true` when a trigger has been sent and the chat is not currently streaming or awaiting input.
+
 ## Hook Reference (React)
 
 ### useOctavusChat
@@ -234,6 +249,8 @@ interface UseOctavusChatReturn {
     options?: { userMessage?: UserMessageInput },
   ) => Promise<void>;
   stop: () => void;
+  retry: () => Promise<void>; // Retry last trigger from same starting point
+  canRetry: boolean; // Whether retry() can be called
 
   // Connection management (socket transport only - undefined for HTTP)
   connect: (() => Promise<void>) | undefined;

package/content/03-client-sdk/06-http-transport.md

@@ -271,6 +271,7 @@ interface TriggerRequest {
   type: 'trigger';
   triggerName: string;
   input?: Record<string, unknown>;
+  rollbackAfterMessageId?: string | null; // For retry: truncate messages after this ID
 }
 
 // Continue after client-side tool handling

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/03-client-sdk/09-error-handling.md

@@ -124,6 +124,21 @@ if (isProviderError(error) && error.provider) {
 }
 ```
 
+## Retrying After Errors
+
+Use `retry()` to re-execute the last trigger from the same starting point. Messages are rolled back, the user message is re-added (if any), and the agent re-executes. Files are reused without re-uploading.
+
+```tsx
+const { error, canRetry, retry } = useOctavusChat({ transport });
+
+// Retry after any error
+if (canRetry) {
+  await retry();
+}
+```
+
+`retry()` also works after stopping (cancellation) or when the result is unsatisfactory — not just errors.
+
 ## Building Error UI
 
 ```tsx
@@ -135,7 +150,7 @@ import {
 } from '@octavus/react';
 
 function Chat() {
-  const { error, status } = useOctavusChat({ transport });
+  const { error, status, retry, canRetry } = useOctavusChat({ transport });
 
   return (
     <div>
@@ -149,7 +164,11 @@ function Chat() {
               Please try again in {error.retryAfter} seconds
             </p>
           )}
-          {error.retryable && <button className="mt-3 text-red-700 underline">Try again</button>}
+          {canRetry && (
+            <button className="mt-3 text-red-700 underline" onClick={() => void retry()}>
+              Retry
+            </button>
+          )}
         </div>
       )}
     </div>
@@ -197,12 +216,17 @@ useOctavusChat({
 The hook exposes error state directly:
 
 ```typescript
-const { error, status } = useOctavusChat({ transport });
+const { error, status, retry, canRetry } = useOctavusChat({ transport });
 
 // status is 'error' when an error occurred
 // error contains the OctavusError object
 
-// Clear error by sending a new message
+// Option 1: Retry the same trigger (rolls back messages, re-executes)
+if (canRetry) {
+  await retry();
+}
+
+// Option 2: Send a new message (clears the error)
 await send('user-message', { USER_MESSAGE: 'Try again' });
 ```
 

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

@@ -81,6 +81,7 @@ agent:
   tools: [get-user-account]
   skills: [qr-code] # Enable skills
   imageModel: google/gemini-2.5-flash-image # Enable image generation
+  webSearch: true # Enable web search
   agentic: true # Allow multiple tool calls
   thinking: medium # Extended reasoning
 
@@ -105,16 +106,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 +188,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/04-tools.md

@@ -8,10 +8,11 @@ description: Defining external tools implemented in your backend.
 Tools extend what agents can do. Octavus supports multiple types:
 
 1. **External Tools** — Defined in the protocol, implemented in your backend (this page)
-2. **Provider Tools** — Built-in tools executed server-side by the provider (e.g., Anthropic's web search)
-3. **Skills** — Code execution and knowledge packages (see [Skills](/docs/protocol/skills))
+2. **Built-in Tools** — Provider-agnostic tools managed by Octavus (web search, image generation)
+3. **Provider Tools** — Provider-specific tools executed by the provider (e.g., Anthropic's code execution)
+4. **Skills** — Code execution and knowledge packages (see [Skills](/docs/protocol/skills))
 
-This page covers external tools. For provider tools, see [Provider Options](/docs/protocol/provider-options). For code execution capabilities, see [Skills](/docs/protocol/skills).
+This page covers external tools. Built-in tools are enabled via agent config — see [Web Search](/docs/protocol/agent-config#web-search) and [Image Generation](/docs/protocol/agent-config#image-generation). For provider-specific tools, see [Provider Options](/docs/protocol/provider-options). For code execution, see [Skills](/docs/protocol/skills).
 
 ## External Tools
 

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,8 +27,10 @@ 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) |
+| `webSearch`      | No       | Enable built-in web search tool (provider-agnostic)       |
 | `agentic`        | No       | Allow multiple tool call cycles                           |
 | `maxSteps`       | No       | Maximum agentic steps (default: 10)                       |
 | `temperature`    | No       | Model temperature (0-2)                                   |
@@ -212,6 +215,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:
@@ -267,6 +286,28 @@ Use `generate-image` block (see [Handlers](/docs/protocol/handlers#generate-imag
 - Building prompt engineering pipelines
 - Images are generated at specific handler steps
 
+## Web Search
+
+Enable the LLM to search the web for current information:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  webSearch: true
+  agentic: true
+```
+
+When `webSearch` is enabled, the `octavus_web_search` tool becomes available. The LLM can decide when to search the web based on the conversation. Search results include source URLs that are emitted as citations in the UI.
+
+This is a **provider-agnostic** built-in tool — it works with any LLM provider (Anthropic, Google, OpenAI, etc.). For Anthropic's own web search implementation, see [Provider Options](/docs/protocol/provider-options).
+
+Use cases:
+
+- Current events and real-time data
+- Fact verification and documentation lookups
+- Any information that may have changed since the model's training
+
 ## Temperature
 
 Control response randomness:
@@ -321,10 +362,12 @@ 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
+      webSearch: true # Thread-specific web search
 ```
 
-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, image model, and web search setting. Skills must be defined in the protocol's `skills:` section. References must exist in the agent's `references/` directory. Workers use this same pattern since they don't have a global `agent:` section.
 
 ## Full Example
 
@@ -372,6 +415,8 @@ agent:
     - search-docs
     - create-support-ticket
   skills: [qr-code] # Octavus skills
+  references: [support-policies] # On-demand context
+  webSearch: true # Built-in web search
   agentic: true
   maxSteps: 10
   thinking: medium

package/content/04-protocol/08-provider-options.md

@@ -65,7 +65,7 @@ anthropic:
 
 ### Web Search
 
-Allows the agent to search the web for current information:
+Allows the agent to search the web using Anthropic's built-in web search:
 
 ```yaml
 agent:
@@ -77,12 +77,7 @@ agent:
         description: Looking up current information
 ```
 
-Use cases:
-
-- Current events and news
-- Real-time data (prices, weather)
-- Fact verification
-- Documentation lookups
+> **Tip**: Octavus also provides a **provider-agnostic** web search via `webSearch: true` in the agent config. This works with any LLM provider and is the recommended approach for multi-provider agents. See [Web Search](/docs/protocol/agent-config#web-search) for details.
 
 ### Code Execution
 

package/content/04-protocol/11-workers.md

@@ -228,6 +228,7 @@ All LLM configuration goes here:
 | `tools`       | Tools available in this thread                    |
 | `skills`      | Octavus skills available in this thread           |
 | `imageModel`  | Image generation model                            |
+| `webSearch`   | Enable built-in web search tool                   |
 | `thinking`    | Extended reasoning level                          |
 | `temperature` | Model temperature                                 |
 | `maxSteps`    | Maximum tool call cycles (enables agentic if > 1) |
@@ -362,9 +363,9 @@ steps:
 output: CONVERSATION_SUMMARY
 ```
 
-## Skills and Image Generation
+## Skills, Image Generation, and Web Search
 
-Workers can use Octavus skills and image generation, configured per-thread via `start-thread`:
+Workers can use Octavus skills, image generation, and web search, configured per-thread via `start-thread`:
 
 ```yaml
 skills:
@@ -380,6 +381,7 @@ steps:
     system: system
     skills: [qr-code]
     imageModel: google/gemini-2.5-flash-image
+    webSearch: true
     maxSteps: 10
 ```
 

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/02-sessions.md

@@ -258,11 +258,12 @@ POST /api/agent-sessions/:sessionId/trigger
 }
 ```
 
-| Field         | Type   | Required | Description                                    |
-| ------------- | ------ | -------- | ---------------------------------------------- |
-| `triggerName` | string | Yes      | Name of the trigger to execute                 |
-| `input`       | object | No       | Input variables for the trigger                |
-| `toolResults` | array  | No       | Tool results for continuation (handled by SDK) |
+| Field                    | Type           | Required | Description                                                                                        |
+| ------------------------ | -------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `triggerName`            | string         | Yes      | Name of the trigger to execute                                                                     |
+| `input`                  | object         | No       | Input variables for the trigger                                                                    |
+| `toolResults`            | array          | No       | Tool results for continuation (handled by SDK)                                                     |
+| `rollbackAfterMessageId` | string \| null | No       | For retry: ID of the last message to keep. Messages after this are removed. `null` = truncate all. |
 
 ### Response