ai-elements-chat/dev.ai.elements.core.chat

Package-level declarations

Types

ChatBackend

fun interface ChatBackend

Produces one assistant turn as a cold stream of ChatEvents.

ChatBackendException

class ChatBackendException(message: String, cause: Throwable? = null, val statusCode: Int? = null) : Exception

Thrown by backends for transport / HTTP failures.

ChatController

class ChatController(backend: (ToolApprover) -> ChatBackend, scope: CoroutineScope, initialMessages: List<Message> = emptyList(), clock: () -> Long = System::currentTimeMillis, newId: () -> String = { UUID.randomUUID().toString() }, publishIntervalMs: Long = 32)

Owns one conversation and drives a ChatBackend, the Kotlin counterpart of the AI SDK useChat() hook.

ChatEvent

sealed interface ChatEvent

Protocol-neutral stream events. They map 1:1 onto the AI SDK UI Message Stream chunk types, so every backend (UI Message Stream, OpenAI, Anthropic, mock) translates its wire format into the same small vocabulary.

ChatState

data class ChatState(val messages: List<Message> = emptyList(), val status: ChatStatus = ChatStatus.READY, val error: String? = null, val queue: List<QueuedMessage> = emptyList(), val queuePaused: Boolean = false, val inputRequests: List<InputRequest> = emptyList())

Immutable snapshot rendered by the UI.

InputRequest

data class InputRequest(val id: String, val message: String, val schema: JsonObject? = null, val url: String? = null, val source: String? = null)

A request for information only the user can give — the neutral form of an AG-UI interrupt with a responseSchema and of MCP elicitation.

InputResponse

sealed interface InputResponse

The user's answer to an InputRequest.

QueuedMessage

data class QueuedMessage(val id: String, val text: String, val attachments: List<FilePart> = emptyList(), val data: List<DataPart> = emptyList())

A prompt sent while the agent was busy, waiting its turn (AI Elements <Queue>).

ToolApprover

fun interface ToolApprover

The human in the loop. Backends ask it to approve tool calls (AgentTool.requiresApproval, AI SDK tool approval, AG-UI interrupts) and for information only the user can give (AG-UI interrupts with a responseSchema, MCP elicitation). ChatController implements it by surfacing a Confirmation or an input form in the UI.

ToolDecision

data class ToolDecision(val approved: Boolean, val reason: String? = null, val editedInput: JsonObject? = null, val remember: Boolean = false)

A user's answer to a tool approval request.

Functions

deferredBackend

fun deferredBackend(create: suspend () -> ChatBackend): ChatBackend

A backend whose construction needs I/O — e.g. listing MCP tools or fetching an A2A agent card — built fresh for every turn inside the turn's coroutine, so failures surface as the turn's error.

finishStreaming

fun Message.finishStreaming(now: Long): Message

Close every still-streaming part (end of turn, stop, or error).

reduce

fun Message.reduce(event: ChatEvent, now: Long): Message

Folds one ChatEvent into the assistant Message. Pure, so it is trivially unit-testable and every backend shares the exact same message semantics.