switchroom 0.7.15 → 0.10.0

package/telegram-plugin/uat/assertions.ts

@@ -68,71 +68,298 @@ export async function expectEventually(
   });
 }
 
-// ---------- Phase 2 stubs ----------
+// ---------- Phase 2a (DM smoke) ----------
+
+export interface ExpectMessageOptions extends PollOptions {
+  threadId?: number;
+  /**
+   * Filter the observed stream by sender. `userId` matches exact
+   * senders; `notUserId` excludes a specific sender (used by the
+   * harness to translate `from: "bot"` into "anyone but the driver").
+   */
+  senderFilter?: { userId: number } | { notUserId: number };
+}
 
 /**
- * TODO(#866): wait for the bot to send a message in `chatId`/topic
- * matching `match` (substring, regex, or predicate over the raw
- * `ObservedMessage`). Returns the matched message.
+ * Wait for the next message in `chatId` (optionally a forum topic)
+ * matching `match` — a substring, regex, or predicate over the raw
+ * `ObservedMessage`. Returns the matched message.
+ *
+ * The implementation iterates the live `driver.observeMessages`
+ * stream, so messages sent *before* the call started are not
+ * considered; backfill is a Phase 2b helper.
  */
 export async function expectMessage(
-  _driver: Driver,
-  _chatId: number,
-  _match: string | RegExp | ((m: ObservedMessage) => boolean),
-  _opts: PollOptions & { threadId?: number; from?: "bot" | "user" },
+  driver: Driver,
+  chatId: number,
+  match: string | RegExp | ((m: ObservedMessage) => boolean),
+  opts: ExpectMessageOptions,
 ): Promise<ObservedMessage> {
-  throw new Error("expectMessage not implemented (Phase 2)");
+  const predicate = compileMatcher(match);
+  const senderOk = compileSenderFilter(opts.senderFilter);
+  const iter = driver.observeMessages(chatId, opts.threadId !== undefined ? { threadId: opts.threadId } : undefined)[Symbol.asyncIterator]();
+  const deadline = Date.now() + opts.timeout;
+
+  try {
+    while (Date.now() < deadline) {
+      // Race the next observation against the remaining timeout so
+      // we don't hang forever if no messages arrive.
+      const remaining = deadline - Date.now();
+      const next = await raceTimeout(iter.next(), remaining);
+      if (next === "timeout") break;
+      if (next.done === true) break;
+      const msg = next.value;
+      if (!senderOk(msg)) continue;
+      if (predicate(msg)) return msg;
+    }
+  } finally {
+    await iter.return?.();
+  }
+  throw new Error(
+    `expectMessage: no matching message in chat=${chatId} within ${opts.timeout}ms`,
+  );
+}
+
+function compileMatcher(
+  match: string | RegExp | ((m: ObservedMessage) => boolean),
+): (m: ObservedMessage) => boolean {
+  if (typeof match === "string") return (m) => m.text.includes(match);
+  if (match instanceof RegExp) return (m) => match.test(m.text);
+  return match;
+}
+
+function compileSenderFilter(
+  f: ExpectMessageOptions["senderFilter"],
+): (m: ObservedMessage) => boolean {
+  if (!f) return () => true;
+  if ("userId" in f) return (m) => m.senderUserId === f.userId;
+  return (m) => m.senderUserId !== f.notUserId;
 }
 
+function raceTimeout<T>(p: Promise<T>, ms: number): Promise<T | "timeout"> {
+  if (ms <= 0) return Promise.resolve("timeout");
+  return new Promise<T | "timeout">((resolve) => {
+    const t = setTimeout(() => resolve("timeout"), ms);
+    p.then((v) => {
+      clearTimeout(t);
+      resolve(v);
+    }).catch(() => {
+      clearTimeout(t);
+      resolve("timeout");
+    });
+  });
+}
+
+// ---------- Phase 2b stubs (deferred to follow-up PR) ----------
+
 /**
- * TODO(#866): wait for a reaction sequence on `messageId`. Each
- * emoji in `sequence` must appear (add op) in order; intermediate
- * other reactions are tolerated. Returns the full observed reaction
- * trail.
+ * Wait for a reaction `sequence` on `messageId` in `chatId`. Each
+ * emoji must appear (as an add `+` op) in the order given;
+ * intermediate add/remove ops for other emojis are tolerated.
+ *
+ * Returns the full observed trail (every add/remove seen up to and
+ * including the final match) so scenarios can do follow-up
+ * assertions on the order or count.
+ *
+ * Production note: the gateway calls `setMessageReaction` which
+ * REPLACES the prior emoji (not adds-in-addition-to). So an
+ * 👀 → 🤔 transition emits `-👀` and `+🤔` in the same observation
+ * window. This helper only watches the `+` ops, so the
+ * gateway-replace pattern reads as a clean sequence.
+ *
+ * Fast-turn note: turns shorter than the gateway's
+ * `progress-card initialDelayMs` may collapse intermediate
+ * reactions — you might only see 👀 and 👍. The sequence-match
+ * tolerates this: every emoji in `sequence` must appear in order,
+ * but we don't require it to be the ONLY emojis added.
  */
 export async function expectReaction(
-  _driver: Driver,
-  _chatId: number,
-  _messageId: number,
-  _sequence: string[],
-  _opts: PollOptions,
+  driver: Driver,
+  chatId: number,
+  messageId: number,
+  sequence: string[],
+  opts: PollOptions,
 ): Promise<ObservedReaction[]> {
-  throw new Error("expectReaction not implemented (Phase 2)");
+  if (sequence.length === 0) {
+    throw new Error("expectReaction: sequence must be non-empty");
+  }
+  const trail: ObservedReaction[] = [];
+  const iter = driver.observeReactions(chatId, { messageId })[Symbol.asyncIterator]();
+  const deadline = Date.now() + opts.timeout;
+  let cursor = 0;
+  try {
+    while (Date.now() < deadline && cursor < sequence.length) {
+      const remaining = deadline - Date.now();
+      const next = await raceTimeout(iter.next(), remaining);
+      if (next === "timeout") break;
+      if (next.done === true) break;
+      const r = next.value;
+      trail.push(r);
+      if (r.op === "+" && r.emoji === sequence[cursor]) {
+        cursor++;
+      }
+    }
+  } finally {
+    await iter.return?.();
+  }
+  if (cursor < sequence.length) {
+    throw new Error(
+      `expectReaction: saw ${cursor}/${sequence.length} expected emoji ` +
+        `(missing ${sequence.slice(cursor).map((e) => JSON.stringify(e)).join(", ")}) ` +
+        `on chat=${chatId} msg=${messageId} within ${opts.timeout}ms ` +
+        `(observed ops: ${trail.map((t) => `${t.op}${t.emoji}`).join(" ")})`,
+    );
+  }
+  return trail;
 }
 
+export type CardPhase = "boot" | "working" | "background" | "done" | "error";
+
 export interface PinnedCardSnapshot {
+  chatId: number;
   messageId: number;
   text: string;
-  html?: string;
-  /** Production phase markers: `boot` | `working` | `done` | `error`. */
-  phase: string;
+  /** Detected phase, or `"unknown"` when the text doesn't match any marker. */
+  phase: CardPhase | "unknown";
 }
 
 /**
- * TODO(#866): wait for a pinned message to appear in
- * `chatId`/topic (the progress card). Resolves with a snapshot of
- * its current text/phase.
+ * Wait for a pinned message to appear in `chatId` (the progress
+ * card). Resolves with a snapshot of its current text + phase.
+ *
+ * Implementation:
+ * 1. Subscribe to `driver.observePins(chatId)`.
+ * 2. On the first pin event, fetch the message text via
+ *    `driver.getMessage` (the pin update carries only ids).
+ * 3. Return a snapshot with the parsed phase.
+ *
+ * Fast-turn note: the gateway's `progress_card.delay_ms` (default
+ * 45s) suppresses the card entirely for short turns. UAT runs
+ * against the standard-runtime test-harness agent will time out
+ * here unless the operator sets `delay_ms` to something small in
+ * `switchroom.yaml` under the agent's `channels.telegram` block.
  */
 export async function expectPinnedCard(
-  _driver: Driver,
-  _chatId: number,
-  _opts: PollOptions & { threadId?: number },
+  driver: Driver,
+  chatId: number,
+  opts: PollOptions & { threadId?: number },
 ): Promise<PinnedCardSnapshot> {
-  throw new Error("expectPinnedCard not implemented (Phase 2)");
+  void opts.threadId; // forum/topic routing rolls in with Phase 2d
+  const iter = driver.observePins(chatId)[Symbol.asyncIterator]();
+  const deadline = Date.now() + opts.timeout;
+  try {
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      const next = await raceTimeout(iter.next(), remaining);
+      if (next === "timeout") break;
+      if (next.done === true) break;
+      const pin = next.value;
+      if (!pin.pinned) continue; // skip unpin events; we want pins
+      // Fetch the message body to compose the snapshot. If the
+      // message has been deleted in the gap between pin event and
+      // lookup, treat as a miss and keep waiting.
+      const msg = await driver.getMessage(chatId, pin.messageId).catch(() => null);
+      if (!msg) continue;
+      return {
+        chatId,
+        messageId: pin.messageId,
+        text: msg.text,
+        phase: detectPhase(msg.text),
+      };
+    }
+  } finally {
+    await iter.return?.();
+  }
+  throw new Error(
+    `expectPinnedCard: no pinned message in chat=${chatId} within ${opts.timeout}ms`,
+  );
 }
 
 /**
- * TODO(#866): wait for the pinned progress card to transition to
- * `phase`. The harness must read live edits, not just the snapshot
- * captured by `expectPinnedCard`.
+ * Wait for the pinned progress card to transition to `phase`.
+ *
+ * The gateway updates the card via `editMessage`, NOT by sending a
+ * new message. We observe edits via `driver.observeMessages` on
+ * the card's chat, filter to `msg.messageId === card.messageId`,
+ * and detect the target phase via the same regex set as
+ * `detectPhase`. If the snapshot we were handed is already at the
+ * target phase (e.g. a fast-turn scenario where the card was
+ * first-rendered straight at `done`), resolve immediately.
+ *
+ * The iterator yields a fresh `PinnedCardSnapshot` for each
+ * matching edit, so callers can chain phase transitions
+ * (`boot → working → done`) without re-subscribing.
  */
 export async function waitForCardPhase(
-  _driver: Driver,
-  _card: PinnedCardSnapshot,
-  _phase: "boot" | "working" | "done" | "error",
-  _opts: PollOptions,
+  driver: Driver,
+  card: PinnedCardSnapshot,
+  phase: CardPhase,
+  opts: PollOptions,
 ): Promise<PinnedCardSnapshot> {
-  throw new Error("waitForCardPhase not implemented (Phase 2)");
+  if (detectPhase(card.text) === phase) {
+    // Refresh the phase field — the snapshot we were handed may
+    // have a stale `phase` from when the snapshot was captured
+    // (e.g. pin-time at "boot") even though the text has since
+    // been edited to a later phase. Returning the input as-is
+    // would surface that stale phase to the caller.
+    return { ...card, phase };
+  }
+  const iter = driver
+    .observeMessages(card.chatId)
+    [Symbol.asyncIterator]();
+  const deadline = Date.now() + opts.timeout;
+  try {
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      const next = await raceTimeout(iter.next(), remaining);
+      if (next === "timeout") break;
+      if (next.done === true) break;
+      const msg = next.value;
+      if (msg.messageId !== card.messageId) continue;
+      const detected = detectPhase(msg.text);
+      if (detected === phase) {
+        return {
+          chatId: card.chatId,
+          messageId: card.messageId,
+          text: msg.text,
+          phase,
+        };
+      }
+    }
+  } finally {
+    await iter.return?.();
+  }
+  throw new Error(
+    `waitForCardPhase: card ${card.messageId} did not reach phase="${phase}" within ${opts.timeout}ms`,
+  );
+}
+
+/**
+ * Detect the progress card's phase from its rendered text.
+ *
+ * The actual card render (telegram-plugin/progress-card.ts) uses
+ * emoji markers in the header: `✅` for done, `❌` for errors, `⚙️`
+ * while working (foreground), `🌀` for Background (parent done but
+ * fleet still running, see #862 / status-card-design.md §Header),
+ * and `⏳` during the boot-card window. These markers are stable
+ * enough to key on for UAT — finer parsing (checklist items,
+ * sub-agent row content) is out of scope.
+ *
+ * Phase precedence (highest first): error → done → background →
+ * working → boot. "background" sits above "working" because the
+ * Background phase implies parent reached terminal state — the
+ * card is no longer in foreground "working" mode even though the
+ * fleet is still alive. Tests asserting "is still working" should
+ * use either "working" or "background" depending on whether the
+ * parent has replied.
+ */
+function detectPhase(text: string): CardPhase | "unknown" {
+  if (/❌|\bFailed\b|\bError\b/i.test(text)) return "error";
+  if (/✅|\bDone\b/i.test(text)) return "done";
+  if (/🌀|\bBackground\b/i.test(text)) return "background";
+  if (/⚙️|🤖|\bWorking\b/i.test(text)) return "working";
+  if (/⏳|\bStarting\b/i.test(text)) return "boot";
+  return "unknown";
 }
 
 function sleep(ms: number): Promise<void> {

package/telegram-plugin/uat/driver-info.ts

@@ -0,0 +1,57 @@
+/**
+ * `bun uat/driver-info.ts` — prints the driver user account's
+ * numeric `user_id` to stdout. Used during one-shot `test-harness`
+ * agent creation (see uat/SETUP.md §5) to populate `--allow-from`.
+ *
+ * Issue: https://github.com/switchroom/switchroom/issues/866
+ *
+ * Reads vault credentials via `switchroom vault get --no-broker`
+ * (the operator already has `SWITCHROOM_VAULT_PASSPHRASE` set per
+ * the runbook). The session string lives in-process only; never
+ * printed.
+ */
+
+import { execFileSync } from "node:child_process";
+import { Driver } from "./driver.js";
+
+async function main(): Promise<void> {
+  const apiIdRaw = vaultGet("telegram-uat-api-id");
+  const apiHash = vaultGet("telegram-uat-api-hash");
+  const session = vaultGet("telegram-uat-driver-session");
+
+  const apiId = Number.parseInt(apiIdRaw, 10);
+  if (!Number.isFinite(apiId)) {
+    process.stderr.write(
+      `uat/driver-info: invalid TELEGRAM_API_ID in vault (got '${apiIdRaw}')\n`,
+    );
+    process.exit(1);
+  }
+
+  const driver = new Driver({ apiId, apiHash, session });
+  try {
+    await driver.connect();
+    const uid = await driver.getMyUserId();
+    process.stdout.write(`${uid}\n`);
+  } finally {
+    await driver.disconnect().catch(() => undefined);
+  }
+}
+
+function vaultGet(key: string): string {
+  const out = execFileSync(
+    "switchroom",
+    ["vault", "get", "--no-broker", key],
+    { encoding: "utf8", stdio: ["inherit", "pipe", "inherit"] },
+  );
+  return out.trim();
+}
+
+main().catch((err) => {
+  // Strip any long base64 blob defensively (same posture as login.ts).
+  const sanitized = String(err?.message ?? err).replace(
+    /[A-Za-z0-9+/=_-]{64,}/g,
+    "<redacted>",
+  );
+  process.stderr.write(`uat/driver-info failed: ${sanitized}\n`);
+  process.exit(1);
+});