Raxol.Agent.Conversation.Item (Raxol Agent v2.6.0)

One immutable entry in a Raxol.Agent.Conversation.Log.

Every event in a conversation -- assistant messages, tool calls and their results, reasoning, errors, compaction markers, terminal I/O, slash commands -- is a typed Item. A single append-only log of these unifies what every surface (terminal, browser, phone, MCP) renders, and lets a reconnecting client reconcile by stable id.

Items are append-only and never mutated. The store assigns seq (monotonic per conversation, 0-based) and derives a stable id of "<conversation_id>:<seq>", so snapshot + live tail can be deduped by id with no coordination.

Types

type	typical `data`	meaning
`:message`	`%{role, content, usage}`	an assistant/user message
`:tool_call`	`%{name, arguments, id}`	the model requested a tool
`:tool_result`	`%{name, result}`	the result of a tool call
`:reasoning`	`%{text}`	chain-of-thought / thinking
`:error`	`%{reason}`	an error in the turn
`:compaction`	`%{summary, last_seq}`	a summarization marker
`:resource_event`	`%{kind, ...}`	session/sub-agent lifecycle
`:slash_command`	`%{command, args}`	a user slash command
`:terminal`	`%{stream, text}`	terminal input/output observation

The set is open; adapters round-trip arbitrary atoms.

Summary

Types

status()

t()

type()

Functions

id(conversation_id, seq)

The stable item id derived from a conversation id and sequence.

new(opts)

Construct an Item. Used by stores when materializing items on append; callers go through Raxol.Agent.Conversation.Log.append/3 instead.

Types

status()

@type status() :: :completed | :in_progress | :action_required | atom() | nil

t()

@type t() :: %Raxol.Agent.Conversation.Item{
  conversation_id: binary(),
  created_at: DateTime.t(),
  created_by: term() | nil,
  data: map(),
  id: binary(),
  response_id: binary() | nil,
  seq: non_neg_integer(),
  status: status(),
  type: type()
}

type()

@type type() ::
  :message
  | :tool_call
  | :tool_result
  | :reasoning
  | :error
  | :compaction
  | :resource_event
  | :slash_command
  | :terminal
  | atom()

Functions

id(conversation_id, seq)

@spec id(binary(), non_neg_integer()) :: binary()

The stable item id derived from a conversation id and sequence.

new(opts)

@spec new(keyword()) :: t()

Construct an Item. Used by stores when materializing items on append; callers go through Raxol.Agent.Conversation.Log.append/3 instead.

Requires :conversation_id, :seq, and :type. :id defaults to id/2, :status to :completed, and :created_at to now.