@gakr-gakr/msteams 0.1.0

package/src/config-schema.ts

@@ -0,0 +1,6 @@
+import { buildChannelConfigSchema, MSTeamsConfigSchema } from "../config-api.js";
+import { msTeamsChannelConfigUiHints } from "./config-ui-hints.js";
+
+export const MSTeamsChannelConfigSchema = buildChannelConfigSchema(MSTeamsConfigSchema, {
+  uiHints: msTeamsChannelConfigUiHints,
+});

package/src/config-ui-hints.ts

@@ -0,0 +1,40 @@
+import type { ChannelConfigUiHint } from "autobot/plugin-sdk/channel-core";
+
+export const msTeamsChannelConfigUiHints = {
+  "": {
+    label: "MS Teams",
+    help: "Microsoft Teams channel provider configuration and provider-specific policy toggles. Use this section to isolate Teams behavior from other enterprise chat providers.",
+  },
+  configWrites: {
+    label: "MS Teams Config Writes",
+    help: "Allow Microsoft Teams to write config in response to channel events/commands (default: true).",
+  },
+  streaming: {
+    label: "MS Teams Streaming",
+    help: 'Microsoft Teams preview/progress streaming mode: "off" | "partial" | "block" | "progress". Personal chats use Teams native streaminfo progress when available.',
+  },
+  "streaming.progress.label": {
+    label: "MS Teams Progress Label",
+    help: 'Initial progress title. Use "auto" for built-in single-word labels, a custom string, or false to hide the title.',
+  },
+  "streaming.progress.labels": {
+    label: "MS Teams Progress Label Pool",
+    help: 'Candidate labels for streaming.progress.label="auto". Leave unset to use AutoBot built-in progress labels.',
+  },
+  "streaming.progress.maxLines": {
+    label: "MS Teams Progress Max Lines",
+    help: "Maximum number of compact progress lines to keep below the progress title (default: 8).",
+  },
+  "streaming.progress.maxLineChars": {
+    label: "MS Teams Progress Max Line Chars",
+    help: "Maximum characters per compact progress line before truncation (default: 120). Prose cuts at word boundaries; commands and paths keep useful suffixes.",
+  },
+  "streaming.progress.toolProgress": {
+    label: "MS Teams Progress Tool Lines",
+    help: "Show compact tool/progress lines in progress mode (default: true). Set false to keep only the title until final delivery.",
+  },
+  "streaming.progress.commandText": {
+    label: "MS Teams Progress Command Text",
+    help: 'Command/exec detail in progress lines: "raw" preserves released behavior; "status" shows only the tool label.',
+  },
+} satisfies Record<string, ChannelConfigUiHint>;

package/src/conversation-store-fs.ts

@@ -0,0 +1,149 @@
+import {
+  findPreferredDmConversationByUserId,
+  mergeStoredConversationReference,
+  normalizeStoredConversationId,
+  parseStoredConversationTimestamp,
+  toConversationStoreEntries,
+} from "./conversation-store-helpers.js";
+import type {
+  MSTeamsConversationStore,
+  MSTeamsConversationStoreEntry,
+  StoredConversationReference,
+} from "./conversation-store.js";
+import { resolveMSTeamsStorePath } from "./storage.js";
+import { readJsonFile, withFileLock, writeJsonFile } from "./store-fs.js";
+
+type ConversationStoreData = {
+  version: 1;
+  conversations: Record<string, StoredConversationReference>;
+};
+
+const STORE_FILENAME = "msteams-conversations.json";
+const MAX_CONVERSATIONS = 1000;
+const CONVERSATION_TTL_MS = 365 * 24 * 60 * 60 * 1000;
+
+function pruneToLimit(conversations: Record<string, StoredConversationReference>) {
+  const entries = Object.entries(conversations);
+  if (entries.length <= MAX_CONVERSATIONS) {
+    return conversations;
+  }
+
+  entries.sort((a, b) => {
+    const aTs = parseStoredConversationTimestamp(a[1].lastSeenAt) ?? 0;
+    const bTs = parseStoredConversationTimestamp(b[1].lastSeenAt) ?? 0;
+    return aTs - bTs;
+  });
+
+  const keep = entries.slice(entries.length - MAX_CONVERSATIONS);
+  return Object.fromEntries(keep);
+}
+
+function pruneExpired(
+  conversations: Record<string, StoredConversationReference>,
+  nowMs: number,
+  ttlMs: number,
+) {
+  let removed = false;
+  const kept: typeof conversations = {};
+  for (const [conversationId, reference] of Object.entries(conversations)) {
+    const lastSeenAt = parseStoredConversationTimestamp(reference.lastSeenAt);
+    // Preserve legacy entries that have no lastSeenAt until they're seen again.
+    if (lastSeenAt != null && nowMs - lastSeenAt > ttlMs) {
+      removed = true;
+      continue;
+    }
+    kept[conversationId] = reference;
+  }
+  return { conversations: kept, removed };
+}
+
+export function createMSTeamsConversationStoreFs(params?: {
+  env?: NodeJS.ProcessEnv;
+  homedir?: () => string;
+  ttlMs?: number;
+  stateDir?: string;
+  storePath?: string;
+}): MSTeamsConversationStore {
+  const ttlMs = params?.ttlMs ?? CONVERSATION_TTL_MS;
+  const filePath = resolveMSTeamsStorePath({
+    filename: STORE_FILENAME,
+    env: params?.env,
+    homedir: params?.homedir,
+    stateDir: params?.stateDir,
+    storePath: params?.storePath,
+  });
+
+  const empty: ConversationStoreData = { version: 1, conversations: {} };
+
+  const readStore = async (): Promise<ConversationStoreData> => {
+    const { value } = await readJsonFile(filePath, empty);
+    if (
+      value.version !== 1 ||
+      !value.conversations ||
+      typeof value.conversations !== "object" ||
+      Array.isArray(value.conversations)
+    ) {
+      return empty;
+    }
+    const nowMs = Date.now();
+    const pruned = pruneExpired(value.conversations, nowMs, ttlMs).conversations;
+    return { version: 1, conversations: pruneToLimit(pruned) };
+  };
+
+  const list = async (): Promise<MSTeamsConversationStoreEntry[]> => {
+    const store = await readStore();
+    return toConversationStoreEntries(Object.entries(store.conversations));
+  };
+
+  const get = async (conversationId: string): Promise<StoredConversationReference | null> => {
+    const store = await readStore();
+    return store.conversations[normalizeStoredConversationId(conversationId)] ?? null;
+  };
+
+  const findPreferredDmByUserId = async (
+    id: string,
+  ): Promise<MSTeamsConversationStoreEntry | null> => {
+    return findPreferredDmConversationByUserId(await list(), id);
+  };
+
+  const upsert = async (
+    conversationId: string,
+    reference: StoredConversationReference,
+  ): Promise<void> => {
+    const normalizedId = normalizeStoredConversationId(conversationId);
+    await withFileLock(filePath, empty, async () => {
+      const store = await readStore();
+      store.conversations[normalizedId] = mergeStoredConversationReference(
+        store.conversations[normalizedId],
+        reference,
+        new Date().toISOString(),
+      );
+      const nowMs = Date.now();
+      store.conversations = pruneExpired(store.conversations, nowMs, ttlMs).conversations;
+      store.conversations = pruneToLimit(store.conversations);
+      await writeJsonFile(filePath, store);
+    });
+  };
+
+  const remove = async (conversationId: string): Promise<boolean> => {
+    const normalizedId = normalizeStoredConversationId(conversationId);
+    return await withFileLock(filePath, empty, async () => {
+      const store = await readStore();
+      if (!(normalizedId in store.conversations)) {
+        return false;
+      }
+      delete store.conversations[normalizedId];
+      await writeJsonFile(filePath, store);
+      return true;
+    });
+  };
+
+  return {
+    upsert,
+    get,
+    list,
+    remove,
+    findPreferredDmByUserId,
+    findByUserId: findPreferredDmByUserId,
+  };
+}

package/src/conversation-store-helpers.ts

@@ -0,0 +1,105 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import type {
+  MSTeamsConversationStoreEntry,
+  StoredConversationReference,
+} from "./conversation-store.js";
+
+export function normalizeStoredConversationId(raw: string): string {
+  return raw.split(";")[0] ?? raw;
+}
+
+export function parseStoredConversationTimestamp(value: string | undefined): number | null {
+  if (!value) {
+    return null;
+  }
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) {
+    return null;
+  }
+  return parsed;
+}
+
+export function toConversationStoreEntries(
+  entries: Iterable<[string, StoredConversationReference]>,
+): MSTeamsConversationStoreEntry[] {
+  return Array.from(entries, ([conversationId, reference]) => ({
+    conversationId,
+    reference,
+  }));
+}
+
+export function mergeStoredConversationReference(
+  existing: StoredConversationReference | undefined,
+  incoming: StoredConversationReference,
+  nowIso: string,
+): StoredConversationReference {
+  return {
+    // Preserve fields from the previous entry that may not be present on every
+    // inbound activity. Without this, sparse activities (e.g. conversationUpdate,
+    // reactions) would clear previously captured values. Some fields are only
+    // populated opportunistically, such as timezone from clientInfo entities and
+    // graphChatId from Graph lookups used for DM media downloads.
+    ...(existing?.timezone && !incoming.timezone ? { timezone: existing.timezone } : {}),
+    ...(existing?.graphChatId && !incoming.graphChatId
+      ? { graphChatId: existing.graphChatId }
+      : {}),
+    ...(existing?.tenantId && !incoming.tenantId ? { tenantId: existing.tenantId } : {}),
+    ...(existing?.aadObjectId && !incoming.aadObjectId
+      ? { aadObjectId: existing.aadObjectId }
+      : {}),
+    ...incoming,
+    lastSeenAt: nowIso,
+  };
+}
+
+export function findPreferredDmConversationByUserId(
+  entries: Iterable<MSTeamsConversationStoreEntry>,
+  id: string,
+): MSTeamsConversationStoreEntry | null {
+  const target = id.trim();
+  if (!target) {
+    return null;
+  }
+
+  // Partition user matches into DM-safe and non-DM buckets.
+  // Channel and group conversations also carry the sender's aadObjectId, but
+  // returning one of those when the caller asked for a user-targeted DM would
+  // leak the reply into a shared channel -- the root cause of #54520.
+  const personalMatches: MSTeamsConversationStoreEntry[] = [];
+  const unknownTypeMatches: MSTeamsConversationStoreEntry[] = [];
+  for (const entry of entries) {
+    if (entry.reference.user?.aadObjectId !== target && entry.reference.user?.id !== target) {
+      continue;
+    }
+    const convType = normalizeLowercaseStringOrEmpty(
+      entry.reference.conversation?.conversationType ?? "",
+    );
+    if (convType === "personal") {
+      personalMatches.push(entry);
+    } else if (convType === "channel" || convType === "groupchat") {
+      // Explicitly skip channel/group conversations -- these must never be
+      // returned for a user-targeted DM lookup.
+    } else {
+      // Legacy entries without conversationType are ambiguous. Include them
+      // as a fallback but rank below confirmed personal conversations.
+      unknownTypeMatches.push(entry);
+    }
+  }
+
+  // Prefer confirmed personal DMs, fall back to unknown-type entries.
+  const candidates = personalMatches.length > 0 ? personalMatches : unknownTypeMatches;
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  // When multiple candidates exist, prefer the most recently seen one.
+  if (candidates.length > 1) {
+    candidates.sort(
+      (a, b) =>
+        (parseStoredConversationTimestamp(b.reference.lastSeenAt) ?? 0) -
+        (parseStoredConversationTimestamp(a.reference.lastSeenAt) ?? 0),
+    );
+  }
+
+  return candidates[0] ?? null;
+}

package/src/conversation-store-memory.ts

@@ -0,0 +1,51 @@
+import {
+  findPreferredDmConversationByUserId,
+  mergeStoredConversationReference,
+  normalizeStoredConversationId,
+  toConversationStoreEntries,
+} from "./conversation-store-helpers.js";
+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(normalizeStoredConversationId(conversationId), reference);
+  }
+
+  const findPreferredDmByUserId = async (
+    id: string,
+  ): Promise<MSTeamsConversationStoreEntry | null> => {
+    return findPreferredDmConversationByUserId(toConversationStoreEntries(map.entries()), id);
+  };
+
+  return {
+    upsert: async (conversationId, reference) => {
+      const normalizedId = normalizeStoredConversationId(conversationId);
+      map.set(
+        normalizedId,
+        mergeStoredConversationReference(
+          map.get(normalizedId),
+          reference,
+          new Date().toISOString(),
+        ),
+      );
+    },
+    get: async (conversationId) => {
+      return map.get(normalizeStoredConversationId(conversationId)) ?? null;
+    },
+    list: async () => {
+      return toConversationStoreEntries(map.entries());
+    },
+    remove: async (conversationId) => {
+      return map.delete(normalizeStoredConversationId(conversationId));
+    },
+    findPreferredDmByUserId,
+    findByUserId: findPreferredDmByUserId,
+  };
+}

package/src/conversation-store.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 = {
+  /** Timestamp when this reference was last seen/updated. */
+  lastSeenAt?: string;
+  /** Activity ID from the last message */
+  activityId?: string;
+  /** Channel thread root activity ID for threaded replies. */
+  threadId?: 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 };
+  /**
+   * Tenant ID sourced from `activity.channelData.tenant.id` at inbound time.
+   * Bot Framework requires this on outbound proactive messages so the connector
+   * can route them to the correct Azure AD tenant; without it, the connector
+   * rejects the request with HTTP 403. For channel activities, `conversation.tenantId`
+   * is often unset, making `channelData.tenant.id` the reliable source.
+   */
+  tenantId?: string;
+  /**
+   * Azure AD object ID of the user who sent the last inbound activity,
+   * mirrored from `activity.from.aadObjectId` so outbound proactive sends
+   * can include it on the connector request (required for personal DMs).
+   */
+  aadObjectId?: 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;
+  /**
+   * Cached Graph API chat ID (format: `19:xxx@thread.tacv2` or `19:xxx@unq.gbl.spaces`).
+   * Bot Framework conversation IDs for personal DMs use a different format (`a:1xxx` or
+   * `8:orgid:xxx`) that the Graph API does not accept. This field caches the resolved
+   * Graph-native chat ID so we don't need to re-query the API on every send.
+   */
+  graphChatId?: string;
+  /** IANA timezone from Teams clientInfo entity (e.g. "America/New_York") */
+  timezone?: 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>;
+  /** Person-targeted proactive lookup: prefer the freshest personal DM reference. */
+  findPreferredDmByUserId: (id: string) => Promise<MSTeamsConversationStoreEntry | null>;
+  /** @deprecated Use `findPreferredDmByUserId` for proactive user-targeted sends. */
+  findByUserId: (id: string) => Promise<MSTeamsConversationStoreEntry | null>;
+};

package/src/directory-live.ts

@@ -0,0 +1,111 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { ChannelDirectoryEntry } from "../runtime-api.js";
+import { searchGraphUsers } from "./graph-users.js";
+import {
+  listChannelsForTeam,
+  listTeamsByName,
+  normalizeQuery,
+  resolveGraphToken,
+} from "./graph.js";
+
+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;
+
+  const users = await searchGraphUsers({ token, query, top: limit });
+
+  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 (
+        !normalizeLowercaseStringOrEmpty(name).includes(
+          normalizeLowercaseStringOrEmpty(channelQuery),
+        )
+      ) {
+        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/doctor.ts

@@ -0,0 +1,27 @@
+import { createDangerousNameMatchingMutableAllowlistWarningCollector } from "autobot/plugin-sdk/channel-policy";
+
+function isMSTeamsMutableAllowEntry(raw: string): boolean {
+  const text = raw.trim();
+  if (!text || text === "*") {
+    return false;
+  }
+
+  const withoutPrefix = text.replace(/^(msteams|user):/i, "").trim();
+  return /\s/.test(withoutPrefix) || withoutPrefix.includes("@");
+}
+
+export const collectMSTeamsMutableAllowlistWarnings =
+  createDangerousNameMatchingMutableAllowlistWarningCollector({
+    channel: "msteams",
+    detector: isMSTeamsMutableAllowEntry,
+    collectLists: (scope) => [
+      {
+        pathLabel: `${scope.prefix}.allowFrom`,
+        list: scope.account.allowFrom,
+      },
+      {
+        pathLabel: `${scope.prefix}.groupAllowFrom`,
+        list: scope.account.groupAllowFrom,
+      },
+    ],
+  });