@elizaos/plugin-matrix 2.0.0-alpha.3

package/src/actions/joinRoom.ts

@@ -0,0 +1,147 @@
+/**
+ * Join room action for Matrix plugin.
+ */
+
+import type { Action, ActionResult, HandlerCallback, HandlerOptions, IAgentRuntime, Memory, State } from "@elizaos/core";
+import { composePromptFromState, ModelType, parseJSONObjectFromText } from "@elizaos/core";
+import { MatrixService } from "../service.js";
+import { MATRIX_SERVICE_NAME, isValidMatrixRoomId, isValidMatrixRoomAlias } from "../types.js";
+
+const JOIN_ROOM_TEMPLATE = `You are helping to extract a Matrix room identifier.
+
+The user wants to join a Matrix room.
+
+Recent conversation:
+{{recentMessages}}
+
+Extract the room ID (!room:server) or room alias (#alias:server) to join.
+
+Respond with a JSON object like:
+{
+  "room": "!room:matrix.org"
+}
+
+or:
+
+{
+  "room": "#alias:matrix.org"
+}
+
+Only respond with the JSON object, no other text.`;
+
+export const joinRoom: Action = {
+  name: "MATRIX_JOIN_ROOM",
+  similes: [
+    "JOIN_MATRIX_ROOM",
+    "ENTER_ROOM",
+  ],
+  description: "Join a Matrix room by ID or alias",
+
+  validate: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State
+  ): Promise<boolean> => {
+    return message.content.source === "matrix";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state?: State,
+    _options?: HandlerOptions,
+    callback?: HandlerCallback
+  ): Promise<ActionResult | undefined> => {
+    const matrixService = runtime.getService(MATRIX_SERVICE_NAME) as MatrixService | undefined;
+
+    if (!matrixService || !matrixService.isConnected()) {
+      if (callback) {
+        await callback({ text: "Matrix service is not available.", source: "matrix" });
+      }
+      return { success: false, error: "Matrix service not available" };
+    }
+
+    // Compose prompt - ensure state has required properties
+    const composedState: State = state ?? {
+      values: {},
+      data: {},
+      text: "",
+    };
+    const prompt = await composePromptFromState({
+      template: JOIN_ROOM_TEMPLATE,
+      state: composedState,
+    });
+
+    // Extract room using LLM
+    let room: string | null = null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+        prompt,
+      });
+
+      const parsed = parseJSONObjectFromText(response as string);
+      if (parsed?.room) {
+        const roomStr = String(parsed.room).trim();
+        if (isValidMatrixRoomId(roomStr) || isValidMatrixRoomAlias(roomStr)) {
+          room = roomStr;
+          break;
+        }
+      }
+    }
+
+    if (!room) {
+      if (callback) {
+        await callback({
+          text: "I couldn't understand which room you want me to join. Please specify a room ID (!room:server) or alias (#alias:server).",
+          source: "matrix",
+        });
+      }
+      return { success: false, error: "Could not extract room identifier" };
+    }
+
+    // Join room
+    try {
+      const roomId = await matrixService.joinRoom(room);
+
+      if (callback) {
+        await callback({
+          text: `Joined room ${room}.`,
+          source: message.content.source as string,
+        });
+      }
+
+      return {
+        success: true,
+        data: {
+          roomId,
+          joined: room,
+        },
+      };
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      if (callback) {
+        await callback({
+          text: `Failed to join room: ${error}`,
+          source: "matrix",
+        });
+      }
+      return { success: false, error };
+    }
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Join #general:matrix.org" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll join that room.",
+          actions: ["MATRIX_JOIN_ROOM"],
+        },
+      },
+    ],
+  ],
+};

package/src/actions/listRooms.ts

@@ -0,0 +1,95 @@
+/**
+ * List rooms action for Matrix plugin.
+ */
+
+import type { Action, ActionResult, HandlerCallback, HandlerOptions, IAgentRuntime, Memory, State } from "@elizaos/core";
+import { MatrixService } from "../service.js";
+import { MATRIX_SERVICE_NAME } from "../types.js";
+
+export const listRooms: Action = {
+  name: "MATRIX_LIST_ROOMS",
+  similes: [
+    "LIST_MATRIX_ROOMS",
+    "SHOW_ROOMS",
+    "GET_ROOMS",
+    "MY_ROOMS",
+  ],
+  description: "List all Matrix rooms the bot has joined",
+
+  validate: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State
+  ): Promise<boolean> => {
+    return message.content.source === "matrix";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+    _options?: HandlerOptions,
+    callback?: HandlerCallback
+  ): Promise<ActionResult | undefined> => {
+    const matrixService = runtime.getService(MATRIX_SERVICE_NAME) as MatrixService | undefined;
+
+    if (!matrixService || !matrixService.isConnected()) {
+      if (callback) {
+        await callback({ text: "Matrix service is not available.", source: "matrix" });
+      }
+      return { success: false, error: "Matrix service not available" };
+    }
+
+    const rooms = await matrixService.getJoinedRooms();
+
+    // Format room list
+    const roomList = rooms.map((room) => {
+      const name = room.name || room.canonicalAlias || room.roomId;
+      const members = `${room.memberCount} members`;
+      const encrypted = room.isEncrypted ? " (encrypted)" : "";
+      return `- ${name} (${members})${encrypted}`;
+    });
+
+    const responseText =
+      rooms.length > 0
+        ? `Joined ${rooms.length} room(s):\n\n${roomList.join("\n")}`
+        : "Not currently in any rooms.";
+
+    if (callback) {
+      await callback({
+        text: responseText,
+        source: message.content.source as string,
+      });
+    }
+
+    return {
+      success: true,
+      data: {
+        roomCount: rooms.length,
+        rooms: rooms.map((r) => ({
+          roomId: r.roomId,
+          name: r.name,
+          alias: r.canonicalAlias,
+          memberCount: r.memberCount,
+          isEncrypted: r.isEncrypted,
+        })),
+      },
+    };
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "What rooms are you in?" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll list the rooms I've joined.",
+          actions: ["MATRIX_LIST_ROOMS"],
+        },
+      },
+    ],
+  ],
+};

package/src/actions/sendMessage.ts

@@ -0,0 +1,175 @@
+/**
+ * Send message action for Matrix plugin.
+ */
+
+import type { Action, ActionResult, HandlerCallback, HandlerOptions, IAgentRuntime, Memory, State } from "@elizaos/core";
+import { composePromptFromState, ModelType, parseJSONObjectFromText } from "@elizaos/core";
+import { MatrixService } from "../service.js";
+import { MATRIX_SERVICE_NAME, isValidMatrixRoomId, isValidMatrixRoomAlias } from "../types.js";
+
+const SEND_MESSAGE_TEMPLATE = `You are helping to extract send message parameters for Matrix.
+
+The user wants to send a message to a Matrix room.
+
+Recent conversation:
+{{recentMessages}}
+
+Extract the following:
+1. text: The message text to send
+2. roomId: The room ID (!room:server) or alias (#alias:server), or "current" for the current room
+
+Respond with a JSON object like:
+{
+  "text": "The message to send",
+  "roomId": "current"
+}
+
+Only respond with the JSON object, no other text.`;
+
+interface SendMessageParams {
+  text: string;
+  roomId: string;
+}
+
+export const sendMessage: Action = {
+  name: "MATRIX_SEND_MESSAGE",
+  similes: [
+    "SEND_MATRIX_MESSAGE",
+    "MESSAGE_MATRIX",
+    "MATRIX_TEXT",
+  ],
+  description: "Send a message to a Matrix room",
+
+  validate: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State
+  ): Promise<boolean> => {
+    return message.content.source === "matrix";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state?: State,
+    _options?: HandlerOptions,
+    callback?: HandlerCallback
+  ): Promise<ActionResult | undefined> => {
+    const matrixService = runtime.getService(MATRIX_SERVICE_NAME) as MatrixService | undefined;
+
+    if (!matrixService || !matrixService.isConnected()) {
+      if (callback) {
+        await callback({ text: "Matrix service is not available.", source: "matrix" });
+      }
+      return { success: false, error: "Matrix service not available" };
+    }
+
+    // Compose prompt - ensure state has required properties
+    const composedState: State = state ?? {
+      values: {},
+      data: {},
+      text: "",
+    };
+    const prompt = await composePromptFromState({
+      template: SEND_MESSAGE_TEMPLATE,
+      state: composedState,
+    });
+
+    // Extract parameters using LLM
+    let messageInfo: SendMessageParams | null = null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+        prompt,
+      });
+
+      const parsed = parseJSONObjectFromText(response as string);
+      if (parsed?.text) {
+        messageInfo = {
+          text: String(parsed.text),
+          roomId: String(parsed.roomId || "current"),
+        };
+        break;
+      }
+    }
+
+    if (!messageInfo || !messageInfo.text) {
+      if (callback) {
+        await callback({
+          text: "I couldn't understand what message you want me to send. Please try again.",
+          source: "matrix",
+        });
+      }
+      return { success: false, error: "Could not extract message parameters" };
+    }
+
+    // Determine target room
+    let targetRoomId: string | undefined;
+    if (messageInfo.roomId && messageInfo.roomId !== "current") {
+      if (isValidMatrixRoomId(messageInfo.roomId) || isValidMatrixRoomAlias(messageInfo.roomId)) {
+        targetRoomId = messageInfo.roomId;
+      }
+    }
+
+    // Get room from state context if available
+    const roomData = state?.data?.room as Record<string, string> | undefined;
+    if (!targetRoomId && roomData?.roomId) {
+      targetRoomId = roomData.roomId;
+    }
+
+    if (!targetRoomId) {
+      if (callback) {
+        await callback({
+          text: "I couldn't determine which room to send to. Please specify a room.",
+          source: "matrix",
+        });
+      }
+      return { success: false, error: "Could not determine target room" };
+    }
+
+    // Send message
+    const result = await matrixService.sendMessage(messageInfo.text, {
+      roomId: targetRoomId,
+    });
+
+    if (!result.success) {
+      if (callback) {
+        await callback({
+          text: `Failed to send message: ${result.error}`,
+          source: "matrix",
+        });
+      }
+      return { success: false, error: result.error };
+    }
+
+    if (callback) {
+      await callback({
+        text: "Message sent successfully.",
+        source: message.content.source as string,
+      });
+    }
+
+    return {
+      success: true,
+      data: {
+        roomId: result.roomId,
+        eventId: result.eventId,
+      },
+    };
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Send a message saying 'Hello everyone!'" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll send that message to the room.",
+          actions: ["MATRIX_SEND_MESSAGE"],
+        },
+      },
+    ],
+  ],
+};

package/src/actions/sendReaction.ts

@@ -0,0 +1,162 @@
+/**
+ * Send reaction action for Matrix plugin.
+ */
+
+import type { Action, ActionResult, HandlerCallback, HandlerOptions, IAgentRuntime, Memory, State } from "@elizaos/core";
+import { composePromptFromState, ModelType, parseJSONObjectFromText } from "@elizaos/core";
+import { MatrixService } from "../service.js";
+import { MATRIX_SERVICE_NAME } from "../types.js";
+
+const SEND_REACTION_TEMPLATE = `You are helping to extract reaction parameters for Matrix.
+
+The user wants to react to a Matrix message with an emoji.
+
+Recent conversation:
+{{recentMessages}}
+
+Extract the following:
+1. emoji: The emoji to react with (single emoji character)
+2. eventId: The event ID of the message to react to (starts with $)
+
+Respond with a JSON object like:
+{
+  "emoji": "👍",
+  "eventId": "$event123"
+}
+
+Only respond with the JSON object, no other text.`;
+
+export const sendReaction: Action = {
+  name: "MATRIX_SEND_REACTION",
+  similes: [
+    "REACT_MATRIX",
+    "MATRIX_REACT",
+    "ADD_MATRIX_REACTION",
+  ],
+  description: "React to a Matrix message with an emoji",
+
+  validate: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State
+  ): Promise<boolean> => {
+    return message.content.source === "matrix";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state?: State,
+    _options?: HandlerOptions,
+    callback?: HandlerCallback
+  ): Promise<ActionResult | undefined> => {
+    const matrixService = runtime.getService(MATRIX_SERVICE_NAME) as MatrixService | undefined;
+
+    if (!matrixService || !matrixService.isConnected()) {
+      if (callback) {
+        await callback({ text: "Matrix service is not available.", source: "matrix" });
+      }
+      return { success: false, error: "Matrix service not available" };
+    }
+
+    // Compose prompt - ensure state has required properties
+    const composedState: State = state ?? {
+      values: {},
+      data: {},
+      text: "",
+    };
+    const prompt = await composePromptFromState({
+      template: SEND_REACTION_TEMPLATE,
+      state: composedState,
+    });
+
+    // Extract parameters using LLM
+    let reactionInfo: { emoji: string; eventId: string } | null = null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+        prompt,
+      });
+
+      const parsed = parseJSONObjectFromText(response as string);
+      if (parsed?.emoji && parsed?.eventId) {
+        reactionInfo = {
+          emoji: String(parsed.emoji),
+          eventId: String(parsed.eventId),
+        };
+        break;
+      }
+    }
+
+    if (!reactionInfo) {
+      if (callback) {
+        await callback({
+          text: "I couldn't understand the reaction request. Please specify the emoji and message.",
+          source: "matrix",
+        });
+      }
+      return { success: false, error: "Could not extract reaction parameters" };
+    }
+
+    // Get room from state
+    const roomData = state?.data?.room as Record<string, string> | undefined;
+    const roomId = roomData?.roomId;
+    if (!roomId) {
+      if (callback) {
+        await callback({
+          text: "I couldn't determine which room this is in.",
+          source: "matrix",
+        });
+      }
+      return { success: false, error: "Could not determine room" };
+    }
+
+    // Send reaction
+    const result = await matrixService.sendReaction(
+      roomId,
+      reactionInfo.eventId,
+      reactionInfo.emoji
+    );
+
+    if (!result.success) {
+      if (callback) {
+        await callback({
+          text: `Failed to add reaction: ${result.error}`,
+          source: "matrix",
+        });
+      }
+      return { success: false, error: result.error };
+    }
+
+    if (callback) {
+      await callback({
+        text: `Added ${reactionInfo.emoji} reaction.`,
+        source: message.content.source as string,
+      });
+    }
+
+    return {
+      success: true,
+      data: {
+        emoji: reactionInfo.emoji,
+        eventId: reactionInfo.eventId,
+        roomId,
+      },
+    };
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "React to the last message with a thumbs up" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll add a thumbs up reaction.",
+          actions: ["MATRIX_SEND_REACTION"],
+        },
+      },
+    ],
+  ],
+};

package/src/index.ts

@@ -0,0 +1,105 @@
+/**
+ * Matrix messaging integration plugin for ElizaOS.
+ *
+ * This plugin provides Matrix protocol integration using matrix-js-sdk.
+ */
+
+import type { Plugin, IAgentRuntime } from "@elizaos/core";
+import { logger } from "@elizaos/core";
+
+// Service
+export { MatrixService } from "./service.js";
+
+// Types
+export * from "./types.js";
+
+// Actions
+import { sendMessage } from "./actions/sendMessage.js";
+import { sendReaction } from "./actions/sendReaction.js";
+import { listRooms } from "./actions/listRooms.js";
+import { joinRoom } from "./actions/joinRoom.js";
+
+export { sendMessage, sendReaction, listRooms, joinRoom };
+
+// Providers
+import { roomStateProvider } from "./providers/roomState.js";
+import { userContextProvider } from "./providers/userContext.js";
+
+export { roomStateProvider, userContextProvider };
+
+// Import service for plugin
+import { MatrixService } from "./service.js";
+
+/**
+ * Matrix plugin definition.
+ */
+const matrixPlugin: Plugin = {
+  name: "matrix",
+  description: "Matrix messaging integration plugin for ElizaOS with E2EE support",
+
+  services: [MatrixService],
+
+  actions: [sendMessage, sendReaction, listRooms, joinRoom],
+
+  providers: [roomStateProvider, userContextProvider],
+
+  tests: [],
+
+  init: async (
+    _config: Record<string, string>,
+    runtime: IAgentRuntime
+  ): Promise<void> => {
+    const homeserver = runtime.getSetting("MATRIX_HOMESERVER");
+    const userId = runtime.getSetting("MATRIX_USER_ID");
+    const accessToken = runtime.getSetting("MATRIX_ACCESS_TOKEN");
+
+    logger.info("=".repeat(60));
+    logger.info("Matrix Plugin Configuration");
+    logger.info("=".repeat(60));
+    logger.info(`  Homeserver: ${homeserver ? `✓ ${homeserver}` : "✗ Missing (required)"}`);
+    logger.info(`  User ID: ${userId ? `✓ ${userId}` : "✗ Missing (required)"}`);
+    logger.info(`  Access Token: ${accessToken ? "✓ Set" : "✗ Missing (required)"}`);
+    logger.info("=".repeat(60));
+
+    // Validate required settings
+    const missing: string[] = [];
+    if (!homeserver) missing.push("MATRIX_HOMESERVER");
+    if (!userId) missing.push("MATRIX_USER_ID");
+    if (!accessToken) missing.push("MATRIX_ACCESS_TOKEN");
+
+    if (missing.length > 0) {
+      logger.warn(
+        `Matrix plugin: Missing required configuration: ${missing.join(", ")}`
+      );
+    }
+
+    // Additional optional settings
+    const deviceId = runtime.getSetting("MATRIX_DEVICE_ID");
+    const rooms = runtime.getSetting("MATRIX_ROOMS");
+    const autoJoin = runtime.getSetting("MATRIX_AUTO_JOIN");
+    const encryption = runtime.getSetting("MATRIX_ENCRYPTION");
+    const requireMention = runtime.getSetting("MATRIX_REQUIRE_MENTION");
+
+    if (deviceId) {
+      logger.info(`  Device ID: ${deviceId}`);
+    }
+
+    if (rooms) {
+      logger.info(`  Auto-join Rooms: ${rooms}`);
+    }
+
+    if (autoJoin === "true") {
+      logger.info("  Auto-join Invites: ✓ Enabled");
+    }
+
+    if (encryption === "true") {
+      logger.info("  End-to-End Encryption: ✓ Enabled");
+    }
+
+    if (requireMention === "true") {
+      logger.info("  Require Mention: ✓ Enabled (will only respond to mentions in rooms)");
+    }
+  },
+};
+
+export default matrixPlugin;