@octavus/docs 2.2.0 → 2.4.0

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

@@ -111,6 +111,7 @@ interface OctavusClientConfig {
 class OctavusClient {
   readonly agents: AgentsApi;
   readonly agentSessions: AgentSessionsApi;
+  readonly workers: WorkersApi;
   readonly files: FilesApi;
 
   constructor(config: OctavusClientConfig);
@@ -219,3 +220,4 @@ The client uploads files directly to S3 using the presigned upload URL. See [Fil
 - [Sessions](/docs/server-sdk/sessions) — Deep dive into session management
 - [Tools](/docs/server-sdk/tools) — Implementing tool handlers
 - [Streaming](/docs/server-sdk/streaming) — Understanding stream events
+- [Workers](/docs/server-sdk/workers) — Executing worker agents

package/content/02-server-sdk/06-workers.md

@@ -0,0 +1,360 @@
+---
+title: Workers
+description: Executing worker agents with the Server SDK.
+---
+
+# Workers API
+
+The `WorkersApi` enables executing worker agents from your server. Workers are task-based agents that run steps sequentially and return an output value.
+
+## Basic Usage
+
+```typescript
+import { OctavusClient } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: 'https://octavus.ai',
+  apiKey: 'your-api-key',
+});
+
+// Execute a worker
+const events = client.workers.execute(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);
+  }
+}
+```
+
+## WorkersApi Reference
+
+### execute()
+
+Execute a worker and stream the response.
+
+```typescript
+async *execute(
+  agentId: string,
+  input: Record<string, unknown>,
+  options?: WorkerExecuteOptions
+): AsyncGenerator<StreamEvent>
+```
+
+**Parameters:**
+
+| Parameter | Type                      | Description                 |
+| --------- | ------------------------- | --------------------------- |
+| `agentId` | `string`                  | The worker agent ID         |
+| `input`   | `Record<string, unknown>` | Input values for the worker |
+| `options` | `WorkerExecuteOptions`    | Optional configuration      |
+
+**Options:**
+
+```typescript
+interface WorkerExecuteOptions {
+  /** Tool handlers for server-side tool execution */
+  tools?: ToolHandlers;
+  /** Abort signal to cancel the execution */
+  signal?: AbortSignal;
+}
+```
+
+### continue()
+
+Continue execution after client-side tool handling.
+
+```typescript
+async *continue(
+  agentId: string,
+  executionId: string,
+  toolResults: ToolResult[],
+  options?: WorkerExecuteOptions
+): AsyncGenerator<StreamEvent>
+```
+
+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.
+
+## Tool Handlers
+
+Provide tool handlers to execute tools server-side:
+
+```typescript
+const events = client.workers.execute(
+  agentId,
+  { TOPIC: 'AI safety' },
+  {
+    tools: {
+      'web-search': async (args) => {
+        const results = await searchWeb(args.query);
+        return results;
+      },
+      'get-user-data': async (args) => {
+        return await db.users.findById(args.userId);
+      },
+    },
+  },
+);
+```
+
+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
+
+Workers emit standard stream events plus worker-specific events.
+
+### Worker Events
+
+```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
+}
+
+// Worker completed
+{
+  type: 'worker-result',
+  workerId: string,
+  output?: unknown,  // The worker's output value
+  error?: string,    // Error message if worker failed
+}
+```
+
+### Common Events
+
+| 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              |
+
+## Extracting Output
+
+To get just the worker's output value:
+
+```typescript
+async function executeWorker(
+  client: OctavusClient,
+  agentId: string,
+  input: Record<string, unknown>,
+): Promise<unknown> {
+  const events = client.workers.execute(agentId, input);
+
+  for await (const event of events) {
+    if (event.type === 'worker-result') {
+      if (event.error) {
+        throw new Error(event.error);
+      }
+      return event.output;
+    }
+  }
+
+  return undefined;
+}
+
+// Usage
+const analysis = await executeWorker(client, agentId, { TOPIC: 'AI' });
+```
+
+## 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
+    }
+    break;
+  }
+}
+```
+
+The `client-tool-request` event includes:
+
+```typescript
+{
+  type: 'client-tool-request',
+  executionId: string,      // Pass to continue()
+  toolCalls: [{
+    toolCallId: string,
+    toolName: string,
+    args: Record<string, unknown>,
+  }],
+}
+```
+
+## 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),
+    },
+  });
+
+  return new Response(toSSEStream(events), {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
+```
+
+## Cancellation
+
+Use an abort signal to cancel execution:
+
+```typescript
+const controller = new AbortController();
+
+// Cancel after 30 seconds
+setTimeout(() => controller.abort(), 30000);
+
+const events = client.workers.execute(agentId, input, {
+  signal: controller.signal,
+});
+
+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}`);
+  }
+
+  // Worker-level error in result
+  if (event.type === 'worker-result' && event.error) {
+    console.error(`Worker failed: ${event.error}`);
+  }
+}
+```
+
+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    |
+
+## Full Example
+
+```typescript
+import { OctavusClient, type StreamEvent } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: 'https://octavus.ai',
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+async function runResearchWorker(topic: string) {
+  console.log(`Researching: ${topic}\n`);
+
+  const events = client.workers.execute(
+    'research-assistant-id',
+    {
+      TOPIC: topic,
+      DEPTH: 'detailed',
+    },
+    {
+      tools: {
+        'web-search': async ({ query }) => {
+          console.log(`Searching: ${query}`);
+          return await performWebSearch(query);
+        },
+      },
+    },
+  );
+
+  let output: unknown;
+
+  for await (const event of events) {
+    switch (event.type) {
+      case 'worker-start':
+        console.log(`Started: ${event.workerSlug}`);
+        break;
+
+      case 'block-start':
+        console.log(`Step: ${event.blockName}`);
+        break;
+
+      case 'text-delta':
+        process.stdout.write(event.delta);
+        break;
+
+      case 'worker-result':
+        if (event.error) {
+          throw new Error(event.error);
+        }
+        output = event.output;
+        break;
+
+      case 'error':
+        throw new Error(event.message);
+    }
+  }
+
+  console.log('\n\nResearch complete!');
+  return output;
+}
+
+// Run the worker
+const result = await runResearchWorker('AI safety best practices');
+console.log('Result:', result);
+```
+
+## Next Steps
+
+- [Workers Protocol](/docs/protocol/workers) — Worker protocol reference
+- [Streaming](/docs/server-sdk/streaming) — Understanding stream events
+- [Tools](/docs/server-sdk/tools) — Tool handler patterns

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

@@ -17,7 +17,22 @@ Protocols provide:
 - **Validation** — Catch errors before runtime
 - **Visualization** — Debug execution flows
 
-## Protocol Structure
+## Agent Formats
+
+Octavus supports two agent formats:
+
+| Format        | Use Case                       | Structure                         |
+| ------------- | ------------------------------ | --------------------------------- |
+| `interactive` | Chat and multi-turn dialogue   | `triggers` + `handlers` + `agent` |
+| `worker`      | Background tasks and pipelines | `steps` + `output`                |
+
+**Interactive agents** handle conversations — they respond to triggers (like user messages) and maintain session state across interactions.
+
+**Worker agents** execute tasks — they run steps sequentially and return an output value. Workers can be called independently or composed into interactive agents.
+
+See [Workers](/docs/protocol/workers) for the worker protocol reference.
+
+## Interactive Protocol Structure
 
 ```yaml
 # Agent inputs (provided when creating a session)
@@ -148,5 +163,6 @@ Variables are replaced with their values at runtime. If a variable is not provid
 - [Skills](/docs/protocol/skills) — Code execution and knowledge packages
 - [Handlers](/docs/protocol/handlers) — Execution blocks
 - [Agent Config](/docs/protocol/agent-config) — Model and settings
+- [Workers](/docs/protocol/workers) — Worker agent format
 - [Provider Options](/docs/protocol/provider-options) — Provider-specific features
 - [Types](/docs/protocol/types) — Custom type definitions

package/content/04-protocol/05-skills.md

@@ -288,6 +288,19 @@ agent:
   skills: [custom-analysis]
 ```
 
+## Sandbox Timeout
+
+The default sandbox timeout is 5 minutes. For long-running operations, you can configure a custom timeout using `sandboxTimeout` in the agent config:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  skills: [data-analysis]
+  sandboxTimeout: 1800000 # 30 minutes (in milliseconds)
+```
+
+`sandboxTimeout` Maximum: 1 hour (3,600,000 ms)
+
 ## Security
 
 Skills run in isolated sandbox environments:
@@ -295,7 +308,7 @@ Skills run in isolated sandbox environments:
 - **No network access** (unless explicitly configured)
 - **No persistent storage** (sandbox destroyed after execution)
 - **File output only** via `/output/` directory
-- **Time limits** enforced (5-minute default timeout)
+- **Time limits** enforced (5-minute default, configurable via `sandboxTimeout`)
 
 ## Next Steps
 

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

@@ -39,11 +39,11 @@ Specify models in `provider/model-id` format. Any model supported by the provide
 
 ### Supported Providers
 
-| Provider  | Format                 | Examples                                                     |
-| --------- | ---------------------- | ------------------------------------------------------------ |
-| Anthropic | `anthropic/{model-id}` | `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`   |
-| Google    | `google/{model-id}`    | `gemini-3-pro-preview`, `gemini-3-flash`, `gemini-2.5-flash` |
-| OpenAI    | `openai/{model-id}`    | `gpt-5`, `gpt-4o`, `o4-mini`, `o3`, `o3-mini`, `o1`          |
+| Provider  | Format                 | Examples                                                             |
+| --------- | ---------------------- | -------------------------------------------------------------------- |
+| Anthropic | `anthropic/{model-id}` | `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`           |
+| Google    | `google/{model-id}`    | `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash` |
+| OpenAI    | `openai/{model-id}`    | `gpt-5`, `gpt-4o`, `o4-mini`, `o3`, `o3-mini`, `o1`                  |
 
 ### Examples
 
@@ -54,7 +54,7 @@ agent:
 
 # Google Gemini 3
 agent:
-  model: google/gemini-3-flash
+  model: google/gemini-3-flash-preview
 
 # OpenAI GPT-5
 agent:

package/content/04-protocol/09-skills-advanced.md

@@ -220,11 +220,22 @@ This means:
 
 ### Timeout Limits
 
-Sandboxes have a 5-minute default timeout:
+Sandboxes have a 5-minute default timeout, which can be configured via `sandboxTimeout`:
 
-- **Short operations**: QR codes, simple calculations
-- **Medium operations**: Data analysis, report generation
-- **Long operations**: May need to split into multiple steps
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  skills: [data-analysis]
+  sandboxTimeout: 1800000 # 30 minutes for long-running analysis
+```
+
+`sandboxTimeout` Maximum: 1 hour (3,600,000 ms)
+
+**Timeout guidelines:**
+
+- **Short operations** (default 5 min): QR codes, simple calculations
+- **Medium operations** (10-30 min): Data analysis, report generation
+- **Long operations** (30+ min): Complex processing, large dataset analysis
 
 ### Sandbox Lifecycle
 
@@ -339,7 +350,7 @@ The LLM sees these errors and can retry or explain to users.
 - **No network access** (unless explicitly configured)
 - **No persistent storage** (sandbox destroyed after execution)
 - **File output only** via `/output/` directory
-- **Time limits** enforced (5-minute default)
+- **Time limits** enforced (5-minute default, configurable via `sandboxTimeout`)
 
 ### Input Validation