@octavus/docs 0.0.9 → 1.0.0

package/content/02-server-sdk/03-tools.md

@@ -26,10 +26,10 @@ import type { ToolHandlers } from '@octavus/server-sdk';
 const tools: ToolHandlers = {
   'get-user-account': async (args) => {
     const userId = args.userId as string;
-    
+
     // Query your database
     const user = await db.users.findById(userId);
-    
+
     return {
       name: user.name,
       email: user.email,
@@ -37,18 +37,18 @@ const tools: ToolHandlers = {
       createdAt: user.createdAt.toISOString(),
     };
   },
-  
+
   'create-support-ticket': async (args) => {
     const summary = args.summary as string;
     const priority = args.priority as string;
-    
+
     // Create ticket in your system
     const ticket = await ticketService.create({
       summary,
       priority,
       source: 'ai-chat',
     });
-    
+
     return {
       ticketId: ticket.id,
       estimatedResponse: getEstimatedResponse(priority),
@@ -90,7 +90,7 @@ Arguments are passed as a `Record<string, unknown>`. Type-check as needed:
   const query = args.query as string;
   const category = args.category as string | undefined;
   const maxPrice = args.maxPrice as number | undefined;
-  
+
   return await productSearch({ query, category, maxPrice });
 }
 ```
@@ -98,6 +98,7 @@ Arguments are passed as a `Record<string, unknown>`. Type-check as needed:
 ### Return Values
 
 Return any JSON-serializable value. The result is:
+
 1. Sent back to the LLM as context
 2. Stored in session state
 3. Optionally stored in a variable for protocol use
@@ -123,13 +124,13 @@ Throw errors for failures. They're captured and sent to the LLM:
 ```typescript
 'get-user-account': async (args) => {
   const userId = args.userId as string;
-  
+
   const user = await db.users.findById(userId);
-  
+
   if (!user) {
     throw new Error(`User not found: ${userId}`);
   }
-  
+
   return user;
 }
 ```
@@ -151,15 +152,15 @@ sequenceDiagram
     Platform-->>UI: tool-input-start, tool-input-delta
     Platform-->>UI: tool-input-available
     Platform-->>SDK: 2. tool-request (stream pauses)
-    
+
     Note over SDK: 3. Execute handler<br/>tools['get-user']()
-    
+
     SDK-->>UI: 4. tool-output-available
     SDK->>Platform: 5. POST /trigger with results
     Platform->>LLM: 6. Continue with results
     LLM-->>Platform: Response
     Platform-->>UI: text-delta events
-    
+
     Note over LLM,UI: 7. Repeat if more tools needed
 ```
 
@@ -174,7 +175,7 @@ import { toSSEStream } from '@octavus/server-sdk';
 export async function POST(request: Request) {
   const authToken = request.headers.get('Authorization');
   const user = await validateToken(authToken);
-  
+
   const session = client.agentSessions.attach(sessionId, {
     tools: {
       'get-user-account': async (args) => {
@@ -191,7 +192,7 @@ export async function POST(request: Request) {
       },
     },
   });
-  
+
   const events = session.trigger(triggerName, input);
   return new Response(toSSEStream(events));
 }
@@ -217,7 +218,7 @@ export async function POST(request: Request) {
 'external-api-call': async (args) => {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 10000);
-  
+
   try {
     const response = await fetch(url, { signal: controller.signal });
     return await response.json();
@@ -232,14 +233,13 @@ export async function POST(request: Request) {
 ```typescript
 'search-products': async (args) => {
   console.log('Tool call: search-products', { args });
-  
+
   const result = await productSearch(args);
-  
-  console.log('Tool result: search-products', { 
-    resultCount: result.length 
+
+  console.log('Tool result: search-products', {
+    resultCount: result.length
   });
-  
+
   return result;
 }
 ```
-

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

@@ -15,8 +15,8 @@ When you trigger an action, you get an async generator of parsed events:
 import { toSSEStream } from '@octavus/server-sdk';
 
 // trigger() returns an async generator of StreamEvent
-const events = session.trigger('user-message', { 
-  USER_MESSAGE: 'Hello!' 
+const events = session.trigger('user-message', {
+  USER_MESSAGE: 'Hello!',
 });
 
 // For HTTP endpoints, convert to SSE stream
@@ -24,7 +24,7 @@ return new Response(toSSEStream(events), {
   headers: {
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache',
-    'Connection': 'keep-alive',
+    Connection: 'keep-alive',
   },
 });
 
@@ -36,7 +36,7 @@ for await (const event of events) {
 
 ## Event Types
 
-The stream emits various event types. Octavus events align with the [Vercel AI SDK](https://sdk.vercel.ai/) naming conventions where applicable.
+The stream emits various event types for lifecycle, text, reasoning, and tool interactions.
 
 ### Lifecycle Events
 
@@ -55,8 +55,8 @@ The stream emits various event types. Octavus events align with the [Vercel AI S
 // - 'error': Error occurred
 // - 'other': Other reason
 
-// Error event
-{ type: 'error', errorText: 'Something went wrong' }
+// Error event (see Error Handling docs for full structure)
+{ type: 'error', errorType: 'internal_error', message: 'Something went wrong', source: 'platform', retryable: false }
 ```
 
 ### Block Events
@@ -127,7 +127,7 @@ Tool call lifecycle:
 { type: 'tool-output-available', toolCallId: '...', output: { name: 'Demo User', email: '...' } }
 
 // Tool output error (failure)
-{ type: 'tool-output-error', toolCallId: '...', errorText: 'User not found' }
+{ type: 'tool-output-error', toolCallId: '...', error: 'User not found' }
 ```
 
 ### Resource Events
@@ -142,12 +142,12 @@ Resource updates:
 
 Each block/tool specifies how it should appear to users:
 
-| Mode | Description |
-|------|-------------|
-| `hidden` | Not shown to user (background work) |
-| `name` | Shows block/tool name |
-| `description` | Shows description text |
-| `stream` | Streams content to chat |
+| Mode          | Description                         |
+| ------------- | ----------------------------------- |
+| `hidden`      | Not shown to user (background work) |
+| `name`        | Shows block/tool name               |
+| `description` | Shows description text              |
+| `stream`      | Streams content to chat             |
 
 **Note**: Hidden events are filtered before reaching the client SDK. Your frontend only sees user-facing events.
 
@@ -181,16 +181,46 @@ type StreamEvent =
   | ToolRequestEvent;
 ```
 
-## Error Recovery
+## Error Events
 
-The SDK handles common error scenarios:
+Errors are emitted as structured events with type classification:
 
 ```typescript
-// Network errors are caught and emitted
-{ type: 'error', errorText: 'Network request failed' }
+{
+  type: 'error',
+  errorType: 'rate_limit_error',     // Error classification
+  message: 'Rate limit exceeded',     // Human-readable message
+  source: 'provider',                 // 'platform' | 'provider' | 'tool'
+  retryable: true,                    // Whether retry is possible
+  retryAfter: 60,                     // Seconds to wait (rate limits)
+  code: 'ANTHROPIC_429',              // Machine-readable code
+  provider: {                         // Provider details (when applicable)
+    name: 'anthropic',
+    statusCode: 429,
+    requestId: 'req_...'
+  }
+}
+```
+
+### Error Types
+
+| Type                   | Description           |
+| ---------------------- | --------------------- |
+| `rate_limit_error`     | Too many requests     |
+| `authentication_error` | Invalid API key       |
+| `provider_error`       | LLM provider issue    |
+| `provider_overloaded`  | Provider at capacity  |
+| `tool_error`           | Tool execution failed |
+| `internal_error`       | Platform error        |
 
-// Tool errors are captured per-tool
-{ type: 'tool-output-error', toolCallId: '...', errorText: 'Handler threw exception' }
+### Tool Errors
 
-// The stream always ends with either 'finish' or 'error'
+Tool errors are captured per-tool and don't stop the stream:
+
+```typescript
+{ type: 'tool-output-error', toolCallId: '...', error: 'Handler threw exception' }
 ```
+
+The stream always ends with either `finish` or `error`.
+
+For client-side error handling patterns, see [Error Handling](/docs/client-sdk/error-handling).

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

@@ -0,0 +1,247 @@
+---
+title: CLI
+description: Command-line interface for validating and syncing agent definitions.
+---
+
+# Octavus CLI
+
+The `@octavus/cli` package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform.
+
+**Current version:** `{{VERSION:@octavus/cli}}`
+
+## Installation
+
+```bash
+npm install --save-dev @octavus/cli
+```
+
+## Configuration
+
+The CLI requires an API key with agent management permissions.
+
+### Environment Variables
+
+| Variable              | Description                                             |
+| --------------------- | ------------------------------------------------------- |
+| `OCTAVUS_CLI_API_KEY` | API key with agent management permissions (recommended) |
+| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set               |
+| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`              |
+
+### Two-Key Strategy (Recommended)
+
+For production deployments, use separate API keys:
+
+```bash
+# CI/CD or .env.local (not committed)
+OCTAVUS_CLI_API_KEY=oct_sk_...  # Agent management permissions
+
+# Production .env
+OCTAVUS_API_KEY=oct_sk_...      # Session-only permissions
+```
+
+This ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.
+
+### Multiple Environments
+
+Use separate Octavus projects for staging and production, each with their own API keys. The `--env` flag lets you load different environment files:
+
+```bash
+# Local development (default: .env)
+octavus sync ./agents/my-agent
+
+# Staging project
+octavus --env .env.staging sync ./agents/my-agent
+
+# Production project
+octavus --env .env.production sync ./agents/my-agent
+```
+
+Example environment files:
+
+```bash
+# .env.staging (syncs to your staging project)
+OCTAVUS_CLI_API_KEY=oct_sk_staging_project_key...
+
+# .env.production (syncs to your production project)
+OCTAVUS_CLI_API_KEY=oct_sk_production_project_key...
+```
+
+Each project has its own agents, so you'll get different agent IDs per environment.
+
+## Global Options
+
+| Option         | Description                                             |
+| -------------- | ------------------------------------------------------- |
+| `--env <file>` | Load environment from a specific file (default: `.env`) |
+| `--help`       | Show help                                               |
+| `--version`    | Show version                                            |
+
+## Commands
+
+### `octavus sync <path>`
+
+Sync an agent definition to the platform. Creates the agent if it doesn't exist, or updates it if it does.
+
+```bash
+octavus sync ./agents/my-agent
+```
+
+**Options:**
+
+- `--json` — Output as JSON (for CI/CD parsing)
+- `--quiet` — Suppress non-essential output
+
+**Example output:**
+
+```
+ℹ Reading agent from ./agents/my-agent...
+ℹ Syncing support-chat...
+✓ Created: support-chat
+  Agent ID: clxyz123abc456
+```
+
+### `octavus validate <path>`
+
+Validate an agent definition without saving. Useful for CI/CD pipelines.
+
+```bash
+octavus validate ./agents/my-agent
+```
+
+**Exit codes:**
+
+- `0` — Validation passed
+- `1` — Validation errors
+- `2` — Configuration errors (missing API key, etc.)
+
+### `octavus list`
+
+List all agents in your project.
+
+```bash
+octavus list
+```
+
+**Example output:**
+
+```
+SLUG                  NAME                            FORMAT        ID
+────────────────────────────────────────────────────────────────────────────
+support-chat          Support Chat Agent              interactive   clxyz123abc456
+
+1 agent(s)
+```
+
+### `octavus get <slug>`
+
+Get details about a specific agent by its slug.
+
+```bash
+octavus get support-chat
+```
+
+## Agent Directory Structure
+
+The CLI expects agent definitions in a specific directory structure:
+
+```
+my-agent/
+├── settings.json     # Required: Agent metadata
+├── protocol.yaml     # Required: Agent protocol
+└── prompts/          # Optional: Prompt templates
+    ├── system.md
+    └── user-message.md
+```
+
+### settings.json
+
+```json
+{
+  "slug": "my-agent",
+  "name": "My Agent",
+  "description": "A helpful assistant",
+  "format": "interactive"
+}
+```
+
+### protocol.yaml
+
+See the [Protocol documentation](/docs/protocol/overview) for details on protocol syntax.
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Validate and Sync Agents
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'agents/**'
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - run: npm install
+
+      - name: Validate agent
+        run: npx octavus validate ./agents/support-chat
+        env:
+          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}
+
+      - name: Sync agent
+        run: npx octavus sync ./agents/support-chat
+        env:
+          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}
+```
+
+### Package.json Scripts
+
+Add sync scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "agents:validate": "octavus validate ./agents/my-agent",
+    "agents:sync": "octavus sync ./agents/my-agent"
+  },
+  "devDependencies": {
+    "@octavus/cli": "^0.1.0"
+  }
+}
+```
+
+## Workflow
+
+The recommended workflow for managing agents:
+
+1. **Define agent locally** — Create `settings.json`, `protocol.yaml`, and prompts
+2. **Validate** — Run `octavus validate ./my-agent` to check for errors
+3. **Sync** — Run `octavus sync ./my-agent` to push to platform
+4. **Store agent ID** — Save the output ID in an environment variable
+5. **Use in app** — Read the ID from env and pass to `client.agentSessions.create()`
+
+```bash
+# After syncing: octavus sync ./agents/support-chat
+# Output: Agent ID: clxyz123abc456
+
+# Add to your .env file
+OCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456
+```
+
+```typescript
+const agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;
+
+const sessionId = await client.agentSessions.create(agentId, {
+  COMPANY_NAME: 'Acme Corp',
+});
+```