Kill Bash

Terminates a running background bash shell by its ID.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

Inputs

• Shell ID - string - The ID of the background shell to kill (required).

Outputs

• Success - bool - Whether the shell was successfully killed.
• Message - string - Status message about the operation.
• Kill Info - object - Detailed information about the kill operation:
  • shellID - The shell ID
  • found - Whether the shell was found
  • previousStatus - Status before kill attempt
  • command - The original command
  • killed - Whether the process was actually killed
  • error - Error message if kill failed

How It Works

The Kill Bash node terminates background shell processes. When executed, the node:

1. Validates the shell ID is provided
2. Looks up the background shell in the registry
3. Checks if the process exists and is running
4. Attempts graceful termination:
   • Sends SIGTERM signal first (graceful shutdown)
   • If SIGTERM fails, sends SIGKILL signal (force kill)
5. Updates shell status in registry
6. Removes shell from registry if killed or already completed
7. Returns success status and detailed information

Requirements

• Valid shell ID from a Shell node background execution
• Background shell must exist in the registry
• Appropriate permissions to send signals to the process

Error Handling

The node will return specific errors in the following cases:

• Missing shell ID - "Shell ID is required"
• Empty shell ID - "Shell ID cannot be empty"
• Shell not found - "No background shell found with ID: {{shellID}}"

Note: The node returns error information in outputs rather than throwing errors, allowing workflows to continue.

Usage Examples

Basic Termination

Shell ID: abc123-xyz789

Conditional Termination

1. Bash Output: check status
2. If status = "running" AND timeout exceeded:
   - Kill Bash: `{{shell_id}}`

Cleanup After Processing

1. Shell (Background): long_running_process
2. Loop: monitor with Bash Output
3. When complete:
   - Kill Bash: cleanup the shell

Emergency Stop

Shell ID: abc123-xyz789

Termination Process

The node uses a two-step termination approach:

Step 1: SIGTERM (Graceful)

• Sends SIGTERM signal to the process
• Allows process to clean up resources
• Process can catch this signal and exit gracefully
• Updates status to "terminated" with exit code -15

Step 2: SIGKILL (Force)

• If SIGTERM fails, sends SIGKILL
• Process cannot catch or ignore this signal
• Forces immediate termination
• Updates status to "killed" with exit code -9

Status Handling

The node handles different shell states:

Running Process

• Sends termination signal
• Updates status
• Removes from registry
• Returns success: true

Already Completed

• No action needed
• Removes from registry
• Returns success: true
• Message indicates already completed

Already Failed

• No action needed
• Removes from registry
• Returns success: true
• Message indicates already failed

Not Found

• Returns success: false
• Message indicates shell not found
• Returns error in outputs

Usage Notes

• SIGTERM is always tried first for graceful shutdown
• SIGKILL is used only if SIGTERM fails
• The shell is removed from registry after successful kill
• Already completed/failed shells are cleaned up without error
• Exit codes: -15 for SIGTERM, -9 for SIGKILL
• Process children may not be killed (depends on process group)
• On Windows, the termination approach may differ

Common Use Cases

Timeout Handling

Kill processes that exceed maximum execution time.

Resource Management

Terminate processes when resource limits are reached.

Error Recovery

Stop processes that have encountered errors.

Cleanup Operations

Remove completed background processes from registry.

User Cancellation

Allow users to cancel long-running operations.

System Shutdown

Cleanly terminate all background processes before shutdown.

Best Practices

• Check status first with Bash Output before killing
• Retrieve final output before killing if needed
• Use timeouts to automatically kill hung processes
• Handle both success and failure in your workflow
• Clean up completed processes to free resources
• Wait briefly after kill before checking again
• Log kill operations for audit and debugging
• Consider graceful shutdown before forcing kill

Example Workflows

Timeout-Based Kill

1. Shell (Background): command
   Output: shell_id

2. Loop (max iterations: 60):
   - Delay: 5 seconds
   - Bash Output: check status
   - If status = "completed": break
   - If iteration = 60:
     - Kill Bash: `{{shell_id}}`
     - Log: "Process timed out and was killed"

Conditional Kill

1. Bash Output: get latest output and status
2. If stderr contains "FATAL ERROR":
   - Kill Bash: `{{shell_id}}`
   - Handle error

Cleanup All Background Shells

For each shell_id in active_shells:
  - Bash Output: check status
  - If status != "running":
    - Kill Bash: cleanup

Error Scenarios

Shell Not Found

• Success: false
• Message: "No background shell found with ID: {{id}}"
• Kill Info includes found: false

Process Already Terminated

• Success: true
• Message: "Shell {{id}} was already {{status}}"
• Process removed from registry

Kill Failed

• Success: false
• Message: "Failed to kill shell {{id}}: {{error}}"
• Kill Info includes error details

Platform Differences

Unix/Linux

• Uses SIGTERM (15) and SIGKILL (9) signals
• Process groups may need separate handling

Windows

• Uses process termination APIs
• Signal semantics may differ
• Child processes may need separate termination

Comparison with Other Nodes

• Kill Bash vs Shell: Kill Bash terminates processes; Shell starts them
• Kill Bash vs Bash Output: Kill Bash stops processes; Bash Output reads their output
• Kill Bash vs Edit/Write: Kill Bash manages processes; Edit/Write manage files