@botcord/daemon 0.2.1 → 0.2.2

package/dist/daemon-config-map.js

@@ -113,9 +113,10 @@ export function toGatewayConfig(cfg, opts = {}) {
     const routes = (cfg.routes ?? []).map(mapRoute);
     // Synthesize a per-agent route for every bound agent and hand it to the
     // gateway via the managed-routes bucket (plan §10.1). User-authored
-    // `cfg.routes[]` stay untouched so an explicit operator override still
-    // wins on conflict — the gateway matches `routes[] → managedRoutes →
-    // defaultRoute` in that order.
+    // `cfg.routes[]` stay untouched. Match priority (see router.ts):
+    // `routes[] with explicit accountId → managedRoutes → other routes[] →
+    // defaultRoute`. Broad prefix/kind rules no longer clobber the agent's
+    // chosen runtime — only routes that name the agent by `accountId` do.
     const managedMap = buildManagedRoutes(agentIds, opts.agentRuntimes ?? {}, defaultRoute);
     return {
         channels,

package/dist/gateway/channels/botcord.d.ts

@@ -82,6 +82,17 @@ declare function normalizeInbox(msg: InboxMessage, options: {
     channelId: string;
     accountId: string;
 }): GatewayInboundMessage | null;
+/**
+ * Shape of the `raw` field when the channel batches multiple messages into
+ * one envelope. Keeps the latest message's InboxMessage fields at top level
+ * so existing accesses (`raw.envelope.type`, `raw.source_type`, …) still
+ * work, and exposes the full list via `raw.batch`. `composeBotCordUserTurn`
+ * reads `raw.batch` to build one `<agent-message>` / `<human-message>` block
+ * per entry.
+ */
+export interface BatchedInboxRaw extends InboxMessage {
+    batch: InboxMessage[];
+}
 /**
  * Construct a BotCord channel adapter.
  *

package/dist/gateway/channels/botcord.js

@@ -113,6 +113,50 @@ function normalizeInbox(msg, options) {
         trace: { id: msg.hub_msg_id, streamable },
     };
 }
+/**
+ * Normalize a group of InboxMessages for the same `(room, topic)` into a
+ * single `GatewayInboundMessage`. The envelope carries the latest msg's
+ * metadata (routing, session key, trace) and a `raw.batch` array the
+ * composer uses to render per-sender blocks.
+ *
+ * `mentioned` is sticky: true if ANY message in the group is a mention.
+ * Returns null if no message in the group is normalizable on its own.
+ */
+function normalizeInboxBatch(msgs, options) {
+    if (msgs.length === 0)
+        return null;
+    if (msgs.length === 1)
+        return normalizeInbox(msgs[0], options);
+    const latest = msgs[msgs.length - 1];
+    const base = normalizeInbox(latest, options);
+    if (!base)
+        return null;
+    // Fold sibling metadata into the base envelope. `text` is kept non-empty
+    // when at least one batched member has a body, so the dispatcher's empty-
+    // text skip rule doesn't drop the whole batch just because the latest
+    // envelope was e.g. a zero-payload contact_request.
+    const anyMentioned = msgs.some((m) => m.mentioned === true);
+    let representativeText = base.text ?? "";
+    if (!representativeText.trim()) {
+        for (let i = msgs.length - 1; i >= 0; i--) {
+            const m = msgs[i];
+            const candidate = m.text ??
+                (typeof m.envelope?.payload?.text === "string"
+                    ? m.envelope.payload.text
+                    : "");
+            if (candidate && candidate.trim()) {
+                representativeText = candidate;
+                break;
+            }
+        }
+    }
+    return {
+        ...base,
+        text: representativeText,
+        mentioned: anyMentioned,
+        raw: { ...latest, batch: msgs },
+    };
+}
 /**
  * Construct a BotCord channel adapter.
  *
@@ -161,9 +205,14 @@ export function createBotCordChannel(options) {
         log.info("botcord inbox drained", { count: msgs.length });
         if (msgs.length === 0)
             return;
+        // First pass: ack duplicates/skipped messages so Hub stops requeueing,
+        // and collect eligible messages preserving poll order. Grouping by
+        // `(room_id, topic)` mirrors plugin's `handleInboxMessageBatch` — the
+        // same conversation thread folds into one turn so the agent sees all
+        // new messages at once instead of running N turns back-to-back.
+        const eligible = [];
         for (const msg of msgs) {
             if (!rememberSeen(msg.hub_msg_id)) {
-                // Already emitted; ack again so Hub stops requeueing.
                 try {
                     await client.ackMessages([msg.hub_msg_id]);
                 }
@@ -177,7 +226,6 @@ export function createBotCordChannel(options) {
                 accountId: options.accountId,
             });
             if (!normalized) {
-                // Not eligible (wrong type, missing room, etc.) — ack so it drops.
                 try {
                     await client.ackMessages([msg.hub_msg_id]);
                 }
@@ -186,16 +234,42 @@ export function createBotCordChannel(options) {
                 }
                 continue;
             }
+            eligible.push(msg);
+        }
+        if (eligible.length === 0)
+            return;
+        // Group by `(room_id, topic)`. Insertion order is the poll order, so
+        // iterating the map yields groups with the same external chronology.
+        const groups = new Map();
+        for (const msg of eligible) {
+            const topic = msg.topic_id ?? msg.topic ?? "";
+            const key = `${msg.room_id ?? ""}:${topic}`;
+            const list = groups.get(key);
+            if (list)
+                list.push(msg);
+            else
+                groups.set(key, [msg]);
+        }
+        for (const group of groups.values()) {
+            const normalized = normalizeInboxBatch(group, {
+                channelId: options.id,
+                accountId: options.accountId,
+            });
+            if (!normalized)
+                continue;
+            const hubIds = group.map((m) => m.hub_msg_id);
             const envelope = {
                 message: normalized,
                 ack: {
                     accept: async () => {
                         try {
-                            await client.ackMessages([msg.hub_msg_id]);
+                            // Ack the entire batch together so Hub never re-delivers any
+                            // member of this turn if the agent succeeds on the group.
+                            await client.ackMessages(hubIds);
                         }
                         catch (err) {
                             log.warn("botcord ack failed — relying on seen-cache dedup", {
-                                hubMsgId: msg.hub_msg_id,
+                                hubMsgIds: hubIds,
                                 err: String(err),
                             });
                         }
@@ -207,7 +281,7 @@ export function createBotCordChannel(options) {
             }
             catch (err) {
                 log.error("botcord emit threw", {
-                    hubMsgId: msg.hub_msg_id,
+                    hubMsgIds: hubIds,
                     err: String(err),
                 });
             }

package/dist/gateway/router.d.ts

@@ -3,8 +3,13 @@ import type { GatewayConfig, GatewayInboundMessage, GatewayRoute, RouteMatch } f
 export declare function matchesRoute(message: GatewayInboundMessage, match: RouteMatch | undefined): boolean;
 /**
  * Picks the first matching route in priority order:
- *   1. `config.routes[]` (user-authored)
- *   2. `managedRoutes` (daemon-synthesized per-agent)
- *   3. `config.defaultRoute`
+ *   1. `config.routes[]` entries whose `match.accountId` names this message's
+ *      accountId — explicit operator override for a specific agent.
+ *   2. `managedRoutes` (daemon-synthesized per-agent, reflects the runtime
+ *      the user picked when provisioning the agent). Broad user routes do
+ *      NOT clobber this, because the agent's runtime is itself an explicit
+ *      user choice — a catch-all prefix rule shouldn't silently downgrade it.
+ *   3. Remaining `config.routes[]` (broad prefix/kind/channel rules).
+ *   4. `config.defaultRoute`.
  */
 export declare function resolveRoute(message: GatewayInboundMessage, config: Pick<GatewayConfig, "defaultRoute" | "routes">, managedRoutes?: readonly GatewayRoute[]): GatewayRoute;

package/dist/gateway/router.js

@@ -28,15 +28,21 @@ export function matchesRoute(message, match) {
 }
 /**
  * Picks the first matching route in priority order:
- *   1. `config.routes[]` (user-authored)
- *   2. `managedRoutes` (daemon-synthesized per-agent)
- *   3. `config.defaultRoute`
+ *   1. `config.routes[]` entries whose `match.accountId` names this message's
+ *      accountId — explicit operator override for a specific agent.
+ *   2. `managedRoutes` (daemon-synthesized per-agent, reflects the runtime
+ *      the user picked when provisioning the agent). Broad user routes do
+ *      NOT clobber this, because the agent's runtime is itself an explicit
+ *      user choice — a catch-all prefix rule shouldn't silently downgrade it.
+ *   3. Remaining `config.routes[]` (broad prefix/kind/channel rules).
+ *   4. `config.defaultRoute`.
  */
 export function resolveRoute(message, config, managedRoutes) {
     const routes = config.routes ?? [];
     for (const route of routes) {
-        if (matchesRoute(message, route.match))
+        if (route.match?.accountId === message.accountId && matchesRoute(message, route.match)) {
             return route;
+        }
     }
     if (managedRoutes) {
         for (const route of managedRoutes) {
@@ -44,5 +50,9 @@ export function resolveRoute(message, config, managedRoutes) {
                 return route;
         }
     }
+    for (const route of routes) {
+        if (matchesRoute(message, route.match))
+            return route;
+    }
     return config.defaultRoute;
 }

package/dist/turn-text.js

@@ -1,4 +1,4 @@
-import { sanitizeSenderName } from "./gateway/index.js";
+import { sanitizeSenderName, sanitizeUntrustedContent } from "./gateway/index.js";
 import { classifyActivitySender } from "./sender-classify.js";
 const GROUP_HINT = '[In group chats, do NOT reply unless you are explicitly mentioned or addressed. ' +
     'If no response is needed, reply with exactly "NO_REPLY" and nothing else.]';
@@ -18,6 +18,39 @@ function readEnvelopeType(raw) {
     const t = env.type;
     return typeof t === "string" ? t : undefined;
 }
+/**
+ * Read the `raw.batch` array emitted by the BotCord channel when inbox
+ * drain groups multiple messages for the same `(room, topic)`. Returns the
+ * list when present and well-shaped, else null. Single-message envelopes
+ * have no `batch` field and fall through to the single-message path.
+ */
+function readBatch(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const b = raw.batch;
+    if (!Array.isArray(b) || b.length < 2)
+        return null;
+    return b;
+}
+function entryFromLabel(e) {
+    const envType = typeof e.envelope?.type === "string" ? e.envelope.type : undefined;
+    const isHuman = e.source_type === "dashboard_human_room" ||
+        (typeof e.envelope?.from === "string" && e.envelope.from.startsWith("hu_"));
+    const fromId = typeof e.envelope?.from === "string" ? e.envelope.from : "unknown";
+    const label = isHuman
+        ? typeof e.source_user_name === "string" && e.source_user_name
+            ? e.source_user_name
+            : "User"
+        : fromId;
+    return { label, kind: isHuman ? "human" : "agent", envelopeType: envType };
+}
+function entryText(e) {
+    if (typeof e.text === "string")
+        return e.text;
+    if (typeof e.envelope?.payload?.text === "string")
+        return e.envelope.payload.text;
+    return "";
+}
 /**
  * Compose the user-turn text for a BotCord inbound message.
  *
@@ -37,6 +70,10 @@ export function composeBotCordUserTurn(msg) {
     // system-context handles context; wrapping here would just add noise.
     if (sender.kind === "owner")
         return trimmed;
+    const batch = readBatch(msg.raw);
+    if (batch) {
+        return composeBatchedTurn(msg, batch);
+    }
     const conversation = msg.conversation;
     const isGroup = conversation.kind === "group";
     const roomTitle = typeof conversation.title === "string" ? conversation.title : undefined;
@@ -85,3 +122,53 @@ export function composeBotCordUserTurn(msg) {
     }
     return lines.join("\n");
 }
+/**
+ * Render a batched turn (≥2 messages from the same room/topic folded into
+ * one envelope by `botcord.ts:normalizeInboxBatch`). Mirrors plugin's
+ * `handleA2AGroup` output shape so Claude Code sees the same prompt
+ * whether driven by OpenClaw or by daemon.
+ */
+function composeBatchedTurn(msg, batch) {
+    const conversation = msg.conversation;
+    const isGroup = conversation.kind === "group";
+    const roomTitle = typeof conversation.title === "string" ? conversation.title : undefined;
+    const header = [
+        `[BotCord Messages (${batch.length} new)]`,
+        `to: ${msg.accountId}`,
+    ];
+    if (isGroup && roomTitle) {
+        const safeRoom = sanitizeSenderName(roomTitle.replace(/[\r\n]+/g, " "));
+        header.push(`room: ${safeRoom}`);
+    }
+    if (msg.mentioned) {
+        header.push("mentioned: true");
+    }
+    const blocks = [];
+    const contactRequestSenders = [];
+    for (const entry of batch) {
+        const { label, kind, envelopeType } = entryFromLabel(entry);
+        const safeLabel = sanitizeSenderName(label);
+        const raw = entryText(entry);
+        // Owner-trust bypass is handled at the outer level — by the time we
+        // reach a batched turn the sender classifier has already returned
+        // non-owner. Still sanitize defensively.
+        const safeBody = sanitizeUntrustedContent(raw);
+        const tag = kind === "human" ? "human-message" : "agent-message";
+        blocks.push(`<${tag} sender="${safeLabel}" sender_kind="${kind}">\n${safeBody}\n</${tag}>`);
+        if (envelopeType === "contact_request") {
+            contactRequestSenders.push(safeLabel);
+        }
+    }
+    const hint = isGroup ? GROUP_HINT : DIRECT_HINT;
+    const lines = [header.join(" | "), blocks.join("\n"), "", hint];
+    if (contactRequestSenders.length > 0) {
+        // Dedup + list — multiple distinct senders show as "A, B".
+        const unique = Array.from(new Set(contactRequestSenders));
+        lines.push("", "[You received a contact request from " +
+            unique.join(", ") +
+            ". Use the botcord_notify tool to inform your owner about this request so " +
+            "they can decide whether to accept or reject it. Include the sender's " +
+            "agent ID and any message they attached.]");
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/daemon",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
   "type": "module",
   "bin": {

package/src/__tests__/turn-text.test.ts

@@ -131,6 +131,117 @@ describe("composeBotCordUserTurn", () => {
     expect(out).not.toContain("contact request from");
   });
 
+  it("renders a multi-message batch as [BotCord Messages (N new)] with one block per sender", () => {
+    const batch = [
+      {
+        hub_msg_id: "m1",
+        text: "first message",
+        envelope: { from: "ag_alice", type: "message" },
+      },
+      {
+        hub_msg_id: "m2",
+        text: "second message",
+        envelope: { from: "ag_bob", type: "message" },
+        mentioned: true,
+      },
+    ];
+    const out = composeBotCordUserTurn(
+      makeMessage({
+        text: "second message",
+        sender: { id: "ag_bob", kind: "agent" },
+        conversation: { id: "rm_team", kind: "group", title: "Ouraca" },
+        mentioned: true,
+        raw: { batch, envelope: { type: "message", from: "ag_bob" } },
+      }),
+    );
+    expect(out).toContain("[BotCord Messages (2 new)]");
+    expect(out).toContain("room: Ouraca");
+    expect(out).toContain("mentioned: true");
+    expect(out).toContain('<agent-message sender="ag_alice" sender_kind="agent">');
+    expect(out).toContain("first message");
+    expect(out).toContain('<agent-message sender="ag_bob" sender_kind="agent">');
+    expect(out).toContain("second message");
+    // Single-message header must NOT appear in batch mode.
+    expect(out).not.toContain("[BotCord Message]");
+    // Group hint still appears after the blocks.
+    expect(out).toContain("do NOT reply unless");
+  });
+
+  it("batched path tags dashboard_human_room senders as human-message", () => {
+    const batch = [
+      {
+        hub_msg_id: "m1",
+        text: "hi bot",
+        envelope: { from: "ag_me", type: "message" },
+        source_type: "dashboard_human_room",
+        source_user_name: "Alice",
+      },
+      {
+        hub_msg_id: "m2",
+        text: "你好",
+        envelope: { from: "ag_peer", type: "message" },
+      },
+    ];
+    const out = composeBotCordUserTurn(
+      makeMessage({
+        text: "你好",
+        sender: { id: "ag_peer", kind: "agent" },
+        conversation: { id: "rm_team", kind: "group" },
+        raw: { batch, envelope: { type: "message", from: "ag_peer" } },
+      }),
+    );
+    expect(out).toContain('<human-message sender="Alice" sender_kind="human">');
+    expect(out).toContain("hi bot");
+    expect(out).toContain('<agent-message sender="ag_peer" sender_kind="agent">');
+  });
+
+  it("batched path appends a single notify-owner hint listing every contact_request sender", () => {
+    const batch = [
+      {
+        hub_msg_id: "m1",
+        text: "please add me",
+        envelope: { from: "ag_stranger_a", type: "contact_request" },
+      },
+      {
+        hub_msg_id: "m2",
+        text: "add me too",
+        envelope: { from: "ag_stranger_b", type: "contact_request" },
+      },
+      {
+        hub_msg_id: "m3",
+        text: "normal reply",
+        envelope: { from: "ag_old_friend", type: "message" },
+      },
+    ];
+    const out = composeBotCordUserTurn(
+      makeMessage({
+        text: "normal reply",
+        sender: { id: "ag_old_friend", kind: "agent" },
+        conversation: { id: "rm_dm_x", kind: "direct" },
+        raw: { batch, envelope: { type: "message", from: "ag_old_friend" } },
+      }),
+    );
+    expect(out).toContain("contact request from ag_stranger_a, ag_stranger_b");
+    // Direct hint (not group) for a DM room.
+    expect(out).toContain("naturally concluded");
+  });
+
+  it("falls back to the single-message path when raw.batch has only one entry", () => {
+    const out = composeBotCordUserTurn(
+      makeMessage({
+        raw: {
+          batch: [
+            { hub_msg_id: "m1", text: "solo", envelope: { from: "ag_x", type: "message" } },
+          ],
+          envelope: { type: "message", from: "ag_x" },
+        },
+      }),
+    );
+    // batch length 1 → readBatch returns null → single-message header.
+    expect(out).toContain("[BotCord Message]");
+    expect(out).not.toContain("[BotCord Messages (");
+  });
+
   it("sanitizes room names so newline-based injection can't reshape the header", () => {
     const out = composeBotCordUserTurn(
       makeMessage({

package/src/daemon-config-map.ts

@@ -150,9 +150,10 @@ export function toGatewayConfig(
 
   // Synthesize a per-agent route for every bound agent and hand it to the
   // gateway via the managed-routes bucket (plan §10.1). User-authored
-  // `cfg.routes[]` stay untouched so an explicit operator override still
-  // wins on conflict — the gateway matches `routes[] → managedRoutes →
-  // defaultRoute` in that order.
+  // `cfg.routes[]` stay untouched. Match priority (see router.ts):
+  // `routes[] with explicit accountId → managedRoutes → other routes[] →
+  // defaultRoute`. Broad prefix/kind rules no longer clobber the agent's
+  // chosen runtime — only routes that name the agent by `accountId` do.
   const managedMap = buildManagedRoutes(
     agentIds,
     opts.agentRuntimes ?? {},

package/src/gateway/__tests__/botcord-channel.test.ts

@@ -281,6 +281,69 @@ describe("createBotCordChannel — inbox normalization", () => {
     }
   });
 
+  it("groups two messages in the same room/topic into one batched envelope", async () => {
+    const server = await startAuthOkServer();
+    try {
+      const polled = [
+        makeInbox({
+          hub_msg_id: "m_b1",
+          room_id: "rm_team",
+          room_name: "Team",
+          text: "hi all",
+          envelope: { from: "ag_alice" } as InboxMessage["envelope"],
+        }),
+        makeInbox({
+          hub_msg_id: "m_b2",
+          room_id: "rm_team",
+          room_name: "Team",
+          text: "yeah",
+          envelope: { from: "ag_bob" } as InboxMessage["envelope"],
+          mentioned: true,
+        }),
+      ];
+      const client = makeClient({
+        pollInbox: vi.fn().mockResolvedValue({ messages: polled, count: 2, has_more: false }),
+        getHubUrl: vi.fn().mockReturnValue(server.url),
+      });
+      const channel = createBotCordChannel({
+        id: "botcord-main",
+        accountId: "ag_self",
+        agentId: "ag_self",
+        client,
+        hubBaseUrl: server.url,
+      });
+      const abort = new AbortController();
+      const emits: GatewayInboundEnvelope[] = [];
+      const startP = channel.start({
+        config: stubConfig,
+        accountId: "ag_self",
+        abortSignal: abort.signal,
+        log: silentLog,
+        emit: async (env) => {
+          emits.push(env);
+        },
+        setStatus: () => {},
+      });
+      await vi.waitFor(() => expect(emits).toHaveLength(1));
+      const env = emits[0]!.message;
+      // Last sender wins for representative metadata; mentioned is sticky.
+      expect(env.sender.id).toBe("ag_bob");
+      expect(env.mentioned).toBe(true);
+      const raw = env.raw as { batch?: Array<{ hub_msg_id: string }> };
+      expect(Array.isArray(raw.batch)).toBe(true);
+      expect(raw.batch!.map((m) => m.hub_msg_id)).toEqual(["m_b1", "m_b2"]);
+
+      // One accept() call acks BOTH hub ids together.
+      await emits[0]!.ack!.accept();
+      expect(client.ackMessages).toHaveBeenCalledWith(["m_b1", "m_b2"]);
+
+      abort.abort();
+      await startP;
+    } finally {
+      await server.close();
+    }
+  });
+
   it("sanitizes prompt-injection markers in untrusted text but not in owner-chat", async () => {
     const { emits, server } = await startWithInbox([
       makeInbox({

package/src/gateway/__tests__/router.test.ts

@@ -78,13 +78,39 @@ describe("resolveRoute", () => {
   });
 
   describe("managedRoutes", () => {
-    it("user cfg.routes match wins over managed for same accountId", () => {
+    it("user route with explicit accountId wins over managed for same agent", () => {
       const user = makeRoute({ runtime: "user", match: { accountId: "ag_1" } });
       const managed = makeRoute({ runtime: "managed", match: { accountId: "ag_1" } });
       const msg = makeMessage({ accountId: "ag_1" });
       expect(resolveRoute(msg, { defaultRoute, routes: [user] }, [managed])).toBe(user);
     });
 
+    it("broad user route (no accountId) does NOT override managed per-agent route", () => {
+      const broad = makeRoute({
+        runtime: "broad",
+        match: { conversationPrefix: "rm_oc_" },
+      });
+      const managed = makeRoute({ runtime: "managed", match: { accountId: "ag_1" } });
+      const msg = makeMessage({
+        accountId: "ag_1",
+        conversation: { id: "rm_oc_abc", kind: "group" },
+      });
+      expect(resolveRoute(msg, { defaultRoute, routes: [broad] }, [managed])).toBe(managed);
+    });
+
+    it("broad user route applies when no managed route matches the agent", () => {
+      const broad = makeRoute({
+        runtime: "broad",
+        match: { conversationPrefix: "rm_oc_" },
+      });
+      const managed = makeRoute({ runtime: "managed", match: { accountId: "ag_other" } });
+      const msg = makeMessage({
+        accountId: "ag_1",
+        conversation: { id: "rm_oc_abc", kind: "group" },
+      });
+      expect(resolveRoute(msg, { defaultRoute, routes: [broad] }, [managed])).toBe(broad);
+    });
+
     it("no user match + managed match → managed wins", () => {
       const managed = makeRoute({ runtime: "managed", match: { accountId: "ag_1" } });
       const msg = makeMessage({ accountId: "ag_1" });

package/src/gateway/channels/botcord.ts

@@ -196,6 +196,66 @@ function normalizeInbox(
   };
 }
 
+/**
+ * Shape of the `raw` field when the channel batches multiple messages into
+ * one envelope. Keeps the latest message's InboxMessage fields at top level
+ * so existing accesses (`raw.envelope.type`, `raw.source_type`, …) still
+ * work, and exposes the full list via `raw.batch`. `composeBotCordUserTurn`
+ * reads `raw.batch` to build one `<agent-message>` / `<human-message>` block
+ * per entry.
+ */
+export interface BatchedInboxRaw extends InboxMessage {
+  batch: InboxMessage[];
+}
+
+/**
+ * Normalize a group of InboxMessages for the same `(room, topic)` into a
+ * single `GatewayInboundMessage`. The envelope carries the latest msg's
+ * metadata (routing, session key, trace) and a `raw.batch` array the
+ * composer uses to render per-sender blocks.
+ *
+ * `mentioned` is sticky: true if ANY message in the group is a mention.
+ * Returns null if no message in the group is normalizable on its own.
+ */
+function normalizeInboxBatch(
+  msgs: InboxMessage[],
+  options: { channelId: string; accountId: string },
+): GatewayInboundMessage | null {
+  if (msgs.length === 0) return null;
+  if (msgs.length === 1) return normalizeInbox(msgs[0]!, options);
+
+  const latest = msgs[msgs.length - 1]!;
+  const base = normalizeInbox(latest, options);
+  if (!base) return null;
+
+  // Fold sibling metadata into the base envelope. `text` is kept non-empty
+  // when at least one batched member has a body, so the dispatcher's empty-
+  // text skip rule doesn't drop the whole batch just because the latest
+  // envelope was e.g. a zero-payload contact_request.
+  const anyMentioned = msgs.some((m) => m.mentioned === true);
+  let representativeText = base.text ?? "";
+  if (!representativeText.trim()) {
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const m = msgs[i]!;
+      const candidate =
+        m.text ??
+        (typeof m.envelope?.payload?.text === "string"
+          ? (m.envelope.payload.text as string)
+          : "");
+      if (candidate && candidate.trim()) {
+        representativeText = candidate;
+        break;
+      }
+    }
+  }
+  return {
+    ...base,
+    text: representativeText,
+    mentioned: anyMentioned,
+    raw: { ...latest, batch: msgs } satisfies BatchedInboxRaw,
+  };
+}
+
 /**
  * Construct a BotCord channel adapter.
  *
@@ -250,9 +310,14 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
     log.info("botcord inbox drained", { count: msgs.length });
     if (msgs.length === 0) return;
 
+    // First pass: ack duplicates/skipped messages so Hub stops requeueing,
+    // and collect eligible messages preserving poll order. Grouping by
+    // `(room_id, topic)` mirrors plugin's `handleInboxMessageBatch` — the
+    // same conversation thread folds into one turn so the agent sees all
+    // new messages at once instead of running N turns back-to-back.
+    const eligible: InboxMessage[] = [];
     for (const msg of msgs) {
       if (!rememberSeen(msg.hub_msg_id)) {
-        // Already emitted; ack again so Hub stops requeueing.
         try {
           await client.ackMessages([msg.hub_msg_id]);
         } catch (err) {
@@ -265,7 +330,6 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         accountId: options.accountId,
       });
       if (!normalized) {
-        // Not eligible (wrong type, missing room, etc.) — ack so it drops.
         try {
           await client.ackMessages([msg.hub_msg_id]);
         } catch (err) {
@@ -273,15 +337,41 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         }
         continue;
       }
+      eligible.push(msg);
+    }
+
+    if (eligible.length === 0) return;
+
+    // Group by `(room_id, topic)`. Insertion order is the poll order, so
+    // iterating the map yields groups with the same external chronology.
+    const groups = new Map<string, InboxMessage[]>();
+    for (const msg of eligible) {
+      const topic = msg.topic_id ?? msg.topic ?? "";
+      const key = `${msg.room_id ?? ""}:${topic}`;
+      const list = groups.get(key);
+      if (list) list.push(msg);
+      else groups.set(key, [msg]);
+    }
+
+    for (const group of groups.values()) {
+      const normalized = normalizeInboxBatch(group, {
+        channelId: options.id,
+        accountId: options.accountId,
+      });
+      if (!normalized) continue;
+
+      const hubIds = group.map((m) => m.hub_msg_id);
       const envelope: GatewayInboundEnvelope = {
         message: normalized,
         ack: {
           accept: async () => {
             try {
-              await client.ackMessages([msg.hub_msg_id]);
+              // Ack the entire batch together so Hub never re-delivers any
+              // member of this turn if the agent succeeds on the group.
+              await client.ackMessages(hubIds);
             } catch (err) {
               log.warn("botcord ack failed — relying on seen-cache dedup", {
-                hubMsgId: msg.hub_msg_id,
+                hubMsgIds: hubIds,
                 err: String(err),
               });
             }
@@ -292,7 +382,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         await emit(envelope);
       } catch (err) {
         log.error("botcord emit threw", {
-          hubMsgId: msg.hub_msg_id,
+          hubMsgIds: hubIds,
           err: String(err),
         });
       }

package/src/gateway/router.ts

@@ -38,9 +38,14 @@ export function matchesRoute(
 
 /**
  * Picks the first matching route in priority order:
- *   1. `config.routes[]` (user-authored)
- *   2. `managedRoutes` (daemon-synthesized per-agent)
- *   3. `config.defaultRoute`
+ *   1. `config.routes[]` entries whose `match.accountId` names this message's
+ *      accountId — explicit operator override for a specific agent.
+ *   2. `managedRoutes` (daemon-synthesized per-agent, reflects the runtime
+ *      the user picked when provisioning the agent). Broad user routes do
+ *      NOT clobber this, because the agent's runtime is itself an explicit
+ *      user choice — a catch-all prefix rule shouldn't silently downgrade it.
+ *   3. Remaining `config.routes[]` (broad prefix/kind/channel rules).
+ *   4. `config.defaultRoute`.
  */
 export function resolveRoute(
   message: GatewayInboundMessage,
@@ -48,13 +53,22 @@ export function resolveRoute(
   managedRoutes?: readonly GatewayRoute[],
 ): GatewayRoute {
   const routes = config.routes ?? [];
+
   for (const route of routes) {
-    if (matchesRoute(message, route.match)) return route;
+    if (route.match?.accountId === message.accountId && matchesRoute(message, route.match)) {
+      return route;
+    }
   }
+
   if (managedRoutes) {
     for (const route of managedRoutes) {
       if (matchesRoute(message, route.match)) return route;
     }
   }
+
+  for (const route of routes) {
+    if (matchesRoute(message, route.match)) return route;
+  }
+
   return config.defaultRoute;
 }

package/src/turn-text.ts

@@ -24,7 +24,7 @@
  * model the context it needs.
  */
 import type { GatewayInboundMessage } from "./gateway/index.js";
-import { sanitizeSenderName } from "./gateway/index.js";
+import { sanitizeSenderName, sanitizeUntrustedContent } from "./gateway/index.js";
 import { classifyActivitySender } from "./sender-classify.js";
 
 const GROUP_HINT =
@@ -47,6 +47,55 @@ function readEnvelopeType(raw: unknown): string | undefined {
   return typeof t === "string" ? t : undefined;
 }
 
+/** Minimal shape of one batched inbound entry. Matches the BotCord channel
+ * `BatchedInboxRaw.batch[]` elements but expressed structurally so the
+ * composer doesn't import channel internals. */
+interface BatchedEntry {
+  hub_msg_id?: unknown;
+  text?: unknown;
+  envelope?: { from?: unknown; type?: unknown; payload?: { text?: unknown } };
+  source_type?: unknown;
+  source_user_name?: unknown;
+  mentioned?: unknown;
+}
+
+/**
+ * Read the `raw.batch` array emitted by the BotCord channel when inbox
+ * drain groups multiple messages for the same `(room, topic)`. Returns the
+ * list when present and well-shaped, else null. Single-message envelopes
+ * have no `batch` field and fall through to the single-message path.
+ */
+function readBatch(raw: unknown): BatchedEntry[] | null {
+  if (!raw || typeof raw !== "object") return null;
+  const b = (raw as { batch?: unknown }).batch;
+  if (!Array.isArray(b) || b.length < 2) return null;
+  return b as BatchedEntry[];
+}
+
+function entryFromLabel(e: BatchedEntry): {
+  label: string;
+  kind: "human" | "agent";
+  envelopeType: string | undefined;
+} {
+  const envType = typeof e.envelope?.type === "string" ? e.envelope.type : undefined;
+  const isHuman =
+    e.source_type === "dashboard_human_room" ||
+    (typeof e.envelope?.from === "string" && e.envelope.from.startsWith("hu_"));
+  const fromId = typeof e.envelope?.from === "string" ? e.envelope.from : "unknown";
+  const label = isHuman
+    ? typeof e.source_user_name === "string" && e.source_user_name
+      ? e.source_user_name
+      : "User"
+    : fromId;
+  return { label, kind: isHuman ? "human" : "agent", envelopeType: envType };
+}
+
+function entryText(e: BatchedEntry): string {
+  if (typeof e.text === "string") return e.text;
+  if (typeof e.envelope?.payload?.text === "string") return e.envelope.payload.text;
+  return "";
+}
+
 /**
  * Compose the user-turn text for a BotCord inbound message.
  *
@@ -67,6 +116,11 @@ export function composeBotCordUserTurn(msg: GatewayInboundMessage): string {
   // system-context handles context; wrapping here would just add noise.
   if (sender.kind === "owner") return trimmed;
 
+  const batch = readBatch(msg.raw);
+  if (batch) {
+    return composeBatchedTurn(msg, batch);
+  }
+
   const conversation = msg.conversation;
   const isGroup = conversation.kind === "group";
   const roomTitle =
@@ -121,3 +175,67 @@ export function composeBotCordUserTurn(msg: GatewayInboundMessage): string {
   }
   return lines.join("\n");
 }
+
+/**
+ * Render a batched turn (≥2 messages from the same room/topic folded into
+ * one envelope by `botcord.ts:normalizeInboxBatch`). Mirrors plugin's
+ * `handleA2AGroup` output shape so Claude Code sees the same prompt
+ * whether driven by OpenClaw or by daemon.
+ */
+function composeBatchedTurn(
+  msg: GatewayInboundMessage,
+  batch: BatchedEntry[],
+): string {
+  const conversation = msg.conversation;
+  const isGroup = conversation.kind === "group";
+  const roomTitle =
+    typeof conversation.title === "string" ? conversation.title : undefined;
+
+  const header: string[] = [
+    `[BotCord Messages (${batch.length} new)]`,
+    `to: ${msg.accountId}`,
+  ];
+  if (isGroup && roomTitle) {
+    const safeRoom = sanitizeSenderName(roomTitle.replace(/[\r\n]+/g, " "));
+    header.push(`room: ${safeRoom}`);
+  }
+  if (msg.mentioned) {
+    header.push("mentioned: true");
+  }
+
+  const blocks: string[] = [];
+  const contactRequestSenders: string[] = [];
+  for (const entry of batch) {
+    const { label, kind, envelopeType } = entryFromLabel(entry);
+    const safeLabel = sanitizeSenderName(label);
+    const raw = entryText(entry);
+    // Owner-trust bypass is handled at the outer level — by the time we
+    // reach a batched turn the sender classifier has already returned
+    // non-owner. Still sanitize defensively.
+    const safeBody = sanitizeUntrustedContent(raw);
+    const tag = kind === "human" ? "human-message" : "agent-message";
+    blocks.push(
+      `<${tag} sender="${safeLabel}" sender_kind="${kind}">\n${safeBody}\n</${tag}>`,
+    );
+    if (envelopeType === "contact_request") {
+      contactRequestSenders.push(safeLabel);
+    }
+  }
+
+  const hint = isGroup ? GROUP_HINT : DIRECT_HINT;
+  const lines: string[] = [header.join(" | "), blocks.join("\n"), "", hint];
+
+  if (contactRequestSenders.length > 0) {
+    // Dedup + list — multiple distinct senders show as "A, B".
+    const unique = Array.from(new Set(contactRequestSenders));
+    lines.push(
+      "",
+      "[You received a contact request from " +
+        unique.join(", ") +
+        ". Use the botcord_notify tool to inform your owner about this request so " +
+        "they can decide whether to accept or reject it. Include the sender's " +
+        "agent ID and any message they attached.]",
+    );
+  }
+  return lines.join("\n");
+}