@octavus/docs 0.0.5 → 0.0.7

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

@@ -88,6 +88,6 @@ sequenceDiagram
 
 - [Quick Start](/docs/getting-started/quickstart) — Get your first agent running in minutes
 - [Server SDK](/docs/server-sdk/overview) — Learn about backend integration
-- [Client SDK](/docs/client-sdk/overview) — Build chat interfaces with React
+- [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

@@ -21,8 +21,8 @@ Install the Octavus SDKs in your project:
 # Server SDK for backend
 npm install @octavus/server-sdk
 
-# Client SDK for frontend (React)
-npm install @octavus/client-sdk
+# React bindings for frontend
+npm install @octavus/react
 ```
 
 ## Backend Setup
@@ -118,14 +118,14 @@ export async function POST(request: Request) {
 
 ### 1. Create a Chat Component
 
-Use the `useOctavusChat` hook to build a chat interface:
+Use the `useOctavusChat` hook with the HTTP transport:
 
 ```tsx
 // components/chat.tsx
 'use client';
 
-import { useOctavusChat, type UIMessage } from '@octavus/client-sdk';
-import { useState } from 'react';
+import { useState, useMemo } from 'react';
+import { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';
 
 interface ChatProps {
   sessionId: string;
@@ -134,15 +134,21 @@ interface ChatProps {
 export function Chat({ sessionId }: ChatProps) {
   const [inputValue, setInputValue] = useState('');
 
-  const { messages, status, error, send } = useOctavusChat({
-    onTrigger: async (triggerName, input) => {
-      return fetch('/api/trigger', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ sessionId, triggerName, input }),
-      });
-    },
-  });
+  // Create a stable transport instance
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { messages, status, error, send } = useOctavusChat({ transport });
 
   const isStreaming = status === 'streaming';
 
@@ -154,9 +160,11 @@ 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 (
@@ -208,7 +216,7 @@ function MessageBubble({ message }: { message: UIMessage }) {
           }
           return null;
         })}
-        
+
         {/* Streaming indicator */}
         {message.status === 'streaming' && (
           <span className="inline-block w-2 h-4 bg-gray-400 animate-pulse ml-1" />

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

@@ -34,13 +34,13 @@ Create and manage agent sessions:
 
 ```typescript
 // Create a new session
-const sessionId = await client.agentSessions.create('support-chat', {
+const sessionId = await client.agentSessions.create('agent-id', {
   COMPANY_NAME: 'Acme Corp',
   PRODUCT_NAME: 'Widget Pro',
 });
 
-// Get session state
-const state = await client.agentSessions.get(sessionId);
+// Get UI-ready session messages (for session restore)
+const session = await client.agentSessions.getMessages(sessionId);
 ```
 
 ### Tool Handlers
@@ -63,8 +63,8 @@ const session = client.agentSessions.attach(sessionId, {
 All responses stream in real-time:
 
 ```typescript
-const { stream } = session.trigger('user-message', { 
-  USER_MESSAGE: 'Hello!' 
+const { stream } = session.trigger('user-message', {
+  USER_MESSAGE: 'Hello!',
 });
 
 // Use as a streaming response
@@ -88,7 +88,7 @@ interface OctavusClientConfig {
 class OctavusClient {
   readonly agents: AgentsApi;
   readonly agentSessions: AgentSessionsApi;
-  
+
   constructor(config: OctavusClientConfig);
 }
 ```
@@ -101,24 +101,35 @@ Manages agent sessions.
 class AgentSessionsApi {
   // Create a new session
   async create(agentId: string, input?: Record<string, unknown>): Promise<string>;
-  
-  // Get session state (includes UI-ready messages)
-  async get(sessionId: string): Promise<UISessionState>;
-  
+
+  // Get full session state (for debugging/internal use)
+  async get(sessionId: string): Promise<SessionState>;
+
+  // Get UI-ready messages (for client display)
+  async getMessages(sessionId: string): Promise<UISessionState>;
+
   // Attach to a session for triggering
   attach(sessionId: string, options?: SessionAttachOptions): AgentSession;
 }
 
-interface UISessionState {
+// Full session state (internal format)
+interface SessionState {
   id: string;
   agentId: string;
   input: Record<string, unknown>;
   variables: Record<string, unknown>;
   resources: Record<string, unknown>;
-  messages: UIMessage[];  // UI-ready messages for session restore
+  messages: ChatMessage[];  // Internal message format
   createdAt: string;
   updatedAt: string;
 }
+
+// UI-ready session state
+interface UISessionState {
+  sessionId: string;
+  agentId: string;
+  messages: UIMessage[];  // UI-ready messages for frontend
+}
 ```
 
 ### AgentSession
@@ -132,7 +143,7 @@ class AgentSession {
     triggerName: string,
     input?: Record<string, unknown>
   ): { stream: ReadableStream<Uint8Array> };
-  
+
   // Get the session ID
   getSessionId(): string;
 }

package/content/03-client-sdk/01-overview.md

@@ -1,39 +1,77 @@
 ---
 title: Overview
-description: Introduction to the Octavus Client SDK for building chat interfaces.
+description: Introduction to the Octavus Client SDKs for building chat interfaces.
 ---
 
 # Client SDK Overview
 
-The `@octavus/client-sdk` package provides React hooks for building chat interfaces with Octavus agents. It handles streaming, message state, and real-time updates.
+Octavus provides two packages for frontend integration:
 
-**Current version:** `{{VERSION:@octavus/client-sdk}}`
+| Package | Purpose | Use When |
+|---------|---------|----------|
+| `@octavus/react` | React hooks and bindings | Building React applications |
+| `@octavus/client-sdk` | Framework-agnostic core | Using Vue, Svelte, vanilla JS, or custom integrations |
+
+**Most users should install `@octavus/react`** — it includes everything from `@octavus/client-sdk` plus React-specific hooks.
 
 ## Installation
 
+### React Applications
+
+```bash
+npm install @octavus/react
+```
+
+**Current version:** `{{VERSION:@octavus/react}}`
+
+### Other Frameworks
+
 ```bash
 npm install @octavus/client-sdk
 ```
 
-## Basic Usage
+**Current version:** `{{VERSION:@octavus/client-sdk}}`
+
+## Transport Pattern
+
+The Client SDK uses a **transport abstraction** to handle communication with your backend. This gives you flexibility in how events are delivered:
+
+| Transport | Use Case |
+|-----------|----------|
+| `createHttpTransport` | HTTP/SSE (Next.js, Express, etc.) |
+| `createSocketTransport` | WebSocket, SockJS, or other socket protocols |
+
+## React Usage
+
+The `useOctavusChat` hook provides state management and streaming for React applications:
 
 ```tsx
-import { useOctavusChat, type UIMessage } from '@octavus/client-sdk';
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';
 
 function Chat({ sessionId }: { sessionId: string }) {
-  const { messages, status, send } = useOctavusChat({
-    onTrigger: async (triggerName, input) => {
-      return fetch(`/api/trigger`, {
-        method: 'POST',
-        body: JSON.stringify({ sessionId, triggerName, input }),
-      });
-    },
-  });
+  // Create a stable transport instance (memoized on sessionId)
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { messages, status, send } = useOctavusChat({ transport });
 
   const sendMessage = async (text: string) => {
-    await send('user-message', { USER_MESSAGE: text }, {
-      userMessage: { content: text },
-    });
+    await send(
+      'user-message',
+      { USER_MESSAGE: text },
+      { userMessage: { content: text } },
+    );
   };
 
   return (
@@ -59,6 +97,42 @@ function MessageBubble({ message }: { message: UIMessage }) {
 }
 ```
 
+## Framework-Agnostic Usage
+
+The `OctavusChat` class can be used with any framework or vanilla JavaScript:
+
+```typescript
+import { OctavusChat, createHttpTransport } from '@octavus/client-sdk';
+
+const transport = createHttpTransport({
+  triggerRequest: (triggerName, input) =>
+    fetch('/api/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, triggerName, input }),
+    }),
+});
+
+const chat = new OctavusChat({ transport });
+
+// Subscribe to state changes
+const unsubscribe = chat.subscribe(() => {
+  console.log('Messages:', chat.messages);
+  console.log('Status:', chat.status);
+  // Update your UI here
+});
+
+// Send a message
+await chat.send(
+  'user-message',
+  { USER_MESSAGE: 'Hello' },
+  { userMessage: { content: 'Hello' } },
+);
+
+// Cleanup when done
+unsubscribe();
+```
+
 ## Key Features
 
 ### Unified Send Function
@@ -66,12 +140,14 @@ function MessageBubble({ message }: { message: UIMessage }) {
 The `send` function handles both user message display and agent triggering in one call:
 
 ```tsx
-const { send } = useOctavusChat({...});
+const { send } = useOctavusChat({ transport });
 
 // Add user message to UI and trigger agent
-await send('user-message', { USER_MESSAGE: text }, {
-  userMessage: { content: text },
-});
+await send(
+  'user-message',
+  { USER_MESSAGE: text },
+  { userMessage: { content: text } },
+);
 
 // Trigger without adding a user message (e.g., button click)
 await send('request-human');
@@ -82,7 +158,7 @@ await send('request-human');
 Messages contain ordered `parts` for rich content:
 
 ```tsx
-const { messages } = useOctavusChat({...});
+const { messages } = useOctavusChat({ transport });
 
 // Each message has typed parts
 message.parts.map((part) => {
@@ -98,7 +174,7 @@ message.parts.map((part) => {
 ### Status Tracking
 
 ```tsx
-const { status } = useOctavusChat({...});
+const { status } = useOctavusChat({ transport });
 
 // status: 'idle' | 'streaming' | 'error'
 ```
@@ -106,26 +182,26 @@ const { status } = useOctavusChat({...});
 ### Stop Streaming
 
 ```tsx
-const { stop } = useOctavusChat({...});
+const { stop } = useOctavusChat({ transport });
 
 // Stop current stream and finalize message
 stop();
 ```
 
-## Hook Reference
+## Hook Reference (React)
 
 ### useOctavusChat
 
 ```typescript
-function useOctavusChat(options: UseOctavusChatOptions): UseOctavusChatReturn;
+function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;
+
+interface OctavusChatOptions {
+  // Required: Transport for streaming events
+  transport: Transport;
 
-interface UseOctavusChatOptions {
-  // Required: Function that calls your backend trigger endpoint
-  onTrigger: TriggerFunction;
-  
   // Optional: Pre-populate with existing messages (session restore)
   initialMessages?: UIMessage[];
-  
+
   // Optional: Callbacks
   onError?: (error: Error) => void;
   onFinish?: () => void;
@@ -137,7 +213,7 @@ interface UseOctavusChatReturn {
   messages: UIMessage[];
   status: ChatStatus;  // 'idle' | 'streaming' | 'error'
   error: Error | null;
-  
+
   // Actions
   send: (
     triggerName: string,
@@ -147,18 +223,78 @@ interface UseOctavusChatReturn {
   stop: () => void;
 }
 
-type TriggerFunction = (
-  triggerName: string,
-  input?: Record<string, unknown>,
-) => Promise<Response>;
-
 interface UserMessageInput {
   content: string;
 }
 ```
 
+## Transport Reference
+
+### createHttpTransport
+
+Creates an HTTP/SSE transport using native `fetch()`:
+
+```typescript
+import { createHttpTransport } from '@octavus/react';
+
+const transport = createHttpTransport({
+  triggerRequest: (triggerName, input) =>
+    fetch('/api/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, triggerName, input }),
+    }),
+});
+```
+
+### createSocketTransport
+
+Creates a WebSocket/SockJS transport for real-time connections:
+
+```typescript
+import { createSocketTransport } from '@octavus/react';
+
+const transport = createSocketTransport({
+  connect: () =>
+    new Promise((resolve, reject) => {
+      const ws = new WebSocket(`wss://api.example.com/stream?sessionId=${sessionId}`);
+      ws.onopen = () => resolve(ws);
+      ws.onerror = () => reject(new Error('Connection failed'));
+    }),
+});
+```
+
+For detailed WebSocket/SockJS usage including custom events, reconnection patterns, and server-side implementation, see [Socket Transport](/docs/client-sdk/socket-transport).
+
+## Class Reference (Framework-Agnostic)
+
+### OctavusChat
+
+```typescript
+class OctavusChat {
+  constructor(options: OctavusChatOptions);
+
+  // State (read-only)
+  readonly messages: UIMessage[];
+  readonly status: ChatStatus;
+  readonly error: Error | null;
+
+  // Actions
+  send(
+    triggerName: string,
+    input?: Record<string, unknown>,
+    options?: { userMessage?: UserMessageInput }
+  ): Promise<void>;
+  stop(): void;
+
+  // Subscription
+  subscribe(callback: () => void): () => void;  // Returns unsubscribe function
+}
+```
+
 ## Next Steps
 
 - [Messages](/docs/client-sdk/messages) — Working with message state
 - [Streaming](/docs/client-sdk/streaming) — Building streaming UIs
-- [Execution Blocks](/docs/client-sdk/execution-blocks) — Showing agent progress
+- [Operations](/docs/client-sdk/execution-blocks) — Showing agent progress
+- [Socket Transport](/docs/client-sdk/socket-transport) — WebSocket and SockJS integration

package/content/03-client-sdk/02-messages.md

@@ -24,10 +24,10 @@ interface UIMessage {
 Messages contain ordered `parts` that preserve content ordering:
 
 ```typescript
-type UIMessagePart = 
-  | UITextPart 
-  | UIReasoningPart 
-  | UIToolCallPart 
+type UIMessagePart =
+  | UITextPart
+  | UIReasoningPart
+  | UIToolCallPart
   | UIOperationPart;
 
 // Text content
@@ -73,13 +73,35 @@ interface UIOperationPart {
 ## Sending Messages
 
 ```tsx
-const { send } = useOctavusChat({...});
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
 
-async function handleSend(text: string) {
-  // Add user message to UI and trigger agent
-  await send('user-message', { USER_MESSAGE: text }, {
-    userMessage: { content: text },
-  });
+  const { send } = useOctavusChat({ transport });
+
+  async function handleSend(text: string) {
+    // Add user message to UI and trigger agent
+    await send(
+      'user-message',
+      { USER_MESSAGE: text },
+      { userMessage: { content: text } },
+    );
+  }
+
+  // ...
 }
 ```
 
@@ -121,7 +143,7 @@ function MessageBubble({ message }: { message: UIMessage }) {
 ### Rendering Parts
 
 ```tsx
-import { isOtherThread, type UIMessagePart } from '@octavus/client-sdk';
+import { isOtherThread, type UIMessagePart } from '@octavus/react';
 
 function PartRenderer({ part }: { part: UIMessagePart }) {
   // Check if part belongs to a named thread (e.g., "summary")
@@ -180,7 +202,7 @@ function TextPart({ part }: { part: UITextPart }) {
 Content from named threads (like "summary") is identified by the `thread` property. Use the `isOtherThread` helper:
 
 ```tsx
-import { isOtherThread } from '@octavus/client-sdk';
+import { isOtherThread } from '@octavus/react';
 
 function PartRenderer({ part }: { part: UIMessagePart }) {
   if (isOtherThread(part)) {
@@ -201,24 +223,54 @@ function PartRenderer({ part }: { part: UIMessagePart }) {
 
 ## Session Restore
 
-When restoring a session, pass existing messages:
+When restoring a session, fetch messages from your backend and pass them to the hook:
 
 ```tsx
-// Fetch session state from your backend
-const sessionState = await fetchSession(sessionId);
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport, type UIMessage } from '@octavus/react';
 
-// Pass to hook
-const { messages } = useOctavusChat({
-  initialMessages: sessionState.messages,
-  onTrigger: ...
-});
+interface ChatProps {
+  sessionId: string;
+  initialMessages: UIMessage[];
+}
+
+function Chat({ sessionId, initialMessages }: ChatProps) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  // Pass existing messages to restore the conversation
+  const { messages } = useOctavusChat({
+    transport,
+    initialMessages,
+  });
+
+  // ...
+}
+```
+
+On your backend, use `agentSessions.getMessages()` to fetch UI-ready messages:
+
+```typescript
+// Server-side
+const session = await client.agentSessions.getMessages(sessionId);
+// session.messages is UIMessage[] ready for the client
 ```
 
 ## Callbacks
 
 ```tsx
 useOctavusChat({
-  onTrigger: ...,
+  transport,
   onFinish: () => {
     console.log('Stream completed');
     // Scroll to bottom, play sound, etc.