@gakr-gakr/msteams 0.1.0

package/src/streaming-message.ts

@@ -0,0 +1,327 @@
+/**
+ * Teams streaming message using the streaminfo entity protocol.
+ *
+ * Follows the official Teams SDK pattern:
+ * 1. First chunk → POST a typing activity with streaminfo entity (streamType: "streaming")
+ * 2. Subsequent chunks → POST typing activities with streaminfo + incrementing streamSequence
+ * 3. Finalize → POST a message activity with streaminfo (streamType: "final")
+ *
+ * Uses the shared draft-stream-loop for throttling (avoids rate limits).
+ */
+
+import { createDraftStreamLoop, type DraftStreamLoop } from "autobot/plugin-sdk/channel-lifecycle";
+import { readStringValue } from "autobot/plugin-sdk/string-coerce-runtime";
+
+/** Default throttle interval between stream updates (ms).
+ * Teams docs recommend buffering tokens for 1.5-2s; limit is 1 req/s. */
+const DEFAULT_THROTTLE_MS = 1500;
+
+/** Minimum chars before sending the first streaming message. */
+const MIN_INITIAL_CHARS = 20;
+
+/** Teams message text limit. */
+const TEAMS_MAX_CHARS = 4000;
+
+/**
+ * Stop streaming before Teams expires the content stream server-side.
+ * The exact service limit is opaque, so stay comfortably under it.
+ */
+const MAX_STREAM_AGE_MS = 45_000;
+
+type StreamSendFn = (activity: Record<string, unknown>) => Promise<unknown>;
+
+type TeamsStreamOptions = {
+  /** Function to send an activity (POST to Bot Framework). */
+  sendActivity: StreamSendFn;
+  /** Whether to enable feedback loop on the final message. */
+  feedbackLoopEnabled?: boolean;
+  /** Throttle interval in ms. Default: 600. */
+  throttleMs?: number;
+  /** Called on errors during streaming. */
+  onError?: (err: unknown) => void;
+};
+
+import { AI_GENERATED_ENTITY } from "./ai-entity.js";
+import { formatUnknownError } from "./errors.js";
+
+function extractId(response: unknown): string | undefined {
+  if (response && typeof response === "object" && "id" in response) {
+    return readStringValue((response as { id?: unknown }).id);
+  }
+  return undefined;
+}
+
+function buildStreamInfoEntity(
+  streamId: string | undefined,
+  streamType: "informative" | "streaming" | "final",
+  streamSequence?: number,
+): Record<string, unknown> {
+  const entity: Record<string, unknown> = {
+    type: "streaminfo",
+    streamType,
+  };
+  // streamId is only present after the first chunk (returned by the service)
+  if (streamId) {
+    entity.streamId = streamId;
+  }
+  // streamSequence must be present for start/continue, but NOT for final
+  if (streamSequence != null) {
+    entity.streamSequence = streamSequence;
+  }
+  return entity;
+}
+
+export class TeamsHttpStream {
+  private sendActivity: StreamSendFn;
+  private feedbackLoopEnabled: boolean;
+  private onError?: (err: unknown) => void;
+
+  private accumulatedText = "";
+  private streamId: string | undefined = undefined;
+  private sequenceNumber = 0;
+  private stopped = false;
+  private finalized = false;
+  private streamFailed = false;
+  private lastStreamedText = "";
+  private finalMessageId: string | undefined = undefined;
+  private streamStartedAt: number | undefined = undefined;
+  private loop: DraftStreamLoop;
+
+  constructor(options: TeamsStreamOptions) {
+    this.sendActivity = options.sendActivity;
+    this.feedbackLoopEnabled = options.feedbackLoopEnabled ?? false;
+    this.onError = options.onError;
+
+    this.loop = createDraftStreamLoop({
+      throttleMs: options.throttleMs ?? DEFAULT_THROTTLE_MS,
+      isStopped: () => this.stopped,
+      sendOrEditStreamMessage: (text) => this.pushStreamChunk(text),
+    });
+  }
+
+  /**
+   * Send an informative status update (blue progress bar in Teams).
+   * Call this immediately when a message is received, before LLM starts generating.
+   * Establishes the stream so subsequent chunks continue from this stream ID.
+   */
+  async sendInformativeUpdate(text: string): Promise<void> {
+    if (this.stopped || this.finalized) {
+      return;
+    }
+
+    this.sequenceNumber++;
+
+    const activity: Record<string, unknown> = {
+      type: "typing",
+      text,
+      entities: [buildStreamInfoEntity(this.streamId, "informative", this.sequenceNumber)],
+    };
+
+    try {
+      const response = await this.sendActivity(activity);
+      if (!this.streamId) {
+        this.streamId = extractId(response);
+      }
+    } catch (err) {
+      this.onError?.(err);
+    }
+  }
+
+  /**
+   * Ingest partial text from the LLM token stream.
+   * Called by onPartialReply — accumulates text and throttles updates.
+   */
+  update(text: string): void {
+    if (this.stopped || this.finalized) {
+      return;
+    }
+    this.accumulatedText = text;
+
+    // Wait for minimum chars before first send (avoids push notification flicker)
+    if (!this.streamId && this.accumulatedText.length < MIN_INITIAL_CHARS) {
+      return;
+    }
+
+    // Text exceeded Teams limit — finalize immediately with what we have
+    // so the user isn't left waiting while the LLM keeps generating.
+    if (this.accumulatedText.length > TEAMS_MAX_CHARS) {
+      this.streamFailed = true;
+      void this.finalize();
+      return;
+    }
+
+    // Stop early before Teams expires the stream server-side. finalize() will
+    // close the stream with the last good content, and reply-stream-controller
+    // will deliver any remaining suffix via normal fallback delivery.
+    if (this.streamStartedAt && Date.now() - this.streamStartedAt >= MAX_STREAM_AGE_MS) {
+      this.streamFailed = true;
+      void this.finalize();
+      return;
+    }
+
+    // Don't append cursor — Teams requires each chunk to be a prefix of subsequent chunks.
+    // The cursor character would cause "content should contain previously streamed content" errors.
+    this.loop.update(this.accumulatedText);
+  }
+
+  /**
+   * Replace an informative progress update with final answer text.
+   * Returns false when the stream could not safely carry the final text, so
+   * callers can deliver the answer through the normal Teams message path.
+   */
+  async replaceInformativeWithFinal(text: string): Promise<boolean> {
+    if (this.stopped || this.finalized) {
+      return false;
+    }
+    this.update(text);
+    await this.loop.flush();
+    await this.finalize();
+    return !this.streamFailed && this.hasContent;
+  }
+
+  /**
+   * Finalize the stream — send the final message activity.
+   */
+  async finalize(): Promise<string | undefined> {
+    if (this.finalized) {
+      return this.finalMessageId;
+    }
+    this.finalized = true;
+    this.stopped = true;
+    this.loop.stop();
+    await this.loop.waitForInFlight();
+
+    // If no text was streamed (e.g. agent sent a card via tool instead of
+    // streaming text), just return. Teams auto-clears the informative progress
+    // bar after its streaming timeout. Sending an empty final message fails
+    // with 403.
+    if (!this.accumulatedText.trim()) {
+      return this.finalMessageId;
+    }
+
+    // If streaming failed (>4000 chars or POST errors), close the stream
+    // with the last successfully streamed text so Teams removes the "Stop"
+    // button and replaces the partial chunks. deliver() handles the complete
+    // response since hasContent returns false when streamFailed is true.
+    if (this.streamFailed) {
+      if (this.streamId) {
+        try {
+          const response = await this.sendActivity({
+            type: "message",
+            text: this.lastStreamedText || "",
+            channelData: { feedbackLoopEnabled: this.feedbackLoopEnabled },
+            entities: [AI_GENERATED_ENTITY, buildStreamInfoEntity(this.streamId, "final")],
+          });
+          this.finalMessageId = extractId(response);
+        } catch {
+          // Best effort — stream will auto-close after Teams timeout
+        }
+      }
+      return this.finalMessageId;
+    }
+
+    // Send final message activity.
+    // Per the spec: type=message, streamType=final, NO streamSequence.
+    try {
+      const entities: Array<Record<string, unknown>> = [AI_GENERATED_ENTITY];
+      if (this.streamId) {
+        entities.push(buildStreamInfoEntity(this.streamId, "final"));
+      }
+
+      const finalActivity: Record<string, unknown> = {
+        type: "message",
+        text: this.accumulatedText,
+        channelData: {
+          feedbackLoopEnabled: this.feedbackLoopEnabled,
+        },
+        entities,
+      };
+
+      const response = await this.sendActivity(finalActivity);
+      this.finalMessageId = extractId(response);
+    } catch (err) {
+      this.streamFailed = true;
+      this.onError?.(err);
+    }
+    return this.finalMessageId;
+  }
+
+  /** Whether streaming successfully delivered content (at least one chunk sent, not failed). */
+  get hasContent(): boolean {
+    return this.accumulatedText.length > 0 && !this.streamFailed;
+  }
+
+  /** Whether streaming failed and fallback delivery is needed. */
+  get isFailed(): boolean {
+    return this.streamFailed;
+  }
+
+  /** Number of characters successfully streamed before failure. */
+  get streamedLength(): number {
+    return this.lastStreamedText.length;
+  }
+
+  /** Whether the stream has been finalized. */
+  get isFinalized(): boolean {
+    return this.finalized;
+  }
+
+  /** Platform id returned by the final message activity, when available. */
+  get messageId(): string | undefined {
+    return this.finalMessageId;
+  }
+
+  /** Stream id returned by the first streaminfo activity, when available. */
+  get previewStreamId(): string | undefined {
+    return this.streamId;
+  }
+
+  /** Whether streaming fell back (not used in this implementation). */
+  get isFallback(): boolean {
+    return false;
+  }
+
+  /**
+   * Send a single streaming chunk as a typing activity with streaminfo.
+   * Per the Teams REST API spec:
+   * - First chunk: no streamId, streamSequence=1 → returns 201 with { id: streamId }
+   * - Subsequent chunks: include streamId, increment streamSequence → returns 202
+   */
+  private async pushStreamChunk(text: string): Promise<boolean> {
+    if (this.stopped && !this.finalized) {
+      return false;
+    }
+
+    this.sequenceNumber++;
+
+    const activity: Record<string, unknown> = {
+      type: "typing",
+      text,
+      entities: [buildStreamInfoEntity(this.streamId, "streaming", this.sequenceNumber)],
+    };
+
+    try {
+      const response = await this.sendActivity(activity);
+      if (!this.streamStartedAt) {
+        this.streamStartedAt = Date.now();
+      }
+      if (!this.streamId) {
+        this.streamId = extractId(response);
+      }
+      this.lastStreamedText = text;
+      return true;
+    } catch (err) {
+      const axiosData = (err as { response?: { data?: unknown; status?: number } })?.response;
+      const statusCode = axiosData?.status ?? (err as { statusCode?: number })?.statusCode;
+      const responseBody = axiosData?.data ? JSON.stringify(axiosData.data).slice(0, 300) : "";
+      const msg = formatUnknownError(err);
+      this.onError?.(
+        new Error(
+          `stream POST failed (HTTP ${statusCode ?? "?"}): ${msg}${responseBody ? ` body=${responseBody}` : ""}`,
+        ),
+      );
+      this.streamFailed = true;
+      return false;
+    }
+  }
+}

package/src/thread-parent-context.ts

@@ -0,0 +1,159 @@
+// Parent-message context injection for Teams channel thread replies.
+//
+// When an inbound message arrives as a reply inside a Teams channel thread,
+// the triggering message often makes no sense on its own (for example, a
+// one-word "yes" or "go ahead"). Per-thread session isolation (PR #62713)
+// gives each thread its own session, but the first message in a brand-new
+// thread session still has no parent context.
+//
+// This module fetches the parent message via Graph and prepends a compact
+// `Replying to @sender: …` system event to the next agent turn so the agent
+// knows what is being responded to. Fetches are cached to avoid repeated
+// Graph calls within the same active thread, and per-session dedupe ensures
+// the same parent is not re-injected on every subsequent reply in the
+// thread.
+
+import { fetchChannelMessage, stripHtmlFromTeamsMessage } from "./graph-thread.js";
+import type { GraphThreadMessage } from "./graph-thread.js";
+
+// LRU cache for parent message fetches. Keyed by `teamId:channelId:parentId`.
+// 5-minute TTL and 100-entry cap keep active-thread chatter fast without
+// holding stale data when a thread goes quiet. Eviction uses Map insertion
+// order for LRU semantics (get() re-inserts on hit).
+const PARENT_CACHE_TTL_MS = 5 * 60 * 1000;
+const PARENT_CACHE_MAX = 100;
+
+type ParentCacheEntry = {
+  message: GraphThreadMessage | undefined;
+  expiresAt: number;
+};
+
+const parentCache = new Map<string, ParentCacheEntry>();
+
+// Per-session dedupe: remembers the most recent parent id we injected for a
+// given session key. When the same thread session sees another reply against
+// the same parent, we skip re-enqueueing the identical system event. We keep
+// a small LRU so idle sessions eventually drop out.
+const INJECTED_MAX = 200;
+const injectedParents = new Map<string, string>();
+
+type ThreadParentContextFetcher = (
+  token: string,
+  groupId: string,
+  channelId: string,
+  messageId: string,
+) => Promise<GraphThreadMessage | undefined>;
+
+function touchLru<K, V>(map: Map<K, V>, key: K, value: V, max: number): void {
+  if (map.has(key)) {
+    map.delete(key);
+  } else if (map.size >= max) {
+    // Drop the oldest (first-inserted) entry.
+    const firstKey = map.keys().next().value;
+    if (firstKey !== undefined) {
+      map.delete(firstKey);
+    }
+  }
+  map.set(key, value);
+}
+
+function buildParentCacheKey(groupId: string, channelId: string, parentId: string): string {
+  return `${groupId}\u0000${channelId}\u0000${parentId}`;
+}
+
+/**
+ * Fetch a channel parent message with an LRU+TTL cache.
+ *
+ * Uses the injected `fetchParent` (defaults to `fetchChannelMessage`) so
+ * tests can swap in a stub without mocking the Graph transport.
+ */
+export async function fetchParentMessageCached(
+  token: string,
+  groupId: string,
+  channelId: string,
+  parentId: string,
+  fetchParent: ThreadParentContextFetcher = fetchChannelMessage,
+): Promise<GraphThreadMessage | undefined> {
+  const key = buildParentCacheKey(groupId, channelId, parentId);
+  const now = Date.now();
+  const cached = parentCache.get(key);
+  if (cached && cached.expiresAt > now) {
+    // Refresh LRU ordering on hit.
+    parentCache.delete(key);
+    parentCache.set(key, cached);
+    return cached.message;
+  }
+  const message = await fetchParent(token, groupId, channelId, parentId);
+  touchLru(parentCache, key, { message, expiresAt: now + PARENT_CACHE_TTL_MS }, PARENT_CACHE_MAX);
+  return message;
+}
+
+type ParentContextSummary = {
+  /** Display name of the parent message author, or "unknown". */
+  sender: string;
+  /** Stripped, single-line parent body text (or empty if unresolved). */
+  text: string;
+};
+
+const PARENT_TEXT_MAX_CHARS = 400;
+
+/**
+ * Extract a compact summary (sender + plain-text body) from a Graph parent
+ * message. Returns undefined when the parent cannot be summarized (missing
+ * or blank body).
+ */
+export function summarizeParentMessage(
+  message: GraphThreadMessage | undefined,
+): ParentContextSummary | undefined {
+  if (!message) {
+    return undefined;
+  }
+  const sender =
+    message.from?.user?.displayName ?? message.from?.application?.displayName ?? "unknown";
+  const contentType = message.body?.contentType ?? "text";
+  const raw = message.body?.content ?? "";
+  const text =
+    contentType === "html" ? stripHtmlFromTeamsMessage(raw) : raw.replace(/\s+/g, " ").trim();
+  if (!text) {
+    return undefined;
+  }
+  return {
+    sender,
+    text:
+      text.length > PARENT_TEXT_MAX_CHARS ? `${text.slice(0, PARENT_TEXT_MAX_CHARS - 1)}…` : text,
+  };
+}
+
+/**
+ * Build the single-line `Replying to @sender: body` system event text.
+ * Callers should pass this text to `enqueueSystemEvent` together with a
+ * stable contextKey derived from the parent id.
+ */
+export function formatParentContextEvent(summary: ParentContextSummary): string {
+  return `Replying to @${summary.sender}: ${summary.text}`;
+}
+
+/**
+ * Decide whether a parent context event should be enqueued for the current
+ * session. Returns `false` when we already injected the same parent for this
+ * session recently (prevents re-prepending identical context on every reply
+ * in the thread).
+ */
+export function shouldInjectParentContext(sessionKey: string, parentId: string): boolean {
+  const key = sessionKey;
+  return injectedParents.get(key) !== parentId;
+}
+
+/**
+ * Record that `parentId` was just injected for `sessionKey` so subsequent
+ * replies with the same parent can short-circuit via `shouldInjectParentContext`.
+ */
+export function markParentContextInjected(sessionKey: string, parentId: string): void {
+  touchLru(injectedParents, sessionKey, parentId, INJECTED_MAX);
+}
+
+// Exported for test isolation.
+export function resetThreadParentContextCachesForTest(): void {
+  parentCache.clear();
+  injectedParents.clear();
+}

package/src/token-response.ts

@@ -0,0 +1,11 @@
+export function readAccessToken(value: unknown): string | null {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value && typeof value === "object") {
+    const token =
+      (value as { accessToken?: unknown }).accessToken ?? (value as { token?: unknown }).token;
+    return typeof token === "string" ? token : null;
+  }
+  return null;
+}

package/src/token.ts

@@ -0,0 +1,194 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { privateFileStoreSync } from "autobot/plugin-sdk/security-runtime";
+import type { MSTeamsConfig } from "../runtime-api.js";
+import type { MSTeamsDelegatedTokens } from "./oauth.shared.js";
+import { refreshMSTeamsDelegatedTokens } from "./oauth.token.js";
+import {
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "./secret-input.js";
+import { resolveMSTeamsStorePath } from "./storage.js";
+
+// ── Credential types ───────────────────────────────────────────────────────
+
+export type MSTeamsSecretCredentials = {
+  type: "secret";
+  appId: string;
+  appPassword: string;
+  tenantId: string;
+};
+
+export type MSTeamsFederatedCredentials = {
+  type: "federated";
+  appId: string;
+  tenantId: string;
+  certificatePath?: string;
+  certificateThumbprint?: string;
+  useManagedIdentity?: boolean;
+  managedIdentityClientId?: string;
+};
+
+export type MSTeamsCredentials = MSTeamsSecretCredentials | MSTeamsFederatedCredentials;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function resolveAuthType(cfg?: MSTeamsConfig): "secret" | "federated" {
+  const fromCfg = cfg?.authType;
+  if (fromCfg === "secret" || fromCfg === "federated") {
+    return fromCfg;
+  }
+
+  const fromEnv = process.env.MSTEAMS_AUTH_TYPE;
+  if (fromEnv === "federated") {
+    return "federated";
+  }
+
+  return "secret";
+}
+
+// ── hasConfiguredMSTeamsCredentials ────────────────────────────────────────
+
+export function hasConfiguredMSTeamsCredentials(cfg?: MSTeamsConfig): boolean {
+  const authType = resolveAuthType(cfg);
+
+  const hasAppId = Boolean(
+    normalizeSecretInputString(cfg?.appId) ||
+    normalizeSecretInputString(process.env.MSTEAMS_APP_ID),
+  );
+  const hasTenantId = Boolean(
+    normalizeSecretInputString(cfg?.tenantId) ||
+    normalizeSecretInputString(process.env.MSTEAMS_TENANT_ID),
+  );
+
+  if (authType === "federated") {
+    const hasCert = Boolean(cfg?.certificatePath || process.env.MSTEAMS_CERTIFICATE_PATH);
+    const hasManagedIdentity =
+      cfg?.useManagedIdentity ?? process.env.MSTEAMS_USE_MANAGED_IDENTITY === "true";
+
+    return hasAppId && hasTenantId && (hasCert || hasManagedIdentity);
+  }
+
+  // "secret" (default) — original logic
+  return Boolean(
+    normalizeSecretInputString(cfg?.appId) &&
+    hasConfiguredSecretInput(cfg?.appPassword) &&
+    normalizeSecretInputString(cfg?.tenantId),
+  );
+}
+
+// ── resolveMSTeamsCredentials ─────────────────────────────────────────────
+
+export function resolveMSTeamsCredentials(cfg?: MSTeamsConfig): MSTeamsCredentials | undefined {
+  const authType = resolveAuthType(cfg);
+
+  const appId =
+    normalizeSecretInputString(cfg?.appId) ||
+    normalizeSecretInputString(process.env.MSTEAMS_APP_ID);
+
+  const tenantId =
+    normalizeSecretInputString(cfg?.tenantId) ||
+    normalizeSecretInputString(process.env.MSTEAMS_TENANT_ID);
+
+  if (!appId || !tenantId) {
+    return undefined;
+  }
+
+  if (authType === "federated") {
+    const certificatePath =
+      cfg?.certificatePath || process.env.MSTEAMS_CERTIFICATE_PATH || undefined;
+
+    const certificateThumbprint =
+      cfg?.certificateThumbprint || process.env.MSTEAMS_CERTIFICATE_THUMBPRINT || undefined;
+
+    const useManagedIdentity =
+      cfg?.useManagedIdentity ?? process.env.MSTEAMS_USE_MANAGED_IDENTITY === "true";
+
+    const managedIdentityClientId =
+      cfg?.managedIdentityClientId || process.env.MSTEAMS_MANAGED_IDENTITY_CLIENT_ID || undefined;
+
+    // At least one federated mechanism must be configured.
+    if (!certificatePath && !useManagedIdentity) {
+      return undefined;
+    }
+
+    return {
+      type: "federated",
+      appId,
+      tenantId,
+      certificatePath,
+      certificateThumbprint,
+      useManagedIdentity: useManagedIdentity || undefined,
+      managedIdentityClientId,
+    };
+  }
+
+  // "secret" (default) — original logic
+  const appPassword =
+    normalizeResolvedSecretInputString({
+      value: cfg?.appPassword,
+      path: "channels.msteams.appPassword",
+    }) || normalizeSecretInputString(process.env.MSTEAMS_APP_PASSWORD);
+
+  if (!appPassword) {
+    return undefined;
+  }
+
+  return { type: "secret", appId, appPassword, tenantId };
+}
+
+// ---------------------------------------------------------------------------
+// Delegated token storage / resolution
+// ---------------------------------------------------------------------------
+
+const DELEGATED_TOKEN_FILENAME = "msteams-delegated.json";
+
+function resolveDelegatedTokenPath(): string {
+  return resolveMSTeamsStorePath({ filename: DELEGATED_TOKEN_FILENAME });
+}
+
+export function loadDelegatedTokens(): MSTeamsDelegatedTokens | undefined {
+  try {
+    const content = readFileSync(resolveDelegatedTokenPath(), "utf8");
+    return JSON.parse(content) as MSTeamsDelegatedTokens;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveDelegatedTokens(tokens: MSTeamsDelegatedTokens): void {
+  const tokenPath = resolveDelegatedTokenPath();
+  privateFileStoreSync(dirname(tokenPath)).writeJson(basename(tokenPath), tokens);
+}
+
+export async function resolveDelegatedAccessToken(params: {
+  tenantId: string;
+  clientId: string;
+  clientSecret: string;
+}): Promise<string | undefined> {
+  const tokens = loadDelegatedTokens();
+  if (!tokens) {
+    return undefined;
+  }
+
+  // Token still valid (5-min buffer already baked into expiresAt)
+  if (tokens.expiresAt > Date.now()) {
+    return tokens.accessToken;
+  }
+
+  // Attempt refresh
+  try {
+    const refreshed = await refreshMSTeamsDelegatedTokens({
+      tenantId: params.tenantId,
+      clientId: params.clientId,
+      clientSecret: params.clientSecret,
+      refreshToken: tokens.refreshToken,
+      scopes: tokens.scopes,
+    });
+    saveDelegatedTokens(refreshed);
+    return refreshed.accessToken;
+  } catch {
+    return undefined;
+  }
+}