feat: change plugins from project-scoped to agent-scoped architecture #5270
Conversation
…passing char names as args)
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughThis update refactors plugin management in ElizaOS CLI from a project-level to a character-centric approach. Core CLI commands ( Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CLI
participant CharacterFile
participant PluginRegistry
User->>CLI: elizaos plugins add <plugin> --character <file>
CLI->>CharacterFile: Resolve and validate <file>
CLI->>PluginRegistry: Install <plugin> if missing
CLI->>CharacterFile: Add <plugin> to plugins array
CharacterFile-->>CLI: Save updated character file
CLI-->>User: Plugin added to character
sequenceDiagram
participant User
participant CLI
participant CharacterFile
User->>CLI: elizaos plugins remove <plugin> --character <file>
CLI->>CharacterFile: Resolve and validate <file>
CLI->>CharacterFile: Remove <plugin> from plugins array
CharacterFile-->>CLI: Save updated character file
CLI-->>User: Plugin removed from character
Possibly related PRs
Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate Unit Tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
How to use the Graphite Merge QueueAdd either label to this PR to merge it via the merge queue:
You must have a Graphite account in order to use the merge queue. Sign up using this link. An organization admin has enabled the Graphite Merge Queue in this repository. Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue. |
|
@BugBot full review |
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
There was a problem hiding this comment.
Pull Request Overview
This PR refactors the ElizaOS plugin system from a project-scoped architecture to a character-centric model, enabling individual characters/agents to have their own plugin configurations.
- Removed plugin dependencies from package.json and adjusted tsconfig path mappings.
- Added new utilities for character file discovery, parsing, and updates.
- Updated CLI commands and associated documentation to reflect the shift to character-scoped plugin management.
Reviewed Changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/project-starter/tsconfig.json | Updated path mapping for @elizaos/core to resolve Bun module issues. |
| packages/project-starter/package.json | Removed project-scoped plugin dependencies. |
| packages/docs/* | Updated documentation and examples for character-centric plugins. |
| packages/cli/src/utils/* | Added/modified utilities for character file finding, parsing, and logging. |
| packages/cli/src/commands/* | Adjusted CLI commands (start, agent, plugins) to support character files. |
| packages/cli/package.json & packages/cli/README.md | Updated dependencies and documentation to align with the new architecture. |
Comments suppressed due to low confidence (1)
packages/cli/src/commands/plugins/actions/install.ts:124
- [nitpick] Including a comment that clarifies the required format and behavior of the '--character' flag (such as supporting multiple file paths) would help future developers understand the expected input.
async function updateCharacterFiles(pluginName: string, opts: AddPluginOptions): Promise<void> {
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (8)
packages/docs/docs/cli/agent.md (1)
145-157: Fix duplicated "directory" phrase.The character file resolution documentation is excellent, but there's a grammatical issue with "directory directory" repetition.
- 2. Search common directories: - - Current directory - - `./characters/` directory - - `./agents/` directory - - `./src/characters/` directory - - `./src/agents/` directory + 2. Search common directories: + - Current directory + - `./characters/` + - `./agents/` + - `./src/characters/` + - `./src/agents/`packages/cli/src/commands/plugins/actions/installed-plugins.ts (3)
30-66: Missing error handling for empty results.When specific character paths are provided but yield no valid character files (line 36), the function returns without any user feedback. Consider logging a message to inform the user that their specified paths didn't match any valid character files.
if (characterFilePaths.size === 0) { - console.log('No valid character files found.'); + console.log('No valid character files found for the specified paths.'); + console.log('Please check your character paths and try again.'); return; }
87-91: Remove unnecessary continue statement.The
continuestatement is redundant as it's the last statement in the loop iteration.} catch (error) { // Skip files that can't be loaded - continue; }
54-63: Inconsistent output formatting between paths.The output format differs between specific character queries and all character scans. Consider using consistent formatting for better user experience.
For consistency, consider using the same header style in both paths. Either use
logHeaderonce for all output or use it consistently per character.Also applies to: 99-107
packages/cli/src/commands/plugins/actions/install.ts (1)
137-141: Consider graceful error handling for character updates.The function exits the process when character file updates fail, even though the plugin installation may have succeeded. Consider offering a recovery option or warning instead of a hard exit.
} catch (error) { logger.error(`Failed to update character file ${characterPath}:`, error); - process.exit(1); + logger.warn('Plugin was installed but character file update failed.'); + logger.info('You can manually add the plugin to your character file.'); + // Optionally continue with other character files or exit based on a flag }packages/cli/README.md (1)
310-313: Consider expanding the plugin loading documentation.While the auto-installation feature is mentioned, users might benefit from more details about:
- Where plugins are installed (node_modules?)
- What happens if installation fails
- Network requirements for auto-installation
packages/cli/src/commands/plugins/utils/character-updater.ts (1)
39-45: TypeScript character file support needed.The current implementation throws an error for TypeScript files. Since the character finder utility can detect TypeScript character files, this limitation should be addressed.
Would you like me to help implement TypeScript character file update support? This would involve parsing and updating the TypeScript AST.
packages/cli/src/utils/character-finder.ts (1)
361-385: Use optional chaining for cleaner code.Replace manual null checks with optional chaining.
- if (characterMatch && characterMatch[1]) { - return characterMatch[1]; + if (characterMatch?.[1]) { + return characterMatch[1]; } // Look for agents array with character const agentsMatch = content.match(/agents\s*:\s*\[[^\]]*character\s*:\s*{[^}]*name\s*:\s*["'`]([^"'`]+)["'`]/); - if (agentsMatch && agentsMatch[1]) { - return agentsMatch[1]; + if (agentsMatch?.[1]) { + return agentsMatch[1]; } // Look for const characterName: Character = { name: "..." } const typedCharMatch = content.match(/const\s+\w+\s*:\s*Character\s*=\s*{[^}]*name\s*:\s*["'`]([^"'`]+)["'`]/); - if (typedCharMatch && typedCharMatch[1]) { - return typedCharMatch[1]; + if (typedCharMatch?.[1]) { + return typedCharMatch[1]; } // Fallback to simple patterns for (const pattern of patterns) { const match = content.match(pattern); - if (match && match[1]) { - return match[1]; + if (match?.[1]) { + return match[1]; }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (22)
packages/cli/README.md(6 hunks)packages/cli/package.json(0 hunks)packages/cli/src/commands/agent/actions/lifecycle.ts(2 hunks)packages/cli/src/commands/agent/index.ts(1 hunks)packages/cli/src/commands/plugins/actions/install.ts(6 hunks)packages/cli/src/commands/plugins/actions/installed-plugins.ts(1 hunks)packages/cli/src/commands/plugins/actions/list.ts(0 hunks)packages/cli/src/commands/plugins/actions/remove.ts(2 hunks)packages/cli/src/commands/plugins/index.ts(5 hunks)packages/cli/src/commands/plugins/types.ts(1 hunks)packages/cli/src/commands/plugins/utils/character-updater.ts(1 hunks)packages/cli/src/commands/start/index.ts(3 hunks)packages/cli/src/utils/character-finder.ts(1 hunks)packages/cli/src/utils/character-parser.ts(1 hunks)packages/cli/src/utils/load-plugin.ts(2 hunks)packages/docs/docs/cli/agent.md(3 hunks)packages/docs/docs/cli/dev.md(3 hunks)packages/docs/docs/cli/plugins.md(6 hunks)packages/docs/docs/cli/start.md(2 hunks)packages/docs/docs/quickstart.md(2 hunks)packages/project-starter/package.json(0 hunks)packages/project-starter/tsconfig.json(1 hunks)
💤 Files with no reviewable changes (3)
- packages/cli/package.json
- packages/project-starter/package.json
- packages/cli/src/commands/plugins/actions/list.ts
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: wtfsayo
PR: elizaOS/eliza#4493
File: packages/docs/docs/core/plugins.md:95-101
Timestamp: 2025-05-08T09:37:35.805Z
Learning: The ElizaOS CLI uses the plural form "plugins" for plugin management commands (e.g., "elizaos plugins add", "elizaos plugins remove", "elizaos plugins list"), while the singular form "plugin" is used for plugin development operations (e.g., "elizaos plugin publish").
packages/docs/docs/cli/plugins.md (1)
Learnt from: wtfsayo
PR: elizaOS/eliza#4493
File: packages/docs/docs/core/plugins.md:95-101
Timestamp: 2025-05-08T09:37:35.805Z
Learning: The ElizaOS CLI uses the plural form "plugins" for plugin management commands (e.g., "elizaos plugins add", "elizaos plugins remove", "elizaos plugins list"), while the singular form "plugin" is used for plugin development operations (e.g., "elizaos plugin publish").
packages/cli/README.md (1)
Learnt from: wtfsayo
PR: elizaOS/eliza#4493
File: packages/docs/docs/core/plugins.md:95-101
Timestamp: 2025-05-08T09:37:35.805Z
Learning: The ElizaOS CLI uses the plural form "plugins" for plugin management commands (e.g., "elizaos plugins add", "elizaos plugins remove", "elizaos plugins list"), while the singular form "plugin" is used for plugin development operations (e.g., "elizaos plugin publish").
🪛 LanguageTool
packages/docs/docs/cli/agent.md
[grammar] ~149-~149: This phrase is duplicated. You should probably use “directory directory” only once.
Context: ...Search common directories: - Current directory - ./characters/ directory - ./agents/ directory - ./src/characters/ directory - ./src/agents/ directory 3. If no...
(PHRASE_REPETITION)
🪛 Biome (1.9.4)
packages/cli/src/commands/plugins/actions/installed-plugins.ts
[error] 89-89: Unnecessary continue statement
Unsafe fix: Delete the unnecessary continue statement
(lint/correctness/noUnnecessaryContinue)
packages/cli/src/utils/character-finder.ts
[error] 318-318: The catch clause that only rethrows the original error is useless.
An unnecessary catch clause can be confusing.
Unsafe fix: Remove the try/catch clause.
(lint/complexity/noUselessCatch)
[error] 362-362: Change to an optional chain.
Unsafe fix: Change to an optional chain.
(lint/complexity/useOptionalChain)
[error] 368-368: Change to an optional chain.
Unsafe fix: Change to an optional chain.
(lint/complexity/useOptionalChain)
[error] 374-374: Change to an optional chain.
Unsafe fix: Change to an optional chain.
(lint/complexity/useOptionalChain)
[error] 381-381: Change to an optional chain.
Unsafe fix: Change to an optional chain.
(lint/complexity/useOptionalChain)
⏰ Context from checks skipped due to timeout of 90000ms (6)
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: validate
- GitHub Check: databaseIntegrationTests
- GitHub Check: test (ubuntu-latest)
- GitHub Check: test (windows-latest)
- GitHub Check: test (macos-latest)
🔇 Additional comments (33)
packages/cli/src/utils/character-parser.ts (1)
1-57: Well-designed utility with comprehensive format support.The implementation correctly handles multiple CLI input formats and edge cases. The regex pattern, deduplication logic, and defensive filtering are all properly implemented.
packages/project-starter/tsconfig.json (1)
26-27: Path mapping correctly updated for new architecture.The change from source paths to node_modules aligns with the character-centric plugin management where core modules are treated as installed dependencies.
packages/cli/src/commands/plugins/types.ts (1)
14-19: Types properly support character-scoped plugin management.The optional character properties correctly enable plugin operations on specific character files while maintaining flexibility for multiple file handling.
packages/cli/src/utils/load-plugin.ts (2)
70-74: Enhanced logging improves plugin loading visibility.The detailed debug messages with emojis clearly indicate import success/failure, making plugin loading issues easier to troubleshoot.
223-231: Strategy-level logging provides excellent debugging detail.The per-strategy logging helps users understand exactly which import methods are being attempted and their outcomes.
packages/docs/docs/quickstart.md (2)
51-95: Excellent documentation of character-centric workflow.The new character creation step clearly explains the architecture shift and provides a practical JSON template. The optional nature keeps the quickstart accessible while introducing advanced concepts.
106-106: Wording correctly reflects new plugin management.The updated text accurately describes how plugins are now added to character configurations rather than project-level dependencies.
packages/cli/src/commands/agent/index.ts (1)
53-62: Excellent documentation enhancement.The detailed character file resolution explanation and examples significantly improve user experience by clearly documenting the automatic path resolution behavior.
packages/docs/docs/cli/dev.md (1)
114-162: Comprehensive plugin loading documentation.The new sections clearly explain the character-centric plugin architecture and provide practical examples for both development and troubleshooting scenarios.
packages/cli/src/commands/agent/actions/lifecycle.ts (2)
79-102: Solid refactoring to use new character utilities.The implementation correctly uses the new utility functions with proper async handling and maintains comprehensive error handling throughout the character path resolution flow.
109-112: Improved error messaging.The updated error messages provide clearer context about character file parsing failures, enhancing debugging experience.
packages/docs/docs/cli/start.md (2)
138-162: Clear explanation of character-centric plugin loading.The updated startup process documentation and plugin loading section effectively communicate the architectural shift from project-scoped to character-scoped plugin management.
207-223: Practical plugin troubleshooting guidance.The troubleshooting section provides useful commands and steps for debugging plugin loading issues in the new character-centric architecture.
packages/cli/src/commands/plugins/actions/install.ts (1)
125-128: Good defensive programming.The function properly validates the character option before proceeding, preventing undefined behavior.
packages/cli/src/commands/plugins/actions/remove.ts (1)
67-75: Smart handling of missing dependencies.Good approach to attempt character file updates even when the plugin isn't found in package.json, as it may have been manually removed.
packages/cli/src/commands/start/index.ts (2)
83-89: Excellent user guidance.The informative output clearly shows available characters and how to use them, improving the user experience significantly.
118-125: Clean error handling.Good distinction between expected and unexpected errors, avoiding unnecessary noise in the logs.
packages/cli/src/commands/plugins/index.ts (2)
47-49: Clear requirement for character specification.The required
--characteroption with descriptive help text makes the new architecture clear to users.
21-23: Consistent with established naming conventions.The plural form "plugins" for management commands aligns with the documented ElizaOS CLI patterns.
packages/cli/README.md (5)
142-144: LGTM! Clear explanation of the new architecture.The documentation effectively communicates the paradigm shift from project-level to character-centric plugin management.
147-147: Good clarification on thelistcommand behavior change.The updated description accurately reflects that
listnow shows registry plugins rather than project dependencies.
164-176: Helpful character file example.The JSON example clearly shows how plugins are now declared within character files, supporting both npm packages and local paths.
179-189: Comprehensive usage examples.The examples effectively demonstrate the new
--characterflag requirement across different plugin operations.
679-684: Clear development workflow updates.The documentation properly reflects the new character-centric workflow for both plugin and project development.
Also applies to: 768-771
packages/cli/src/commands/plugins/utils/character-updater.ts (3)
51-64: Well-implemented plugin addition logic.Good use of immutable updates and duplicate checking.
69-82: Clean plugin removal implementation.Proper existence checking and immutable updates.
87-94: LGTM!Simple and effective JSON file update.
packages/docs/docs/cli/plugins.md (3)
29-32: Accurate command documentation updates.The table correctly reflects the new
--characterrequirement for plugin management commands.
143-168: Excellent architectural explanation.The documentation clearly explains the benefits of character-centric plugin management and provides a helpful example.
280-347: Comprehensive troubleshooting guide.Excellent coverage of common issues with practical command examples for debugging character and plugin problems.
packages/cli/src/utils/character-finder.ts (3)
21-72: Robust character path resolution.The function implements a comprehensive search strategy checking multiple locations and extensions.
84-105: Well-configured file search patterns.Good use of globby with comprehensive ignore patterns to exclude non-character files.
186-241: Thorough TypeScript character detection.Excellent pattern matching for various character export formats with proper test file exclusion.
Co-authored-by: Copilot <[email protected]>
…n and --path into --character
|
@wtfsayo @ChristopherTrimboli still a failing ci test or two to clean up but otherwise good to review |
…ranch instead of develop
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Resolved conflicts: - packages/core/src/utils.ts: Used develop's smarter attachment formatting logic - packages/cli/package.json: Kept our character-centric approach without plugin dependencies
Incorrect |
umm what? |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
@wtfsayo windows macos and ubuntu are passing |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
i fixed this |
|
@coderabbitai full summary what does it change |
|
Tip For best results, initiate chat on the files or code changes. @wtfsayo Here's a comprehensive summary of what this PR changes: 🔄 Core Architectural ChangeFrom Project-Scoped to Agent-Scoped Plugin Management Previously, plugins were managed globally at the project level in 📝 Key Changes1. Plugin Configuration Location
2. CLI Commands RefactoredAll plugin management commands now require a
3. New Utility Modules
4. Runtime Plugin Loading
💥 Breaking Changes
✨ Benefits
📚 Documentation UpdatesExtensive updates to:
This is a fundamental architectural shift that makes ElizaOS more flexible for multi-agent scenarios while maintaining backward compatibility through migration guidance. |
Problem
package.json, forcing all agents to share the same plugin setelizaos agent startsilently ignoring multiple characters--name,--path,--remote-character) for character specificationSolution
Comprehensive refactor implementing character-centric architecture with full multi-agent support:
Character-Centric Plugin Management
character.pluginsarray)Multi-Agent Support
-c, --characterflagsKey Changes
Core Infrastructure
character-finder.ts- Standardized character file discovery across project directories with path resolutioncharacter-parser.ts- Unified parsing for both JSON and TypeScript character files with flexible input handlingcharacter-updater.ts- Safe character configuration updates with plugin-specific utilitiespackage.json- defined exclusively in characterpluginsarraysMulti-Agent Command Support
-c, --character <paths...>syntaxelizaos agent start -c bobby,billy- Start multiple agents simultaneouslyelizaos agent stop -c bobby,billy- Stop multiple agentselizaos agent get -c bobby,billy- Get details for multiple agentselizaos agent remove -c bobby,billy- Remove multiple agentselizaos agent clear-memories -c bobby,billy- Clear memories for multiple agentselizaos agent set -c bobby- Only accepts single character (by design)elizaos agent start -c bobby,billyelizaos agent start -c bobby billyelizaos agent start -c bobby ./billy.json https://example.com/alice.json.jsonextension added automatically if missingRefactors & Code Cleanup
installed-plugins.tsfromlist.tsfor improved separation of concernsstart,dev,agent, andpluginscommandsCI Test Infrastructure Fixes
Bun.spawnweren't properly terminating server processes, leaving orphaned processes that CI environments detect as failures. This was causing all 3 CLI tests (ubuntu, macos, windows) to failafterAllhooks in test files to kill entire process groups, not just individual processestest-like-ci.sh,verify-cleanup.sh)agent.test.tsanddev.test.ts- Enhanced process terminationcleanup-processes.sh- Shell script for process cleanup.github/workflows/cli-tests.yml- Added always-run cleanup steppackage.json- Updated test:cli to include cleanupCLI Commands
Plugin Commands (Character-Scoped)
elizaos plugins add -c <character>- Adds plugins to character files (supports both-cand--characterflags)elizaos plugins remove -c <character>- Removes plugins from character fileselizaos plugins installed-plugins -c <character>- Displays character-specific plugins, organized by agentAgent Commands (Multi-Agent Support)
elizaos agent start -c <characters...>- Start single or multiple agentselizaos agent stop -c <characters...>- Stop single or multiple agentselizaos agent get -c <characters...>- Get details for single or multiple agentselizaos agent remove -c <characters...>- Remove single or multiple agentselizaos agent clear-memories -c <characters...>- Clear memories for single or multiple agentselizaos agent set -c <character>- Update configuration (single agent only)Enhanced Character Resolution
.jsonextension and common directory searchingTechnical Fixes & Improvements
@elizaos/coreto resolve Bun module resolution issuespackage.jsonfilesDocumentation Updates
Breaking Changes
Plugin Management Migration Required
package.jsondependenciespluginsarrayspackage.jsonto relevant character filesAgent Command Parameter Changes
--name,--path,--remote-character)-c, --characterfor all agent operations