@openclaw/msteams 2026.1.29

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 2026.1.29
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.23
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.22
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.21
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.20
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.17-1
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.17
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.16
+
+### Changes
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.15
+
+### Features
+- Bot Framework gateway monitor (Express + JWT auth) with configurable webhook path/port and `/api/messages` fallback.
+- Onboarding flow for Azure Bot credentials (config + env var detection) and DM policy setup.
+- Channel capabilities: DMs, group chats, channels, threads, media, polls, and `teams` alias.
+- DM pairing/allowlist enforcement plus group policies with per-team/channel overrides and mention gating.
+- Inbound debounce + history context for room/group chats; mention tag stripping and timestamp parsing.
+- Proactive messaging via stored conversation references (file store with TTL/size pruning).
+- Outbound text/media send with markdown chunking, 4k limit, split/inline media handling.
+- Adaptive Card polls: build cards, parse votes, and persist poll state with vote tracking.
+- Attachment processing: placeholders + HTML summaries, inline image extraction (including data: URLs).
+- Media downloads with host allowlist, auth scope fallback, and Graph hostedContents/attachments fallback.
+- Retry/backoff on transient/throttled sends with classified errors + helpful hints.

package/index.ts

@@ -0,0 +1,18 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+
+import { msteamsPlugin } from "./src/channel.js";
+import { setMSTeamsRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "msteams",
+  name: "Microsoft Teams",
+  description: "Microsoft Teams channel plugin (Bot Framework)",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setMSTeamsRuntime(api.runtime);
+    api.registerChannel({ plugin: msteamsPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "msteams",
+  "channels": [
+    "msteams"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@openclaw/msteams",
+  "version": "2026.1.29",
+  "type": "module",
+  "description": "OpenClaw Microsoft Teams channel plugin",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "msteams",
+      "label": "Microsoft Teams",
+      "selectionLabel": "Microsoft Teams (Bot Framework)",
+      "docsPath": "/channels/msteams",
+      "docsLabel": "msteams",
+      "blurb": "Bot Framework; enterprise support.",
+      "aliases": [
+        "teams"
+      ],
+      "order": 60
+    },
+    "install": {
+      "npmSpec": "@openclaw/msteams",
+      "localPath": "extensions/msteams",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "@microsoft/agents-hosting": "^1.2.2",
+    "@microsoft/agents-hosting-express": "^1.2.2",
+    "@microsoft/agents-hosting-extensions-teams": "^1.2.2",
+    "openclaw": "workspace:*",
+    "express": "^5.2.1",
+    "proper-lockfile": "^4.1.2"
+  }
+}

package/src/attachments/download.ts

@@ -0,0 +1,206 @@
+import { getMSTeamsRuntime } from "../runtime.js";
+import {
+  extractInlineImageCandidates,
+  inferPlaceholder,
+  isDownloadableAttachment,
+  isRecord,
+  isUrlAllowed,
+  normalizeContentType,
+  resolveAllowedHosts,
+} from "./shared.js";
+import type {
+  MSTeamsAccessTokenProvider,
+  MSTeamsAttachmentLike,
+  MSTeamsInboundMedia,
+} from "./types.js";
+
+type DownloadCandidate = {
+  url: string;
+  fileHint?: string;
+  contentTypeHint?: string;
+  placeholder: string;
+};
+
+function resolveDownloadCandidate(att: MSTeamsAttachmentLike): DownloadCandidate | null {
+  const contentType = normalizeContentType(att.contentType);
+  const name = typeof att.name === "string" ? att.name.trim() : "";
+
+  if (contentType === "application/vnd.microsoft.teams.file.download.info") {
+    if (!isRecord(att.content)) return null;
+    const downloadUrl =
+      typeof att.content.downloadUrl === "string" ? att.content.downloadUrl.trim() : "";
+    if (!downloadUrl) return null;
+
+    const fileType = typeof att.content.fileType === "string" ? att.content.fileType.trim() : "";
+    const uniqueId = typeof att.content.uniqueId === "string" ? att.content.uniqueId.trim() : "";
+    const fileName = typeof att.content.fileName === "string" ? att.content.fileName.trim() : "";
+
+    const fileHint = name || fileName || (uniqueId && fileType ? `${uniqueId}.${fileType}` : "");
+    return {
+      url: downloadUrl,
+      fileHint: fileHint || undefined,
+      contentTypeHint: undefined,
+      placeholder: inferPlaceholder({
+        contentType,
+        fileName: fileHint,
+        fileType,
+      }),
+    };
+  }
+
+  const contentUrl = typeof att.contentUrl === "string" ? att.contentUrl.trim() : "";
+  if (!contentUrl) return null;
+
+  return {
+    url: contentUrl,
+    fileHint: name || undefined,
+    contentTypeHint: contentType,
+    placeholder: inferPlaceholder({ contentType, fileName: name }),
+  };
+}
+
+function scopeCandidatesForUrl(url: string): string[] {
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    const looksLikeGraph =
+      host.endsWith("graph.microsoft.com") ||
+      host.endsWith("sharepoint.com") ||
+      host.endsWith("1drv.ms") ||
+      host.includes("sharepoint");
+    return looksLikeGraph
+      ? ["https://graph.microsoft.com", "https://api.botframework.com"]
+      : ["https://api.botframework.com", "https://graph.microsoft.com"];
+  } catch {
+    return ["https://api.botframework.com", "https://graph.microsoft.com"];
+  }
+}
+
+async function fetchWithAuthFallback(params: {
+  url: string;
+  tokenProvider?: MSTeamsAccessTokenProvider;
+  fetchFn?: typeof fetch;
+}): Promise<Response> {
+  const fetchFn = params.fetchFn ?? fetch;
+  const firstAttempt = await fetchFn(params.url);
+  if (firstAttempt.ok) return firstAttempt;
+  if (!params.tokenProvider) return firstAttempt;
+  if (firstAttempt.status !== 401 && firstAttempt.status !== 403) return firstAttempt;
+
+  const scopes = scopeCandidatesForUrl(params.url);
+  for (const scope of scopes) {
+    try {
+      const token = await params.tokenProvider.getAccessToken(scope);
+      const res = await fetchFn(params.url, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (res.ok) return res;
+    } catch {
+      // Try the next scope.
+    }
+  }
+
+  return firstAttempt;
+}
+
+/**
+ * Download all file attachments from a Teams message (images, documents, etc.).
+ * Renamed from downloadMSTeamsImageAttachments to support all file types.
+ */
+export async function downloadMSTeamsAttachments(params: {
+  attachments: MSTeamsAttachmentLike[] | undefined;
+  maxBytes: number;
+  tokenProvider?: MSTeamsAccessTokenProvider;
+  allowHosts?: string[];
+  fetchFn?: typeof fetch;
+  /** When true, embeds original filename in stored path for later extraction. */
+  preserveFilenames?: boolean;
+}): Promise<MSTeamsInboundMedia[]> {
+  const list = Array.isArray(params.attachments) ? params.attachments : [];
+  if (list.length === 0) return [];
+  const allowHosts = resolveAllowedHosts(params.allowHosts);
+
+  // Download ANY downloadable attachment (not just images)
+  const downloadable = list.filter(isDownloadableAttachment);
+  const candidates: DownloadCandidate[] = downloadable
+    .map(resolveDownloadCandidate)
+    .filter(Boolean) as DownloadCandidate[];
+
+  const inlineCandidates = extractInlineImageCandidates(list);
+
+  const seenUrls = new Set<string>();
+  for (const inline of inlineCandidates) {
+    if (inline.kind === "url") {
+      if (!isUrlAllowed(inline.url, allowHosts)) continue;
+      if (seenUrls.has(inline.url)) continue;
+      seenUrls.add(inline.url);
+      candidates.push({
+        url: inline.url,
+        fileHint: inline.fileHint,
+        contentTypeHint: inline.contentType,
+        placeholder: inline.placeholder,
+      });
+    }
+  }
+  if (candidates.length === 0 && inlineCandidates.length === 0) return [];
+
+  const out: MSTeamsInboundMedia[] = [];
+  for (const inline of inlineCandidates) {
+    if (inline.kind !== "data") continue;
+    if (inline.data.byteLength > params.maxBytes) continue;
+    try {
+      // Data inline candidates (base64 data URLs) don't have original filenames
+      const saved = await getMSTeamsRuntime().channel.media.saveMediaBuffer(
+        inline.data,
+        inline.contentType,
+        "inbound",
+        params.maxBytes,
+      );
+      out.push({
+        path: saved.path,
+        contentType: saved.contentType,
+        placeholder: inline.placeholder,
+      });
+    } catch {
+      // Ignore decode failures and continue.
+    }
+  }
+  for (const candidate of candidates) {
+    if (!isUrlAllowed(candidate.url, allowHosts)) continue;
+    try {
+      const res = await fetchWithAuthFallback({
+        url: candidate.url,
+        tokenProvider: params.tokenProvider,
+        fetchFn: params.fetchFn,
+      });
+      if (!res.ok) continue;
+      const buffer = Buffer.from(await res.arrayBuffer());
+      if (buffer.byteLength > params.maxBytes) continue;
+      const mime = await getMSTeamsRuntime().media.detectMime({
+        buffer,
+        headerMime: res.headers.get("content-type"),
+        filePath: candidate.fileHint ?? candidate.url,
+      });
+      const originalFilename = params.preserveFilenames ? candidate.fileHint : undefined;
+      const saved = await getMSTeamsRuntime().channel.media.saveMediaBuffer(
+        buffer,
+        mime ?? candidate.contentTypeHint,
+        "inbound",
+        params.maxBytes,
+        originalFilename,
+      );
+      out.push({
+        path: saved.path,
+        contentType: saved.contentType,
+        placeholder: candidate.placeholder,
+      });
+    } catch {
+      // Ignore download failures and continue with next candidate.
+    }
+  }
+  return out;
+}
+
+/**
+ * @deprecated Use `downloadMSTeamsAttachments` instead (supports all file types).
+ */
+export const downloadMSTeamsImageAttachments = downloadMSTeamsAttachments;

package/src/attachments/graph.ts

@@ -0,0 +1,319 @@
+import { getMSTeamsRuntime } from "../runtime.js";
+import { downloadMSTeamsAttachments } from "./download.js";
+import { GRAPH_ROOT, inferPlaceholder, isRecord, normalizeContentType, resolveAllowedHosts } from "./shared.js";
+import type {
+  MSTeamsAccessTokenProvider,
+  MSTeamsAttachmentLike,
+  MSTeamsGraphMediaResult,
+  MSTeamsInboundMedia,
+} from "./types.js";
+
+type GraphHostedContent = {
+  id?: string | null;
+  contentType?: string | null;
+  contentBytes?: string | null;
+};
+
+type GraphAttachment = {
+  id?: string | null;
+  contentType?: string | null;
+  contentUrl?: string | null;
+  name?: string | null;
+  thumbnailUrl?: string | null;
+  content?: unknown;
+};
+
+function readNestedString(value: unknown, keys: Array<string | number>): string | undefined {
+  let current: unknown = value;
+  for (const key of keys) {
+    if (!isRecord(current)) return undefined;
+    current = current[key as keyof typeof current];
+  }
+  return typeof current === "string" && current.trim() ? current.trim() : undefined;
+}
+
+export function buildMSTeamsGraphMessageUrls(params: {
+  conversationType?: string | null;
+  conversationId?: string | null;
+  messageId?: string | null;
+  replyToId?: string | null;
+  conversationMessageId?: string | null;
+  channelData?: unknown;
+}): string[] {
+  const conversationType = params.conversationType?.trim().toLowerCase() ?? "";
+  const messageIdCandidates = new Set<string>();
+  const pushCandidate = (value: string | null | undefined) => {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    if (trimmed) messageIdCandidates.add(trimmed);
+  };
+
+  pushCandidate(params.messageId);
+  pushCandidate(params.conversationMessageId);
+  pushCandidate(readNestedString(params.channelData, ["messageId"]));
+  pushCandidate(readNestedString(params.channelData, ["teamsMessageId"]));
+
+  const replyToId = typeof params.replyToId === "string" ? params.replyToId.trim() : "";
+
+  if (conversationType === "channel") {
+    const teamId =
+      readNestedString(params.channelData, ["team", "id"]) ??
+      readNestedString(params.channelData, ["teamId"]);
+    const channelId =
+      readNestedString(params.channelData, ["channel", "id"]) ??
+      readNestedString(params.channelData, ["channelId"]) ??
+      readNestedString(params.channelData, ["teamsChannelId"]);
+    if (!teamId || !channelId) return [];
+    const urls: string[] = [];
+    if (replyToId) {
+      for (const candidate of messageIdCandidates) {
+        if (candidate === replyToId) continue;
+        urls.push(
+          `${GRAPH_ROOT}/teams/${encodeURIComponent(teamId)}/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(replyToId)}/replies/${encodeURIComponent(candidate)}`,
+        );
+      }
+    }
+    if (messageIdCandidates.size === 0 && replyToId) messageIdCandidates.add(replyToId);
+    for (const candidate of messageIdCandidates) {
+      urls.push(
+        `${GRAPH_ROOT}/teams/${encodeURIComponent(teamId)}/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(candidate)}`,
+      );
+    }
+    return Array.from(new Set(urls));
+  }
+
+  const chatId = params.conversationId?.trim() || readNestedString(params.channelData, ["chatId"]);
+  if (!chatId) return [];
+  if (messageIdCandidates.size === 0 && replyToId) messageIdCandidates.add(replyToId);
+  const urls = Array.from(messageIdCandidates).map(
+    (candidate) =>
+      `${GRAPH_ROOT}/chats/${encodeURIComponent(chatId)}/messages/${encodeURIComponent(candidate)}`,
+  );
+  return Array.from(new Set(urls));
+}
+
+async function fetchGraphCollection<T>(params: {
+  url: string;
+  accessToken: string;
+  fetchFn?: typeof fetch;
+}): Promise<{ status: number; items: T[] }> {
+  const fetchFn = params.fetchFn ?? fetch;
+  const res = await fetchFn(params.url, {
+    headers: { Authorization: `Bearer ${params.accessToken}` },
+  });
+  const status = res.status;
+  if (!res.ok) return { status, items: [] };
+  try {
+    const data = (await res.json()) as { value?: T[] };
+    return { status, items: Array.isArray(data.value) ? data.value : [] };
+  } catch {
+    return { status, items: [] };
+  }
+}
+
+function normalizeGraphAttachment(att: GraphAttachment): MSTeamsAttachmentLike {
+  let content: unknown = att.content;
+  if (typeof content === "string") {
+    try {
+      content = JSON.parse(content);
+    } catch {
+      // Keep as raw string if it's not JSON.
+    }
+  }
+  return {
+    contentType: normalizeContentType(att.contentType) ?? undefined,
+    contentUrl: att.contentUrl ?? undefined,
+    name: att.name ?? undefined,
+    thumbnailUrl: att.thumbnailUrl ?? undefined,
+    content,
+  };
+}
+
+/**
+ * Download all hosted content from a Teams message (images, documents, etc.).
+ * Renamed from downloadGraphHostedImages to support all file types.
+ */
+async function downloadGraphHostedContent(params: {
+  accessToken: string;
+  messageUrl: string;
+  maxBytes: number;
+  fetchFn?: typeof fetch;
+  preserveFilenames?: boolean;
+}): Promise<{ media: MSTeamsInboundMedia[]; status: number; count: number }> {
+  const hosted = await fetchGraphCollection<GraphHostedContent>({
+    url: `${params.messageUrl}/hostedContents`,
+    accessToken: params.accessToken,
+    fetchFn: params.fetchFn,
+  });
+  if (hosted.items.length === 0) {
+    return { media: [], status: hosted.status, count: 0 };
+  }
+
+  const out: MSTeamsInboundMedia[] = [];
+  for (const item of hosted.items) {
+    const contentBytes = typeof item.contentBytes === "string" ? item.contentBytes : "";
+    if (!contentBytes) continue;
+    let buffer: Buffer;
+    try {
+      buffer = Buffer.from(contentBytes, "base64");
+    } catch {
+      continue;
+    }
+    if (buffer.byteLength > params.maxBytes) continue;
+    const mime = await getMSTeamsRuntime().media.detectMime({
+      buffer,
+      headerMime: item.contentType ?? undefined,
+    });
+    // Download any file type, not just images
+    try {
+      const saved = await getMSTeamsRuntime().channel.media.saveMediaBuffer(
+        buffer,
+        mime ?? item.contentType ?? undefined,
+        "inbound",
+        params.maxBytes,
+      );
+      out.push({
+        path: saved.path,
+        contentType: saved.contentType,
+        placeholder: inferPlaceholder({ contentType: saved.contentType }),
+      });
+    } catch {
+      // Ignore save failures.
+    }
+  }
+
+  return { media: out, status: hosted.status, count: hosted.items.length };
+}
+
+export async function downloadMSTeamsGraphMedia(params: {
+  messageUrl?: string | null;
+  tokenProvider?: MSTeamsAccessTokenProvider;
+  maxBytes: number;
+  allowHosts?: string[];
+  fetchFn?: typeof fetch;
+  /** When true, embeds original filename in stored path for later extraction. */
+  preserveFilenames?: boolean;
+}): Promise<MSTeamsGraphMediaResult> {
+  if (!params.messageUrl || !params.tokenProvider) return { media: [] };
+  const allowHosts = resolveAllowedHosts(params.allowHosts);
+  const messageUrl = params.messageUrl;
+  let accessToken: string;
+  try {
+    accessToken = await params.tokenProvider.getAccessToken("https://graph.microsoft.com");
+  } catch {
+    return { media: [], messageUrl, tokenError: true };
+  }
+
+  // Fetch the full message to get SharePoint file attachments (for group chats)
+  const fetchFn = params.fetchFn ?? fetch;
+  const sharePointMedia: MSTeamsInboundMedia[] = [];
+  const downloadedReferenceUrls = new Set<string>();
+  try {
+    const msgRes = await fetchFn(messageUrl, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (msgRes.ok) {
+      const msgData = (await msgRes.json()) as {
+        body?: { content?: string; contentType?: string };
+        attachments?: Array<{
+          id?: string;
+          contentUrl?: string;
+          contentType?: string;
+          name?: string;
+        }>;
+      };
+
+      // Extract SharePoint file attachments (contentType: "reference")
+      // Download any file type, not just images
+      const spAttachments = (msgData.attachments ?? []).filter(
+        (a) => a.contentType === "reference" && a.contentUrl && a.name,
+      );
+      for (const att of spAttachments) {
+        const name = att.name ?? "file";
+
+        try {
+          // SharePoint URLs need to be accessed via Graph shares API
+          const shareUrl = att.contentUrl!;
+          const encodedUrl = Buffer.from(shareUrl).toString("base64url");
+          const sharesUrl = `${GRAPH_ROOT}/shares/u!${encodedUrl}/driveItem/content`;
+
+          const spRes = await fetchFn(sharesUrl, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+            redirect: "follow",
+          });
+
+          if (spRes.ok) {
+            const buffer = Buffer.from(await spRes.arrayBuffer());
+            if (buffer.byteLength <= params.maxBytes) {
+              const mime = await getMSTeamsRuntime().media.detectMime({
+                buffer,
+                headerMime: spRes.headers.get("content-type") ?? undefined,
+                filePath: name,
+              });
+              const originalFilename = params.preserveFilenames ? name : undefined;
+              const saved = await getMSTeamsRuntime().channel.media.saveMediaBuffer(
+                buffer,
+                mime ?? "application/octet-stream",
+                "inbound",
+                params.maxBytes,
+                originalFilename,
+              );
+              sharePointMedia.push({
+                path: saved.path,
+                contentType: saved.contentType,
+                placeholder: inferPlaceholder({ contentType: saved.contentType, fileName: name }),
+              });
+              downloadedReferenceUrls.add(shareUrl);
+            }
+          }
+        } catch {
+          // Ignore SharePoint download failures.
+        }
+      }
+    }
+  } catch {
+    // Ignore message fetch failures.
+  }
+
+  const hosted = await downloadGraphHostedContent({
+    accessToken,
+    messageUrl,
+    maxBytes: params.maxBytes,
+    fetchFn: params.fetchFn,
+    preserveFilenames: params.preserveFilenames,
+  });
+
+  const attachments = await fetchGraphCollection<GraphAttachment>({
+    url: `${messageUrl}/attachments`,
+    accessToken,
+    fetchFn: params.fetchFn,
+  });
+
+  const normalizedAttachments = attachments.items.map(normalizeGraphAttachment);
+  const filteredAttachments =
+    sharePointMedia.length > 0
+      ? normalizedAttachments.filter((att) => {
+          const contentType = att.contentType?.toLowerCase();
+          if (contentType !== "reference") return true;
+          const url = typeof att.contentUrl === "string" ? att.contentUrl : "";
+          if (!url) return true;
+          return !downloadedReferenceUrls.has(url);
+        })
+      : normalizedAttachments;
+  const attachmentMedia = await downloadMSTeamsAttachments({
+    attachments: filteredAttachments,
+    maxBytes: params.maxBytes,
+    tokenProvider: params.tokenProvider,
+    allowHosts,
+    fetchFn: params.fetchFn,
+    preserveFilenames: params.preserveFilenames,
+  });
+
+  return {
+    media: [...sharePointMedia, ...hosted.media, ...attachmentMedia],
+    hostedCount: hosted.count,
+    attachmentCount: filteredAttachments.length + sharePointMedia.length,
+    hostedStatus: hosted.status,
+    attachmentStatus: attachments.status,
+    messageUrl,
+  };
+}