@clawling/clawchat-plugin-openclaw 2026.6.16-4 → 2026.6.22-1

package/dist/src/runtime.js

@@ -8,7 +8,7 @@ import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.j
 import { ClawlingApiError } from "./api-types.js";
 import { RefreshManager } from "./refresh-manager.js";
 import { runOpenclawClawlingLogin, } from "./login.runtime.js";
-import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, hasOpenclawClawlingConnectCredentials, resolveOpenclawClawlingAccount, } from "./config.js";
+import { CHANNEL_ID, effectiveOutputVisibility, effectiveGroupCommandMode, effectiveGroupMode, hasOpenclawClawlingConnectCredentials, resolveOpenclawClawlingAccount, } from "./config.js";
 import { dispatchOpenclawClawlingInbound } from "./inbound.js";
 import { fetchInboundMedia } from "./media-runtime.js";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.js";
@@ -25,11 +25,20 @@ import { deleteClawChatMemoryFile, readClawChatMemoryFile } from "./clawchat-mem
 import { clearClawChatPromptInjectionForSession, stageClawChatPromptInjection, } from "./prompt-injection.js";
 import { createGroupMessageCoalescer } from "./group-message-coalescer.js";
 import { openclawLlmContextDebug } from "./llm-context-debug.js";
+import { GroupSettingsCache } from "./group-settings.js";
 const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } = createPluginRuntimeStore("clawchat-plugin-openclaw runtime not initialized");
 export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 const activeClients = new Map();
 const CLAWCHAT_PLUGIN_SLASH_COMMANDS = new Set(["clawchat-activate", "clawchat-output"]);
 const ACTIVATION_CREDENTIAL_POLL_INTERVAL_MS = 2_000;
+// Upper bound (ms) on how long group ingest waits for the FIRST group-settings
+// pull to settle before proceeding anyway. Best-effort governance must never
+// permanently disable group traffic, so a stalled initial GET (endpoint accepts
+// but never responds) can hold the gate at most this long. Matches the sibling
+// hermes plugin's GROUP_SETTINGS_READY_TIMEOUT_SECONDS (5s).
+const GROUP_SETTINGS_READY_TIMEOUT_MS = 5_000;
+/** Number of recent group messages to prepend as context when the agent is @-mentioned. */
+const MENTION_CONTEXT_N = 10;
 const CLAWCHAT_MEMORY_ROOT_UNAVAILABLE = "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved";
 const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
     "approve",
@@ -406,6 +415,109 @@ export async function maybeAutoActivateFromEnv(params) {
     params.log?.info?.(`[${accountId}] clawchat-plugin-openclaw ${CONNECT_CODE_ENV} activation succeeded hasToken=${Boolean(next.token)}`);
     return next;
 }
+export function createSettingsReadyGate() {
+    let generation = 0;
+    // Epoch counter: incremented every time the gate RE-CLOSES (an arm() while the
+    // gate was open). `pending` is epoch-scoped — a pull armed in a prior epoch is
+    // retired and can neither keep nor reopen the current epoch's gate.
+    let epoch = 0;
+    // Number of CURRENT-epoch dispatched pulls that have not yet settled (released).
+    let pending = 0;
+    // Has an authoritative snapshot been applied since the gate last closed? Reset
+    // whenever the gate re-closes (the first arm() after an open).
+    let authoritativeApplied = false;
+    // Starts OPEN: a resolved promise so nothing blocks until the first arm().
+    let ready = Promise.resolve();
+    let resolveReady = null;
+    const open = () => {
+        const resolve = resolveReady;
+        resolveReady = null;
+        resolve?.();
+    };
+    return {
+        arm() {
+            generation += 1;
+            // Only create a fresh pending promise when the gate is currently open; if a
+            // pull is already in flight (resolveReady set) keep the SAME promise so its
+            // existing waiters stay parked. When re-closing an open gate, start a NEW
+            // epoch: discard any stale pending count left over from pulls of the prior
+            // (now-closed) period — a startup pull that STALLED and never settled must
+            // not keep the new epoch's `pending` above zero forever — and clear the
+            // authoritative flag so the new epoch must observe a fresh authoritative
+            // pull (or drain to zero in-flight) before opening again.
+            if (resolveReady === null) {
+                epoch += 1;
+                pending = 0;
+                authoritativeApplied = false;
+                ready = new Promise((resolve) => {
+                    resolveReady = resolve;
+                });
+            }
+            pending += 1;
+            return { generation, epoch };
+        },
+        release(token, authoritative) {
+            // Retire stale older-epoch pulls. The gate re-closed (a newer pull started)
+            // since this token was armed, so this release belongs to a superseded
+            // period. Ignore it entirely: a stalled startup pull settling LATE must
+            // neither decrement the current epoch's `pending` (which would spuriously
+            // open via pending===0) nor mark the current epoch authoritative.
+            if (token.epoch !== epoch)
+                return;
+            // Count this current-epoch pull out of the in-flight set.
+            if (pending > 0)
+                pending -= 1;
+            // Only the LATEST armed pull's authoritative snapshot may open the gate.
+            // An OLDER pull (e.g. an on-ready/reconnect pull armed before a config
+            // change) can return an authoritative HTTP-200 snapshot while a NEWER
+            // `agent.config.changed` pull — carrying the just-muted / mention-only
+            // state — is still in flight. Opening on that stale authoritative release
+            // would let held group traffic proceed against settings the newer pull is
+            // about to replace (Finding #3). So only set `authoritativeApplied` when
+            // this release is for the latest armed generation. An older-generation
+            // authoritative release merely decrements `pending`.
+            if (authoritative && token.generation === generation)
+                authoritativeApplied = true;
+            // Open iff the cache is now authoritative for the LATEST epoch, OR no pull
+            // is still in flight (a slower, earlier pull could still be applying an
+            // authoritative snapshot, so a non-authoritative settle must NOT open the
+            // gate while `pending > 0`). The `pending === 0` backstop still fires when
+            // every pull has settled — including the older-authoritative-then-newer-
+            // failure case, where the older snapshot is the freshest available.
+            if (authoritativeApplied || pending === 0)
+                open();
+        },
+        forceOpen() {
+            pending = 0;
+            open();
+        },
+        wait() {
+            return ready;
+        },
+    };
+}
+// Resolve when `gate` settles, OR after `ms`, OR on abort — whichever comes
+// first. The timer is always cleared so it can't leak under fake timers. Used to
+// bound the first-group-settings-pull gate so a stalled pull can never hang group
+// traffic permanently (best-effort governance must always release).
+function waitWithTimeout(gate, ms, abortSignal) {
+    if (abortSignal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            abortSignal.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, Math.max(1, ms));
+        abortSignal.addEventListener("abort", finish, { once: true });
+        void gate.then(finish, finish);
+    });
+}
 function waitForActivationPoll(abortSignal, ms) {
     if (abortSignal.aborted)
         return Promise.resolve(false);
@@ -1224,6 +1336,80 @@ export async function startOpenclawClawlingGateway(params) {
         log: (msg) => log?.info?.(msg),
         context: wsLogContext,
     });
+    const groupSettingsCache = new GroupSettingsCache();
+    // Findings 2 & 3 — gate group dispatch on the IN-FLIGHT settings pull, not just
+    // the first one. The pull is fire-and-forget, so replayed/live group messages
+    // could otherwise enter the governance gate against a stale/empty cache
+    // (treating a just-muted/mention-only chat as default "all"). A RE-ARMABLE gate
+    // (`settingsReadyGate`) re-closes whenever a new pull starts — at startup, on
+    // every WS reconnect (after hello-ok), and on `agent.config.changed` — so a
+    // reconnect/config-change pull holds group traffic until the fresh settings
+    // land, mirroring the hermes adapter's `_group_settings_ready` event. Group
+    // ingest awaits it through a bounded race (`waitWithTimeout`,
+    // GROUP_SETTINGS_READY_TIMEOUT_MS) so even a stalled pull — endpoint accepts but
+    // never responds — can hold group traffic at most that long before the gate
+    // releases. Non-group traffic never awaits this.
+    const settingsReadyGate = createSettingsReadyGate();
+    // Best-effort re-pull of per-group agent settings from the backend.
+    // Called at startup, on every successful WS (re)connect, and on
+    // `notify.signal` with type "agent.config.changed".
+    //
+    // Finding 4 — `bypassRefresh` is set for the PRE-connect startup pull only. The
+    // normal pull runs through the REST `withRefresh` wrapper; a 401/403 there
+    // rotates `account.token`. But the WS client captured the token at construction
+    // (`createOpenclawClawlingClient`, `token: account.token`), so a pre-connect
+    // rotation would leave the client connecting with a stale token. The startup
+    // pull therefore calls the api-client WITHOUT the refresh wrapper: on auth
+    // failure it simply fails (empty cache + gate released), leaving the WS
+    // handshake — which has its own auth/refresh path — to own token rotation. The
+    // on-ready pull (post hello-ok) keeps the refresh wrapper.
+    // Monotonic fetch sequence: incremented once per dispatched pull and passed
+    // into `applyFetched` so the cache can order results across overlapping
+    // requests (including empty pulls, which have no row version to compare). A
+    // late result with a lower sequence is ignored, so a stale snapshot — empty
+    // or not — can never roll back newer state.
+    let groupSettingsFetchSequence = 0;
+    const pullGroupSettings = (opts) => {
+        const sequence = ++groupSettingsFetchSequence;
+        // Re-close the gate SYNCHRONOUSLY, before the async pull is scheduled, so any
+        // group frame the read loop dispatches concurrently observes the closed gate
+        // (rather than slipping past against the pre-pull cache). The opaque token
+        // scopes the release by generation AND epoch, so a superseded pull (from a
+        // prior re-closed epoch) never re-opens or counts against a newer pull's gate.
+        const gateToken = settingsReadyGate.arm();
+        void (async () => {
+            // Whether THIS pull applied an authoritative (HTTP 200) snapshot. Only an
+            // authoritative apply opens the gate immediately; a non-authoritative /
+            // failed pull must not open the gate while an earlier pull is still in
+            // flight (Finding 2) — it only counts down the in-flight set.
+            let authoritative = false;
+            try {
+                const result = opts?.bypassRefresh
+                    ? await (conversationApiClient ??= buildConversationApiClient()).getMyGroupSettings()
+                    : await getConversationApiClient().getMyGroupSettings();
+                if (!result.authoritative) {
+                    // Non-authoritative outcome (404 / endpoint-absent / malformed body):
+                    // preserve the cache. This is NOT "cleared".
+                    log?.info?.(`[${accountId}] clawchat-plugin-openclaw group-settings pull non-authoritative seq=${sequence} (cache preserved)`);
+                    return;
+                }
+                groupSettingsCache.applyFetched(result.rows, sequence);
+                authoritative = true;
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw group-settings pull ok seq=${sequence} rows=${result.rows.length}`);
+            }
+            catch (err) {
+                log?.error?.(`[${accountId}] clawchat-plugin-openclaw group-settings pull failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                // Pull settled. Open the gate iff this pull applied an authoritative
+                // snapshot OR no in-flight pull remains. A non-authoritative/failed pull
+                // settling ahead of an earlier still-pending authoritative pull does NOT
+                // open the gate — the earlier pull's authoritative apply (or the call-site
+                // timeout/abort backstop) does.
+                settingsReadyGate.release(gateToken, authoritative);
+            }
+        })();
+    };
     const logAuthFailure = (reason) => {
         if (authFailureLogged)
             return;
@@ -1316,6 +1502,9 @@ export async function startOpenclawClawlingGateway(params) {
             }
             void refreshConversationCacheAfterReady();
             void dispatchActivationBootstrap();
+            // Re-pull per-group agent settings on every successful (re)connect so the
+            // cache stays current after a network interruption or token refresh.
+            pullGroupSettings();
             // §A.1 — arm the proactive refresh timer from the live token's `exp`
             // every time a connection becomes ready (re-armed after every refresh via
             // the gateway re-enter).
@@ -1461,7 +1650,17 @@ export async function startOpenclawClawlingGateway(params) {
         // cache (friends are fetched on demand via REST tools), so there is nothing
         // to invalidate — observe + dedup only. The live frame and its reliable
         // inbox replay carry the same event_id and collapse to one observation.
-        notifySignalObserver.observe(env);
+        const outcome = notifySignalObserver.observe(env);
+        if (outcome === "observed") {
+            const payload = env.payload && typeof env.payload === "object"
+                ? env.payload
+                : undefined;
+            const type = typeof payload?.type === "string" ? payload.type : "";
+            if (type === "agent.config.changed") {
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw agent.config.changed signal received; re-pulling group settings`);
+                pullGroupSettings();
+            }
+        }
     });
     client.on("replay:done", (env) => {
         // §11.5 terminal control frame: device replay drained, live delivery begins.
@@ -1862,10 +2061,83 @@ export async function startOpenclawClawlingGateway(params) {
             }
         }
     };
+    // Resolve the live mute / reply-mode / batch-window for a group chat from the
+    // backend settings cache, falling back to the static channel config. Shared by
+    // the enqueue-time gate (ingestTurn) and the flush-time re-gate (coalescer
+    // dispatch) so both decisions read the SAME source of truth.
+    const resolveGroupEffectiveSettings = (chatId) => groupSettingsCache.effective(chatId, {
+        muted: false,
+        replyMode: effectiveGroupMode(account, chatId),
+        batchDelaySeconds: 10,
+    });
     const groupCoalescer = createGroupMessageCoalescer({
         idleMs: 10_000,
         maxWaitMs: 30_000,
         dispatch: async (turn) => {
+            // Finding 3 — gate the FLUSH path too. A queued non-mention batch can flush
+            // (idle/max timer) while an `agent.config.changed` settings pull is in
+            // flight; resolving effective settings here without awaiting the gate reads
+            // the stale cache and dispatches one reply for a chat about to be muted /
+            // flipped to mention-only. Await the same re-armable gate (bounded by
+            // GROUP_SETTINGS_READY_TIMEOUT_MS) so the flush-time re-check below sees the
+            // fresh snapshot.
+            //
+            // Finding #4 — do NOT early-return on abort here. The ingest path DOES early-
+            // return on abort, but only AFTER it has already taken the idempotency claim
+            // (`claimInboundTurn` runs BEFORE the gate wait there, so the frame is durably
+            // persisted before the interruptible wait — required by legacy advance-on-
+            // write delivery, where a frame written before a disconnect is not re-delivered
+            // on reconnect; see docs/client-integration.md §11.7). So even an ingest-time
+            // abort keeps the frame; it just skips dispatch. Here at FLUSH the batch was
+            // likewise already claimed at ingest AND `flush()` has already removed it from
+            // the coalescer's pending set. An abort early-return would therefore silently
+            // DROP an already-claimed, already-dequeued batch — and a replay of the same
+            // message_id is deduped by `claimMessageOnce`, permanently losing the group
+            // reply. The gate wait still runs and resolves immediately on abort (forceOpen)
+            // so we re-resolve against the freshest available settings, then dispatch
+            // best-effort rather than dropping.
+            await waitWithTimeout(settingsReadyGate.wait(), GROUP_SETTINGS_READY_TIMEOUT_MS, abortSignal);
+            // Finding 1 — re-evaluate governance at FLUSH time. Settings can change
+            // (via an agent.config.changed pull) while a coalesced batch sits pending,
+            // so the enqueue-time decision may be stale. Drop the batch if the chat is
+            // now muted, or if it flipped to mention-only and this batch carries no
+            // mention.
+            const eff = resolveGroupEffectiveSettings(turn.peer.id);
+            if (eff.muted) {
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw coalesced group batch dropped at flush (now muted) chat_id=${turn.peer.id} msg=${turn.messageId}`);
+                return;
+            }
+            if (eff.replyMode === "mention" && !turn.wasMentioned) {
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw coalesced group batch dropped at flush (now mention-only, no mention) chat_id=${turn.peer.id} msg=${turn.messageId}`);
+                return;
+            }
+            if (turn.wasMentioned && store?.listRecentGroupMessages) {
+                const chatId = turn.peer.id;
+                // Dedupe: exclude rows whose message_id belongs to the current batch/turn.
+                // For a coalesced multi-message turn this covers every constituent ID,
+                // not just the latest one (turn.messageId), so none of the batched
+                // messages appear twice — once in the coalesced body and once in the
+                // prepended "Prior group context" block.
+                const batchIds = new Set(turn.allMessageIds ?? [turn.messageId]);
+                // Overfetch so the batch's own just-stored messages don't crowd out the
+                // MENTION_CONTEXT_N prior rows: fetch batch-size extra rows, drop the
+                // batch members, then keep the most recent MENTION_CONTEXT_N survivors.
+                const priorRows = store.listRecentGroupMessages("openclaw", accountId, chatId, MENTION_CONTEXT_N + batchIds.size) ?? [];
+                const contextRows = priorRows
+                    .filter((row) => row.message_id != null && !batchIds.has(row.message_id))
+                    .slice(-MENTION_CONTEXT_N);
+                if (contextRows.length > 0) {
+                    const priorContextBody = [
+                        "Prior group context:",
+                        ...contextRows.map((row, i) => `[prior ${i + 1}] ${row.text ?? "(empty)"}`),
+                    ].join("\n");
+                    await dispatchTurnToAgent({
+                        ...turn,
+                        rawBody: `${priorContextBody}\n${turn.rawBody}`,
+                    });
+                    return;
+                }
+            }
             await dispatchTurnToAgent(turn);
         },
         onError: (err) => {
@@ -1906,10 +2178,49 @@ export async function startOpenclawClawlingGateway(params) {
             senderNickName: resolveSenderNickNameForTurn(rawTurn),
             ...senderBatchIdentity,
         };
-        const claimed = claimInboundTurn(turn);
-        if (claimed === "skipped")
-            return "skipped";
         if (turn.peer.kind === "group") {
+            // Finding 1 corrected (message loss) — claim the inbound idempotency row
+            // BEFORE the (interruptible) settings-gate wait, so every received group
+            // frame is durably persisted EXACTLY ONCE before any wait that a shutdown
+            // can interrupt. This client does NOT advertise `reliable_delivery`
+            // (src/ws-client.ts), so under legacy delivery the server's replay cursor
+            // advances on socket-WRITE (docs/client-integration.md §11.7): a frame
+            // already written before a disconnect is NOT re-delivered on reconnect.
+            // `claimMessageOnce` is the ONLY durability an inbound has, and the store
+            // never reprocesses undispatched inbounds. So if we claimed only AFTER the
+            // wait, a shutdown-mid-wait would leave the frame neither persisted NOR
+            // replayed — permanently lost. Claiming first makes it durable; the abort
+            // check below then returns without dispatching, but the frame is kept.
+            // `claimInboundTurn` is INSERT OR IGNORE, so a genuine duplicate (same
+            // message_id) is still deduped here exactly once.
+            const claimed = claimInboundTurn(turn);
+            if (claimed === "skipped")
+                return "skipped";
+            // Findings 2 & 3 — hold ALL group traffic until the in-flight settings pull
+            // has settled so the mute / reply-mode gate never runs against a stale/empty
+            // cache (startup, reconnect, AND config-change pulls all re-close the gate).
+            // This only delays group traffic; direct messages return below. The wait is
+            // bounded (GROUP_SETTINGS_READY_TIMEOUT_MS): a stalled pull must never hang
+            // group traffic forever, so the gate always releases — falling back to the
+            // (possibly stale) cache rather than blocking indefinitely.
+            await waitWithTimeout(settingsReadyGate.wait(), GROUP_SETTINGS_READY_TIMEOUT_MS, abortSignal);
+            // Finding (#2 follow-up) — the bounded wait also resolves on abort. If the
+            // gateway is closing, stop here instead of enqueuing/dispatching a group turn
+            // into a tearing-down gateway. The frame is already claimed (persisted), so
+            // returning here drops only the dispatch, never the message.
+            if (abortSignal.aborted)
+                return "skipped";
+            // Mute gate — evaluated BEFORE the slash-command branch so a backend-muted
+            // group is fully store-only, consistent with muted normal messages: a
+            // muted group must never forward/dispatch a `/clawchat-*` command (or any
+            // group slash command) to the agent or the owner. Known commands were
+            // previously handled above this gate, which let a muted group still drive
+            // the agent — contradicting the mute semantics. Keep this check first.
+            const eff = resolveGroupEffectiveSettings(turn.peer.id);
+            if (eff.muted) {
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw group message stored but muted chat_id=${turn.peer.id} msg=${turn.messageId}`);
+                return "stored_muted";
+            }
             if (isKnownOpenClawGroupSlashCommand(turn.rawBody, cfg)) {
                 if (isOpenClawConfirmSlashCommand(turn.rawBody)) {
                     return forwardGroupApprovalSlashToOwner(turn);
@@ -1924,16 +2235,28 @@ export async function startOpenclawClawlingGateway(params) {
                 log?.info?.(`[${accountId}] clawchat-plugin-openclaw dispatching group command chat_id=${turn.peer.id} msg=${turn.messageId} mode=${commandMode}`);
                 return dispatchTurnToAgent(turn);
             }
+            if (eff.replyMode === "mention" && !turn.wasMentioned) {
+                log?.info?.(`[${accountId}] clawchat-plugin-openclaw group message stored but skipped (mention mode) chat_id=${turn.peer.id} msg=${turn.messageId}`);
+                return "stored_skipped";
+            }
+            const idleMsOverride = eff.batchDelaySeconds * 1000;
             if (turn.wasMentioned) {
-                groupCoalescer.enqueue(turn);
+                groupCoalescer.enqueue(turn, { idleMsOverride });
                 groupCoalescer.flushNow(turn.peer.id);
                 log?.info?.(`[${accountId}] clawchat-plugin-openclaw dispatching mentioned group batch chat_id=${turn.peer.id} msg=${turn.messageId}`);
                 return "submitted";
             }
-            groupCoalescer.enqueue(turn);
+            groupCoalescer.enqueue(turn, { idleMsOverride });
             log?.info?.(`[${accountId}] clawchat-plugin-openclaw queued group batch chat_id=${turn.peer.id} msg=${turn.messageId}`);
             return "submitted";
         }
+        // Direct messages: no gate to await, so claim right before dispatch. (The
+        // group branch claims BEFORE its gate wait so a shutdown-mid-wait cannot lose
+        // the frame under this client's legacy advance-on-write delivery — see
+        // Finding 1 corrected above.)
+        const claimed = claimInboundTurn(turn);
+        if (claimed === "skipped")
+            return "skipped";
         return dispatchTurnToAgent(turn);
     };
     const handleInboundEnvelope = async (env) => {
@@ -1996,6 +2319,15 @@ export async function startOpenclawClawlingGateway(params) {
             await handleInboundEnvelope(env);
         })();
     });
+    // Initial pull of per-group agent settings at startup (best-effort; errors are
+    // logged). `bypassRefresh: true` (Finding 4) keeps this pre-connect pull from
+    // rotating `account.token` out from under the already-constructed WS client.
+    // Settling this releases the Finding-2 group-dispatch gate.
+    pullGroupSettings({ bypassRefresh: true });
+    // Safety: never strand a held group message if the runtime is torn down while a
+    // pull is in flight. `waitWithTimeout` already releases group waiters on abort,
+    // but force the gate open too so any later `wait()` resolves immediately.
+    abortSignal.addEventListener("abort", () => settingsReadyGate.forceOpen(), { once: true });
     // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`
     // (auth). Transport failures (server unreachable, DNS error, etc.) do
     // NOT reject this promise — the local client handles them internally and

package/dist/src/storage.js

@@ -503,6 +503,24 @@ export class ClawChatStore {
     listToolCallsForTest() {
         return this.read(() => this.requireDb().prepare("SELECT * FROM tool_calls ORDER BY id").all()) ?? [];
     }
+    /**
+     * Return the last `limit` user-visible messages in a group chat, ordered
+     * oldest-first. Only `kind = 'message'` rows are returned; internal kinds such
+     * as `'thinking'` are excluded so the @-mention prior-context block never
+     * surfaces the agent's intermediate output as conversation history.
+     * Uses `idx_clawchat_messages_chat_created` for performance.
+     * Returns an empty array if the store is unavailable.
+     */
+    listRecentGroupMessages(platform, accountId, chatId, limit) {
+        return this.read(() => {
+            const rows = this.requireDb()
+                .prepare(`SELECT * FROM clawchat_messages
+            WHERE platform = ? AND account_id = ? AND chat_id = ? AND kind = 'message'
+            ORDER BY created_at DESC, rowid DESC LIMIT ?`)
+                .all(platform, accountId, chatId, limit);
+            return rows.reverse(); // oldest-first for prompt order
+        }) ?? [];
+    }
     close() {
         this.db?.close();
         this.db = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.6.16-4",
+  "version": "2026.6.22-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "files": [

package/src/api-client.ts

@@ -15,6 +15,7 @@ import {
   type UploadResult,
   type UserSearchHit,
 } from "./api-types.ts";
+import type { GroupSettings, GroupSettingsFetchResult } from "./group-settings.ts";
 import { CHANNEL_ID } from "./config.ts";
 
 export interface PluginReportInput {
@@ -158,6 +159,17 @@ export interface OpenclawClawlingApiClient {
     input: PluginReportInput,
     opts?: { authenticated?: boolean },
   ): Promise<void>;
+  /**
+   * Fetch per-group agent settings from `GET /v1/agents/me/group-settings`.
+   *
+   * Returns `{ authoritative: true, rows }` only for an HTTP 200 whose envelope
+   * parsed cleanly — only this may replace the cache (an empty `rows` then means
+   * "zero overrides"). Returns `{ authoritative: false }` for a NON-authoritative
+   * outcome — HTTP 404 / endpoint-absent (older backend), non-2xx, or a malformed
+   * body — which the caller must treat as a cache-preserving no-op. A network
+   * error still throws.
+   */
+  getMyGroupSettings(): Promise<GroupSettingsFetchResult>;
 }
 
 /** Backend envelope codes for `POST /v1/auth/refresh` (§0). */
@@ -659,5 +671,64 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         body: JSON.stringify(buildPluginReportBody(input)),
       });
     },
+    async getMyGroupSettings(): Promise<GroupSettingsFetchResult> {
+      // GET /v1/agents/me/group-settings returns { settings: [...] }.
+      //
+      // Only an authoritative HTTP 200 whose envelope parses cleanly carries the
+      // agent's real override set and may replace the cache (an empty `settings`
+      // then legitimately means "zero overrides"). A non-authoritative outcome
+      // — HTTP 404 / endpoint-absent (older backend), or a malformed body — must
+      // NOT be reported as "cleared"; it returns `{ authoritative: false }` so
+      // the caller preserves the cache. Auth (401/403) and non-2xx-without-
+      // envelope still throw from `readEnvelope` (the caller's catch is itself a
+      // no-op, and auth throws drive token refresh), as does a network error.
+      const path = "/v1/agents/me/group-settings";
+      let res: Response;
+      try {
+        res = await fetchImpl(url(path), { method: "GET", headers: authHeaders() });
+      } catch (err) {
+        throw new ClawlingApiError(
+          "transport",
+          `fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+          { path },
+        );
+      }
+      if (res.status === 404) return { authoritative: false };
+      // Auth (401/403) must still throw so the caller can drive a token refresh;
+      // `readEnvelope` handles that at the top before any body parsing. But ONLY
+      // an HTTP 200 is an authoritative snapshot that may replace/clear the cache
+      // — any other non-2xx (e.g. 500/502) is non-authoritative even when its body
+      // happens to carry a parseable `{ code: 0, data: { settings } }` envelope.
+      const data = await readEnvelope<{ settings: unknown[] }>(res, path);
+      if (res.status !== 200) return { authoritative: false };
+      if (!data || !Array.isArray(data.settings)) return { authoritative: false };
+      const rows: GroupSettings[] = [];
+      for (const item of data.settings) {
+        // Guard non-object rows (`null`, primitives) before any field access: a
+        // `null` row would throw on `r.conversation_id` and fail the whole pull
+        // (treated as a transport error) instead of being skipped as invalid.
+        if (typeof item !== "object" || item === null) {
+          continue;
+        }
+        const r = item as Record<string, unknown>;
+        if (
+          typeof r.conversation_id !== "string" ||
+          typeof r.muted !== "boolean" ||
+          (r.reply_mode !== "all" && r.reply_mode !== "mention") ||
+          typeof r.batch_delay_seconds !== "number" ||
+          typeof r.version !== "number"
+        ) {
+          continue;
+        }
+        rows.push({
+          conversationId: r.conversation_id,
+          muted: r.muted,
+          replyMode: r.reply_mode as "all" | "mention",
+          batchDelaySeconds: r.batch_delay_seconds,
+          version: r.version,
+        });
+      }
+      return { authoritative: true, rows };
+    },
   };
 }

package/src/group-message-coalescer.ts

@@ -8,6 +8,14 @@ export type CoalescableGroupTurn = {
   senderIsGroupOwner?: boolean;
   rawBody: string;
   messageId: string;
+  /**
+   * All constituent message IDs in this turn. For a single (non-coalesced)
+   * turn this is `[messageId]`. For a coalesced batch this contains every
+   * individual message ID that was merged into this turn, oldest first.
+   * Used by the @-mention prior-context dedup filter to exclude ALL batch
+   * messages from the "Prior group context" block, not just the latest one.
+   */
+  allMessageIds: string[];
   traceId: string;
   timestamp: number;
   wasMentioned: boolean;
@@ -110,6 +118,9 @@ export function mergeGroupTurns<T extends CoalescableGroupTurn>(
           .map((mention) => [mention.id, mention]),
       ).values(),
     ),
+    // Collect ALL constituent message IDs so callers can exclude every batch
+    // member (not just the latest) from prior-context dedup.
+    allMessageIds: turns.flatMap((turn) => turn.allMessageIds),
     coalescedGroupBatch: true,
   };
 }
@@ -139,16 +150,17 @@ export function createGroupMessageCoalescer<T extends CoalescableGroupTurn>(para
   };
 
   return {
-    enqueue(turn: T): void {
+    enqueue(turn: T, options?: { idleMsOverride?: number }): void {
       const chatId = turn.peer.id;
+      const idleMs = options?.idleMsOverride ?? params.idleMs;
       const existing = pending.get(chatId);
       if (existing) {
         existing.turns.push(turn);
         clearTimeout(existing.idleTimer);
-        existing.idleTimer = setTimeout(() => flush(chatId), params.idleMs);
+        existing.idleTimer = setTimeout(() => flush(chatId), idleMs);
         return;
       }
-      const idleTimer = setTimeout(() => flush(chatId), params.idleMs);
+      const idleTimer = setTimeout(() => flush(chatId), idleMs);
       const maxWaitTimer = setTimeout(() => flush(chatId), params.maxWaitMs);
       pending.set(chatId, { turns: [turn], idleTimer, maxWaitTimer });
     },