Listener ExecUnits
A listener ExecUnit provides the agent-side transport behavior for a listener plugin. This page explains its relationship to the core, its sustained lifetime, and the distinction between listener ExecUnits and listener-owned commands.
Responsibilities
The listener ExecUnit handles the transport-specific part of communication with Command and Control (C2) or a relay endpoint. The agent core retains responsibility for command dispatch, command-result handling, and the core's C2 message processing. The listener plugin supplies the corresponding C2-side behavior.
The term listener describes a Tuoni component role. It does not mean that every implementation waits for incoming network connections. The available listener families use different connection models, while their agent-side components still fill the same architectural role.
Keep the two communication boundaries separate:
| Boundary | Responsibility |
|---|---|
| Listener ExecUnit and agent core | Local exchange of listener messages. |
| Listener transport and its external peer | Transport-specific exchange outside the core. |
The core and the listener can be in the same process and still use a local communication channel. The channel is a boundary between components, not proof that the components occupy different processes.
Listener-Owned Commands
Relay listener plugins also package commands associated with their functionality. These are command ExecUnits, with command output and completion semantics. They do not become listener ExecUnits because they share a plugin or use network facilities.
Read Command ExecUnits for their lifecycle. Check their artifact support separately from the listener itself in Formats and Compatibility.
Lifecycle
A listener normally has a longer lifetime than any individual exchange it performs. During that lifetime it maintains transport-specific state and interacts with the core as needed. An exchange completing is an event within the listener's lifetime, rather than a command-style terminal outcome.
There are several independently meaningful states: the listener's executable code may still be active, local communication may be available, and the external transport may be connected or disconnected. No one of these observations proves the others. An idle or reconnecting transport does not imply that the ExecUnit failed to load.
Configuration changes also belong to the listener's lifetime. The protocol has a way to express reconfiguration, but the effective behavior depends on the listener implementation. Do not infer uniform reconfiguration or graceful-shutdown support from the existence of a shared protocol message.
The current implementations have platform-specific shutdown limitations. A long-lived listener and its background activity require separate consideration from a finite command's outcome; see Limitations and Diagnostics.
Communication responsibilities
The listener-facing core interface separates transport behavior from core-owned information and processing. At an architectural level, listener messages support access to agent information, exchange of outbound and inbound data, and listener configuration. They are not command-result messages.
The Agent and Listener ExecUnits protocol is the canonical reference for these messages. The Type-Length-Value (TLV) reference defines their shared encoding. The external transport's behavior belongs to the listener's documentation; sharing TLV encoding does not make the local interface and external transport interchangeable.
Local communication completion is also different from successful receipt by an external peer. A completed local write only describes that local communication operation. It does not establish remote processing or an end-to-end delivery guarantee.
See Local Communication for Windows named pipes and the first-in, first-out (FIFO) objects used on Portable Operating System Interface (POSIX) platforms. These mechanisms apply to the local boundary independently of the listener's external transport.
Examples
| Listener family | Architectural distinction |
|---|---|
| Simple Hypertext Transfer Protocol (HTTP) listener | An individual request and response belong to a longer-lived listener responsibility. |
| Simple Transmission Control Protocol (TCP) listener | A network connection has its own lifetime, separate from the local component channel. |
| Simple Domain Name System (DNS) listener | A different external transport still uses the listener role at the core boundary. |
| Relay listeners | Related command artifacts and listener artifacts remain separate roles within the same plugin family. |
These examples describe component boundaries. Platform availability and artifact families are listed in Formats and Compatibility.
Limitations
Listener families do not have identical platform or artifact support. In the supplied implementations, the Server Message Block (SMB) relay family is Windows-only, and Windows relay listener implementations are managed. Do not infer native relay artifacts from the native variants available for simple listeners.
A local Windows named pipe and an SMB listener's transport are distinct channels with different participants and purposes. A POSIX FIFO provides local communication; it does not provide SMB listener support on Linux, FreeBSD, or macOS.
Connection recovery, configuration changes, concurrent activity, and shutdown are implementation-specific. Review the relevant Windows, Linux, FreeBSD, or macOS page alongside the listener's own documentation.