@octavus/docs 0.0.1

package/content/04-protocol/01-overview.md

@@ -0,0 +1,142 @@
+---
+title: Overview
+description: Introduction to Octavus agent protocols.
+---
+
+# Protocol Overview
+
+Agent protocols define how an AI agent behaves. They're written in YAML and specify inputs, triggers, tools, and execution handlers.
+
+## Why Protocols?
+
+Protocols provide:
+
+- **Declarative definition** — Define behavior, not implementation
+- **Portable agents** — Move agents between projects
+- **Versioning** — Track changes with git
+- **Validation** — Catch errors before runtime
+- **Visualization** — Debug execution flows
+
+## Protocol Structure
+
+```yaml
+# Agent inputs (provided when creating a session)
+input:
+  COMPANY_NAME: { type: string }
+  USER_ID: { type: string, optional: true }
+
+# Persistent resources the agent can read/write
+resources:
+  CONVERSATION_SUMMARY:
+    description: Summary for handoff
+    default: ""
+
+# How the agent can be invoked
+triggers:
+  user-message:
+    input:
+      USER_MESSAGE: { type: string }
+  request-human:
+    description: User clicks "Talk to Human"
+
+# Temporary variables for execution
+variables:
+  - SUMMARY
+  - TICKET
+
+# Tools the agent can use
+tools:
+  get-user-account:
+    description: Looking up your account
+    parameters:
+      userId: { type: string }
+    returns:
+      name: { type: string }
+      email: { type: string }
+
+# Agent configuration (model, tools, etc.)
+agent:
+  model: anthropic/claude-sonnet-4-5
+  system: system            # References prompts/system.md
+  tools: [get-user-account]
+  agentic: true             # Allow multiple tool calls
+  thinking: medium          # Extended reasoning
+
+# What happens when triggers fire
+handlers:
+  user-message:
+    Add user message:
+      type: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+    
+    Respond to user:
+      type: next-message
+```
+
+## File Structure
+
+Each agent is a folder with:
+
+```
+my-agent/
+├── protocol.yaml           # Main logic (required)
+├── settings.json           # Agent metadata (required)
+└── prompts/               # Prompt templates
+    ├── system.md
+    ├── user-message.md
+    └── escalation-summary.md
+```
+
+### settings.json
+
+```json
+{
+  "slug": "my-agent",
+  "name": "My Agent",
+  "description": "What this agent does",
+  "format": "interactive"
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `slug` | Yes | URL-safe identifier (lowercase, digits, dashes) |
+| `name` | Yes | Human-readable name |
+| `description` | No | Brief description |
+| `format` | Yes | `interactive` (chat) or `generation` (background) |
+
+## Naming Conventions
+
+- **Slugs**: `lowercase-with-dashes`
+- **Variables**: `UPPERCASE_SNAKE_CASE`
+- **Prompts**: `lowercase-with-dashes.md`
+- **Tools**: `lowercase-with-dashes`
+- **Triggers**: `lowercase-with-dashes`
+
+## Variables in Prompts
+
+Reference variables with `{{VARIABLE_NAME}}`:
+
+```markdown
+<!-- prompts/system.md -->
+You are a support agent for {{COMPANY_NAME}}.
+
+Help users with their {{PRODUCT_NAME}} questions.
+
+## Support Policies
+
+{{SUPPORT_POLICIES}}
+```
+
+Variables are replaced with their values at runtime. If a variable is not provided, it's replaced with an empty string.
+
+## Next Steps
+
+- [Input & Resources](/docs/protocol/input-resources) — Defining agent inputs
+- [Triggers](/docs/protocol/triggers) — How agents are invoked
+- [Tools](/docs/protocol/tools) — External capabilities
+- [Handlers](/docs/protocol/handlers) — Execution blocks
+- [Agent Config](/docs/protocol/agent-config) — Model and settings
+

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

@@ -0,0 +1,200 @@
+---
+title: Input & Resources
+description: Defining agent inputs and persistent resources.
+---
+
+# Input & Resources
+
+Inputs are provided when creating a session. Resources are persistent state the agent can read and write.
+
+## Input Variables
+
+Define inputs that consumers must (or may) provide:
+
+```yaml
+input:
+  # Required input
+  COMPANY_NAME:
+    type: string
+    description: The company name to use in responses
+
+  # Required input with description
+  PRODUCT_NAME:
+    type: string
+    description: Product being supported
+
+  # Optional input (defaults to "NONE")
+  SUPPORT_POLICIES:
+    type: string
+    description: Company policies for support
+    optional: true
+
+  # Optional input with custom default
+  USER_ID:
+    type: string
+    description: Current user's ID
+    optional: true
+    default: ""
+```
+
+### Input Definition
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Data type: `string`, `number`, `boolean`, `array`, `object` |
+| `description` | No | Describes what this input is for |
+| `optional` | No | If true, consumer doesn't have to provide it |
+| `default` | No | Default value if not provided (defaults to `"NONE"`) |
+
+### Using Inputs
+
+When creating a session, pass input values:
+
+```typescript
+const sessionId = await client.agentSessions.create('support-chat', {
+  COMPANY_NAME: 'Acme Corp',
+  PRODUCT_NAME: 'Widget Pro',
+  SUPPORT_POLICIES: 'Refunds within 30 days...',
+  // USER_ID is optional, not provided
+});
+```
+
+In prompts, reference with `{{INPUT_NAME}}`:
+
+```markdown
+You are a support agent for {{COMPANY_NAME}}.
+```
+
+## Resources
+
+Resources are persistent state that:
+- Survive across triggers
+- Can be read and written by the agent
+- Are synced to the consumer's application
+
+```yaml
+resources:
+  # Simple resource with default
+  CONVERSATION_SUMMARY:
+    description: Running summary of the conversation
+    default: ""
+
+  # Resource with type
+  USER_CONTEXT:
+    type: object
+    description: Cached user information
+    default: {}
+
+  # Read-only resource (agent can read but not write)
+  SYSTEM_CONFIG:
+    type: object
+    description: System configuration
+    readonly: true
+    default:
+      maxRetries: 3
+      timeout: 30000
+```
+
+### Resource Definition
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | No | Data type (defaults to string) |
+| `description` | No | Describes the resource purpose |
+| `default` | No | Initial value |
+| `readonly` | No | If true, agent cannot write to it |
+
+### Writing Resources
+
+Use the `set-resource` block in handlers:
+
+```yaml
+handlers:
+  request-human:
+    # ... generate summary ...
+    
+    Save summary:
+      type: set-resource
+      resource: CONVERSATION_SUMMARY
+      value: SUMMARY  # Variable containing the value
+```
+
+### Resource Events
+
+When a resource is updated, the client SDK receives a `resource-update` event:
+
+```typescript
+useOctavusChat({
+  onResourceUpdate: (name, value) => {
+    if (name === 'CONVERSATION_SUMMARY') {
+      console.log('Summary updated:', value);
+    }
+  },
+});
+```
+
+## Variables
+
+Variables are temporary storage during execution. Unlike resources, they don't persist across triggers.
+
+```yaml
+variables:
+  - SUMMARY
+  - TICKET
+  - CONVERSATION_TEXT
+```
+
+### Using Variables
+
+Set variables as output from blocks:
+
+```yaml
+handlers:
+  request-human:
+    Serialize conversation:
+      type: serialize-thread
+      format: markdown
+      output: CONVERSATION_TEXT  # Stores result in variable
+    
+    Generate summary:
+      type: next-message
+      output: SUMMARY  # LLM output stored in variable
+    
+    Create ticket:
+      type: tool-call
+      tool: create-support-ticket
+      input:
+        summary: SUMMARY  # Use variable as input
+      output: TICKET
+```
+
+## Scoping
+
+| Type | Scope | Persistence |
+|------|-------|-------------|
+| `input` | Session | Read-only, set at creation |
+| `resources` | Session | Read/write, persists |
+| `variables` | Trigger execution | Temporary |
+
+```mermaid
+flowchart TB
+    subgraph Session["Session (persistent)"]
+        direction TB
+        Input["**input** (immutable)<br/>COMPANY_NAME, PRODUCT_NAME"]
+        Resources["**resources** (read/write)<br/>CONVERSATION_SUMMARY"]
+        
+        subgraph T1["Trigger: user-message"]
+            V1["**variables**: { }"]
+        end
+        
+        subgraph T2["Trigger: request-human"]
+            V2["**variables**: { SUMMARY, TICKET }"]
+        end
+    end
+    
+    Input -.-> T1
+    Input -.-> T2
+    Resources -.-> T1
+    Resources -.-> T2
+```
+

package/content/04-protocol/03-triggers.md

@@ -0,0 +1,209 @@
+---
+title: Triggers
+description: Defining how agents are invoked.
+---
+
+# Triggers
+
+Triggers define how an agent can be invoked. Each trigger has a name, optional inputs, and a corresponding handler.
+
+## Trigger Types
+
+### User Message
+
+The most common trigger — when a user sends a chat message:
+
+```yaml
+triggers:
+  user-message:
+    description: User sends a chat message
+    input:
+      USER_MESSAGE:
+        type: string
+        description: The user's message
+```
+
+### User Action
+
+For UI interactions like button clicks:
+
+```yaml
+triggers:
+  request-human:
+    description: User clicks "Talk to Human" button
+    # No input needed - action is implicit
+  
+  submit-feedback:
+    description: User submits feedback form
+    input:
+      RATING:
+        type: number
+        description: Rating from 1-5
+      COMMENT:
+        type: string
+        description: Optional comment
+        optional: true
+```
+
+### API Trigger
+
+Direct invocation through the SDK:
+
+```yaml
+triggers:
+  analyze-document:
+    description: Analyze an uploaded document
+    input:
+      DOCUMENT_URL:
+        type: string
+      ANALYSIS_TYPE:
+        type: string
+        enum: [summary, sentiment, extraction]
+```
+
+## Trigger Definition
+
+```yaml
+triggers:
+  trigger-name:
+    description: Optional description
+    input:
+      VARIABLE_NAME:
+        type: string | number | boolean | array | object
+        description: What this input is for
+        optional: true | false  # defaults to false
+        default: value  # default if optional and not provided
+```
+
+## Invoking Triggers
+
+### From Client SDK
+
+```typescript
+// User message trigger
+await triggerAction('user-message', { 
+  USER_MESSAGE: 'How do I reset my password?' 
+});
+
+// User action trigger (no input)
+await triggerAction('request-human');
+
+// Action with input
+await triggerAction('submit-feedback', { 
+  RATING: 5, 
+  COMMENT: 'Great help!' 
+});
+```
+
+### From Server SDK
+
+```typescript
+const { stream } = session.trigger('user-message', { 
+  USER_MESSAGE: 'Help me with billing' 
+});
+
+const { stream } = session.trigger('request-human');
+```
+
+## Handlers
+
+Each trigger must have a corresponding handler:
+
+```yaml
+triggers:
+  user-message:
+    input:
+      USER_MESSAGE: { type: string }
+
+  request-human:
+    description: Escalate to human support
+
+handlers:
+  user-message:
+    # Blocks executed when user-message is triggered
+    Add user message:
+      type: add-message
+      role: user
+      prompt: user-message
+      input: [USER_MESSAGE]
+    
+    Respond:
+      type: next-message
+
+  request-human:
+    # Blocks executed when request-human is triggered
+    Summarize:
+      type: serialize-thread
+      # ...
+```
+
+## Trigger Input Naming
+
+Trigger inputs use `UPPERCASE_SNAKE_CASE`:
+
+```yaml
+triggers:
+  search-products:
+    input:
+      SEARCH_QUERY: { type: string }
+      MAX_RESULTS: { type: number, optional: true, default: 10 }
+      CATEGORIES: { type: array, optional: true }
+```
+
+## Best Practices
+
+### 1. Use Descriptive Names
+
+```yaml
+# Good
+triggers:
+  user-message:       # Clear - user sends chat message
+  request-human:      # Clear - wants human support
+  cancel-subscription: # Clear - specific action
+
+# Avoid
+triggers:
+  trigger1:           # Unclear
+  msg:                # Too abbreviated
+  do-thing:           # Vague
+```
+
+### 2. Document Triggers
+
+```yaml
+triggers:
+  escalate-to-tier2:
+    description: >
+      Escalate the conversation to tier 2 support.
+      Should be called when the issue cannot be resolved
+      at tier 1 level.
+    input:
+      REASON:
+        type: string
+        description: Why escalation is needed
+```
+
+### 3. Keep Triggers Focused
+
+Each trigger should do one thing:
+
+```yaml
+# Good - focused triggers
+triggers:
+  send-message:
+    input: { MESSAGE: { type: string } }
+  
+  upload-file:
+    input: { FILE_URL: { type: string } }
+  
+  request-callback:
+    input: { PHONE: { type: string } }
+
+# Avoid - overloaded trigger
+triggers:
+  user-action:
+    input:
+      ACTION_TYPE: { type: string }  # "message" | "file" | "callback"
+      PAYLOAD: { type: object }      # Different structure per type
+```
+