Channels

Messaging Platform --> ChannelAdapter --> UnifiedMessage --> MessageRouter --> Agent Layer
                                                                                  |
Messaging Platform <-- ChannelAdapter <-- UnifiedResponse <---------------------+

// 1. Create registry and discover adapters on classpath
ChannelRegistry registry = new ChannelRegistry();
registry.discoverAdapters();

// 2. Create message router
MessageRouter router = new MessageRouter(registry);
router.setMessageHandler((message, callback) -> {
    // Process with your agent
    String response = agent.chat(message.text());
    callback.send(UnifiedResponse.builder()
        .channelId(message.channelId())
        .conversationId(message.conversationId())
        .text(response)
        .build());
});

// 3. Start all adapters
registry.startAll(router);

com.tnsai.channels
+-- api/          Core interfaces and message models
+-- annotation/   @Channel annotation
+-- enums/        ChannelState lifecycle enum
+-- model/        Attachment, MessageMeta, ResponseHints, ChannelError
+-- registry/     SPI-based adapter discovery and lifecycle
+-- routing/      MessageRouter, SessionRegistry
+-- telegram/     Telegram Bot API adapter
+-- cli/          Local REPL + JSON adapter (streaming-capable reference)
+-- email/        IMAP poll + SMTP send adapter
+-- slack/        Slack Socket Mode adapter
+-- discord/      Discord Gateway adapter
+-- whatsapp/     WhatsApp Cloud API adapter

public interface ChannelAdapter {
    String id();                           // Unique identifier (e.g. "telegram")
    String displayName();                  // Human-readable name
    ChannelCapabilities capabilities();    // What the channel supports
    void start(ChannelContext context);    // Begin listening for messages
    void stop();                           // Tear down and release resources
    void send(UnifiedResponse response);  // Send a response back through the channel
    boolean isRunning();                   // Whether the adapter is operational
}

public interface ChannelAdapterFactory {
    String getType();                    // Channel type identifier
    String getDisplayName();             // Human-readable name
    ChannelAdapter create(Object config); // Create adapter with platform-specific config
    boolean isAvailable();               // Whether required SDK classes are on classpath
}

public interface ChannelContext {
    void onMessage(UnifiedMessage message);     // Inbound message arrived
    void onTyping(String conversationId);       // Remote user is typing
    void onError(ChannelError error);           // Adapter encountered an error
}

// Only factories whose SDK is on the classpath
List<ChannelAdapterFactory> factories = ChannelDiscovery.discoverFactories();

// All registered factories, regardless of availability
List<ChannelAdapterFactory> all = ChannelDiscovery.discoverAllFactories();

public interface StreamingChannelAdapter extends ChannelAdapter {
    void sendChunk(UnifiedChunk chunk);
}

public record UnifiedChunk(
    String conversationId,         // Same key as the parent UnifiedResponse
    String delta,                  // Text fragment (may be empty for control chunks)
    boolean done,                  // true for the final chunk in a reply
    Map<String, Object> metadata,  // Free-form per-chunk metadata; null treated as empty
    Instant timestamp              // When the chunk was emitted
) { ... }

UnifiedChunk.text(conversationId, "hello");   // non-terminal text chunk
UnifiedChunk.done(conversationId);             // final empty chunk with done=true

public record UnifiedMessage(
    String channelId,          // Adapter id (e.g. "telegram")
    String senderId,           // Platform-specific user id
    String senderName,         // Human-readable sender name
    String conversationId,     // Platform-specific chat/channel id
    String text,               // Message text (null for media-only)
    List<Attachment> attachments,
    MessageMeta meta,          // Reply-to, thread id, platform message id
    Instant timestamp
) {
    // Convenience method: unique session key
    public String sessionKey();  // Returns "channelId:conversationId"
}

UnifiedMessage message = UnifiedMessage.builder()
    .channelId("telegram")
    .senderId("123456")
    .senderName("Alice")
    .conversationId("789")
    .text("Hello, agent!")
    .timestamp(Instant.now())
    .build();

public record UnifiedResponse(
    String channelId,            // Target adapter id
    String conversationId,       // Target chat/channel
    String text,                 // Response text
    List<Attachment> attachments, // Files to send
    ResponseHints hints          // Delivery hints
) {}

UnifiedResponse response = UnifiedResponse.builder()
    .channelId("telegram")
    .conversationId("789")
    .text("Here is your answer.")
    .hints(ResponseHints.withStreaming())
    .build();

public record Attachment(
    String fileName,
    String mimeType,
    String url,            // Remote URL (null for local data)
    byte[] data,           // Raw bytes (null for remote)
    long sizeBytes,        // -1 if unknown
    AttachmentType type    // IMAGE, AUDIO, VIDEO, DOCUMENT, VOICE, STICKER, OTHER
) {
    // Factory methods
    static Attachment ofUrl(String fileName, String mimeType, String url, AttachmentType type);
    static Attachment ofData(String fileName, String mimeType, byte[] data, AttachmentType type);
}

public record MessageMeta(
    String replyToMessageId,    // Message this is replying to
    String threadId,            // Thread identifier
    String platformMessageId,   // Native message id from source platform
    Map<String, String> extra   // Arbitrary platform-specific data
) {
    static MessageMeta of(String platformMessageId);
    static MessageMeta reply(String platformMessageId, String replyToMessageId);
}

public record ResponseHints(
    boolean streaming,           // Token-by-token delivery if supported
    boolean showTyping,          // Send typing indicator first
    boolean splitLongMessages,   // Auto-split text exceeding channel max length
    String replyToMessageId      // Native message id to reply to
) {
    static ResponseHints defaults();        // typing=true, split=true
    static ResponseHints withStreaming();    // streaming=true, typing=true, split=true
    static ResponseHints replyTo(String messageId);
}

public record ChannelError(
    String channelId,
    Severity severity,    // TRANSIENT, DEGRADED, FATAL
    String message,
    Throwable cause,
    Instant timestamp
) {
    static ChannelError transient_(String channelId, String message, Throwable cause);
    static ChannelError degraded(String channelId, String message, Throwable cause);
    static ChannelError fatal(String channelId, String message, Throwable cause);
}

public record ChannelCapabilities(
    boolean threads,           // Threaded conversations
    boolean reactions,         // Emoji reactions
    boolean fileUpload,        // File/document uploads
    boolean voice,             // Voice messages
    boolean typing,            // Typing indicators
    boolean editing,           // Message editing (for streaming)
    boolean streaming,         // Token-by-token streaming via editing
    long maxMessageLength      // Max text length per message
) {}

ChannelCapabilities capabilities = ChannelCapabilities.builder()
    .threads(false)
    .reactions(true)
    .fileUpload(true)
    .voice(true)
    .typing(true)
    .editing(true)
    .streaming(true)
    .maxMessageLength(4096)
    .build();

REGISTERED --> STARTING --> RUNNING --> STOPPING --> STOPPED
                  |            |
                  v            v
               FAILED       DEGRADED

public class ChannelRegistry {
    void discoverAdapters();                               // Load via ServiceLoader
    void register(ChannelAdapter adapter);                 // Register programmatically
    void startAdapter(String channelId, ChannelContext context);
    void startAll(ChannelContext context);
    void stopAdapter(String channelId);
    void stopAll();
    Optional<ChannelAdapter> get(String channelId);
    ChannelState getState(String channelId);
    Collection<ChannelAdapter> getAllAdapters();
    Collection<String> getRegisteredIds();
}

public class MessageRouter implements ChannelContext {

    MessageRouter(ChannelRegistry registry);

    // Connect to agent layer
    void setMessageHandler(BiConsumer<UnifiedMessage, ResponseCallback> handler);

    // Proactive outbound messaging
    void sendProactive(String channelId, String conversationId, String text);

    SessionRegistry getSessions();

    // Callback interface for agent responses
    @FunctionalInterface
    interface ResponseCallback {
        void send(UnifiedResponse response);
    }
}

public class SessionRegistry {
    void touch(String sessionKey, String channelId, String conversationId);
    Optional<ChannelSession> get(String sessionKey);
    Collection<ChannelSession> getAll();
    void remove(String sessionKey);
    int reapIdle(Duration maxIdle);    // Remove sessions idle longer than threshold
    int size();

    record ChannelSession(
        String sessionKey,        // "channelId:conversationId"
        String channelId,
        String conversationId,
        Instant createdAt,
        Instant lastActive
    ) {}
}

@Channel(id = "telegram", displayName = "Telegram")
public class TelegramAdapter implements ChannelAdapter { ... }

@Channel(id = "telegram", displayName = "Telegram")
public class TelegramAdapter implements ChannelAdapter {

    @Override
    public ChannelCapabilities capabilities() {
        return ChannelCapabilities.builder()
            .threads(false).reactions(true).fileUpload(true)
            .voice(true).typing(true).editing(true)
            .streaming(true).maxMessageLength(4096)
            .build();
    }

    // ... start(), stop(), send(), isRunning()
}