@ixo/oracle-runtime 0.0.1

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

@@ -0,0 +1,186 @@
+import { MatrixManager } from '@ixo/matrix';
+import { createMiddleware } from 'langchain';
+import { mainAgentRequestContextSchema } from '../../graph/main-agent-types.js';
+import { ChannelMemoryService } from './channel-memory.service.js';
+import { markBotThreadActive, shouldAgentRespond, sweepExpiredBotThreads, } from './guard.js';
+import { getBotPowerLevel } from './power-levels.js';
+import { RoomInfoCache } from './room-info.js';
+const NOOP_LOGGER = {
+    log: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+/**
+ * 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 const createGroupChatMiddleware = (options) => {
+    const logger = options.logger ?? NOOP_LOGGER;
+    const activeBotThreads = new Map();
+    const roomInfoCache = new RoomInfoCache(options.roomInfoTtlMs);
+    return createMiddleware({
+        name: 'GroupChatMiddleware',
+        contextSchema: mainAgentRequestContextSchema,
+        beforeAgent: {
+            canJumpTo: ['end'],
+            hook: async (state, runtime) => {
+                const parsedCtx = mainAgentRequestContextSchema.safeParse(runtime.context);
+                if (!parsedCtx.success)
+                    return;
+                const ctx = parsedCtx.data;
+                if (ctx.session.client !== 'matrix' || !ctx.session.roomId) {
+                    return;
+                }
+                const roomId = ctx.session.roomId;
+                const messages = Array.isArray(state.messages)
+                    ? state.messages
+                    : [];
+                const lastHuman = findLastHuman(messages);
+                if (!lastHuman)
+                    return;
+                const kwargs = lastHuman.additional_kwargs
+                    ? { ...lastHuman.additional_kwargs }
+                    : {};
+                const eventId = pickString(kwargs.eventId);
+                const threadId = pickString(kwargs.threadId) ?? eventId;
+                if (!eventId || !threadId) {
+                    logger.warn?.('[GroupChatMiddleware] Last HumanMessage is missing eventId/threadId metadata — passing through');
+                    return;
+                }
+                let roomInfo;
+                try {
+                    roomInfo = await roomInfoCache.get(roomId);
+                }
+                catch (err) {
+                    logger.warn?.(`[GroupChatMiddleware] getRoomInfo failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`);
+                    return;
+                }
+                if (roomInfo.isDirect || roomInfo.memberCount <= 2) {
+                    return;
+                }
+                const channelMemory = ChannelMemoryService.getInstance();
+                const senderDid = pickString(kwargs.senderDid) ?? ctx.user.did;
+                const senderMatrixUserId = pickString(kwargs.senderMatrixUserId) ?? ctx.user.matrixUserId;
+                const senderDisplayName = pickString(kwargs.senderDisplayName) ?? senderMatrixUserId;
+                const body = stringifyContent(lastHuman.content);
+                const observed = {
+                    eventId,
+                    threadId,
+                    senderDid,
+                    senderMatrixUserId,
+                    senderDisplayName,
+                    body,
+                    timestamp: Date.now(),
+                };
+                if (channelMemory) {
+                    try {
+                        channelMemory.observeMessage(roomId, observed);
+                    }
+                    catch (err) {
+                        logger.warn?.(`[GroupChatMiddleware] observeMessage failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                sweepExpiredBotThreads(activeBotThreads);
+                const matrixManager = MatrixManager.getInstance();
+                const botMatrixUserId = matrixManager.getBotMatrixUserId();
+                const event = { eventId, content: kwargs };
+                const decision = await shouldAgentRespond({
+                    event,
+                    roomId,
+                    threadId,
+                    matrixManager,
+                    botMatrixUserId,
+                    roomInfo,
+                    activeBotThreads,
+                    activeBotThreadTtlMs: options.activeThreadTtlMs,
+                });
+                if (!decision.respond) {
+                    logger.log(`[GroupChatMiddleware] room=${roomId} thread=${threadId.slice(0, 10)} ignored (${decision.reason})`);
+                    return { jumpTo: 'end' };
+                }
+                // Power-level check — short-circuit silently if the bot can't post.
+                try {
+                    const pl = await getBotPowerLevel(roomId, botMatrixUserId);
+                    if (!pl.allowed(options.requirePowerLevel)) {
+                        logger.warn(`[GroupChatMiddleware] room=${roomId} bot PL ${pl.pl} < required ${Math.max(pl.sendThreshold, options.requirePowerLevel)} — skipping`);
+                        return { jumpTo: 'end' };
+                    }
+                }
+                catch (err) {
+                    logger.warn?.(`[GroupChatMiddleware] power_levels check failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                markBotThreadActive(activeBotThreads, roomId, threadId, options.activeThreadTtlMs);
+                // Refresh the member roster mid-conversation. Fire-and-forget so
+                // we never block the turn waiting on Matrix.
+                if (channelMemory) {
+                    channelMemory
+                        .refreshMembers(roomId, matrixManager)
+                        .catch(() => undefined);
+                    // JIT compaction — service has its own 3-sec timeout cap.
+                    await channelMemory.compactJustInTime(roomId).catch(() => undefined);
+                }
+                // Intentionally NO state mutation here. Returning `{ messages: ... }`
+                // from `beforeAgent` interacts with the `addMessages` reducer in
+                // ways that break checkpointer thread continuity. The speaker
+                // identity is already on the HumanMessage's `additional_kwargs`
+                // for downstream consumers; we don't need to rewrite the content.
+                return;
+            },
+        },
+    });
+};
+function findLastHuman(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m?.type === 'human') {
+            return m;
+        }
+    }
+    return undefined;
+}
+function pickString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function stringifyContent(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 '';
+}
+/** Build the middleware from `PluginContext` config. */
+export function buildGroupChatMiddleware(ctx) {
+    const config = ctx.config;
+    return createGroupChatMiddleware({
+        activeThreadTtlMs: config.GROUP_CHAT_ACTIVE_THREAD_TTL_MS ?? 30 * 60 * 1000,
+        requirePowerLevel: config.GROUP_CHAT_REQUIRE_POWER_LEVEL ?? 0,
+        roomInfoTtlMs: config.GROUP_CHAT_ROOM_INFO_TTL_MS ?? 30 * 60 * 1000,
+        logger: ctx.logger,
+    });
+}
+export { RoomInfoCache } from './room-info.js';

package/dist/plugins/matrix-group-chats/power-levels.d.ts

@@ -0,0 +1,15 @@
+export interface BotPowerLevel {
+    /** Bot's effective power level in this room. */
+    pl: number;
+    /** Power level required to send `m.room.message` events. */
+    sendThreshold: number;
+    /** True when bot has at least `max(sendThreshold, requiredMin)` PL. */
+    allowed: (requiredMin?: number) => boolean;
+}
+/**
+ * Read `m.room.power_levels` for the room and resolve whether the bot has
+ * permission to send `m.room.message` events. Missing power-levels event
+ * is treated as "everyone allowed" — that's the Matrix default.
+ */
+export declare function getBotPowerLevel(roomId: string, botUserId: string): Promise<BotPowerLevel>;
+//# sourceMappingURL=power-levels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"power-levels.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/power-levels.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CAgCxB"}

package/dist/plugins/matrix-group-chats/power-levels.js

@@ -0,0 +1,36 @@
+import { MatrixManager } from '@ixo/matrix';
+import { Logger } from '@nestjs/common';
+const logger = new Logger('GroupChatPowerLevels');
+/**
+ * Read `m.room.power_levels` for the room and resolve whether the bot has
+ * permission to send `m.room.message` events. Missing power-levels event
+ * is treated as "everyone allowed" — that's the Matrix default.
+ */
+export async function getBotPowerLevel(roomId, botUserId) {
+    let content = null;
+    try {
+        const client = MatrixManager.getInstance().getClient();
+        if (!client) {
+            throw new Error('Matrix client not initialised');
+        }
+        const event = await client.mxClient.getRoomStateEvent(roomId, 'm.room.power_levels', '');
+        if (event && typeof event === 'object') {
+            content = event;
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!/M_NOT_FOUND|not found/i.test(message)) {
+            logger.warn(`Failed to read power_levels for ${roomId}: ${message}`);
+        }
+    }
+    const usersDefault = content?.users_default ?? 0;
+    const eventsDefault = content?.events_default ?? 0;
+    const pl = content?.users?.[botUserId] ?? usersDefault;
+    const sendThreshold = content?.events?.['m.room.message'] ?? eventsDefault;
+    return {
+        pl,
+        sendThreshold,
+        allowed: (requiredMin = 0) => pl >= Math.max(sendThreshold, requiredMin),
+    };
+}

package/dist/plugins/matrix-group-chats/room-info.d.ts

@@ -0,0 +1,23 @@
+import type { RoomTypeInfo } from './guard.js';
+interface CacheEntry {
+    info: RoomTypeInfo & {
+        joinedMemberIds: string[];
+    };
+    expiresAt: number;
+}
+/**
+ * Tiny TTL cache around `MatrixManager.getRoomInfo`. Reused by the
+ * group-chat middleware and the request-time tool builder so we don't pay
+ * a Matrix round-trip on every turn.
+ */
+export declare class RoomInfoCache {
+    private readonly ttlMs;
+    private readonly entries;
+    constructor(ttlMs: number);
+    get(roomId: string): Promise<CacheEntry['info']>;
+    /** Drop a single room (e.g. on member event). */
+    invalidate(roomId: string): void;
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=room-info.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"room-info.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/room-info.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,UAAU,UAAU;IAClB,IAAI,EAAE,YAAY,GAAG;QAAE,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,aAAa;IAGZ,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;gBAE5B,KAAK,EAAE,MAAM;IAEpC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAetD,iDAAiD;IACjD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIhC,KAAK,IAAI,IAAI;CAGd"}

package/dist/plugins/matrix-group-chats/room-info.js

@@ -0,0 +1,34 @@
+import { MatrixManager } from '@ixo/matrix';
+/**
+ * Tiny TTL cache around `MatrixManager.getRoomInfo`. Reused by the
+ * group-chat middleware and the request-time tool builder so we don't pay
+ * a Matrix round-trip on every turn.
+ */
+export class RoomInfoCache {
+    ttlMs;
+    entries = new Map();
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    async get(roomId) {
+        const cached = this.entries.get(roomId);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.info;
+        }
+        const fresh = await MatrixManager.getInstance().getRoomInfo(roomId);
+        const info = {
+            isDirect: fresh.isDirect,
+            memberCount: fresh.memberCount,
+            joinedMemberIds: fresh.joinedMemberIds,
+        };
+        this.entries.set(roomId, { info, expiresAt: Date.now() + this.ttlMs });
+        return info;
+    }
+    /** Drop a single room (e.g. on member event). */
+    invalidate(roomId) {
+        this.entries.delete(roomId);
+    }
+    clear() {
+        this.entries.clear();
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { PluginTool } from '../../plugin-api/types.js';
+/**
+ * Build the per-room channel-memory tools. Visibility=`always` on each so
+ * they bypass the capability gate — gating happens in `getRequestTools`,
+ * which returns these only when the session is in a Matrix group room.
+ */
+export declare function buildChannelMemoryTools(): PluginTool[];
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,2BAA2B,CAAC;AAoC5E;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,UAAU,EAAE,CA+HtD"}

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

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { ChannelMemoryService } from './channel-memory.service.js';
+const formatChunk = (chunk) => ({
+    id: chunk.id,
+    tier: chunk.tier,
+    fromTimestamp: new Date(chunk.fromTimestamp).toISOString(),
+    toTimestamp: new Date(chunk.toTimestamp).toISOString(),
+    messageCount: chunk.messageCount,
+    participants: chunk.participants,
+    threadIds: chunk.threadIds,
+    summary: chunk.summary,
+});
+function getService(rtCtx) {
+    const instance = ChannelMemoryService.getInstance();
+    if (!instance) {
+        rtCtx.logger.warn('ChannelMemoryService not initialised — matrix-group-chats tool invoked without a running Nest context');
+        throw new Error('ChannelMemoryService not initialised');
+    }
+    return instance;
+}
+function requireRoomId(rtCtx) {
+    const roomId = rtCtx.session.roomId;
+    if (!roomId) {
+        throw new Error('No active Matrix room — channel-memory tools require a roomId in the current session.');
+    }
+    return roomId;
+}
+/**
+ * Build the per-room channel-memory tools. Visibility=`always` on each so
+ * they bypass the capability gate — gating happens in `getRequestTools`,
+ * which returns these only when the session is in a Matrix group room.
+ */
+export function buildChannelMemoryTools() {
+    return [
+        {
+            name: 'recall_channel_memory',
+            description: 'Read recent channel memory: most recent compacted summary chunks, pinned facts, and the member roster for the current group room. Use this to understand what has been happening in this channel before responding.',
+            visibility: 'always',
+            schema: z.object({
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(30)
+                    .optional()
+                    .describe('Number of recent summary chunks to return (default 10, max 30).'),
+            }),
+            async handler(args, rtCtx) {
+                const roomId = requireRoomId(rtCtx);
+                const service = getService(rtCtx);
+                const parsed = z
+                    .object({ limit: z.number().int().min(1).max(30).optional() })
+                    .parse(args);
+                const cap = parsed.limit ?? 10;
+                const [chunks, facts, members] = await Promise.all([
+                    service.recentChunks(roomId, cap),
+                    service.listPinnedFacts(roomId),
+                    service.getMembers(roomId),
+                ]);
+                return {
+                    chunks: chunks.map(formatChunk),
+                    pinnedFacts: facts,
+                    members,
+                };
+            },
+        },
+        {
+            name: 'search_channel_memory',
+            description: 'Keyword-search the compacted summary chunks for the current group room. Use to find earlier discussions of a topic, decisions, names, dates. Returns matching chunks with their summaries.',
+            visibility: 'always',
+            schema: z.object({
+                query: z
+                    .string()
+                    .min(1)
+                    .describe('Keywords or phrase to search for in channel memory.'),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(30)
+                    .optional()
+                    .describe('Maximum matching chunks to return (default 10).'),
+            }),
+            async handler(args, rtCtx) {
+                const roomId = requireRoomId(rtCtx);
+                const service = getService(rtCtx);
+                const parsed = z
+                    .object({
+                    query: z.string().min(1),
+                    limit: z.number().int().min(1).max(30).optional(),
+                })
+                    .parse(args);
+                const cap = parsed.limit ?? 10;
+                const chunks = await service.search(roomId, parsed.query, cap);
+                if (chunks.length === 0) {
+                    return { chunks: [], note: 'No matching chunks.' };
+                }
+                return { chunks: chunks.map(formatChunk) };
+            },
+        },
+        {
+            name: 'pin_room_fact',
+            description: "Save a durable fact to the current group room's memory — survives across threads and sessions. Use for decisions, deadlines, member roles, project context. Surface in your reply so users know it has been saved.",
+            visibility: 'always',
+            schema: z.object({
+                fact: z
+                    .string()
+                    .min(3)
+                    .max(500)
+                    .describe('Concise factual statement to remember (max 500 chars).'),
+                sourceEventId: z
+                    .string()
+                    .optional()
+                    .describe('Optional Matrix event id this fact was derived from.'),
+            }),
+            async handler(args, rtCtx) {
+                const roomId = requireRoomId(rtCtx);
+                const service = getService(rtCtx);
+                const parsed = z
+                    .object({
+                    fact: z.string().min(3).max(500),
+                    sourceEventId: z.string().optional(),
+                })
+                    .parse(args);
+                const trimmed = parsed.fact.trim();
+                if (!trimmed) {
+                    throw new Error('Pinned fact must not be empty.');
+                }
+                const pinned = await service.pinFact({
+                    roomId,
+                    fact: trimmed.slice(0, 500),
+                    pinnedByDid: rtCtx.user.did,
+                    sourceEventId: parsed.sourceEventId,
+                });
+                return { factId: pinned.id, fact: pinned.fact };
+            },
+        },
+        {
+            name: 'unpin_room_fact',
+            description: "Remove a previously pinned fact from this group room's memory by its factId.",
+            visibility: 'always',
+            schema: z.object({
+                factId: z.string().min(1).describe('The id of the fact to remove.'),
+            }),
+            async handler(args, rtCtx) {
+                const roomId = requireRoomId(rtCtx);
+                const service = getService(rtCtx);
+                const parsed = z.object({ factId: z.string().min(1) }).parse(args);
+                const ok = await service.unpinFact(roomId, parsed.factId);
+                return { ok };
+            },
+        },
+    ];
+}

package/dist/plugins/memory/index.d.ts

@@ -0,0 +1,5 @@
+export { createDefaultMemoryMcpFactory, DEFAULT_MEMORY_TOOLS, fetchMemoryTools, MEMORY_ADD_MCP_NAME, MEMORY_ADD_ORACLE_KNOWLEDGE_MCP_NAME, MEMORY_CLEAR_MCP_NAME, MEMORY_DELETE_EDGE_MCP_NAME, MEMORY_DELETE_EPISODE_MCP_NAME, MEMORY_SEARCH_MCP_NAME, type MemoryMcpFactory, type UpstreamMcpTool, } from './memory-tools.js';
+export { buildMemoryHeaders } from './memory-ucan.js';
+export { MemoryPlugin, type MemoryPluginOptions } from './memory.plugin.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,oCAAoC,EACpC,qBAAqB,EACrB,2BAA2B,EAC3B,8BAA8B,EAC9B,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,mBAAmB,YAAY,CAAC"}

package/dist/plugins/memory/index.js

@@ -0,0 +1,3 @@
+export { createDefaultMemoryMcpFactory, DEFAULT_MEMORY_TOOLS, fetchMemoryTools, MEMORY_ADD_MCP_NAME, MEMORY_ADD_ORACLE_KNOWLEDGE_MCP_NAME, MEMORY_CLEAR_MCP_NAME, MEMORY_DELETE_EDGE_MCP_NAME, MEMORY_DELETE_EPISODE_MCP_NAME, MEMORY_SEARCH_MCP_NAME, } from './memory-tools.js';
+export { buildMemoryHeaders } from './memory-ucan.js';
+export { MemoryPlugin } from './memory.plugin.js';

package/dist/plugins/memory/memory-tools.d.ts

@@ -0,0 +1,52 @@
+import type { z } from 'zod';
+import type { PluginTool, RuntimeContext } from '../../plugin-api/types.js';
+/**
+ * Tool names the upstream Memory Engine MCP server exposes (prefixed with the
+ * server name configured in `MultiServerMCPClient`). The plugin surfaces these
+ * upstream tools as-is — name, description, and schema all come from the
+ * upstream server. Wrapping them locally with a different shape (as an earlier
+ * iteration did) caused upstream-side schema rejections at invoke time
+ * because the wrapper schema didn't match the server's contract.
+ */
+export declare const MEMORY_SEARCH_MCP_NAME = "memory-engine__search_memory_engine";
+export declare const MEMORY_ADD_MCP_NAME = "memory-engine__add_memory";
+export declare const MEMORY_ADD_ORACLE_KNOWLEDGE_MCP_NAME = "memory-engine__add_oracle_knowledge";
+export declare const MEMORY_DELETE_EPISODE_MCP_NAME = "memory-engine__delete_episode";
+export declare const MEMORY_DELETE_EDGE_MCP_NAME = "memory-engine__delete_edge";
+export declare const MEMORY_CLEAR_MCP_NAME = "memory-engine__clear";
+/**
+ * Default selection — mirrors the old `apps/app` Memory Agent default: search,
+ * add, and delete-episode. Forks that need org-owner knowledge writes or the
+ * destructive `clear` op pass an explicit list via plugin options.
+ */
+export declare const DEFAULT_MEMORY_TOOLS: readonly ["memory-engine__search_memory_engine", "memory-engine__add_memory", "memory-engine__delete_episode", "memory-engine__clear"];
+/**
+ * Minimal shape every upstream MCP tool exposes. `@langchain/mcp-adapters`
+ * returns `StructuredTool` instances whose runtime shape includes these
+ * fields. The plugin only depends on this slice; tests can satisfy it with a
+ * plain object.
+ */
+export interface UpstreamMcpTool {
+    name: string;
+    description: string;
+    schema: z.ZodType;
+    invoke: (input: unknown) => Promise<unknown>;
+}
+export type MemoryMcpFactory = (runCtx: RuntimeContext) => Promise<UpstreamMcpTool[] | null>;
+/**
+ * Default factory: opens an HTTP MCP client to `MEMORY_MCP_URL` with the
+ * per-request UCAN headers from {@link buildMemoryHeaders} and returns the
+ * upstream's tool list. A fresh client per request mirrors the old apps/app
+ * pattern and ensures each invocation runs against the authenticated user.
+ */
+export declare function createDefaultMemoryMcpFactory(memoryMcpUrl: string): MemoryMcpFactory;
+/**
+ * Fetch the upstream Memory Engine MCP tools for this request and return them
+ * as `PluginTool[]`. Filtered by `selectedTools` so forks can scope the
+ * surface (e.g. drop `clear`, add `add_oracle_knowledge` for org-owner mode).
+ *
+ * Returns `[]` when the factory cannot mint auth — the agent then sees no
+ * memory tools rather than getting a half-built request to upstream.
+ */
+export declare function fetchMemoryTools(runCtx: RuntimeContext, factory: MemoryMcpFactory, selectedTools?: readonly string[]): Promise<PluginTool[]>;
+//# sourceMappingURL=memory-tools.d.ts.map

package/dist/plugins/memory/memory-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-tools.d.ts","sourceRoot":"","sources":["../../../src/plugins/memory/memory-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG5E;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,wCAAwC,CAAC;AAC5E,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAC/D,eAAO,MAAM,oCAAoC,wCACV,CAAC;AACxC,eAAO,MAAM,8BAA8B,kCAAkC,CAAC;AAC9E,eAAO,MAAM,2BAA2B,+BAA+B,CAAC;AACxE,eAAO,MAAM,qBAAqB,yBAAyB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,wIAKvB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,MAAM,GACnB,gBAAgB,CAyBlB;AAiBD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,gBAAgB,EACzB,aAAa,GAAE,SAAS,MAAM,EAAyB,GACtD,OAAO,CAAC,UAAU,EAAE,CAAC,CAMvB"}

package/dist/plugins/memory/memory-tools.js

@@ -0,0 +1,88 @@
+import { MultiServerMCPClient } from '@langchain/mcp-adapters';
+import { buildMemoryHeaders } from './memory-ucan.js';
+/**
+ * Tool names the upstream Memory Engine MCP server exposes (prefixed with the
+ * server name configured in `MultiServerMCPClient`). The plugin surfaces these
+ * upstream tools as-is — name, description, and schema all come from the
+ * upstream server. Wrapping them locally with a different shape (as an earlier
+ * iteration did) caused upstream-side schema rejections at invoke time
+ * because the wrapper schema didn't match the server's contract.
+ */
+export const MEMORY_SEARCH_MCP_NAME = 'memory-engine__search_memory_engine';
+export const MEMORY_ADD_MCP_NAME = 'memory-engine__add_memory';
+export const MEMORY_ADD_ORACLE_KNOWLEDGE_MCP_NAME = 'memory-engine__add_oracle_knowledge';
+export const MEMORY_DELETE_EPISODE_MCP_NAME = 'memory-engine__delete_episode';
+export const MEMORY_DELETE_EDGE_MCP_NAME = 'memory-engine__delete_edge';
+export const MEMORY_CLEAR_MCP_NAME = 'memory-engine__clear';
+/**
+ * Default selection — mirrors the old `apps/app` Memory Agent default: search,
+ * add, and delete-episode. Forks that need org-owner knowledge writes or the
+ * destructive `clear` op pass an explicit list via plugin options.
+ */
+export const DEFAULT_MEMORY_TOOLS = [
+    MEMORY_SEARCH_MCP_NAME,
+    MEMORY_ADD_MCP_NAME,
+    MEMORY_DELETE_EPISODE_MCP_NAME,
+    MEMORY_CLEAR_MCP_NAME,
+];
+/**
+ * Default factory: opens an HTTP MCP client to `MEMORY_MCP_URL` with the
+ * per-request UCAN headers from {@link buildMemoryHeaders} and returns the
+ * upstream's tool list. A fresh client per request mirrors the old apps/app
+ * pattern and ensures each invocation runs against the authenticated user.
+ */
+export function createDefaultMemoryMcpFactory(memoryMcpUrl) {
+    return async (runCtx) => {
+        const headers = await buildMemoryHeaders(runCtx, memoryMcpUrl);
+        if (!headers)
+            return null;
+        const client = new MultiServerMCPClient({
+            useStandardContentBlocks: true,
+            prefixToolNameWithServerName: true,
+            mcpServers: {
+                'memory-engine': {
+                    type: 'http',
+                    transport: 'http',
+                    url: memoryMcpUrl,
+                    headers,
+                    reconnect: {
+                        enabled: true,
+                        maxAttempts: 3,
+                        delayMs: 2000,
+                    },
+                    defaultToolTimeout: 420_000,
+                },
+            },
+        });
+        return (await client.getTools());
+    };
+}
+/**
+ * Adapt one upstream MCP tool into a `PluginTool`. Name, description, and
+ * schema are taken VERBATIM from upstream — the agent sees the same contract
+ * the Memory Engine server publishes, and our handler is a thin passthrough
+ * to `mcpTool.invoke`.
+ */
+function adaptMcpTool(mcpTool) {
+    return {
+        name: mcpTool.name,
+        description: mcpTool.description,
+        schema: mcpTool.schema,
+        handler: async (args) => mcpTool.invoke(args),
+    };
+}
+/**
+ * Fetch the upstream Memory Engine MCP tools for this request and return them
+ * as `PluginTool[]`. Filtered by `selectedTools` so forks can scope the
+ * surface (e.g. drop `clear`, add `add_oracle_knowledge` for org-owner mode).
+ *
+ * Returns `[]` when the factory cannot mint auth — the agent then sees no
+ * memory tools rather than getting a half-built request to upstream.
+ */
+export async function fetchMemoryTools(runCtx, factory, selectedTools = DEFAULT_MEMORY_TOOLS) {
+    const mcpTools = await factory(runCtx);
+    if (!mcpTools)
+        return [];
+    const allow = new Set(selectedTools);
+    return mcpTools.filter((t) => allow.has(t.name)).map(adaptMcpTool);
+}

package/dist/plugins/memory/memory-ucan.d.ts

@@ -0,0 +1,17 @@
+import type { RuntimeContext } from '../../plugin-api/types.js';
+/**
+ * Build the headers needed to call the Memory Engine MCP server on behalf of
+ * the current user.
+ *
+ *   1. Resolve the memory service DID via `runCtx.ucan.resolveServiceDid`
+ *      (delegates the did:web lookup + cache to the Tier-0 UCAN service).
+ *   2. Mint an `ixo:memory` invocation using the user's signing key.
+ *   3. Layer the resulting Bearer token plus the active `x-room-id`.
+ *
+ * UCAN-only — no Matrix-OpenID fallback. If minting fails for any reason
+ * (no signing key, no cached delegation, did:web unresolved) the function
+ * returns `null` so callers can degrade silently rather than leak a
+ * half-built request to the upstream service.
+ */
+export declare function buildMemoryHeaders(runCtx: RuntimeContext, memoryMcpUrl: string): Promise<Record<string, string> | null>;
+//# sourceMappingURL=memory-ucan.d.ts.map

package/dist/plugins/memory/memory-ucan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-ucan.d.ts","sourceRoot":"","sources":["../../../src/plugins/memory/memory-ucan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CA4BxC"}