PiloTY

Manages persistent pseudo-terminal (PTY) sessions with full state preservation across multiple command executions. Implements session lifecycle management including initialization, command buffering, output capture, and graceful termination. Maintains terminal state (working directory, environment variables, shell context) across sequential operations without requiring re-authentication or context reestablishment.

Manages SSH connections with connection pooling, automatic reconnection, and SSH agent forwarding support for multi-hop authentication scenarios. Implements connection lifecycle management with configurable timeouts, keepalive mechanisms, and credential caching. Supports both password and key-based authentication with transparent fallback and agent socket forwarding for nested SSH operations.

Manages background process execution within PTY sessions with explicit lifecycle tracking, signal handling, and process state monitoring. Implements background job spawning, status polling, output streaming, and graceful termination with configurable signal escalation (SIGTERM → SIGKILL). Maintains process metadata (PID, start time, exit status) and enables agents to query and control long-running operations.

Executes interactive terminal commands that require user input (stdin) with support for multi-step interactions, response buffering, and output pattern matching. Implements input/output synchronization to handle commands that prompt for input (e.g., password prompts, interactive menus). Supports sending input at runtime and capturing output between input events for response-driven automation.

Captures command output (stdout/stderr) with support for real-time streaming, line-buffered processing, and output filtering. Implements asynchronous output reading to prevent buffer deadlocks in long-running operations. Supports both blocking (wait for completion) and streaming (process output as it arrives) modes with configurable buffer sizes and line-ending handling.

Executes commands with configurable timeouts and cancellation support, implementing signal-based termination with graceful degradation to force kill. Tracks execution time and enforces hard limits to prevent runaway processes. Supports both soft timeouts (SIGTERM) and hard timeouts (SIGKILL) with configurable escalation delays.

Manages shell environment variables and execution context (working directory, shell type, locale) with inheritance and override capabilities. Implements context isolation for different execution scopes and supports dynamic environment modification within sessions. Tracks environment state changes across command executions and enables context snapshots for debugging.

Captures and interprets command exit codes with structured error reporting and failure classification. Implements exit code semantics mapping (0=success, non-zero=failure) with support for custom error handlers. Distinguishes between different failure modes (timeout, signal termination, normal exit) and provides detailed error context for agent decision-making.

Detects and adapts to different shell types (bash, zsh, sh, fish) with shell-specific command syntax and behavior handling. Implements shell capability detection and feature compatibility checks. Supports shell-specific features (job control, aliases, functions) with fallback to POSIX-compliant alternatives when needed.

Exposes a high-level Python API for agents to control PTY sessions with methods for command execution, session management, and process control. Implements a clean abstraction layer over PTY operations with type hints and structured return values. Supports both synchronous and asynchronous execution patterns for integration with async agent frameworks.