@botcord/daemon 0.1.1 → 0.2.2

package/dist/loop-risk.js

@@ -0,0 +1,286 @@
+/**
+ * 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
+ */
+// Module-level state. Keys are caller-supplied session identifiers
+// (daemon uses `${accountId}:${conversationId}:${threadId ?? ""}`).
+const inboundBySession = new Map();
+const outboundBySession = new Map();
+// --- Tunables ---------------------------------------------------------
+const TURN_WINDOW_MS = 2 * 60_000;
+const TURN_THRESHOLD = 8;
+const ALTERNATION_THRESHOLD = 6;
+const MIN_TURNS_PER_SIDE = 3;
+const SAMPLE_MAX_AGE_MS = 10 * 60_000;
+const MAX_TRACKED_PER_SIDE = 6;
+const SHORT_ACK_MAX_CHARS = 48;
+const MIN_REPEAT_TEXT_CHARS = 6;
+const OUTBOUND_SIMILARITY_THRESHOLD = 0.88;
+// --- Ack / closure phrase lists (mirrors plugin) ----------------------
+const ENGLISH_ACK_OR_CLOSURE = new Set([
+    "ok", "okay", "got it", "thanks", "thank you", "noted", "understood",
+    "sounds good", "sgtm", "roger", "copy", "will do", "all good",
+    "no worries", "bye", "goodbye", "see you", "talk later",
+]);
+const CHINESE_ACK_OR_CLOSURE = new Set([
+    "收到", "好的", "好", "行", "嗯", "嗯嗯", "明白", "明白了", "知道了",
+    "谢谢", "谢谢你", "感谢", "辛苦了", "先这样", "回头聊", "有需要再说",
+    "没问题", "了解", "好嘞",
+]);
+// --- Text normalization -----------------------------------------------
+/**
+ * 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 function stripBotCordPromptScaffolding(text) {
+    const filtered = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => {
+        if (!line)
+            return false;
+        if (line.startsWith("[BotCord Message]"))
+            return false;
+        if (line.startsWith("[BotCord Notification]"))
+            return false;
+        if (line.startsWith("[Room Rule]"))
+            return false;
+        if (line.startsWith("[In group chats, do NOT reply"))
+            return false;
+        if (line.startsWith("[If the conversation has naturally concluded"))
+            return false;
+        if (line.startsWith("[You received a contact request"))
+            return false;
+        if (line.includes('reply with exactly "NO_REPLY"'))
+            return false;
+        if (line.startsWith("<agent-message"))
+            return false;
+        if (line === "</agent-message>")
+            return false;
+        if (line.startsWith("<human-message"))
+            return false;
+        if (line === "</human-message>")
+            return false;
+        return true;
+    });
+    return filtered.join("\n").trim();
+}
+export function normalizeLoopText(text) {
+    return stripBotCordPromptScaffolding(text)
+        .toLowerCase()
+        .replace(/https?:\/\/\S+/gu, " ")
+        .replace(/[^\p{L}\p{N}\s]/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+}
+function isShortAckOrClosure(text) {
+    const n = normalizeLoopText(text);
+    if (!n || n.length > SHORT_ACK_MAX_CHARS)
+        return false;
+    return ENGLISH_ACK_OR_CLOSURE.has(n) || CHINESE_ACK_OR_CLOSURE.has(n);
+}
+// --- Similarity -------------------------------------------------------
+function trigramSet(text) {
+    if (text.length <= 3)
+        return new Set([text]);
+    const grams = new Set();
+    for (let i = 0; i <= text.length - 3; i++)
+        grams.add(text.slice(i, i + 3));
+    return grams;
+}
+function jaccardSimilarity(a, b) {
+    if (!a || !b)
+        return 0;
+    if (a === b)
+        return 1;
+    const A = trigramSet(a);
+    const B = trigramSet(b);
+    let inter = 0;
+    for (const g of A)
+        if (B.has(g))
+            inter++;
+    const union = A.size + B.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+function areOutboundTextsHighlySimilar(a, b) {
+    if (!a || !b)
+        return false;
+    if (a === b)
+        return true;
+    if (a.length < MIN_REPEAT_TEXT_CHARS || b.length < MIN_REPEAT_TEXT_CHARS)
+        return false;
+    return jaccardSimilarity(a, b) >= OUTBOUND_SIMILARITY_THRESHOLD;
+}
+// --- Sample store -----------------------------------------------------
+function prune(map, sessionKey, now) {
+    const existing = map.get(sessionKey) ?? [];
+    const next = existing.filter((s) => now - s.timestamp <= SAMPLE_MAX_AGE_MS);
+    if (next.length === 0) {
+        map.delete(sessionKey);
+        return [];
+    }
+    map.set(sessionKey, next);
+    return next;
+}
+function record(map, sessionKey, sample) {
+    const kept = prune(map, sessionKey, sample.timestamp);
+    const next = [...kept, sample].slice(-MAX_TRACKED_PER_SIDE);
+    map.set(sessionKey, next);
+}
+export function recordInboundText(params) {
+    const sessionKey = params.sessionKey?.trim();
+    const raw = typeof params.text === "string" ? params.text.trim() : "";
+    if (!sessionKey || !raw)
+        return;
+    const normalized = normalizeLoopText(raw);
+    if (!normalized)
+        return;
+    record(inboundBySession, sessionKey, {
+        text: raw,
+        normalized,
+        timestamp: params.timestamp ?? Date.now(),
+    });
+}
+export function recordOutboundText(params) {
+    const sessionKey = params.sessionKey?.trim();
+    const raw = typeof params.text === "string" ? params.text.trim() : "";
+    if (!sessionKey || !raw)
+        return;
+    const normalized = normalizeLoopText(raw);
+    if (!normalized)
+        return;
+    record(outboundBySession, sessionKey, {
+        text: raw,
+        normalized,
+        timestamp: params.timestamp ?? Date.now(),
+    });
+}
+export function clearLoopRiskSession(sessionKey) {
+    if (!sessionKey)
+        return;
+    inboundBySession.delete(sessionKey);
+    outboundBySession.delete(sessionKey);
+}
+export function resetLoopRiskStateForTests() {
+    inboundBySession.clear();
+    outboundBySession.clear();
+}
+// --- Detectors --------------------------------------------------------
+function detectHighTurnRate(inbound, outbound, now) {
+    const timeline = [];
+    for (const s of inbound) {
+        if (now - s.timestamp <= TURN_WINDOW_MS)
+            timeline.push({ role: "user", timestamp: s.timestamp });
+    }
+    for (const s of outbound) {
+        if (now - s.timestamp <= TURN_WINDOW_MS)
+            timeline.push({ role: "assistant", timestamp: s.timestamp });
+    }
+    if (timeline.length < TURN_THRESHOLD)
+        return undefined;
+    timeline.sort((a, b) => a.timestamp - b.timestamp);
+    let userTurns = 0;
+    let assistantTurns = 0;
+    let alternations = 0;
+    for (let i = 0; i < timeline.length; i++) {
+        if (timeline[i].role === "user")
+            userTurns++;
+        else
+            assistantTurns++;
+        if (i > 0 && timeline[i].role !== timeline[i - 1].role)
+            alternations++;
+    }
+    if (userTurns >= MIN_TURNS_PER_SIDE &&
+        assistantTurns >= MIN_TURNS_PER_SIDE &&
+        alternations >= ALTERNATION_THRESHOLD) {
+        return {
+            id: "high_turn_rate",
+            summary: `same session shows ${timeline.length} user/assistant turns within ${Math.round(TURN_WINDOW_MS / 1000)}s`,
+        };
+    }
+    return undefined;
+}
+function detectShortAckTail(inbound) {
+    const tail = inbound.slice(-2);
+    if (tail.length < 2)
+        return undefined;
+    if (tail.every((s) => isShortAckOrClosure(s.text))) {
+        return {
+            id: "short_ack_tail",
+            summary: "the last two inbound user messages are short acknowledgements or closure phrases",
+        };
+    }
+    return undefined;
+}
+function detectRepeatedOutbound(outbound) {
+    const recent = outbound.slice(-3);
+    if (recent.length < 2)
+        return undefined;
+    const last = recent[recent.length - 1];
+    if (!last)
+        return undefined;
+    const previous = recent.slice(0, -1);
+    const exact = previous.filter((s) => s.normalized === last.normalized).length;
+    const similar = previous.filter((s) => areOutboundTextsHighlySimilar(s.normalized, last.normalized)).length;
+    if (exact >= 1 || (recent.length >= 3 && similar >= 2)) {
+        return {
+            id: "repeated_outbound",
+            summary: "recent outbound texts in this session are highly similar",
+        };
+    }
+    return undefined;
+}
+export function evaluateLoopRisk(params) {
+    const now = params.now ?? Date.now();
+    if (!params.sessionKey)
+        return { reasons: [] };
+    const inbound = prune(inboundBySession, params.sessionKey, now);
+    const outbound = prune(outboundBySession, params.sessionKey, now);
+    const reasons = [
+        detectHighTurnRate(inbound, outbound, now),
+        detectShortAckTail(inbound),
+        detectRepeatedOutbound(outbound),
+    ].filter((r) => Boolean(r));
+    return { reasons };
+}
+/** Build the injected system-context hint, or `null` if no risk detected. */
+export function buildLoopRiskPrompt(params) {
+    const evaluation = evaluateLoopRisk(params);
+    if (evaluation.reasons.length === 0)
+        return null;
+    return [
+        "[BotCord loop-risk check]",
+        "Observed signals:",
+        ...evaluation.reasons.map((r) => `- ${r.summary}`),
+        "",
+        "Before sending any BotCord reply, verify that it adds new information, concrete progress, a blocking question, or a final result/error.",
+        'If it does not, reply with exactly "NO_REPLY" and nothing else.',
+        "Do not send courtesy-only acknowledgements or mirrored sign-offs.",
+    ].join("\n");
+}
+/**
+ * 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 function loopRiskSessionKey(params) {
+    const thread = params.threadId ?? "";
+    return `${params.accountId}:${params.conversationId}:${thread}`;
+}

package/dist/system-context.d.ts

@@ -46,6 +46,12 @@ export interface SystemContextDeps {
      * is skipped.
      */
     roomContextBuilder?: RoomStaticContextBuilder;
+    /**
+     * Optional per-turn loop-risk check. Returns a warning block when the
+     * session shows signs of agent-to-agent echo or courtesy loops. Sync
+     * + cheap — consulted every turn even when roomContextBuilder is absent.
+     */
+    loopRiskBuilder?: (message: GatewayInboundMessage) => string | null;
 }
 /**
  * Build a {@link SystemContextBuilder} for the gateway dispatcher.

package/dist/system-context.js

@@ -53,10 +53,28 @@ export function createDaemonSystemContextBuilder(deps) {
         const filtered = parts.filter((p) => typeof p === "string" && p.length > 0);
         return filtered.length > 0 ? filtered.join("\n\n") : undefined;
     };
+    const runLoopRisk = (message) => {
+        if (!deps.loopRiskBuilder)
+            return null;
+        try {
+            return deps.loopRiskBuilder(message);
+        }
+        catch (err) {
+            log.warn("system-context: loopRiskBuilder threw — skipping loop-risk block", {
+                agentId: deps.agentId,
+                roomId: message.conversation.id,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    };
     if (!deps.roomContextBuilder) {
         const syncBuilder = (message) => {
             const { ownerScene, memory, digest } = gatherSyncBlocks(message);
-            return assemble([ownerScene, memory, digest]);
+            // Loop-risk sits at the end so its "reply NO_REPLY unless…" guidance
+            // is the last thing the model sees before the user turn body.
+            const loopRisk = runLoopRisk(message);
+            return assemble([ownerScene, memory, digest, loopRisk]);
         };
         // Compile-time witness that the narrower sync signature still satisfies
         // `SystemContextBuilder` (which allows async). Prevents the two contracts
@@ -83,7 +101,8 @@ export function createDaemonSystemContextBuilder(deps) {
                 err: err instanceof Error ? err.message : String(err),
             });
         }
-        return assemble([ownerScene, memory, roomBlock, digest]);
+        const loopRisk = runLoopRisk(message);
+        return assemble([ownerScene, memory, roomBlock, digest, loopRisk]);
     };
     const _typecheck = asyncBuilder;
     void _typecheck;

package/dist/turn-text.js

@@ -1,9 +1,56 @@
-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.]';
 const DIRECT_HINT = '[If the conversation has naturally concluded or no response is needed, ' +
     'reply with exactly "NO_REPLY" and nothing else.]';
+/**
+ * Read the BotCord envelope type from a raw inbound message. Returns
+ * `undefined` when the message didn't come from the BotCord channel or the
+ * raw shape is unexpected — callers treat that the same as "message".
+ */
+function readEnvelopeType(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const env = raw.envelope;
+    if (!env || typeof env !== "object")
+        return undefined;
+    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.
  *
@@ -23,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;
@@ -46,12 +97,78 @@ export function composeBotCordUserTurn(msg) {
     const tag = sender.kind === "human" ? "human-message" : "agent-message";
     const senderKindAttr = sender.kind === "human" ? "human" : "agent";
     const hint = isGroup ? GROUP_HINT : DIRECT_HINT;
-    return [
+    // Contact-request envelopes travel through the same "inbound message"
+    // path as regular messages, but carry an additional expectation: the
+    // agent should surface the request to its owner rather than auto-accept
+    // or auto-reject. Mirrors `plugin/src/inbound.ts` §handleA2ASingle.
+    const isContactRequest = readEnvelopeType(msg.raw) === "contact_request";
+    const contactRequestHint = isContactRequest
+        ? "[You received a contact request from " +
+            sanitizedSenderLabel +
+            ". 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.]"
+        : null;
+    const lines = [
         headerFields.join(" | "),
         `<${tag} sender="${sanitizedSenderLabel}" sender_kind="${senderKindAttr}">`,
         trimmed,
         `</${tag}>`,
         "",
         hint,
-    ].join("\n");
+    ];
+    if (contactRequestHint) {
+        lines.push("", contactRequestHint);
+    }
+    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.1.1",
+  "version": "0.2.2",
   "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@botcord/protocol-core": "^0.1.1",
+    "@botcord/protocol-core": "^0.2.0",
     "ws": "^8.18.0"
   },
   "devDependencies": {

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:");
+  });
+});