fix(qa): accept rich Telegram canary presence

vincentkoc · vincentkoc · commit 47759c35063c · 2026-06-14T07:20:16.000+08:00
(cherry picked from commit e86eb75)
diff --git a/extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.test.ts b/extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.test.ts
@@ -321,6 +321,58 @@ describe("telegram live qa runtime", () => {
         },
       })?.text,
     ).toBe("<b>hello</b> rich");
+
+    expect(
+      testing.normalizeTelegramObservedMessage({
+        update_id: 10,
+        message: {
+          message_id: 12,
+          date: 1_700_000_003,
+          rich_message: {
+            blocks: [
+              {
+                type: "paragraph",
+                text: ["hello ", { type: "bold", text: "rich" }],
+              },
+              {
+                type: "footer",
+                text: { type: "italic", text: "footer" },
+              },
+            ],
+          },
+          chat: { id: -100123 },
+          from: {
+            id: 88,
+            is_bot: true,
+            username: "sut_bot",
+          },
+        },
+      })?.text,
+    ).toBe("hello rich\nfooter");
+
+    expect(
+      testing.normalizeTelegramObservedMessage({
+        update_id: 11,
+        message: {
+          message_id: 13,
+          date: 1_700_000_004,
+          rich_message: {
+            blocks: [
+              {
+                type: "table",
+                cells: [[{ text: "Open" }, { text: "Claw" }], [{ text: "release" }]],
+              },
+            ],
+          },
+          chat: { id: -100123 },
+          from: {
+            id: 88,
+            is_bot: true,
+            username: "sut_bot",
+          },
+        },
+      })?.text,
+    ).toBe("Open\tClaw\nrelease");
   });
 
   it("ignores unrelated sut replies when matching the canary response", () => {
@@ -389,6 +441,27 @@ describe("telegram live qa runtime", () => {
     ).toBe("match");
   });
 
+  it("keeps scenario text checks strict while allowing canary presence replies", () => {
+    const message = {
+      updateId: 3,
+      messageId: 11,
+      chatId: -100123,
+      senderId: 88,
+      senderIsBot: true,
+      senderUsername: "sut_bot",
+      text: "",
+      replyToMessageId: 55,
+      timestamp: 1_700_000_002_000,
+      inlineButtons: [],
+      mediaKinds: [],
+    };
+
+    expect(() => testing.assertTelegramScenarioReply({ message })).toThrow(
+      "reply message 11 was empty",
+    );
+    expect(() => testing.assertTelegramCanaryPresenceReply(message)).not.toThrow();
+  });
+
   it("fails when any requested Telegram scenario id is unknown", () => {
     expect(() => testing.findScenario(["telegram-help-command", "typo-scenario"])).toThrow(
       "unknown Telegram QA scenario id(s): typo-scenario",
diff --git a/extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts b/extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts
@@ -206,6 +206,7 @@ type TelegramReplyMarkup = {
 type TelegramRichMessage = {
   markdown?: string;
   html?: string;
+  blocks?: unknown[];
 };
 
 type TelegramMessage = {
@@ -703,13 +704,99 @@ function detectMediaKinds(message: TelegramMessage) {
   return kinds;
 }
 
+function flattenTelegramRichText(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((part) => flattenTelegramRichText(part)).join("");
+  }
+  if (!isRecord(value)) {
+    return "";
+  }
+  if ("text" in value) {
+    return flattenTelegramRichText(value.text);
+  }
+  if (typeof value.alternative_text === "string") {
+    return value.alternative_text;
+  }
+  if (typeof value.expression === "string") {
+    return value.expression;
+  }
+  return "";
+}
+
+function flattenTelegramRichBlock(value: unknown): string {
+  if (typeof value === "string" || Array.isArray(value)) {
+    return flattenTelegramRichText(value);
+  }
+  if (!isRecord(value)) {
+    return "";
+  }
+  const parts: string[] = [];
+  if ("text" in value) {
+    parts.push(flattenTelegramRichText(value.text));
+  }
+  if ("summary" in value) {
+    parts.push(flattenTelegramRichText(value.summary));
+  }
+  if (typeof value.label === "string") {
+    parts.push(value.label);
+  }
+  if (typeof value.expression === "string") {
+    parts.push(value.expression);
+  }
+  if ("blocks" in value) {
+    parts.push(flattenTelegramRichBlocks(value.blocks));
+  }
+  if ("items" in value) {
+    parts.push(flattenTelegramRichBlocks(value.items));
+  }
+  if ("cells" in value) {
+    parts.push(flattenTelegramRichTableCells(value.cells));
+  }
+  if ("caption" in value) {
+    parts.push(flattenTelegramRichBlock(value.caption));
+  }
+  if ("credit" in value) {
+    parts.push(flattenTelegramRichText(value.credit));
+  }
+  return parts.filter((part) => part.trim()).join("\n");
+}
+
+function flattenTelegramRichBlocks(value: unknown): string {
+  const blocks = Array.isArray(value) ? value : [value];
+  return blocks
+    .map((block) => flattenTelegramRichBlock(block))
+    .filter((part) => part.trim())
+    .join("\n");
+}
+
+function flattenTelegramRichTableCells(value: unknown): string {
+  if (!Array.isArray(value)) {
+    return flattenTelegramRichBlock(value);
+  }
+  return value
+    .map((row) => {
+      const cells = Array.isArray(row) ? row : [row];
+      return cells
+        .map((cell) => flattenTelegramRichBlock(cell))
+        .filter((cell) => cell.trim())
+        .join("\t");
+    })
+    .filter((row) => row.trim())
+    .join("\n");
+}
+
+function selectTelegramRichMessageText(richMessage: TelegramRichMessage | undefined) {
+  return (
+    richMessage?.markdown || richMessage?.html || flattenTelegramRichBlocks(richMessage?.blocks)
+  );
+}
+
 function selectTelegramObservedText(message: TelegramMessage) {
   return (
-    message.text ||
-    message.caption ||
-    message.rich_message?.markdown ||
-    message.rich_message?.html ||
-    ""
+    message.text || message.caption || selectTelegramRichMessageText(message.rich_message) || ""
   );
 }
 
@@ -911,6 +998,7 @@ async function waitForObservedMessage(params: {
   observationScenarioId: string;
   observationScenarioTitle: string;
   expectedTextIncludes?: string[];
+  validateMatchedMessage?: (message: TelegramObservedMessage) => void;
 }) {
   const startedAt = Date.now();
   let offset = params.initialOffset;
@@ -963,10 +1051,14 @@ async function waitForObservedMessage(params: {
       params.observedMessages.push(observedMessage);
       if (matchedScenario) {
         try {
-          assertTelegramScenarioReply({
-            expectedTextIncludes: params.expectedTextIncludes,
-            message: observedMessage,
-          });
+          if (params.validateMatchedMessage) {
+            params.validateMatchedMessage(observedMessage);
+          } else {
+            assertTelegramScenarioReply({
+              expectedTextIncludes: params.expectedTextIncludes,
+              message: observedMessage,
+            });
+          }
         } catch (error) {
           lastExpectedMismatch =
             error instanceof Error ? error : new Error(formatErrorMessage(error));
@@ -1330,6 +1422,15 @@ function assertTelegramScenarioReply(params: {
   }
 }
 
+function assertTelegramCanaryPresenceReply(message: TelegramObservedMessage) {
+  if (!message.senderIsBot) {
+    throw new Error(`canary reply message ${message.messageId} was not sent by a bot`);
+  }
+  // Telegram rich-message updates can arrive to the driver bot with no text
+  // body. The release canary proves command delivery plus threaded SUT output;
+  // text assertions stay on explicit command/scenario checks.
+}
+
 function isTelegramObservedMessageTimeoutError(error: unknown, timeoutMs: number) {
   return formatErrorMessage(error).startsWith(
     `timed out after ${timeoutMs}ms waiting for Telegram message`,
@@ -1451,6 +1552,7 @@ async function runCanary(params: {
       observedMessages: params.observedMessages,
       observationScenarioId: "telegram-canary",
       observationScenarioTitle: "Telegram canary",
+      validateMatchedMessage: assertTelegramCanaryPresenceReply,
       predicate: (message) => {
         const classification = classifyCanaryReply({
           message,
@@ -1497,18 +1599,6 @@ async function runCanary(params: {
       },
     );
   }
-  if (!sutObserved.message.text.trim()) {
-    throw new TelegramQaCanaryError(
-      "sut_reply_empty",
-      "SUT bot replied to the canary message but the reply text was empty.",
-      {
-        groupId: params.groupId,
-        sutBotId: params.sutBotId,
-        driverMessageId: driverMessage.message_id,
-        sutMessageId: sutObserved.message.messageId,
-      },
-    );
-  }
   return {
     requestStartedAt,
     responseObservedAt: new Date(sutObserved.observedAtMs).toISOString(),
@@ -2096,6 +2186,7 @@ export const testing = {
   buildObservedMessagesArtifact,
   canaryFailureMessage,
   callTelegramApi,
+  assertTelegramCanaryPresenceReply,
   assertTelegramScenarioMessageSet,
   isRecoverableTelegramQaPollError,
   assertTelegramScenarioReply,
