Bot DM 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 answer direct messages (and occasionally initiate them) in-persona via DeepSeek, with live SSE delivery from the separate worker process.

Architecture: All bot DM behavior lives in the server/bot-worker process as a new dmTick() loop, mirroring the existing feed-reply ticks. Pure decision logic (privacy, reactive-reply detection, anti-pester, history formatting) is extracted into side-effect-free modules under lib/ so it is unit-testable. Because notifyUser is in-memory per-process, the worker pushes live SSE events by POSTing a new internal web endpoint guarded by a shared secret.

Tech Stack: TypeScript, Prisma (Postgres), TanStack Start file routes, OpenAI SDK pointed at DeepSeek, Vitest.

Global Constraints¶

DM generation MUST pass the bot’s existing user.botPersona string — the same composePersona(spec) output that drives generatePost/generateReply. Same voice across posts, feed replies, and DMs.
Bots MUST never reveal they are bots/AI (carried by the persona system prompt).
No Prisma schema changes / migrations. All state is derived from existing Conversation, DirectMessage, Follow rows.
Privacy is mandatory for bot-initiated DMs: NONE → never; FOLLOWERS → only if the human follows the bot; EVERYONE → allowed. Reactive replies need no privacy check (the human opened the conversation).
All tunables use the existing intEnv / probEnv helpers in server/bot-worker/index.ts.
Conversation creation MUST use the canonical participant ordering used in app/routes/api/messages.ts:219-238: [pOne, pTwo] = a < b ? [a, b] : [b, a], then upsert on participantOneId_participantTwoId.
DM length cap reuses MAX_REPLY_CHARS (500) from lib/rmhark-ai/persona.ts.
Tests run with: node_modules/.bin/vitest run <path> (auto-loads vitest.config.ts; @ alias resolves to repo root).
Lint a file with: pnpm exec eslint <path>.

Task 1: Pure DM policy module¶

Side-effect-free decision logic plus the Vitest wiring so its tests run.

Files:

Create: lib/rmhark-ai/dm-policy.ts
Create: lib/rmhark-ai/__tests__/dm-policy.test.ts
Modify: vitest.config.ts (add the new test dir to include)

Interfaces:

Consumes: nothing (pure).
Produces:
- type DmPrivacy = 'EVERYONE' | 'FOLLOWERS' | 'NONE'
- interface PolicyMessage { senderId: string; createdAt: Date }
- interface DmMessage { senderId: string; content: string }
- interface DmTurn { from: 'them' | 'you'; text: string }
- needsReactiveReply(messages: PolicyMessage[], botId: string): boolean
- canBotMessage(opts: { dmPrivacy: DmPrivacy; humanFollowsBot: boolean }): boolean
- type InitiationDecision = 'opener' | 'followup' | 'skip'
- decideInitiation(opts: { botId: string; now: number; followupSilenceMs: number; messages: PolicyMessage[] | null }): InitiationDecision
- formatDmHistory(messages: DmMessage[], botId: string): DmTurn[]
Step 1: Add the new test dir to the Vitest include list

In vitest.config.ts, change the include array:

    include: [
      'testing/**/*.test.ts',
      'lib/dream-rift/__tests__/**/*.test.ts',
      'lib/rmhark-ai/__tests__/**/*.test.ts',
    ],

Step 2: Write the failing tests

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

import { describe, it, expect } from 'vitest';
import {
  needsReactiveReply,
  canBotMessage,
  decideInitiation,
  formatDmHistory,
} from '@/lib/rmhark-ai/dm-policy';

const BOT = 'bot-1';
const HUMAN = 'human-1';
const at = (ms: number) => ({ senderId: HUMAN, createdAt: new Date(ms) });

describe('needsReactiveReply', () => {
  it('is false for an empty conversation', () => {
    expect(needsReactiveReply([], BOT)).toBe(false);
  });
  it('is true when the human spoke last', () => {
    expect(
      needsReactiveReply(
        [{ senderId: BOT, createdAt: new Date(1) }, { senderId: HUMAN, createdAt: new Date(2) }],
        BOT,
      ),
    ).toBe(true);
  });
  it('is false when the bot already replied last', () => {
    expect(
      needsReactiveReply(
        [{ senderId: HUMAN, createdAt: new Date(1) }, { senderId: BOT, createdAt: new Date(2) }],
        BOT,
      ),
    ).toBe(false);
  });
});

describe('canBotMessage', () => {
  it('blocks NONE', () => {
    expect(canBotMessage({ dmPrivacy: 'NONE', humanFollowsBot: true })).toBe(false);
  });
  it('allows FOLLOWERS only when the human follows the bot', () => {
    expect(canBotMessage({ dmPrivacy: 'FOLLOWERS', humanFollowsBot: true })).toBe(true);
    expect(canBotMessage({ dmPrivacy: 'FOLLOWERS', humanFollowsBot: false })).toBe(false);
  });
  it('allows EVERYONE', () => {
    expect(canBotMessage({ dmPrivacy: 'EVERYONE', humanFollowsBot: false })).toBe(true);
  });
});

describe('decideInitiation', () => {
  const base = { botId: BOT, now: 1_000_000, followupSilenceMs: 1000 };
  it('opens when there is no conversation', () => {
    expect(decideInitiation({ ...base, messages: null })).toBe('opener');
    expect(decideInitiation({ ...base, messages: [] })).toBe('opener');
  });
  it('skips when the human has ever replied', () => {
    expect(
      decideInitiation({
        ...base,
        messages: [{ senderId: BOT, createdAt: new Date(0) }, at(5)],
      }),
    ).toBe('skip');
  });
  it('follows up once enough silence has passed after a lone opener', () => {
    expect(
      decideInitiation({ ...base, messages: [{ senderId: BOT, createdAt: new Date(0) }] }),
    ).toBe('followup');
  });
  it('skips a lone opener that is still within the silence window', () => {
    expect(
      decideInitiation({ ...base, messages: [{ senderId: BOT, createdAt: new Date(999_500) }] }),
    ).toBe('skip');
  });
  it('gives up after two unanswered bot messages', () => {
    expect(
      decideInitiation({
        ...base,
        messages: [
          { senderId: BOT, createdAt: new Date(0) },
          { senderId: BOT, createdAt: new Date(1) },
        ],
      }),
    ).toBe('skip');
  });
});

describe('formatDmHistory', () => {
  it('labels messages from the bot perspective, preserving order', () => {
    expect(
      formatDmHistory(
        [
          { senderId: HUMAN, content: 'hey' },
          { senderId: BOT, content: 'hi there' },
        ],
        BOT,
      ),
    ).toEqual([
      { from: 'them', text: 'hey' },
      { from: 'you', text: 'hi there' },
    ]);
  });
});

Step 3: Run the tests to verify they fail

Run: node_modules/.bin/vitest run lib/rmhark-ai/__tests__/dm-policy.test.ts Expected: FAIL — cannot resolve @/lib/rmhark-ai/dm-policy.

Step 4: Implement the module

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

/**
 * Pure decision logic for bot direct messages — no Prisma, no I/O, no DeepSeek.
 * Side-effect-free so it is unit-testable and reused by the bot-worker dmTick.
 */

export type DmPrivacy = 'EVERYONE' | 'FOLLOWERS' | 'NONE';

/** Minimal shape of a direct message the policy functions reason about. */
export interface PolicyMessage {
  senderId: string;
  createdAt: Date;
}

/** A direct message with its text, used when formatting history for the model. */
export interface DmMessage {
  senderId: string;
  content: string;
}

/** One labeled turn of a DM conversation, from the bot's point of view. */
export interface DmTurn {
  from: 'them' | 'you';
  text: string;
}

/**
 * Whether a bot owes a reactive reply: true when there is at least one message
 * and the most recent one is NOT from the bot (the human spoke last).
 * `messages` must be ordered oldest-first.
 */
export function needsReactiveReply(messages: PolicyMessage[], botId: string): boolean {
  if (messages.length === 0) return false;
  return messages[messages.length - 1].senderId !== botId;
}

/**
 * Whether a bot may send the FIRST message to a human, per the human's DM
 * privacy. Mirrors app/routes/api/messages.ts.
 */
export function canBotMessage(opts: { dmPrivacy: DmPrivacy; humanFollowsBot: boolean }): boolean {
  switch (opts.dmPrivacy) {
    case 'NONE':
      return false;
    case 'FOLLOWERS':
      return opts.humanFollowsBot;
    case 'EVERYONE':
      return true;
    default:
      return false;
  }
}

export type InitiationDecision = 'opener' | 'followup' | 'skip';

/**
 * Decide whether a bot may initiate (or follow up) with a human, given the
 * existing conversation's messages (oldest-first), or null if none exists.
 *
 *  - No conversation            -> 'opener'
 *  - Human has ever replied     -> 'skip' (active; reactive path handles it)
 *  - One unanswered bot opener  -> 'followup' once enough silence elapsed, else 'skip'
 *  - Two+ unanswered bot msgs   -> 'skip' (give up; never pester further)
 */
export function decideInitiation(opts: {
  botId: string;
  now: number;
  followupSilenceMs: number;
  messages: PolicyMessage[] | null;
}): InitiationDecision {
  const { botId, now, followupSilenceMs, messages } = opts;
  if (!messages || messages.length === 0) return 'opener';

  const humanReplied = messages.some((m) => m.senderId !== botId);
  if (humanReplied) return 'skip';

  if (messages.length >= 2) return 'skip';

  const last = messages[messages.length - 1];
  return now - last.createdAt.getTime() >= followupSilenceMs ? 'followup' : 'skip';
}

/** Label conversation messages as them/you for the model prompt (order preserved). */
export function formatDmHistory(messages: DmMessage[], botId: string): DmTurn[] {
  return messages.map((m) => ({
    from: m.senderId === botId ? 'you' : 'them',
    text: m.content,
  }));
}

Step 5: Run the tests to verify they pass

Run: node_modules/.bin/vitest run lib/rmhark-ai/__tests__/dm-policy.test.ts Expected: PASS (all cases green).

Step 6: Lint

Run: pnpm exec eslint lib/rmhark-ai/dm-policy.ts lib/rmhark-ai/__tests__/dm-policy.test.ts Expected: no errors.

Step 7: Commit

git add lib/rmhark-ai/dm-policy.ts lib/rmhark-ai/__tests__/dm-policy.test.ts vitest.config.ts
git commit -m "feat(bot-worker): pure DM policy (privacy, reactive, anti-pester)"

Task 2: Internal request authorization helper¶

A reusable shared-secret gate for server-to-server internal endpoints.

Files:

Create: lib/internal-auth.ts
Create: lib/__tests__/internal-auth.test.ts
Modify: vitest.config.ts (add lib/__tests__/** to include)

Interfaces:

Consumes: nothing.
Produces: authorizeInternalRequest(provided: string | null, configured: string | undefined): { ok: true } | { ok: false; status: 401 | 503 }
Step 1: Add the test dir to the Vitest include list

In vitest.config.ts, add to include:

      'lib/__tests__/**/*.test.ts',

Step 2: Write the failing tests

Create lib/__tests__/internal-auth.test.ts:

import { describe, it, expect } from 'vitest';
import { authorizeInternalRequest } from '@/lib/internal-auth';

describe('authorizeInternalRequest', () => {
  it('503 when no secret is configured (feature disabled)', () => {
    expect(authorizeInternalRequest('anything', undefined)).toEqual({ ok: false, status: 503 });
    expect(authorizeInternalRequest('anything', '')).toEqual({ ok: false, status: 503 });
  });
  it('401 when the header is missing', () => {
    expect(authorizeInternalRequest(null, 'sekret')).toEqual({ ok: false, status: 401 });
  });
  it('401 when the header does not match', () => {
    expect(authorizeInternalRequest('nope', 'sekret')).toEqual({ ok: false, status: 401 });
  });
  it('ok when the header matches', () => {
    expect(authorizeInternalRequest('sekret', 'sekret')).toEqual({ ok: true });
  });
});

Step 3: Run the tests to verify they fail

Run: node_modules/.bin/vitest run lib/__tests__/internal-auth.test.ts Expected: FAIL — cannot resolve @/lib/internal-auth.

Step 4: Implement the helper

Create lib/internal-auth.ts:

/**
 * Authorize a server-to-server internal request by shared secret.
 *  - configured secret missing/empty -> 503 (the internal API is disabled)
 *  - provided header missing or mismatched -> 401
 *  - otherwise -> ok
 */
export function authorizeInternalRequest(
  provided: string | null,
  configured: string | undefined,
): { ok: true } | { ok: false; status: 401 | 503 } {
  if (!configured) return { ok: false, status: 503 };
  if (!provided || provided !== configured) return { ok: false, status: 401 };
  return { ok: true };
}

Step 5: Run the tests to verify they pass

Run: node_modules/.bin/vitest run lib/__tests__/internal-auth.test.ts Expected: PASS.

Step 6: Lint

Run: pnpm exec eslint lib/internal-auth.ts lib/__tests__/internal-auth.test.ts Expected: no errors.

Step 7: Commit

git add lib/internal-auth.ts lib/__tests__/internal-auth.test.ts vitest.config.ts
git commit -m "feat: shared-secret authorizer for internal endpoints"

Task 3: DeepSeek DM generators¶

Add DM reply + opener generators to the existing AI module, reusing chat(), persona framing, and cleanGeneratedText.

Files:

Modify: lib/rmhark-ai/generate.server.ts (append a “Direct messages” section after the Replies section, ~line 196)
Create: lib/rmhark-ai/__tests__/generate-dm.test.ts

Interfaces:

Consumes: chat() (internal), MAX_REPLY_CHARS, cleanGeneratedText (from ./persona), isRmharkAIConfigured.
Produces:
- generateDirectMessageReply(opts: { persona: string; history: { from: 'them' | 'you'; text: string }[] }): Promise<string>
- generateDirectMessageOpener(opts: { persona: string }): Promise<string>
Step 1: Write the failing tests

Create lib/rmhark-ai/__tests__/generate-dm.test.ts:

import { describe, it, expect, beforeEach, vi } from 'vitest';

// Capture the mocked DeepSeek call so tests can inspect prompts & set replies.
const { createMock } = vi.hoisted(() => ({ createMock: vi.fn() }));
vi.mock('openai', () => ({
  default: vi.fn(() => ({ chat: { completions: { create: createMock } } })),
}));

import {
  generateDirectMessageReply,
  generateDirectMessageOpener,
} from '@/lib/rmhark-ai/generate.server';

const reply = (content: string) =>
  createMock.mockResolvedValueOnce({ choices: [{ message: { content } }] });

beforeEach(() => {
  createMock.mockReset();
  process.env.DEEPSEEK_API_KEY = 'test-key';
});

describe('generateDirectMessageReply', () => {
  it('puts the persona in the system prompt and the labeled transcript in the user prompt', async () => {
    reply('sounds good!');
    const out = await generateDirectMessageReply({
      persona: 'THEME: vintage synths.',
      history: [
        { from: 'them', text: 'hey do you gig?' },
        { from: 'you', text: 'sometimes' },
      ],
    });
    expect(out).toBe('sounds good!');
    const [{ messages }] = createMock.mock.calls[0];
    const system = messages.find((m: any) => m.role === 'system').content;
    const user = messages.find((m: any) => m.role === 'user').content;
    expect(system).toContain('THEME: vintage synths.');
    expect(system).toMatch(/never reveal/i);
    expect(user).toContain('Them: hey do you gig?');
    expect(user).toContain('You: sometimes');
  });

  it('clamps output to the reply char limit', async () => {
    reply('x'.repeat(900));
    const out = await generateDirectMessageReply({ persona: 'p', history: [] });
    expect(out.length).toBeLessThanOrEqual(500);
  });
});

describe('generateDirectMessageOpener', () => {
  it('asks the model to open a new conversation in persona', async () => {
    reply('hey! love your last post');
    const out = await generateDirectMessageOpener({ persona: 'THEME: trail running.' });
    expect(out).toBe('hey! love your last post');
    const [{ messages }] = createMock.mock.calls[0];
    const system = messages.find((m: any) => m.role === 'system').content;
    const user = messages.find((m: any) => m.role === 'user').content;
    expect(system).toContain('THEME: trail running.');
    expect(user).toMatch(/start a new .*conversation/i);
  });
});

Step 2: Run the tests to verify they fail

Run: node_modules/.bin/vitest run lib/rmhark-ai/__tests__/generate-dm.test.ts Expected: FAIL — generateDirectMessageReply / generateDirectMessageOpener are not exported.

Step 3: Implement the generators

In lib/rmhark-ai/generate.server.ts, after the Replies section (after generateReply ends near line 196), add:

/* ------------------------------------------------------------------ */
/*  Direct messages                                                    */
/* ------------------------------------------------------------------ */

const BASE_DM_RULES = [
  'This is a private one-to-one direct message (DM), not a public post.',
  `Hard limit: ${MAX_REPLY_CHARS} characters; most DMs are a sentence or two.`,
  'Write like a real person messaging privately: warm, specific, conversational. You may ask a question back.',
  'Do NOT use markdown, do NOT wrap the message in quotes, do NOT add a label. Output ONLY the message text.',
].join(' ');

/** Shared in-character system prompt for DMs (persona + never-reveal + rules). */
function dmPersonaSystem(persona: string): string {
  return [
    'You are roleplaying as a specific person chatting in private DMs. Stay completely in character.',
    'Never reveal or hint that you are an AI, a bot, or generated. You are just a person.',
    'Follow this persona exactly, including the VOICE rules (formality, quirks, and any typos):',
    '',
    persona,
    '',
    BASE_DM_RULES,
  ].join('\n');
}

/**
 * Generate an in-character reply to a private DM conversation. `history` is the
 * recent message chain labeled from the bot's perspective (them = the other
 * person, you = the bot), oldest first.
 */
export async function generateDirectMessageReply(opts: {
  persona: string;
  history: { from: 'them' | 'you'; text: string }[];
}): Promise<string> {
  const transcript = opts.history
    .map((t) => `${t.from === 'you' ? 'You' : 'Them'}: ${t.text}`)
    .join('\n');
  const user = [
    'Here is your DM conversation so far (oldest first):',
    transcript || '(no messages yet)',
    '',
    'Write your next message as the most recent reply. Output only the message.',
  ].join('\n');

  const raw = await chat(
    [
      { role: 'system', content: dmPersonaSystem(opts.persona) },
      { role: 'user', content: user },
    ],
    { maxTokens: 300, temperature: 1.0 },
  );
  return cleanGeneratedText(raw, MAX_REPLY_CHARS);
}

/** Generate a short, natural opening DM in the bot's voice (no prior context). */
export async function generateDirectMessageOpener(opts: { persona: string }): Promise<string> {
  const user = [
    'Start a new private conversation with someone on the same social platform.',
    'Open naturally and briefly — a friendly hello, a small question, or a light comment in your voice.',
    'Output only the message.',
  ].join('\n');

  const raw = await chat(
    [
      { role: 'system', content: dmPersonaSystem(opts.persona) },
      { role: 'user', content: user },
    ],
    { maxTokens: 200, temperature: 1.1 },
  );
  return cleanGeneratedText(raw, MAX_REPLY_CHARS);
}

Confirm MAX_REPLY_CHARS and cleanGeneratedText are already imported from ./persona at the top of the file (they are — used by generateReply). No new imports needed.

Step 4: Run the tests to verify they pass

Run: node_modules/.bin/vitest run lib/rmhark-ai/__tests__/generate-dm.test.ts Expected: PASS.

Step 5: Lint

Run: pnpm exec eslint lib/rmhark-ai/generate.server.ts lib/rmhark-ai/__tests__/generate-dm.test.ts Expected: no errors.

Step 6: Commit

git add lib/rmhark-ai/generate.server.ts lib/rmhark-ai/__tests__/generate-dm.test.ts
git commit -m "feat(rmhark-ai): DeepSeek DM reply + opener generators"

Task 4: Internal notify-message endpoint¶

A web route the worker calls to push a new-message SSE event from inside the web process.

Files:

Create: app/routes/api/internal/notify-message.ts

Interfaces:

Consumes: authorizeInternalRequest (Task 2), notifyUser + MessagePayload (@/lib/message-events).
Produces: POST /api/internal/notify-message — header x-internal-secret, body { userId, message }.
Step 1: Implement the route

Create app/routes/api/internal/notify-message.ts:

import { createFileRoute } from '@tanstack/react-router';
import { z } from 'zod';
import { notifyUser, type MessagePayload } from '@/lib/message-events';
import { authorizeInternalRequest } from '@/lib/internal-auth';

const bodySchema = z.object({
  userId: z.string().min(1),
  message: z.object({
    id: z.string(),
    conversationId: z.string(),
    content: z.string(),
    senderId: z.string(),
    read: z.boolean(),
    createdAt: z.string(),
  }),
});

/** POST /api/internal/notify-message — server-to-server SSE fan-out for bot DMs. */
export const Route = createFileRoute('/api/internal/notify-message')({
  server: {
    handlers: {
      POST: async ({ request }) => {
        const authz = authorizeInternalRequest(
          request.headers.get('x-internal-secret'),
          process.env.INTERNAL_API_SECRET,
        );
        if (!authz.ok) {
          return Response.json({ error: 'Unauthorized' }, { status: authz.status });
        }

        const parsed = bodySchema.safeParse(await request.json().catch(() => null));
        if (!parsed.success) {
          return Response.json({ error: 'Invalid input' }, { status: 400 });
        }

        notifyUser(parsed.data.userId, {
          type: 'new-message',
          message: parsed.data.message as MessagePayload,
        });
        return Response.json({ ok: true });
      },
    },
  },
});

Step 2: Regenerate the route tree / verify it compiles in dev

The TanStack route tree is generated on dev/build. Start dev (or the web app alone) and confirm no route-tree or type error for the new file:

Run: pnpm exec eslint app/routes/api/internal/notify-message.ts Expected: no errors. (Route-tree regeneration happens automatically under vite dev; if a routeTree.gen.ts diff appears, include it in the commit.)

Step 3: Manual smoke (optional but recommended)

With the web app running and INTERNAL_API_SECRET=devsecret in .env:

# wrong/missing secret -> 401; with a valid body + secret -> {"ok":true}
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:7005/api/internal/notify-message \
  -H 'content-type: application/json' -d '{"userId":"x","message":{"id":"1","conversationId":"c","content":"hi","senderId":"b","read":false,"createdAt":"2026-06-19T00:00:00.000Z"}}'
# expect 401 (no x-internal-secret header)

Expected: 401. Re-run with -H 'x-internal-secret: devsecret' → 200.

Step 4: Commit

git add app/routes/api/internal/notify-message.ts
# include routeTree.gen.ts only if it changed:
git add -A app/routeTree.gen.ts 2>/dev/null || true
git commit -m "feat(api): internal notify-message endpoint for bot DM SSE push"

Self-Review Notes¶

Spec coverage:

Worker dmTick + own interval → Task 5 (Steps 2,6,7). ✓
Internal notify bridge (worker → web) → Task 2 (auth) + Task 4 (route) + Task 5 Step 3. ✓
DM generators reusing persona → Task 3; persona passed through getPersona/botPersona → Task 5 Steps 4,5. ✓
Reactive replies (always-on, history, no privacy check) → Task 5 Step 4 + Task 1 needsReactiveReply/formatDmHistory. ✓
Initiated openers: privacy + anti-pester + canonical conversation creation + rare volume → Task 5 Step 5 + Task 1 canBotMessage/decideInitiation. ✓
No schema migration → confirmed; all reads over existing models. ✓
Env knobs via intEnv/probEnv + .env.example docs → Task 5 Steps 2,8. ✓
Graceful degradation when INTERNAL_API_SECRET / DEEPSEEK_API_KEY unset → Task 5 Step 3 (notifyMessageDelivered early return) + Step 10 smoke. ✓

Type consistency: MessagePayload (message-events) used in route + worker; DmTurn/from union shared between formatDmHistory (Task 1) and generateDirectMessageReply (Task 3); DmPrivacy from Task 1 reused in Task 5; conversation upsert key participantOneId_participantTwoId matches schema. ✓

Placeholder scan: none — every step shows concrete code/commands. ✓

Bot DM Responses Implementation Plan¶

Global Constraints¶

Task 1: Pure DM policy module¶

Task 2: Internal request authorization helper¶

Task 3: DeepSeek DM generators¶

Task 4: Internal notify-message endpoint¶

Task 5: Bot-worker dmTick orchestration¶

Self-Review Notes¶