process-manager-skill

# Process Manager Tool

Manage long-running processes with **full system PATH access**. Use this for anything that needs `npm`, `python`, `node`, or runs as a persistent server/watcher.

## Security

The process manager **blocks destructive file commands** to prevent accidental deletion outside the agent's workspace. Use `shell_execute` for file operations instead (sandboxed, no PATH, confined to workspace).

**Blocked commands:** `rm`, `rmdir`, `del`, `rd`, `Remove-Item`, `format`, `mkfs`, `dd`, `shred`, `chmod 777`

**Allowed:** `npm`, `python`, `node`, `pip`, `cargo`, `go`, servers, build tools, installers

## Operations

### start
Launch a process. Output streams to the Terminal tab and is saved to log files.
```json
{"operation": "start", "name": "dev-server", "command": "python -m http.server 8080"}
```

### stop
Kill a process and its entire process tree.
```json
{"operation": "stop", "name": "dev-server"}
```

### restart
Stop then re-launch with the same command.
```json
{"operation": "restart", "name": "dev-server"}
```

### list
Show all running processes for this workflow.
```json
{"operation": "list"}
```

### get_output
Read output from a process's log file. Use `tail` to get last N lines, `stream` to choose stdout or stderr.
```json
{"operation": "get_output", "name": "dev-server", "stream": "stdout", "tail": 20}
```
Returns `{"lines": [...], "total": 150, "file": "/path/to/stdout.log"}`.

### send_input
Write text to a process's stdin (newline appended automatically).
```json
{"operation": "send_input", "name": "dev-server", "text": "quit"}
```

## Shell vs Process Manager

| Need | Tool | Why |
|------|------|-----|
| `ls`, `cat`, `find`, `grep` | **shell_execute** | Sandboxed, fast, no PATH |
| `rm`, `mv`, `cp`, file ops | **shell_execute** | Sandboxed, confined to workspace |
| `npm install`, `pip install` | **process_manager** | Needs PATH |
| `python script.py` | **process_manager** | Needs PATH |
| `npm run dev`, `flask run` | **process_manager** | Long-running, streams output |
| Dev servers, watchers | **process_manager** | Persistent, log files |

## Output Log Files

Each process writes to its own log files in the agent's workspace:
```
{workspace}/{agent_node_id}/.processes/{process_name}/
  stdout.log    # Standard output
  stderr.log    # Error output
```

Use `get_output` to read them selectively. The agent can also read these files directly with the `file_read` tool.

## OS-Specific Commands

Commands differ by platform. Refer to:
- **bash-skill** -- Linux/macOS (apt, brew, lsof, kill, curl)
- **powershell-skill** -- Windows (Get-Process, Stop-Process, Invoke-WebRequest)
- **wsl-skill** -- Running Linux tools on Windows (prefix with `wsl`)

Detect the OS first:
```json
{"operation": "start", "name": "os", "command": "python -c \"import platform; print(platform.system())\""}
```
Returns `Windows`, `Linux`, or `Darwin` (macOS).

## Guidelines

- Always give processes a meaningful **name** so you can stop/check them later
- Use **get_output** after starting to verify the process launched correctly
- Use **stop** to clean up processes when done -- don't leave servers running
- **Do NOT use process_manager for file deletion** -- use shell_execute instead
- Processes are automatically killed when the server shuts down
- Max concurrent processes: configurable in Settings (default: 10)
- Output streams to the Terminal tab in real-time