Self-improving AI Employees for everyone
Process Manager (processManager)
| Field | Value |
|---|---|
| Category | code_fs_process / process (plugin lives under server/nodes/utility/) |
| Backend handler | server/nodes/utility/process_manager/__init__.py::ProcessManagerNode.dispatch (dispatched via BaseNode.execute() + @Operation("dispatch")) |
| Service | server/services/process_service.py::ProcessService |
| Tests | server/tests/nodes/test_code_fs_process.py |
| Skill (if any) | server/skills/terminal/process-manager-skill/SKILL.md |
| Dual-purpose tool | yes - tool name process_manager |
Purpose
Manages long-running subprocesses (dev servers, watchers, build tools) for a
workflow. Unlike shell, processes spawned here inherit the
full system PATH and run asynchronously - their stdout/stderr streams into
the Terminal tab via broadcast_terminal_log() and persists to per-process log
files at <workspace>/<agent_node_id>/.processes/<name>/{stdout,stderr}.log.
Six operations: start, stop, restart, send_input, list, get_output
(default list). The plugin's dispatch op is a thin wrapper over the
ProcessService singleton; the singleton owns a {(workflow_id, name): ManagedProcess} dict, the streaming tasks, and the cleanup scheduler. The
wrapper's _unwrap raises NodeUserError on any service {"success": False}
envelope so the framework returns a clean failure.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Not consumed |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
operation |
start/stop/restart/list/send_input/get_output (Literal) |
list |
no | - | Operation to run |
name |
string | "" |
yes (all except list) |
- | Unique process name within the workflow (LLM "None" coerced to empty by _clean) |
command |
string | "" |
yes (start only) |
operation=start |
Command (ProcessService parses with shlex.split) |
cwd |
string | "" |
no | operation=start |
Working directory; defaults to <workspace>/<node_id> |
ports |
int[] | [] |
no | operation=start |
Listener ports reserved before spawn; occupied ports fail with PORT_IN_USE instead of launching |
env |
object (Dict[str,str]) | {} |
no | operation=start |
Extra environment variables, forwarded to ProcessService.start(extra_env=...) |
input_text |
string | "" |
yes (send_input) |
operation=send_input |
Text to write to stdin (newline auto-appended by the service) |
stream |
stdout/stderr (Literal) |
stdout |
no | operation=get_output |
Stream to read for get_output |
tail |
number | 100 (ge=1, le=10000) |
no | operation=get_output |
Tail N lines |
ProcessManagerParams uses extra="ignore". There are NO toolName /
toolDescription / working_directory / text / offset params (the old
card listed pre-Wave-11 frontend fields). get_output is always called with
offset=0.
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | Standard envelope payload (node declares only input-main / output-main; usable_as_tool=True exposes the same payload as the process_manager tool result) |
Output payload per operation
The shapes below are whatever ProcessService returns (passed through _unwrap).
The plugin's own ProcessManagerOutput declares operation / pid / status / output / processes (extra="allow").
start/stop/restart: theProcessInfodict from the service ({name, command, pid, status, started_at, exit_code, working_directory, log_dir, ...}).send_input: the service's send-input result dict.list:{processes: Array<ProcessInfo>}for the current workflow.get_output: the service's{lines, total, file, ...}dict.
Logic Flow
flowchart TD
A[dispatch] --> B[name = _clean params.name<br/>agent_dir = workspace/node_id]
B --> C[route on params.operation]
C --> D{operation}
D -- start --> S1{command blocked?<br/>rm, format, mkfs...}
S1 -- yes --> Sblk[Return error:<br/>Destructive commands blocked]
S1 -- no --> S2{process limit reached?}
S2 -- yes --> Slim[Return error:<br/>Process limit reached]
S2 -- no --> S3{name exists & running?}
S3 -- yes --> S3s[await self.stop]
S3 -- no --> S4
S3s --> S4[shlex.split command,<br/>cwd must be inside workspace_base]
S4 --> S5[mkdir log_dir, clear stdout.log/stderr.log]
S5 --> S6[create_subprocess_exec argv<br/>stdin/out/err=PIPE, PYTHONUNBUFFERED=1]
S6 --> S7[spawn stdout + stderr reader tasks]
S7 --> S8[Return success ProcessInfo]
D -- stop --> St1{process found & running?}
St1 -- no --> Sterr[Return error or idempotent success]
St1 -- yes --> St2[psutil kill tree, cancel reader tasks]
St2 --> St3[wait exit, schedule 60s cleanup]
St3 --> St4[Return success]
D -- restart --> R[stop then start with same cmd+cwd]
D -- send_input --> I1[svc.send_input name, wf, input_text]
D -- list --> L[svc.list_processes workflow_id]
D -- get_output --> O[svc.get_output name, wf, stream, tail, 0]
D -- unknown --> U[raise NodeUserError:<br/>Unknown operation]
Each service call (except list) is wrapped in _unwrap, which raises
NodeUserError if the service returned {"success": False}.
Decision Logic
_clean(): LLMs sometimes pass the literal string"None"for missing fields; the wrapper coerces""and"None"to empty (applied toname,command,cwd,input_text).cwdfallback: ifcwdis empty the wrapper usesagent_dir = <workspace>/<node_id>(each agent node gets its own subfolder). If the workspace is also empty,ProcessService.startfalls back to<workspace_base>/defaultand mkdir's it.- Workspace guardrail:
cwdmust resolve insideworkspace_base_resolvedviaPath.is_relative_to(). Violations return an error. - Destructive-command block: the service maintains a hard-coded list of
prefixes/tokens (
rm,rmdir,del,rd,remove-item,format,mkfs,dd if=,shred,> /dev/,chmod 777,chmod -r) and refuses any command that matches. Users are told to useshell_executeinstead. - Process limit:
max_processes(default 10) caps the number of concurrently-running processes. Stopped/error entries do not count. When at the limit, a newstartreturns an error; restarting an existing entry is still allowed. - Duplicate name handling: starting a name that already exists and is
running triggers an implicit
stopfirst; the new process inherits the samelog_dir(cleared before spawn). - PATH inheritance:
env = {**os.environ, "PYTHONUNBUFFERED": "1"}. The full system PATH is available - this is the main distinction from the sandboxed shell node. - ANSI-stripped at capture:
_read_streamruns each decoded line throughcore.ansi.strip_ansi(a wrapper overclick.unstyle) BEFORE the log-file write /broadcast_terminal_log/line_handler, so colour + cursor/erase codes from build tools (vite/npm/…) render as clean text in the Terminal tab, the persisted logs, andget_output.click.unstyleis byte-faithful apart from the stripped escapes (unlikerich.Text.from_ansi, which drops trailing newlines). - Exit code capture: only the stdout reader task fulfils
exit_codeon EOF viaprocess.wait()with a 5s timeout. Status becomesstopped(exit=0) orerror(nonzero). - Auto cleanup: 60 seconds after a process exits,
_cleanup_completedremoves its log directory and drops it from the tracking dict. Fast consumers must callget_outputbefore the grace window.
Side Effects
- Database writes: none.
- Broadcasts:
- Every streamed stdout/stderr line fires
broadcast_terminal_log({timestamp, level, message, source: "process:<name>"}).
- Every streamed stdout/stderr line fires
- External API calls: none.
- File I/O:
<workspace>/<node_id>/.processes/<name>/stdout.log<workspace>/<node_id>/.processes/<name>/stderr.log- Appended line-by-line by the reader tasks; cleared on each
startand removed onstop/shutdown.
- Subprocess:
asyncio.create_subprocess_exec(*argv, stdin/out/err=PIPE, cwd=..., env=...).psutil.Process(pid).children(recursive=True)+.kill()for tree termination.
External Dependencies
- Python packages:
asyncio,psutil,shlex,shutil. - Services:
ProcessServicesingleton (global).set_broadcaster()must be called at startup for Terminal streaming to reach the frontend. - OS utilities: whatever the user command references - full PATH.
Edge cases & known limits
shlex.splitis POSIX-style even on Windows: Windows-style backslashes inside quotes may be mis-split. Complex PowerShell invocations are fragile; users are guided toward a wrapper script or to use thebash/wslvariants.- Blocked-commands list is substring-based:
"rm "matching checks for leading and mid-string occurrences, but a command likepython -c "os.system('rm -rf ...')"slips through because it does not start withrmand the wordrmdoes not appear with a leading space. - 60-second cleanup race: if an agent polls
get_outputat 65s it may hit{lines: [], total: 0, file: ""}with no hint that the process ever existed. send_inputrequires trailing newline: the handler appends\nonly iftextdoes not already end with one.exit_code=-1on stop timeout: ifprocess.wait()does not return within 3s after the kill,exit_code=-1is written - ambiguous with real exit codes that happen to be negative (rare on POSIX, common on Windows).- stdout-only exit capture: if a process writes only to stderr and
closes stdout immediately, the stderr reader runs to completion but the
status stays
runninguntil the handler is asked again. This is a known race in_read_stream. - No resource limits: CPU/memory caps are NOT applied; rogue processes can exhaust the host.
- Log dir name collision: two concurrent
startcalls with the samenamewill serialise via thestopguard, but a partial cleanup from a previous run can leave stale files if the server was killed mid-cleanup.
Related
- Skills using this as a tool:
process-manager-skill/SKILL.md - Sibling nodes:
shell,fileRead,fsSearch - Architecture docs: DESIGN.md, Status Broadcaster