SSE Events

SSE (Server-Sent Events) are used for streaming AI responses and real-time updates from the server.

Chat Events

During a chat interaction, the system emits a stream of typed events. In the desktop app these flow over IPC; in the web app they flow over SSE.

Event Types

Type	Fields	Description
`text`	`text`	A chunk of streaming text from the LLM. Append to the current response.
`thinking`	—	The AI is processing. Shown before the first token arrives and between tool call rounds.
`tool_call`	`toolName`, `toolCallId`, `toolArgs`	The AI is invoking a tool. Use `toolName` to display a human-readable activity indicator.
`tool_result`	`toolCallId`, `toolResult`	A tool call completed. `toolResult` is a truncated preview (max 200 characters).
`done`	`contextUsage?`	The full response is complete. Includes context window usage if available. Finalize the message and clean up streaming state.
`error`	`error`	An error occurred. Display the error message and stop streaming.
`title-updated`	`title`	The session title was generated or updated (arrives asynchronously after first exchange).

Event Shape

interface ChatEvent {
  sessionId: string
  type: 'text' | 'done' | 'error' | 'title-updated' | 'tool_call' | 'tool_result' | 'thinking'
  text?: string
  error?: string
  title?: string
  toolName?: string
  toolCallId?: string
  toolArgs?: Record<string, unknown>
  toolResult?: string
  contextUsage?: {
    usedTokens: number   // Current context consumption
    maxTokens: number    // Model's context window limit
    percentage: number   // usedTokens / maxTokens * 100
  }
}

Typical Event Sequence

A simple text response:

thinking → text → text → text → done

A response that calls tools:

thinking → text → tool_call → tool_result → thinking → text → text → done

Multiple tool calls in one turn:

thinking → tool_call → tool_call → tool_result → tool_result → thinking → text → done

Rendering Guidance

When building a chat UI that consumes these events:

On thinking — Show a subtle loading indicator (e.g., animated dots with "Thinking" label). Remove it when the next text or tool_call event arrives.
On text — Append to the current text segment. If the previous segment was a thinking indicator, replace it with a text bubble.
On tool_call — Show an activity badge with the tool name and a spinner. Display alongside text segments, not replacing them.
On tool_result — Mark the corresponding tool call badge as complete (spinner to checkmark). Optionally show the result preview on expand.
On done — Finalize: combine all text segments into the persisted message, clear streaming state. If contextUsage is present, update the context meter UI.
On error — Save any partial text as a message, then display the error.

Context Usage

The done event may include a contextUsage field with the current context window consumption. Use this to display a context meter:

usedTokens — how many tokens the conversation is using
maxTokens — the model's context window limit (e.g., 200,000 for Claude models)
percentage — usage as a percentage

When percentage exceeds 80%, the engine may auto-compact older messages to free space. The next done event will reflect the reduced usage.

Server-Handled Tool Calls

Some tool calls are executed server-side by the AI provider (e.g., Anthropic's web search). These follow the same event flow as regular tool calls but with key differences:

The tool_call event has the same shape, but the engine does not execute the tool — the provider handles it
The tool_result event is emitted by the provider once the server-side execution completes
The engine's agentic loop does not re-run for server-handled calls — they resolve within a single provider turn

Web search event sequence:

thinking → tool_call (web_search) → tool_result (search complete) → text → text → done

From the UI's perspective, server-handled tools look identical to regular tools — you show a spinner, then a checkmark. The difference is only in the engine layer.

Tool Name Formatting

Tool names follow conventions that can be formatted for display:

cosmo_tasks_create — Cosmo built-in tool. Format as "Tasks: Create"
cosmo_artifacts_move — Format as "Artifacts: Move"
mcp__notion__search — MCP connector tool. Format as "Notion: Search"
web_search — Provider built-in tool. Format as "Web Search"

On this page