@microsoft/m365agentsplayground-cli 0.2.25-alpha.20260507-efe1416.0

package/src/conversationTypes.ts

@@ -0,0 +1,169 @@
+/**
+ * Type definitions for multi-turn conversation execution.
+ */
+
+import type { BotConfig } from "./types";
+import type { CustomActivityTemplateType } from "schema";
+import type { CardValidationError } from "./cardValidator";
+
+/**
+ * Identity for a user persona in notification activities.
+ */
+export interface PersonaConfig {
+  id: string;
+  name: string;
+  email?: string;
+}
+
+/**
+ * Server configuration passed per /run-conversation request.
+ */
+export interface E2EConfig {
+  /** Bot endpoint URL (e.g., "http://localhost:3978/api/messages") */
+  botEndpoint: string;
+
+  /** Response timeout in milliseconds (default: 120000) */
+  timeout?: number;
+
+  /** Activity delivery mode (default: "expectReplies") */
+  deliveryMode?: "expectReplies" | "default";
+
+  /** Bot identity configuration */
+  bot?: BotConfig;
+
+  /** Named personas for notification activities */
+  personas?: Record<string, PersonaConfig>;
+
+  /**
+   * Default chat context for all "chat" turns in this conversation.
+   * Can be overridden per-turn via turn.chat_type.
+   * Default: "personal"
+   */
+  chatType?: "personal" | "group" | "channel";
+
+  /**
+   * Quiet-period fallback (ms) for streaming responses.
+   * Primary: resolves on streamType:"final" event (teams-ai / teams.ts SDK).
+   * Fallback: resolves after this many ms with no new updateActivity calls.
+   * Default: 800. Has no effect for bots with stream: false.
+   */
+  streamingSettleDelayMs?: number;
+}
+
+/**
+ * A single turn to execute in a conversation.
+ */
+export interface Turn {
+  /** Unique identifier for this turn */
+  test_id: string;
+
+  /** Message text or notification body to send */
+  prompt: string;
+
+  /**
+   * Activity type. Default: "chat" (standard message).
+   * Any CustomActivityTemplateType value (e.g., "sendEmail", "mentionInWord", "meetingStart")
+   * sends the corresponding notification activity.
+   */
+  turn_type?: "chat" | "card_action" | CustomActivityTemplateType;
+
+  /**
+   * Chat context for "chat" turn_type. Default: "personal".
+   * - "personal": 1:1 personal chat (default)
+   * - "group": group chat
+   * - "channel": team channel
+   */
+  chat_type?: "personal" | "group" | "channel";
+
+  /** Persona name override for this turn (looks up in config.personas) */
+  persona?: string;
+
+  /** Extra metadata for the turn */
+  prompt_metadata?: Record<string, string>;
+
+  /**
+   * For "messageReaction" turn_type: the reaction emoji.
+   * Defaults to "like". Options: like, heart, laugh, surprised, sad, angry.
+   */
+  reaction_type?: "like" | "heart" | "laugh" | "surprised" | "sad" | "angry";
+
+  /**
+   * For "messageReaction" turn_type: the message ID to react to.
+   * If omitted, reacts to the last bot message in the conversation.
+   */
+  reply_to_id?: string;
+
+  /**
+   * For "card_action" turn_type: simulate clicking an Adaptive Card button.
+   * The server must already have a card message in this conversation to target.
+   */
+  card_action?: {
+    /**
+     * The verb of the Action.Execute button to click (required for Action.Execute).
+     */
+    verb?: string;
+    /**
+     * Data payload to send with the action (merged with button's own data).
+     */
+    data?: Record<string, unknown>;
+    /**
+     * test_id of the turn whose first bot response card to target.
+     * If omitted, uses the last bot message that has an attachment.
+     */
+    reply_to_turn?: string;
+    /**
+     * Action type. Default: "Action.Execute".
+     * Use "Action.Submit" for legacy bots.
+     */
+    action_type?: "Action.Execute" | "Action.Submit";
+  };
+}
+
+/**
+ * Input for a single conversation: a list of turns to execute sequentially.
+ */
+export interface ConversationInput {
+  /** Default persona for all turns */
+  persona?: string;
+
+  /** Ordered turns to execute */
+  turns: Turn[];
+}
+
+/**
+ * A single validated Adaptive Card attachment returned with a turn result.
+ */
+export interface TurnAttachment {
+  /** Attachment content type (e.g. "application/vnd.microsoft.card.adaptive") */
+  contentType: string;
+  /** The raw card JSON content */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  content: Record<string, unknown>;
+  /** Schema validation errors for this card. Empty array means valid. */
+  card_errors: CardValidationError[];
+}
+
+/**
+ * Result of a single turn execution.
+ */
+export interface TurnResult {
+  test_id: string;
+  prompt: string;
+  actual_response: string | null;
+  /** Adaptive Card attachments returned by the bot this turn, with validation results */
+  attachments: TurnAttachment[];
+  status: "Completed" | "TimedOut" | "Errored" | "Skipped";
+  error_message?: string;
+  duration_seconds: number;
+}
+
+/**
+ * Result of a full conversation execution.
+ */
+export interface ConversationResult {
+  type: "conversation_result";
+  scenario: string;
+  status: "Completed" | "TimedOut" | "Errored";
+  duration_seconds: number;
+  turns: TurnResult[];
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+export { TestClient } from "./testClient";
+export { ServerManager } from "./serverManager";
+export { ResponseCapture } from "./responseCapture";
+export type { TestClientConfig, BotConfig, BotResponse, PendingResponse } from "./types";
+
+// Re-export WebSocket event types for consumers
+export { ActionType, LogActionType } from "./types";
+export type {
+  IAction,
+  ICreateMessageAction,
+  IUpdateMessageAction,
+  ITypingAction,
+  IActionMessage,
+  // Log action types
+  ILogAction,
+  IAppendLogAction,
+  LogItem,
+} from "./types";
+
+// Conversation runner
+export { runConversation, log, logError } from "./runConversation";
+export { sendNotificationAndWait } from "./notificationSender";
+export { createConversationServer } from "./conversationServer";
+export type { ConversationServer, ConversationServerOptions } from "./conversationServer";
+export type {
+  E2EConfig,
+  PersonaConfig,
+  Turn,
+  TurnAttachment,
+  ConversationInput,
+  TurnResult,
+  ConversationResult,
+} from "./conversationTypes";
+
+// Adaptive Card validation
+export { validateAdaptiveCard } from "./cardValidator";
+export type { CardValidationError } from "./cardValidator";

package/src/notificationSender.ts

@@ -0,0 +1,135 @@
+/**
+ * Notification sender for multi-turn conversation execution.
+ *
+ * Sends custom notification activities through the playground's Factory
+ * infrastructure and polls ConversationManager for bot responses.
+ */
+
+import { Factory } from "server";
+import type { CustomActivityTemplateType } from "schema";
+import type { PersonaConfig, Turn } from "./conversationTypes";
+
+const POLL_INTERVAL_MS = 200;
+
+function log(msg: string): void {
+  process.stderr.write(`[notification] ${msg}\n`);
+}
+
+/**
+ * Send a notification activity and wait for the bot's response.
+ *
+ * The turn's turn_type must be a valid CustomActivityTemplateType
+ * (e.g., "sendEmail", "mentionInWord"). It is passed directly to
+ * the playground's CustomActivityService.
+ */
+export async function sendNotificationAndWait(
+  conversationId: string,
+  turn: Turn,
+  persona: PersonaConfig | undefined,
+  timeout: number
+): Promise<string> {
+  const templateType = turn.turn_type as CustomActivityTemplateType;
+  const customActivityService = Factory.getCustomActivityService();
+  const accessor = Factory.getBaseUserBotAccessor();
+  const conversationManager = Factory.getConversationManager();
+
+  // Count existing messages before sending.
+  const messagesBefore = conversationManager.listMessages(conversationId);
+  const countBefore = messagesBefore.length;
+
+  // Generate the activity template as a mutable plain object.
+  const template = customActivityService.generateTemplate(conversationId, templateType) as Record<
+    string,
+    unknown
+  >;
+
+  // Override the from field if a persona is provided.
+  if (persona) {
+    const from = (template.from ?? {}) as Record<string, unknown>;
+    template.from = {
+      ...from,
+      id: persona.email ?? persona.id,
+      name: persona.name,
+    };
+  }
+
+  // Customize the activity body based on turn type.
+  if (templateType === "sendEmail") {
+    const entities = template.entities as Array<Record<string, unknown>> | undefined;
+    const emailEntity = entities?.find((e) => e.type === "emailNotification");
+    if (emailEntity) {
+      emailEntity.htmlBody = turn.prompt;
+    }
+  } else if (templateType === "mentionInWord") {
+    template.text = turn.prompt;
+    if (turn.prompt_metadata?.documentUrl) {
+      const attachments = template.attachments as Array<Record<string, unknown>> | undefined;
+      if (attachments?.[0]) {
+        attachments[0].contentUrl = turn.prompt_metadata.documentUrl;
+      }
+    }
+    if (turn.prompt_metadata?.documentName) {
+      const attachments = template.attachments as Array<Record<string, unknown>> | undefined;
+      if (attachments?.[0]) {
+        attachments[0].name = turn.prompt_metadata.documentName;
+      }
+    }
+  } else if (templateType === "meetingStart" || templateType === "meetingEnd") {
+    if (turn.prompt_metadata?.meetingTitle) {
+      const value = (template.value ?? {}) as Record<string, unknown>;
+      value.Title = turn.prompt_metadata.meetingTitle;
+      template.value = value;
+    }
+  } else if (templateType === "participantJoin" || templateType === "participantLeave") {
+    if (turn.prompt) {
+      const value = (template.value ?? {}) as Record<string, unknown>;
+      const members = (value.members ?? []) as Array<Record<string, unknown>>;
+      if (members[0]) {
+        const user = (members[0].user ?? {}) as Record<string, unknown>;
+        user.name = turn.prompt;
+        members[0].user = user;
+        value.members = members;
+        template.value = value;
+      }
+    }
+  } else if (templateType === "messageReaction") {
+    const reaction = turn.reaction_type ?? "like";
+    template.reactionsAdded = [{ type: reaction }];
+    template.reactionsRemoved = [];
+    if (turn.reply_to_id) {
+      template.replyToId = turn.reply_to_id;
+    } else {
+      // Default: react to last bot message
+      const messages = conversationManager.listMessages(conversationId);
+      const lastBotMsg = [...messages].reverse().find((m) => m.createdBy === "bot");
+      if (lastBotMsg) {
+        template.replyToId = lastBotMsg.content.id;
+      }
+    }
+  }
+
+  log(`Sending ${templateType} activity to conversation ${conversationId}`);
+
+  // sendActivity expects the Activity class from the server's dependency tree.
+  // We cast through unknown to bridge the inferred template type.
+  await accessor.sendActivity(template as Parameters<typeof accessor.sendActivity>[0]);
+
+  // Poll for new bot messages.
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const messages = conversationManager.listMessages(conversationId);
+    const newBotMessages = messages.slice(countBefore).filter((m) => m.createdBy === "bot");
+
+    if (newBotMessages.length > 0) {
+      const responseText = newBotMessages
+        .map((m) => m.content.text ?? "")
+        .filter((t) => t.length > 0)
+        .join("\n\n");
+      return responseText;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+
+  throw new Error(`Timeout waiting for bot response to ${templateType} after ${timeout}ms`);
+}

package/src/responseCapture.ts

@@ -0,0 +1,145 @@
+import { BotConnectorService, ConversationManager, Message } from "server";
+import type { CreateActivity } from "server";
+import { PendingResponse } from "./types";
+
+/**
+ * Captures bot responses by hooking into BotConnectorService.processActivity
+ */
+export class ResponseCapture {
+  private pendingResponses: Map<string, PendingResponse> = new Map();
+  private originalProcessActivity?: typeof BotConnectorService.prototype.processActivity;
+
+  /**
+   * Hook into BotConnectorService to intercept responses
+   */
+  hookIntoBotConnectorService(service: BotConnectorService): void {
+    if (this.originalProcessActivity) {
+      // Already hooked
+      return;
+    }
+
+    this.originalProcessActivity = service.processActivity.bind(service);
+
+    service.processActivity = async (
+      conversationId: string,
+      activity: CreateActivity
+    ): Promise<{ resIds: string[]; shouldRespond: boolean; statusCode: number }> => {
+      if (this.originalProcessActivity === undefined) {
+        throw new Error("BotConnectorService.processActivity is undefined");
+      }
+
+      try {
+        const result = await this.originalProcessActivity(conversationId, activity);
+
+        // Only resolve waiting when an actual message was created (resIds non-empty).
+        // Typing indicators and trace activities return resIds:[] and must NOT
+        // resolve the waiting promise prematurely.
+        if (result.resIds.length > 0) {
+          this.resolveWaiting(conversationId);
+        }
+
+        return result;
+      } catch (error) {
+        // Log the error for debugging — this is the actual error that causes 500s
+        // when the bot POSTs back to the connector.
+        console.error(
+          `[ResponseCapture] processActivity error for conversation ${conversationId}:`,
+          error
+        );
+        const activityAny = activity as Record<string, unknown>;
+        const entities = Array.isArray(activityAny.entities) ? activityAny.entities : [];
+        console.error(
+          `[ResponseCapture] Activity type: ${String(activityAny.type)}, ` +
+            `entities: ${JSON.stringify(entities.map((e: Record<string, unknown>) => e.type))}`
+        );
+
+        // Still resolve waiting on error — the test should see whatever messages
+        // were created before the error, rather than timing out silently.
+        this.resolveWaiting(conversationId);
+
+        throw error;
+      }
+    };
+  }
+
+  /**
+   * Wait for a response in the given conversation
+   */
+  async waitForResponse(
+    conversationId: string,
+    conversationManager: ConversationManager,
+    timeout: number
+  ): Promise<Message[]> {
+    const messageCountBefore = conversationManager.listMessages(conversationId).length;
+
+    return new Promise<Message[]>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingResponses.delete(conversationId);
+        // Check one more time before rejecting
+        const messages = conversationManager.listMessages(conversationId);
+        const newMessages = messages.slice(messageCountBefore);
+        const botMessages = newMessages.filter((m) => m.createdBy === "bot");
+        if (botMessages.length > 0) {
+          resolve(botMessages);
+        } else {
+          reject(new Error(`Timeout waiting for bot response after ${timeout}ms`));
+        }
+      }, timeout);
+
+      this.pendingResponses.set(conversationId, {
+        resolve: (messages: Message[]) => {
+          clearTimeout(timer);
+          resolve(messages);
+        },
+        reject,
+        timer,
+        messageCountBefore,
+      });
+    });
+  }
+
+  /**
+   * Resolve waiting promises when a response arrives
+   */
+  private resolveWaiting(conversationId: string): void {
+    const pending = this.pendingResponses.get(conversationId);
+    if (!pending) {
+      return;
+    }
+
+    // Use setImmediate to allow the message to be stored first
+    setImmediate(() => {
+      // The pending might have been removed by timeout
+      if (!this.pendingResponses.has(conversationId)) {
+        return;
+      }
+
+      // We don't have direct access to conversationManager here,
+      // so we just signal completion. The TestClient will check for new messages.
+      this.pendingResponses.delete(conversationId);
+      clearTimeout(pending.timer);
+      pending.resolve([]);
+    });
+  }
+
+  /**
+   * Clear all pending responses
+   */
+  clear(): void {
+    this.pendingResponses.forEach((pending) => {
+      clearTimeout(pending.timer);
+    });
+    this.pendingResponses.clear();
+  }
+
+  /**
+   * Clear pending responses for a specific conversation only
+   */
+  clearConversation(conversationId: string): void {
+    const pending = this.pendingResponses.get(conversationId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pendingResponses.delete(conversationId);
+    }
+  }
+}