Fixing Outbound Session Mirroring for Better Message Routing

I have been working on a fix for a common headache: messages ending up in the wrong place. If you have ever sent a response from an agent or a tool only to find it didn’t show up in the right thread, you know how annoying it is. Usually, this happens because the system tracks the “tool session” instead of the actual conversation session where the user is waiting.

I updated the core and plugin channel routing to handle outbound mirroring correctly. Now, outbound messages land in the target channel session rather than the current agent session. This keeps the conversation history together and makes sure first-contact targets actually have session entries.

What You’ll Need

• Access to the project source code, specifically src/infra/outbound/.
• Core channels or bundled extensions like Slack, Discord, Telegram, or Mattermost.

Quick Start

I simplified the process so that outbound messages automatically find their way home. Here is the 4-step logic I implemented:

1. Resolve the Route: Use resolveOutboundSessionRoute in src/infra/outbound/outbound-session.ts. This builds the target sessionKey using buildAgentSessionKey based on your DM scope and identity links.
2. Ensure the Entry: Call ensureOutboundSessionEntry to write the required MsgContext. This uses recordSessionMetaFromInbound to keep the metadata aligned with how inbound messages are stored.
3. Derive the Key: Update your send actions to use runMessageAction. It now derives the target sessionKey and passes it to executeSendAction for mirroring.
4. Lowercase Everything: Always canonicalize your session keys to lowercase on write to prevent casing mismatches.

Troubleshooting

Messages landing in the wrong session

If your outbound responses are disconnected from the inbound thread, check if you are omitting the sessionKey. I updated the Gateway send to derive a target session key from the target and default agent when one isn’t provided. This ensures the message mirrors to the right place.

Missing session entries for new contacts

If you send a message to a new user and no session is created, make sure you are using ensureOutboundSessionEntry. This writes the necessary Provider, From, To, and ChatType metadata so the session exists in the database immediately.

What’s Next

• Check src/infra/outbound/outbound-session.test.ts for Slack thread and Telegram topic examples.
• Review the message-tool.ts updates to see how agentId is derived from session keys.
• Look into the gateway/server-methods/send.ts logic for default agent session derivation.
• Verify specific channel handling for Mattermost, BlueBubbles, Zalo, or Discord.

If you need help setting this up in your specific environment, check out the AI Setup Assistant.