org.llm4s.agent.graph.toolloop

A reviewer's answer. Edit runs the call with new arguments, recording them in the assistant message first.

The question an approval interrupt asks: one tool call, from one assistant message.

Who asked for an approval. Both kinds resume at the same approval node.

A tool the loop can call. Stage 0 prototype of the agent-level tool contract: (#1271) replaces it with the typed, schema-validated AgentTool[A]. approved is true when a human approved this call, so a tool that asks for approval must not ask again.

An operation on the message history, applied to the committed value in commit order.

The model call: the conversation so far to the next assistant message.

A conversation message with a stable, graph-owned id. Core org.llm4s.llmconnect.model.Message stays id-free; ids exist so operations can name the message they change, and are derived from the task that wrote the message so a re-run produces the same ids.

Decides each call before it runs - the policy-middleware stand-in until (#1271)'s AgentMiddleware.

The model/tool loop as a graph - the Stage 0 proof of runtime-owned tool results and resumable approval ((#1269)):

input -> model --fan-out, one task per call--> call-tool --(dynamic join "tool-batch")--> collect -> model
                                                  \--suspend--> approval --/

• Each call is its own task: policy first, then the tool. A policy RequireApproval and a tool's NeedsApproval both suspend the call with an ApprovalRequest and resume at the one approval node, whose continuation fills that call's slot in the batch barrier.
• The loop, not the tool, records exactly one ToolResult per call - for success, failure, denial, rejection and unknown tools alike; the results key refuses a second one.
• collect runs only when the barrier releases, checks every call of the batch has exactly one result, and appends the ToolMessages in call order. The model never sees a partial batch.
• The model node re-checks the history with Message.validateConversation before every call.

What a tool did. Tools return content, never ToolMessages: the loop writes every result message.

The result the loop wrote for one call, waiting for the batch barrier.

One model-issued tool call, scheduled as its own task.