Owns one session's execution mode, runtime phase, and turn-scoped resources.
Transitions are pure. They return the next owned value or a domain outcome; MingaAgent.Session remains responsible for provider calls, notifications, broadcasts, transcript updates, and persistence.
Summary
Types
An active provider tool identified by its stable call ID.
Provider activity within one active turn.
Supported approval response.
Prompt content admitted to steering and follow-up queues.
Execution mode, independent of whether a provider turn is active.
Runtime phase. Approval and nonterminal error presentation are orthogonal to provider activity within an active turn.
Whether a prompt starts a turn now or joins one of the active turn's queues.
How an active turn should admit an additional prompt.
Public status retained at the Session API boundary.
Canonical turn execution state.
Tool trust lifetime.
Functions
Aborts provider and tool work before returning to an inactive phase.
Returns true while provider work belongs to the current turn.
Returns the most recently started active tool name.
Returns active tools in provider start order.
Admits a prompt by starting an inactive turn or queueing behind an active turn.
Records a trusted approval, or rejects it outside an admitted turn.
Moves an admitted turn into completion.
Begins a provider turn from an inactive state.
Returns one edit boundary as its public line tuple.
Clears every edit boundary.
Clears one edit boundary.
Clears both prompt queues.
Dequeues steering prompts without changing follow-up admission.
Switches from plan mode to execution mode.
Switches to plan mode while preserving the runtime phase.
Returns the current error message, if any.
Moves any runtime phase into failure and clears turn-owned active resources.
Finishes completion, clearing turn trust before admitting queued work.
Returns the current execution mode.
Builds an idle execution state.
Returns the current pending approval, if any.
Returns the current runtime phase name.
Accepts the provider's turn-start event.
Adds or replaces one tool trust decision.
Returns a failed queued-send transition to idle without restoring consumed entries.
Returns steering and follow-up queues in FIFO order.
Returns and clears both prompt queues.
Returns true when turn state does not prevent detached-session reclamation.
Clears a provider failure after provider recovery.
Records a provider-reported error without discarding active turn work.
Moves an active turn into approval waiting.
Resets every turn resource for a fresh session.
Resolves the matching pending approval and restores the active runtime phase.
Restores an idle execution value after live work is cleaned up.
Removes one or all tool trust decisions.
Validates and stores an edit boundary by absolute path.
Derives the stable public Session status.
Completes one matching active tool and rejects stale or duplicate completions.
Returns the name for one active tool call.
Starts one tool and records its stable identity.
Returns all current tool trust decisions.
Returns the matching trust scope for one provider approval event.
Updates the current provider failure presentation without changing its phase.
Types
An active provider tool identified by its stable call ID.
@type activity() :: :starting | :thinking | :completion | {:tool_execution, [active_tool(), ...]}
Provider activity within one active turn.
@type approval_decision() :: :approve | :approve_session | :approve_turn | :reject
Supported approval response.
@type content() :: String.t() | [ReqLLM.Message.ContentPart.t()]
Prompt content admitted to steering and follow-up queues.
@type mode() :: :exec | :plan
Execution mode, independent of whether a provider turn is active.
@type phase() :: :idle | {:active, activity(), MingaAgent.ToolApproval.t() | nil, String.t() | nil} | {:failure, String.t()}
Runtime phase. Approval and nonterminal error presentation are orthogonal to provider activity within an active turn.
Whether a prompt starts a turn now or joins one of the active turn's queues.
@type prompt_kind() :: :steering | :follow_up
How an active turn should admit an additional prompt.
@type status() :: :idle | :plan | :thinking | :tool_executing | :error
Public status retained at the Session API boundary.
@type t() :: %MingaAgent.Session.TurnExecution{ boundaries: %{required(String.t()) => MingaAgent.EditBoundary.t()}, follow_up_queue: [content()], mode: mode(), pending_auto_approvals: %{required(String.t()) => trust_scope()}, phase: phase(), steering_queue: [content()], trust_levels: %{required(String.t()) => trust_scope()} }
Canonical turn execution state.
@type trust_scope() :: :session | :turn
Tool trust lifetime.
Functions
Aborts provider and tool work before returning to an inactive phase.
Returns true while provider work belongs to the current turn.
Returns the most recently started active tool name.
@spec active_tools(t()) :: [active_tool()]
Returns active tools in provider start order.
@spec admit_prompt(t(), prompt_kind(), content()) :: prompt_admission()
Admits a prompt by starting an inactive turn or queueing behind an active turn.
@spec auto_approve(t(), MingaAgent.Event.ToolApproval.t(), trust_scope()) :: {:approved, MingaAgent.ToolApproval.t(), t()} | {:rejected, MingaAgent.ToolApproval.t()}
Records a trusted approval, or rejects it outside an admitted turn.
Moves an admitted turn into completion.
Begins a provider turn from an inactive state.
@spec boundary(t(), String.t()) :: {non_neg_integer(), non_neg_integer()} | nil
Returns one edit boundary as its public line tuple.
Clears every edit boundary.
Clears one edit boundary.
Clears both prompt queues.
Dequeues steering prompts without changing follow-up admission.
Switches from plan mode to execution mode.
Switches to plan mode while preserving the runtime phase.
Returns the current error message, if any.
Moves any runtime phase into failure and clears turn-owned active resources.
@spec finish_completion(t()) :: {:idle, t()} | {:send_next, [content(), ...], t()} | {:error, :invalid_phase}
Finishes completion, clearing turn trust before admitting queued work.
Returns the current execution mode.
Builds an idle execution state.
@spec pending_approval(t()) :: MingaAgent.ToolApproval.t() | nil
Returns the current pending approval, if any.
@spec phase(t()) :: :idle | :starting | :thinking | :approval_waiting | :tool_execution | :completion | :failure
Returns the current runtime phase name.
Accepts the provider's turn-start event.
@spec put_trust(t(), String.t(), trust_scope()) :: t()
Adds or replaces one tool trust decision.
Returns a failed queued-send transition to idle without restoring consumed entries.
Returns steering and follow-up queues in FIFO order.
Returns and clears both prompt queues.
Returns true when turn state does not prevent detached-session reclamation.
Clears a provider failure after provider recovery.
Records a provider-reported error without discarding active turn work.
@spec request_approval(t(), MingaAgent.ToolApproval.t()) :: {:accepted, t()} | :rejected
Moves an active turn into approval waiting.
Resets every turn resource for a fresh session.
@spec resolve_approval(t(), String.t() | nil, approval_decision()) :: {:ok, MingaAgent.ToolApproval.t(), t()} | {:error, :approval_not_found | :no_pending_approval}
Resolves the matching pending approval and restores the active runtime phase.
Restores an idle execution value after live work is cleaned up.
Removes one or all tool trust decisions.
@spec set_boundary(t(), String.t(), non_neg_integer(), non_neg_integer()) :: {:ok, t()} | {:error, String.t()}
Validates and stores an edit boundary by absolute path.
Derives the stable public Session status.
Completes one matching active tool and rejects stale or duplicate completions.
Returns the name for one active tool call.
@spec tool_started(t(), MingaAgent.Event.ToolStart.t()) :: {:ok, trust_scope() | nil, t()} | {:error, :invalid_phase | :tool_already_active}
Starts one tool and records its stable identity.
@spec trust_levels(t()) :: %{required(String.t()) => trust_scope()}
Returns all current tool trust decisions.
@spec trusted_scope(t(), MingaAgent.Event.ToolApproval.t()) :: trust_scope() | nil
Returns the matching trust scope for one provider approval event.
Updates the current provider failure presentation without changing its phase.