refactor: extract mattermost channel plugin to extension

Move mattermost channel implementation from core to extensions/mattermost plugin. Extract config schema, group mentions, normalize utilities, and all mattermost-specific logic (accounts, client, monitor, probe, send) into the extension. Update imports to use plugin SDK and local modules. Add channel metadata directly in plugin definition instead of using getChatChannelMeta. Update package.json with channel and install configuration.

extensions/mattermost/package.json

@@ -6,6 +6,20 @@
   "clawdbot": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "channel": {
+      "id": "mattermost",
+      "label": "Mattermost",
+      "selectionLabel": "Mattermost (plugin)",
+      "docsPath": "/channels/mattermost",
+      "docsLabel": "mattermost",
+      "blurb": "self-hosted Slack-style chat; install the plugin to enable.",
+      "order": 65
+    },
+    "install": {
+      "npmSpec": "@clawdbot/mattermost",
+      "localPath": "extensions/mattermost",
+      "defaultChoice": "npm"
+    }
   }
 }

extensions/mattermost/src/channel.ts

@@ -3,26 +3,42 @@ import {
   buildChannelConfigSchema,
   DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
-  getChatChannelMeta,
-  listMattermostAccountIds,
-  looksLikeMattermostTargetId,
   migrateBaseNameToDefaultAccount,
   normalizeAccountId,
-  normalizeMattermostBaseUrl,
-  normalizeMattermostMessagingTarget,
-  resolveDefaultMattermostAccountId,
-  resolveMattermostAccount,
-  resolveMattermostGroupRequireMention,
   setAccountEnabledInConfigSection,
-  mattermostOnboardingAdapter,
-  MattermostConfigSchema,
   type ChannelPlugin,
-  type ResolvedMattermostAccount,
 } from "clawdbot/plugin-sdk";
 
+import { MattermostConfigSchema } from "./config-schema.js";
+import { resolveMattermostGroupRequireMention } from "./group-mentions.js";
+import {
+  looksLikeMattermostTargetId,
+  normalizeMattermostMessagingTarget,
+} from "./normalize.js";
+import { mattermostOnboardingAdapter } from "./onboarding.js";
+import {
+  listMattermostAccountIds,
+  resolveDefaultMattermostAccountId,
+  resolveMattermostAccount,
+  type ResolvedMattermostAccount,
+} from "./mattermost/accounts.js";
+import { normalizeMattermostBaseUrl } from "./mattermost/client.js";
+import { monitorMattermostProvider } from "./mattermost/monitor.js";
+import { probeMattermost } from "./mattermost/probe.js";
+import { sendMessageMattermost } from "./mattermost/send.js";
 import { getMattermostRuntime } from "./runtime.js";
 
-const meta = getChatChannelMeta("mattermost");
+const meta = {
+  id: "mattermost",
+  label: "Mattermost",
+  selectionLabel: "Mattermost (plugin)",
+  detailLabel: "Mattermost Bot",
+  docsPath: "/channels/mattermost",
+  docsLabel: "mattermost",
+  blurb: "self-hosted Slack-style chat; install the plugin to enable.",
+  systemImage: "bubble.left.and.bubble.right",
+  order: 65,
+} as const;
 
 export const mattermostPlugin: ChannelPlugin<ResolvedMattermostAccount> = {
   id: "mattermost",
@@ -96,8 +112,7 @@ export const mattermostPlugin: ChannelPlugin<ResolvedMattermostAccount> = {
       return { ok: true, to: trimmed };
     },
     sendText: async ({ to, text, accountId, deps, replyToId }) => {
-      const send =
-        deps?.sendMattermost ?? getMattermostRuntime().channel.mattermost.sendMessageMattermost;
+      const send = deps?.sendMattermost ?? sendMessageMattermost;
       const result = await send(to, text, {
         accountId: accountId ?? undefined,
         replyToId: replyToId ?? undefined,
@@ -105,8 +120,7 @@ export const mattermostPlugin: ChannelPlugin<ResolvedMattermostAccount> = {
       return { channel: "mattermost", ...result };
     },
     sendMedia: async ({ to, text, mediaUrl, accountId, deps, replyToId }) => {
-      const send =
-        deps?.sendMattermost ?? getMattermostRuntime().channel.mattermost.sendMessageMattermost;
+      const send = deps?.sendMattermost ?? sendMessageMattermost;
       const result = await send(to, text, {
         accountId: accountId ?? undefined,
         mediaUrl,
@@ -144,11 +158,7 @@ export const mattermostPlugin: ChannelPlugin<ResolvedMattermostAccount> = {
       if (!token || !baseUrl) {
         return { ok: false, error: "bot token or baseUrl missing" };
       }
-      return await getMattermostRuntime().channel.mattermost.probeMattermost(
-        baseUrl,
-        token,
-        timeoutMs,
-      );
+      return await probeMattermost(baseUrl, token, timeoutMs);
     },
     buildAccountSnapshot: ({ account, runtime, probe }) => ({
       accountId: account.accountId,
@@ -256,7 +266,7 @@ export const mattermostPlugin: ChannelPlugin<ResolvedMattermostAccount> = {
         botTokenSource: account.botTokenSource,
       });
       ctx.log?.info(`[${account.accountId}] starting channel`);
-      return getMattermostRuntime().channel.mattermost.monitorMattermostProvider({
+      return monitorMattermostProvider({
         botToken: account.botToken ?? undefined,
         baseUrl: account.baseUrl ?? undefined,
         accountId: account.accountId,

extensions/mattermost/src/config-schema.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+import { BlockStreamingCoalesceSchema } from "clawdbot/plugin-sdk";
+
+const MattermostAccountSchema = z
+  .object({
+    name: z.string().optional(),
+    capabilities: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    configWrites: z.boolean().optional(),
+    botToken: z.string().optional(),
+    baseUrl: z.string().optional(),
+    chatmode: z.enum(["oncall", "onmessage", "onchar"]).optional(),
+    oncharPrefixes: z.array(z.string()).optional(),
+    requireMention: z.boolean().optional(),
+    textChunkLimit: z.number().int().positive().optional(),
+    blockStreaming: z.boolean().optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema.optional(),
+  })
+  .strict();
+
+export const MattermostConfigSchema = MattermostAccountSchema.extend({
+  accounts: z.record(z.string(), MattermostAccountSchema.optional()).optional(),
+});

extensions/mattermost/src/group-mentions.ts

@@ -0,0 +1,14 @@
+import type { ChannelGroupContext } from "clawdbot/plugin-sdk";
+
+import { resolveMattermostAccount } from "./mattermost/accounts.js";
+
+export function resolveMattermostGroupRequireMention(
+  params: ChannelGroupContext,
+): boolean | undefined {
+  const account = resolveMattermostAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  if (typeof account.requireMention === "boolean") return account.requireMention;
+  return true;
+}

extensions/mattermost/src/mattermost/accounts.ts

@@ -0,0 +1,115 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+import type { MattermostAccountConfig, MattermostChatMode } from "../types.js";
+import { normalizeMattermostBaseUrl } from "./client.js";
+
+export type MattermostTokenSource = "env" | "config" | "none";
+export type MattermostBaseUrlSource = "env" | "config" | "none";
+
+export type ResolvedMattermostAccount = {
+  accountId: string;
+  enabled: boolean;
+  name?: string;
+  botToken?: string;
+  baseUrl?: string;
+  botTokenSource: MattermostTokenSource;
+  baseUrlSource: MattermostBaseUrlSource;
+  config: MattermostAccountConfig;
+  chatmode?: MattermostChatMode;
+  oncharPrefixes?: string[];
+  requireMention?: boolean;
+  textChunkLimit?: number;
+  blockStreaming?: boolean;
+  blockStreamingCoalesce?: MattermostAccountConfig["blockStreamingCoalesce"];
+};
+
+function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
+  const accounts = cfg.channels?.mattermost?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listMattermostAccountIds(cfg: ClawdbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultMattermostAccountId(cfg: ClawdbotConfig): string {
+  const ids = listMattermostAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): MattermostAccountConfig | undefined {
+  const accounts = cfg.channels?.mattermost?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as MattermostAccountConfig | undefined;
+}
+
+function mergeMattermostAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): MattermostAccountConfig {
+  const { accounts: _ignored, ...base } = (cfg.channels?.mattermost ??
+    {}) as MattermostAccountConfig & { accounts?: unknown };
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...base, ...account };
+}
+
+function resolveMattermostRequireMention(config: MattermostAccountConfig): boolean | undefined {
+  if (config.chatmode === "oncall") return true;
+  if (config.chatmode === "onmessage") return false;
+  if (config.chatmode === "onchar") return true;
+  return config.requireMention;
+}
+
+export function resolveMattermostAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedMattermostAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = params.cfg.channels?.mattermost?.enabled !== false;
+  const merged = mergeMattermostAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+
+  const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+  const envToken = allowEnv ? process.env.MATTERMOST_BOT_TOKEN?.trim() : undefined;
+  const envUrl = allowEnv ? process.env.MATTERMOST_URL?.trim() : undefined;
+  const configToken = merged.botToken?.trim();
+  const configUrl = merged.baseUrl?.trim();
+  const botToken = configToken || envToken;
+  const baseUrl = normalizeMattermostBaseUrl(configUrl || envUrl);
+  const requireMention = resolveMattermostRequireMention(merged);
+
+  const botTokenSource: MattermostTokenSource = configToken ? "config" : envToken ? "env" : "none";
+  const baseUrlSource: MattermostBaseUrlSource = configUrl ? "config" : envUrl ? "env" : "none";
+
+  return {
+    accountId,
+    enabled,
+    name: merged.name?.trim() || undefined,
+    botToken,
+    baseUrl,
+    botTokenSource,
+    baseUrlSource,
+    config: merged,
+    chatmode: merged.chatmode,
+    oncharPrefixes: merged.oncharPrefixes,
+    requireMention,
+    textChunkLimit: merged.textChunkLimit,
+    blockStreaming: merged.blockStreaming,
+    blockStreamingCoalesce: merged.blockStreamingCoalesce,
+  };
+}
+
+export function listEnabledMattermostAccounts(cfg: ClawdbotConfig): ResolvedMattermostAccount[] {
+  return listMattermostAccountIds(cfg)
+    .map((accountId) => resolveMattermostAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

extensions/mattermost/src/mattermost/client.ts

@@ -0,0 +1,208 @@
+export type MattermostClient = {
+  baseUrl: string;
+  apiBaseUrl: string;
+  token: string;
+  request: <T>(path: string, init?: RequestInit) => Promise<T>;
+};
+
+export type MattermostUser = {
+  id: string;
+  username?: string | null;
+  nickname?: string | null;
+  first_name?: string | null;
+  last_name?: string | null;
+};
+
+export type MattermostChannel = {
+  id: string;
+  name?: string | null;
+  display_name?: string | null;
+  type?: string | null;
+  team_id?: string | null;
+};
+
+export type MattermostPost = {
+  id: string;
+  user_id?: string | null;
+  channel_id?: string | null;
+  message?: string | null;
+  file_ids?: string[] | null;
+  type?: string | null;
+  root_id?: string | null;
+  create_at?: number | null;
+  props?: Record<string, unknown> | null;
+};
+
+export type MattermostFileInfo = {
+  id: string;
+  name?: string | null;
+  mime_type?: string | null;
+  size?: number | null;
+};
+
+export function normalizeMattermostBaseUrl(raw?: string | null): string | undefined {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  const withoutTrailing = trimmed.replace(/\/+$/, "");
+  return withoutTrailing.replace(/\/api\/v4$/i, "");
+}
+
+function buildMattermostApiUrl(baseUrl: string, path: string): string {
+  const normalized = normalizeMattermostBaseUrl(baseUrl);
+  if (!normalized) throw new Error("Mattermost baseUrl is required");
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  return `${normalized}/api/v4${suffix}`;
+}
+
+async function readMattermostError(res: Response): Promise<string> {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const data = (await res.json()) as { message?: string } | undefined;
+    if (data?.message) return data.message;
+    return JSON.stringify(data);
+  }
+  return await res.text();
+}
+
+export function createMattermostClient(params: {
+  baseUrl: string;
+  botToken: string;
+  fetchImpl?: typeof fetch;
+}): MattermostClient {
+  const baseUrl = normalizeMattermostBaseUrl(params.baseUrl);
+  if (!baseUrl) throw new Error("Mattermost baseUrl is required");
+  const apiBaseUrl = `${baseUrl}/api/v4`;
+  const token = params.botToken.trim();
+  const fetchImpl = params.fetchImpl ?? fetch;
+
+  const request = async <T>(path: string, init?: RequestInit): Promise<T> => {
+    const url = buildMattermostApiUrl(baseUrl, path);
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    if (typeof init?.body === "string" && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    const res = await fetchImpl(url, { ...init, headers });
+    if (!res.ok) {
+      const detail = await readMattermostError(res);
+      throw new Error(
+        `Mattermost API ${res.status} ${res.statusText}: ${detail || "unknown error"}`,
+      );
+    }
+    return (await res.json()) as T;
+  };
+
+  return { baseUrl, apiBaseUrl, token, request };
+}
+
+export async function fetchMattermostMe(client: MattermostClient): Promise<MattermostUser> {
+  return await client.request<MattermostUser>("/users/me");
+}
+
+export async function fetchMattermostUser(
+  client: MattermostClient,
+  userId: string,
+): Promise<MattermostUser> {
+  return await client.request<MattermostUser>(`/users/${userId}`);
+}
+
+export async function fetchMattermostUserByUsername(
+  client: MattermostClient,
+  username: string,
+): Promise<MattermostUser> {
+  return await client.request<MattermostUser>(`/users/username/${encodeURIComponent(username)}`);
+}
+
+export async function fetchMattermostChannel(
+  client: MattermostClient,
+  channelId: string,
+): Promise<MattermostChannel> {
+  return await client.request<MattermostChannel>(`/channels/${channelId}`);
+}
+
+export async function sendMattermostTyping(
+  client: MattermostClient,
+  params: { channelId: string; parentId?: string },
+): Promise<void> {
+  const payload: Record<string, string> = {
+    channel_id: params.channelId,
+  };
+  const parentId = params.parentId?.trim();
+  if (parentId) payload.parent_id = parentId;
+  await client.request<Record<string, unknown>>("/users/me/typing", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function createMattermostDirectChannel(
+  client: MattermostClient,
+  userIds: string[],
+): Promise<MattermostChannel> {
+  return await client.request<MattermostChannel>("/channels/direct", {
+    method: "POST",
+    body: JSON.stringify(userIds),
+  });
+}
+
+export async function createMattermostPost(
+  client: MattermostClient,
+  params: {
+    channelId: string;
+    message: string;
+    rootId?: string;
+    fileIds?: string[];
+  },
+): Promise<MattermostPost> {
+  const payload: Record<string, string> = {
+    channel_id: params.channelId,
+    message: params.message,
+  };
+  if (params.rootId) payload.root_id = params.rootId;
+  if (params.fileIds?.length) {
+    (payload as Record<string, unknown>).file_ids = params.fileIds;
+  }
+  return await client.request<MattermostPost>("/posts", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function uploadMattermostFile(
+  client: MattermostClient,
+  params: {
+    channelId: string;
+    buffer: Buffer;
+    fileName: string;
+    contentType?: string;
+  },
+): Promise<MattermostFileInfo> {
+  const form = new FormData();
+  const fileName = params.fileName?.trim() || "upload";
+  const bytes = Uint8Array.from(params.buffer);
+  const blob = params.contentType
+    ? new Blob([bytes], { type: params.contentType })
+    : new Blob([bytes]);
+  form.append("files", blob, fileName);
+  form.append("channel_id", params.channelId);
+
+  const res = await fetch(`${client.apiBaseUrl}/files`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${client.token}`,
+    },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const detail = await readMattermostError(res);
+    throw new Error(`Mattermost API ${res.status} ${res.statusText}: ${detail || "unknown error"}`);
+  }
+
+  const data = (await res.json()) as { file_infos?: MattermostFileInfo[] };
+  const info = data.file_infos?.[0];
+  if (!info?.id) {
+    throw new Error("Mattermost file upload failed");
+  }
+  return info;
+}

extensions/mattermost/src/mattermost/index.ts

@@ -0,0 +1,9 @@
+export {
+  listEnabledMattermostAccounts,
+  listMattermostAccountIds,
+  resolveDefaultMattermostAccountId,
+  resolveMattermostAccount,
+} from "./accounts.js";
+export { monitorMattermostProvider } from "./monitor.js";
+export { probeMattermost } from "./probe.js";
+export { sendMessageMattermost } from "./send.js";

extensions/mattermost/src/mattermost/monitor-helpers.ts

@@ -0,0 +1,150 @@
+import { Buffer } from "node:buffer";
+
+import type WebSocket from "ws";
+
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+
+export type ResponsePrefixContext = {
+  model?: string;
+  modelFull?: string;
+  provider?: string;
+  thinkingLevel?: string;
+  identityName?: string;
+};
+
+export function extractShortModelName(fullModel: string): string {
+  const slash = fullModel.lastIndexOf("/");
+  const modelPart = slash >= 0 ? fullModel.slice(slash + 1) : fullModel;
+  return modelPart.replace(/-\d{8}$/, "").replace(/-latest$/, "");
+}
+
+export function formatInboundFromLabel(params: {
+  isGroup: boolean;
+  groupLabel?: string;
+  groupId?: string;
+  directLabel: string;
+  directId?: string;
+  groupFallback?: string;
+}): string {
+  if (params.isGroup) {
+    const label = params.groupLabel?.trim() || params.groupFallback || "Group";
+    const id = params.groupId?.trim();
+    return id ? `${label} id:${id}` : label;
+  }
+
+  const directLabel = params.directLabel.trim();
+  const directId = params.directId?.trim();
+  if (!directId || directId === directLabel) return directLabel;
+  return `${directLabel} id:${directId}`;
+}
+
+type DedupeCache = {
+  check: (key: string | undefined | null, now?: number) => boolean;
+};
+
+export function createDedupeCache(options: { ttlMs: number; maxSize: number }): DedupeCache {
+  const ttlMs = Math.max(0, options.ttlMs);
+  const maxSize = Math.max(0, Math.floor(options.maxSize));
+  const cache = new Map<string, number>();
+
+  const touch = (key: string, now: number) => {
+    cache.delete(key);
+    cache.set(key, now);
+  };
+
+  const prune = (now: number) => {
+    const cutoff = ttlMs > 0 ? now - ttlMs : undefined;
+    if (cutoff !== undefined) {
+      for (const [entryKey, entryTs] of cache) {
+        if (entryTs < cutoff) {
+          cache.delete(entryKey);
+        }
+      }
+    }
+    if (maxSize <= 0) {
+      cache.clear();
+      return;
+    }
+    while (cache.size > maxSize) {
+      const oldestKey = cache.keys().next().value as string | undefined;
+      if (!oldestKey) break;
+      cache.delete(oldestKey);
+    }
+  };
+
+  return {
+    check: (key, now = Date.now()) => {
+      if (!key) return false;
+      const existing = cache.get(key);
+      if (existing !== undefined && (ttlMs <= 0 || now - existing < ttlMs)) {
+        touch(key, now);
+        return true;
+      }
+      touch(key, now);
+      prune(now);
+      return false;
+    },
+  };
+}
+
+export function rawDataToString(
+  data: WebSocket.RawData,
+  encoding: BufferEncoding = "utf8",
+): string {
+  if (typeof data === "string") return data;
+  if (Buffer.isBuffer(data)) return data.toString(encoding);
+  if (Array.isArray(data)) return Buffer.concat(data).toString(encoding);
+  if (data instanceof ArrayBuffer) {
+    return Buffer.from(data).toString(encoding);
+  }
+  return Buffer.from(String(data)).toString(encoding);
+}
+
+function normalizeAgentId(value: string | undefined | null): string {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) return "main";
+  if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed)) return trimmed;
+  return (
+    trimmed
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+/, "")
+      .replace(/-+$/, "")
+      .slice(0, 64) || "main"
+  );
+}
+
+type AgentEntry = NonNullable<NonNullable<ClawdbotConfig["agents"]>["list"]>[number];
+
+function listAgents(cfg: ClawdbotConfig): AgentEntry[] {
+  const list = cfg.agents?.list;
+  if (!Array.isArray(list)) return [];
+  return list.filter((entry): entry is AgentEntry => Boolean(entry && typeof entry === "object"));
+}
+
+function resolveAgentEntry(cfg: ClawdbotConfig, agentId: string): AgentEntry | undefined {
+  const id = normalizeAgentId(agentId);
+  return listAgents(cfg).find((entry) => normalizeAgentId(entry.id) === id);
+}
+
+export function resolveIdentityName(cfg: ClawdbotConfig, agentId: string): string | undefined {
+  const entry = resolveAgentEntry(cfg, agentId);
+  return entry?.identity?.name?.trim() || undefined;
+}
+
+export function resolveThreadSessionKeys(params: {
+  baseSessionKey: string;
+  threadId?: string | null;
+  parentSessionKey?: string;
+  useSuffix?: boolean;
+}): { sessionKey: string; parentSessionKey?: string } {
+  const threadId = (params.threadId ?? "").trim();
+  if (!threadId) {
+    return { sessionKey: params.baseSessionKey, parentSessionKey: undefined };
+  }
+  const useSuffix = params.useSuffix ?? true;
+  const sessionKey = useSuffix
+    ? `${params.baseSessionKey}:thread:${threadId}`
+    : params.baseSessionKey;
+  return { sessionKey, parentSessionKey: params.parentSessionKey };
+}

extensions/mattermost/src/mattermost/monitor.ts

@@ -0,0 +1,763 @@
+import WebSocket from "ws";
+
+import type {
+  ChannelAccountSnapshot,
+  ClawdbotConfig,
+  ReplyPayload,
+  RuntimeEnv,
+} from "clawdbot/plugin-sdk";
+import {
+  buildPendingHistoryContextFromMap,
+  clearHistoryEntries,
+  DEFAULT_GROUP_HISTORY_LIMIT,
+  recordPendingHistoryEntry,
+  resolveChannelMediaMaxBytes,
+  type HistoryEntry,
+} from "clawdbot/plugin-sdk";
+
+import { getMattermostRuntime } from "../runtime.js";
+import { resolveMattermostAccount } from "./accounts.js";
+import {
+  createMattermostClient,
+  fetchMattermostChannel,
+  fetchMattermostMe,
+  fetchMattermostUser,
+  normalizeMattermostBaseUrl,
+  sendMattermostTyping,
+  type MattermostChannel,
+  type MattermostPost,
+  type MattermostUser,
+} from "./client.js";
+import {
+  createDedupeCache,
+  extractShortModelName,
+  formatInboundFromLabel,
+  rawDataToString,
+  resolveIdentityName,
+  resolveThreadSessionKeys,
+  type ResponsePrefixContext,
+} from "./monitor-helpers.js";
+import { sendMessageMattermost } from "./send.js";
+
+export type MonitorMattermostOpts = {
+  botToken?: string;
+  baseUrl?: string;
+  accountId?: string;
+  config?: ClawdbotConfig;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  statusSink?: (patch: Partial<ChannelAccountSnapshot>) => void;
+};
+
+type FetchLike = typeof fetch;
+type MediaKind = "image" | "audio" | "video" | "document" | "unknown";
+
+type MattermostEventPayload = {
+  event?: string;
+  data?: {
+    post?: string;
+    channel_id?: string;
+    channel_name?: string;
+    channel_display_name?: string;
+    channel_type?: string;
+    sender_name?: string;
+    team_id?: string;
+  };
+  broadcast?: {
+    channel_id?: string;
+    team_id?: string;
+    user_id?: string;
+  };
+};
+
+const RECENT_MATTERMOST_MESSAGE_TTL_MS = 5 * 60_000;
+const RECENT_MATTERMOST_MESSAGE_MAX = 2000;
+const CHANNEL_CACHE_TTL_MS = 5 * 60_000;
+const USER_CACHE_TTL_MS = 10 * 60_000;
+const DEFAULT_ONCHAR_PREFIXES = [">", "!"];
+
+const recentInboundMessages = createDedupeCache({
+  ttlMs: RECENT_MATTERMOST_MESSAGE_TTL_MS,
+  maxSize: RECENT_MATTERMOST_MESSAGE_MAX,
+});
+
+function resolveRuntime(opts: MonitorMattermostOpts): RuntimeEnv {
+  return (
+    opts.runtime ?? {
+      log: console.log,
+      error: console.error,
+      exit: (code: number): never => {
+        throw new Error(`exit ${code}`);
+      },
+    }
+  );
+}
+
+function normalizeMention(text: string, mention: string | undefined): string {
+  if (!mention) return text.trim();
+  const escaped = mention.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`@${escaped}\\b`, "gi");
+  return text.replace(re, " ").replace(/\s+/g, " ").trim();
+}
+
+function resolveOncharPrefixes(prefixes: string[] | undefined): string[] {
+  const cleaned = prefixes?.map((entry) => entry.trim()).filter(Boolean) ?? DEFAULT_ONCHAR_PREFIXES;
+  return cleaned.length > 0 ? cleaned : DEFAULT_ONCHAR_PREFIXES;
+}
+
+function stripOncharPrefix(
+  text: string,
+  prefixes: string[],
+): { triggered: boolean; stripped: string } {
+  const trimmed = text.trimStart();
+  for (const prefix of prefixes) {
+    if (!prefix) continue;
+    if (trimmed.startsWith(prefix)) {
+      return {
+        triggered: true,
+        stripped: trimmed.slice(prefix.length).trimStart(),
+      };
+    }
+  }
+  return { triggered: false, stripped: text };
+}
+
+function isSystemPost(post: MattermostPost): boolean {
+  const type = post.type?.trim();
+  return Boolean(type);
+}
+
+function channelKind(channelType?: string | null): "dm" | "group" | "channel" {
+  if (!channelType) return "channel";
+  const normalized = channelType.trim().toUpperCase();
+  if (normalized === "D") return "dm";
+  if (normalized === "G") return "group";
+  return "channel";
+}
+
+function channelChatType(kind: "dm" | "group" | "channel"): "direct" | "group" | "channel" {
+  if (kind === "dm") return "direct";
+  if (kind === "group") return "group";
+  return "channel";
+}
+
+type MattermostMediaInfo = {
+  path: string;
+  contentType?: string;
+  kind: MediaKind;
+};
+
+function buildMattermostAttachmentPlaceholder(mediaList: MattermostMediaInfo[]): string {
+  if (mediaList.length === 0) return "";
+  if (mediaList.length === 1) {
+    const kind = mediaList[0].kind === "unknown" ? "document" : mediaList[0].kind;
+    return `<media:${kind}>`;
+  }
+  const allImages = mediaList.every((media) => media.kind === "image");
+  const label = allImages ? "image" : "file";
+  const suffix = mediaList.length === 1 ? label : `${label}s`;
+  const tag = allImages ? "<media:image>" : "<media:document>";
+  return `${tag} (${mediaList.length} ${suffix})`;
+}
+
+function buildMattermostMediaPayload(mediaList: MattermostMediaInfo[]): {
+  MediaPath?: string;
+  MediaType?: string;
+  MediaUrl?: string;
+  MediaPaths?: string[];
+  MediaUrls?: string[];
+  MediaTypes?: string[];
+} {
+  const first = mediaList[0];
+  const mediaPaths = mediaList.map((media) => media.path);
+  const mediaTypes = mediaList.map((media) => media.contentType).filter(Boolean) as string[];
+  return {
+    MediaPath: first?.path,
+    MediaType: first?.contentType,
+    MediaUrl: first?.path,
+    MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+  };
+}
+
+function buildMattermostWsUrl(baseUrl: string): string {
+  const normalized = normalizeMattermostBaseUrl(baseUrl);
+  if (!normalized) throw new Error("Mattermost baseUrl is required");
+  const wsBase = normalized.replace(/^http/i, "ws");
+  return `${wsBase}/api/v4/websocket`;
+}
+
+export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}): Promise<void> {
+  const core = getMattermostRuntime();
+  const runtime = resolveRuntime(opts);
+  const cfg = opts.config ?? core.config.loadConfig();
+  const account = resolveMattermostAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const botToken = opts.botToken?.trim() || account.botToken?.trim();
+  if (!botToken) {
+    throw new Error(
+      `Mattermost bot token missing for account "${account.accountId}" (set channels.mattermost.accounts.${account.accountId}.botToken or MATTERMOST_BOT_TOKEN for default).`,
+    );
+  }
+  const baseUrl = normalizeMattermostBaseUrl(opts.baseUrl ?? account.baseUrl);
+  if (!baseUrl) {
+    throw new Error(
+      `Mattermost baseUrl missing for account "${account.accountId}" (set channels.mattermost.accounts.${account.accountId}.baseUrl or MATTERMOST_URL for default).`,
+    );
+  }
+
+  const client = createMattermostClient({ baseUrl, botToken });
+  const botUser = await fetchMattermostMe(client);
+  const botUserId = botUser.id;
+  const botUsername = botUser.username?.trim() || undefined;
+  runtime.log?.(`mattermost connected as ${botUsername ? `@${botUsername}` : botUserId}`);
+
+  const channelCache = new Map<string, { value: MattermostChannel | null; expiresAt: number }>();
+  const userCache = new Map<string, { value: MattermostUser | null; expiresAt: number }>();
+  const logger = core.logging.getChildLogger({ module: "mattermost" });
+  const logVerboseMessage = (message: string) => {
+    if (!core.logging.shouldLogVerbose()) return;
+    logger.debug?.(message);
+  };
+  const mediaMaxBytes =
+    resolveChannelMediaMaxBytes({
+      cfg,
+      resolveChannelLimitMb: () => undefined,
+      accountId: account.accountId,
+    }) ?? 8 * 1024 * 1024;
+  const historyLimit = Math.max(
+    0,
+    cfg.messages?.groupChat?.historyLimit ?? DEFAULT_GROUP_HISTORY_LIMIT,
+  );
+  const channelHistories = new Map<string, HistoryEntry[]>();
+
+  const fetchWithAuth: FetchLike = (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${client.token}`);
+    return fetch(input, { ...init, headers });
+  };
+
+  const resolveMattermostMedia = async (
+    fileIds?: string[] | null,
+  ): Promise<MattermostMediaInfo[]> => {
+    const ids = (fileIds ?? []).map((id) => id?.trim()).filter(Boolean) as string[];
+    if (ids.length === 0) return [];
+    const out: MattermostMediaInfo[] = [];
+    for (const fileId of ids) {
+      try {
+        const fetched = await core.channel.media.fetchRemoteMedia({
+          url: `${client.apiBaseUrl}/files/${fileId}`,
+          fetchImpl: fetchWithAuth,
+          filePathHint: fileId,
+          maxBytes: mediaMaxBytes,
+        });
+        const saved = await core.channel.media.saveMediaBuffer(
+          fetched.buffer,
+          fetched.contentType ?? undefined,
+          "inbound",
+          mediaMaxBytes,
+        );
+        const contentType = saved.contentType ?? fetched.contentType ?? undefined;
+        out.push({
+          path: saved.path,
+          contentType,
+          kind: core.media.mediaKindFromMime(contentType),
+        });
+      } catch (err) {
+        logger.debug?.(`mattermost: failed to download file ${fileId}: ${String(err)}`);
+      }
+    }
+    return out;
+  };
+
+  const sendTypingIndicator = async (channelId: string, parentId?: string) => {
+    try {
+      await sendMattermostTyping(client, { channelId, parentId });
+    } catch (err) {
+      logger.debug?.(`mattermost typing cue failed for channel ${channelId}: ${String(err)}`);
+    }
+  };
+
+  const resolveChannelInfo = async (channelId: string): Promise<MattermostChannel | null> => {
+    const cached = channelCache.get(channelId);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    try {
+      const info = await fetchMattermostChannel(client, channelId);
+      channelCache.set(channelId, {
+        value: info,
+        expiresAt: Date.now() + CHANNEL_CACHE_TTL_MS,
+      });
+      return info;
+    } catch (err) {
+      logger.debug?.(`mattermost: channel lookup failed: ${String(err)}`);
+      channelCache.set(channelId, {
+        value: null,
+        expiresAt: Date.now() + CHANNEL_CACHE_TTL_MS,
+      });
+      return null;
+    }
+  };
+
+  const resolveUserInfo = async (userId: string): Promise<MattermostUser | null> => {
+    const cached = userCache.get(userId);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    try {
+      const info = await fetchMattermostUser(client, userId);
+      userCache.set(userId, {
+        value: info,
+        expiresAt: Date.now() + USER_CACHE_TTL_MS,
+      });
+      return info;
+    } catch (err) {
+      logger.debug?.(`mattermost: user lookup failed: ${String(err)}`);
+      userCache.set(userId, {
+        value: null,
+        expiresAt: Date.now() + USER_CACHE_TTL_MS,
+      });
+      return null;
+    }
+  };
+
+  const handlePost = async (
+    post: MattermostPost,
+    payload: MattermostEventPayload,
+    messageIds?: string[],
+  ) => {
+    const channelId = post.channel_id ?? payload.data?.channel_id ?? payload.broadcast?.channel_id;
+    if (!channelId) return;
+
+    const allMessageIds = messageIds?.length ? messageIds : post.id ? [post.id] : [];
+    if (allMessageIds.length === 0) return;
+    const dedupeEntries = allMessageIds.map((id) =>
+      recentInboundMessages.check(`${account.accountId}:${id}`),
+    );
+    if (dedupeEntries.length > 0 && dedupeEntries.every(Boolean)) return;
+
+    const senderId = post.user_id ?? payload.broadcast?.user_id;
+    if (!senderId) return;
+    if (senderId === botUserId) return;
+    if (isSystemPost(post)) return;
+
+    const channelInfo = await resolveChannelInfo(channelId);
+    const channelType = payload.data?.channel_type ?? channelInfo?.type ?? undefined;
+    const kind = channelKind(channelType);
+    const chatType = channelChatType(kind);
+
+    const teamId = payload.data?.team_id ?? channelInfo?.team_id ?? undefined;
+    const channelName = payload.data?.channel_name ?? channelInfo?.name ?? "";
+    const channelDisplay =
+      payload.data?.channel_display_name ?? channelInfo?.display_name ?? channelName;
+    const roomLabel = channelName ? `#${channelName}` : channelDisplay || `#${channelId}`;
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "mattermost",
+      accountId: account.accountId,
+      teamId,
+      peer: {
+        kind,
+        id: kind === "dm" ? senderId : channelId,
+      },
+    });
+
+    const baseSessionKey = route.sessionKey;
+    const threadRootId = post.root_id?.trim() || undefined;
+    const threadKeys = resolveThreadSessionKeys({
+      baseSessionKey,
+      threadId: threadRootId,
+      parentSessionKey: threadRootId ? baseSessionKey : undefined,
+    });
+    const sessionKey = threadKeys.sessionKey;
+    const historyKey = kind === "dm" ? null : sessionKey;
+
+    const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg, route.agentId);
+    const rawText = post.message?.trim() || "";
+    const wasMentioned =
+      kind !== "dm" &&
+      ((botUsername ? rawText.toLowerCase().includes(`@${botUsername.toLowerCase()}`) : false) ||
+        core.channel.mentions.matchesMentionPatterns(rawText, mentionRegexes));
+    const pendingBody =
+      rawText ||
+      (post.file_ids?.length
+        ? `[Mattermost ${post.file_ids.length === 1 ? "file" : "files"}]`
+        : "");
+    const pendingSender = payload.data?.sender_name?.trim() || senderId;
+    const recordPendingHistory = () => {
+      if (!historyKey || historyLimit <= 0) return;
+      const trimmed = pendingBody.trim();
+      if (!trimmed) return;
+      recordPendingHistoryEntry({
+        historyMap: channelHistories,
+        historyKey,
+        limit: historyLimit,
+        entry: {
+          sender: pendingSender,
+          body: trimmed,
+          timestamp: typeof post.create_at === "number" ? post.create_at : undefined,
+          messageId: post.id ?? undefined,
+        },
+      });
+    };
+
+    const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+      cfg,
+      surface: "mattermost",
+    });
+    const isControlCommand = allowTextCommands && core.channel.text.hasControlCommand(rawText, cfg);
+    const oncharEnabled = account.chatmode === "onchar" && kind !== "dm";
+    const oncharPrefixes = oncharEnabled ? resolveOncharPrefixes(account.oncharPrefixes) : [];
+    const oncharResult = oncharEnabled
+      ? stripOncharPrefix(rawText, oncharPrefixes)
+      : { triggered: false, stripped: rawText };
+    const oncharTriggered = oncharResult.triggered;
+
+    const shouldRequireMention = kind === "channel" && (account.requireMention ?? true);
+    const shouldBypassMention = isControlCommand && shouldRequireMention && !wasMentioned;
+    const effectiveWasMentioned = wasMentioned || shouldBypassMention || oncharTriggered;
+    const canDetectMention = Boolean(botUsername) || mentionRegexes.length > 0;
+
+    if (oncharEnabled && !oncharTriggered && !wasMentioned && !isControlCommand) {
+      recordPendingHistory();
+      return;
+    }
+
+    if (kind === "channel" && shouldRequireMention && canDetectMention) {
+      if (!effectiveWasMentioned) {
+        recordPendingHistory();
+        return;
+      }
+    }
+
+    const senderName =
+      payload.data?.sender_name?.trim() ||
+      (await resolveUserInfo(senderId))?.username?.trim() ||
+      senderId;
+    const mediaList = await resolveMattermostMedia(post.file_ids);
+    const mediaPlaceholder = buildMattermostAttachmentPlaceholder(mediaList);
+    const bodySource = oncharTriggered ? oncharResult.stripped : rawText;
+    const baseText = [bodySource, mediaPlaceholder].filter(Boolean).join("\n").trim();
+    const bodyText = normalizeMention(baseText, botUsername);
+    if (!bodyText) return;
+
+    core.channel.activity.record({
+      channel: "mattermost",
+      accountId: account.accountId,
+      direction: "inbound",
+    });
+
+    const fromLabel = formatInboundFromLabel({
+      isGroup: kind !== "dm",
+      groupLabel: channelDisplay || roomLabel,
+      groupId: channelId,
+      groupFallback: roomLabel || "Channel",
+      directLabel: senderName,
+      directId: senderId,
+    });
+
+    const preview = bodyText.replace(/\s+/g, " ").slice(0, 160);
+    const inboundLabel =
+      kind === "dm"
+        ? `Mattermost DM from ${senderName}`
+        : `Mattermost message in ${roomLabel} from ${senderName}`;
+    core.system.enqueueSystemEvent(`${inboundLabel}: ${preview}`, {
+      sessionKey,
+      contextKey: `mattermost:message:${channelId}:${post.id ?? "unknown"}`,
+    });
+
+    const textWithId = `${bodyText}\n[mattermost message id: ${post.id ?? "unknown"} channel: ${channelId}]`;
+    const body = core.channel.reply.formatInboundEnvelope({
+      channel: "Mattermost",
+      from: fromLabel,
+      timestamp: typeof post.create_at === "number" ? post.create_at : undefined,
+      body: textWithId,
+      chatType,
+      sender: { name: senderName, id: senderId },
+    });
+    let combinedBody = body;
+    if (historyKey && historyLimit > 0) {
+      combinedBody = buildPendingHistoryContextFromMap({
+        historyMap: channelHistories,
+        historyKey,
+        limit: historyLimit,
+        currentMessage: combinedBody,
+        formatEntry: (entry) =>
+          core.channel.reply.formatInboundEnvelope({
+            channel: "Mattermost",
+            from: fromLabel,
+            timestamp: entry.timestamp,
+            body: `${entry.body}${
+              entry.messageId ? ` [id:${entry.messageId} channel:${channelId}]` : ""
+            }`,
+            chatType,
+            senderLabel: entry.sender,
+          }),
+      });
+    }
+
+    const to = kind === "dm" ? `user:${senderId}` : `channel:${channelId}`;
+    const mediaPayload = buildMattermostMediaPayload(mediaList);
+    const commandAuthorized = core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+      useAccessGroups: cfg.commands?.useAccessGroups ?? false,
+      authorizers: [],
+    });
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: combinedBody,
+      RawBody: bodyText,
+      CommandBody: bodyText,
+      From:
+        kind === "dm"
+          ? `mattermost:${senderId}`
+          : kind === "group"
+            ? `mattermost:group:${channelId}`
+            : `mattermost:channel:${channelId}`,
+      To: to,
+      SessionKey: sessionKey,
+      ParentSessionKey: threadKeys.parentSessionKey,
+      AccountId: route.accountId,
+      ChatType: chatType,
+      ConversationLabel: fromLabel,
+      GroupSubject: kind !== "dm" ? channelDisplay || roomLabel : undefined,
+      GroupChannel: channelName ? `#${channelName}` : undefined,
+      GroupSpace: teamId,
+      SenderName: senderName,
+      SenderId: senderId,
+      Provider: "mattermost" as const,
+      Surface: "mattermost" as const,
+      MessageSid: post.id ?? undefined,
+      MessageSids: allMessageIds.length > 1 ? allMessageIds : undefined,
+      MessageSidFirst: allMessageIds.length > 1 ? allMessageIds[0] : undefined,
+      MessageSidLast:
+        allMessageIds.length > 1 ? allMessageIds[allMessageIds.length - 1] : undefined,
+      ReplyToId: threadRootId,
+      MessageThreadId: threadRootId,
+      Timestamp: typeof post.create_at === "number" ? post.create_at : undefined,
+      WasMentioned: kind !== "dm" ? effectiveWasMentioned : undefined,
+      CommandAuthorized: commandAuthorized,
+      OriginatingChannel: "mattermost" as const,
+      OriginatingTo: to,
+      ...mediaPayload,
+    });
+
+    if (kind === "dm") {
+      const sessionCfg = cfg.session;
+      const storePath = core.channel.session.resolveStorePath(sessionCfg?.store, {
+        agentId: route.agentId,
+      });
+      await core.channel.session.updateLastRoute({
+        storePath,
+        sessionKey: route.mainSessionKey,
+        deliveryContext: {
+          channel: "mattermost",
+          to,
+          accountId: route.accountId,
+        },
+      });
+    }
+
+    const previewLine = bodyText.slice(0, 200).replace(/\n/g, "\\n");
+    logVerboseMessage(
+      `mattermost inbound: from=${ctxPayload.From} len=${bodyText.length} preview="${previewLine}"`,
+    );
+
+    const textLimit = core.channel.text.resolveTextChunkLimit(cfg, "mattermost", account.accountId, {
+      fallbackLimit: account.textChunkLimit ?? 4000,
+    });
+
+    let prefixContext: ResponsePrefixContext = {
+      identityName: resolveIdentityName(cfg, route.agentId),
+    };
+
+    const { dispatcher, replyOptions, markDispatchIdle } =
+      core.channel.reply.createReplyDispatcherWithTyping({
+        responsePrefix: core.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId)
+          .responsePrefix,
+        responsePrefixContextProvider: () => prefixContext,
+        humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
+        deliver: async (payload: ReplyPayload) => {
+          const mediaUrls = payload.mediaUrls ?? (payload.mediaUrl ? [payload.mediaUrl] : []);
+          const text = payload.text ?? "";
+          if (mediaUrls.length === 0) {
+            const chunks = core.channel.text.chunkMarkdownText(text, textLimit);
+            for (const chunk of chunks.length > 0 ? chunks : [text]) {
+              if (!chunk) continue;
+              await sendMessageMattermost(to, chunk, {
+                accountId: account.accountId,
+                replyToId: threadRootId,
+              });
+            }
+          } else {
+            let first = true;
+            for (const mediaUrl of mediaUrls) {
+              const caption = first ? text : "";
+              first = false;
+              await sendMessageMattermost(to, caption, {
+                accountId: account.accountId,
+                mediaUrl,
+                replyToId: threadRootId,
+              });
+            }
+          }
+          runtime.log?.(`delivered reply to ${to}`);
+        },
+        onError: (err, info) => {
+          runtime.error?.(`mattermost ${info.kind} reply failed: ${String(err)}`);
+        },
+        onReplyStart: () => sendTypingIndicator(channelId, threadRootId),
+      });
+
+    await core.channel.reply.dispatchReplyFromConfig({
+      ctx: ctxPayload,
+      cfg,
+      dispatcher,
+      replyOptions: {
+        ...replyOptions,
+        disableBlockStreaming:
+          typeof account.blockStreaming === "boolean" ? !account.blockStreaming : undefined,
+        onModelSelected: (ctx) => {
+          prefixContext.provider = ctx.provider;
+          prefixContext.model = extractShortModelName(ctx.model);
+          prefixContext.modelFull = `${ctx.provider}/${ctx.model}`;
+          prefixContext.thinkingLevel = ctx.thinkLevel ?? "off";
+        },
+      },
+    });
+    markDispatchIdle();
+    if (historyKey && historyLimit > 0) {
+      clearHistoryEntries({ historyMap: channelHistories, historyKey });
+    }
+  };
+
+  const inboundDebounceMs = core.channel.debounce.resolveInboundDebounceMs({
+    cfg,
+    channel: "mattermost",
+  });
+  const debouncer = core.channel.debounce.createInboundDebouncer<{
+    post: MattermostPost;
+    payload: MattermostEventPayload;
+  }>({
+    debounceMs: inboundDebounceMs,
+    buildKey: (entry) => {
+      const channelId =
+        entry.post.channel_id ??
+        entry.payload.data?.channel_id ??
+        entry.payload.broadcast?.channel_id;
+      if (!channelId) return null;
+      const threadId = entry.post.root_id?.trim();
+      const threadKey = threadId ? `thread:${threadId}` : "channel";
+      return `mattermost:${account.accountId}:${channelId}:${threadKey}`;
+    },
+    shouldDebounce: (entry) => {
+      if (entry.post.file_ids && entry.post.file_ids.length > 0) return false;
+      const text = entry.post.message?.trim() ?? "";
+      if (!text) return false;
+      return !core.channel.text.hasControlCommand(text, cfg);
+    },
+    onFlush: async (entries) => {
+      const last = entries.at(-1);
+      if (!last) return;
+      if (entries.length === 1) {
+        await handlePost(last.post, last.payload);
+        return;
+      }
+      const combinedText = entries
+        .map((entry) => entry.post.message?.trim() ?? "")
+        .filter(Boolean)
+        .join("\n");
+      const mergedPost: MattermostPost = {
+        ...last.post,
+        message: combinedText,
+        file_ids: [],
+      };
+      const ids = entries.map((entry) => entry.post.id).filter(Boolean) as string[];
+      await handlePost(mergedPost, last.payload, ids.length > 0 ? ids : undefined);
+    },
+    onError: (err) => {
+      runtime.error?.(`mattermost debounce flush failed: ${String(err)}`);
+    },
+  });
+
+  const wsUrl = buildMattermostWsUrl(baseUrl);
+  let seq = 1;
+
+  const connectOnce = async (): Promise<void> => {
+    const ws = new WebSocket(wsUrl);
+    const onAbort = () => ws.close();
+    opts.abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+    return await new Promise((resolve) => {
+      ws.on("open", () => {
+        opts.statusSink?.({
+          connected: true,
+          lastConnectedAt: Date.now(),
+          lastError: null,
+        });
+        ws.send(
+          JSON.stringify({
+            seq: seq++,
+            action: "authentication_challenge",
+            data: { token: botToken },
+          }),
+        );
+      });
+
+      ws.on("message", async (data) => {
+        const raw = rawDataToString(data);
+        let payload: MattermostEventPayload;
+        try {
+          payload = JSON.parse(raw) as MattermostEventPayload;
+        } catch {
+          return;
+        }
+        if (payload.event !== "posted") return;
+        const postData = payload.data?.post;
+        if (!postData) return;
+        let post: MattermostPost | null = null;
+        if (typeof postData === "string") {
+          try {
+            post = JSON.parse(postData) as MattermostPost;
+          } catch {
+            return;
+          }
+        } else if (typeof postData === "object") {
+          post = postData as MattermostPost;
+        }
+        if (!post) return;
+        try {
+          await debouncer.enqueue({ post, payload });
+        } catch (err) {
+          runtime.error?.(`mattermost handler failed: ${String(err)}`);
+        }
+      });
+
+      ws.on("close", (code, reason) => {
+        const message = reason.length > 0 ? reason.toString("utf8") : "";
+        opts.statusSink?.({
+          connected: false,
+          lastDisconnect: {
+            at: Date.now(),
+            status: code,
+            error: message || undefined,
+          },
+        });
+        opts.abortSignal?.removeEventListener("abort", onAbort);
+        resolve();
+      });
+
+      ws.on("error", (err) => {
+        runtime.error?.(`mattermost websocket error: ${String(err)}`);
+        opts.statusSink?.({
+          lastError: String(err),
+        });
+      });
+    });
+  };
+
+  while (!opts.abortSignal?.aborted) {
+    await connectOnce();
+    if (opts.abortSignal?.aborted) return;
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  }
+}

extensions/mattermost/src/mattermost/probe.ts

@@ -0,0 +1,70 @@
+import { normalizeMattermostBaseUrl, type MattermostUser } from "./client.js";
+
+export type MattermostProbe = {
+  ok: boolean;
+  status?: number | null;
+  error?: string | null;
+  elapsedMs?: number | null;
+  bot?: MattermostUser;
+};
+
+async function readMattermostError(res: Response): Promise<string> {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const data = (await res.json()) as { message?: string } | undefined;
+    if (data?.message) return data.message;
+    return JSON.stringify(data);
+  }
+  return await res.text();
+}
+
+export async function probeMattermost(
+  baseUrl: string,
+  botToken: string,
+  timeoutMs = 2500,
+): Promise<MattermostProbe> {
+  const normalized = normalizeMattermostBaseUrl(baseUrl);
+  if (!normalized) {
+    return { ok: false, error: "baseUrl missing" };
+  }
+  const url = `${normalized}/api/v4/users/me`;
+  const start = Date.now();
+  const controller = timeoutMs > 0 ? new AbortController() : undefined;
+  let timer: NodeJS.Timeout | null = null;
+  if (controller) {
+    timer = setTimeout(() => controller.abort(), timeoutMs);
+  }
+  try {
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${botToken}` },
+      signal: controller?.signal,
+    });
+    const elapsedMs = Date.now() - start;
+    if (!res.ok) {
+      const detail = await readMattermostError(res);
+      return {
+        ok: false,
+        status: res.status,
+        error: detail || res.statusText,
+        elapsedMs,
+      };
+    }
+    const bot = (await res.json()) as MattermostUser;
+    return {
+      ok: true,
+      status: res.status,
+      elapsedMs,
+      bot,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      status: null,
+      error: message,
+      elapsedMs: Date.now() - start,
+    };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

extensions/mattermost/src/mattermost/send.ts

@@ -0,0 +1,208 @@
+import { getMattermostRuntime } from "../runtime.js";
+import { resolveMattermostAccount } from "./accounts.js";
+import {
+  createMattermostClient,
+  createMattermostDirectChannel,
+  createMattermostPost,
+  fetchMattermostMe,
+  fetchMattermostUserByUsername,
+  normalizeMattermostBaseUrl,
+  uploadMattermostFile,
+  type MattermostUser,
+} from "./client.js";
+
+export type MattermostSendOpts = {
+  botToken?: string;
+  baseUrl?: string;
+  accountId?: string;
+  mediaUrl?: string;
+  replyToId?: string;
+};
+
+export type MattermostSendResult = {
+  messageId: string;
+  channelId: string;
+};
+
+type MattermostTarget =
+  | { kind: "channel"; id: string }
+  | { kind: "user"; id?: string; username?: string };
+
+const botUserCache = new Map<string, MattermostUser>();
+const userByNameCache = new Map<string, MattermostUser>();
+
+const getCore = () => getMattermostRuntime();
+
+function cacheKey(baseUrl: string, token: string): string {
+  return `${baseUrl}::${token}`;
+}
+
+function normalizeMessage(text: string, mediaUrl?: string): string {
+  const trimmed = text.trim();
+  const media = mediaUrl?.trim();
+  return [trimmed, media].filter(Boolean).join("\n");
+}
+
+function isHttpUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function parseMattermostTarget(raw: string): MattermostTarget {
+  const trimmed = raw.trim();
+  if (!trimmed) throw new Error("Recipient is required for Mattermost sends");
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith("channel:")) {
+    const id = trimmed.slice("channel:".length).trim();
+    if (!id) throw new Error("Channel id is required for Mattermost sends");
+    return { kind: "channel", id };
+  }
+  if (lower.startsWith("user:")) {
+    const id = trimmed.slice("user:".length).trim();
+    if (!id) throw new Error("User id is required for Mattermost sends");
+    return { kind: "user", id };
+  }
+  if (lower.startsWith("mattermost:")) {
+    const id = trimmed.slice("mattermost:".length).trim();
+    if (!id) throw new Error("User id is required for Mattermost sends");
+    return { kind: "user", id };
+  }
+  if (trimmed.startsWith("@")) {
+    const username = trimmed.slice(1).trim();
+    if (!username) {
+      throw new Error("Username is required for Mattermost sends");
+    }
+    return { kind: "user", username };
+  }
+  return { kind: "channel", id: trimmed };
+}
+
+async function resolveBotUser(baseUrl: string, token: string): Promise<MattermostUser> {
+  const key = cacheKey(baseUrl, token);
+  const cached = botUserCache.get(key);
+  if (cached) return cached;
+  const client = createMattermostClient({ baseUrl, botToken: token });
+  const user = await fetchMattermostMe(client);
+  botUserCache.set(key, user);
+  return user;
+}
+
+async function resolveUserIdByUsername(params: {
+  baseUrl: string;
+  token: string;
+  username: string;
+}): Promise<string> {
+  const { baseUrl, token, username } = params;
+  const key = `${cacheKey(baseUrl, token)}::${username.toLowerCase()}`;
+  const cached = userByNameCache.get(key);
+  if (cached?.id) return cached.id;
+  const client = createMattermostClient({ baseUrl, botToken: token });
+  const user = await fetchMattermostUserByUsername(client, username);
+  userByNameCache.set(key, user);
+  return user.id;
+}
+
+async function resolveTargetChannelId(params: {
+  target: MattermostTarget;
+  baseUrl: string;
+  token: string;
+}): Promise<string> {
+  if (params.target.kind === "channel") return params.target.id;
+  const userId = params.target.id
+    ? params.target.id
+    : await resolveUserIdByUsername({
+        baseUrl: params.baseUrl,
+        token: params.token,
+        username: params.target.username ?? "",
+      });
+  const botUser = await resolveBotUser(params.baseUrl, params.token);
+  const client = createMattermostClient({
+    baseUrl: params.baseUrl,
+    botToken: params.token,
+  });
+  const channel = await createMattermostDirectChannel(client, [botUser.id, userId]);
+  return channel.id;
+}
+
+export async function sendMessageMattermost(
+  to: string,
+  text: string,
+  opts: MattermostSendOpts = {},
+): Promise<MattermostSendResult> {
+  const core = getCore();
+  const logger = core.logging.getChildLogger({ module: "mattermost" });
+  const cfg = core.config.loadConfig();
+  const account = resolveMattermostAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const token = opts.botToken?.trim() || account.botToken?.trim();
+  if (!token) {
+    throw new Error(
+      `Mattermost bot token missing for account "${account.accountId}" (set channels.mattermost.accounts.${account.accountId}.botToken or MATTERMOST_BOT_TOKEN for default).`,
+    );
+  }
+  const baseUrl = normalizeMattermostBaseUrl(opts.baseUrl ?? account.baseUrl);
+  if (!baseUrl) {
+    throw new Error(
+      `Mattermost baseUrl missing for account "${account.accountId}" (set channels.mattermost.accounts.${account.accountId}.baseUrl or MATTERMOST_URL for default).`,
+    );
+  }
+
+  const target = parseMattermostTarget(to);
+  const channelId = await resolveTargetChannelId({
+    target,
+    baseUrl,
+    token,
+  });
+
+  const client = createMattermostClient({ baseUrl, botToken: token });
+  let message = text?.trim() ?? "";
+  let fileIds: string[] | undefined;
+  let uploadError: Error | undefined;
+  const mediaUrl = opts.mediaUrl?.trim();
+  if (mediaUrl) {
+    try {
+      const media = await core.media.loadWebMedia(mediaUrl);
+      const fileInfo = await uploadMattermostFile(client, {
+        channelId,
+        buffer: media.buffer,
+        fileName: media.fileName ?? "upload",
+        contentType: media.contentType ?? undefined,
+      });
+      fileIds = [fileInfo.id];
+    } catch (err) {
+      uploadError = err instanceof Error ? err : new Error(String(err));
+      if (core.logging.shouldLogVerbose()) {
+        logger.debug?.(
+          `mattermost send: media upload failed, falling back to URL text: ${String(err)}`,
+        );
+      }
+      message = normalizeMessage(message, isHttpUrl(mediaUrl) ? mediaUrl : "");
+    }
+  }
+
+  if (!message && (!fileIds || fileIds.length === 0)) {
+    if (uploadError) {
+      throw new Error(`Mattermost media upload failed: ${uploadError.message}`);
+    }
+    throw new Error("Mattermost message is empty");
+  }
+
+  const post = await createMattermostPost(client, {
+    channelId,
+    message,
+    rootId: opts.replyToId,
+    fileIds,
+  });
+
+  core.channel.activity.record({
+    channel: "mattermost",
+    accountId: account.accountId,
+    direction: "outbound",
+  });
+
+  return {
+    messageId: post.id ?? "unknown",
+    channelId,
+  };
+}

extensions/mattermost/src/normalize.ts

@@ -0,0 +1,38 @@
+export function normalizeMattermostMessagingTarget(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith("channel:")) {
+    const id = trimmed.slice("channel:".length).trim();
+    return id ? `channel:${id}` : undefined;
+  }
+  if (lower.startsWith("group:")) {
+    const id = trimmed.slice("group:".length).trim();
+    return id ? `channel:${id}` : undefined;
+  }
+  if (lower.startsWith("user:")) {
+    const id = trimmed.slice("user:".length).trim();
+    return id ? `user:${id}` : undefined;
+  }
+  if (lower.startsWith("mattermost:")) {
+    const id = trimmed.slice("mattermost:".length).trim();
+    return id ? `user:${id}` : undefined;
+  }
+  if (trimmed.startsWith("@")) {
+    const id = trimmed.slice(1).trim();
+    return id ? `user:${id}` : undefined;
+  }
+  if (trimmed.startsWith("#")) {
+    const id = trimmed.slice(1).trim();
+    return id ? `channel:${id}` : undefined;
+  }
+  return `channel:${trimmed}`;
+}
+
+export function looksLikeMattermostTargetId(raw: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed) return false;
+  if (/^(user|channel|group|mattermost):/i.test(trimmed)) return true;
+  if (/^[@#]/.test(trimmed)) return true;
+  return /^[a-z0-9]{8,}$/i.test(trimmed);
+}

extensions/mattermost/src/onboarding-helpers.ts

@@ -0,0 +1,42 @@
+import type { ClawdbotConfig, WizardPrompter } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+type PromptAccountIdParams = {
+  cfg: ClawdbotConfig;
+  prompter: WizardPrompter;
+  label: string;
+  currentId?: string;
+  listAccountIds: (cfg: ClawdbotConfig) => string[];
+  defaultAccountId: string;
+};
+
+export async function promptAccountId(params: PromptAccountIdParams): Promise<string> {
+  const existingIds = params.listAccountIds(params.cfg);
+  const initial = params.currentId?.trim() || params.defaultAccountId || DEFAULT_ACCOUNT_ID;
+  const choice = (await params.prompter.select({
+    message: `${params.label} account`,
+    options: [
+      ...existingIds.map((id) => ({
+        value: id,
+        label: id === DEFAULT_ACCOUNT_ID ? "default (primary)" : id,
+      })),
+      { value: "__new__", label: "Add a new account" },
+    ],
+    initialValue: initial,
+  })) as string;
+
+  if (choice !== "__new__") return normalizeAccountId(choice);
+
+  const entered = await params.prompter.text({
+    message: `New ${params.label} account id`,
+    validate: (value) => (value?.trim() ? undefined : "Required"),
+  });
+  const normalized = normalizeAccountId(String(entered));
+  if (String(entered).trim() !== normalized) {
+    await params.prompter.note(
+      `Normalized account id to "${normalized}".`,
+      `${params.label} account`,
+    );
+  }
+  return normalized;
+}

extensions/mattermost/src/onboarding.ts

@@ -0,0 +1,187 @@
+import type { ChannelOnboardingAdapter, ClawdbotConfig, WizardPrompter } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+import {
+  listMattermostAccountIds,
+  resolveDefaultMattermostAccountId,
+  resolveMattermostAccount,
+} from "./mattermost/accounts.js";
+import { promptAccountId } from "./onboarding-helpers.js";
+
+const channel = "mattermost" as const;
+
+async function noteMattermostSetup(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "1) Mattermost System Console -> Integrations -> Bot Accounts",
+      "2) Create a bot + copy its token",
+      "3) Use your server base URL (e.g., https://chat.example.com)",
+      "Tip: the bot must be a member of any channel you want it to monitor.",
+      "Docs: https://docs.clawd.bot/channels/mattermost",
+    ].join("\n"),
+    "Mattermost bot token",
+  );
+}
+
+export const mattermostOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const configured = listMattermostAccountIds(cfg).some((accountId) => {
+      const account = resolveMattermostAccount({ cfg, accountId });
+      return Boolean(account.botToken && account.baseUrl);
+    });
+    return {
+      channel,
+      configured,
+      statusLines: [`Mattermost: ${configured ? "configured" : "needs token + url"}`],
+      selectionHint: configured ? "configured" : "needs setup",
+      quickstartScore: configured ? 2 : 1,
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides, shouldPromptAccountIds }) => {
+    const override = accountOverrides.mattermost?.trim();
+    const defaultAccountId = resolveDefaultMattermostAccountId(cfg);
+    let accountId = override ? normalizeAccountId(override) : defaultAccountId;
+    if (shouldPromptAccountIds && !override) {
+      accountId = await promptAccountId({
+        cfg,
+        prompter,
+        label: "Mattermost",
+        currentId: accountId,
+        listAccountIds: listMattermostAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg;
+    const resolvedAccount = resolveMattermostAccount({
+      cfg: next,
+      accountId,
+    });
+    const accountConfigured = Boolean(resolvedAccount.botToken && resolvedAccount.baseUrl);
+    const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+    const canUseEnv =
+      allowEnv &&
+      Boolean(process.env.MATTERMOST_BOT_TOKEN?.trim()) &&
+      Boolean(process.env.MATTERMOST_URL?.trim());
+    const hasConfigValues =
+      Boolean(resolvedAccount.config.botToken) || Boolean(resolvedAccount.config.baseUrl);
+
+    let botToken: string | null = null;
+    let baseUrl: string | null = null;
+
+    if (!accountConfigured) {
+      await noteMattermostSetup(prompter);
+    }
+
+    if (canUseEnv && !hasConfigValues) {
+      const keepEnv = await prompter.confirm({
+        message: "MATTERMOST_BOT_TOKEN + MATTERMOST_URL detected. Use env vars?",
+        initialValue: true,
+      });
+      if (keepEnv) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            mattermost: {
+              ...next.channels?.mattermost,
+              enabled: true,
+            },
+          },
+        };
+      } else {
+        botToken = String(
+          await prompter.text({
+            message: "Enter Mattermost bot token",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+        baseUrl = String(
+          await prompter.text({
+            message: "Enter Mattermost base URL",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
+    } else if (accountConfigured) {
+      const keep = await prompter.confirm({
+        message: "Mattermost credentials already configured. Keep them?",
+        initialValue: true,
+      });
+      if (!keep) {
+        botToken = String(
+          await prompter.text({
+            message: "Enter Mattermost bot token",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+        baseUrl = String(
+          await prompter.text({
+            message: "Enter Mattermost base URL",
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
+    } else {
+      botToken = String(
+        await prompter.text({
+          message: "Enter Mattermost bot token",
+          validate: (value) => (value?.trim() ? undefined : "Required"),
+        }),
+      ).trim();
+      baseUrl = String(
+        await prompter.text({
+          message: "Enter Mattermost base URL",
+          validate: (value) => (value?.trim() ? undefined : "Required"),
+        }),
+      ).trim();
+    }
+
+    if (botToken || baseUrl) {
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            mattermost: {
+              ...next.channels?.mattermost,
+              enabled: true,
+              ...(botToken ? { botToken } : {}),
+              ...(baseUrl ? { baseUrl } : {}),
+            },
+          },
+        };
+      } else {
+        next = {
+          ...next,
+          channels: {
+            ...next.channels,
+            mattermost: {
+              ...next.channels?.mattermost,
+              enabled: true,
+              accounts: {
+                ...next.channels?.mattermost?.accounts,
+                [accountId]: {
+                  ...next.channels?.mattermost?.accounts?.[accountId],
+                  enabled: next.channels?.mattermost?.accounts?.[accountId]?.enabled ?? true,
+                  ...(botToken ? { botToken } : {}),
+                  ...(baseUrl ? { baseUrl } : {}),
+                },
+              },
+            },
+          },
+        };
+      }
+    }
+
+    return { cfg: next, accountId };
+  },
+  disable: (cfg: ClawdbotConfig) => ({
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      mattermost: { ...cfg.channels?.mattermost, enabled: false },
+    },
+  }),
+};

extensions/mattermost/src/types.ts

@@ -0,0 +1,40 @@
+import type { BlockStreamingCoalesceConfig } from "clawdbot/plugin-sdk";
+
+export type MattermostChatMode = "oncall" | "onmessage" | "onchar";
+
+export type MattermostAccountConfig = {
+  /** Optional display name for this account (used in CLI/UI lists). */
+  name?: string;
+  /** Optional provider capability tags used for agent/runtime guidance. */
+  capabilities?: string[];
+  /** Allow channel-initiated config writes (default: true). */
+  configWrites?: boolean;
+  /** If false, do not start this Mattermost account. Default: true. */
+  enabled?: boolean;
+  /** Bot token for Mattermost. */
+  botToken?: string;
+  /** Base URL for the Mattermost server (e.g., https://chat.example.com). */
+  baseUrl?: string;
+  /**
+   * Controls when channel messages trigger replies.
+   * - "oncall": only respond when mentioned
+   * - "onmessage": respond to every channel message
+   * - "onchar": respond when a trigger character prefixes the message
+   */
+  chatmode?: MattermostChatMode;
+  /** Prefix characters that trigger onchar mode (default: [">", "!"]). */
+  oncharPrefixes?: string[];
+  /** Require @mention to respond in channels. Default: true. */
+  requireMention?: boolean;
+  /** Outbound text chunk size (chars). Default: 4000. */
+  textChunkLimit?: number;
+  /** Disable block streaming for this account. */
+  blockStreaming?: boolean;
+  /** Merge streamed block replies before sending. */
+  blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+};
+
+export type MattermostConfig = {
+  /** Optional per-account Mattermost configuration (multi-account). */
+  accounts?: Record<string, MattermostAccountConfig>;
+} & MattermostAccountConfig;