switchroom 0.16.46 → 0.17.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.16.46",
+  "version": "0.17.0",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {
@@ -24,9 +24,9 @@
     "build": "node scripts/build.mjs",
     "build:cli": "node scripts/build.mjs && bun build --compile --target=bun-linux-x64 --minify bin/switchroom.ts --outfile switchroom-linux-amd64",
     "pretest": "npm run build",
-    "test": "vitest run && bun test telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
+    "test": "vitest run && bun test telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
     "test:vitest": "vitest run",
-    "test:bun": "bun test src/vault/grants.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/litellm/provision-apply-e2e.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/tests/subagent-watcher-workflow-visibility.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/uat/uat-driver.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
+    "test:bun": "bun test src/vault/grants.test.ts src/vault/grants-db.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/litellm/provision-apply-e2e.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/tests/subagent-watcher-workflow-visibility.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/uat/uat-driver.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
     "test:watch": "vitest",
     "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs && node scripts/check-no-broadcast-delivery.mjs && node scripts/check-stale-tool-descriptions.mjs && node scripts/check-web-subscription-honest.mjs",
     "lint:tsc": "tsc --noEmit",

package/profiles/_base/cron-session.sh.hbs

@@ -95,7 +95,7 @@ cd "{{agentDir}}" || exit 1
 # can distinguish cron spend from main-session spend per agent.
 # FAIL-OPEN: missing key OR unreachable proxy → strip routing env, fall back to
 # direct OAuth. An outage must never take the cron session dark.
-if [ -n "$SWITCHROOM_LITELLM" ] && command -v switchroom >/dev/null 2>&1; then
+if [ -n "${SWITCHROOM_LITELLM:-}" ] && command -v switchroom >/dev/null 2>&1; then
   sr_ll_key="$(switchroom vault get "litellm/{{name}}/api-key" 2>/dev/null || true)"
   sr_ll_ok=""
   if [ -z "$sr_ll_key" ]; then

package/profiles/_base/start.sh.hbs

@@ -64,7 +64,7 @@ if [ "$SWITCHROOM_RUNTIME" = "docker" ] && [ -z "$SWITCHROOM_DOCKER_TMUX_INNER"
   #
   # SWITCHROOM_AGENT_NAME is injected by compose env (compose.ts:1816)
   # so it is available here, before the inner-pass export at line ~320.
-  if [ -n "$SWITCHROOM_LITELLM" ] && [ -z "$ANTHROPIC_CUSTOM_HEADERS" ] && command -v switchroom >/dev/null 2>&1; then
+  if [ -n "${SWITCHROOM_LITELLM:-}" ] && [ -z "$ANTHROPIC_CUSTOM_HEADERS" ] && command -v switchroom >/dev/null 2>&1; then
     sr_ll_key="$(switchroom vault get "litellm/$SWITCHROOM_AGENT_NAME/api-key" 2>/dev/null || true)"
     sr_ll_ok=""
     if [ -z "$sr_ll_key" ]; then
@@ -657,8 +657,24 @@ mkdir -p "$TELEGRAM_STATE_DIR" 2>/dev/null || true
 # .handoff-briefing.md and merged alongside (or instead of) .handoff.md.
 HANDOFF_FILE="{{agentDir}}/.handoff.md"
 HANDOFF_BRIEFING_FILE="{{agentDir}}/.handoff-briefing.md"
+# Decide whether the on-disk briefing is stale and must be rebuilt (#2790).
+# A clean shutdown leaves a non-empty .handoff.md; a *later* hard crash never
+# fires the Stop hook, so that stale briefing would otherwise be re-injected
+# — hiding the crashed session's turns and reorienting the agent from old
+# context. Rebuild when .handoff.md is empty OR when the newest session JSONL
+# is newer than .handoff.md (i.e. a session ran after the briefing was written).
+_LATEST_JSONL=$(_find_latest_jsonl "$CLAUDE_CONFIG_DIR/projects")
+_HANDOFF_STALE=0
 if [ ! -s "$HANDOFF_FILE" ]; then
-  _LATEST_JSONL=$(_find_latest_jsonl "$CLAUDE_CONFIG_DIR/projects")
+  _HANDOFF_STALE=1
+elif [ -n "$_LATEST_JSONL" ]; then
+  _JSONL_MOD=$(_stat_mtime "$_LATEST_JSONL")
+  _HANDOFF_MOD=$(_stat_mtime "$HANDOFF_FILE")
+  if [ "$_JSONL_MOD" -gt "$_HANDOFF_MOD" ]; then
+    _HANDOFF_STALE=1
+  fi
+fi
+if [ "$_HANDOFF_STALE" = "1" ]; then
   if [ -n "$_LATEST_JSONL" ]; then
     _LAST_MOD=$(_stat_mtime "$_LATEST_JSONL")
     _NOW=$(date +%s)
@@ -704,6 +720,11 @@ $_HANDOFF_CONTENT"
     APPEND_PROMPT="$_HANDOFF_CONTENT"
   fi
 fi
+# Consume the briefing sidecars once injected (#2790). Leaving them on disk
+# lets a later hard crash (which never fires the Stop hook to refresh them)
+# re-serve this now-stale briefing on the next boot. Removing them means the
+# staleness guard above starts from a clean slate every boot.
+rm -f "$HANDOFF_BRIEFING_FILE" "$HANDOFF_FILE" 2>/dev/null || true
 {{else}}
 APPEND_PROMPT={{#if systemPromptAppendShellQuoted}}{{{systemPromptAppendShellQuoted}}}{{else}}""{{/if}}
 {{/if}}
@@ -807,6 +828,36 @@ if command -v switchroom >/dev/null 2>&1; then
   unset sr_wk_pair sr_wk_env sr_wk_key sr_wk_val
 fi
 
+# Fleet-wide webkite render config (#2805). Seed the image-baked default
+# (/opt/switchroom/webkite/config.toml) into the XDG location webkite reads
+# ($HOME/.config/webkite/config.toml) so JS-heavy SPA/booking pages render
+# via the baked-in cloakbrowser instead of returning a static shell.
+#
+# REFRESH-from-image, not copy-if-absent. $HOME (/state/agent/home) is a
+# host-PERSISTENT bind mount (see src/agents/compose.ts), so a copy-if-absent
+# seed would write once and then the stale home copy would shadow every future
+# image-shipped config update forever — the config would be un-updatable
+# fleet-wide after first boot. Instead re-sync the target from the baked
+# default whenever they differ, so an image bump always propagates.
+#
+# Operator override still wins: an operator-authored
+# ~/.switchroom/webkite/config.toml is bind-mounted RO onto this exact target
+# (compose.ts). We detect that mount and leave it untouched; even absent the
+# mountpoint check, a cp onto the RO mount fails harmlessly and the override
+# is preserved.
+if [ -f /opt/switchroom/webkite/config.toml ]; then
+  sr_wk_target="$HOME/.config/webkite/config.toml"
+  if mountpoint -q "$sr_wk_target" 2>/dev/null; then
+    : # operator override bind-mounted RO — never clobber it
+  elif ! cmp -s /opt/switchroom/webkite/config.toml "$sr_wk_target" 2>/dev/null; then
+    mkdir -p "$HOME/.config/webkite" 2>/dev/null || true
+    cp /opt/switchroom/webkite/config.toml "$sr_wk_target" 2>/dev/null \
+      && echo "webkite: synced fleet render config to \$HOME/.config/webkite/config.toml" >&2 \
+      || echo "webkite: could not sync render config (non-fatal)" >&2
+  fi
+  unset sr_wk_target
+fi
+
 # LiteLLM routing (opt-in, #litellm). When SWITCHROOM_LITELLM is set (compose
 # env, gated on litellm.enabled && keyConfirmed), route the unmodified `claude`
 # CLI through the operator's LiteLLM proxy at ANTHROPIC_BASE_URL: fetch the
@@ -833,7 +884,7 @@ fi
 # per-session cost/issue tracking is handled out-of-band by correlating
 # LiteLLM's request log against switchroom's turn ledger, never by mutating the
 # claude protocol.
-if [ -n "$SWITCHROOM_LITELLM" ] && command -v switchroom >/dev/null 2>&1; then
+if [ -n "${SWITCHROOM_LITELLM:-}" ] && command -v switchroom >/dev/null 2>&1; then
   sr_ll_key="$(switchroom vault get "litellm/$SWITCHROOM_AGENT_NAME/api-key" 2>/dev/null || true)"
   sr_ll_ok=""
   if [ -z "$sr_ll_key" ]; then

package/skills/switchroom-architecture/telegram.md

@@ -2,12 +2,11 @@
 
 Switchroom ships an enhanced `switchroom-telegram` MCP plugin that replaces the official marketplace plugin. It is the default — no configuration needed.
 
-## 10 MCP tools
+## 9 MCP tools
 
 | Tool | What it does |
 |------|-------------|
-| `reply` | Send text, photos, or documents. Supports threading, topic routing, file attachments. |
-| `stream_reply` | Edit a single message in place as work progresses (~1/sec throttle). Use for long tasks to avoid chat spam. |
+| `reply` | Send text, photos, or documents — the single final-answer tool. Chunks anything over Telegram's 4096-char limit. Supports threading, topic routing, file attachments. |
 | `react` | Add emoji reactions to messages (Telegram whitelist: 👍 👎 ❤️ 🔥 👀 🎉 etc). |
 | `edit_message` | Update a previously sent message. Edits are silent (no push notification). |
 | `delete_message` | Remove a bot-sent message (48h Telegram API limit). |
@@ -37,19 +36,13 @@ A local SQLite database (`telegram/history.db`) records every message. After a C
 
 History survives process restarts and session resets.
 
-## stream_reply pattern
+## Progress while working
 
-For tasks taking more than ~5 seconds:
-
-```
-1. stream_reply(chat_id, "Reading the file...", done=false)  ← creates message
-2. stream_reply(chat_id, "Reading the file...\nParsing...", done=false)  ← edits in place
-3. stream_reply(chat_id, "Done! Here's the result: ...", done=true)  ← locks
-```
-
-Pass the **full current text** on each call (not a delta). The plugin throttles to ~1/sec.
-
-After `done=true`, send a separate `reply` if you want a push notification to the user's device (edits are silent).
+For long tasks you do not need to narrate progress by editing a message. The
+plugin renders an event-driven progress card (Plan → Run → Done with live tool
+bullets, elapsed time, and status emoji) for free while the turn is in-flight.
+Send the final answer once, with `reply` — it chunks anything over Telegram's
+4096-char limit. For an explicit mid-turn check-in use `progress_update`.
 
 ## Formatting
 

package/skills/switchroom-cli/SKILL.md

@@ -10,7 +10,7 @@ This skill is the reference for running `switchroom` CLI commands against existi
 
 **Four commands to know:**
 - `switchroom update` — full operator path: pulls images + applies config + recreates containers + runs doctor (since v0.7.8 / #918). What you want 95% of the time.
-- `switchroom apply` — config-only reconcile: refresh per-agent scaffolds and (re)write `~/.switchroom/compose/docker-compose.yml` without touching running containers. Use when you want to inspect the generated compose before bringing the fleet up yourself.
+- `switchroom apply` — **host/operator-only**, for structural changes: refresh per-agent scaffolds and (re)write `~/.switchroom/compose/docker-compose.yml`. Its full per-agent scaffold **cannot run from inside an agent container** (no vault at the container HOME, no `docker compose` v2 plugin) — that's correct by construction, not a bug. Version rolls do NOT need it: drive the **hostd rollout** (`mcp__hostd__rollout`), which runs a `--compose-only` apply plus a per-agent restart-reconcile that refreshes each agent's templates automatically. Reserve a host-side `sudo switchroom apply` for compose regeneration / new-agent scaffolding.
 - `switchroom restart [agent]` — bounces a stuck or wedged agent
 - `switchroom version` — shows what's running (versions + health summary)
 
@@ -59,7 +59,7 @@ switchroom update --rebuild      # source-checkout users: also git pull + npm bu
 
 `switchroom update` is the operator path. The CLI self-elevates via sudo internally for the per-agent scaffold dirs that need root — no need for `sudo HOME=… PATH=…` incantations.
 
-If you only need the config-reconcile half without restarting agents, `switchroom apply` writes `~/.switchroom/compose/docker-compose.yml` and refreshes per-agent scaffolds without touching running containers. The operator runs the docker bring-up themselves.
+If you only need the config-reconcile half without restarting agents, `switchroom apply` (run **on the host by the operator**) writes `~/.switchroom/compose/docker-compose.yml` and refreshes per-agent scaffolds without touching running containers. The operator runs the docker bring-up themselves. Note this full apply cannot run from inside an agent container by construction — to roll the fleet to a new version from an agent, use the hostd rollout (`mcp__hostd__rollout`) instead of a full apply.
 
 From inside an agent's Telegram DM, the same flow is available as `/upgradestatus` (read-only) and `/update apply` (admin-gated).
 
@@ -265,12 +265,11 @@ If the user asks whether scheduled runs were missed during downtime: the schedul
 
 ## Telegram plugin reference — "what MCP tools", "how does reply work"
 
-The `switchroom-telegram` plugin is an enhanced fork of the official Telegram MCP plugin and is the default for all switchroom agents. It exposes **10 MCP tools** (all prefixed `mcp__switchroom-telegram__`):
+The `switchroom-telegram` plugin is an enhanced fork of the official Telegram MCP plugin and is the default for all switchroom agents. It exposes **9 MCP tools** (all prefixed `mcp__switchroom-telegram__`):
 
 | Tool | Purpose |
 |---|---|
-| `reply` | Send a text/photo message, with optional `reply_to` for threaded quotes |
-| `stream_reply` | Incrementally stream a long reply (edits the same message as tokens arrive) |
+| `reply` | Send a text/photo message — the single final-answer tool; chunks anything over Telegram's 4096-char limit. Optional `reply_to` for threaded quotes |
 | `react` | Emoji reaction on an inbound or outbound message |
 | `edit_message` | Modify an earlier bot message's text |
 | `delete_message` | Remove an earlier bot message |

package/skills/telegram-test-harness/SKILL.md

@@ -191,4 +191,4 @@ Before writing the test, ask:
 - `telegram-plugin/tests/fake-bot-api.test.ts` — meta-test of the fake;
   read first when adding new fake-bot capabilities
 - `telegram-plugin/tests/streaming-e2e.test.ts` — worked example of a
-  larger end-to-end test (PTY → stream_reply → done)
+  larger end-to-end test (PTY → internal stream-reply handler → done)

package/telegram-plugin/README.md

@@ -9,10 +9,12 @@ and substantially extended for long-running, multi-agent deployments.
 The upstream plugin handles the basic send/receive wire protocol. This fork
 adds the ergonomics and reliability that an always-on agent fleet needs:
 
-- **Streaming replies** — `stream_reply` edits a single message in place as
-  work progresses (~1/sec throttle), so users see live progress instead of
-  silent gaps followed by a wall-of-text. Optional `lane` parameter lets each
-  lane (e.g. `thinking` vs default `answer`) get its own message per chat+thread.
+- **Live progress card** — an event-driven progress card (Plan → Run → Done
+  with live tool bullets, elapsed time, and status emoji) edits a single
+  message in place as work progresses, so users see live progress instead of
+  silent gaps followed by a wall-of-text. This is rendered by the plugin for
+  free while the turn is in-flight — the model just sends the final answer once
+  via `reply`.
 - **Status reactions** — emoji lifecycle (👀 queued → 🤔 thinking → 👨‍💻 tool
   use → 🔥 streaming → 👍 done) on the user's own message gives "I'm working"
   feedback for free, plus stall watchdogs (🥱 30s idle, 😨 90s).
@@ -36,7 +38,7 @@ adds the ergonomics and reliability that an always-on agent fleet needs:
 - **Switchroom slash-commands** — `/agents`, `/restart`, `/logs`, `/memory`,
   `/grant`, `/dangerous`, `/permissions`, `/reconcile` etc., handled by the
   plugin without consuming Claude Code tokens.
-- **12 MCP tools** — `reply`, `stream_reply`, `react`, `edit_message`,
+- **11 MCP tools** — `reply`, `react`, `edit_message`,
   `delete_message`, `forward_message`, `pin_message`, `send_typing`,
   `download_attachment`, `get_recent_messages`, `send_checklist`,
   `update_checklist` (the latter two ship native Telegram checklists,
@@ -196,40 +198,27 @@ When an inbound message is received, the plugin immediately reacts with an emoji
 
 Set to an empty string `""` to disable. Only Telegram's fixed emoji whitelist is accepted (👍 👎 ❤ 🔥 👀 🎉 etc). A typing indicator is also sent automatically.
 
-### `stream_reply` tool (preferred for multi-step work)
+### Progress while working
 
-Sends or updates a streaming reply that edits one message in-place rather
-than sending many. Call repeatedly during long tasks with full snapshots of
-the current message; the plugin throttles edits to ~1/sec to respect
-Telegram's rate limit. Set `done=true` on the final call to lock the
-message.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `chat_id` | yes | Target chat ID |
-| `text` | yes | Full text snapshot (NOT a delta — pass the complete current content each call) |
-| `done` | no | `true` on final call. After `done=true` the stream is locked and further calls are no-ops. Default `false`. |
-| `format` | no | `"html"` (default), `"markdownv2"`, or `"text"` |
-| `lane` | no | Optional lane name. Each lane gets its own Telegram message per chat+thread. Use `lane: "thinking"` to surface reasoning progress alongside the main answer stream. Omit for the default answer lane. |
-| `message_thread_id` | no | Forum topic thread ID (auto-applied from the last inbound message if not specified) |
-
-Hard-stops at 4096 chars (Telegram message limit). On edit-404 (the message
-we're editing was deleted), the plugin sends a fresh message and continues
-the stream against the new id. A short `idleMs` pre-send debounce coalesces
-back-to-back snapshots before the first wire send, avoiding a redundant
-edit when several updates arrive in the same tick.
+For long tasks the model does **not** need to narrate progress or drive a
+streaming message itself. The plugin renders an event-driven progress card
+(Plan → Run → Done with live tool bullets, elapsed time, and status emoji)
+for free while the turn is in-flight. Send the final answer once, with
+`reply` — it chunks anything over Telegram's 4096-char limit. (The retired
+`stream_reply` tool was a redundant, worse alias of `reply`; the internal
+progress-card streaming that drove it is preserved and is what renders the
+live card.)
 
 ### Manual streaming progress via `edit_message`
 
-If you need finer control than `stream_reply` offers, you can drive the
-edit loop yourself:
+If you want to drive an in-place edit loop yourself:
 
 1. Send an initial "thinking..." message with `reply` — note the returned `message_id`
 2. Call `edit_message` with updated text as work progresses (edits are silent — no push notification)
 3. Call `send_typing` between steps to keep the typing indicator alive (it expires after ~5s)
 4. When done, send a **new** `reply` so the user's device pings with a push notification
 
-In most cases `stream_reply` is simpler and is the recommended path.
+In most cases the automatic progress card is simpler and is the recommended path.
 
 ### `send_typing` tool
 

package/telegram-plugin/bridge/bridge.ts

@@ -75,7 +75,7 @@ const mcp = new Server(
     instructions: [
       'The sender reads Telegram, not this session. Anything you want them to see must go through the reply tool — your transcript output never reaches their chat.',
       '',
-      'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file — it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. A single message may carry SEVERAL attachments (a forwarded album or a text+multi-image burst): when attachment_count is set (>1), also handle the numbered siblings — image_path_2, image_path_3, … (Read each) and attachment_file_id_2, attachment_file_id_3, … (download_attachment each). Process every one, not just the first. Reply with the reply tool — pass chat_id back. The reply and stream_reply tools quote-reply to the latest inbound user message by default, so you do NOT need to pass reply_to for normal responses. Pass reply_to (a message_id) only when quoting a specific earlier message, or pass quote:false to send a bare (non-quoted) message.',
+      'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file — it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. A single message may carry SEVERAL attachments (a forwarded album or a text+multi-image burst): when attachment_count is set (>1), also handle the numbered siblings — image_path_2, image_path_3, … (Read each) and attachment_file_id_2, attachment_file_id_3, … (download_attachment each). Process every one, not just the first. Reply with the reply tool — pass chat_id back. The reply tool quote-replies to the latest inbound user message by default, so you do NOT need to pass reply_to for normal responses. Pass reply_to (a message_id) only when quoting a specific earlier message, or pass quote:false to send a bare (non-quoted) message.',
       '',
       'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, edit_message for interim progress updates, and delete_message when you need to truly remove a message (prefer edit_message if you just want to change text — delete is for retraction). Edits don\'t trigger push notifications — when a long task completes, send a new reply so the user\'s device pings. Use send_typing to show a typing indicator during long operations. Use pin_message to pin important outputs. Use forward_message to quote/resurface earlier messages.',
       '',
@@ -134,46 +134,6 @@ const TOOL_SCHEMAS = [
       required: ['chat_id', 'text'],
     },
   },
-  {
-    name: 'stream_reply',
-    description:
-      'Post the final answer for this turn. The plugin renders an event-driven progress card (Plan → Run → Done with live tool bullets, elapsed time, and status emoji) for free while the turn is in-flight, so you do not need to narrate intermediate progress. Call `stream_reply` exactly once per turn with done=true and the complete answer text. Hard cap is 32768 chars (the rich-message wire limit) — longer text is dropped by a defensive guard, so use `reply` for anything that long (it chunks). Calling with done=false is an error in this environment (the progress card already owns the mid-turn surface). inline_keyboard adds tappable buttons under the final message — see `reply` for shape and constraints.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        chat_id: { type: 'string' },
-        text: { type: 'string', description: 'Full text snapshot. NOT a delta — pass the complete current content each call.' },
-        done: { type: 'boolean', description: 'Must be true. Posts this text as the final answer for the turn and locks the message.' },
-        message_thread_id: { type: 'string', description: 'Forum topic thread ID. Auto-applied from the last inbound message if not specified.' },
-        origin_turn_id: { type: 'string', description: 'In a forum supergroup, pass back the origin_turn_id attribute from the <channel> message you are answering. It pins the reply to that message\'s topic even if another topic\'s turn started meanwhile. Omit in DMs / single-topic chats.' },
-        format: { type: 'string', enum: ['html', 'markdownv2', 'text'], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." },
-        reply_to: { type: 'string', description: 'Message ID to quote-reply to. Overrides the default (latest inbound).' },
-        quote: { type: 'boolean', description: 'Opt out of the default quote-reply behavior. Default: true. Ignored when reply_to is explicitly set.' },
-        protect_content: { type: 'boolean', description: 'When true, Telegram prevents the message from being forwarded or saved.' },
-        quote_text: { type: 'string', description: 'Surgical quote: specific text to highlight from the reply_to message. Requires reply_to.' },
-        disable_notification: { type: 'boolean', description: 'When true, the INITIAL message send is silent (no device ping). Has no effect on subsequent edits — Telegram never pings on editMessageText. Default false. Use for mid-turn stream starts you do not want to ping; omit on the final answer.' },
-        inline_keyboard: {
-          type: 'array',
-          description: '2D array of tappable buttons under the final message. Same shape and constraints as `reply.inline_keyboard` — each button has `text` and EXACTLY ONE of `url` or `callback_data`, plus optional `ack_text` (custom tap-toast; default "✓ received") and `single_use` (default true; set false to keep the keyboard tappable after a tap). Tap on a callback_data button is delivered to this agent as an inbound channel event with meta.button_callback_data set.',
-          items: {
-            type: 'array',
-            items: {
-              type: 'object',
-              properties: {
-                text: { type: 'string' },
-                url: { type: 'string' },
-                callback_data: { type: 'string' },
-                ack_text: { type: 'string', description: 'Toast text shown on tap. Default "✓ received".' },
-                single_use: { type: 'boolean', description: 'Default true. Set false to keep the keyboard tappable after this button is tapped.' },
-              },
-              required: ['text'],
-            },
-          },
-        },
-      },
-      required: ['chat_id', 'text'],
-    },
-  },
   {
     name: 'react',
     description: 'Add an emoji reaction to a Telegram message. Telegram only accepts a fixed whitelist (👍 👎 ❤ 🔥 👀 🎉 etc) — non-whitelisted emoji will be rejected.',

package/telegram-plugin/bridge/tool-filter.ts

@@ -30,13 +30,12 @@ export interface NamedTool {
 }
 
 /**
- * Hot tools pinned loaded — must never defer. The reply path
- * (reply/stream_reply) plus the frequently-used early-turn ops. Everything
- * NOT in this set defers under tool-search.
+ * Hot tools pinned loaded — must never defer. The reply path plus the
+ * frequently-used early-turn ops. Everything NOT in this set defers under
+ * tool-search.
  */
 export const ALWAYS_LOAD_TOOLS: ReadonlySet<string> = new Set([
   'reply',
-  'stream_reply',
   'get_recent_messages',
   'react',
   'edit_message',