Streaming

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

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

// For HTTP endpoints, convert to SSE stream
return new Response(toSSEStream(events), {
  headers: {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    Connection: 'keep-alive',
    'X-Accel-Buffering': 'no',
  },
});

// For sockets, iterate events directly
for await (const event of events) {
  conn.write(JSON.stringify(event));
}

// Stream started
{ type: 'start', messageId: '...', executionId: '...' }

// Stream completed
{ type: 'finish', finishReason: 'stop' }

// Possible finish reasons:
// - 'stop': Normal completion
// - 'tool-calls': Waiting for server tool execution (handled by SDK internally)
// - 'client-tool-calls': Waiting for client tool execution
// - 'length': Max tokens reached
// - 'content-filter': Content filtered
// - 'error': Error occurred
// - 'other': Other reason

// Error event (see Error Handling docs for full structure)
{ type: 'error', errorType: 'internal_error', message: 'Something went wrong', source: 'platform', retryable: false }

// Block started
{ type: 'block-start', blockId: '...', blockName: 'Respond to user', blockType: 'next-message', display: 'stream', thread: 'main' }

// Block completed
{ type: 'block-end', blockId: '...', summary: 'Generated response' }

// A later model step is starting (never sent for a block's first step).
// The live counterpart of the `step-start` message part, so a message built
// from the stream has the same structure as one loaded from history.
{
  type: 'step-start';
}

// The current step's partial output is abandoned: drop everything streamed
// since the step began (after the last `step-start`, or since the block's
// output began). A fresh attempt at the same step streams next.
{
  type: 'step-discard';
}

// Everything streamed before this event is now in saved session state.
// Sent once per round, after the round's state write and before the
// tool request that pauses the execution.
{
  type: 'persisted';
  executionId: string;
  round: number; // rounds of this execution saved so far (1 after the first)
  messageId?: string; // the in-progress assistant message the round extended
}

// Text generation started
{ type: 'text-start', id: '...' }

// Incremental text (most common event)
{ type: 'text-delta', id: '...', delta: 'Hello! How' }
{ type: 'text-delta', id: '...', delta: ' can I help?' }

// Text generation ended
{ type: 'text-end', id: '...' }

// Reasoning started
{ type: 'reasoning-start', id: '...' }

// Reasoning content
{ type: 'reasoning-delta', id: '...', delta: 'Let me analyze this request...' }

// Reasoning ended
{ type: 'reasoning-end', id: '...' }

agent:
  model: anthropic/claude-sonnet-4-5
  system: system-prompt
  streaming:
    chunking: word # off (default) | word | line
    delayMs: 15 # optional inter-chunk delay

// Tool input started
{ type: 'tool-input-start', toolCallId: '...', toolName: 'get-user-account', title: 'Looking up account' }

// Tool input/arguments streaming
{ type: 'tool-input-delta', toolCallId: '...', inputTextDelta: '{"userId":"user-123"}' }

// Tool input streaming ended
{ type: 'tool-input-end', toolCallId: '...' }

// Tool input is complete and available
{ type: 'tool-input-available', toolCallId: '...', toolName: 'get-user-account', input: { userId: 'user-123' } }

// Tool output available (success)
{ type: 'tool-output-available', toolCallId: '...', output: { name: 'Demo User', email: '...' } }

// Tool output error (failure)
{ type: 'tool-output-error', toolCallId: '...', error: 'User not found' }

{ type: 'resource-update', name: 'CONVERSATION_SUMMARY', value: 'User asked about...' }

type StreamEvent =
  // Lifecycle
  | StartEvent
  | FinishEvent
  | ErrorEvent
  // Text
  | TextStartEvent
  | TextDeltaEvent
  | TextEndEvent
  // Reasoning
  | ReasoningStartEvent
  | ReasoningDeltaEvent
  | ReasoningEndEvent
  // Tool Input/Output
  | ToolInputStartEvent
  | ToolInputDeltaEvent
  | ToolInputEndEvent
  | ToolInputAvailableEvent
  | ToolOutputAvailableEvent
  | ToolOutputErrorEvent
  // Octavus-Specific
  | BlockStartEvent
  | BlockEndEvent
  | ResourceUpdateEvent
  | ToolRequestEvent
  | ClientToolRequestEvent;

{
  type: 'client-tool-request',
  executionId: 'exec_abc123',       // Use this to continue execution
  toolCalls: [                       // Tools for client to handle
    {
      toolCallId: 'call_xyz',
      toolName: 'get-browser-location',
      args: {}
    }
  ],
  serverToolResults: [               // Results from server tools in same batch
    {
      toolCallId: 'call_def',
      toolName: 'get-user-account',
      result: { name: 'Demo User' }
    }
  ]
}

session.execute({
  type: 'continue',
  executionId: 'exec_abc123',
  toolResults: [
    ...serverToolResults, // Include server results from the event
    {
      toolCallId: 'call_xyz',
      toolName: 'get-browser-location',
      result: { lat: 40.7128, lng: -74.006 },
    },
  ],
});

{
  type: 'error',
  errorType: 'rate_limit_error',     // Error classification
  message: 'Rate limit exceeded',     // Human-readable message
  source: 'provider',                 // 'platform' | 'provider' | 'tool'
  retryable: true,                    // Whether retry is possible
  retryAfter: 60,                     // Seconds to wait (rate limits)
  code: 'ANTHROPIC_429',              // Machine-readable code
  provider: {                         // Provider details (when applicable)
    name: 'anthropic',
    statusCode: 429,
    requestId: 'req_...'
  },
  backup: {                           // How the backup model failed too (when one was tried)
    model: 'openai/gpt-5.5',
    errorType: 'rate_limit_error',
    message: 'You have no credits remaining. ...',
    code: 'PROVIDER_ACCOUNT_ERROR'
  }
}

{ type: 'tool-output-error', toolCallId: '...', error: 'Handler threw exception' }