@gakr-gakr/msteams 0.1.0

package/src/reply-stream-controller.ts

@@ -0,0 +1,334 @@
+import {
+  createLiveMessageState,
+  createPreviewMessageReceipt,
+  defineFinalizableLivePreviewAdapter,
+  deliverWithFinalizableLivePreviewAdapter,
+  markLiveMessageFinalized,
+  type LiveMessageState,
+} from "autobot/plugin-sdk/channel-message";
+import {
+  createChannelProgressDraftGate,
+  type ChannelProgressDraftLine,
+  formatChannelProgressDraftText,
+  isChannelProgressDraftWorkToolName,
+  mergeChannelProgressDraftLine,
+  normalizeChannelProgressDraftLineIdentity,
+  resolveChannelPreviewStreamMode,
+  resolveChannelProgressDraftMaxLines,
+  resolveChannelProgressDraftLabel,
+  resolveChannelStreamingPreviewToolProgress,
+} from "autobot/plugin-sdk/channel-streaming";
+import { normalizeOptionalLowercaseString } from "autobot/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.ts

@@ -0,0 +1,309 @@
+import { mapAllowlistResolutionInputs } from "autobot/plugin-sdk/allow-from";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalLowercaseString,
+} from "autobot/plugin-sdk/string-coerce-runtime";
+import { searchGraphUsers } from "./graph-users.js";
+import {
+  listChannelsForTeam,
+  listTeamsByName,
+  normalizeQuery,
+  resolveGraphToken,
+} from "./graph.js";
+
+type MSTeamsChannelResolution = {
+  input: string;
+  resolved: boolean;
+  teamId?: string;
+  teamName?: string;
+  channelId?: string;
+  channelName?: string;
+  note?: string;
+};
+
+type MSTeamsUserResolution = {
+  input: string;
+  resolved: boolean;
+  id?: string;
+  name?: string;
+  note?: string;
+};
+
+function stripProviderPrefix(raw: string): string {
+  return raw.replace(/^(msteams|teams):/i, "");
+}
+
+export function normalizeMSTeamsMessagingTarget(raw: string): string | undefined {
+  let trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  trimmed = stripProviderPrefix(trimmed).trim();
+  if (/^conversation:/i.test(trimmed)) {
+    const id = trimmed.slice("conversation:".length).trim();
+    return id ? `conversation:${id}` : undefined;
+  }
+  if (/^user:/i.test(trimmed)) {
+    const id = trimmed.slice("user:".length).trim();
+    return id ? `user:${id}` : undefined;
+  }
+  return trimmed || undefined;
+}
+
+export function normalizeMSTeamsUserInput(raw: string): string {
+  return stripProviderPrefix(raw)
+    .replace(/^(user|conversation):/i, "")
+    .trim();
+}
+
+export function parseMSTeamsConversationId(raw: string): string | null {
+  const trimmed = stripProviderPrefix(raw).trim();
+  if (!/^conversation:/i.test(trimmed)) {
+    return null;
+  }
+  const id = trimmed.slice("conversation:".length).trim();
+  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, "")
+    .trim();
+  return trimmed || undefined;
+}
+
+function normalizeMSTeamsChannelKey(raw?: string | null): string | undefined {
+  const trimmed = raw?.trim().replace(/^#/, "").trim() ?? "";
+  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) {
+    return {};
+  }
+  const parts = trimmed.split("/");
+  const team = normalizeMSTeamsTeamKey(parts[0] ?? "");
+  const channel =
+    parts.length > 1 ? normalizeMSTeamsChannelKey(parts.slice(1).join("/")) : undefined;
+  return {
+    ...(team ? { team } : {}),
+    ...(channel ? { channel } : {}),
+  };
+}
+
+export function parseMSTeamsTeamEntry(
+  raw: string,
+): { teamKey: string; channelKey?: string } | null {
+  const { team, channel } = parseMSTeamsTeamChannelInput(raw);
+  if (!team) {
+    return null;
+  }
+  return {
+    teamKey: team,
+    ...(channel ? { channelKey: channel } : {}),
+  };
+}
+
+export async function resolveMSTeamsChannelAllowlist(params: {
+  cfg: unknown;
+  entries: string[];
+}): Promise<MSTeamsChannelResolution[]> {
+  let tokenPromise: Promise<string> | undefined;
+  const getToken = () => {
+    tokenPromise ??= resolveGraphToken(params.cfg);
+    return tokenPromise;
+  };
+  return await mapAllowlistResolutionInputs({
+    inputs: params.entries,
+    mapInput: async (input): Promise<MSTeamsChannelResolution> => {
+      const { team, channel } = parseMSTeamsTeamChannelInput(input);
+      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);
+      if (teams.length === 0) {
+        return { input, resolved: false, note: "team not found" };
+      }
+      const teamMatch = teams[0];
+      const graphTeamId = teamMatch.id?.trim();
+      const teamName = teamMatch.displayName?.trim() || team;
+      if (!graphTeamId) {
+        return { input, resolved: false, note: "team id missing" };
+      }
+      // Bot Framework sends the General channel's conversation ID as
+      // channelData.team.id at runtime, NOT the Graph API group GUID.
+      // Fetch channels upfront so we can resolve the correct key format for
+      // runtime matching and reuse the list for channel lookups.
+      let teamChannels: Awaited<ReturnType<typeof listChannelsForTeam>> = [];
+      try {
+        teamChannels = await listChannelsForTeam(token, graphTeamId);
+      } catch {
+        // API failure (rate limit, network error) — fall back to Graph GUID as team key
+      }
+      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).
+      const teamId = generalChannel?.id?.trim() || graphTeamId;
+      if (!channel) {
+        return {
+          input,
+          resolved: true,
+          teamId,
+          teamName,
+          note: teams.length > 1 ? "multiple teams; chose first" : undefined,
+        };
+      }
+      // Reuse teamChannels — already fetched above
+      const normalizedChannel = normalizeOptionalLowercaseString(channel);
+      const channelMatch =
+        teamChannels.find((item) => item.id === channel) ??
+        teamChannels.find(
+          (item) => normalizeOptionalLowercaseString(item.displayName) === normalizedChannel,
+        ) ??
+        teamChannels.find((item) =>
+          normalizeLowercaseStringOrEmpty(item.displayName ?? "").includes(normalizedChannel ?? ""),
+        );
+      if (!channelMatch?.id) {
+        return { input, resolved: false, note: "channel not found" };
+      }
+      return {
+        input,
+        resolved: true,
+        teamId,
+        teamName,
+        channelId: channelMatch.id,
+        channelName: channelMatch.displayName ?? channel,
+        note: teamChannels.length > 1 ? "multiple channels; chose first" : undefined,
+      };
+    },
+  });
+}
+
+export async function resolveMSTeamsUserAllowlist(params: {
+  cfg: unknown;
+  entries: string[];
+}): Promise<MSTeamsUserResolution[]> {
+  const token = await resolveGraphToken(params.cfg);
+  return await mapAllowlistResolutionInputs({
+    inputs: params.entries,
+    mapInput: async (input): Promise<MSTeamsUserResolution> => {
+      const query = normalizeQuery(normalizeMSTeamsUserInput(input));
+      if (!query) {
+        return { input, resolved: false };
+      }
+      if (/^[0-9a-fA-F-]{16,}$/.test(query)) {
+        return { input, resolved: true, id: query };
+      }
+      const users = await searchGraphUsers({ token, query, top: 10 });
+      const match = users[0];
+      if (!match?.id) {
+        return { input, resolved: false };
+      }
+      return {
+        input,
+        resolved: true,
+        id: match.id,
+        name: match.displayName ?? undefined,
+        note: users.length > 1 ? "multiple matches; chose first" : undefined,
+      };
+    },
+  });
+}

package/src/revoked-context.ts

@@ -0,0 +1,17 @@
+import { isRevokedProxyError } from "./errors.js";
+
+export async function withRevokedProxyFallback<T>(params: {
+  run: () => Promise<T>;
+  onRevoked: () => Promise<T>;
+  onRevokedLog?: () => void;
+}): Promise<T> {
+  try {
+    return await params.run();
+  } catch (err) {
+    if (!isRevokedProxyError(err)) {
+      throw err;
+    }
+    params.onRevokedLog?.();
+    return await params.onRevoked();
+  }
+}

package/src/runtime.ts

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