Server SDK Overview

npm install @octavus/server-sdk

npm install --save-dev @octavus/cli

import { OctavusClient } from '@octavus/server-sdk';

const client = new OctavusClient({
  baseUrl: 'https://octavus.ai',
  apiKey: 'your-api-key',
});

# Sync agent from local files
octavus sync ./agents/support-chat

# Output: Created: support-chat
#         Agent ID: clxyz123abc456

// 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',
});

// Get UI-ready session messages (for session restore)
const session = await client.agentSessions.getMessages(sessionId);

const session = client.agentSessions.attach(sessionId, {
  tools: {
    'get-user-account': async (args) => {
      // Access your database, APIs, etc.
      return await db.users.findById(args.userId);
    },
  },
});

import { toSSEStream } from '@octavus/server-sdk';

// execute() returns an async generator of events
const events = session.execute({
  type: 'trigger',
  triggerName: 'user-message',
  input: { USER_MESSAGE: 'Hello!' },
});

// Convert to SSE stream for HTTP responses
return new Response(toSSEStream(events), {
  headers: { 'Content-Type': 'text/event-stream' },
});

import { Computer } from '@octavus/computer';

const computer = new Computer({
  mcpServers: {
    browser: Computer.stdio('chrome-devtools-mcp', ['--browser-url=...']),
    filesystem: Computer.stdio('@modelcontextprotocol/server-filesystem', [dir]),
    shell: Computer.shell({ cwd: dir, mode: 'unrestricted' }),
  },
});

await computer.start();

const session = client.agentSessions.attach(sessionId, {
  tools: {
    'set-chat-title': async (args) => ({ title: args.title }),
  },
});

session.setDynamicTools(computer);

// Non-streaming: get the output directly
const { output } = await client.workers.generate(agentId, {
  TOPIC: 'AI safety',
});

// Streaming: observe events in real-time
for await (const event of client.workers.execute(agentId, input)) {
  // Handle stream events
}

interface OctavusClientConfig {
  baseUrl: string; // Octavus API URL
  apiKey?: string; // Your API key
  traceModelRequests?: boolean; // Enable model request tracing (default: false)
  maxRetries?: number; // Retries for transient network failures during streaming (default: 2, set to 0 to disable)
}

class OctavusClient {
  readonly agents: AgentsApi;
  readonly agentSessions: AgentSessionsApi;
  readonly workers: WorkersApi;
  readonly files: FilesApi;

  constructor(config: OctavusClientConfig);
}

class AgentSessionsApi {
  // Create a new session
  async create(agentId: string, input?: Record<string, unknown>): Promise<string>;

  // 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;
}

// Full session state (internal format)
interface SessionState {
  id: string;
  agentId: string;
  input: Record<string, unknown>;
  variables: Record<string, unknown>;
  resources: Record<string, unknown>;
  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
}

class AgentSession {
  // Execute a request and stream parsed events
  execute(request: SessionRequest, options?: TriggerOptions): AsyncGenerator<StreamEvent>;

  // Get the session ID
  getSessionId(): string;

  // Register dynamic tools (e.g., pass a Computer or explicit DynamicTool[])
  setDynamicTools(source: ToolProvider | DynamicTool[]): void;
}

type SessionRequest = TriggerRequest | ContinueRequest;

interface TriggerRequest {
  type: 'trigger';
  triggerName: string;
  input?: Record<string, unknown>;
}

interface ContinueRequest {
  type: 'continue';
  executionId: string;
  toolResults: ToolResult[];
}

// Helper to convert events to SSE stream
function toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;

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
  }[];
}