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

package/README.md

@@ -0,0 +1,155 @@
+# @elizaos/plugin-matrix
+
+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`
+
+## 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 | 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` |
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import matrixPlugin from "@elizaos/plugin-matrix";
+
+const agent = new Agent({
+  plugins: [matrixPlugin],
+});
+```
+
+### 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 |
+
+### Providers
+
+#### matrixRoomState
+
+Provides context about the current Matrix room:
+- Room ID and name
+- Member count
+- Encryption status
+- Whether it's a DM
+
+#### matrixUserContext
+
+Provides context about the user in the conversation:
+- User ID
+- Display name
+- Avatar URL
+
+### Events
+
+The plugin emits the following events:
+
+| 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
+
+- Maximum message length: 4000 characters
+- Longer messages are split automatically
+
+## 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/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/dist/accounts.d.ts

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,18 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -4,16 +4,9 @@
  * 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";
-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.
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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"}