Owns the ordered, identified agent transcript and its branch snapshots.
Every active message is carried by a TranscriptEntry, so message content and
identity cannot be reordered independently. Branches freeze those same entry
values. The identity high-water mark includes active and branched entries, so
truncation and branch switching never permit ID reuse.
Transition contract
Total transitions return the next transcript directly. Rejectable branch
operations return {:ok, next} or {:error, reason}. All transitions are
pure: callers provide timestamps, and this module performs no persistence,
timer, broadcast, provider, or tool effects.
Compaction keeps the requested active entry IDs in their existing order and preserves every branch snapshot and pin relationship unchanged. Retained entries and every branch entry keep their IDs.
Summary
Types
Decoded branch fields accepted by the canonical restore transition.
The streaming message kind that may replace the active tail.
Canonical transcript state owned by one Session process.
Functions
Adds one turn's usage to the transcript aggregate.
Appends one newly identified message.
Appends a batch of messages and allocates one stable ID per message.
Replaces or appends one streaming tail from a whole batch of chunks.
Creates a frozen branch snapshot and truncates the active transcript.
Returns the immutable branch snapshots.
Collapses every expanded thinking entry without changing identity.
Compacts the active transcript to retained stable IDs and preserves branches.
Returns the last externally published transcript timestamp.
Returns the active tail message, or nil for an empty transcript.
Returns active messages in transcript order.
Returns active stable-ID/message pairs in transcript order.
Creates a live transcript with freshly allocated stable IDs.
Returns pinned active entry IDs.
Resets the active transcript and usage for a new logical session.
Restores active and branched entries through the canonical identity allocator.
Returns the transcript mutation revision.
Switches to a one-based branch snapshot without renumbering its entries.
Toggles collapse for one collapsible active entry by stable transcript ID.
Toggles a pin relationship for one stable transcript ID.
Records the timestamp at which Session published transcript changes.
Transforms every message while preserving entry identity and order.
Transforms one message by active transcript index while preserving its identity.
Updates the matching tool-call entry while preserving its stable identity.
Returns cumulative transcript usage.
Types
@type restore_branch() :: {name :: String.t(), messages :: [MingaAgent.Message.t()], message_ids :: [term()], created_at :: DateTime.t()}
Decoded branch fields accepted by the canonical restore transition.
@type stream_kind() :: :assistant | :thinking
The streaming message kind that may replace the active tail.
@type t() :: %MingaAgent.Session.Transcript{ branches: [MingaAgent.Branch.t()], entries: [MingaAgent.TranscriptEntry.t()], last_changed_at: DateTime.t(), next_id: pos_integer(), pinned_ids: MapSet.t(pos_integer()), revision: non_neg_integer(), usage: MingaAgent.TurnUsage.t() }
Canonical transcript state owned by one Session process.
Functions
@spec add_usage(t(), MingaAgent.TurnUsage.t()) :: t()
Adds one turn's usage to the transcript aggregate.
@spec append(t(), MingaAgent.Message.t()) :: t()
Appends one newly identified message.
@spec append_many(t(), [MingaAgent.Message.t()]) :: t()
Appends a batch of messages and allocates one stable ID per message.
@spec append_stream_tail(t(), stream_kind(), iodata()) :: t()
Replaces or appends one streaming tail from a whole batch of chunks.
@spec branch_at(t(), integer(), DateTime.t()) :: {:ok, t(), MingaAgent.Branch.t()} | {:error, String.t()}
Creates a frozen branch snapshot and truncates the active transcript.
@spec branches(t()) :: [MingaAgent.Branch.t()]
Returns the immutable branch snapshots.
Collapses every expanded thinking entry without changing identity.
@spec compact(t(), [pos_integer()]) :: t()
Compacts the active transcript to retained stable IDs and preserves branches.
@spec last_changed_at(t()) :: DateTime.t()
Returns the last externally published transcript timestamp.
@spec last_message(t()) :: MingaAgent.Message.t() | nil
Returns the active tail message, or nil for an empty transcript.
@spec messages(t()) :: [MingaAgent.Message.t()]
Returns active messages in transcript order.
@spec messages_with_ids(t()) :: [{pos_integer(), MingaAgent.Message.t()}]
Returns active stable-ID/message pairs in transcript order.
@spec new([MingaAgent.Message.t()], DateTime.t()) :: t()
Creates a live transcript with freshly allocated stable IDs.
@spec pinned_ids(t()) :: MapSet.t(pos_integer())
Returns pinned active entry IDs.
@spec reset(t(), [MingaAgent.Message.t()]) :: t()
Resets the active transcript and usage for a new logical session.
@spec restore( [MingaAgent.Message.t()], term(), [MingaAgent.Branch.t() | restore_branch()], MingaAgent.TurnUsage.t(), MapSet.t(pos_integer()), DateTime.t() ) :: t()
Restores active and branched entries through the canonical identity allocator.
@spec revision(t()) :: non_neg_integer()
Returns the transcript mutation revision.
Switches to a one-based branch snapshot without renumbering its entries.
@spec toggle_message_collapse(t(), non_neg_integer()) :: t()
Toggles collapse for one collapsible active entry by stable transcript ID.
@spec toggle_pin(t(), pos_integer()) :: t()
Toggles a pin relationship for one stable transcript ID.
@spec touch(t(), DateTime.t()) :: t()
Records the timestamp at which Session published transcript changes.
@spec transform_messages(t(), (MingaAgent.Message.t() -> MingaAgent.Message.t())) :: t()
Transforms every message while preserving entry identity and order.
@spec update_at(t(), integer(), (MingaAgent.Message.t() -> MingaAgent.Message.t())) :: t()
Transforms one message by active transcript index while preserving its identity.
@spec update_tool_call(t(), String.t(), (MingaAgent.ToolCall.t() -> MingaAgent.ToolCall.t())) :: t()
Updates the matching tool-call entry while preserving its stable identity.
@spec usage(t()) :: MingaAgent.TurnUsage.t()
Returns cumulative transcript usage.