Migrating from v1 to v2

This guide covers all breaking changes and new features in Octavus SDK v2.0.0.

Overview

Version 2.0.0 introduces client-side tool execution, allowing tools to run in the browser with support for both automatic execution and interactive user input. This required changes to the transport layer and streaming protocol.

Breaking Changes

HTTP Transport Configuration

The triggerRequest option has been renamed to request and the function signature changed to support both trigger and continuation requests.

Before (v1):

After (v2):

The payload parameter is a discriminated union with type: 'trigger' | 'continue':

• Trigger request: { type: 'trigger', triggerName: string, input?: Record<string, unknown> }
• Continue request: { type: 'continue', executionId: string, toolResults: ToolResult[] }

Server SDK Route Handler

Server-side route handlers should use the new execute() method which handles both triggers and continuations via the request type.

Before (v1):

After (v2):

The SessionRequest type is a discriminated union:

• Trigger: { type: 'trigger', triggerName: string, input?: Record<string, unknown> }
• Continue: { type: 'continue', executionId: string, toolResults: ToolResult[] }

Export Changes

The SDKs no longer use star exports (export * from '@octavus/core'). Instead, they use explicit type exports and value exports. This improves tree-shaking but may require import adjustments.

If you were importing schemas:

Some Zod schemas are no longer re-exported from @octavus/server-sdk. If you need validation schemas, import them directly from @octavus/core:

Type imports remain the same:

Custom Transport Interface

Custom transport implementations must now implement the continueWithToolResults() method:

New ChatStatus Value

The ChatStatus type now includes 'awaiting-input':

Update any status checks that assume only three values.

Stream Event Changes

Two stream events have been modified:

StartEvent and FinishEvent now include executionId:

New FinishReason:

New ClientToolRequestEvent:

New Features

Client-Side Tools

v2 introduces client-side tool execution, allowing tools to run in the browser. This is useful for:

• Accessing browser APIs (geolocation, clipboard, etc.)
• Interactive tools requiring user input (confirmations, forms, selections)
• Tools that need access to client-side state

See the Client Tools guide for full documentation.

Automatic Client Tools

Tools that execute automatically without user interaction:

Interactive Client Tools

Tools that require user interaction before completing:

New Types for Client Tools

pendingClientTools Property

Both OctavusChat and useOctavusChat now expose pendingClientTools:

This allows multiple simultaneous calls to the same tool (e.g., batch confirmations).

Migration Checklist

Use this checklist to ensure you've addressed all breaking changes:

• Update all Octavus packages to v2.0.0
• Update HTTP transport from triggerRequest to request with new signature
• Update server route handlers to use execute() with SessionRequest type
• Update any status checks to handle 'awaiting-input'
• Update custom transport implementations to include continueWithToolResults()
• Review any direct schema imports and update if needed
• (Optional) Add client-side tools for browser-based functionality

Package Versions

All packages should be updated together to ensure compatibility:

Need Help?

If you encounter issues during migration:

• Check the Client Tools documentation for the new features
• Review the HTTP Transport and Server SDK Sessions docs for updated APIs
• Open an issue on GitHub if you find a bug