@octavus/docs 0.0.9 → 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# @octavus/docs
+
+Documentation content package for Octavus SDKs.
+
+## Installation
+
+```bash
+npm install @octavus/docs
+```
+
+## Overview
+
+This package provides the documentation content for Octavus SDKs as structured data with full-text search capabilities. It's designed for:
+
+- Embedding documentation in your application
+- Building custom documentation sites
+- Providing AI-friendly documentation access
+
+## Usage
+
+### Get Documentation Content
+
+```typescript
+import { getDocBySlug, getDocSlugs, getDocSections } from '@octavus/docs';
+
+// Get all sections with their docs
+const sections = getDocSections();
+// [{ slug: 'getting-started', title: 'Getting Started', docs: [...] }, ...]
+
+// Get all doc slugs (for static generation)
+const slugs = getDocSlugs();
+// ['getting-started/introduction', 'getting-started/quickstart', ...]
+
+// Get a specific doc by slug
+const doc = getDocBySlug('getting-started/introduction');
+// { slug, section, title, description, content, excerpt }
+```
+
+### Full Content Access
+
+```typescript
+import { getAllDocs, getDocsData } from '@octavus/docs/content';
+
+// Get all docs as array
+const docs = getAllDocs();
+
+// Get all data (docs + sections)
+const { docs, sections } = getDocsData();
+```
+
+### Search
+
+```typescript
+import { searchDocs } from '@octavus/docs/search';
+
+// Search documentation
+const results = searchDocs('streaming events', 10);
+// [{ slug, title, section, excerpt, score }, ...]
+```
+
+## Data Types
+
+```typescript
+interface Doc {
+  slug: string; // 'getting-started/introduction'
+  section: string; // 'getting-started'
+  title: string; // 'Introduction'
+  description: string; // 'Learn about Octavus...'
+  content: string; // Full markdown content
+  excerpt: string; // First ~200 chars, plain text
+}
+
+interface DocSection {
+  slug: string;
+  title: string;
+  description: string;
+  order: number;
+  docs: Doc[];
+}
+
+interface SearchResult {
+  slug: string;
+  title: string;
+  section: string;
+  excerpt: string;
+  score: number;
+}
+```
+
+## Content Structure
+
+Documentation is organized by section:
+
+- **Getting Started** - Introduction and quickstart guides
+- **Server SDK** - Server-side integration with `@octavus/server-sdk`
+- **Client SDK** - Client-side integration with `@octavus/client-sdk`
+- **Protocol** - Agent protocol definition language
+- **API Reference** - REST API documentation
+- **Examples** - Full application examples
+
+## Use with Static Site Generators
+
+```typescript
+// Next.js generateStaticParams example
+export function generateStaticParams() {
+  return getDocSlugs().map((slug) => ({
+    slug: slug.split('/'),
+  }));
+}
+
+export default function DocPage({ params }) {
+  const doc = getDocBySlug(params.slug.join('/'));
+  if (!doc) notFound();
+
+  return <MarkdownRenderer content={doc.content} />;
+}
+```
+
+## Related Packages
+
+- [`@octavus/server-sdk`](https://www.npmjs.com/package/@octavus/server-sdk) - Server-side SDK
+- [`@octavus/client-sdk`](https://www.npmjs.com/package/@octavus/client-sdk) - Client-side SDK
+- [`@octavus/react`](https://www.npmjs.com/package/@octavus/react) - React hooks
+
+## License
+
+MIT

package/content/01-getting-started/01-introduction.md

@@ -20,6 +20,7 @@ Building and managing AI agents is complex. Developers face challenges with:
 Octavus solves these problems by providing:
 
 - A **protocol-based approach** to defining agent behavior
+- **Agent Preview** for testing agents directly in the platform
 - **Server and client SDKs** for easy integration
 - **Built-in streaming** support for real-time responses
 - **Tool execution** that runs on your servers with your data
@@ -73,12 +74,12 @@ sequenceDiagram
     API->>LLM: 2. Execute protocol
     LLM-->>API: Response
     API-->>App: 3. Stream events
-    
+
     Note over App: Tool request received
     API-->>App: 4. Tool request
     Note over App: 5. Execute tool locally
     App->>API: 6. Return results
-    
+
     API->>LLM: 7. Continue
     LLM-->>API: Response
     API-->>App: 8. Stream response
@@ -90,4 +91,3 @@ sequenceDiagram
 - [Server SDK](/docs/server-sdk/overview) — Learn about backend integration
 - [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React (or other frameworks)
 - [Protocol Reference](/docs/protocol/overview) — Deep dive into agent protocols
-

package/content/01-getting-started/02-quickstart.md

@@ -13,6 +13,17 @@ This guide will walk you through integrating Octavus into your application in un
 - An Octavus account with API key
 - A Next.js application (or any Node.js backend)
 
+## Test Your Agent First
+
+Before integrating with SDKs, use **Agent Preview** to test your agent directly in the platform:
+
+1. Open your agent in the platform at `octavus.ai/agents/[agentId]`
+2. Click the **Preview** tab
+3. Configure session inputs and tool mock responses
+4. Start a conversation to test agent behavior
+
+Agent Preview supports all trigger types, file attachments, tool mocking, and real-time streaming. This is the fastest way to iterate on your agent logic before writing any integration code.
+
 ## Installation
 
 Install the Octavus SDKs in your project:
@@ -50,22 +61,41 @@ Create an API endpoint that creates sessions and returns the session ID:
 import { NextResponse } from 'next/server';
 import { octavus } from '@/lib/octavus';
 
-export async function POST(request: Request) {
-  const { agentSlug, input } = await request.json();
+// Agent ID - get from platform or CLI (see below)
+const SUPPORT_AGENT_ID = process.env.OCTAVUS_SUPPORT_AGENT_ID!;
 
-  // Look up agent by slug to get its ID
-  const agent = await octavus.agents.getBySlug(agentSlug);
-  if (!agent) {
-    return NextResponse.json({ error: 'Agent not found' }, { status: 404 });
-  }
+export async function POST(request: Request) {
+  const { input } = await request.json();
 
   // Create a new session using the agent ID
-  const sessionId = await octavus.agentSessions.create(agent.id, input);
+  const sessionId = await octavus.agentSessions.create(SUPPORT_AGENT_ID, input);
 
   return NextResponse.json({ sessionId });
 }
 ```
 
+### Getting Your Agent ID
+
+There are two ways to create and manage agents:
+
+**Option 1: Platform UI (Recommended for getting started)**
+
+1. Go to [octavus.ai](https://octavus.ai) and create an agent in the web editor
+2. Copy the agent ID from the URL (e.g., `octavus.ai/agents/clxyz123abc456`)
+3. Add it to your `.env.local`: `OCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456`
+
+**Option 2: Local Development with CLI**
+
+For version-controlled agent definitions, use the [Octavus CLI](/docs/server-sdk/cli):
+
+```bash
+npm install --save-dev @octavus/cli
+octavus sync ./agents/support-chat
+# Output: Agent ID: clxyz123abc456
+```
+
+The CLI approach is better for teams and CI/CD pipelines where you want agent definitions in your repository.
+
 ### 3. Create a Trigger Endpoint
 
 Create an endpoint that handles triggers and streams responses:
@@ -161,11 +191,7 @@ export function Chat({ sessionId }: ChatProps) {
     setInputValue('');
 
     // Add user message and trigger in one call
-    await send(
-      'user-message',
-      { USER_MESSAGE: message },
-      { userMessage: { content: message } },
-    );
+    await send('user-message', { USER_MESSAGE: message }, { userMessage: { content: message } });
   };
 
   return (
@@ -207,9 +233,7 @@ function MessageBubble({ message }: { message: UIMessage }) {
   return (
     <div className={`flex ${isUser ? 'justify-end' : 'justify-start'}`}>
       <div
-        className={`p-3 rounded-lg max-w-md ${
-          isUser ? 'bg-blue-500 text-white' : 'bg-gray-100'
-        }`}
+        className={`p-3 rounded-lg max-w-md ${isUser ? 'bg-blue-500 text-white' : 'bg-gray-100'}`}
       >
         {message.parts.map((part, i) => {
           if (part.type === 'text') {
@@ -246,7 +270,6 @@ export default function ChatPage() {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          agentSlug: 'support-chat',
           input: {
             COMPANY_NAME: 'Acme Corp',
             PRODUCT_NAME: 'Widget Pro',

package/content/02-server-sdk/01-overview.md

@@ -15,6 +15,12 @@ The `@octavus/server-sdk` package provides a Node.js SDK for integrating Octavus
 npm install @octavus/server-sdk
 ```
 
+For agent management (sync, validate), install the CLI as a dev dependency:
+
+```bash
+npm install --save-dev @octavus/cli
+```
+
 ## Basic Usage
 
 ```typescript
@@ -28,13 +34,25 @@ const client = new OctavusClient({
 
 ## Key Features
 
+### Agent Management
+
+Agent definitions are managed via the CLI. See the [CLI documentation](/docs/server-sdk/cli) for details.
+
+```bash
+# Sync agent from local files
+octavus sync ./agents/support-chat
+
+# Output: Created: support-chat
+#         Agent ID: clxyz123abc456
+```
+
 ### Session Management
 
-Create and manage agent sessions:
+Create and manage agent sessions using the agent ID:
 
 ```typescript
-// Create a new session
-const sessionId = await client.agentSessions.create('agent-id', {
+// Create a new session (use agent ID from CLI sync)
+const sessionId = await client.agentSessions.create('clxyz123abc456', {
   COMPANY_NAME: 'Acme Corp',
   PRODUCT_NAME: 'Widget Pro',
 });
@@ -84,13 +102,14 @@ The main entry point for interacting with Octavus.
 
 ```typescript
 interface OctavusClientConfig {
-  baseUrl: string;  // Octavus API URL
-  apiKey?: string;  // Your API key
+  baseUrl: string; // Octavus API URL
+  apiKey?: string; // Your API key
 }
 
 class OctavusClient {
   readonly agents: AgentsApi;
   readonly agentSessions: AgentSessionsApi;
+  readonly files: FilesApi;
 
   constructor(config: OctavusClientConfig);
 }
@@ -122,7 +141,7 @@ interface SessionState {
   input: Record<string, unknown>;
   variables: Record<string, unknown>;
   resources: Record<string, unknown>;
-  messages: ChatMessage[];  // Internal message format
+  messages: ChatMessage[]; // Internal message format
   createdAt: string;
   updatedAt: string;
 }
@@ -131,7 +150,7 @@ interface SessionState {
 interface UISessionState {
   sessionId: string;
   agentId: string;
-  messages: UIMessage[];  // UI-ready messages for frontend
+  messages: UIMessage[]; // UI-ready messages for frontend
 }
 ```
 
@@ -142,10 +161,7 @@ Handles triggering and streaming for a specific session.
 ```typescript
 class AgentSession {
   // Trigger an action and stream parsed events
-  trigger(
-    triggerName: string,
-    input?: Record<string, unknown>
-  ): AsyncGenerator<StreamEvent>;
+  trigger(triggerName: string, input?: Record<string, unknown>): AsyncGenerator<StreamEvent>;
 
   // Get the session ID
   getSessionId(): string;
@@ -155,6 +171,33 @@ class AgentSession {
 function toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;
 ```
 
+### FilesApi
+
+Handles file uploads for sessions.
+
+```typescript
+class FilesApi {
+  // Get presigned URLs for file uploads
+  async getUploadUrls(sessionId: string, files: FileUploadRequest[]): Promise<UploadUrlsResponse>;
+}
+
+interface FileUploadRequest {
+  filename: string;
+  mediaType: string;
+  size: number;
+}
+
+interface UploadUrlsResponse {
+  files: {
+    id: string; // File ID for references
+    uploadUrl: string; // PUT to this URL
+    downloadUrl: string; // GET URL after upload
+  }[];
+}
+```
+
+The client uploads files directly to S3 using the presigned upload URL. See [File Uploads](/docs/client-sdk/file-uploads) for the full integration pattern.
+
 ## Next Steps
 
 - [Sessions](/docs/server-sdk/sessions) — Deep dive into session management

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

@@ -39,7 +39,7 @@ const session = await client.agentSessions.getMessages(sessionId);
 console.log({
   sessionId: session.sessionId,
   agentId: session.agentId,
-  messages: session.messages.length,  // UIMessage[] ready for frontend
+  messages: session.messages.length, // UIMessage[] ready for frontend
 });
 ```
 
@@ -51,7 +51,7 @@ The returned messages can be passed directly to the client SDK's `initialMessage
 interface UISessionState {
   sessionId: string;
   agentId: string;
-  messages: UIMessage[];  // UI-ready conversation history
+  messages: UIMessage[]; // UI-ready conversation history
 }
 ```
 
@@ -65,7 +65,7 @@ const state = await client.agentSessions.get(sessionId);
 console.log({
   id: state.id,
   agentId: state.agentId,
-  messages: state.messages.length,  // ChatMessage[] (internal format)
+  messages: state.messages.length, // ChatMessage[] (internal format)
   resources: state.resources,
   variables: state.variables,
   createdAt: state.createdAt,
@@ -108,6 +108,19 @@ return new Response(toSSEStream(events), {
 });
 ```
 
+### Stop Support
+
+Pass an abort signal to allow clients to stop generation:
+
+```typescript
+// In your API route handler
+const events = session.trigger(triggerName, input, {
+  signal: request.signal, // Forward the client's abort signal
+});
+```
+
+When the client aborts the request, the signal propagates through to the LLM provider, stopping generation immediately. Any partial content is preserved.
+
 ## Session Lifecycle
 
 ```mermaid
@@ -118,44 +131,182 @@ flowchart TD
     C --> D[4. RETRIEVE]
     D --> C
     C --> E[5. EXPIRE]
+    E --> F{6. RESTORE?}
+    F -->|Yes| C
+    F -->|No| A
 
     A -.- A1["`**client.agentSessions.create()**
     Returns sessionId
     Initializes state`"]
-    
+
     B -.- B1["`**client.agentSessions.attach()**
     Configure tool handlers
     Configure resource watchers`"]
-    
+
     C -.- C1["`**session.trigger()**
     Execute handler
     Stream events
     Update state`"]
-    
+
     D -.- D1["`**client.agentSessions.getMessages()**
     Get UI-ready messages
-    Restore conversation`"]
-    
+    Check session status`"]
+
     E -.- E1["`Sessions expire after
     24 hours (configurable)`"]
+
+    F -.- F1["`**client.agentSessions.restore()**
+    Restore from stored messages
+    Or create new session`"]
+```
+
+## Session Expiration
+
+Sessions expire after a period of inactivity (default: 24 hours). When you call `getMessages()` or `get()`, the response includes a `status` field:
+
+```typescript
+const result = await client.agentSessions.getMessages(sessionId);
+
+if (result.status === 'expired') {
+  // Session has expired - restore or create new
+  console.log('Session expired:', result.sessionId);
+} else {
+  // Session is active
+  console.log('Messages:', result.messages.length);
+}
+```
+
+### Response Types
+
+| Status    | Type                  | Description                                                   |
+| --------- | --------------------- | ------------------------------------------------------------- |
+| `active`  | `UISessionState`      | Session is active, includes `messages` array                  |
+| `expired` | `ExpiredSessionState` | Session expired, includes `sessionId`, `agentId`, `createdAt` |
+
+## Persisting Chat History
+
+To enable session restoration, store the chat messages in your own database after each interaction:
+
+```typescript
+// After each trigger completes, save messages
+const result = await client.agentSessions.getMessages(sessionId);
+
+if (result.status === 'active') {
+  // Store in your database
+  await db.chats.update({
+    where: { id: chatId },
+    data: {
+      sessionId: result.sessionId,
+      messages: result.messages, // Store UIMessage[] as JSON
+    },
+  });
+}
 ```
 
+> **Best Practice**: Store the full `UIMessage[]` array. This preserves all message parts (text, tool calls, files, etc.) needed for accurate restoration.
+
 ## Restoring Sessions
 
-When a user returns to your app, restore their session:
+When a user returns to your app:
 
 ```typescript
-// On page load
-const session = await client.agentSessions.getMessages(sessionId);
+// 1. Load stored data from your database
+const chat = await db.chats.findUnique({ where: { id: chatId } });
+
+// 2. Check if session is still active
+const result = await client.agentSessions.getMessages(chat.sessionId);
+
+if (result.status === 'active') {
+  // Session is active - use it directly
+  return {
+    sessionId: result.sessionId,
+    messages: result.messages,
+  };
+}
+
+// 3. Session expired - restore from stored messages
+if (chat.messages && chat.messages.length > 0) {
+  const restored = await client.agentSessions.restore(
+    chat.sessionId,
+    chat.messages,
+    { COMPANY_NAME: 'Acme Corp' }, // Optional: same input as create()
+  );
+
+  if (restored.restored) {
+    // Session restored successfully
+    return {
+      sessionId: restored.sessionId,
+      messages: chat.messages,
+    };
+  }
+}
+
+// 4. Cannot restore - create new session
+const newSessionId = await client.agentSessions.create('support-chat', {
+  COMPANY_NAME: 'Acme Corp',
+});
 
-// Pass messages to frontend - they're already UI-ready
 return {
-  sessionId: session.sessionId,
-  messages: session.messages,  // UIMessage[] with parts
+  sessionId: newSessionId,
+  messages: [],
 };
 ```
 
-The `messages` array contains `UIMessage` objects with properly structured `parts`, enabling direct use with the client SDK's `initialMessages` option.
+### Restore Response
+
+```typescript
+interface RestoreSessionResult {
+  sessionId: string;
+  restored: boolean; // true if restored, false if session was already active
+}
+```
+
+## Complete Example
+
+Here's a complete session management flow:
+
+```typescript
+import { OctavusClient } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+async function getOrCreateSession(chatId: string, agentId: string, input: Record<string, unknown>) {
+  // Load existing chat data
+  const chat = await db.chats.findUnique({ where: { id: chatId } });
+
+  if (chat?.sessionId) {
+    // Check session status
+    const result = await client.agentSessions.getMessages(chat.sessionId);
+
+    if (result.status === 'active') {
+      return { sessionId: result.sessionId, messages: result.messages };
+    }
+
+    // Try to restore expired session
+    if (chat.messages?.length > 0) {
+      const restored = await client.agentSessions.restore(chat.sessionId, chat.messages, input);
+      if (restored.restored) {
+        return { sessionId: restored.sessionId, messages: chat.messages };
+      }
+    }
+  }
+
+  // Create new session
+  const sessionId = await client.agentSessions.create(agentId, input);
+
+  // Save to database
+  await db.chats.upsert({
+    where: { id: chatId },
+    create: { id: chatId, sessionId, messages: [] },
+    update: { sessionId, messages: [] },
+  });
+
+  return { sessionId, messages: [] };
+}
+```
 
 ## Error Handling