@openclaw/msteams 2026.3.12 → 2026.5.1-beta.1

package/src/graph-thread.ts

@@ -0,0 +1,146 @@
+import { fetchGraphJson, type GraphResponse } from "./graph.js";
+
+export type GraphThreadMessage = {
+  id?: string;
+  from?: {
+    user?: { displayName?: string; id?: string };
+    application?: { displayName?: string; id?: string };
+  };
+  body?: { content?: string; contentType?: string };
+  createdDateTime?: string;
+};
+
+// TTL cache for team ID -> group GUID mapping.
+const teamGroupIdCache = new Map<string, { groupId: string; expiresAt: number }>();
+const CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Strip HTML tags from Teams message content, preserving @mention display names.
+ * Teams wraps mentions in <at>Name</at> tags.
+ */
+export function stripHtmlFromTeamsMessage(html: string): string {
+  // Preserve mention display names by replacing <at>Name</at> with @Name.
+  let text = html.replace(/<at[^>]*>(.*?)<\/at>/gi, "@$1");
+  // Strip remaining HTML tags.
+  text = text.replace(/<[^>]*>/g, " ");
+  // Decode common HTML entities.
+  text = text
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, " ");
+  // Normalize whitespace.
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Resolve the Azure AD group GUID for a Teams conversation team ID.
+ * Results are cached with a TTL to avoid repeated Graph API calls.
+ */
+export async function resolveTeamGroupId(
+  token: string,
+  conversationTeamId: string,
+): Promise<string> {
+  const cached = teamGroupIdCache.get(conversationTeamId);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.groupId;
+  }
+
+  // The team ID in channelData is typically the group ID itself for standard teams.
+  // Validate by fetching /teams/{id} and returning the confirmed id.
+  // Requires Team.ReadBasic.All permission; fall back to raw ID if missing.
+  try {
+    const path = `/teams/${encodeURIComponent(conversationTeamId)}?$select=id`;
+    const team = await fetchGraphJson<{ id?: string }>({ token, path });
+    const groupId = team.id ?? conversationTeamId;
+
+    // Only cache when the Graph lookup succeeds — caching a fallback raw ID
+    // can cause silent failures for the entire TTL if the ID is not a valid
+    // Graph team GUID (e.g. Bot Framework conversation key).
+    teamGroupIdCache.set(conversationTeamId, {
+      groupId,
+      expiresAt: Date.now() + CACHE_TTL_MS,
+    });
+
+    return groupId;
+  } catch {
+    // Fallback to raw team ID without caching so subsequent calls retry the
+    // Graph lookup instead of using a potentially invalid cached value.
+    return conversationTeamId;
+  }
+}
+
+/**
+ * Fetch a single channel message (the parent/root of a thread).
+ * Returns undefined on error so callers can degrade gracefully.
+ */
+export async function fetchChannelMessage(
+  token: string,
+  groupId: string,
+  channelId: string,
+  messageId: string,
+): Promise<GraphThreadMessage | undefined> {
+  const path = `/teams/${encodeURIComponent(groupId)}/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(messageId)}?$select=id,from,body,createdDateTime`;
+  try {
+    return await fetchGraphJson<GraphThreadMessage>({ token, path });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Fetch thread replies for a channel message, ordered chronologically.
+ *
+ * **Limitation:** The Graph API replies endpoint (`/messages/{id}/replies`) does not
+ * support `$orderby`, so results are always returned in ascending (oldest-first) order.
+ * Combined with the `$top` cap of 50, this means only the **oldest 50 replies** are
+ * returned for long threads — newer replies are silently omitted. There is currently no
+ * Graph API workaround for this; pagination via `@odata.nextLink` can retrieve more
+ * replies but still in ascending order only.
+ */
+export async function fetchThreadReplies(
+  token: string,
+  groupId: string,
+  channelId: string,
+  messageId: string,
+  limit = 50,
+): Promise<GraphThreadMessage[]> {
+  const top = Math.min(Math.max(limit, 1), 50);
+  // NOTE: Graph replies endpoint returns oldest-first and does not support $orderby.
+  // For threads with >50 replies, only the oldest 50 are returned. The most recent
+  // replies (often the most relevant context) may be truncated.
+  const path = `/teams/${encodeURIComponent(groupId)}/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(messageId)}/replies?$top=${top}&$select=id,from,body,createdDateTime`;
+  const res = await fetchGraphJson<GraphResponse<GraphThreadMessage>>({ token, path });
+  return res.value ?? [];
+}
+
+/**
+ * Format thread messages into a context string for the agent.
+ * Skips the current message (by id) and blank messages.
+ */
+export function formatThreadContext(
+  messages: GraphThreadMessage[],
+  currentMessageId?: string,
+): string {
+  const lines: string[] = [];
+  for (const msg of messages) {
+    if (msg.id && msg.id === currentMessageId) {
+      continue;
+    } // Skip the triggering message.
+    const sender = msg.from?.user?.displayName ?? msg.from?.application?.displayName ?? "unknown";
+    const contentType = msg.body?.contentType ?? "text";
+    const rawContent = msg.body?.content ?? "";
+    const content =
+      contentType === "html" ? stripHtmlFromTeamsMessage(rawContent) : rawContent.trim();
+    if (!content) {
+      continue;
+    }
+    lines.push(`${sender}: ${content}`);
+  }
+  return lines.join("\n");
+}
+
+// Exported for testing only.
+export { teamGroupIdCache as _teamGroupIdCacheForTest };

package/src/graph-upload.test.ts

@@ -0,0 +1,258 @@
+import { withFetchPreconnect } from "openclaw/plugin-sdk/test-env";
+import { describe, expect, it, vi } from "vitest";
+import { buildTeamsFileInfoCard } from "./graph-chat.js";
+import { resolveGraphChatId, uploadToOneDrive, uploadToSharePoint } from "./graph-upload.js";
+
+describe("graph upload helpers", () => {
+  const tokenProvider = {
+    getAccessToken: vi.fn(async () => "graph-token"),
+  };
+
+  it("uploads to OneDrive with the personal drive path", async () => {
+    const fetchFn = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({ id: "item-1", webUrl: "https://example.com/1", name: "a.txt" }),
+          {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          },
+        ),
+    );
+
+    const result = await uploadToOneDrive({
+      buffer: Buffer.from("hello"),
+      filename: "a.txt",
+      tokenProvider,
+      fetchFn: withFetchPreconnect(fetchFn),
+    });
+
+    expect(fetchFn).toHaveBeenCalledWith(
+      "https://graph.microsoft.com/v1.0/me/drive/root:/OpenClawShared/a.txt:/content",
+      expect.objectContaining({
+        method: "PUT",
+        headers: expect.objectContaining({
+          Authorization: "Bearer graph-token",
+          "Content-Type": "application/octet-stream",
+          "User-Agent": expect.stringMatching(/^teams\.ts\[apps\]\/.+ OpenClaw\/.+$/),
+        }),
+      }),
+    );
+    expect(result).toEqual({
+      id: "item-1",
+      webUrl: "https://example.com/1",
+      name: "a.txt",
+    });
+  });
+
+  it("uploads to SharePoint with the site drive path", async () => {
+    const fetchFn = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({ id: "item-2", webUrl: "https://example.com/2", name: "b.txt" }),
+          {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          },
+        ),
+    );
+
+    const result = await uploadToSharePoint({
+      buffer: Buffer.from("world"),
+      filename: "b.txt",
+      siteId: "site-123",
+      tokenProvider,
+      fetchFn: withFetchPreconnect(fetchFn),
+    });
+
+    expect(fetchFn).toHaveBeenCalledWith(
+      "https://graph.microsoft.com/v1.0/sites/site-123/drive/root:/OpenClawShared/b.txt:/content",
+      expect.objectContaining({
+        method: "PUT",
+        headers: expect.objectContaining({
+          Authorization: "Bearer graph-token",
+          "Content-Type": "application/octet-stream",
+          "User-Agent": expect.stringMatching(/^teams\.ts\[apps\]\/.+ OpenClaw\/.+$/),
+        }),
+      }),
+    );
+    expect(result).toEqual({
+      id: "item-2",
+      webUrl: "https://example.com/2",
+      name: "b.txt",
+    });
+  });
+
+  it("rejects upload responses missing required fields", async () => {
+    const fetchFn = vi.fn(
+      async () =>
+        new Response(JSON.stringify({ id: "item-3" }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    );
+
+    await expect(
+      uploadToSharePoint({
+        buffer: Buffer.from("world"),
+        filename: "bad.txt",
+        siteId: "site-123",
+        tokenProvider,
+        fetchFn: withFetchPreconnect(fetchFn),
+      }),
+    ).rejects.toThrow("SharePoint upload response missing required fields");
+  });
+});
+
+describe("resolveGraphChatId", () => {
+  const tokenProvider = {
+    getAccessToken: vi.fn(async () => "graph-token"),
+  };
+
+  it("returns the ID directly when it already starts with 19:", async () => {
+    const fetchFn = vi.fn();
+    const result = await resolveGraphChatId({
+      botFrameworkConversationId: "19:abc123@thread.tacv2",
+      tokenProvider,
+      fetchFn: withFetchPreconnect(fetchFn),
+    });
+    // Should short-circuit without making any API call
+    expect(fetchFn).not.toHaveBeenCalled();
+    expect(result).toBe("19:abc123@thread.tacv2");
+  });
+
+  it("resolves personal DM chat ID via Graph API using user AAD object ID", async () => {
+    const fetchFn = vi.fn(
+      async () =>
+        new Response(JSON.stringify({ value: [{ id: "19:dm-chat-id@unq.gbl.spaces" }] }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    );
+
+    const result = await resolveGraphChatId({
+      botFrameworkConversationId: "a:1abc_bot_framework_dm_id",
+      userAadObjectId: "user-aad-object-id-123",
+      tokenProvider,
+      fetchFn: withFetchPreconnect(fetchFn),
+    });
+
+    expect(fetchFn).toHaveBeenCalledWith(
+      expect.stringContaining("/me/chats"),
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "Bearer graph-token",
+          "User-Agent": expect.stringMatching(/^teams\.ts\[apps\]\/.+ OpenClaw\/.+$/),
+        }),
+      }),
+    );
+    const firstCall = fetchFn.mock.calls[0];
+    if (!firstCall) {
+      throw new Error("expected Graph chat lookup request");
+    }
+    const [callUrlRaw] = firstCall as unknown as [string, RequestInit?];
+    const callUrl = new URL(callUrlRaw);
+    expect(callUrl.origin).toBe("https://graph.microsoft.com");
+    expect(callUrl.pathname).toBe("/v1.0/me/chats");
+    expect(callUrl.searchParams.get("$filter")).toBe(
+      "chatType eq 'oneOnOne' and members/any(m:m/microsoft.graph.aadUserConversationMember/userId eq 'user-aad-object-id-123')",
+    );
+    expect(callUrl.searchParams.get("$select")).toBe("id");
+    expect(result).toBe("19:dm-chat-id@unq.gbl.spaces");
+  });
+
+  it("resolves personal DM chat ID without user AAD object ID (lists all 1:1 chats)", async () => {
+    const fetchFn = vi.fn(
+      async () =>
+        new Response(JSON.stringify({ value: [{ id: "19:fallback-chat@unq.gbl.spaces" }] }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    );
+
+    const result = await resolveGraphChatId({
+      botFrameworkConversationId: "8:orgid:user-object-id",
+      tokenProvider,
+      fetchFn: withFetchPreconnect(fetchFn),
+    });
+
+    expect(fetchFn).toHaveBeenCalledOnce();
+    expect(result).toBe("19:fallback-chat@unq.gbl.spaces");
+  });
+
+  it("returns null when Graph API returns no chats", async () => {
+    const fetchFn = vi.fn(
+      async () =>
+        new Response(JSON.stringify({ value: [] }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    );
+
+    const result = await resolveGraphChatId({
+      botFrameworkConversationId: "a:1unknown_dm",
+      userAadObjectId: "some-user",
+      tokenProvider,
+      fetchFn: withFetchPreconnect(fetchFn),
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when Graph API call fails", async () => {
+    const fetchFn = vi.fn(
+      async () =>
+        new Response("Unauthorized", {
+          status: 401,
+          headers: { "content-type": "text/plain" },
+        }),
+    );
+
+    const result = await resolveGraphChatId({
+      botFrameworkConversationId: "a:1some_dm_id",
+      userAadObjectId: "some-user",
+      tokenProvider,
+      fetchFn: withFetchPreconnect(fetchFn),
+    });
+
+    expect(result).toBeNull();
+  });
+});
+
+describe("buildTeamsFileInfoCard", () => {
+  it("extracts a unique id from quoted etags and lowercases file extensions", () => {
+    expect(
+      buildTeamsFileInfoCard({
+        eTag: '"{ABC-123},42"',
+        name: "Quarterly.Report.PDF",
+        webDavUrl: "https://sharepoint.example.com/file.pdf",
+      }),
+    ).toEqual({
+      contentType: "application/vnd.microsoft.teams.card.file.info",
+      contentUrl: "https://sharepoint.example.com/file.pdf",
+      name: "Quarterly.Report.PDF",
+      content: {
+        uniqueId: "ABC-123",
+        fileType: "pdf",
+      },
+    });
+  });
+
+  it("keeps the raw etag when no version suffix exists and handles extensionless files", () => {
+    expect(
+      buildTeamsFileInfoCard({
+        eTag: "plain-etag",
+        name: "README",
+        webDavUrl: "https://sharepoint.example.com/readme",
+      }),
+    ).toEqual({
+      contentType: "application/vnd.microsoft.teams.card.file.info",
+      contentUrl: "https://sharepoint.example.com/readme",
+      name: "README",
+      content: {
+        uniqueId: "plain-etag",
+        fileType: "",
+      },
+    });
+  });
+});

package/src/graph-upload.ts

@@ -10,12 +10,13 @@
  */
 
 import type { MSTeamsAccessTokenProvider } from "./attachments/types.js";
+import { buildUserAgent } from "./user-agent.js";
 
 const GRAPH_ROOT = "https://graph.microsoft.com/v1.0";
 const GRAPH_BETA = "https://graph.microsoft.com/beta";
 const GRAPH_SCOPE = "https://graph.microsoft.com";
 
-export interface OneDriveUploadResult {
+interface OneDriveUploadResult {
   id: string;
   webUrl: string;
   name: string;
@@ -41,6 +42,7 @@ export async function uploadToOneDrive(params: {
   const res = await fetchFn(`${GRAPH_ROOT}/me/drive/root:${uploadPath}:/content`, {
     method: "PUT",
     headers: {
+      "User-Agent": buildUserAgent(),
       Authorization: `Bearer ${token}`,
       "Content-Type": params.contentType ?? "application/octet-stream",
     },
@@ -69,7 +71,7 @@ export async function uploadToOneDrive(params: {
   };
 }
 
-export interface OneDriveSharingLink {
+interface OneDriveSharingLink {
   webUrl: string;
 }
 
@@ -77,7 +79,7 @@ export interface OneDriveSharingLink {
  * Create a sharing link for a OneDrive file.
  * The link allows organization members to view the file.
  */
-export async function createSharingLink(params: {
+async function createSharingLink(params: {
   itemId: string;
   tokenProvider: MSTeamsAccessTokenProvider;
   /** Sharing scope: "organization" (default) or "anonymous" */
@@ -90,6 +92,7 @@ export async function createSharingLink(params: {
   const res = await fetchFn(`${GRAPH_ROOT}/me/drive/items/${params.itemId}/createLink`, {
     method: "POST",
     headers: {
+      "User-Agent": buildUserAgent(),
       Authorization: `Bearer ${token}`,
       "Content-Type": "application/json",
     },
@@ -186,6 +189,7 @@ export async function uploadToSharePoint(params: {
     {
       method: "PUT",
       headers: {
+        "User-Agent": buildUserAgent(),
         Authorization: `Bearer ${token}`,
         "Content-Type": params.contentType ?? "application/octet-stream",
       },
@@ -215,7 +219,7 @@ export async function uploadToSharePoint(params: {
   };
 }
 
-export interface ChatMember {
+interface ChatMember {
   aadObjectId: string;
   displayName?: string;
 }
@@ -251,7 +255,7 @@ export async function getDriveItemProperties(params: {
 
   const res = await fetchFn(
     `${GRAPH_ROOT}/sites/${params.siteId}/drive/items/${params.itemId}?$select=eTag,webDavUrl,name`,
-    { headers: { Authorization: `Bearer ${token}` } },
+    { headers: { "User-Agent": buildUserAgent(), Authorization: `Bearer ${token}` } },
   );
 
   if (!res.ok) {
@@ -276,11 +280,85 @@ export async function getDriveItemProperties(params: {
   };
 }
 
+/**
+ * Resolve the Graph API-native chat ID from a Bot Framework conversation ID.
+ *
+ * Bot Framework personal DM conversation IDs use formats like `a:1xxx@unq.gbl.spaces`
+ * or `8:orgid:xxx` that the Graph API does not accept. Graph API requires the
+ * `19:xxx@thread.tacv2` or `19:xxx@unq.gbl.spaces` format.
+ *
+ * This function looks up the matching Graph chat by querying the bot's chats filtered
+ * by the target user's AAD object ID.
+ */
+export async function resolveGraphChatId(params: {
+  /** Bot Framework conversation ID (may be in non-Graph format for personal DMs) */
+  botFrameworkConversationId: string;
+  /** AAD object ID of the user in the conversation (used for filtering chats) */
+  userAadObjectId?: string;
+  tokenProvider: MSTeamsAccessTokenProvider;
+  fetchFn?: typeof fetch;
+}): Promise<string | null> {
+  const { botFrameworkConversationId, userAadObjectId, tokenProvider } = params;
+  const fetchFn = params.fetchFn ?? fetch;
+
+  // If the conversation ID already looks like a valid Graph chat ID, return it directly.
+  // Graph chat IDs start with "19:" — Bot Framework group chat IDs already use this format.
+  if (botFrameworkConversationId.startsWith("19:")) {
+    return botFrameworkConversationId;
+  }
+
+  // For personal DMs with non-Graph conversation IDs (e.g. `a:1xxx` or `8:orgid:xxx`),
+  // query the bot's chats to find the matching one.
+  const token = await tokenProvider.getAccessToken(GRAPH_SCOPE);
+
+  // Build filter: if we have the user's AAD object ID, narrow the search to 1:1 chats
+  // with that member. Otherwise, fall back to listing all 1:1 chats.
+  let path: string;
+  if (userAadObjectId) {
+    const encoded = encodeURIComponent(
+      `chatType eq 'oneOnOne' and members/any(m:m/microsoft.graph.aadUserConversationMember/userId eq '${userAadObjectId}')`,
+    );
+    path = `/me/chats?$filter=${encoded}&$select=id`;
+  } else {
+    // Fallback: list all 1:1 chats when no user ID is available.
+    // Only safe when the bot has exactly one 1:1 chat; returns null otherwise to
+    // avoid sending to the wrong person's chat.
+    path = `/me/chats?$filter=${encodeURIComponent("chatType eq 'oneOnOne'")}&$select=id`;
+  }
+
+  const res = await fetchFn(`${GRAPH_ROOT}${path}`, {
+    headers: { "User-Agent": buildUserAgent(), Authorization: `Bearer ${token}` },
+  });
+
+  if (!res.ok) {
+    return null;
+  }
+
+  const data = (await res.json()) as {
+    value?: Array<{ id?: string }>;
+  };
+
+  const chats = data.value ?? [];
+
+  // When filtered by userAadObjectId, any non-empty result is the right 1:1 chat.
+  if (userAadObjectId && chats.length > 0 && chats[0]?.id) {
+    return chats[0].id;
+  }
+
+  // Without a user ID we can only be certain when exactly one chat is returned;
+  // multiple results would be ambiguous and could route to the wrong person.
+  if (!userAadObjectId && chats.length === 1 && chats[0]?.id) {
+    return chats[0].id;
+  }
+
+  return null;
+}
+
 /**
  * Get members of a Teams chat for per-user sharing.
  * Used to create sharing links scoped to only the chat participants.
  */
-export async function getChatMembers(params: {
+async function getChatMembers(params: {
   chatId: string;
   tokenProvider: MSTeamsAccessTokenProvider;
   fetchFn?: typeof fetch;
@@ -289,7 +367,7 @@ export async function getChatMembers(params: {
   const token = await params.tokenProvider.getAccessToken(GRAPH_SCOPE);
 
   const res = await fetchFn(`${GRAPH_ROOT}/chats/${params.chatId}/members`, {
-    headers: { Authorization: `Bearer ${token}` },
+    headers: { "User-Agent": buildUserAgent(), Authorization: `Bearer ${token}` },
   });
 
   if (!res.ok) {
@@ -317,7 +395,7 @@ export async function getChatMembers(params: {
  * For organization scope (default), uses v1.0 API.
  * For per-user scope, uses beta API with recipients.
  */
-export async function createSharePointSharingLink(params: {
+async function createSharePointSharingLink(params: {
   siteId: string;
   itemId: string;
   tokenProvider: MSTeamsAccessTokenProvider;
@@ -349,6 +427,7 @@ export async function createSharePointSharingLink(params: {
     {
       method: "POST",
       headers: {
+        "User-Agent": buildUserAgent(),
         Authorization: `Bearer ${token}`,
         "Content-Type": "application/json",
       },