@elizaos/plugin-shell 1.2.0 → 2.0.0-alpha.10

package/dist/utils/shellUtils.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Shell Utilities - Platform-specific shell configuration and helpers
+ * Ported from otto shell-utils.ts and bash-tools.shared.ts
+ */
+import type { ChildProcess, ChildProcessWithoutNullStreams, SpawnOptions } from "node:child_process";
+import { spawn } from "node:child_process";
+/**
+ * Get shell configuration for the current platform
+ */
+export declare function getShellConfig(): {
+    shell: string;
+    args: string[];
+};
+/**
+ * Sanitize binary output by removing control characters
+ */
+export declare function sanitizeBinaryOutput(text: string): string;
+/**
+ * Kill a process tree (cross-platform)
+ */
+export declare function killProcessTree(pid: number): void;
+/**
+ * Kill a session's process
+ */
+export declare function killSession(session: {
+    pid?: number;
+    child?: ChildProcessWithoutNullStreams;
+}): void;
+/**
+ * Coerce environment object to Record<string, string>
+ */
+export declare function coerceEnv(env?: NodeJS.ProcessEnv | Record<string, string>): Record<string, string>;
+/**
+ * Resolve working directory with fallback
+ */
+export declare function resolveWorkdir(workdir: string, warnings: string[]): string;
+/**
+ * Clamp a number to a range with a default value
+ */
+export declare function clampNumber(value: number | undefined, defaultValue: number, min: number, max: number): number;
+/**
+ * Read an environment variable as an integer
+ */
+export declare function readEnvInt(key: string): number | undefined;
+/**
+ * Chunk a string into smaller pieces
+ */
+export declare function chunkString(input: string, limit?: number): string[];
+/**
+ * Safely slice a string respecting UTF-16 surrogate pairs
+ */
+export declare function sliceUtf16Safe(str: string, start: number, end?: number): string;
+/**
+ * Truncate string in the middle with ellipsis
+ */
+export declare function truncateMiddle(str: string, max: number): string;
+/**
+ * Slice log lines with optional offset and limit
+ */
+export declare function sliceLogLines(text: string, offset?: number, limit?: number): {
+    slice: string;
+    totalLines: number;
+    totalChars: number;
+};
+/**
+ * Derive a session name from a command
+ */
+export declare function deriveSessionName(command: string): string | undefined;
+/**
+ * Format duration in human-readable format
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Pad a string to a minimum width
+ */
+export declare function pad(str: string, width: number): string;
+export type SpawnFallback = {
+    label: string;
+    options: SpawnOptions;
+};
+export type SpawnWithFallbackResult = {
+    child: ChildProcess;
+    usedFallback: boolean;
+    fallbackLabel?: string;
+};
+type SpawnWithFallbackParams = {
+    argv: string[];
+    options: SpawnOptions;
+    fallbacks?: SpawnFallback[];
+    spawnImpl?: typeof spawn;
+    retryCodes?: string[];
+    onFallback?: (err: unknown, fallback: SpawnFallback) => void;
+};
+/**
+ * Format a spawn error for display
+ */
+export declare function formatSpawnError(err: unknown): string;
+/**
+ * Spawn a process with fallback options on certain error codes
+ */
+export declare function spawnWithFallback(params: SpawnWithFallbackParams): Promise<SpawnWithFallbackResult>;
+export {};
+//# sourceMappingURL=shellUtils.d.ts.map

package/dist/utils/shellUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shellUtils.d.ts","sourceRoot":"","sources":["../../utils/shellUtils.ts"],"names":[],"mappings":"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"}

package/dist/vitest.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("vite").UserConfig;
+export default _default;
+//# sourceMappingURL=vitest.config.d.ts.map

package/dist/vitest.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":";AAEA,wBAMG"}

package/package.json

@@ -1,39 +1,126 @@
 {
-  "name": "@elizaos/plugin-shell",
-  "version": "1.2.0",
-  "description": "Shell command execution plugin for ElizaOS with directory restrictions and history tracking",
-  "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "keywords": ["eliza", "plugin", "shell", "terminal", "command", "history"],
-  "author": "elizaOS",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/elizaos/eliza.git"
-  },
-  "dependencies": {
-    "@elizaos/core": "^1.2.0",
-    "cross-spawn": "^7.0.6",
-    "joi": "^17.13.3"
-  },
-  "devDependencies": {
-    "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^20.11.16",
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3",
-    "vitest": "^1.2.1"
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  }
-}
+	"name": "@elizaos/plugin-shell",
+	"version": "2.0.0-alpha.10",
+	"description": "Shell history and observability plugin for ElizaOS",
+	"type": "module",
+	"main": "dist/index.js",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"sideEffects": false,
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/elizaos/eliza.git"
+	},
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"keywords": [
+		"eliza",
+		"plugin",
+		"shell",
+		"terminal",
+		"command",
+		"history"
+	],
+	"author": "elizaOS",
+	"license": "MIT",
+	"dependencies": {
+		"@elizaos/core": "2.0.0-alpha.114",
+		"cross-spawn": "^7.0.6",
+		"zod": "^4.3.6"
+	},
+	"optionalDependencies": {
+		"@lydell/node-pty": "^1.1.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.11",
+		"@types/cross-spawn": "^6.0.6",
+		"@types/node": "^25.0.3",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.0"
+	},
+	"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": "echo \"Typecheck skipped for release\"",
+		"lint": "echo \"Lint skipped for release\"",
+		"lint:check": "bun run lint",
+		"format": "bunx @biomejs/biome format --write .",
+		"format:check": "bunx @biomejs/biome format ."
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"agentConfig": {
+		"pluginType": "elizaos:plugin:1.0.0",
+		"pluginParameters": {
+			"SHELL_ALLOWED_DIRECTORY": {
+				"type": "string",
+				"description": "The directory that shell commands are restricted to. Commands cannot execute outside this directory.",
+				"required": true,
+				"sensitive": false
+			},
+			"SHELL_TIMEOUT": {
+				"type": "number",
+				"description": "Maximum command execution timeout in milliseconds",
+				"required": false,
+				"default": 30000,
+				"sensitive": false
+			},
+			"SHELL_FORBIDDEN_COMMANDS": {
+				"type": "string",
+				"description": "Comma-separated list of additional forbidden commands",
+				"required": false,
+				"sensitive": false
+			},
+			"SHELL_MAX_OUTPUT_CHARS": {
+				"type": "number",
+				"description": "Maximum output characters to capture from commands",
+				"required": false,
+				"default": 200000,
+				"sensitive": false
+			},
+			"SHELL_BACKGROUND_MS": {
+				"type": "number",
+				"description": "Default milliseconds to wait before backgrounding commands",
+				"required": false,
+				"default": 10000,
+				"sensitive": false
+			},
+			"SHELL_ALLOW_BACKGROUND": {
+				"type": "boolean",
+				"description": "Whether to allow background command execution",
+				"required": false,
+				"default": true,
+				"sensitive": false
+			},
+			"SHELL_JOB_TTL_MS": {
+				"type": "number",
+				"description": "Time-to-live for finished session records in milliseconds",
+				"required": false,
+				"default": 1800000,
+				"sensitive": false
+			}
+		}
+	},
+	"milady": {
+		"platforms": [
+			"node"
+		],
+		"runtime": "node",
+		"platformDetails": {
+			"node": "Default export (Node.js)"
+		}
+	}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 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,352 +0,0 @@
-# @elizaos/plugin-shell
-
-A secure shell command execution plugin for ElizaOS that allows agents to run terminal commands within a restricted directory with command history tracking.
-
-## 🚨 TL;DR - Quick Setup
-
-**Just want your agent to execute commands? Here's the fastest path:**
-
-1. **Install the plugin**:
-   ```bash
-   cd your-eliza-project
-   bun add @elizaos/plugin-shell
-   ```
-
-2. **Create/update your `.env`**:
-   ```bash
-   SHELL_ENABLED=true
-   SHELL_ALLOWED_DIRECTORY=/path/to/safe/directory
-   ```
-
-3. **Add to your character**:
-   ```typescript
-   const character = {
-       // ... other config
-       plugins: ["@elizaos/plugin-shell"],
-   };
-   ```
-
-4. **Run:** `bun start`
-
-⚠️ **Security note:** The agent can ONLY execute commands within `SHELL_ALLOWED_DIRECTORY` - choose wisely!
-
-## 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
-- ✅ **Shell context provider**: Provides command history and working directory to agent context
-- ✅ **Output capture**: Returns both stdout and stderr from executed commands
-- ✅ **Safety first**: Disabled by default, requires explicit enabling
-
-## Prerequisites
-
-- Node.js 20+ and bun installed
-- ElizaOS project set up
-- A designated safe directory for command execution
-
-## 🚀 Quick Start
-
-### Step 1: Install the Plugin
-
-```bash
-# Using bun (recommended)
-bun add @elizaos/plugin-shell
-
-# Using npm
-npm install @elizaos/plugin-shell
-
-# Using pnpm
-pnpm add @elizaos/plugin-shell
-```
-
-### Step 2: Configure Environment Variables
-
-Create or edit `.env` file in your project root:
-
-```bash
-# REQUIRED: Enable the shell plugin (disabled by default for safety)
-SHELL_ENABLED=true
-
-# REQUIRED: Set the allowed directory (commands can only run here)
-SHELL_ALLOWED_DIRECTORY=/home/user/safe-workspace
-
-# 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
-```
-
-### Step 3: Add to Your Character
-
-```typescript
-import { Character } from "@elizaos/core";
-
-const myCharacter: Character = {
-    name: "DevAssistant",
-    description: "A helpful development assistant",
-    plugins: ["@elizaos/plugin-shell"],  // Add the shell plugin
-    // ... rest of your character config
-};
-```
-
-### Step 4: Run Your Agent
-
-```bash
-bun start
-```
-
-Your agent can now execute shell commands! Try:
-- "Show me what files are in this directory"
-- "Run ls -la"
-- "Create a file called hello.txt"
-- "Check the git status"
-
-## 📋 Available Actions
-
-### EXECUTE_COMMAND
-
-Executes ANY shell command within the allowed directory, including file operations.
-
-**Examples:**
-- `run ls -la` - List files with details
-- `execute npm test` - Run tests
-- `show me the current directory` - Execute pwd
-- `create a file called hello.txt` - Creates a new file
-- `write 'Hello World' to output.txt` - Write content to file
-- `make a new directory called src` - Create directory
-- `check git status` - Show git repository status
-
-### CLEAR_SHELL_HISTORY
-
-Clears the command history for the current conversation.
-
-**Examples:**
-- `clear my shell history`
-- `reset the terminal history`
-- `delete command history`
-
-## 🧠 Shell History Provider
-
-The plugin includes a `SHELL_HISTORY` provider that makes the following information available to the agent:
-
-- **Recent Commands**: Last 10 executed commands with their outputs
-- **Current Working Directory**: The current directory within the allowed path
-- **Allowed Directory**: The configured safe directory boundary
-- **File Operations**: Recent file creation, modification, and deletion operations
-
-This context helps the agent understand previous commands and maintain continuity in conversations.
-
-## 🔒 Security Considerations
-
-### 1. Directory Restriction
-The plugin enforces that ALL commands execute within `SHELL_ALLOWED_DIRECTORY`:
-- Attempts to navigate outside are blocked
-- Absolute paths outside the boundary are rejected
-- `cd ..` stops at the allowed directory root
-
-### 2. Forbidden Commands
-By default, these potentially dangerous commands are blocked:
-- **Destructive**: `rm`, `rmdir`
-- **Permission changes**: `chmod`, `chown`, `chgrp`
-- **System operations**: `shutdown`, `reboot`, `halt`, `poweroff`
-- **Process control**: `kill`, `killall`, `pkill`
-- **User management**: `sudo`, `su`, `passwd`, `useradd`, `userdel`
-- **Disk operations**: `format`, `fdisk`, `mkfs`, `dd`, `shred`
-
-**Note:** Safe file operations ARE allowed: `touch`, `echo`, `cat`, `mkdir`, `ls`, etc.
-
-### 3. Additional Safety Features
-- **No Shell Expansion**: Commands execute without dangerous shell interpretation
-- **Timeout Protection**: Commands auto-terminate after timeout
-- **Command History**: All executed commands are logged for audit
-- **Path Traversal Protection**: Blocks `../` and similar patterns
-
-## 🎯 Common Use Cases
-
-### Development Assistant
-```bash
-SHELL_ALLOWED_DIRECTORY=/home/user/projects
-SHELL_TIMEOUT=120000  # 2 minutes for build commands
-```
-
-Your agent can help with:
-- Running tests and builds
-- Git operations
-- File management
-- Code generation
-
-### System Monitor
-```bash
-SHELL_ALLOWED_DIRECTORY=/var/log
-SHELL_FORBIDDEN_COMMANDS=rm,mv,cp,chmod,chown  # Read-only access
-```
-
-Your agent can:
-- Check log files
-- Monitor system status
-- Generate reports
-
-### Content Creator
-```bash
-SHELL_ALLOWED_DIRECTORY=/home/user/content
-```
-
-Your agent can:
-- Create and organize files
-- Process text files
-- Manage content structure
-
-## 🔧 Troubleshooting
-
-### Plugin Not Working
-
-**Checklist:**
-- ✅ Is `SHELL_ENABLED=true` in your `.env`?
-- ✅ Does `SHELL_ALLOWED_DIRECTORY` exist and is accessible?
-- ✅ Is the plugin added to your character's `plugins` array?
-- ✅ Check logs for "Shell service initialized"
-
-### "Shell plugin is disabled"
-
-**Solution:** Set `SHELL_ENABLED=true` in your `.env` file
-
-### "Cannot navigate outside allowed directory"
-
-**This is a security feature!** The agent cannot access files outside `SHELL_ALLOWED_DIRECTORY`.
-
-**Solution:** 
-- Move your work to the allowed directory, OR
-- Change `SHELL_ALLOWED_DIRECTORY` to include your work area
-
-### "Command is forbidden by security policy"
-
-The command you're trying to run is in the forbidden list.
-
-**Solution:** 
-- Use alternative safe commands, OR
-- Remove the command from `SHELL_FORBIDDEN_COMMANDS` if you trust your environment
-
-### Command Not Found
-
-The command might not be in the system PATH.
-
-**Solution:**
-- Use full paths: `/usr/bin/git` instead of `git`
-- Ensure required tools are installed
-
-## 📚 Advanced Configuration
-
-### Per-Conversation History
-
-Each conversation maintains its own:
-- Command history (last 100 commands)
-- Working directory context
-- File operation tracking
-
-This ensures privacy between different users/conversations.
-
-### Custom Timeout for Long Operations
-
-```bash
-# For development environments with slow builds
-SHELL_TIMEOUT=300000  # 5 minutes
-```
-
-### Minimal Forbidden Commands
-
-```bash
-# For trusted environments
-SHELL_FORBIDDEN_COMMANDS=shutdown,reboot
-```
-
-### Read-Only Mode
-
-```bash
-# Block all write operations
-SHELL_FORBIDDEN_COMMANDS=rm,rmdir,mv,cp,touch,mkdir,echo,cat,chmod,chown,dd
-```
-
-## 🧪 Development & Testing
-
-```bash
-# Clone the repository
-git clone https://github.com/elizaos/eliza.git
-cd eliza/packages/plugin-shell
-
-# Install dependencies
-bun install
-
-# Build the plugin
-bun run build
-
-# Run tests
-bun test
-
-# Run with debug logging
-DEBUG=eliza:* bun start
-```
-
-### Testing Your Setup
-
-1. **Test Basic Commands**: Try `ls`, `pwd`, `echo test`
-2. **Test Restrictions**: Try `cd /` (should fail)
-3. **Test History**: Run commands then ask "what commands have I run?"
-4. **Test File Ops**: Create a file, then check history for tracking
-
-## 📊 How It Works
-
-### Architecture
-```
-┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐
-│   Your Agent    │────▶│  Shell Plugin    │────▶│  cross-spawn   │
-│                 │     │                  │     │                │
-│  "run ls -la"   │     │ - Path validation│     │ - Secure exec  │
-│                 │     │ - History track  │     │ - No shell     │
-└─────────────────┘     │ - Timeout mgmt   │     └────────────────┘
-                        └──────────────────┘
-```
-
-### Execution Flow
-1. Agent receives command request
-2. Plugin validates command safety
-3. Checks directory boundaries
-4. Executes via `cross-spawn` (no shell)
-5. Captures output and errors
-6. Tracks in conversation history
-7. Returns formatted result
-
-## 🤝 Contributing
-
-Contributions are welcome! Please:
-1. Check existing issues first
-2. Follow the code style
-3. Add tests for new features
-4. Update documentation
-
-### Running Plugin Tests
-
-```bash
-# Run all tests
-bun test
-
-# Run specific test file
-bun test src/__tests__/shellHistory.test.ts
-
-# Run tests in watch mode
-bun test --watch
-```
-
-## 📖 Additional Resources
-
-- [ElizaOS Documentation](https://github.com/elizaos/eliza)
-- [Security Best Practices](https://owasp.org/www-community/attacks/Command_Injection)
-- [Cross-spawn Documentation](https://github.com/moxystudio/node-cross-spawn)
-
-## 📝 License
-
-This plugin is part of the ElizaOS project. See the main repository for license information.