| 1 | # Code Execution |
| 2 | |
| 3 | Run terminal commands and execute Python or Node.js code through Agent Zero using persistent shell sessions. |
| 4 | |
| 5 | ## What It Does |
| 6 | |
| 7 | This plugin provides the code execution tool used by agents for development tasks. It supports: |
| 8 | |
| 9 | - **Terminal commands** in interactive shell sessions |
| 10 | - **Python execution** through `ipython -c` |
| 11 | - **Node.js execution** through `node /exe/node_eval.js` |
| 12 | - **Persistent sessions** keyed by session number |
| 13 | - **Session reset and output retrieval** |
| 14 | - **Local or SSH-backed execution** depending on plugin configuration |
| 15 | |
| 16 | ## Main Behavior |
| 17 | |
| 18 | - **Persistent shells** |
| 19 | - Maintains per-session shell state in agent data so subsequent calls can reuse the same terminal session. |
| 20 | - Groups multi-line terminal input in the current shell so only the final prompt marks the command complete. |
| 21 | - **Multiple runtimes** |
| 22 | - Dispatches requests based on `runtime`: `terminal`, `python`, `nodejs`, `output`, or `reset`. |
| 23 | - **Remote execution support** |
| 24 | - Can open SSH interactive sessions instead of local shells when configured. |
| 25 | - **Streaming output** |
| 26 | - Continuously reads shell output, updates the current log item, and detects progress while commands are running. |
| 27 | - Detects local shell exit and SSH channel termination when strict mode, `exit`, or a lost connection prevents a final prompt from appearing. |
| 28 | - **Long-running work** |
| 29 | - Keeps normal command execution responsive while giving the `output` runtime longer polling windows for builds, installs, servers, tests, and training jobs. |
| 30 | - **Safety around running sessions** |
| 31 | - Tracks whether a shell is currently busy and can prevent overlapping commands unless explicitly allowed. |
| 32 | |
| 33 | ## Key Files |
| 34 | |
| 35 | - **Tool** |
| 36 | - `tools/code_execution_tool.py` contains runtime dispatch, session lifecycle, and streaming output logic. |
| 37 | - **Helpers** |
| 38 | - `helpers/shell_local.py` provides the local interactive shell implementation. |
| 39 | - `helpers/shell_ssh.py` provides the SSH-backed interactive shell implementation. |
| 40 | - **Configuration** |
| 41 | - `default_config.yaml` defines execution, prompt, and timeout settings. |
| 42 | - **Prompts** |
| 43 | - `prompts/` contains the response templates shown to the agent. |
| 44 | |
| 45 | ## Configuration Scope |
| 46 | |
| 47 | - **Settings section**: `agent` |
| 48 | - **Per-project config**: `true` |
| 49 | - **Per-agent config**: `true` |
| 50 | - **Always enabled**: `false` |
| 51 | |
| 52 | ## Plugin Metadata |
| 53 | |
| 54 | - **Name**: `_code_execution` |
| 55 | - **Title**: `Code Execution` |
| 56 | - **Description**: Code execution tool supporting terminal, Python, and Node.js runtimes via local TTY or SSH. |