@octavus/docs 0.0.9 → 1.0.0

package/content/05-api-reference/01-overview.md

@@ -49,34 +49,34 @@ All responses are JSON. Success responses return the data directly (not wrapped
 
 ## HTTP Status Codes
 
-| Code | Description |
-|------|-------------|
-| 200 | Success |
-| 201 | Created |
-| 400 | Bad Request - Invalid parameters |
-| 401 | Unauthorized - Missing or invalid API key |
-| 403 | Forbidden - Insufficient permissions |
-| 404 | Not Found |
-| 500 | Internal Server Error |
+| Code | Description                               |
+| ---- | ----------------------------------------- |
+| 200  | Success                                   |
+| 201  | Created                                   |
+| 400  | Bad Request - Invalid parameters          |
+| 401  | Unauthorized - Missing or invalid API key |
+| 403  | Forbidden - Insufficient permissions      |
+| 404  | Not Found                                 |
+| 500  | Internal Server Error                     |
 
 ## Endpoints Overview
 
 ### Agents
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/agents` | List all agents |
-| GET | `/api/agents/:id` | Get agent by ID |
-| POST | `/api/agents` | Create agent |
-| PATCH | `/api/agents/:id` | Update agent |
+| Method | Endpoint          | Description     |
+| ------ | ----------------- | --------------- |
+| GET    | `/api/agents`     | List all agents |
+| GET    | `/api/agents/:id` | Get agent by ID |
+| POST   | `/api/agents`     | Create agent    |
+| PATCH  | `/api/agents/:id` | Update agent    |
 
 ### Sessions
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | `/api/agent-sessions` | Create session |
-| GET | `/api/agent-sessions/:id` | Get session state |
-| POST | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |
+| Method | Endpoint                          | Description           |
+| ------ | --------------------------------- | --------------------- |
+| POST   | `/api/agent-sessions`             | Create session        |
+| GET    | `/api/agent-sessions/:id`         | Get session state     |
+| POST   | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |
 
 ## Streaming
 
@@ -120,4 +120,3 @@ We recommend using our SDKs instead of calling the API directly:
 - **Client SDK**: `@octavus/client-sdk` - For other frontend frameworks
 
 The SDKs handle authentication, streaming, and tool execution automatically.
-

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

@@ -28,12 +28,12 @@ POST /api/agent-sessions
 }
 ```
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `agentId` | string | Yes | Agent ID (the `id` field, not `slug`) |
-| `input` | object | No | Input variables for the agent |
+| Field     | Type   | Required | Description                           |
+| --------- | ------ | -------- | ------------------------------------- |
+| `agentId` | string | Yes      | Agent ID (the `id` field, not `slug`) |
+| `input`   | object | No       | Input variables for the agent         |
 
-> To get the agent ID, copy it from the platform URL, use [Get Agent by slug](/docs/api-reference/agents#get-agent) (`GET /api/agents/:slug?by=slug`), or the SDK's `agents.getBySlug()` method.
+> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.
 
 ### Response
 
@@ -60,20 +60,27 @@ curl -X POST https://octavus.ai/api/agent-sessions \
 
 ## Get Session
 
-Retrieve session state including UI-ready messages and resources.
+Retrieve session state. Returns UI-ready messages for active sessions, or expiration info for expired sessions.
 
 ```
 GET /api/agent-sessions/:sessionId
 ```
 
-### Response
+### Query Parameters
+
+| Parameter | Type   | Description                                          |
+| --------- | ------ | ---------------------------------------------------- |
+| `format`  | string | Optional. Use `format=ui` for UI-ready messages only |
+
+### Response (Active Session)
 
-The response includes `UIMessage` objects that can be passed directly to the client SDK's `initialMessages` option:
+When the session is active, the response includes `UIMessage` objects:
 
 ```json
 {
   "id": "cm5xyz123abc456def",
   "agentId": "cm5xvz7k80001abcd",
+  "status": "active",
   "input": {
     "COMPANY_NAME": "Acme Corp",
     "PRODUCT_NAME": "Widget Pro"
@@ -86,9 +93,7 @@ The response includes `UIMessage` objects that can be passed directly to the cli
     {
       "id": "1702345800000-xyz789a",
       "role": "user",
-      "parts": [
-        { "type": "text", "text": "How do I reset my password?", "status": "done" }
-      ],
+      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],
       "status": "done",
       "createdAt": "2024-01-15T10:30:00.000Z"
     },
@@ -107,6 +112,23 @@ The response includes `UIMessage` objects that can be passed directly to the cli
 }
 ```
 
+### Response (Expired Session)
+
+When the session has expired, the response indicates the expiration status:
+
+```json
+{
+  "status": "expired",
+  "sessionId": "cm5xyz123abc456def",
+  "agentId": "cm5xvz7k80001abcd",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+
+Use the [Restore Session](#restore-session) endpoint to restore an expired session from stored messages.
+
+````
+
 ### UIMessage Parts
 
 Messages contain typed `parts` that preserve content ordering:
@@ -117,14 +139,77 @@ Messages contain typed `parts` that preserve content ordering:
 | `reasoning` | Extended reasoning with `text` and `status` fields |
 | `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |
 | `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |
+| `file` | File attachment with `id`, `mediaType`, `url`, `filename`, `size` |
+| `source` | Source reference with `sourceType`, `id`, `url`, `title` |
+| `object` | Structured output with `id`, `typeName`, `object`, `status` |
 
 ### Example
 
 ```bash
 curl https://octavus.ai/api/agent-sessions/:sessionId \
   -H "Authorization: Bearer YOUR_API_KEY"
+````
+
+## Restore Session
+
+Restore an expired session from stored messages. This allows you to continue a conversation after the server-side state has expired.
+
+```
+POST /api/agent-sessions/:sessionId/restore
+```
+
+### Request Body
+
+```json
+{
+  "messages": [
+    {
+      "id": "1702345800000-xyz789a",
+      "role": "user",
+      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],
+      "status": "done",
+      "createdAt": "2024-01-15T10:30:00.000Z"
+    }
+  ],
+  "input": {
+    "COMPANY_NAME": "Acme Corp"
+  }
+}
+```
+
+| Field      | Type        | Required | Description                                                    |
+| ---------- | ----------- | -------- | -------------------------------------------------------------- |
+| `messages` | UIMessage[] | Yes      | Previously stored chat history                                 |
+| `input`    | object      | No       | Session input for system prompt interpolation (same as create) |
+
+### Response
+
+```json
+{
+  "sessionId": "cm5xyz123abc456def",
+  "restored": true
+}
 ```
 
+| Field       | Type    | Description                                                             |
+| ----------- | ------- | ----------------------------------------------------------------------- |
+| `sessionId` | string  | The session ID                                                          |
+| `restored`  | boolean | `true` if restored from messages, `false` if session was already active |
+
+### Example
+
+```bash
+curl -X POST https://octavus.ai/api/agent-sessions/:sessionId/restore \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [...],
+    "input": { "COMPANY_NAME": "Acme Corp" }
+  }'
+```
+
+> **Note**: Store the `UIMessage[]` array after each interaction to enable restoration. The restore endpoint reconstructs the conversation state from these messages.
+
 ## Trigger Session
 
 Execute a trigger on a session. Returns a Server-Sent Events stream.
@@ -145,11 +230,11 @@ POST /api/agent-sessions/:sessionId/trigger
 }
 ```
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `triggerName` | string | Yes | Name of the trigger to execute |
-| `input` | object | No | Input variables for the trigger |
-| `toolResults` | array | No | Tool results for continuation (handled by SDK) |
+| Field         | Type   | Required | Description                                    |
+| ------------- | ------ | -------- | ---------------------------------------------- |
+| `triggerName` | string | Yes      | Name of the trigger to execute                 |
+| `input`       | object | No       | Input variables for the trigger                |
+| `toolResults` | array  | No       | Tool results for continuation (handled by SDK) |
 
 ### Response
 
@@ -193,27 +278,28 @@ data: [DONE]
 
 ### Event Types
 
-| Event | Description |
-|-------|-------------|
-| `start` | Stream started |
-| `finish` | Execution complete |
-| `error` | Error occurred |
-| `block-start` | Execution block started |
-| `block-end` | Execution block completed |
-| `text-start` | Text generation started |
-| `text-delta` | Incremental text content |
-| `text-end` | Text generation ended |
-| `reasoning-start` | Extended reasoning started |
-| `reasoning-delta` | Reasoning content |
-| `reasoning-end` | Extended reasoning ended |
-| `tool-input-start` | Tool call initiated |
-| `tool-input-delta` | Tool arguments streaming |
-| `tool-input-end` | Tool arguments streaming ended |
-| `tool-input-available` | Tool input complete |
-| `tool-output-available` | Tool completed with result |
-| `tool-output-error` | Tool failed |
-| `tool-request` | Platform requesting tool execution |
-| `resource-update` | Resource value changed |
+| Event                   | Description                        |
+| ----------------------- | ---------------------------------- |
+| `start`                 | Stream started                     |
+| `finish`                | Execution complete                 |
+| `error`                 | Error occurred                     |
+| `block-start`           | Execution block started            |
+| `block-end`             | Execution block completed          |
+| `text-start`            | Text generation started            |
+| `text-delta`            | Incremental text content           |
+| `text-end`              | Text generation ended              |
+| `reasoning-start`       | Extended reasoning started         |
+| `reasoning-delta`       | Reasoning content                  |
+| `reasoning-end`         | Extended reasoning ended           |
+| `tool-input-start`      | Tool call initiated                |
+| `tool-input-delta`      | Tool arguments streaming           |
+| `tool-input-end`        | Tool arguments streaming ended     |
+| `tool-input-available`  | Tool input complete                |
+| `tool-output-available` | Tool completed with result         |
+| `tool-output-error`     | Tool failed                        |
+| `tool-request`          | Platform requesting tool execution |
+| `file-available`        | File ready for display/download    |
+| `resource-update`       | Resource value changed             |
 
 ### Example
 
@@ -249,3 +335,72 @@ When the agent calls external tools, you'll receive a `tool-request` event. Exec
 ```
 
 The Server SDK handles this continuation pattern automatically.
+
+## Upload URLs
+
+Get presigned URLs for file uploads. Files are uploaded directly to S3.
+
+```
+POST /api/files/upload-urls
+```
+
+### Request Body
+
+```json
+{
+  "sessionId": "cm5xyz123abc456def",
+  "files": [
+    {
+      "filename": "photo.jpg",
+      "mediaType": "image/jpeg",
+      "size": 102400
+    }
+  ]
+}
+```
+
+| Field               | Type   | Required | Description                         |
+| ------------------- | ------ | -------- | ----------------------------------- |
+| `sessionId`         | string | Yes      | Session ID to associate files with  |
+| `files`             | array  | Yes      | Array of file metadata (1-20 files) |
+| `files[].filename`  | string | Yes      | Original filename                   |
+| `files[].mediaType` | string | Yes      | MIME type (e.g., `image/png`)       |
+| `files[].size`      | number | Yes      | File size in bytes                  |
+
+### Response
+
+```json
+{
+  "files": [
+    {
+      "id": "file-abc123",
+      "uploadUrl": "https://s3.amazonaws.com/bucket/key?...",
+      "downloadUrl": "https://s3.amazonaws.com/bucket/key?..."
+    }
+  ]
+}
+```
+
+### Upload Flow
+
+1. Request upload URLs from the platform
+2. PUT file content to `uploadUrl` with `Content-Type` header
+3. Use `downloadUrl` as the `url` in `FileReference`
+4. Include `FileReference` in trigger input
+
+### Supported Types
+
+| Category  | Media Types                                                          |
+| --------- | -------------------------------------------------------------------- |
+| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |
+| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |
+
+### Limits
+
+| Limit                 | Value      |
+| --------------------- | ---------- |
+| Max file size         | 10 MB      |
+| Max total per request | 50 MB      |
+| Max files per request | 20         |
+| Upload URL expiry     | 15 minutes |
+| Download URL expiry   | 24 hours   |

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

@@ -42,11 +42,10 @@ curl https://octavus.ai/api/agents \
 
 ## Get Agent
 
-Get a single agent by ID or slug.
+Get a single agent by ID.
 
 ```
 GET /api/agents/:id
-GET /api/agents/:slug?by=slug
 ```
 
 ### Response
@@ -77,15 +76,12 @@ GET /api/agents/:slug?by=slug
 ### Example
 
 ```bash
-# By ID
 curl https://octavus.ai/api/agents/:agentId \
   -H "Authorization: Bearer YOUR_API_KEY"
-
-# By slug
-curl "https://octavus.ai/api/agents/:slug?by=slug" \
-  -H "Authorization: Bearer YOUR_API_KEY"
 ```
 
+> **Tip:** You can also view and edit agents directly in the [platform](https://octavus.ai), or use the [CLI](/docs/server-sdk/cli) (`octavus list`) for local workflows.
+
 ## Create Agent
 
 Create a new agent.
@@ -114,14 +110,14 @@ POST /api/agents
 }
 ```
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `settings.slug` | string | Yes | URL-safe identifier |
-| `settings.name` | string | Yes | Display name |
-| `settings.description` | string | No | Agent description |
-| `settings.format` | string | Yes | `interactive` or `generation` |
-| `protocol` | string | Yes | YAML protocol definition |
-| `prompts` | array | Yes | Prompt files |
+| Field                  | Type   | Required | Description               |
+| ---------------------- | ------ | -------- | ------------------------- |
+| `settings.slug`        | string | Yes      | URL-safe identifier       |
+| `settings.name`        | string | Yes      | Display name              |
+| `settings.description` | string | No       | Agent description         |
+| `settings.format`      | string | Yes      | `interactive` or `worker` |
+| `protocol`             | string | Yes      | YAML protocol definition  |
+| `prompts`              | array  | Yes      | Prompt files              |
 
 ### Response
 
@@ -157,7 +153,6 @@ Update an existing agent.
 
 ```
 PATCH /api/agents/:id
-PATCH /api/agents/:slug?by=slug
 ```
 
 ### Request Body
@@ -196,29 +191,22 @@ curl -X PATCH https://octavus.ai/api/agents/:agentId \
   }'
 ```
 
-## Sync Agent
+## Creating and Managing Agents
 
-The Server SDK provides a `sync` method that creates or updates an agent:
+There are two ways to manage agents:
 
-```typescript
-const { agentId, created } = await client.agents.sync({
-  settings: {
-    slug: 'support-chat',
-    name: 'Support Chat',
-    format: 'interactive',
-  },
-  protocol: protocolYaml,
-  prompts: [
-    { name: 'system', content: systemPrompt },
-  ],
-});
-
-if (created) {
-  console.log('Created new agent:', agentId);
-} else {
-  console.log('Updated existing agent:', agentId);
-}
+### Platform UI
+
+Create and edit agents directly at [octavus.ai](https://octavus.ai). The web editor provides real-time validation and is the easiest way to get started. Copy the agent ID from the URL to use in your application.
+
+### CLI (Local Development)
+
+For version-controlled agent definitions, use the [Octavus CLI](/docs/server-sdk/cli):
+
+```bash
+octavus sync ./agents/support-chat
 ```
 
-This is useful for CI/CD pipelines to deploy agent updates.
+This creates the agent if it doesn't exist, or updates it if it does. The CLI outputs the agent ID which you should store in an environment variable.
 
+For CI/CD integration, see the [CLI documentation](/docs/server-sdk/cli#cicd-integration).

package/content/06-examples/01-overview.md

@@ -9,19 +9,21 @@ This section provides complete integration examples for different architectures.
 
 ## Available Examples
 
-| Example | Transport | Best For |
-|---------|-----------|----------|
-| [Next.js Chat](/docs/examples/nextjs-chat) | HTTP/SSE | Next.js, Remix, standard web apps |
-| [Socket Chat](/docs/examples/socket-chat) | SockJS | Meteor, Phoenix, real-time apps |
+| Example                                    | Transport | Best For                          |
+| ------------------------------------------ | --------- | --------------------------------- |
+| [Next.js Chat](/docs/examples/nextjs-chat) | HTTP/SSE  | Next.js, Remix, standard web apps |
+| [Socket Chat](/docs/examples/socket-chat)  | SockJS    | Meteor, Phoenix, real-time apps   |
 
 ## Choosing a Transport
 
 **Use HTTP Transport when:**
+
 - Building with Next.js, Remix, or similar frameworks
 - You want the simplest integration
 - Deploying to serverless (Vercel, Netlify, etc.)
 
 **Use Socket Transport when:**
+
 - Using Meteor, Phoenix, or socket-based frameworks
 - Need custom real-time events (typing indicators, presence)
 - Behind proxies that don't support SSE well

package/content/06-examples/02-nextjs-chat.md

@@ -10,6 +10,7 @@ This example builds a support chat interface using Next.js App Router with HTTP/
 ## What You're Building
 
 A chat interface that:
+
 - Creates sessions server-side
 - Streams AI responses in real-time
 - Handles tool calls on your server
@@ -56,7 +57,26 @@ export const octavus = new OctavusClient({
 });
 ```
 
-## Step 4: Create Session Endpoint
+## Step 4: Create Upload URLs Endpoint (Optional)
+
+If your agent supports file uploads (images, documents), create an endpoint to get presigned URLs:
+
+```typescript
+// app/api/upload-urls/route.ts
+import { NextResponse } from 'next/server';
+import { octavus } from '@/lib/octavus';
+
+export async function POST(request: Request) {
+  const { sessionId, files } = await request.json();
+
+  // Get presigned URLs from Octavus
+  const result = await octavus.files.getUploadUrls(sessionId, files);
+
+  return NextResponse.json(result);
+}
+```
+
+## Step 5: Create Session Endpoint
 
 Sessions hold conversation state. Create one when the user opens the chat:
 
@@ -84,7 +104,7 @@ const sessionId = await octavus.agentSessions.create(agentId, {
 });
 ```
 
-## Step 5: Create Trigger Endpoint
+## Step 6: Create Trigger Endpoint
 
 Triggers execute agent actions. The `user-message` trigger is the most common:
 
@@ -141,7 +161,7 @@ export async function POST(request: Request) {
 
 **Protocol Note:** Tool names and arguments are defined in your agent's protocol YAML. The tool handlers here must match those definitions.
 
-## Step 6: Build the Chat Component
+## Step 7: Build the Chat Component
 
 ```tsx
 // components/Chat.tsx
@@ -182,11 +202,7 @@ export function Chat({ sessionId }: ChatProps) {
 
     // Send triggers the 'user-message' action
     // The third argument adds the user message to the UI
-    await send(
-      'user-message',
-      { USER_MESSAGE: message },
-      { userMessage: { content: message } },
-    );
+    await send('user-message', { USER_MESSAGE: message }, { userMessage: { content: message } });
   };
 
   return (
@@ -194,15 +210,10 @@ export function Chat({ sessionId }: ChatProps) {
       {/* Messages */}
       <div className="flex-1 overflow-y-auto p-4 space-y-4">
         {messages.map((msg) => (
-          <div
-            key={msg.id}
-            className={msg.role === 'user' ? 'text-right' : 'text-left'}
-          >
+          <div key={msg.id} className={msg.role === 'user' ? 'text-right' : 'text-left'}>
             <div
               className={`inline-block p-3 rounded-lg ${
-                msg.role === 'user'
-                  ? 'bg-blue-500 text-white'
-                  : 'bg-gray-100'
+                msg.role === 'user' ? 'bg-blue-500 text-white' : 'bg-gray-100'
               }`}
             >
               {msg.parts.map((part, i) => {
@@ -248,7 +259,7 @@ export function Chat({ sessionId }: ChatProps) {
 }
 ```
 
-## Step 7: Create the Page
+## Step 8: Create the Page
 
 ```tsx
 // app/chat/page.tsx
@@ -307,7 +318,7 @@ The `send()` call maps directly:
 
 ```typescript
 await send(
-  'user-message',           // trigger name
+  'user-message', // trigger name
   { USER_MESSAGE: message }, // trigger inputs
   { userMessage: { content: message } },
 );
@@ -340,4 +351,3 @@ Tool handlers receive the parameters as `args`:
 - [Protocol Overview](/docs/protocol/overview) — Define agent behavior
 - [Messages](/docs/client-sdk/messages) — Rich message rendering
 - [Streaming](/docs/client-sdk/streaming) — Advanced streaming UI
-