Bot Mention Responses Implementation Plan¶

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make bot accounts reply when their @handle is mentioned on the RMHark feed (posts and comments), and fix the existing bug where @mentions inside comments notify no one.

Architecture: Mentions already create persisted MENTION notification rows (posts do; comments don’t yet). We extract a shared notifyMentions helper, wire it into the comment route to close the human-side gap, and add a reactToMentions tick to the bot-worker that consumes unread MENTION notifications addressed to bot users and replies in-context via the worker’s existing reply generators. Loop-prevention logic is a pure, unit-tested module mirroring dm-policy.ts.

Tech Stack: TypeScript, TanStack Start (file routes), Prisma/PostgreSQL, Vitest, DeepSeek (via the existing lib/rmhark-ai generators). The bot-worker is a standalone Node process (server/bot-worker/index.ts).

Global Constraints¶

Best-effort notifications: notification/SSE fan-out must NEVER fail the originating post/comment write. All such code stays inside try/catch that only logs (existing convention in lib/notifications.server.ts).
No DB schema changes. Reuse the Notification.read flag as the bot’s processed-marker.
Graceful no-op when unconfigured: the bot-worker already idles when DEEPSEEK_API_KEY is unset (isRmharkAIConfigured() gate in startup()); the new tick lives behind that same gate.
Env knobs use the existing intEnv helper in server/bot-worker/index.ts and are documented in .env.example.
Pure decision logic goes in a side-effect-free module (no Prisma/IO), like lib/rmhark-ai/dm-policy.ts, so it is unit-testable.
Mention parsing is parseHandles from lib/feed/mentions.ts (regex, dedupe, cap 10). Do not reimplement it.
Architectural boundary (important): bot-authored posts/comments are written directly through Prisma in the worker, NOT through the API routes — so they never run notifyMentions and never create MENTION notifications. Consequently the mention queue contains only human- and admin-authored mentions. The bot↔bot depth cap is therefore defensive/future-proofing, not a hot path. Keep it (it honors the approved spec) but do not expect it to fire in the current architecture.

Task 1: Shared `notifyMentions` helper + comment-mention notifications¶

Close the human-side gap: @mentions inside comments currently notify nobody (app/routes/api/rmharks/$id/comment.ts never parses handles). Extract the post route’s inline mention logic into a reusable server helper, use it in both routes. Posts tag the notification entityType: "rmhark"; comments tag it entityType: "comment" so Task 3 can tell where the mention lives.

Files:

Create: lib/feed/notify-mentions.server.ts
Modify: app/routes/api/rmharks.ts:266-320 (replace inline block with helper call)
Modify: app/routes/api/rmharks/$id/comment.ts:169-216 (add helper call inside the existing notification try)

Interfaces:

Produces: notifyMentions(input: NotifyMentionsInput): Promise<void> where

interface MentionAuthor { id: string; name: string | null; image: string | null; handle: string | null }
interface NotifyMentionsInput {
  content: string;                          // text to scan for @handles
  author: MentionAuthor;                    // who wrote it (never self-notified)
  postId: string;                           // RMHark the mention lives on (SSE deep-link target)
  entityType: "rmhark" | "comment";         // what the persisted notification points at
  entityId: string;                         // postId for posts, commentId for comments
  link: string;                             // notification navigation target (a post permalink)
  timestamp: string;                        // ISO timestamp for the SSE event
}

Consumes: parseHandles (lib/feed/mentions.ts), createNotification (lib/notifications.server.ts), feedEventBus (lib/feed-sse.ts), prisma (lib/prisma.server).
Step 1: Create the shared helper

Create lib/feed/notify-mentions.server.ts:

/**
 * Shared @mention fan-out for feed writes (posts and comments).
 *
 * Resolves the @handles in a block of user text to users, then sends each a
 * persisted MENTION notification plus a live SSE toast (excluding the author /
 * self). Posts pass entityType "rmhark"/postId; comments pass entityType
 * "comment"/commentId so the bot-worker can tell where the mention lives and
 * reply in the right place.
 *
 * Best-effort: callers MUST wrap this in try/catch so a notification failure
 * never breaks the originating write.
 */

import { prisma } from "@/lib/prisma.server";
import { feedEventBus } from "@/lib/feed-sse";
import { createNotification } from "@/lib/notifications.server";
import { parseHandles } from "@/lib/feed/mentions";

export interface MentionAuthor {
  id: string;
  name: string | null;
  image: string | null;
  handle: string | null;
}

export interface NotifyMentionsInput {
  content: string;
  author: MentionAuthor;
  postId: string;
  entityType: "rmhark" | "comment";
  entityId: string;
  link: string;
  timestamp: string;
}

export async function notifyMentions(input: NotifyMentionsInput): Promise<void> {
  const handles = parseHandles(input.content);
  if (handles.length === 0) return;

  const mentioned = await prisma.user.findMany({
    where: {
      id: { not: input.author.id }, // never self-notify
      OR: handles.map((h) => ({ handle: { equals: h, mode: "insensitive" as const } })),
    },
    select: { id: true },
  });
  if (mentioned.length === 0) return;

  // Live toast for any mentioned user with an open stream.
  feedEventBus.publish({
    type: "notification.mention",
    rmharkId: input.postId,
    payload: { id: input.postId },
    timestamp: input.timestamp,
    authorId: input.author.id,
    targetUserIds: mentioned.map((m) => m.id),
    notification: {
      rmharkId: input.postId,
      preview: input.content.slice(0, 120),
      author: {
        id: input.author.id,
        name: input.author.name,
        image: input.author.image,
        handle: input.author.handle,
      },
    },
  });

  // Persist so it appears in the notification center — and, for bot recipients,
  // becomes the bot-worker's mention work queue.
  await Promise.all(
    mentioned.map((m) =>
      createNotification({
        userId: m.id,
        actorId: input.author.id,
        type: "MENTION",
        entityType: input.entityType,
        entityId: input.entityId,
        preview: input.content,
        link: input.link,
      })
    )
  );
}

Step 2: Refactor the post route to use the helper

In app/routes/api/rmharks.ts, replace the entire mention block (the try { ... } catch (err) { console.error("Mention notification error:", err); } spanning lines 266-320) with:

    // Notify mentioned users (persisted MENTION notification + live SSE toast).
    // Best-effort: never let notification fan-out fail the post creation.
    try {
      const author = item.user;
      if (author) {
        await notifyMentions({
          content: rmhark.content,
          author: {
            id: author.id,
            name: author.name ?? null,
            image: author.image ?? null,
            handle: author.handle ?? null,
          },
          postId: item.id,
          entityType: "rmhark",
          entityId: item.id,
          link: `/u/${author.handle ?? author.id}/post/${item.id}`,
          timestamp: item.createdAt,
        });
      }
    } catch (err) {
      console.error("Mention notification error:", err);
    }

Then add the import near the other @/lib imports at the top of the file:

import { notifyMentions } from "@/lib/feed/notify-mentions.server";

Step 3: Wire the helper into the comment route

In app/routes/api/rmharks/$id/comment.ts, add the import near the top (next to the existing createNotification import):

import { notifyMentions } from "@/lib/feed/notify-mentions.server";

Then, inside the existing notification try block, immediately AFTER the post-owner COMMENT notification (after the block that ends at line 213, before the closing } catch (e) {), add:

      // Also notify anyone @mentioned in the comment body (parity with posts;
      // this also feeds the bot-worker mention queue). `postLink` is defined
      // whenever the post exists.
      if (post && postLink) {
        await notifyMentions({
          content: comment.content,
          author: {
            id: comment.user.id,
            name: comment.user.name ?? null,
            image: comment.user.image ?? null,
            handle: comment.user.handle ?? null,
          },
          postId: id,
          entityType: "comment",
          entityId: comment.id,
          link: postLink,
          timestamp: comment.createdAt.toISOString(),
        });
      }

(comment.user is already selected via userDisplaySelect in the create call; postLink and post are already in scope from the existing block.)

Step 4: Remove the now-unused import in the post route

In app/routes/api/rmharks.ts, parseHandles was only used by the block you replaced. Delete its import line:

import { parseHandles } from "@/lib/feed/mentions";

Leave createNotification and feedEventBus imports alone unless lint reports them unused (the post route still publishes rmhark.created via feedEventBus).

Step 5: Lint the changed files

Run: pnpm lint Expected: PASS with no new errors. In particular, no no-unused-vars for parseHandles/createNotification in rmharks.ts. If lint flags a still-unused import, remove it.

Step 6: Manual verification

Start the app (pnpm dev) and, as a logged-in user:

Post hey @someExistingHandle → confirm that user gets a MENTION notification (unchanged behavior).
Comment hey @someExistingHandle on any post → confirm that user now ALSO gets a MENTION notification and (if they have the feed open) a toast. This is the bug fix — before this task they got nothing.
Mention yourself in a comment → confirm NO self-notification.

Step 7: Commit

git add lib/feed/notify-mentions.server.ts app/routes/api/rmharks.ts "app/routes/api/rmharks/\$id/comment.ts"
git commit -m "feat(feed): notify @mentions in comments; extract shared notifyMentions helper"

Task 2: Pure mention loop-cap policy (TDD)¶

A side-effect-free module (no Prisma, no IO) that decides whether a bot should answer a mention and computes bot↔bot chain depth. Mirrors lib/rmhark-ai/dm-policy.ts. Test-first.

Files:

Create: lib/rmhark-ai/mention-policy.ts
Test: lib/rmhark-ai/__tests__/mention-policy.test.ts

Interfaces:

Produces:
- consecutiveBotDepth(tipToRootIsBot: boolean[]): number
- shouldReplyToMention(opts: { actorIsBot: boolean; botChainDepth: number; maxBotMentionDepth: number }): boolean
Consumes: nothing (pure).
Step 1: Write the failing test

Create lib/rmhark-ai/__tests__/mention-policy.test.ts:

import { describe, it, expect } from 'vitest';
import { consecutiveBotDepth, shouldReplyToMention } from '@/lib/rmhark-ai/mention-policy';

describe('consecutiveBotDepth', () => {
  it('counts the leading run of bot authors from the thread tip', () => {
    expect(consecutiveBotDepth([true, true, false, true])).toBe(2);
  });
  it('is 0 when the tip author is human', () => {
    expect(consecutiveBotDepth([false, true, true])).toBe(0);
  });
  it('is 0 for an empty thread', () => {
    expect(consecutiveBotDepth([])).toBe(0);
  });
  it('counts an all-bot chain fully', () => {
    expect(consecutiveBotDepth([true, true, true])).toBe(3);
  });
});

describe('shouldReplyToMention', () => {
  it('always replies to a human mention regardless of depth', () => {
    expect(
      shouldReplyToMention({ actorIsBot: false, botChainDepth: 99, maxBotMentionDepth: 3 }),
    ).toBe(true);
  });
  it('replies to a bot mention below the depth cap', () => {
    expect(
      shouldReplyToMention({ actorIsBot: true, botChainDepth: 2, maxBotMentionDepth: 3 }),
    ).toBe(true);
  });
  it('stops a bot mention at the depth cap', () => {
    expect(
      shouldReplyToMention({ actorIsBot: true, botChainDepth: 3, maxBotMentionDepth: 3 }),
    ).toBe(false);
  });
});

Step 2: Run the test to verify it fails

Run: pnpm exec vitest run lib/rmhark-ai/__tests__/mention-policy.test.ts Expected: FAIL — cannot resolve @/lib/rmhark-ai/mention-policy (module not found).

Step 3: Write the implementation

Create lib/rmhark-ai/mention-policy.ts:

/**
 * Pure decision logic for bot @mention replies — no Prisma, no I/O, no DeepSeek.
 * Side-effect-free so it is unit-testable, mirroring dm-policy.ts.
 */

/**
 * Given whether each comment author is a bot, walking from the thread tip (most
 * recent) toward the root, return the length of the leading run of bot authors.
 * Stops at the first human. Used to cap bot↔bot @mention ping-pong.
 *
 *   [true, true, false, true] -> 2
 *   [false, ...]              -> 0
 *   []                        -> 0
 */
export function consecutiveBotDepth(tipToRootIsBot: boolean[]): number {
  let depth = 0;
  for (const isBot of tipToRootIsBot) {
    if (!isBot) break;
    depth++;
  }
  return depth;
}

/**
 * Whether a bot should answer a mention. Humans are always answered. A mention
 * authored by a bot is answered only while the bot↔bot chain at the thread tip
 * is shorter than `maxBotMentionDepth`.
 */
export function shouldReplyToMention(opts: {
  actorIsBot: boolean;
  botChainDepth: number;
  maxBotMentionDepth: number;
}): boolean {
  if (!opts.actorIsBot) return true;
  return opts.botChainDepth < opts.maxBotMentionDepth;
}

Step 4: Run the test to verify it passes

Run: pnpm exec vitest run lib/rmhark-ai/__tests__/mention-policy.test.ts Expected: PASS — 7 tests pass.

Step 5: Commit

git add lib/rmhark-ai/mention-policy.ts lib/rmhark-ai/__tests__/mention-policy.test.ts
git commit -m "feat(bot): pure mention loop-cap policy (depth + should-reply)"

Notes / Known boundaries¶

Queue is human/admin mentions only. Bot posts/comments are written directly via Prisma in the worker, bypassing the API routes that run notifyMentions, so bot-authored @mentions never create MENTION notifications. The bot↔bot depth cap is retained as defensive/future-proofing (and honors the approved spec), but will not fire under the current architecture. If we later want bots to answer mentions inside other bots’ content, that needs a separate worker scan (out of scope here).
Dedupe relies on three guards: marking the notification read = true after processing, the re-entrancy flag (mentionRunning) preventing overlapping ticks, and the per-entity “already replied” check (replyToPostMention post-already-answered; the replies check before replyToComment).
No schema migration. Everything derives from existing Notification / RMHark / RMHarkComment / User.isBot rows.

Bot Mention Responses Implementation Plan¶

Global Constraints¶

Task 1: Shared notifyMentions helper + comment-mention notifications¶

Task 2: Pure mention loop-cap policy (TDD)¶

Task 3: Bot-worker reactToMentions tick¶

Notes / Known boundaries¶

Task 1: Shared `notifyMentions` helper + comment-mention notifications¶

Task 3: Bot-worker `reactToMentions` tick¶