elizaos-plugin-shell 2.0.0a4__tar.gz

elizaos_plugin_shell-2.0.0a4/.gitignore

@@ -0,0 +1,67 @@
+# Build outputs
+dist/
+node_modules/
+
+# Environment files
+.env
+.env.local
+.env.production
+.env.staging
+.env.development
+.env.bak
+*.env
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+
+# Cache directories
+.cache/
+.npm/
+.eslintcache
+
+# Temporary folders
+tmp/
+temp/
+
+# Database files
+*.db
+*.pglite
+*.pglite3
+
+# ElizaOS specific
+.eliza/
+.elizadb/
+pglite/
+cache/
+dist
+node_modules
+.elizadb
+.turbo
+target/
+__pycache__
+*.pyc
+.venv
+*.egg-info
+package-lock.json

elizaos_plugin_shell-2.0.0a4/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2024 elizaOS
+
+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.
+
+
+
+
+
+
+

elizaos_plugin_shell-2.0.0a4/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: elizaos-plugin-shell
+Version: 2.0.0a4
+Summary: elizaOS Shell Plugin - Shell command execution with directory restrictions and history tracking
+Project-URL: Homepage, https://github.com/elizaos/eliza
+Project-URL: Documentation, https://elizaos.ai/docs
+Project-URL: Repository, https://github.com/elizaos/eliza
+Author: elizaOS Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,command,elizaos,shell,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.10.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-xprocess>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# elizaOS Shell Plugin (Python)
+
+A secure shell command execution plugin for elizaOS that allows agents to run terminal commands within a restricted directory with command history tracking.
+
+## Installation
+
+```bash
+pip install elizaos-plugin-shell
+```
+
+## Features
+
+- **Cross-platform support**: Works on Linux, macOS, and Windows
+- **Directory restriction**: Commands are restricted to a specified directory for safety
+- **Command filtering**: Configurable list of forbidden commands
+- **Timeout protection**: Automatic termination of long-running commands
+- **Command history**: Tracks command execution history per conversation
+- **File operation tracking**: Monitors file creation, modification, and deletion
+- **Type safe**: Full type annotations with Pydantic models
+
+## Configuration
+
+Set the following environment variables:
+
+```bash
+# Set the allowed directory (commands can only run here)
+SHELL_ALLOWED_DIRECTORY=/path/to/safe/directory
+
+# Optional: Set custom timeout in milliseconds (default: 30000)
+SHELL_TIMEOUT=60000
+
+# Optional: Add additional forbidden commands (comma-separated)
+SHELL_FORBIDDEN_COMMANDS=rm,mv,cp,chmod,chown,shutdown,reboot
+```
+
+## Usage
+
+```python
+from elizaos_plugin_shell import ShellService, ShellConfig
+
+# Load configuration
+config = ShellConfig.from_env()
+
+# Create service
+service = ShellService(config)
+
+# Execute a command
+result = await service.execute_command("ls -la", conversation_id="conv-123")
+
+if result.success:
+    print(f"Output: {result.stdout}")
+else:
+    print(f"Error: {result.stderr}")
+
+# Get command history
+history = service.get_command_history("conv-123", limit=10)
+
+# Clear history
+service.clear_command_history("conv-123")
+```
+
+## Security
+
+The plugin enforces several security measures:
+
+1. **Directory Restriction**: All commands execute within `SHELL_ALLOWED_DIRECTORY`
+2. **Forbidden Commands**: Dangerous commands are blocked by default
+3. **Path Traversal Protection**: Blocks `../` and similar patterns
+4. **No Shell Expansion**: Commands execute without dangerous shell interpretation
+5. **Timeout Protection**: Commands auto-terminate after timeout
+
+## License
+
+MIT
+
+
+

elizaos_plugin_shell-2.0.0a4/README.md

@@ -0,0 +1,77 @@
+# elizaOS Shell Plugin (Python)
+
+A secure shell command execution plugin for elizaOS that allows agents to run terminal commands within a restricted directory with command history tracking.
+
+## Installation
+
+```bash
+pip install elizaos-plugin-shell
+```
+
+## Features
+
+- **Cross-platform support**: Works on Linux, macOS, and Windows
+- **Directory restriction**: Commands are restricted to a specified directory for safety
+- **Command filtering**: Configurable list of forbidden commands
+- **Timeout protection**: Automatic termination of long-running commands
+- **Command history**: Tracks command execution history per conversation
+- **File operation tracking**: Monitors file creation, modification, and deletion
+- **Type safe**: Full type annotations with Pydantic models
+
+## Configuration
+
+Set the following environment variables:
+
+```bash
+# Set the allowed directory (commands can only run here)
+SHELL_ALLOWED_DIRECTORY=/path/to/safe/directory
+
+# Optional: Set custom timeout in milliseconds (default: 30000)
+SHELL_TIMEOUT=60000
+
+# Optional: Add additional forbidden commands (comma-separated)
+SHELL_FORBIDDEN_COMMANDS=rm,mv,cp,chmod,chown,shutdown,reboot
+```
+
+## Usage
+
+```python
+from elizaos_plugin_shell import ShellService, ShellConfig
+
+# Load configuration
+config = ShellConfig.from_env()
+
+# Create service
+service = ShellService(config)
+
+# Execute a command
+result = await service.execute_command("ls -la", conversation_id="conv-123")
+
+if result.success:
+    print(f"Output: {result.stdout}")
+else:
+    print(f"Error: {result.stderr}")
+
+# Get command history
+history = service.get_command_history("conv-123", limit=10)
+
+# Clear history
+service.clear_command_history("conv-123")
+```
+
+## Security
+
+The plugin enforces several security measures:
+
+1. **Directory Restriction**: All commands execute within `SHELL_ALLOWED_DIRECTORY`
+2. **Forbidden Commands**: Dangerous commands are blocked by default
+3. **Path Traversal Protection**: Blocks `../` and similar patterns
+4. **No Shell Expansion**: Commands execute without dangerous shell interpretation
+5. **Timeout Protection**: Commands auto-terminate after timeout
+
+## License
+
+MIT
+
+
+

elizaos_plugin_shell-2.0.0a4/elizaos_plugin_shell/__init__.py

@@ -0,0 +1,57 @@
+# Actions
+from elizaos_plugin_shell.actions import (
+    ClearHistoryAction,
+    ExecuteCommandAction,
+    get_shell_action_names,
+)
+from elizaos_plugin_shell.path_utils import (
+    DEFAULT_FORBIDDEN_COMMANDS,
+    extract_base_command,
+    is_forbidden_command,
+    is_safe_command,
+    validate_path,
+)
+from elizaos_plugin_shell.providers import (
+    ShellHistoryProvider,
+    get_shell_provider_names,
+)
+from elizaos_plugin_shell.service import ShellService
+from elizaos_plugin_shell.types import (
+    CommandHistoryEntry,
+    CommandResult,
+    FileOperation,
+    FileOperationType,
+    ShellConfig,
+)
+
+__version__ = "1.2.0"
+
+# Plugin metadata
+PLUGIN_NAME = "shell"
+PLUGIN_DESCRIPTION = "Execute shell commands within a restricted directory with history tracking"
+
+__all__ = [
+    # Types
+    "CommandResult",
+    "CommandHistoryEntry",
+    "FileOperation",
+    "FileOperationType",
+    "ShellConfig",
+    # Service
+    "ShellService",
+    # Actions
+    "ExecuteCommandAction",
+    "ClearHistoryAction",
+    "get_shell_action_names",
+    # Providers
+    "ShellHistoryProvider",
+    "get_shell_provider_names",
+    # Utils
+    "validate_path",
+    "is_safe_command",
+    "extract_base_command",
+    "is_forbidden_command",
+    "DEFAULT_FORBIDDEN_COMMANDS",
+    "PLUGIN_NAME",
+    "PLUGIN_DESCRIPTION",
+]

elizaos_plugin_shell-2.0.0a4/elizaos_plugin_shell/_generated_prompts.py

@@ -0,0 +1,64 @@
+"""
+Auto-generated prompt templates
+DO NOT EDIT - Generated from ../../../../prompts/*.txt
+
+These prompts use Handlebars-style template syntax:
+- {{variableName}} for simple substitution
+- {{#each items}}...{{/each}} for iteration
+- {{#if condition}}...{{/if}} for conditionals
+"""
+
+from __future__ import annotations
+
+COMMAND_EXTRACTION_TEMPLATE = """# Extracting shell command from request
+{{recentMessages}}
+
+# Instructions: {{senderName}} wants to execute a shell command. Extract the COMPLETE shell command they want to run.
+
+IMPORTANT:
+1. Always return the FULL executable shell command, not just the content or partial command.
+2. If the user mentions installing something, create the appropriate brew/npm/apt command.
+3. If the user directly provides a command (like "brew install X"), use it exactly as provided.
+4. ALWAYS extract a command if the user is asking for ANY kind of system operation.
+
+Common patterns:
+- "run ls -la" -> command: "ls -la"
+- "execute npm test" -> command: "npm test"
+- "show me the files" or "list files" -> command: "ls -la"
+- "what's in this directory" -> command: "ls -la"
+- "check git status" -> command: "git status"
+- "navigate to src folder" -> command: "cd src"
+- "create a file called test.txt" -> command: "touch test.txt"
+- "write hello world to a file" -> command: "echo 'hello world' > file.txt"
+- "create hello.js with javascript code" -> command: "echo 'console.log(\\"Hello, World!\\");' > hello.js"
+- "create hello_world.py and write a python hello world script inside" -> command: "echo 'print(\\"Hello, World!\\")' > hello_world.py"
+- "make a new directory" -> command: "mkdir newdir"
+- "list files inside your filesystem" -> command: "ls -la"
+- "install orbstack" or "brew install orbstack" -> command: "brew install orbstack"
+- "install mullvad vpn" -> command: "brew install --cask mullvad-vpn"
+- "get system info" -> command: "system_profiler SPHardwareDataType"
+- "check memory usage" -> command: "vm_stat"
+- "install package" -> command: "brew install <package>"
+
+Special cases:
+- "Run it in your shell" or "execute it" -> Extract the command from previous context
+- "Install these" -> Look for package names in previous messages
+- Direct commands should be used exactly as provided
+
+Key rules:
+1. For file creation with content, use: echo 'content' > filename
+2. For listing files, use: ls -la (not just ls)
+3. Always include the echo command when writing to files
+4. Include all flags and arguments
+5. When user says "run it", "execute it", or similar, they want you to run the command
+
+Your response must be formatted as a JSON block:
+```json
+{
+  "command": "<complete shell command to execute>"
+}
+```"""
+
+__all__ = [
+    "COMMAND_EXTRACTION_TEMPLATE",
+]

elizaos_plugin_shell-2.0.0a4/elizaos_plugin_shell/actions/__init__.py

@@ -0,0 +1,23 @@
+from elizaos_plugin_shell.actions.clear_history import ClearHistoryAction
+from elizaos_plugin_shell.actions.execute_command import ExecuteCommandAction
+
+__all__ = [
+    "ExecuteCommandAction",
+    "ClearHistoryAction",
+    "get_shell_actions",
+    "get_shell_action_names",
+]
+
+
+def get_shell_actions() -> list:
+    return [
+        ExecuteCommandAction(),
+        ClearHistoryAction(),
+    ]
+
+
+def get_shell_action_names() -> list[str]:
+    return [
+        "EXECUTE_COMMAND",
+        "CLEAR_SHELL_HISTORY",
+    ]

elizaos_plugin_shell-2.0.0a4/elizaos_plugin_shell/actions/clear_history.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass
+
+from elizaos_plugin_shell.service import ShellService
+
+
+@dataclass
+class ActionExample:
+    user_message: str
+    agent_response: str
+
+
+@dataclass
+class ActionResult:
+    success: bool
+    text: str
+    data: dict | None = None
+    error: str | None = None
+
+
+class ClearHistoryAction:
+    CLEAR_KEYWORDS = ["clear", "reset", "delete", "remove", "clean", "wipe", "forget"]
+    HISTORY_KEYWORDS = ["history", "terminal", "shell", "command", "commands"]
+
+    @property
+    def name(self) -> str:
+        return "CLEAR_SHELL_HISTORY"
+
+    @property
+    def similes(self) -> list[str]:
+        return ["RESET_SHELL", "CLEAR_TERMINAL", "CLEAR_HISTORY", "RESET_HISTORY"]
+
+    @property
+    def description(self) -> str:
+        return "Clears the recorded history of shell commands for the current conversation"
+
+    def _has_clear_keyword(self, text: str) -> bool:
+        lower = text.lower()
+        return any(kw in lower for kw in self.CLEAR_KEYWORDS)
+
+    def _has_history_keyword(self, text: str) -> bool:
+        lower = text.lower()
+        return any(kw in lower for kw in self.HISTORY_KEYWORDS)
+
+    async def validate(self, message: dict, state: dict) -> bool:
+        text = message.get("content", {}).get("text", "")
+        return self._has_clear_keyword(text) and self._has_history_keyword(text)
+
+    async def handler(
+        self,
+        message: dict,
+        state: dict,
+        service: ShellService | None = None,
+    ) -> ActionResult:
+        if service is None:
+            return ActionResult(
+                success=False,
+                text="Shell service is not available.",
+                error="Shell service is not available",
+            )
+
+        conversation_id = message.get("room_id") or message.get("agent_id") or "default"
+        service.clear_command_history(conversation_id)
+
+        return ActionResult(
+            success=True,
+            text="Shell command history has been cleared.",
+        )
+
+    def examples(self) -> list[ActionExample]:
+        return [
+            ActionExample(
+                user_message="clear my shell history",
+                agent_response="Shell command history has been cleared.",
+            ),
+            ActionExample(
+                user_message="reset the terminal history",
+                agent_response="Shell command history has been cleared.",
+            ),
+            ActionExample(
+                user_message="delete command history",
+                agent_response="Shell command history has been cleared.",
+            ),
+        ]