@elizaos/plugin-matrix 2.0.0-alpha.8 → 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @elizaos/plugin-matrix
+
+Matrix messaging integration plugin for elizaOS agents.
+
+## Features
+
+- Connect to any Matrix homeserver via `matrix-js-sdk`
+- Receive and send messages in Matrix rooms
+- Room membership: join, leave, auto-join on invite
+- Reactions, threading, typing indicators, read receipts
+- Optional E2EE support
+- Multi-account configuration
+
+## Configuration
+
+Set the following environment variables:
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `MATRIX_HOMESERVER` | Homeserver URL (e.g., https://matrix.org) |
+| `MATRIX_USER_ID` | Full Matrix user ID (@user:homeserver.org) |
+| `MATRIX_ACCESS_TOKEN` | Access token for authentication |
+
+### Optional
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MATRIX_DEVICE_ID` | Auto-generated | Device ID for this session |
+| `MATRIX_ROOMS` | — | Comma-separated room IDs/aliases to auto-join |
+| `MATRIX_AUTO_JOIN` | `false` | Auto-accept room invites |
+| `MATRIX_ENCRYPTION` | `false` | Enable E2EE support |
+| `MATRIX_REQUIRE_MENTION` | `false` | Only respond when mentioned in rooms |
+| `MATRIX_ACCOUNTS` | — | JSON array/object of per-account configs for multi-account setups |
+| `MATRIX_DEFAULT_ACCOUNT_ID` | — | Which account is the default when multiple are configured |
+| `MATRIX_ACCOUNT_ID` | — | Alias for `MATRIX_DEFAULT_ACCOUNT_ID` |
+
+## Usage
+
+```typescript
+import matrixPlugin from "@elizaos/plugin-matrix";
+// Pass to the plugin list when constructing an AgentRuntime or character config.
+```
+
+## Connector actions
+
+Matrix messaging is exposed through the canonical message connector. Use `source: "matrix"` when a request needs to target Matrix explicitly.
+
+| Operation | Description |
+|-----------|-------------|
+| `send` | Send a message to a Matrix room, channel, thread, or DM |
+| `react` | React to a Matrix message with an emoji |
+| `list_channels` | List joined Matrix rooms |
+| `join` | Join a Matrix room by ID or alias |
+| `leave` | Leave a Matrix room |
+
+There are no registered `Provider` objects. Room context is surfaced through the connector's `getChatContext` and `listRooms` hooks.
+
+## Events
+
+The service emits these events via `runtime.emitEvent`:
+
+| Event | Trigger |
+|-------|---------|
+| `MATRIX_MESSAGE_RECEIVED` | Incoming `m.room.message` (text only; filtered by `requireMention` if set) |
+| `MATRIX_MESSAGE_SENT` | Message sent via `sendMessage` |
+| `MATRIX_ROOM_JOINED` | `joinRoom` succeeds |
+| `MATRIX_ROOM_LEFT` | `leaveRoom` succeeds |
+| `MATRIX_SYNC_COMPLETE` | Matrix `PREPARED` sync state |
+
+Additional constants (`MATRIX_INVITE_RECEIVED`, `MATRIX_REACTION_RECEIVED`, `MATRIX_TYPING_RECEIVED`, `MATRIX_CONNECTION_READY`, `MATRIX_CONNECTION_LOST`) are defined in `MatrixEventTypes` but not currently emitted by the service.
+
+## Message limits
+
+Maximum message length: `MAX_MATRIX_MESSAGE_LENGTH = 4000` characters (exported from `src/types.ts`). The service does not auto-split; callers must chunk before calling `sendMessage`.
+
+## Matrix ID formats
+
+- **User ID**: `@localpart:homeserver.org`
+- **Room ID**: `!opaque_id:homeserver.org`
+- **Room Alias**: `#human_readable:homeserver.org`

package/auto-enable.ts

@@ -0,0 +1,20 @@
+// Auto-enable check for @elizaos/plugin-matrix.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+/** Enable when a `matrix` connector block is present and not explicitly disabled. */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  const c = (ctx.config?.connectors as Record<string, unknown> | undefined)?.matrix;
+  if (!c || typeof c !== "object") return false;
+  const config = c as Record<string, unknown>;
+  if (config.enabled === false) return false;
+  // The full per-connector field check (homeserver/accessToken/userId) lives
+  // in the central engine's isConnectorConfigured. We delegate to a simple
+  // "block present + not explicitly disabled" check here; the central
+  // engine's stricter check remains as a fallback during migration.
+  return true;
+}

package/package.json

@@ -1,42 +1,67 @@
 {
   "name": "@elizaos/plugin-matrix",
-  "version": "2.0.0-alpha.8",
+  "version": "2.0.11-beta.7",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "auto-enable.ts"
   ],
+  "elizaos": {
+    "plugin": {
+      "autoEnableModule": "./auto-enable.ts",
+      "capabilities": [
+        "messaging"
+      ]
+    }
+  },
   "scripts": {
     "build": "bun run build.ts",
-    "test": "vitest run --config vitest.config.ts --passWithNoTests",
+    "test": "vitest run --config vitest.config.ts",
     "lint": "bunx @biomejs/biome check --write --unsafe .",
     "lint:check": "bunx @biomejs/biome check .",
     "format": "bunx @biomejs/biome format --write .",
     "format:check": "bunx @biomejs/biome format .",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "matrix-js-sdk": "^31.0.0",
-    "zod": "^4.3.6"
+    "fake-indexeddb": "^6.2.5",
+    "matrix-js-sdk": "^41.4.0"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-alpha.3"
+    "@elizaos/core": "2.0.11-beta.7"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
     "@types/bun": "^1.1.0",
-    "typescript": "^5.3.0",
-    "@biomejs/biome": "^2.3.11",
-    "vitest": "^3.2.4"
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
   },
-  "milady": {
+  "eliza": {
     "platforms": [
       "node"
     ],
@@ -99,5 +124,6 @@
         "sensitive": false
       }
     }
-  }
+  },
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
 }

package/dist/actions/joinRoom.d.ts

@@ -1,6 +0,0 @@
-/**
- * Join room action for Matrix plugin.
- */
-import type { Action } from "@elizaos/core";
-export declare const joinRoom: Action;
-//# sourceMappingURL=joinRoom.d.ts.map

package/dist/actions/joinRoom.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"joinRoom.d.ts","sourceRoot":"","sources":["../../src/actions/joinRoom.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,MAAM,EAOP,MAAM,eAAe,CAAC;AA2BvB,eAAO,MAAM,QAAQ,EAAE,MA4GtB,CAAC"}

package/dist/actions/listRooms.d.ts

@@ -1,6 +0,0 @@
-/**
- * List rooms action for Matrix plugin.
- */
-import type { Action } from "@elizaos/core";
-export declare const listRooms: Action;
-//# sourceMappingURL=listRooms.d.ts.map

package/dist/actions/listRooms.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"listRooms.d.ts","sourceRoot":"","sources":["../../src/actions/listRooms.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,MAAM,EAOP,MAAM,eAAe,CAAC;AAIvB,eAAO,MAAM,SAAS,EAAE,MA6EvB,CAAC"}

package/dist/actions/sendMessage.d.ts

@@ -1,6 +0,0 @@
-/**
- * Send message action for Matrix plugin.
- */
-import type { Action } from "@elizaos/core";
-export declare const sendMessage: Action;
-//# sourceMappingURL=sendMessage.d.ts.map

package/dist/actions/sendMessage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sendMessage.d.ts","sourceRoot":"","sources":["../../src/actions/sendMessage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,MAAM,EAOP,MAAM,eAAe,CAAC;AA6BvB,eAAO,MAAM,WAAW,EAAE,MAqIzB,CAAC"}

package/dist/actions/sendReaction.d.ts

@@ -1,6 +0,0 @@
-/**
- * Send reaction action for Matrix plugin.
- */
-import type { Action } from "@elizaos/core";
-export declare const sendReaction: Action;
-//# sourceMappingURL=sendReaction.d.ts.map

package/dist/actions/sendReaction.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sendReaction.d.ts","sourceRoot":"","sources":["../../src/actions/sendReaction.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,MAAM,EAOP,MAAM,eAAe,CAAC;AAwBvB,eAAO,MAAM,YAAY,EAAE,MA6H1B,CAAC"}

package/dist/index.d.ts

@@ -1,22 +0,0 @@
-/**
- * Matrix messaging integration plugin for ElizaOS.
- *
- * This plugin provides Matrix protocol integration using matrix-js-sdk.
- */
-import type { Plugin } from "@elizaos/core";
-export { MatrixService } from "./service.js";
-export * from "./types.js";
-import { joinRoom } from "./actions/joinRoom.js";
-import { listRooms } from "./actions/listRooms.js";
-import { sendMessage } from "./actions/sendMessage.js";
-import { sendReaction } from "./actions/sendReaction.js";
-export { sendMessage, sendReaction, listRooms, joinRoom };
-import { roomStateProvider } from "./providers/roomState.js";
-import { userContextProvider } from "./providers/userContext.js";
-export { roomStateProvider, userContextProvider };
-/**
- * Matrix plugin definition.
- */
-declare const matrixPlugin: Plugin;
-export default matrixPlugin;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAiB,MAAM,EAAE,MAAM,eAAe,CAAC;AAI3D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,cAAc,YAAY,CAAC;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAC;AAKlD;;GAEG;AACH,QAAA,MAAM,YAAY,EAAE,MA8DnB,CAAC;AAEF,eAAe,YAAY,CAAC"}