A turn of the assistant (spec §6.1): the user's message, then rounds of model calls and tool calls until the model answers, or until a write waits for the user's confirmation (PhoenixKitAgent.Confirmations).

Like PhoenixKitAgent.Conversations, every function acts for a live browser session — the {session_token_uuid, user_uuid} reference of PhoenixKit.Users.Auth.SessionRef.from_session/1 — and takes the answer of PhoenixKitWeb.Users.MultiSession.impersonated?/1 for it, a boolean (anything else raises ArgumentError). An impersonated session is refused before anything is read or written.

start/6, in order (the first failure is the answer; a start that fails leaves no lock behind and writes nothing to the chat — except for a limit reached, below):

0-1. the checks of Conversations — impersonation, the session's scope,

   the `agent` permission, the module and the user's switch, the chat is
   the user's;
 - a non-blank message of at most `agent_history_chars` characters, the
   AI module on, an endpoint chosen (the user's own, else
   `agent_default_endpoint_uuid`; `PhoenixKitAgent.UserConfig`), no more
   attachments than `max_attachments_per_message` allows, and each one
   ready, the user's own, of this chat and not sent yet
   (`PhoenixKitAgent.Attachments`);

2. the locks (PhoenixKitAgent.Turns.Locks): one turn per chat (:conversation_busy) and per user (:turn_in_flight, or :click_in_flight while a click on a confirmation card runs); the history is read only once they are taken, so it holds the previous turn's end;
3. the limits (PhoenixKitAgent.Limits.check/3), under the locks: the user's previous turn is over, so all it spent is in the AI journal. A limit used up is {:error, {:limit_reached, kind}}: the locks are released, the model is not called, the user's text is not stored, and — the one refusal that writes — a notice goes into the chat (error daily_cost_limit, monthly_cost_limit or daily_turn_limit) and the limit is announced (PhoenixKitAgent.Limits.announce_reached/2); 3a. the AI guard admits the turn (PhoenixKitAI.Guard.admit/4, task agent.chat, for as long as the turn's lock may live): the user's block ({:error, :task_blocked}) and the task's own limits ({:error, :task_limit_exceeded}) are checked here once, and the rounds pass the admission on (guard_admission:), so a turn admitted before a block or a limit runs to its end. A refusal is like a limit reached: nothing runs or is stored but a notice (error task_blocked or task_limit_exceeded), once a day per chat (a monthly limit: once a month); an answer of the guard this module does not know starts no turn either (model_error, a log line without it);
4. the task starts (PhoenixKitAgent.Turns.Monitor), and {:ok, turn_ref} is returned; there the user message is stored (and the attachments linked to it), then the rounds run (PhoenixKitAgent.Turns.Runner). A turn that started under its limits runs to its end.

The chat's topic (Conversations.topic/1) hears every stored message ({:agent_message_added, conversation_uuid, message_uuid}) and the end of the turn ({:agent_turn_finished, conversation_uuid, turn_ref}), after its locks are released. A listener matches the turn_ref it got from start/6: a start that failed half-way is announced as finished too.

A refusal never carries turn data: an unavailable monitor or a task that did not start is {:monitor_unavailable, class} / {:not_started, class} with only the class of the exit (PhoenixKitAgent.Turns.Monitor.exit_class/0). NUL characters are cut from the text before anything else.

The assistant acts with the session's rights only: tools are listed and run by PhoenixKit.API.Executor.visible_for/3 / execute_as/5 with allow: :all, for this session; there is no service user and no API key. A write is never run by the turn: core holds it for the user's click (PhoenixKitAgent.Turns.Runner, "A write"), and only modules that let a session write (core's api_session_write_modules) show any.