@ixo/oracle-runtime 0.0.1

package/dist/plugins/matrix-group-chats/channel-memory.summarizer.js

@@ -0,0 +1,128 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { Logger } from '@nestjs/common';
+import { getProviderChatModel } from '../../llm/llm-provider.js';
+const logger = new Logger('ChannelMemorySummarizer');
+const SYSTEM_PROMPT = `You compact a chunk of group-chat messages into a durable, dense summary used as long-term memory for an AI assistant.
+
+KEEP:
+- Decisions, agreements, commitments
+- Concrete facts (names, dates, numbers, URLs)
+- Topics discussed and any unresolved questions
+- Member dynamics and stated preferences
+- Action items and ownership
+
+DROP:
+- Pleasantries, fillers, redundancy
+- Transient state (typing, reactions)
+- Information that has been explicitly superseded
+
+OUTPUT RULES:
+- Output ONLY the summary text. No preamble, no headings, no markdown lists unless they aid clarity.
+- Aim for 200-400 tokens.
+- Refer to people by their display name.
+- Be concrete. Quote short fragments verbatim when wording matters.
+- If the messages are mostly chitchat, produce a one-sentence summary noting that.`;
+const TIER_ROLLUP_PROMPT = `You are consolidating several already-summarized chunks of group-chat history into a single higher-tier summary.
+
+KEEP:
+- Persistent facts, decisions, ownership, deadlines that still matter
+- Names, project context, recurring topics
+- Unresolved threads that were never closed
+
+DROP:
+- Day-to-day chatter that is no longer relevant
+- Anything explicitly superseded by a later chunk
+
+OUTPUT:
+- A single dense paragraph (or short paragraphs) — no headings.
+- 200-400 tokens. Refer to people by display name.
+- Be concrete; quote fragments when wording matters.`;
+const formatMessagesForPrompt = (messages) => messages
+    .map((m) => {
+    const ts = new Date(m.timestamp).toISOString();
+    const thread = m.threadId ? ` thread=${m.threadId.slice(0, 10)}` : '';
+    return `[${m.senderDisplayName} @ ${ts}${thread}]: ${m.body}`;
+})
+    .join('\n');
+export class ChannelMemorySummarizer {
+    /**
+     * Compact a batch of observed messages into a summary string.
+     * Returns null if the LLM call fails — caller should keep the buffer.
+     */
+    async summarize(messages) {
+        if (messages.length === 0)
+            return null;
+        try {
+            const llm = getProviderChatModel('session-title', {
+                temperature: 0.2,
+                maxTokens: 800,
+            });
+            const prompt = formatMessagesForPrompt(messages);
+            const response = await llm.invoke([
+                new SystemMessage(SYSTEM_PROMPT),
+                new HumanMessage(prompt),
+            ]);
+            const text = extractText(response.content).trim();
+            if (!text) {
+                logger.warn(`[Summarizer] Empty summary returned for ${messages.length} messages`);
+                return null;
+            }
+            return text.length > 6000 ? text.slice(0, 6000) : text;
+        }
+        catch (err) {
+            logger.warn(`[Summarizer] Compaction failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Consolidate multiple tier-N summaries into a single tier-(N+1) summary.
+     * Used by the tier scheduler for week/month rollups.
+     */
+    async rollup(summaries) {
+        if (summaries.length === 0)
+            return null;
+        if (summaries.length === 1)
+            return summaries[0] ?? null;
+        try {
+            const llm = getProviderChatModel('session-title', {
+                temperature: 0.2,
+                maxTokens: 800,
+            });
+            const body = summaries
+                .map((s, i) => `--- chunk ${i + 1} ---\n${s}`)
+                .join('\n\n');
+            const response = await llm.invoke([
+                new SystemMessage(TIER_ROLLUP_PROMPT),
+                new HumanMessage(body),
+            ]);
+            const text = extractText(response.content).trim();
+            if (!text) {
+                logger.warn(`[Summarizer] Empty rollup returned for ${summaries.length} chunks`);
+                return null;
+            }
+            return text.length > 6000 ? text.slice(0, 6000) : text;
+        }
+        catch (err) {
+            logger.warn(`[Summarizer] Rollup failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+}
+function extractText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => {
+            if (typeof part === 'string')
+                return part;
+            if (part && typeof part === 'object' && 'text' in part) {
+                const t = part.text;
+                return typeof t === 'string' ? t : '';
+            }
+            return '';
+        })
+            .join('');
+    }
+    return '';
+}

package/dist/plugins/matrix-group-chats/channel-memory.types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Channel memory — distilled long-term memory of group rooms.
+ *
+ * Each `ChannelMemoryChunk` is an LLM-compacted summary of a batch of recent
+ * room messages. Chunks accumulate immutably. They are NEVER overwritten.
+ *
+ * `tier` drives age-based consolidation:
+ *   - tier=1 — recent, granular (default)
+ *   - tier=2 — older, weekly rollup
+ *   - tier=3 — ancient, monthly rollup
+ */
+export interface ChannelMemoryChunk {
+    id: string;
+    roomId: string;
+    summary: string;
+    fromEventId: string;
+    toEventId: string;
+    fromTimestamp: number;
+    toTimestamp: number;
+    messageCount: number;
+    participants: string[];
+    threadIds: string[];
+    tier: number;
+    createdAt: number;
+}
+export interface PinnedFact {
+    id: string;
+    roomId: string;
+    fact: string;
+    pinnedByDid: string;
+    sourceEventId?: string;
+    createdAt: number;
+}
+export interface ChannelMember {
+    matrixUserId: string;
+    displayName: string;
+    did?: string;
+}
+export interface ObservedMessage {
+    eventId: string;
+    threadId: string;
+    senderDid: string;
+    senderMatrixUserId: string;
+    senderDisplayName: string;
+    body: string;
+    timestamp: number;
+}
+/** Shared-state key under which the service exposes itself. */
+export declare const CHANNEL_MEMORY_SHARED_KEY: "channelMemory";
+//# sourceMappingURL=channel-memory.types.d.ts.map

package/dist/plugins/matrix-group-chats/channel-memory.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-memory.types.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/channel-memory.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,EAAG,eAAwB,CAAC"}

package/dist/plugins/matrix-group-chats/channel-memory.types.js

@@ -0,0 +1,2 @@
+/** Shared-state key under which the service exposes itself. */
+export const CHANNEL_MEMORY_SHARED_KEY = 'channelMemory';

package/dist/plugins/matrix-group-chats/guard.d.ts

@@ -0,0 +1,83 @@
+import { type MatrixManager } from '@ixo/matrix';
+import { type BaseMessage } from '@langchain/core/messages';
+/**
+ * Group-chat utilities — pure, self-contained.
+ *
+ * Decides whether the agent should respond to an incoming Matrix event in a
+ * group room. DMs are unaffected (always respond). Even when the agent stays
+ * silent, the caller is expected to still capture the message into channel
+ * memory so summaries stay accurate.
+ */
+export interface RoomTypeInfo {
+    isDirect: boolean;
+    memberCount: number;
+}
+/** Minimal structural type for the incoming Matrix event. */
+export interface GuardEvent {
+    eventId: string;
+    content?: Record<string, unknown> | undefined;
+}
+export interface ShouldRespondInput {
+    event: GuardEvent;
+    roomId: string;
+    threadId: string;
+    matrixManager: MatrixManager;
+    /** Bot's Matrix user ID, e.g. `@oracle:matrix.example.org`. */
+    botMatrixUserId: string;
+    /** Resolved room type. Caller is responsible for caching. */
+    roomInfo: RoomTypeInfo;
+    /** Active-thread map shared with the middleware. */
+    activeBotThreads: Map<string, number>;
+    /** TTL to use when re-warming an active-thread entry found via history. */
+    activeBotThreadTtlMs: number;
+}
+export type ShouldRespondReason = 'dm' | 'mentioned' | 'reply-to-bot' | 'active-thread' | 'ignored';
+export interface ShouldRespondResult {
+    respond: boolean;
+    reason: ShouldRespondReason;
+}
+/**
+ * True when the event's `m.mentions.user_ids` array includes the bot.
+ * Tolerant of older clients that omit `m.mentions` — returns false.
+ */
+export declare function isBotMentioned(content: Record<string, unknown> | undefined, botMatrixUserId: string): boolean;
+/** Extract the in-reply-to event id from message content, if present. */
+export declare function getInReplyToEventId(content: Record<string, unknown> | undefined): string | undefined;
+/**
+ * Check whether an incoming message is a direct reply to a bot-authored event.
+ * One Matrix API lookup; failures degrade to `false`.
+ */
+export declare function isReplyToBotMessage(event: GuardEvent, roomId: string, matrixManager: MatrixManager, botMatrixUserId: string): Promise<boolean>;
+/** Mark a thread as actively engaged with the bot. */
+export declare function markBotThreadActive(activeBotThreads: Map<string, number>, roomId: string, threadId: string, ttlMs: number): void;
+/**
+ * True when (room, thread) is in the active-bot-thread map and not expired.
+ * Lazily evicts expired entries.
+ */
+export declare function isActiveBotThread(activeBotThreads: Map<string, number>, roomId: string, threadId: string): boolean;
+/** Periodic eviction of expired entries. Called opportunistically. */
+export declare function sweepExpiredBotThreads(activeBotThreads: Map<string, number>): void;
+/**
+ * Resolve whether the agent should respond to this Matrix event.
+ *
+ * Order of precedence:
+ *   1. DM → respond
+ *   2. Bot @mentioned → respond
+ *   3. Direct reply to a bot message → respond
+ *   4. Thread already in active-bot-thread map → respond
+ *   5. Cache cold: check Matrix history for prior bot participation → respond
+ *   6. Otherwise → ignore (still capture passively elsewhere)
+ */
+export declare function shouldAgentRespond(input: ShouldRespondInput): Promise<ShouldRespondResult>;
+/**
+ * Speaker context derived from the most recent HumanMessage in graph state.
+ * In group rooms every HumanMessage carries `additional_kwargs.senderDid`
+ * (and friends). In DMs, fall back to the session-owner DID.
+ */
+export interface SpeakerContext {
+    did: string;
+    matrixUserId?: string;
+    displayName?: string;
+}
+export declare function getCurrentSpeaker(messages: ReadonlyArray<BaseMessage> | undefined, fallbackDid: string): SpeakerContext;
+//# sourceMappingURL=guard.d.ts.map

package/dist/plugins/matrix-group-chats/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,EAAE,YAAY,CAAC;IACvB,oDAAoD;IACpD,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,2EAA2E;IAC3E,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,mBAAmB,GAC3B,IAAI,GACJ,WAAW,GACX,cAAc,GACd,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAOD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,eAAe,EAAE,MAAM,GACtB,OAAO,CAMT;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,MAAM,GAAG,SAAS,CAOpB;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,aAAa,EAC5B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED,sDAAsD;AACtD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAST;AAED,sEAAsE;AACtE,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,IAAI,CAKN;AAoCD;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CA6C9B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,SAAS,EAChD,WAAW,EAAE,MAAM,GAClB,cAAc,CAoBhB"}

package/dist/plugins/matrix-group-chats/guard.js

@@ -0,0 +1,138 @@
+import { Logger } from '@nestjs/common';
+const ACTIVE_THREAD_KEY = (roomId, threadId) => `${roomId}:${threadId}`;
+const logger = new Logger('GroupChatGuard');
+/**
+ * True when the event's `m.mentions.user_ids` array includes the bot.
+ * Tolerant of older clients that omit `m.mentions` — returns false.
+ */
+export function isBotMentioned(content, botMatrixUserId) {
+    if (!content)
+        return false;
+    const mentions = content['m.mentions'];
+    const userIds = mentions?.user_ids;
+    if (!Array.isArray(userIds))
+        return false;
+    return userIds.some((id) => typeof id === 'string' && id === botMatrixUserId);
+}
+/** Extract the in-reply-to event id from message content, if present. */
+export function getInReplyToEventId(content) {
+    if (!content)
+        return undefined;
+    const relates = content['m.relates_to'];
+    const eventId = relates?.['m.in_reply_to']?.event_id;
+    return typeof eventId === 'string' ? eventId : undefined;
+}
+/**
+ * Check whether an incoming message is a direct reply to a bot-authored event.
+ * One Matrix API lookup; failures degrade to `false`.
+ */
+export async function isReplyToBotMessage(event, roomId, matrixManager, botMatrixUserId) {
+    const inReplyTo = getInReplyToEventId(event.content);
+    if (!inReplyTo)
+        return false;
+    try {
+        const target = await matrixManager.getEventById(roomId, inReplyTo);
+        return target?.sender === botMatrixUserId;
+    }
+    catch (err) {
+        logger.warn(`Failed to fetch reply target ${inReplyTo} in ${roomId}: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+/** Mark a thread as actively engaged with the bot. */
+export function markBotThreadActive(activeBotThreads, roomId, threadId, ttlMs) {
+    activeBotThreads.set(ACTIVE_THREAD_KEY(roomId, threadId), Date.now() + ttlMs);
+}
+/**
+ * True when (room, thread) is in the active-bot-thread map and not expired.
+ * Lazily evicts expired entries.
+ */
+export function isActiveBotThread(activeBotThreads, roomId, threadId) {
+    const key = ACTIVE_THREAD_KEY(roomId, threadId);
+    const expiresAt = activeBotThreads.get(key);
+    if (!expiresAt)
+        return false;
+    if (expiresAt <= Date.now()) {
+        activeBotThreads.delete(key);
+        return false;
+    }
+    return true;
+}
+/** Periodic eviction of expired entries. Called opportunistically. */
+export function sweepExpiredBotThreads(activeBotThreads) {
+    const now = Date.now();
+    for (const [key, expiresAt] of activeBotThreads.entries()) {
+        if (expiresAt <= now)
+            activeBotThreads.delete(key);
+    }
+}
+/**
+ * Fallback when the in-memory active-thread cache is cold (restart / TTL
+ * expiry): scan recent Matrix history for prior bot participation in this
+ * thread. Re-warms the cache on hit.
+ */
+async function hasBotSpokenInThread(roomId, threadId, matrixManager, botMatrixUserId, activeBotThreads, activeBotThreadTtlMs) {
+    try {
+        const { messages } = await matrixManager.getRecentRoomMessages(roomId, {
+            limit: 100,
+        });
+        const botWasActive = messages.some((m) => m.sender === botMatrixUserId && m.threadId === threadId);
+        if (botWasActive) {
+            markBotThreadActive(activeBotThreads, roomId, threadId, activeBotThreadTtlMs);
+        }
+        return botWasActive;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve whether the agent should respond to this Matrix event.
+ *
+ * Order of precedence:
+ *   1. DM → respond
+ *   2. Bot @mentioned → respond
+ *   3. Direct reply to a bot message → respond
+ *   4. Thread already in active-bot-thread map → respond
+ *   5. Cache cold: check Matrix history for prior bot participation → respond
+ *   6. Otherwise → ignore (still capture passively elsewhere)
+ */
+export async function shouldAgentRespond(input) {
+    const { event, roomId, threadId, matrixManager, botMatrixUserId, roomInfo, activeBotThreads, activeBotThreadTtlMs, } = input;
+    if (roomInfo.isDirect) {
+        return { respond: true, reason: 'dm' };
+    }
+    if (isBotMentioned(event.content, botMatrixUserId)) {
+        return { respond: true, reason: 'mentioned' };
+    }
+    if (await isReplyToBotMessage(event, roomId, matrixManager, botMatrixUserId)) {
+        return { respond: true, reason: 'reply-to-bot' };
+    }
+    if (isActiveBotThread(activeBotThreads, roomId, threadId)) {
+        return { respond: true, reason: 'active-thread' };
+    }
+    if (threadId !== event.eventId &&
+        (await hasBotSpokenInThread(roomId, threadId, matrixManager, botMatrixUserId, activeBotThreads, activeBotThreadTtlMs))) {
+        return { respond: true, reason: 'active-thread' };
+    }
+    return { respond: false, reason: 'ignored' };
+}
+export function getCurrentSpeaker(messages, fallbackDid) {
+    if (!messages || messages.length === 0)
+        return { did: fallbackDid };
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m && typeof m._getType === 'function' && m._getType() === 'human') {
+            const kwargs = (m.additional_kwargs ?? {});
+            const did = typeof kwargs.senderDid === 'string' ? kwargs.senderDid : fallbackDid;
+            const matrixUserId = typeof kwargs.senderMatrixUserId === 'string'
+                ? kwargs.senderMatrixUserId
+                : undefined;
+            const displayName = typeof kwargs.senderDisplayName === 'string'
+                ? kwargs.senderDisplayName
+                : undefined;
+            return { did, matrixUserId, displayName };
+        }
+    }
+    return { did: fallbackDid };
+}

package/dist/plugins/matrix-group-chats/index.d.ts

@@ -0,0 +1,59 @@
+import { MatrixManager } from '@ixo/matrix';
+import type { DynamicModule, Type } from '@nestjs/common';
+import { type AgentMiddleware } from 'langchain';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginContext, PluginManifest, PluginTool, RuntimeContext } from '../../plugin-api/types.js';
+/**
+ * `matrix-group-chats` — one plugin that owns the per-room memory pipeline
+ * AND the per-turn gating middleware for Matrix group rooms.
+ *
+ * Activation:
+ *  - **Boot:** on by default. Developers opt out with
+ *    `features: { 'matrix-group-chats': false }`.
+ *  - **Per request:** the middleware short-circuits when the session is not
+ *    a Matrix room with >2 members, and `getRequestTools` returns the four
+ *    channel-memory tools only for group rooms, so DM oracles never see
+ *    them in the prompt.
+ *
+ * Tools (per-tool visibility=`always`, bypassing the capability gate):
+ *  - `recall_channel_memory` — recent chunks + pinned facts + members
+ *  - `search_channel_memory` — FTS5 keyword search over compacted chunks
+ *  - `pin_room_fact` / `unpin_room_fact` — manage durable per-room facts
+ */
+export declare class MatrixGroupChatsPlugin extends OraclePlugin {
+    static readonly NAME = "matrix-group-chats";
+    readonly name = "matrix-group-chats";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    readonly configSchema: z.ZodObject<{
+        CHANNEL_MEMORY_SYNC_INTERVAL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        GROUP_CHAT_ACTIVE_THREAD_TTL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        GROUP_CHAT_REQUIRE_POWER_LEVEL: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        GROUP_CHAT_ROOM_INFO_TTL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>;
+    /** Shared between `getRequestTools` (membership check) and the middleware. */
+    private readonly roomInfoCache;
+    getNestModules(): Array<Type | DynamicModule>;
+    getMiddlewares(ctx: PluginContext): AgentMiddleware[];
+    /**
+     * Per-request: only expose the four channel-memory tools when the current
+     * session is in a Matrix group room (memberCount > 2). DM / portal /
+     * slack sessions get an empty list so the agent never sees them.
+     */
+    getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]>;
+    getSharedState(): Record<string, (state: unknown, runCtx: RuntimeContext) => unknown>;
+}
+export { ChannelMemoryModule } from './channel-memory.module.js';
+export { ChannelMemoryService } from './channel-memory.service.js';
+export { CHANNEL_MEMORY_SHARED_KEY, type ChannelMember, type ChannelMemoryChunk, type ObservedMessage, type PinnedFact, } from './channel-memory.types.js';
+export { isBotMentioned, isReplyToBotMessage, isActiveBotThread, markBotThreadActive, sweepExpiredBotThreads, shouldAgentRespond, getCurrentSpeaker, type GuardEvent, type RoomTypeInfo, type ShouldRespondInput, type ShouldRespondReason, type ShouldRespondResult, type SpeakerContext, } from './guard.js';
+export { getBotPowerLevel, type BotPowerLevel } from './power-levels.js';
+export { RoomInfoCache } from './room-info.js';
+/**
+ * Tiny export so tests can assert the plugin behaves identically against
+ * the real MatrixManager singleton. Exposed for symmetry — production
+ * callers should use `MatrixGroupChatsPlugin` directly.
+ */
+export { MatrixManager };
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/matrix-group-chats/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,2BAA2B,CAAC;AA8EnC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACtD,MAAM,CAAC,QAAQ,CAAC,IAAI,wBAAwB;IAE5C,QAAQ,CAAC,IAAI,wBAA+B;IAE5C,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,iBAAY;IAE7B,SAAkB,YAAY;;;;;sBAAgB;IAE9C,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+C;IAEpE,cAAc,IAAI,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC;IAI7C,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,EAAE;IAI9D;;;;OAIG;IACY,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAkBnE,cAAc,IAAI,MAAM,CAC/B,MAAM,EACN,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,KAAK,OAAO,CACpD;CAKF;AAED,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EACL,yBAAyB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,UAAU,GAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/plugins/matrix-group-chats/index.js

@@ -0,0 +1,140 @@
+import { MatrixManager } from '@ixo/matrix';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { ChannelMemoryModule } from './channel-memory.module.js';
+import { ChannelMemoryService } from './channel-memory.service.js';
+import { CHANNEL_MEMORY_SHARED_KEY } from './channel-memory.types.js';
+import { buildGroupChatMiddleware } from './middleware.js';
+import { RoomInfoCache } from './room-info.js';
+import { buildChannelMemoryTools } from './tools.js';
+const DEFAULT_ROOM_INFO_TTL_MS = 30 * 60 * 1000;
+const configSchema = z.object({
+    CHANNEL_MEMORY_SYNC_INTERVAL_MS: z.coerce
+        .number()
+        .int()
+        .min(1000)
+        .default(60_000)
+        .describe('Debounce window between a write and the Matrix snapshot upload.'),
+    // Group-chat gating
+    GROUP_CHAT_ACTIVE_THREAD_TTL_MS: z.coerce
+        .number()
+        .int()
+        .min(60_000)
+        .default(30 * 60 * 1000)
+        .describe('How long a thread stays "active with the bot" after a reply.'),
+    GROUP_CHAT_REQUIRE_POWER_LEVEL: z.coerce
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe('Extra minimum power level the bot must have before posting (0 = use the room default).'),
+    GROUP_CHAT_ROOM_INFO_TTL_MS: z.coerce
+        .number()
+        .int()
+        .min(60_000)
+        .default(DEFAULT_ROOM_INFO_TTL_MS)
+        .describe('How long roomInfo (membership, DM flag) stays cached.'),
+});
+const manifest = {
+    title: 'Matrix Group Chats',
+    summary: 'Lets the oracle participate cleanly in Matrix group rooms: it only replies when mentioned, replied to, or already in an active thread, and keeps an FTS5-searchable compacted memory of every room it sits in.',
+    whenToUse: [
+        'A user asks what was said or decided earlier in this Matrix group room.',
+        'A user asks who is in the room or what their role is.',
+        'A durable fact should survive across threads (deadline, decision, project context) — pin it.',
+        'You need to recall the gist of prior conversation before answering a multi-step group request.',
+    ],
+    whenNotToUse: [
+        'Single-user DMs — the plugin only acts in rooms with more than 2 members.',
+        'Long-term personal memory about a specific user — use the Memory plugin.',
+        'Verbatim text of a specific Matrix event — use Matrix history directly.',
+    ],
+    examples: [
+        {
+            user: 'What did we agree about the launch date?',
+            thought: 'Search channel memory for "launch date" before answering — the decision may be in an older chunk.',
+            tool: 'search_channel_memory',
+            args: { query: 'launch date' },
+        },
+        {
+            user: 'Remember that Alice owns the redesign.',
+            thought: 'Persist that as a pinned fact for the group room.',
+            tool: 'pin_room_fact',
+            args: { fact: 'Alice owns the redesign.' },
+        },
+    ],
+    tags: ['matrix', 'group-chat', 'memory'],
+    category: 'communication',
+    visibility: 'on-demand',
+    stability: 'beta',
+};
+/**
+ * `matrix-group-chats` — one plugin that owns the per-room memory pipeline
+ * AND the per-turn gating middleware for Matrix group rooms.
+ *
+ * Activation:
+ *  - **Boot:** on by default. Developers opt out with
+ *    `features: { 'matrix-group-chats': false }`.
+ *  - **Per request:** the middleware short-circuits when the session is not
+ *    a Matrix room with >2 members, and `getRequestTools` returns the four
+ *    channel-memory tools only for group rooms, so DM oracles never see
+ *    them in the prompt.
+ *
+ * Tools (per-tool visibility=`always`, bypassing the capability gate):
+ *  - `recall_channel_memory` — recent chunks + pinned facts + members
+ *  - `search_channel_memory` — FTS5 keyword search over compacted chunks
+ *  - `pin_room_fact` / `unpin_room_fact` — manage durable per-room facts
+ */
+export class MatrixGroupChatsPlugin extends OraclePlugin {
+    static NAME = 'matrix-group-chats';
+    name = MatrixGroupChatsPlugin.NAME;
+    version = '1.0.0';
+    manifest = manifest;
+    configSchema = configSchema;
+    /** Shared between `getRequestTools` (membership check) and the middleware. */
+    roomInfoCache = new RoomInfoCache(DEFAULT_ROOM_INFO_TTL_MS);
+    getNestModules() {
+        return [ChannelMemoryModule];
+    }
+    getMiddlewares(ctx) {
+        return [buildGroupChatMiddleware(ctx)];
+    }
+    /**
+     * Per-request: only expose the four channel-memory tools when the current
+     * session is in a Matrix group room (memberCount > 2). DM / portal /
+     * slack sessions get an empty list so the agent never sees them.
+     */
+    async getRequestTools(rtCtx) {
+        if (rtCtx.session.client !== 'matrix' || !rtCtx.session.roomId) {
+            return [];
+        }
+        try {
+            const info = await this.roomInfoCache.get(rtCtx.session.roomId);
+            if (info.isDirect || info.memberCount <= 2) {
+                return [];
+            }
+        }
+        catch (err) {
+            rtCtx.logger.warn?.(`[matrix-group-chats] getRoomInfo failed for ${rtCtx.session.roomId}: ${err instanceof Error ? err.message : String(err)} — skipping tools`);
+            return [];
+        }
+        return buildChannelMemoryTools();
+    }
+    getSharedState() {
+        return {
+            [CHANNEL_MEMORY_SHARED_KEY]: () => ChannelMemoryService.getInstance(),
+        };
+    }
+}
+export { ChannelMemoryModule } from './channel-memory.module.js';
+export { ChannelMemoryService } from './channel-memory.service.js';
+export { CHANNEL_MEMORY_SHARED_KEY, } from './channel-memory.types.js';
+export { isBotMentioned, isReplyToBotMessage, isActiveBotThread, markBotThreadActive, sweepExpiredBotThreads, shouldAgentRespond, getCurrentSpeaker, } from './guard.js';
+export { getBotPowerLevel } from './power-levels.js';
+export { RoomInfoCache } from './room-info.js';
+/**
+ * Tiny export so tests can assert the plugin behaves identically against
+ * the real MatrixManager singleton. Exposed for symmetry — production
+ * callers should use `MatrixGroupChatsPlugin` directly.
+ */
+export { MatrixManager };

package/dist/plugins/matrix-group-chats/middleware.d.ts

@@ -0,0 +1,31 @@
+import { type AgentMiddleware } from 'langchain';
+import type { Logger, PluginContext } from '../../plugin-api/types.js';
+export interface GroupChatMiddlewareOptions {
+    activeThreadTtlMs: number;
+    requirePowerLevel: number;
+    roomInfoTtlMs: number;
+    logger?: Logger;
+}
+/**
+ * Per-turn gate for Matrix group rooms. Runs as `beforeAgent`:
+ *
+ *  - Non-Matrix transports → pass through.
+ *  - DMs / rooms with ≤2 members → pass through.
+ *  - Group rooms (>2 members):
+ *      - Capture the latest HumanMessage into channel memory (side effect).
+ *      - Run `shouldAgentRespond` (mention / reply-to-bot / active-thread).
+ *      - If the bot shouldn't respond → short-circuit with `jumpTo: 'end'`.
+ *      - If it should → check `m.room.power_levels`; short-circuit when the
+ *        bot lacks send permission.
+ *
+ * Does NOT declare a `stateSchema` and NEVER returns state updates.
+ * Re-declaring the agent's built-in `messages` channel clobbers its
+ * `addMessages` reducer and resets the conversation per turn — that's why
+ * earlier versions of this middleware caused "every message is a new
+ * thread" behaviour. Side effects only.
+ */
+export declare const createGroupChatMiddleware: (options: GroupChatMiddlewareOptions) => AgentMiddleware;
+/** Build the middleware from `PluginContext` config. */
+export declare function buildGroupChatMiddleware(ctx: PluginContext): AgentMiddleware;
+export { RoomInfoCache } from './room-info.js';
+//# sourceMappingURL=middleware.d.ts.map

package/dist/plugins/matrix-group-chats/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/middleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAEnE,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAkBvE,MAAM,WAAW,0BAA0B;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,yBAAyB,GACpC,SAAS,0BAA0B,KAClC,eAiJF,CAAC;AAmCF,wDAAwD;AACxD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,CAY5E;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}