@spec continue(ALLM.Engine.t(), t(), ALLM.Message.t() | nil, session_opts()) ::
  {:ok, t(), ALLM.ChatResult.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()
     | ALLM.Error.SessionError.t()}

Drive the next adapter turn on a session.

When message is a %Message{}, it is appended to session.thread before the adapter call. When message is nil, no append happens — this form is used for manual-tool-cycle resumption after the caller has populated tool-role messages via submit_tool_result/3 (see Decision #4).

Status preconditions:

• :idle, :completed — legal with any message.
• :awaiting_user — raises ArgumentError (caller should use reply/4 to clear pending fields and supply user text). The reply/4 delegation passes a %Message{role: :user} through this function, so a user-role message on :awaiting_user is legal as the delegated path; any other shape raises.
• :awaiting_tools — legal only with message == nil AND pending_tool_calls == [] (i.e., the caller has already submitted every pending tool result and the session has flipped back to :idle). Calling on :awaiting_tools while pending_tool_calls is non-empty raises ArgumentError.
• :error — returns {:error, %SessionError{reason: :session_in_error_state}}.

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [
...>     scripts: [
...>       [{:text, "first"}, {:finish, :stop}],
...>       [{:text, "second"}, {:finish, :stop}]
...>     ]
...>   ]
...> )
iex> {:ok, s, _} = ALLM.Session.start(engine, [ALLM.user("hi")])
iex> {:ok, s2, _} = ALLM.Session.continue(engine, s, ALLM.user("more"))
iex> s2.status
:completed

@spec reply(ALLM.Engine.t(), t(), String.t(), session_opts()) ::
  {:ok, t(), ALLM.ChatResult.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()
     | ALLM.Error.SessionError.t()}

Append a :user-role message with user_text and run ALLM.Chat.run/3.

Equivalent to continue(engine, session, ALLM.user(user_text), opts). See continue/3.

Legal on :idle, :awaiting_user (clears the pending fields), and :completed (treated as :idle per Decision #5). Raises ArgumentError on :awaiting_tools. Returns {:error, %SessionError{reason: :session_in_error_state}} on :error.

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [
...>     scripts: [
...>       [{:text, "ok"}, {:finish, :stop}],
...>       [{:text, "again"}, {:finish, :stop}]
...>     ]
...>   ]
...> )
iex> {:ok, s, _} = ALLM.Session.start(engine, [ALLM.user("hi")])
iex> {:ok, s2, _} = ALLM.Session.reply(engine, s, "again")
iex> length(ALLM.Session.messages(s2)) > length(ALLM.Session.messages(s))
true

@spec start(ALLM.Engine.t(), session_input(), session_opts()) ::
  {:ok, t(), ALLM.ChatResult.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()
     | ALLM.Error.SessionError.t()}

Start a new session by running ALLM.Chat.run/3 against engine and the supplied input.

session_input may be a %Session{} (preserves :id, :context, :metadata), a %Thread{}, or a list of %Message{} (per Decision #2). Anything else returns {:error, %ValidationError{reason: :invalid_session_input}}.

Returns {:ok, %Session{}, %ChatResult{}} on a successful adapter round-trip. The session's :status reflects the chat result's :halted_reason (see status-transition table in the moduledoc).

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [script: [{:text, "hi"}, {:finish, :stop}]]
...> )
iex> {:ok, session, result} = ALLM.Session.start(engine, [ALLM.user("hello")])
iex> session.status
:completed
iex> result.halted_reason
:completed

@spec step(ALLM.Engine.t(), t(), session_opts()) ::
  {:ok, t(), ALLM.StepResult.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()
     | ALLM.Error.SessionError.t()}

Run a single adapter turn (ALLM.Chat.step/3) on the session.

Unlike continue/3, step/3 does not loop — it dispatches one adapter call and returns the resulting %StepResult{} projected onto the session via apply_step_result/2. Status follows Phase 6's semantics; see steering/PHASE_8_DESIGN.md Decision #6 for the table.

Legal on :idle and :completed (treated as :idle). Raises ArgumentError on :awaiting_user and :awaiting_tools. Returns {:error, %SessionError{reason: :session_in_error_state}} on :error.

Examples

step/3 is a single-turn entry point; this doctest seeds the thread directly via Session.new/1 to keep the example focused on the single-step return shape. The start/3 → step/3 flow is tested in test/allm/session_test.exs.

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [script: [{:text, "hi"}, {:finish, :stop}]]
...> )
iex> {:ok, s, sr} = ALLM.Session.step(engine, ALLM.Session.new(thread: ALLM.Thread.from_messages([ALLM.user("hi")])))
iex> sr.done?
true
iex> s.status
:completed

@spec stream_reply(ALLM.Engine.t(), t(), String.t(), session_opts()) ::
  {:ok, Enumerable.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()
     | ALLM.Error.SessionError.t()}

Streaming counterpart to reply/4. Appends a :user-role message with user_text to session.thread, then dispatches via ALLM.Chat.stream/3. Returns {:ok, stream} whose terminal event is :chat_completed.

Status preconditions (synchronous, BEFORE the stream is constructed):

• :idle, :completed — legal.
• :awaiting_user — legal; pending fields are cleared at StreamReducer.finalize/1 time via apply_chat_result/2.
• :awaiting_tools — raises ArgumentError.
• :error — returns {:error, %SessionError{reason: :session_in_error_state}}.

Pre-flight errors (missing adapter, validation, status precondition) surface synchronously; mid-stream adapter errors fold into the terminal :chat_completed event's result.halted_reason: :error.

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [
...>     scripts: [
...>       [{:text, "ok"}, {:finish, :stop}],
...>       [{:text, "again"}, {:finish, :stop}]
...>     ]
...>   ]
...> )
iex> {:ok, s, _} = ALLM.Session.start(engine, [ALLM.user("hi")])
iex> {:ok, stream} = ALLM.Session.stream_reply(engine, s, "again")
iex> Enum.count(Enum.to_list(stream), &match?({:chat_completed, _}, &1))
1

@spec stream_start(ALLM.Engine.t(), session_input(), session_opts()) ::
  {:ok, Enumerable.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()
     | ALLM.Error.SessionError.t()}

Streaming counterpart to start/3. Returns {:ok, stream} where the stream is the inner ALLM.Chat.stream/3 enumerable verbatim.

Pre-flight errors (missing adapter, coerce_session_input/1 failure, status precondition, :error-status session) are returned {:error, _} SYNCHRONOUSLY before any stream is constructed. Mid-stream adapter errors fold into the terminal :chat_completed event's result.halted_reason: :error; the call-site tuple stays {:ok, stream}. Mirrors Phase 7's Chat.stream/3 synchronous-vs-lazy split.

The consumer drives ALLM.Session.StreamReducer themselves to recover the post-call session and %ChatResult{} (see Decision #15). No session-side state changes happen until StreamReducer.finalize/1.

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [script: [{:text, "hi"}, {:finish, :stop}]]
...> )
iex> {:ok, stream} = ALLM.Session.stream_start(engine, [ALLM.user("hello")])
iex> events = Enum.to_list(stream)
iex> Enum.count(events, &match?({:chat_completed, _}, &1))
1

@spec stream_step(ALLM.Engine.t(), t(), session_opts()) ::
  {:ok, Enumerable.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()
     | ALLM.Error.SessionError.t()}

Streaming counterpart to step/3. Returns {:ok, stream} whose terminal event is :step_completed (NOT :chat_completed — per Decision #11). Composes ALLM.Chat.stream_step/3; the stream represents one adapter turn.

Pre-flight errors (missing adapter, status precondition, :error state) surface synchronously. Consumers fold the stream through ALLM.Session.StreamReducer.new(session, mode: :step) to recover {updated_session, %StepResult{}}.

Legal on :idle and :completed. Raises ArgumentError on :awaiting_user and :awaiting_tools. Returns {:error, %SessionError{reason: :session_in_error_state}} on :error.

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [script: [{:text, "hi"}, {:finish, :stop}]]
...> )
iex> session = ALLM.Session.new(thread: ALLM.Thread.from_messages([ALLM.user("hi")]))
iex> {:ok, stream} = ALLM.Session.stream_step(engine, session)
iex> events = Enum.to_list(stream)
iex> Enum.count(events, &match?({:step_completed, _}, &1))
1

@spec submit_tool_result(t(), String.t(), String.t() | map()) ::
  t() | {:error, ALLM.Error.SessionError.t()}

Submit a tool-role result for one pending tool call. In-process state mutation only; this does NOT call the adapter (Decision #3).

Appends a :tool-role message to session.thread with the supplied tool_call_id and content, removes the matching %ToolCall{} from pending_tool_calls, and flips status back to :idle when the last pending call is submitted.

Returns the updated %Session{} on success or {:error, %SessionError{reason: :unknown_tool_call_id, metadata: %{tool_call_id: id}}} when the id doesn't match any pending call (Decision #14 — data-validation, not a programmer-flow error).

Raises ArgumentError if session.status != :awaiting_tools (Decision #7).

Examples

iex> tc = %ALLM.ToolCall{id: "c0", name: "echo", arguments: %{}}
iex> session = ALLM.Session.new(
...>   status: :awaiting_tools,
...>   pending_tool_calls: [tc],
...>   thread: ALLM.Thread.from_messages([ALLM.user("hi")])
...> )
iex> updated = ALLM.Session.submit_tool_result(session, "c0", %{ok: true})
iex> updated.status
:idle
iex> updated.pending_tool_calls
[]

@spec submit_tool_results(t(), [{String.t(), String.t() | map()}]) ::
  t() | {:error, ALLM.Error.SessionError.t()}

Submit a batch of tool-role results in order.

Equivalent to folding submit_tool_result/3 over results; on the first {:error, _} the fold short-circuits and returns that error unchanged — no partial submissions land (matches ALLM.Validate's hard-reject semantics).

An empty list is identity (returns the session unchanged).

Errors mirror submit_tool_result/3: an unknown id yields {:error, %SessionError{reason: :unknown_tool_call_id}}. A status mismatch raises ArgumentError.

Examples

iex> tc0 = %ALLM.ToolCall{id: "c0", name: "echo", arguments: %{}}
iex> tc1 = %ALLM.ToolCall{id: "c1", name: "echo", arguments: %{}}
iex> session = ALLM.Session.new(
...>   status: :awaiting_tools,
...>   pending_tool_calls: [tc0, tc1],
...>   thread: ALLM.Thread.from_messages([ALLM.user("hi")])
...> )
iex> updated = ALLM.Session.submit_tool_results(session, [{"c0", "r0"}, {"c1", "r1"}])
iex> updated.status
:idle
iex> updated.pending_tool_calls
[]