AgentMiddleware

A middleware that asks typed questions of type Q and takes answers of type Ans, as org.llm4s.agent.graph.tool.AgentTool.Asking does for a tool: it suspends the run for a reviewer - to approve or edit an answer, or to supply missing information - instead of only blocking or failing.

A hook asks by returning ask - from beforeAgent, afterAgent or wrapModelCall - or askAbout from wrapToolCall. The run suspends at the end of the superstep with a question of its own, keyed by the asking task's interrupt id like any other, so several pending questions are answered together or one at a time. The answer is decoded as Ans when the run is resumed: one that does not decode is refused, the thread unchanged.

Once answered, the hook's whole stack runs again from the outermost middleware - nothing about a stack's position is checkpointed, as for approvals - and answered gives this middleware its question and answer, so it continues instead of asking again. Answers given earlier in the same stack run are kept while it runs again, so two asking middleware in one stack each ask once. A middleware outside the asking one therefore runs twice, and must not depend on running once.

What runs again is the asking task: beforeAgent re-runs the turn's input (nothing of the turn is stored while it waits), afterAgent the final answer, wrapToolCall the tool call (its arguments checked again), and wrapModelCall the model call - so a model wrapper that asks after calling next calls the model again once answered, unless it returns a completion of its own (the calls made before asking are counted in the thread's usage, and announced, while the question waits). A question from a tool wrapper while the tool continues after its own question is refused, as the call's error result.