@elizaos/plugin-matrix 2.0.0-beta.1 → 2.0.3-beta.3

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

@@ -1,36 +1,15 @@
 # @elizaos/plugin-matrix
 
-Matrix messaging integration plugin for ElizaOS agents.
+Matrix messaging integration plugin for elizaOS agents.
 
 ## Features
 
-- **Decentralized Messaging**: Connect to any Matrix homeserver
-- **End-to-End Encryption**: Optional E2EE support for secure communications
-- **Room Support**: Join, leave, and manage Matrix rooms
-- **Reactions**: React to messages with emoji
-- **Threading**: Support for Matrix threads
-- **Direct Messages**: Handle DMs and group rooms
-- **Typing Indicators**: Send typing notifications
-- **Read Receipts**: Mark messages as read
-
-## Installation
-
-```bash
-npm install @elizaos/plugin-matrix
-```
-
-## Prerequisites
-
-1. **Matrix Account**: A Matrix account on any homeserver
-2. **Access Token**: Generate an access token for your account
-
-### Getting an Access Token
-
-You can get an access token by:
-
-1. **Element/Web Client**: Settings -> Help & About -> Access Token
-2. **API Login**: Use the Matrix login API with your password
-3. **Command Line**: Use `curl` or a tool like `matrix-commander`
+- 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
 
@@ -46,110 +25,58 @@ Set the following environment variables:
 
 ### Optional
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `MATRIX_DEVICE_ID` | Device ID for this session | Auto-generated |
-| `MATRIX_ROOMS` | Comma-separated room IDs/aliases to auto-join | - |
-| `MATRIX_AUTO_JOIN` | Auto-accept room invites | `false` |
-| `MATRIX_ENCRYPTION` | Enable E2EE support | `false` |
-| `MATRIX_REQUIRE_MENTION` | Only respond when mentioned in rooms | `false` |
+| 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
 
-### Basic Setup
-
 ```typescript
 import matrixPlugin from "@elizaos/plugin-matrix";
-
-const agent = new Agent({
-  plugins: [matrixPlugin],
-});
+// Pass to the plugin list when constructing an AgentRuntime or character config.
 ```
 
-### Actions
-
-Matrix messaging is exposed through the canonical message connector actions.
-Use `source: "matrix"` when a request needs to target Matrix explicitly.
-
-| Primary action | Operation | Description |
-|----------------|-----------|-------------|
-| `MESSAGE` | `send` | Send a message to a Matrix room, channel, thread, or DM |
-| `MESSAGE` | `react` | React to a Matrix message with an emoji |
-| `MESSAGE` | `list_channels` | List joined Matrix rooms |
-| `MESSAGE` | `join` | Join a Matrix room by ID or alias |
-| `MESSAGE` | `leave` | Leave a Matrix room |
+## Connector actions
 
-### Providers
+Matrix messaging is exposed through the canonical message connector. Use `source: "matrix"` when a request needs to target Matrix explicitly.
 
-#### matrixRoomState
+| 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 |
 
-Provides context about the current Matrix room:
-- Room ID and name
-- Member count
-- Encryption status
-- Whether it's a DM
+There are no registered `Provider` objects. Room context is surfaced through the connector's `getChatContext` and `listRooms` hooks.
 
-#### matrixUserContext
+## Events
 
-Provides context about the user in the conversation:
-- User ID
-- Display name
-- Avatar URL
+The service emits these events via `runtime.emitEvent`:
 
-### Events
+| 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 |
 
-The plugin emits the following events:
+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.
 
-| Event | Description |
-|-------|-------------|
-| `MATRIX_MESSAGE_RECEIVED` | A message was received |
-| `MATRIX_MESSAGE_SENT` | A message was sent |
-| `MATRIX_ROOM_JOINED` | Joined a room |
-| `MATRIX_ROOM_LEFT` | Left a room |
-| `MATRIX_INVITE_RECEIVED` | Received a room invite |
-| `MATRIX_REACTION_RECEIVED` | Received a reaction |
-| `MATRIX_SYNC_COMPLETE` | Initial sync completed |
-| `MATRIX_CONNECTION_READY` | Client connected |
-| `MATRIX_CONNECTION_LOST` | Connection lost |
+## Message limits
 
-## 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`.
 
-- Maximum message length: 4000 characters
-- Longer messages are split automatically
-
-## Matrix ID Formats
+## Matrix ID formats
 
 - **User ID**: `@localpart:homeserver.org`
 - **Room ID**: `!opaque_id:homeserver.org`
 - **Room Alias**: `#human_readable:homeserver.org`
-
-## Security Considerations
-
-1. **Token Security**: Never expose your access token
-2. **Homeserver Trust**: Only connect to trusted homeservers
-3. **E2EE**: Enable encryption for sensitive communications
-4. **Room Verification**: Verify room members when using E2EE
-
-## Troubleshooting
-
-### Connection Issues
-
-1. Verify your homeserver URL is correct
-2. Check that your access token is valid
-3. Ensure your homeserver is reachable
-
-### Sync Issues
-
-1. The initial sync may take time for accounts with many rooms
-2. Check homeserver rate limits
-3. Verify network connectivity
-
-### Encryption Issues
-
-1. Ensure E2EE is enabled on both ends
-2. Verify device is properly set up
-3. Check for key verification requirements
-
-## License
-
-MIT

package/package.json

@@ -1,17 +1,34 @@
 {
   "name": "@elizaos/plugin-matrix",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.3-beta.3",
   "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": [
+    "registry-entry.json",
     "dist",
     "auto-enable.ts"
   ],
@@ -30,14 +47,14 @@
     "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": "^41.4.0",
-    "zod": "^4.4.3"
+    "fake-indexeddb": "^6.2.5",
+    "matrix-js-sdk": "^41.4.0"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-beta.1"
+    "@elizaos/core": "2.0.3-beta.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
@@ -108,5 +125,6 @@
         "sensitive": false
       }
     }
-  }
+  },
+  "gitHead": "f54b0f4eaed317d59fa7dbcdce20f4cdb0734420"
 }

package/registry-entry.json

@@ -0,0 +1,95 @@
+{
+  "id": "matrix",
+  "name": "Matrix",
+  "description": "Matrix connector for rooms, bots, and federated chat workflows.",
+  "npmName": "@elizaos/plugin-matrix",
+  "version": "2.0.0-beta.0",
+  "source": "bundled",
+  "tags": ["connector", "messaging", "matrix", "chat", "social", "social-chat"],
+  "config": {
+    "MATRIX_ROOMS": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Rooms",
+      "help": "Comma-separated room/channel list",
+      "advanced": false
+    },
+    "MATRIX_USER_ID": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "User Id",
+      "help": "User identifier",
+      "advanced": false
+    },
+    "MATRIX_AUTO_JOIN": {
+      "type": "boolean",
+      "required": false,
+      "sensitive": false,
+      "label": "Auto Join",
+      "help": "Automatically join/discover channels",
+      "advanced": false
+    },
+    "MATRIX_DEVICE_ID": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Device Id",
+      "help": "Device identifier",
+      "advanced": false
+    },
+    "MATRIX_ENCRYPTION": {
+      "type": "boolean",
+      "required": false,
+      "sensitive": false,
+      "label": "Encryption",
+      "help": "Enable encryption",
+      "advanced": false
+    },
+    "MATRIX_HOMESERVER": {
+      "type": "string",
+      "required": false,
+      "sensitive": false,
+      "label": "Homeserver",
+      "help": "Homeserver URL",
+      "advanced": false
+    },
+    "MATRIX_ACCESS_TOKEN": {
+      "type": "secret",
+      "required": true,
+      "sensitive": true,
+      "label": "Access Token",
+      "help": "Access token for Matrix",
+      "advanced": false
+    },
+    "MATRIX_REQUIRE_MENTION": {
+      "type": "boolean",
+      "required": false,
+      "sensitive": false,
+      "label": "Require Mention",
+      "help": "Only respond when mentioned",
+      "advanced": false
+    }
+  },
+  "render": {
+    "visible": false,
+    "pinTo": [],
+    "style": "setup-panel",
+    "icon": "Link",
+    "group": "connector",
+    "groupOrder": 1,
+    "actions": ["enable", "configure", "setup-guide"]
+  },
+  "resources": {
+    "setupGuideUrl": "https://docs.eliza.ai/plugin-setup-guide#matrix"
+  },
+  "dependsOn": [],
+  "kind": "connector",
+  "subtype": "messaging",
+  "auth": {
+    "kind": "token",
+    "credentialKeys": ["MATRIX_ACCESS_TOKEN"]
+  },
+  "channels": ["matrix"]
+}

package/dist/accounts.d.ts

@@ -1,14 +0,0 @@
-import type { IAgentRuntime } from "@elizaos/core";
-import type { MatrixSettings } from "./types.js";
-export declare const DEFAULT_MATRIX_ACCOUNT_ID = "default";
-export type MatrixAccountConfig = Partial<Omit<MatrixSettings, "rooms" | "accountId">> & {
-    accountId?: string;
-    id?: string;
-    rooms?: string[] | string;
-};
-export declare function normalizeMatrixAccountId(accountId?: unknown): string;
-export declare function listMatrixAccountIds(runtime: IAgentRuntime): string[];
-export declare function resolveDefaultMatrixAccountId(runtime: IAgentRuntime): string;
-export declare function readMatrixAccountId(...sources: unknown[]): string | undefined;
-export declare function resolveMatrixAccountSettings(runtime: IAgentRuntime, requestedAccountId?: string | null): MatrixSettings;
-//# sourceMappingURL=accounts.d.ts.map

package/dist/accounts.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../src/accounts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,CAAC,CAAC,GAAG;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CAC3B,CAAC;AAqEF,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAIpE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,EAAE,CAkBrE;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAQ5E;AAED,wBAAgB,mBAAmB,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,GAAG,SAAS,CA6B7E;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,aAAa,EACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,GACjC,cAAc,CAiDhB"}

package/dist/connector-account-provider.d.ts

@@ -1,18 +0,0 @@
-/**
- * Matrix ConnectorAccountManager provider.
- *
- * Adapts the multi-account scaffolding in `accounts.ts` to the
- * `ConnectorAccountProvider` contract from
- * `@elizaos/core/connectors/account-manager`.
- *
- * Source of truth for accounts is character settings (`character.settings.matrix`)
- * + MATRIX_ACCOUNTS JSON env var + single-account env vars (MATRIX_HOMESERVER,
- * MATRIX_USER_ID, MATRIX_ACCESS_TOKEN). AccountKey is `<homeserver>/<userId>`
- * by convention; role is `OWNER` since matrix access tokens authenticate the
- * user, not a bot. E2EE keys are scoped per account by the matrix client and
- * are NOT shared between accounts.
- */
-import type { ConnectorAccountProvider, IAgentRuntime } from "@elizaos/core";
-export declare const MATRIX_PROVIDER_ID = "matrix";
-export declare function createMatrixConnectorAccountProvider(runtime: IAgentRuntime): ConnectorAccountProvider;
-//# sourceMappingURL=connector-account-provider.d.ts.map

package/dist/connector-account-provider.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"connector-account-provider.d.ts","sourceRoot":"","sources":["../src/connector-account-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAIV,wBAAwB,EACxB,aAAa,EACd,MAAM,eAAe,CAAC;AASvB,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAmC3C,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,aAAa,GACrB,wBAAwB,CAmC1B"}

package/dist/index.d.ts

@@ -1,15 +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 * from "./accounts.js";
-export { MatrixService } from "./service.js";
-export * from "./types.js";
-/**
- * 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;AAG3D,cAAc,eAAe,CAAC;AAE9B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,cAAc,YAAY,CAAC;AAO3B;;GAEG;AACH,QAAA,MAAM,YAAY,EAAE,MAmFnB,CAAC;AAEF,eAAe,YAAY,CAAC"}