@elizaos/plugin-discord 1.3.7 → 2.0.0-alpha.1

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@elizaos/plugin-discord",
-  "version": "1.3.7",
+  "version": "2.0.0-alpha.1",
+  "description": "",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "sideEffects": false,
   "repository": {
     "type": "git",
     "url": "git+https://github.com/elizaos-plugins/plugin-discord.git"
@@ -12,20 +14,34 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "dist"
   ],
+  "keywords": [],
+  "author": "elizaOS",
+  "license": "MIT",
+  "scripts": {
+    "build": "bun run build.ts",
+    "build:ts": "bun run build.ts",
+    "dev": "bun --hot build.ts",
+    "clean": "rm -rf dist .turbo node_modules",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "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 ."
+  },
   "dependencies": {
     "@discordjs/opus": "^0.10.0",
     "@discordjs/rest": "2.4.3",
     "@discordjs/voice": "0.18.0",
-    "@elizaos/core": "^1.7.2",
+    "@elizaos/core": "workspace:*",
     "discord.js": "14.18.0",
     "fast-levenshtein": "^3.0.0",
     "fluent-ffmpeg": "^2.1.3",
@@ -33,36 +49,21 @@
     "libsodium-wrappers": "^0.7.13",
     "opusscript": "^0.1.1",
     "prism-media": "1.3.5",
-    "typescript": "^5.8.3",
-    "zod": "4.1.13"
+    "typescript": "^5.9.3",
+    "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@elizaos/config": "1.6.5",
-    "@eslint/js": "^9.17.0",
-    "@typescript-eslint/eslint-plugin": "^8.22.0",
-    "@typescript-eslint/parser": "^8.22.0",
-    "eslint": "^9.17.0",
-    "prettier": "3.5.3",
-    "tsup": "8.4.0",
-    "vitest": "1.6.1"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "elizaos test",
-    "lint": "eslint ./src --fix && prettier --write ./src",
-    "lint:check": "eslint ./src",
-    "clean": "rm -rf dist .turbo node_modules .turbo-tsconfig.json tsconfig.tsbuildinfo",
-    "format": "prettier --write ./src",
-    "format:check": "prettier --check ./src"
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "@biomejs/biome": "^2.3.11"
   },
   "peerDependencies": {
-    "whatwg-url": "7.1.0"
+    "whatwg-url": "7.1.0",
+    "@elizaos/core": "workspace:*"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "646c632924826e2b75c2304a75ee56959fe4a460",
   "agentConfig": {
     "pluginType": "elizaos:plugin:1.0.0",
     "pluginParameters": {

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 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,531 +0,0 @@
-# @elizaos/plugin-discord
-
-A Discord plugin implementation for ElizaOS, enabling rich integration with Discord servers for managing interactions, voice, and message handling.
-
-## Features
-
-- Handle server join events and manage initial configurations
-- Voice event management via the voice manager
-- Manage and process new messages with the message manager
-- Slash command registration and interaction handling
-- Support for Discord attachments and media files
-- Voice channel join/leave functionality
-- Conversation summarization
-- Media transcription capabilities
-- Channel state and voice state providers
-- Channel restriction support (limit bot to specific channels)
-- Robust permissions management and audit event tracking
-- Event-driven architecture with comprehensive event handling
-- History backfill with efficient batch processing
-
-## Installation
-
-As this is a workspace package, it's installed as part of the ElizaOS monorepo:
-
-```bash
-bun install
-```
-
-## Configuration
-
-The plugin requires the following environment variables:
-
-```bash
-# Discord API Credentials (Required)
-DISCORD_APPLICATION_ID=your_application_id
-DISCORD_API_TOKEN=your_api_token
-
-# Channel Restrictions (Optional)
-# Comma-separated list of Discord channel IDs to restrict the bot to.
-# If not set, the bot operates in all channels.
-# These channels cannot be removed via the leaveChannel action.
-CHANNEL_IDS=123456789012345678,987654321098765432
-
-# Listen-only channels (Optional)
-# Comma-separated list of channel IDs where the bot will only listen (not respond).
-DISCORD_LISTEN_CHANNEL_IDS=123456789012345678
-
-# Voice Channel (Optional)
-# ID of the voice channel the bot should auto-join when scanning a guild.
-# If not set, the bot selects based on member activity.
-DISCORD_VOICE_CHANNEL_ID=123456789012345678
-
-# Behavior Settings (Optional)
-# If true, ignore messages from other bots (default: false)
-DISCORD_SHOULD_IGNORE_BOT_MESSAGES=false
-
-# If true, ignore direct messages (default: false)
-DISCORD_SHOULD_IGNORE_DIRECT_MESSAGES=false
-
-# If true, only respond when explicitly @mentioned (default: false)
-DISCORD_SHOULD_RESPOND_ONLY_TO_MENTIONS=false
-
-# Testing (Optional)
-DISCORD_TEST_CHANNEL_ID=123456789012345678
-```
-
-Settings can also be configured in your character file under `settings.discord`:
-
-```json
-{
-  "settings": {
-    "discord": {
-      "shouldIgnoreBotMessages": false,
-      "shouldIgnoreDirectMessages": false,
-      "shouldRespondOnlyToMentions": false,
-      "allowedChannelIds": ["123456789012345678"]
-    }
-  }
-}
-```
-
-## Usage
-
-```json
-{
-  "plugins": ["@elizaos/plugin-discord"]
-}
-```
-
-## Slash Command Permissions
-
-The plugin uses a hybrid permission system that combines Discord's native features with ElizaOS-specific controls.
-
-### Permission Layers
-
-Commands go through multiple permission checks in this order:
-
-1. **Discord Native Checks** (before interaction fires):
-   - User must have required Discord permissions
-   - Command must be available in the current context (guild vs DM)
-
-2. **ElizaOS Channel Whitelist** (if `CHANNEL_IDS` is set):
-   - Commands only work in whitelisted channels
-   - Unless command has `bypassChannelWhitelist: true`
-
-3. **Custom Validator** (if provided):
-   - Runs custom validation logic
-   - Full programmatic control
-
-### Registering Commands
-
-```typescript
-import { PermissionFlagsBits } from 'discord.js';
-
-// Simple command (works everywhere)
-const helpCommand = {
-  name: 'help',
-  description: 'Show help information'
-};
-
-// Guild-only command
-const serverInfoCommand = {
-  name: 'serverinfo',
-  description: 'Show server information',
-  guildOnly: true
-};
-
-// Requires Discord permission
-const configCommand = {
-  name: 'config',
-  description: 'Configure bot settings',
-  requiredPermissions: PermissionFlagsBits.ManageGuild
-};
-
-// Bypasses channel whitelist
-const utilityCommand = {
-  name: 'export',
-  description: 'Export data',
-  bypassChannelWhitelist: true
-};
-
-// Advanced: custom validation
-const adminCommand = {
-  name: 'admin',
-  description: 'Admin-only command',
-  validator: async (interaction, runtime) => {
-    const adminIds = runtime.getSetting('ADMIN_USER_IDS')?.split(',') ?? [];
-    return adminIds.includes(interaction.user.id);
-  }
-};
-
-// Register commands
-await runtime.emitEvent(['DISCORD_REGISTER_COMMANDS'], {
-  commands: [helpCommand, serverInfoCommand, configCommand, utilityCommand, adminCommand]
-});
-```
-
-### Permission Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `guildOnly` | `boolean` | If true, command only works in guilds (not DMs) |
-| `bypassChannelWhitelist` | `boolean` | If true, bypasses `CHANNEL_IDS` restrictions |
-| `requiredPermissions` | `bigint \| string` | Discord permission bitfield (e.g., `PermissionFlagsBits.ManageGuild`) |
-| `contexts` | `number[]` | Raw Discord contexts (0=Guild, 1=BotDM, 2=PrivateChannel) |
-| `guildIds` | `string[]` | Register only in specific guilds (instant updates) |
-| `validator` | `function` | Custom validation function for advanced logic |
-
-### Common Permission Values
-
-From Discord.js `PermissionFlagsBits`:
-
-- `ManageGuild` - Server settings
-- `ManageChannels` - Channel management
-- `ManageMessages` - Delete messages
-- `BanMembers` - Ban users
-- `KickMembers` - Kick users
-- `ModerateMembers` - Timeout users
-- `ManageRoles` - Role management
-- `Administrator` - Full access
-
-### Design Rationale
-
-**Why Hybrid Approach?**
-- Discord's native permissions are powerful but limited to role-based access
-- ElizaOS needs programmatic control for channel restrictions and custom logic
-- Combining both gives developers the best of both worlds
-
-**Why Simple Flags?**
-- `guildOnly: true` is clearer than `contexts: [0]`
-- Abstracts Discord API details
-- Sensible defaults: zero config should "just work"
-
-**Why Keep Channel Whitelist?**
-- Discord's channel permissions are UI-based (Server Settings > Integrations)
-- Programmatic control is better for developer experience
-- Allows dynamic, runtime-based channel restrictions
-
-### Available Actions
-
-The plugin provides the following actions:
-
-| Action | Description |
-|--------|-------------|
-| **chatWithAttachments** | Handle messages with Discord attachments |
-| **createPoll** | Create a poll in a Discord channel |
-| **downloadMedia** | Download media files from Discord messages |
-| **getUserInfo** | Get information about a Discord user |
-| **joinVoice** | Join a voice channel |
-| **leaveVoice** | Leave a voice channel |
-| **listChannels** | List channels in a Discord server |
-| **pinMessage** | Pin a message in a channel |
-| **reactToMessage** | Add a reaction to a message |
-| **readChannel** | Read messages from a channel |
-| **searchMessages** | Search for messages in a channel |
-| **sendDM** | Send a direct message to a user |
-| **serverInfo** | Get information about the current server |
-| **summarize** | Summarize conversation history |
-| **transcribeMedia** | Transcribe audio/video media to text |
-| **unpinMessage** | Unpin a message from a channel |
-
-### Providers
-
-The plugin includes two state providers:
-
-1. **channelStateProvider** - Provides state information about Discord channels
-2. **voiceStateProvider** - Provides state information about voice channels and connection status
-
-### Event Types
-
-The plugin emits the following Discord-specific events:
-
-| Event | Description |
-|-------|-------------|
-| `DISCORD_MESSAGE_RECEIVED` | When a message is received |
-| `DISCORD_MESSAGE_SENT` | When a message is sent |
-| `DISCORD_SLASH_COMMAND` | When a slash command is invoked |
-| `DISCORD_MODAL_SUBMIT` | When a modal form is submitted |
-| `DISCORD_REACTION_RECEIVED` | When a reaction is added to a message |
-| `DISCORD_REACTION_REMOVED` | When a reaction is removed from a message |
-| `DISCORD_WORLD_JOINED` | When the bot joins a guild |
-| `DISCORD_SERVER_CONNECTED` | When connected to a server |
-| `DISCORD_USER_JOINED` | When a user joins a guild |
-| `DISCORD_USER_LEFT` | When a user leaves a guild |
-| `DISCORD_VOICE_STATE_CHANGED` | When voice state changes |
-| `DISCORD_CHANNEL_PERMISSIONS_CHANGED` | When channel permissions change |
-| `DISCORD_ROLE_PERMISSIONS_CHANGED` | When role permissions change |
-| `DISCORD_MEMBER_ROLES_CHANGED` | When a member's roles change |
-| `DISCORD_ROLE_CREATED` | When a role is created |
-| `DISCORD_ROLE_DELETED` | When a role is deleted |
-
-## Key Components
-
-### DiscordService
-
-Main service class that extends ElizaOS Service:
-- Handles authentication and session management
-- Manages Discord client connection
-- Processes events and interactions
-- Supports channel history backfill with efficient batch processing
-
-### MessageManager
-
-- Processes incoming messages and responses
-- Handles attachments and media files
-- Supports message formatting and templating
-- Manages conversation context
-
-### VoiceManager
-
-- Manages voice channel interactions
-- Handles joining and leaving voice channels
-- Processes voice events and audio streams
-- Integrates with transcription services
-
-### Attachment Handler
-
-- Downloads and processes Discord attachments
-- Supports various media types
-- Integrates with media transcription
-
-## Developer Guide
-
-### Custom Slash Commands
-
-Register slash commands via the `DISCORD_REGISTER_COMMANDS` event, then listen for interactions:
-
-```typescript
-// Register custom slash commands
-await runtime.emitEvent(['DISCORD_REGISTER_COMMANDS'], {
-  commands: [
-    {
-      name: 'mycommand',
-      description: 'My custom command',
-      options: [
-        {
-          name: 'input',
-          description: 'User input',
-          type: 3, // STRING type
-          required: true,
-        },
-      ],
-    },
-    {
-      name: 'serverinfo',
-      description: 'Get server information',
-      guildOnly: true, // Only works in guilds, not DMs
-    },
-  ],
-});
-
-// Listen for slash command events to handle the interaction
-runtime.registerEvent({
-  name: 'DISCORD_SLASH_COMMAND',
-  handler: async (payload) => {
-    const { interaction, client, commands } = payload;
-    
-    if (interaction.commandName === 'mycommand') {
-      const input = interaction.options.getString('input');
-      await interaction.reply(`You said: ${input}`);
-    }
-  },
-});
-```
-
-### Building on the Listen System
-
-The `DISCORD_LISTEN_CHANNEL_IDS` setting creates "listen-only" channels where the bot receives messages but doesn't respond. This is useful for:
-
-- **Monitoring channels** - Track activity without interrupting conversations
-- **Data collection** - Gather messages for analysis or training
-- **Conditional responses** - Build custom logic that decides when to respond
-
-```typescript
-// Check if a channel is listen-only
-const listenChannels = runtime.getSetting('DISCORD_LISTEN_CHANNEL_IDS');
-const listenChannelIds = listenChannels?.split(',').map(s => s.trim()) || [];
-
-runtime.registerEvent({
-  name: 'DISCORD_MESSAGE_RECEIVED',
-  handler: async (payload) => {
-    const { message } = payload;
-    const channelId = message.content.channelId;
-    
-    if (listenChannelIds.includes(channelId)) {
-      // This is a listen-only channel - process without responding
-      await processMessageSilently(message);
-    }
-  },
-});
-```
-
-### Handling Modal and Component Interactions
-
-Modal submits and message components (buttons, select menus) bypass channel whitelists to support multi-step UI flows:
-
-```typescript
-// Listen for modal submissions
-runtime.registerEvent({
-  name: 'DISCORD_MODAL_SUBMIT',
-  handler: async (payload) => {
-    const { interaction } = payload;
-    const fieldValue = interaction.fields.getTextInputValue('myField');
-    await interaction.reply(`Received: ${fieldValue}`);
-  },
-});
-```
-
-### Permission Audit System
-
-The plugin includes a comprehensive permission audit system that tracks all permission changes with full audit log integration. This is useful for:
-
-- **Security monitoring** - Detect unauthorized permission escalations
-- **Compliance logging** - Maintain records of who changed what and when
-- **Bot self-protection** - Detect when the bot's permissions are modified
-
-#### Event Payloads
-
-**DISCORD_CHANNEL_PERMISSIONS_CHANGED** - When channel overwrites change:
-
-```typescript
-interface ChannelPermissionsChangedPayload {
-  runtime: IAgentRuntime;
-  guild: { id: string; name: string };
-  channel: { id: string; name: string };
-  target: { type: 'role' | 'user'; id: string; name: string };
-  action: 'CREATE' | 'UPDATE' | 'DELETE';
-  changes: Array<{
-    permission: string;      // e.g., 'ManageMessages', 'Administrator'
-    oldState: 'ALLOW' | 'DENY' | 'NEUTRAL';
-    newState: 'ALLOW' | 'DENY' | 'NEUTRAL';
-  }>;
-  audit: { executorId: string; executorTag: string; reason: string | null } | null;
-}
-```
-
-**DISCORD_ROLE_PERMISSIONS_CHANGED** - When role permissions change:
-
-```typescript
-interface RolePermissionsChangedPayload {
-  runtime: IAgentRuntime;
-  guild: { id: string; name: string };
-  role: { id: string; name: string };
-  changes: PermissionDiff[];
-  audit: AuditInfo | null;
-}
-```
-
-**DISCORD_MEMBER_ROLES_CHANGED** - When a member's roles change:
-
-```typescript
-interface MemberRolesChangedPayload {
-  runtime: IAgentRuntime;
-  guild: { id: string; name: string };
-  member: { id: string; tag: string };
-  added: Array<{ id: string; name: string; permissions: string[] }>;
-  removed: Array<{ id: string; name: string; permissions: string[] }>;
-  audit: AuditInfo | null;
-}
-```
-
-**DISCORD_ROLE_CREATED / DISCORD_ROLE_DELETED** - Role lifecycle:
-
-```typescript
-interface RoleLifecyclePayload {
-  runtime: IAgentRuntime;
-  guild: { id: string; name: string };
-  role: { id: string; name: string; permissions: string[] };
-  audit: AuditInfo | null;
-}
-```
-
-#### Example: Security Monitoring
-
-```typescript
-import { DiscordEventTypes } from '@elizaos/plugin-discord';
-
-// Alert on dangerous permission grants
-runtime.registerEvent({
-  name: DiscordEventTypes.CHANNEL_PERMISSIONS_CHANGED,
-  handler: async (payload) => {
-    const dangerousPerms = ['Administrator', 'ManageGuild', 'ManageRoles'];
-    
-    for (const change of payload.changes) {
-      if (dangerousPerms.includes(change.permission) && change.newState === 'ALLOW') {
-        console.warn(`⚠️ Dangerous permission granted!`, {
-          channel: payload.channel.name,
-          target: payload.target.name,
-          permission: change.permission,
-          grantedBy: payload.audit?.executorTag || 'Unknown',
-        });
-      }
-    }
-  },
-});
-
-// Track role escalations
-runtime.registerEvent({
-  name: DiscordEventTypes.MEMBER_ROLES_CHANGED,
-  handler: async (payload) => {
-    const adminRoles = payload.added.filter(r => 
-      r.permissions.includes('Administrator')
-    );
-    
-    if (adminRoles.length > 0) {
-      console.warn(`⚠️ Admin role granted to ${payload.member.tag}`, {
-        roles: adminRoles.map(r => r.name),
-        grantedBy: payload.audit?.executorTag || 'Unknown',
-      });
-    }
-  },
-});
-
-// Log all role creations
-runtime.registerEvent({
-  name: DiscordEventTypes.ROLE_CREATED,
-  handler: async (payload) => {
-    console.log(`New role created: ${payload.role.name}`, {
-      permissions: payload.role.permissions,
-      createdBy: payload.audit?.executorTag || 'Unknown',
-    });
-  },
-});
-```
-
-#### Bot Self-Protection
-
-Monitor when the bot's own permissions change:
-
-```typescript
-runtime.registerEvent({
-  name: DiscordEventTypes.MEMBER_ROLES_CHANGED,
-  handler: async (payload) => {
-    const botId = runtime.getSetting('DISCORD_APPLICATION_ID');
-    
-    if (payload.member.id === botId && payload.removed.length > 0) {
-      console.error(`🚨 Bot roles removed!`, {
-        removed: payload.removed.map(r => r.name),
-        by: payload.audit?.executorTag || 'Unknown',
-      });
-      // Could trigger alerts, notifications, etc.
-    }
-  },
-});
-```
-
-## Cross-Core Compatibility
-
-This plugin includes a compatibility layer (`compat.ts`) that allows it to work with both old and new versions of `@elizaos/core`. The compatibility layer:
-
-- Automatically handles `serverId` vs `messageServerId` differences
-- Uses a runtime proxy to intercept and adapt API calls
-- Requires no changes to existing code
-
-When migrating to a new core version, see the comments in `compat.ts` for removal instructions.
-
-## Testing
-
-The plugin includes a test suite for validating functionality:
-
-```bash
-bun run test
-```
-
-## Notes
-
-- Ensure that your `.env` file includes the required `DISCORD_API_TOKEN`
-- The bot requires appropriate Discord permissions (send messages, connect to voice, etc.)
-- If no token is provided, the plugin will load but remain non-functional with appropriate warnings
-- The plugin uses Discord.js v14.18.0 with comprehensive intent support
-- Slash commands and modal/component interactions bypass channel whitelists