Process Management

The ProcessSupervisor manages the lifecycle of all external processes -- tool executions, delegated agent runs, and long-running commands. It provides non-blocking execution, configurable timeout handling, and background process tracking.

How It Works

When an agent calls a tool, the supervisor:

1. Starts the process asynchronously
2. Waits up to default_timeout seconds for completion
3. If the process completes, returns the result directly
4. If the timeout is reached, takes the configured on_timeout action (background, kill, or wait)
5. Logs all output to files in ~/.supyagent/process_logs/

The supervisor runs on a persistent background thread with its own asyncio event loop. This allows backgrounded processes to continue running even after the timeout returns control to the agent.

Configuration

Configure the supervisor in your agent YAML under the supervisor key:

name: myagent
model:
  provider: anthropic/claude-sonnet-4-5-20250929

supervisor:
  default_timeout: 60           # Seconds before timeout action
  on_timeout: background        # background | kill | wait
  max_background_processes: 10  # Max concurrent background processes

  # Patterns for tools that always run in background
  force_background_patterns:
    - "*__start_server*"
    - "*__run_server*"
    - "*__serve*"

  # Patterns for tools that always run synchronously
  force_sync_patterns:
    - "*__read_*"
    - "*__list_*"
    - "*__get_*"

  # Per-tool overrides
  tool_settings:
    "shell__run_command":
      timeout: 120
      mode: auto
    "web__fetch_url":
      timeout: 30
      mode: sync

  # Delegation settings
  default_delegation_mode: subprocess
  delegation_timeout: 600

Configuration Fields

Timeout Actions

When a tool execution exceeds the default_timeout, the supervisor takes one of three actions:

background (default)

The process is promoted to a background process. The agent receives an immediate response with the process ID and can check on it later:

{
  "ok": true,
  "data": {
    "status": "backgrounded",
    "process_id": "tool_143025_1",
    "pid": 12345,
    "message": "Process promoted to background after 60s. Use /process tool_143025_1 to check status."
  }
}

kill

The process is terminated immediately (SIGTERM, then SIGKILL after 5 seconds). The agent receives an error:

{
  "ok": false,
  "error": "Process killed after 60s timeout",
  "process_id": "tool_143025_1"
}

wait

The supervisor continues waiting up to max_execution_time (hard limit of 300 seconds). If the hard limit is also exceeded, the process is killed.

Pattern-Based Execution Modes

Tool names follow the script__function format (double underscore). You can use glob patterns to force specific tools into background or synchronous mode:

Force Background Patterns

Tools matching these patterns start in the background immediately, without waiting for the timeout:

force_background_patterns:
  - "server__*"           # All server tools
  - "docker__run*"        # Docker run commands
  - "*__serve*"           # Any serve function
  - "*__start_server*"    # Any start_server function

This is useful for long-running processes like web servers, file watchers, or database processes.

Force Sync Patterns

Tools matching these patterns always wait for completion (using max_execution_time as the timeout):

force_sync_patterns:
  - "files__read_file"    # File reads should always complete
  - "files__write_file"   # File writes should always complete
  - "*__read_*"           # Any read operation
  - "*__list_*"           # Any list operation
  - "*__get_*"            # Any get operation

Per-Tool Settings

For fine-grained control, use tool_settings to override timeout and mode for specific tools:

tool_settings:
  "shell__run_command":
    timeout: 120          # Shell commands get 2 minutes
    mode: auto            # Use timeout-based behavior
  "web__fetch_url":
    timeout: 30           # Web fetches get 30 seconds
    mode: sync            # Always wait for completion
  "docker__build*":
    timeout: 300          # Docker builds get 5 minutes
    mode: auto

The mode field accepts:

• auto -- Use the default timeout-based behavior
• sync -- Always wait for completion
• background -- Always run in background

Background Process Lifecycle

Background processes go through these statuses:

PENDING -> RUNNING -> BACKGROUNDED -> COMPLETED | FAILED | KILLED

Built-in Process Management Tools

The agent automatically has access to three built-in tools for managing background processes:

list_processes

Lists all running and backgrounded processes with their status, PID, and start time.

get_process_output

Retrieves the output (stdout/stderr) from a background process by its process ID. Supports a tail parameter to limit the number of lines returned.

kill_process

Terminates a running or backgrounded process. Sends SIGTERM first, then SIGKILL after 5 seconds if the process does not exit.

CLI Process Commands

You can also manage processes from the CLI:

# List running processes
supyagent process list
supyagent process list --all    # Include completed processes

# Show details of a specific process
supyagent process show <process_id>

# View output from a background process
supyagent process output <process_id>
supyagent process output <process_id> --tail 100

# Kill a process
supyagent process kill <process_id>
supyagent process kill <process_id> --force

# Clean up completed processes and old logs
supyagent process cleanup

Log Files

All process output is logged to ~/.supyagent/process_logs/. Log files are named by process ID (e.g., tool_143025_1.log) and contain stdout, stderr, and exit code.

Log files are automatically cleaned up based on log_retention_days (default: 7 days). You can trigger cleanup manually with supyagent process cleanup.

Delegation and Process Supervision

When an agent delegates to a child agent in subprocess mode, the delegation runs through the same ProcessSupervisor. The delegation-specific settings are:

supervisor:
  default_delegation_mode: subprocess   # subprocess or in_process
  delegation_timeout: 600               # 10 minutes for delegated tasks

In subprocess mode, the child agent runs as supyagent exec <agent> --task "..." and the supervisor manages its lifecycle like any other process.

In in_process mode, the child agent runs directly in the parent's Python process, sharing the event loop. This is faster but provides less isolation.

Related

• Building Agents -- Agent configuration overview
• CLI Reference -- Full process management CLI commands
• Security -- Sandbox configuration for isolated execution