Agent-loop kernel. Dispatches to a ExAthena.Loop.Mode implementation and handles everything around it: caps, budget, hooks, counters, events, and termination accounting.

Public entry point: run/2, returning {:ok, %ExAthena.Result{}} | {:error, reason}.

v0.3 breaking change

The return shape is now an ExAthena.Result struct instead of a loose map. Every termination — success or error — produces a Result with the typed finish_reason (see ExAthena.Loop.Terminations for the enumeration). Callers can dispatch on Result.category/1 (:success | :retryable | :capacity | :fatal) instead of pattern-matching individual atoms.

Options

• :provider — required. Provider atom (:ollama, :openai, :claude, :mock, :req_llm) or a module implementing ExAthena.Provider.
• :model, :system_prompt, :messages, :temperature, :top_p, :max_tokens, :stop, :timeout_ms, :tool_choice, :response_format, :provider_opts, :metadata — forwarded to ExAthena.Request.new/2.
• :tools — list of modules implementing ExAthena.Tool or :all (default — all builtins). nil falls back to config :ex_athena, tools: ….
• :mode — atom (:react, :plan_and_solve, :reflexion) or module. Defaults to :react.
• :cwd, :phase, :assigns — threaded into every tool's ExAthena.ToolContext.
• :allowed_tools, :disallowed_tools, :can_use_tool — see ExAthena.Permissions.
• :hooks — see ExAthena.Hooks.
• :max_iterations (default 25) — hard iteration cap.
• :max_consecutive_mistakes (default 3) — counter threshold at which the loop terminates with :error_consecutive_mistakes.
• :max_budget_usd — optional float. Trips :error_max_budget_usd when cumulative cost crosses it.
• :tool_timeout_ms (default 60_000) — per-call timeout for parallel tool execution.
• :max_concurrency (default 4) — Task.async_stream concurrency cap for parallel-safe tool calls in a single iteration.
• :on_event — (ExAthena.Loop.Events.t -> term) callback for streaming. Events are flat tuples ({:content, text}, {:tool_call, tc}, {:tool_result, tr}, {:iteration, n}, {:usage, u}, {:error, reason}, {:done, Result}).

Returns

• {:ok, Result.t()} — ran to termination (possibly with an error subtype like :error_max_turns; the Result contains the classification).
• {:error, reason} — unexpected failure before the loop started (e.g. unknown provider, bad tool module).