@octavus/docs 3.4.0 → 3.6.0

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

@@ -75,6 +75,67 @@ console.log({
 
 > **Note**: Use `getMessages()` for client-facing code. The `get()` method returns internal message format that includes hidden content not intended for end users.
 
+## Getting Execution Logs
+
+`getLogs()` returns the chronological execution trace for a session - triggers, messages, tool calls, LLM responses, errors, and other events emitted while the agent ran. Useful for debugging, observability, and building custom timeline views.
+
+```typescript
+const result = await client.agentSessions.getLogs(sessionId);
+
+if (result.status === 'expired') {
+  console.log('Session expired:', result.sessionId);
+} else {
+  for (const entry of result.entries) {
+    console.log(entry.type, entry.timestamp);
+  }
+}
+```
+
+Each entry is a typed variant of `ExecutionLogEntry` (a discriminated union) so consumers can narrow on `entry.type`:
+
+```typescript
+const result = await client.agentSessions.getLogs(sessionId);
+
+if (result.status !== 'expired') {
+  const toolCalls = result.entries.filter((e) => e.type === 'tool-call');
+  for (const call of toolCalls) {
+    // call.toolName, call.toolArguments are typed without optional chaining
+    console.log(call.toolName, call.toolArguments);
+  }
+}
+```
+
+### Excluding Model Request Payloads
+
+Model-request entries include the full provider request body and can be large. Pass `excludeModelRequests: true` to skip them:
+
+```typescript
+const result = await client.agentSessions.getLogs(sessionId, {
+  excludeModelRequests: true,
+});
+```
+
+### Truncation
+
+Responses are capped at 1000 entries (most recent). When the log exceeds that cap, the response includes `total` and `truncated` so consumers can detect this:
+
+```typescript
+const result = await client.agentSessions.getLogs(sessionId);
+
+if (result.status !== 'expired' && result.truncated) {
+  console.warn(`Showing latest 1000 of ${result.total} entries`);
+}
+```
+
+### Response Types
+
+| Status    | Type                  | Description                                                                                  |
+| --------- | --------------------- | -------------------------------------------------------------------------------------------- |
+| `active`  | `ExecutionLogsResult` | `{ sessionId, entries, total?, truncated? }`. `total` and `truncated` are present when known |
+| `expired` | `ExpiredSessionState` | `{ sessionId, agentId, status: 'expired', createdAt }`                                       |
+
+> **Forward-compatible types**: `ExecutionLogEntry` may gain new variants over time. Include a `default` case when switching on `entry.type` so unknown variants are handled gracefully.
+
 ## Attaching to Sessions
 
 To trigger actions on a session, you need to attach to it first:

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

@@ -59,18 +59,25 @@ const sessionId = await client.agentSessions.create('support-chat', {
 });
 ```
 
-Inputs can also be used for [dynamic model selection](/docs/protocol/agent-config#dynamic-model-selection):
+Inputs can also drive agent configuration at session creation time. The `model`, `backupModel`, `imageModel`, `temperature`, `thinking`, and `maxSteps` fields all accept variable references:
 
 ```yaml
 input:
   MODEL:
     type: string
     description: The LLM model to use
+  TEMPERATURE:
+    type: number
+    description: Override temperature
+    optional: true
 
 agent:
   model: MODEL # Resolved from session input
+  temperature: TEMPERATURE # Same pattern works for thinking, maxSteps
 ```
 
+Each setting accepts the natural type for that field - declare `temperature: number`, `maxSteps: integer`, `thinking: string`. See [Dynamic Model Selection](/docs/protocol/agent-config#dynamic-model-selection) and [Dynamic Configuration](/docs/protocol/agent-config#dynamic-configuration) for details.
+
 In prompts, reference variables with `{{VARIABLE_NAME}}`:
 
 ```markdown

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

@@ -42,12 +42,31 @@ tools:
 
 ### Display Modes
 
-| Mode          | Behavior                                    |
-| ------------- | ------------------------------------------- |
-| `hidden`      | Tool runs silently, user doesn't see it     |
-| `name`        | Shows tool name while executing             |
-| `description` | Shows description while executing (default) |
-| `stream`      | Streams tool progress if available          |
+Controls what the client sees about tool execution. The default is `description`.
+
+| Mode          | Behavior                                                                                                                                                           |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `hidden`      | No UI events emitted. The tool executes silently and the user has no awareness it was called. Use for internal plumbing tools (title setting, context management). |
+| `name`        | Shows the raw tool name while executing. Arguments and result are not displayed.                                                                                   |
+| `description` | Shows the tool's description while executing (default). Arguments are visible during live streaming but the result is not preserved after page refresh.            |
+| `stream`      | Full visibility. Arguments stream progressively as the LLM generates them, and the result is shown after execution. The result is preserved after page refresh.    |
+
+**When to use `stream`:**
+
+- Client tools where the user benefits from seeing arguments or results
+- Interactive client tools (user provides input via the tool card)
+- Tools whose result is rendered via `renderToolCallResult`
+- Any tool where transparency into what was sent/received matters
+
+**When to use `hidden`:**
+
+- Internal lifecycle tools (e.g., session title setting)
+- Context-setting tools that would clutter the UI
+- Tools that are implementation details of the agent's protocol
+
+**Refresh and restore behavior:**
+
+`stream` is the only mode that preserves the tool result after a page refresh. For all other modes, the result is available during the live session but stripped on refresh. On session restore (when the session expires and is rebuilt from stored `UIMessage[]`), `stream` tools retain their original result while other modes receive a placeholder.
 
 ## Parameters
 

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

@@ -53,12 +53,14 @@ skills:
 
 ### Display Modes
 
-| Mode          | Behavior                                    |
-| ------------- | ------------------------------------------- |
-| `hidden`      | Skill usage not shown to users              |
-| `name`        | Shows skill name while executing            |
-| `description` | Shows description while executing (default) |
-| `stream`      | Streams progress if available               |
+The `display` setting on a skill applies to all tools under that skill namespace. See [Tool Display Modes](/docs/protocol/tools#display-modes) for full details on each mode.
+
+| Mode          | Behavior                                                                                                             |
+| ------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `hidden`      | Skill tools run silently, no UI events emitted                                                                       |
+| `name`        | Shows skill name while executing                                                                                     |
+| `description` | Shows description while executing (default). Result not preserved after page refresh.                                |
+| `stream`      | Full visibility - arguments stream progressively, result shown after execution, result preserved after page refresh. |
 
 ## Enabling Skills
 

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

@@ -158,7 +158,7 @@ Start summary thread:
 
 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.
+The `model` field can also reference a variable for dynamic model selection. The `backupModel`, `temperature`, `thinking`, and `maxSteps` fields also support variable references - see [Dynamic Configuration](/docs/protocol/agent-config#dynamic-configuration).
 
 ```yaml
 Start summary thread:

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

@@ -21,25 +21,25 @@ agent:
 
 ## Configuration Options
 
-| 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                                                       |
-| `cache`          | No       | Prompt caching mode: `auto` (default), `extended`, or `off`                    |
-| `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) - literal or variable reference                      |
+| `temperature`    | No       | Model temperature (0-2), `"off"`, or a variable reference                                |
+| `thinking`       | No       | Extended reasoning level (`low`/`medium`/`high`/`max`), `"off"`, or a variable reference |
+| `cache`          | No       | Prompt caching mode: `auto` (default), `extended`, or `off`                              |
+| `anthropic`      | No       | Anthropic-specific options (tools, skills)                                               |
 
 ## Models
 
@@ -222,14 +222,15 @@ Enable extended reasoning for complex tasks:
 ```yaml
 agent:
   model: anthropic/claude-sonnet-4-5
-  thinking: medium # low | medium | high
+  thinking: medium # low | medium | high | max
 ```
 
-| Level    | Use Case            |
-| -------- | ------------------- |
-| `low`    | Simple reasoning    |
-| `medium` | Moderate complexity |
-| `high`   | Complex analysis    |
+| Level    | Use Case                           |
+| -------- | ---------------------------------- |
+| `low`    | Simple reasoning                   |
+| `medium` | Moderate complexity                |
+| `high`   | Complex analysis                   |
+| `max`    | Maximum reasoning budget available |
 
 Thinking content streams to the UI and can be displayed to users.
 
@@ -237,15 +238,15 @@ Thinking content streams to the UI and can be displayed to users.
 
 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                                                        |
+| 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 / max` |
+| Anthropic older (4.5 and earlier)                                          | Fixed token budgets: `low` ~5,000, `medium` ~10,000, `high` ~20,000, `max` ~40,000                      |
+| OpenAI (GPT-5.x, o-series)                                                 | `reasoningEffort: low / medium / high` (`max` maps to `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, `max` 65,536                                 |
+| OpenRouter                                                                 | Unified `reasoning.max_tokens` (translated upstream)                                                    |
+| Vercel AI Gateway                                                          | Forwards the underlying provider's options                                                              |
 
 ## Prompt Caching
 
@@ -453,6 +454,68 @@ agent:
 - `0.8 - 1.2`: Creative, varied responses
 - `> 1.2`: Very creative (may be inconsistent)
 
+## Dynamic Configuration
+
+Like `model`, the `temperature`, `thinking`, and `maxSteps` fields can also reference an input variable. Consumers choose values at session creation, so the same agent can be tuned per call without protocol changes:
+
+```yaml
+input:
+  TEMPERATURE:
+    type: number
+    description: Override temperature (0-2)
+    optional: true
+  THINKING:
+    type: string
+    description: Override thinking effort (low/medium/high/max, or "off")
+    optional: true
+  MAX_STEPS:
+    type: integer
+    description: Override max agentic steps
+    optional: true
+
+agent:
+  model: anthropic/claude-sonnet-4-5
+  temperature: TEMPERATURE
+  thinking: THINKING
+  maxSteps: MAX_STEPS
+  system: system
+```
+
+When creating a session, pass the values in their natural type:
+
+```typescript
+const sessionId = await client.agentSessions.create('my-agent', {
+  TEMPERATURE: 0.7,
+  THINKING: 'medium',
+  MAX_STEPS: 5,
+});
+```
+
+### Accepted values
+
+The resolver accepts the natural type for each field, plus a string fallback so consumers can pass values from form inputs without coercing first.
+
+| Field         | Suggested input type                       | Value at session creation                          |
+| ------------- | ------------------------------------------ | -------------------------------------------------- |
+| `temperature` | `number` (or `string` for `"off"` support) | A number `0`-`2`, a numeric string, or `"off"`     |
+| `thinking`    | `string`                                   | `"low"`, `"medium"`, `"high"`, `"max"`, or `"off"` |
+| `maxSteps`    | `integer` (or `string`)                    | A positive integer or a positive integer string    |
+
+The protocol's `input:` declaration enforces what the consumer can pass. Pick `type: number` / `type: integer` if you want native numeric overrides; pick `type: string` (or `type: unknown`) if you also need to pass the `"off"` sentinel for `temperature`.
+
+### Explicit "off" vs not set
+
+`temperature` and `thinking` accept an explicit `"off"` value to disable the field at session creation. This is different from omitting the variable:
+
+- **Variable not provided** -> the field is unset; the provider uses its default behavior
+- **Variable provided as `"off"`** -> the field is explicitly disabled (no temperature emitted, reasoning disabled)
+
+The distinction matters because `temperature` and `thinking` are mutually exclusive at the provider level - several providers ignore temperature when reasoning is enabled. Use `"off"` to opt one out so the other takes effect.
+
+### Validation
+
+Variable references are caught at protocol validation time. If `temperature: TEMPERATURE` is declared but `TEMPERATURE` is missing from `input:` or `variables:`, the validator surfaces the error in the dashboard before the agent runs.
+
 ## Provider Options
 
 Enable provider-specific features like Anthropic's built-in tools and skills:

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

@@ -219,21 +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                                    |
-| `cache`       | Prompt caching mode: `auto` (default), `extended`, or `off` |
-| `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 (`low`/`medium`/`high`/`max`), `"off"`, or variable reference |
+| `cache`       | Prompt caching mode: `auto` (default), `extended`, or `off`                            |
+| `temperature` | Model temperature (0-2), `"off"`, or variable reference                                |
+| `maxSteps`    | Maximum tool call cycles (enables agentic if > 1), or variable reference               |
 
 ## Simple Example
 
@@ -520,14 +520,20 @@ The LLM can then call workers as tools during conversation.
 
 ### Display Modes
 
-Control how worker execution appears to users:
+Controls how worker execution appears to users. The default for workers is `stream`.
 
-| Mode          | Behavior                          |
-| ------------- | --------------------------------- |
-| `hidden`      | Worker runs silently              |
-| `name`        | Shows worker name                 |
-| `description` | Shows description text            |
-| `stream`      | Streams all worker events to user |
+| Mode          | Behavior                                                                                                                           |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `hidden`      | Worker runs silently. No events reach the client - no `UIWorkerPart` is created.                                                   |
+| `name`        | Shows a running/done indicator with the worker name. No nested content (text, tool calls, reasoning) is forwarded.                 |
+| `description` | Shows a running/done indicator with the worker description. No nested content is forwarded.                                        |
+| `stream`      | Full visibility. All nested events are forwarded - text, reasoning, tool calls, sources, files. Worker input is included on start. |
+
+**Progressive input streaming:** When a worker with `display: stream` is invoked agentically (LLM calls it as a tool), the `UIWorkerPart` appears in the UI immediately as the LLM starts generating the worker's arguments. The worker input streams progressively into the worker part, the same way text tokens stream into a text part. Once input finishes, worker execution begins and nested content flows into the same worker part. There is no intermediate tool card.
+
+**`name` and `description` modes:** Worker input is stripped from the `worker-start` event (it may contain sensitive data). Only the running/done status and the final `worker-result` are forwarded to the parent stream. Use these for workers where the user only needs to know the worker ran, not what it did internally.
+
+**`hidden` mode:** The worker executes normally but produces no UI presence at all. Use for internal workers that are implementation details.
 
 ### Tool Mapping