badgerclaw 0.1.7 → 1.4.0

package/src/matrix/monitor/handler.ts

@@ -0,0 +1,847 @@
+import type { LocationMessageEventContent, MatrixClient } from "@vector-im/matrix-bot-sdk";
+import {
+  DEFAULT_ACCOUNT_ID,
+  createScopedPairingAccess,
+  createReplyPrefixOptions,
+  createTypingCallbacks,
+  dispatchReplyFromConfigWithSettledDispatcher,
+  evaluateGroupRouteAccessForPolicy,
+  formatAllowlistMatchMeta,
+  logInboundDrop,
+  logTypingFailure,
+  resolveInboundSessionEnvelopeContext,
+  resolveControlCommandGate,
+  type PluginRuntime,
+  type RuntimeEnv,
+  type RuntimeLogger,
+} from "openclaw/plugin-sdk/matrix";
+import type { CoreConfig, MatrixRoomConfig, ReplyToMode } from "../../types.js";
+import { fetchEventSummary } from "../actions/summary.js";
+import {
+  formatPollAsText,
+  isPollStartType,
+  parsePollStartContent,
+  type PollStartContent,
+} from "../poll-types.js";
+import { reactMatrixMessage, sendMessageMatrix, sendTypingMatrix } from "../send.js";
+import { enforceMatrixDirectMessageAccess, resolveMatrixAccessState } from "./access-policy.js";
+import {
+  normalizeMatrixAllowList,
+  resolveMatrixAllowListMatch,
+  resolveMatrixAllowListMatches,
+} from "./allowlist.js";
+import { appendHistory, formatHistoryForContext } from "./chat-history.js";
+import {
+  resolveMatrixBodyForAgent,
+  resolveMatrixInboundSenderLabel,
+  resolveMatrixSenderUsername,
+} from "./inbound-body.js";
+import { resolveMatrixLocation, type MatrixLocationPayload } from "./location.js";
+import { downloadMatrixMedia } from "./media.js";
+import { resolveMentions } from "./mentions.js";
+import { deliverMatrixReplies } from "./replies.js";
+import { resolveMatrixRoomConfig } from "./rooms.js";
+import { resolveMatrixThreadRootId, resolveMatrixThreadTarget } from "./threads.js";
+import type { MatrixRawEvent, RoomMessageEventContent } from "./types.js";
+import { EventType, RelationType } from "./types.js";
+
+export type MatrixMonitorHandlerParams = {
+  client: MatrixClient;
+  core: PluginRuntime;
+  cfg: CoreConfig;
+  runtime: RuntimeEnv;
+  logger: RuntimeLogger;
+  logVerboseMessage: (message: string) => void;
+  allowFrom: string[];
+  roomsConfig: Record<string, MatrixRoomConfig> | undefined;
+  mentionRegexes: ReturnType<PluginRuntime["channel"]["mentions"]["buildMentionRegexes"]>;
+  groupPolicy: "open" | "allowlist" | "disabled";
+  replyToMode: ReplyToMode;
+  threadReplies: "off" | "inbound" | "always";
+  dmEnabled: boolean;
+  dmPolicy: "open" | "pairing" | "allowlist" | "disabled";
+  textLimit: number;
+  mediaMaxBytes: number;
+  startupMs: number;
+  startupGraceMs: number;
+  directTracker: {
+    isDirectMessage: (params: {
+      roomId: string;
+      senderId: string;
+      selfUserId: string;
+    }) => Promise<boolean>;
+  };
+  getRoomInfo: (
+    roomId: string,
+  ) => Promise<{ name?: string; canonicalAlias?: string; altAliases: string[] }>;
+  getMemberDisplayName: (roomId: string, userId: string) => Promise<string>;
+  accountId?: string | null;
+};
+
+export function resolveMatrixBaseRouteSession(params: {
+  buildAgentSessionKey: (params: {
+    agentId: string;
+    channel: string;
+    accountId?: string | null;
+    peer?: { kind: "direct" | "channel"; id: string } | null;
+  }) => string;
+  baseRoute: {
+    agentId: string;
+    sessionKey: string;
+    mainSessionKey: string;
+    matchedBy?: string;
+  };
+  isDirectMessage: boolean;
+  roomId: string;
+  accountId?: string | null;
+}): { sessionKey: string; lastRoutePolicy: "main" | "session" } {
+  const sessionKey =
+    params.isDirectMessage && params.baseRoute.matchedBy === "binding.peer.parent"
+      ? params.buildAgentSessionKey({
+          agentId: params.baseRoute.agentId,
+          channel: "badgerclaw",
+          accountId: params.accountId,
+          peer: { kind: "channel", id: params.roomId },
+        })
+      : params.baseRoute.sessionKey;
+  return {
+    sessionKey,
+    lastRoutePolicy: sessionKey === params.baseRoute.mainSessionKey ? "main" : "session",
+  };
+}
+
+export function shouldOverrideMatrixDmToGroup(params: {
+  isDirectMessage: boolean;
+  roomConfigInfo?:
+    | {
+        config?: MatrixRoomConfig;
+        allowed: boolean;
+        matchSource?: string;
+      }
+    | undefined;
+}): boolean {
+  return (
+    params.isDirectMessage === true &&
+    params.roomConfigInfo?.config !== undefined &&
+    params.roomConfigInfo.allowed === true &&
+    params.roomConfigInfo.matchSource === "direct"
+  );
+}
+
+export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParams) {
+  const {
+    client,
+    core,
+    cfg,
+    runtime,
+    logger,
+    logVerboseMessage,
+    allowFrom,
+    roomsConfig,
+    mentionRegexes,
+    groupPolicy,
+    replyToMode,
+    threadReplies,
+    dmEnabled,
+    dmPolicy,
+    textLimit,
+    mediaMaxBytes,
+    startupMs,
+    startupGraceMs,
+    directTracker,
+    getRoomInfo,
+    getMemberDisplayName,
+    accountId,
+  } = params;
+  const resolvedAccountId = accountId?.trim() || DEFAULT_ACCOUNT_ID;
+  const pairing = createScopedPairingAccess({
+    core,
+    channel: "badgerclaw",
+    accountId: resolvedAccountId,
+  });
+
+  return async (roomId: string, event: MatrixRawEvent) => {
+    try {
+      const eventType = event.type;
+      if (eventType === EventType.RoomMessageEncrypted) {
+        // Encrypted messages are decrypted automatically by @vector-im/matrix-bot-sdk with crypto enabled
+        return;
+      }
+
+      const isPollEvent = isPollStartType(eventType);
+      const locationContent = event.content as unknown as LocationMessageEventContent;
+      const isLocationEvent =
+        eventType === EventType.Location ||
+        (eventType === EventType.RoomMessage && locationContent.msgtype === EventType.Location);
+      if (eventType !== EventType.RoomMessage && !isPollEvent && !isLocationEvent) {
+        return;
+      }
+      logVerboseMessage(
+        `badgerclaw: room.message recv room=${roomId} type=${eventType} id=${event.event_id ?? "unknown"}`,
+      );
+      if (event.unsigned?.redacted_because) {
+        return;
+      }
+      const senderId = event.sender;
+      if (!senderId) {
+        return;
+      }
+      const selfUserId = await client.getUserId();
+      if (senderId === selfUserId) {
+        return;
+      }
+      const eventTs = event.origin_server_ts;
+      const eventAge = event.unsigned?.age;
+      if (typeof eventTs === "number" && eventTs < startupMs - startupGraceMs) {
+        return;
+      }
+      if (
+        typeof eventTs !== "number" &&
+        typeof eventAge === "number" &&
+        eventAge > startupGraceMs
+      ) {
+        return;
+      }
+
+      const roomInfo = await getRoomInfo(roomId);
+      const roomName = roomInfo.name;
+      const roomAliases = [roomInfo.canonicalAlias ?? "", ...roomInfo.altAliases].filter(Boolean);
+
+      let content = event.content as unknown as RoomMessageEventContent;
+      if (isPollEvent) {
+        const pollStartContent = event.content as unknown as PollStartContent;
+        const pollSummary = parsePollStartContent(pollStartContent);
+        if (pollSummary) {
+          pollSummary.eventId = event.event_id ?? "";
+          pollSummary.roomId = roomId;
+          pollSummary.sender = senderId;
+          const senderDisplayName = await getMemberDisplayName(roomId, senderId);
+          pollSummary.senderName = senderDisplayName;
+          const pollText = formatPollAsText(pollSummary);
+          content = {
+            msgtype: "m.text",
+            body: pollText,
+          } as unknown as RoomMessageEventContent;
+        } else {
+          return;
+        }
+      }
+
+      const locationPayload: MatrixLocationPayload | null = resolveMatrixLocation({
+        eventType,
+        content: content as LocationMessageEventContent,
+      });
+
+      const relates = content["m.relates_to"];
+      if (relates && "rel_type" in relates) {
+        if (relates.rel_type === RelationType.Replace) {
+          return;
+        }
+      }
+
+      let isDirectMessage = await directTracker.isDirectMessage({
+        roomId,
+        senderId,
+        selfUserId,
+      });
+
+      // Resolve room config early so explicitly configured rooms can override DM classification.
+      // This ensures rooms in the groups config are always treated as groups regardless of
+      // member count or protocol-level DM flags. Only explicit matches (not wildcards) trigger
+      // the override to avoid breaking DM routing when a wildcard entry exists. (See #9106)
+      const roomConfigInfo = resolveMatrixRoomConfig({
+        rooms: roomsConfig,
+        roomId,
+        aliases: roomAliases,
+        name: roomName,
+      });
+      if (shouldOverrideMatrixDmToGroup({ isDirectMessage, roomConfigInfo })) {
+        logVerboseMessage(
+          `badgerclaw: overriding DM to group for configured room=${roomId} (${roomConfigInfo.matchKey})`,
+        );
+        isDirectMessage = false;
+      }
+
+      const isRoom = !isDirectMessage;
+
+      if (isRoom && groupPolicy === "disabled") {
+        return;
+      }
+      // Only expose room config for confirmed group rooms. DMs should never inherit
+      // group settings (skills, systemPrompt, autoReply) even when a wildcard entry exists.
+      const roomConfig = isRoom ? roomConfigInfo?.config : undefined;
+      const roomMatchMeta = roomConfigInfo
+        ? `matchKey=${roomConfigInfo.matchKey ?? "none"} matchSource=${
+            roomConfigInfo.matchSource ?? "none"
+          }`
+        : "matchKey=none matchSource=none";
+
+      if (isRoom) {
+        const routeAccess = evaluateGroupRouteAccessForPolicy({
+          groupPolicy,
+          routeAllowlistConfigured: Boolean(roomConfigInfo?.allowlistConfigured),
+          routeMatched: Boolean(roomConfig),
+          routeEnabled: roomConfigInfo?.allowed ?? true,
+        });
+        if (!routeAccess.allowed) {
+          if (routeAccess.reason === "route_disabled") {
+            logVerboseMessage(`badgerclaw: room disabled room=${roomId} (${roomMatchMeta})`);
+          } else if (routeAccess.reason === "empty_allowlist") {
+            logVerboseMessage(`badgerclaw: drop room message (no allowlist, ${roomMatchMeta})`);
+          } else if (routeAccess.reason === "route_not_allowlisted") {
+            logVerboseMessage(`badgerclaw: drop room message (not in allowlist, ${roomMatchMeta})`);
+          }
+          return;
+        }
+      }
+
+      const senderName = await getMemberDisplayName(roomId, senderId);
+      const senderUsername = resolveMatrixSenderUsername(senderId);
+      const senderLabel = resolveMatrixInboundSenderLabel({
+        senderName,
+        senderId,
+        senderUsername,
+      });
+      const groupAllowFrom = cfg.channels?.badgerclaw?.groupAllowFrom ?? [];
+      const { access, effectiveAllowFrom, effectiveGroupAllowFrom, groupAllowConfigured } =
+        await resolveMatrixAccessState({
+          isDirectMessage,
+          resolvedAccountId,
+          dmPolicy,
+          groupPolicy,
+          allowFrom,
+          groupAllowFrom,
+          senderId,
+          readStoreForDmPolicy: pairing.readStoreForDmPolicy,
+        });
+
+      if (isDirectMessage) {
+        const allowedDirectMessage = await enforceMatrixDirectMessageAccess({
+          dmEnabled,
+          dmPolicy,
+          accessDecision: access.decision,
+          senderId,
+          senderName,
+          effectiveAllowFrom,
+          upsertPairingRequest: pairing.upsertPairingRequest,
+          sendPairingReply: async (text) => {
+            await sendMessageMatrix(`room:${roomId}`, text, { client });
+          },
+          logVerboseMessage,
+        });
+        if (!allowedDirectMessage) {
+          return;
+        }
+      }
+
+      const roomUsers = roomConfig?.users ?? [];
+      if (isRoom && roomUsers.length > 0) {
+        const userMatch = resolveMatrixAllowListMatch({
+          allowList: normalizeMatrixAllowList(roomUsers),
+          userId: senderId,
+        });
+        if (!userMatch.allowed) {
+          logVerboseMessage(
+            `badgerclaw: blocked sender ${senderId} (room users allowlist, ${roomMatchMeta}, ${formatAllowlistMatchMeta(
+              userMatch,
+            )})`,
+          );
+          return;
+        }
+      }
+      if (isRoom && roomUsers.length === 0 && groupAllowConfigured && access.decision !== "allow") {
+        const groupAllowMatch = resolveMatrixAllowListMatch({
+          allowList: effectiveGroupAllowFrom,
+          userId: senderId,
+        });
+        if (!groupAllowMatch.allowed) {
+          logVerboseMessage(
+            `badgerclaw: blocked sender ${senderId} (groupAllowFrom, ${roomMatchMeta}, ${formatAllowlistMatchMeta(
+              groupAllowMatch,
+            )})`,
+          );
+          return;
+        }
+      }
+      if (isRoom) {
+        logVerboseMessage(`badgerclaw: allow room ${roomId} (${roomMatchMeta})`);
+      }
+
+      const rawBody =
+        locationPayload?.text ?? (typeof content.body === "string" ? content.body.trim() : "");
+      let media: {
+        path: string;
+        contentType?: string;
+        placeholder: string;
+      } | null = null;
+      const contentUrl =
+        "url" in content && typeof content.url === "string" ? content.url : undefined;
+      const contentFile =
+        "file" in content && content.file && typeof content.file === "object"
+          ? content.file
+          : undefined;
+      const mediaUrl = contentUrl ?? contentFile?.url;
+      if (!rawBody && !mediaUrl) {
+        return;
+      }
+
+      const contentInfo =
+        "info" in content && content.info && typeof content.info === "object"
+          ? (content.info as { mimetype?: string; size?: number })
+          : undefined;
+      const contentType = contentInfo?.mimetype;
+      const contentSize = typeof contentInfo?.size === "number" ? contentInfo.size : undefined;
+      if (mediaUrl?.startsWith("mxc://")) {
+        try {
+          media = await downloadMatrixMedia({
+            client,
+            mxcUrl: mediaUrl,
+            contentType,
+            sizeBytes: contentSize,
+            maxBytes: mediaMaxBytes,
+            file: contentFile,
+          });
+        } catch (err) {
+          logVerboseMessage(`badgerclaw: media download failed: ${String(err)}`);
+        }
+      }
+
+      const bodyText = rawBody || media?.placeholder || "";
+      if (!bodyText) {
+        return;
+      }
+
+      // Handle /bot commands before anything else
+      if (bodyText.trim().startsWith("/bot")) {
+        const { handleBotCommand } = await import("./bot-commands.js");
+        const handled = await handleBotCommand({
+          client,
+          roomId,
+          senderId,
+          body: bodyText,
+          selfUserId,
+        });
+        if (handled) return;
+      }
+
+      const { wasMentioned, hasExplicitMention } = resolveMentions({
+        content,
+        userId: selfUserId,
+        text: bodyText,
+        mentionRegexes,
+      });
+      const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+        cfg,
+        surface: "badgerclaw",
+      });
+      const useAccessGroups = cfg.commands?.useAccessGroups !== false;
+      const senderAllowedForCommands = resolveMatrixAllowListMatches({
+        allowList: effectiveAllowFrom,
+        userId: senderId,
+      });
+      const senderAllowedForGroup = groupAllowConfigured
+        ? resolveMatrixAllowListMatches({
+            allowList: effectiveGroupAllowFrom,
+            userId: senderId,
+          })
+        : false;
+      const senderAllowedForRoomUsers =
+        isRoom && roomUsers.length > 0
+          ? resolveMatrixAllowListMatches({
+              allowList: normalizeMatrixAllowList(roomUsers),
+              userId: senderId,
+            })
+          : false;
+      const hasControlCommandInMessage = core.channel.text.hasControlCommand(bodyText, cfg);
+      const commandGate = resolveControlCommandGate({
+        useAccessGroups,
+        authorizers: [
+          { configured: effectiveAllowFrom.length > 0, allowed: senderAllowedForCommands },
+          { configured: roomUsers.length > 0, allowed: senderAllowedForRoomUsers },
+          { configured: groupAllowConfigured, allowed: senderAllowedForGroup },
+        ],
+        allowTextCommands,
+        hasControlCommand: hasControlCommandInMessage,
+      });
+      const commandAuthorized = commandGate.commandAuthorized;
+      if (isRoom && commandGate.shouldBlock) {
+        logInboundDrop({
+          log: logVerboseMessage,
+          channel: "badgerclaw",
+          reason: "control command (unauthorized)",
+          target: senderId,
+        });
+        return;
+      }
+      // Check room-config.json first (set by /bot talk on|off) — it takes priority
+      // over the OpenClaw config wildcard entry. Supports per-bot activeBots list.
+      const roomConfigJsonAutoReply = (() => {
+        try {
+          const fs = require("fs");
+          const path = require("path");
+          const configPath = path.join(
+            process.env.HOME || "/tmp",
+            ".openclaw/extensions/badgerclaw/room-config.json"
+          );
+          const raw = fs.readFileSync(configPath, "utf-8");
+          const roomCfg = JSON.parse(raw) as Record<string, { autoReply?: boolean; activeBots?: string[] }>;
+          const normalizedRoomId = roomId.toLowerCase();
+          const keys = Object.keys(roomCfg);
+          const matchedKey = keys.find((k) => k.toLowerCase() === normalizedRoomId);
+          if (matchedKey) {
+            const entry = roomCfg[matchedKey];
+            // New per-bot format: check if THIS bot is in activeBots
+            if (Array.isArray(entry.activeBots)) {
+              const botActive = entry.activeBots.some(
+                (b: string) => b.toLowerCase() === selfUserId.toLowerCase()
+              );
+              return botActive; // true = this bot auto-replies, false = mention-only
+            }
+            // Legacy format
+            if (typeof entry.autoReply === "boolean") {
+              return entry.autoReply;
+            }
+          }
+        } catch { /* ignore */ }
+        return undefined;
+      })();
+      const shouldRequireMention = isRoom
+        ? roomConfigJsonAutoReply === true
+          ? false
+          : roomConfigJsonAutoReply === false
+            ? true
+            : roomConfig?.autoReply === true
+              ? false
+              : roomConfig?.autoReply === false
+                ? true
+                : typeof roomConfig?.requireMention === "boolean"
+                  ? roomConfig?.requireMention
+                  : true
+        : false;
+      const shouldBypassMention =
+        allowTextCommands &&
+        isRoom &&
+        shouldRequireMention &&
+        !wasMentioned &&
+        !hasExplicitMention &&
+        commandAuthorized &&
+        hasControlCommandInMessage;
+      const canDetectMention = mentionRegexes.length > 0 || hasExplicitMention;
+      if (isRoom && shouldRequireMention && !wasMentioned && !shouldBypassMention) {
+        logger.info("skipping room message", { roomId, reason: "no-mention" });
+        return;
+      }
+
+      const messageId = event.event_id ?? "";
+      const replyToEventId = content["m.relates_to"]?.["m.in_reply_to"]?.event_id;
+      const threadRootId = resolveMatrixThreadRootId({ event, content });
+      const threadTarget = resolveMatrixThreadTarget({
+        threadReplies,
+        messageId,
+        threadRootId,
+        isThreadRoot: false, // @vector-im/matrix-bot-sdk doesn't have this info readily available
+      });
+
+      const baseRoute = core.channel.routing.resolveAgentRoute({
+        cfg,
+        channel: "badgerclaw",
+        accountId,
+        peer: {
+          kind: isDirectMessage ? "direct" : "channel",
+          id: isDirectMessage ? senderId : roomId,
+        },
+        // For DMs, pass roomId as parentPeer so the conversation is bindable by room ID
+        // while preserving DM trust semantics (secure 1:1, no group restrictions).
+        parentPeer: isDirectMessage ? { kind: "channel", id: roomId } : undefined,
+      });
+      const baseRouteSession = resolveMatrixBaseRouteSession({
+        buildAgentSessionKey: core.channel.routing.buildAgentSessionKey,
+        baseRoute,
+        isDirectMessage,
+        roomId,
+        accountId,
+      });
+
+      const route = {
+        ...baseRoute,
+        lastRoutePolicy: baseRouteSession.lastRoutePolicy,
+        sessionKey: threadRootId
+          ? `${baseRouteSession.sessionKey}:thread:${threadRootId}`
+          : baseRouteSession.sessionKey,
+      };
+
+      let threadStarterBody: string | undefined;
+      let threadLabel: string | undefined;
+      let parentSessionKey: string | undefined;
+
+      if (threadRootId) {
+        const existingSession = core.channel.session.readSessionUpdatedAt({
+          storePath: core.channel.session.resolveStorePath(cfg.session?.store, {
+            agentId: baseRoute.agentId,
+          }),
+          sessionKey: route.sessionKey,
+        });
+
+        if (existingSession === undefined) {
+          try {
+            const rootEvent = await fetchEventSummary(client, roomId, threadRootId);
+            if (rootEvent?.body) {
+              const rootSenderName = rootEvent.sender
+                ? await getMemberDisplayName(roomId, rootEvent.sender)
+                : undefined;
+
+              threadStarterBody = core.channel.reply.formatAgentEnvelope({
+                channel: "BadgerClaw",
+                from: rootSenderName ?? rootEvent.sender ?? "Unknown",
+                timestamp: rootEvent.timestamp,
+                envelope: core.channel.reply.resolveEnvelopeFormatOptions(cfg),
+                body: rootEvent.body,
+              });
+
+              threadLabel = `BadgerClaw thread in ${roomName ?? roomId}`;
+              parentSessionKey = baseRoute.sessionKey;
+            }
+          } catch (err) {
+            logVerboseMessage(
+              `badgerclaw: failed to fetch thread root ${threadRootId}: ${String(err)}`,
+            );
+          }
+        }
+      }
+
+      const envelopeFrom = isDirectMessage ? senderName : (roomName ?? roomId);
+      const textWithId = threadRootId
+        ? `${bodyText}\n[badgerclaw event id: ${messageId} room: ${roomId} thread: ${threadRootId}]`
+        : `${bodyText}\n[badgerclaw event id: ${messageId} room: ${roomId}]`;
+      const { storePath, envelopeOptions, previousTimestamp } =
+        resolveInboundSessionEnvelopeContext({
+          cfg,
+          agentId: route.agentId,
+          sessionKey: route.sessionKey,
+        });
+      const body = core.channel.reply.formatInboundEnvelope({
+        channel: "BadgerClaw",
+        from: envelopeFrom,
+        timestamp: eventTs ?? undefined,
+        previousTimestamp,
+        envelope: envelopeOptions,
+        body: textWithId,
+        chatType: isDirectMessage ? "direct" : "channel",
+        senderLabel,
+      });
+
+      const groupSystemPrompt = roomConfig?.systemPrompt?.trim() || undefined;
+
+      // Append inbound user message to chat history
+      if (cfg.chatHistory?.enabled) {
+        appendHistory(roomId, {
+          ts: new Date().toISOString(),
+          role: "user",
+          sender: senderName || senderId,
+          text: bodyText,
+        }, roomName);
+      }
+
+      // Inject rolling history into BodyForAgent context
+      let bodyForAgent = resolveMatrixBodyForAgent({
+        isDirectMessage,
+        bodyText,
+        senderLabel,
+      });
+      if (cfg.chatHistory?.enabled) {
+        const history = formatHistoryForContext(roomId);
+        if (history) {
+          bodyForAgent = history + bodyForAgent;
+        }
+      }
+
+      const ctxPayload = core.channel.reply.finalizeInboundContext({
+        Body: body,
+        BodyForAgent: bodyForAgent,
+        RawBody: bodyText,
+        CommandBody: bodyText,
+        From: isDirectMessage ? `badgerclaw:${senderId}` : `badgerclaw:channel:${roomId}`,
+        To: `room:${roomId}`,
+        SessionKey: route.sessionKey,
+        AccountId: route.accountId,
+        ChatType: threadRootId ? "thread" : isDirectMessage ? "direct" : "channel",
+        ConversationLabel: envelopeFrom,
+        SenderName: senderName,
+        SenderId: senderId,
+        SenderUsername: senderUsername,
+        GroupSubject: isRoom ? (roomName ?? roomId) : undefined,
+        GroupChannel: isRoom ? (roomInfo.canonicalAlias ?? roomId) : undefined,
+        GroupSystemPrompt: isRoom ? groupSystemPrompt : undefined,
+        Provider: "badgerclaw" as const,
+        Surface: "badgerclaw" as const,
+        WasMentioned: isRoom ? wasMentioned : undefined,
+        MessageSid: messageId,
+        ReplyToId: threadTarget ? undefined : (replyToEventId ?? undefined),
+        MessageThreadId: threadTarget,
+        Timestamp: eventTs ?? undefined,
+        MediaPath: media?.path,
+        MediaType: media?.contentType,
+        MediaUrl: media?.path,
+        ...locationPayload?.context,
+        CommandAuthorized: commandAuthorized,
+        CommandSource: "text" as const,
+        OriginatingChannel: "badgerclaw" as const,
+        OriginatingTo: `room:${roomId}`,
+        ThreadStarterBody: threadStarterBody,
+        ThreadLabel: threadLabel,
+        ParentSessionKey: parentSessionKey,
+      });
+
+      await core.channel.session.recordInboundSession({
+        storePath,
+        sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+        ctx: ctxPayload,
+        updateLastRoute: isDirectMessage
+          ? {
+              sessionKey: route.mainSessionKey,
+              channel: "badgerclaw",
+              to: `room:${roomId}`,
+              accountId: route.accountId,
+            }
+          : undefined,
+        onRecordError: (err) => {
+          logger.warn("failed updating session meta", {
+            error: String(err),
+            storePath,
+            sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+          });
+        },
+      });
+
+      const preview = bodyText.slice(0, 200).replace(/\n/g, "\\n");
+      logVerboseMessage(`badgerclaw inbound: room=${roomId} from=${senderId} preview="${preview}"`);
+
+      const ackReaction = (cfg.messages?.ackReaction ?? "").trim();
+      const ackScope = cfg.messages?.ackReactionScope ?? "group-mentions";
+      const shouldAckReaction = () =>
+        Boolean(
+          ackReaction &&
+          core.channel.reactions.shouldAckReaction({
+            scope: ackScope,
+            isDirect: isDirectMessage,
+            isGroup: isRoom,
+            isMentionableGroup: isRoom,
+            requireMention: Boolean(shouldRequireMention),
+            canDetectMention,
+            effectiveWasMentioned: wasMentioned || shouldBypassMention,
+            shouldBypassMention,
+          }),
+        );
+      if (shouldAckReaction() && messageId) {
+        reactMatrixMessage(roomId, messageId, ackReaction, client).catch((err) => {
+          logVerboseMessage(`badgerclaw react failed for room ${roomId}: ${String(err)}`);
+        });
+      }
+
+      const replyTarget = ctxPayload.To;
+      if (!replyTarget) {
+        runtime.error?.("badgerclaw: missing reply target");
+        return;
+      }
+
+      let didSendReply = false;
+      const tableMode = core.channel.text.resolveMarkdownTableMode({
+        cfg,
+        channel: "badgerclaw",
+        accountId: route.accountId,
+      });
+      const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+        cfg,
+        agentId: route.agentId,
+        channel: "badgerclaw",
+        accountId: route.accountId,
+      });
+      const humanDelay = core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId);
+      const typingCallbacks = createTypingCallbacks({
+        start: () => sendTypingMatrix(roomId, true, undefined, client),
+        stop: () => sendTypingMatrix(roomId, false, undefined, client),
+        onStartError: (err) => {
+          logTypingFailure({
+            log: logVerboseMessage,
+            channel: "badgerclaw",
+            action: "start",
+            target: roomId,
+            error: err,
+          });
+        },
+        onStopError: (err) => {
+          logTypingFailure({
+            log: logVerboseMessage,
+            channel: "badgerclaw",
+            action: "stop",
+            target: roomId,
+            error: err,
+          });
+        },
+      });
+      const { dispatcher, replyOptions, markDispatchIdle } =
+        core.channel.reply.createReplyDispatcherWithTyping({
+          ...prefixOptions,
+          humanDelay,
+          typingCallbacks,
+          deliver: async (payload) => {
+            await deliverMatrixReplies({
+              replies: [payload],
+              roomId,
+              client,
+              runtime,
+              textLimit,
+              replyToMode,
+              threadId: threadTarget,
+              accountId: route.accountId,
+              tableMode,
+            });
+            if (cfg.chatHistory?.enabled && payload?.text) {
+              const botSender = resolveMatrixSenderUsername(selfUserId) || selfUserId;
+              appendHistory(roomId, {
+                ts: new Date().toISOString(),
+                role: "bot",
+                sender: botSender,
+                text: payload.text,
+              }, roomName);
+            }
+            didSendReply = true;
+          },
+          onError: (err, info) => {
+            runtime.error?.(`badgerclaw ${info.kind} reply failed: ${String(err)}`);
+          },
+        });
+
+      const { queuedFinal, counts } = await dispatchReplyFromConfigWithSettledDispatcher({
+        cfg,
+        ctxPayload,
+        dispatcher,
+        onSettled: () => {
+          markDispatchIdle();
+        },
+        replyOptions: {
+          ...replyOptions,
+          skillFilter: roomConfig?.skills,
+          onModelSelected,
+        },
+      });
+      if (!queuedFinal) {
+        return;
+      }
+      didSendReply = true;
+      const finalCount = counts.final;
+      logVerboseMessage(
+        `badgerclaw: delivered ${finalCount} reply${finalCount === 1 ? "" : "ies"} to ${replyTarget}`,
+      );
+      if (didSendReply) {
+        const previewText = bodyText.replace(/\s+/g, " ").slice(0, 160);
+        core.system.enqueueSystemEvent(`BadgerClaw message from ${senderName}: ${previewText}`, {
+          sessionKey: route.sessionKey,
+          contextKey: `badgerclaw:message:${roomId}:${messageId || "unknown"}`,
+        });
+      }
+    } catch (err) {
+      runtime.error?.(`badgerclaw handler failed: ${String(err)}`);
+    }
+  };
+}