clawdbot/docs/refactor/channel-unify.md

summary, read_when

summary	read_when
Checklist for unifying messaging channel logic	Planning refactors across channel implementations Standardizing shared message handling behavior

Channel unification checklist

Purpose: centralize repeated messaging logic so core + extensions stay consistent, testable, and easier to evolve.

Ack reactions (already centralized)

• Shared gating helper for core channels.
• Shared gating helper for extensions.
• WhatsApp-specific gating helper (direct/group/mentions) aligned with activation.
• Optional: centralize “remove after reply” behavior (see below).

Ack reaction removal (after reply)

Problem: duplicated logic across Discord, Slack, Telegram, BlueBubbles.

• Create channel.reactions.removeAfterReply() helper that accepts:
  • removeAckAfterReply flag
  • ack promise + result boolean
  • channel-specific remove fn + ids
• Wire in:
  • src/discord/monitor/message-handler.process.ts
  • src/slack/monitor/message-handler/dispatch.ts
  • src/telegram/bot-message-dispatch.ts
  • extensions/bluebubbles/src/monitor.ts
• Add unit tests for the helper (success + ack-failed paths).

Pending history buffering + flush

Problem: repeated “record pending history”, “prepend pending history”, and “clear history” patterns.

• Identify shared flow in:
  • src/discord/monitor/message-handler.preflight.ts
  • src/discord/monitor/message-handler.process.ts
  • src/slack/monitor/message-handler/prepare.ts
  • src/telegram/bot-message-context.ts
  • src/signal/monitor/event-handler.ts
  • src/imessage/monitor/monitor-provider.ts
  • extensions/mattermost/src/mattermost/monitor.ts
  • src/web/auto-reply/monitor/group-gating.ts
• Add helper(s) to src/auto-reply/reply/history.ts:
  • recordPendingIfBlocked() (accepts allowlist/mention gating reason)
  • mergePendingIntoBody() (returns combined body)
  • clearPendingHistory() (wrapper to standardize historyKey, limits)
• Ensure per-channel metadata (sender label, timestamps, messageId) preserved.
• Add tests for helper(s); keep per-channel smoke tests.

Typing lifecycle

Problem: inconsistent typing start/stop handling and error logging.

• Add a shared typing adapter in core (ex: src/channels/typing.ts) that accepts:
  • startTyping / stopTyping callbacks
  • onReplyStart / onReplyIdle hooks from dispatcher
  • TTL + interval config (reuse auto-reply/reply/typing machinery)
• Wire in:
  • Discord (src/discord/monitor/typing.ts)
  • Slack (src/slack/monitor/message-handler/dispatch.ts)
  • Telegram (dispatch flow)
  • Signal (src/signal/monitor/event-handler.ts)
  • Matrix (extensions/matrix/src/matrix/monitor/handler.ts)
  • Mattermost (extensions/mattermost/src/mattermost/monitor.ts)
  • BlueBubbles (extensions/bluebubbles/src/monitor.ts)
  • MS Teams (extensions/msteams/src/reply-dispatcher.ts)
• Add helper tests for start/stop and error handling.

Reply dispatcher wiring

Problem: channels hand-roll dispatcher glue; varies in error handling and typing.

• Add a shared wrapper that builds:
  • reply dispatcher
  • response prefix context
  • table mode conversion
• Adopt in:
  • Discord, Slack, Telegram (core)
  • BlueBubbles, Matrix, Mattermost (extensions)
• Keep per-channel delivery adapter (send message / chunking).

Session meta + last route updates

Problem: repeated patterns for recordSessionMetaFromInbound and updateLastRoute.

• Add helper channel.session.recordInbound() that accepts:
  • storePath, sessionKey, ctx
  • optional channel/accountId/target for updateLastRoute
• Wire in:
  • Discord, Slack, Telegram, Matrix, BlueBubbles

Control command gating patterns

Problem: similar gating flow per channel (allowlists + commands).

• Add a helper that merges:
  • allowlist checks
  • command gating decisions
  • mention bypass evaluation
• Keep channel-specific identity/user resolution separate.

Error + verbose logging

Problem: inconsistent message formats across channels.

• Define canonical log helpers:
  • logInboundDrop(reason, meta)
  • logAckFailure(meta)
  • logTypingFailure(meta)
• Apply to all channel handlers.

Docs + SDK

• Expose new helpers through src/plugin-sdk/index.ts + plugin runtime.
• Update docs/tools/reactions.md if ack semantics expand.
• Add read_when hints if new cross-cutting helpers are introduced.