RFC: Structured MsgContext and Decomposition of CombinedBody

Problem Statement

Currently, several gateway providers (WhatsApp, Discord) construct a combinedBody string by concatenating historical context, message envelopes, the current message, and sender metadata. This single string is passed as the Body in MsgContext.

Downstream consumers, such as command detection (/status, /help, /reset) and directive parsing, must then attempt to "deconstruct" this string or use side-channels like RawBody (recently added to WhatsApp in c4cd50b6) to find the actual user intent. This leads to fragile regex-based prefix stripping and inconsistent behavior across providers.

Architecture Comparison

Current (Fragile)

1. Provider: Fetches history + current msg.
2. Provider: Formats into combinedBody (e.g. [History]\n[Envelope] User: /status\n[from: Name]).
3. Core: Receives combinedBody.
4. Core: Strips prefixes to guess clean message for command detection.
5. LLM: Receives combinedBody directly.

Proposed (Structured)

1. Provider: Extracts clean MessageBody.
2. Provider: Collects HistoryEntries[] and SenderContext as typed objects.
3. Core: Receives structured MsgContext. Command detection runs on clean MessageBody.
4. Agent Runner: Composes the final prompt for the LLM using a standardized template/envelope logic.

Drivers

• Reliability: Command detection (e.g., /status, /help) should not depend on how a provider stringifies history.
• Consistency: Discord, Slack, and WhatsApp should share the same logic for presenting context to the LLM.
• Maintainability: Moving "Agent Envelope" formatting out of providers reduces duplicate logic and makes it easier to change the "AI's view" of the world in one place.
• Testability: Easier to unit test command detection without simulating complex stringified envelopes.

Impacts & Concerns

• Provider Refactoring: src/web/auto-reply.ts, src/discord/monitor.ts, src/slack/monitor.ts, and src/telegram/bot.ts all need updates to their inbound message handlers.
• MsgContext Schema: Requires a pervasive change to the MsgContext and TemplateContext types in src/auto-reply/templating.ts.
• LLM Prompt Stability: We must ensure that the downstream composition logic (AgentRunner) produces a prompt that performs as well as the current manual stringification.
• Regression Risk: Moderate. Changing the input to the LLM can affect agent behavior.

Implementation Note

We are currently working on submitting a temporary band-aid PR (and tests) to solve an immediate issue for WhatsApp where the combinedBody approach is causing /commands to fail in group chats. However, we seek alignment on this overall architectural approach to improve codebase health and prevent similar regressions in other providers (like Discord, which currently lacks a RawBody fallback).

Note from Agent

I am an AI coding agent assisting with the maintenance of Clawdbot. This RFC was generated after identifying the root cause of recent command detection regressions in group chat environments.