@spec abort(GenServer.server()) :: :ok

Aborts the current agent operation.

@spec activate_skill(GenServer.server(), String.t()) ::
  {:ok, term()} | {:error, term()}

Activates a skill by name.

@spec add_system_message(
  GenServer.server(),
  String.t(),
  MingaAgent.Message.system_level()
) :: :ok

Appends a system message to the conversation and notifies subscribers.

@spec boundary_for(GenServer.server(), String.t()) ::
  {non_neg_integer(), non_neg_integer()} | nil

Returns the edit boundary for the given file path, or nil if unbounded.

@spec branch_at(GenServer.server(), non_neg_integer()) ::
  {:ok, String.t()} | {:error, String.t()}

Branches the conversation at the given turn index.

@spec claim_driver(GenServer.server(), pid()) ::
  :ok | {:error, :driver_taken | :not_subscribed}

Claims the driver role for a subscribed client when the role is vacant.

@spec clear_all_boundaries(GenServer.server()) :: :ok

Clears all edit boundaries for this session.

@spec clear_boundary(GenServer.server(), String.t()) :: :ok

Clears the edit boundary for the given file path, restoring full-buffer access.

@spec clear_queues(GenServer.server()) :: :ok

Clears both queues without returning their contents.

@spec combine_queue_entries_to_text([String.t() | [ReqLLM.Message.ContentPart.t()]]) ::
  String.t()

Converts a list of queue entries (strings or ContentPart lists) into a single string suitable for display or restoring to the prompt input.

@spec compact(GenServer.server()) :: {:ok, String.t()} | {:error, String.t()}

Manually triggers context compaction on the provider.

@spec continue(GenServer.server()) :: :ok | {:error, term()}

Continues from an interrupted stream response.

@spec cycle_model(GenServer.server()) :: {:ok, map()} | {:error, term()}

Cycles to the next model in the configured rotation.

@spec cycle_thinking_level(GenServer.server()) :: {:ok, term()} | {:error, term()}

Cycles to the next thinking level.

@spec deactivate_skill(GenServer.server(), String.t()) :: :ok | {:error, term()}

Deactivates a skill by name.

@spec dequeue_steering(GenServer.server()) :: [
  String.t() | [ReqLLM.Message.ContentPart.t()]
]

Pops and returns all pending steering messages, clearing the steering queue.

@spec editor_snapshot(GenServer.server()) :: editor_snapshot()

Returns a snapshot of session state for the editor to rebuild AgentState.

@spec enter_exec(GenServer.server()) :: :ok

Leaves plan mode and returns the session to execution mode.

@spec enter_plan(GenServer.server()) :: :ok

Enters plan mode, where destructive tools are refused before execution.

@spec get_available_models(GenServer.server()) :: {:ok, term()} | {:error, term()}

Fetches available models from the provider.

@spec get_commands(GenServer.server()) :: {:ok, [map()]} | {:error, term()}

Fetches available commands from the provider.

@spec get_provider(GenServer.server()) :: pid() | nil

Returns the provider pid for direct provider-specific calls.

@spec get_queued_messages(GenServer.server()) ::
  {[String.t() | [ReqLLM.Message.ContentPart.t()]],
   [String.t() | [ReqLLM.Message.ContentPart.t()]]}

Returns both queues without modifying them (for pending message display).

@spec hooks_enabled?(GenServer.server()) :: boolean()

Returns whether hooks are enabled for this session.

@spec list_branches(GenServer.server()) :: {:ok, String.t()}

Lists all conversation branches.

@spec list_skills(GenServer.server()) ::
  {:ok, [map()], [String.t()]} | {:error, term()}

Lists all discovered skills and which are active.

@spec list_tool_trust(GenServer.server()) :: %{required(String.t()) => trust_scope()}

Lists trusted tools and their trust scope.

@spec load_session(GenServer.server(), String.t()) :: :ok | {:error, term()}

Loads a previously saved session, replacing the current conversation history.

The current session is saved before replacement. The restored conversation history, branches, model, and metadata become the active session state.

@spec messages(GenServer.server()) :: [MingaAgent.Message.t()]

Returns the conversation messages.

@spec messages_with_ids(GenServer.server()) :: [
  {pos_integer(), MingaAgent.Message.t()}
]

Returns the conversation messages paired with their stable BEAM-assigned IDs.

@spec metadata(GenServer.server()) :: MingaAgent.SessionMetadata.t()

Returns lightweight metadata about this session (for the picker).

@spec new_session(GenServer.server()) :: :ok | {:error, term()}

Starts a fresh conversation.

@spec persist?(GenServer.server()) :: boolean()

Returns whether this session persists its conversation to disk.

@spec pinned_ids(GenServer.server()) :: MapSet.t(pos_integer())

Returns the set of pinned message IDs.

@spec queue_follow_up(
  GenServer.server(),
  String.t() | [ReqLLM.Message.ContentPart.t()]
) ::
  :ok | {:queued, :follow_up} | {:error, term()}

Queues a message as a follow-up (sent automatically once the current agent run finishes).

When the agent is idle, behaves identically to send_prompt/2. Returns {:queued, :follow_up} when the message was queued.

@spec queue_steering(
  GenServer.server(),
  String.t() | [ReqLLM.Message.ContentPart.t()]
) ::
  :ok | {:queued, :steering} | {:error, term()}

Queues a message as a steering prompt (injected between tool calls on the next turn).

When the agent is idle, behaves identically to send_prompt/2. Returns {:queued, :steering} when the message was queued.

@spec recall_queues(GenServer.server()) ::
  {[String.t() | [ReqLLM.Message.ContentPart.t()]],
   [String.t() | [ReqLLM.Message.ContentPart.t()]]}

Returns both queues and clears them. Used by abort (Ctrl-C) and dequeue (Alt+Up) so pending messages can be restored to the prompt input.

@spec refresh_credentials(GenServer.server()) :: :ok

Re-checks whether any provider credential is now configured.

Call after /auth or /login so the current session stops gating prompts and the UI's "not configured" state clears without a restart.

@spec respond_to_approval(GenServer.server(), approval_decision()) ::
  :ok | {:error, :no_pending_approval}

Responds to a pending tool approval.

Sends the decision directly to the Task process that is blocking on receive, then clears the pending approval and broadcasts the resolution to subscribers.

@spec respond_to_approval_as(GenServer.server(), pid(), approval_decision()) ::
  :ok | {:error, :no_pending_approval | :not_driver}

Responds to a pending tool approval as an attached remote client.

@spec respond_to_approval_as(
  GenServer.server(),
  pid(),
  String.t() | nil,
  approval_decision()
) ::
  :ok | {:error, :approval_not_found | :no_pending_approval | :not_driver}

Responds to a pending tool approval by stable approval id as an attached driver.

@spec revoke_tool_trust(GenServer.server(), String.t() | :all) :: :ok

Revokes trust for one tool, or all tools with :all.

@spec seed_messages(GenServer.server(), [MingaAgent.Message.t()]) :: :ok

Seeds a session transcript without sending a prompt.

@spec send_prompt(GenServer.server(), String.t() | [ReqLLM.Message.ContentPart.t()]) ::
  :ok | {:queued, :steering} | {:error, term()}

Sends a user prompt to the agent.

Accepts either a plain text string or a list of ContentPart structs (for multi-modal messages with images).

@spec send_prompt_as(
  GenServer.server(),
  pid(),
  String.t() | [ReqLLM.Message.ContentPart.t()]
) ::
  :ok | {:queued, :steering} | {:error, term()}

Sends a user prompt as an attached remote client.

@spec session_id(GenServer.server()) :: String.t()

Returns the session ID.

@spec set_boundary(
  GenServer.server(),
  String.t(),
  non_neg_integer(),
  non_neg_integer()
) ::
  :ok | {:error, String.t()}

Sets an edit boundary for the agent on the given file path.

The agent will be restricted to editing within the specified line range (0-indexed, both inclusive). Edits outside the boundary are rejected with a descriptive error message.

@spec set_model(GenServer.server(), String.t()) :: :ok | {:error, term()}

Sets the model without resetting conversation context.

@spec set_thinking_level(GenServer.server(), String.t()) :: :ok | {:error, term()}

Sets the thinking level on the provider.

@spec set_tool_trust(GenServer.server(), String.t(), trust_scope()) :: :ok

Trusts a tool for the session or current turn.

@spec start_link(keyword()) :: GenServer.on_start()

Starts a new agent session.

@spec status(GenServer.server()) :: status()

Returns the current session status.

@spec subagent_context(GenServer.server()) :: subagent_context()

Returns the provider context that should be inherited by a subagent.

@spec subscribe(GenServer.server()) :: :ok | {:error, :invalid_role}

Subscribes the calling process to session events.

@spec subscribe(GenServer.server(), pid(), keyword()) :: :ok | {:error, :invalid_role}

Subscribes the given process to session events.

@spec subscriber_role(GenServer.server(), pid()) :: attachment_role() | nil

Returns the current remote attachment role for a subscriber.

@spec summarize(GenServer.server()) ::
  {:ok, String.t(), String.t()} | {:error, term()}

Generates a context artifact summarizing the current session.

@spec switch_branch(GenServer.server(), non_neg_integer()) ::
  :ok | {:error, String.t()}

Switches to a named branch, replacing the current messages.

@spec toggle_all_tool_collapses(GenServer.server()) :: :ok

Toggles all tool call messages between collapsed and expanded.

@spec toggle_pin(GenServer.server(), pos_integer()) :: :ok

Toggles the pinned state of a message by its stable ID.

@spec toggle_tool_collapse(GenServer.server(), non_neg_integer()) :: :ok

Toggles the collapsed state of a tool call message.

@spec touched_files(GenServer.server()) :: [file_touch()]

Returns files touched by this agent session, ordered by most recent first.

Each entry contains:

• path: relative file path
• action: :created, :modified, or :deleted
• timestamp: monotonic timestamp of the last touch

Derived from tool call history (file_write, file_edit, multi_edit_file, apply_diff).

@spec unsubscribe(GenServer.server()) :: :ok

Unsubscribes the calling process from session events.

@spec unsubscribe(GenServer.server(), pid()) :: :ok

Unsubscribes the given process from session events.

@spec usage(GenServer.server()) :: MingaAgent.Event.token_usage()

Returns accumulated token usage.