@octavus/docs 2.10.0 → 2.12.0

package/content/02-server-sdk/01-overview.md

@@ -96,6 +96,22 @@ return new Response(toSSEStream(events), {
 });
 ```
 
+### Workers
+
+Execute worker agents for task-based processing:
+
+```typescript
+// Non-streaming: get the output directly
+const { output } = await client.workers.generate(agentId, {
+  TOPIC: 'AI safety',
+});
+
+// Streaming: observe events in real-time
+for await (const event of client.workers.execute(agentId, input)) {
+  // Handle stream events
+}
+```
+
 ## API Reference
 
 ### OctavusClient

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/02-server-sdk/06-workers.md

@@ -17,59 +17,56 @@ const client = new OctavusClient({
   apiKey: 'your-api-key',
 });
 
-// Execute a worker
-const events = client.workers.execute(agentId, {
+const { output, sessionId } = await client.workers.generate(agentId, {
   TOPIC: 'AI safety',
   DEPTH: 'detailed',
 });
 
-// Process events
-for await (const event of events) {
-  if (event.type === 'worker-start') {
-    console.log(`Worker ${event.workerSlug} started`);
-  }
-  if (event.type === 'text-delta') {
-    process.stdout.write(event.delta);
-  }
-  if (event.type === 'worker-result') {
-    console.log('Output:', event.output);
-  }
-}
+console.log('Result:', output);
+console.log(`Debug: ${client.baseUrl}/sessions/${sessionId}`);
 ```
 
 ## WorkersApi Reference
 
-### execute()
+### generate()
 
-Execute a worker and stream the response.
+Execute a worker and return the output directly.
 
 ```typescript
-async *execute(
+async generate(
   agentId: string,
   input: Record<string, unknown>,
   options?: WorkerExecuteOptions
-): AsyncGenerator<StreamEvent>
+): Promise<WorkerGenerateResult>
 ```
 
-**Parameters:**
-
-| Parameter | Type                      | Description                 |
-| --------- | ------------------------- | --------------------------- |
-| `agentId` | `string`                  | The worker agent ID         |
-| `input`   | `Record<string, unknown>` | Input values for the worker |
-| `options` | `WorkerExecuteOptions`    | Optional configuration      |
+Runs the worker to completion and returns the output value. This is the simplest way to execute a worker.
 
-**Options:**
+**Returns:**
 
 ```typescript
-interface WorkerExecuteOptions {
-  /** Tool handlers for server-side tool execution */
-  tools?: ToolHandlers;
-  /** Abort signal to cancel the execution */
-  signal?: AbortSignal;
+interface WorkerGenerateResult {
+  /** The worker's output value */
+  output: unknown;
+  /** Session ID for debugging (usable for session URLs) */
+  sessionId: string;
 }
 ```
 
+**Throws:** `WorkerError` if the worker fails or completes without producing output.
+
+### execute()
+
+Execute a worker and stream the response. Use this when you need to observe intermediate events like text deltas, tool calls, or progress tracking.
+
+```typescript
+async *execute(
+  agentId: string,
+  input: Record<string, unknown>,
+  options?: WorkerExecuteOptions
+): AsyncGenerator<StreamEvent>
+```
+
 ### continue()
 
 Continue execution after client-side tool handling.
@@ -85,19 +82,39 @@ async *continue(
 
 Use this when the worker has tools without server-side handlers. The execution pauses with a `client-tool-request` event, you execute the tools, then call `continue()` to resume.
 
+### Shared Options
+
+All methods accept the same options:
+
+```typescript
+interface WorkerExecuteOptions {
+  /** Tool handlers for server-side tool execution */
+  tools?: ToolHandlers;
+  /** Abort signal to cancel the execution */
+  signal?: AbortSignal;
+}
+```
+
+**Parameters:**
+
+| Parameter | Type                      | Description                 |
+| --------- | ------------------------- | --------------------------- |
+| `agentId` | `string`                  | The worker agent ID         |
+| `input`   | `Record<string, unknown>` | Input values for the worker |
+| `options` | `WorkerExecuteOptions`    | Optional configuration      |
+
 ## Tool Handlers
 
 Provide tool handlers to execute tools server-side:
 
 ```typescript
-const events = client.workers.execute(
+const { output } = await client.workers.generate(
   agentId,
   { TOPIC: 'AI safety' },
   {
     tools: {
       'web-search': async (args) => {
-        const results = await searchWeb(args.query);
-        return results;
+        return await searchWeb(args.query);
       },
       'get-user-data': async (args) => {
         return await db.users.findById(args.userId);
@@ -109,85 +126,141 @@ const events = client.workers.execute(
 
 Tools defined in the worker protocol but not provided as handlers become client tools — the execution pauses and emits a `client-tool-request` event.
 
-## Stream Events
+## Error Handling
 
-Workers emit standard stream events plus worker-specific events.
+### WorkerError (generate)
 
-### Worker Events
+`generate()` throws a `WorkerError` on failure. The error includes an optional `sessionId` for constructing debug URLs:
 
 ```typescript
-// Worker started
-{
-  type: 'worker-start',
-  workerId: string,     // Unique ID (also used as session ID for debug)
-  workerSlug: string,   // The worker's slug
-  description?: string, // Display description for UI
+import { OctavusClient, WorkerError } from '@octavus/server-sdk';
+
+try {
+  const { output } = await client.workers.generate(agentId, input);
+  console.log('Result:', output);
+} catch (error) {
+  if (error instanceof WorkerError) {
+    console.error('Worker failed:', error.message);
+    if (error.sessionId) {
+      console.error(`Debug: ${client.baseUrl}/sessions/${error.sessionId}`);
+    }
+  }
 }
+```
 
-// Worker completed
-{
-  type: 'worker-result',
-  workerId: string,
-  output?: unknown,  // The worker's output value
-  error?: string,    // Error message if worker failed
+### Stream Errors (execute)
+
+When using `execute()`, errors appear as stream events:
+
+```typescript
+for await (const event of client.workers.execute(agentId, input)) {
+  if (event.type === 'error') {
+    console.error(`Error: ${event.message}`);
+    console.error(`Type: ${event.errorType}`);
+    console.error(`Retryable: ${event.retryable}`);
+  }
+
+  if (event.type === 'worker-result' && event.error) {
+    console.error(`Worker failed: ${event.error}`);
+  }
 }
 ```
 
-### Common Events
+### Error Types
 
-| Event                   | Description                 |
-| ----------------------- | --------------------------- |
-| `start`                 | Execution started           |
-| `finish`                | Execution completed         |
-| `text-start`            | Text generation started     |
-| `text-delta`            | Text chunk received         |
-| `text-end`              | Text generation ended       |
-| `block-start`           | Step started                |
-| `block-end`             | Step completed              |
-| `tool-input-available`  | Tool arguments ready        |
-| `tool-output-available` | Tool result ready           |
-| `client-tool-request`   | Client tools need execution |
-| `error`                 | Error occurred              |
+| Type               | Description           |
+| ------------------ | --------------------- |
+| `validation_error` | Invalid input         |
+| `not_found_error`  | Worker not found      |
+| `provider_error`   | LLM provider error    |
+| `tool_error`       | Tool execution failed |
+| `execution_error`  | Worker step failed    |
 
-## Extracting Output
+## Cancellation
 
-To get just the worker's output value:
+Use an abort signal to cancel execution:
 
 ```typescript
-async function executeWorker(
-  client: OctavusClient,
-  agentId: string,
-  input: Record<string, unknown>,
-): Promise<unknown> {
-  const events = client.workers.execute(agentId, input);
+const { output } = await client.workers.generate(agentId, input, {
+  signal: AbortSignal.timeout(30_000),
+});
+```
 
-  for await (const event of events) {
-    if (event.type === 'worker-result') {
-      if (event.error) {
-        throw new Error(event.error);
-      }
-      return event.output;
-    }
+With `execute()` and a manual controller:
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 30000);
+
+try {
+  for await (const event of client.workers.execute(agentId, input, {
+    signal: controller.signal,
+  })) {
+    // Process events
+  }
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Worker cancelled');
   }
+}
+```
+
+## Streaming
 
-  return undefined;
+When you need real-time visibility into the worker's execution — text generation, tool calls, or progress — use `execute()` instead of `generate()`.
+
+### Basic Streaming
+
+```typescript
+const events = client.workers.execute(agentId, {
+  TOPIC: 'AI safety',
+  DEPTH: 'detailed',
+});
+
+for await (const event of events) {
+  if (event.type === 'worker-start') {
+    console.log(`Worker ${event.workerSlug} started`);
+  }
+  if (event.type === 'text-delta') {
+    process.stdout.write(event.delta);
+  }
+  if (event.type === 'worker-result') {
+    console.log('Output:', event.output);
+  }
 }
+```
+
+### Streaming to HTTP Response
+
+Convert worker events to an SSE stream:
+
+```typescript
+import { toSSEStream } from '@octavus/server-sdk';
+
+export async function POST(request: Request) {
+  const { agentId, input } = await request.json();
+
+  const events = client.workers.execute(agentId, input, {
+    tools: {
+      search: async (args) => await search(args.query),
+    },
+  });
 
-// Usage
-const analysis = await executeWorker(client, agentId, { TOPIC: 'AI' });
+  return new Response(toSSEStream(events), {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
 ```
 
-## Client Tool Continuation
+### Client Tool Continuation
 
 When workers have tools without handlers, execution pauses:
 
 ```typescript
 for await (const event of client.workers.execute(agentId, input)) {
   if (event.type === 'client-tool-request') {
-    // Execute tools client-side
     const results = await executeClientTools(event.toolCalls);
 
-    // Continue execution
     for await (const ev of client.workers.continue(agentId, event.executionId, results)) {
       // Handle remaining events
     }
@@ -210,84 +283,87 @@ The `client-tool-request` event includes:
 }
 ```
 
-## Streaming to HTTP Response
+### Stream Events
 
-Convert worker events to an SSE stream:
-
-```typescript
-import { toSSEStream } from '@octavus/server-sdk';
+Workers emit standard stream events plus worker-specific events.
 
-export async function POST(request: Request) {
-  const { agentId, input } = await request.json();
+#### Worker Events
 
-  const events = client.workers.execute(agentId, input, {
-    tools: {
-      search: async (args) => await search(args.query),
-    },
-  });
+```typescript
+// Worker started
+{
+  type: 'worker-start',
+  workerId: string,     // Unique ID (also used as session ID for debug)
+  workerSlug: string,   // The worker's slug
+  description?: string, // Display description for UI
+}
 
-  return new Response(toSSEStream(events), {
-    headers: { 'Content-Type': 'text/event-stream' },
-  });
+// Worker completed
+{
+  type: 'worker-result',
+  workerId: string,
+  output?: unknown,  // The worker's output value
+  error?: string,    // Error message if worker failed
 }
 ```
 
-## Cancellation
+#### Common Events
 
-Use an abort signal to cancel execution:
+| Event                   | Description                 |
+| ----------------------- | --------------------------- |
+| `start`                 | Execution started           |
+| `finish`                | Execution completed         |
+| `text-start`            | Text generation started     |
+| `text-delta`            | Text chunk received         |
+| `text-end`              | Text generation ended       |
+| `block-start`           | Step started                |
+| `block-end`             | Step completed              |
+| `tool-input-available`  | Tool arguments ready        |
+| `tool-output-available` | Tool result ready           |
+| `client-tool-request`   | Client tools need execution |
+| `error`                 | Error occurred              |
 
-```typescript
-const controller = new AbortController();
+## Full Examples
 
-// Cancel after 30 seconds
-setTimeout(() => controller.abort(), 30000);
+### generate()
+
+```typescript
+import { OctavusClient, WorkerError } from '@octavus/server-sdk';
 
-const events = client.workers.execute(agentId, input, {
-  signal: controller.signal,
+const client = new OctavusClient({
+  baseUrl: 'https://octavus.ai',
+  apiKey: process.env.OCTAVUS_API_KEY!,
 });
 
 try {
-  for await (const event of events) {
-    // Process events
-  }
-} catch (error) {
-  if (error.name === 'AbortError') {
-    console.log('Worker cancelled');
-  }
-}
-```
-
-## Error Handling
-
-Errors can occur at different levels:
-
-```typescript
-for await (const event of client.workers.execute(agentId, input)) {
-  // Stream-level error event
-  if (event.type === 'error') {
-    console.error(`Error: ${event.message}`);
-    console.error(`Type: ${event.errorType}`);
-    console.error(`Retryable: ${event.retryable}`);
-  }
+  const { output, sessionId } = await client.workers.generate(
+    'research-assistant-id',
+    {
+      TOPIC: 'AI safety best practices',
+      DEPTH: 'detailed',
+    },
+    {
+      tools: {
+        'web-search': async ({ query }) => await performWebSearch(query),
+      },
+      signal: AbortSignal.timeout(120_000),
+    },
+  );
 
-  // Worker-level error in result
-  if (event.type === 'worker-result' && event.error) {
-    console.error(`Worker failed: ${event.error}`);
+  console.log('Result:', output);
+} catch (error) {
+  if (error instanceof WorkerError) {
+    console.error('Failed:', error.message);
+    if (error.sessionId) {
+      console.error(`Debug: ${client.baseUrl}/sessions/${error.sessionId}`);
+    }
   }
 }
 ```
 
-Error types include:
-
-| Type               | Description           |
-| ------------------ | --------------------- |
-| `validation_error` | Invalid input         |
-| `not_found_error`  | Worker not found      |
-| `provider_error`   | LLM provider error    |
-| `tool_error`       | Tool execution failed |
-| `execution_error`  | Worker step failed    |
+### execute()
 
-## Full Example
+For full control over streaming events and progress tracking:
 
 ```typescript
 import { OctavusClient, type StreamEvent } from '@octavus/server-sdk';
@@ -348,7 +424,6 @@ async function runResearchWorker(topic: string) {
   return output;
 }
 
-// Run the worker
 const result = await runResearchWorker('AI safety best practices');
 console.log('Result:', result);
 ```

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,12 +105,20 @@ Each agent is a folder with:
 my-agent/
 ├── protocol.yaml           # Main logic (required)
 ├── settings.json           # Agent metadata (required)
-└── prompts/               # Prompt templates
-    ├── system.md
-    ├── user-message.md
-    └── escalation-summary.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
@@ -133,7 +141,7 @@ my-agent/
 
 - **Slugs**: `lowercase-with-dashes`
 - **Variables**: `UPPERCASE_SNAKE_CASE`
-- **Prompts**: `lowercase-with-dashes.md`
+- **Prompts**: `lowercase-with-dashes.md` (paths use `/` for subdirectories)
 - **Tools**: `lowercase-with-dashes`
 - **Triggers**: `lowercase-with-dashes`
 
@@ -153,7 +161,25 @@ Help users with their {{PRODUCT_NAME}} questions.
 {{SUPPORT_POLICIES}}
 ```
 
-Variables are replaced with their values at runtime. If a variable is not provided, it's replaced with an empty string.
+Variables are replaced with their values at runtime. If a variable is not provided, the placeholder is kept as-is.
+
+## Prompt Interpolation
+
+Include other prompts inside a prompt with `{{@path.md}}`:
+
+```markdown
+<!-- prompts/system.md -->
+
+You are a customer support agent.
+
+{{@shared/company-info.md}}
+
+{{@shared/formatting-rules.md}}
+
+Help users with their questions.
+```
+
+The referenced prompt content is inserted before variable interpolation, so variables in included prompts work the same way. Circular references are not allowed and will be caught during validation.
 
 ## Next Steps
 
@@ -161,6 +187,7 @@ Variables are replaced with their values at runtime. If a variable is not provid
 - [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