ChannelContext

ExecutionContextBase<ChannelNotification>
  └── ChannelContext (abstract)
        ├── Your @Channel class
        └── FunctionChannelContext (internal, for channel() builder)

abstract onEvent(payload: unknown): Promise<ChannelNotification>;

async onReply(reply: string, meta?: Record<string, string>): Promise<void>

async onConnect(): Promise<void>

async onConnect(): Promise<void> {
  this.client = new WhatsAppClient(process.env['WA_TOKEN']);
  this.client.on('message', (msg) => {
    this.pushIncoming({ sender: msg.from, text: msg.body, chatId: msg.chatId });
  });
  await this.client.connect();
}

async onDisconnect(): Promise<void>

async onDisconnect(): Promise<void> {
  await this.client?.disconnect();
  this.watcher?.close();
}

protected pushIncoming(payload: unknown): void

@Channel({
  name: 'monitoring',
  source: { type: 'webhook', path: '/hooks/monitor' },
  twoWay: true,
})
class MonitoringChannel extends ChannelContext {
  async onEvent(payload: unknown): Promise<ChannelNotification> {
    const { body } = payload as { body: { alert: string; severity: string } };
    return { content: `Alert: ${body.alert}`, meta: { severity: body.severity } };
  }

  async onReply(reply: string, meta?: Record<string, string>): Promise<void> {
    const messenger = this.get(MessengerServiceToken);
    await messenger.send(meta?.chat_id, reply);
  }
}

@Channel({
  name: 'whatsapp',
  source: { type: 'service', service: 'whatsapp-business' },
  tools: [SendWhatsAppTool],  // Claude calls this to send outbound messages
  twoWay: true,
})
class WhatsAppChannel extends ChannelContext {
  private client: WhatsAppClient;

  async onConnect(): Promise<void> {
    // Called during scope initialization
    this.client = new WhatsAppClient(process.env['WA_TOKEN']);
    this.client.on('message', (msg) => {
      // Feed incoming messages into the notification pipeline
      this.pushIncoming({ from: msg.sender, text: msg.body, chatId: msg.chatId });
    });
    await this.client.connect();
  }

  async onDisconnect(): Promise<void> {
    // Called during scope teardown
    await this.client.disconnect();
  }

  async onEvent(payload: unknown): Promise<ChannelNotification> {
    // Transform incoming service event → notification for Claude
    const msg = payload as { from: string; text: string; chatId: string };
    return {
      content: `${msg.from}: ${msg.text}`,
      meta: { chat_id: msg.chatId, sender: msg.from },
    };
  }

  async onReply(reply: string, meta?: Record<string, string>): Promise<void> {
    // Forward Claude's reply back through the service
    await this.client.sendMessage(meta?.chat_id, reply);
  }
}