Phase 1: Gateway & Channel Foundation

Overview

This phase establishes the messaging infrastructure that makes AgenC agents reachable via external platforms (Telegram, Discord, etc.). The Gateway wraps the existing AgentRuntime and adds multi-channel communication, session management, lifecycle hooks, and a chat execution loop that turns user messages into task completions.

What this enables:

Dependencies

None — This is a greenfield implementation.

Existing runtime infrastructure used:

Issue Dependency Graph

Implementation Order

1. 1053 — Gateway core process and WebSocket control plane (L)

- Foundation class, runtime integration, control socket for management

2. 1051 — Unified message format (S)

- Type definitions for all message flows

3. 1054 — Channel plugin interface and ChannelContext (S)

- Plugin contract, context object, plugin catalog

4. 1055 — Session management (M)

- Session state, scoping, reset, compaction

5. 1056 — Lifecycle hook system (M)

- Event hooks, dispatcher, built-in hooks

6. 1052 — Slash commands handler (S)

- Command parser, built-in commands

7. 1060 — Telegram channel plugin (M)

- First concrete channel implementation

8. 1061 — Discord channel plugin (M)

- Second channel, validates plugin interface

9. 1063 — Agent loop integration (L)

- ChatExecutor, model fallback, tool integration

10. 1057 — Cross-channel identity linking (M)

- Link Telegram/Discord identities to single user profile

11. 1058 — Gateway CLI commands and setup wizard (M)

- CLI for gateway start/stop/status, interactive setup

12. 1059 — Media pipeline (M)

- Voice transcription, image description

Rationale: Core gateway → message types → plugin interface → session/hooks → first channels → agent loop → identity/CLI/media.

Issue Details

1.1: Gateway core process and WebSocket control plane (#1053)

Goal: Create the Gateway service that wraps AgentRuntime and exposes a WebSocket control interface.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface GatewayConfig {
  runtime: AgentRuntime;
  controlSocketPath?: string;
  sessionBackend: MemoryBackend;
}

interface Gateway {
  start(): Promisevoid>;
  stop(): Promisevoid>;
  getState(): GatewayState;
  registerChannel(plugin: ChannelPlugin): void;
}

interface ControlMessage {
  type: 'ping' | 'status' | 'reload' | 'stop';
  payload?: unknown;
}

Testing strategy:

Estimated scope: L (500-800 lines)

1.2: Unified message format (GatewayMessage / OutboundMessage) (#1051)

Goal: Define the canonical message types flowing through the gateway.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface GatewayMessage {
  id: string;
  channelType: string;
  channelUserId: string;
  text: string;
  attachments?: MessageAttachment[];
  timestamp: number;
}

interface OutboundMessage {
  text: string;
  attachments?: MessageAttachment[];
  replyTo?: string;
}

Testing strategy:

Estimated scope: S (200-300 lines)

1.3: Channel plugin interface and ChannelContext (#1054)

Goal: Define the plugin contract and context object passed to channels.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface ChannelPlugin {
  readonly name: string;
  initialize(context: ChannelContext): Promisevoid>;
  shutdown(): Promisevoid>;
  sendMessage(userId: string, message: OutboundMessage): Promisevoid>;
}

interface ChannelContext {
  gateway: Gateway;
  onMessage(handler: (msg: GatewayMessage) => Promisevoid>): void;
  logger: Logger;
}

Testing strategy:

Estimated scope: S (300-400 lines)

1.4: Telegram channel plugin (#1060)

Goal: Implement Telegram channel using telegraf library.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface TelegramConfig {
  botToken: string;
  allowedUsers?: number[];
  webhookUrl?: string;
}

class TelegramChannelPlugin implements ChannelPlugin {
  readonly name = 'telegram';
  // implementation
}

Testing strategy:

Estimated scope: M (400-600 lines)

1.5: Discord channel plugin (#1061)

Goal: Implement Discord channel using discord.js library.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface DiscordConfig {
  botToken: string;
  allowedGuilds?: string[];
  allowedChannels?: string[];
}

class DiscordChannelPlugin implements ChannelPlugin {
  readonly name = 'discord';
  // implementation
}

Testing strategy:

Estimated scope: M (400-600 lines)

1.6: Session management (scoping, reset, compaction) (#1055)

Goal: Manage conversation sessions with memory backend integration.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface Session {
  id: string;
  userId: string;
  channelType: string;
  createdAt: number;
  lastActivityAt: number;
}

interface SessionManager {
  getOrCreate(channelType: string, userId: string): PromiseSession>;
  reset(sessionId: string): Promisevoid>;
  compact(sessionId: string): Promisevoid>;
}

Testing strategy:

Estimated scope: M (400-500 lines)

1.7: Lifecycle hook system (HookDispatcher) (#1056)

Goal: Provide event hooks for message lifecycle (before/after send, on error, etc.).

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface HookEvent {
  type: 'message:before' | 'message:after' | 'send:before' | 'send:after' | 'error';
  data: unknown;
  timestamp: number;
}

interface HookHandler {
  handle(event: HookEvent): Promisevoid>;
}

interface HookDispatcher {
  register(type: HookEvent['type'], handler: HookHandler): void;
  dispatch(event: HookEvent): Promisevoid>;
}

Testing strategy:

Estimated scope: M (350-450 lines)

1.8: Slash commands handler (#1052)

Goal: Parse and execute slash commands (/help, /reset, etc.).

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface Command {
  name: string;
  description: string;
  execute(ctx: CommandContext, args: string[]): Promisestring>;
}

interface CommandContext {
  session: Session;
  gateway: Gateway;
}

Testing strategy:

Estimated scope: S (250-350 lines)

1.9: Cross-channel identity linking (#1057)

Goal: Link Telegram and Discord identities to a single user profile.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface UserProfile {
  canonicalId: string;
  linkedIdentities: IdentityLink[];
  createdAt: number;
}

interface IdentityLink {
  channelType: string;
  channelUserId: string;
  linkedAt: number;
}

interface IdentityLinker {
  link(fromChannel: string, fromUserId: string, toUserId: string): Promisevoid>;
  resolve(channelType: string, userId: string): Promisestring>;
}

Testing strategy:

Estimated scope: M (350-450 lines)

1.10: Gateway CLI commands and setup wizard (#1058)

Goal: CLI for gateway start/stop/status and interactive setup.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface GatewayCommand {
  name: string;
  description: string;
  execute(args: string[]): Promisevoid>;
}

interface SetupWizard {
  run(): PromiseGatewayConfig>;
}

Testing strategy:

Estimated scope: M (400-500 lines)

1.11: Agent loop integration (ChatExecutor + model fallback) (#1063)

Goal: Execute chat messages through LLM with tool calling and model fallback.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface ChatExecutorConfig {
  primaryModel: LLMProvider;
  fallbackModels?: LLMProvider[];
  tools: ToolRegistry;
  memory: MemoryBackend;
  maxToolRounds?: number;
}

interface ChatExecutor {
  execute(message: GatewayMessage, session: Session): PromiseOutboundMessage>;
}

Testing strategy:

Estimated scope: L (600-800 lines)

1.12: Media pipeline (voice transcription, image description) (#1059)

Goal: Process voice and image attachments before sending to LLM.

Files to create:

Files to modify:

Integration points:

Patterns to follow:

Key interfaces:

interface MediaProcessor {
  process(attachment: MessageAttachment): Promisestring>;
}

interface MediaPipeline {
  processAttachments(attachments: MessageAttachment[]): Promisestring[]>;
}

interface TranscriptionConfig {
  apiKey: string;
  model?: string;
}

Testing strategy:

Estimated scope: M (400-500 lines)

Integration Checklist

After completing all issues:

Success Metrics