@octavus/docs 2.10.0 → 2.11.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/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/04-protocol/01-overview.md

@@ -105,12 +105,16 @@ Each agent is a folder with:
 my-agent/
 ├── protocol.yaml           # Main logic (required)
 ├── settings.json           # Agent metadata (required)
-└── prompts/               # Prompt templates
+└── prompts/               # Prompt templates (supports subdirectories)
     ├── system.md
     ├── user-message.md
-    └── escalation-summary.md
+    └── shared/
+        ├── company-info.md
+        └── formatting-rules.md
 ```
 
+Prompts can be organized in subdirectories. In the protocol, reference nested prompts by their path relative to `prompts/` (without `.md`): `shared/company-info`.
+
 ### settings.json
 
 ```json
@@ -133,7 +137,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 +157,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
 

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

@@ -61,24 +61,48 @@ skills:
 
 ## Enabling Skills
 
-After defining skills in the `skills:` section, specify which skills are available for the chat thread in `agent.skills`:
+After defining skills in the `skills:` section, specify which skills are available. Skills work in both interactive agents and workers.
+
+### Interactive Agents
+
+Reference skills in `agent.skills`:
 
 ```yaml
-# All skills available to this agent (defined once at protocol level)
 skills:
   qr-code:
     display: description
     description: Generating QR codes
 
-# Skills available for this chat thread
 agent:
   model: anthropic/claude-sonnet-4-5
   system: system
   tools: [get-user-account]
-  skills: [qr-code] # Skills available for this thread
+  skills: [qr-code]
   agentic: true
 ```
 
+### Workers and Named Threads
+
+Reference skills per-thread in `start-thread.skills`:
+
+```yaml
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+
+steps:
+  Start thread:
+    block: start-thread
+    thread: worker
+    model: anthropic/claude-sonnet-4-5
+    system: system
+    skills: [qr-code]
+    maxSteps: 10
+```
+
+This also works for named threads in interactive agents, allowing different threads to have different skills.
+
 ## Skill Tools
 
 When skills are enabled, the LLM has access to these tools:
@@ -290,23 +314,35 @@ agent:
 
 ## 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:
+The default sandbox timeout is 5 minutes. You can configure a custom timeout using `sandboxTimeout` in the agent config or on individual `start-thread` blocks:
 
 ```yaml
+# Agent-level timeout (applies to main thread)
 agent:
   model: anthropic/claude-sonnet-4-5
   skills: [data-analysis]
   sandboxTimeout: 1800000 # 30 minutes (in milliseconds)
 ```
 
-`sandboxTimeout` Maximum: 1 hour (3,600,000 ms)
+```yaml
+# Thread-level timeout (overrides agent-level for this thread)
+steps:
+  Start thread:
+    block: start-thread
+    thread: analysis
+    model: anthropic/claude-sonnet-4-5
+    skills: [data-analysis]
+    sandboxTimeout: 3600000 # 1 hour
+```
+
+Thread-level `sandboxTimeout` takes priority over agent-level. Maximum: 1 hour (3,600,000 ms).
 
 ## Security
 
 Skills run in isolated sandbox environments:
 
 - **No network access** (unless explicitly configured)
-- **No persistent storage** (sandbox destroyed after execution)
+- **No persistent storage** (sandbox destroyed after each `next-message` execution)
 - **File output only** via `/output/` directory
 - **Time limits** enforced (5-minute default, configurable via `sandboxTimeout`)
 

package/content/04-protocol/06-handlers.md

@@ -148,6 +148,9 @@ Start summary thread:
   maxSteps: 1 # Tool call limit
   system: escalation-summary # System prompt
   input: [COMPANY_NAME] # Variables for prompt
+  skills: [qr-code] # Octavus skills for this thread
+  sandboxTimeout: 600000 # Skill sandbox timeout (default: 5 min, max: 1 hour)
+  imageModel: google/gemini-2.5-flash-image # Image generation model
 ```
 
 The `model` field can also reference a variable for dynamic model selection: