Routing

One-line summary

The routing system maps inbound messages to agent + session pairs through a multi-tier binding priority chain: peer > guild+roles > guild > team > account > channel > default.

Responsibilities

Resolve which agent handles a message based on channel, account, peer, guild, team, and roles
Build session keys that encode the full routing context (agent, channel, chat type, identity)
Support DM session scoping (main, per-peer, per-channel-peer, per-account-channel-peer)
Handle thread parent inheritance for nested contexts
Manage identity linking across channels

Architecture diagram

Key source files

File	Lines	Role
`src/routing/resolve-route.ts`	443	Main resolver: `resolveAgentRoute()`, binding matching, DM scope resolution
`src/routing/bindings.ts`	113	Binding queries: `listBindings()`, `listBoundAccountIds()`, account resolution
`src/routing/session-key.ts`	241	Session keys: `buildAgentMainSessionKey()`, `buildAgentPeerSessionKey()`, key parsing, normalization

Session key format

agent:<agentId>:<channel>:<chatType>:<identifier>

Examples:
  agent:main:main                                    (main session)
  agent:main:telegram:direct:user123                 (DM per-peer)
  agent:main:telegram:account1:direct:user123        (DM per-account-channel-peer)
  agent:main:telegram:group:chat456                  (group)
  agent:main:telegram:group:chat456:thread:thread789 (thread)

Constraints: 64-char limit, path-safe, shell-friendly characters.

Binding priority chain

1. binding.peer         — exact peer match (highest priority)
2. binding.peer.parent  — thread parent inheritance
3. binding.guild+roles  — guild + member role match
4. binding.guild        — guild-only match
5. binding.team         — team match
6. binding.account      — account match
7. binding.channel      — channel match
8. default              — fallback to default agent

How it connects to other modules

Depends on: config/ (bindings configuration), channels/ (chat type normalization)
Depended by: auto-reply/ (resolves route before dispatching), sessions/ (session key parsing)

Identity linking — how cross-channel identity resolution works
Caching behavior in resolveAgentRoute() — whether results are cached
Legacy key migration — how old session key formats are handled

Change frequency

resolve-route.ts: Medium — new binding types added with features
session-key.ts: Medium — new key formats for new session types
bindings.ts: Low — query utilities are stable

#Routing

#One-line summary

#Responsibilities

#Architecture diagram

#Key source files

#Session key format

#Binding priority chain

#How it connects to other modules

#My blind spots

#Change frequency