@kodelyth/msteams 2026.5.39 → 2026.5.42

package/src/reply-stream-controller.ts

@@ -0,0 +1,334 @@
+import {
+  createLiveMessageState,
+  createPreviewMessageReceipt,
+  defineFinalizableLivePreviewAdapter,
+  deliverWithFinalizableLivePreviewAdapter,
+  markLiveMessageFinalized,
+  type LiveMessageState,
+} from "klaw/plugin-sdk/channel-message";
+import {
+  createChannelProgressDraftGate,
+  type ChannelProgressDraftLine,
+  formatChannelProgressDraftText,
+  isChannelProgressDraftWorkToolName,
+  mergeChannelProgressDraftLine,
+  normalizeChannelProgressDraftLineIdentity,
+  resolveChannelPreviewStreamMode,
+  resolveChannelProgressDraftMaxLines,
+  resolveChannelProgressDraftLabel,
+  resolveChannelStreamingPreviewToolProgress,
+} from "klaw/plugin-sdk/channel-streaming";
+import { normalizeOptionalLowercaseString } from "klaw/plugin-sdk/string-coerce-runtime";
+import type { MSTeamsConfig, 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;
+
+export function pickInformativeStatusText(
+  params: { config?: MSTeamsConfig; seed?: string; random?: () => number } | (() => number) = {},
+): string | undefined {
+  const options = typeof params === "function" ? { random: params } : params;
+  return resolveChannelProgressDraftLabel({
+    entry: options.config,
+    seed: options.seed,
+    random: options.random,
+  });
+}
+
+export function createTeamsReplyStreamController(params: {
+  conversationType?: string;
+  context: MSTeamsTurnContext;
+  feedbackLoopEnabled: boolean;
+  log: MSTeamsMonitorLogger;
+  msteamsConfig?: MSTeamsConfig;
+  progressSeed?: string;
+  random?: () => number;
+}) {
+  const isPersonal = normalizeOptionalLowercaseString(params.conversationType) === "personal";
+  const streamMode = resolveChannelPreviewStreamMode(params.msteamsConfig, "partial");
+  const shouldUseNativeStream =
+    isPersonal && (streamMode === "partial" || streamMode === "progress");
+  const shouldSuppressDefaultToolProgressMessages =
+    shouldUseNativeStream && streamMode === "progress";
+  const shouldStreamPreviewToolProgress =
+    shouldSuppressDefaultToolProgressMessages &&
+    resolveChannelStreamingPreviewToolProgress(params.msteamsConfig);
+  const stream = shouldUseNativeStream
+    ? 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 progressLines: Array<string | ChannelProgressDraftLine> = [];
+  let lastInformativeText = "";
+  let pendingFinalize: Promise<void> | undefined;
+  let liveState: LiveMessageState<ReplyPayload> = createLiveMessageState({
+    canFinalizeInPlace: Boolean(stream),
+  });
+
+  const markStreamFinalized = () => {
+    if (!stream || stream.isFailed) {
+      return;
+    }
+    const messageId = stream.messageId ?? stream.previewStreamId;
+    if (!messageId) {
+      return;
+    }
+    liveState = markLiveMessageFinalized(liveState, createPreviewMessageReceipt({ id: messageId }));
+  };
+
+  const renderInformativeUpdate = async () => {
+    if (!stream) {
+      return;
+    }
+    const informativeText = formatChannelProgressDraftText({
+      entry: params.msteamsConfig,
+      lines: shouldStreamPreviewToolProgress ? progressLines : [],
+      seed: params.progressSeed,
+      bullet: "-",
+    });
+    if (!informativeText || informativeText === lastInformativeText) {
+      return;
+    }
+    lastInformativeText = informativeText;
+    informativeUpdateSent = true;
+    await stream.sendInformativeUpdate(informativeText);
+  };
+
+  const progressDraftGate = createChannelProgressDraftGate({
+    onStart: renderInformativeUpdate,
+  });
+
+  const noteProgressWork = async (options?: { toolName?: string }): Promise<void> => {
+    if (!stream || streamMode !== "progress") {
+      return;
+    }
+    if (options?.toolName !== undefined && !isChannelProgressDraftWorkToolName(options.toolName)) {
+      return;
+    }
+    const hadStarted = progressDraftGate.hasStarted;
+    await progressDraftGate.noteWork();
+    if (hadStarted && progressDraftGate.hasStarted) {
+      await renderInformativeUpdate();
+    }
+  };
+
+  const pushProgressLine = async (
+    line?: string | ChannelProgressDraftLine,
+    options?: { toolName?: string },
+  ): Promise<void> => {
+    if (!stream || streamMode !== "progress") {
+      return;
+    }
+    if (options?.toolName !== undefined && !isChannelProgressDraftWorkToolName(options.toolName)) {
+      return;
+    }
+    if (shouldStreamPreviewToolProgress) {
+      const normalized = normalizeChannelProgressDraftLineIdentity(line);
+      if (normalized) {
+        const progressLine: string | ChannelProgressDraftLine =
+          typeof line === "object" && line !== undefined ? line : normalized;
+        progressLines = mergeChannelProgressDraftLine(progressLines, progressLine, {
+          maxLines: resolveChannelProgressDraftMaxLines(params.msteamsConfig),
+        });
+      }
+    }
+    await noteProgressWork();
+  };
+
+  const fallbackAfterStreamFailure = (
+    payload: ReplyPayload,
+    hasMedia: boolean,
+  ): Maybe<ReplyPayload> => {
+    if (!payload.text) {
+      return payload;
+    }
+    const streamedLength = stream?.streamedLength ?? 0;
+    if (streamedLength <= 0) {
+      return payload;
+    }
+    const remainingText = payload.text.slice(streamedLength);
+    if (!remainingText) {
+      return hasMedia ? { ...payload, text: undefined } : undefined;
+    }
+    return { ...payload, text: remainingText };
+  };
+
+  const finalizeProgressPayload = async (
+    payload: ReplyPayload,
+    hasMedia: boolean,
+  ): Promise<Maybe<ReplyPayload>> => {
+    if (!stream || !payload.text) {
+      return payload;
+    }
+    const result = await deliverWithFinalizableLivePreviewAdapter({
+      kind: "final",
+      payload,
+      liveState,
+      adapter: defineFinalizableLivePreviewAdapter<ReplyPayload, string, { text: string }>({
+        draft: {
+          flush: async () => {},
+          clear: async () => {},
+          id: () => stream.previewStreamId,
+        },
+        buildFinalEdit: (candidate) => (candidate.text ? { text: candidate.text } : undefined),
+        editFinal: async (_previewId, edit) => {
+          const finalized = await stream.replaceInformativeWithFinal(edit.text);
+          informativeUpdateSent = false;
+          if (!finalized || stream.isFailed) {
+            throw new Error("Teams progress stream finalization failed");
+          }
+        },
+        resolveFinalizedId: (previewId) => stream.messageId ?? stream.previewStreamId ?? previewId,
+        createPreviewReceipt: (id) => createPreviewMessageReceipt({ id }),
+        onPreviewFinalized: (_id, _receipt, state) => {
+          liveState = state;
+        },
+        logPreviewEditFailure: (err) => {
+          params.log.debug?.(`stream finalization failed: ${formatUnknownError(err)}`);
+        },
+      }),
+      deliverNormally: async () => false,
+    });
+
+    return result.kind === "preview-finalized"
+      ? hasMedia
+        ? { ...payload, text: undefined }
+        : undefined
+      : payload;
+  };
+
+  return {
+    async onReplyStart(): Promise<void> {
+      return;
+    },
+
+    async noteProgressWork(options?: { toolName?: string }): Promise<void> {
+      await noteProgressWork(options);
+    },
+
+    onPartialReply(payload: { text?: string }): void {
+      if (!stream || !payload.text) {
+        return;
+      }
+      if (streamMode === "progress") {
+        return;
+      }
+      streamReceivedTokens = true;
+      stream.update(payload.text);
+    },
+
+    async pushProgressLine(
+      line?: string | ChannelProgressDraftLine,
+      options?: { toolName?: string },
+    ): Promise<void> {
+      await pushProgressLine(line, options);
+    },
+
+    shouldSuppressDefaultToolProgressMessages(): boolean {
+      return shouldSuppressDefaultToolProgressMessages;
+    },
+
+    shouldStreamPreviewToolProgress(): boolean {
+      return shouldStreamPreviewToolProgress;
+    },
+
+    async preparePayload(payload: ReplyPayload): Promise<Maybe<ReplyPayload>> {
+      const hasMedia = Boolean(payload.mediaUrl || payload.mediaUrls?.length);
+
+      if (stream && streamMode === "progress" && informativeUpdateSent && !stream.isFinalized) {
+        if (!payload.text) {
+          return payload;
+        }
+        return await finalizeProgressPayload(payload, hasMedia);
+      }
+
+      if (!stream || !streamReceivedTokens) {
+        return payload;
+      }
+
+      // 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;
+
+        return fallbackAfterStreamFailure(payload, hasMedia);
+      }
+
+      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().then(() => {
+        markStreamFinalized();
+      });
+
+      if (!hasMedia) {
+        return undefined;
+      }
+      return { ...payload, text: undefined };
+    },
+
+    async finalize(): Promise<void> {
+      progressDraftGate.cancel();
+      await pendingFinalize;
+      if (!pendingFinalize) {
+        await stream?.finalize();
+        markStreamFinalized();
+      }
+    },
+
+    hasStream(): boolean {
+      return Boolean(stream);
+    },
+
+    liveState(): LiveMessageState<ReplyPayload> {
+      return liveState;
+    },
+
+    /**
+     * 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

@@ -0,0 +1,253 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  listTeamsByName,
+  listChannelsForTeam,
+  normalizeQuery,
+  resolveGraphToken,
+  searchGraphUsers,
+} = vi.hoisted(() => ({
+  listTeamsByName: vi.fn(),
+  listChannelsForTeam: vi.fn(),
+  normalizeQuery: vi.fn((value: string) => value.trim().toLowerCase()),
+  resolveGraphToken: vi.fn(async () => "graph-token"),
+  searchGraphUsers: vi.fn(),
+}));
+
+vi.mock("./graph.js", () => ({
+  listTeamsByName,
+  listChannelsForTeam,
+  normalizeQuery,
+  resolveGraphToken,
+}));
+
+vi.mock("./graph-users.js", () => ({
+  searchGraphUsers,
+}));
+
+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: ["  "] });
+    expect(result).toEqual({ input: "  ", resolved: false });
+  });
+
+  it("resolves first Graph user match", async () => {
+    searchGraphUsers.mockResolvedValueOnce([
+      { id: "user-1", displayName: "Alice One" },
+      { id: "user-2", displayName: "Alice Two" },
+    ]);
+    const [result] = await resolveMSTeamsUserAllowlist({ cfg: {}, entries: ["alice"] });
+    expect(result).toEqual({
+      input: "alice",
+      resolved: true,
+      id: "user-1",
+      name: "Alice One",
+      note: "multiple matches; chose first",
+    });
+  });
+});
+
+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).toEqual({
+      input: "19:team-general@thread.tacv2/conversation:19:roadmap@thread.tacv2",
+      resolved: true,
+      teamId: "19:team-general@thread.tacv2",
+      teamName: "19:team-general@thread.tacv2",
+      channelId: "19:roadmap@thread.tacv2",
+      channelName: "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.
+    listTeamsByName.mockResolvedValueOnce([{ id: "team-guid-1", displayName: "Product Team" }]);
+    listChannelsForTeam.mockResolvedValueOnce([
+      { id: "19:general-conv-id@thread.tacv2", displayName: "General" },
+      { id: "19:roadmap-conv-id@thread.tacv2", displayName: "Roadmap" },
+    ]);
+
+    const [result] = await resolveMSTeamsChannelAllowlist({
+      cfg: {},
+      entries: ["Product Team/Roadmap"],
+    });
+
+    // teamId is now the General channel's conversation ID — not the Graph GUID —
+    // because that's what Bot Framework sends as channelData.team.id at runtime.
+    expect(result).toEqual({
+      input: "Product Team/Roadmap",
+      resolved: true,
+      teamId: "19:general-conv-id@thread.tacv2",
+      teamName: "Product Team",
+      channelId: "19:roadmap-conv-id@thread.tacv2",
+      channelName: "Roadmap",
+      note: "multiple channels; chose first",
+    });
+  });
+
+  it("uses General channel conversation ID as team key for team-only entry", async () => {
+    // When no channel is specified we still resolve the General channel so the
+    // stored key matches what Bot Framework sends as channelData.team.id.
+    listTeamsByName.mockResolvedValueOnce([{ id: "guid-engineering", displayName: "Engineering" }]);
+    listChannelsForTeam.mockResolvedValueOnce([
+      { id: "19:eng-general@thread.tacv2", displayName: "General" },
+      { id: "19:eng-standups@thread.tacv2", displayName: "Standups" },
+    ]);
+
+    const [result] = await resolveMSTeamsChannelAllowlist({
+      cfg: {},
+      entries: ["Engineering"],
+    });
+
+    expect(result).toEqual({
+      input: "Engineering",
+      resolved: true,
+      teamId: "19:eng-general@thread.tacv2",
+      teamName: "Engineering",
+    });
+  });
+
+  it("falls back to Graph GUID when listChannelsForTeam throws", async () => {
+    // Edge case: API call fails (rate limit, network error). We fall back to
+    // the Graph GUID as the team key — the pre-fix behavior — so resolution
+    // still succeeds instead of propagating the error.
+    listTeamsByName.mockResolvedValueOnce([{ id: "guid-flaky", displayName: "Flaky Team" }]);
+    listChannelsForTeam.mockRejectedValueOnce(new Error("429 Too Many Requests"));
+
+    const [result] = await resolveMSTeamsChannelAllowlist({
+      cfg: {},
+      entries: ["Flaky Team"],
+    });
+
+    expect(result).toEqual({
+      input: "Flaky Team",
+      resolved: true,
+      teamId: "guid-flaky",
+      teamName: "Flaky Team",
+    });
+  });
+
+  it("falls back to Graph GUID when General channel is not found", async () => {
+    // Edge case: General channel was renamed or deleted. We fall back to the
+    // Graph GUID so resolution still succeeds rather than silently breaking.
+    listTeamsByName.mockResolvedValueOnce([{ id: "guid-ops", displayName: "Operations" }]);
+    listChannelsForTeam.mockResolvedValueOnce([
+      { id: "19:ops-announce@thread.tacv2", displayName: "Announcements" },
+      { id: "19:ops-random@thread.tacv2", displayName: "Random" },
+    ]);
+
+    const [result] = await resolveMSTeamsChannelAllowlist({
+      cfg: {},
+      entries: ["Operations"],
+    });
+
+    expect(result).toEqual({
+      input: "Operations",
+      resolved: true,
+      teamId: "guid-ops",
+      teamName: "Operations",
+    });
+  });
+});
+
+describe("looksLikeMSTeamsTargetId", () => {
+  // Regression suite for https://github.com/klaw/klaw/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);
+  });
+});