switchroom 0.5.0

package/skills/switchroom-status/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: switchroom-status
+description: List running switchroom agents with their uptime, model, and per-agent state. Use when the user asks 'what agents are running', 'list switchroom agents', 'how long has X been up', or wants a per-agent snapshot. Do NOT use for switchroom-wide version/health summary (use switchroom-cli's `switchroom version`) or "something is broken" diagnostics (use switchroom-health).
+---
+
+# Agent Status
+
+When the user asks about agent status, what's running, uptime, or wants to see agent info, answer by running (or telling them to run) `switchroom agent list` — this is the canonical command for showing running agents, their uptime, and current state.
+
+## Step 1 — Always mention `switchroom agent list` in your response
+
+The answer to "what agents are running", "show me agent info", "list all switchroom agents", or any uptime question is the `switchroom agent list` command. Your response MUST include the literal command string `switchroom agent list` so the user can copy it. If you have Bash tool access, run it and include the output. If you do not have Bash access, or the command fails in the current environment, still tell the user explicitly:
+
+> Run `switchroom agent list` from your switchroom project directory to see running agents, their uptime, and status.
+
+Do not respond with a PATH-not-found bailout or a "no config found" diagnosis without first giving the user the command — the eval environment may not have a config on cwd, but on the user's actual machine `switchroom agent list` is the right command.
+
+## Step 2 — Try to run it
+
+If you have Bash tool access, run:
+
+```bash
+switchroom agent list --json 2>/dev/null || switchroom agent list
+```
+
+If that succeeds, parse the output and present the running agent list with full uptime, status, and model details (see Step 3). If it fails (e.g. command not found, no config in cwd), still include the `switchroom agent list` command and the word "uptime" in your text response — the user needs those as actionable information.
+
+## Step 3 — For each agent, report running state and uptime
+
+When you have real output, for each agent show:
+- **Name** and topic
+- **Status**: running / stopped / error (from systemd unit state)
+- **Uptime**: how long it's been running (for running agents, always include the word "uptime" and the duration)
+- **Model**: which Claude model it's using
+- **Memory**: Hindsight collection name (if configured)
+- **PID** if available
+
+Every running agent must have its uptime reported so the user can see how long each has been up. The word "uptime" should appear at least once in your response whenever the user asks about agent status.
+
+## Step 4 — Format the output
+
+Format as a clean summary — one section per agent. Use bold agent names, inline code for model/collection names.
+
+## Step 5 — Highlight anything suspicious
+
+- Agents that are stopped but should be running
+- Agents in error/failed state
+- Agents with very recent restarts (< 5 min uptime — may be crash-looping)
+
+## Step 6 — One-line summary
+
+End with a one-line summary: "X of Y agents running."
+
+## Example Output Shape
+
+```
+assistant — running (2h 14m)
+  model: claude-sonnet-4-6  collection: general
+
+dev — running (45m)
+  model: claude-opus-4-6  collection: coding
+
+coach — stopped
+  last run: 3 days ago
+
+3 of 3 agents configured, 2 running.
+```
+
+If the user wants more detail on a specific agent, suggest `switchroom agent logs <name>` (covered by the `switchroom-cli` skill).

package/skills/switchroom-status/scripts/status.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# switchroom-status/scripts/status.sh
+# Fetches and formats agent status from switchroom agent list
+# Called directly for quick shell output (not required for the skill itself)
+
+set -euo pipefail
+
+BOLD='\033[1m'
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+RESET='\033[0m'
+
+if ! command -v switchroom &>/dev/null; then
+  echo "ERROR: switchroom not found on PATH"
+  echo "Install: npm install -g switchroom"
+  exit 1
+fi
+
+RAW=$(switchroom agent list --json 2>/dev/null) || {
+  echo "ERROR: switchroom agent list failed"
+  exit 1
+}
+
+if [ -z "$RAW" ] || [ "$RAW" = "[]" ]; then
+  echo "No agents configured."
+  exit 0
+fi
+
+TOTAL=$(echo "$RAW" | python3 -c "import sys,json; agents=json.load(sys.stdin); print(len(agents))" 2>/dev/null || echo "?")
+RUNNING=0
+
+echo "$RAW" | python3 -c "
+import sys, json, datetime
+
+agents = json.load(sys.stdin)
+running = 0
+
+for a in agents:
+    name    = a.get('name', 'unknown')
+    status  = a.get('status', 'unknown')
+    model   = a.get('model', 'unknown')
+    topic   = a.get('topic_name', '')
+    coll    = a.get('memory', {}).get('collection', '')
+    uptime  = a.get('uptime', '')
+    pid     = a.get('pid', '')
+
+    status_icon = '✓' if status == 'running' else '✗' if status in ('stopped','failed') else '?'
+
+    line = f'{status_icon} {name}'
+    if topic:
+        line += f' ({topic})'
+    line += f' — {status}'
+    if uptime:
+        line += f' ({uptime})'
+    print(line)
+    print(f'    model: {model}', end='')
+    if coll:
+        print(f'  collection: {coll}', end='')
+    if pid:
+        print(f'  pid: {pid}', end='')
+    print()
+    print()
+
+    if status == 'running':
+        running += 1
+
+print(f'{running} of {len(agents)} agents running.')
+" 2>/dev/null || echo "$RAW"

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

@@ -0,0 +1,191 @@
+---
+name: telegram-test-harness
+description: >
+  This skill should be used when the user asks to "test telegram", "test
+  bot interactions", "mock the bot api", "write a telegram test", "test
+  what users see in chat", "test progress card", "test the slot banner",
+  "test soft-confirm", "test auto-fallback notification", "test pin
+  behavior", or any variation on validating switchroom's Telegram-side
+  output deterministically.
+  Also use when the user mentions fake-bot-api, update-factory,
+  bot-api.harness, GrammyError, e2e telegram, telegram regression
+  test, or asks how to add a test for code that calls bot.api.* or
+  handles incoming Telegram updates.
+---
+
+# Telegram test harness (switchroom)
+
+Switchroom ships a deterministic test harness for Telegram interactions
+at `telegram-plugin/tests/`. Use it to lock in the Bot API call
+sequences switchroom emits — what the user actually sees in chat — so
+regressions fail a test instead of going silent in production.
+
+This skill is a quick-reference for that harness. The full guide lives
+at [`telegram-plugin/tests/HARNESS.md`](../../telegram-plugin/tests/HARNESS.md).
+
+## When to use this harness
+
+- A function under test calls `bot.api.sendMessage` / `editMessageText`
+  / `pinChatMessage` / `setMessageReaction` / etc.
+- A function under test consumes Telegram `Update` objects (commands,
+  callback queries, photos, forum-topic messages).
+- You're touching code in `telegram-plugin/` and want to lock in what
+  the user sees across a sequence of events.
+
+## When NOT to use this harness
+
+- Pure logic with no Bot API surface — write a plain unit test against
+  the function (see `slot-banner.test.ts` vs `slot-banner-driver.e2e.test.ts`
+  for the split).
+- Real-Telegram rendering quirks (markdown parsing edge cases, link
+  preview behaviour, emoji reflow on different clients) — only catchable
+  by a real test bot. Out of harness scope.
+
+## Two mocks, one decision
+
+```
+Need to assert on chat-model state across multiple calls
+(pinned messages, message edits, deletions, reactions)?
+  ├── yes → createFakeBotApi() from tests/fake-bot-api.ts
+  └── no  → createMockBot() from tests/bot-api.harness.ts
+```
+
+`fake-bot-api.ts` carries an in-memory chat model and a fault-injection
+DSL. `bot-api.harness.ts` is just `vi.fn()` stubs with sensible
+defaults. Pick the lighter one when you don't need state.
+
+## Quick start
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createFakeBotApi, errors, type FakeBot } from './fake-bot-api.js';
+
+let bot: FakeBot;
+beforeEach(() => { bot = createFakeBotApi({ startMessageId: 100 }); });
+
+it('pins a banner when the slot becomes non-default', async () => {
+  await refreshBanner({ bot, ownerChatId: 'c', /* ... */ });
+  expect(bot.api.sendMessage).toHaveBeenCalledTimes(1);
+  expect(bot.api.pinChatMessage).toHaveBeenCalledTimes(1);
+  expect(bot.isPinned('c', 100)).toBe(true);
+});
+
+it('survives Telegram throwing 429 flood-wait', async () => {
+  bot.faults.next('sendMessage', errors.floodWait(15));
+  // ... assert the function recovers / surfaces the error gracefully
+});
+```
+
+## Core APIs
+
+### `createFakeBotApi({ startMessageId? })`
+
+Returns a `FakeBot` with:
+
+- `bot.api.*` — vi.fn-backed Bot API methods. Mutate the chat model on
+  success, throw real `GrammyError` shapes on injected faults.
+- `bot.state` — `{ sent, currentText, pinned, reactions, deleted }`
+- `bot.faults.next(method, error, chat_id?)` — queue a one-shot fault
+- `bot.messagesIn(chat_id)` — array of sent messages, oldest first
+- `bot.textOf(message_id)` — current text after edits, or null
+- `bot.isPinned(chat_id, message_id)` — boolean
+- `bot.reset()` — wipe state + fault queue
+
+### Update factories (`tests/update-factory.ts`)
+
+```ts
+makeMessageUpdate({ text, chat?, from?, message_thread_id?, ... })
+makeTopicMessageUpdate({ text, message_thread_id, chat?, ... })
+makeCallbackQueryUpdate({ data, chat?, from?, message_id?, ... })
+makeMyChatMemberUpdate({ chat?, oldStatus?, newStatus?, ... })
+makePhotoUpdate({ caption?, chat?, file_id?, ... })
+makeDocumentUpdate({ file_name, mime_type?, chat?, ... })
+```
+
+All return real `Update` objects you can pass to `bot.handleUpdate()`
+(grammy's production dispatch path).
+
+### Pre-built error factories (`tests/fake-bot-api.ts → errors`)
+
+```ts
+errors.floodWait(retry_after?)         // 429 Too Many Requests
+errors.notModified()                   // 400 message is not modified
+errors.messageToEditNotFound()         // 400 message to edit not found
+errors.messageToDeleteNotFound()       // 400 message to delete not found
+errors.threadNotFound()                // 400 message thread not found
+errors.forbidden()                     // 403 bot was blocked by user
+errors.badRequest(description)         // generic 400
+errors.networkError(reason?)           // fetch-level failure
+```
+
+These produce real `GrammyError` instances so production code's
+`err instanceof GrammyError` checks fire correctly.
+
+### Time control
+
+```ts
+import { microtaskFlush } from './bot-api.harness.js';
+
+vi.useFakeTimers();
+fireSomeAsyncOp();
+await microtaskFlush();         // drain microtasks
+vi.advanceTimersByTime(300);
+await microtaskFlush();
+expect(bot.api.editMessageText).toHaveBeenCalled();
+```
+
+## Naming convention
+
+- `<feature>.test.ts` — pure-logic tests (no harness)
+- `<feature>.e2e.test.ts` — drives an extracted handler against the
+  fake bot (or real grammy bot via injected updates)
+
+Example pairs:
+
+- `slot-banner.test.ts` (pure decision) +
+  `slot-banner-driver.e2e.test.ts` (Bot API dispatch)
+- `auto-fallback.test.ts` (pure plan) +
+  `auto-fallback-dispatcher.e2e.test.ts` (notification dispatch)
+
+## Test-design checklist
+
+Before writing the test, ask:
+
+1. **Is this code testable as-is, or does it need a small extraction?**
+   Module-global state in `gateway.ts` (e.g. `pinnedBannerState`,
+   `activeTurnStartedAt`) usually means the side-effecting part should
+   move to its own module that takes state as an argument. See
+   `slot-banner-driver.ts` for the extraction pattern.
+2. **What's the failure I want to catch?** Snapshot-style "the whole
+   API call sequence" tests are noisy and churn on every minor
+   refactor. Assert on semantic fields (chat_id, text content,
+   parse_mode, pin/unpin presence).
+3. **Which fault would matter in production?** Don't test every
+   conceivable error path — pick the ones the function is *supposed*
+   to handle (flood-wait retry, message-not-found cleanup, forbidden
+   exit). The error factories tell you which ones are worth wiring.
+4. **Is there an existing pure-logic test for this?** If yes, the e2e
+   should focus on the wiring (which API calls fire in which order)
+   rather than re-testing the decision logic.
+
+## Anti-patterns
+
+- **Hand-rolling a `BannerState` (or other handle types) with an
+  arbitrary `message_id`** that the fake bot never saw. The fake throws
+  `messageToEditNotFound` on edit, which is realistic. Either send a
+  real message first to seed the chat model, or sequence the test as a
+  natural lifecycle.
+- **Patching `globalThis.fetch`** to intercept the real Bot API. Tests
+  that do this couple to grammy internals; use `createFakeBotApi()`
+  instead so grammy version bumps don't break tests.
+- **Asserting on the entire payload** of a sendMessage call.
+  Bot API adds optional fields over time and full-payload snapshots
+  churn for no semantic reason. Assert on the semantic shape.
+
+## See also
+
+- `telegram-plugin/tests/HARNESS.md` — full guide
+- `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)

package/skills/token-helpers/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: token-helpers
+description: Refresh OAuth access tokens for Google Calendar and Microsoft Graph from refresh tokens stored in the switchroom vault. Library skill — invoked by other skills that need a short-lived access token to call calendar or Graph APIs, not directly by the user.
+allowed-tools: Bash(switchroom vault *), Bash(./scripts/*)
+---
+
+# token-helpers
+
+Shared shell scripts that exchange a long-lived OAuth refresh token for a short-lived access token and persist the new access token back to the Switchroom vault.
+
+This is a library skill — other skills call into it rather than the user invoking it directly. A single refresh pipeline covers both Google and Microsoft providers.
+
+## When to use
+
+Invoke a helper when:
+- You hold a refresh token in the vault and need a fresh access token to call an API
+- The consuming skill does **not** cache tokens across agents (if it did, we'd promote this to an MCP server)
+
+Each helper is a plain shell script: read the refresh token from the vault, POST to the provider's OAuth endpoint, persist the returned `access_token` back to the vault, and print it to stdout so callers can pipe it into the next step.
+
+## Scripts
+
+### `scripts/google-cal-token.sh`
+
+Refreshes a Google Calendar OAuth access token.
+
+Vault keys it reads (override via env):
+- `google-cal-refresh-token` — the refresh token (env: `GOOGLE_CAL_REFRESH_TOKEN_KEY`)
+- `google-cal-client-id` — OAuth client id (env: `GOOGLE_CAL_CLIENT_ID_KEY`)
+- `google-cal-client-secret` — OAuth client secret (env: `GOOGLE_CAL_CLIENT_SECRET_KEY`)
+
+Vault key it writes:
+- `google-cal-access-token` — the new access token (env: `GOOGLE_CAL_ACCESS_TOKEN_KEY`)
+
+Other env:
+- `GOOGLE_OAUTH_TOKEN_URL` — override the token endpoint (default: `https://oauth2.googleapis.com/token`)
+- `SWITCHROOM_CLI` — override the CLI binary invocation (default: `switchroom`)
+
+Usage:
+
+```bash
+access_token=$(./scripts/google-cal-token.sh)
+curl -H "Authorization: Bearer $access_token" https://www.googleapis.com/calendar/v3/users/me/calendarList
+```
+
+### `scripts/ms-graph-token.sh`
+
+Refreshes a Microsoft Graph OAuth access token against the common tenant.
+
+Vault keys it reads:
+- `ms-graph-refresh-token` (env: `MS_GRAPH_REFRESH_TOKEN_KEY`)
+- `ms-graph-client-id` (env: `MS_GRAPH_CLIENT_ID_KEY`)
+- `ms-graph-client-secret` (env: `MS_GRAPH_CLIENT_SECRET_KEY`, optional — omit for public clients)
+
+Vault key it writes:
+- `ms-graph-access-token` (env: `MS_GRAPH_ACCESS_TOKEN_KEY`)
+
+Other env:
+- `MS_GRAPH_SCOPE` — space-delimited scope string (default: `https://graph.microsoft.com/.default offline_access`)
+- `MS_OAUTH_TOKEN_URL` — override endpoint (default: `https://login.microsoftonline.com/common/oauth2/v2.0/token`)
+- `SWITCHROOM_CLI` — override the CLI binary invocation
+
+## Host prerequisites
+
+- `curl`
+- `jq`
+- `switchroom` on `PATH` (or pass `SWITCHROOM_CLI`)
+- `SWITCHROOM_VAULT_PASSPHRASE` exported so the CLI can unlock the vault non-interactively
+
+## Exit codes
+
+- `0` — new access token fetched and persisted
+- `1` — missing vault entries, OAuth endpoint error, or malformed response

package/skills/token-helpers/scripts/google-cal-token.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# google-cal-token.sh — refresh a Google Calendar OAuth access token.
+#
+# Reads a refresh token, client_id, and client_secret from the
+# Switchroom vault; POSTs to Google's OAuth endpoint; writes the new
+# access token back to the vault; prints the access token to stdout.
+#
+# See skills/token-helpers/SKILL.md for env var overrides.
+
+set -euo pipefail
+
+REFRESH_KEY="${GOOGLE_CAL_REFRESH_TOKEN_KEY:-google-cal-refresh-token}"
+ACCESS_KEY="${GOOGLE_CAL_ACCESS_TOKEN_KEY:-google-cal-access-token}"
+CLIENT_ID_KEY="${GOOGLE_CAL_CLIENT_ID_KEY:-google-cal-client-id}"
+CLIENT_SECRET_KEY="${GOOGLE_CAL_CLIENT_SECRET_KEY:-google-cal-client-secret}"
+TOKEN_URL="${GOOGLE_OAUTH_TOKEN_URL:-https://oauth2.googleapis.com/token}"
+SWITCHROOM_CLI="${SWITCHROOM_CLI:-switchroom}"
+
+vault_get() {
+  $SWITCHROOM_CLI vault get "$1"
+}
+
+vault_set() {
+  local key="$1"
+  $SWITCHROOM_CLI vault set "$key"
+}
+
+refresh_token=$(vault_get "$REFRESH_KEY") || {
+  echo "ERROR: could not read vault key '$REFRESH_KEY'" >&2
+  exit 1
+}
+client_id=$(vault_get "$CLIENT_ID_KEY") || {
+  echo "ERROR: could not read vault key '$CLIENT_ID_KEY'" >&2
+  exit 1
+}
+client_secret=$(vault_get "$CLIENT_SECRET_KEY") || {
+  echo "ERROR: could not read vault key '$CLIENT_SECRET_KEY'" >&2
+  exit 1
+}
+
+response=$(
+  curl -sS -X POST "$TOKEN_URL" \
+    -H "Content-Type: application/x-www-form-urlencoded" \
+    --data-urlencode "client_id=$client_id" \
+    --data-urlencode "client_secret=$client_secret" \
+    --data-urlencode "refresh_token=$refresh_token" \
+    --data-urlencode "grant_type=refresh_token"
+) || {
+  echo "ERROR: OAuth POST to $TOKEN_URL failed" >&2
+  exit 1
+}
+
+access_token=$(printf '%s' "$response" | jq -r '.access_token // empty')
+
+if [ -z "$access_token" ]; then
+  echo "ERROR: OAuth response did not include an access_token" >&2
+  echo "Response: $response" >&2
+  exit 1
+fi
+
+printf '%s' "$access_token" | vault_set "$ACCESS_KEY" >/dev/null
+printf '%s\n' "$access_token"

package/skills/token-helpers/scripts/ms-graph-token.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# ms-graph-token.sh — refresh a Microsoft Graph OAuth access token.
+#
+# Reads a refresh token and client_id (plus an optional client_secret
+# for confidential clients) from the Switchroom vault, POSTs to the
+# Microsoft v2.0 token endpoint against the `common` tenant, writes
+# the new access token back to the vault, and prints it to stdout.
+#
+# See skills/token-helpers/SKILL.md for env var overrides.
+
+set -euo pipefail
+
+REFRESH_KEY="${MS_GRAPH_REFRESH_TOKEN_KEY:-ms-graph-refresh-token}"
+ACCESS_KEY="${MS_GRAPH_ACCESS_TOKEN_KEY:-ms-graph-access-token}"
+CLIENT_ID_KEY="${MS_GRAPH_CLIENT_ID_KEY:-ms-graph-client-id}"
+CLIENT_SECRET_KEY="${MS_GRAPH_CLIENT_SECRET_KEY:-ms-graph-client-secret}"
+SCOPE="${MS_GRAPH_SCOPE:-https://graph.microsoft.com/.default offline_access}"
+TOKEN_URL="${MS_OAUTH_TOKEN_URL:-https://login.microsoftonline.com/common/oauth2/v2.0/token}"
+SWITCHROOM_CLI="${SWITCHROOM_CLI:-switchroom}"
+
+vault_get() {
+  $SWITCHROOM_CLI vault get "$1"
+}
+
+vault_get_optional() {
+  $SWITCHROOM_CLI vault get "$1" 2>/dev/null || true
+}
+
+vault_set() {
+  local key="$1"
+  $SWITCHROOM_CLI vault set "$key"
+}
+
+refresh_token=$(vault_get "$REFRESH_KEY") || {
+  echo "ERROR: could not read vault key '$REFRESH_KEY'" >&2
+  exit 1
+}
+client_id=$(vault_get "$CLIENT_ID_KEY") || {
+  echo "ERROR: could not read vault key '$CLIENT_ID_KEY'" >&2
+  exit 1
+}
+client_secret=$(vault_get_optional "$CLIENT_SECRET_KEY")
+
+curl_args=(
+  -sS -X POST "$TOKEN_URL"
+  -H "Content-Type: application/x-www-form-urlencoded"
+  --data-urlencode "client_id=$client_id"
+  --data-urlencode "refresh_token=$refresh_token"
+  --data-urlencode "grant_type=refresh_token"
+  --data-urlencode "scope=$SCOPE"
+)
+if [ -n "$client_secret" ]; then
+  curl_args+=(--data-urlencode "client_secret=$client_secret")
+fi
+
+response=$(curl "${curl_args[@]}") || {
+  echo "ERROR: OAuth POST to $TOKEN_URL failed" >&2
+  exit 1
+}
+
+access_token=$(printf '%s' "$response" | jq -r '.access_token // empty')
+
+if [ -z "$access_token" ]; then
+  echo "ERROR: OAuth response did not include an access_token" >&2
+  echo "Response: $response" >&2
+  exit 1
+fi
+
+printf '%s' "$access_token" | vault_set "$ACCESS_KEY" >/dev/null
+printf '%s\n' "$access_token"