@botcord/daemon 0.1.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/daemon.js

@@ -12,6 +12,7 @@ import { SnapshotWriter } from "./snapshot-writer.js";
 import { createDaemonSystemContextBuilder } from "./system-context.js";
 import { createRoomStaticContextBuilder } from "./room-context.js";
 import { createRoomContextFetcher } from "./room-context-fetcher.js";
+import { buildLoopRiskPrompt, loopRiskSessionKey, recordInboundText as recordLoopRiskInbound, recordOutboundText as recordLoopRiskOutbound, } from "./loop-risk.js";
 import { composeBotCordUserTurn } from "./turn-text.js";
 import { UserAuthManager } from "./user-auth.js";
 /**
@@ -144,11 +145,19 @@ export async function startDaemon(opts) {
         log: logger,
     });
     const scBuilders = new Map();
+    const loopRiskBuilder = (msg) => buildLoopRiskPrompt({
+        sessionKey: loopRiskSessionKey({
+            accountId: msg.accountId,
+            conversationId: msg.conversation.id,
+            threadId: msg.conversation.threadId ?? null,
+        }),
+    });
     for (const aid of agentIds) {
         scBuilders.set(aid, createDaemonSystemContextBuilder({
             agentId: aid,
             activityTracker,
             roomContextBuilder,
+            loopRiskBuilder,
         }));
     }
     const buildSystemContext = (message) => {
@@ -169,10 +178,34 @@ export async function startDaemon(opts) {
     // outside the system-context builder (option A) means the builder stays
     // pure — a cleaner contract the gateway can also expose to non-daemon
     // callers in the future.
-    const onInbound = createActivityRecorder({
+    const recordActivity = createActivityRecorder({
         activityTracker,
         ...(agentIds[0] ? { fallbackAgentId: agentIds[0] } : {}),
     });
+    const onInbound = (msg) => {
+        recordActivity(msg);
+        // Feed the loop-risk tracker with the sanitized inbound text so
+        // detectShortAckTail + detectHighTurnRate have a timeline.
+        recordLoopRiskInbound({
+            sessionKey: loopRiskSessionKey({
+                accountId: msg.accountId,
+                conversationId: msg.conversation.id,
+                threadId: msg.conversation.threadId ?? null,
+            }),
+            text: msg.text,
+            timestamp: msg.receivedAt,
+        });
+    };
+    const onOutbound = (out) => {
+        recordLoopRiskOutbound({
+            sessionKey: loopRiskSessionKey({
+                accountId: out.accountId,
+                conversationId: out.conversationId,
+                threadId: out.threadId ?? null,
+            }),
+            text: out.text,
+        });
+    };
     const gateway = new Gateway({
         config: gwConfig,
         sessionStorePath: opts.sessionStorePath ?? SESSIONS_PATH,
@@ -190,6 +223,7 @@ export async function startDaemon(opts) {
         turnTimeoutMs: DEFAULT_TURN_TIMEOUT_MS,
         buildSystemContext,
         onInbound,
+        onOutbound,
         composeUserTurn: composeBotCordUserTurn,
     });
     logger.info("daemon starting", {

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

@@ -69,7 +69,13 @@ function normalizeInbox(msg, options) {
     const env = msg.envelope;
     if (!env)
         return null;
-    if (env.type !== "message")
+    // `message` is the normal conversational envelope; `contact_request` is
+    // a lightweight inbound asking the agent to notify its owner (the
+    // composer appends the notify-owner hint). All other envelope types
+    // (notification, system, contact_added/removed, …) are still filtered
+    // out here — they belong in a separate push-notification path that
+    // daemon does not yet implement.
+    if (env.type !== "message" && env.type !== "contact_request")
         return null;
     if (!msg.room_id)
         return null;
@@ -107,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.
  *
@@ -155,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]);
                 }
@@ -171,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]);
                 }
@@ -180,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),
                             });
                         }
@@ -201,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/dispatcher.d.ts

@@ -1,6 +1,6 @@
 import type { GatewayLogger } from "./log.js";
 import { type SessionStore } from "./session-store.js";
-import type { ChannelAdapter, GatewayConfig, GatewayInboundEnvelope, GatewayRoute, InboundObserver, RuntimeAdapter, SystemContextBuilder, TurnStatusSnapshot, UserTurnBuilder } from "./types.js";
+import type { ChannelAdapter, GatewayConfig, GatewayInboundEnvelope, GatewayRoute, InboundObserver, OutboundObserver, RuntimeAdapter, SystemContextBuilder, TurnStatusSnapshot, UserTurnBuilder } from "./types.js";
 /** Factory signature for building a runtime adapter at turn dispatch time. */
 export type RuntimeFactory = (runtimeId: string, extraArgs?: string[]) => RuntimeAdapter;
 /** Constructor options for `Dispatcher`. */
@@ -36,6 +36,12 @@ export interface DispatcherOptions {
      * a fallback so a buggy composer cannot drop turns.
      */
     composeUserTurn?: UserTurnBuilder;
+    /**
+     * Optional observer fired after each reply is dispatched. Intended for
+     * outbound bookkeeping such as loop-risk tracking. Errors are logged
+     * and suppressed so observer failures never break the turn.
+     */
+    onOutbound?: OutboundObserver;
 }
 /**
  * Gateway dispatcher: consumes `GatewayInboundEnvelope` and drives a runtime
@@ -56,6 +62,7 @@ export declare class Dispatcher {
     private readonly turnTimeoutMs;
     private readonly buildSystemContext?;
     private readonly onInbound?;
+    private readonly onOutbound?;
     private readonly composeUserTurn?;
     private readonly managedRoutes?;
     private readonly queues;

package/dist/gateway/dispatcher.js

@@ -20,6 +20,7 @@ export class Dispatcher {
     turnTimeoutMs;
     buildSystemContext;
     onInbound;
+    onOutbound;
     composeUserTurn;
     managedRoutes;
     queues = new Map();
@@ -32,6 +33,7 @@ export class Dispatcher {
         this.turnTimeoutMs = opts.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
         this.buildSystemContext = opts.buildSystemContext;
         this.onInbound = opts.onInbound;
+        this.onOutbound = opts.onOutbound;
         this.composeUserTurn = opts.composeUserTurn;
         this.managedRoutes = opts.managedRoutes;
     }
@@ -414,6 +416,18 @@ export class Dispatcher {
                 conversationId: outbound.conversationId,
                 error: err instanceof Error ? err.message : String(err),
             });
+            return;
+        }
+        if (this.onOutbound) {
+            try {
+                await this.onOutbound(outbound);
+            }
+            catch (err) {
+                this.log.warn("dispatcher: onOutbound threw — continuing", {
+                    conversationId: outbound.conversationId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
         }
     }
 }

package/dist/gateway/gateway.d.ts

@@ -1,7 +1,7 @@
 import { type ChannelBackoffOptions } from "./channel-manager.js";
 import { type RuntimeFactory } from "./dispatcher.js";
 import { type GatewayLogger } from "./log.js";
-import type { ChannelAdapter, GatewayChannelConfig, GatewayConfig, GatewayRoute, GatewayRuntimeSnapshot, InboundObserver, SystemContextBuilder, UserTurnBuilder } from "./types.js";
+import type { ChannelAdapter, GatewayChannelConfig, GatewayConfig, GatewayRoute, GatewayRuntimeSnapshot, InboundObserver, OutboundObserver, SystemContextBuilder, UserTurnBuilder } from "./types.js";
 /** Constructor options for `Gateway`. */
 export interface GatewayBootOptions {
     config: GatewayConfig;
@@ -30,6 +30,11 @@ export interface GatewayBootOptions {
      * to the runtime. Forwarded to the dispatcher; see {@link UserTurnBuilder}.
      */
     composeUserTurn?: UserTurnBuilder;
+    /**
+     * Optional observer fired after each reply is sent. Intended for outbound
+     * bookkeeping like loop-risk tracking.
+     */
+    onOutbound?: OutboundObserver;
 }
 /**
  * Top-level gateway bootstrap. Wires `ChannelManager` → `Dispatcher` →

package/dist/gateway/gateway.js

@@ -63,6 +63,7 @@ export class Gateway {
             buildSystemContext: opts.buildSystemContext,
             onInbound: opts.onInbound,
             composeUserTurn: opts.composeUserTurn,
+            onOutbound: opts.onOutbound,
             managedRoutes: this.managedRoutes,
         });
         this.channelManager = new ChannelManager({

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/gateway/types.d.ts

@@ -110,6 +110,12 @@ export type InboundObserver = (message: GatewayInboundMessage) => Promise<void>
  * a buggy composer never drops turns.
  */
 export type UserTurnBuilder = (message: GatewayInboundMessage) => string;
+/**
+ * Optional hook fired after the dispatcher dispatches a reply to a channel.
+ * Intended for outbound bookkeeping (loop-risk tracking, metrics). Errors
+ * are caught and logged so observer failures never break the turn.
+ */
+export type OutboundObserver = (message: GatewayOutboundMessage) => Promise<void> | void;
 /** Outbound reply payload passed to `ChannelAdapter.send()`. */
 export interface GatewayOutboundMessage {
     channel: string;

package/dist/loop-risk.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Loop-risk guard — detects patterns that suggest two daemon-hosted agents
+ * are stuck echoing each other (or that a conversation has naturally
+ * wound down but both sides keep sending courtesy acks). When triggered,
+ * `buildLoopRiskPrompt()` returns an injected hint that encourages the
+ * agent to reply with `NO_REPLY` unless it has something substantive to
+ * add.
+ *
+ * Ported from `plugin/src/loop-risk.ts` with one structural change: plugin
+ * has OpenClaw's message transcript available (`messages: unknown[]`) so
+ * it can reconstruct historical user turns on demand. Daemon does not —
+ * Claude Code owns the transcript, not daemon. So daemon records inbound
+ * texts in a module-level map the same way plugin records outbound ones.
+ *
+ * Detectors:
+ *   - high_turn_rate  — many user↔assistant alternations in a short window
+ *   - short_ack_tail  — the last two inbound texts are acks / closure phrases
+ *   - repeated_outbound — recent outbound replies are highly similar
+ */
+export type LoopRiskReason = {
+    id: "high_turn_rate" | "short_ack_tail" | "repeated_outbound";
+    summary: string;
+};
+export interface LoopRiskEvaluation {
+    reasons: LoopRiskReason[];
+}
+/**
+ * Strip the `[BotCord Message] | …` header and `<agent-message>` / hint
+ * wrappers the user-turn composer adds around the raw inbound text. Leaves
+ * the plain body so similarity / ack detection operates on actual content.
+ * Kept in sync with `turn-text.ts` output shape.
+ */
+export declare function stripBotCordPromptScaffolding(text: string): string;
+export declare function normalizeLoopText(text: string): string;
+export declare function recordInboundText(params: {
+    sessionKey?: string;
+    text?: unknown;
+    timestamp?: number;
+}): void;
+export declare function recordOutboundText(params: {
+    sessionKey?: string;
+    text?: unknown;
+    timestamp?: number;
+}): void;
+export declare function clearLoopRiskSession(sessionKey?: string): void;
+export declare function resetLoopRiskStateForTests(): void;
+export declare function evaluateLoopRisk(params: {
+    sessionKey?: string;
+    now?: number;
+}): LoopRiskEvaluation;
+/** Build the injected system-context hint, or `null` if no risk detected. */
+export declare function buildLoopRiskPrompt(params: {
+    sessionKey?: string;
+    now?: number;
+}): string | null;
+/**
+ * Derive a loop-risk session key from a gateway inbound message or
+ * outbound reply. Keyed on (accountId, conversationId, threadId) so a
+ * DM and a group thread under the same agent don't share state.
+ */
+export declare function loopRiskSessionKey(params: {
+    accountId: string;
+    conversationId: string;
+    threadId?: string | null;
+}): string;