@octavus/docs 2.9.0 → 2.11.0

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

@@ -19,19 +19,20 @@ agent:
 
 ## Configuration Options
 
-| Field         | Required | Description                                               |
-| ------------- | -------- | --------------------------------------------------------- |
-| `model`       | Yes      | Model identifier or variable reference                    |
-| `system`      | Yes      | System prompt filename (without .md)                      |
-| `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                    |
-| `imageModel`  | No       | Image generation model (enables agentic image generation) |
-| `agentic`     | No       | Allow multiple tool call cycles                           |
-| `maxSteps`    | No       | Maximum agentic steps (default: 10)                       |
-| `temperature` | No       | Model temperature (0-2)                                   |
-| `thinking`    | No       | Extended reasoning level                                  |
-| `anthropic`   | No       | Anthropic-specific options (tools, skills)                |
+| Field            | Required | Description                                               |
+| ---------------- | -------- | --------------------------------------------------------- |
+| `model`          | Yes      | Model identifier or variable reference                    |
+| `system`         | Yes      | System prompt filename (without .md)                      |
+| `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                    |
+| `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                           |
+| `maxSteps`       | No       | Maximum agentic steps (default: 10)                       |
+| `temperature`    | No       | Model temperature (0-2)                                   |
+| `thinking`       | No       | Extended reasoning level                                  |
+| `anthropic`      | No       | Anthropic-specific options (tools, skills)                |
 
 ## Models
 
@@ -319,8 +320,12 @@ handlers:
       thinking: low # Different thinking
       maxSteps: 1 # Limit tool calls
       system: escalation-summary # Different prompt
+      skills: [data-analysis] # Thread-specific skills
+      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.
+
 ## Full Example
 
 ```yaml

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

@@ -26,10 +26,11 @@ Use external tools instead when:
 
 ### Defining Available Skills
 
-Define all skills available to this agent in the `skills:` section. Then specify which skills are available for the chat thread in `agent.skills`:
+Define all skills in the `skills:` section, then reference which skills are available where they're used:
+
+**Interactive agents** — reference in `agent.skills`:
 
 ```yaml
-# All skills available to this agent (defined once at protocol level)
 skills:
   qr-code:
     display: description
@@ -37,23 +38,39 @@ skills:
   pdf-processor:
     display: description
     description: Processing PDFs
-  data-analysis:
-    display: description
-    description: Analyzing data
 
-# Skills available for this chat thread
 agent:
   model: anthropic/claude-sonnet-4-5
   system: system
-  skills: [qr-code] # Skills available for this thread
+  skills: [qr-code]
+```
+
+**Workers and named threads** — reference per-thread in `start-thread.skills`:
+
+```yaml
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+  data-analysis:
+    display: description
+    description: Analyzing data
+
+steps:
+  Start analysis:
+    block: start-thread
+    thread: analysis
+    model: anthropic/claude-sonnet-4-5
+    system: system
+    skills: [qr-code, data-analysis]
+    maxSteps: 10
 ```
 
 ### Match Skills to Use Cases
 
-Define all skills available to this agent in the `skills:` section. Then specify which skills are available for the chat thread based on use case:
+Different threads can have different skills. Define all skills at the protocol level, then scope them to each thread:
 
 ```yaml
-# All skills available to this agent (defined once at protocol level)
 skills:
   qr-code:
     display: description
@@ -65,14 +82,13 @@ skills:
     display: description
     description: Creating charts and visualizations
 
-# Skills available for this chat thread (support use case)
 agent:
   model: anthropic/claude-sonnet-4-5
   system: system
-  skills: [qr-code] # Skills available for this thread
+  skills: [qr-code]
 ```
 
-For a data analysis thread, you would specify `[data-analysis, visualization]` in `agent.skills`, but still define all available skills in the `skills:` section above.
+For a data analysis thread, you would specify `[data-analysis, visualization]` in `agent.skills` or in a `start-thread` block's `skills` field.
 
 ## Display Mode Strategy
 
@@ -207,43 +223,48 @@ with open(f'{output_dir}/metadata.json', 'w') as f:
 Sandboxes are created only when a skill tool is first called:
 
 ```yaml
-# Sandbox not created until LLM calls a skill tool
 agent:
-  skills: [qr-code] # Sandbox created on first use
+  skills: [qr-code] # Sandbox created on first skill tool call
 ```
 
 This means:
 
 - No cost if skills aren't used
 - Fast startup (no sandbox creation delay)
-- Sandbox reused for all skill calls in a trigger
+- Each `next-message` execution gets its own sandbox with only the skills it needs
 
 ### Timeout Limits
 
-Sandboxes have a 5-minute default timeout, which can be configured via `sandboxTimeout`:
+Sandboxes default to a 5-minute timeout. Configure `sandboxTimeout` on the agent config or per thread:
 
 ```yaml
+# Agent-level
 agent:
   model: anthropic/claude-sonnet-4-5
   skills: [data-analysis]
-  sandboxTimeout: 1800000 # 30 minutes for long-running analysis
+  sandboxTimeout: 1800000 # 30 minutes
 ```
 
-`sandboxTimeout` Maximum: 1 hour (3,600,000 ms)
-
-**Timeout guidelines:**
+```yaml
+# Thread-level (overrides agent-level)
+steps:
+  Start thread:
+    block: start-thread
+    thread: analysis
+    skills: [data-analysis]
+    sandboxTimeout: 3600000 # 1 hour for long-running analysis
+```
 
-- **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
+Thread-level `sandboxTimeout` takes priority. Maximum: 1 hour (3,600,000 ms).
 
 ### Sandbox Lifecycle
 
-Each trigger execution gets a fresh sandbox:
+Each `next-message` execution gets its own sandbox:
 
-- **Clean state** - No leftover files from previous executions
-- **Isolated** - No interference between sessions
-- **Destroyed** - Sandbox cleaned up after trigger completes
+- **Scoped** - Only contains the skills available to that thread
+- **Isolated** - Interactive agents and workers don't share sandboxes
+- **Resilient** - If a sandbox expires, it's transparently recreated
+- **Cleaned up** - Sandbox destroyed when the LLM call completes
 
 ## Combining Skills with Tools
 
@@ -348,7 +369,7 @@ The LLM sees these errors and can retry or explain to users.
 ### Sandbox Isolation
 
 - **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`)
 
@@ -373,7 +394,7 @@ if len(data) > 1000:
 Be aware of:
 
 - **File size limits** - Large files may fail to upload
-- **Execution time** - 5-minute sandbox timeout
+- **Execution time** - Sandbox timeout (5-minute default, 1-hour maximum)
 - **Memory limits** - Sandbox environment constraints
 
 ## Debugging Skills

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

@@ -148,7 +148,7 @@ steps:
     tools: [tool-b]
 ```
 
-This gives workers flexibility to use different models, tools, and settings at different stages.
+This gives workers flexibility to use different models, tools, skills, and settings at different stages.
 
 ### Steps Instead of Handlers
 
@@ -226,7 +226,7 @@ All LLM configuration goes here:
 | `system`      | System prompt filename (required)                 |
 | `input`       | Variables for system prompt                       |
 | `tools`       | Tools available in this thread                    |
-| `workers`     | Workers available to this thread (as LLM tools)   |
+| `skills`      | Octavus skills available in this thread           |
 | `imageModel`  | Image generation model                            |
 | `thinking`    | Extended reasoning level                          |
 | `temperature` | Model temperature                                 |
@@ -362,6 +362,31 @@ steps:
 output: CONVERSATION_SUMMARY
 ```
 
+## Skills and Image Generation
+
+Workers can use Octavus skills and image generation, configured per-thread via `start-thread`:
+
+```yaml
+skills:
+  qr-code:
+    display: description
+    description: Generate QR codes
+
+steps:
+  Start thread:
+    block: start-thread
+    thread: worker
+    model: anthropic/claude-sonnet-4-5
+    system: system
+    skills: [qr-code]
+    imageModel: google/gemini-2.5-flash-image
+    maxSteps: 10
+```
+
+Workers define their own skills independently -- they don't inherit skills from a parent interactive agent. Each thread gets its own sandbox scoped to only its listed skills.
+
+See [Skills](/docs/protocol/skills) for full documentation.
+
 ## Tool Handling
 
 Workers support the same tool handling as interactive agents:
@@ -370,14 +395,24 @@ Workers support the same tool handling as interactive agents:
 - **Client tools** — Pause execution, return tool request to caller
 
 ```typescript
+// Non-streaming: get the output directly
+const { output } = await client.workers.generate(
+  agentId,
+  { TOPIC: 'AI safety' },
+  {
+    tools: {
+      'web-search': async (args) => await searchWeb(args.query),
+    },
+  },
+);
+
+// Streaming: observe events in real-time
 const events = client.workers.execute(
   agentId,
   { TOPIC: 'AI safety' },
   {
     tools: {
-      'web-search': async (args) => {
-        return await searchWeb(args.query);
-      },
+      'web-search': async (args) => await searchWeb(args.query),
     },
   },
 );