@spec build_config(config_input()) :: Jido.AI.Reasoning.ReAct.Config.t()

Normalizes user-provided configuration into a Config struct.

@spec cancel(String.t(), config_input(), atom()) ::
  {:ok, String.t()} | {:error, term()}

Marks a checkpoint token as cancelled and returns a replacement token.

@spec collect(Enumerable.t() | String.t(), config_input(), keyword()) ::
  {:ok, map()} | {:error, term()}

Collects run output from an event stream or checkpoint token.

@spec collect_stream(Enumerable.t()) :: map()

Reduces a ReAct event stream into terminal result, usage, token, and full trace.

@spec continue(String.t(), config_input(), keyword()) ::
  {:ok, map()} | {:error, term()}

Resumes a run from a checkpoint token and returns run metadata plus a stream handle.

@spec inject(GenServer.server(), String.t(), keyword()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}

Injects user-visible input into an active ReAct-backed agent.

This is intended for programmatic or inter-agent steering and follows the same queuing rules as steer/3.

@spec run(String.t(), config_input(), keyword()) :: map()

Runs ReAct to completion and returns an aggregated result map.

@spec start(String.t(), config_input(), keyword()) :: {:ok, map()} | {:error, term()}

Starts a run and returns run metadata plus a stream handle.

@spec steer(GenServer.server(), String.t(), keyword()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}

Steers an active ReAct-backed agent with additional user-visible input.

Returns {:ok, agent} when the input is queued for the current run or {:error, {:rejected, reason}} when no eligible run is active.

Queued input is best-effort. If the run terminates before the runtime drains the queue into conversation state, the queued input is dropped.

@spec stream(String.t(), config_input(), keyword()) :: Enumerable.t()

Starts a new ReAct run and returns a lazy event stream.

@spec stream_from_state(Jido.AI.Reasoning.ReAct.State.t(), config_input(), keyword()) ::
  Enumerable.t()

Resumes a ReAct run from state and returns a lazy event stream.