Core Concepts

This page explains the domain model behind @cognipeer/chat-ui.

Chat session

A session represents one conversational thread between user and assistant. Session metadata (title, agent, runtime, usage limit) is used by the history sidebar and backend APIs.

Message model

Each message has a role and content. Common roles:

• user
• assistant
• system (optional, backend-oriented)
• tool-related metadata for visualization

Messages can include:

• plain text content, or an array of parts (text and images)
• markdown-formatted content
• optional attachments (with upload state, deadlines and conversion status)
• optional tool call traces (metadata.toolCallDetails)
• how the turn ended: status (completed, requires_action, incomplete, cancelled) and stopReason
• the cards of a pause (pendingActions) and how each ended (actionStates)
• the person's rating (feedback)

Streaming lifecycle

For streamed responses, one assistant message is usually created and continuously appended as chunks arrive.

• Initial placeholder is shown.
• Stream chunks append to the live text; tool calls appear as steps.
• A completion event finalizes the turn; the stored message replaces the live view.
• An error event updates the UI with a localized, retry-safe state; a dropped connection is first checked against the server, because the turn may still be running.

Runs, pauses and limits

On agent-server 0.3.0+ a turn is a run that outlives the request that started it:

• Pause: the agent can stop for a tool approval or a question. The conversation's runtime.status is requires_action and the cards wait for an answer.
• Cancel: Stop cancels the run on the server; the partial answer stays, marked stopped.
• Budget: a conversation can have a spend limit. Used up, it is budget_paused (or ended) until the limit is raised.
• Reattach: opening or reloading a conversation whose turn is still running follows the run.

UI variants

• Chat: full-featured UI with history and richer controls.
• ChatMinimal: compact embedding with the core chat loop (no sidebar).
• EmbedChat: Chat for an iframe inside another site, signed in with a host-signed token.

Choose based on your product surface and available screen space.

Composer states

One value says what the composer does: open, blocked / cancel / answer (a card waits), following (a turn runs elsewhere), budget_paused (the limit is used up) and readonly. See Running Turns and Stop.

Who decides what

The host page decides which opt-in features are on (props). The agent (GET /agents) can narrow them and tells the chat what it accepts (attachments, composer mode). The server enforces and refuses. See Architecture.

Theming model

The library uses preset theme modes (dark, light) plus token overrides via themeColors, including the status colours (success, danger, warning, info).

• Prefer token overrides for brand adaptation.
• Avoid per-component ad-hoc styling unless doing advanced customization.
• The theme is read when the chat mounts.

Internationalization

English and Turkish are built in. Any other locale works with customMessages; keys it leaves out fall back to English. Server error codes become localized messages.

Integration boundary

The UI library expects a compatible backend contract (typically @cognipeer/agent-server; other backends through transports).

UI responsibilities:

• display conversation state
• collect user input and answers to pauses
• render streaming/tool updates
• check what it draws (safe URLs, safe Markdown)

Backend responsibilities:

• persistence
• model execution
• authorization and business logic
• limits, retention and enforcement of what the UI offers