@octavus/docs 3.0.0 → 3.2.0

package/content/04-protocol/02-input-resources.md

@@ -77,7 +77,7 @@ In prompts, reference variables with `{{VARIABLE_NAME}}`:
 You are a support agent for {{COMPANY_NAME}}.
 ```
 
-To use a variable in a prompt, pass it through the `input` mapping on the [agent config](/docs/protocol/agent-config#system-prompt) or [block](/docs/protocol/handlers#block-input-mapping). Variables not listed in the `input` mapping won't be interpolated — the `{{VARIABLE}}` placeholder will be preserved as-is.
+To use a variable in a prompt, pass it through the `input` mapping on the [agent config](/docs/protocol/agent-config#system-prompt) or [block](/docs/protocol/handlers#block-input-mapping). Variables not listed in the `input` mapping won't be interpolated - the `{{VARIABLE}}` placeholder will be preserved as-is.
 
 > **Note:** Variables must be `UPPER_SNAKE_CASE`. Nested properties (dot notation like `{{VAR.property}}`) are not supported. Objects are serialized as JSON when interpolated.
 

package/content/04-protocol/03-triggers.md

@@ -11,7 +11,7 @@ Triggers define how an agent can be invoked. Each trigger has a name, optional i
 
 ### User Message
 
-The most common trigger — when a user sends a chat message:
+The most common trigger - when a user sends a chat message:
 
 ```yaml
 triggers:

package/content/04-protocol/04-tools.md

@@ -7,13 +7,13 @@ 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. **MCP Tools** — Auto-discovered from MCP servers (see [MCP Servers](/docs/protocol/mcp-servers))
-3. **Built-in Tools** — Provider-agnostic tools managed by Octavus (web search, image generation)
-4. **Provider Tools** — Provider-specific tools executed by the provider (e.g., Anthropic's code execution)
-5. **Skills** — Code execution and knowledge packages (see [Skills](/docs/protocol/skills))
+1. **External Tools** - Defined in the protocol, implemented in your backend (this page)
+2. **MCP Tools** - Auto-discovered from MCP servers (see [MCP Servers](/docs/protocol/mcp-servers))
+3. **Built-in Tools** - Provider-agnostic tools managed by Octavus (web search, image generation)
+4. **Provider Tools** - Provider-specific tools executed by the provider (e.g., Anthropic's code execution)
+5. **Skills** - Code execution and knowledge packages (see [Skills](/docs/protocol/skills))
 
-This page covers external tools. For MCP-based tools from services like Figma, Sentry, or device capabilities like browser and filesystem, see [MCP Servers](/docs/protocol/mcp-servers). 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).
+This page covers external tools. For MCP-based tools from services like Figma, Sentry, or device capabilities like browser and filesystem, see [MCP Servers](/docs/protocol/mcp-servers). 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/05-skills.md

@@ -413,7 +413,7 @@ When a skill has secrets configured for the organization, it automatically runs
 
 - The skill gets its own **isolated sandbox** (separate from other skills)
 - Secrets are injected as **environment variables** available to all scripts
-- Only `octavus_skill_read`, `octavus_skill_list`, and `octavus_skill_run` are available — `octavus_code_run`, `octavus_file_write`, and `octavus_file_read` are blocked
+- Only `octavus_skill_read`, `octavus_skill_list`, and `octavus_skill_run` are available - `octavus_code_run`, `octavus_file_write`, and `octavus_file_read` are blocked
 - Scripts receive input as **JSON via stdin** (using the `input` parameter on `octavus_skill_run`) instead of CLI args
 - All output (stdout/stderr) is **automatically redacted** for secret values before being returned to the LLM
 
@@ -442,10 +442,10 @@ Skills run in isolated sandbox environments:
 - **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`)
-- **Secret redaction** — output from secure skills is automatically scanned for secret values
+- **Secret redaction** - output from secure skills is automatically scanned for secret values
 
 ## Next Steps
 
-- [Agent Config](/docs/protocol/agent-config) — Configuring skills in agent settings
-- [Provider Options](/docs/protocol/provider-options) — Anthropic's built-in skills
-- [Skills Advanced Guide](/docs/protocol/skills-advanced) — Best practices and advanced patterns
+- [Agent Config](/docs/protocol/agent-config) - Configuring skills in agent settings
+- [Provider Options](/docs/protocol/provider-options) - Anthropic's built-in skills
+- [Skills Advanced Guide](/docs/protocol/skills-advanced) - Best practices and advanced patterns

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

@@ -146,6 +146,7 @@ Start summary thread:
   model: anthropic/claude-sonnet-4-5 # Optional: different model
   backupModel: openai/gpt-4o # Failover on provider errors
   thinking: low # Extended reasoning level
+  cache: auto # auto (default) | extended | off
   maxSteps: 1 # Tool call limit
   system: escalation-summary # System prompt
   input: [COMPANY_NAME] # Variables for prompt
@@ -155,6 +156,8 @@ Start summary thread:
   imageModel: google/gemini-2.5-flash-image # Image generation model
 ```
 
+The `cache` field controls prompt caching for this thread and defaults to `auto` when omitted. Threads do not inherit the agent's `cache` value - see [Prompt Caching](/docs/protocol/agent-config#prompt-caching).
+
 The `model` field can also reference a variable for dynamic model selection. The `backupModel` field follows the same format and supports variable references.
 
 ```yaml

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

@@ -38,6 +38,7 @@ agent:
 | `maxSteps`       | No       | Maximum agentic steps (default: 10)                                            |
 | `temperature`    | No       | Model temperature (0-2)                                                        |
 | `thinking`       | No       | Extended reasoning level                                                       |
+| `cache`          | No       | Prompt caching mode: `auto` (default), `extended`, or `off`                    |
 | `anthropic`      | No       | Anthropic-specific options (tools, skills)                                     |
 
 ## Models
@@ -46,11 +47,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-preview`, `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-7`, `claude-opus-4-6`, `claude-sonnet-4-6`, `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
 
@@ -99,9 +100,9 @@ const sessionId = await client.agentSessions.create('my-agent', {
 
 This enables:
 
-- **Multi-provider support** — Same agent works with different providers
-- **A/B testing** — Test different models without protocol changes
-- **User preferences** — Let users choose their preferred model
+- **Multi-provider support** - Same agent works with different providers
+- **A/B testing** - Test different models without protocol changes
+- **User preferences** - Let users choose their preferred model
 
 The model value is validated at runtime to ensure it's in the correct `provider/model-id` format.
 
@@ -122,7 +123,7 @@ When a provider error occurs, the system retries once with the backup model. If
 
 **Key behaviors:**
 
-- Only transient provider errors trigger fallback — authentication and validation errors are not retried
+- Only transient provider errors trigger fallback - authentication and validation errors are not retried
 - Provider-specific options (like `anthropic:`) are only forwarded to the backup model if it uses the same provider
 - For streaming responses, fallback only occurs if no content has been sent to the client yet
 
@@ -144,7 +145,7 @@ agent:
 
 ## System Prompt
 
-The system prompt sets the agent's persona and instructions. The `input` field controls which variables are available to the prompt — only variables listed in `input` are interpolated.
+The system prompt sets the agent's persona and instructions. The `input` field controls which variables are available to the prompt - only variables listed in `input` are interpolated.
 
 ```yaml
 agent:
@@ -224,14 +225,81 @@ agent:
   thinking: medium # low | medium | high
 ```
 
-| Level    | Token Budget | Use Case            |
-| -------- | ------------ | ------------------- |
-| `low`    | ~5,000       | Simple reasoning    |
-| `medium` | ~10,000      | Moderate complexity |
-| `high`   | ~20,000      | Complex analysis    |
+| Level    | Use Case            |
+| -------- | ------------------- |
+| `low`    | Simple reasoning    |
+| `medium` | Moderate complexity |
+| `high`   | Complex analysis    |
 
 Thinking content streams to the UI and can be displayed to users.
 
+### How levels are applied
+
+Each provider translates `thinking` into its own reasoning controls:
+
+| Provider                                                                   | Level mapping                                                                                     |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Anthropic 4.6+ (`claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`) | Adaptive thinking - the model decides how much to reason, guided by `effort: low / medium / high` |
+| Anthropic older (4.5 and earlier)                                          | Fixed token budgets: `low` ~5,000, `medium` ~10,000, `high` ~20,000                               |
+| OpenAI (GPT-5.x, o-series)                                                 | `reasoningEffort: low / medium / high`                                                            |
+| Google (Gemini 3.x)                                                        | `thinkingLevel: low / high` (`medium` rounds up to `high`)                                        |
+| Google (Gemini 1.x / 2.x)                                                  | Token budgets: `low` 1,024, `medium` 8,192, `high` 24,576                                         |
+| OpenRouter                                                                 | Unified `reasoning.max_tokens` (translated upstream)                                              |
+| Vercel AI Gateway                                                          | Forwards the underlying provider's options                                                        |
+
+## Prompt Caching
+
+Providers charge less for tokens served from their prompt cache (often 10% of the uncached rate). Octavus exposes a single `cache` field that picks the right retention policy per provider, so the stable prefix of your agent - tools, system prompt, and historical messages - gets billed at the cache-read rate on repeat requests.
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  cache: auto # auto (default) | extended | off
+```
+
+| Mode       | Behavior                                                                      | When to use                                                                                             |
+| ---------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `auto`     | Short-TTL caching. Default when omitted.                                      | Most agents. Free on all supported providers and pays for itself within the same session.               |
+| `extended` | Long-TTL caching. Trades a higher cache-write cost for much longer residency. | Agents triggered with gaps (daily reports, on-call assistants) where the prefix is reused across hours. |
+| `off`      | No opt-in caching emitted.                                                    | When you explicitly want to skip caching - e.g. debugging a non-deterministic prefix.                   |
+
+### Per-provider behavior
+
+The `cache` field is provider-agnostic at the protocol level - each provider translates it into its own cache retention policy:
+
+| Provider  | `auto` TTL                | `extended` TTL |
+| --------- | ------------------------- | -------------- |
+| Anthropic | 5 minutes                 | 1 hour         |
+| OpenAI    | in-memory (~5–10 minutes) | 24 hours       |
+| Google    | Implicit (Gemini 2.5+)    | Implicit       |
+
+On `off`, Octavus emits no explicit cache options. Providers that auto-cache (OpenAI on prefixes ≥ 1,024 tokens, Gemini 2.5+) may still cache transparently - `off` just disables Octavus's opt-in behavior.
+
+### Threads don't inherit
+
+Named threads (created with `start-thread`) read their own `cache` field independently - they **do not** inherit the agent's cache value:
+
+```yaml
+agent:
+  cache: extended # 1-hour TTL on the main thread
+
+handlers:
+  summarize:
+    Start summary:
+      block: start-thread
+      thread: summary
+      # No cache field → defaults to 'auto' (5-minute TTL), NOT 'extended'
+      system: summary-system
+```
+
+This is intentional: named threads are often used for short, one-shot work (summarization, classification) where the long TTL would be wasted. Set `cache` explicitly on `start-thread` when you do want it.
+
+### Cost trade-offs
+
+- **Cache reads** are always much cheaper than uncached input on any provider - caching is effectively free if your prefix is stable.
+- **Cache writes** on Anthropic cost ~1.25× input for `auto` and 2× input for `extended`. OpenAI and Google don't charge separately for cache writes.
+- Use `extended` only when the same prefix is genuinely reused across sessions that span hours; otherwise the higher write cost dominates the savings.
+
 ## Skills
 
 Enable Octavus skills for code execution and file generation:
@@ -297,9 +365,9 @@ When `imageModel` is configured, the `octavus_generate_image` tool becomes avail
 
 The tool supports three image sizes:
 
-- `1024x1024` (default) — Square
-- `1792x1024` — Landscape (16:9)
-- `1024x1792` — Portrait (9:16)
+- `1024x1024` (default) - Square
+- `1792x1024` - Landscape (16:9)
+- `1024x1792` - Portrait (9:16)
 
 ### Image Editing with Reference Images
 
@@ -338,7 +406,7 @@ agent:
 
 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).
+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:
 
@@ -346,6 +414,28 @@ Use cases:
 - Fact verification and documentation lookups
 - Any information that may have changed since the model's training
 
+## TODO List
+
+Enable the LLM to maintain a structured task list while it works:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  todoList: true
+  agentic: true
+```
+
+When `todoList` is enabled, the `octavus_todo_write` tool becomes available. The LLM creates and updates a list of items - each with `id`, `content`, and `status` (`pending`, `in_progress`, `completed`, `cancelled`) - and the platform emits a `todo-update` stream event with the resolved snapshot. The Client SDK accumulates updates into a single `UITodoPart` per assistant message, so consumers render an evolving "Plan" card without managing state themselves.
+
+The list persists across messages: the LLM can use `merge=true` to update items by id (sending only the changed fields), or `merge=false` to replace the list entirely.
+
+Use cases:
+
+- Multi-step tasks where the user benefits from seeing progress
+- Long-running agentic loops that should communicate intent
+- Workflows where the agent plans before acting
+
 ## Temperature
 
 Control response randomness:
@@ -381,7 +471,7 @@ agent:
         description: Processing PDF
 ```
 
-Provider options are validated against the model—using `anthropic:` with a non-Anthropic model will fail validation.
+Provider options are validated against the model - using `anthropic:` with a non-Anthropic model will fail validation.
 
 See [Provider Options](/docs/protocol/provider-options) for full documentation.
 
@@ -398,6 +488,7 @@ handlers:
       model: anthropic/claude-sonnet-4-5 # Different model
       backupModel: openai/gpt-4o # Failover model
       thinking: low # Different thinking
+      cache: off # Different cache mode (does not inherit from agent)
       maxSteps: 1 # Limit tool calls
       system: escalation-summary # Different prompt
       mcpServers: [figma, browser] # Thread-specific MCP servers
@@ -405,9 +496,10 @@ handlers:
       references: [escalation-policy] # Thread-specific references
       imageModel: google/gemini-2.5-flash-image # Thread-specific image model
       webSearch: true # Thread-specific web search
+      todoList: true # Thread-specific task list
 ```
 
-Each thread can have its own model, backup model, MCP servers, 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.
+Each thread can have its own model, backup model, cache mode, MCP servers, skills, references, image model, web search setting, and task list 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
 
@@ -465,6 +557,7 @@ agent:
   skills: [qr-code] # Octavus skills
   references: [support-policies] # On-demand context
   webSearch: true # Built-in web search
+  todoList: true # Structured task tracking
   agentic: true
   maxSteps: 10
   thinking: medium

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

@@ -28,7 +28,7 @@ Use external tools instead when:
 
 Define all skills in the `skills:` section, then reference which skills are available where they're used:
 
-**Interactive agents** — reference in `agent.skills`:
+**Interactive agents** - reference in `agent.skills`:
 
 ```yaml
 skills:
@@ -45,7 +45,7 @@ agent:
   skills: [qr-code]
 ```
 
-**Workers and named threads** — reference per-thread in `start-thread.skills`:
+**Workers and named threads** - reference per-thread in `start-thread.skills`:
 
 ```yaml
 skills:
@@ -348,8 +348,8 @@ print(result.stdout)
 Key patterns:
 
 - **Read stdin**: `json.load(sys.stdin)` to get the `input` object from the `octavus_skill_run` call
-- **Access secrets**: `os.environ["SECRET_NAME"]` — secrets are injected as env vars
-- **Print output**: Write results to stdout — the LLM sees the (redacted) stdout
+- **Access secrets**: `os.environ["SECRET_NAME"]` - secrets are injected as env vars
+- **Print output**: Write results to stdout - the LLM sees the (redacted) stdout
 - **Error handling**: Write errors to stderr and exit with non-zero code
 
 ### Declaring Secrets in SKILL.md
@@ -447,10 +447,10 @@ The LLM sees these errors and can retry or explain to users.
 
 For skills with configured secrets:
 
-- **Isolated sandbox** — each secure skill gets its own sandbox, preventing cross-skill secret leakage
-- **No arbitrary code** — `octavus_code_run`, `octavus_file_write`, and `octavus_file_read` are blocked for secure skills, so only pre-built scripts can execute
-- **Output redaction** — all stdout and stderr are scanned for secret values before being returned to the LLM
-- **Encrypted at rest** — secrets are encrypted using AES-256-GCM and only decrypted at execution time
+- **Isolated sandbox** - each secure skill gets its own sandbox, preventing cross-skill secret leakage
+- **No arbitrary code** - `octavus_code_run`, `octavus_file_write`, and `octavus_file_read` are blocked for secure skills, so only pre-built scripts can execute
+- **Output redaction** - all stdout and stderr are scanned for secret values before being returned to the LLM
+- **Encrypted at rest** - secrets are encrypted using AES-256-GCM and only decrypted at execution time
 
 ### Input Validation
 
@@ -534,16 +534,16 @@ Check execution logs in the platform debug view:
 
 ## Best Practices Summary
 
-1. **Enable only needed skills** — Don't overwhelm the LLM
-2. **Choose appropriate display modes** — Match user experience needs
-3. **Write clear skill descriptions** — Help LLM understand when to use
-4. **Handle errors gracefully** — Provide helpful error messages
-5. **Test skills locally** — Verify before uploading
-6. **Monitor execution** — Check logs for issues
-7. **Combine with tools** — Use tools for data, skills for processing
-8. **Consider performance** — Be aware of timeouts and limits
-9. **Use secrets for credentials** — Declare secrets in frontmatter instead of hardcoding tokens
-10. **Design scripts for stdin input** — Secure skills receive JSON via stdin, so plan for both input methods if the skill might be used in either mode
+1. **Enable only needed skills** - Don't overwhelm the LLM
+2. **Choose appropriate display modes** - Match user experience needs
+3. **Write clear skill descriptions** - Help LLM understand when to use
+4. **Handle errors gracefully** - Provide helpful error messages
+5. **Test skills locally** - Verify before uploading
+6. **Monitor execution** - Check logs for issues
+7. **Combine with tools** - Use tools for data, skills for processing
+8. **Consider performance** - Be aware of timeouts and limits
+9. **Use secrets for credentials** - Declare secrets in frontmatter instead of hardcoding tokens
+10. **Design scripts for stdin input** - Secure skills receive JSON via stdin, so plan for both input methods if the skill might be used in either mode
 
 ## Next Steps
 

package/content/04-protocol/10-types.md

@@ -9,11 +9,11 @@ Types let you define reusable data structures for your agent. Use them in inputs
 
 ## Why Types?
 
-- **Reusability** — Define once, use in multiple places
-- **Validation** — Catch errors at protocol validation time
-- **Documentation** — Clear data contracts for your agent
-- **Tool Parameters** — Use complex types in tool parameters
-- **Structured Output** — Get typed JSON responses from the LLM
+- **Reusability** - Define once, use in multiple places
+- **Validation** - Catch errors at protocol validation time
+- **Documentation** - Clear data contracts for your agent
+- **Tool Parameters** - Use complex types in tool parameters
+- **Structured Output** - Get typed JSON responses from the LLM
 
 ## Defining Types
 
@@ -504,9 +504,9 @@ The tool receives: `{ cartItems: [{ productId: "...", quantity: 1 }, ...] }`
 
 Named array types provide:
 
-- **Reusability** — Use the same array type in multiple tools
-- **Clear schema** — The array structure is validated
-- **Clean tool calls** — No unnecessary wrapper objects
+- **Reusability** - Use the same array type in multiple tools
+- **Clear schema** - The array structure is validated
+- **Clean tool calls** - No unnecessary wrapper objects
 
 ## Structured Output
 
@@ -602,9 +602,9 @@ The `responseType` must be an **object type** (regular custom type with properti
 
 The following cannot be used directly as `responseType`:
 
-- **Discriminated unions** — LLM providers don't allow `anyOf` at the schema root ([OpenAI docs](https://platform.openai.com/docs/guides/structured-outputs#root-objects-must-not-be-anyof-and-must-be-an-object))
-- **Array types** — Must be wrapped in an object
-- **Primitives** — `string`, `number`, etc. are not valid
+- **Discriminated unions** - LLM providers don't allow `anyOf` at the schema root ([OpenAI docs](https://platform.openai.com/docs/guides/structured-outputs#root-objects-must-not-be-anyof-and-must-be-an-object))
+- **Array types** - Must be wrapped in an object
+- **Primitives** - `string`, `number`, etc. are not valid
 
 ```yaml
 types:
@@ -695,23 +695,23 @@ Types are validated when the protocol is loaded:
 
 ### Type Definition Limits
 
-- **No standalone `array` or `object`** — Define a custom type instead, or use `unknown` for untyped data
-- **No recursive types** — A type cannot reference itself (directly or indirectly)
-- **No generic types** — Types are concrete, not parameterized
-- **String enums only** — `enum` values must be strings
-- **No array constraints** — `minItems` and `maxItems` are not supported (LLM providers don't enforce them)
+- **No standalone `array` or `object`** - Define a custom type instead, or use `unknown` for untyped data
+- **No recursive types** - A type cannot reference itself (directly or indirectly)
+- **No generic types** - Types are concrete, not parameterized
+- **String enums only** - `enum` values must be strings
+- **No array constraints** - `minItems` and `maxItems` are not supported (LLM providers don't enforce them)
 
 ### Tool Limitations
 
-- **Tool parameters are always objects** — Each tool call is `{ param1: value1, param2: value2, ... }`
-- **Array parameters need named types** — Use top-level array types for array parameters
+- **Tool parameters are always objects** - Each tool call is `{ param1: value1, param2: value2, ... }`
+- **Array parameters need named types** - Use top-level array types for array parameters
 
 ### Structured Output Limitations
 
-- **responseType must be an object type** — Only object types can be used as responseType
-- **Discriminated unions need object wrapper** — Unions (`anyOf`) are not allowed at the schema root
-- **Array types need object wrapper** — Arrays cannot be used directly as responseType
-- **Primitives are not allowed** — `string`, `number`, etc. cannot be used as responseType
+- **responseType must be an object type** - Only object types can be used as responseType
+- **Discriminated unions need object wrapper** - Unions (`anyOf`) are not allowed at the schema root
+- **Array types need object wrapper** - Arrays cannot be used directly as responseType
+- **Primitives are not allowed** - `string`, `number`, etc. cannot be used as responseType
 
 These limitations exist because LLM providers (OpenAI, Anthropic) require the root schema to be an object:
 

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

@@ -11,16 +11,16 @@ Workers are agents designed for task-based execution. Unlike interactive agents
 
 Workers are ideal for:
 
-- **Background processing** — Long-running tasks that don't need conversation
-- **Composable tasks** — Reusable units of work called by other agents
-- **Pipelines** — Multi-step processing with structured output
-- **Parallel execution** — Tasks that can run independently
+- **Background processing** - Long-running tasks that don't need conversation
+- **Composable tasks** - Reusable units of work called by other agents
+- **Pipelines** - Multi-step processing with structured output
+- **Parallel execution** - Tasks that can run independently
 
 Use interactive agents instead when:
 
-- **Conversation is needed** — Multi-turn dialogue with users
-- **Persistence matters** — State should survive across interactions
-- **Session context** — User context needs to persist
+- **Conversation is needed** - Multi-turn dialogue with users
+- **Persistence matters** - State should survive across interactions
+- **Session context** - User context needs to persist
 
 ## Worker vs Interactive
 
@@ -124,7 +124,7 @@ Workers are identified by the `format` field:
 
 ### No Global Agent Config
 
-Interactive agents have a global `agent:` section that configures a main thread. Workers don't have this — every thread must be explicitly created via `start-thread`:
+Interactive agents have a global `agent:` section that configures a main thread. Workers don't have this - every thread must be explicitly created via `start-thread`:
 
 ```yaml
 # Interactive agent: Global config
@@ -219,20 +219,21 @@ steps:
 
 All LLM configuration goes here:
 
-| Field         | Description                                       |
-| ------------- | ------------------------------------------------- |
-| `thread`      | Thread name (defaults to block name)              |
-| `model`       | LLM model to use                                  |
-| `system`      | System prompt filename (required)                 |
-| `input`       | Variables for system prompt                       |
-| `tools`       | Tools available in this thread                    |
-| `skills`      | Octavus skills available in this thread           |
-| `mcpServers`  | MCP servers 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) |
+| Field         | Description                                                 |
+| ------------- | ----------------------------------------------------------- |
+| `thread`      | Thread name (defaults to block name)                        |
+| `model`       | LLM model to use                                            |
+| `system`      | System prompt filename (required)                           |
+| `input`       | Variables for system prompt                                 |
+| `tools`       | Tools available in this thread                              |
+| `skills`      | Octavus skills available in this thread                     |
+| `mcpServers`  | MCP servers available in this thread                        |
+| `imageModel`  | Image generation model                                      |
+| `webSearch`   | Enable built-in web search tool                             |
+| `thinking`    | Extended reasoning level                                    |
+| `cache`       | Prompt caching mode: `auto` (default), `extended`, or `off` |
+| `temperature` | Model temperature                                           |
+| `maxSteps`    | Maximum tool call cycles (enables agentic if > 1)           |
 
 ## Simple Example
 
@@ -389,7 +390,7 @@ steps:
     maxSteps: 10
 ```
 
-Workers resolve their own MCP connections independently — they don't inherit MCP servers from a parent interactive agent. Remote MCP connections are project-scoped, so a worker in the same project automatically has access to the same OAuth connections.
+Workers resolve their own MCP connections independently - they don't inherit MCP servers from a parent interactive agent. Remote MCP connections are project-scoped, so a worker in the same project automatically has access to the same OAuth connections.
 
 See [MCP Servers](/docs/protocol/mcp-servers) for full documentation.
 
@@ -423,8 +424,8 @@ See [Skills](/docs/protocol/skills) for full documentation.
 
 Workers support the same tool handling as interactive agents:
 
-- **Server tools** — Handled by tool handlers you provide
-- **Client tools** — Pause execution, return tool request to caller
+- **Server tools** - Handled by tool handlers you provide
+- **Client tools** - Pause execution, return tool request to caller
 
 ```typescript
 // Non-streaming: get the output directly
@@ -467,8 +468,8 @@ All standard events (text-delta, tool calls, etc.) are also emitted.
 
 Interactive agents can call workers in two ways:
 
-1. **Deterministically** — Using the `run-worker` block
-2. **Agentically** — LLM calls worker as a tool
+1. **Deterministically** - Using the `run-worker` block
+2. **Agentically** - LLM calls worker as a tool
 
 ### Worker Declaration
 
@@ -542,6 +543,6 @@ When the worker calls its `search` tool, your `web-search` handler executes.
 
 ## Next Steps
 
-- [Server SDK Workers](/docs/server-sdk/workers) — Executing workers from code
-- [Handlers](/docs/protocol/handlers) — Block reference for steps
-- [Agent Config](/docs/protocol/agent-config) — Model and settings
+- [Server SDK Workers](/docs/server-sdk/workers) - Executing workers from code
+- [Handlers](/docs/protocol/handlers) - Block reference for steps
+- [Agent Config](/docs/protocol/agent-config) - Model and settings

package/content/04-protocol/12-references.md

@@ -11,9 +11,9 @@ References are markdown documents that agents can fetch on demand. Instead of lo
 
 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
+- **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
 
@@ -165,10 +165,10 @@ When a user asks the agent to review code, the agent will:
 
 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
+- **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
 
@@ -184,6 +184,6 @@ Use **references** when the agent needs access to text-based knowledge. Use **sk
 
 ## 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
+- [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