Self-improving AI Employees for everyone
Shell (shell)
| Field | Value |
|---|---|
| Category | code_fs_process / filesystem |
| Backend handler | server/nodes/filesystem/shell/__init__.py::ShellNode.execute_op (dispatched via BaseNode.execute() + @Operation("execute")) |
| Backend | WorkspaceBackend.execute (with NushellBackend retained as a compatibility alias) in server/nodes/filesystem/_backend.py |
| Tests | server/tests/nodes/test_code_fs_process.py |
| Skill (if any) | server/skills/terminal/shell-skill/SKILL.md |
| Dual-purpose tool | yes - tool name shell_execute |
Purpose
Runs a short-lived shell command inside the per-workflow workspace. The native
WorkspaceBackend is constructed with inherit_env=True, so external tools
like npm, node, python, and git ARE reachable on PATH. It uses Nushell
when nu is installed and otherwise uses the host shell (sh or cmd.exe).
When Nushell is selected, && / || / $VAR / backticks / > do not use
bash semantics; see shell-skill/SKILL.md for conditional Nu guidance. When
Nushell is absent, all other syntax is interpreted by the host shell. For
long-running processes (dev servers, watchers), users are directed to
processManager; this node kills the command at
timeout. Node metadata describes this as short-lived execution from the
workflow workspace and marks the tool as open-world.
A pre-flight regex (_BASH_CHAIN_RE) rejects bash chain operators (&& / ||)
up-front with a corrective message before runner selection. They are therefore
rejected even when the fallback host shell would otherwise support them.
Runs synchronously under asyncio.to_thread() so the event loop keeps
servicing other requests while the command executes.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Not consumed by the handler |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
command |
string | (required, min_length=1) |
yes | - | Nushell command when nu is installed; otherwise a host-shell command |
cwd |
string | "" |
no | - | Declared param, but get_backend resolves the working dir from working_directory (not exposed) / ctx.workspace_dir, so cwd does NOT change the backend root |
timeout |
number | 30 (ge=1, le=600) |
no | - | Max seconds |
ShellParams uses extra="ignore" — working_directory is NOT exposed; the
backend root is ctx.workspace_dir.
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 shell_execute tool result) |
Output payload
{
stdout: string; // Combined output (backend merges stderr into stdout unless truncated); ANSI-stripped
exit_code: number; // 124 = timed out, else the process exit code
truncated: boolean; // Whether the backend truncated the output buffer
command: string; // Echo of the requested command
}
The plugin's ShellOutput (server/nodes/filesystem/shell/init.py) declares stdout / exit_code / truncated; command rides through on extra="allow".
Logic Flow
flowchart TD
A[execute_op] --> P{_BASH_CHAIN_RE matches<br/> && / || ?}
P -- yes --> Pe[raise NodeUserError:<br/>use ; or try{}catch{}]
P -- no --> C[get_backend workspace root<br/>WorkspaceBackend, inherited environment]
C --> D[to_thread backend.execute command, timeout]
D --> S[strip_ansi result.output]
S --> I{exit_code?}
I -- 124 --> I1[Log warning:<br/>Timed out]
I -- nonzero --> I2[Log warning:<br/>Non-zero exit]
I -- 0 --> I3[Log info: Completed]
I1 & I2 & I3 --> J[Return dict<br/>stdout, exit_code, truncated, command]
Decision Logic
- Validation: empty
commandis rejected by Pydanticmin_length=1(no manual check). A&&/||in the command ->raise NodeUserErrorbefore runner selection, with a Nushell-oriented hint (;ortry { … } catch { … }). - Runner selection:
_find_nu()cachesshutil.which("nu"). A match runs[nu, "-n", "--no-history", "-c", command]; otherwisesubprocess.run(command, shell=True, ...)delegates syntax to the host shell. - Inherited PATH:
WorkspaceBackend(inherit_env=True)— external tools (npm,node,python,git, …) ARE reachable. The previous "scrubbed PATH" framing no longer holds. AI agents are still steered towardprocess_managerfor long-running daemons (the shell kills attimeout). - Timeout handling:
timeoutis forwarded tobackend.execute(command, timeout=timeout). On timeout the backend kills the process and setsexit_code=124(POSIX convention). Logged at WARNING. - Non-zero exit still returns
success: true: the envelope-level success reflects whether the handler itself finished, not whether the command succeeded. Users must inspectexit_codein the payload. - Truncation: the native backend caps output at 100,000 characters by
default; when capped,
truncated=trueand the returnedstdoutcontains... Output truncated at 100000 bytes.after the retained prefix. For a non-zero process exit, the subsequently appendedExit code: Nline follows that marker. - ANSI stripping:
result.outputis run throughcore.ansi.strip_ansi(a wrapper overclick.unstyle) before being returned asstdout(and before the operator-log line), so colour/cursor codes from tools likevite/npmdon't render as garbage in the Output panel.click.unstyleis byte-faithful apart from the stripped escapes. - No catch-all error wrapper: the op does not wrap
backend.executein a try/except — non-zero exit codes are returned as a normal success envelope withexit_code != 0. An unexpected backend exception surfaces with a full traceback viaBaseNode.execute()'s generic path.
Side Effects
- Database writes: none.
- Broadcasts: none (but the process stdout/stderr is NOT streamed to
Terminal - only
processManagerdoes that). - External API calls: none.
- File I/O:
get_backendensures the workspace root exists. The command itself may read/write under that root. - Subprocess: one per call, via the backend's subprocess (synchronous, inherited PATH). Finished before the operation returns.
External Dependencies
- Python packages: standard library plus
core.ansi. - Environment variables:
WORKSPACE_BASE_DIR. - OS utilities: optional
nu(Nushell) on PATH; otherwise the platform host shell. Whatever the command references is reachable because PATH is inherited.
Edge cases & known limits
- Conditional shell grammar: space-delimited
&&/||are pre-flight-rejected. Other variables, substitutions, redirection, pipelines, and builtins follow Nushell grammar only whennuis installed; otherwise they follow the host shell. Seeshell-skill/SKILL.md. - Truncation corrupts JSON output: if a command prints JSON and the
backend truncates, the
stdoutstring becomes invalid JSON because the backend appends its human-readable truncation marker;truncated=trueprovides the machine-readable signal. exit_code=124is exit-code polysemy: real programs can legitimately exit 124; the handler does not distinguish those from the backend's timeout result.timeoutcovers the direct subprocess: the backend usessubprocess.run(..., timeout=)and kills the direct child on expiry. Descendant processes started by that shell may not be terminated as a process group.- Stdin is empty: the node exposes no way to pipe data into the
command -
input_datafrom upstream nodes does not reach it. - No environment variable override: users cannot inject env vars via
parameters; the backend inherits the server's env (
inherit_env=True). - Shell commands are open-world: filesystem helper methods enforce workspace containment, but a shell command can use absolute paths or invoke external programs. This preserves the node's historical shell behavior.
Related
- Skills using this as a tool:
shell-skill/SKILL.md,bash-skill/SKILL.md,powershell-skill/SKILL.md,wsl-skill/SKILL.md - Sibling nodes:
processManager,fileRead,fsSearch