Skip to content

Self-improving AI Employees for everyone

8.9 KB
Raw Blame

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 command is rejected by Pydantic min_length=1 (no manual check). A && / || in the command -> raise NodeUserError before runner selection, with a Nushell-oriented hint (; or try { … } catch { … }).
  • Runner selection: _find_nu() caches shutil.which("nu"). A match runs [nu, "-n", "--no-history", "-c", command]; otherwise subprocess.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 toward process_manager for long-running daemons (the shell kills at timeout).
  • Timeout handling: timeout is forwarded to backend.execute(command, timeout=timeout). On timeout the backend kills the process and sets exit_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 inspect exit_code in the payload.
  • Truncation: the native backend caps output at 100,000 characters by default; when capped, truncated=true and the returned stdout contains ... Output truncated at 100000 bytes. after the retained prefix. For a non-zero process exit, the subsequently appended Exit code: N line follows that marker.
  • ANSI stripping: result.output is run through core.ansi.strip_ansi (a wrapper over click.unstyle) before being returned as stdout (and before the operator-log line), so colour/cursor codes from tools like vite/npm don't render as garbage in the Output panel. click.unstyle is byte-faithful apart from the stripped escapes.
  • No catch-all error wrapper: the op does not wrap backend.execute in a try/except — non-zero exit codes are returned as a normal success envelope with exit_code != 0. An unexpected backend exception surfaces with a full traceback via BaseNode.execute()'s generic path.

Side Effects

  • Database writes: none.
  • Broadcasts: none (but the process stdout/stderr is NOT streamed to Terminal - only processManager does that).
  • External API calls: none.
  • File I/O: get_backend ensures 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 when nu is installed; otherwise they follow the host shell. See shell-skill/SKILL.md.
  • Truncation corrupts JSON output: if a command prints JSON and the backend truncates, the stdout string becomes invalid JSON because the backend appends its human-readable truncation marker; truncated=true provides the machine-readable signal.
  • exit_code=124 is exit-code polysemy: real programs can legitimately exit 124; the handler does not distinguish those from the backend's timeout result.
  • timeout covers the direct subprocess: the backend uses subprocess.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_data from 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