Tell the sender when a known mention is outside the pod

backend/__tests__/unit/routes/agentsRuntime.post-message.config.test.js

@@ -13,6 +13,9 @@ jest.mock('../../../services/agentIdentityService', () => ({
 jest.mock('../../../services/agentMessageService', () => ({
   postMessage: jest.fn(),
 }));
+jest.mock('../../../services/mentionNonMemberNoticeService', () => ({
+  findNonMemberMentionNotices: jest.fn(),
+}));
 jest.mock('../../../services/agentThreadService', () => ({}));
 jest.mock('../../../services/podContextService', () => ({}));
 jest.mock('../../../services/globalModelConfigService', () => ({}));
@@ -28,14 +31,18 @@ jest.mock('../../../integrations', () => ({ get: jest.fn() }));
 jest.mock('../../../models/Activity', () => ({}));
 jest.mock('../../../models/User', () => ({ findById: jest.fn() }));
 jest.mock('../../../models/Post', () => ({ findById: jest.fn() }));
-jest.mock('../../../models/Pod', () => ({ find: jest.fn() }));
+jest.mock('../../../models/Pod', () => ({
+  find: jest.fn(),
+  findById: jest.fn(() => ({ select: () => ({ lean: async () => ({ type: 'chat' }) }) })),
+}));
 jest.mock('../../../services/dmService', () => ({ getOrCreateAgentDM: jest.fn() }));
 jest.mock('../../../models/Integration', () => ({ find: jest.fn(), findOne: jest.fn() }));
 jest.mock('../../../models/AgentRegistry', () => ({
   AgentInstallation: { findOne: jest.fn(), find: jest.fn() },
 }));
 
 const AgentMessageService = require('../../../services/agentMessageService');
+const { findNonMemberMentionNotices } = require('../../../services/mentionNonMemberNoticeService');
 const router = require('../../../routes/agentsRuntime');
 
 const getRouteHandler = (path, method) => {
@@ -51,6 +58,7 @@ const getRouteHandler = (path, method) => {
 describe('agentsRuntime post message installation config forwarding', () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    findNonMemberMentionNotices.mockResolvedValue([]);
   });
 
   it('passes installation config to AgentMessageService.postMessage', async () => {
@@ -92,7 +100,54 @@ describe('agentsRuntime post message installation config forwarding', () => {
       messageType: 'text',
       installationConfig: { errorRouting: { ownerDm: true } },
     }));
-    expect(res.json).toHaveBeenCalledWith({ success: true });
+    expect(res.json).toHaveBeenCalledWith({ success: true, mentionNotices: [] });
+  });
+
+  it('returns structured non-member feedback in the MCP post result', async () => {
+    const handler = getRouteHandler('/pods/:podId/messages', 'post');
+    AgentMessageService.postMessage.mockResolvedValue({
+      success: true, message: { id: 'm1', content: 'Please review @rhea' },
+    });
+    findNonMemberMentionNotices.mockResolvedValue([{ code: 'MENTION_NOT_IN_POD', handle: 'rhea', message: "rhea isn't in this pod. Invite them, or ask in a pod they're in." }]);
+    const installation = { podId: 'pod-1', agentName: 'openclaw', instanceId: 'tarik', config: {} };
+    const req = {
+      params: { podId: 'pod-1' }, body: { content: 'Please review @rhea' },
+      agentInstallation: installation, agentInstallations: [installation],
+    };
+    const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
+
+    await handler(req, res);
+
+    expect(findNonMemberMentionNotices).toHaveBeenCalledWith('pod-1', 'Please review @rhea');
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      mentionNotices: [{ code: 'MENTION_NOT_IN_POD', handle: 'rhea', message: "rhea isn't in this pod. Invite them, or ask in a pod they're in." }],
+      notice: "rhea isn't in this pod. Invite them, or ask in a pod they're in.",
+    }));
+  });
+
+  it('still reports a successful post if the advisory lookup fails', async () => {
+    const handler = getRouteHandler('/pods/:podId/messages', 'post');
+    AgentMessageService.postMessage.mockResolvedValue({
+      success: true, message: { id: 'm1', content: '@rhea please review' },
+    });
+    findNonMemberMentionNotices.mockRejectedValueOnce(new Error('lookup unavailable'));
+    const installation = { podId: 'pod-1', agentName: 'openclaw', instanceId: 'tarik', config: {} };
+    const req = {
+      params: { podId: 'pod-1' }, body: { content: '@rhea please review' },
+      agentInstallation: installation, agentInstallations: [installation],
+    };
+    const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      await handler(req, res);
+      expect(res.status).not.toHaveBeenCalledWith(500);
+      expect(res.json).toHaveBeenCalledWith({
+        success: true, message: { id: 'm1', content: '@rhea please review' }, mentionNotices: [],
+      });
+    } finally {
+      warn.mockRestore();
+    }
   });
 
   // answeringMessageId tells the answer rule which message a post answers

backend/__tests__/unit/services/mentionNonMemberNoticeService.test.js

@@ -0,0 +1,64 @@
+jest.mock('../../../models/Pod', () => ({ findById: jest.fn() }));
+jest.mock('../../../models/User', () => ({ find: jest.fn() }));
+jest.mock('../../../models/AgentProfile', () => ({ find: jest.fn() }));
+jest.mock('../../../models/AgentRegistry', () => ({
+  AgentInstallation: { find: jest.fn() },
+}));
+
+const Pod = require('../../../models/Pod');
+const User = require('../../../models/User');
+const AgentProfile = require('../../../models/AgentProfile');
+const { AgentInstallation } = require('../../../models/AgentRegistry');
+const { findNonMemberMentionNotices } = require('../../../services/mentionNonMemberNoticeService');
+
+const rows = (value) => ({ select: () => ({ lean: async () => value }) });
+
+describe('non-member mention feedback', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    Pod.findById.mockReturnValue(rows({ members: ['member-user'] }));
+    User.find.mockReturnValue(rows([
+      { _id: 'member-user', username: 'sam' },
+      { _id: 'other-user', username: 'Lily' },
+    ]));
+    AgentInstallation.find.mockReturnValue(rows([
+      { podId: 'pod-1', agentName: 'nova', instanceId: 'nova', displayName: 'Nova' },
+      { podId: 'pod-2', agentName: 'rhea', instanceId: 'rhea', displayName: 'Rhea' },
+      { podId: 'pod-2', agentName: 'scout', instanceId: 'scout', displayName: '' },
+    ]));
+    AgentProfile.find.mockReturnValue(rows([
+      { podId: 'pod-2', agentName: 'scout', instanceId: 'scout', name: 'Friendly Scout' },
+    ]));
+  });
+
+  it('notifies for known outsiders but not members or unknown handles', async () => {
+    const notices = await findNonMemberMentionNotices(
+      'pod-1', '@rhea @lily @nova @sam @notarealhandle @rhea @guide @friendly-scout',
+    );
+    expect(notices).toEqual([
+      { code: 'MENTION_NOT_IN_POD', handle: 'rhea', message: "rhea isn't in this pod. Invite them, or ask in a pod they're in." },
+      { code: 'MENTION_NOT_IN_POD', handle: 'lily', message: "lily isn't in this pod. Invite them, or ask in a pod they're in." },
+      { code: 'MENTION_NOT_IN_POD', handle: 'guide', message: "guide isn't in this pod. Invite them, or ask in a pod they're in." },
+      { code: 'MENTION_NOT_IN_POD', handle: 'friendly-scout', message: "friendly-scout isn't in this pod. Invite them, or ask in a pod they're in." },
+    ]);
+    expect(User.find).toHaveBeenCalledWith({
+      $or: expect.arrayContaining([{ username: /^lily$/i }]),
+    });
+  });
+
+  it('skips all lookups when there is no mention', async () => {
+    expect(await findNonMemberMentionNotices('pod-1', 'hello')).toEqual([]);
+    expect(Pod.findById).not.toHaveBeenCalled();
+  });
+
+  it('recognizes an in-pod legacy alias and profile display slug as delivered', async () => {
+    AgentInstallation.find.mockReturnValue(rows([
+      { podId: 'pod-1', agentName: 'scout', instanceId: 'scout', displayName: '' },
+    ]));
+    AgentProfile.find.mockReturnValue(rows([
+      { podId: 'pod-1', agentName: 'scout', instanceId: 'scout', name: 'Friendly Scout' },
+    ]));
+
+    expect(await findNonMemberMentionNotices('pod-1', '@guide @friendly-scout')).toEqual([]);
+  });
+});

backend/__tests__/unit/services/messageAgentDeliveryService.test.js

@@ -7,8 +7,12 @@ jest.mock('../../../services/agentMentionService', () => ({
 jest.mock('../../../models/AgentRegistry', () => ({
   AgentInstallation: { countDocuments: jest.fn() },
 }));
+jest.mock('../../../services/mentionNonMemberNoticeService', () => ({
+  findNonMemberMentionNotices: jest.fn().mockResolvedValue([]),
+}));
 
 const AgentMentionService = require('../../../services/agentMentionService');
+const { findNonMemberMentionNotices } = require('../../../services/mentionNonMemberNoticeService');
 const { AgentInstallation } = require('../../../models/AgentRegistry');
 const {
   authorUsername,
@@ -66,6 +70,33 @@ describe('messageAgentDeliveryService', () => {
     });
   });
 
+  it('puts a known non-member notice only in the sender response', async () => {
+    const notice = { code: 'MENTION_NOT_IN_POD', handle: 'rhea', message: "rhea isn't in this pod." };
+    findNonMemberMentionNotices.mockResolvedValueOnce([notice]);
+    const message = { id: 'm2', content: '@rhea please review', userId: { username: 'sam' } };
+
+    const response = await deliverMessageToAgents({
+      podId: 'p1', podType: 'chat', message, userId: 'u1',
+    });
+
+    expect(response.mentionNotices).toEqual([notice]);
+    expect(message).not.toHaveProperty('mentionNotices');
+  });
+
+  it('keeps delivery successful when the advisory lookup fails', async () => {
+    findNonMemberMentionNotices.mockRejectedValueOnce(new Error('lookup unavailable'));
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const response = await deliverMessageToAgents({
+        podId: 'p1', podType: 'chat', message: { id: 'm2', content: '@rhea' }, userId: 'u1',
+      });
+      expect(response).not.toHaveProperty('mentionNotices');
+      expect(AgentMentionService.enqueueMentions).toHaveBeenCalledTimes(1);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   it('omits a reply edge for a route that cannot receive one', async () => {
     const message = { id: 'm1', userId: { username: 'joined' } };
 

backend/routes/agentsRuntime.ts

@@ -25,6 +25,7 @@ const AgentEventService = require('../services/agentEventService');
 const HostedRuntimeMeter = require('../services/hostedRuntimeService');
 const AgentIdentityService = require('../services/agentIdentityService');
 const AgentMessageService = require('../services/agentMessageService');
+const { findNonMemberMentionNotices } = require('../services/mentionNonMemberNoticeService');
 const AgentThreadService = require('../services/agentThreadService');
 const PodContextService = require('../services/podContextService');
 const GlobalModelConfigService = require('../services/globalModelConfigService');
@@ -2117,7 +2118,25 @@ router.post('/pods/:podId/messages', phase4RateLimit, agentRuntimeAuth, async (r
         .catch((err: any) => console.warn('agent post-message DM/mention enqueue failed:', err.message));
     }
 
-    return res.json(result);
+    let mentionNotices: Array<{ code: 'MENTION_NOT_IN_POD'; handle: string; message: string }> = [];
+    if (result.success && !result.skipped && result.message) {
+      try {
+        mentionNotices = await findNonMemberMentionNotices(
+          podId, String((result.message as { content?: string }).content || ''),
+        );
+      } catch (noticeError) {
+        // The post already landed. A failed advisory lookup cannot make the
+        // tool report a failed send and invite a duplicate retry.
+        console.warn('[agent post-message] mention notice lookup failed:', (noticeError as Error).message);
+      }
+    }
+    return res.json({
+      ...result,
+      mentionNotices,
+      ...(mentionNotices.length > 0
+        ? { notice: mentionNotices.map((item) => item.message).join(' ') }
+        : {}),
+    });
   } catch (error: any) {
     const err = error as Error & { code?: string; statusCode?: number; name?: string };
     // A bad thread target is caller-fixable input, same as on the human

backend/services/agentMentionService.ts

@@ -2457,6 +2457,9 @@ const enqueueDmEvent = async ({
 
 export {
   extractMentions,
+  // Sender feedback must recognize the exact same routed handles (including
+  // legacy aliases and profile display names) as the delivery path.
+  buildMentionMap,
   // Exported for the escaping test: the property that matters — a metacharacter
   // in a handle matches literally — is unreachable through `enqueueMentions`
   // while `extractMentions` still excludes metacharacters. A test that can only

backend/services/mentionNonMemberNoticeService.ts

@@ -0,0 +1,86 @@
+// A sender can address only pod members. When a real handle names someone
+// outside this pod, return sender-only feedback without exposing where they are.
+// eslint-disable-next-line global-require
+const Pod = require('../models/Pod');
+// eslint-disable-next-line global-require
+const User = require('../models/User');
+// eslint-disable-next-line global-require
+const { AgentInstallation } = require('../models/AgentRegistry');
+// eslint-disable-next-line global-require
+const AgentProfile = require('../models/AgentProfile');
+// eslint-disable-next-line global-require
+const { buildMentionMap } = require('./agentMentionService');
+
+export interface MentionNotice {
+  code: 'MENTION_NOT_IN_POD';
+  handle: string;
+  message: string;
+}
+
+const mentionedHandles = (content: string): string[] => {
+  const handles = new Set<string>();
+  const regex = /@([a-z0-9_-]{2,})/gi;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(content)) !== null && handles.size < 20) {
+    handles.add(match[1].toLowerCase());
+  }
+  return [...handles];
+};
+
+const exactHandle = (handle: string): RegExp => new RegExp(`^${handle}$`, 'i');
+
+export const findNonMemberMentionNotices = async (
+  podId: string,
+  content: string,
+): Promise<MentionNotice[]> => {
+  const handles = mentionedHandles(content);
+  if (handles.length === 0) return [];
+
+  const [pod, users, installations, profiles] = await Promise.all([
+    Pod.findById(podId).select('members').lean(),
+    // Usernames retain their original case at write time. Mention parsing
+    // lowercases them, so use the same anchored case-insensitive match as
+    // human mention routing.
+    User.find({ $or: handles.map((handle) => ({ username: exactHandle(handle) })) })
+      .select('_id username').lean(),
+    // Display-name slugs and instance handles are routable in the pod, so
+    // inspect the same active installation records rather than only names.
+    AgentInstallation.find({ status: 'active' })
+      .select('podId agentName instanceId displayName').lean(),
+    AgentProfile.find({}).select('podId agentName instanceId name').lean(),
+  ]);
+  if (!pod) return [];
+
+  const members = new Set((pod.members || []).map((id: unknown) => String(id)));
+  const known = new Set<string>();
+  const inPod = new Set<string>();
+  for (const user of users || []) {
+    const handle = String(user.username || '').toLowerCase();
+    known.add(handle);
+    if (members.has(String(user._id))) inPod.add(handle);
+  }
+  const installationsByPod = new Map<string, Array<Record<string, unknown>>>();
+  for (const installation of installations || []) {
+    const installationPodId = String(installation.podId);
+    const list = installationsByPod.get(installationPodId) || [];
+    list.push(installation);
+    installationsByPod.set(installationPodId, list);
+  }
+  for (const [installationPodId, podInstallations] of installationsByPod) {
+    const podProfiles = (profiles || []).filter(
+      (profile: { podId: unknown }) => String(profile.podId) === installationPodId,
+    );
+    const { map } = buildMentionMap(podInstallations, podProfiles);
+    for (const handle of map.keys()) {
+      known.add(handle);
+      if (installationPodId === String(podId)) inPod.add(handle);
+    }
+  }
+
+  return handles.filter((handle) => known.has(handle) && !inPod.has(handle))
+    .map((handle) => ({
+      code: 'MENTION_NOT_IN_POD' as const,
+      handle,
+      message: `${handle} isn't in this pod. Invite them, or ask in a pod they're in.`,
+    }));
+};

backend/services/messageAgentDeliveryService.ts

@@ -2,8 +2,11 @@
 const AgentMentionService = require('./agentMentionService');
 // eslint-disable-next-line global-require
 const { AgentInstallation } = require('../models/AgentRegistry');
+// eslint-disable-next-line global-require
+const { findNonMemberMentionNotices } = require('./mentionNonMemberNoticeService');
 
 export interface MessageForAgentDelivery {
+  content?: string;
   userId?: { username?: string } | string;
   username?: string;
   user?: { username?: string };
@@ -34,7 +37,18 @@ interface AgentDelivery {
   woken: number;
 }
 
-type DeliveredMessage<T> = T | (T & { agentDelivery: AgentDelivery });
+type DeliveredMessage<T> = T | (T & { mentionNotices?: unknown[]; agentDelivery?: AgentDelivery });
+
+const senderNotices = async (podId: string, message: { content?: string }): Promise<unknown[]> => {
+  try {
+    return await findNonMemberMentionNotices(podId, message.content || '');
+  } catch (error) {
+    // The message is already stored. Advisory feedback cannot turn a send
+    // into an apparent failure and tempt the caller to post it again.
+    console.warn('[messageAgentDelivery] mention notice lookup failed:', (error as Error).message);
+    return [];
+  }
+};
 
 // The persisted message is the authoritative sender frame. Request auth can
 // have only an id (JWT) while either PG or Mongo may have joined the author.
@@ -66,11 +80,12 @@ export const deliverMessageToAgents = async <T extends MessageForAgentDelivery>(
   onlyExplicitMentions = false,
 }: DeliveryOptions<T>): Promise<DeliveredMessage<T>> => {
   const username = authorUsername(message, requestUser);
+  const mentionNotices = await senderNotices(podId, message);
 
   if (AgentMentionService.isAutoRoutedDmPod(podType)) {
-    if (suppressImplicitReply) return message;
+    if (suppressImplicitReply) return mentionNotices.length ? { ...message, mentionNotices } : message;
     await AgentMentionService.enqueueDmEvent({ podId, message, userId, username });
-    return message;
+    return mentionNotices.length ? { ...message, mentionNotices } : message;
   }
 
   const mentionOptions = {
@@ -95,6 +110,7 @@ export const deliverMessageToAgents = async <T extends MessageForAgentDelivery>(
 
   return {
     ...message,
+    ...(mentionNotices.length ? { mentionNotices } : {}),
     agentDelivery: {
       enqueued: mentionResult.enqueued.length,
       implicit: mentionResult.implicit || [],