Anatomy of a turn

Two words to pin down first, because everything else follows from them.

• Step One request One call to the model plus the tools it calls as a result
• Turn Several steps From the moment you ask for something until nothing is pending. It can contain several steps, or none

Anatomy of a turn

Expand ⤢

The sequence

The turn opens. Whatever you wrote is picked up. The instructions and the list of available tools are assembled.

Before anything is sent, there is a point where any installed piece can rewrite what the model is about to see, or reject it outright.

If it passes, a step opens. Your message is written to the log. The history the model will see is built. The request goes out and the answer arrives in fragments, which are stored too.

If the model asks for a tool, that request goes through three phases: one where permission is decided, one where it runs and one where the result can be transformed. The result is written to the log.

The step closes. And if the tools left something pending, another one opens. That is where a turn stretches out: every step is another request to the model, with its own cost.

When nothing is left, the turn closes.

The detail that says the most about the design

If the pre-flight filter rejects your message, the turn closes anyway and is recorded, even though not a single request ever reached the model.

What never ran can be audited too.

Technical detail optional

Turn, step, message and tool events are durable and get written to the log. The rest are live extension points. Six of them work as wrapping middleware and their listeners have to delegate explicitly for the chain to continue. The event that announces the end of the turn is the exception: it runs in order and does not delegate.