Merge pull request #2733 from nanocoai/feat/channel-instances

feat(channels): native channel-instance dimension — multi-bot substrate

Author: gavrielc

.claude/skills/add-github/SKILL.md

@@ -111,8 +111,8 @@ Run `/manage-channels` to wire the GitHub channel to an agent group, or insert m
 
 ```sql
 -- Create messaging group (one per repo)
-INSERT INTO messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy, created_at)
-VALUES ('mg-github-myrepo', 'github', 'github:owner/repo', 'owner/repo', 1, '<policy>', datetime('now'));
+INSERT INTO messaging_groups (id, channel_type, platform_id, instance, name, is_group, unknown_sender_policy, created_at)
+VALUES ('mg-github-myrepo', 'github', 'github:owner/repo', 'github', 'owner/repo', 1, '<policy>', datetime('now'));
 
 -- Wire to agent group
 INSERT INTO messaging_group_agents (id, messaging_group_id, agent_group_id, trigger_rules, response_scope, session_mode, priority, created_at)

.claude/skills/add-linear/SKILL.md

@@ -119,8 +119,8 @@ Run `/manage-channels` to wire the Linear channel to an agent group, or insert m
 
 ```sql
 -- Create messaging group (one per team)
-INSERT INTO messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy, created_at)
-VALUES ('mg-linear-eng', 'linear', 'linear:ENG', 'Engineering', 1, 'public', datetime('now'));
+INSERT INTO messaging_groups (id, channel_type, platform_id, instance, name, is_group, unknown_sender_policy, created_at)
+VALUES ('mg-linear-eng', 'linear', 'linear:ENG', 'linear', 'Engineering', 1, 'public', datetime('now'));
 
 -- Wire to agent group
 INSERT INTO messaging_group_agents (id, messaging_group_id, agent_group_id, trigger_rules, response_scope, session_mode, priority, created_at)

CLAUDE.md

@@ -33,7 +33,7 @@ user_dms (user_id, channel_type, messaging_group_id) — cold-DM cache
 
 agent_groups (workspace, memory, CLAUDE.md, personality, container config)
     ↕ many-to-many via messaging_group_agents (session_mode, trigger_rules, priority)
-messaging_groups (one chat/channel on one platform; unknown_sender_policy)
+messaging_groups (one chat/channel on one platform; instance = adapter-instance name, defaults to channel_type; unknown_sender_policy)
 
 sessions (agent_group_id + messaging_group_id + thread_id → per-session container)
 ```

docs/architecture.md

@@ -668,15 +668,19 @@ CREATE TABLE agent_groups (
 );
 
 -- Platform groups/channels (WhatsApp group, Slack channel, Discord channel, email thread, etc.)
+-- One row per chat PER ADAPTER INSTANCE. instance defaults to channel_type
+-- (the "default instance"), so single-instance installs never see it.
 CREATE TABLE messaging_groups (
   id                     TEXT PRIMARY KEY,
   channel_type           TEXT NOT NULL,     -- 'whatsapp', 'slack', 'discord', 'telegram', 'email'
   platform_id            TEXT NOT NULL,     -- platform-specific ID (JID, channel ID, etc.)
+  instance               TEXT NOT NULL,     -- adapter-instance name; default = channel_type
   name                   TEXT,
   is_group               INTEGER DEFAULT 0,
   unknown_sender_policy  TEXT NOT NULL DEFAULT 'strict',  -- 'strict' | 'request_approval' | 'public'
   created_at             TEXT NOT NULL,
-  UNIQUE(channel_type, platform_id)
+  denied_at              TEXT,
+  UNIQUE(channel_type, platform_id, instance)
 );
 
 -- Users (messaging platform identities, namespaced "<channel_type>:<handle>")

docs/db-central.md

@@ -27,21 +27,24 @@ CREATE TABLE agent_groups (
 
 ### 1.2 `messaging_groups`
 
-One row per platform chat (one WhatsApp group, one Slack channel, one 1:1 DM, etc.).
+One row per platform chat (one WhatsApp group, one Slack channel, one 1:1 DM, etc.) per adapter instance.
 
 ```sql
 CREATE TABLE messaging_groups (
   id                    TEXT PRIMARY KEY,
   channel_type          TEXT NOT NULL,
   platform_id           TEXT NOT NULL,
+  instance              TEXT NOT NULL,
   name                  TEXT,
   is_group              INTEGER DEFAULT 0,
   unknown_sender_policy TEXT NOT NULL DEFAULT 'strict',
   created_at            TEXT NOT NULL,
-  UNIQUE(channel_type, platform_id)
+  denied_at             TEXT,
+  UNIQUE(channel_type, platform_id, instance)
 );
 ```
 
+- `instance`: adapter-instance name — N adapters of one platform (e.g. three Slack apps in one workspace) each own their rows. The default instance IS the channel type: migration 016 backfills `instance = channel_type` and `createMessagingGroup` stamps the same default, so single-instance installs never see the dimension. Inbound lookups are exact-on-instance (an unknown named instance auto-creates its own row); outbound lookups resolve default-instance-first.
 - `unknown_sender_policy`: `strict` (drop), `request_approval` (ask admin), `public` (allow).
 - **Readers:** `src/router.ts`, `src/delivery.ts`, `src/session-manager.ts`
 - **Writers:** `src/db/messaging-groups.ts`, channel setup flows
@@ -134,7 +137,7 @@ CREATE TABLE user_dms (
 );
 ```
 
-Populated lazily by `ensureUserDm()` in `src/user-dm.ts`.
+Populated lazily by `ensureUserDm()` in `src/user-dm.ts`. Cold DMs resolve via the channel's default adapter instance — `PRIMARY KEY (user_id, channel_type)` is per-platform, not per-instance.
 
 ### 1.8 `sessions`
 

src/channels/adapter.ts

@@ -44,6 +44,9 @@ export interface DeliveryAddress {
  */
 export interface InboundEvent {
   channelType: string;
+  /** Receiving adapter instance; stamped host-side (src/index.ts onInbound).
+   *  Absent (e.g. CLI onInboundEvent) means the default instance (= channelType). */
+  instance?: string;
   platformId: string;
   threadId: string | null;
   message: {
@@ -112,6 +115,15 @@ export interface ChannelAdapter {
   name: string;
   channelType: string;
 
+  /**
+   * Adapter-instance name — distinguishes N adapters of one platform
+   * (e.g. three Slack apps in one workspace). Defaults to channelType.
+   * channelType stays the SEMANTIC platform key (user ids '<channelType>:<handle>',
+   * formatting, container config); instance is a host-side routing key only.
+   * Must be unique across active adapters and URL-safe (no '/', '?', ':').
+   */
+  instance?: string;
+
   /**
    * Whether this adapter models conversations as threads.
    *

src/channels/channel-registry.test.ts

@@ -30,19 +30,24 @@ function now() {
 /** Create a mock ChannelAdapter for testing. */
 function createMockAdapter(
   channelType: string,
-): ChannelAdapter & { delivered: OutboundMessage[]; inbound: InboundMessage[] } {
+  instance?: string,
+): ChannelAdapter & { delivered: OutboundMessage[]; inbound: InboundMessage[]; setupTimes: number[] } {
   const delivered: OutboundMessage[] = [];
   const inbound: InboundMessage[] = [];
+  const setupTimes: number[] = [];
   let setupConfig: ChannelSetup | null = null;
 
   return {
-    name: channelType,
+    name: instance ?? channelType,
     channelType,
+    instance,
     supportsThreads: false,
     delivered,
     inbound,
+    setupTimes,
 
     async setup(config: ChannelSetup) {
+      setupTimes.push(Date.now());
       setupConfig = config;
     },
 
@@ -117,6 +122,117 @@ describe('channel registry', () => {
   });
 });
 
+describe('channel registry — instance keying', () => {
+  // Fresh module per test: the registry and activeAdapters maps are
+  // module-level, and these arms register conflicting same-channelType
+  // adapters that must not leak across tests.
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(async () => {
+    const { teardownChannelAdapters } = await import('./channel-registry.js');
+    await teardownChannelAdapters();
+    // Drop this test's registrations so later describe blocks (which import
+    // the registry without resetting) start from an empty registry instead
+    // of inheriting same-channelType pairs.
+    vi.resetModules();
+  });
+
+  const mockSetup = () => ({
+    onInbound: () => {},
+    onInboundEvent: () => {},
+    onMetadata: () => {},
+    onAction: () => {},
+  });
+
+  it('keys two same-channelType adapters by instance — both resolvable', async () => {
+    const reg = await import('./channel-registry.js');
+    const worker = createMockAdapter('slack', 'slack-worker');
+    const tester = createMockAdapter('slack', 'slack-tester');
+    reg.registerChannelAdapter('slack-worker', { factory: () => worker });
+    reg.registerChannelAdapter('slack-tester', { factory: () => tester });
+
+    await reg.initChannelAdapters(mockSetup);
+
+    expect(reg.getChannelAdapter('slack-worker')).toBe(worker);
+    expect(reg.getChannelAdapter('slack-tester')).toBe(tester);
+    expect(reg.getActiveAdapters()).toHaveLength(2);
+  });
+
+  it('resolves channelType to the default-instance adapter when one exists, else first-registered', async () => {
+    const reg = await import('./channel-registry.js');
+    const named = createMockAdapter('slack', 'slack-tester');
+    const unnamed = createMockAdapter('slack');
+    reg.registerChannelAdapter('slack-tester', { factory: () => named });
+    reg.registerChannelAdapter('slack', { factory: () => unnamed });
+
+    await reg.initChannelAdapters(mockSetup);
+
+    // Exact key (default instance keyed by channelType) beats the fallback
+    // scan, even though the named sibling registered first.
+    expect(reg.getChannelAdapter('slack')).toBe(unnamed);
+
+    // With ONLY named instances active, channelType still resolves —
+    // deterministic first-registered fallback.
+    await reg.teardownChannelAdapters();
+    vi.resetModules();
+    const reg2 = await import('./channel-registry.js');
+    const first = createMockAdapter('slack', 'slack-tester');
+    const second = createMockAdapter('slack', 'slack-worker');
+    reg2.registerChannelAdapter('slack-tester', { factory: () => first });
+    reg2.registerChannelAdapter('slack-worker', { factory: () => second });
+    await reg2.initChannelAdapters(mockSetup);
+    expect(reg2.getChannelAdapter('slack')).toBe(first);
+  });
+
+  it('does NOT reroute default-instance outbound through a named sibling when the default adapter is missing', async () => {
+    // The default Slack app is offline (token rotated, factory returned
+    // null, …) while a named sibling boots fine. Outbound for the default
+    // instance must get the offline-adapter handling (drop into the retry
+    // path) — NEVER a cross-identity send through the sibling bot.
+    const reg = await import('./channel-registry.js');
+    const tester = createMockAdapter('slack', 'slack-tester');
+    reg.registerChannelAdapter('slack-tester', { factory: () => tester });
+    reg.registerChannelAdapter('slack', { factory: () => null });
+
+    await reg.initChannelAdapters(mockSetup);
+
+    // Exact lookup (delivery/typing path): the default key resolves nothing.
+    expect(reg.getChannelAdapterExact('slack')).toBeUndefined();
+    // Fallback-capable lookup (channelType-only callers) still resolves.
+    expect(reg.getChannelAdapter('slack')).toBe(tester);
+
+    // The delivery bridge dispatches by exact key: a default-instance
+    // message (instance === channelType after backfill) is dropped, not
+    // delivered through the sibling's identity.
+    const bridge = reg.createChannelDeliveryAdapter();
+    const result = await bridge.deliver(
+      'slack',
+      'slack:C1',
+      null,
+      'chat',
+      JSON.stringify({ text: 'to the default bot' }),
+      undefined,
+      'slack',
+    );
+    expect(result).toBeUndefined();
+    expect(tester.delivered).toHaveLength(0);
+
+    // Sanity: the same bridge DOES deliver when the exact instance is live.
+    await bridge.deliver(
+      'slack',
+      'slack:C1',
+      null,
+      'chat',
+      JSON.stringify({ text: 'to the tester bot' }),
+      undefined,
+      'slack-tester',
+    );
+    expect(tester.delivered).toHaveLength(1);
+  });
+});
+
 describe('channel + router integration', () => {
   beforeEach(async () => {
     if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });

src/channels/channel-registry.ts

@@ -4,7 +4,8 @@
  * Channels self-register on import. The host calls initChannelAdapters() at startup
  * to instantiate and set up all registered adapters.
  */
-import type { ChannelAdapter, ChannelRegistration, ChannelSetup } from './adapter.js';
+import type { ChannelAdapter, ChannelRegistration, ChannelSetup, OutboundFile } from './adapter.js';
+import type { ChannelDeliveryAdapter } from '../delivery.js';
 import { log } from '../log.js';
 
 const SETUP_RETRY_DELAYS_MS = [2000, 5000, 10000];
@@ -26,9 +27,79 @@ export function registerChannelAdapter(name: string, registration: ChannelRegist
   registry.set(name, registration);
 }
 
-/** Get a live adapter by channel type. */
-export function getChannelAdapter(channelType: string): ChannelAdapter | undefined {
-  return activeAdapters.get(channelType);
+/** Get a live adapter by its EXACT registry key (instance name; default
+ *  instances are keyed by channelType itself). No channelType fallback —
+ *  callers that address a specific instance (outbound delivery, typing)
+ *  must never be rerouted through a sibling instance: that would send
+ *  through the wrong bot identity with the wrong token. A missing key
+ *  means the owning adapter is offline; callers apply their normal
+ *  offline-adapter handling. */
+export function getChannelAdapterExact(key: string): ChannelAdapter | undefined {
+  return activeAdapters.get(key);
+}
+
+/** Get a live adapter by instance name, falling back to any adapter of the
+ *  given channel type. The fallback exists ONLY for channelType-only callers
+ *  (user-id prefix resolution and cold DMs in user-dm.ts, approval delivery
+ *  in channel-approval.ts, the router's thread-policy probe when an event
+ *  carries no instance) — they must still resolve when every instance of a
+ *  platform is named. First registered wins (Map insertion order,
+ *  deterministic). Default instances are keyed by channelType itself, so
+ *  single-instance installs always hit the exact-key path. Instance-addressed
+ *  dispatch (delivery, typing) must use getChannelAdapterExact instead. */
+export function getChannelAdapter(key: string): ChannelAdapter | undefined {
+  const exact = activeAdapters.get(key);
+  if (exact) return exact;
+  for (const [registryKey, adapter] of activeAdapters) {
+    if (adapter.channelType === key) {
+      log.warn('Channel adapter fallback: requested key resolved through a differently-keyed instance', {
+        requested: key,
+        resolvedKey: registryKey,
+      });
+      return adapter;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Build the host's outbound delivery bridge: dispatches delivery-poll and
+ * typing traffic into the adapter registry. Resolution is EXACT-key only —
+ * `instance ?? channelType`. For default-instance messaging_groups rows the
+ * stored instance IS the channelType, which matches default-registered
+ * adapters, so single-instance behavior is unchanged. A named instance whose
+ * adapter is offline gets the normal offline-adapter handling (warn + drop
+ * into the delivery retry path) — never a cross-identity send through a
+ * sibling bot of the same platform.
+ */
+export function createChannelDeliveryAdapter(): ChannelDeliveryAdapter {
+  return {
+    async deliver(
+      channelType: string,
+      platformId: string,
+      threadId: string | null,
+      kind: string,
+      content: string,
+      files?: OutboundFile[],
+      instance?: string,
+    ): Promise<string | undefined> {
+      const adapter = getChannelAdapterExact(instance ?? channelType);
+      if (!adapter) {
+        log.warn('No adapter for channel type', { channelType, instance });
+        return;
+      }
+      return adapter.deliver(platformId, threadId, { kind, content: JSON.parse(content), files });
+    },
+    async setTyping(
+      channelType: string,
+      platformId: string,
+      threadId: string | null,
+      instance?: string,
+    ): Promise<void> {
+      const adapter = getChannelAdapterExact(instance ?? channelType);
+      await adapter?.setTyping?.(platformId, threadId);
+    },
+  };
 }
 
 /** Get all active adapters. */
@@ -85,8 +156,16 @@ export async function initChannelAdapters(setupFn: (adapter: ChannelAdapter) =>
           throw err;
         }
       }
-      activeAdapters.set(adapter.channelType, adapter);
-      log.info('Channel adapter started', { channel: name, type: adapter.channelType });
+      // Adapters key by instance (default instance = channelType), so N
+      // instances of one platform coexist. Duplicate keys warn instead of
+      // throwing — boot stays resilient, matching the historical silent
+      // last-write-wins, but now visibly.
+      const key = adapter.instance ?? adapter.channelType;
+      if (activeAdapters.has(key)) {
+        log.warn('Duplicate adapter instance key — overwriting previous adapter', { key, channel: name });
+      }
+      activeAdapters.set(key, adapter);
+      log.info('Channel adapter started', { channel: name, type: adapter.channelType, instance: key });
     } catch (err) {
       log.error('Failed to start channel adapter', { channel: name, err });
     }