Hmp1WorkloadAdapter

Namespace: Hex1b

Assembly: Hex1b.dll

A workload adapter that connects to a remote muxer server over the Hex1b Muxer Protocol (HMP).

public sealed class Hmp1WorkloadAdapter : IHex1bTerminalWorkloadAdapter, IAsyncDisposable, IHmp1ConnectionHandle

Inheritance

Object → Hmp1WorkloadAdapter

Implements

• IHex1bTerminalWorkloadAdapter
• IAsyncDisposable
• IHmp1ConnectionHandle

Constructors

Hmp1WorkloadAdapter(Hmp1ClientOptions)

Creates a muxer workload adapter from the supplied options bag.

Parameters:

• options (Hmp1ClientOptions): Transport (), optional , handshake hints, and event hooks.

public Hmp1WorkloadAdapter(Hmp1ClientOptions options)

Properties

CurrentHeight

Gets the current PTY height as known to this adapter.

Returns: Int32

public int CurrentHeight { get; }

CurrentWidth

Gets the current PTY width as known to this adapter (updated on and observed ).

Returns: Int32

public int CurrentWidth { get; }

DefaultRole

The role hint this adapter sent in its ClientHello, or null if no hint was supplied.

Returns: Nullable<Hmp1Role>

public Hmp1Role? DefaultRole { get; }

DisconnectedTask

Completes when the read pump has observed disconnection (clean transport close, stream error, or local disposal). Completed before the callback is awaited so framework consumers that just want to know "the transport went away" do not get coupled to user-handler duration.

Returns: Task

public Task DisconnectedTask { get; }

IsPrimary

Gets whether this adapter is currently the primary peer.

Returns: Boolean

public bool IsPrimary { get; }

LocalDisplayName

The display name this adapter sent in its frame. If the caller did not supply one, this returns the auto-generated value.

Returns: String

public string LocalDisplayName { get; }

OnConnected

Invoked once after the HMP v1 handshake (ClientHello → Hello → StateSync) completes successfully. Pre-populated from at adapter construction; may be replaced or composed with += at runtime (multicast handlers are awaited sequentially with per-handler exception isolation).

Returns: Func<Hmp1ConnectedEventArgs, CancellationToken, Task>

public Func<Hmp1ConnectedEventArgs, CancellationToken, Task>? OnConnected { get; set; }

OnDisconnected

Invoked once when the underlying transport stream closes.

Returns: Func<CancellationToken, Task>

public Func<CancellationToken, Task>? OnDisconnected { get; set; }

OnPeerJoined

Invoked when another peer joins the same producer.

Returns: Func<PeerJoinEventArgs, CancellationToken, Task>

public Func<PeerJoinEventArgs, CancellationToken, Task>? OnPeerJoined { get; set; }

OnPeerLeft

Invoked when another peer leaves.

Returns: Func<PeerLeaveEventArgs, CancellationToken, Task>

public Func<PeerLeaveEventArgs, CancellationToken, Task>? OnPeerLeft { get; set; }

OnRemoteResized

Invoked when the producer's PTY dimensions change at runtime.

Returns: Func<RemoteResizedEventArgs, CancellationToken, Task>

public Func<RemoteResizedEventArgs, CancellationToken, Task>? OnRemoteResized { get; set; }

OnRoleChanged

Invoked when the primary peer changes.

Returns: Func<RoleChangedEventArgs, CancellationToken, Task>

public Func<RoleChangedEventArgs, CancellationToken, Task>? OnRoleChanged { get; set; }

PeerId

Gets the peer ID assigned by the server in the Hello frame.

Returns: String

public string PeerId { get; }

Peers

Gets a snapshot of currently-connected peer roster (excluding self).

Returns: IReadOnlyList<PeerInfo>

public IReadOnlyList<PeerInfo> Peers { get; }

PrimaryPeerId

Gets the peer ID of the current primary peer, or null when no peer is primary.

Returns: String

public string? PrimaryPeerId { get; }

RemoteHeight

Gets the remote terminal height reported in the Hello frame (preserved for source compatibility with single-head HMP1 callers).

Returns: Int32

public int RemoteHeight { get; }

RemoteWidth

Gets the remote terminal width reported in the Hello frame (preserved for source compatibility with single-head HMP1 callers).

Returns: Int32

public int RemoteWidth { get; }

Methods

ConnectAsync(CancellationToken)

Connects to the server, sends ClientHello, reads Hello and StateSync, and starts the background read pump.

Parameters:

• ct (CancellationToken):

Returns: Task

public Task ConnectAsync(CancellationToken ct)

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Returns: ValueTask

A task that represents the asynchronous dispose operation.

public ValueTask DisposeAsync()

ReadOutputAsync(CancellationToken)

Read output FROM the workload (ANSI sequences to display). The terminal calls this to get data to parse and send to presentation. Returns empty when workload has no more output (should be called in a loop).

Parameters:

• ct (CancellationToken):

Returns: ValueTask<Byte>>

public ValueTask<ReadOnlyMemory<byte>> ReadOutputAsync(CancellationToken ct = default)

RequestPrimaryAsync(int, int, CancellationToken)

Asks the server to make this peer the primary at the supplied dimensions. The server always grants in this iteration; observe

(or call ) for the acknowledged transition.

Parameters:

• cols (Int32):
• rows (Int32):
• ct (CancellationToken):

Returns: Task

public Task RequestPrimaryAsync(int cols, int rows, CancellationToken ct = default)

ResizeAsync(int, int, CancellationToken)

Sends a Resize frame to the producer when this adapter is the current primary; silently no-ops (with a debug-tracing line) otherwise.

Parameters:

• width (Int32):
• height (Int32):
• ct (CancellationToken):

Returns: ValueTask

public ValueTask ResizeAsync(int width, int height, CancellationToken ct = default)

WaitForRoleAsync(bool, TimeSpan, CancellationToken)

Waits up to timeout for this adapter's to match primary. Returns true on success, false on timeout.

Parameters:

• primary (Boolean):
• timeout (TimeSpan):
• ct (CancellationToken):

Returns: Task<Boolean>

public Task<bool> WaitForRoleAsync(bool primary, TimeSpan timeout, CancellationToken ct = default)

WriteInputAsync(ReadOnlyMemory<byte>, CancellationToken)

Write input TO the workload (raw bytes from keyboard/mouse). The terminal calls this when it receives input from the presentation layer.

Parameters:

• data (ReadOnlyMemory<Byte>):
• ct (CancellationToken):

Returns: ValueTask

public ValueTask WriteInputAsync(ReadOnlyMemory<byte> data, CancellationToken ct = default)

Events

Disconnected

Raised when the underlying transport closes. Required by the contract so the hosting Hex1bTerminal can observe workload exit. HMP1 consumers that want async-callback semantics should set instead — the event remains for the workload-adapter contract only.

Returns: Action

public event Action? Disconnected

Remarks

This adapter reads terminal output from a remote server and forwards local keyboard input and resize events to it. On connection, the client sends a frame; the server responds with a (with the assigned peer ID, current primary, and roster) and a .

The adapter is transport-agnostic: provide any bidirectional (Unix domain socket, TCP, named pipe, etc.).

Multi-head: a connected client is a "secondary" by default. To take control of the underlying PTY's dimensions, call . Until the role transition is acknowledged, calls are silently dropped at the producer (the local is also a no-op while is false). Set , , and to drive UX state.