# Chats

## Overview

A **chat** is a conversation container owned by a user. Agents become chat members, receive messages, and can reply in threads. Every message a user sees belongs to a chat.

Chats are either **persistent** (stored in the database) or **temporary** (in-memory only, useful for quick, unsaved conversations). Both kinds share the same features and appear together in listings.

## Structure

A chat contains:

*   **Messages** — the conversation content.
*   **Threads** — messages can be grouped into named threads; messages without a thread go to the chat's default thread.
*   **Memberships** — which agents are in the chat. Every agent is created with a **main chat** it belongs to.

## Messages

Each message carries:

*   `sender` — `'user'` or an agent id.
*   `kind` — the message class: `message` (normal content), `log` (agent internals like reasoning), `note` (annotations), or `resource` (declarations such as remotes; not shown to agents).
*   `subkind` — a refinement of the kind (e.g. `reasoning`, `remote`).
*   `format` — content format hint.
*   `threadId` — the thread the message belongs to.

Message content may be a **stream** rather than a final value: the message is stored immediately with a stream reference and updated in place when the stream finishes. This is how agent replies appear progressively.

## Delivery

When a message is sent to a chat:

*   The chat's owner is notified over their websocket connections (as an update when a streamed message settles).
*   Every member agent is notified, except the sender itself. The agent then builds a run from the message's thread and can stream a reply into the same thread.
*   `resource` messages are not delivered to agents — they are declarations, not conversation.

## Threads

Threads are lightweight sub-conversations inside a chat:

*   Messages with no thread id belong to the chat's implicit **default thread**.
*   Named threads can be created on demand; new messages open new threads implicitly.
*   `note` and `resource` messages are attached to their thread separately from the main message list, so notes and remote declarations travel with a thread without polluting the conversation.

## Reading Chats

The **ChatView** is the read-side view of a chat in the backend, used both by agents (to build their message history) and by tooling:

*   Loads the chat's basic data plus the most recent page of messages (`MESSAGE_PAGE_SIZE`), paging further back on demand — messages are ordered by id, which is more robust than timestamps.
*   Groups messages into threads, keeping messages, notes, and resources separate per thread.
*   Tracks the **current thread** (the most recently active one) and provides a debug dump of the full structure.

## Lifecycle

*   Chats are created with a name, description, picture, and an optional list of member agents.
*   Agents can be added to existing chats at any time.
*   Deleting a chat removes its memberships.

## Frontend: the chat view

The chat page is the live surface of these concepts:

- **Messages** render with sender names resolved from the agent registry; new messages arrive over websockets, streamed content updates in place, and the user's own messages appear optimistically until the broadcast confirms them.
- **Threads** are UI-first: "New Thread" is a local state, and the thread is only created upstream once a message is actually sent into it. Exactly one thread is open at a time — the active one — while all others collapse into preview headers; opening a preview makes that thread active. The last thread is only continued automatically while it is fresh (ten minutes), otherwise the chat starts in "New Thread" state.
- **Composing** supports note mode, editing an existing message, and attaching a connected remote to the current thread as a resource.
- **Runs** are tracked per message, so an in-flight agent reply can be cancelled from the chat.

### Backend and frontend

On the backend, chats are **storage and routing**: the App owns chat, thread and message persistence, membership, and the notification fan-out to users and agents. On the frontend, chats are **presentation and composing**: thread UX, live updates, optimistic sending, notes and edits.