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

package/README.md

@@ -0,0 +1,341 @@
+# playground-cli
+
+A programmatic simulation library for Microsoft 365 bots/agents. Drive your bot's responses without a browser or manual interaction — ideal for automated testing, CI pipelines, and LLM-based evaluation.
+
+## Installation
+
+The package is part of the monorepo. Link it in your project:
+
+```json
+{
+  "dependencies": {
+    "@microsoft/m365agentsplayground-cli": "file:../../packages/playground-cli"
+  }
+}
+```
+
+Build the package before use:
+
+```bash
+npm run build --workspace=packages/playground-cli
+```
+
+## Quick Start
+
+```typescript
+import { TestClient } from "@microsoft/m365agentsplayground-cli";
+
+const client = new TestClient({
+  botEndpoint: "http://localhost:3978/api/messages",
+});
+
+await client.start();
+const [response] = await client.sendMessage("Hello!");
+console.log(response.text);
+await client.stop();
+```
+
+## API
+
+### TestClient
+
+The main class for interacting with your bot.
+
+```typescript
+new TestClient(config: TestClientConfig)
+```
+
+#### TestClientConfig
+
+| Property       | Type                           | Default    | Description                      |
+| -------------- | ------------------------------ | ---------- | -------------------------------- |
+| `botEndpoint`  | `string`                       | _required_ | Your bot's endpoint URL          |
+| `timeout`      | `number`                       | `5000`     | Response timeout in milliseconds |
+| `bot`          | `BotConfig`                    | -          | Bot identity configuration       |
+| `deliveryMode` | `"expectReplies" \| "default"` | -          | How the bot delivers responses   |
+
+#### BotConfig
+
+| Property        | Type                               | Description                                            |
+| --------------- | ---------------------------------- | ------------------------------------------------------ |
+| `id`            | `string`                           | Bot's unique identifier                                |
+| `name`          | `string`                           | Display name (max 42 chars)                            |
+| `role`          | `"user" \| "bot" \| "agenticUser"` | Bot role                                               |
+| `tenantId`      | `string`                           | Tenant ID (also sets `activity.conversation.tenantId`) |
+| `agenticUserId` | `string`                           | User ID for agentic bots                               |
+| `agenticAppId`  | `string`                           | App ID for agentic bots                                |
+
+#### Methods
+
+| Method                | Returns                  | Description                          |
+| --------------------- | ------------------------ | ------------------------------------ |
+| `start()`             | `Promise<void>`          | Initialize the client                |
+| `stop()`              | `Promise<void>`          | Shut down and clean up               |
+| `sendMessage(text)`   | `Promise<BotResponse[]>` | Send a message, wait for response(s) |
+| `getMessages()`       | `Message[]`              | All messages in the conversation     |
+| `getLastBotMessage()` | `Message \| undefined`   | Most recent bot message              |
+| `getConversationId()` | `string`                 | Current conversation ID              |
+| `newConversation()`   | `void`                   | Reset conversation state             |
+
+#### WebSocket Events
+
+TestClient extends EventEmitter and emits real-time events:
+
+| Event             | Payload                | Description                           |
+| ----------------- | ---------------------- | ------------------------------------- |
+| `message:created` | `ICreateMessageAction` | New message from bot or user          |
+| `message:updated` | `IUpdateMessageAction` | Message was updated (streaming, edit) |
+| `typing`          | `ITypingAction`        | Bot typing indicator                  |
+| `websocket:error` | `Error`                | WebSocket connection error            |
+| `websocket:close` | -                      | WebSocket connection closed           |
+
+### BotResponse
+
+Returned by `sendMessage()`.
+
+| Property      | Type            | Description                                |
+| ------------- | --------------- | ------------------------------------------ |
+| `messageId`   | `string`        | Unique message ID                          |
+| `text`        | `string?`       | Text content                               |
+| `attachments` | `Attachment[]?` | Attachments (Adaptive Cards, etc.)         |
+| `timestamp`   | `number`        | Unix timestamp                             |
+| `raw`         | `Message`       | Raw Message object for detailed inspection |
+
+## Conversation Server
+
+An HTTP wrapper around TestClient so non-Node languages (Python, curl, etc.) can drive bot conversations by POSTing JSON.
+
+```bash
+# From the repo root (after install + build):
+npm run server --workspace=packages/agents-simulator -- --port 9000
+```
+
+Or programmatically:
+
+```typescript
+import { createConversationServer } from "agents-simulator";
+const server = await createConversationServer({ port: 9000 });
+```
+
+### `POST /run-conversation`
+
+Run a multi-turn conversation:
+
+```json
+{
+  "config": {
+    "botEndpoint": "http://localhost:3978/api/messages",
+    "timeout": 120000,
+    "deliveryMode": "expectReplies",
+    "bot": { "id": "bot@tenant.onmicrosoft.com", "name": "My Bot" },
+    "personas": {
+      "alice": { "id": "alice-id", "name": "Alice", "email": "alice@example.com" }
+    }
+  },
+  "scenario": "greeting-test",
+  "input": {
+    "turns": [
+      { "test_id": "t1", "prompt": "Hello!" },
+      { "test_id": "t2", "prompt": "What can you do?" }
+    ]
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "type": "conversation_result",
+  "scenario": "greeting-test",
+  "status": "Completed",
+  "duration_seconds": 4.2,
+  "turns": [
+    {
+      "test_id": "t1",
+      "prompt": "Hello!",
+      "actual_response": "Hi! I'd be happy to help. What do you need?",
+      "status": "Completed",
+      "duration_seconds": 1.8
+    },
+    {
+      "test_id": "t2",
+      "prompt": "What can you do?",
+      "actual_response": "I can help you with...",
+      "status": "Completed",
+      "duration_seconds": 2.4
+    }
+  ]
+}
+```
+
+### Configuration
+
+The `config` object in the request body:
+
+| Field          | Type                            | Default           | Description                           |
+| -------------- | ------------------------------- | ----------------- | ------------------------------------- |
+| `botEndpoint`  | `string`                        | _required_        | Bot's messaging endpoint URL          |
+| `timeout`      | `number`                        | `120000`          | Per-turn response timeout (ms)        |
+| `deliveryMode` | `"expectReplies" \| "default"`  | `"expectReplies"` | How the bot delivers responses        |
+| `chatType`     | `"personal" \| "group" \| "channel"` | `"personal"` | Default chat context for all turns   |
+| `streamingSettleDelayMs` | `number` | `800` | Quiet-period (ms) for streaming bots — see below |
+| `bot`          | `BotConfig`                     | -                 | Bot identity (see above)              |
+| `personas`     | `Record<string, PersonaConfig>` | -                 | Named personas for notification turns |
+
+> **Streaming bots (teams-ai / teams.ts `stream: true`):** When the simulator receives the placeholder `"Loading stream results..."`, it automatically switches into streaming mode. It first waits for a `streamType:"final"` WebSocket event (the precise end-of-stream signal from teams-ai and teams.ts SDK) — this is instant and accurate. If the bot doesn't send `streamType`, it falls back to a quiet-period: waits until no new `updateActivity` events arrive for `streamingSettleDelayMs` ms (default: 800 ms). Increase `streamingSettleDelayMs` only if you have a slow LLM that pauses mid-stream for over 800 ms. For bots with `stream: false` this option has no effect.
+
+### Turn Types
+
+Each turn has an optional `turn_type` that controls what kind of Bot Framework activity is sent:
+
+| Turn type           | Description                                      |
+| ------------------- | ------------------------------------------------ |
+| `"chat"`            | Standard chat message (default)                  |
+| `"sendEmail"`       | Email notification activity                      |
+| `"mentionInWord"`   | Word document mention notification activity      |
+| `"meetingStart"`    | Meeting started event                            |
+| `"meetingEnd"`      | Meeting ended event                              |
+| `"participantJoin"` | Meeting participant joined event                 |
+| `"participantLeave"`| Meeting participant left event                   |
+| `"messageReaction"` | Reaction added to a message (like, heart, etc.)  |
+| `"install"`         | Bot installation update                          |
+| `"userAdded"`       | User added to conversation                       |
+| `"botAdded"`        | Bot added to conversation                        |
+| `"channelCreated"`  | Channel created (team context required)          |
+| `"teamRenamed"`     | Team renamed (team context required)             |
+
+All values from `CustomActivityTemplateType` are supported. You can mix turn types within a single conversation:
+
+```json
+{
+  "input": {
+    "turns": [
+      { "test_id": "t1", "prompt": "Hello", "turn_type": "chat" },
+      {
+        "test_id": "t2",
+        "prompt": "<html><body>Customer complaint about order #789...</body></html>",
+        "turn_type": "sendEmail",
+        "persona": "customer1"
+      },
+      { "test_id": "t3", "prompt": "Summarize the email I just received", "turn_type": "chat" },
+      { "test_id": "t4", "prompt": "", "turn_type": "meetingStart" },
+      { "test_id": "t5", "prompt": "", "turn_type": "messageReaction", "reaction_type": "like" }
+    ]
+  }
+}
+```
+
+#### Turn-specific fields
+
+| Field             | Applies to                      | Description                                              |
+| ----------------- | ------------------------------- | -------------------------------------------------------- |
+| `reaction_type`   | `messageReaction`               | Reaction emoji: `like` (default), `heart`, `laugh`, `surprised`, `sad`, `angry` |
+| `reply_to_id`     | `messageReaction`               | Message ID to react to. Defaults to last bot message.    |
+| `prompt_metadata.meetingTitle` | `meetingStart`, `meetingEnd` | Override the meeting title in the event.        |
+| `prompt_metadata.documentUrl` | `mentionInWord` | Override the document URL.                       |
+| `prompt_metadata.documentName`| `mentionInWord` | Override the document name.                      |
+
+### Chat Types
+
+The `chat_type` field on a turn (or `chatType` in config) controls the conversation context:
+
+| Chat type    | Description                                    |
+| ------------ | ---------------------------------------------- |
+| `"personal"` | 1:1 personal chat with the bot (default)       |
+| `"group"`    | Group chat context                             |
+| `"channel"`  | Team channel context (uses general channel)    |
+
+Set the default for the whole conversation in `config.chatType`, or override per turn with `turn.chat_type`:
+
+```json
+{
+  "config": {
+    "botEndpoint": "http://localhost:3978/api/messages",
+    "chatType": "group"
+  },
+  "scenario": "group-chat-test",
+  "input": {
+    "turns": [
+      { "test_id": "t1", "prompt": "@bot Hello everyone!", "turn_type": "chat" },
+      { "test_id": "t2", "prompt": "Personal follow-up", "turn_type": "chat", "chat_type": "personal" }
+    ]
+  }
+}
+```
+
+### Parallel Testing
+
+Multiple `TestClient` instances in the same process each get a unique `conversationId`, so concurrent tests don't interfere with each other's messages.
+
+To test multiple bot endpoints in parallel, run separate `conversationServer` processes on different ports:
+
+```bash
+# Terminal 1 — bot-a on port 9001
+npm run server --workspace=packages/agents-simulator -- --port 9001
+
+# Terminal 2 — bot-b on port 9002
+npm run server --workspace=packages/agents-simulator -- --port 9002
+```
+
+Then point each test suite at its own server URL.
+
+### Personas
+
+Personas set the `from` identity on notification activities. Define them in `config.personas` and reference by name:
+
+- **Conversation-level default:** Set `input.persona` to apply to all turns
+- **Per-turn override:** Set `turn.persona` to override for a specific turn
+- **Persona fields:** `id` (required), `name` (required), `email` (optional — used as `from.id` when present)
+
+### Turn Result Statuses
+
+| Status      | Description                                     |
+| ----------- | ----------------------------------------------- |
+| `Completed` | Bot responded successfully                      |
+| `TimedOut`  | No response within the configured timeout       |
+| `Errored`   | An error occurred during execution              |
+| `Skipped`   | Turn was skipped because a previous turn failed |
+
+### Example: curl
+
+```bash
+curl http://localhost:9000/health
+
+curl -X POST http://localhost:9000/run-conversation \
+  -H "Content-Type: application/json" \
+  -d '{
+    "config": { "botEndpoint": "http://localhost:3978/api/messages" },
+    "scenario": "smoke-test",
+    "input": { "turns": [{ "test_id": "t1", "prompt": "Hello" }] }
+  }'
+```
+
+### Example: Python
+
+```python
+import requests
+
+resp = requests.post("http://localhost:9000/run-conversation", json={
+    "config": {"botEndpoint": "http://localhost:3978/api/messages"},
+    "scenario": "my-test",
+    "input": {
+        "turns": [
+            {"test_id": "t1", "prompt": "Hello"},
+            {"test_id": "t2", "prompt": "What can you do?"},
+        ]
+    },
+})
+
+for turn in resp.json()["turns"]:
+    print(f"[{turn['status']}] {turn['actual_response'][:80]}")
+```
+
+### `GET /health`
+
+Returns `{ "status": "ok" }`.
+
+## Example Project
+
+See `samples/agents-simulator-example` for a complete example with Mocha tests and a sanity-test script.
+

package/build/cardValidator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Adaptive Card schema validation using the official `adaptivecards` package.
+ *
+ * Validates that a card payload is a well-formed Adaptive Card that Teams can
+ * parse. Does NOT check visual rendering — only structural/schema correctness.
+ */
+export interface CardValidationError {
+    /** Human-readable description of the issue */
+    message: string;
+    /** "parsing" | "schema" */
+    phase: string;
+}
+/**
+ * Validate a raw Adaptive Card JSON payload.
+ * Returns an empty array if the card is valid.
+ */
+export declare function validateAdaptiveCard(payload: Record<string, unknown>): CardValidationError[];
+//# sourceMappingURL=cardValidator.d.ts.map

package/build/cardValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardValidator.d.ts","sourceRoot":"","sources":["../src/cardValidator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAElC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,mBAAmB,EAAE,CAgCvB"}

package/build/cardValidator.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Adaptive Card schema validation using the official `adaptivecards` package.
+ *
+ * Validates that a card payload is a well-formed Adaptive Card that Teams can
+ * parse. Does NOT check visual rendering — only structural/schema correctness.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAdaptiveCard = void 0;
+const adaptivecards_1 = require("adaptivecards");
+/**
+ * Validate a raw Adaptive Card JSON payload.
+ * Returns an empty array if the card is valid.
+ */
+function validateAdaptiveCard(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+payload) {
+    const errors = [];
+    // Basic type guard: must have type === "AdaptiveCard"
+    if (payload.type !== "AdaptiveCard") {
+        errors.push({
+            message: `Expected type "AdaptiveCard", got "${payload.type ?? "(missing)"}"`,
+            phase: "schema",
+        });
+        return errors; // No point parsing further
+    }
+    try {
+        const card = new adaptivecards_1.AdaptiveCard();
+        const context = new adaptivecards_1.SerializationContext();
+        card.parse(payload, context);
+        for (let i = 0; i < context.eventCount; i++) {
+            const event = context.getEventAt(i);
+            errors.push({
+                message: event.message ?? String(event),
+                phase: event.phase !== undefined ? String(event.phase) : "parsing",
+            });
+        }
+    }
+    catch (err) {
+        errors.push({
+            message: err instanceof Error ? err.message : String(err),
+            phase: "parsing",
+        });
+    }
+    return errors;
+}
+exports.validateAdaptiveCard = validateAdaptiveCard;

package/build/conversationServer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP server for multi-turn conversation execution.
+ *
+ * Provides a factory function that creates an HTTP server with:
+ *   POST /run-conversation — execute a multi-turn conversation
+ *   GET  /health           — health check
+ *
+ * All diagnostic logging goes to stderr. The returned port can be
+ * written to stdout by the caller (CLI wrapper).
+ */
+export interface ConversationServerOptions {
+    /** Port to listen on. Default: 0 (OS-assigned). */
+    port?: number;
+    /** Host to bind to. Default: "127.0.0.1". */
+    host?: string;
+}
+export interface ConversationServer {
+    /** The port the server is listening on. */
+    port: number;
+    /** Gracefully shut down the server. */
+    close: () => Promise<void>;
+}
+/**
+ * Create and start a conversation server.
+ *
+ * Returns a handle with the assigned port and a close() method.
+ */
+export declare function createConversationServer(options?: ConversationServerOptions): Promise<ConversationServer>;
+//# sourceMappingURL=conversationServer.d.ts.map

package/build/conversationServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversationServer.d.ts","sourceRoot":"","sources":["../src/conversationServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AA4ED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,kBAAkB,CAAC,CAgC7B"}

package/build/conversationServer.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * HTTP server for multi-turn conversation execution.
+ *
+ * Provides a factory function that creates an HTTP server with:
+ *   POST /run-conversation — execute a multi-turn conversation
+ *   GET  /health           — health check
+ *
+ * All diagnostic logging goes to stderr. The returned port can be
+ * written to stdout by the caller (CLI wrapper).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConversationServer = void 0;
+const http = __importStar(require("http"));
+const runConversation_1 = require("./runConversation");
+// ─────────────────────────────────────────────────────────────────────────────
+// Request body parsing
+// ─────────────────────────────────────────────────────────────────────────────
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+async function handleRequest(req, res) {
+    const url = req.url ?? "";
+    const method = req.method ?? "";
+    if (method === "GET" && url === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+        return;
+    }
+    if (method === "POST" && url === "/run-conversation") {
+        let body;
+        try {
+            const raw = await readBody(req);
+            body = JSON.parse(raw);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: `Invalid JSON: ${message}` }));
+            return;
+        }
+        if (!body.config || !body.scenario || !body.input) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Missing required fields: config, scenario, input" }));
+            return;
+        }
+        try {
+            (0, runConversation_1.log)(`HTTP request: ${body.scenario}`);
+            const result = await (0, runConversation_1.runConversation)(body.config, body.scenario, body.input);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(result));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            (0, runConversation_1.logError)(`Unhandled error in runConversation: ${message}`);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: message }));
+        }
+        return;
+    }
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create and start a conversation server.
+ *
+ * Returns a handle with the assigned port and a close() method.
+ */
+async function createConversationServer(options) {
+    const port = options?.port ?? 0;
+    const host = options?.host ?? "127.0.0.1";
+    const server = http.createServer((req, res) => {
+        handleRequest(req, res).catch((err) => {
+            (0, runConversation_1.logError)(`Request handler crashed: ${String(err)}`);
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+            }
+            res.end(JSON.stringify({ error: "Internal server error" }));
+        });
+    });
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            const addr = server.address();
+            const assignedPort = typeof addr === "object" && addr ? addr.port : port;
+            (0, runConversation_1.log)(`Server listening on http://${host}:${assignedPort}`);
+            resolve({
+                port: assignedPort,
+                close: () => new Promise((res, rej) => {
+                    server.close((err) => (err ? rej(err) : res()));
+                }),
+            });
+        });
+    });
+}
+exports.createConversationServer = createConversationServer;