flynn/docs/plans/2026-02-05-phase3-channel-adapters.md

Phase 3: Channel Adapters — Implementation Plan

Goal

Introduce a ChannelAdapter abstraction that decouples message sources (Telegram, WebChat, future Discord/WhatsApp/Slack) from the agent. Each adapter handles platform-specific I/O and maps messages to a common interface. A ChannelRegistry manages adapter lifecycle and routes messages to/from the agent.

Scope (This Iteration)

1. Channel types — ChannelAdapter interface, InboundMessage, OutboundMessage, ChannelStatus
2. Channel registry — Register, start/stop, route messages, adapter lifecycle
3. Telegram adapter — Refactor existing src/frontends/telegram/ into a ChannelAdapter
4. WebChat adapter — Wrap the existing gateway WS into a ChannelAdapter
5. Daemon integration — Replace direct bot/gateway creation with registry-managed adapters

Discord, WhatsApp, and Slack adapters are deferred (require new dependencies + credentials).

Architecture

src/channels/
├── types.ts              # ChannelAdapter interface, message types
├── registry.ts           # ChannelRegistry: lifecycle + message routing
├── registry.test.ts      # Registry tests
├── index.ts              # Barrel exports
├── telegram/
│   ├── adapter.ts        # TelegramAdapter implements ChannelAdapter
│   ├── adapter.test.ts   # Adapter tests
│   └── index.ts          # Barrel
└── webchat/
    ├── adapter.ts        # WebChatAdapter implements ChannelAdapter
    ├── adapter.test.ts   # Adapter tests
    └── index.ts          # Barrel

The existing src/frontends/telegram/ code (bot.ts, handlers.ts, confirmations.ts) stays in place and is wrapped by the adapter. The adapter delegates to the existing bot creation logic. No breaking changes to existing code.

Types Design

InboundMessage

interface InboundMessage {
  id: string;                    // Platform message ID
  channel: string;               // Adapter name: "telegram", "webchat", etc.
  senderId: string;              // Platform user ID
  senderName?: string;           // Display name (optional)
  text: string;                  // Message text
  replyTo?: string;              // ID of message being replied to
  timestamp: number;             // Unix ms
  metadata?: Record<string, unknown>;  // Platform-specific extras
}

OutboundMessage

interface OutboundMessage {
  text: string;                  // Response text (markdown)
  replyTo?: string;              // Original message ID
  metadata?: Record<string, unknown>;  // Platform-specific extras (e.g. parse_mode)
}

ChannelAdapter

interface ChannelAdapter {
  readonly name: string;
  readonly status: ChannelStatus;

  /** Start the adapter (connect to platform, begin listening). */
  connect(): Promise<void>;

  /** Stop the adapter (disconnect, clean up). */
  disconnect(): Promise<void>;

  /** Send a message to a specific peer. */
  send(peerId: string, message: OutboundMessage): Promise<void>;

  /** Register the inbound message handler. Called by registry. */
  onMessage(handler: (msg: InboundMessage) => void): void;

  /** Register a tool event handler for displaying tool execution status. */
  onToolEvent?(handler: (peerId: string, event: ToolStatusEvent) => void): void;
}

type ChannelStatus = 'disconnected' | 'connecting' | 'connected' | 'error';

interface ToolStatusEvent {
  type: 'start' | 'end';
  tool: string;
  args?: unknown;
  result?: { success: boolean; output: string; error?: string };
}

ChannelRegistry

class ChannelRegistry {
  register(adapter: ChannelAdapter): void;
  unregister(name: string): void;
  get(name: string): ChannelAdapter | undefined;
  list(): ChannelAdapter[];

  /** Start all registered adapters. */
  startAll(): Promise<void>;

  /** Stop all registered adapters. */
  stopAll(): Promise<void>;

  /** Set the message handler that all adapters route to. */
  setMessageHandler(handler: (msg: InboundMessage, reply: (msg: OutboundMessage) => Promise<void>) => Promise<void>): void;
}

Telegram Adapter Design

The TelegramAdapter wraps the existing createTelegramBot() logic:

• connect(): Creates grammy Bot, starts long polling
• disconnect(): Stops the bot
• send(): Calls bot.api.sendMessage(peerId, text, { parse_mode: 'Markdown' })
• onMessage(): Sets up bot.on('message:text', ...) to convert grammy context to InboundMessage
• Preserves existing confirmations, commands (/start, /reset, /status, /local, /cloud, /model)
• Preserves chat ID allowlist check as middleware
• Tool status display: adapter handles the onToolUse events by posting/editing Telegram messages

Constructor takes:

interface TelegramAdapterConfig {
  botToken: string;
  allowedChatIds: number[];
  hookEngine?: HookEngine;
}

The adapter does NOT take an agent directly — the registry routes messages to the agent.

WebChat Adapter Design

The WebChatAdapter is a thin shim since the gateway already handles WS connections.

• connect(): No-op (gateway server is already running)
• disconnect(): No-op (gateway lifecycle managed by daemon)
• send(): Sends via the gateway's WS connection to the peer
• onMessage(): Hooks into the gateway's agent.send handler to intercept messages

Constructor takes:

interface WebChatAdapterConfig {
  gateway: GatewayServer;
}

This adapter is simpler because the gateway already has its own session bridge and agent management. The adapter primarily exists to:

1. Report WebChat as a registered channel in the registry
2. Allow the daemon to manage all channels uniformly
3. Provide status/metrics via a common interface

Daemon Integration

The daemon currently:

1. Creates a grammy Bot directly
2. Creates a GatewayServer directly
3. Starts both independently

After refactor:

1. Creates a ChannelRegistry
2. Creates TelegramAdapter + WebChatAdapter
3. Registers both with the registry
4. Registry starts all adapters

The message handler in the registry creates per-channel agents via the session manager, same as the existing session bridge pattern.

Implementation Order

1. src/channels/types.ts — Pure types (no runtime)
2. src/channels/registry.ts — Registry class
3. src/channels/registry.test.ts — Registry unit tests
4. src/channels/telegram/adapter.ts — Telegram adapter
5. src/channels/telegram/adapter.test.ts — Telegram adapter tests
6. src/channels/webchat/adapter.ts — WebChat adapter
7. src/channels/webchat/adapter.test.ts — WebChat adapter tests
8. src/channels/index.ts + sub-barrel exports
9. src/daemon/index.ts — Wire registry
10. Run full test suite

Existing Code Impact

• src/frontends/telegram/ — NOT deleted. The adapter wraps these existing modules.
• src/gateway/ — NOT modified. WebChat adapter wraps the existing gateway.
• src/daemon/index.ts — Modified to use ChannelRegistry.
• src/backends/native/agent.ts — NOT modified. Agent creation happens in the registry message handler.

Test Strategy

• Unit tests for ChannelRegistry (mock adapters)
• Unit tests for TelegramAdapter (mock grammy Bot)
• Unit tests for WebChatAdapter (mock GatewayServer)
• Existing tests remain unchanged (frontends/telegram, gateway)

---

Plan Version: 1.0 Created: 2026-02-05 Parent: docs/plans/2026-02-05-openclaw-parity-design.md Phase 3