@openclaw/msteams 2026.1.29

package/src/conversation-store-memory.ts

@@ -0,0 +1,45 @@
+import type {
+  MSTeamsConversationStore,
+  MSTeamsConversationStoreEntry,
+  StoredConversationReference,
+} from "./conversation-store.js";
+
+export function createMSTeamsConversationStoreMemory(
+  initial: MSTeamsConversationStoreEntry[] = [],
+): MSTeamsConversationStore {
+  const map = new Map<string, StoredConversationReference>();
+  for (const { conversationId, reference } of initial) {
+    map.set(conversationId, reference);
+  }
+
+  return {
+    upsert: async (conversationId, reference) => {
+      map.set(conversationId, reference);
+    },
+    get: async (conversationId) => {
+      return map.get(conversationId) ?? null;
+    },
+    list: async () => {
+      return Array.from(map.entries()).map(([conversationId, reference]) => ({
+        conversationId,
+        reference,
+      }));
+    },
+    remove: async (conversationId) => {
+      return map.delete(conversationId);
+    },
+    findByUserId: async (id) => {
+      const target = id.trim();
+      if (!target) return null;
+      for (const [conversationId, reference] of map.entries()) {
+        if (reference.user?.aadObjectId === target) {
+          return { conversationId, reference };
+        }
+        if (reference.user?.id === target) {
+          return { conversationId, reference };
+        }
+      }
+      return null;
+    },
+  };
+}

package/src/conversation-store.ts

@@ -0,0 +1,41 @@
+/**
+ * Conversation store for MS Teams proactive messaging.
+ *
+ * Stores ConversationReference-like objects keyed by conversation ID so we can
+ * send proactive messages later (after the webhook turn has completed).
+ */
+
+/** Minimal ConversationReference shape for proactive messaging */
+export type StoredConversationReference = {
+  /** Activity ID from the last message */
+  activityId?: string;
+  /** User who sent the message */
+  user?: { id?: string; name?: string; aadObjectId?: string };
+  /** Agent/bot that received the message */
+  agent?: { id?: string; name?: string; aadObjectId?: string } | null;
+  /** @deprecated legacy field (pre-Agents SDK). Prefer `agent`. */
+  bot?: { id?: string; name?: string };
+  /** Conversation details */
+  conversation?: { id?: string; conversationType?: string; tenantId?: string };
+  /** Team ID for channel messages (when available). */
+  teamId?: string;
+  /** Channel ID (usually "msteams") */
+  channelId?: string;
+  /** Service URL for sending messages back */
+  serviceUrl?: string;
+  /** Locale */
+  locale?: string;
+};
+
+export type MSTeamsConversationStoreEntry = {
+  conversationId: string;
+  reference: StoredConversationReference;
+};
+
+export type MSTeamsConversationStore = {
+  upsert: (conversationId: string, reference: StoredConversationReference) => Promise<void>;
+  get: (conversationId: string) => Promise<StoredConversationReference | null>;
+  list: () => Promise<MSTeamsConversationStoreEntry[]>;
+  remove: (conversationId: string) => Promise<boolean>;
+  findByUserId: (id: string) => Promise<MSTeamsConversationStoreEntry | null>;
+};

package/src/directory-live.ts

@@ -0,0 +1,179 @@
+import type { ChannelDirectoryEntry } from "openclaw/plugin-sdk";
+
+import { GRAPH_ROOT } from "./attachments/shared.js";
+import { loadMSTeamsSdkWithAuth } from "./sdk.js";
+import { resolveMSTeamsCredentials } from "./token.js";
+
+type GraphUser = {
+  id?: string;
+  displayName?: string;
+  userPrincipalName?: string;
+  mail?: string;
+};
+
+type GraphGroup = {
+  id?: string;
+  displayName?: string;
+};
+
+type GraphChannel = {
+  id?: string;
+  displayName?: string;
+};
+
+type GraphResponse<T> = { value?: T[] };
+
+function readAccessToken(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    const token =
+      (value as { accessToken?: unknown }).accessToken ?? (value as { token?: unknown }).token;
+    return typeof token === "string" ? token : null;
+  }
+  return null;
+}
+
+function normalizeQuery(value?: string | null): string {
+  return value?.trim() ?? "";
+}
+
+function escapeOData(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
+async function fetchGraphJson<T>(params: {
+  token: string;
+  path: string;
+  headers?: Record<string, string>;
+}): Promise<T> {
+  const res = await fetch(`${GRAPH_ROOT}${params.path}`, {
+    headers: {
+      Authorization: `Bearer ${params.token}`,
+      ...(params.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Graph ${params.path} failed (${res.status}): ${text || "unknown error"}`);
+  }
+  return (await res.json()) as T;
+}
+
+async function resolveGraphToken(cfg: unknown): Promise<string> {
+  const creds = resolveMSTeamsCredentials((cfg as { channels?: { msteams?: unknown } })?.channels?.msteams);
+  if (!creds) throw new Error("MS Teams credentials missing");
+  const { sdk, authConfig } = await loadMSTeamsSdkWithAuth(creds);
+  const tokenProvider = new sdk.MsalTokenProvider(authConfig);
+  const token = await tokenProvider.getAccessToken("https://graph.microsoft.com");
+  const accessToken = readAccessToken(token);
+  if (!accessToken) throw new Error("MS Teams graph token unavailable");
+  return accessToken;
+}
+
+async function listTeamsByName(token: string, query: string): Promise<GraphGroup[]> {
+  const escaped = escapeOData(query);
+  const filter = `resourceProvisioningOptions/Any(x:x eq 'Team') and startsWith(displayName,'${escaped}')`;
+  const path = `/groups?$filter=${encodeURIComponent(filter)}&$select=id,displayName`;
+  const res = await fetchGraphJson<GraphResponse<GraphGroup>>({ token, path });
+  return res.value ?? [];
+}
+
+async function listChannelsForTeam(token: string, teamId: string): Promise<GraphChannel[]> {
+  const path = `/teams/${encodeURIComponent(teamId)}/channels?$select=id,displayName`;
+  const res = await fetchGraphJson<GraphResponse<GraphChannel>>({ token, path });
+  return res.value ?? [];
+}
+
+export async function listMSTeamsDirectoryPeersLive(params: {
+  cfg: unknown;
+  query?: string | null;
+  limit?: number | null;
+}): Promise<ChannelDirectoryEntry[]> {
+  const query = normalizeQuery(params.query);
+  if (!query) return [];
+  const token = await resolveGraphToken(params.cfg);
+  const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : 20;
+
+  let users: GraphUser[] = [];
+  if (query.includes("@")) {
+    const escaped = escapeOData(query);
+    const filter = `(mail eq '${escaped}' or userPrincipalName eq '${escaped}')`;
+    const path = `/users?$filter=${encodeURIComponent(filter)}&$select=id,displayName,mail,userPrincipalName`;
+    const res = await fetchGraphJson<GraphResponse<GraphUser>>({ token, path });
+    users = res.value ?? [];
+  } else {
+    const path = `/users?$search=${encodeURIComponent(`"displayName:${query}"`)}&$select=id,displayName,mail,userPrincipalName&$top=${limit}`;
+    const res = await fetchGraphJson<GraphResponse<GraphUser>>({
+      token,
+      path,
+      headers: { ConsistencyLevel: "eventual" },
+    });
+    users = res.value ?? [];
+  }
+
+  return users
+    .map((user) => {
+      const id = user.id?.trim();
+      if (!id) return null;
+      const name = user.displayName?.trim();
+      const handle = user.userPrincipalName?.trim() || user.mail?.trim();
+      return {
+        kind: "user",
+        id: `user:${id}`,
+        name: name || undefined,
+        handle: handle ? `@${handle}` : undefined,
+        raw: user,
+      } satisfies ChannelDirectoryEntry;
+    })
+    .filter(Boolean) as ChannelDirectoryEntry[];
+}
+
+export async function listMSTeamsDirectoryGroupsLive(params: {
+  cfg: unknown;
+  query?: string | null;
+  limit?: number | null;
+}): Promise<ChannelDirectoryEntry[]> {
+  const rawQuery = normalizeQuery(params.query);
+  if (!rawQuery) return [];
+  const token = await resolveGraphToken(params.cfg);
+  const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : 20;
+  const [teamQuery, channelQuery] = rawQuery.includes("/")
+    ? rawQuery.split("/", 2).map((part) => part.trim()).filter(Boolean)
+    : [rawQuery, null];
+
+  const teams = await listTeamsByName(token, teamQuery);
+  const results: ChannelDirectoryEntry[] = [];
+
+  for (const team of teams) {
+    const teamId = team.id?.trim();
+    if (!teamId) continue;
+    const teamName = team.displayName?.trim() || teamQuery;
+    if (!channelQuery) {
+      results.push({
+        kind: "group",
+        id: `team:${teamId}`,
+        name: teamName,
+        handle: teamName ? `#${teamName}` : undefined,
+        raw: team,
+      });
+      if (results.length >= limit) return results;
+      continue;
+    }
+    const channels = await listChannelsForTeam(token, teamId);
+    for (const channel of channels) {
+      const name = channel.displayName?.trim();
+      if (!name) continue;
+      if (!name.toLowerCase().includes(channelQuery.toLowerCase())) continue;
+      results.push({
+        kind: "group",
+        id: `conversation:${channel.id}`,
+        name: `${teamName}/${name}`,
+        handle: `#${name}`,
+        raw: channel,
+      });
+      if (results.length >= limit) return results;
+    }
+  }
+
+  return results;
+}

package/src/errors.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  classifyMSTeamsSendError,
+  formatMSTeamsSendErrorHint,
+  formatUnknownError,
+} from "./errors.js";
+
+describe("msteams errors", () => {
+  it("formats unknown errors", () => {
+    expect(formatUnknownError("oops")).toBe("oops");
+    expect(formatUnknownError(null)).toBe("null");
+  });
+
+  it("classifies auth errors", () => {
+    expect(classifyMSTeamsSendError({ statusCode: 401 }).kind).toBe("auth");
+    expect(classifyMSTeamsSendError({ statusCode: 403 }).kind).toBe("auth");
+  });
+
+  it("classifies throttling errors and parses retry-after", () => {
+    expect(classifyMSTeamsSendError({ statusCode: 429, retryAfter: "1.5" })).toMatchObject({
+      kind: "throttled",
+      statusCode: 429,
+      retryAfterMs: 1500,
+    });
+  });
+
+  it("classifies transient errors", () => {
+    expect(classifyMSTeamsSendError({ statusCode: 503 })).toMatchObject({
+      kind: "transient",
+      statusCode: 503,
+    });
+  });
+
+  it("classifies permanent 4xx errors", () => {
+    expect(classifyMSTeamsSendError({ statusCode: 400 })).toMatchObject({
+      kind: "permanent",
+      statusCode: 400,
+    });
+  });
+
+  it("provides actionable hints for common cases", () => {
+    expect(formatMSTeamsSendErrorHint({ kind: "auth" })).toContain("msteams");
+    expect(formatMSTeamsSendErrorHint({ kind: "throttled" })).toContain("throttled");
+  });
+});

package/src/errors.ts

@@ -0,0 +1,158 @@
+export function formatUnknownError(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  if (err === null) return "null";
+  if (err === undefined) return "undefined";
+  if (typeof err === "number" || typeof err === "boolean" || typeof err === "bigint") {
+    return String(err);
+  }
+  if (typeof err === "symbol") return err.description ?? err.toString();
+  if (typeof err === "function") {
+    return err.name ? `[function ${err.name}]` : "[function]";
+  }
+  try {
+    return JSON.stringify(err) ?? "unknown error";
+  } catch {
+    return "unknown error";
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function extractStatusCode(err: unknown): number | null {
+  if (!isRecord(err)) return null;
+  const direct = err.statusCode ?? err.status;
+  if (typeof direct === "number" && Number.isFinite(direct)) return direct;
+  if (typeof direct === "string") {
+    const parsed = Number.parseInt(direct, 10);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+
+  const response = err.response;
+  if (isRecord(response)) {
+    const status = response.status;
+    if (typeof status === "number" && Number.isFinite(status)) return status;
+    if (typeof status === "string") {
+      const parsed = Number.parseInt(status, 10);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+  }
+
+  return null;
+}
+
+function extractRetryAfterMs(err: unknown): number | null {
+  if (!isRecord(err)) return null;
+
+  const direct = err.retryAfterMs ?? err.retry_after_ms;
+  if (typeof direct === "number" && Number.isFinite(direct) && direct >= 0) {
+    return direct;
+  }
+
+  const retryAfter = err.retryAfter ?? err.retry_after;
+  if (typeof retryAfter === "number" && Number.isFinite(retryAfter)) {
+    return retryAfter >= 0 ? retryAfter * 1000 : null;
+  }
+  if (typeof retryAfter === "string") {
+    const parsed = Number.parseFloat(retryAfter);
+    if (Number.isFinite(parsed) && parsed >= 0) return parsed * 1000;
+  }
+
+  const response = err.response;
+  if (!isRecord(response)) return null;
+
+  const headers = response.headers;
+  if (!headers) return null;
+
+  if (isRecord(headers)) {
+    const raw = headers["retry-after"] ?? headers["Retry-After"];
+    if (typeof raw === "string") {
+      const parsed = Number.parseFloat(raw);
+      if (Number.isFinite(parsed) && parsed >= 0) return parsed * 1000;
+    }
+  }
+
+  // Fetch Headers-like interface
+  if (
+    typeof headers === "object" &&
+    headers !== null &&
+    "get" in headers &&
+    typeof (headers as { get?: unknown }).get === "function"
+  ) {
+    const raw = (headers as { get: (name: string) => string | null }).get("retry-after");
+    if (raw) {
+      const parsed = Number.parseFloat(raw);
+      if (Number.isFinite(parsed) && parsed >= 0) return parsed * 1000;
+    }
+  }
+
+  return null;
+}
+
+export type MSTeamsSendErrorKind = "auth" | "throttled" | "transient" | "permanent" | "unknown";
+
+export type MSTeamsSendErrorClassification = {
+  kind: MSTeamsSendErrorKind;
+  statusCode?: number;
+  retryAfterMs?: number;
+};
+
+/**
+ * Classify outbound send errors for safe retries and actionable logs.
+ *
+ * Important: We only mark errors as retryable when we have an explicit HTTP
+ * status code that indicates the message was not accepted (e.g. 429, 5xx).
+ * For transport-level errors where delivery is ambiguous, we prefer to avoid
+ * retries to reduce the chance of duplicate posts.
+ */
+export function classifyMSTeamsSendError(err: unknown): MSTeamsSendErrorClassification {
+  const statusCode = extractStatusCode(err);
+  const retryAfterMs = extractRetryAfterMs(err);
+
+  if (statusCode === 401 || statusCode === 403) {
+    return { kind: "auth", statusCode };
+  }
+
+  if (statusCode === 429) {
+    return {
+      kind: "throttled",
+      statusCode,
+      retryAfterMs: retryAfterMs ?? undefined,
+    };
+  }
+
+  if (statusCode === 408 || (statusCode != null && statusCode >= 500)) {
+    return {
+      kind: "transient",
+      statusCode,
+      retryAfterMs: retryAfterMs ?? undefined,
+    };
+  }
+
+  if (statusCode != null && statusCode >= 400) {
+    return { kind: "permanent", statusCode };
+  }
+
+  return {
+    kind: "unknown",
+    statusCode: statusCode ?? undefined,
+    retryAfterMs: retryAfterMs ?? undefined,
+  };
+}
+
+export function formatMSTeamsSendErrorHint(
+  classification: MSTeamsSendErrorClassification,
+): string | undefined {
+  if (classification.kind === "auth") {
+    return "check msteams appId/appPassword/tenantId (or env vars MSTEAMS_APP_ID/MSTEAMS_APP_PASSWORD/MSTEAMS_TENANT_ID)";
+  }
+  if (classification.kind === "throttled") {
+    return "Teams throttled the bot; backing off may help";
+  }
+  if (classification.kind === "transient") {
+    return "transient Teams/Bot Framework error; retry may succeed";
+  }
+  return undefined;
+}

package/src/file-consent-helpers.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { prepareFileConsentActivity, requiresFileConsent } from "./file-consent-helpers.js";
+import * as pendingUploads from "./pending-uploads.js";
+
+describe("requiresFileConsent", () => {
+  const thresholdBytes = 4 * 1024 * 1024; // 4MB
+
+  it("returns true for personal chat with non-image", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "personal",
+        contentType: "application/pdf",
+        bufferSize: 1000,
+        thresholdBytes,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns true for personal chat with large image", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "personal",
+        contentType: "image/png",
+        bufferSize: 5 * 1024 * 1024, // 5MB
+        thresholdBytes,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false for personal chat with small image", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "personal",
+        contentType: "image/png",
+        bufferSize: 1000,
+        thresholdBytes,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false for group chat with large non-image", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "groupChat",
+        contentType: "application/pdf",
+        bufferSize: 5 * 1024 * 1024,
+        thresholdBytes,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false for channel with large non-image", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "channel",
+        contentType: "application/pdf",
+        bufferSize: 5 * 1024 * 1024,
+        thresholdBytes,
+      }),
+    ).toBe(false);
+  });
+
+  it("handles case-insensitive conversation type", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "Personal",
+        contentType: "application/pdf",
+        bufferSize: 1000,
+        thresholdBytes,
+      }),
+    ).toBe(true);
+
+    expect(
+      requiresFileConsent({
+        conversationType: "PERSONAL",
+        contentType: "application/pdf",
+        bufferSize: 1000,
+        thresholdBytes,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false when conversationType is undefined", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: undefined,
+        contentType: "application/pdf",
+        bufferSize: 1000,
+        thresholdBytes,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns true for personal chat when contentType is undefined (non-image)", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "personal",
+        contentType: undefined,
+        bufferSize: 1000,
+        thresholdBytes,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns true for personal chat with file exactly at threshold", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "personal",
+        contentType: "image/jpeg",
+        bufferSize: thresholdBytes, // exactly 4MB
+        thresholdBytes,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false for personal chat with file just below threshold", () => {
+    expect(
+      requiresFileConsent({
+        conversationType: "personal",
+        contentType: "image/jpeg",
+        bufferSize: thresholdBytes - 1, // 4MB - 1 byte
+        thresholdBytes,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("prepareFileConsentActivity", () => {
+  const mockUploadId = "test-upload-id-123";
+
+  beforeEach(() => {
+    vi.spyOn(pendingUploads, "storePendingUpload").mockReturnValue(mockUploadId);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("creates activity with consent card attachment", () => {
+    const result = prepareFileConsentActivity({
+      media: {
+        buffer: Buffer.from("test content"),
+        filename: "test.pdf",
+        contentType: "application/pdf",
+      },
+      conversationId: "conv123",
+      description: "My file",
+    });
+
+    expect(result.uploadId).toBe(mockUploadId);
+    expect(result.activity.type).toBe("message");
+    expect(result.activity.attachments).toHaveLength(1);
+
+    const attachment = (result.activity.attachments as unknown[])[0] as Record<string, unknown>;
+    expect(attachment.contentType).toBe("application/vnd.microsoft.teams.card.file.consent");
+    expect(attachment.name).toBe("test.pdf");
+  });
+
+  it("stores pending upload with correct data", () => {
+    const buffer = Buffer.from("test content");
+    prepareFileConsentActivity({
+      media: {
+        buffer,
+        filename: "test.pdf",
+        contentType: "application/pdf",
+      },
+      conversationId: "conv123",
+      description: "My file",
+    });
+
+    expect(pendingUploads.storePendingUpload).toHaveBeenCalledWith({
+      buffer,
+      filename: "test.pdf",
+      contentType: "application/pdf",
+      conversationId: "conv123",
+    });
+  });
+
+  it("uses default description when not provided", () => {
+    const result = prepareFileConsentActivity({
+      media: {
+        buffer: Buffer.from("test"),
+        filename: "document.docx",
+        contentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      },
+      conversationId: "conv456",
+    });
+
+    const attachment = (result.activity.attachments as unknown[])[0] as Record<string, { description: string }>;
+    expect(attachment.content.description).toBe("File: document.docx");
+  });
+
+  it("uses provided description", () => {
+    const result = prepareFileConsentActivity({
+      media: {
+        buffer: Buffer.from("test"),
+        filename: "report.pdf",
+        contentType: "application/pdf",
+      },
+      conversationId: "conv789",
+      description: "Q4 Financial Report",
+    });
+
+    const attachment = (result.activity.attachments as unknown[])[0] as Record<string, { description: string }>;
+    expect(attachment.content.description).toBe("Q4 Financial Report");
+  });
+
+  it("includes uploadId in consent card context", () => {
+    const result = prepareFileConsentActivity({
+      media: {
+        buffer: Buffer.from("test"),
+        filename: "file.txt",
+        contentType: "text/plain",
+      },
+      conversationId: "conv000",
+    });
+
+    const attachment = (result.activity.attachments as unknown[])[0] as Record<string, { acceptContext: { uploadId: string } }>;
+    expect(attachment.content.acceptContext.uploadId).toBe(mockUploadId);
+  });
+
+  it("handles media without contentType", () => {
+    const result = prepareFileConsentActivity({
+      media: {
+        buffer: Buffer.from("binary data"),
+        filename: "unknown.bin",
+      },
+      conversationId: "conv111",
+    });
+
+    expect(result.uploadId).toBe(mockUploadId);
+    expect(result.activity.type).toBe("message");
+  });
+});