switchroom 0.5.0 → 0.7.9

package/telegram-plugin/uat/harness.ts

@@ -0,0 +1,161 @@
+/**
+ * Scenario harness for UAT runs.
+ *
+ * Issue: https://github.com/switchroom/switchroom/issues/866
+ *
+ * `spinUp({ agent, topic })` is the single entry point a scenario
+ * uses. Phase 1 ships the type shape + the lifecycle skeleton; the
+ * actual `child_process.spawn` of the agent under test is stubbed
+ * with TODO markers so the reviewer can see exactly where Phase 2
+ * lands.
+ */
+
+import { Driver } from "./driver.js";
+import {
+  expectMessage,
+  expectPinnedCard,
+  expectReaction,
+  waitForCardPhase,
+  type PollOptions,
+  type PinnedCardSnapshot,
+} from "./assertions.js";
+import { allocatePort } from "./port-allocator.js";
+
+export interface SpinUpOptions {
+  /** Agent name to install + run, e.g. `"clerk"`, `"test-harness"`. */
+  agent: string;
+  /**
+   * Forum topic slug for isolation. The harness creates the topic in
+   * the test supergroup and tears it down after the scenario.
+   */
+  topic: string;
+}
+
+export interface Scenario {
+  /** mtcute driver, already connected. */
+  driver: Driver;
+  /** Negative supergroup chat id; from `$SWITCHROOM_UAT_CHAT_ID`. */
+  chatId: number;
+  /** Topic id created for this scenario. */
+  threadId: number;
+
+  // Sugar over the assertion helpers, pre-bound to this scenario's
+  // chat + thread. Phase 1 returns a thin pass-through.
+  expectMessage: (
+    match: Parameters<typeof expectMessage>[2],
+    opts: PollOptions & { from?: "bot" | "user" },
+  ) => ReturnType<typeof expectMessage>;
+  expectReaction: (
+    messageId: number,
+    sequence: string[],
+    opts: PollOptions,
+  ) => ReturnType<typeof expectReaction>;
+  expectPinnedCard: (opts: PollOptions) => ReturnType<typeof expectPinnedCard>;
+  waitForCardPhase: (
+    card: PinnedCardSnapshot,
+    phase: "boot" | "working" | "done" | "error",
+    opts: PollOptions,
+  ) => ReturnType<typeof waitForCardPhase>;
+
+  /** Stop the agent process, delete the topic, disconnect the driver. */
+  tearDown: () => Promise<void>;
+}
+
+/**
+ * Spin up an isolated agent + scenario context.
+ *
+ * Phase 1: returns a stub Scenario whose tools throw helpful "not
+ * implemented" errors. The shape is correct so scenarios written
+ * against it will typecheck today and run for real once Phase 2
+ * lands.
+ */
+export async function spinUp(opts: SpinUpOptions): Promise<Scenario> {
+  // TODO(#866): resolve secrets from vault.
+  //   - `telegram-test-bot-token` for the agent under test
+  //   - `telegram-uat-driver-session` for the mtcute driver
+  //   - `TELEGRAM_API_ID` / `TELEGRAM_API_HASH` from env
+  // For now we throw early with a clear message so accidental runs
+  // before Phase 2 don't crash with confusing stack traces.
+  if (!process.env.SWITCHROOM_UAT_CHAT_ID) {
+    throw new Error(
+      "[uat/harness] SWITCHROOM_UAT_CHAT_ID is not set — see uat/SETUP.md §2",
+    );
+  }
+  const chatId = Number.parseInt(process.env.SWITCHROOM_UAT_CHAT_ID, 10);
+  if (!Number.isFinite(chatId) || chatId >= 0) {
+    throw new Error(
+      `[uat/harness] SWITCHROOM_UAT_CHAT_ID must be a negative supergroup id (got ${process.env.SWITCHROOM_UAT_CHAT_ID})`,
+    );
+  }
+
+  // TODO(#866): allocate gateway port + ephemeral STATE_DIR.
+  //   const port = await allocatePort();
+  //   const stateDir = await mkdtemp(join(tmpdir(), `uat-${opts.agent}-`));
+  //   process.env.STATE_DIR is per-process — we instead pass STATE_DIR
+  //   in the spawned child's env, never mutate ours.
+  const port = await allocatePort();
+  void port; // Phase 2: feed into agent child env
+
+  // TODO(#866): create the forum topic via Bot API
+  // (`createForumTopic`) using the test bot token; capture the
+  // returned `message_thread_id` and stash for tearDown's
+  // `deleteForumTopic`.
+  const threadId = -1; // sentinel; Phase 2 fills in
+
+  // TODO(#866): spawn the agent under test as a child process.
+  //   const child = spawn(process.execPath, [agentEntry], {
+  //     env: {
+  //       ...process.env,
+  //       STATE_DIR: stateDir,
+  //       TELEGRAM_GATEWAY_PORT: String(port),
+  //       SWITCHROOM_AGENT_NAME: opts.agent,
+  //       BOT_TOKEN: <vault: telegram-test-bot-token>,
+  //     },
+  //     stdio: ["ignore", "pipe", "pipe"],
+  //   });
+  //   await waitForGatewayReady(port, { timeout: 30_000 });
+
+  // TODO(#866): connect mtcute driver.
+  //   const driver = new Driver({ apiId, apiHash, session });
+  //   await driver.connect();
+  const driver = new Driver({
+    apiId: 0,
+    apiHash: "",
+    session: "<resolved-from-vault>",
+  });
+
+  const scenario: Scenario = {
+    driver,
+    chatId,
+    threadId,
+    expectMessage: (match, pollOpts) =>
+      expectMessage(driver, chatId, match, {
+        ...pollOpts,
+        threadId,
+      }),
+    expectReaction: (messageId, sequence, pollOpts) =>
+      expectReaction(driver, chatId, messageId, sequence, pollOpts),
+    expectPinnedCard: (pollOpts) =>
+      expectPinnedCard(driver, chatId, { ...pollOpts, threadId }),
+    waitForCardPhase: (card, phase, pollOpts) =>
+      waitForCardPhase(driver, card, phase, pollOpts),
+    tearDown: async () => {
+      // TODO(#866): SIGTERM child, await exit (or SIGKILL after 5s),
+      // delete forum topic, rm -rf state dir, disconnect driver.
+      await driver.disconnect().catch(() => {
+        /* idempotent */
+      });
+    },
+  };
+
+  // Phase 1 marker so accidental runs fail loudly instead of silently
+  // sending nothing.
+  void opts;
+  throw new Error(
+    "[uat/harness] spinUp is scaffolded but not wired (Phase 1 stub) — see TODO markers in uat/harness.ts",
+  );
+
+  // unreachable in Phase 1; left for shape:
+  // eslint-disable-next-line no-unreachable
+  return scenario;
+}

package/telegram-plugin/uat/login.ts

@@ -0,0 +1,134 @@
+/**
+ * One-time interactive login script for the UAT mtcute driver.
+ *
+ * Issue: https://github.com/switchroom/switchroom/issues/865
+ *
+ * Run via `bun run uat:login` from telegram-plugin/. Prompts for
+ * phone, login code, and (optionally) 2FA password on stdin. Captures
+ * the session string in memory and writes it to vault under
+ * `telegram-uat-driver-session`. The session string is **never
+ * printed** — not to stdout, not to stderr, not to logs. If you see
+ * one in scrollback, file an incident.
+ *
+ * Required env:
+ *   TELEGRAM_API_ID    — from https://my.telegram.org/apps
+ *   TELEGRAM_API_HASH  — from https://my.telegram.org/apps
+ */
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { TelegramClient } from "@mtcute/node";
+
+const VAULT_KEY = "telegram-uat-driver-session";
+
+async function main(): Promise<void> {
+  const apiId = Number.parseInt(process.env.TELEGRAM_API_ID ?? "", 10);
+  const apiHash = process.env.TELEGRAM_API_HASH ?? "";
+  if (!Number.isFinite(apiId) || !apiHash) {
+    fail(
+      "TELEGRAM_API_ID and TELEGRAM_API_HASH must be set. See uat/SETUP.md §3.",
+    );
+  }
+
+  const rl = createInterface({ input, output, terminal: true });
+
+  // Confirm the operator understands the security posture before we
+  // mint a bearer-equivalent credential.
+  const ack = await rl.question(
+    [
+      "",
+      "About to mint a Telegram USER session string for the UAT driver.",
+      "This is bearer-equivalent to the user account. It will be stored",
+      "in vault under `" + VAULT_KEY + "` and NEVER printed.",
+      "",
+      "Type YES to proceed: ",
+    ].join("\n"),
+  );
+  if (ack.trim() !== "YES") {
+    fail("Aborted.");
+  }
+
+  const phone = (await rl.question("Phone number (E.164, e.g. +14155551234): ")).trim();
+  if (!phone.startsWith("+")) fail("Phone must start with '+'.");
+
+  const client = new TelegramClient({ apiId, apiHash });
+
+  // mtcute exposes a `start()` flow that takes async callbacks for
+  // each interactive step. Exact callback names may shift across
+  // versions — verify against the pinned mtcute version before first
+  // run.
+  await client.start({
+    phone: async () => phone,
+    code: async () =>
+      (await rl.question("Login code (from Telegram app or SMS): ")).trim(),
+    password: async () =>
+      (await rl.question("2FA password (leave blank if none): ")),
+  });
+
+  // TODO(#865): mtcute v0.27 exports sessions via the
+  // `@mtcute/core/utils.js` `StringSessionStorage` adapter; the
+  // exact call is `await client.exportSession()` only when that
+  // storage is configured, otherwise sessions live in the SQLite
+  // file at `client.session`. Phase 2 wires the string-session
+  // storage so this script can mint a string. For now we throw
+  // before producing a value so the operator never gets a half-
+  // baked session in vault.
+  const session: string = await Promise.reject(
+    new Error(
+      "uat:login: Phase 1 stub — Phase 2 wires StringSessionStorage. See uat/SETUP.md §3.",
+    ),
+  );
+
+  await client.destroy();
+  rl.close();
+
+  // Write to vault via the switchroom CLI's stdin path so the
+  // session never appears in argv (which would land in `ps` output).
+  await writeToVault(VAULT_KEY, session);
+
+  // Belt-and-suspenders: zero out the local copy.
+  scrub(session);
+
+  process.stdout.write(
+    `\nDone. Session stored in vault as \`${VAULT_KEY}\`.\n` +
+      "If you ever see the actual session string in your terminal, file an incident.\n",
+  );
+}
+
+function writeToVault(key: string, value: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("switchroom", ["vault", "set", key], {
+      stdio: ["pipe", "inherit", "inherit"],
+    });
+    proc.on("error", reject);
+    proc.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`switchroom vault set exited ${code}`));
+    });
+    proc.stdin.end(value + "\n");
+  });
+}
+
+function scrub(_s: string): void {
+  // JS strings are immutable — best we can do is drop the reference
+  // and trust the GC. Documented here so a future hardening pass
+  // (e.g. SecureBuffer) has a hook.
+}
+
+function fail(msg: string): never {
+  process.stderr.write(`uat:login: ${msg}\n`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  // Defensive: if mtcute throws, the error MAY contain the session
+  // string in some adapters. Strip anything that looks like a base64
+  // blob > 64 chars before printing.
+  const sanitized = String(err?.message ?? err).replace(
+    /[A-Za-z0-9+/=_-]{64,}/g,
+    "<redacted>",
+  );
+  process.stderr.write(`uat:login failed: ${sanitized}\n`);
+  process.exit(1);
+});

package/telegram-plugin/uat/port-allocator.ts

@@ -0,0 +1,71 @@
+/**
+ * Process-wide unique port allocator for the UAT harness.
+ *
+ * Why this exists: each scenario `spinUp`s an agent child process
+ * with its own gateway listening on `TELEGRAM_GATEWAY_PORT`. If two
+ * sibling scenarios race to pick a port we get silent collisions
+ * that masquerade as flaky assertions ("the bridge couldn't reach
+ * the gateway, so no replies showed up"). See SETUP.md §6 for the
+ * port-vs-unix-socket decision.
+ *
+ * The allocator is monotonic per process and probes the candidate
+ * by `bind()`ing a transient socket — catches the case where some
+ * other process on the host has stolen a port out of our range.
+ */
+
+import { createServer } from "node:net";
+
+const DEFAULT_BASE_PORT = 47000;
+const DEFAULT_MAX_PORT = 47999;
+
+let cursor = DEFAULT_BASE_PORT;
+
+/**
+ * Allocate the next free TCP port in the harness range.
+ *
+ * Throws if every port in [base, max] is taken — almost certainly
+ * means a previous run leaked agent processes. Recovery: `pkill -f
+ * test-harness-uat` and try again.
+ */
+export async function allocatePort(opts?: {
+  base?: number;
+  max?: number;
+}): Promise<number> {
+  const base = opts?.base ?? DEFAULT_BASE_PORT;
+  const max = opts?.max ?? DEFAULT_MAX_PORT;
+
+  if (cursor < base) cursor = base;
+
+  const start = cursor;
+  for (;;) {
+    const port = cursor;
+    cursor = cursor + 1 > max ? base : cursor + 1;
+
+    if (await isPortFree(port)) {
+      return port;
+    }
+
+    if (cursor === start) {
+      throw new Error(
+        `[uat/port-allocator] no free ports in [${base}, ${max}]; ` +
+          "likely leaked agent child processes — try `pkill -f test-harness-uat`",
+      );
+    }
+  }
+}
+
+/** Reset the allocator. Test-only. */
+export function _resetAllocatorForTests(): void {
+  cursor = DEFAULT_BASE_PORT;
+}
+
+function isPortFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => resolve(false));
+    probe.once("listening", () => {
+      probe.close(() => resolve(true));
+    });
+    probe.listen(port, "127.0.0.1");
+  });
+}

package/telegram-plugin/uat/scenarios/smoke-clerk-reply.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Smoke scenario — clerk replies to a simple text message.
+ *
+ * Part of: https://github.com/switchroom/switchroom/issues/866
+ *
+ * Phase 1 status: this file exercises the harness shape (typecheck-
+ * clean, reads as the canonical example) but will FAIL at runtime
+ * because `harness.spinUp` is stubbed. Phase 2 wires the real
+ * lifecycle and this becomes the first green UAT scenario.
+ *
+ * The shape mirrors the canonical scenario in epic #863 so reviewers
+ * can map directly between the design doc and the code.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+
+describe("uat: clerk smoke", () => {
+  it("replies to a text message with the right reaction sequence + HTML reply", async () => {
+    const sc = await spinUp({ agent: "clerk", topic: "smoke-clerk-reply" });
+
+    try {
+      const sent = await sc.driver.sendText(
+        sc.chatId,
+        "summarize this short note",
+        { messageThreadId: sc.threadId },
+      );
+
+      // Status reactions should walk 👀 → 🤔 → 🔥 → 👍 on the inbound
+      // message within 30s on a healthy run.
+      await sc.expectReaction(
+        sent.messageId,
+        ["👀", "🤔", "🔥", "👍"],
+        { timeout: 30_000 },
+      );
+
+      // The progress card should be pinned within a few seconds.
+      const card = await sc.expectPinnedCard({ timeout: 5_000 });
+
+      // And ride to `done` within the model's normal turn budget.
+      const finalCard = await sc.waitForCardPhase(card, "done", {
+        timeout: 60_000,
+      });
+      expect(finalCard.text).toMatch(/Done|✅/);
+
+      // The actual reply prose lands as a fresh bot message, in HTML.
+      const reply = await sc.expectMessage(/./, {
+        from: "bot",
+        timeout: 60_000,
+      });
+      // Reviewer note: parse_mode isn't on the wire-level update;
+      // we proxy via "did the rendered HTML contain a `<` we
+      // recognize, or did markdown leak as plain `*`?". Phase 2
+      // will pick the right shape — left as a TODO so this file
+      // typechecks today.
+      expect(reply.text.length).toBeGreaterThan(0);
+    } finally {
+      await sc.tearDown();
+    }
+  });
+});

package/telegram-plugin/welcome-text.ts

@@ -48,6 +48,21 @@ export type AgentAudit = {
   memoryBank?: string;
 };
 
+/**
+ * One live probe row for the `/status` health block. Mirrors the
+ * `ProbeResult` shape used by the boot card without dragging the
+ * boot-probes module into welcome-text — keeps welcome-text dependency-
+ * free for unit tests.
+ */
+export type StatusProbeRow = {
+  /** ProbeStatus shape from boot-probes: ok / degraded / fail. */
+  status: 'ok' | 'degraded' | 'fail';
+  /** Display label, e.g. "Broker", "Scheduler". */
+  label: string;
+  /** Free-text detail, e.g. "running (pid 23) · last fire 4m ago". */
+  detail: string;
+};
+
 export type AgentMetadata = {
   agentName: string;
   model: string | null;
@@ -59,6 +74,13 @@ export type AgentMetadata = {
   auth: AuthSummary | null;
   /** Live audit details — present only when switchroom.yaml loaded cleanly. */
   audit?: AgentAudit;
+  /**
+   * Live probe results gathered at request time. Same probe set as the
+   * boot card. Unlike the boot card (silent-when-healthy), `/status`
+   * shows EVERY row including the green ones — the user explicitly
+   * asked for current state, so terseness loses to completeness here.
+   */
+  live?: StatusProbeRow[];
 };
 
 // Tiny escaper — duplicates the one in gateway.ts / server.ts so this
@@ -151,6 +173,12 @@ export function helpText(agentName: string): string {
  * Version. This is the on-demand reincarnation of the SessionStart
  * greeting card deleted in #142 PR 1.
  */
+const STATUS_DOT: Record<StatusProbeRow['status'], string> = {
+  ok: '🟢',
+  degraded: '🟡',
+  fail: '🔴',
+};
+
 export function statusPairedText(params: {
   user: string;
   meta: AgentMetadata;
@@ -164,6 +192,19 @@ export function statusPairedText(params: {
   ];
   if (meta.status) lines.push(`Status: <code>${escapeHtml(meta.status)}</code>${meta.uptime ? ` · up ${escapeHtml(meta.uptime)}` : ""}`);
 
+  // Live health block — every probe (green and otherwise) so the user
+  // can see at a glance what's working AND what isn't. This is the
+  // `/status`-specific opposite of the boot card's silent-when-healthy
+  // contract: the boot card is a quiet ack, /status is the dashboard.
+  if (meta.live && meta.live.length > 0) {
+    lines.push("");
+    lines.push("<b>Health</b>");
+    for (const row of meta.live) {
+      const dot = STATUS_DOT[row.status] ?? STATUS_DOT.fail;
+      lines.push(`${dot} <b>${escapeHtml(row.label)}</b>  ${escapeHtml(row.detail)}`);
+    }
+  }
+
   const audit = meta.audit;
   if (audit) {
     // Blank separator before the audit block so the reply reads as two
@@ -312,7 +353,8 @@ export function switchroomHelpText(agentName: string): string {
     `<code>/memory &lt;query&gt;</code> — search agent memory`,
     ``,
     `<b>Fleet management</b>`,
-    `<code>/update</code> — pull latest code, reconcile, restart everything`,
+    `<code>/upgradestatus</code> — read-only: CLI version, image age, container age per service`,
+    `<code>/update</code> — dry-run plan; <code>/update apply</code> — actually pull images, reconcile, restart`,
     `<code>/restart [name|all]</code> — bounce agent (drains in-flight turn by default)`,
     `<code>/version</code> — show versions + running agent health summary`,
     ``,
@@ -336,7 +378,7 @@ export function switchroomHelpText(agentName: string): string {
     `<code>/inject &lt;slash&gt;</code> — inject a Claude Code REPL slash command (e.g. <code>/inject /cost</code>; allowlisted)`,
     `<code>/commands</code> — this help`,
     ``,
-    `<i>Tip: <code>/update</code> picks up new code; <code>/restart</code> bounces a stuck agent; <code>/version</code> checks what's running.</i>`,
+    `<i>Tip: <code>/update</code> shows the plan; <code>/update apply</code> executes it; <code>/restart</code> bounces a stuck agent; <code>/version</code> checks what's running.</i>`,
   ].join("\n");
 }