switchroom 0.5.0 → 0.7.8

package/telegram-plugin/tool-labels.ts

@@ -155,7 +155,15 @@ export function toolLabel(
   tool: string,
   input?: Record<string, unknown>,
   preamble?: string,
+  precomputedLabel?: string,
 ): string {
+  // Precomputed sidecar label (PreToolUse hook, #783) — top of the
+  // precedence ladder per spec. The hook deliberately emits NO label
+  // for Bash/Task/Agent/TodoWrite, so falling through to the
+  // existing description path for those is automatic.
+  if (precomputedLabel && precomputedLabel.trim().length > 0) {
+    return truncate(firstLine(precomputedLabel.trim()), MAX_DESCRIPTION_CHARS)
+  }
   if (!input || typeof input !== 'object') return ''
   const str = (k: string): string | undefined =>
     typeof input[k] === 'string' ? (input[k] as string) : undefined
@@ -307,6 +315,53 @@ export function toolLabel(
  * labels, and otherwise capitalise the first letter and keep the rest
  * verbatim so unknown servers still render cleanly.
  */
+/**
+ * Public alias for `mcpBaseLabel` — the progress card uses this when an
+ * `mcp__*` tool fires with no human label so the row can still render
+ * something readable (e.g. "Telegram: reply") instead of the raw tool
+ * name.
+ */
+export function mcpDisplayName(tool: string): string {
+  return mcpBaseLabel(tool)
+}
+
+/**
+ * Human-readable fallback for a bare tool name when no label is
+ * available (TodoWrite, Task housekeeping, etc.). Returns the lowercased
+ * raw tool name when the tool isn't in the map.
+ */
+const TOOL_FALLBACK_LABELS: Record<string, string> = {
+  Bash: 'running command',
+  BashOutput: 'running command',
+  Edit: 'editing file',
+  Write: 'editing file',
+  NotebookEdit: 'editing file',
+  Read: 'reading file',
+  Grep: 'searching',
+  Glob: 'searching',
+  WebFetch: 'fetching',
+  WebSearch: 'searching the web',
+  Task: 'delegating',
+  Agent: 'delegating',
+  TodoWrite: 'updating tasks',
+  TaskCreate: 'updating tasks',
+  TaskUpdate: 'updating tasks',
+  TaskList: 'updating tasks',
+  TaskGet: 'updating tasks',
+  TaskStop: 'updating tasks',
+  TaskOutput: 'updating tasks',
+  Skill: 'running skill',
+  SlashCommand: 'running command',
+  KillShell: 'running command',
+  ToolSearch: 'searching',
+}
+
+export function toolFallbackLabel(tool: string): string {
+  if (!tool) return ''
+  if (TOOL_FALLBACK_LABELS[tool]) return TOOL_FALLBACK_LABELS[tool]
+  return tool.toLowerCase()
+}
+
 function mcpBaseLabel(tool: string): string {
   if (!tool.startsWith('mcp__')) return ''
   const parts = tool.slice('mcp__'.length).split('__')

package/telegram-plugin/two-zone-card.ts

@@ -16,6 +16,7 @@ import type { FleetMember, FleetStatus } from './fleet-state.js'
 import { cap } from './fleet-state.js'
 import type { ProgressCardState, RenderOptions, TaskNum } from './progress-card.js'
 import { escapeHtml, formatDuration } from './card-format.js'
+import { mcpDisplayName, toolFallbackLabel } from './tool-labels.js'
 
 const PARENT_BULLET_CAP = 8
 const FLEET_ROW_CAP = 5
@@ -86,7 +87,15 @@ export function phaseFor(
   if (stalledClose) return { icon: '⚠', label: 'Forced close' }
 
   const fleetRunning = anyFleetActive(fleet)
-  const fleetAllStuck = fleet.size > 0 && [...fleet.values()].filter((m) => m.status === 'running' || m.status === 'stuck').every((m) => isStuck(m, now))
+  // Stalled = "the only fleet members that could still make progress have
+  // gone idle past the threshold". An empty filtered list (every fleet
+  // member is already terminal) MUST NOT count as stalled — Array#every
+  // returns true vacuously on `[]`, which previously caused the card to
+  // freeze at ⚠ Stalled the moment the last sub-agent finished while the
+  // parent was still running. We require at least one running-or-stuck
+  // member before claiming the fleet is stalled.
+  const runningOrStuck = [...fleet.values()].filter((m) => m.status === 'running' || m.status === 'stuck')
+  const fleetAllStuck = runningOrStuck.length > 0 && runningOrStuck.every((m) => isStuck(m, now))
 
   // SilentEnd: parent terminated without a reply. Lifted above the
   // background/done branches so a still-running fleet can't mask it,
@@ -98,8 +107,11 @@ export function phaseFor(
   // Stalled: every running-or-stuck member is past the idle threshold.
   // Members already terminal (done/failed) are excluded from this check —
   // a fleet of [done, stuck] still surfaces as Stalled because the only
-  // member that could still make progress is no longer doing so.
-  if (fleet.size > 0 && fleetAllStuck && !parentDone) {
+  // member that could still make progress is no longer doing so. The
+  // `fleetAllStuck` calc itself guards against an empty filtered list
+  // (otherwise `[].every()` would lock the card at Stalled the moment
+  // the last sub-agent finished).
+  if (fleetAllStuck && !parentDone) {
     return { icon: '⚠', label: 'Stalled' }
   }
 
@@ -159,12 +171,20 @@ function renderParentZone(state: ProgressCardState): string {
   const lastIdx = visible.length - 1
   for (let i = 0; i < visible.length; i++) {
     const it = visible[i]
-    const tool = escapeHtml(it.tool || '')
-    const label = it.label ? ` <code>${escapeHtml(truncate(it.label, 80))}</code>` : ''
+    let text: string
+    if (it.label) {
+      text = escapeHtml(truncate(it.label, 80))
+    } else {
+      const tool = it.tool || ''
+      const fallback = tool.startsWith('mcp__')
+        ? mcpDisplayName(tool) || toolFallbackLabel(tool)
+        : toolFallbackLabel(tool)
+      text = escapeHtml(fallback)
+    }
     if (inFlight && i === lastIdx) {
-      lines.push(`◉ <b>${tool}</b>${label}`)
+      lines.push(`◉ ${text}`)
     } else {
-      lines.push(`● ${tool}${label}`)
+      lines.push(`● ${text}`)
     }
   }
   return lines.join('\n')

package/telegram-plugin/uat/SETUP.md

@@ -0,0 +1,160 @@
+# UAT Harness — One-time Setup
+
+This is the operator runbook for bringing up the Telegram UAT harness
+introduced by epic [#863](https://github.com/switchroom/switchroom/issues/863).
+Phase 1 ships scaffolding only — every step in this file is a manual
+prerequisite that must be completed once before the first scenario can
+run against real Telegram.
+
+> ⚠️ **Security floor.** The mtcute *session string* this harness mints
+> is **bearer-equivalent to the driver Telegram user account**. Anyone
+> holding it can read every chat the user can read and impersonate them
+> in messages. Treat it with the same care as a long-lived OAuth refresh
+> token:
+>
+> - **Never** log it. **Never** echo it to a terminal. **Never** commit
+>   it. **Never** paste it into chat for "debugging."
+> - It lives in vault under key `telegram-uat-driver-session` and that
+>   is the only legitimate location.
+> - Same rules apply to `telegram-test-bot-token` (a normal bot token,
+>   but a bot the harness drives autonomously — leak = remote control).
+
+---
+
+## 1. BotFather: create the test bot
+
+1. Open `@BotFather` from the operator's Telegram account.
+2. `/newbot` → name (e.g. `Switchroom UAT`) → username (e.g.
+   `@switchroom_uat_bot`).
+3. Copy the HTTP API token BotFather returns.
+4. **Disable privacy mode** so the test bot sees all messages in groups,
+   not just commands: `/setprivacy` → select the bot → `Disable`.
+   (Privacy mode does not affect the driver's ability to read the bot —
+   bots cannot read other bots regardless. This is for the bot reading
+   the driver user.)
+5. Vault the token:
+   ```bash
+   switchroom vault set telegram-test-bot-token
+   # paste token at the prompt; do not pass via argv
+   ```
+6. Sanity check:
+   ```bash
+   TOKEN=$(switchroom vault get telegram-test-bot-token)
+   curl -s "https://api.telegram.org/bot${TOKEN}/getMe" | jq .ok
+   # expect: true
+   unset TOKEN
+   ```
+
+## 2. Create the test supergroup
+
+1. New Group → add the test bot + the driver user → "Upgrade to
+   supergroup" (Settings → Group Type, or just enable Topics; both
+   actions imply supergroup).
+2. Settings → **Topics: Enabled**.
+3. Settings → Administrators → promote both:
+   - test bot — needs at least: Manage Topics, Pin Messages, Delete
+     Messages.
+   - driver user — needs at least: Manage Topics (so per-scenario
+     topic creation works without the bot doing it).
+4. Note the chat id. Easiest: forward any message from the supergroup
+   to `@RawDataBot` and copy `forward_from_chat.id`. It will be
+   negative and ~13 digits (`-100…`).
+5. Stash the chat id under your shell profile or a UAT env file (NOT
+   in the repo):
+   ```bash
+   echo 'export SWITCHROOM_UAT_CHAT_ID=-1001234567890' >> ~/.config/switchroom/uat.env
+   ```
+
+## 3. Driver user: mint the mtcute session
+
+The mtcute MTProto driver runs as a **Telegram user account**, not a
+bot, because bots cannot read other bots' messages even with admin
+rights. ([Telegram Bots FAQ](https://core.telegram.org/bots/faq).)
+
+You will need:
+- An `api_id` and `api_hash` from <https://my.telegram.org/apps> (one
+  per developer; reusable across projects).
+- The driver user's phone number, the SMS/Telegram login code, and the
+  2FA password if set.
+
+Run:
+```bash
+cd telegram-plugin
+TELEGRAM_API_ID=12345 TELEGRAM_API_HASH=abcdef0123... bun run uat:login
+```
+
+The script prompts for phone, login code, and 2FA password on stdin,
+captures the session string in memory, and writes it to vault as
+`telegram-uat-driver-session`. It **never prints the session string
+to stdout or stderr** — if you see one in your scrollback, file an
+incident.
+
+## 4. 2FA / new-device re-login playbook
+
+mtcute session strings can get invalidated when:
+- The user changes/sets a 2FA password.
+- The user terminates the session from another client (Settings →
+  Devices → Active sessions → Terminate).
+- Telegram's anti-abuse heuristics decide the session is suspicious
+  (rare, but happens after long idle + IP change).
+
+When a scenario fails with `AUTH_KEY_UNREGISTERED`,
+`SESSION_REVOKED`, or `SESSION_PASSWORD_NEEDED`:
+
+1. Confirm via the Telegram app (Settings → Devices) that the prior
+   session is gone.
+2. Re-run `bun run uat:login` from the operator's machine.
+3. Enter the current 2FA password when prompted.
+4. The script overwrites the vault key. No other action required —
+   nothing caches the old string.
+
+If the driver account is locked entirely (e.g. SPAM_WAIT), only the
+account owner can resolve it via support@telegram.org. The harness has
+no recourse.
+
+## 5. Worktree-based agent install (NOT `switchroom agent add`)
+
+The UAT harness does **not** persistently install the test-harness
+agent through `switchroom agent add` (which writes a systemd unit + a
+persistent state dir — wrong shape for hermetic test runs). Instead,
+the harness `exec`s the agent as a child process per scenario with:
+
+- `STATE_DIR=$(mktemp -d)` — ephemeral; teardown rm-rfs it.
+- A unique `TELEGRAM_GATEWAY_PORT` (see port allocator note below).
+- `SWITCHROOM_AGENT_NAME=test-harness`.
+- The test bot token loaded from `telegram-test-bot-token`.
+
+The Phase 1 scaffold stubs this out in `harness.ts`; Phase 2 wires it
+end-to-end.
+
+## 6. Port allocator vs unix sockets
+
+Phase 1 commits to a **process-wide port allocator** (see
+`uat/port-allocator.ts`) rather than unix sockets. Rationale:
+
+- The gateway already speaks IP loopback to the bridge; switching to
+  unix sockets is a code change in `gateway/` we don't want bundled
+  with the UAT scaffold work.
+- Tests only ever run from one harness process, so a node-local
+  monotonic counter starting at a high ephemeral port (default 47000)
+  is enough to avoid collisions with the system + with sibling
+  scenarios in the same run.
+- The allocator also `bind()`s a probe socket and releases it before
+  returning, which catches "port already in use by another process"
+  before the agent boots and produces a confusing crash.
+
+If we ever want concurrent harness runs from CI, swap to unix sockets;
+the harness API takes a `transport` shape so it's a one-line change.
+
+## 7. Verification checklist before running scenarios
+
+- [ ] `switchroom vault get telegram-test-bot-token` returns a token.
+- [ ] `switchroom vault get telegram-uat-driver-session` returns a
+      session string (the command output may be redacted by the
+      vault — that's fine, you only need exit code 0).
+- [ ] `$SWITCHROOM_UAT_CHAT_ID` exported and is a negative int.
+- [ ] Test bot is admin in the supergroup.
+- [ ] Driver user is admin in the supergroup.
+- [ ] Topics enabled in the supergroup.
+
+When all six are checked, `bun run test:uat` is safe to run.

package/telegram-plugin/uat/assertions.ts

@@ -0,0 +1,140 @@
+/**
+ * Eventual-assertion helpers for UAT scenarios.
+ *
+ * Issue: https://github.com/switchroom/switchroom/issues/866
+ *
+ * Real Telegram is eventually consistent across the bot API, MTProto,
+ * and CDN edges. Every assertion in a UAT scenario is a `waitFor`-
+ * shape: poll a predicate until it goes truthy or a deadline trips.
+ * Avoid `setTimeout(..., N); expect(...)` patterns at all cost.
+ */
+
+import type { Driver, ObservedMessage, ObservedReaction } from "./driver.js";
+
+export interface PollOptions {
+  /** Hard deadline; the predicate must resolve truthy before this. */
+  timeout: number;
+  /** Poll cadence in ms. Default 250ms. */
+  interval?: number;
+}
+
+/**
+ * Poll `predicate` every `interval` ms until it returns a truthy
+ * value, then resolve with that value. Reject when `timeout` ms
+ * elapse without success.
+ *
+ * The predicate may throw — exceptions are caught and treated as a
+ * "not yet" signal until the deadline. The last-seen exception is
+ * attached to the timeout error so flakes are debuggable.
+ */
+export async function pollUntil<T>(
+  predicate: () => Promise<T | undefined | null | false> | T | undefined | null | false,
+  opts: PollOptions,
+): Promise<T> {
+  const interval = opts.interval ?? 250;
+  const deadline = Date.now() + opts.timeout;
+  let lastError: unknown;
+
+  while (Date.now() < deadline) {
+    try {
+      const result = await predicate();
+      if (result) return result as T;
+    } catch (err) {
+      lastError = err;
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await sleep(Math.min(interval, remaining));
+  }
+
+  const detail = lastError instanceof Error ? `: ${lastError.message}` : "";
+  throw new Error(`pollUntil: deadline exceeded after ${opts.timeout}ms${detail}`);
+}
+
+/**
+ * Sugar over `pollUntil` for the boolean-predicate case where the
+ * caller wants a clear assertion message.
+ */
+export async function expectEventually(
+  predicate: () => Promise<boolean> | boolean,
+  opts: PollOptions,
+  msg: string,
+): Promise<void> {
+  await pollUntil(async () => {
+    const ok = await predicate();
+    return ok || undefined;
+  }, opts).catch((err) => {
+    throw new Error(`expectEventually(${msg}): ${(err as Error).message}`);
+  });
+}
+
+// ---------- Phase 2 stubs ----------
+
+/**
+ * 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.
+ */
+export async function expectMessage(
+  _driver: Driver,
+  _chatId: number,
+  _match: string | RegExp | ((m: ObservedMessage) => boolean),
+  _opts: PollOptions & { threadId?: number; from?: "bot" | "user" },
+): Promise<ObservedMessage> {
+  throw new Error("expectMessage not implemented (Phase 2)");
+}
+
+/**
+ * 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.
+ */
+export async function expectReaction(
+  _driver: Driver,
+  _chatId: number,
+  _messageId: number,
+  _sequence: string[],
+  _opts: PollOptions,
+): Promise<ObservedReaction[]> {
+  throw new Error("expectReaction not implemented (Phase 2)");
+}
+
+export interface PinnedCardSnapshot {
+  messageId: number;
+  text: string;
+  html?: string;
+  /** Production phase markers: `boot` | `working` | `done` | `error`. */
+  phase: string;
+}
+
+/**
+ * TODO(#866): wait for a pinned message to appear in
+ * `chatId`/topic (the progress card). Resolves with a snapshot of
+ * its current text/phase.
+ */
+export async function expectPinnedCard(
+  _driver: Driver,
+  _chatId: number,
+  _opts: PollOptions & { threadId?: number },
+): Promise<PinnedCardSnapshot> {
+  throw new Error("expectPinnedCard not implemented (Phase 2)");
+}
+
+/**
+ * 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`.
+ */
+export async function waitForCardPhase(
+  _driver: Driver,
+  _card: PinnedCardSnapshot,
+  _phase: "boot" | "working" | "done" | "error",
+  _opts: PollOptions,
+): Promise<PinnedCardSnapshot> {
+  throw new Error("waitForCardPhase not implemented (Phase 2)");
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/telegram-plugin/uat/driver.ts

@@ -0,0 +1,174 @@
+/**
+ * mtcute-backed Telegram user-account driver for the UAT harness.
+ *
+ * Issue: https://github.com/switchroom/switchroom/issues/865
+ *
+ * The driver is a Telegram **user account** (not a bot) because bots
+ * cannot read other bots' messages even with privacy mode disabled
+ * and admin rights — see Telegram Bots FAQ. The driver sends fixture
+ * inbounds and observes everything the test bot emits.
+ *
+ * Phase 1: typed wrapper around mtcute with `connect` / `disconnect` /
+ * `sendText` implemented. `sendVoice`, `observeMessages`,
+ * `observeReactions`, `observePins` are stubs with TODO markers — they
+ * land in Phase 2 alongside the scenario catalog.
+ *
+ * Security: never log session strings, never log message bodies that
+ * might contain auth codes (see `auth-code-redact.ts` for the
+ * production pattern).
+ */
+
+import { TelegramClient } from "@mtcute/node";
+
+export interface DriverOptions {
+  /** Telegram developer credential — `api_id` from my.telegram.org. */
+  apiId: number;
+  /** Telegram developer credential — `api_hash` from my.telegram.org. */
+  apiHash: string;
+  /**
+   * Session string previously minted by `bun run uat:login` and
+   * stored in vault under `telegram-uat-driver-session`. Bearer-
+   * equivalent — never log.
+   */
+  session: string;
+}
+
+export interface SendTextOptions {
+  /** Forum topic id, when targeting a topic in a supergroup. */
+  messageThreadId?: number;
+  /** Reply-quote a specific earlier message id. */
+  replyTo?: number;
+}
+
+export interface ObservedMessage {
+  chatId: number;
+  messageId: number;
+  threadId?: number;
+  text: string;
+  /** raw HTML if the message was sent with `parse_mode: HTML`. */
+  html?: string;
+  fromBot: boolean;
+  date: Date;
+}
+
+export interface ObservedReaction {
+  chatId: number;
+  messageId: number;
+  emoji: string;
+  /** Reaction add (`+`) vs remove (`-`). */
+  op: "+" | "-";
+  date: Date;
+}
+
+export interface ObservedPin {
+  chatId: number;
+  messageId: number;
+  pinned: boolean;
+  date: Date;
+}
+
+/**
+ * Thin wrapper. Concrete mtcute use is intentionally narrow so the
+ * scenarios don't get tangled up in raw MTProto types.
+ */
+export class Driver {
+  private client: TelegramClient | null = null;
+
+  constructor(private readonly opts: DriverOptions) {}
+
+  async connect(): Promise<void> {
+    // mtcute v0.27 takes session via the `storage` option. For a
+    // string-session driver we'll use `@mtcute/core/utils.js`'s
+    // string-session-storage in Phase 2; Phase 1 just records the
+    // shape so the harness compiles.
+    // TODO(#865): wire StringSessionStorage from @mtcute/core/utils
+    // and feed `this.opts.session` through it.
+    this.client = new TelegramClient({
+      apiId: this.opts.apiId,
+      apiHash: this.opts.apiHash,
+    });
+    void this.opts.session;
+  }
+
+  async disconnect(): Promise<void> {
+    if (!this.client) return;
+    await this.client.destroy();
+    this.client = null;
+  }
+
+  async sendText(
+    chatId: number,
+    text: string,
+    opts?: SendTextOptions,
+  ): Promise<{ messageId: number }> {
+    const c = this.requireClient();
+    // mtcute exposes `sendText(peer, text, params)`. Forum topic
+    // targeting is via `params.replyTo` carrying a topic ref in
+    // newer mtcute; precise shape verified in Phase 2.
+    const sent = await c.sendText(chatId, text, {
+      replyTo: opts?.replyTo,
+    } as Parameters<TelegramClient["sendText"]>[2]);
+    void opts?.messageThreadId; // TODO(#865): topic routing in Phase 2
+    return { messageId: sent.id };
+  }
+
+  // -------- Phase 2 stubs --------
+
+  /**
+   * TODO(#865): send a voice note as the driver user. Needed for the
+   * `voice-inbound.test.ts` scenario. mtcute's `sendVoice` takes an
+   * OGG/Opus buffer or a path; we'll stage fixtures under
+   * `uat/fixtures/voice/`.
+   */
+  async sendVoice(
+    _chatId: number,
+    _oggPath: string,
+    _opts?: SendTextOptions,
+  ): Promise<{ messageId: number }> {
+    throw new Error("Driver.sendVoice not implemented (Phase 2)");
+  }
+
+  /**
+   * TODO(#865): subscribe to new + edited messages in `chatId`/topic.
+   * Returns an async iterable so scenarios can `for await` until a
+   * predicate matches. Should backfill via `getHistory(limit:50)` to
+   * catch messages that arrived between connect and observe-start.
+   */
+  observeMessages(
+    _chatId: number,
+    _opts?: { threadId?: number },
+  ): AsyncIterable<ObservedMessage> {
+    throw new Error("Driver.observeMessages not implemented (Phase 2)");
+  }
+
+  /**
+   * TODO(#865): subscribe to message-reaction updates. Note: mtcute
+   * delivers `updateMessageReactions` as a delta (full set after the
+   * change); the driver should compute add/remove ops vs the prior
+   * snapshot so scenarios can assert on the 👀→🤔→🔥→👍 sequence.
+   */
+  observeReactions(
+    _chatId: number,
+    _opts?: { messageId?: number },
+  ): AsyncIterable<ObservedReaction> {
+    throw new Error("Driver.observeReactions not implemented (Phase 2)");
+  }
+
+  /**
+   * TODO(#865): subscribe to pin/unpin events on `chatId`/topic.
+   * Used for progress-card-lifecycle assertions.
+   */
+  observePins(
+    _chatId: number,
+    _opts?: { threadId?: number },
+  ): AsyncIterable<ObservedPin> {
+    throw new Error("Driver.observePins not implemented (Phase 2)");
+  }
+
+  private requireClient(): TelegramClient {
+    if (!this.client) {
+      throw new Error("Driver not connected — call connect() first");
+    }
+    return this.client;
+  }
+}