refactor(messages): centralize per-agent prefixes

src/agents/agent-scope.ts

@@ -3,14 +3,12 @@ import path from "node:path";
 
 import type { ClawdbotConfig } from "../config/config.js";
 import { resolveStateDir } from "../config/paths.js";
-import {
-  DEFAULT_AGENT_ID,
-  normalizeAgentId,
-  parseAgentSessionKey,
-} from "../routing/session-key.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId } from "../routing/session-key.js";
 import { resolveUserPath } from "../utils.js";
 import { DEFAULT_AGENT_WORKSPACE_DIR } from "./workspace.js";
 
+export { resolveAgentIdFromSessionKey } from "../routing/session-key.js";
+
 type AgentEntry = NonNullable<
   NonNullable<ClawdbotConfig["agents"]>["list"]
 >[number];
@@ -29,13 +27,6 @@ type ResolvedAgentConfig = {
 
 let defaultAgentWarned = false;
 
-export function resolveAgentIdFromSessionKey(
-  sessionKey?: string | null,
-): string {
-  const parsed = parseAgentSessionKey(sessionKey);
-  return normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
-}
-
 function listAgents(cfg: ClawdbotConfig): AgentEntry[] {
   const list = cfg.agents?.list;
   if (!Array.isArray(list)) return [];

src/agents/identity.ts

@@ -29,6 +29,22 @@ export function resolveIdentityNamePrefix(
   return `[${name}]`;
 }
 
+export function resolveMessagePrefix(
+  cfg: ClawdbotConfig,
+  agentId: string,
+  opts?: { hasAllowFrom?: boolean; fallback?: string },
+): string {
+  const configured = cfg.messages?.messagePrefix;
+  if (configured !== undefined) return configured;
+
+  const hasAllowFrom = opts?.hasAllowFrom === true;
+  if (hasAllowFrom) return "";
+
+  return (
+    resolveIdentityNamePrefix(cfg, agentId) ?? opts?.fallback ?? "[clawdbot]"
+  );
+}
+
 export function resolveResponsePrefix(
   cfg: ClawdbotConfig,
   agentId: string,
@@ -37,3 +53,17 @@ export function resolveResponsePrefix(
   if (configured !== undefined) return configured;
   return resolveIdentityNamePrefix(cfg, agentId);
 }
+
+export function resolveEffectiveMessagesConfig(
+  cfg: ClawdbotConfig,
+  agentId: string,
+  opts?: { hasAllowFrom?: boolean; fallbackMessagePrefix?: string },
+): { messagePrefix: string; responsePrefix?: string } {
+  return {
+    messagePrefix: resolveMessagePrefix(cfg, agentId, {
+      hasAllowFrom: opts?.hasAllowFrom,
+      fallback: opts?.fallbackMessagePrefix,
+    }),
+    responsePrefix: resolveResponsePrefix(cfg, agentId),
+  };
+}

src/auto-reply/reply/route-reply.ts

@@ -7,12 +7,12 @@
  * across multiple providers.
  */
 
-import { resolveAgentIdFromSessionKey } from "../../agents/agent-scope.js";
-import { resolveResponsePrefix } from "../../agents/identity.js";
+import { resolveEffectiveMessagesConfig } from "../../agents/identity.js";
 import type { ClawdbotConfig } from "../../config/config.js";
 import { sendMessageDiscord } from "../../discord/send.js";
 import { sendMessageIMessage } from "../../imessage/send.js";
 import { sendMessageMSTeams } from "../../msteams/send.js";
+import { resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
 import { sendMessageSignal } from "../../signal/send.js";
 import { sendMessageSlack } from "../../slack/send.js";
 import { sendMessageTelegram } from "../../telegram/send.js";
@@ -65,10 +65,10 @@ export async function routeReply(
 
   // Debug: `pnpm test src/auto-reply/reply/route-reply.test.ts`
   const responsePrefix = params.sessionKey
-    ? resolveResponsePrefix(
+    ? resolveEffectiveMessagesConfig(
         cfg,
         resolveAgentIdFromSessionKey(params.sessionKey),
-      )
+      ).responsePrefix
     : cfg.messages?.responsePrefix;
   const normalized = normalizeReplyPayload(payload, {
     responsePrefix,

src/config/sessions.ts

@@ -11,7 +11,7 @@ import {
   DEFAULT_AGENT_ID,
   DEFAULT_MAIN_KEY,
   normalizeAgentId,
-  parseAgentSessionKey,
+  resolveAgentIdFromSessionKey,
 } from "../routing/session-key.js";
 import { normalizeE164 } from "../utils.js";
 import {
@@ -232,12 +232,7 @@ export function resolveMainSessionKey(cfg?: {
   return buildAgentMainSessionKey({ agentId, mainKey });
 }
 
-export function resolveAgentIdFromSessionKey(
-  sessionKey?: string | null,
-): string {
-  const parsed = parseAgentSessionKey(sessionKey);
-  return normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
-}
+export { resolveAgentIdFromSessionKey };
 
 export function resolveAgentMainSessionKey(params: {
   cfg?: { session?: { mainKey?: string } };

src/discord/monitor.ts

@@ -19,7 +19,7 @@ import { ApplicationCommandOptionType, Routes } from "discord-api-types/v10";
 
 import {
   resolveAckReaction,
-  resolveResponsePrefix,
+  resolveEffectiveMessagesConfig,
 } from "../agents/identity.js";
 import { resolveTextChunkLimit } from "../auto-reply/chunk.js";
 import { hasControlCommand } from "../auto-reply/command-detection.js";
@@ -1033,7 +1033,8 @@ export function createDiscordMessageHandler(params: {
       let didSendReply = false;
       const { dispatcher, replyOptions, markDispatchIdle } =
         createReplyDispatcherWithTyping({
-          responsePrefix: resolveResponsePrefix(cfg, route.agentId),
+          responsePrefix: resolveEffectiveMessagesConfig(cfg, route.agentId)
+            .responsePrefix,
           deliver: async (payload) => {
             await deliverDiscordReply({
               replies: [payload],
@@ -1513,7 +1514,8 @@ function createDiscordNativeCommand(params: {
 
       let didReply = false;
       const dispatcher = createReplyDispatcher({
-        responsePrefix: resolveResponsePrefix(cfg, route.agentId),
+        responsePrefix: resolveEffectiveMessagesConfig(cfg, route.agentId)
+          .responsePrefix,
         deliver: async (payload, _info) => {
           await deliverDiscordInteractionReply({
             interaction,

src/imessage/monitor.ts

@@ -1,4 +1,4 @@
-import { resolveResponsePrefix } from "../agents/identity.js";
+import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js";
 import { hasControlCommand } from "../auto-reply/command-detection.js";
 import { formatAgentEnvelope } from "../auto-reply/envelope.js";
@@ -422,7 +422,8 @@ export async function monitorIMessageProvider(
     }
 
     const dispatcher = createReplyDispatcher({
-      responsePrefix: resolveResponsePrefix(cfg, route.agentId),
+      responsePrefix: resolveEffectiveMessagesConfig(cfg, route.agentId)
+        .responsePrefix,
       deliver: async (payload) => {
         await deliverReplies({
           replies: [payload],

src/infra/heartbeat-runner.ts

@@ -1,4 +1,4 @@
-import { resolveResponsePrefix } from "../agents/identity.js";
+import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import {
   DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
   DEFAULT_HEARTBEAT_EVERY,
@@ -269,7 +269,10 @@ export async function runHeartbeatOnce(opts: {
     const ackMaxChars = resolveHeartbeatAckMaxChars(cfg);
     const normalized = normalizeHeartbeatReply(
       replyPayload,
-      resolveResponsePrefix(cfg, resolveAgentIdFromSessionKey(sessionKey)),
+      resolveEffectiveMessagesConfig(
+        cfg,
+        resolveAgentIdFromSessionKey(sessionKey),
+      ).responsePrefix,
       ackMaxChars,
     );
     if (normalized.shouldSkip && !normalized.hasMedia) {

src/msteams/reply-dispatcher.ts

@@ -1,4 +1,4 @@
-import { resolveResponsePrefix } from "../agents/identity.js";
+import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import { createReplyDispatcherWithTyping } from "../auto-reply/reply/reply-dispatcher.js";
 import type { ClawdbotConfig, MSTeamsReplyStyle } from "../config/types.js";
 import { danger } from "../globals.js";
@@ -38,7 +38,8 @@ export function createMSTeamsReplyDispatcher(params: {
   };
 
   return createReplyDispatcherWithTyping({
-    responsePrefix: resolveResponsePrefix(params.cfg, params.agentId),
+    responsePrefix: resolveEffectiveMessagesConfig(params.cfg, params.agentId)
+      .responsePrefix,
     deliver: async (payload) => {
       const messages = renderReplyPayloadsToMessages([payload], {
         textChunkLimit: params.textLimit,

src/routing/session-key.ts

@@ -7,6 +7,13 @@ export type ParsedAgentSessionKey = {
   rest: string;
 };
 
+export function resolveAgentIdFromSessionKey(
+  sessionKey: string | undefined | null,
+): string {
+  const parsed = parseAgentSessionKey(sessionKey);
+  return normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID);
+}
+
 export function normalizeAgentId(value: string | undefined | null): string {
   const trimmed = (value ?? "").trim();
   if (!trimmed) return DEFAULT_AGENT_ID;

src/signal/monitor.ts

@@ -1,4 +1,4 @@
-import { resolveResponsePrefix } from "../agents/identity.js";
+import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js";
 import { formatAgentEnvelope } from "../auto-reply/envelope.js";
 import { dispatchReplyFromConfig } from "../auto-reply/reply/dispatch-from-config.js";
@@ -508,7 +508,8 @@ export async function monitorSignalProvider(
       }
 
       const dispatcher = createReplyDispatcher({
-        responsePrefix: resolveResponsePrefix(cfg, route.agentId),
+        responsePrefix: resolveEffectiveMessagesConfig(cfg, route.agentId)
+          .responsePrefix,
         deliver: async (payload) => {
           await deliverReplies({
             replies: [payload],

src/slack/monitor.tool-result.test.ts

@@ -154,6 +154,70 @@ describe("monitorSlackProvider tool results", () => {
     expect(sendMock.mock.calls[1][1]).toBe("PFX final reply");
   });
 
+  it("derives responsePrefix from routed agent identity when unset", async () => {
+    config = {
+      agents: {
+        list: [
+          {
+            id: "main",
+            default: true,
+            identity: { name: "Mainbot", theme: "space lobster", emoji: "🦞" },
+          },
+          {
+            id: "rich",
+            identity: { name: "Richbot", theme: "lion bot", emoji: "🦁" },
+          },
+        ],
+      },
+      bindings: [
+        {
+          agentId: "rich",
+          match: { provider: "slack", peer: { kind: "dm", id: "U1" } },
+        },
+      ],
+      messages: {
+        ackReaction: "👀",
+        ackReactionScope: "group-mentions",
+      },
+      slack: { dm: { enabled: true, policy: "open", allowFrom: ["*"] } },
+    };
+
+    replyMock.mockImplementation(async (_ctx, opts) => {
+      await opts?.onToolResult?.({ text: "tool update" });
+      return { text: "final reply" };
+    });
+
+    const controller = new AbortController();
+    const run = monitorSlackProvider({
+      botToken: "bot-token",
+      appToken: "app-token",
+      abortSignal: controller.signal,
+    });
+
+    await waitForEvent("message");
+    const handler = getSlackHandlers()?.get("message");
+    if (!handler) throw new Error("Slack message handler not registered");
+
+    await handler({
+      event: {
+        type: "message",
+        user: "U1",
+        text: "hello",
+        ts: "123",
+        channel: "C1",
+        channel_type: "im",
+      },
+    });
+
+    await flush();
+    controller.abort();
+    await run;
+
+    expect(sendMock).toHaveBeenCalledTimes(2);
+    expect(sendMock.mock.calls[0][1]).toBe("[Richbot] tool update");
+    expect(sendMock.mock.calls[1][1]).toBe("[Richbot] final reply");
+  });
+
   it("updates assistant thread status when replies start", async () => {
     replyMock.mockImplementation(async (_ctx, opts) => {
       await opts?.onReplyStart?.();

src/slack/monitor.ts

@@ -6,7 +6,7 @@ import {
 import type { WebClient as SlackWebClient } from "@slack/web-api";
 import {
   resolveAckReaction,
-  resolveResponsePrefix,
+  resolveEffectiveMessagesConfig,
 } from "../agents/identity.js";
 import {
   chunkMarkdownText,
@@ -1119,7 +1119,8 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
     };
     const { dispatcher, replyOptions, markDispatchIdle } =
       createReplyDispatcherWithTyping({
-        responsePrefix: resolveResponsePrefix(cfg, route.agentId),
+        responsePrefix: resolveEffectiveMessagesConfig(cfg, route.agentId)
+          .responsePrefix,
         deliver: async (payload) => {
           await deliverReplies({
             replies: [payload],

src/telegram/bot.ts

@@ -8,7 +8,7 @@ import { Bot, InputFile, webhookCallback } from "grammy";
 import { resolveDefaultAgentId } from "../agents/agent-scope.js";
 import {
   resolveAckReaction,
-  resolveResponsePrefix,
+  resolveEffectiveMessagesConfig,
 } from "../agents/identity.js";
 import { EmbeddedBlockChunker } from "../agents/pi-embedded-block-chunker.js";
 import {
@@ -729,7 +729,8 @@ export function createTelegramBot(opts: TelegramBotOptions) {
 
     const { dispatcher, replyOptions, markDispatchIdle } =
       createReplyDispatcherWithTyping({
-        responsePrefix: resolveResponsePrefix(cfg, route.agentId),
+        responsePrefix: resolveEffectiveMessagesConfig(cfg, route.agentId)
+          .responsePrefix,
         deliver: async (payload, info) => {
           if (info.kind === "final") {
             await flushDraft();

src/web/auto-reply.ts

@@ -1,6 +1,6 @@
 import {
-  resolveIdentityNamePrefix,
-  resolveResponsePrefix,
+  resolveEffectiveMessagesConfig,
+  resolveMessagePrefix,
 } from "../agents/identity.js";
 import {
   chunkMarkdownText,
@@ -1038,13 +1038,9 @@ export async function monitorWebProvider(
 
     const buildLine = (msg: WebInboundMsg, agentId: string) => {
       // Build message prefix: explicit config > identity name > default based on allowFrom
-      let messagePrefix = cfg.messages?.messagePrefix;
-      if (messagePrefix === undefined) {
-        const hasAllowFrom = (cfg.whatsapp?.allowFrom?.length ?? 0) > 0;
-        messagePrefix = hasAllowFrom
-          ? ""
-          : (resolveIdentityNamePrefix(cfg, agentId) ?? "[clawdbot]");
-      }
+      const messagePrefix = resolveMessagePrefix(cfg, agentId, {
+        hasAllowFrom: (cfg.whatsapp?.allowFrom?.length ?? 0) > 0,
+      });
       const prefixStr = messagePrefix ? `${messagePrefix} ` : "";
       const senderLabel =
         msg.chatType === "group"
@@ -1178,7 +1174,10 @@ export async function monitorWebProvider(
       const textLimit = resolveTextChunkLimit(cfg, "whatsapp");
       let didLogHeartbeatStrip = false;
       let didSendReply = false;
-      const responsePrefix = resolveResponsePrefix(cfg, route.agentId);
+      const responsePrefix = resolveEffectiveMessagesConfig(
+        cfg,
+        route.agentId,
+      ).responsePrefix;
       const { dispatcher, replyOptions, markDispatchIdle } =
         createReplyDispatcherWithTyping({
           responsePrefix,