feat(msteams): respond to channel messages by keyword without an @mention

clwilliams8 · clwilliams8 · commit 763dd83ca42d · 2026-06-12T22:54:40.000-05:00
The MS Teams channel is the only group-capable channel that ignores
messages.groupChat.mentionPatterns: Discord, Slack and WhatsApp all expose a
per-provider mentionPatterns policy that scopes those patterns and treats a
text match as an implicit mention, but msteams drops every non-@mention group
message at the requireMention gate. This adds the same seam to msteams.

- config: channels.msteams.mentionPatterns (MentionPatternsPolicyConfig),
  matching the discord/slack/whatsapp shape; scopes the global
  messages.groupChat.mentionPatterns to selected Teams conversations.
- handler: build the mention regexes and OR a match into the wasMentioned fact
  fed to resolveInboundMentionDecision, so a named-without-@ message dispatches
  while non-matching messages still hit the requireMention skip (no extra model
  turn). Self-echo guarded so the bot does not trigger on its own posts (with
  RSC ChannelMessage.Read.Group the bot also receives its own channel messages).
- isMSTeamsKeywordMention helper (mirrors discord's mention-state resolution),
  unit-tested for match/case-insensitive/no-keyword/self-echo/DM/already-
  mentioned/empty-patterns/empty-text.
diff --git a/extensions/msteams/src/mentions.test.ts b/extensions/msteams/src/mentions.test.ts
@@ -1,6 +1,11 @@
 // Msteams tests cover mentions plugin behavior.
 import { describe, expect, it } from "vitest";
-import { buildMentionEntities, formatMentionText, parseMentions } from "./mentions.js";
+import {
+  buildMentionEntities,
+  formatMentionText,
+  isMSTeamsKeywordMention,
+  parseMentions,
+} from "./mentions.js";
 
 function requireFirstEntity(result: ReturnType<typeof parseMentions>) {
   const entity = result.entities[0];
@@ -253,3 +258,49 @@ describe("formatMentionText", () => {
     expect(result).toBe("Hey <at>John(Test)</at> and <at>Alice.Smith</at>");
   });
 });
+
+describe("isMSTeamsKeywordMention", () => {
+  const regexes = [/\bradar\b/i];
+  const base = {
+    isDirectMessage: false,
+    alreadyMentioned: false,
+    text: "hey radar, you there?",
+    fromId: "29:user",
+    recipientId: "28:bot",
+    mentionRegexes: regexes,
+  };
+
+  it("treats a keyword match in a channel message as an implicit mention", () => {
+    expect(isMSTeamsKeywordMention(base)).toBe(true);
+  });
+
+  it("is case-insensitive (regex carries the flag)", () => {
+    expect(isMSTeamsKeywordMention({ ...base, text: "RADAR, status?" })).toBe(true);
+  });
+
+  it("does not trigger when the keyword is absent", () => {
+    expect(isMSTeamsKeywordMention({ ...base, text: "the weather is nice today" })).toBe(false);
+  });
+
+  it("does not trigger on the bot's own posts (self-echo guard)", () => {
+    expect(isMSTeamsKeywordMention({ ...base, fromId: "28:bot", recipientId: "28:bot" })).toBe(
+      false,
+    );
+  });
+
+  it("skips direct messages (handled by the normal DM path)", () => {
+    expect(isMSTeamsKeywordMention({ ...base, isDirectMessage: true })).toBe(false);
+  });
+
+  it("skips messages already @mentioned (handled normally)", () => {
+    expect(isMSTeamsKeywordMention({ ...base, alreadyMentioned: true })).toBe(false);
+  });
+
+  it("no-ops when no patterns are configured", () => {
+    expect(isMSTeamsKeywordMention({ ...base, mentionRegexes: [] })).toBe(false);
+  });
+
+  it("no-ops on empty text", () => {
+    expect(isMSTeamsKeywordMention({ ...base, text: undefined })).toBe(false);
+  });
+});
diff --git a/extensions/msteams/src/mentions.ts b/extensions/msteams/src/mentions.ts
@@ -5,6 +5,7 @@
  * 1. Text containing <at>Name</at> tags
  * 2. entities array with mention metadata
  */
+import { matchesMentionPatterns } from "openclaw/plugin-sdk/channel-inbound";
 
 type MentionEntity = {
   type: "mention";
@@ -112,3 +113,35 @@ export function formatMentionText(text: string, mentions: MentionInfo[]): string
   }
   return formatted;
 }
+
+/**
+ * Whether a channel/group message should be treated as an implicit mention because
+ * its text matches a configured mention pattern (e.g. the agent's name). This lets
+ * the agent answer when named without an `@` — the message-handler ORs the result
+ * into the `wasMentioned` fact so the existing requireMention gate still drops
+ * everything else (no extra model turn).
+ *
+ * Guards, in order: never for DMs or already-@mentioned messages (handled by the
+ * normal path); nothing to match without text or patterns; and never for the bot's
+ * own posts — with RSC the bot also receives its own channel messages, and a reply
+ * that happens to contain the keyword would otherwise re-trigger itself.
+ */
+export function isMSTeamsKeywordMention(params: {
+  isDirectMessage: boolean;
+  alreadyMentioned: boolean;
+  text: string | undefined;
+  fromId: string | undefined;
+  recipientId: string | undefined;
+  mentionRegexes: RegExp[];
+}): boolean {
+  if (params.isDirectMessage || params.alreadyMentioned) {
+    return false;
+  }
+  if (!params.text || params.mentionRegexes.length === 0) {
+    return false;
+  }
+  if (params.fromId && params.fromId === params.recipientId) {
+    return false;
+  }
+  return matchesMentionPatterns(params.text, params.mentionRegexes);
+}
diff --git a/extensions/msteams/src/monitor-handler/message-handler.ts b/extensions/msteams/src/monitor-handler/message-handler.ts
@@ -2,6 +2,7 @@
 import { formatAllowlistMatchMeta } from "openclaw/plugin-sdk/allow-from";
 import {
   buildChannelInboundEventContext,
+  buildMentionRegexes,
   logInboundDrop,
   resolveInboundMentionDecision,
   resolveInboundSessionEnvelopeContext,
@@ -37,6 +38,7 @@ import {
   type GraphThreadMessage,
 } from "../graph-thread.js";
 import { resolveGraphChatId } from "../graph-upload.js";
+import { isMSTeamsKeywordMention } from "../mentions.js";
 import {
   extractMSTeamsConversationMessageId,
   extractMSTeamsQuoteInfo,
@@ -522,10 +524,26 @@ export function createMSTeamsMessageHandler(deps: MSTeamsMessageHandlerDeps) {
       channelConfig,
     });
     const timestamp = parseMSTeamsActivityTimestamp(activity.timestamp);
+    // A non-@mention channel message that matches a configured mention pattern
+    // (e.g. the agent's name) counts as an implicit mention, so the agent answers
+    // when named without an `@`. Non-matching messages fall through to the
+    // requireMention gate below and are dropped before any model turn.
+    const keywordMention = isMSTeamsKeywordMention({
+      isDirectMessage,
+      alreadyMentioned: params.wasMentioned,
+      text,
+      fromId: activity.from?.id,
+      recipientId: activity.recipient?.id,
+      mentionRegexes: buildMentionRegexes(cfg, route.agentId, {
+        provider: "msteams",
+        conversationId,
+        providerPolicy: msteamsCfg?.mentionPatterns,
+      }),
+    });
     const mentionDecision = resolveInboundMentionDecision({
       facts: {
         canDetectMention: true,
-        wasMentioned: params.wasMentioned,
+        wasMentioned: params.wasMentioned || keywordMention,
         implicitMentionKinds: params.implicitMentionKinds,
       },
       policy: {
diff --git a/src/config/types.msteams.ts b/src/config/types.msteams.ts
@@ -11,7 +11,7 @@ import type {
   ChannelHealthMonitorConfig,
   ChannelHeartbeatVisibilityConfig,
 } from "./types.channel-health.js";
-import type { DmConfig } from "./types.messages.js";
+import type { DmConfig, MentionPatternsPolicyConfig } from "./types.messages.js";
 import type { SecretInput } from "./types.secrets.js";
 import type { GroupToolPolicyBySenderConfig, GroupToolPolicyConfig } from "./types.tools.js";
 
@@ -163,6 +163,13 @@ export type MSTeamsConfig = {
   mediaAuthAllowHosts?: Array<string>;
   /** Default: require @mention to respond in channels/groups. */
   requireMention?: boolean;
+  /**
+   * Scope the global `messages.groupChat.mentionPatterns` to selected Teams
+   * conversations. A pattern match makes a non-@mention channel message count
+   * as a mention, so the agent answers when named without an @ (e.g. "Radar, …").
+   * Same seam as the Discord/Slack/WhatsApp channels.
+   */
+  mentionPatterns?: MentionPatternsPolicyConfig;
   /** Max group/channel messages to keep as history context (0 disables). */
   historyLimit?: number;
   /** Max DM turns to keep as history context. */
diff --git a/src/config/zod-schema.providers-core.ts b/src/config/zod-schema.providers-core.ts
@@ -1609,6 +1609,7 @@ export const MSTeamsConfigSchema = z
     mediaAllowHosts: z.array(z.string()).optional(),
     mediaAuthAllowHosts: z.array(z.string()).optional(),
     requireMention: z.boolean().optional(),
+    mentionPatterns: MentionPatternsPolicySchema.optional(),
     historyLimit: z.number().int().min(0).optional(),
     dmHistoryLimit: z.number().int().min(0).optional(),
     dms: z.record(z.string(), DmConfigSchema.optional()).optional(),
