Router semantics

Established 2026-07-23. Canonical definitions for the Weave Router codebase and documentation. These terms replace the historical usage where "turn" often meant a single upstream API request.

Terms

Term	Definition	Notes
Session	The full conversation between a user and an agent.	Identified by session_id. Spans many rounds.
Round	One user-agent interaction within a session.	Typically one user turn followed by one agent turn.
Turn	A single user input or a single agent output within a round.	E.g. a user message (U1) or an agent response (A1).
Action	A single agent API request to an upstream model.	One POST /v1/messages, POST /v1/chat/completions, or generateContent call. This is the router's finest addressable routing grain.
Step	An action within a turn, addressed by its ordinal position.	An agent turn is made of one or more steps; each step is one action. A1_S3 = agent turn 1, step 3 (its 3rd action).

Action vs. step. An action and a step denote the same physical unit — one upstream API request. "Action" names what it is (a single agent API request, the routable grain); "step" names where it sits (its ordinal position within a turn). Use "action" when talking about routing; use "step" when addressing a specific request inside a turn.

Hierarchy

Session
  └── Round (one user-agent interaction)
        └── Turn (one user input or one agent output)
              └── Step (one action within the turn = one upstream API request)

A session contains many rounds. Each round is typically one user turn plus one agent turn. An agent turn is made of one or more steps, and each step is a single action — one upstream API request that the router routes independently.

Notation

Turns are labeled by actor and index; steps and subagents nest after them with _-separated segments.

Label	Meaning
U1	User turn 1
A1	Agent turn 1
A1_S3	Agent turn 1, step 3 (its 3rd action)
A2_S4_SA1_S1	Agent turn 2, step 4, subagent 1, step 1
A2_S4_SA2_S1	Agent turn 2, step 4, subagent 2, step 1

Segment prefixes: U = user turn, A = agent turn, S = step, SA = subagent. When a step spawns subagents, each subagent carries its own steps (..._SA<n>_S<m>), so the two subagents launched from A2_S4 above are A2_S4_SA1_S1 and A2_S4_SA2_S1.

What the router routes

The router makes a decision per action (i.e. per step): for every inbound API request, it selects a model and provider. It does not route per turn, per round, or per session, though it may use session-level state (e.g. the session pin) to inform the per-action decision.

Legacy naming

Some existing code and older documentation still uses "turn" to mean what we now call an action / step (a single upstream API request). Notable historical names:

• internal/router/turntype — classifies an action based on the kind of step it handles (e.g. MainLoop, ToolResult). A future rename to actiontype would align with these semantics.
• "per-turn routing" / "per-turn orchestration" in older docs means per-action routing.
• "turn loop" in internal/proxy means the action loop that processes one inbound API request.

New code, documentation, and telemetry should use the terms above. When touching legacy docs, prefer updating them to the new terminology or adding a note that they use the pre-2026-07-23 convention.