@octavus/docs 2.15.0 → 2.17.0

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

@@ -107,17 +107,19 @@ This also works for named threads in interactive agents, allowing different thre
 
 When skills are enabled, the LLM has access to these tools:
 
-| Tool                 | Purpose                                 |
-| -------------------- | --------------------------------------- |
-| `octavus_skill_read` | Read skill documentation (SKILL.md)     |
-| `octavus_skill_list` | List available scripts in a skill       |
-| `octavus_skill_run`  | Execute a pre-built script from a skill |
-| `octavus_code_run`   | Execute arbitrary Python/Bash code      |
-| `octavus_file_write` | Create files in the sandbox             |
-| `octavus_file_read`  | Read files from the sandbox             |
+| Tool                 | Purpose                                 | Availability         |
+| -------------------- | --------------------------------------- | -------------------- |
+| `octavus_skill_read` | Read skill documentation (SKILL.md)     | All skills           |
+| `octavus_skill_list` | List available scripts in a skill       | All skills           |
+| `octavus_skill_run`  | Execute a pre-built script from a skill | All skills           |
+| `octavus_code_run`   | Execute arbitrary Python/Bash code      | Standard skills only |
+| `octavus_file_write` | Create files in the sandbox             | Standard skills only |
+| `octavus_file_read`  | Read files from the sandbox             | Standard skills only |
 
 The LLM learns about available skills through system prompt injection and can use these tools to interact with skills.
 
+Skills that have [secrets](#skill-secrets) configured run in **secure mode**, where only `octavus_skill_read`, `octavus_skill_list`, and `octavus_skill_run` are available. See [Skill Secrets](#skill-secrets) below.
+
 ## Example: QR Code Generation
 
 ```yaml
@@ -212,6 +214,17 @@ Main script for generating QR codes...
 
 ````
 
+### Frontmatter Fields
+
+| Field         | Required | Description                                            |
+| ------------- | -------- | ------------------------------------------------------ |
+| `name`        | Yes      | Skill slug (lowercase, hyphens)                        |
+| `description` | Yes      | What the skill does (shown to the LLM)                 |
+| `version`     | No       | Semantic version string                                |
+| `license`     | No       | License identifier                                     |
+| `author`      | No       | Skill author                                           |
+| `secrets`     | No       | Array of secret declarations (enables secure mode)     |
+
 ## Best Practices
 
 ### 1. Clear Descriptions
@@ -337,6 +350,72 @@ steps:
 
 Thread-level `sandboxTimeout` takes priority over agent-level. Maximum: 1 hour (3,600,000 ms).
 
+## Skill Secrets
+
+Skills can declare secrets they need to function. When an organization configures those secrets, the skill runs in **secure mode** with additional isolation.
+
+### Declaring Secrets
+
+Add a `secrets` array to your SKILL.md frontmatter:
+
+```yaml
+---
+name: github
+description: >
+  Run GitHub CLI (gh) commands to manage repos, issues, PRs, and more.
+secrets:
+  - name: GITHUB_TOKEN
+    description: GitHub personal access token with repo access
+    required: true
+  - name: GITHUB_ORG
+    description: Default GitHub organization
+    required: false
+---
+```
+
+Each secret declaration has:
+
+| Field         | Required | Description                                                 |
+| ------------- | -------- | ----------------------------------------------------------- |
+| `name`        | Yes      | Environment variable name (uppercase, e.g., `GITHUB_TOKEN`) |
+| `description` | No       | Explains what this secret is for (shown in the UI)          |
+| `required`    | No       | Whether the secret is required (defaults to `true`)         |
+
+Secret names must match the pattern `^[A-Z_][A-Z0-9_]*$` (uppercase letters, digits, and underscores).
+
+### Configuring Secrets
+
+Organization admins configure secret values through the skill editor in the platform UI. Each organization maintains its own independent set of secrets for each skill.
+
+Secrets are encrypted at rest and only decrypted at execution time.
+
+### Secure Mode
+
+When a skill has secrets configured for the organization, it automatically runs in **secure mode**:
+
+- 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
+- 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
+
+### Writing Scripts for Secure Skills
+
+Scripts in secure skills read input from stdin as JSON and access secrets from environment variables:
+
+```python
+import json
+import os
+import sys
+
+input_data = json.load(sys.stdin)
+token = os.environ.get('GITHUB_TOKEN')
+
+# Use the token and input_data to perform the task
+```
+
+For standard skills (without secrets), scripts receive input as CLI arguments. For secure skills, always use stdin JSON.
+
 ## Security
 
 Skills run in isolated sandbox environments:
@@ -345,6 +424,7 @@ 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
 
 ## Next Steps
 

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

@@ -144,16 +144,18 @@ Start summary thread:
   block: start-thread
   thread: summary # Thread name
   model: anthropic/claude-sonnet-4-5 # Optional: different model
+  backupModel: openai/gpt-4o # Failover on provider errors
   thinking: low # Extended reasoning level
   maxSteps: 1 # Tool call limit
   system: escalation-summary # System prompt
   input: [COMPANY_NAME] # Variables for prompt
+  mcpServers: [figma, browser] # MCP servers for this thread
   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:
+The `model` field can also reference a variable for dynamic model selection. The `backupModel` field follows the same format and supports variable references.
 
 ```yaml
 Start summary thread:

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

@@ -14,28 +14,31 @@ agent:
   model: anthropic/claude-sonnet-4-5
   system: system # References prompts/system.md
   tools: [get-user-account] # Available tools
+  mcpServers: [figma, browser] # MCP server connections
   skills: [qr-code] # Available skills
   references: [api-guidelines] # On-demand context documents
 ```
 
 ## 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                    |
-| `references`     | No       | List of references the LLM can fetch on demand            |
-| `sandboxTimeout` | No       | Skill sandbox timeout in ms (default: 5 min, max: 1 hour) |
-| `imageModel`     | No       | Image generation model (enables agentic image generation) |
-| `webSearch`      | No       | Enable built-in web search tool (provider-agnostic)       |
-| `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                                         |
+| `backupModel`    | No       | Backup model for automatic failover on provider errors                         |
+| `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                                                 |
+| `mcpServers`     | No       | List of MCP servers to connect (see [MCP Servers](/docs/protocol/mcp-servers)) |
+| `skills`         | No       | List of Octavus skills the LLM can use                                         |
+| `references`     | No       | List of references the LLM can fetch on demand                                 |
+| `sandboxTimeout` | No       | Skill sandbox timeout in ms (default: 5 min, max: 1 hour)                      |
+| `imageModel`     | No       | Image generation model (enables agentic image generation)                      |
+| `webSearch`      | No       | Enable built-in web search tool (provider-agnostic)                            |
+| `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
 
@@ -104,6 +107,41 @@ The model value is validated at runtime to ensure it's in the correct `provider/
 
 > **Note**: When using dynamic models, provider-specific options (like `anthropic:`) may not apply if the model resolves to a different provider.
 
+## Backup Model
+
+Configure a fallback model that activates automatically when the primary model encounters a transient provider error (rate limits, outages, timeouts):
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  backupModel: openai/gpt-4o
+  system: system
+```
+
+When a provider error occurs, the system retries once with the backup model. If the backup also fails, the original error is returned.
+
+**Key behaviors:**
+
+- 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
+
+Like `model`, `backupModel` supports variable references:
+
+```yaml
+input:
+  BACKUP_MODEL:
+    type: string
+    description: Fallback model for provider errors
+
+agent:
+  model: anthropic/claude-sonnet-4-5
+  backupModel: BACKUP_MODEL
+  system: system
+```
+
+> **Tip**: Use a different provider for your backup model (e.g., primary on Anthropic, backup on OpenAI) to maximize resilience against single-provider outages.
+
 ## 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.
@@ -358,16 +396,18 @@ handlers:
       block: start-thread
       thread: summary
       model: anthropic/claude-sonnet-4-5 # Different model
+      backupModel: openai/gpt-4o # Failover model
       thinking: low # Different thinking
       maxSteps: 1 # Limit tool calls
       system: escalation-summary # Different prompt
+      mcpServers: [figma, browser] # Thread-specific MCP servers
       skills: [data-analysis] # Thread-specific skills
       references: [escalation-policy] # Thread-specific references
       imageModel: google/gemini-2.5-flash-image # Thread-specific image model
       webSearch: true # Thread-specific web search
 ```
 
-Each thread can have its own 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, 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.
 
 ## Full Example
 
@@ -399,6 +439,12 @@ tools:
       summary: { type: string }
       priority: { type: string } # low, medium, high
 
+mcpServers:
+  figma:
+    description: Figma design tool integration
+    source: remote
+    display: description
+
 skills:
   qr-code:
     display: description
@@ -406,6 +452,7 @@ skills:
 
 agent:
   model: anthropic/claude-sonnet-4-5
+  backupModel: openai/gpt-4o
   system: system
   input:
     - COMPANY_NAME
@@ -414,6 +461,7 @@ agent:
     - get-user-account
     - search-docs
     - create-support-ticket
+  mcpServers: [figma] # MCP server connections
   skills: [qr-code] # Octavus skills
   references: [support-policies] # On-demand context
   webSearch: true # Built-in web search

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

@@ -307,6 +307,76 @@ Pattern:
 2. LLM uses skill to analyze/process the data
 3. Generate outputs (files, reports)
 
+## Secure Skills
+
+When a skill declares secrets and an organization configures them, the skill runs in secure mode with its own isolated sandbox.
+
+### Standard vs Secure Skills
+
+| Aspect              | Standard Skills                   | Secure Skills                                       |
+| ------------------- | --------------------------------- | --------------------------------------------------- |
+| **Sandbox**         | Shared with other standard skills | Isolated (one per skill)                            |
+| **Available tools** | All 6 skill tools                 | `skill_read`, `skill_list`, `skill_run` only        |
+| **Script input**    | CLI arguments via `args`          | JSON via stdin (use `input` parameter)              |
+| **Environment**     | No secrets                        | Secrets as env vars                                 |
+| **Output**          | Raw stdout/stderr                 | Redacted (secret values replaced with `[REDACTED]`) |
+
+### Writing Scripts for Secure Skills
+
+Secure skill scripts receive structured input via stdin (JSON) and access secrets from environment variables:
+
+```python
+#!/usr/bin/env python3
+import json
+import os
+import sys
+import subprocess
+
+input_data = json.load(sys.stdin)
+token = os.environ["GITHUB_TOKEN"]
+
+repo = input_data.get("repo", "")
+result = subprocess.run(
+    ["gh", "repo", "view", repo, "--json", "name,description"],
+    capture_output=True, text=True,
+    env={**os.environ, "GH_TOKEN": token}
+)
+
+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
+- **Error handling**: Write errors to stderr and exit with non-zero code
+
+### Declaring Secrets in SKILL.md
+
+```yaml
+---
+name: github
+description: >
+  Run GitHub CLI (gh) commands to manage repos, issues, PRs, and more.
+secrets:
+  - name: GITHUB_TOKEN
+    description: GitHub personal access token with repo access
+    required: true
+  - name: GITHUB_ORG
+    description: Default GitHub organization
+    required: false
+---
+```
+
+### Testing Secure Skills Locally
+
+You can test scripts locally by piping JSON to stdin:
+
+```bash
+echo '{"repo": "octavus-ai/agent-sdk"}' | GITHUB_TOKEN=ghp_xxx python scripts/list-issues.py
+```
+
 ## Skill Development Tips
 
 ### Writing SKILL.md
@@ -373,6 +443,15 @@ The LLM sees these errors and can retry or explain to users.
 - **File output only** via `/output/` directory
 - **Time limits** enforced (5-minute default, configurable via `sandboxTimeout`)
 
+### Secret Protection
+
+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
+
 ### Input Validation
 
 Skills should validate inputs:
@@ -455,14 +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
+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