refactor: migrate messaging plugins to sdk

CHANGELOG.md

@@ -13,29 +13,18 @@ Docs: https://docs.clawd.bot
 ### Fixes
 - Auth profiles: keep auto-pinned preference while allowing rotation on failover; user pins stay locked. (#1138) — thanks @cheeeee.
 - macOS: avoid touching launchd in Remote over SSH so quitting the app no longer disables the remote gateway. (#1105)
-
 ## 2026.1.18-3
 
 ### Changes
 - Exec: add host/security/ask routing for gateway + node exec.
-- Exec: add `/exec` directive for per-session exec defaults (host/security/ask/node).
 - macOS: migrate exec approvals to `~/.clawdbot/exec-approvals.json` with per-agent allowlists and skill auto-allow toggle.
 - macOS: add approvals socket UI server + node exec lifecycle events.
-- Nodes: add headless node host (`clawdbot node start`) for `system.run`/`system.which`.
-- Nodes: add node daemon service install/status/start/stop/restart.
-- Bridge: add `skills.bins` RPC to support node host auto-allow skill bins.
-- Slash commands: replace `/cost` with `/usage off|tokens|full` to control per-response usage footer; `/usage` no longer aliases `/status`. (Supersedes #1140) — thanks @Nachx639.
-- Sessions: add daily reset policy with per-type overrides and idle windows (default 4am local), preserving legacy idle-only configs. (#1146) — thanks @austinm911.
-- Agents: auto-inject local image references for vision models and avoid reloading history images. (#1098) — thanks @tyler6204.
+- Plugins: ship Discord/Slack/Telegram/Signal/WhatsApp as bundled channel plugins via the shared SDK (iMessage now bundled + opt-in).
 - Docs: refresh exec/elevated/exec-approvals docs for the new flow. https://docs.clawd.bot/tools/exec-approvals
-- Docs: add node host CLI + update exec approvals/bridge protocol docs. https://docs.clawd.bot/cli/node
-- ACP: add experimental ACP support for IDE integrations (`clawdbot acp`). Thanks @visionik.
 
 ### Fixes
-- Exec approvals: enforce allowlist when ask is off; prefer raw command for node approvals/events.
 - Tools: return a companion-app-required message when node exec is requested with no paired node.
-- Streaming: emit assistant deltas for OpenAI-compatible SSE chunks. (#1147) — thanks @alauppe.
-- Model fallback: treat timeout aborts as failover while preserving user aborts. (#1137) — thanks @cheeeee.
+- Tests: avoid extension imports when wiring plugin registries in unit tests.
 
 ## 2026.1.18-2
 

extensions/discord/index.ts

@@ -0,0 +1,14 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+
+import { discordPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "discord",
+  name: "Discord",
+  description: "Discord channel plugin",
+  register(api: ClawdbotPluginApi) {
+    api.registerChannel({ plugin: discordPlugin });
+  },
+};
+
+export default plugin;

extensions/discord/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/discord",
+  "version": "2026.1.17-1",
+  "type": "module",
+  "description": "Clawdbot Discord channel plugin",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}

extensions/discord/src/channel.ts

@@ -0,0 +1,406 @@
+import {
+  applyAccountNameToChannelSection,
+  auditDiscordChannelPermissions,
+  buildChannelConfigSchema,
+  collectDiscordAuditChannelIds,
+  collectDiscordStatusIssues,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  discordMessageActions,
+  discordOnboardingAdapter,
+  DiscordConfigSchema,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  listDiscordAccountIds,
+  listDiscordDirectoryGroupsFromConfig,
+  listDiscordDirectoryGroupsLive,
+  listDiscordDirectoryPeersFromConfig,
+  listDiscordDirectoryPeersLive,
+  looksLikeDiscordTargetId,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  normalizeDiscordMessagingTarget,
+  PAIRING_APPROVED_MESSAGE,
+  probeDiscord,
+  resolveDiscordAccount,
+  resolveDefaultDiscordAccountId,
+  resolveDiscordChannelAllowlist,
+  resolveDiscordGroupRequireMention,
+  resolveDiscordUserAllowlist,
+  sendMessageDiscord,
+  sendPollDiscord,
+  setAccountEnabledInConfigSection,
+  shouldLogVerbose,
+  type ChannelPlugin,
+  type ResolvedDiscordAccount,
+} from "clawdbot/plugin-sdk";
+
+const meta = getChatChannelMeta("discord");
+
+export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount> = {
+  id: "discord",
+  meta: {
+    ...meta,
+  },
+  onboarding: discordOnboardingAdapter,
+  pairing: {
+    idLabel: "discordUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^(discord|user):/i, ""),
+    notifyApproval: async ({ id }) => {
+      await sendMessageDiscord(`user:${id}`, PAIRING_APPROVED_MESSAGE);
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "channel", "thread"],
+    polls: true,
+    reactions: true,
+    threads: true,
+    media: true,
+    nativeCommands: true,
+  },
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+  reload: { configPrefixes: ["channels.discord"] },
+  configSchema: buildChannelConfigSchema(DiscordConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listDiscordAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveDiscordAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultDiscordAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "discord",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "discord",
+        accountId,
+        clearBaseFields: ["token", "name"],
+      }),
+    isConfigured: (account) => Boolean(account.token?.trim()),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.token?.trim()),
+      tokenSource: account.tokenSource,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveDiscordAccount({ cfg, accountId }).config.dm?.allowFrom ?? []).map((entry) =>
+        String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.toLowerCase()),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.discord?.accounts?.[resolvedAccountId]);
+      const allowFromPath = useAccountPath
+        ? `channels.discord.accounts.${resolvedAccountId}.dm.`
+        : "channels.discord.dm.";
+      return {
+        policy: account.config.dm?.policy ?? "pairing",
+        allowFrom: account.config.dm?.allowFrom ?? [],
+        allowFromPath,
+        approveHint: formatPairingApproveHint("discord"),
+        normalizeEntry: (raw) => raw.replace(/^(discord|user):/i, "").replace(/^<@!?(\d+)>$/, "$1"),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const warnings: string[] = [];
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "open";
+      const guildEntries = account.config.guilds ?? {};
+      const guildsConfigured = Object.keys(guildEntries).length > 0;
+      const channelAllowlistConfigured = guildsConfigured;
+
+      if (groupPolicy === "open") {
+        if (channelAllowlistConfigured) {
+          warnings.push(
+            `- Discord guilds: groupPolicy="open" allows any channel not explicitly denied to trigger (mention-gated). Set channels.discord.groupPolicy="allowlist" and configure channels.discord.guilds.<id>.channels.`,
+          );
+        } else {
+          warnings.push(
+            `- Discord guilds: groupPolicy="open" with no guild/channel allowlist; any channel can trigger (mention-gated). Set channels.discord.groupPolicy="allowlist" and configure channels.discord.guilds.<id>.channels.`,
+          );
+        }
+      }
+
+      return warnings;
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveDiscordGroupRequireMention,
+  },
+  mentions: {
+    stripPatterns: () => ["<@!?\\d+>"],
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg }) => cfg.channels?.discord?.replyToMode ?? "off",
+  },
+  messaging: {
+    normalizeTarget: normalizeDiscordMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeDiscordTargetId,
+      hint: "<channelId|user:ID|channel:ID>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async (params) => listDiscordDirectoryPeersFromConfig(params),
+    listGroups: async (params) => listDiscordDirectoryGroupsFromConfig(params),
+    listPeersLive: async (params) => listDiscordDirectoryPeersLive(params),
+    listGroupsLive: async (params) => listDiscordDirectoryGroupsLive(params),
+  },
+  resolver: {
+    resolveTargets: async ({ cfg, accountId, inputs, kind }) => {
+      const account = resolveDiscordAccount({ cfg, accountId });
+      const token = account.token?.trim();
+      if (!token) {
+        return inputs.map((input) => ({
+          input,
+          resolved: false,
+          note: "missing Discord token",
+        }));
+      }
+      if (kind === "group") {
+        const resolved = await resolveDiscordChannelAllowlist({ token, entries: inputs });
+        return resolved.map((entry) => ({
+          input: entry.input,
+          resolved: entry.resolved,
+          id: entry.channelId ?? entry.guildId,
+          name:
+            entry.channelName ??
+            entry.guildName ??
+            (entry.guildId && !entry.channelId ? entry.guildId : undefined),
+          note: entry.note,
+        }));
+      }
+      const resolved = await resolveDiscordUserAllowlist({ token, entries: inputs });
+      return resolved.map((entry) => ({
+        input: entry.input,
+        resolved: entry.resolved,
+        id: entry.id,
+        name: entry.name,
+        note: entry.note,
+      }));
+    },
+  },
+  actions: discordMessageActions,
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "discord",
+        accountId,
+        name,
+      }),
+    validateInput: ({ accountId, input }) => {
+      if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+        return "DISCORD_BOT_TOKEN can only be used for the default account.";
+      }
+      if (!input.useEnv && !input.token) {
+        return "Discord requires token (or --use-env).";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "discord",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "discord",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            discord: {
+              ...next.channels?.discord,
+              enabled: true,
+              ...(input.useEnv ? {} : input.token ? { token: input.token } : {}),
+            },
+          },
+        };
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          discord: {
+            ...next.channels?.discord,
+            enabled: true,
+            accounts: {
+              ...next.channels?.discord?.accounts,
+              [accountId]: {
+                ...next.channels?.discord?.accounts?.[accountId],
+                enabled: true,
+                ...(input.token ? { token: input.token } : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: null,
+    textChunkLimit: 2000,
+    pollMaxOptions: 10,
+    sendText: async ({ to, text, accountId, deps, replyToId }) => {
+      const send = deps?.sendDiscord ?? sendMessageDiscord;
+      const result = await send(to, text, {
+        verbose: false,
+        replyTo: replyToId ?? undefined,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "discord", ...result };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, deps, replyToId }) => {
+      const send = deps?.sendDiscord ?? sendMessageDiscord;
+      const result = await send(to, text, {
+        verbose: false,
+        mediaUrl,
+        replyTo: replyToId ?? undefined,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "discord", ...result };
+    },
+    sendPoll: async ({ to, poll, accountId }) =>
+      await sendPollDiscord(to, poll, {
+        accountId: accountId ?? undefined,
+      }),
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: collectDiscordStatusIssues,
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      tokenSource: snapshot.tokenSource ?? "none",
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }) =>
+      probeDiscord(account.token, timeoutMs, { includeApplication: true }),
+    auditAccount: async ({ account, timeoutMs, cfg }) => {
+      const { channelIds, unresolvedChannels } = collectDiscordAuditChannelIds({
+        cfg,
+        accountId: account.accountId,
+      });
+      if (!channelIds.length && unresolvedChannels === 0) return undefined;
+      const botToken = account.token?.trim();
+      if (!botToken) {
+        return {
+          ok: unresolvedChannels === 0,
+          checkedChannels: 0,
+          unresolvedChannels,
+          channels: [],
+          elapsedMs: 0,
+        };
+      }
+      const audit = await auditDiscordChannelPermissions({
+        token: botToken,
+        accountId: account.accountId,
+        channelIds,
+        timeoutMs,
+      });
+      return { ...audit, unresolvedChannels };
+    },
+    buildAccountSnapshot: ({ account, runtime, probe, audit }) => {
+      const configured = Boolean(account.token?.trim());
+      const app = runtime?.application ?? (probe as { application?: unknown })?.application;
+      const bot = runtime?.bot ?? (probe as { bot?: unknown })?.bot;
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured,
+        tokenSource: account.tokenSource,
+        running: runtime?.running ?? false,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        application: app ?? undefined,
+        bot: bot ?? undefined,
+        probe,
+        audit,
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const token = account.token.trim();
+      let discordBotLabel = "";
+      try {
+        const probe = await probeDiscord(token, 2500, {
+          includeApplication: true,
+        });
+        const username = probe.ok ? probe.bot?.username?.trim() : null;
+        if (username) discordBotLabel = ` (@${username})`;
+        ctx.setStatus({
+          accountId: account.accountId,
+          bot: probe.bot,
+          application: probe.application,
+        });
+        const messageContent = probe.application?.intents?.messageContent;
+        if (messageContent === "disabled") {
+          ctx.log?.warn(
+            `[${account.accountId}] Discord Message Content Intent is disabled; bot may not respond to channel messages. Enable it in Discord Dev Portal (Bot → Privileged Gateway Intents) or require mentions.`,
+          );
+        } else if (messageContent === "limited") {
+          ctx.log?.info(
+            `[${account.accountId}] Discord Message Content Intent is limited; bots under 100 servers can use it without verification.`,
+          );
+        }
+      } catch (err) {
+        if (shouldLogVerbose()) {
+          ctx.log?.debug?.(`[${account.accountId}] bot probe failed: ${String(err)}`);
+        }
+      }
+      ctx.log?.info(`[${account.accountId}] starting provider${discordBotLabel}`);
+      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+      const { monitorDiscordProvider } = await import("clawdbot/plugin-sdk");
+      return monitorDiscordProvider({
+        token,
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        mediaMaxMb: account.config.mediaMaxMb,
+        historyLimit: account.config.historyLimit,
+      });
+    },
+  },
+};

extensions/imessage/index.ts

@@ -0,0 +1,14 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+
+import { imessagePlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "imessage",
+  name: "iMessage",
+  description: "iMessage channel plugin",
+  register(api: ClawdbotPluginApi) {
+    api.registerChannel({ plugin: imessagePlugin });
+  },
+};
+
+export default plugin;

extensions/imessage/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/imessage",
+  "version": "2026.1.17-1",
+  "type": "module",
+  "description": "Clawdbot iMessage channel plugin",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}

extensions/imessage/src/channel.ts

@@ -0,0 +1,291 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  chunkText,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  imessageOnboardingAdapter,
+  IMessageConfigSchema,
+  listIMessageAccountIds,
+  migrateBaseNameToDefaultAccount,
+  monitorIMessageProvider,
+  normalizeAccountId,
+  PAIRING_APPROVED_MESSAGE,
+  probeIMessage,
+  resolveChannelMediaMaxBytes,
+  resolveDefaultIMessageAccountId,
+  resolveIMessageAccount,
+  resolveIMessageGroupRequireMention,
+  setAccountEnabledInConfigSection,
+  sendMessageIMessage,
+  type ChannelPlugin,
+  type ResolvedIMessageAccount,
+} from "clawdbot/plugin-sdk";
+
+const meta = getChatChannelMeta("imessage");
+
+export const imessagePlugin: ChannelPlugin<ResolvedIMessageAccount> = {
+  id: "imessage",
+  meta: {
+    ...meta,
+    showConfigured: false,
+  },
+  onboarding: imessageOnboardingAdapter,
+  pairing: {
+    idLabel: "imessageSenderId",
+    notifyApproval: async ({ id }) => {
+      await sendMessageIMessage(id, PAIRING_APPROVED_MESSAGE);
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+  },
+  reload: { configPrefixes: ["channels.imessage"] },
+  configSchema: buildChannelConfigSchema(IMessageConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listIMessageAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveIMessageAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultIMessageAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "imessage",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "imessage",
+        accountId,
+        clearBaseFields: ["cliPath", "dbPath", "service", "region", "name"],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveIMessageAccount({ cfg, accountId }).config.allowFrom ?? []).map((entry) =>
+        String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom.map((entry) => String(entry).trim()).filter(Boolean),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.imessage?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.imessage.accounts.${resolvedAccountId}.`
+        : "channels.imessage.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("imessage"),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- iMessage groups: groupPolicy="open" allows any member to trigger the bot. Set channels.imessage.groupPolicy="allowlist" + channels.imessage.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveIMessageGroupRequireMention,
+  },
+  messaging: {
+    targetResolver: {
+      looksLikeId: (raw) => {
+        const trimmed = raw.trim();
+        if (!trimmed) return false;
+        if (/^(imessage:|chat_id:)/i.test(trimmed)) return true;
+        if (trimmed.includes("@")) return true;
+        return /^\+?\d{3,}$/.test(trimmed);
+      },
+      hint: "<handle|chat_id:ID>",
+    },
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "imessage",
+        accountId,
+        name,
+      }),
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "imessage",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "imessage",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            imessage: {
+              ...next.channels?.imessage,
+              enabled: true,
+              ...(input.cliPath ? { cliPath: input.cliPath } : {}),
+              ...(input.dbPath ? { dbPath: input.dbPath } : {}),
+              ...(input.service ? { service: input.service } : {}),
+              ...(input.region ? { region: input.region } : {}),
+            },
+          },
+        };
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          imessage: {
+            ...next.channels?.imessage,
+            enabled: true,
+            accounts: {
+              ...next.channels?.imessage?.accounts,
+              [accountId]: {
+                ...next.channels?.imessage?.accounts?.[accountId],
+                enabled: true,
+                ...(input.cliPath ? { cliPath: input.cliPath } : {}),
+                ...(input.dbPath ? { dbPath: input.dbPath } : {}),
+                ...(input.service ? { service: input.service } : {}),
+                ...(input.region ? { region: input.region } : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: chunkText,
+    textChunkLimit: 4000,
+    sendText: async ({ cfg, to, text, accountId, deps }) => {
+      const send = deps?.sendIMessage ?? sendMessageIMessage;
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          cfg.channels?.imessage?.accounts?.[accountId]?.mediaMaxMb ??
+          cfg.channels?.imessage?.mediaMaxMb,
+        accountId,
+      });
+      const result = await send(to, text, {
+        maxBytes,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "imessage", ...result };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, accountId, deps }) => {
+      const send = deps?.sendIMessage ?? sendMessageIMessage;
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          cfg.channels?.imessage?.accounts?.[accountId]?.mediaMaxMb ??
+          cfg.channels?.imessage?.mediaMaxMb,
+        accountId,
+      });
+      const result = await send(to, text, {
+        mediaUrl,
+        maxBytes,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "imessage", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+      cliPath: null,
+      dbPath: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((account) => {
+        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+        if (!lastError) return [];
+        return [
+          {
+            channel: "imessage",
+            accountId: account.accountId,
+            kind: "runtime",
+            message: `Channel error: ${lastError}`,
+          },
+        ];
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      cliPath: snapshot.cliPath ?? null,
+      dbPath: snapshot.dbPath ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ timeoutMs }) => probeIMessage(timeoutMs),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      cliPath: runtime?.cliPath ?? account.config.cliPath ?? null,
+      dbPath: runtime?.dbPath ?? account.config.dbPath ?? null,
+      probe,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+    resolveAccountState: ({ enabled }) => (enabled ? "enabled" : "disabled"),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const cliPath = account.config.cliPath?.trim() || "imsg";
+      const dbPath = account.config.dbPath?.trim();
+      ctx.setStatus({
+        accountId: account.accountId,
+        cliPath,
+        dbPath: dbPath ?? null,
+      });
+      ctx.log?.info(
+        `[${account.accountId}] starting provider (${cliPath}${dbPath ? ` db=${dbPath}` : ""})`,
+      );
+      return monitorIMessageProvider({
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+      });
+    },
+  },
+};

extensions/signal/index.ts

@@ -0,0 +1,14 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+
+import { signalPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "signal",
+  name: "Signal",
+  description: "Signal channel plugin",
+  register(api: ClawdbotPluginApi) {
+    api.registerChannel({ plugin: signalPlugin });
+  },
+};
+
+export default plugin;

extensions/signal/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/signal",
+  "version": "2026.1.17-1",
+  "type": "module",
+  "description": "Clawdbot Signal channel plugin",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}

extensions/signal/src/channel.ts

@@ -0,0 +1,303 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  chunkText,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  listSignalAccountIds,
+  looksLikeSignalTargetId,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  normalizeE164,
+  normalizeSignalMessagingTarget,
+  PAIRING_APPROVED_MESSAGE,
+  probeSignal,
+  resolveChannelMediaMaxBytes,
+  resolveDefaultSignalAccountId,
+  resolveSignalAccount,
+  sendMessageSignal,
+  setAccountEnabledInConfigSection,
+  signalOnboardingAdapter,
+  SignalConfigSchema,
+  type ChannelPlugin,
+  type ResolvedSignalAccount,
+} from "clawdbot/plugin-sdk";
+
+const meta = getChatChannelMeta("signal");
+
+export const signalPlugin: ChannelPlugin<ResolvedSignalAccount> = {
+  id: "signal",
+  meta: {
+    ...meta,
+  },
+  onboarding: signalOnboardingAdapter,
+  pairing: {
+    idLabel: "signalNumber",
+    normalizeAllowEntry: (entry) => entry.replace(/^signal:/i, ""),
+    notifyApproval: async ({ id }) => {
+      await sendMessageSignal(id, PAIRING_APPROVED_MESSAGE);
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+  },
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+  reload: { configPrefixes: ["channels.signal"] },
+  configSchema: buildChannelConfigSchema(SignalConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listSignalAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveSignalAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultSignalAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "signal",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "signal",
+        accountId,
+        clearBaseFields: ["account", "httpUrl", "httpHost", "httpPort", "cliPath", "name"],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.baseUrl,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveSignalAccount({ cfg, accountId }).config.allowFrom ?? []).map((entry) =>
+        String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => (entry === "*" ? "*" : normalizeE164(entry.replace(/^signal:/i, ""))))
+        .filter(Boolean),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.signal?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.signal.accounts.${resolvedAccountId}.`
+        : "channels.signal.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("signal"),
+        normalizeEntry: (raw) => normalizeE164(raw.replace(/^signal:/i, "").trim()),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- Signal groups: groupPolicy="open" allows any member to trigger the bot. Set channels.signal.groupPolicy="allowlist" + channels.signal.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  messaging: {
+    normalizeTarget: normalizeSignalMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeSignalTargetId,
+      hint: "<E.164|group:ID|signal:group:ID|signal:+E.164>",
+    },
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "signal",
+        accountId,
+        name,
+      }),
+    validateInput: ({ input }) => {
+      if (
+        !input.signalNumber &&
+        !input.httpUrl &&
+        !input.httpHost &&
+        !input.httpPort &&
+        !input.cliPath
+      ) {
+        return "Signal requires --signal-number or --http-url/--http-host/--http-port/--cli-path.";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "signal",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "signal",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            signal: {
+              ...next.channels?.signal,
+              enabled: true,
+              ...(input.signalNumber ? { account: input.signalNumber } : {}),
+              ...(input.cliPath ? { cliPath: input.cliPath } : {}),
+              ...(input.httpUrl ? { httpUrl: input.httpUrl } : {}),
+              ...(input.httpHost ? { httpHost: input.httpHost } : {}),
+              ...(input.httpPort ? { httpPort: Number(input.httpPort) } : {}),
+            },
+          },
+        };
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          signal: {
+            ...next.channels?.signal,
+            enabled: true,
+            accounts: {
+              ...next.channels?.signal?.accounts,
+              [accountId]: {
+                ...next.channels?.signal?.accounts?.[accountId],
+                enabled: true,
+                ...(input.signalNumber ? { account: input.signalNumber } : {}),
+                ...(input.cliPath ? { cliPath: input.cliPath } : {}),
+                ...(input.httpUrl ? { httpUrl: input.httpUrl } : {}),
+                ...(input.httpHost ? { httpHost: input.httpHost } : {}),
+                ...(input.httpPort ? { httpPort: Number(input.httpPort) } : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: chunkText,
+    textChunkLimit: 4000,
+    sendText: async ({ cfg, to, text, accountId, deps }) => {
+      const send = deps?.sendSignal ?? sendMessageSignal;
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          cfg.channels?.signal?.accounts?.[accountId]?.mediaMaxMb ??
+          cfg.channels?.signal?.mediaMaxMb,
+        accountId,
+      });
+      const result = await send(to, text, {
+        maxBytes,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "signal", ...result };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, accountId, deps }) => {
+      const send = deps?.sendSignal ?? sendMessageSignal;
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          cfg.channels?.signal?.accounts?.[accountId]?.mediaMaxMb ??
+          cfg.channels?.signal?.mediaMaxMb,
+        accountId,
+      });
+      const result = await send(to, text, {
+        mediaUrl,
+        maxBytes,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "signal", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((account) => {
+        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+        if (!lastError) return [];
+        return [
+          {
+            channel: "signal",
+            accountId: account.accountId,
+            kind: "runtime",
+            message: `Channel error: ${lastError}`,
+          },
+        ];
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      baseUrl: snapshot.baseUrl ?? null,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }) => {
+      const baseUrl = account.baseUrl;
+      return await probeSignal(baseUrl, timeoutMs);
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.baseUrl,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        baseUrl: account.baseUrl,
+      });
+      ctx.log?.info(`[${account.accountId}] starting provider (${account.baseUrl})`);
+      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+      const { monitorSignalProvider } = await import("clawdbot/plugin-sdk");
+      return monitorSignalProvider({
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        mediaMaxMb: account.config.mediaMaxMb,
+      });
+    },
+  },
+};

extensions/slack/index.ts

@@ -0,0 +1,14 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+
+import { slackPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "slack",
+  name: "Slack",
+  description: "Slack channel plugin",
+  register(api: ClawdbotPluginApi) {
+    api.registerChannel({ plugin: slackPlugin });
+  },
+};
+
+export default plugin;

extensions/slack/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/slack",
+  "version": "2026.1.17-1",
+  "type": "module",
+  "description": "Clawdbot Slack channel plugin",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}

extensions/slack/src/channel.ts

@@ -0,0 +1,585 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  createActionGate,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  handleSlackAction,
+  loadConfig,
+  listEnabledSlackAccounts,
+  listSlackAccountIds,
+  listSlackDirectoryGroupsFromConfig,
+  listSlackDirectoryGroupsLive,
+  listSlackDirectoryPeersFromConfig,
+  listSlackDirectoryPeersLive,
+  looksLikeSlackTargetId,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  normalizeSlackMessagingTarget,
+  PAIRING_APPROVED_MESSAGE,
+  probeSlack,
+  readNumberParam,
+  readStringParam,
+  resolveDefaultSlackAccountId,
+  resolveSlackAccount,
+  resolveSlackChannelAllowlist,
+  resolveSlackGroupRequireMention,
+  resolveSlackUserAllowlist,
+  sendMessageSlack,
+  setAccountEnabledInConfigSection,
+  slackOnboardingAdapter,
+  SlackConfigSchema,
+  type ChannelMessageActionName,
+  type ChannelPlugin,
+  type ResolvedSlackAccount,
+} from "clawdbot/plugin-sdk";
+
+const meta = getChatChannelMeta("slack");
+
+// Select the appropriate Slack token for read/write operations.
+function getTokenForOperation(
+  account: ResolvedSlackAccount,
+  operation: "read" | "write",
+): string | undefined {
+  const userToken = account.config.userToken?.trim() || undefined;
+  const botToken = account.botToken?.trim();
+  const allowUserWrites = account.config.userTokenReadOnly === false;
+  if (operation === "read") return userToken ?? botToken;
+  if (!allowUserWrites) return botToken;
+  return botToken ?? userToken;
+}
+
+export const slackPlugin: ChannelPlugin<ResolvedSlackAccount> = {
+  id: "slack",
+  meta: {
+    ...meta,
+  },
+  onboarding: slackOnboardingAdapter,
+  pairing: {
+    idLabel: "slackUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^(slack|user):/i, ""),
+    notifyApproval: async ({ id }) => {
+      const cfg = loadConfig();
+      const account = resolveSlackAccount({
+        cfg,
+        accountId: DEFAULT_ACCOUNT_ID,
+      });
+      const token = getTokenForOperation(account, "write");
+      const botToken = account.botToken?.trim();
+      const tokenOverride = token && token !== botToken ? token : undefined;
+      if (tokenOverride) {
+        await sendMessageSlack(`user:${id}`, PAIRING_APPROVED_MESSAGE, {
+          token: tokenOverride,
+        });
+      } else {
+        await sendMessageSlack(`user:${id}`, PAIRING_APPROVED_MESSAGE);
+      }
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "channel", "thread"],
+    reactions: true,
+    threads: true,
+    media: true,
+    nativeCommands: true,
+  },
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+  reload: { configPrefixes: ["channels.slack"] },
+  configSchema: buildChannelConfigSchema(SlackConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listSlackAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveSlackAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultSlackAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "slack",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "slack",
+        accountId,
+        clearBaseFields: ["botToken", "appToken", "name"],
+      }),
+    isConfigured: (account) => Boolean(account.botToken && account.appToken),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.botToken && account.appToken),
+      botTokenSource: account.botTokenSource,
+      appTokenSource: account.appTokenSource,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveSlackAccount({ cfg, accountId }).dm?.allowFrom ?? []).map((entry) => String(entry)),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.toLowerCase()),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.slack?.accounts?.[resolvedAccountId]);
+      const allowFromPath = useAccountPath
+        ? `channels.slack.accounts.${resolvedAccountId}.dm.`
+        : "channels.slack.dm.";
+      return {
+        policy: account.dm?.policy ?? "pairing",
+        allowFrom: account.dm?.allowFrom ?? [],
+        allowFromPath,
+        approveHint: formatPairingApproveHint("slack"),
+        normalizeEntry: (raw) => raw.replace(/^(slack|user):/i, ""),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const warnings: string[] = [];
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "open";
+      const channelAllowlistConfigured =
+        Boolean(account.config.channels) && Object.keys(account.config.channels ?? {}).length > 0;
+
+      if (groupPolicy === "open") {
+        if (channelAllowlistConfigured) {
+          warnings.push(
+            `- Slack channels: groupPolicy="open" allows any channel not explicitly denied to trigger (mention-gated). Set channels.slack.groupPolicy="allowlist" and configure channels.slack.channels.`,
+          );
+        } else {
+          warnings.push(
+            `- Slack channels: groupPolicy="open" with no channel allowlist; any channel can trigger (mention-gated). Set channels.slack.groupPolicy="allowlist" and configure channels.slack.channels.`,
+          );
+        }
+      }
+
+      return warnings;
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveSlackGroupRequireMention,
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg, accountId }) =>
+      resolveSlackAccount({ cfg, accountId }).replyToMode ?? "off",
+    allowTagsWhenOff: true,
+    buildToolContext: ({ cfg, accountId, context, hasRepliedRef }) => {
+      const configuredReplyToMode = resolveSlackAccount({ cfg, accountId }).replyToMode ?? "off";
+      const effectiveReplyToMode = context.ThreadLabel ? "all" : configuredReplyToMode;
+      return {
+        currentChannelId: context.To?.startsWith("channel:")
+          ? context.To.slice("channel:".length)
+          : undefined,
+        currentThreadTs: context.ReplyToId,
+        replyToMode: effectiveReplyToMode,
+        hasRepliedRef,
+      };
+    },
+  },
+  messaging: {
+    normalizeTarget: normalizeSlackMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeSlackTargetId,
+      hint: "<channelId|user:ID|channel:ID>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async (params) => listSlackDirectoryPeersFromConfig(params),
+    listGroups: async (params) => listSlackDirectoryGroupsFromConfig(params),
+    listPeersLive: async (params) => listSlackDirectoryPeersLive(params),
+    listGroupsLive: async (params) => listSlackDirectoryGroupsLive(params),
+  },
+  resolver: {
+    resolveTargets: async ({ cfg, accountId, inputs, kind }) => {
+      const account = resolveSlackAccount({ cfg, accountId });
+      const token = account.config.userToken?.trim() || account.botToken?.trim();
+      if (!token) {
+        return inputs.map((input) => ({
+          input,
+          resolved: false,
+          note: "missing Slack token",
+        }));
+      }
+      if (kind === "group") {
+        const resolved = await resolveSlackChannelAllowlist({ token, entries: inputs });
+        return resolved.map((entry) => ({
+          input: entry.input,
+          resolved: entry.resolved,
+          id: entry.id,
+          name: entry.name,
+          note: entry.archived ? "archived" : undefined,
+        }));
+      }
+      const resolved = await resolveSlackUserAllowlist({ token, entries: inputs });
+      return resolved.map((entry) => ({
+        input: entry.input,
+        resolved: entry.resolved,
+        id: entry.id,
+        name: entry.name,
+        note: entry.note,
+      }));
+    },
+  },
+  actions: {
+    listActions: ({ cfg }) => {
+      const accounts = listEnabledSlackAccounts(cfg).filter(
+        (account) => account.botTokenSource !== "none",
+      );
+      if (accounts.length === 0) return [];
+      const isActionEnabled = (key: string, defaultValue = true) => {
+        for (const account of accounts) {
+          const gate = createActionGate(
+            (account.actions ?? cfg.channels?.slack?.actions) as Record<string, boolean | undefined>,
+          );
+          if (gate(key, defaultValue)) return true;
+        }
+        return false;
+      };
+
+      const actions = new Set<ChannelMessageActionName>(["send"]);
+      if (isActionEnabled("reactions")) {
+        actions.add("react");
+        actions.add("reactions");
+      }
+      if (isActionEnabled("messages")) {
+        actions.add("read");
+        actions.add("edit");
+        actions.add("delete");
+      }
+      if (isActionEnabled("pins")) {
+        actions.add("pin");
+        actions.add("unpin");
+        actions.add("list-pins");
+      }
+      if (isActionEnabled("memberInfo")) actions.add("member-info");
+      if (isActionEnabled("emojiList")) actions.add("emoji-list");
+      return Array.from(actions);
+    },
+    extractToolSend: ({ args }) => {
+      const action = typeof args.action === "string" ? args.action.trim() : "";
+      if (action !== "sendMessage") return null;
+      const to = typeof args.to === "string" ? args.to : undefined;
+      if (!to) return null;
+      const accountId = typeof args.accountId === "string" ? args.accountId.trim() : undefined;
+      return { to, accountId };
+    },
+    handleAction: async ({ action, params, cfg, accountId, toolContext }) => {
+      const resolveChannelId = () =>
+        readStringParam(params, "channelId") ?? readStringParam(params, "to", { required: true });
+
+      if (action === "send") {
+        const to = readStringParam(params, "to", { required: true });
+        const content = readStringParam(params, "message", {
+          required: true,
+          allowEmpty: true,
+        });
+        const mediaUrl = readStringParam(params, "media", { trim: false });
+        const threadId = readStringParam(params, "threadId");
+        const replyTo = readStringParam(params, "replyTo");
+        return await handleSlackAction(
+          {
+            action: "sendMessage",
+            to,
+            content,
+            mediaUrl: mediaUrl ?? undefined,
+            accountId: accountId ?? undefined,
+            threadTs: threadId ?? replyTo ?? undefined,
+          },
+          cfg,
+          toolContext,
+        );
+      }
+
+      if (action === "react") {
+        const messageId = readStringParam(params, "messageId", {
+          required: true,
+        });
+        const emoji = readStringParam(params, "emoji", { allowEmpty: true });
+        const remove = typeof params.remove === "boolean" ? params.remove : undefined;
+        return await handleSlackAction(
+          {
+            action: "react",
+            channelId: resolveChannelId(),
+            messageId,
+            emoji,
+            remove,
+            accountId: accountId ?? undefined,
+          },
+          cfg,
+        );
+      }
+
+      if (action === "reactions") {
+        const messageId = readStringParam(params, "messageId", {
+          required: true,
+        });
+        const limit = readNumberParam(params, "limit", { integer: true });
+        return await handleSlackAction(
+          {
+            action: "reactions",
+            channelId: resolveChannelId(),
+            messageId,
+            limit,
+            accountId: accountId ?? undefined,
+          },
+          cfg,
+        );
+      }
+
+      if (action === "read") {
+        const limit = readNumberParam(params, "limit", { integer: true });
+        return await handleSlackAction(
+          {
+            action: "readMessages",
+            channelId: resolveChannelId(),
+            limit,
+            before: readStringParam(params, "before"),
+            after: readStringParam(params, "after"),
+            accountId: accountId ?? undefined,
+          },
+          cfg,
+        );
+      }
+
+      if (action === "edit") {
+        const messageId = readStringParam(params, "messageId", {
+          required: true,
+        });
+        const content = readStringParam(params, "message", { required: true });
+        return await handleSlackAction(
+          {
+            action: "editMessage",
+            channelId: resolveChannelId(),
+            messageId,
+            content,
+            accountId: accountId ?? undefined,
+          },
+          cfg,
+        );
+      }
+
+      if (action === "delete") {
+        const messageId = readStringParam(params, "messageId", {
+          required: true,
+        });
+        return await handleSlackAction(
+          {
+            action: "deleteMessage",
+            channelId: resolveChannelId(),
+            messageId,
+            accountId: accountId ?? undefined,
+          },
+          cfg,
+        );
+      }
+
+      if (action === "pin" || action === "unpin" || action === "list-pins") {
+        const messageId =
+          action === "list-pins"
+            ? undefined
+            : readStringParam(params, "messageId", { required: true });
+        return await handleSlackAction(
+          {
+            action:
+              action === "pin" ? "pinMessage" : action === "unpin" ? "unpinMessage" : "listPins",
+            channelId: resolveChannelId(),
+            messageId,
+            accountId: accountId ?? undefined,
+          },
+          cfg,
+        );
+      }
+
+      if (action === "member-info") {
+        const userId = readStringParam(params, "userId", { required: true });
+        return await handleSlackAction(
+          { action: "memberInfo", userId, accountId: accountId ?? undefined },
+          cfg,
+        );
+      }
+
+      if (action === "emoji-list") {
+        return await handleSlackAction(
+          { action: "emojiList", accountId: accountId ?? undefined },
+          cfg,
+        );
+      }
+
+      throw new Error(`Action ${action} is not supported for provider ${meta.id}.`);
+    },
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "slack",
+        accountId,
+        name,
+      }),
+    validateInput: ({ accountId, input }) => {
+      if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+        return "Slack env tokens can only be used for the default account.";
+      }
+      if (!input.useEnv && (!input.botToken || !input.appToken)) {
+        return "Slack requires --bot-token and --app-token (or --use-env).";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "slack",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "slack",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            slack: {
+              ...next.channels?.slack,
+              enabled: true,
+              ...(input.useEnv
+                ? {}
+                : {
+                    ...(input.botToken ? { botToken: input.botToken } : {}),
+                    ...(input.appToken ? { appToken: input.appToken } : {}),
+                  }),
+            },
+          },
+        };
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          slack: {
+            ...next.channels?.slack,
+            enabled: true,
+            accounts: {
+              ...next.channels?.slack?.accounts,
+              [accountId]: {
+                ...next.channels?.slack?.accounts?.[accountId],
+                enabled: true,
+                ...(input.botToken ? { botToken: input.botToken } : {}),
+                ...(input.appToken ? { appToken: input.appToken } : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: null,
+    textChunkLimit: 4000,
+    sendText: async ({ to, text, accountId, deps, replyToId, cfg }) => {
+      const send = deps?.sendSlack ?? sendMessageSlack;
+      const account = resolveSlackAccount({ cfg, accountId });
+      const token = getTokenForOperation(account, "write");
+      const botToken = account.botToken?.trim();
+      const tokenOverride = token && token !== botToken ? token : undefined;
+      const result = await send(to, text, {
+        threadTs: replyToId ?? undefined,
+        accountId: accountId ?? undefined,
+        ...(tokenOverride ? { token: tokenOverride } : {}),
+      });
+      return { channel: "slack", ...result };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, deps, replyToId, cfg }) => {
+      const send = deps?.sendSlack ?? sendMessageSlack;
+      const account = resolveSlackAccount({ cfg, accountId });
+      const token = getTokenForOperation(account, "write");
+      const botToken = account.botToken?.trim();
+      const tokenOverride = token && token !== botToken ? token : undefined;
+      const result = await send(to, text, {
+        mediaUrl,
+        threadTs: replyToId ?? undefined,
+        accountId: accountId ?? undefined,
+        ...(tokenOverride ? { token: tokenOverride } : {}),
+      });
+      return { channel: "slack", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      botTokenSource: snapshot.botTokenSource ?? "none",
+      appTokenSource: snapshot.appTokenSource ?? "none",
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }) => {
+      const token = account.botToken?.trim();
+      if (!token) return { ok: false, error: "missing token" };
+      return await probeSlack(token, timeoutMs);
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => {
+      const configured = Boolean(account.botToken && account.appToken);
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured,
+        botTokenSource: account.botTokenSource,
+        appTokenSource: account.appTokenSource,
+        running: runtime?.running ?? false,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        probe,
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const botToken = account.botToken?.trim();
+      const appToken = account.appToken?.trim();
+      ctx.log?.info(`[${account.accountId}] starting provider`);
+      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+      const { monitorSlackProvider } = await import("clawdbot/plugin-sdk");
+      return monitorSlackProvider({
+        botToken: botToken ?? "",
+        appToken: appToken ?? "",
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        mediaMaxMb: account.config.mediaMaxMb,
+        slashCommand: account.config.slashCommand,
+      });
+    },
+  },
+};

extensions/telegram/index.ts

@@ -0,0 +1,14 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+
+import { telegramPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "telegram",
+  name: "Telegram",
+  description: "Telegram channel plugin",
+  register(api: ClawdbotPluginApi) {
+    api.registerChannel({ plugin: telegramPlugin });
+  },
+};
+
+export default plugin;

extensions/telegram/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/telegram",
+  "version": "2026.1.17-1",
+  "type": "module",
+  "description": "Clawdbot Telegram channel plugin",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}

extensions/telegram/src/channel.ts

@@ -0,0 +1,463 @@
+import {
+  applyAccountNameToChannelSection,
+  auditTelegramGroupMembership,
+  buildChannelConfigSchema,
+  chunkMarkdownText,
+  collectTelegramStatusIssues,
+  collectTelegramUnmentionedGroupIds,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  getChatChannelMeta,
+  listTelegramAccountIds,
+  listTelegramDirectoryGroupsFromConfig,
+  listTelegramDirectoryPeersFromConfig,
+  looksLikeTelegramTargetId,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  normalizeTelegramMessagingTarget,
+  PAIRING_APPROVED_MESSAGE,
+  probeTelegram,
+  resolveDefaultTelegramAccountId,
+  resolveTelegramAccount,
+  resolveTelegramGroupRequireMention,
+  resolveTelegramToken,
+  sendMessageTelegram,
+  setAccountEnabledInConfigSection,
+  shouldLogVerbose,
+  telegramMessageActions,
+  telegramOnboardingAdapter,
+  TelegramConfigSchema,
+  type ChannelPlugin,
+  type ClawdbotConfig,
+  type ResolvedTelegramAccount,
+  writeConfigFile,
+} from "clawdbot/plugin-sdk";
+
+const meta = getChatChannelMeta("telegram");
+
+function parseReplyToMessageId(replyToId?: string | null) {
+  if (!replyToId) return undefined;
+  const parsed = Number.parseInt(replyToId, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function parseThreadId(threadId?: string | number | null) {
+  if (threadId == null) return undefined;
+  if (typeof threadId === "number") {
+    return Number.isFinite(threadId) ? Math.trunc(threadId) : undefined;
+  }
+  const trimmed = threadId.trim();
+  if (!trimmed) return undefined;
+  const parsed = Number.parseInt(trimmed, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+export const telegramPlugin: ChannelPlugin<ResolvedTelegramAccount> = {
+  id: "telegram",
+  meta: {
+    ...meta,
+    quickstartAllowFrom: true,
+  },
+  onboarding: telegramOnboardingAdapter,
+  pairing: {
+    idLabel: "telegramUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^(telegram|tg):/i, ""),
+    notifyApproval: async ({ cfg, id }) => {
+      const { token } = resolveTelegramToken(cfg);
+      if (!token) throw new Error("telegram token not configured");
+      await sendMessageTelegram(id, PAIRING_APPROVED_MESSAGE, { token });
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group", "channel", "thread"],
+    reactions: true,
+    threads: true,
+    media: true,
+    nativeCommands: true,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.telegram"] },
+  configSchema: buildChannelConfigSchema(TelegramConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listTelegramAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveTelegramAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultTelegramAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "telegram",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "telegram",
+        accountId,
+        clearBaseFields: ["botToken", "tokenFile", "name"],
+      }),
+    isConfigured: (account) => Boolean(account.token?.trim()),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.token?.trim()),
+      tokenSource: account.tokenSource,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveTelegramAccount({ cfg, accountId }).config.allowFrom ?? []).map((entry) =>
+        String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.replace(/^(telegram|tg):/i, ""))
+        .map((entry) => entry.toLowerCase()),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.telegram?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.telegram.accounts.${resolvedAccountId}.`
+        : "channels.telegram.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("telegram"),
+        normalizeEntry: (raw) => raw.replace(/^(telegram|tg):/i, ""),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      const groupAllowlistConfigured =
+        account.config.groups && Object.keys(account.config.groups).length > 0;
+      if (groupAllowlistConfigured) {
+        return [
+          `- Telegram groups: groupPolicy="open" allows any member in allowed groups to trigger (mention-gated). Set channels.telegram.groupPolicy="allowlist" + channels.telegram.groupAllowFrom to restrict senders.`,
+        ];
+      }
+      return [
+        `- Telegram groups: groupPolicy="open" with no channels.telegram.groups allowlist; any group can add + ping (mention-gated). Set channels.telegram.groupPolicy="allowlist" + channels.telegram.groupAllowFrom or configure channels.telegram.groups.`,
+      ];
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveTelegramGroupRequireMention,
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg }) => cfg.channels?.telegram?.replyToMode ?? "first",
+  },
+  messaging: {
+    normalizeTarget: normalizeTelegramMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeTelegramTargetId,
+      hint: "<chatId>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async (params) => listTelegramDirectoryPeersFromConfig(params),
+    listGroups: async (params) => listTelegramDirectoryGroupsFromConfig(params),
+  },
+  actions: telegramMessageActions,
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "telegram",
+        accountId,
+        name,
+      }),
+    validateInput: ({ accountId, input }) => {
+      if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+        return "TELEGRAM_BOT_TOKEN can only be used for the default account.";
+      }
+      if (!input.useEnv && !input.token && !input.tokenFile) {
+        return "Telegram requires token or --token-file (or --use-env).";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "telegram",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "telegram",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            telegram: {
+              ...next.channels?.telegram,
+              enabled: true,
+              ...(input.useEnv
+                ? {}
+                : input.tokenFile
+                  ? { tokenFile: input.tokenFile }
+                  : input.token
+                    ? { botToken: input.token }
+                    : {}),
+            },
+          },
+        };
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          telegram: {
+            ...next.channels?.telegram,
+            enabled: true,
+            accounts: {
+              ...next.channels?.telegram?.accounts,
+              [accountId]: {
+                ...next.channels?.telegram?.accounts?.[accountId],
+                enabled: true,
+                ...(input.tokenFile
+                  ? { tokenFile: input.tokenFile }
+                  : input.token
+                    ? { botToken: input.token }
+                    : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: chunkMarkdownText,
+    textChunkLimit: 4000,
+    sendText: async ({ to, text, accountId, deps, replyToId, threadId }) => {
+      const send = deps?.sendTelegram ?? sendMessageTelegram;
+      const replyToMessageId = parseReplyToMessageId(replyToId);
+      const messageThreadId = parseThreadId(threadId);
+      const result = await send(to, text, {
+        verbose: false,
+        messageThreadId,
+        replyToMessageId,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "telegram", ...result };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, deps, replyToId, threadId }) => {
+      const send = deps?.sendTelegram ?? sendMessageTelegram;
+      const replyToMessageId = parseReplyToMessageId(replyToId);
+      const messageThreadId = parseThreadId(threadId);
+      const result = await send(to, text, {
+        verbose: false,
+        mediaUrl,
+        messageThreadId,
+        replyToMessageId,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "telegram", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: collectTelegramStatusIssues,
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      tokenSource: snapshot.tokenSource ?? "none",
+      running: snapshot.running ?? false,
+      mode: snapshot.mode ?? null,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }) =>
+      probeTelegram(account.token, timeoutMs, account.config.proxy),
+    auditAccount: async ({ account, timeoutMs, probe, cfg }) => {
+      const groups =
+        cfg.channels?.telegram?.accounts?.[account.accountId]?.groups ??
+        cfg.channels?.telegram?.groups;
+      const { groupIds, unresolvedGroups, hasWildcardUnmentionedGroups } =
+        collectTelegramUnmentionedGroupIds(groups);
+      if (!groupIds.length && unresolvedGroups === 0 && !hasWildcardUnmentionedGroups) {
+        return undefined;
+      }
+      const botId =
+        (probe as { ok?: boolean; bot?: { id?: number } })?.ok &&
+        (probe as { bot?: { id?: number } }).bot?.id != null
+          ? (probe as { bot: { id: number } }).bot.id
+          : null;
+      if (!botId) {
+        return {
+          ok: unresolvedGroups === 0 && !hasWildcardUnmentionedGroups,
+          checkedGroups: 0,
+          unresolvedGroups,
+          hasWildcardUnmentionedGroups,
+          groups: [],
+          elapsedMs: 0,
+        };
+      }
+      const audit = await auditTelegramGroupMembership({
+        token: account.token,
+        botId,
+        groupIds,
+        proxyUrl: account.config.proxy,
+        timeoutMs,
+      });
+      return { ...audit, unresolvedGroups, hasWildcardUnmentionedGroups };
+    },
+    buildAccountSnapshot: ({ account, cfg, runtime, probe, audit }) => {
+      const configured = Boolean(account.token?.trim());
+      const groups =
+        cfg.channels?.telegram?.accounts?.[account.accountId]?.groups ??
+        cfg.channels?.telegram?.groups;
+      const allowUnmentionedGroups =
+        Boolean(
+          groups?.["*"] && (groups["*"] as { requireMention?: boolean }).requireMention === false,
+        ) ||
+        Object.entries(groups ?? {}).some(
+          ([key, value]) =>
+            key !== "*" &&
+            Boolean(value) &&
+            typeof value === "object" &&
+            (value as { requireMention?: boolean }).requireMention === false,
+        );
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured,
+        tokenSource: account.tokenSource,
+        running: runtime?.running ?? false,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        mode: runtime?.mode ?? (account.config.webhookUrl ? "webhook" : "polling"),
+        probe,
+        audit,
+        allowUnmentionedGroups,
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const token = account.token.trim();
+      let telegramBotLabel = "";
+      try {
+        const probe = await probeTelegram(token, 2500, account.config.proxy);
+        const username = probe.ok ? probe.bot?.username?.trim() : null;
+        if (username) telegramBotLabel = ` (@${username})`;
+      } catch (err) {
+        if (shouldLogVerbose()) {
+          ctx.log?.debug?.(`[${account.accountId}] bot probe failed: ${String(err)}`);
+        }
+      }
+      ctx.log?.info(`[${account.accountId}] starting provider${telegramBotLabel}`);
+      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+      const { monitorTelegramProvider } = await import("clawdbot/plugin-sdk");
+      return monitorTelegramProvider({
+        token,
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        useWebhook: Boolean(account.config.webhookUrl),
+        webhookUrl: account.config.webhookUrl,
+        webhookSecret: account.config.webhookSecret,
+        webhookPath: account.config.webhookPath,
+      });
+    },
+    logoutAccount: async ({ accountId, cfg }) => {
+      const envToken = process.env.TELEGRAM_BOT_TOKEN?.trim() ?? "";
+      const nextCfg = { ...cfg } as ClawdbotConfig;
+      const nextTelegram = cfg.channels?.telegram ? { ...cfg.channels.telegram } : undefined;
+      let cleared = false;
+      let changed = false;
+      if (nextTelegram) {
+        if (accountId === DEFAULT_ACCOUNT_ID && nextTelegram.botToken) {
+          delete nextTelegram.botToken;
+          cleared = true;
+          changed = true;
+        }
+        const accounts =
+          nextTelegram.accounts && typeof nextTelegram.accounts === "object"
+            ? { ...nextTelegram.accounts }
+            : undefined;
+        if (accounts && accountId in accounts) {
+          const entry = accounts[accountId];
+          if (entry && typeof entry === "object") {
+            const nextEntry = { ...entry } as Record<string, unknown>;
+            if ("botToken" in nextEntry) {
+              const token = nextEntry.botToken;
+              if (typeof token === "string" ? token.trim() : token) {
+                cleared = true;
+              }
+              delete nextEntry.botToken;
+              changed = true;
+            }
+            if (Object.keys(nextEntry).length === 0) {
+              delete accounts[accountId];
+              changed = true;
+            } else {
+              accounts[accountId] = nextEntry as typeof entry;
+            }
+          }
+        }
+        if (accounts) {
+          if (Object.keys(accounts).length === 0) {
+            delete nextTelegram.accounts;
+            changed = true;
+          } else {
+            nextTelegram.accounts = accounts;
+          }
+        }
+      }
+      if (changed) {
+        if (nextTelegram && Object.keys(nextTelegram).length > 0) {
+          nextCfg.channels = { ...nextCfg.channels, telegram: nextTelegram };
+        } else {
+          const nextChannels = { ...nextCfg.channels };
+          delete nextChannels.telegram;
+          if (Object.keys(nextChannels).length > 0) {
+            nextCfg.channels = nextChannels;
+          } else {
+            delete nextCfg.channels;
+          }
+        }
+      }
+      const resolved = resolveTelegramAccount({
+        cfg: changed ? nextCfg : cfg,
+        accountId,
+      });
+      const loggedOut = resolved.tokenSource === "none";
+      if (changed) {
+        await writeConfigFile(nextCfg);
+      }
+      return { cleared, envToken: Boolean(envToken), loggedOut };
+    },
+  },
+};

extensions/whatsapp/index.ts

@@ -0,0 +1,14 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+
+import { whatsappPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "whatsapp",
+  name: "WhatsApp",
+  description: "WhatsApp channel plugin",
+  register(api: ClawdbotPluginApi) {
+    api.registerChannel({ plugin: whatsappPlugin });
+  },
+};
+
+export default plugin;

extensions/whatsapp/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/whatsapp",
+  "version": "2026.1.17-1",
+  "type": "module",
+  "description": "Clawdbot WhatsApp channel plugin",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}

extensions/whatsapp/src/channel.ts

@@ -0,0 +1,497 @@
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  chunkText,
+  collectWhatsAppStatusIssues,
+  createActionGate,
+  createWhatsAppLoginTool,
+  DEFAULT_ACCOUNT_ID,
+  formatPairingApproveHint,
+  getActiveWebListener,
+  getChatChannelMeta,
+  getWebAuthAgeMs,
+  handleWhatsAppAction,
+  isWhatsAppGroupJid,
+  listWhatsAppAccountIds,
+  listWhatsAppDirectoryGroupsFromConfig,
+  listWhatsAppDirectoryPeersFromConfig,
+  logWebSelfId,
+  looksLikeWhatsAppTargetId,
+  logoutWeb,
+  migrateBaseNameToDefaultAccount,
+  missingTargetError,
+  normalizeAccountId,
+  normalizeE164,
+  normalizeWhatsAppMessagingTarget,
+  normalizeWhatsAppTarget,
+  readStringParam,
+  readWebSelfId,
+  resolveDefaultWhatsAppAccountId,
+  resolveWhatsAppAccount,
+  resolveWhatsAppGroupRequireMention,
+  resolveWhatsAppHeartbeatRecipients,
+  sendMessageWhatsApp,
+  sendPollWhatsApp,
+  shouldLogVerbose,
+  whatsappOnboardingAdapter,
+  WhatsAppConfigSchema,
+  type ChannelMessageActionName,
+  type ChannelPlugin,
+  type ResolvedWhatsAppAccount,
+  webAuthExists,
+} from "clawdbot/plugin-sdk";
+
+const meta = getChatChannelMeta("whatsapp");
+
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export const whatsappPlugin: ChannelPlugin<ResolvedWhatsAppAccount> = {
+  id: "whatsapp",
+  meta: {
+    ...meta,
+    showConfigured: false,
+    quickstartAllowFrom: true,
+    forceAccountBinding: true,
+    preferSessionLookupForAnnounceTarget: true,
+  },
+  onboarding: whatsappOnboardingAdapter,
+  agentTools: () => [createWhatsAppLoginTool()],
+  pairing: {
+    idLabel: "whatsappSenderId",
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    polls: true,
+    reactions: true,
+    media: true,
+  },
+  reload: { configPrefixes: ["web"], noopPrefixes: ["channels.whatsapp"] },
+  gatewayMethods: ["web.login.start", "web.login.wait"],
+  configSchema: buildChannelConfigSchema(WhatsAppConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listWhatsAppAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveWhatsAppAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultWhatsAppAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) => {
+      const accountKey = accountId || DEFAULT_ACCOUNT_ID;
+      const accounts = { ...cfg.channels?.whatsapp?.accounts };
+      const existing = accounts[accountKey] ?? {};
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          whatsapp: {
+            ...cfg.channels?.whatsapp,
+            accounts: {
+              ...accounts,
+              [accountKey]: {
+                ...existing,
+                enabled,
+              },
+            },
+          },
+        },
+      };
+    },
+    deleteAccount: ({ cfg, accountId }) => {
+      const accountKey = accountId || DEFAULT_ACCOUNT_ID;
+      const accounts = { ...cfg.channels?.whatsapp?.accounts };
+      delete accounts[accountKey];
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          whatsapp: {
+            ...cfg.channels?.whatsapp,
+            accounts: Object.keys(accounts).length ? accounts : undefined,
+          },
+        },
+      };
+    },
+    isEnabled: (account, cfg) => account.enabled !== false && cfg.web?.enabled !== false,
+    disabledReason: () => "disabled",
+    isConfigured: async (account) => await webAuthExists(account.authDir),
+    unconfiguredReason: () => "not linked",
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.authDir),
+      linked: Boolean(account.authDir),
+      dmPolicy: account.dmPolicy,
+      allowFrom: account.allowFrom,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      resolveWhatsAppAccount({ cfg, accountId }).allowFrom ?? [],
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter((entry): entry is string => Boolean(entry))
+        .map((entry) => (entry === "*" ? entry : normalizeWhatsAppTarget(entry)))
+        .filter((entry): entry is string => Boolean(entry)),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.whatsapp?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.whatsapp.accounts.${resolvedAccountId}.`
+        : "channels.whatsapp.";
+      return {
+        policy: account.dmPolicy ?? "pairing",
+        allowFrom: account.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("whatsapp"),
+        normalizeEntry: (raw) => normalizeE164(raw),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+      const groupPolicy = account.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      const groupAllowlistConfigured =
+        Boolean(account.groups) && Object.keys(account.groups ?? {}).length > 0;
+      if (groupAllowlistConfigured) {
+        return [
+          `- WhatsApp groups: groupPolicy="open" allows any member in allowed groups to trigger (mention-gated). Set channels.whatsapp.groupPolicy="allowlist" + channels.whatsapp.groupAllowFrom to restrict senders.`,
+        ];
+      }
+      return [
+        `- WhatsApp groups: groupPolicy="open" with no channels.whatsapp.groups allowlist; any group can add + ping (mention-gated). Set channels.whatsapp.groupPolicy="allowlist" + channels.whatsapp.groupAllowFrom or configure channels.whatsapp.groups.`,
+      ];
+    },
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "whatsapp",
+        accountId,
+        name,
+        alwaysUseAccounts: true,
+      }),
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "whatsapp",
+        accountId,
+        name: input.name,
+        alwaysUseAccounts: true,
+      });
+      const next = migrateBaseNameToDefaultAccount({
+        cfg: namedConfig,
+        channelKey: "whatsapp",
+        alwaysUseAccounts: true,
+      });
+      const entry = {
+        ...next.channels?.whatsapp?.accounts?.[accountId],
+        ...(input.authDir ? { authDir: input.authDir } : {}),
+        enabled: true,
+      };
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          whatsapp: {
+            ...next.channels?.whatsapp,
+            accounts: {
+              ...next.channels?.whatsapp?.accounts,
+              [accountId]: entry,
+            },
+          },
+        },
+      };
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveWhatsAppGroupRequireMention,
+    resolveGroupIntroHint: () =>
+      "WhatsApp IDs: SenderId is the participant JID; [message_id: ...] is the message id for reactions (use SenderId as participant).",
+  },
+  mentions: {
+    stripPatterns: ({ ctx }) => {
+      const selfE164 = (ctx.To ?? "").replace(/^whatsapp:/, "");
+      if (!selfE164) return [];
+      const escaped = escapeRegExp(selfE164);
+      return [escaped, `@${escaped}`];
+    },
+  },
+  commands: {
+    enforceOwnerForCommands: true,
+    skipWhenConfigEmpty: true,
+  },
+  messaging: {
+    normalizeTarget: normalizeWhatsAppMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeWhatsAppTargetId,
+      hint: "<E.164|group JID>",
+    },
+  },
+  directory: {
+    self: async ({ cfg, accountId }) => {
+      const account = resolveWhatsAppAccount({ cfg, accountId });
+      const { e164, jid } = readWebSelfId(account.authDir);
+      const id = e164 ?? jid;
+      if (!id) return null;
+      return {
+        kind: "user",
+        id,
+        name: account.name,
+        raw: { e164, jid },
+      };
+    },
+    listPeers: async (params) => listWhatsAppDirectoryPeersFromConfig(params),
+    listGroups: async (params) => listWhatsAppDirectoryGroupsFromConfig(params),
+  },
+  actions: {
+    listActions: ({ cfg }) => {
+      if (!cfg.channels?.whatsapp) return [];
+      const gate = createActionGate(cfg.channels.whatsapp.actions);
+      const actions = new Set<ChannelMessageActionName>();
+      if (gate("reactions")) actions.add("react");
+      if (gate("polls")) actions.add("poll");
+      return Array.from(actions);
+    },
+    supportsAction: ({ action }) => action === "react",
+    handleAction: async ({ action, params, cfg, accountId }) => {
+      if (action !== "react") {
+        throw new Error(`Action ${action} is not supported for provider ${meta.id}.`);
+      }
+      const messageId = readStringParam(params, "messageId", {
+        required: true,
+      });
+      const emoji = readStringParam(params, "emoji", { allowEmpty: true });
+      const remove = typeof params.remove === "boolean" ? params.remove : undefined;
+      return await handleWhatsAppAction(
+        {
+          action: "react",
+          chatJid:
+            readStringParam(params, "chatJid") ?? readStringParam(params, "to", { required: true }),
+          messageId,
+          emoji,
+          remove,
+          participant: readStringParam(params, "participant"),
+          accountId: accountId ?? undefined,
+          fromMe: typeof params.fromMe === "boolean" ? params.fromMe : undefined,
+        },
+        cfg,
+      );
+    },
+  },
+  outbound: {
+    deliveryMode: "gateway",
+    chunker: chunkText,
+    textChunkLimit: 4000,
+    pollMaxOptions: 12,
+    resolveTarget: ({ to, allowFrom, mode }) => {
+      const trimmed = to?.trim() ?? "";
+      const allowListRaw = (allowFrom ?? []).map((entry) => String(entry).trim()).filter(Boolean);
+      const hasWildcard = allowListRaw.includes("*");
+      const allowList = allowListRaw
+        .filter((entry) => entry !== "*")
+        .map((entry) => normalizeWhatsAppTarget(entry))
+        .filter((entry): entry is string => Boolean(entry));
+
+      if (trimmed) {
+        const normalizedTo = normalizeWhatsAppTarget(trimmed);
+        if (!normalizedTo) {
+          if ((mode === "implicit" || mode === "heartbeat") && allowList.length > 0) {
+            return { ok: true, to: allowList[0] };
+          }
+          return {
+            ok: false,
+            error: missingTargetError(
+              "WhatsApp",
+              "<E.164|group JID> or channels.whatsapp.allowFrom[0]",
+            ),
+          };
+        }
+        if (isWhatsAppGroupJid(normalizedTo)) {
+          return { ok: true, to: normalizedTo };
+        }
+        if (mode === "implicit" || mode === "heartbeat") {
+          if (hasWildcard || allowList.length === 0) {
+            return { ok: true, to: normalizedTo };
+          }
+          if (allowList.includes(normalizedTo)) {
+            return { ok: true, to: normalizedTo };
+          }
+          return { ok: true, to: allowList[0] };
+        }
+        return { ok: true, to: normalizedTo };
+      }
+
+      if (allowList.length > 0) {
+        return { ok: true, to: allowList[0] };
+      }
+      return {
+        ok: false,
+        error: missingTargetError(
+          "WhatsApp",
+          "<E.164|group JID> or channels.whatsapp.allowFrom[0]",
+        ),
+      };
+    },
+    sendText: async ({ to, text, accountId, deps, gifPlayback }) => {
+      const send = deps?.sendWhatsApp ?? sendMessageWhatsApp;
+      const result = await send(to, text, {
+        verbose: false,
+        accountId: accountId ?? undefined,
+        gifPlayback,
+      });
+      return { channel: "whatsapp", ...result };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, deps, gifPlayback }) => {
+      const send = deps?.sendWhatsApp ?? sendMessageWhatsApp;
+      const result = await send(to, text, {
+        verbose: false,
+        mediaUrl,
+        accountId: accountId ?? undefined,
+        gifPlayback,
+      });
+      return { channel: "whatsapp", ...result };
+    },
+    sendPoll: async ({ to, poll, accountId }) =>
+      await sendPollWhatsApp(to, poll, {
+        verbose: shouldLogVerbose(),
+        accountId: accountId ?? undefined,
+      }),
+  },
+  auth: {
+    login: async ({ cfg, accountId, runtime, verbose }) => {
+      const resolvedAccountId = accountId?.trim() || resolveDefaultWhatsAppAccountId(cfg);
+      const { loginWeb } = await import("clawdbot/plugin-sdk");
+      await loginWeb(Boolean(verbose), undefined, runtime, resolvedAccountId);
+    },
+  },
+  heartbeat: {
+    checkReady: async ({ cfg, accountId, deps }) => {
+      if (cfg.web?.enabled === false) {
+        return { ok: false, reason: "whatsapp-disabled" };
+      }
+      const account = resolveWhatsAppAccount({ cfg, accountId });
+      const authExists = await (deps?.webAuthExists ?? webAuthExists)(account.authDir);
+      if (!authExists) {
+        return { ok: false, reason: "whatsapp-not-linked" };
+      }
+      const listenerActive = deps?.hasActiveWebListener
+        ? deps.hasActiveWebListener()
+        : Boolean(getActiveWebListener());
+      if (!listenerActive) {
+        return { ok: false, reason: "whatsapp-not-running" };
+      }
+      return { ok: true, reason: "ok" };
+    },
+    resolveRecipients: ({ cfg, opts }) => resolveWhatsAppHeartbeatRecipients(cfg, opts),
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      reconnectAttempts: 0,
+      lastConnectedAt: null,
+      lastDisconnect: null,
+      lastMessageAt: null,
+      lastEventAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: collectWhatsAppStatusIssues,
+    buildChannelSummary: async ({ account, snapshot }) => {
+      const authDir = account.authDir;
+      const linked =
+        typeof snapshot.linked === "boolean"
+          ? snapshot.linked
+          : authDir
+            ? await webAuthExists(authDir)
+            : false;
+      const authAgeMs = linked && authDir ? getWebAuthAgeMs(authDir) : null;
+      const self = linked && authDir ? readWebSelfId(authDir) : { e164: null, jid: null };
+      return {
+        configured: linked,
+        linked,
+        authAgeMs,
+        self,
+        running: snapshot.running ?? false,
+        connected: snapshot.connected ?? false,
+        lastConnectedAt: snapshot.lastConnectedAt ?? null,
+        lastDisconnect: snapshot.lastDisconnect ?? null,
+        reconnectAttempts: snapshot.reconnectAttempts,
+        lastMessageAt: snapshot.lastMessageAt ?? null,
+        lastEventAt: snapshot.lastEventAt ?? null,
+        lastError: snapshot.lastError ?? null,
+      };
+    },
+    buildAccountSnapshot: async ({ account, runtime }) => {
+      const linked = await webAuthExists(account.authDir);
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured: true,
+        linked,
+        running: runtime?.running ?? false,
+        connected: runtime?.connected ?? false,
+        reconnectAttempts: runtime?.reconnectAttempts,
+        lastConnectedAt: runtime?.lastConnectedAt ?? null,
+        lastDisconnect: runtime?.lastDisconnect ?? null,
+        lastMessageAt: runtime?.lastMessageAt ?? null,
+        lastEventAt: runtime?.lastEventAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        dmPolicy: account.dmPolicy,
+        allowFrom: account.allowFrom,
+      };
+    },
+    resolveAccountState: ({ configured }) => (configured ? "linked" : "not linked"),
+    logSelfId: ({ account, runtime, includeChannelPrefix }) => {
+      logWebSelfId(account.authDir, runtime, includeChannelPrefix);
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const { e164, jid } = readWebSelfId(account.authDir);
+      const identity = e164 ? e164 : jid ? `jid ${jid}` : "unknown";
+      ctx.log?.info(`[${account.accountId}] starting provider (${identity})`);
+      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+      const { monitorWebChannel } = await import("clawdbot/plugin-sdk");
+      return monitorWebChannel(
+        shouldLogVerbose(),
+        undefined,
+        true,
+        undefined,
+        ctx.runtime,
+        ctx.abortSignal,
+        {
+          statusSink: (next) => ctx.setStatus({ accountId: ctx.accountId, ...next }),
+          accountId: account.accountId,
+        },
+      );
+    },
+    loginWithQrStart: async ({ accountId, force, timeoutMs, verbose }) =>
+      await (async () => {
+        const { startWebLoginWithQr } = await import("clawdbot/plugin-sdk");
+        return await startWebLoginWithQr({
+          accountId,
+          force,
+          timeoutMs,
+          verbose,
+        });
+      })(),
+    loginWithQrWait: async ({ accountId, timeoutMs }) =>
+      await (async () => {
+        const { waitForWebLogin } = await import("clawdbot/plugin-sdk");
+        return await waitForWebLogin({ accountId, timeoutMs });
+      })(),
+    logoutAccount: async ({ account, runtime }) => {
+      const cleared = await logoutWeb({
+        authDir: account.authDir,
+        isLegacyAuthDir: account.isLegacyAuthDir,
+        runtime,
+      });
+      return { cleared, loggedOut: cleared };
+    },
+  },
+};

src/agents/pi-embedded-runner.run-embedded-pi-agent.writes-models-json-into-provided-agentdir.test.ts

@@ -1,97 +1,101 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeAll, describe, expect, it, vi } from "vitest";
 import type { ClawdbotConfig } from "../config/config.js";
 import { ensureClawdbotModelsJson } from "./models-config.js";
 
-vi.mock("@mariozechner/pi-ai", async () => {
-  const actual = await vi.importActual<typeof import("@mariozechner/pi-ai")>("@mariozechner/pi-ai");
-
-  const buildAssistantMessage = (model: { api: string; provider: string; id: string }) => ({
-    role: "assistant" as const,
-    content: [{ type: "text" as const, text: "ok" }],
-    stopReason: "stop" as const,
-    api: model.api,
-    provider: model.provider,
-    model: model.id,
-    usage: {
-      input: 1,
-      output: 1,
-      cacheRead: 0,
-      cacheWrite: 0,
-      totalTokens: 2,
-      cost: {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-        total: 0,
-      },
-    },
-    timestamp: Date.now(),
-  });
-
-  const buildAssistantErrorMessage = (model: { api: string; provider: string; id: string }) => ({
-    role: "assistant" as const,
-    content: [] as const,
-    stopReason: "error" as const,
-    errorMessage: "boom",
-    api: model.api,
-    provider: model.provider,
-    model: model.id,
-    usage: {
+const buildAssistantMessage = (model: { api: string; provider: string; id: string }) => ({
+  role: "assistant" as const,
+  content: [{ type: "text" as const, text: "ok" }],
+  stopReason: "stop" as const,
+  api: model.api,
+  provider: model.provider,
+  model: model.id,
+  usage: {
+    input: 1,
+    output: 1,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 2,
+    cost: {
       input: 0,
       output: 0,
       cacheRead: 0,
       cacheWrite: 0,
-      totalTokens: 0,
-      cost: {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-        total: 0,
-      },
+      total: 0,
     },
-    timestamp: Date.now(),
-  });
-
-  return {
-    ...actual,
-    complete: async (model: { api: string; provider: string; id: string }) => {
-      if (model.id === "mock-error") return buildAssistantErrorMessage(model);
-      return buildAssistantMessage(model);
-    },
-    completeSimple: async (model: { api: string; provider: string; id: string }) => {
-      if (model.id === "mock-error") return buildAssistantErrorMessage(model);
-      return buildAssistantMessage(model);
-    },
-    streamSimple: (model: { api: string; provider: string; id: string }) => {
-      const stream = new actual.AssistantMessageEventStream();
-      queueMicrotask(() => {
-        stream.push({
-          type: "done",
-          reason: "stop",
-          message:
-            model.id === "mock-error"
-              ? buildAssistantErrorMessage(model)
-              : buildAssistantMessage(model),
-        });
-        stream.end();
-      });
-      return stream;
-    },
-  };
+  },
+  timestamp: Date.now(),
 });
 
+const buildAssistantErrorMessage = (model: { api: string; provider: string; id: string }) => ({
+  role: "assistant" as const,
+  content: [] as const,
+  stopReason: "error" as const,
+  errorMessage: "boom",
+  api: model.api,
+  provider: model.provider,
+  model: model.id,
+  usage: {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: 0,
+    },
+  },
+  timestamp: Date.now(),
+});
+
+const mockPiAi = () => {
+  vi.doMock("@mariozechner/pi-ai", async () => {
+    const actual = await vi.importActual<typeof import("@mariozechner/pi-ai")>(
+      "@mariozechner/pi-ai",
+    );
+    return {
+      ...actual,
+      complete: async (model: { api: string; provider: string; id: string }) => {
+        if (model.id === "mock-error") return buildAssistantErrorMessage(model);
+        return buildAssistantMessage(model);
+      },
+      completeSimple: async (model: { api: string; provider: string; id: string }) => {
+        if (model.id === "mock-error") return buildAssistantErrorMessage(model);
+        return buildAssistantMessage(model);
+      },
+      streamSimple: (model: { api: string; provider: string; id: string }) => {
+        const stream = new actual.AssistantMessageEventStream();
+        queueMicrotask(() => {
+          stream.push({
+            type: "done",
+            reason: "stop",
+            message:
+              model.id === "mock-error"
+                ? buildAssistantErrorMessage(model)
+                : buildAssistantMessage(model),
+          });
+          stream.end();
+        });
+        return stream;
+      },
+    };
+  });
+};
+
 let runEmbeddedPiAgent: typeof import("./pi-embedded-runner.js").runEmbeddedPiAgent;
 
-beforeEach(async () => {
+beforeAll(async () => {
   vi.useRealTimers();
   vi.resetModules();
+  mockPiAi();
   ({ runEmbeddedPiAgent } = await import("./pi-embedded-runner.js"));
-});
+}, 20_000);
 
 const makeOpenAiConfig = (modelIds: string[]) =>
   ({

src/agents/pi-embedded-subscribe.tools.test.ts

@@ -1,8 +1,17 @@
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it } from "vitest";
 
 import { extractMessagingToolSend } from "./pi-embedded-subscribe.tools.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
 
 describe("extractMessagingToolSend", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(
+      createTestRegistry([{ pluginId: "telegram", plugin: telegramPlugin, source: "test" }]),
+    );
+  });
+
   it("uses channel as provider for message tool", () => {
     const result = extractMessagingToolSend("message", {
       action: "send",

src/agents/tools/sessions-announce-target.test.ts

@@ -1,18 +1,51 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
+import { createTestRegistry } from "../../test-utils/channel-plugins.js";
+
 const callGatewayMock = vi.fn();
 vi.mock("../../gateway/call.js", () => ({
   callGateway: (opts: unknown) => callGatewayMock(opts),
 }));
 
-import { resolveAnnounceTarget } from "./sessions-announce-target.js";
+const loadResolveAnnounceTarget = async () => await import("./sessions-announce-target.js");
+
+const installRegistry = async () => {
+  const { setActivePluginRegistry } = await import("../../plugins/runtime.js");
+  setActivePluginRegistry(
+    createTestRegistry([
+      {
+        pluginId: "whatsapp",
+        source: "test",
+        plugin: {
+          id: "whatsapp",
+          meta: {
+            id: "whatsapp",
+            label: "WhatsApp",
+            selectionLabel: "WhatsApp",
+            docsPath: "/channels/whatsapp",
+            blurb: "WhatsApp test stub.",
+            preferSessionLookupForAnnounceTarget: true,
+          },
+          capabilities: { chatTypes: ["direct", "group"] },
+          config: {
+            listAccountIds: () => ["default"],
+            resolveAccount: () => ({}),
+          },
+        },
+      },
+    ]),
+  );
+};
 
 describe("resolveAnnounceTarget", () => {
-  beforeEach(() => {
+  beforeEach(async () => {
     callGatewayMock.mockReset();
+    vi.resetModules();
+    await installRegistry();
   });
 
   it("derives non-WhatsApp announce targets from the session key", async () => {
+    const { resolveAnnounceTarget } = await loadResolveAnnounceTarget();
     const target = await resolveAnnounceTarget({
       sessionKey: "agent:main:discord:group:dev",
       displayKey: "agent:main:discord:group:dev",
@@ -22,6 +55,7 @@ describe("resolveAnnounceTarget", () => {
   });
 
   it("hydrates WhatsApp accountId from sessions.list when available", async () => {
+    const { resolveAnnounceTarget } = await loadResolveAnnounceTarget();
     callGatewayMock.mockResolvedValueOnce({
       sessions: [
         {

src/auto-reply/reply.triggers.group-intro-prompts.test.ts

@@ -1,3 +1,4 @@
+import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { withTempHome as withTempHomeBase } from "../../test/helpers/temp-home.js";
@@ -63,6 +64,7 @@ vi.mock("../web/session.js", () => webMocks);
 async function withTempHome<T>(fn: (home: string) => Promise<T>): Promise<T> {
   return withTempHomeBase(
     async (home) => {
+      await mkdir(join(home, ".clawdbot", "agents", "main", "sessions"), { recursive: true });
       vi.mocked(runEmbeddedPiAgent).mockClear();
       vi.mocked(abortEmbeddedPiRun).mockClear();
       return await fn(home);

src/auto-reply/reply/route-reply.test.ts

@@ -4,6 +4,17 @@ import type { ChannelOutboundAdapter, ChannelPlugin } from "../../channels/plugi
 import type { ClawdbotConfig } from "../../config/config.js";
 import type { PluginRegistry } from "../../plugins/registry.js";
 import { setActivePluginRegistry } from "../../plugins/runtime.js";
+import {
+  createIMessageTestPlugin,
+  createOutboundTestPlugin,
+  createTestRegistry,
+} from "../../test-utils/channel-plugins.js";
+import { discordOutbound } from "../../channels/plugins/outbound/discord.js";
+import { imessageOutbound } from "../../channels/plugins/outbound/imessage.js";
+import { signalOutbound } from "../../channels/plugins/outbound/signal.js";
+import { slackOutbound } from "../../channels/plugins/outbound/slack.js";
+import { telegramOutbound } from "../../channels/plugins/outbound/telegram.js";
+import { whatsappOutbound } from "../../channels/plugins/outbound/whatsapp.js";
 import { SILENT_REPLY_TOKEN } from "../tokens.js";
 
 const mocks = vi.hoisted(() => ({
@@ -53,9 +64,50 @@ const actualDeliver = await vi.importActual<typeof import("../../infra/outbound/
 
 const { routeReply } = await import("./route-reply.js");
 
+const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
+  plugins: [],
+  tools: [],
+  channels,
+  providers: [],
+  gatewayHandlers: {},
+  httpHandlers: [],
+  cliRegistrars: [],
+  services: [],
+  diagnostics: [],
+});
+
+const createMSTeamsOutbound = (): ChannelOutboundAdapter => ({
+  deliveryMode: "direct",
+  sendText: async ({ cfg, to, text }) => {
+    const result = await mocks.sendMessageMSTeams({ cfg, to, text });
+    return { channel: "msteams", ...result };
+  },
+  sendMedia: async ({ cfg, to, text, mediaUrl }) => {
+    const result = await mocks.sendMessageMSTeams({ cfg, to, text, mediaUrl });
+    return { channel: "msteams", ...result };
+  },
+});
+
+const createMSTeamsPlugin = (params: { outbound: ChannelOutboundAdapter }): ChannelPlugin => ({
+  id: "msteams",
+  meta: {
+    id: "msteams",
+    label: "Microsoft Teams",
+    selectionLabel: "Microsoft Teams (Bot Framework)",
+    docsPath: "/channels/msteams",
+    blurb: "Bot Framework; enterprise support.",
+  },
+  capabilities: { chatTypes: ["direct"] },
+  config: {
+    listAccountIds: () => [],
+    resolveAccount: () => ({}),
+  },
+  outbound: params.outbound,
+});
+
 describe("routeReply", () => {
   beforeEach(() => {
-    setActivePluginRegistry(emptyRegistry);
+    setActivePluginRegistry(defaultRegistry);
     mocks.deliverOutboundPayloads.mockImplementation(actualDeliver.deliverOutboundPayloads);
   });
 
@@ -296,45 +348,51 @@ describe("routeReply", () => {
   });
 });
 
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
 const emptyRegistry = createRegistry([]);
-
-const createMSTeamsOutbound = (): ChannelOutboundAdapter => ({
-  deliveryMode: "direct",
-  sendText: async ({ cfg, to, text }) => {
-    const result = await mocks.sendMessageMSTeams({ cfg, to, text });
-    return { channel: "msteams", ...result };
+const defaultRegistry = createTestRegistry([
+  {
+    pluginId: "discord",
+    plugin: createOutboundTestPlugin({ id: "discord", outbound: discordOutbound, label: "Discord" }),
+    source: "test",
   },
-  sendMedia: async ({ cfg, to, text, mediaUrl }) => {
-    const result = await mocks.sendMessageMSTeams({ cfg, to, text, mediaUrl });
-    return { channel: "msteams", ...result };
+  {
+    pluginId: "slack",
+    plugin: createOutboundTestPlugin({ id: "slack", outbound: slackOutbound, label: "Slack" }),
+    source: "test",
   },
-});
-
-const createMSTeamsPlugin = (params: { outbound: ChannelOutboundAdapter }): ChannelPlugin => ({
-  id: "msteams",
-  meta: {
-    id: "msteams",
-    label: "Microsoft Teams",
-    selectionLabel: "Microsoft Teams (Bot Framework)",
-    docsPath: "/channels/msteams",
-    blurb: "Bot Framework; enterprise support.",
+  {
+    pluginId: "telegram",
+    plugin: createOutboundTestPlugin({
+      id: "telegram",
+      outbound: telegramOutbound,
+      label: "Telegram",
+    }),
+    source: "test",
   },
-  capabilities: { chatTypes: ["direct"] },
-  config: {
-    listAccountIds: () => [],
-    resolveAccount: () => ({}),
+  {
+    pluginId: "whatsapp",
+    plugin: createOutboundTestPlugin({
+      id: "whatsapp",
+      outbound: whatsappOutbound,
+      label: "WhatsApp",
+    }),
+    source: "test",
   },
-  outbound: params.outbound,
-});
+  {
+    pluginId: "signal",
+    plugin: createOutboundTestPlugin({ id: "signal", outbound: signalOutbound, label: "Signal" }),
+    source: "test",
+  },
+  {
+    pluginId: "imessage",
+    plugin: createIMessageTestPlugin({ outbound: imessageOutbound }),
+    source: "test",
+  },
+  {
+    pluginId: "msteams",
+    plugin: createMSTeamsPlugin({
+      outbound: createMSTeamsOutbound(),
+    }),
+    source: "test",
+  },
+]);

src/channels/plugins/index.test.ts

@@ -1,12 +1,46 @@
-import { describe, expect, it } from "vitest";
-import { CHANNEL_IDS } from "../registry.js";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { ChannelPlugin } from "./types.js";
+import { setActivePluginRegistry } from "../../plugins/runtime.js";
+import { createTestRegistry } from "../../test-utils/channel-plugins.js";
 import { listChannelPlugins } from "./index.js";
 
 describe("channel plugin registry", () => {
-  it("includes the built-in channel ids", () => {
+  const emptyRegistry = createTestRegistry([]);
+
+  const createPlugin = (id: string): ChannelPlugin => ({
+    id,
+    meta: {
+      id,
+      label: id,
+      selectionLabel: id,
+      docsPath: `/channels/${id}`,
+      blurb: "test",
+    },
+    capabilities: { chatTypes: ["direct"] },
+    config: {
+      listAccountIds: () => [],
+      resolveAccount: () => ({}),
+    },
+  });
+
+  beforeEach(() => {
+    setActivePluginRegistry(emptyRegistry);
+  });
+
+  afterEach(() => {
+    setActivePluginRegistry(emptyRegistry);
+  });
+
+  it("sorts channel plugins by configured order", () => {
+    const registry = createTestRegistry(
+      ["slack", "telegram", "signal"].map((id) => ({
+        pluginId: id,
+        plugin: createPlugin(id),
+        source: "test",
+      })),
+    );
+    setActivePluginRegistry(registry);
     const pluginIds = listChannelPlugins().map((plugin) => plugin.id);
-    for (const id of CHANNEL_IDS) {
-      expect(pluginIds).toContain(id);
-    }
+    expect(pluginIds).toEqual(["telegram", "slack", "signal"]);
   });
 });

src/channels/plugins/index.ts

@@ -1,11 +1,5 @@
 import { CHAT_CHANNEL_ORDER, type ChatChannelId, normalizeChatChannelId } from "../registry.js";
-import { discordPlugin } from "./discord.js";
-import { imessagePlugin } from "./imessage.js";
-import { signalPlugin } from "./signal.js";
-import { slackPlugin } from "./slack.js";
-import { telegramPlugin } from "./telegram.js";
 import type { ChannelId, ChannelPlugin } from "./types.js";
-import { whatsappPlugin } from "./whatsapp.js";
 import { getActivePluginRegistry } from "../../plugins/runtime.js";
 
 // Channel plugins registry (runtime).
@@ -14,14 +8,7 @@ import { getActivePluginRegistry } from "../../plugins/runtime.js";
 // Shared code paths (reply flow, command auth, sandbox explain) should depend on `src/channels/dock.ts`
 // instead, and only call `getChannelPlugin()` at execution boundaries.
 //
-// Adding a channel:
-// - add `<id>Plugin` import + entry in `resolveChannels()`
-// - add an entry to `src/channels/dock.ts` for shared behavior (capabilities, allowFrom, threading, …)
-// - add ids/aliases in `src/channels/registry.ts`
-function resolveCoreChannels(): ChannelPlugin[] {
-  return [telegramPlugin, whatsappPlugin, discordPlugin, slackPlugin, signalPlugin, imessagePlugin];
-}
-
+// Channel plugins are registered by the plugin loader (extensions/ or configured paths).
 function listPluginChannels(): ChannelPlugin[] {
   const registry = getActivePluginRegistry();
   if (!registry) return [];
@@ -41,7 +28,7 @@ function dedupeChannels(channels: ChannelPlugin[]): ChannelPlugin[] {
 }
 
 export function listChannelPlugins(): ChannelPlugin[] {
-  const combined = dedupeChannels([...resolveCoreChannels(), ...listPluginChannels()]);
+  const combined = dedupeChannels(listPluginChannels());
   return combined.sort((a, b) => {
     const indexA = CHAT_CHANNEL_ORDER.indexOf(a.id as ChatChannelId);
     const indexB = CHAT_CHANNEL_ORDER.indexOf(b.id as ChatChannelId);
@@ -72,8 +59,6 @@ export function normalizeChannelId(raw?: string | null): ChannelId | null {
   });
   return plugin?.id ?? null;
 }
-
-export { discordPlugin, imessagePlugin, signalPlugin, slackPlugin, telegramPlugin, whatsappPlugin };
 export {
   listDiscordDirectoryGroupsFromConfig,
   listDiscordDirectoryPeersFromConfig,

src/channels/plugins/load.ts

@@ -1,36 +1,25 @@
 import type { ChannelId, ChannelPlugin } from "./types.js";
-import type { ChatChannelId } from "../registry.js";
+import type { PluginRegistry } from "../../plugins/registry.js";
 import { getActivePluginRegistry } from "../../plugins/runtime.js";
 
-type PluginLoader = () => Promise<ChannelPlugin>;
-
-// Channel docking: load *one* plugin on-demand.
-//
-// This avoids importing `src/channels/plugins/index.ts` (intentionally heavy)
-// from shared flows like outbound delivery / followup routing.
-const LOADERS: Record<ChatChannelId, PluginLoader> = {
-  telegram: async () => (await import("./telegram.js")).telegramPlugin,
-  whatsapp: async () => (await import("./whatsapp.js")).whatsappPlugin,
-  discord: async () => (await import("./discord.js")).discordPlugin,
-  slack: async () => (await import("./slack.js")).slackPlugin,
-  signal: async () => (await import("./signal.js")).signalPlugin,
-  imessage: async () => (await import("./imessage.js")).imessagePlugin,
-};
-
 const cache = new Map<ChannelId, ChannelPlugin>();
+let lastRegistry: PluginRegistry | null = null;
+
+function ensureCacheForRegistry(registry: PluginRegistry | null) {
+  if (registry === lastRegistry) return;
+  cache.clear();
+  lastRegistry = registry;
+}
 
 export async function loadChannelPlugin(id: ChannelId): Promise<ChannelPlugin | undefined> {
+  const registry = getActivePluginRegistry();
+  ensureCacheForRegistry(registry);
   const cached = cache.get(id);
   if (cached) return cached;
-  const registry = getActivePluginRegistry();
   const pluginEntry = registry?.channels.find((entry) => entry.plugin.id === id);
   if (pluginEntry) {
     cache.set(id, pluginEntry.plugin);
     return pluginEntry.plugin;
   }
-  const loader = LOADERS[id as ChatChannelId];
-  if (!loader) return undefined;
-  const plugin = await loader();
-  cache.set(id, plugin);
-  return plugin;
+  return undefined;
 }

src/channels/plugins/outbound/load.ts

@@ -1,40 +1,33 @@
 import type { ChannelId, ChannelOutboundAdapter } from "../types.js";
-import type { ChatChannelId } from "../../registry.js";
+import type { PluginRegistry } from "../../../plugins/registry.js";
 import { getActivePluginRegistry } from "../../../plugins/runtime.js";
 
-type OutboundLoader = () => Promise<ChannelOutboundAdapter>;
-
 // Channel docking: outbound sends should stay cheap to import.
 //
 // The full channel plugins (src/channels/plugins/*.ts) pull in status,
 // onboarding, gateway monitors, etc. Outbound delivery only needs chunking +
 // send primitives, so we keep a dedicated, lightweight loader here.
-const LOADERS: Record<ChatChannelId, OutboundLoader> = {
-  telegram: async () => (await import("./telegram.js")).telegramOutbound,
-  whatsapp: async () => (await import("./whatsapp.js")).whatsappOutbound,
-  discord: async () => (await import("./discord.js")).discordOutbound,
-  slack: async () => (await import("./slack.js")).slackOutbound,
-  signal: async () => (await import("./signal.js")).signalOutbound,
-  imessage: async () => (await import("./imessage.js")).imessageOutbound,
-};
-
 const cache = new Map<ChannelId, ChannelOutboundAdapter>();
+let lastRegistry: PluginRegistry | null = null;
+
+function ensureCacheForRegistry(registry: PluginRegistry | null) {
+  if (registry === lastRegistry) return;
+  cache.clear();
+  lastRegistry = registry;
+}
 
 export async function loadChannelOutboundAdapter(
   id: ChannelId,
 ): Promise<ChannelOutboundAdapter | undefined> {
+  const registry = getActivePluginRegistry();
+  ensureCacheForRegistry(registry);
   const cached = cache.get(id);
   if (cached) return cached;
-  const registry = getActivePluginRegistry();
   const pluginEntry = registry?.channels.find((entry) => entry.plugin.id === id);
   const outbound = pluginEntry?.plugin.outbound;
   if (outbound) {
     cache.set(id, outbound);
     return outbound;
   }
-  const loader = LOADERS[id as ChatChannelId];
-  if (!loader) return undefined;
-  const loaded = await loader();
-  cache.set(id, loaded);
-  return loaded;
+  return undefined;
 }

src/channels/plugins/outbound/whatsapp.ts

@@ -1,6 +1,6 @@
 import { chunkText } from "../../../auto-reply/chunk.js";
 import { shouldLogVerbose } from "../../../globals.js";
-import { sendMessageWhatsApp, sendPollWhatsApp } from "../../../web/outbound.js";
+import { sendPollWhatsApp } from "../../../web/outbound.js";
 import { isWhatsAppGroupJid, normalizeWhatsAppTarget } from "../../../whatsapp/normalize.js";
 import type { ChannelOutboundAdapter } from "../types.js";
 import { missingTargetError } from "../../../infra/outbound/target-errors.js";
@@ -57,7 +57,8 @@ export const whatsappOutbound: ChannelOutboundAdapter = {
     };
   },
   sendText: async ({ to, text, accountId, deps, gifPlayback }) => {
-    const send = deps?.sendWhatsApp ?? sendMessageWhatsApp;
+    const send =
+      deps?.sendWhatsApp ?? (await import("../../../web/outbound.js")).sendMessageWhatsApp;
     const result = await send(to, text, {
       verbose: false,
       accountId: accountId ?? undefined,
@@ -66,7 +67,8 @@ export const whatsappOutbound: ChannelOutboundAdapter = {
     return { channel: "whatsapp", ...result };
   },
   sendMedia: async ({ to, text, mediaUrl, accountId, deps, gifPlayback }) => {
-    const send = deps?.sendWhatsApp ?? sendMessageWhatsApp;
+    const send =
+      deps?.sendWhatsApp ?? (await import("../../../web/outbound.js")).sendMessageWhatsApp;
     const result = await send(to, text, {
       verbose: false,
       mediaUrl,

src/channels/registry.ts

@@ -2,8 +2,8 @@ import type { ChannelMeta } from "./plugins/types.js";
 import type { ChannelId } from "./plugins/types.js";
 import { getActivePluginRegistry } from "../plugins/runtime.js";
 
-// Channel docking: add new channels here (order + meta + aliases), then
-// register the plugin in src/channels/plugins/index.ts and keep protocol IDs in sync.
+// Channel docking: add new core channels here (order + meta + aliases), then
+// register the plugin in its extension entrypoint and keep protocol IDs in sync.
 export const CHAT_CHANNEL_ORDER = [
   "telegram",
   "whatsapp",

src/commands/agent.test.ts

@@ -19,7 +19,10 @@ import { runEmbeddedPiAgent } from "../agents/pi-embedded.js";
 import type { ClawdbotConfig } from "../config/config.js";
 import * as configModule from "../config/config.js";
 import type { RuntimeEnv } from "../runtime.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
 import { agentCommand } from "./agent.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
 
 const runtime: RuntimeEnv = {
   log: vi.fn(),
@@ -251,6 +254,9 @@ describe("agentCommand", () => {
     await withTempHome(async (home) => {
       const store = path.join(home, "sessions.json");
       mockConfig(home, store, undefined, { botToken: "t-1" });
+      setActivePluginRegistry(
+        createTestRegistry([{ pluginId: "telegram", plugin: telegramPlugin, source: "test" }]),
+      );
       const deps = {
         sendMessageWhatsApp: vi.fn(),
         sendMessageTelegram: vi.fn().mockResolvedValue({ messageId: "t1", chatId: "123" }),

src/commands/channels.adds-non-default-telegram-account.test.ts

@@ -1,6 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { RuntimeEnv } from "../runtime.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
+import { discordPlugin } from "../../extensions/discord/src/channel.js";
+import { imessagePlugin } from "../../extensions/imessage/src/channel.js";
+import { signalPlugin } from "../../extensions/signal/src/channel.js";
+import { slackPlugin } from "../../extensions/slack/src/channel.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
+import { whatsappPlugin } from "../../extensions/whatsapp/src/channel.js";
 
 const configMocks = vi.hoisted(() => ({
   readConfigFileSnapshot: vi.fn(),
@@ -64,6 +72,16 @@ describe("channels command", () => {
       version: 1,
       profiles: {},
     });
+    setActivePluginRegistry(
+      createTestRegistry([
+        { pluginId: "discord", plugin: discordPlugin, source: "test" },
+        { pluginId: "slack", plugin: slackPlugin, source: "test" },
+        { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+        { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+        { pluginId: "signal", plugin: signalPlugin, source: "test" },
+        { pluginId: "imessage", plugin: imessagePlugin, source: "test" },
+      ]),
+    );
   });
 
   it("adds a non-default telegram account", async () => {

src/commands/channels.surfaces-signal-runtime-errors-channels-status-output.test.ts

@@ -1,6 +1,9 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { RuntimeEnv } from "../runtime.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createIMessageTestPlugin, createTestRegistry } from "../test-utils/channel-plugins.js";
+import { signalPlugin } from "../../extensions/signal/src/channel.js";
 
 const configMocks = vi.hoisted(() => ({
   readConfigFileSnapshot: vi.fn(),
@@ -59,6 +62,13 @@ describe("channels command", () => {
       version: 1,
       profiles: {},
     });
+    setActivePluginRegistry(
+      createTestRegistry([{ pluginId: "signal", source: "test", plugin: signalPlugin }]),
+    );
+  });
+
+  afterEach(() => {
+    setActivePluginRegistry(createTestRegistry([]));
   });
 
   it("surfaces Signal runtime errors in channels status output", () => {
@@ -81,6 +91,15 @@ describe("channels command", () => {
   });
 
   it("surfaces iMessage runtime errors in channels status output", () => {
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "imessage",
+          source: "test",
+          plugin: createIMessageTestPlugin(),
+        },
+      ]),
+    );
     const lines = formatGatewayChannelsStatusLines({
       channelAccounts: {
         imessage: [

src/commands/health.command.coverage.test.ts

@@ -3,6 +3,8 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { HealthSummary } from "./health.js";
 import { healthCommand } from "./health.js";
 import { stripAnsi } from "../terminal/ansi.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
 
 const callGatewayMock = vi.fn();
 const logWebSelfIdMock = vi.fn();
@@ -26,6 +28,32 @@ describe("healthCommand (coverage)", () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "whatsapp",
+          source: "test",
+          plugin: {
+            id: "whatsapp",
+            meta: {
+              id: "whatsapp",
+              label: "WhatsApp",
+              selectionLabel: "WhatsApp",
+              docsPath: "/channels/whatsapp",
+              blurb: "WhatsApp test stub.",
+            },
+            capabilities: { chatTypes: ["direct", "group"] },
+            config: {
+              listAccountIds: () => ["default"],
+              resolveAccount: () => ({}),
+            },
+            status: {
+              logSelfId: () => logWebSelfIdMock(),
+            },
+          },
+        },
+      ]),
+    );
   });
 
   it("prints the rich text summary when linked and configured", async () => {

src/commands/health.snapshot.test.ts

@@ -2,10 +2,13 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { HealthSummary } from "./health.js";
 import { getHealthSnapshot } from "./health.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
 
 let testConfig: Record<string, unknown> = {};
 let testStore: Record<string, { updatedAt?: number }> = {};
@@ -32,6 +35,12 @@ vi.mock("../web/auth-store.js", () => ({
 }));
 
 describe("getHealthSnapshot", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(
+      createTestRegistry([{ pluginId: "telegram", plugin: telegramPlugin, source: "test" }]),
+    );
+  });
+
   afterEach(() => {
     vi.unstubAllGlobals();
     vi.unstubAllEnvs();

src/commands/message.test.ts

@@ -1,8 +1,14 @@
 import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
 
+import type {
+  ChannelMessageActionAdapter,
+  ChannelOutboundAdapter,
+  ChannelPlugin,
+} from "../channels/plugins/types.js";
 import type { CliDeps } from "../cli/deps.js";
 import type { RuntimeEnv } from "../runtime.js";
-import { messageCommand } from "./message.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
+const loadMessageCommand = async () => await import("./message.js");
 
 let testConfig: Record<string, unknown> = {};
 vi.mock("../config/config.js", async (importOriginal) => {
@@ -47,10 +53,17 @@ vi.mock("../agents/tools/whatsapp-actions.js", () => ({
 const originalTelegramToken = process.env.TELEGRAM_BOT_TOKEN;
 const originalDiscordToken = process.env.DISCORD_BOT_TOKEN;
 
-beforeEach(() => {
+const setRegistry = async (registry: ReturnType<typeof createTestRegistry>) => {
+  const { setActivePluginRegistry } = await import("../plugins/runtime.js");
+  setActivePluginRegistry(registry);
+};
+
+beforeEach(async () => {
   process.env.TELEGRAM_BOT_TOKEN = "";
   process.env.DISCORD_BOT_TOKEN = "";
   testConfig = {};
+  vi.resetModules();
+  await setRegistry(createTestRegistry([]));
   callGatewayMock.mockReset();
   webAuthExists.mockReset().mockResolvedValue(false);
   handleDiscordAction.mockReset();
@@ -82,10 +95,55 @@ const makeDeps = (overrides: Partial<CliDeps> = {}): CliDeps => ({
   ...overrides,
 });
 
+const createStubPlugin = (params: {
+  id: ChannelPlugin["id"];
+  label?: string;
+  actions?: ChannelMessageActionAdapter;
+  outbound?: ChannelOutboundAdapter;
+}): ChannelPlugin => ({
+  id: params.id,
+  meta: {
+    id: params.id,
+    label: params.label ?? String(params.id),
+    selectionLabel: params.label ?? String(params.id),
+    docsPath: `/channels/${params.id}`,
+    blurb: "test stub.",
+  },
+  capabilities: { chatTypes: ["direct"] },
+  config: {
+    listAccountIds: () => ["default"],
+    resolveAccount: () => ({}),
+    isConfigured: async () => true,
+  },
+  actions: params.actions,
+  outbound: params.outbound,
+});
+
 describe("messageCommand", () => {
   it("defaults channel when only one configured", async () => {
     process.env.TELEGRAM_BOT_TOKEN = "token-abc";
+    await setRegistry(
+      createTestRegistry([
+        {
+          pluginId: "telegram",
+          source: "test",
+          plugin: createStubPlugin({
+            id: "telegram",
+            label: "Telegram",
+            actions: {
+              listActions: () => ["send"],
+              handleAction: async ({ action, params, cfg, accountId }) =>
+                await handleTelegramAction(
+                  { action, to: params.to, accountId: accountId ?? undefined },
+                  cfg,
+                ),
+            },
+          }),
+        },
+      ]),
+    );
     const deps = makeDeps();
+    const { messageCommand } = await loadMessageCommand();
     await messageCommand(
       {
         target: "123456",
@@ -100,7 +158,44 @@ describe("messageCommand", () => {
   it("requires channel when multiple configured", async () => {
     process.env.TELEGRAM_BOT_TOKEN = "token-abc";
     process.env.DISCORD_BOT_TOKEN = "token-discord";
+    await setRegistry(
+      createTestRegistry([
+        {
+          pluginId: "telegram",
+          source: "test",
+          plugin: createStubPlugin({
+            id: "telegram",
+            label: "Telegram",
+            actions: {
+              listActions: () => ["send"],
+              handleAction: async ({ action, params, cfg, accountId }) =>
+                await handleTelegramAction(
+                  { action, to: params.to, accountId: accountId ?? undefined },
+                  cfg,
+                ),
+            },
+          }),
+        },
+        {
+          pluginId: "discord",
+          source: "test",
+          plugin: createStubPlugin({
+            id: "discord",
+            label: "Discord",
+            actions: {
+              listActions: () => ["poll"],
+              handleAction: async ({ action, params, cfg, accountId }) =>
+                await handleDiscordAction(
+                  { action, to: params.to, accountId: accountId ?? undefined },
+                  cfg,
+                ),
+            },
+          }),
+        },
+      ]),
+    );
     const deps = makeDeps();
+    const { messageCommand } = await loadMessageCommand();
     await expect(
       messageCommand(
         {
@@ -115,7 +210,23 @@ describe("messageCommand", () => {
 
   it("sends via gateway for WhatsApp", async () => {
     callGatewayMock.mockResolvedValueOnce({ messageId: "g1" });
+    await setRegistry(
+      createTestRegistry([
+        {
+          pluginId: "whatsapp",
+          source: "test",
+          plugin: createStubPlugin({
+            id: "whatsapp",
+            label: "WhatsApp",
+            outbound: {
+              deliveryMode: "gateway",
+            },
+          }),
+        },
+      ]),
+    );
     const deps = makeDeps();
+    const { messageCommand } = await loadMessageCommand();
     await messageCommand(
       {
         action: "send",
@@ -130,7 +241,28 @@ describe("messageCommand", () => {
   });
 
   it("routes discord polls through message action", async () => {
+    await setRegistry(
+      createTestRegistry([
+        {
+          pluginId: "discord",
+          source: "test",
+          plugin: createStubPlugin({
+            id: "discord",
+            label: "Discord",
+            actions: {
+              listActions: () => ["poll"],
+              handleAction: async ({ action, params, cfg, accountId }) =>
+                await handleDiscordAction(
+                  { action, to: params.to, accountId: accountId ?? undefined },
+                  cfg,
+                ),
+            },
+          }),
+        },
+      ]),
+    );
     const deps = makeDeps();
+    const { messageCommand } = await loadMessageCommand();
     await messageCommand(
       {
         action: "poll",

src/commands/onboard-channels.test.ts

@@ -1,9 +1,17 @@
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { ClawdbotConfig } from "../config/config.js";
 import type { RuntimeEnv } from "../runtime.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import { setupChannels } from "./onboard-channels.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
+import { discordPlugin } from "../../extensions/discord/src/channel.js";
+import { imessagePlugin } from "../../extensions/imessage/src/channel.js";
+import { signalPlugin } from "../../extensions/signal/src/channel.js";
+import { slackPlugin } from "../../extensions/slack/src/channel.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
+import { whatsappPlugin } from "../../extensions/whatsapp/src/channel.js";
 
 vi.mock("node:fs/promises", () => ({
   default: {
@@ -22,6 +30,18 @@ vi.mock("./onboard-helpers.js", () => ({
 }));
 
 describe("setupChannels", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(
+      createTestRegistry([
+        { pluginId: "discord", plugin: discordPlugin, source: "test" },
+        { pluginId: "slack", plugin: slackPlugin, source: "test" },
+        { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+        { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+        { pluginId: "signal", plugin: signalPlugin, source: "test" },
+        { pluginId: "imessage", plugin: imessagePlugin, source: "test" },
+      ]),
+    );
+  });
   it("QuickStart uses single-select (no multiselect) and doesn't prompt for Telegram token when WhatsApp is chosen", async () => {
     const select = vi.fn(async () => "whatsapp");
     const multiselect = vi.fn(async () => {

src/commands/onboard-non-interactive.gateway-auth.test.ts

@@ -3,7 +3,7 @@ import { createServer } from "node:net";
 import os from "node:os";
 import path from "node:path";
 
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { WebSocket } from "ws";
 
 import { PROTOCOL_VERSION } from "../gateway/protocol/index.js";
@@ -114,6 +114,7 @@ describe("onboard (non-interactive): gateway auth", () => {
     process.env.HOME = tempHome;
     delete process.env.CLAWDBOT_STATE_DIR;
     delete process.env.CLAWDBOT_CONFIG_PATH;
+    vi.resetModules();
 
     const token = "tok_test_123";
     const workspace = path.join(tempHome, "clawd");

src/commands/onboard-non-interactive.remote.test.ts

@@ -3,7 +3,7 @@ import { createServer } from "node:net";
 import os from "node:os";
 import path from "node:path";
 
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 
 async function getFreePort(): Promise<number> {
   return await new Promise((resolve, reject) => {
@@ -50,6 +50,7 @@ describe("onboard (non-interactive): remote gateway config", () => {
     process.env.HOME = tempHome;
     delete process.env.CLAWDBOT_STATE_DIR;
     delete process.env.CLAWDBOT_CONFIG_PATH;
+    vi.resetModules();
 
     const port = await getFreePort();
     const token = "tok_remote_123";

src/cron/isolated-agent.skips-delivery-without-whatsapp-recipient-besteffortdeliver-true.test.ts

@@ -6,7 +6,12 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { withTempHome as withTempHomeBase } from "../../test/helpers/temp-home.js";
 import type { CliDeps } from "../cli/deps.js";
 import type { ClawdbotConfig } from "../config/config.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
 import type { CronJob } from "./types.js";
+import { discordPlugin } from "../../extensions/discord/src/channel.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
+import { whatsappPlugin } from "../../extensions/whatsapp/src/channel.js";
 
 vi.mock("../agents/pi-embedded.js", () => ({
   abortEmbeddedPiRun: vi.fn().mockReturnValue(false),
@@ -85,6 +90,13 @@ describe("runCronIsolatedAgentTurn", () => {
   beforeEach(() => {
     vi.mocked(runEmbeddedPiAgent).mockReset();
     vi.mocked(loadModelCatalog).mockResolvedValue([]);
+    setActivePluginRegistry(
+      createTestRegistry([
+        { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+        { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+        { pluginId: "discord", plugin: discordPlugin, source: "test" },
+      ]),
+    );
   });
 
   it("skips delivery without a WhatsApp recipient when bestEffortDeliver=true", async () => {

src/gateway/config-reload.test.ts

@@ -1,5 +1,8 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { listChannelPlugins } from "../channels/plugins/index.js";
+import type { ChannelPlugin } from "../channels/plugins/types.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
 import {
   buildGatewayReloadPlan,
   diffConfigPaths,
@@ -23,6 +26,52 @@ describe("diffConfigPaths", () => {
 });
 
 describe("buildGatewayReloadPlan", () => {
+  const emptyRegistry = createTestRegistry([]);
+  const telegramPlugin: ChannelPlugin = {
+    id: "telegram",
+    meta: {
+      id: "telegram",
+      label: "Telegram",
+      selectionLabel: "Telegram",
+      docsPath: "/channels/telegram",
+      blurb: "test",
+    },
+    capabilities: { chatTypes: ["direct"] },
+    config: {
+      listAccountIds: () => [],
+      resolveAccount: () => ({}),
+    },
+    reload: { configPrefixes: ["channels.telegram"] },
+  };
+  const whatsappPlugin: ChannelPlugin = {
+    id: "whatsapp",
+    meta: {
+      id: "whatsapp",
+      label: "WhatsApp",
+      selectionLabel: "WhatsApp",
+      docsPath: "/channels/whatsapp",
+      blurb: "test",
+    },
+    capabilities: { chatTypes: ["direct"] },
+    config: {
+      listAccountIds: () => [],
+      resolveAccount: () => ({}),
+    },
+    reload: { configPrefixes: ["web"], noopPrefixes: ["channels.whatsapp"] },
+  };
+  const registry = createTestRegistry([
+    { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+    { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+  ]);
+
+  beforeEach(() => {
+    setActivePluginRegistry(registry);
+  });
+
+  afterEach(() => {
+    setActivePluginRegistry(emptyRegistry);
+  });
+
   it("marks gateway changes as restart required", () => {
     const plan = buildGatewayReloadPlan(["gateway.port"]);
     expect(plan.restartGateway).toBe(true);

src/gateway/config-reload.ts

@@ -1,5 +1,6 @@
 import chokidar from "chokidar";
 import { type ChannelId, listChannelPlugins } from "../channels/plugins/index.js";
+import { getActivePluginRegistry } from "../plugins/runtime.js";
 import type { ClawdbotConfig, ConfigFileSnapshot, GatewayReloadMode } from "../config/config.js";
 
 export type GatewayReloadSettings = {
@@ -85,8 +86,14 @@ const BASE_RELOAD_RULES_TAIL: ReloadRule[] = [
 ];
 
 let cachedReloadRules: ReloadRule[] | null = null;
+let cachedRegistry: ReturnType<typeof getActivePluginRegistry> | null = null;
 
 function listReloadRules(): ReloadRule[] {
+  const registry = getActivePluginRegistry();
+  if (registry !== cachedRegistry) {
+    cachedReloadRules = null;
+    cachedRegistry = registry;
+  }
   if (cachedReloadRules) return cachedReloadRules;
   // Channel docking: plugins contribute hot reload/no-op prefixes here.
   const channelReloadRules: ReloadRule[] = listChannelPlugins().flatMap((plugin) => [

src/gateway/gateway.wizard.e2e.test.ts

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { WebSocket } from "ws";
 
 import { rawDataToString } from "../infra/ws.js";
@@ -141,6 +141,7 @@ describe("gateway wizard (e2e)", () => {
     process.env.HOME = tempHome;
     delete process.env.CLAWDBOT_STATE_DIR;
     delete process.env.CLAWDBOT_CONFIG_PATH;
+    vi.resetModules();
 
     const wizardToken = `wiz-${randomUUID()}`;
     const port = await getFreeGatewayPort();

src/gateway/hooks.test.ts

@@ -2,8 +2,8 @@ import type { IncomingMessage } from "node:http";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import type { ClawdbotConfig } from "../config/config.js";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
-import type { PluginRegistry } from "../plugins/registry.js";
 import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createIMessageTestPlugin, createTestRegistry } from "../test-utils/channel-plugins.js";
 import {
   extractHookToken,
   normalizeAgentPayload,
@@ -85,6 +85,15 @@ describe("gateway hooks helpers", () => {
       expect(explicitNoDeliver.value.deliver).toBe(false);
     }
 
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "imessage",
+          source: "test",
+          plugin: createIMessageTestPlugin(),
+        },
+      ]),
+    );
     const imsg = normalizeAgentPayload(
       { message: "yo", channel: "imsg" },
       { idFactory: () => "x" },
@@ -95,7 +104,7 @@ describe("gateway hooks helpers", () => {
     }
 
     setActivePluginRegistry(
-      createRegistry([
+      createTestRegistry([
         {
           pluginId: "msteams",
           source: "test",
@@ -117,19 +126,7 @@ describe("gateway hooks helpers", () => {
   });
 });
 
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
-const emptyRegistry = createRegistry([]);
+const emptyRegistry = createTestRegistry([]);
 
 const createMSTeamsPlugin = (params: { aliases?: string[] }): ChannelPlugin => ({
   id: "msteams",

src/gateway/server-methods/send.test.ts

@@ -8,9 +8,15 @@ const mocks = vi.hoisted(() => ({
   appendAssistantMessageToSessionTranscript: vi.fn(async () => ({ ok: true, sessionFile: "x" })),
 }));
 
-vi.mock("../../config/config.js", () => ({
-  loadConfig: () => ({}),
-}));
+vi.mock("../../config/config.js", async () => {
+  const actual = await vi.importActual<typeof import("../../config/config.js")>(
+    "../../config/config.js",
+  );
+  return {
+    ...actual,
+    loadConfig: () => ({}),
+  };
+});
 
 vi.mock("../../channels/plugins/index.js", () => ({
   getChannelPlugin: () => ({ outbound: {} }),

src/gateway/server-methods/send.ts

@@ -2,6 +2,7 @@ import { getChannelPlugin, normalizeChannelId } from "../../channels/plugins/ind
 import type { ChannelId } from "../../channels/plugins/types.js";
 import { DEFAULT_CHAT_CHANNEL } from "../../channels/registry.js";
 import { loadConfig } from "../../config/config.js";
+import { createOutboundSendDeps } from "../../cli/deps.js";
 import { deliverOutboundPayloads } from "../../infra/outbound/deliver.js";
 import { resolveSessionAgentId } from "../../agents/agent-scope.js";
 import type { OutboundChannel } from "../../infra/outbound/targets.js";
@@ -15,7 +16,28 @@ import {
   validateSendParams,
 } from "../protocol/index.js";
 import { formatForLog } from "../ws-log.js";
-import type { GatewayRequestHandlers } from "./types.js";
+import type { GatewayRequestContext, GatewayRequestHandlers } from "./types.js";
+
+type InflightResult = {
+  ok: boolean;
+  payload?: Record<string, unknown>;
+  error?: ReturnType<typeof errorShape>;
+  meta?: Record<string, unknown>;
+};
+
+const inflightByContext = new WeakMap<
+  GatewayRequestContext,
+  Map<string, Promise<InflightResult>>
+>();
+
+const getInflightMap = (context: GatewayRequestContext) => {
+  let inflight = inflightByContext.get(context);
+  if (!inflight) {
+    inflight = new Map();
+    inflightByContext.set(context, inflight);
+  }
+  return inflight;
+};
 
 export const sendHandlers: GatewayRequestHandlers = {
   send: async ({ params, respond, context }) => {
@@ -42,13 +64,22 @@ export const sendHandlers: GatewayRequestHandlers = {
       idempotencyKey: string;
     };
     const idem = request.idempotencyKey;
-    const cached = context.dedupe.get(`send:${idem}`);
+    const dedupeKey = `send:${idem}`;
+    const cached = context.dedupe.get(dedupeKey);
     if (cached) {
       respond(cached.ok, cached.payload, cached.error, {
         cached: true,
       });
       return;
     }
+    const inflightMap = getInflightMap(context);
+    const inflight = inflightMap.get(dedupeKey);
+    if (inflight) {
+      const result = await inflight;
+      const meta = result.meta ? { ...result.meta, cached: true } : { cached: true };
+      respond(result.ok, result.payload, result.error, meta);
+      return;
+    }
     const to = request.to.trim();
     const message = request.message.trim();
     const channelInput = typeof request.channel === "string" ? request.channel : undefined;
@@ -66,79 +97,99 @@ export const sendHandlers: GatewayRequestHandlers = {
       typeof request.accountId === "string" && request.accountId.trim().length
         ? request.accountId.trim()
         : undefined;
-    try {
-      const outboundChannel = channel as Exclude<OutboundChannel, "none">;
-      const plugin = getChannelPlugin(channel as ChannelId);
-      if (!plugin) {
-        respond(
-          false,
-          undefined,
-          errorShape(ErrorCodes.INVALID_REQUEST, `unsupported channel: ${channel}`),
-        );
-        return;
-      }
-      const cfg = loadConfig();
-      const resolved = resolveOutboundTarget({
-        channel: outboundChannel,
-        to,
-        cfg,
-        accountId,
-        mode: "explicit",
-      });
-      if (!resolved.ok) {
-        respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, String(resolved.error)));
-        return;
-      }
-      const results = await deliverOutboundPayloads({
-        cfg,
-        channel: outboundChannel,
-        to: resolved.to,
-        accountId,
-        payloads: [{ text: message, mediaUrl: request.mediaUrl }],
-        gifPlayback: request.gifPlayback,
-        mirror:
-          typeof request.sessionKey === "string" && request.sessionKey.trim()
-            ? {
-                sessionKey: request.sessionKey.trim(),
-                agentId: resolveSessionAgentId({
-                  sessionKey: request.sessionKey.trim(),
-                  config: cfg,
-                }),
-                text: message,
-                mediaUrls: request.mediaUrl ? [request.mediaUrl] : undefined,
-              }
-            : undefined,
-      });
+    const outboundChannel = channel as Exclude<OutboundChannel, "none">;
+    const plugin = getChannelPlugin(channel as ChannelId);
+    if (!plugin) {
+      respond(
+        false,
+        undefined,
+        errorShape(ErrorCodes.INVALID_REQUEST, `unsupported channel: ${channel}`),
+      );
+      return;
+    }
 
-      const result = results.at(-1);
-      if (!result) {
-        throw new Error("No delivery result");
+    const work = (async (): Promise<InflightResult> => {
+      try {
+        const cfg = loadConfig();
+        const resolved = resolveOutboundTarget({
+          channel: outboundChannel,
+          to,
+          cfg,
+          accountId,
+          mode: "explicit",
+        });
+        if (!resolved.ok) {
+          return {
+            ok: false,
+            error: errorShape(ErrorCodes.INVALID_REQUEST, String(resolved.error)),
+            meta: { channel },
+          };
+        }
+        const outboundDeps = context.deps ? createOutboundSendDeps(context.deps) : undefined;
+        const results = await deliverOutboundPayloads({
+          cfg,
+          channel: outboundChannel,
+          to: resolved.to,
+          accountId,
+          payloads: [{ text: message, mediaUrl: request.mediaUrl }],
+          gifPlayback: request.gifPlayback,
+          deps: outboundDeps,
+          mirror:
+            typeof request.sessionKey === "string" && request.sessionKey.trim()
+              ? {
+                  sessionKey: request.sessionKey.trim(),
+                  agentId: resolveSessionAgentId({
+                    sessionKey: request.sessionKey.trim(),
+                    config: cfg,
+                  }),
+                  text: message,
+                  mediaUrls: request.mediaUrl ? [request.mediaUrl] : undefined,
+                }
+              : undefined,
+        });
+
+        const result = results.at(-1);
+        if (!result) {
+          throw new Error("No delivery result");
+        }
+        const payload: Record<string, unknown> = {
+          runId: idem,
+          messageId: result.messageId,
+          channel,
+        };
+        if ("chatId" in result) payload.chatId = result.chatId;
+        if ("channelId" in result) payload.channelId = result.channelId;
+        if ("toJid" in result) payload.toJid = result.toJid;
+        if ("conversationId" in result) {
+          payload.conversationId = result.conversationId;
+        }
+        context.dedupe.set(dedupeKey, {
+          ts: Date.now(),
+          ok: true,
+          payload,
+        });
+        return {
+          ok: true,
+          payload,
+          meta: { channel },
+        };
+      } catch (err) {
+        const error = errorShape(ErrorCodes.UNAVAILABLE, String(err));
+        context.dedupe.set(dedupeKey, {
+          ts: Date.now(),
+          ok: false,
+          error,
+        });
+        return { ok: false, error, meta: { channel, error: formatForLog(err) } };
       }
-      const payload: Record<string, unknown> = {
-        runId: idem,
-        messageId: result.messageId,
-        channel,
-      };
-      if ("chatId" in result) payload.chatId = result.chatId;
-      if ("channelId" in result) payload.channelId = result.channelId;
-      if ("toJid" in result) payload.toJid = result.toJid;
-      if ("conversationId" in result) {
-        payload.conversationId = result.conversationId;
-      }
-      context.dedupe.set(`send:${idem}`, {
-        ts: Date.now(),
-        ok: true,
-        payload,
-      });
-      respond(true, payload, undefined, { channel });
-    } catch (err) {
-      const error = errorShape(ErrorCodes.UNAVAILABLE, String(err));
-      context.dedupe.set(`send:${idem}`, {
-        ts: Date.now(),
-        ok: false,
-        error,
-      });
-      respond(false, undefined, error, { channel, error: formatForLog(err) });
+    })();
+
+    inflightMap.set(dedupeKey, work);
+    try {
+      const result = await work;
+      respond(result.ok, result.payload, result.error, result.meta);
+    } finally {
+      inflightMap.delete(dedupeKey);
     }
   },
   poll: async ({ params, respond, context }) => {

src/gateway/server.agent.gateway-server-agent-b.test.ts

@@ -8,6 +8,7 @@ import { emitAgentEvent, registerAgentRunContext } from "../infra/agent-events.j
 import type { PluginRegistry } from "../plugins/registry.js";
 import { setActivePluginRegistry } from "../plugins/runtime.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
+import { whatsappPlugin } from "../../extensions/whatsapp/src/channel.js";
 import {
   agentCommand,
   connectOk,
@@ -53,6 +54,44 @@ vi.mock("./server-plugins.js", async () => {
 const _BASE_IMAGE_PNG =
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+X3mIAAAAASUVORK5CYII=";
 
+const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
+  plugins: [],
+  tools: [],
+  channels,
+  providers: [],
+  gatewayHandlers: {},
+  httpHandlers: [],
+  cliRegistrars: [],
+  services: [],
+  diagnostics: [],
+});
+
+const createMSTeamsPlugin = (params?: { aliases?: string[] }): ChannelPlugin => ({
+  id: "msteams",
+  meta: {
+    id: "msteams",
+    label: "Microsoft Teams",
+    selectionLabel: "Microsoft Teams (Bot Framework)",
+    docsPath: "/channels/msteams",
+    blurb: "Bot Framework; enterprise support.",
+    aliases: params?.aliases,
+  },
+  capabilities: { chatTypes: ["direct"] },
+  config: {
+    listAccountIds: () => [],
+    resolveAccount: () => ({}),
+  },
+});
+
+const emptyRegistry = createRegistry([]);
+const defaultRegistry = createRegistry([
+  {
+    pluginId: "whatsapp",
+    source: "test",
+    plugin: whatsappPlugin,
+  },
+]);
+
 function expectChannels(call: Record<string, unknown>, channel: string) {
   expect(call.channel).toBe(channel);
   expect(call.messageChannel).toBe(channel);
@@ -60,8 +99,8 @@ function expectChannels(call: Record<string, unknown>, channel: string) {
 
 describe("gateway server agent", () => {
   beforeEach(() => {
-    registryState.registry = emptyRegistry;
-    setActivePluginRegistry(emptyRegistry);
+    registryState.registry = defaultRegistry;
+    setActivePluginRegistry(defaultRegistry);
   });
 
   afterEach(() => {
@@ -439,34 +478,3 @@ describe("gateway server agent", () => {
     await server.close();
   });
 });
-
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
-const emptyRegistry = createRegistry([]);
-
-const createMSTeamsPlugin = (params?: { aliases?: string[] }): ChannelPlugin => ({
-  id: "msteams",
-  meta: {
-    id: "msteams",
-    label: "Microsoft Teams",
-    selectionLabel: "Microsoft Teams (Bot Framework)",
-    docsPath: "/channels/msteams",
-    blurb: "Bot Framework; enterprise support.",
-    aliases: params?.aliases,
-  },
-  capabilities: { chatTypes: ["direct"] },
-  config: {
-    listAccountIds: () => [],
-    resolveAccount: () => ({}),
-  },
-});

src/gateway/test-helpers.mocks.ts

@@ -66,6 +66,7 @@ const hoisted = vi.hoisted(() => ({
     waitCalls: [] as string[],
     waitResults: new Map<string, boolean>(),
   },
+  sendWhatsAppMock: vi.fn().mockResolvedValue({ messageId: "msg-1", toJid: "jid-1" }),
 }));
 
 const testConfigRoot = {
@@ -74,6 +75,7 @@ const testConfigRoot = {
 
 export const setTestConfigRoot = (root: string) => {
   testConfigRoot.value = root;
+  process.env.CLAWDBOT_CONFIG_PATH = path.join(root, "clawdbot.json");
 };
 
 export const bridgeStartCalls = hoisted.bridgeStartCalls;
@@ -342,10 +344,33 @@ vi.mock("../commands/status.js", () => ({
   getStatusSummary: vi.fn().mockResolvedValue({ ok: true }),
 }));
 vi.mock("../web/outbound.js", () => ({
-  sendMessageWhatsApp: vi.fn().mockResolvedValue({ messageId: "msg-1", toJid: "jid-1" }),
+  sendMessageWhatsApp: (...args: unknown[]) =>
+    (hoisted.sendWhatsAppMock as (...args: unknown[]) => unknown)(...args),
 }));
+vi.mock("../channels/web/index.js", async () => {
+  const actual = await vi.importActual<typeof import("../channels/web/index.js")>(
+    "../channels/web/index.js",
+  );
+  return {
+    ...actual,
+    sendMessageWhatsApp: (...args: unknown[]) =>
+      (hoisted.sendWhatsAppMock as (...args: unknown[]) => unknown)(...args),
+  };
+});
 vi.mock("../commands/agent.js", () => ({
   agentCommand,
 }));
+vi.mock("../cli/deps.js", async () => {
+  const actual = await vi.importActual<typeof import("../cli/deps.js")>("../cli/deps.js");
+  const base = actual.createDefaultDeps();
+  return {
+    ...actual,
+    createDefaultDeps: () => ({
+      ...base,
+      sendMessageWhatsApp: (...args: unknown[]) =>
+        (hoisted.sendWhatsAppMock as (...args: unknown[]) => unknown)(...args),
+    }),
+  };
+});
 
 process.env.CLAWDBOT_SKIP_CHANNELS = "1";

src/imessage/send.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import { sendMessageIMessage } from "./send.js";
+const loadSendMessageIMessage = async () => await import("./send.js");
 
 const requestMock = vi.fn();
 const stopMock = vi.fn();
@@ -38,9 +38,11 @@ describe("sendMessageIMessage", () => {
   beforeEach(() => {
     requestMock.mockReset().mockResolvedValue({ ok: true });
     stopMock.mockReset().mockResolvedValue(undefined);
+    vi.resetModules();
   });
 
   it("sends to chat_id targets", async () => {
+    const { sendMessageIMessage } = await loadSendMessageIMessage();
     await sendMessageIMessage("chat_id:123", "hi");
     const params = requestMock.mock.calls[0]?.[1] as Record<string, unknown>;
     expect(requestMock).toHaveBeenCalledWith("send", expect.any(Object), expect.any(Object));
@@ -49,6 +51,7 @@ describe("sendMessageIMessage", () => {
   });
 
   it("applies sms service prefix", async () => {
+    const { sendMessageIMessage } = await loadSendMessageIMessage();
     await sendMessageIMessage("sms:+1555", "hello");
     const params = requestMock.mock.calls[0]?.[1] as Record<string, unknown>;
     expect(params.service).toBe("sms");
@@ -56,6 +59,7 @@ describe("sendMessageIMessage", () => {
   });
 
   it("adds file attachment with placeholder text", async () => {
+    const { sendMessageIMessage } = await loadSendMessageIMessage();
     await sendMessageIMessage("chat_id:7", "", { mediaUrl: "http://x/y.jpg" });
     const params = requestMock.mock.calls[0]?.[1] as Record<string, unknown>;
     expect(params.file).toBe("/tmp/imessage-media.jpg");

src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts

@@ -1,15 +1,28 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import * as replyModule from "../auto-reply/reply.js";
 import type { ClawdbotConfig } from "../config/config.js";
 import { resolveMainSessionKey } from "../config/sessions.js";
 import { runHeartbeatOnce } from "./heartbeat-runner.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
+import { whatsappPlugin } from "../../extensions/whatsapp/src/channel.js";
 
 // Avoid pulling optional runtime deps during isolated runs.
 vi.mock("jiti", () => ({ createJiti: () => () => ({}) }));
 
+beforeEach(() => {
+  setActivePluginRegistry(
+    createTestRegistry([
+      { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+      { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+    ]),
+  );
+});
+
 describe("resolveHeartbeatIntervalMs", () => {
   it("respects ackMaxChars for heartbeat acks", async () => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));

src/infra/heartbeat-runner.returns-default-unset.test.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { HEARTBEAT_PROMPT } from "../auto-reply/heartbeat.js";
 import * as replyModule from "../auto-reply/reply.js";
 import type { ClawdbotConfig } from "../config/config.js";
@@ -18,10 +18,23 @@ import {
   runHeartbeatOnce,
 } from "./heartbeat-runner.js";
 import { resolveHeartbeatDeliveryTarget } from "./outbound/targets.js";
+import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createTestRegistry } from "../test-utils/channel-plugins.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
+import { whatsappPlugin } from "../../extensions/whatsapp/src/channel.js";
 
 // Avoid pulling optional runtime deps during isolated runs.
 vi.mock("jiti", () => ({ createJiti: () => () => ({}) }));
 
+beforeEach(() => {
+  setActivePluginRegistry(
+    createTestRegistry([
+      { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+      { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+    ]),
+  );
+});
+
 describe("resolveHeartbeatIntervalMs", () => {
   it("returns default when unset", () => {
     expect(resolveHeartbeatIntervalMs({})).toBe(30 * 60_000);

src/infra/outbound/deliver.test.ts

@@ -1,7 +1,16 @@
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { ClawdbotConfig } from "../../config/config.js";
+import { signalOutbound } from "../../channels/plugins/outbound/signal.js";
+import { telegramOutbound } from "../../channels/plugins/outbound/telegram.js";
+import { whatsappOutbound } from "../../channels/plugins/outbound/whatsapp.js";
 import { markdownToSignalTextChunks } from "../../signal/format.js";
+import { setActivePluginRegistry } from "../../plugins/runtime.js";
+import {
+  createIMessageTestPlugin,
+  createOutboundTestPlugin,
+  createTestRegistry,
+} from "../../test-utils/channel-plugins.js";
 
 const mocks = vi.hoisted(() => ({
   appendAssistantMessageToSessionTranscript: vi.fn(async () => ({ ok: true, sessionFile: "x" })),
@@ -20,6 +29,13 @@ vi.mock("../../config/sessions.js", async () => {
 const { deliverOutboundPayloads, normalizeOutboundPayloads } = await import("./deliver.js");
 
 describe("deliverOutboundPayloads", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(defaultRegistry);
+  });
+
+  afterEach(() => {
+    setActivePluginRegistry(emptyRegistry);
+  });
   it("chunks telegram markdown and passes through accountId", async () => {
     const sendTelegram = vi.fn().mockResolvedValue({ messageId: "m1", chatId: "c1" });
     const cfg: ClawdbotConfig = {
@@ -154,6 +170,15 @@ describe("deliverOutboundPayloads", () => {
 
   it("uses iMessage media maxBytes from agent fallback", async () => {
     const sendIMessage = vi.fn().mockResolvedValue({ messageId: "i1" });
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "imessage",
+          source: "test",
+          plugin: createIMessageTestPlugin(),
+        },
+      ]),
+    );
     const cfg: ClawdbotConfig = {
       agents: { defaults: { mediaMaxMb: 3 } },
     };
@@ -234,3 +259,27 @@ describe("deliverOutboundPayloads", () => {
     );
   });
 });
+
+const emptyRegistry = createTestRegistry([]);
+const defaultRegistry = createTestRegistry([
+  {
+    pluginId: "telegram",
+    plugin: createOutboundTestPlugin({ id: "telegram", outbound: telegramOutbound }),
+    source: "test",
+  },
+  {
+    pluginId: "signal",
+    plugin: createOutboundTestPlugin({ id: "signal", outbound: signalOutbound }),
+    source: "test",
+  },
+  {
+    pluginId: "whatsapp",
+    plugin: createOutboundTestPlugin({ id: "whatsapp", outbound: whatsappOutbound }),
+    source: "test",
+  },
+  {
+    pluginId: "imessage",
+    plugin: createIMessageTestPlugin(),
+    source: "test",
+  },
+]);

src/infra/outbound/format.ts

@@ -1,4 +1,5 @@
 import { getChannelPlugin } from "../../channels/plugins/index.js";
+import { getChatChannelMeta, normalizeChatChannelId } from "../../channels/registry.js";
 import type { ChannelId } from "../../channels/plugins/types.js";
 import type { OutboundDeliveryResult } from "./deliver.js";
 
@@ -28,8 +29,13 @@ type OutboundDeliveryMeta = {
   meta?: Record<string, unknown>;
 };
 
-const resolveChannelLabel = (channel: string) =>
-  getChannelPlugin(channel as ChannelId)?.meta.label ?? channel;
+const resolveChannelLabel = (channel: string) => {
+  const pluginLabel = getChannelPlugin(channel as ChannelId)?.meta.label;
+  if (pluginLabel) return pluginLabel;
+  const normalized = normalizeChatChannelId(channel);
+  if (normalized) return getChatChannelMeta(normalized).label;
+  return channel;
+};
 
 export function formatOutboundDeliverySummary(
   channel: string,

src/infra/outbound/message-action-runner.test.ts

@@ -1,6 +1,11 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import type { ClawdbotConfig } from "../../config/config.js";
+import { setActivePluginRegistry } from "../../plugins/runtime.js";
+import { createIMessageTestPlugin, createTestRegistry } from "../../test-utils/channel-plugins.js";
+import { slackPlugin } from "../../../extensions/slack/src/channel.js";
+import { telegramPlugin } from "../../../extensions/telegram/src/channel.js";
+import { whatsappPlugin } from "../../../extensions/whatsapp/src/channel.js";
 import { runMessageAction } from "./message-action-runner.js";
 
 const slackConfig = {
@@ -21,6 +26,36 @@ const whatsappConfig = {
 } as ClawdbotConfig;
 
 describe("runMessageAction context isolation", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "slack",
+          source: "test",
+          plugin: slackPlugin,
+        },
+        {
+          pluginId: "whatsapp",
+          source: "test",
+          plugin: whatsappPlugin,
+        },
+        {
+          pluginId: "telegram",
+          source: "test",
+          plugin: telegramPlugin,
+        },
+        {
+          pluginId: "imessage",
+          source: "test",
+          plugin: createIMessageTestPlugin(),
+        },
+      ]),
+    );
+  });
+
+  afterEach(() => {
+    setActivePluginRegistry(createTestRegistry([]));
+  });
   it("allows send when target matches current channel", async () => {
     const result = await runMessageAction({
       cfg: slackConfig,

src/infra/outbound/message.test.ts

@@ -1,9 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { ChannelOutboundAdapter, ChannelPlugin } from "../../channels/plugins/types.js";
-import type { PluginRegistry } from "../../plugins/registry.js";
-import { setActivePluginRegistry } from "../../plugins/runtime.js";
-import { sendMessage, sendPoll } from "./message.js";
+import { createIMessageTestPlugin, createTestRegistry } from "../../test-utils/channel-plugins.js";
+const loadMessage = async () => await import("./message.js");
+
+const setRegistry = async (registry: ReturnType<typeof createTestRegistry>) => {
+  const { setActivePluginRegistry } = await import("../../plugins/runtime.js");
+  setActivePluginRegistry(registry);
+};
 
 const callGatewayMock = vi.fn();
 vi.mock("../../gateway/call.js", () => ({
@@ -12,22 +16,24 @@ vi.mock("../../gateway/call.js", () => ({
 }));
 
 describe("sendMessage channel normalization", () => {
-  beforeEach(() => {
+  beforeEach(async () => {
     callGatewayMock.mockReset();
-    setActivePluginRegistry(emptyRegistry);
+    vi.resetModules();
+    await setRegistry(emptyRegistry);
   });
 
-  afterEach(() => {
-    setActivePluginRegistry(emptyRegistry);
+  afterEach(async () => {
+    await setRegistry(emptyRegistry);
   });
 
   it("normalizes Teams alias", async () => {
+    const { sendMessage } = await loadMessage();
     const sendMSTeams = vi.fn(async () => ({
       messageId: "m1",
       conversationId: "c1",
     }));
-    setActivePluginRegistry(
-      createRegistry([
+    await setRegistry(
+      createTestRegistry([
         {
           pluginId: "msteams",
           source: "test",
@@ -51,7 +57,17 @@ describe("sendMessage channel normalization", () => {
   });
 
   it("normalizes iMessage alias", async () => {
+    const { sendMessage } = await loadMessage();
     const sendIMessage = vi.fn(async () => ({ messageId: "i1" }));
+    await setRegistry(
+      createTestRegistry([
+        {
+          pluginId: "imessage",
+          source: "test",
+          plugin: createIMessageTestPlugin(),
+        },
+      ]),
+    );
     const result = await sendMessage({
       cfg: {},
       to: "someone@example.com",
@@ -66,19 +82,21 @@ describe("sendMessage channel normalization", () => {
 });
 
 describe("sendPoll channel normalization", () => {
-  beforeEach(() => {
+  beforeEach(async () => {
     callGatewayMock.mockReset();
-    setActivePluginRegistry(emptyRegistry);
+    vi.resetModules();
+    await setRegistry(emptyRegistry);
   });
 
-  afterEach(() => {
-    setActivePluginRegistry(emptyRegistry);
+  afterEach(async () => {
+    await setRegistry(emptyRegistry);
   });
 
   it("normalizes Teams alias for polls", async () => {
+    const { sendPoll } = await loadMessage();
     callGatewayMock.mockResolvedValueOnce({ messageId: "p1" });
-    setActivePluginRegistry(
-      createRegistry([
+    await setRegistry(
+      createTestRegistry([
         {
           pluginId: "msteams",
           source: "test",
@@ -106,19 +124,7 @@ describe("sendPoll channel normalization", () => {
   });
 });
 
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
-const emptyRegistry = createRegistry([]);
+const emptyRegistry = createTestRegistry([]);
 
 const createMSTeamsOutbound = (opts?: { includePoll?: boolean }): ChannelOutboundAdapter => ({
   deliveryMode: "direct",

src/infra/outbound/targets.test.ts

@@ -1,9 +1,22 @@
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it } from "vitest";
 import type { ClawdbotConfig } from "../../config/config.js";
 
+import { setActivePluginRegistry } from "../../plugins/runtime.js";
+import { createTestRegistry } from "../../test-utils/channel-plugins.js";
+import { telegramPlugin } from "../../../extensions/telegram/src/channel.js";
+import { whatsappPlugin } from "../../../extensions/whatsapp/src/channel.js";
 import { resolveOutboundTarget, resolveSessionDeliveryTarget } from "./targets.js";
 
 describe("resolveOutboundTarget", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(
+      createTestRegistry([
+        { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+        { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+      ]),
+    );
+  });
+
   it("falls back to whatsapp allowFrom via config", () => {
     const cfg: ClawdbotConfig = {
       channels: { whatsapp: { allowFrom: ["+1555"] } },

src/media/store.redirect.test.ts

@@ -19,7 +19,7 @@ vi.doMock("node:https", () => ({
   request: (...args: unknown[]) => mockRequest(...args),
 }));
 
-const { saveMediaSource } = await import("./store.js");
+const loadStore = async () => await import("./store.js");
 
 describe("media store redirects", () => {
   beforeAll(async () => {
@@ -28,6 +28,7 @@ describe("media store redirects", () => {
 
   beforeEach(() => {
     mockRequest.mockReset();
+    vi.resetModules();
   });
 
   afterAll(async () => {
@@ -36,6 +37,7 @@ describe("media store redirects", () => {
   });
 
   it("follows redirects and keeps detected mime/extension", async () => {
+    const { saveMediaSource } = await loadStore();
     let call = 0;
     mockRequest.mockImplementation((_url, _opts, cb) => {
       call += 1;
@@ -78,6 +80,7 @@ describe("media store redirects", () => {
   });
 
   it("sniffs xlsx from zip content when headers and url extension are missing", async () => {
+    const { saveMediaSource } = await loadStore();
     mockRequest.mockImplementationOnce((_url, _opts, cb) => {
       const res = new PassThrough();
       const req = {

src/plugin-sdk/index.ts

@@ -57,6 +57,7 @@ export type { ClawdbotPluginApi } from "../plugins/types.js";
 export type { PluginRuntime } from "../plugins/runtime/types.js";
 export type { ClawdbotConfig } from "../config/config.js";
 export type { ChannelDock } from "../channels/dock.js";
+export { getChatChannelMeta } from "../channels/registry.js";
 export type {
   DmPolicy,
   GroupPolicy,
@@ -65,13 +66,21 @@ export type {
   MSTeamsReplyStyle,
   MSTeamsTeamConfig,
 } from "../config/types.js";
-export { MSTeamsConfigSchema } from "../config/zod-schema.providers-core.js";
+export {
+  DiscordConfigSchema,
+  IMessageConfigSchema,
+  MSTeamsConfigSchema,
+  SignalConfigSchema,
+  SlackConfigSchema,
+  TelegramConfigSchema,
+} from "../config/zod-schema.providers-core.js";
+export { WhatsAppConfigSchema } from "../config/zod-schema.providers-whatsapp.js";
 export type { RuntimeEnv } from "../runtime.js";
 export type { WizardPrompter } from "../wizard/prompts.js";
 export { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../routing/session-key.js";
 export type { ReplyPayload } from "../auto-reply/types.js";
 export { SILENT_REPLY_TOKEN, isSilentReplyText } from "../auto-reply/tokens.js";
-export { chunkMarkdownText, resolveTextChunkLimit } from "../auto-reply/chunk.js";
+export { chunkMarkdownText, chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js";
 export {
   hasControlCommand,
   isControlCommandMessage,
@@ -98,6 +107,14 @@ export { resolveEffectiveMessagesConfig, resolveHumanDelayConfig } from "../agen
 export { mergeAllowlist, summarizeMapping } from "../channels/allowlists/resolve-utils.js";
 export { resolveCommandAuthorizedFromAuthorizers } from "../channels/command-gating.js";
 export { resolveMentionGating } from "../channels/mention-gating.js";
+export { resolveChannelMediaMaxBytes } from "../channels/plugins/media-limits.js";
+export {
+  resolveDiscordGroupRequireMention,
+  resolveIMessageGroupRequireMention,
+  resolveSlackGroupRequireMention,
+  resolveTelegramGroupRequireMention,
+  resolveWhatsAppGroupRequireMention,
+} from "../channels/plugins/group-mentions.js";
 export {
   buildChannelKeyCandidates,
   normalizeChannelSlug,
@@ -105,6 +122,16 @@ export {
   resolveChannelEntryMatchWithFallback,
   resolveNestedAllowlistDecision,
 } from "../channels/plugins/channel-config.js";
+export {
+  listDiscordDirectoryGroupsFromConfig,
+  listDiscordDirectoryPeersFromConfig,
+  listSlackDirectoryGroupsFromConfig,
+  listSlackDirectoryPeersFromConfig,
+  listTelegramDirectoryGroupsFromConfig,
+  listTelegramDirectoryPeersFromConfig,
+  listWhatsAppDirectoryGroupsFromConfig,
+  listWhatsAppDirectoryPeersFromConfig,
+} from "../channels/plugins/directory-config.js";
 export type { AllowlistMatch } from "../channels/plugins/allowlist-match.js";
 export { formatAllowlistMatchMeta } from "../channels/plugins/allowlist-match.js";
 export {
@@ -118,7 +145,7 @@ export {
   updateLastRoute,
 } from "../config/sessions.js";
 export { resolveStateDir } from "../config/paths.js";
-export { loadConfig } from "../config/config.js";
+export { loadConfig, writeConfigFile } from "../config/config.js";
 export { optionalStringEnum, stringEnum } from "../agents/schema/typebox.js";
 export { danger } from "../globals.js";
 export { logVerbose, shouldLogVerbose } from "../globals.js";
@@ -144,6 +171,15 @@ export {
 } from "../channels/plugins/setup-helpers.js";
 export { formatPairingApproveHint } from "../channels/plugins/helpers.js";
 export { PAIRING_APPROVED_MESSAGE } from "../channels/plugins/pairing-message.js";
+export {
+  listIMessageAccountIds,
+  resolveDefaultIMessageAccountId,
+  resolveIMessageAccount,
+  type ResolvedIMessageAccount,
+} from "../imessage/accounts.js";
+export { monitorIMessageProvider } from "../imessage/monitor.js";
+export { probeIMessage } from "../imessage/probe.js";
+export { sendMessageIMessage } from "../imessage/send.js";
 
 export type {
   ChannelOnboardingAdapter,
@@ -151,6 +187,7 @@ export type {
 } from "../channels/plugins/onboarding-types.js";
 export { addWildcardAllowFrom, promptAccountId } from "../channels/plugins/onboarding/helpers.js";
 export { promptChannelAccessConfig } from "../channels/plugins/onboarding/channel-access.js";
+export { imessageOnboardingAdapter } from "../channels/plugins/onboarding/imessage.js";
 
 export {
   createActionGate,
@@ -165,3 +202,120 @@ export { registerMemoryCli } from "../cli/memory-cli.js";
 export { formatDocsLink } from "../terminal/links.js";
 export type { HookEntry } from "../hooks/types.js";
 export { registerPluginHooksFromDir } from "../hooks/plugin-hooks.js";
+export { normalizeE164 } from "../utils.js";
+export { missingTargetError } from "../infra/outbound/target-errors.js";
+
+// Channel: Discord
+export {
+  listDiscordAccountIds,
+  resolveDefaultDiscordAccountId,
+  resolveDiscordAccount,
+  type ResolvedDiscordAccount,
+} from "../discord/accounts.js";
+export {
+  auditDiscordChannelPermissions,
+  collectDiscordAuditChannelIds,
+} from "../discord/audit.js";
+export { listDiscordDirectoryGroupsLive, listDiscordDirectoryPeersLive } from "../discord/directory-live.js";
+export { probeDiscord } from "../discord/probe.js";
+export { resolveDiscordChannelAllowlist } from "../discord/resolve-channels.js";
+export { resolveDiscordUserAllowlist } from "../discord/resolve-users.js";
+export { sendMessageDiscord, sendPollDiscord } from "../discord/send.js";
+export { monitorDiscordProvider } from "../discord/monitor.js";
+export { discordMessageActions } from "../channels/plugins/actions/discord.js";
+export { discordOnboardingAdapter } from "../channels/plugins/onboarding/discord.js";
+export {
+  looksLikeDiscordTargetId,
+  normalizeDiscordMessagingTarget,
+} from "../channels/plugins/normalize/discord.js";
+export { collectDiscordStatusIssues } from "../channels/plugins/status-issues/discord.js";
+
+// Channel: Slack
+export {
+  listEnabledSlackAccounts,
+  listSlackAccountIds,
+  resolveDefaultSlackAccountId,
+  resolveSlackAccount,
+  type ResolvedSlackAccount,
+} from "../slack/accounts.js";
+export { listSlackDirectoryGroupsLive, listSlackDirectoryPeersLive } from "../slack/directory-live.js";
+export { probeSlack } from "../slack/probe.js";
+export { resolveSlackChannelAllowlist } from "../slack/resolve-channels.js";
+export { resolveSlackUserAllowlist } from "../slack/resolve-users.js";
+export { sendMessageSlack } from "../slack/send.js";
+export { monitorSlackProvider } from "../slack/index.js";
+export { handleSlackAction } from "../agents/tools/slack-actions.js";
+export { slackOnboardingAdapter } from "../channels/plugins/onboarding/slack.js";
+export {
+  looksLikeSlackTargetId,
+  normalizeSlackMessagingTarget,
+} from "../channels/plugins/normalize/slack.js";
+
+// Channel: Telegram
+export {
+  listTelegramAccountIds,
+  resolveDefaultTelegramAccountId,
+  resolveTelegramAccount,
+  type ResolvedTelegramAccount,
+} from "../telegram/accounts.js";
+export {
+  auditTelegramGroupMembership,
+  collectTelegramUnmentionedGroupIds,
+} from "../telegram/audit.js";
+export { probeTelegram } from "../telegram/probe.js";
+export { resolveTelegramToken } from "../telegram/token.js";
+export { sendMessageTelegram } from "../telegram/send.js";
+export { monitorTelegramProvider } from "../telegram/monitor.js";
+export { telegramMessageActions } from "../channels/plugins/actions/telegram.js";
+export { telegramOnboardingAdapter } from "../channels/plugins/onboarding/telegram.js";
+export {
+  looksLikeTelegramTargetId,
+  normalizeTelegramMessagingTarget,
+} from "../channels/plugins/normalize/telegram.js";
+export { collectTelegramStatusIssues } from "../channels/plugins/status-issues/telegram.js";
+
+// Channel: Signal
+export {
+  listSignalAccountIds,
+  resolveDefaultSignalAccountId,
+  resolveSignalAccount,
+  type ResolvedSignalAccount,
+} from "../signal/accounts.js";
+export { probeSignal } from "../signal/probe.js";
+export { sendMessageSignal } from "../signal/send.js";
+export { monitorSignalProvider } from "../signal/index.js";
+export { signalOnboardingAdapter } from "../channels/plugins/onboarding/signal.js";
+export {
+  looksLikeSignalTargetId,
+  normalizeSignalMessagingTarget,
+} from "../channels/plugins/normalize/signal.js";
+
+// Channel: WhatsApp
+export {
+  listWhatsAppAccountIds,
+  resolveDefaultWhatsAppAccountId,
+  resolveWhatsAppAccount,
+  type ResolvedWhatsAppAccount,
+} from "../web/accounts.js";
+export { getActiveWebListener } from "../web/active-listener.js";
+export {
+  getWebAuthAgeMs,
+  logoutWeb,
+  logWebSelfId,
+  readWebSelfId,
+  webAuthExists,
+} from "../web/auth-store.js";
+export { sendMessageWhatsApp, sendPollWhatsApp } from "../web/outbound.js";
+export { isWhatsAppGroupJid, normalizeWhatsAppTarget } from "../whatsapp/normalize.js";
+export { loginWeb } from "../web/login.js";
+export { startWebLoginWithQr, waitForWebLogin } from "../web/login-qr.js";
+export { monitorWebChannel } from "../channels/web/index.js";
+export { handleWhatsAppAction } from "../agents/tools/whatsapp-actions.js";
+export { createWhatsAppLoginTool } from "../channels/plugins/agent-tools/whatsapp-login.js";
+export { whatsappOnboardingAdapter } from "../channels/plugins/onboarding/whatsapp.js";
+export { resolveWhatsAppHeartbeatRecipients } from "../channels/plugins/whatsapp-heartbeat.js";
+export {
+  looksLikeWhatsAppTargetId,
+  normalizeWhatsAppMessagingTarget,
+} from "../channels/plugins/normalize/whatsapp.js";
+export { collectWhatsAppStatusIssues } from "../channels/plugins/status-issues/whatsapp.js";

src/plugins/loader.ts

@@ -46,6 +46,14 @@ const registryCache = new Map<string, PluginRegistry>();
 
 const defaultLogger = () => createSubsystemLogger("plugins");
 
+const BUNDLED_ENABLED_BY_DEFAULT = new Set([
+  "telegram",
+  "whatsapp",
+  "discord",
+  "slack",
+  "signal",
+]);
+
 const normalizeList = (value: unknown): string[] => {
   if (!Array.isArray(value)) return [];
   return value.map((entry) => (typeof entry === "string" ? entry.trim() : "")).filter(Boolean);
@@ -174,6 +182,9 @@ function resolveEnableState(
   if (entry?.enabled === false) {
     return { enabled: false, reason: "disabled in config" };
   }
+  if (origin === "bundled" && BUNDLED_ENABLED_BY_DEFAULT.has(id)) {
+    return { enabled: true };
+  }
   if (origin === "bundled") {
     return { enabled: false, reason: "bundled (disabled by default)" };
   }

src/security/audit.test.ts

@@ -3,9 +3,9 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { ClawdbotConfig } from "../config/config.js";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
 import { runSecurityAudit } from "./audit.js";
-import { discordPlugin } from "../channels/plugins/discord.js";
-import { slackPlugin } from "../channels/plugins/slack.js";
-import { telegramPlugin } from "../channels/plugins/telegram.js";
+import { discordPlugin } from "../../extensions/discord/src/channel.js";
+import { slackPlugin } from "../../extensions/slack/src/channel.js";
+import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/test-utils/channel-plugins.ts

@@ -0,0 +1,95 @@
+import { imessageOutbound } from "../channels/plugins/outbound/imessage.js";
+import type {
+  ChannelCapabilities,
+  ChannelId,
+  ChannelOutboundAdapter,
+  ChannelPlugin,
+} from "../channels/plugins/types.js";
+import type { PluginRegistry } from "../plugins/registry.js";
+import { normalizeIMessageHandle } from "../imessage/targets.js";
+
+export const createTestRegistry = (
+  channels: PluginRegistry["channels"] = [],
+): PluginRegistry => ({
+  plugins: [],
+  tools: [],
+  channels,
+  providers: [],
+  gatewayHandlers: {},
+  httpHandlers: [],
+  cliRegistrars: [],
+  services: [],
+  diagnostics: [],
+});
+
+export const createIMessageTestPlugin = (params?: {
+  outbound?: ChannelOutboundAdapter;
+}): ChannelPlugin => ({
+  id: "imessage",
+  meta: {
+    id: "imessage",
+    label: "iMessage",
+    selectionLabel: "iMessage (imsg)",
+    docsPath: "/channels/imessage",
+    blurb: "iMessage test stub.",
+  },
+  capabilities: { chatTypes: ["direct", "group"], media: true },
+  config: {
+    listAccountIds: () => [],
+    resolveAccount: () => ({}),
+  },
+  status: {
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((account) => {
+        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+        if (!lastError) return [];
+        return [
+          {
+            channel: "imessage",
+            accountId: account.accountId,
+            kind: "runtime",
+            message: `Channel error: ${lastError}`,
+          },
+        ];
+      }),
+  },
+  outbound: params?.outbound ?? imessageOutbound,
+  messaging: {
+    targetResolver: {
+      looksLikeId: (raw) => {
+        const trimmed = raw.trim();
+        if (!trimmed) return false;
+        if (/^(imessage:|sms:|auto:|chat_id:|chat_guid:|chat_identifier:)/i.test(trimmed)) {
+          return true;
+        }
+        if (trimmed.includes("@")) return true;
+        return /^\+?\d{3,}$/.test(trimmed);
+      },
+      hint: "<handle|chat_id:ID>",
+    },
+    normalizeTarget: (raw) => normalizeIMessageHandle(raw),
+  },
+});
+
+export const createOutboundTestPlugin = (params: {
+  id: ChannelId;
+  outbound: ChannelOutboundAdapter;
+  label?: string;
+  docsPath?: string;
+  capabilities?: ChannelCapabilities;
+}): ChannelPlugin => ({
+  id: params.id,
+  meta: {
+    id: params.id,
+    label: params.label ?? String(params.id),
+    selectionLabel: params.label ?? String(params.id),
+    docsPath: params.docsPath ?? `/channels/${params.id}`,
+    blurb: "test stub.",
+  },
+  capabilities: params.capabilities ?? { chatTypes: ["direct"] },
+  config: {
+    listAccountIds: () => [],
+    resolveAccount: () => ({}),
+  },
+  outbound: params.outbound,
+});

test/helpers/temp-home.ts

@@ -74,6 +74,7 @@ export async function withTempHome<T>(
   const envSnapshot = snapshotExtraEnv(envKeys);
 
   setTempHome(base);
+  await fs.mkdir(path.join(base, ".clawdbot", "agents", "main", "sessions"), { recursive: true });
   if (opts.env) {
     for (const [key, raw] of Object.entries(opts.env)) {
       const value = typeof raw === "function" ? raw(base) : raw;

test/setup.ts

@@ -1,10 +1,141 @@
+import { afterEach, beforeEach, vi } from "vitest";
+
+import type { ChannelId, ChannelOutboundAdapter, ChannelPlugin } from "../src/channels/plugins/types.js";
+import type { ClawdbotConfig } from "../src/config/config.js";
+import type { OutboundSendDeps } from "../src/infra/outbound/deliver.js";
+import { setActivePluginRegistry } from "../src/plugins/runtime.js";
+import { createTestRegistry } from "../src/test-utils/channel-plugins.js";
 import { installTestEnv } from "./test-env";
-import { afterEach, vi } from "vitest";
 
 const { cleanup } = installTestEnv();
 process.on("exit", cleanup);
 
+const pickSendFn = (id: ChannelId, deps?: OutboundSendDeps) => {
+  switch (id) {
+    case "discord":
+      return deps?.sendDiscord;
+    case "slack":
+      return deps?.sendSlack;
+    case "telegram":
+      return deps?.sendTelegram;
+    case "whatsapp":
+      return deps?.sendWhatsApp;
+    case "signal":
+      return deps?.sendSignal;
+    case "imessage":
+      return deps?.sendIMessage;
+    default:
+      return undefined;
+  }
+};
+
+const createStubOutbound = (
+  id: ChannelId,
+  deliveryMode: ChannelOutboundAdapter["deliveryMode"] = "direct",
+): ChannelOutboundAdapter => ({
+  deliveryMode,
+  sendText: async ({ deps, to, text }) => {
+    const send = pickSendFn(id, deps);
+    if (send) {
+      const result = await send(to, text, {});
+      return { channel: id, ...result };
+    }
+    return { channel: id, messageId: "test" };
+  },
+  sendMedia: async ({ deps, to, text, mediaUrl }) => {
+    const send = pickSendFn(id, deps);
+    if (send) {
+      const result = await send(to, text, { mediaUrl });
+      return { channel: id, ...result };
+    }
+    return { channel: id, messageId: "test" };
+  },
+});
+
+const createStubPlugin = (params: {
+  id: ChannelId;
+  label?: string;
+  aliases?: string[];
+  deliveryMode?: ChannelOutboundAdapter["deliveryMode"];
+  preferSessionLookupForAnnounceTarget?: boolean;
+}): ChannelPlugin => ({
+  id: params.id,
+  meta: {
+    id: params.id,
+    label: params.label ?? String(params.id),
+    selectionLabel: params.label ?? String(params.id),
+    docsPath: `/channels/${params.id}`,
+    blurb: "test stub.",
+    aliases: params.aliases,
+    preferSessionLookupForAnnounceTarget: params.preferSessionLookupForAnnounceTarget,
+  },
+  capabilities: { chatTypes: ["direct", "group"] },
+  config: {
+    listAccountIds: (cfg: ClawdbotConfig) => {
+      const channels = cfg.channels as Record<string, unknown> | undefined;
+      const entry = channels?.[params.id];
+      if (!entry || typeof entry !== "object") return [];
+      const accounts = (entry as { accounts?: Record<string, unknown> }).accounts;
+      const ids = accounts ? Object.keys(accounts).filter(Boolean) : [];
+      return ids.length > 0 ? ids : ["default"];
+    },
+    resolveAccount: (cfg: ClawdbotConfig, accountId: string) => {
+      const channels = cfg.channels as Record<string, unknown> | undefined;
+      const entry = channels?.[params.id];
+      if (!entry || typeof entry !== "object") return {};
+      const accounts = (entry as { accounts?: Record<string, unknown> }).accounts;
+      const match = accounts?.[accountId];
+      return (match && typeof match === "object") || typeof match === "string" ? match : entry;
+    },
+    isConfigured: async (_account, cfg: ClawdbotConfig) => {
+      const channels = cfg.channels as Record<string, unknown> | undefined;
+      return Boolean(channels?.[params.id]);
+    },
+  },
+  outbound: createStubOutbound(params.id, params.deliveryMode),
+});
+
+const createDefaultRegistry = () =>
+  createTestRegistry([
+    { pluginId: "discord", plugin: createStubPlugin({ id: "discord", label: "Discord" }), source: "test" },
+    { pluginId: "slack", plugin: createStubPlugin({ id: "slack", label: "Slack" }), source: "test" },
+    {
+      pluginId: "telegram",
+      plugin: {
+        ...createStubPlugin({ id: "telegram", label: "Telegram" }),
+        status: {
+          buildChannelSummary: async () => ({
+            configured: false,
+            tokenSource: process.env.TELEGRAM_BOT_TOKEN ? "env" : "none",
+          }),
+        },
+      },
+      source: "test",
+    },
+    {
+      pluginId: "whatsapp",
+      plugin: createStubPlugin({
+        id: "whatsapp",
+        label: "WhatsApp",
+        deliveryMode: "gateway",
+        preferSessionLookupForAnnounceTarget: true,
+      }),
+      source: "test",
+    },
+    { pluginId: "signal", plugin: createStubPlugin({ id: "signal", label: "Signal" }), source: "test" },
+    {
+      pluginId: "imessage",
+      plugin: createStubPlugin({ id: "imessage", label: "iMessage", aliases: ["imsg"] }),
+      source: "test",
+    },
+  ]);
+
+beforeEach(() => {
+  setActivePluginRegistry(createDefaultRegistry());
+});
+
 afterEach(() => {
+  setActivePluginRegistry(createDefaultRegistry());
   // Guard against leaked fake timers across test files/workers.
   vi.useRealTimers();
 });