Luna/Documentation/Luna AI Assistant/Channels/Channels.md

Channels

The Channels module provides a unified abstraction for communication platforms like the CLI and Telegram. It handles message transport, while Core manages AI context and session state.

Luna.Channels.Abstractions

This project defines the contracts and event models for all channel implementations.

IChannel

The primary interface for any communication transport. There is no abstract base class; IChannel is the complete contract.

public interface IChannel : IDisposable
{
    string ChannelId { get; }
    string ChannelType { get; }
    string DisplayName { get; }
    bool IsConnected { get; }

    event ChannelMessageReceivedEventHandler? MessageReceived;
    event EventHandler<ChannelConnectionEventArgs>? ConnectionStateChanged;

    Task SendMessageAsync(ChannelMessage message, CancellationToken ct = default);
    Task SendStreamingMessageAsync(IAsyncEnumerable<ChatStreamUpdate> messageStream, CancellationToken ct = default);
}

IChannelManager

Coordinates registered channels and handles message routing.

public interface IChannelManager
{
    void RegisterChannel(IChannel channel);
    void UnregisterChannel(string channelId);
    IChannel? GetChannel(string channelId);
    IReadOnlyList<IChannel> GetAllChannels();
    event EventHandler<ChannelMessageReceivedEventArgs>? MessageRouted;
}

Supporting Types

• ChannelType: A static class providing constants like cli and telegram.
• ChannelMessageReceivedEventHandler: Delegate for handling incoming messages. Task ChannelMessageReceivedEventHandler(object? sender, ChannelMessageReceivedEventArgs e)
• ChannelMessageReceivedEventArgs: Contains the Channel, Message, and an IsHandled flag.
• ChannelConnectionEventArgs: Contains the Channel and IsConnected status.

Luna.Channels

This project contains the concrete management logic and specific channel implementations.

ChannelManager

The ChannelManager implements IChannelManager and acts as the central hub for message traffic. It injects ISessionManager from Core and ILogger<ChannelManager>.

When a channel is registered via RegisterChannel, the manager subscribes to its MessageReceived event. The OnMessageReceivedAsync handler performs the following:

1. Calls sessionManager.RouteMessagesAsync(message.Content, message.ConversationId, channel.ChannelId).
2. Pipes the resulting IAsyncEnumerable<ChatStreamUpdate> back to the channel via channel.SendStreamingMessageAsync.

Channel Implementations

• CLI Channel — SignalR-based adapter for the command-line interface.
• Telegram Channel — Telegram Bot API adapter with message splitting and streaming.
• Web Interface Channel — Browser-based chat UI (not yet implemented).

Routing Flow

1. Channel.MessageReceived event triggers.
2. ChannelManager catches the event and identifies the sender.
3. Manager calls SessionManager.RouteMessagesAsync.
4. SessionManager returns an IAsyncEnumerable<ChatStreamUpdate>.
5. ChannelManager passes this stream to Channel.SendStreamingMessageAsync.
6. The channel implementation handles the physical transport of the stream.

Architecture Decisions

• Separation of Concerns: ChannelManager handles transport and routing. SessionManager handles AI context and conversation logic.
• Conversation Scoping: Sessions are scoped to conversations, not specific channels. This allows for potential cross-channel persistence.
• Unified DTOs: All message data uses the ChannelMessage DTO from Luna.Shared.
• Registration: Channels are registered via the AddChannels() DI extension method, following the Configuration patterns.
• Options Pattern: Implementations use IOptions<TOptions> (e.g., TelegramOptions) for configuration.

Dependencies

Project References

• Luna.Channels.Abstractions
• Luna.Configuration
• Luna.Core.Abstractions
• Luna.Shared

NuGet Packages

• Telegram.Bot
• Microsoft.Extensions.Hosting.Abstractions
• Microsoft.Extensions.Logging.Abstractions

Adding a New Channel

To implement a new channel:

1. Create a class implementing IChannel.
2. Ensure it handles both SendMessageAsync and SendStreamingMessageAsync.
3. Raise MessageReceived when the external platform sends a message.
4. Register the channel with IChannelManager during startup or via a background adapter (like TelegramAdapter).