@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/group/activation.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import { resolveGroupActivation, type SessionStoreReader } from "./activation.js";
+
+describe("engine/group/activation", () => {
+  describe("resolveGroupActivation — no reader", () => {
+    it("maps configRequireMention=true → mention", () => {
+      expect(
+        resolveGroupActivation({
+          cfg: {},
+          agentId: "main",
+          sessionKey: "s",
+          configRequireMention: true,
+        }),
+      ).toBe("mention");
+    });
+
+    it("maps configRequireMention=false → always", () => {
+      expect(
+        resolveGroupActivation({
+          cfg: {},
+          agentId: "main",
+          sessionKey: "s",
+          configRequireMention: false,
+        }),
+      ).toBe("always");
+    });
+  });
+
+  describe("resolveGroupActivation — with reader", () => {
+    const makeReader = (
+      store: Record<string, { groupActivation?: string }> | null,
+    ): SessionStoreReader => ({
+      read: () => store,
+    });
+
+    it("honours explicit session-store override (mention)", () => {
+      const reader = makeReader({ k1: { groupActivation: "mention" } });
+      expect(
+        resolveGroupActivation({
+          cfg: {},
+          agentId: "main",
+          sessionKey: "k1",
+          configRequireMention: false,
+          sessionStoreReader: reader,
+        }),
+      ).toBe("mention");
+    });
+
+    it("honours explicit session-store override (always)", () => {
+      const reader = makeReader({ k1: { groupActivation: "always" } });
+      expect(
+        resolveGroupActivation({
+          cfg: {},
+          agentId: "main",
+          sessionKey: "k1",
+          configRequireMention: true,
+          sessionStoreReader: reader,
+        }),
+      ).toBe("always");
+    });
+
+    it("ignores override when the key is absent", () => {
+      const reader = makeReader({});
+      expect(
+        resolveGroupActivation({
+          cfg: {},
+          agentId: "main",
+          sessionKey: "MISSING",
+          configRequireMention: true,
+          sessionStoreReader: reader,
+        }),
+      ).toBe("mention");
+    });
+
+    it("ignores reader errors (null) and falls back", () => {
+      const reader = makeReader(null);
+      expect(
+        resolveGroupActivation({
+          cfg: {},
+          agentId: "main",
+          sessionKey: "k1",
+          configRequireMention: false,
+          sessionStoreReader: reader,
+        }),
+      ).toBe("always");
+    });
+
+    it("ignores invalid activation values", () => {
+      const reader = makeReader({ k1: { groupActivation: "weird-mode" } });
+      expect(
+        resolveGroupActivation({
+          cfg: {},
+          agentId: "main",
+          sessionKey: "k1",
+          configRequireMention: true,
+          sessionStoreReader: reader,
+        }),
+      ).toBe("mention");
+    });
+
+    it("normalizes whitespace / case", () => {
+      const reader = makeReader({ k1: { groupActivation: "  Always  " } });
+      expect(
+        resolveGroupActivation({
+          cfg: {},
+          agentId: "main",
+          sessionKey: "k1",
+          configRequireMention: true,
+          sessionStoreReader: reader,
+        }),
+      ).toBe("always");
+    });
+  });
+});

package/src/engine/group/activation.ts

@@ -0,0 +1,147 @@
+/**
+ * Group activation mode — how the bot decides whether to respond in a group.
+ *
+ * Resolution chain:
+ *   1. session store override (`/activation` command writes per-session
+ *      `groupActivation` value) — highest priority
+ *   2. per-group `requireMention` config
+ *   3. `"mention"` default (require @-bot to respond)
+ *
+ * File I/O is isolated in the default node-based reader so the gating
+ * logic itself stays a pure function, testable without touching disk.
+ *
+ * Note: the implicit-mention predicate (quoting a bot message counts as
+ * @-ing the bot) lives in `./mention.ts` alongside the other mention
+ * helpers — see `resolveImplicitMention` there.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+// ────────────────────────── Types ──────────────────────────
+
+/** High-level activation outcome. */
+export type GroupActivationMode = "mention" | "always";
+
+/**
+ * Pluggable reader that returns parsed session-store contents.
+ *
+ * A return value of `null` means "no override available" (file missing,
+ * parse error, or reader disabled). Implementations must **not** throw —
+ * the gating pipeline treats any failure as "fall back to the config
+ * default".
+ */
+export interface SessionStoreReader {
+  read(params: {
+    cfg: Record<string, unknown>;
+    agentId: string;
+  }): Record<string, { groupActivation?: string }> | null;
+}
+
+// ────────────────────────── groupActivation ──────────────────────────
+
+/**
+ * Resolve the effective activation mode for one inbound message.
+ *
+ * Order of precedence:
+ *   1. `store[sessionKey].groupActivation` (read via the injected reader)
+ *   2. config-level `requireMention` (maps to `"mention"` / `"always"`)
+ *   3. `"mention"` (safe default)
+ */
+export function resolveGroupActivation(params: {
+  cfg: Record<string, unknown>;
+  agentId: string;
+  sessionKey: string;
+  configRequireMention: boolean;
+  /** Pluggable reader; omit to disable the session-store override. */
+  sessionStoreReader?: SessionStoreReader;
+}): GroupActivationMode {
+  const fallback: GroupActivationMode = params.configRequireMention ? "mention" : "always";
+
+  const store = params.sessionStoreReader?.read({
+    cfg: params.cfg,
+    agentId: params.agentId,
+  });
+  if (!store) {
+    return fallback;
+  }
+
+  const entry = store[params.sessionKey];
+  if (!entry?.groupActivation) {
+    return fallback;
+  }
+
+  const normalized = entry.groupActivation.trim().toLowerCase();
+  if (normalized === "mention" || normalized === "always") {
+    return normalized;
+  }
+  return fallback;
+}
+
+// ────────────────────────── Default node reader ──────────────────────────
+
+/**
+ * Resolve the on-disk path to the agent-sessions file.
+ *
+ * Priority:
+ *   1. `cfg.session.store` (supports `{agentId}` placeholder and `~` expansion)
+ *   2. `$OPENCLAW_STATE_DIR` / `$CLAWDBOT_STATE_DIR`
+ *   3. `~/.openclaw/agents/{agentId}/sessions/sessions.json`
+ */
+function resolveSessionStorePath(
+  cfg: Record<string, unknown>,
+  agentId: string | undefined,
+): string {
+  const resolvedAgentId = agentId || "default";
+
+  const session =
+    typeof cfg.session === "object" && cfg.session !== null
+      ? (cfg.session as { store?: unknown })
+      : undefined;
+  const rawStore = typeof session?.store === "string" ? session.store : undefined;
+
+  if (rawStore) {
+    let expanded = rawStore;
+    if (expanded.includes("{agentId}")) {
+      expanded = expanded.replaceAll("{agentId}", resolvedAgentId);
+    }
+    if (expanded.startsWith("~")) {
+      const home = process.env.HOME || process.env.USERPROFILE || "";
+      expanded = expanded.replace(/^~/, home);
+    }
+    return path.resolve(expanded);
+  }
+
+  const stateDir =
+    process.env.OPENCLAW_STATE_DIR?.trim() ||
+    process.env.CLAWDBOT_STATE_DIR?.trim() ||
+    path.join(process.env.HOME || process.env.USERPROFILE || "", ".openclaw");
+  return path.join(stateDir, "agents", resolvedAgentId, "sessions", "sessions.json");
+}
+
+/**
+ * Create the default, production-ready session-store reader.
+ *
+ * Reads the file synchronously on every call. The overhead is acceptable
+ * because activation mode is only resolved once per group message and
+ * the sessions file is typically a handful of kilobytes.
+ *
+ * Any I/O or JSON error is swallowed and returned as `null` so the
+ * gating pipeline falls back to the config default.
+ */
+export function createNodeSessionStoreReader(): SessionStoreReader {
+  return {
+    read: ({ cfg, agentId }) => {
+      try {
+        const storePath = resolveSessionStorePath(cfg, agentId);
+        if (!fs.existsSync(storePath)) {
+          return null;
+        }
+        const raw = fs.readFileSync(storePath, "utf-8");
+        return JSON.parse(raw) as Record<string, { groupActivation?: string }>;
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/src/engine/group/history.test.ts

@@ -0,0 +1,314 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildMergedMessageContext,
+  buildPendingHistoryContext,
+  clearPendingHistory,
+  formatAttachmentTags,
+  formatMessageContent,
+  inferAttachmentType,
+  recordPendingHistoryEntry,
+  toAttachmentSummaries,
+  type HistoryEntry,
+} from "./history.js";
+
+function makeMap(): Map<string, HistoryEntry[]> {
+  return new Map();
+}
+
+function entry(sender: string, body: string, extras: Partial<HistoryEntry> = {}): HistoryEntry {
+  return { sender, body, ...extras };
+}
+
+describe("engine/group/history", () => {
+  describe("inferAttachmentType", () => {
+    it("maps image/* → image", () => {
+      expect(inferAttachmentType("image/png")).toBe("image");
+    });
+
+    it("maps voice / audio / silk / amr → voice", () => {
+      expect(inferAttachmentType("voice")).toBe("voice");
+      expect(inferAttachmentType("audio/mpeg")).toBe("voice");
+      expect(inferAttachmentType("application/silk")).toBe("voice");
+      expect(inferAttachmentType("audio/amr")).toBe("voice");
+    });
+
+    it("maps video / application / text → their category", () => {
+      expect(inferAttachmentType("video/mp4")).toBe("video");
+      expect(inferAttachmentType("application/pdf")).toBe("file");
+      expect(inferAttachmentType("text/plain")).toBe("file");
+    });
+
+    it("unknown content types fall back to unknown", () => {
+      expect(inferAttachmentType()).toBe("unknown");
+      expect(inferAttachmentType("weird/thing")).toBe("unknown");
+    });
+  });
+
+  describe("toAttachmentSummaries", () => {
+    it("returns undefined for empty input", () => {
+      expect(toAttachmentSummaries()).toBeUndefined();
+      expect(toAttachmentSummaries([])).toBeUndefined();
+    });
+
+    it("normalizes raw fields", () => {
+      const result = toAttachmentSummaries([
+        {
+          content_type: "image/png",
+          filename: "a.png",
+          url: "https://x/a.png",
+        },
+        {
+          content_type: "voice",
+          asr_refer_text: "hello",
+        },
+      ]);
+      expect(result).toEqual([
+        { type: "image", filename: "a.png", transcript: undefined, url: "https://x/a.png" },
+        { type: "voice", filename: undefined, transcript: "hello", url: undefined },
+      ]);
+    });
+  });
+
+  describe("formatAttachmentTags", () => {
+    it("returns empty string for empty input", () => {
+      expect(formatAttachmentTags()).toBe("");
+      expect(formatAttachmentTags([])).toBe("");
+    });
+
+    it("renders MEDIA:path for entries with a source", () => {
+      expect(formatAttachmentTags([{ type: "image", localPath: "/tmp/a.png" }])).toBe(
+        "MEDIA:/tmp/a.png",
+      );
+      expect(formatAttachmentTags([{ type: "image", url: "https://x/b.png" }])).toBe(
+        "MEDIA:https://x/b.png",
+      );
+    });
+
+    it("inlines transcript for voice w/ source", () => {
+      expect(
+        formatAttachmentTags([{ type: "voice", localPath: "/tmp/v.wav", transcript: "hi" }]),
+      ).toBe('MEDIA:/tmp/v.wav (transcript: "hi")');
+    });
+
+    it("uses descriptive tags when no source is available", () => {
+      expect(formatAttachmentTags([{ type: "image" }])).toBe("[image]");
+      expect(formatAttachmentTags([{ type: "image", filename: "a.png" }])).toBe("[image: a.png]");
+      expect(formatAttachmentTags([{ type: "voice" }])).toBe("[voice]");
+      expect(formatAttachmentTags([{ type: "voice", transcript: "t" }])).toBe(
+        '[voice (transcript: "t")]',
+      );
+      expect(formatAttachmentTags([{ type: "video" }])).toBe("[video]");
+      expect(formatAttachmentTags([{ type: "file", filename: "b.pdf" }])).toBe("[file: b.pdf]");
+      expect(formatAttachmentTags([{ type: "unknown" }])).toBe("[attachment]");
+    });
+
+    it("joins multiple entries with newline", () => {
+      expect(
+        formatAttachmentTags([
+          { type: "image", localPath: "/tmp/a.png" },
+          { type: "voice", transcript: "hi" },
+        ]),
+      ).toBe('MEDIA:/tmp/a.png\n[voice (transcript: "hi")]');
+    });
+  });
+
+  describe("formatMessageContent", () => {
+    it("passes content through parseFaceTags (no-op for plain text)", () => {
+      // parseFaceTags only rewrites the `<faceType=...>` tag form; plain
+      // text must round-trip unchanged so regressions in the pipeline
+      // don't silently mangle user input.
+      expect(formatMessageContent({ content: "hello world" })).toBe("hello world");
+    });
+
+    it("strips mentions only for group chat", () => {
+      expect(
+        formatMessageContent({
+          content: "<@X>hi",
+          chatType: "group",
+          mentions: [{ member_openid: "X", is_you: true }],
+        }),
+      ).toBe("hi");
+      // Non-group: strip is NOT applied.
+      expect(
+        formatMessageContent({
+          content: "<@X>hi",
+          chatType: "c2c",
+          mentions: [{ member_openid: "X", is_you: true }],
+        }),
+      ).toBe("<@X>hi");
+    });
+
+    it("appends attachment tags", () => {
+      expect(
+        formatMessageContent({
+          content: "see",
+          attachments: [{ content_type: "image/png", url: "https://x/a.png" }],
+        }),
+      ).toBe("see MEDIA:https://x/a.png");
+    });
+  });
+
+  describe("recordPendingHistoryEntry / buildPendingHistoryContext", () => {
+    it("no-ops when limit is 0", () => {
+      const map = makeMap();
+      const entries = recordPendingHistoryEntry({
+        historyMap: map,
+        historyKey: "G",
+        entry: entry("A", "hi"),
+        limit: 0,
+      });
+      expect(entries).toEqual([]);
+      expect(map.size).toBe(0);
+    });
+
+    it("no-ops when entry is null", () => {
+      const map = makeMap();
+      recordPendingHistoryEntry({
+        historyMap: map,
+        historyKey: "G",
+        entry: null,
+        limit: 10,
+      });
+      expect(map.size).toBe(0);
+    });
+
+    it("appends and caps at the limit", () => {
+      const map = makeMap();
+      for (let i = 0; i < 5; i++) {
+        recordPendingHistoryEntry({
+          historyMap: map,
+          historyKey: "G",
+          entry: entry("A", `m${i}`),
+          limit: 3,
+        });
+      }
+      const entries = map.get("G")!;
+      expect(entries).toHaveLength(3);
+      expect(entries.map((e) => e.body)).toEqual(["m2", "m3", "m4"]);
+    });
+
+    it("builds a history-wrapped message when entries exist", () => {
+      const map = makeMap();
+      recordPendingHistoryEntry({
+        historyMap: map,
+        historyKey: "G",
+        entry: entry("Alice", "hello"),
+        limit: 10,
+      });
+      const out = buildPendingHistoryContext({
+        historyMap: map,
+        historyKey: "G",
+        limit: 10,
+        currentMessage: "[Bob] @bot",
+        formatEntry: (e) => `${e.sender}: ${e.body}`,
+      });
+      expect(out).toContain("[Chat messages since your last reply — CONTEXT ONLY]");
+      expect(out).toContain("Alice: hello");
+      expect(out).toContain("[CURRENT MESSAGE — reply to this]");
+      expect(out.endsWith("[Bob] @bot")).toBe(true);
+    });
+
+    it("returns current message unchanged when buffer is empty or disabled", () => {
+      const map = makeMap();
+      expect(
+        buildPendingHistoryContext({
+          historyMap: map,
+          historyKey: "G",
+          limit: 10,
+          currentMessage: "hi",
+          formatEntry: () => "x",
+        }),
+      ).toBe("hi");
+      expect(
+        buildPendingHistoryContext({
+          historyMap: map,
+          historyKey: "G",
+          limit: 0,
+          currentMessage: "hi",
+          formatEntry: () => "x",
+        }),
+      ).toBe("hi");
+    });
+  });
+
+  describe("LRU eviction across groups", () => {
+    it("evicts oldest keys past the implicit cap (smoke check)", () => {
+      const map = makeMap();
+      // Just ensure the cache doesn't explode. The hard cap (1000) is an
+      // implementation detail; here we confirm the data structure keeps
+      // re-inserting without error at modest volume.
+      for (let i = 0; i < 100; i++) {
+        recordPendingHistoryEntry({
+          historyMap: map,
+          historyKey: `G${i}`,
+          entry: entry("A", `m${i}`),
+          limit: 1,
+        });
+      }
+      expect(map.size).toBe(100);
+    });
+
+    it("refreshes LRU ordering on subsequent writes to the same key", () => {
+      const map = makeMap();
+      recordPendingHistoryEntry({
+        historyMap: map,
+        historyKey: "OLD",
+        entry: entry("A", "1"),
+        limit: 5,
+      });
+      recordPendingHistoryEntry({
+        historyMap: map,
+        historyKey: "NEW",
+        entry: entry("A", "2"),
+        limit: 5,
+      });
+      recordPendingHistoryEntry({
+        historyMap: map,
+        historyKey: "OLD",
+        entry: entry("A", "3"),
+        limit: 5,
+      });
+      // After re-writing OLD, its iteration order should come last.
+      const keys = [...map.keys()];
+      expect(keys).toEqual(["NEW", "OLD"]);
+    });
+  });
+
+  describe("buildMergedMessageContext", () => {
+    it("returns current message unchanged when no preceding parts", () => {
+      expect(buildMergedMessageContext({ precedingParts: [], currentMessage: "hi" })).toBe("hi");
+    });
+
+    it("wraps preceding parts with tags", () => {
+      const out = buildMergedMessageContext({
+        precedingParts: ["a", "b"],
+        currentMessage: "c",
+      });
+      expect(out).toContain("[Merged earlier messages — CONTEXT ONLY]");
+      expect(out).toContain("a\nb");
+      expect(out).toContain("[CURRENT MESSAGE — reply using the context above]");
+      expect(out.endsWith("c")).toBe(true);
+    });
+  });
+
+  describe("clearPendingHistory", () => {
+    it("resets the buffer to empty", () => {
+      const map = makeMap();
+      recordPendingHistoryEntry({
+        historyMap: map,
+        historyKey: "G",
+        entry: entry("A", "m"),
+        limit: 5,
+      });
+      clearPendingHistory({ historyMap: map, historyKey: "G", limit: 5 });
+      expect(map.get("G")).toEqual([]);
+    });
+
+    it("no-ops when disabled", () => {
+      const map = makeMap();
+      map.set("G", [entry("A", "m")]);
+      clearPendingHistory({ historyMap: map, historyKey: "G", limit: 0 });
+      expect(map.get("G")).toHaveLength(1);
+    });
+  });
+});