@octavus/docs 0.0.1

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

@@ -0,0 +1,255 @@
+---
+title: Tools
+description: Defining external tools agents can use.
+---
+
+# Tools
+
+Tools extend what agents can do. They're defined in the protocol and implemented in your backend.
+
+## Tool Definition
+
+```yaml
+tools:
+  get-user-account:
+    description: Looking up your account information
+    display: description
+    parameters:
+      userId:
+        type: string
+        description: The user ID to look up
+    returns:
+      name: { type: string }
+      email: { type: string }
+      plan: { type: string }
+      createdAt: { type: string }
+```
+
+### Tool Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | Yes | What the tool does (shown to LLM and optionally user) |
+| `display` | No | How to show in UI: `hidden`, `name`, `description`, `stream` |
+| `parameters` | No | Input parameters the tool accepts |
+| `required` | No | List of required parameter names |
+| `returns` | No | Schema of the return value (for documentation) |
+
+### 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 |
+
+## Parameter Types
+
+```yaml
+tools:
+  search-products:
+    description: Search the product catalog
+    parameters:
+      query:
+        type: string
+        description: Search query
+      
+      category:
+        type: string
+        description: Filter by category
+        enum: [electronics, clothing, books, home]
+      
+      maxPrice:
+        type: number
+        description: Maximum price filter
+      
+      inStock:
+        type: boolean
+        description: Only show in-stock items
+      
+      tags:
+        type: array
+        description: Filter by tags
+```
+
+## Making Tools Available
+
+Tools defined in `tools:` are available. To make them usable by the LLM, add them to `agent.tools`:
+
+```yaml
+tools:
+  get-user-account:
+    description: Look up user account
+    parameters:
+      userId: { type: string }
+  
+  create-support-ticket:
+    description: Create a support ticket
+    parameters:
+      summary: { type: string }
+      priority: { type: string, enum: [low, medium, high, urgent] }
+
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  tools:
+    - get-user-account
+    - create-support-ticket  # LLM can decide when to call these
+  agentic: true
+```
+
+## Tool Invocation Modes
+
+### LLM-Decided (Agentic)
+
+The LLM decides when to call tools based on the conversation:
+
+```yaml
+agent:
+  tools: [get-user-account, create-support-ticket]
+  agentic: true  # Allow multiple tool calls
+  maxSteps: 10   # Max tool call cycles
+```
+
+### Deterministic (Block-Based)
+
+Force tool calls at specific points in the handler:
+
+```yaml
+handlers:
+  request-human:
+    # Always create a ticket when escalating
+    Create support ticket:
+      type: tool-call
+      tool: create-support-ticket
+      input:
+        summary: SUMMARY  # From variable
+        priority: medium  # Literal value
+      output: TICKET      # Store result
+```
+
+## Tool Results
+
+### In Prompts
+
+Reference tool results in prompts:
+
+```markdown
+<!-- prompts/ticket-directive.md -->
+A support ticket has been created:
+- Ticket ID: {{TICKET.ticketId}}
+- Estimated Response: {{TICKET.estimatedResponse}}
+
+Let the user know their ticket has been created.
+```
+
+### In Variables
+
+Store tool results for later use:
+
+```yaml
+handlers:
+  request-human:
+    Get account:
+      type: tool-call
+      tool: get-user-account
+      input:
+        userId: USER_ID
+      output: ACCOUNT  # Result stored here
+    
+    Create ticket:
+      type: tool-call
+      tool: create-support-ticket
+      input:
+        summary: SUMMARY
+        priority: medium
+        # Can reference ACCOUNT here
+        email: ACCOUNT.email
+      output: TICKET
+```
+
+## Implementing Tools
+
+Tools are implemented in your backend:
+
+```typescript
+const session = client.agentSessions.attach(sessionId, {
+  tools: {
+    'get-user-account': async (args) => {
+      const userId = args.userId as string;
+      const user = await db.users.findById(userId);
+      
+      return {
+        name: user.name,
+        email: user.email,
+        plan: user.subscription.plan,
+        createdAt: user.createdAt.toISOString(),
+      };
+    },
+    
+    'create-support-ticket': async (args) => {
+      const ticket = await ticketService.create({
+        summary: args.summary as string,
+        priority: args.priority as string,
+      });
+      
+      return {
+        ticketId: ticket.id,
+        estimatedResponse: getEstimatedTime(args.priority),
+      };
+    },
+  },
+});
+```
+
+## Tool Best Practices
+
+### 1. Clear Descriptions
+
+```yaml
+tools:
+  # Good - clear and specific
+  get-user-account:
+    description: >
+      Retrieves the user's account information including name, email,
+      subscription plan, and account creation date. Use this when the
+      user asks about their account or you need to verify their identity.
+  
+  # Avoid - vague
+  get-data:
+    description: Gets some data
+```
+
+### 2. Define Expected Returns
+
+```yaml
+tools:
+  search-products:
+    description: Search products
+    parameters:
+      query: { type: string }
+    returns:
+      products:
+        type: array
+        items:
+          type: object
+          properties:
+            id: { type: string }
+            name: { type: string }
+            price: { type: number }
+      totalCount: { type: number }
+```
+
+### 3. Use Enums for Constrained Values
+
+```yaml
+tools:
+  create-support-ticket:
+    parameters:
+      priority:
+        type: string
+        description: Ticket priority level
+        enum: [low, medium, high, urgent]
+```
+

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

@@ -0,0 +1,251 @@
+---
+title: Handlers
+description: Defining execution handlers with blocks.
+---
+
+# Handlers
+
+Handlers define what happens when a trigger fires. They contain execution blocks that run in sequence.
+
+## Handler Structure
+
+```yaml
+handlers:
+  trigger-name:
+    Block Name:
+      type: block-type
+      # block-specific properties
+    
+    Another Block:
+      type: another-type
+      # ...
+```
+
+Each block has a human-readable name (shown in debug UI) and a type that determines its behavior.
+
+## Block Types
+
+### next-message
+
+Generate a response from the LLM:
+
+```yaml
+handlers:
+  user-message:
+    Respond to user:
+      type: next-message
+      # Uses main conversation thread by default
+      # Display defaults to 'stream'
+```
+
+With options:
+
+```yaml
+Generate summary:
+  type: next-message
+  thread: summary           # Use named thread
+  display: stream           # Show streaming content
+  independent: true         # Don't add to main chat
+  output: SUMMARY           # Store output in variable
+  description: Generating summary  # Shown in UI
+```
+
+### add-message
+
+Add a message to the conversation:
+
+```yaml
+Add user message:
+  type: add-message
+  role: user                # user | assistant | system
+  prompt: user-message      # Reference to prompt file
+  input: [USER_MESSAGE]     # Variables to interpolate
+  display: hidden           # Don't show in UI
+```
+
+For internal directives (LLM sees it, user doesn't):
+
+```yaml
+Add internal directive:
+  type: add-message
+  role: user
+  prompt: ticket-directive
+  input: [TICKET_DETAILS]
+  visible: false            # LLM sees this, user doesn't
+```
+
+### tool-call
+
+Call a tool deterministically:
+
+```yaml
+Create ticket:
+  type: tool-call
+  tool: create-support-ticket
+  input:
+    summary: SUMMARY        # Variable reference
+    priority: medium        # Literal value
+  output: TICKET           # Store result
+```
+
+### set-resource
+
+Update a persistent resource:
+
+```yaml
+Save summary:
+  type: set-resource
+  resource: CONVERSATION_SUMMARY
+  value: SUMMARY            # Variable to save
+  display: name             # Show block name
+```
+
+### start-thread
+
+Create a named conversation thread:
+
+```yaml
+Start summary thread:
+  type: start-thread
+  thread: summary                    # Thread name
+  model: anthropic/claude-sonnet-4-5 # Optional: different model
+  thinking: low                      # Extended reasoning level
+  maxSteps: 1                        # Tool call limit
+  system: escalation-summary         # System prompt
+  input: [COMPANY_NAME]              # Variables for prompt
+```
+
+### serialize-thread
+
+Convert conversation to text:
+
+```yaml
+Serialize conversation:
+  type: serialize-thread
+  thread: main              # Which thread (default: main)
+  format: markdown          # markdown | json
+  output: CONVERSATION_TEXT # Variable to store result
+```
+
+## Display Modes
+
+Every block has a `display` property:
+
+| Mode | Default For | Behavior |
+|------|-------------|----------|
+| `hidden` | add-message | Not shown to user |
+| `name` | set-resource | Shows block name |
+| `description` | tool-call | Shows description |
+| `stream` | next-message | Streams content |
+
+## Complete Example
+
+```yaml
+handlers:
+  user-message:
+    # Add the user's message to conversation
+    Add user message:
+      type: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+      display: hidden
+    
+    # Generate response (LLM may call tools)
+    Respond to user:
+      type: next-message
+      # display: stream (default)
+
+  request-human:
+    # Step 1: Serialize conversation for summary
+    Serialize conversation:
+      type: serialize-thread
+      format: markdown
+      output: CONVERSATION_TEXT
+    
+    # Step 2: Create separate thread for summarization
+    Start summary thread:
+      type: start-thread
+      thread: summary
+      model: anthropic/claude-sonnet-4-5
+      thinking: low
+      system: escalation-summary
+      input: [COMPANY_NAME]
+    
+    # Step 3: Add request to summary thread
+    Add summarize request:
+      type: add-message
+      thread: summary
+      role: user
+      prompt: summarize-request
+      input:
+        - CONVERSATION: CONVERSATION_TEXT
+    
+    # Step 4: Generate summary
+    Generate summary:
+      type: next-message
+      thread: summary
+      display: stream
+      description: Summarizing your conversation
+      independent: true
+      output: SUMMARY
+    
+    # Step 5: Save to resource
+    Save summary:
+      type: set-resource
+      resource: CONVERSATION_SUMMARY
+      value: SUMMARY
+    
+    # Step 6: Create support ticket
+    Create ticket:
+      type: tool-call
+      tool: create-support-ticket
+      input:
+        summary: SUMMARY
+        priority: medium
+      output: TICKET
+    
+    # Step 7: Add directive for response
+    Add directive:
+      type: add-message
+      role: user
+      prompt: ticket-directive
+      input: [TICKET_DETAILS: TICKET]
+      visible: false
+    
+    # Step 8: Respond to user
+    Respond:
+      type: next-message
+```
+
+## Block Input Mapping
+
+Map variables to block inputs:
+
+```yaml
+# Simple list (variable name = prompt variable)
+input: [USER_MESSAGE, COMPANY_NAME]
+
+# Mapping (different names)
+input:
+  - CONVERSATION: CONVERSATION_TEXT  # CONVERSATION in prompt = CONVERSATION_TEXT
+  - TICKET_DETAILS: TICKET
+```
+
+## Independent Blocks
+
+Use `independent: true` for content that shouldn't go to the main chat:
+
+```yaml
+Generate summary:
+  type: next-message
+  thread: summary
+  independent: true   # Output stored in variable, not main chat
+  output: SUMMARY
+```
+
+This is useful for:
+- Background processing
+- Summarization in separate threads
+- Generating content for tools
+

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

@@ -0,0 +1,215 @@
+---
+title: Agent Config
+description: Configuring the agent model and behavior.
+---
+
+# Agent Config
+
+The `agent` section configures the LLM model, system prompt, tools, and behavior.
+
+## Basic Configuration
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system              # References prompts/system.md
+  tools: [get-user-account]   # Available tools
+```
+
+## Configuration Options
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `model` | Yes | Model identifier (provider/model-id) |
+| `system` | Yes | System prompt filename (without .md) |
+| `input` | No | Variables to interpolate in system prompt |
+| `tools` | No | List of tools the LLM can call |
+| `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 |
+
+## Models
+
+Specify models in `provider/model-id` format:
+
+```yaml
+# Anthropic
+agent:
+  model: anthropic/claude-sonnet-4-5   # Claude 4.5 Sonnet
+  model: anthropic/claude-opus-4       # Claude 4 Opus
+
+# OpenAI
+agent:
+  model: openai/gpt-4o                 # GPT-4o
+  model: openai/gpt-4o-mini            # GPT-4o Mini
+  model: openai/o1                     # O1
+  model: openai/o3-mini                # O3 Mini
+```
+
+## System Prompt
+
+The system prompt sets the agent's persona and instructions:
+
+```yaml
+agent:
+  system: system  # Uses prompts/system.md
+  input:
+    - COMPANY_NAME
+    - PRODUCT_NAME
+    - SUPPORT_POLICIES
+```
+
+Example `prompts/system.md`:
+
+```markdown
+You are a friendly support agent for {{COMPANY_NAME}}.
+
+## Your Role
+
+Help users with questions about {{PRODUCT_NAME}}.
+
+## Guidelines
+
+- Be helpful and professional
+- If you can't help, offer to escalate
+- Never share internal information
+
+{{#if SUPPORT_POLICIES}}
+## Support Policies
+
+{{SUPPORT_POLICIES}}
+{{/if}}
+```
+
+## Agentic Mode
+
+Enable multi-step tool calling:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  tools: [get-user-account, search-docs, create-ticket]
+  agentic: true    # LLM can call multiple tools
+  maxSteps: 10     # Limit cycles to prevent runaway
+```
+
+**How it works:**
+1. LLM receives user message
+2. LLM decides to call a tool
+3. Tool executes, result returned to LLM
+4. LLM decides if more tools needed
+5. Repeat until LLM responds or maxSteps reached
+
+## Extended Thinking
+
+Enable extended reasoning for complex tasks:
+
+```yaml
+agent:
+  model: anthropic/claude-sonnet-4-5
+  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 |
+
+Thinking content streams to the UI and can be displayed to users.
+
+## Temperature
+
+Control response randomness:
+
+```yaml
+agent:
+  model: openai/gpt-4o
+  temperature: 0.7  # 0 = deterministic, 2 = creative
+```
+
+**Guidelines:**
+- `0 - 0.3`: Factual, consistent responses
+- `0.4 - 0.7`: Balanced (good default)
+- `0.8 - 1.2`: Creative, varied responses
+- `> 1.2`: Very creative (may be inconsistent)
+
+## Thread-Specific Config
+
+Override config for named threads:
+
+```yaml
+handlers:
+  request-human:
+    Start summary thread:
+      type: start-thread
+      thread: summary
+      model: anthropic/claude-sonnet-4-5  # Different model
+      thinking: low                        # Different thinking
+      maxSteps: 1                          # Limit tool calls
+      system: escalation-summary           # Different prompt
+```
+
+## Full Example
+
+```yaml
+input:
+  COMPANY_NAME: { type: string }
+  PRODUCT_NAME: { type: string }
+  USER_ID: { type: string, optional: true }
+
+resources:
+  CONVERSATION_SUMMARY:
+    default: ""
+
+tools:
+  get-user-account:
+    description: Look up user account
+    parameters:
+      userId: { type: string }
+  
+  search-docs:
+    description: Search help documentation
+    parameters:
+      query: { type: string }
+  
+  create-support-ticket:
+    description: Create a support ticket
+    parameters:
+      summary: { type: string }
+      priority: { type: string, enum: [low, medium, high] }
+
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system
+  input:
+    - COMPANY_NAME
+    - PRODUCT_NAME
+  tools:
+    - get-user-account
+    - search-docs
+    - create-support-ticket
+  agentic: true
+  maxSteps: 10
+  thinking: medium
+
+triggers:
+  user-message:
+    input:
+      USER_MESSAGE: { type: string }
+
+handlers:
+  user-message:
+    Add message:
+      type: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+      display: hidden
+    
+    Respond:
+      type: next-message
+```
+

package/content/04-protocol/_meta.md

@@ -0,0 +1,4 @@
+---
+title: Protocol
+description: Agent protocol reference - how to define agent behavior with YAML.
+---