@spec run_tool_calls([ALLM.ToolCall.t()], [ALLM.Tool.t()], run_opts()) ::
  run_outcome()

Execute a batch of tool calls synchronously and return :tool-role messages in input order.

Pre-flights the batch by looking up each %ToolCall{} name against tools; if any lookup fails the function returns {:error, %ALLM.Error.EngineError{reason: :unknown_tool}} synchronously and no tool runs. An empty tool_calls list is a short-circuit: {:ok, []}.

Opts

| :on_tool_error | :continue | :continue, :halt, or (tool_call, error -> {:continue, term} | :halt) (Phase 7). | | :tool_timeout | 30_000 | Milliseconds before Task.async_stream/5 kills a task. Timed-out tasks surface as %ToolError{reason: :timeout}. | | :max_concurrency | max(1, min(length(tool_calls), System.schedulers_online() * 2)) | Upper bound on concurrent handler invocations. | | :context | engine.context | Passed to arity-2 handlers. | | :session_id | nil | Phase 6 — session integration lands in Phase 8. | | :request_id | nil | Forwarded from the adapter's Response.request_id. |

Error reason table

Examples

iex> engine = ALLM.Engine.new(adapter: ALLM.Providers.Fake)
iex> tool = ALLM.Tool.new(
...>   name: "echo",
...>   description: "",
...>   schema: %{},
...>   handler: fn args -> {:ok, args} end
...> )
iex> call = ALLM.ToolCall.new(id: "c0", name: "echo", arguments: %{"x" => 1})
iex> {:ok, [msg]} = ALLM.ToolRunner.run_tool_calls([call], [tool], engine: engine)
iex> msg.role
:tool
iex> msg.tool_call_id
"c0"
iex> Jason.decode!(msg.content)
%{"x" => 1}

@spec stream_tool_calls([ALLM.ToolCall.t()], [ALLM.Tool.t()], run_opts()) ::
  Enumerable.t()

Execute a batch of tool calls and return a lazy stream of ALLM.Event values. Events per tool call (in start order for each id, interleaved across ids in completion order):

• {:tool_execution_started, %{id, name, arguments}}
• {:tool_execution_completed, %{id, name, result}}
• One of:
  • {:tool_result_encoded, %{id, content}} — normal handler return (including {:error, _} routed via on_tool_error)
  • {:ask_user_requested, %{tool_call_id, tool_name, question, opts}} — handler returned {:ask_user, _} / {:ask_user, _, _}
  • {:tool_halt, %{tool_call_id, reason, result}} — handler returned {:halt, reason, result}

Pre-flight errors

On unknown tool (Invariant 2), the stream contains a single {:error, %ALLM.Error.EngineError{reason: :unknown_tool}} element and terminates. No tools execute.

Timeout semantics

A tool whose handler exceeds tool_timeout has its task killed by Task.async_stream/5's :on_timeout: :kill_task option. The event stream emits {:tool_execution_completed, %{result: {:error, %ToolError{reason: :timeout}}}} — no new :tool_execution_cancelled variant (Phase 6 keeps the ALLM.Event closed union at 16 tags; see PHASE_6_DESIGN.md Non-obvious Decision #7).

Empty short-circuit

stream_tool_calls([], _, _) returns Stream.concat([]) — an empty enumerable — without invoking Task.async_stream/5.

Examples

iex> engine = ALLM.Engine.new(adapter: ALLM.Providers.Fake)
iex> tool = ALLM.Tool.new(
...>   name: "echo",
...>   description: "",
...>   schema: %{},
...>   handler: fn args -> {:ok, args} end
...> )
iex> call = ALLM.ToolCall.new(id: "c0", name: "echo", arguments: %{"x" => 1})
iex> events =
...>   [call]
...>   |> ALLM.ToolRunner.stream_tool_calls([tool], engine: engine)
...>   |> Enum.to_list()
iex> Enum.map(events, &elem(&1, 0))
[:tool_execution_started, :tool_execution_completed, :tool_result_encoded]