@spec broadcast_message_error(Ecto.UUID.t(), Ecto.UUID.t()) :: :ok

Tells a session one of its messages has failed.

For callers that write the status themselves - the reaper uses a guarded update rather than a read-modify-write - and so cannot go through update_message_status/3.

Handles exceptions for ai_assistant Oban jobs.

Parameters

• measure — A map containing job execution metrics (duration, memory, reductions).
• meta — A map containing job metadata (job, error, stacktrace, etc.).

Handles :stop events for ai_assistant Oban jobs.

This function is invoked when a job in the ai_assistant queue stops with a non-success state (e.g., :discard, :cancelled, or other custom stop reasons).

Jobs with the :success state are ignored.

Parameters

• measure — A map containing job execution metrics (duration, memory, reductions).
• meta — A map containing job metadata (job, state, etc.).

@spec job_timeout() :: pos_integer()

The same ceiling as timeout/1, for callers that have no job in hand.

@spec perform(Oban.Job.t()) :: :ok

Processes an AI assistant message asynchronously.

This is the main entry point called by Oban. It handles the complete lifecycle of message processing including status updates and broadcasting.

Arguments

• job - Oban job containing message_id and session_id in args

Returns

Always returns :ok to prevent Oban retries, even on errors. Errors are handled by updating message status and logging.

@spec timeout(Oban.Job.t()) :: pos_integer()

How long one AI job may run, in milliseconds.

The three Apollo timeouts added together, plus a 10-second buffer, so the transport gets to fail first and say why.

@spec update_message_status(
  Lightning.AiAssistant.ChatMessage.t(),
  atom(),
  {atom(), String.t()} | nil
) ::
  {:ok, Lightning.AiAssistant.ChatSession.t(),
   Lightning.AiAssistant.ChatMessage.t()}

Updates a message's status and broadcasts the change.

This function updates the message status in the database, fetches the updated session with all associations, and broadcasts the status change to connected clients via Phoenix PubSub.

Parameters

• message - The ChatMessage struct to update
• status - The new status atom (:processing, :success, or :error)
• failure - {category, sentence} to record why it failed, or nil to leave the failure columns as they are

Returns

{:ok, updated_session, updated_message} - Tuple with the updated session and message structs