@mininglamp-oss/cc-channel-octo 1.0.1-dev.60b73f3

package/dist/group-config.js

@@ -0,0 +1,104 @@
+/**
+ * v1.0: GROUP.md / THREAD.md per-conversation instruction files.
+ *
+ * Operators can drop a markdown file with custom instructions for a specific
+ * group (or, later, thread) into a configured directory. Its contents are
+ * injected into the agent's system prompt as a trusted instruction block, so a
+ * group can have its own persona / rules without code changes.
+ *
+ * SECURITY — read carefully. The `[Group instructions]` block is injected into
+ * the system prompt UNSANITIZED, so its contents are trusted. That trust holds
+ * ONLY if the file is writable solely by the operator (the gateway process user).
+ *
+ * Placing `groupConfigDir` outside `cwdBase` is necessary but NOT sufficient:
+ * under the shipped defaults (`allowedTools: '*'`, `bypassPermissions`) the agent
+ * has `Bash`/`Write` and can write ABSOLUTE paths anywhere the gateway user can
+ * write — `cwdBase` is a starting dir, not a chroot. So a malicious user in one
+ * group could drive the agent to write `<groupConfigDir>/<otherGroup>.md` and
+ * inject persistent, trusted instructions into a different group.
+ *
+ * The real protection is OS-level: `groupConfigDir` and its files MUST be made
+ * non-writable by the gateway process user (e.g. root-owned, mode 0755/0644),
+ * and/or the deployment hardened (drop `Bash`, sandboxed FS, unprivileged user).
+ * As cheap defense-in-depth, loadGroupConfig() refuses to inject a file that is
+ * group- or world-writable. The group id is filename-pinned to a safe slug so a
+ * crafted id can't traverse out of the config dir.
+ */
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** Max bytes of an instruction file we will inject (keeps the prompt bounded). */
+export const MAX_GROUP_CONFIG_BYTES = 16_384; // 16 KiB
+/**
+ * Only allow ids that are safe as a single path segment — letters, digits, and
+ * a few separators. Anything else (slashes, dots-only, `..`) is rejected so a
+ * channel/thread id cannot escape `groupConfigDir`.
+ */
+function isSafeId(id) {
+    return /^[a-zA-Z0-9._-]+$/.test(id) && id !== '.' && id !== '..';
+}
+/**
+ * Load the instruction file for a group, or undefined when none applies.
+ *
+ * Looks for `<groupConfigDir>/<groupId>.md`. Returns the trimmed contents,
+ * truncated to MAX_GROUP_CONFIG_BYTES. Returns undefined when:
+ *   - groupConfigDir is not configured,
+ *   - groupId is empty or unsafe as a path segment,
+ *   - the file does not exist or is unreadable.
+ *
+ * Never throws — a misconfigured dir or unreadable file degrades to "no custom
+ * instructions" rather than failing the turn.
+ */
+export function loadGroupConfig(groupConfigDir, groupId) {
+    if (!groupConfigDir)
+        return undefined;
+    if (!groupId || !isSafeId(groupId))
+        return undefined;
+    const path = join(groupConfigDir, `${groupId}.md`);
+    try {
+        if (!existsSync(path))
+            return undefined;
+        const st = statSync(path);
+        if (!st.isFile())
+            return undefined;
+        // Defense-in-depth: refuse a group/world-writable file. Its contents are
+        // injected UNSANITIZED into the system prompt, so a file anyone-but-the-
+        // operator can write is an untrusted injection sink. This catches the most
+        // common misconfiguration; it is NOT a substitute for proper OS perms +
+        // a hardened deployment (the agent can still write operator-owned paths
+        // under default Bash/bypassPermissions — see the module header).
+        if ((st.mode & 0o022) !== 0) {
+            console.error(`[cc-channel-octo] refusing group config ${path}: file is group/world-writable ` +
+                `(mode ${(st.mode & 0o777).toString(8)}). Make it writable only by the gateway user.`);
+            return undefined;
+        }
+        // Read at most MAX+1 bytes so a mistakenly huge file can't block the event
+        // loop or allocate unbounded memory on every group turn. Reading one extra
+        // byte lets us detect (and mark) truncation.
+        const fd = openSync(path, 'r');
+        let content;
+        let wasTruncated = false;
+        try {
+            const buf = Buffer.allocUnsafe(MAX_GROUP_CONFIG_BYTES + 1);
+            const bytesRead = readSync(fd, buf, 0, MAX_GROUP_CONFIG_BYTES + 1, 0);
+            wasTruncated = bytesRead > MAX_GROUP_CONFIG_BYTES;
+            const slice = buf.subarray(0, Math.min(bytesRead, MAX_GROUP_CONFIG_BYTES));
+            content = slice.toString('utf-8');
+        }
+        finally {
+            closeSync(fd);
+        }
+        if (wasTruncated) {
+            // The slice may end mid-codepoint; trim back to a valid UTF-8 boundary by
+            // dropping any trailing replacement char produced by a split sequence.
+            content = content.replace(/�+$/, '');
+            content += '\n[… group config truncated]';
+        }
+        const trimmed = content.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    catch (err) {
+        console.error(`[cc-channel-octo] group config read failed for ${path}: ${String(err)}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=group-config.js.map

package/dist/group-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-config.js","sourceRoot":"","sources":["../src/group-config.ts"],"names":[],"mappings":"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"}

package/dist/group-context.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Group Context — group chat message cache + maxContextChars budget + mention mapping.
+ */
+import type { DbAdapter } from './db-adapter.js';
+export declare class GroupContext {
+    private readonly messageCache;
+    private readonly memberMapByChannel;
+    private readonly nameToUidByChannel;
+    private readonly robotFlags;
+    private readonly lastRefresh;
+    private readonly adapter;
+    private readonly maxContextChars;
+    private readonly maxWindowSize;
+    private upsertMember;
+    private deleteMember;
+    private selectMembers;
+    private insertMessage;
+    private selectRecentMessages;
+    private deleteOldMessages;
+    private selectMessagesSince;
+    private selectMaxId;
+    private upsertCursor;
+    private selectCursor;
+    constructor(adapter: DbAdapter, maxContextChars: number);
+    private initStatements;
+    private getMemberMap;
+    private getNameToUid;
+    pushMessage(channelId: string, fromUid: string, fromName: string, content: string, timestamp: number): void;
+    learnMember(channelId: string, uid: string, name: string): void;
+    refreshMembers(channelId: string, apiUrl: string, botToken: string): Promise<void>;
+    fetchAndLearnUser(uid: string, channelId: string, apiUrl: string, botToken: string): Promise<string | undefined>;
+    buildContext(channelId: string): string;
+    /** Read the per-channel consumption cursor (highest already-injected id), or 0. */
+    getContextCursor(channelId: string): number;
+    /** Advance the per-channel cursor to `lastId` (monotonic — never moves backward). */
+    setContextCursor(channelId: string, lastId: number): void;
+    /** The highest group_messages.id for a channel (for cursor priming), or 0. */
+    getMaxMessageId(channelId: string): number;
+    /**
+     * Build a group-context block from messages NEWER than `sinceId` (the delta the
+     * model hasn't seen yet), within `maxContextChars`. Returns the block text (same
+     * `[Recent group messages]` format as buildContext) and the highest id that
+     * EXISTS in the channel above `sinceId` (so the caller advances the cursor past
+     * the whole delta, including any oldest lines the char budget dropped — those
+     * are the least-relevant and are intentionally not re-shown). Empty text + the
+     * unchanged cursor when there's nothing new.
+     *
+     * Rows are fetched newest-first (so a backlog larger than the budget keeps the
+     * most-recent messages); the selected slice is reversed back to chronological
+     * order for display. Unlike buildContext (in-memory rolling window), this reads
+     * from the DB so the cursor delta is exact even across restarts / window eviction.
+     */
+    buildContextSince(channelId: string, sinceId: number): {
+        text: string;
+        lastId: number;
+    };
+    resolveMentions(text: string, channelId: string): string[];
+    getName(uid: string, channelId: string): string | undefined;
+    /** G23: Check the server-authoritative robot flag for a group member. */
+    isRobot(channelId: string, uid: string): boolean | undefined;
+    /**
+     * A8 (#143): true iff `uid` is a current member of `channelId` per the cached
+     * member list. The list is kept authoritative by refreshMembers (it prunes
+     * departed members, not just upserts) — but it is only best-effort fresh:
+     * refresh is throttled to REFRESH_INTERVAL_MS and seeded from DB on restart,
+     * so a membership change inside that window may not be reflected yet. Used by
+     * the outbound mention guard as defense-in-depth (the server still enforces
+     * real permissions), NOT as a real-time authority.
+     */
+    isMember(channelId: string, uid: string): boolean;
+    /**
+     * A8 (#143): the channel's displayName→uid map, for v1 `@name` outbound
+     * resolution in StreamRelay.deliver. Returns the live map (empty if the
+     * channel has no cached members yet). Read-only use by callers.
+     */
+    getNameToUidMap(channelId: string): Map<string, string>;
+    loadMembersFromDb(channelId: string): void;
+    loadMessagesFromDb(channelId: string): void;
+    /** Load all persisted members and messages from DB (call once at startup). */
+    loadAllFromDb(): void;
+}

package/dist/group-context.js

@@ -0,0 +1,466 @@
+/**
+ * Group Context — group chat message cache + maxContextChars budget + mention mapping.
+ */
+import { getGroupMembers, fetchUserInfo } from './octo/api.js';
+import { sanitizeDisplayName } from './prompt-safety.js';
+const REFRESH_INTERVAL_MS = 60 * 60 * 1000;
+export class GroupContext {
+    messageCache = new Map();
+    // Per-channel member maps to avoid cross-group name collisions
+    memberMapByChannel = new Map(); // channelId → uid → name
+    nameToUidByChannel = new Map(); // channelId → name → uid
+    // G23: per-channel robot flag map (channelId → uid → isRobot).
+    // Populated from refreshMembers; stored for future routing integrations
+    // (e.g. 免@ gate that should treat bot members differently).
+    robotFlags = new Map();
+    lastRefresh = new Map();
+    adapter;
+    maxContextChars;
+    maxWindowSize;
+    upsertMember;
+    deleteMember;
+    selectMembers;
+    insertMessage;
+    selectRecentMessages;
+    deleteOldMessages;
+    selectMessagesSince;
+    selectMaxId;
+    upsertCursor;
+    selectCursor;
+    constructor(adapter, maxContextChars) {
+        this.adapter = adapter;
+        this.maxContextChars = maxContextChars;
+        this.maxWindowSize = 100;
+        this.initStatements();
+    }
+    initStatements() {
+        this.adapter.exec(`
+      CREATE TABLE IF NOT EXISTS group_messages (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        channel_id TEXT NOT NULL,
+        from_uid TEXT NOT NULL,
+        from_name TEXT NOT NULL,
+        content TEXT NOT NULL,
+        timestamp INTEGER NOT NULL
+      )
+    `);
+        this.adapter.exec(`
+      CREATE INDEX IF NOT EXISTS idx_group_messages_channel
+      ON group_messages (channel_id, id DESC)
+    `);
+        // Per-channel consumption cursor: the highest group_messages.id that has
+        // already been injected into a turn for this channel. Only group messages
+        // NEWER than this are injected next turn (the bot's standing context lives in
+        // the SDK session, so re-injecting the whole window every turn would be both
+        // redundant and a frozen-prompt violation). Mirrors the reset_barriers /
+        // sdk_sessions single-row-per-key pattern.
+        this.adapter.exec(`
+      CREATE TABLE IF NOT EXISTS group_context_cursors (
+        channel_id TEXT PRIMARY KEY,
+        last_id INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      )
+    `);
+        this.upsertMember = this.adapter.prepare('INSERT INTO group_members (group_id, uid, name, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(group_id, uid) DO UPDATE SET name = excluded.name, updated_at = excluded.updated_at');
+        this.deleteMember = this.adapter.prepare('DELETE FROM group_members WHERE group_id = ? AND uid = ?');
+        this.selectMembers = this.adapter.prepare('SELECT uid, name FROM group_members WHERE group_id = ?');
+        this.insertMessage = this.adapter.prepare('INSERT INTO group_messages (channel_id, from_uid, from_name, content, timestamp) VALUES (?, ?, ?, ?, ?)');
+        this.selectRecentMessages = this.adapter.prepare('SELECT from_uid, from_name, content, timestamp FROM group_messages WHERE channel_id = ? ORDER BY id DESC LIMIT ?');
+        this.deleteOldMessages = this.adapter.prepare('DELETE FROM group_messages WHERE channel_id = ? AND id NOT IN (SELECT id FROM group_messages WHERE channel_id = ? ORDER BY id DESC LIMIT ?)');
+        // Cursor delta: messages strictly newer than the cursor, NEWEST-first so a
+        // backlog larger than the fetch limit keeps the most-recent messages (the
+        // relevant ones) rather than ancient ones. LIMIT (maxWindowSize=100) is <=
+        // deleteOldMessages' retained 200, so every fetchable row survives trimming.
+        // buildContextSince re-sorts the budget-selected slice into chronological
+        // order for display. Mirrors the in-memory buildContext rolling-window.
+        this.selectMessagesSince = this.adapter.prepare('SELECT id, from_name, content FROM group_messages WHERE channel_id = ? AND id > ? ORDER BY id DESC LIMIT ?');
+        this.selectMaxId = this.adapter.prepare('SELECT MAX(id) AS maxId FROM group_messages WHERE channel_id = ?');
+        this.upsertCursor = this.adapter.prepare('INSERT INTO group_context_cursors (channel_id, last_id, updated_at) VALUES (?, ?, ?) ' +
+            'ON CONFLICT(channel_id) DO UPDATE SET last_id = excluded.last_id, updated_at = excluded.updated_at ' +
+            'WHERE excluded.last_id > group_context_cursors.last_id');
+        this.selectCursor = this.adapter.prepare('SELECT last_id FROM group_context_cursors WHERE channel_id = ?');
+    }
+    getMemberMap(channelId) {
+        let m = this.memberMapByChannel.get(channelId);
+        if (!m) {
+            m = new Map();
+            this.memberMapByChannel.set(channelId, m);
+        }
+        return m;
+    }
+    getNameToUid(channelId) {
+        let m = this.nameToUidByChannel.get(channelId);
+        if (!m) {
+            m = new Map();
+            this.nameToUidByChannel.set(channelId, m);
+        }
+        return m;
+    }
+    pushMessage(channelId, fromUid, fromName, content, timestamp) {
+        // SECURITY: fromName is the user-controlled IM display name and is rendered
+        // into the [Group context] block as `<name>：<content>`. Bound + strip it at
+        // the boundary (shared choke point) so it can't forge a label/line. fromUid
+        // is ALSO user-controlled, and sanitizeDisplayName returns its fallback
+        // verbatim — so sanitize the uid fallback too rather than passing it raw
+        // (PR #128 review: raw-uid-as-fallback re-introduces the injection).
+        const safeName = sanitizeDisplayName(fromName) || sanitizeDisplayName(fromUid) || 'unknown';
+        let window = this.messageCache.get(channelId);
+        if (!window) {
+            window = [];
+            this.messageCache.set(channelId, window);
+        }
+        window.push({ fromUid, fromName: safeName, content, timestamp });
+        while (window.length > this.maxWindowSize) {
+            window.shift();
+        }
+        this.learnMember(channelId, fromUid, safeName);
+        try {
+            this.insertMessage.run(channelId, fromUid, safeName, content, timestamp);
+            // Trim old messages to keep DB bounded (keep 2x window for safety)
+            this.deleteOldMessages.run(channelId, channelId, this.maxWindowSize * 2);
+        }
+        catch (err) {
+            console.error(`group-context: insert message failed: ${String(err)}`);
+        }
+    }
+    learnMember(channelId, uid, name) {
+        if (!uid || !name)
+            return;
+        const memberMap = this.getMemberMap(channelId);
+        const nameMap = this.getNameToUid(channelId);
+        const existing = memberMap.get(uid);
+        if (existing !== name) {
+            // Remove old reverse mapping only if it still points to THIS uid.
+            // If another user already claimed the same display name, don't clobber.
+            if (existing && nameMap.get(existing) === uid) {
+                nameMap.delete(existing);
+            }
+            memberMap.set(uid, name);
+            nameMap.set(name, uid);
+            try {
+                this.upsertMember.run(channelId, uid, name, Date.now());
+            }
+            catch (err) {
+                console.error(`group-context: upsert member failed: ${String(err)}`);
+            }
+        }
+    }
+    async refreshMembers(channelId, apiUrl, botToken) {
+        const now = Date.now();
+        const last = this.lastRefresh.get(channelId) ?? 0;
+        if (now - last < REFRESH_INTERVAL_MS)
+            return;
+        // Don't set lastRefresh here — only on success
+        try {
+            const members = await getGroupMembers({ apiUrl, botToken, groupNo: channelId });
+            this.lastRefresh.set(channelId, now); // Record only on success
+            const memberMap = this.getMemberMap(channelId);
+            const nameMap = this.getNameToUid(channelId);
+            // A8 (#143, take 2): the server response is AUTHORITATIVE — it is the full
+            // current roster, not a delta. Upserting returned members WITHOUT pruning
+            // departed ones (the original #144 bug, Jerry-Xin's 🔴) left a user who
+            // left the group cached forever, so isMember() kept accepting them and the
+            // outbound mention guard let a stale @uid through. Track who the server
+            // returned, then drop anyone cached/persisted who is no longer present.
+            //
+            // Best-effort caveat: this is only as fresh as the last successful refresh,
+            // which is throttled to REFRESH_INTERVAL_MS (1h) and seeded from DB on
+            // restart. A membership change inside that window is not reflected until
+            // the next refresh — the outbound guard is defense-in-depth, not a
+            // real-time authority. The server still enforces real permissions.
+            const present = new Set();
+            for (const m of members) {
+                if (!m.uid || !m.name)
+                    continue;
+                present.add(m.uid);
+                const oldName = memberMap.get(m.uid);
+                if (oldName && oldName !== m.name && nameMap.get(oldName) === m.uid) {
+                    nameMap.delete(oldName);
+                }
+                memberMap.set(m.uid, m.name);
+                nameMap.set(m.name, m.uid);
+                // G23: Track server-authoritative robot flag for future 免@ gate.
+                if (m.robot !== undefined) {
+                    let rfMap = this.robotFlags.get(channelId);
+                    if (!rfMap) {
+                        rfMap = new Map();
+                        this.robotFlags.set(channelId, rfMap);
+                    }
+                    rfMap.set(m.uid, m.robot === 1);
+                }
+                try {
+                    this.upsertMember.run(channelId, m.uid, m.name, now);
+                }
+                catch (err) {
+                    console.error(`group-context: upsert member failed: ${String(err)}`);
+                }
+            }
+            // Prune members no longer in the authoritative roster (memory + DB + robot
+            // flags). Iterate a snapshot of uids since we mutate the map in the loop.
+            //
+            // Guard: skip pruning when the roster came back EMPTY. getGroupMembers
+            // returns [] not only for a genuinely empty group but also for a
+            // malformed/unexpected-shape 200 response (data.members not an array →
+            // silently []). A group the bot is in always has ≥1 member, so an empty
+            // roster is far more likely a transient quirk than "everyone left".
+            // Mass-pruning on it would wipe the whole roster — and since lastRefresh
+            // was already set on this "success", it wouldn't re-fetch for an hour,
+            // downgrading every mention to plain text in that window. Keep the prior
+            // snapshot instead; a real emptying still prunes member-by-member as the
+            // roster shrinks across non-empty responses.
+            if (present.size > 0) {
+                const rfMap = this.robotFlags.get(channelId);
+                for (const uid of [...memberMap.keys()]) {
+                    if (present.has(uid))
+                        continue;
+                    const staleName = memberMap.get(uid);
+                    memberMap.delete(uid);
+                    // Only remove the reverse entry if it still points at THIS uid (a rename
+                    // may have already re-pointed the name to someone else).
+                    if (staleName !== undefined && nameMap.get(staleName) === uid) {
+                        nameMap.delete(staleName);
+                    }
+                    rfMap?.delete(uid);
+                    try {
+                        this.deleteMember.run(channelId, uid);
+                    }
+                    catch (err) {
+                        console.error(`group-context: delete stale member failed: ${String(err)}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(`group-context: refreshMembers(${channelId}) failed: ${String(err)}`);
+            // Don't update lastRefresh on failure — allow retry
+        }
+    }
+    async fetchAndLearnUser(uid, channelId, apiUrl, botToken) {
+        const memberMap = this.getMemberMap(channelId);
+        const cached = memberMap.get(uid);
+        if (cached)
+            return cached;
+        try {
+            const info = await fetchUserInfo({ apiUrl, botToken, uid });
+            if (info?.name) {
+                this.learnMember(channelId, uid, info.name);
+                return info.name;
+            }
+        }
+        catch (err) {
+            console.error(`group-context: fetchUserInfo(${uid}) failed: ${String(err)}`);
+        }
+        return undefined;
+    }
+    buildContext(channelId) {
+        const window = this.messageCache.get(channelId);
+        if (!window || window.length === 0)
+            return '';
+        const header = '[Recent group messages]\n';
+        const trailer = '\n';
+        const budget = this.maxContextChars - header.length - trailer.length;
+        if (budget <= 0)
+            return '';
+        const selected = [];
+        let used = 0;
+        for (let i = window.length - 1; i >= 0; i--) {
+            const m = window[i];
+            const line = `${m.fromName}：${m.content}`;
+            const cost = line.length + (selected.length > 0 ? 1 : 0);
+            if (used + cost > budget)
+                break;
+            selected.push(line);
+            used += cost;
+        }
+        if (selected.length === 0)
+            return '';
+        selected.reverse();
+        return `${header}${selected.join('\n')}${trailer}`;
+    }
+    /** Read the per-channel consumption cursor (highest already-injected id), or 0. */
+    getContextCursor(channelId) {
+        try {
+            const row = this.selectCursor.get(channelId);
+            return row?.last_id ?? 0;
+        }
+        catch (err) {
+            console.error(`group-context: getContextCursor(${channelId}) failed: ${String(err)}`);
+            return 0;
+        }
+    }
+    /** Advance the per-channel cursor to `lastId` (monotonic — never moves backward). */
+    setContextCursor(channelId, lastId) {
+        try {
+            this.upsertCursor.run(channelId, lastId, Date.now());
+        }
+        catch (err) {
+            console.error(`group-context: setContextCursor(${channelId}) failed: ${String(err)}`);
+        }
+    }
+    /** The highest group_messages.id for a channel (for cursor priming), or 0. */
+    getMaxMessageId(channelId) {
+        try {
+            const row = this.selectMaxId.get(channelId);
+            return row?.maxId ?? 0;
+        }
+        catch (err) {
+            console.error(`group-context: getMaxMessageId(${channelId}) failed: ${String(err)}`);
+            return 0;
+        }
+    }
+    /**
+     * Build a group-context block from messages NEWER than `sinceId` (the delta the
+     * model hasn't seen yet), within `maxContextChars`. Returns the block text (same
+     * `[Recent group messages]` format as buildContext) and the highest id that
+     * EXISTS in the channel above `sinceId` (so the caller advances the cursor past
+     * the whole delta, including any oldest lines the char budget dropped — those
+     * are the least-relevant and are intentionally not re-shown). Empty text + the
+     * unchanged cursor when there's nothing new.
+     *
+     * Rows are fetched newest-first (so a backlog larger than the budget keeps the
+     * most-recent messages); the selected slice is reversed back to chronological
+     * order for display. Unlike buildContext (in-memory rolling window), this reads
+     * from the DB so the cursor delta is exact even across restarts / window eviction.
+     */
+    buildContextSince(channelId, sinceId) {
+        let rows;
+        try {
+            rows = this.selectMessagesSince.all(channelId, sinceId, this.maxWindowSize);
+        }
+        catch (err) {
+            console.error(`group-context: buildContextSince(${channelId}) failed: ${String(err)}`);
+            return { text: '', lastId: sinceId };
+        }
+        if (rows.length === 0)
+            return { text: '', lastId: sinceId };
+        // rows are newest-first; the highest id is the first row. Advance the cursor to
+        // it regardless of what the budget keeps, so we never re-show a line.
+        const lastId = rows[0].id;
+        const header = '[Recent group messages]\n';
+        const trailer = '\n';
+        const budget = this.maxContextChars - header.length - trailer.length;
+        if (budget <= 0)
+            return { text: '', lastId };
+        // Walk newest→oldest (rows[0] is newest) keeping lines within budget.
+        const selected = [];
+        let used = 0;
+        for (let i = 0; i < rows.length; i++) {
+            const line = `${rows[i].from_name}：${rows[i].content}`;
+            const cost = line.length + (selected.length > 0 ? 1 : 0);
+            if (used + cost > budget)
+                break;
+            selected.push(line);
+            used += cost;
+        }
+        if (selected.length === 0)
+            return { text: '', lastId };
+        selected.reverse(); // chronological order for display
+        return { text: `${header}${selected.join('\n')}${trailer}`, lastId };
+    }
+    resolveMentions(text, channelId) {
+        const uids = [];
+        const seen = new Set();
+        const nameMap = this.nameToUidByChannel.get(channelId);
+        if (!nameMap)
+            return uids;
+        // Match @name where name is a run of word-like characters (letters, digits, underscores,
+        // CJK ideographs, Hangul, Kana, etc.) — stops at punctuation and whitespace.
+        const regex = /@([\w\u4e00-\u9fff\u3400-\u4dbf\uac00-\ud7af\u3040-\u309f\u30a0-\u30ff]+)/g;
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            // Strip known trailing punctuation that might stick to names
+            let name = match[1];
+            name = name.replace(/[,.!?;:，。！？；：、)\]]+$/, '');
+            if (!name)
+                continue;
+            const uid = nameMap.get(name);
+            if (uid && !seen.has(uid)) {
+                seen.add(uid);
+                uids.push(uid);
+            }
+        }
+        return uids;
+    }
+    getName(uid, channelId) {
+        return this.getMemberMap(channelId).get(uid);
+    }
+    /** G23: Check the server-authoritative robot flag for a group member. */
+    isRobot(channelId, uid) {
+        return this.robotFlags.get(channelId)?.get(uid);
+    }
+    /**
+     * A8 (#143): true iff `uid` is a current member of `channelId` per the cached
+     * member list. The list is kept authoritative by refreshMembers (it prunes
+     * departed members, not just upserts) — but it is only best-effort fresh:
+     * refresh is throttled to REFRESH_INTERVAL_MS and seeded from DB on restart,
+     * so a membership change inside that window may not be reflected yet. Used by
+     * the outbound mention guard as defense-in-depth (the server still enforces
+     * real permissions), NOT as a real-time authority.
+     */
+    isMember(channelId, uid) {
+        return this.memberMapByChannel.get(channelId)?.has(uid) ?? false;
+    }
+    /**
+     * A8 (#143): the channel's displayName→uid map, for v1 `@name` outbound
+     * resolution in StreamRelay.deliver. Returns the live map (empty if the
+     * channel has no cached members yet). Read-only use by callers.
+     */
+    getNameToUidMap(channelId) {
+        return this.getNameToUid(channelId);
+    }
+    loadMembersFromDb(channelId) {
+        try {
+            const rows = this.selectMembers.all(channelId);
+            const memberMap = this.getMemberMap(channelId);
+            const nameMap = this.getNameToUid(channelId);
+            for (const r of rows) {
+                if (!r.uid || !r.name)
+                    continue;
+                memberMap.set(r.uid, r.name);
+                nameMap.set(r.name, r.uid);
+            }
+        }
+        catch (err) {
+            console.error(`group-context: loadMembersFromDb(${channelId}) failed: ${String(err)}`);
+        }
+    }
+    loadMessagesFromDb(channelId) {
+        try {
+            const rows = this.selectRecentMessages.all(channelId, this.maxWindowSize);
+            if (rows.length === 0)
+                return;
+            // Rows come in DESC order, reverse to chronological
+            rows.reverse();
+            const existing = this.messageCache.get(channelId);
+            if (existing && existing.length > 0)
+                return; // Don't overwrite live data
+            // Map snake_case DB columns to camelCase GroupMessage
+            this.messageCache.set(channelId, rows.map(r => ({
+                fromUid: r.from_uid,
+                fromName: r.from_name,
+                content: r.content,
+                timestamp: r.timestamp,
+            })));
+        }
+        catch (err) {
+            console.error(`group-context: loadMessagesFromDb(${channelId}) failed: ${String(err)}`);
+        }
+    }
+    /** Load all persisted members and messages from DB (call once at startup). */
+    loadAllFromDb() {
+        try {
+            const rows = this.adapter.prepare('SELECT DISTINCT group_id FROM group_members').all();
+            for (const row of rows) {
+                this.loadMembersFromDb(row.group_id);
+                this.loadMessagesFromDb(row.group_id);
+            }
+            if (rows.length > 0) {
+                console.log(`[group-context] Loaded members + messages for ${rows.length} group(s) from DB`);
+            }
+        }
+        catch (err) {
+            console.error(`group-context: loadAllFromDb failed: ${String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=group-context.js.map