@openclaw/msteams 2026.3.13 → 2026.5.1-beta.1

package/src/reply-stream-controller.ts

@@ -0,0 +1,147 @@
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
+import type { ReplyPayload } from "../runtime-api.js";
+import { formatUnknownError } from "./errors.js";
+import type { MSTeamsMonitorLogger } from "./monitor-types.js";
+import type { MSTeamsTurnContext } from "./sdk-types.js";
+import { TeamsHttpStream } from "./streaming-message.js";
+
+// Local generic wrapper to defer union resolution. Works around a
+// single-file-mode limitation in the type-aware lint where imported
+// types resolved via extension runtime-api barrels are treated as
+// `error` (acting as `any`) and trip `no-redundant-type-constituents`
+// when combined with `undefined` in a union.
+type Maybe<T> = T | undefined;
+
+const INFORMATIVE_STATUS_TEXTS = [
+  "Thinking...",
+  "Working on that...",
+  "Checking the details...",
+  "Putting an answer together...",
+];
+
+export function pickInformativeStatusText(random = Math.random): string {
+  const index = Math.floor(random() * INFORMATIVE_STATUS_TEXTS.length);
+  return INFORMATIVE_STATUS_TEXTS[index] ?? INFORMATIVE_STATUS_TEXTS[0];
+}
+
+export function createTeamsReplyStreamController(params: {
+  conversationType?: string;
+  context: MSTeamsTurnContext;
+  feedbackLoopEnabled: boolean;
+  log: MSTeamsMonitorLogger;
+  random?: () => number;
+}) {
+  const isPersonal = normalizeOptionalLowercaseString(params.conversationType) === "personal";
+  const stream = isPersonal
+    ? new TeamsHttpStream({
+        sendActivity: (activity) => params.context.sendActivity(activity),
+        feedbackLoopEnabled: params.feedbackLoopEnabled,
+        onError: (err) => {
+          params.log.debug?.(`stream error: ${formatUnknownError(err)}`);
+        },
+      })
+    : undefined;
+
+  let streamReceivedTokens = false;
+  let informativeUpdateSent = false;
+  let pendingFinalize: Promise<void> | undefined;
+
+  return {
+    async onReplyStart(): Promise<void> {
+      if (!stream || informativeUpdateSent) {
+        return;
+      }
+      informativeUpdateSent = true;
+      await stream.sendInformativeUpdate(pickInformativeStatusText(params.random));
+    },
+
+    onPartialReply(payload: { text?: string }): void {
+      if (!stream || !payload.text) {
+        return;
+      }
+      streamReceivedTokens = true;
+      stream.update(payload.text);
+    },
+
+    preparePayload(payload: ReplyPayload): Maybe<ReplyPayload> {
+      if (!stream || !streamReceivedTokens) {
+        return payload;
+      }
+
+      const hasMedia = Boolean(payload.mediaUrl || payload.mediaUrls?.length);
+
+      // Stream failed after partial delivery (e.g. > 4000 chars). Send only
+      // the unstreamed suffix via block delivery to avoid duplicate text.
+      if (stream.isFailed) {
+        streamReceivedTokens = false;
+
+        if (!payload.text) {
+          return payload;
+        }
+
+        const streamedLength = stream.streamedLength;
+        if (streamedLength <= 0) {
+          return payload;
+        }
+
+        const remainingText = payload.text.slice(streamedLength);
+        if (!remainingText) {
+          return hasMedia ? { ...payload, text: undefined } : undefined;
+        }
+
+        return { ...payload, text: remainingText };
+      }
+
+      if (!stream.hasContent || stream.isFinalized) {
+        return payload;
+      }
+
+      // Stream handled this text segment. Finalize it and reset so any
+      // subsequent text segments (after tool calls) use fallback delivery.
+      // finalize() is idempotent; the later call in markDispatchIdle is a no-op.
+      streamReceivedTokens = false;
+      pendingFinalize = stream.finalize();
+
+      if (!hasMedia) {
+        return undefined;
+      }
+      return { ...payload, text: undefined };
+    },
+
+    async finalize(): Promise<void> {
+      await pendingFinalize;
+      await stream?.finalize();
+    },
+
+    hasStream(): boolean {
+      return Boolean(stream);
+    },
+
+    /**
+     * Whether the Teams streaming card is currently receiving LLM tokens.
+     * Used to gate side-channel keepalive activity so we don't overlay plain
+     * "typing" indicators on top of a live streaming card.
+     *
+     * Returns true only while the stream is actively chunking text into the
+     * streaming card. The informative update (blue progress bar) is short
+     * lived so we intentionally do not count it as "active"; this way the
+     * typing keepalive can still fire during the informative window and
+     * during tool chains between text segments.
+     *
+     * Returns false when:
+     * - No stream exists (non-personal conversation).
+     * - Stream has not yet received any text tokens.
+     * - Stream has been finalized (e.g. after the first text segment, while
+     *   tools run before the next segment).
+     */
+    isStreamActive(): boolean {
+      if (!stream) {
+        return false;
+      }
+      if (stream.isFinalized || stream.isFailed) {
+        return false;
+      }
+      return streamReceivedTokens;
+    },
+  };
+}

package/src/resolve-allowlist.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const {
   listTeamsByName,
@@ -26,10 +26,19 @@ vi.mock("./graph-users.js", () => ({
 }));
 
 import {
+  looksLikeMSTeamsTargetId,
   resolveMSTeamsChannelAllowlist,
   resolveMSTeamsUserAllowlist,
 } from "./resolve-allowlist.js";
 
+beforeEach(() => {
+  listTeamsByName.mockReset();
+  listChannelsForTeam.mockReset();
+  normalizeQuery.mockImplementation((value: string) => value.trim().toLowerCase());
+  resolveGraphToken.mockReset().mockResolvedValue("graph-token");
+  searchGraphUsers.mockReset();
+});
+
 describe("resolveMSTeamsUserAllowlist", () => {
   it("marks empty input unresolved", async () => {
     const [result] = await resolveMSTeamsUserAllowlist({ cfg: {}, entries: ["  "] });
@@ -53,6 +62,39 @@ describe("resolveMSTeamsUserAllowlist", () => {
 });
 
 describe("resolveMSTeamsChannelAllowlist", () => {
+  it("keeps configured Teams conversation IDs resolved without Graph lookup", async () => {
+    const [result] = await resolveMSTeamsChannelAllowlist({
+      cfg: {},
+      entries: ["19:team-general@thread.skype/19:roadmap@thread.skype"],
+    });
+
+    expect(result).toEqual({
+      input: "19:team-general@thread.skype/19:roadmap@thread.skype",
+      resolved: true,
+      teamId: "19:team-general@thread.skype",
+      teamName: "19:team-general@thread.skype",
+      channelId: "19:roadmap@thread.skype",
+      channelName: "19:roadmap@thread.skype",
+    });
+    expect(resolveGraphToken).not.toHaveBeenCalled();
+    expect(listTeamsByName).not.toHaveBeenCalled();
+    expect(listChannelsForTeam).not.toHaveBeenCalled();
+  });
+
+  it("normalizes conversation-prefixed configured channel IDs", async () => {
+    const [result] = await resolveMSTeamsChannelAllowlist({
+      cfg: {},
+      entries: ["19:team-general@thread.tacv2/conversation:19:roadmap@thread.tacv2"],
+    });
+
+    expect(result).toMatchObject({
+      resolved: true,
+      teamId: "19:team-general@thread.tacv2",
+      channelId: "19:roadmap@thread.tacv2",
+    });
+    expect(resolveGraphToken).not.toHaveBeenCalled();
+  });
+
   it("resolves team/channel by team name + channel display name", async () => {
     // After the fix, listChannelsForTeam is called once and reused for both
     // General channel resolution and channel matching.
@@ -144,3 +186,65 @@ describe("resolveMSTeamsChannelAllowlist", () => {
     });
   });
 });
+
+describe("looksLikeMSTeamsTargetId", () => {
+  // Regression suite for https://github.com/openclaw/openclaw/issues/58001:
+  // cron announce delivery rejected valid Teams conversation ids because the
+  // validator only matched the `conversation:`-prefixed and `@thread`-suffixed
+  // forms. It must now accept every documented Bot Framework + Graph format.
+  it.each([
+    "conversation:19:abc@thread.tacv2",
+    "conversation:a:1abc",
+    "conversation:8:orgid:2d8c2d2c-1111-2222-3333-444444444444",
+  ])("accepts conversation-prefixed ids (%s)", (raw) => {
+    expect(looksLikeMSTeamsTargetId(raw)).toBe(true);
+  });
+
+  it.each(["19:AdviChannelId@thread.tacv2", "19:abc@thread.tacv2", "19:abc@thread.skype"])(
+    "accepts bare channel/group conversation ids (%s)",
+    (raw) => {
+      expect(looksLikeMSTeamsTargetId(raw)).toBe(true);
+    },
+  );
+
+  it("accepts the Graph 1:1 chat thread format", () => {
+    expect(
+      looksLikeMSTeamsTargetId(
+        "19:40a1a0ed4ff24164a21955518990c197_2d8c2d2c11112222@unq.gbl.spaces",
+      ),
+    ).toBe(true);
+  });
+
+  it.each(["a:1abc123def", "a:1xyz-abc_def", "A:1UPPER"])(
+    "accepts Bot Framework personal chat ids (%s)",
+    (raw) => {
+      expect(looksLikeMSTeamsTargetId(raw)).toBe(true);
+    },
+  );
+
+  it.each(["8:orgid:2d8c2d2c-1111-2222-3333-444444444444", "8:orgid:user-object-id"])(
+    "accepts Bot Framework org-scoped personal chat ids (%s)",
+    (raw) => {
+      expect(looksLikeMSTeamsTargetId(raw)).toBe(true);
+    },
+  );
+
+  it("accepts Bot Framework user ids", () => {
+    expect(looksLikeMSTeamsTargetId("29:1a2b3c4d5e6f")).toBe(true);
+  });
+
+  it("accepts user:<aad-object-id> ids", () => {
+    expect(looksLikeMSTeamsTargetId("user:40a1a0ed-4ff2-4164-a219-55518990c197")).toBe(true);
+  });
+
+  it.each(["", "   ", "user:John Smith", "Product Team/Roadmap", "Engineering", "hello"])(
+    "rejects non-id inputs (%s)",
+    (raw) => {
+      expect(looksLikeMSTeamsTargetId(raw)).toBe(false);
+    },
+  );
+
+  it("normalizes leading/trailing whitespace before classifying", () => {
+    expect(looksLikeMSTeamsTargetId("  19:abc@thread.tacv2  ")).toBe(true);
+  });
+});

package/src/resolve-allowlist.ts

@@ -1,4 +1,8 @@
-import { mapAllowlistResolutionInputs } from "openclaw/plugin-sdk/compat";
+import { mapAllowlistResolutionInputs } from "openclaw/plugin-sdk/allow-from";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalLowercaseString,
+} from "openclaw/plugin-sdk/text-runtime";
 import { searchGraphUsers } from "./graph-users.js";
 import {
   listChannelsForTeam,
@@ -7,7 +11,7 @@ import {
   resolveGraphToken,
 } from "./graph.js";
 
-export type MSTeamsChannelResolution = {
+type MSTeamsChannelResolution = {
   input: string;
   resolved: boolean;
   teamId?: string;
@@ -17,7 +21,7 @@ export type MSTeamsChannelResolution = {
   note?: string;
 };
 
-export type MSTeamsUserResolution = {
+type MSTeamsUserResolution = {
   input: string;
   resolved: boolean;
   id?: string;
@@ -61,6 +65,63 @@ export function parseMSTeamsConversationId(raw: string): string | null {
   return id;
 }
 
+/**
+ * Detect whether a raw target string looks like a Microsoft Teams conversation
+ * or user id that cron announce delivery and other explicit-target paths can
+ * forward verbatim to the channel adapter.
+ *
+ * Accepts both prefixed and bare formats:
+ * - `conversation:<id>` — explicit conversation prefix
+ * - `user:<aad-guid>`   — user id (16+ hex chars, UUID-like)
+ * - `19:abc@thread.tacv2` / `19:abc@thread.skype` — channel / legacy group
+ * - `19:{userId}_{appId}@unq.gbl.spaces` — Graph 1:1 chat thread format
+ * - `a:1xxx` — Bot Framework personal (1:1) chat id
+ * - `8:orgid:xxx` — Bot Framework org-scoped personal chat id
+ * - `29:xxx` — Bot Framework user id
+ *
+ * Display-name user targets such as `user:John Smith` intentionally return
+ * false so that the Graph API directory lookup still runs for them.
+ */
+export function looksLikeMSTeamsTargetId(raw: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return false;
+  }
+  if (/^conversation:/i.test(trimmed)) {
+    return true;
+  }
+  if (/^user:/i.test(trimmed)) {
+    // Only treat as an id when the value after `user:` looks like a UUID;
+    // display names must fall through to directory lookup.
+    const id = trimmed.slice("user:".length).trim();
+    return /^[0-9a-fA-F-]{16,}$/.test(id);
+  }
+  // Bare Bot Framework / Graph conversation id formats.
+  // Channel / group ids always start with `19:` and include an `@thread.*`
+  // suffix (`@thread.tacv2` or the legacy `@thread.skype`). Personal chat
+  // ids come in three shapes: `a:1...` (Bot Framework), `8:orgid:...`
+  // (org-scoped Bot Framework), and `19:{userId}_{appId}@unq.gbl.spaces`
+  // (Graph API 1:1 chat thread). Bot Framework user ids use `29:...`.
+  if (/^19:.+@thread\.(tacv2|skype)$/i.test(trimmed)) {
+    return true;
+  }
+  if (/^19:.+@unq\.gbl\.spaces$/i.test(trimmed)) {
+    return true;
+  }
+  if (/^a:1[A-Za-z0-9_-]+$/i.test(trimmed)) {
+    return true;
+  }
+  if (/^8:orgid:[A-Za-z0-9-]+$/i.test(trimmed)) {
+    return true;
+  }
+  if (/^29:[A-Za-z0-9_-]+$/i.test(trimmed)) {
+    return true;
+  }
+  // Fallback: anything containing @thread is still treated as a conversation
+  // id so the current matches for tenant-specific suffixes remain accepted.
+  return /@thread\b/i.test(trimmed);
+}
+
 function normalizeMSTeamsTeamKey(raw: string): string | undefined {
   const trimmed = stripProviderPrefix(raw)
     .replace(/^team:/i, "")
@@ -73,6 +134,16 @@ function normalizeMSTeamsChannelKey(raw?: string | null): string | undefined {
   return trimmed || undefined;
 }
 
+function normalizeMSTeamsConversationTargetId(raw: string): string {
+  const trimmed = stripProviderPrefix(raw).trim();
+  return parseMSTeamsConversationId(trimmed) ?? trimmed;
+}
+
+function looksLikeMSTeamsThreadConversationId(raw: string): boolean {
+  const normalized = normalizeMSTeamsConversationTargetId(raw);
+  return /^19:.+@thread\./i.test(normalized);
+}
+
 export function parseMSTeamsTeamChannelInput(raw: string): { team?: string; channel?: string } {
   const trimmed = stripProviderPrefix(raw).trim();
   if (!trimmed) {
@@ -105,7 +176,11 @@ export async function resolveMSTeamsChannelAllowlist(params: {
   cfg: unknown;
   entries: string[];
 }): Promise<MSTeamsChannelResolution[]> {
-  const token = await resolveGraphToken(params.cfg);
+  let tokenPromise: Promise<string> | undefined;
+  const getToken = () => {
+    tokenPromise ??= resolveGraphToken(params.cfg);
+    return tokenPromise;
+  };
   return await mapAllowlistResolutionInputs({
     inputs: params.entries,
     mapInput: async (input): Promise<MSTeamsChannelResolution> => {
@@ -113,6 +188,31 @@ export async function resolveMSTeamsChannelAllowlist(params: {
       if (!team) {
         return { input, resolved: false };
       }
+      if (looksLikeMSTeamsThreadConversationId(team)) {
+        const teamId = normalizeMSTeamsConversationTargetId(team);
+        if (!channel) {
+          return { input, resolved: true, teamId, teamName: teamId };
+        }
+        if (!looksLikeMSTeamsThreadConversationId(channel)) {
+          return {
+            input,
+            resolved: false,
+            teamId,
+            teamName: teamId,
+            note: "channel id required for conversation-id team",
+          };
+        }
+        const channelId = normalizeMSTeamsConversationTargetId(channel);
+        return {
+          input,
+          resolved: true,
+          teamId,
+          teamName: teamId,
+          channelId,
+          channelName: channelId,
+        };
+      }
+      const token = await getToken();
       const teams = /^[0-9a-fA-F-]{16,}$/.test(team)
         ? [{ id: team, displayName: team }]
         : await listTeamsByName(token, team);
@@ -135,7 +235,9 @@ export async function resolveMSTeamsChannelAllowlist(params: {
       } catch {
         // API failure (rate limit, network error) — fall back to Graph GUID as team key
       }
-      const generalChannel = teamChannels.find((ch) => ch.displayName?.toLowerCase() === "general");
+      const generalChannel = teamChannels.find(
+        (ch) => normalizeOptionalLowercaseString(ch.displayName) === "general",
+      );
       // Use the General channel's conversation ID as the team key — this
       // matches what Bot Framework sends at runtime. Fall back to the Graph
       // GUID if the General channel isn't found (renamed or deleted).
@@ -150,11 +252,14 @@ export async function resolveMSTeamsChannelAllowlist(params: {
         };
       }
       // Reuse teamChannels — already fetched above
+      const normalizedChannel = normalizeOptionalLowercaseString(channel);
       const channelMatch =
         teamChannels.find((item) => item.id === channel) ??
-        teamChannels.find((item) => item.displayName?.toLowerCase() === channel.toLowerCase()) ??
+        teamChannels.find(
+          (item) => normalizeOptionalLowercaseString(item.displayName) === normalizedChannel,
+        ) ??
         teamChannels.find((item) =>
-          item.displayName?.toLowerCase().includes(channel.toLowerCase() ?? ""),
+          normalizeLowercaseStringOrEmpty(item.displayName ?? "").includes(normalizedChannel ?? ""),
         );
       if (!channelMatch?.id) {
         return { input, resolved: false, note: "channel not found" };

package/src/runtime.ts

@@ -1,6 +1,9 @@
-import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
-import type { PluginRuntime } from "openclaw/plugin-sdk/msteams";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
 
 const { setRuntime: setMSTeamsRuntime, getRuntime: getMSTeamsRuntime } =
-  createPluginRuntimeStore<PluginRuntime>("MSTeams runtime not initialized");
+  createPluginRuntimeStore<PluginRuntime>({
+    pluginId: "msteams",
+    errorMessage: "MSTeams runtime not initialized",
+  });
 export { getMSTeamsRuntime, setMSTeamsRuntime };

package/src/sdk-types.ts

@@ -1,5 +1,3 @@
-import type { TurnContext } from "@microsoft/agents-hosting";
-
 /**
  * Minimal public surface we depend on from the Microsoft SDK types.
  *
@@ -8,7 +6,47 @@ import type { TurnContext } from "@microsoft/agents-hosting";
  * stricter than what the runtime accepts (e.g. it allows plain activity-like
  * objects), so we model the minimal structural shape we rely on.
  */
-export type MSTeamsActivity = TurnContext["activity"];
+
+type MSTeamsActivity = {
+  type: string;
+  id?: string;
+  timestamp?: string;
+  localTimestamp?: string;
+  channelId?: string;
+  from?: { id?: string; name?: string; aadObjectId?: string; role?: string };
+  conversation?: {
+    id?: string;
+    conversationType?: string;
+    tenantId?: string;
+    name?: string;
+    isGroup?: boolean;
+  };
+  recipient?: { id?: string; name?: string };
+  text?: string;
+  textFormat?: string;
+  locale?: string;
+  serviceUrl?: string;
+  channelData?: {
+    team?: { id?: string; name?: string };
+    channel?: { id?: string; name?: string };
+    tenant?: { id?: string };
+    [key: string]: unknown;
+  };
+  attachments?: Array<{
+    contentType?: string;
+    contentUrl?: string;
+    content?: unknown;
+    name?: string;
+    thumbnailUrl?: string;
+  }>;
+  entities?: Array<Record<string, unknown>>;
+  value?: unknown;
+  name?: string;
+  membersAdded?: Array<{ id?: string; name?: string }>;
+  membersRemoved?: Array<{ id?: string; name?: string }>;
+  replyToId?: string;
+  [key: string]: unknown;
+};
 
 export type MSTeamsTurnContext = {
   activity: MSTeamsActivity;
@@ -16,4 +54,6 @@ export type MSTeamsTurnContext = {
   sendActivities: (
     activities: Array<{ type: string } & Record<string, unknown>>,
   ) => Promise<unknown>;
+  updateActivity: (activity: object) => Promise<{ id?: string } | void>;
+  deleteActivity: (activityId: string) => Promise<void>;
 };