@octavus/docs 2.14.0 → 2.16.0

package/content/01-getting-started/02-quickstart.md

@@ -141,6 +141,7 @@ export async function POST(request: Request) {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
       Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
     },
   });
 }

package/content/02-server-sdk/04-streaming.md

@@ -27,6 +27,7 @@ return new Response(toSSEStream(events), {
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache',
     Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
   },
 });
 
@@ -36,6 +37,14 @@ for await (const event of events) {
 }
 ```
 
+The `X-Accel-Buffering: no` header disables proxy buffering on Nginx-based infrastructure (including Vercel), ensuring SSE events are forwarded immediately instead of being batched.
+
+### Heartbeat
+
+`toSSEStream` automatically sends SSE comment lines (`: heartbeat`) every 15 seconds during idle periods. This prevents proxies and load balancers from closing the connection due to inactivity — particularly important during multi-step executions where the stream may be silent while waiting for tool processing or LLM responses.
+
+Heartbeat comments are ignored by all SSE parsers per the spec. No client-side handling is needed.
+
 ## Event Types
 
 The stream emits various event types for lifecycle, text, reasoning, and tool interactions.

package/content/03-client-sdk/06-http-transport.md

@@ -80,6 +80,7 @@ export async function POST(request: Request) {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
       Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
     },
   });
 }
@@ -234,6 +235,7 @@ app.post('/api/trigger', async (req, res) => {
   res.setHeader('Content-Type', 'text/event-stream');
   res.setHeader('Cache-Control', 'no-cache');
   res.setHeader('Connection', 'keep-alive');
+  res.setHeader('X-Accel-Buffering', 'no');
 
   // Pipe the stream to the response
   const reader = stream.getReader();

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/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
 

package/content/06-examples/02-nextjs-chat.md

@@ -158,6 +158,7 @@ export async function POST(request: Request) {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
       Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
     },
   });
 }