ChannelRouter

Resolves the target agentId and stable MsgContext for an InboundMessage by evaluating ChannelBinding rules in deterministic priority order.

Binding evaluation tiers (highest to lowest priority)

• explicit — InboundMessage#preferredAgentId() short-circuit when the caller has already nominated a specific agent. Bindings are still consulted to determine sessionScope and outbound addressing.

• peer — exact Peer#key() match (e.g. "direct:u_42")

• peer.parent — exact match on the thread-parent peer's key

• guild + roles — guild id matches AND sender holds at least one of the binding's roles

• guild — guild id matches (no role constraint)

• team — team id matches

• account — account id matches

• channel — channel id matches

• default — ChannelConfig#defaultAgentId() or globalDefaultAgentId

Within each tier the first binding in ChannelConfig#bindings() list order that matches wins.

Session key construction (MsgContext)

After resolving agentId, the router builds a MsgContext whose MsgContext#canonicalKey() produces a stable session key:

• DM + DmScope#MAIN — channel field only; all DMs share one session

• DM + other scopes — room = peerId (optionally group = accountId)

• Thread — room = parentPeer id, threadId = peer id

• Non-DM channel/group — room = peer id, group = guild

The resolved agentId is always included in MsgContext#extra() under key "agentId" so that the gateway can pick the correct agent from its registry.