@octavus/docs 0.0.8 → 1.0.0

package/content/03-client-sdk/09-error-handling.md

@@ -0,0 +1,274 @@
+---
+title: Error Handling
+description: Handling errors in streaming responses with structured error types.
+---
+
+# Error Handling
+
+Octavus provides structured error handling across all transports. Errors are categorized by type and source, enabling you to build appropriate UI responses and monitoring.
+
+## Error Types
+
+The `onError` callback receives an `OctavusError` with structured information:
+
+```typescript
+import { useOctavusChat, type OctavusError } from '@octavus/react';
+
+const { error, status } = useOctavusChat({
+  transport,
+  onError: (err: OctavusError) => {
+    console.error('Chat error:', {
+      type: err.errorType, // Error classification
+      message: err.message, // Human-readable message
+      source: err.source, // Where the error originated
+      retryable: err.retryable, // Can be retried
+      retryAfter: err.retryAfter, // Seconds to wait (rate limits)
+      code: err.code, // Machine-readable code
+      provider: err.provider, // Provider details (if applicable)
+    });
+  },
+});
+```
+
+## Error Classification
+
+### Error Types
+
+| Type                   | Description           | Typical Response    |
+| ---------------------- | --------------------- | ------------------- |
+| `rate_limit_error`     | Too many requests     | Show retry timer    |
+| `quota_exceeded_error` | Usage quota exceeded  | Show upgrade prompt |
+| `authentication_error` | Invalid API key       | Check configuration |
+| `permission_error`     | No access to resource | Check permissions   |
+| `validation_error`     | Invalid request       | Fix request data    |
+| `provider_error`       | LLM provider issue    | Retry or show error |
+| `provider_overloaded`  | Provider at capacity  | Retry with backoff  |
+| `provider_timeout`     | Provider timed out    | Retry               |
+| `tool_error`           | Tool execution failed | Show tool error     |
+| `internal_error`       | Platform error        | Show generic error  |
+
+### Error Sources
+
+| Source     | Description                                  |
+| ---------- | -------------------------------------------- |
+| `platform` | Octavus platform error                       |
+| `provider` | LLM provider error (OpenAI, Anthropic, etc.) |
+| `tool`     | Tool execution error                         |
+| `client`   | Client-side error (network, parsing)         |
+
+## Type Guards
+
+Use type guards to handle specific error types:
+
+```typescript
+import {
+  useOctavusChat,
+  isRateLimitError,
+  isAuthenticationError,
+  isProviderError,
+  isToolError,
+  isRetryableError,
+} from '@octavus/react';
+
+const { error } = useOctavusChat({
+  transport,
+  onError: (err) => {
+    if (isRateLimitError(err)) {
+      // Show countdown timer
+      showRetryTimer(err.retryAfter ?? 60);
+      return;
+    }
+
+    if (isAuthenticationError(err)) {
+      // Configuration issue - shouldn't happen in production
+      reportConfigError(err);
+      return;
+    }
+
+    if (isProviderError(err)) {
+      // LLM service issue
+      showProviderError(err.provider?.name ?? 'AI service');
+      return;
+    }
+
+    if (isToolError(err)) {
+      // Tool failed - already shown inline
+      return;
+    }
+
+    if (isRetryableError(err)) {
+      // Generic retryable error
+      showRetryButton();
+      return;
+    }
+
+    // Non-retryable error
+    showGenericError(err.message);
+  },
+});
+```
+
+## Provider Error Details
+
+When errors come from LLM providers, additional details are available:
+
+```typescript
+if (isProviderError(error) && error.provider) {
+  console.log({
+    name: error.provider.name, // 'anthropic', 'openai', 'google'
+    model: error.provider.model, // Model that caused the error
+    statusCode: error.provider.statusCode, // HTTP status code
+    errorType: error.provider.errorType, // Provider's error type
+    requestId: error.provider.requestId, // For support tickets
+  });
+}
+```
+
+## Building Error UI
+
+```tsx
+import {
+  useOctavusChat,
+  isRateLimitError,
+  isAuthenticationError,
+  isProviderError,
+} from '@octavus/react';
+
+function Chat() {
+  const { error, status } = useOctavusChat({ transport });
+
+  return (
+    <div>
+      {/* Error display */}
+      {error && (
+        <div className="bg-red-50 border border-red-200 rounded-lg p-4">
+          <div className="font-medium text-red-800">{getErrorTitle(error)}</div>
+          <p className="text-red-600 text-sm mt-1">{error.message}</p>
+          {isRateLimitError(error) && error.retryAfter && (
+            <p className="text-red-500 text-sm mt-2">
+              Please try again in {error.retryAfter} seconds
+            </p>
+          )}
+          {error.retryable && <button className="mt-3 text-red-700 underline">Try again</button>}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function getErrorTitle(error: OctavusError): string {
+  if (isRateLimitError(error)) return 'Service is busy';
+  if (isAuthenticationError(error)) return 'Configuration error';
+  if (isProviderError(error)) return 'AI service unavailable';
+  return 'Something went wrong';
+}
+```
+
+## Monitoring & Logging
+
+Log errors for monitoring and debugging:
+
+```typescript
+useOctavusChat({
+  transport,
+  onError: (err) => {
+    // Send to your monitoring service
+    analytics.track('octavus_error', {
+      errorType: err.errorType,
+      source: err.source,
+      retryable: err.retryable,
+      code: err.code,
+      provider: err.provider?.name,
+    });
+
+    // Log for debugging
+    console.error('[Octavus]', {
+      type: err.errorType,
+      message: err.message,
+      source: err.source,
+      provider: err.provider,
+    });
+  },
+});
+```
+
+## Error State
+
+The hook exposes error state directly:
+
+```typescript
+const { error, status } = useOctavusChat({ transport });
+
+// status is 'error' when an error occurred
+// error contains the OctavusError object
+
+// Clear error by sending a new message
+await send('user-message', { USER_MESSAGE: 'Try again' });
+```
+
+## Rate Limit Handling
+
+Rate limits include retry information:
+
+```typescript
+if (isRateLimitError(error)) {
+  const waitTime = error.retryAfter ?? 60; // Default to 60 seconds
+
+  // Show countdown
+  setCountdown(waitTime);
+  const timer = setInterval(() => {
+    setCountdown((c) => {
+      if (c <= 1) {
+        clearInterval(timer);
+        return 0;
+      }
+      return c - 1;
+    });
+  }, 1000);
+}
+```
+
+## Error Event Structure
+
+For custom transports or direct event handling, errors follow this structure:
+
+```typescript
+interface ErrorEvent {
+  type: 'error';
+  errorType: ErrorType;
+  message: string;
+  source: ErrorSource;
+  retryable: boolean;
+  retryAfter?: number;
+  code?: string;
+  provider?: {
+    name: string;
+    model?: string;
+    statusCode?: number;
+    errorType?: string;
+    requestId?: string;
+  };
+  tool?: {
+    name: string;
+    callId?: string;
+  };
+}
+```
+
+## Tool Errors
+
+Tool errors are handled differently—they appear inline on the tool call:
+
+```tsx
+function ToolCallPart({ part }: { part: UIToolCallPart }) {
+  return (
+    <div>
+      <span>{part.toolName}</span>
+
+      {part.status === 'error' && <div className="text-red-500 text-sm mt-1">{part.error}</div>}
+    </div>
+  );
+}
+```
+
+Tool errors don't trigger `onError`—they're captured on the tool call part itself.

package/content/04-protocol/01-overview.md

@@ -29,7 +29,7 @@ input:
 resources:
   CONVERSATION_SUMMARY:
     description: Summary for handoff
-    default: ""
+    default: ''
 
 # How the agent can be invoked
 triggers:
@@ -53,25 +53,33 @@ tools:
     parameters:
       userId: { type: string }
 
+# Octavus skills (provider-agnostic code execution)
+skills:
+  qr-code:
+    display: description
+    description: Generating QR codes
+
 # Agent configuration (model, tools, etc.)
 agent:
   model: anthropic/claude-sonnet-4-5
-  system: system            # References prompts/system.md
+  system: system # References prompts/system.md
   tools: [get-user-account]
-  agentic: true             # Allow multiple tool calls
-  thinking: medium          # Extended reasoning
+  skills: [qr-code] # Enable skills
+  imageModel: google/gemini-2.5-flash-image # Enable image generation
+  agentic: true # Allow multiple tool calls
+  thinking: medium # Extended reasoning
 
 # What happens when triggers fire
 handlers:
   user-message:
     Add user message:
-      type: add-message
+      block: add-message
       role: user
       prompt: user-message
       input: [USER_MESSAGE]
-    
+
     Respond to user:
-      type: next-message
+      block: next-message
 ```
 
 ## File Structure
@@ -99,12 +107,12 @@ my-agent/
 }
 ```
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `slug` | Yes | URL-safe identifier (lowercase, digits, dashes) |
-| `name` | Yes | Human-readable name |
-| `description` | No | Brief description |
-| `format` | Yes | `interactive` (chat) or `generation` (background) |
+| Field         | Required | Description                                     |
+| ------------- | -------- | ----------------------------------------------- |
+| `slug`        | Yes      | URL-safe identifier (lowercase, digits, dashes) |
+| `name`        | Yes      | Human-readable name                             |
+| `description` | No       | Brief description                               |
+| `format`      | Yes      | `interactive` (chat) or `worker` (background)   |
 
 ## Naming Conventions
 
@@ -120,6 +128,7 @@ Reference variables with `{{VARIABLE_NAME}}`:
 
 ```markdown
 <!-- prompts/system.md -->
+
 You are a support agent for {{COMPANY_NAME}}.
 
 Help users with their {{PRODUCT_NAME}} questions.
@@ -136,6 +145,8 @@ Variables are replaced with their values at runtime. If a variable is not provid
 - [Input & Resources](/docs/protocol/input-resources) — Defining agent inputs
 - [Triggers](/docs/protocol/triggers) — How agents are invoked
 - [Tools](/docs/protocol/tools) — External capabilities
+- [Skills](/docs/protocol/skills) — Code execution and knowledge packages
 - [Handlers](/docs/protocol/handlers) — Execution blocks
 - [Agent Config](/docs/protocol/agent-config) — Model and settings
-
+- [Provider Options](/docs/protocol/provider-options) — Provider-specific features
+- [Types](/docs/protocol/types) — Custom type definitions

package/content/04-protocol/02-input-resources.md

@@ -34,17 +34,17 @@ input:
     type: string
     description: Current user's ID
     optional: true
-    default: ""
+    default: ''
 ```
 
 ### Input Definition
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |
-| `description` | No | Describes what this input is for |
-| `optional` | No | If true, consumer doesn't have to provide it |
-| `default` | No | Default value if not provided (defaults to `"NONE"`) |
+| Field         | Required | Description                                                                                              |
+| ------------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `type`        | Yes      | Data type: `string`, `number`, `integer`, `boolean`, `unknown`, or a [custom type](/docs/protocol/types) |
+| `description` | No       | Describes what this input is for                                                                         |
+| `optional`    | No       | If true, consumer doesn't have to provide it                                                             |
+| `default`     | No       | Default value if not provided (defaults to `"NONE"`)                                                     |
 
 ### Using Inputs
 
@@ -70,6 +70,7 @@ You are a support agent for {{COMPANY_NAME}}.
 ## Resources
 
 Resources are persistent state that:
+
 - Survive across triggers
 - Can be read and written by the agent
 - Are synced to the consumer's application
@@ -80,7 +81,7 @@ resources:
   CONVERSATION_SUMMARY:
     type: string
     description: Running summary of the conversation
-    default: ""
+    default: ''
 
   # Resource with unknown type (for complex data)
   USER_CONTEXT:
@@ -100,12 +101,12 @@ resources:
 
 ### Resource Definition
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |
-| `description` | No | Describes the resource purpose |
-| `default` | No | Initial value |
-| `readonly` | No | If true, agent cannot write to it |
+| Field         | Required | Description                                                                                              |
+| ------------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `type`        | Yes      | Data type: `string`, `number`, `integer`, `boolean`, `unknown`, or a [custom type](/docs/protocol/types) |
+| `description` | No       | Describes the resource purpose                                                                           |
+| `default`     | No       | Initial value                                                                                            |
+| `readonly`    | No       | If true, agent cannot write to it                                                                        |
 
 ### Writing Resources
 
@@ -115,11 +116,11 @@ Use the `set-resource` block in handlers:
 handlers:
   request-human:
     # ... generate summary ...
-    
+
     Save summary:
-      type: set-resource
+      block: set-resource
       resource: CONVERSATION_SUMMARY
-      value: SUMMARY  # Variable containing the value
+      value: SUMMARY # Variable containing the value
 ```
 
 ### Resource Events
@@ -155,11 +156,11 @@ variables:
 
 ### Variable Definition
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `type` | Yes | Data type: `string`, `number`, `boolean`, `unknown` |
-| `description` | No | Describes what this variable stores |
-| `default` | No | Initial value |
+| Field         | Required | Description                                                                                              |
+| ------------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `type`        | Yes      | Data type: `string`, `number`, `integer`, `boolean`, `unknown`, or a [custom type](/docs/protocol/types) |
+| `description` | No       | Describes what this variable stores                                                                      |
+| `default`     | No       | Initial value                                                                                            |
 
 ### Using Variables
 
@@ -169,27 +170,26 @@ Set variables as output from blocks:
 handlers:
   request-human:
     Serialize conversation:
-      type: serialize-thread
+      block: serialize-thread
       format: markdown
-      output: CONVERSATION_TEXT  # Stores result in variable
-    
+      output: CONVERSATION_TEXT # Stores result in variable
+
     Generate summary:
-      type: next-message
-      output: SUMMARY  # LLM output stored in variable
-    
+      block: next-message
+      output: SUMMARY # LLM output stored in variable
+
     Create ticket:
-      type: tool-call
+      block: tool-call
       tool: create-support-ticket
       input:
-        summary: SUMMARY  # Use variable as input
+        summary: SUMMARY # Use variable as input
       output: TICKET
 ```
 
 ## Scoping
 
-| Type | Scope | Persistence | Synced to Consumer |
-|------|-------|-------------|---------------------|
-| `input` | Session | Immutable | Yes (at creation) |
+| Type        | Scope   | Persistence              | Synced to Consumer  |
+| ----------- | ------- | ------------------------ | ------------------- |
+| `input`     | Session | Immutable                | Yes (at creation)   |
 | `resources` | Session | Persists across triggers | Yes (via callbacks) |
-| `variables` | Session | Persists across triggers | No (internal only) |
-
+| `variables` | Session | Persists across triggers | No (internal only)  |

package/content/04-protocol/03-triggers.md

@@ -69,12 +69,14 @@ triggers:
     description: Optional description
     input:
       VARIABLE_NAME:
-        type: string | number | boolean | unknown
+        type: string | number | integer | boolean | unknown | CustomType
         description: What this input is for
-        optional: true | false  # defaults to false
-        default: value  # default if optional and not provided
+        optional: true | false # defaults to false
+        default: value # default if optional and not provided
 ```
 
+> **Tip**: You can use [custom types](/docs/protocol/types) for complex trigger inputs.
+
 ## Invoking Triggers
 
 ### From Client SDK
@@ -100,11 +102,7 @@ function Chat({ sessionId }: { sessionId: string }) {
   const { send } = useOctavusChat({ transport });
 
   // User message trigger with UI message
-  await send(
-    'user-message',
-    { USER_MESSAGE: text },
-    { userMessage: { content: text } },
-  );
+  await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });
 
   // User action trigger (no input, no UI message)
   await send('request-human');
@@ -149,18 +147,18 @@ handlers:
   user-message:
     # Blocks executed when user-message is triggered
     Add user message:
-      type: add-message
+      block: add-message
       role: user
       prompt: user-message
       input: [USER_MESSAGE]
 
     Respond:
-      type: next-message
+      block: next-message
 
   request-human:
     # Blocks executed when request-human is triggered
     Summarize:
-      type: serialize-thread
+      block: serialize-thread
       # ...
 ```