@octavus/docs 2.7.0 → 2.9.0

package/content/02-server-sdk/01-overview.md

@@ -106,6 +106,7 @@ The main entry point for interacting with Octavus.
 interface OctavusClientConfig {
   baseUrl: string; // Octavus API URL
   apiKey?: string; // Your API key
+  traceModelRequests?: boolean; // Enable model request tracing (default: false)
 }
 
 class OctavusClient {
@@ -221,3 +222,4 @@ The client uploads files directly to S3 using the presigned upload URL. See [Fil
 - [Tools](/docs/server-sdk/tools) — Implementing tool handlers
 - [Streaming](/docs/server-sdk/streaming) — Understanding stream events
 - [Workers](/docs/server-sdk/workers) — Executing worker agents
+- [Debugging](/docs/server-sdk/debugging) — Model request tracing and debugging

package/content/02-server-sdk/02-sessions.md

@@ -203,6 +203,8 @@ flowchart TD
     C --> D[4. RETRIEVE]
     D --> C
     C --> E[5. EXPIRE]
+    C --> G[5b. CLEAR]
+    G --> F
     E --> F{6. RESTORE?}
     F -->|Yes| C
     F -->|No| A
@@ -227,6 +229,10 @@ flowchart TD
     E -.- E1["`Sessions expire after
     24 hours (configurable)`"]
 
+    G -.- G1["`**client.agentSessions.clear()**
+    Programmatically clear state
+    Session becomes expired`"]
+
     F -.- F1["`**client.agentSessions.restore()**
     Restore from stored messages
     Or create new session`"]
@@ -380,6 +386,26 @@ async function getOrCreateSession(chatId: string, agentId: string, input: Record
 }
 ```
 
+## Clearing Sessions
+
+To programmatically clear a session's state (e.g., for testing reset/restore flows), use `clear()`:
+
+```typescript
+const result = await client.agentSessions.clear(sessionId);
+console.log(result.cleared); // true
+```
+
+After clearing, the session transitions to `expired` status. You can then restore it with `restore()` or create a new session.
+
+```typescript
+interface ClearSessionResult {
+  sessionId: string;
+  cleared: boolean;
+}
+```
+
+This is idempotent — calling `clear()` on an already expired session succeeds without error.
+
 ## Error Handling
 
 ```typescript

package/content/02-server-sdk/05-cli.md

@@ -140,6 +140,27 @@ Get details about a specific agent by its slug.
 octavus get support-chat
 ```
 
+### `octavus archive <slug>`
+
+Archive an agent by slug (soft delete). Archived agents are removed from the active agent list and their slug is freed for reuse.
+
+```bash
+octavus archive support-chat
+```
+
+**Options:**
+
+- `--json` — Output as JSON (for CI/CD parsing)
+- `--quiet` — Suppress non-essential output
+
+**Example output:**
+
+```
+ℹ Archiving support-chat...
+✓ Archived: support-chat
+  Agent ID: clxyz123abc456
+```
+
 ## Agent Directory Structure
 
 The CLI expects agent definitions in a specific directory structure:

package/content/02-server-sdk/07-debugging.md

@@ -0,0 +1,79 @@
+---
+title: Debugging
+description: Model request tracing and debugging tools for Octavus agents.
+---
+
+# Debugging
+
+## Model Request Tracing
+
+Model request tracing captures the full payload sent to model providers (LLM and image) during agent execution. This helps you understand exactly what was sent — system prompts, messages, tool definitions, and provider options — making it easier to debug agent behavior.
+
+### Enabling Tracing
+
+Enable tracing by setting `traceModelRequests: true` in the client config:
+
+```typescript
+import { OctavusClient } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+  traceModelRequests: true,
+});
+```
+
+When enabled, the SDK sends an `X-Octavus-Trace: true` header with every request. The platform captures the full model request payload before each provider call and stores it in the execution logs.
+
+You can also drive this from an environment variable for per-environment control:
+
+```typescript
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+  traceModelRequests: process.env.TRACE_MODEL_REQUESTS === 'true',
+});
+```
+
+### What Gets Captured
+
+**LLM requests** include:
+
+- Full system prompt
+- All messages in AI SDK format (post-conversion)
+- Tool names, descriptions, and JSON schemas
+- Provider-specific options (thinking budgets, etc.)
+- Temperature, max steps, and thinking configuration
+
+**Image generation requests** include:
+
+- Image generation prompt
+- Requested size
+- Whether reference images were provided
+
+### Where Traces Appear
+
+Traces appear as **Model Request** entries in the execution log timeline, alongside existing entries like triggers, tool calls, and responses. Each trace is linked to the block that made the model call.
+
+In the Octavus dashboard:
+
+- **Session debug view** — Full execution log with expandable model request entries
+- **Agent preview** — Activity panel shows model requests in the execution steps
+
+Each entry shows the raw JSON payload with a copy button for easy inspection.
+
+### Storage
+
+Traces are stored in Redis alongside other execution log entries with a 24-hour TTL. They are not permanently stored. A typical LLM trace with 10 messages and 5 tools is 10–50KB. Image traces are smaller (just prompt and metadata).
+
+### Recommendations
+
+| Environment | Recommendation                                             |
+| ----------- | ---------------------------------------------------------- |
+| Development | Enable — helps debug agent behavior during development     |
+| Staging     | Enable — useful for pre-production testing                 |
+| Production  | Disable (default) — saves storage for high-volume sessions |
+
+### Preview Sessions
+
+Model request tracing is always enabled for preview sessions in the Octavus dashboard. No configuration needed — the platform automatically traces all model requests when using the agent preview.

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

@@ -71,12 +71,14 @@ agent:
   model: MODEL # Resolved from session input
 ```
 
-In prompts, reference with `{{INPUT_NAME}}`:
+In prompts, reference variables with `{{VARIABLE_NAME}}`:
 
 ```markdown
 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.
+
 > **Note:** Variables must be `UPPER_SNAKE_CASE`. Nested properties (dot notation like `{{VAR.property}}`) are not supported. Objects are serialized as JSON when interpolated.
 
 ## Resources

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

@@ -305,16 +305,23 @@ handlers:
 
 ## Block Input Mapping
 
-Map variables to block inputs:
+The `input` field on blocks controls which variables are passed to the prompt. Only variables listed in `input` are available for interpolation.
+
+Variables can come from `protocol.input`, `protocol.resources`, `protocol.variables`, `trigger.input`, or outputs from prior blocks.
 
 ```yaml
-# Simple list (variable name = prompt variable)
+# Array format (same name)
 input: [USER_MESSAGE, COMPANY_NAME]
 
-# Mapping (different names)
+# Array format (rename)
 input:
-  - CONVERSATION: CONVERSATION_TEXT  # CONVERSATION in prompt = CONVERSATION_TEXT
+  - CONVERSATION: CONVERSATION_TEXT  # Prompt sees CONVERSATION, value comes from CONVERSATION_TEXT
   - TICKET_DETAILS: TICKET
+
+# Object format (rename)
+input:
+  CONVERSATION: CONVERSATION_TEXT
+  TICKET_DETAILS: TICKET
 ```
 
 ## Independent Blocks

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

@@ -23,7 +23,7 @@ agent:
 | ------------- | -------- | --------------------------------------------------------- |
 | `model`       | Yes      | Model identifier or variable reference                    |
 | `system`      | Yes      | System prompt filename (without .md)                      |
-| `input`       | No       | Variables to interpolate in system prompt                 |
+| `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) |
@@ -102,7 +102,7 @@ The model value is validated at runtime to ensure it's in the correct `provider/
 
 ## System Prompt
 
-The system prompt sets the agent's persona and instructions:
+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:
@@ -112,7 +112,30 @@ agent:
     - PRODUCT_NAME
 ```
 
-Example `prompts/system.md`:
+Variables in `input` can come from `protocol.input`, `protocol.resources`, or `protocol.variables`.
+
+### Input Mapping Formats
+
+```yaml
+# Array format (same name)
+input:
+  - COMPANY_NAME
+  - PRODUCT_NAME
+
+# Array format (rename)
+input:
+  - CONTEXT: CONVERSATION_SUMMARY  # Prompt sees CONTEXT, value comes from CONVERSATION_SUMMARY
+
+# Object format (rename)
+input:
+  CONTEXT: CONVERSATION_SUMMARY
+```
+
+The left side (label) is what the prompt sees. The right side (source) is where the value comes from.
+
+### Example
+
+`prompts/system.md`:
 
 ```markdown
 You are a friendly support agent for {{COMPANY_NAME}}.

package/content/05-api-reference/02-sessions.md

@@ -212,6 +212,32 @@ curl -X POST https://octavus.ai/api/agent-sessions/:sessionId/restore \
 
 > **Note**: Store the `UIMessage[]` array after each interaction to enable restoration. The restore endpoint reconstructs the conversation state from these messages.
 
+## Clear Session
+
+Clear session state, transitioning it to `expired` status. The session can be restored afterwards with the [Restore Session](#restore-session) endpoint.
+
+This is idempotent — clearing an already expired session succeeds without error.
+
+```
+DELETE /api/agent-sessions/:sessionId
+```
+
+### Response
+
+```json
+{
+  "sessionId": "cm5xyz123abc456def",
+  "cleared": true
+}
+```
+
+### Example
+
+```bash
+curl -X DELETE https://octavus.ai/api/agent-sessions/:sessionId \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
 ## Trigger Session
 
 Execute a trigger on a session. Returns a Server-Sent Events stream.

package/content/05-api-reference/03-agents.md

@@ -15,6 +15,7 @@ Manage agent definitions including protocols and prompts.
 | `/api/agents/:id`      | GET    | Agents OR Sessions  |
 | `/api/agents`          | POST   | Agents              |
 | `/api/agents/:id`      | PATCH  | Agents              |
+| `/api/agents/:id`      | DELETE | Agents              |
 | `/api/agents/validate` | POST   | Agents              |
 
 Read endpoints work with either permission since both the CLI (for sync) and Server SDK (for sessions) need to read agent definitions.
@@ -203,6 +204,37 @@ curl -X PATCH https://octavus.ai/api/agents/:agentId \
   }'
 ```
 
+## Archive Agent
+
+Archive an agent (soft delete). The agent is removed from the active agent list and its slug is freed for reuse. Session history is preserved.
+
+```
+DELETE /api/agents/:id
+```
+
+Supports `?by=slug` query parameter to look up by slug instead of ID.
+
+### Response
+
+```json
+{
+  "agentId": "cm5xvz7k80001abcd",
+  "message": "Agent archived successfully"
+}
+```
+
+### Example
+
+```bash
+# Archive by ID
+curl -X DELETE https://octavus.ai/api/agents/:agentId \
+  -H "Authorization: Bearer YOUR_API_KEY"
+
+# Archive by slug
+curl -X DELETE https://octavus.ai/api/agents/support-chat?by=slug \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
 ## Creating and Managing Agents
 
 There are two ways to manage agents: