@botcord/daemon 0.1.1 → 0.2.1

package/src/__tests__/loop-risk.test.ts

@@ -0,0 +1,172 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  buildLoopRiskPrompt,
+  clearLoopRiskSession,
+  evaluateLoopRisk,
+  loopRiskSessionKey,
+  recordInboundText,
+  recordOutboundText,
+  resetLoopRiskStateForTests,
+  stripBotCordPromptScaffolding,
+} from "../loop-risk.js";
+
+afterEach(() => {
+  resetLoopRiskStateForTests();
+});
+
+describe("stripBotCordPromptScaffolding", () => {
+  it("removes headers, hints, and wrapper tags but keeps the actual body", () => {
+    const wrapped = [
+      "[BotCord Message] | from: ag_alice | to: ag_me | room: Team",
+      '<agent-message sender="ag_alice" sender_kind="agent">',
+      "hello world",
+      "</agent-message>",
+      "",
+      '[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.]',
+    ].join("\n");
+    expect(stripBotCordPromptScaffolding(wrapped)).toBe("hello world");
+  });
+
+  it("leaves plain text untouched", () => {
+    expect(stripBotCordPromptScaffolding("just a line")).toBe("just a line");
+  });
+});
+
+describe("evaluateLoopRisk", () => {
+  const key = "ag_me:rm_team:";
+
+  it("returns no reasons for an unknown session", () => {
+    expect(evaluateLoopRisk({ sessionKey: "unknown" })).toEqual({ reasons: [] });
+  });
+
+  it("flags short_ack_tail when the last two inbound messages are both acks", () => {
+    const now = 1_700_000_000_000;
+    recordInboundText({ sessionKey: key, text: "Let's ship it", timestamp: now - 3000 });
+    recordInboundText({ sessionKey: key, text: "Thanks!", timestamp: now - 2000 });
+    recordInboundText({ sessionKey: key, text: "好的", timestamp: now - 1000 });
+    const out = evaluateLoopRisk({ sessionKey: key, now });
+    expect(out.reasons.some((r) => r.id === "short_ack_tail")).toBe(true);
+  });
+
+  it("does NOT flag short_ack_tail when only one message is an ack", () => {
+    const now = 1_700_000_000_000;
+    recordInboundText({ sessionKey: key, text: "Can you help with X?", timestamp: now - 2000 });
+    recordInboundText({ sessionKey: key, text: "OK", timestamp: now - 1000 });
+    const out = evaluateLoopRisk({ sessionKey: key, now });
+    expect(out.reasons.some((r) => r.id === "short_ack_tail")).toBe(false);
+  });
+
+  it("flags repeated_outbound when the last outbound reply matches the previous one exactly", () => {
+    const now = 1_700_000_000_000;
+    recordOutboundText({ sessionKey: key, text: "Got it, thanks!", timestamp: now - 2000 });
+    recordOutboundText({ sessionKey: key, text: "Got it, thanks!", timestamp: now - 1000 });
+    const out = evaluateLoopRisk({ sessionKey: key, now });
+    expect(out.reasons.some((r) => r.id === "repeated_outbound")).toBe(true);
+  });
+
+  it("flags repeated_outbound on high trigram similarity (>= 0.88)", () => {
+    const now = 1_700_000_000_000;
+    const a = "Sounds good, I'll take care of that shortly.";
+    const b = "Sounds good, I'll take care of that shortly!";
+    const c = "Sounds good, I'll take care of that shortly :)";
+    recordOutboundText({ sessionKey: key, text: a, timestamp: now - 3000 });
+    recordOutboundText({ sessionKey: key, text: b, timestamp: now - 2000 });
+    recordOutboundText({ sessionKey: key, text: c, timestamp: now - 1000 });
+    const out = evaluateLoopRisk({ sessionKey: key, now });
+    expect(out.reasons.some((r) => r.id === "repeated_outbound")).toBe(true);
+  });
+
+  it("flags high_turn_rate on rapid user↔assistant alternation", () => {
+    const now = 1_700_000_000_000;
+    // 8 turns over the last 60s, tightly alternating.
+    const base = now - 60_000;
+    for (let i = 0; i < 4; i++) {
+      recordInboundText({
+        sessionKey: key,
+        text: `inbound ${i}`,
+        timestamp: base + i * 14_000,
+      });
+      recordOutboundText({
+        sessionKey: key,
+        text: `outbound ${i}`,
+        timestamp: base + i * 14_000 + 7_000,
+      });
+    }
+    const out = evaluateLoopRisk({ sessionKey: key, now });
+    expect(out.reasons.some((r) => r.id === "high_turn_rate")).toBe(true);
+  });
+
+  it("does NOT flag high_turn_rate when the turns are spread out beyond the 2-minute window", () => {
+    const now = 1_700_000_000_000;
+    const base = now - 5 * 60_000;
+    for (let i = 0; i < 4; i++) {
+      recordInboundText({
+        sessionKey: key,
+        text: `in ${i}`,
+        timestamp: base + i * 30_000,
+      });
+      recordOutboundText({
+        sessionKey: key,
+        text: `out ${i}`,
+        timestamp: base + i * 30_000 + 1000,
+      });
+    }
+    const out = evaluateLoopRisk({ sessionKey: key, now });
+    expect(out.reasons.some((r) => r.id === "high_turn_rate")).toBe(false);
+  });
+
+  it("prunes samples older than the 10-minute max age", () => {
+    const now = 1_700_000_000_000;
+    recordOutboundText({ sessionKey: key, text: "ancient", timestamp: now - 20 * 60_000 });
+    recordOutboundText({ sessionKey: key, text: "ancient", timestamp: now - 15 * 60_000 });
+    // Same text immediately before now would trigger repeated_outbound if the
+    // old samples survived; they should be pruned, so no flag fires.
+    recordOutboundText({ sessionKey: key, text: "ancient", timestamp: now });
+    const out = evaluateLoopRisk({ sessionKey: key, now });
+    expect(out.reasons.some((r) => r.id === "repeated_outbound")).toBe(false);
+  });
+
+  it("clearLoopRiskSession drops all state for the given key", () => {
+    const now = 1_700_000_000_000;
+    recordOutboundText({ sessionKey: key, text: "same", timestamp: now - 1000 });
+    recordOutboundText({ sessionKey: key, text: "same", timestamp: now });
+    clearLoopRiskSession(key);
+    expect(evaluateLoopRisk({ sessionKey: key, now }).reasons).toEqual([]);
+  });
+});
+
+describe("buildLoopRiskPrompt", () => {
+  const key = "ag_me:rm_x:";
+
+  it("returns null when no risk is detected", () => {
+    expect(buildLoopRiskPrompt({ sessionKey: key })).toBeNull();
+  });
+
+  it("renders the full prompt block when a risk fires", () => {
+    const now = 1_700_000_000_000;
+    recordOutboundText({ sessionKey: key, text: "same outbound", timestamp: now - 1000 });
+    recordOutboundText({ sessionKey: key, text: "same outbound", timestamp: now });
+    const out = buildLoopRiskPrompt({ sessionKey: key, now });
+    expect(out).toContain("[BotCord loop-risk check]");
+    expect(out).toContain("Observed signals:");
+    expect(out).toContain("recent outbound texts in this session are highly similar");
+    expect(out).toContain('reply with exactly "NO_REPLY"');
+  });
+});
+
+describe("loopRiskSessionKey", () => {
+  it("includes threadId when present", () => {
+    expect(
+      loopRiskSessionKey({ accountId: "ag_me", conversationId: "rm_1", threadId: "tp_a" }),
+    ).toBe("ag_me:rm_1:tp_a");
+  });
+
+  it("uses empty string for threadId when null/undefined", () => {
+    expect(loopRiskSessionKey({ accountId: "ag_me", conversationId: "rm_1" })).toBe(
+      "ag_me:rm_1:",
+    );
+    expect(
+      loopRiskSessionKey({ accountId: "ag_me", conversationId: "rm_1", threadId: null }),
+    ).toBe("ag_me:rm_1:");
+  });
+});

package/src/__tests__/system-context.test.ts

@@ -288,6 +288,41 @@ describe("createDaemonSystemContextBuilder", () => {
     expect(out).toBeUndefined();
   });
 
+  it("appends loopRiskBuilder output at the end of the system context", async () => {
+    const builder = createDaemonSystemContextBuilder({
+      agentId: "ag_me",
+      roomContextBuilder: async () => null,
+      loopRiskBuilder: () => "[BotCord loop-risk check]\nObserved signals:\n- x",
+    });
+    const out = await builder(
+      makeMessage({ conversation: { id: "rm_team", kind: "group" } }),
+    );
+    expect(typeof out).toBe("string");
+    expect(out).toContain("[BotCord loop-risk check]");
+  });
+
+  it("also injects loopRiskBuilder in the sync (no roomContextBuilder) branch", () => {
+    const builder = createDaemonSystemContextBuilder({
+      agentId: "ag_me",
+      loopRiskBuilder: () => "[BotCord loop-risk check]\nObserved signals:\n- y",
+    });
+    const out = builder(makeMessage()) as string | undefined;
+    expect(typeof out).toBe("string");
+    expect(out).toContain("[BotCord loop-risk check]");
+  });
+
+  it("skips loopRiskBuilder gracefully when it throws", async () => {
+    const builder = createDaemonSystemContextBuilder({
+      agentId: "ag_me",
+      roomContextBuilder: async () => null,
+      loopRiskBuilder: () => {
+        throw new Error("oops");
+      },
+    });
+    const out = await builder(makeMessage());
+    expect(out).toBeUndefined();
+  });
+
   it("translates GatewayInboundMessage.conversation.id → old `room_id` for the digest exclude key", () => {
     const tracker = new ActivityTracker({
       filePath: path.join(tmpDir, "activity.json"),

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

@@ -99,6 +99,38 @@ describe("composeBotCordUserTurn", () => {
     expect(out).toBe("");
   });
 
+  it("appends the contact-request notify-owner hint when envelope.type is contact_request", () => {
+    const out = composeBotCordUserTurn(
+      makeMessage({
+        text: "Hi, please add me",
+        sender: { id: "ag_stranger", kind: "agent" },
+        conversation: { id: "rm_dm_x", kind: "direct" },
+        raw: { envelope: { type: "contact_request" } },
+      }),
+    );
+    expect(out).toContain("contact request from ag_stranger");
+    expect(out).toContain("botcord_notify tool");
+    // Base direct-chat hint should still appear above the contact-request hint.
+    expect(out).toContain("naturally concluded");
+    const baseIdx = out.indexOf("naturally concluded");
+    const crIdx = out.indexOf("contact request from");
+    expect(crIdx).toBeGreaterThan(baseIdx);
+  });
+
+  it("does NOT append the contact-request hint for a plain message envelope", () => {
+    const out = composeBotCordUserTurn(
+      makeMessage({
+        raw: { envelope: { type: "message" } },
+      }),
+    );
+    expect(out).not.toContain("contact request from");
+  });
+
+  it("does NOT append the contact-request hint when msg.raw has no envelope", () => {
+    const out = composeBotCordUserTurn(makeMessage({ raw: {} }));
+    expect(out).not.toContain("contact request from");
+  });
+
   it("sanitizes room names so newline-based injection can't reshape the header", () => {
     const out = composeBotCordUserTurn(
       makeMessage({

package/src/daemon.ts

@@ -6,6 +6,7 @@ import {
   type ChannelAdapter,
   type GatewayChannelConfig,
   type GatewayInboundMessage,
+  type GatewayOutboundMessage,
   type GatewayLogger,
   type GatewayRuntimeSnapshot,
 } from "./gateway/index.js";
@@ -22,6 +23,12 @@ 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";
 
@@ -245,6 +252,14 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
     msg: GatewayInboundMessage,
   ) => Promise<string | undefined> | string | undefined;
   const scBuilders = new Map<string, PerAgentBuilder>();
+  const loopRiskBuilder = (msg: GatewayInboundMessage): string | null =>
+    buildLoopRiskPrompt({
+      sessionKey: loopRiskSessionKey({
+        accountId: msg.accountId,
+        conversationId: msg.conversation.id,
+        threadId: msg.conversation.threadId ?? null,
+      }),
+    });
   for (const aid of agentIds) {
     scBuilders.set(
       aid,
@@ -252,6 +267,7 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
         agentId: aid,
         activityTracker,
         roomContextBuilder,
+        loopRiskBuilder,
       }),
     );
   }
@@ -274,10 +290,34 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
   // 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: GatewayInboundMessage): void => {
+    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: GatewayOutboundMessage): void => {
+    recordLoopRiskOutbound({
+      sessionKey: loopRiskSessionKey({
+        accountId: out.accountId,
+        conversationId: out.conversationId,
+        threadId: out.threadId ?? null,
+      }),
+      text: out.text,
+    });
+  };
 
   const gateway = new Gateway({
     config: gwConfig,
@@ -298,6 +338,7 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
     turnTimeoutMs: DEFAULT_TURN_TIMEOUT_MS,
     buildSystemContext,
     onInbound,
+    onOutbound,
     composeUserTurn: composeBotCordUserTurn,
   });
 

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

@@ -255,6 +255,32 @@ describe("createBotCordChannel — inbox normalization", () => {
     }
   });
 
+  it("lets contact_request envelopes through so the composer can add the notify-owner hint", async () => {
+    const { emits, server } = await startWithInbox([
+      makeInbox({
+        hub_msg_id: "m_cr",
+        room_id: "rm_dm_peer",
+        text: "Hi, please add me",
+        envelope: {
+          type: "contact_request",
+          from: "ag_stranger",
+          payload: { text: "Hi, please add me" },
+        } as unknown as InboxMessage["envelope"],
+      }),
+    ]);
+    try {
+      expect(emits).toHaveLength(1);
+      const env = emits[0].message;
+      expect(env.sender.id).toBe("ag_stranger");
+      expect(env.text).toBe("Hi, please add me");
+      // Raw preserves envelope so turn-text can detect the type.
+      const raw = env.raw as { envelope?: { type?: string } };
+      expect(raw?.envelope?.type).toBe("contact_request");
+    } 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__/dispatcher.test.ts

@@ -350,6 +350,46 @@ describe("Dispatcher", () => {
     expect(runtime.calls[0].text).toBe("hello");
   });
 
+  it("fires onOutbound after a reply is dispatched", async () => {
+    const runtime = new FakeRuntime({ reply: "hello back", newSessionId: "sid-1" });
+    const { store, dir } = await makeStore();
+    tempDirs.push(dir);
+    const channel = new FakeChannel();
+    const outbound: string[] = [];
+    const dispatcher = new Dispatcher({
+      config: baseConfig(),
+      channels: new Map<string, ChannelAdapter>([[channel.id, channel]]),
+      runtime: () => runtime,
+      sessionStore: store,
+      log: silentLogger(),
+      onOutbound: (msg) => {
+        outbound.push(msg.text);
+      },
+    });
+    await dispatcher.handle(makeEnvelope({ id: "msg_1", text: "hi" }));
+    expect(outbound).toEqual(["hello back"]);
+  });
+
+  it("does not crash when onOutbound throws", async () => {
+    const runtime = new FakeRuntime({ reply: "hello back", newSessionId: "sid-1" });
+    const { store, dir } = await makeStore();
+    tempDirs.push(dir);
+    const channel = new FakeChannel();
+    const dispatcher = new Dispatcher({
+      config: baseConfig(),
+      channels: new Map<string, ChannelAdapter>([[channel.id, channel]]),
+      runtime: () => runtime,
+      sessionStore: store,
+      log: silentLogger(),
+      onOutbound: () => {
+        throw new Error("boom");
+      },
+    });
+    await dispatcher.handle(makeEnvelope({ id: "msg_1", text: "hi" }));
+    // Reply still went out; no assertion needed beyond the absence of a throw.
+    expect(channel.sends.length).toBe(1);
+  });
+
   it("does not crash when an errored turn has no prior session entry", async () => {
     const runtime = new FakeRuntime({ newSessionId: "", errorText: "boom" });
     const { dispatcher, store } = await scaffold({ runtimeFactory: () => runtime });

package/src/gateway/channels/botcord.ts

@@ -147,7 +147,13 @@ function normalizeInbox(
 ): GatewayInboundMessage | null {
   const env = msg.envelope;
   if (!env) return null;
-  if (env.type !== "message") return null;
+  // `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;
 
   const rawText =

package/src/gateway/dispatcher.ts

@@ -9,6 +9,7 @@ import type {
   GatewayRoute,
   GatewaySessionEntry,
   InboundObserver,
+  OutboundObserver,
   QueueMode,
   RuntimeAdapter,
   StreamBlock,
@@ -58,6 +59,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;
 }
 
 interface TurnSlot {
@@ -102,6 +109,7 @@ export class Dispatcher {
   private readonly turnTimeoutMs: number;
   private readonly buildSystemContext?: SystemContextBuilder;
   private readonly onInbound?: InboundObserver;
+  private readonly onOutbound?: OutboundObserver;
   private readonly composeUserTurn?: UserTurnBuilder;
   private readonly managedRoutes?: Map<string, GatewayRoute>;
   private readonly queues: Map<string, QueueState> = new Map();
@@ -115,6 +123,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;
   }
@@ -532,6 +541,17 @@ 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/src/gateway/gateway.ts

@@ -10,6 +10,7 @@ import type {
   GatewayRoute,
   GatewayRuntimeSnapshot,
   InboundObserver,
+  OutboundObserver,
   SystemContextBuilder,
   UserTurnBuilder,
 } from "./types.js";
@@ -42,6 +43,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;
 }
 
 /** Default runtime factory: delegates to the built-in registry; ignores extraArgs at construction. */
@@ -110,6 +116,7 @@ export class Gateway {
       buildSystemContext: opts.buildSystemContext,
       onInbound: opts.onInbound,
       composeUserTurn: opts.composeUserTurn,
+      onOutbound: opts.onOutbound,
       managedRoutes: this.managedRoutes,
     });
 

package/src/gateway/types.ts

@@ -138,6 +138,15 @@ export type InboundObserver = (
  */
 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;