Channel Bridge

Conversation Binding Channel Scoping Plugin Identity Gateway Integration

Contents

Overview

flowchart TD
  subgraph Channels["Channel Plugins"]
    Discord["Discord Plugin"]
    Slack["Slack Plugin"]
    WhatsApp["WhatsApp Plugin"]
    More["20+ more"]
  end
  subgraph Binding["Conversation Binding"]
    ConvBind["conversation-binding.ts"]
    ChannelIDs["channel-plugin-ids.ts"]
    Scope["gateway-request-scope.ts"]
  end
  subgraph Bridge["Tool Bridge"]
    PluginRT["Plugin Runtime"]
    ToolFactory["Tool Factory"]
    AgentTools["Agent Tool Set"]
  end
  Discord --> ConvBind
  Slack --> ConvBind
  WhatsApp --> ConvBind
  More --> ConvBind
  ConvBind --> ChannelIDs
  ChannelIDs --> Scope
  Scope --> PluginRT
  PluginRT --> ToolFactory
  ToolFactory --> AgentTools

Each channel plugin registers itself during loading. When a message arrives, the conversation binding layer identifies the owning plugin, binds its identity to the gateway request scope, and passes context through the tool factory pipeline so the agent receives the correct channel-scoped tools.

How It Works

Channel bridging operates in three stages: registration, identity resolution, and scope binding.

Stage 1: Channel Registration

Channel plugins register via api.registerChannel(channelPlugin) during plugin loading. This stores a mapping from channel type identifiers to the plugin that handles them. Each channel plugin declares its supported channel types and any tools it provides.

// channel-plugin-ids.ts — registration mapping
const channelPluginMap = new Map<string, string>();

export function registerChannelPlugin(
  channelType: string,
  pluginId: string,
): void {
  if (channelPluginMap.has(channelType)) {
    throw new Error(
      `Channel type "${channelType}" already claimed by plugin "${channelPluginMap.get(channelType)}"`,
    );
  }
  channelPluginMap.set(channelType, pluginId);
}

export function getPluginIdForChannel(channelType: string): string | undefined {
  return channelPluginMap.get(channelType);
}

Stage 2: Identity Resolution

When a message arrives, conversation-binding.ts resolves which channel plugin handles it by looking up the channel type in the channelPluginMap. The resolved pluginId is then passed to the scope binding layer.

// conversation-binding.ts — identity resolution
export async function resolveConversationBinding(
  message: IncomingMessage,
): Promise<ConversationBinding> {
  const channelType = message.channelType;
  const pluginId = getPluginIdForChannel(channelType);

  if (!pluginId) {
    throw new Error(`No plugin registered for channel type: "${channelType}"`);
  }

  return {
    pluginId,
    channelType,
    conversationId: message.conversationId,
    metadata: message.channelMetadata,
  };
}

Stage 3: Scope Binding

withPluginRuntimePluginIdScope() in gateway-request-scope.ts binds the plugin’s identity to the gateway request. This scoping ensures that all tool calls made during agent execution carry the correct plugin identity, so MCP servers declared by the channel plugin’s bundle are accessible through the bridge.

// gateway-request-scope.ts — scope binding
export function withPluginRuntimePluginIdScope<T>(
  pluginId: string,
  fn: () => T,
): T {
  const previousScope = currentPluginScope;
  currentPluginScope = pluginId;
  try {
    return fn();
  } finally {
    currentPluginScope = previousScope;
  }
}

Message Flow Sequence

sequenceDiagram
  participant Chan as Channel Adapter
  participant Bind as conversation-binding.ts
  participant IDs as channel-plugin-ids.ts
  participant Scope as gateway-request-scope.ts
  participant RT as Plugin Runtime
  participant Agent as Agent
  Chan->>Bind: Incoming message
  Bind->>IDs: Resolve plugin ID for channel
  IDs-->>Bind: pluginId
  Bind->>Scope: withPluginRuntimePluginIdScope(pluginId)
  Scope-->>RT: Scoped runtime context
  RT->>Agent: Provide channel-scoped tools
  Agent->>Agent: Execute with tools

The sequence above traces a single incoming message from a channel adapter through the full binding pipeline. The plugin identity is resolved once per message, and the scope is held for the duration of agent execution.

Annotated Code Walkthrough

const pluginId = channelPluginMap.get(message.channelType);
if (!pluginId) {
  throw new Error(`No plugin registered for channel: "${message.channelType}"`);
}

const result = withPluginRuntimePluginIdScope(pluginId, () => {
  // All tool calls inside this scope carry pluginId
  return resolvePluginTools({ context, allowlist, existingToolNames });
});

const binding = await resolveConversationBinding(message);
eventBus.emit('onConversationBindingResolved', {
  pluginId: binding.pluginId,
  channelType: binding.channelType,
  conversationId: binding.conversationId,
});

Edge Cases & Error Handling

Related Topics

• MCP Bridge overview — the parent sub-module page
• Tool Serving — how resolved tools are exposed to the agent
• Plugin Tools — tool resolution, allowlists, and conflict management

Directory Map

src/plugins/
├── conversation-binding.ts      ← Resolves incoming messages to plugin identity
├── channel-plugin-ids.ts        ← Channel type → plugin ID mapping registry
├── gateway-request-scope.ts     ← withPluginRuntimePluginIdScope() context manager
├── plugin-runtime.ts            ← Plugin runtime that invokes tool factories in scope
└── channels/
    ├── discord.ts               ← Discord channel adapter plugin
    ├── slack.ts                 ← Slack channel adapter plugin
    ├── whatsapp.ts              ← WhatsApp channel adapter plugin
    └── ...                      ← 20+ additional channel adapters